1 | # mkdirp
|
2 |
|
3 | Like `mkdir -p`, but in Node.js!
|
4 |
|
5 | Now with a modern API and no\* bugs!
|
6 |
|
7 | <small>\* may contain some bugs</small>
|
8 |
|
9 | # example
|
10 |
|
11 | ## pow.js
|
12 |
|
13 | ```js
|
14 | // hybrid module, import or require() both work
|
15 | import { mkdirp } from 'mkdirp'
|
16 | // or:
|
17 | const { mkdirp } = require('mkdirp')
|
18 |
|
19 | // return value is a Promise resolving to the first directory created
|
20 | mkdirp('/tmp/foo/bar/baz').then(made =>
|
21 | console.log(`made directories, starting with ${made}`)
|
22 | )
|
23 | ```
|
24 |
|
25 | Output (where `/tmp/foo` already exists)
|
26 |
|
27 | ```
|
28 | made directories, starting with /tmp/foo/bar
|
29 | ```
|
30 |
|
31 | Or, if you don't have time to wait around for promises:
|
32 |
|
33 | ```js
|
34 | import { mkdirp } from 'mkdirp'
|
35 |
|
36 | // return value is the first directory created
|
37 | const made = mkdirp.sync('/tmp/foo/bar/baz')
|
38 | console.log(`made directories, starting with ${made}`)
|
39 | ```
|
40 |
|
41 | And now /tmp/foo/bar/baz exists, huzzah!
|
42 |
|
43 | # methods
|
44 |
|
45 | ```js
|
46 | import { mkdirp } from 'mkdirp'
|
47 | ```
|
48 |
|
49 | ## `mkdirp(dir: string, opts?: MkdirpOptions) => Promise<string | undefined>`
|
50 |
|
51 | Create a new directory and any necessary subdirectories at `dir`
|
52 | with octal permission string `opts.mode`. If `opts` is a string
|
53 | or number, it will be treated as the `opts.mode`.
|
54 |
|
55 | If `opts.mode` isn't specified, it defaults to `0o777`.
|
56 |
|
57 | Promise resolves to first directory `made` that had to be
|
58 | created, or `undefined` if everything already exists. Promise
|
59 | rejects if any errors are encountered. Note that, in the case of
|
60 | promise rejection, some directories _may_ have been created, as
|
61 | recursive directory creation is not an atomic operation.
|
62 |
|
63 | You can optionally pass in an alternate `fs` implementation by
|
64 | passing in `opts.fs`. Your implementation should have
|
65 | `opts.fs.mkdir(path, opts, cb)` and `opts.fs.stat(path, cb)`.
|
66 |
|
67 | You can also override just one or the other of `mkdir` and `stat`
|
68 | by passing in `opts.stat` or `opts.mkdir`, or providing an `fs`
|
69 | option that only overrides one of these.
|
70 |
|
71 | ## `mkdirp.sync(dir: string, opts: MkdirpOptions) => string|undefined`
|
72 |
|
73 | Synchronously create a new directory and any necessary
|
74 | subdirectories at `dir` with octal permission string `opts.mode`.
|
75 | If `opts` is a string or number, it will be treated as the
|
76 | `opts.mode`.
|
77 |
|
78 | If `opts.mode` isn't specified, it defaults to `0o777`.
|
79 |
|
80 | Returns the first directory that had to be created, or undefined
|
81 | if everything already exists.
|
82 |
|
83 | You can optionally pass in an alternate `fs` implementation by
|
84 | passing in `opts.fs`. Your implementation should have
|
85 | `opts.fs.mkdirSync(path, mode)` and `opts.fs.statSync(path)`.
|
86 |
|
87 | You can also override just one or the other of `mkdirSync` and
|
88 | `statSync` by passing in `opts.statSync` or `opts.mkdirSync`, or
|
89 | providing an `fs` option that only overrides one of these.
|
90 |
|
91 | ## `mkdirp.manual`, `mkdirp.manualSync`
|
92 |
|
93 | Use the manual implementation (not the native one). This is the
|
94 | default when the native implementation is not available or the
|
95 | stat/mkdir implementation is overridden.
|
96 |
|
97 | ## `mkdirp.native`, `mkdirp.nativeSync`
|
98 |
|
99 | Use the native implementation (not the manual one). This is the
|
100 | default when the native implementation is available and
|
101 | stat/mkdir are not overridden.
|
102 |
|
103 | # implementation
|
104 |
|
105 | On Node.js v10.12.0 and above, use the native `fs.mkdir(p,
|
106 | {recursive:true})` option, unless `fs.mkdir`/`fs.mkdirSync` has
|
107 | been overridden by an option.
|
108 |
|
109 | ## native implementation
|
110 |
|
111 | - If the path is a root directory, then pass it to the underlying
|
112 | implementation and return the result/error. (In this case,
|
113 | it'll either succeed or fail, but we aren't actually creating
|
114 | any dirs.)
|
115 | - Walk up the path statting each directory, to find the first
|
116 | path that will be created, `made`.
|
117 | - Call `fs.mkdir(path, { recursive: true })` (or `fs.mkdirSync`)
|
118 | - If error, raise it to the caller.
|
119 | - Return `made`.
|
120 |
|
121 | ## manual implementation
|
122 |
|
123 | - Call underlying `fs.mkdir` implementation, with `recursive:
|
124 | false`
|
125 | - If error:
|
126 | - If path is a root directory, raise to the caller and do not
|
127 | handle it
|
128 | - If ENOENT, mkdirp parent dir, store result as `made`
|
129 | - stat(path)
|
130 | - If error, raise original `mkdir` error
|
131 | - If directory, return `made`
|
132 | - Else, raise original `mkdir` error
|
133 | - else
|
134 | - return `undefined` if a root dir, or `made` if set, or `path`
|
135 |
|
136 | ## windows vs unix caveat
|
137 |
|
138 | On Windows file systems, attempts to create a root directory (ie,
|
139 | a drive letter or root UNC path) will fail. If the root
|
140 | directory exists, then it will fail with `EPERM`. If the root
|
141 | directory does not exist, then it will fail with `ENOENT`.
|
142 |
|
143 | On posix file systems, attempts to create a root directory (in
|
144 | recursive mode) will succeed silently, as it is treated like just
|
145 | another directory that already exists. (In non-recursive mode,
|
146 | of course, it fails with `EEXIST`.)
|
147 |
|
148 | In order to preserve this system-specific behavior (and because
|
149 | it's not as if we can create the parent of a root directory
|
150 | anyway), attempts to create a root directory are passed directly
|
151 | to the `fs` implementation, and any errors encountered are not
|
152 | handled.
|
153 |
|
154 | ## native error caveat
|
155 |
|
156 | The native implementation (as of at least Node.js v13.4.0) does
|
157 | not provide appropriate errors in some cases (see
|
158 | [nodejs/node#31481](https://github.com/nodejs/node/issues/31481)
|
159 | and
|
160 | [nodejs/node#28015](https://github.com/nodejs/node/issues/28015)).
|
161 |
|
162 | In order to work around this issue, the native implementation
|
163 | will fall back to the manual implementation if an `ENOENT` error
|
164 | is encountered.
|
165 |
|
166 | # choosing a recursive mkdir implementation
|
167 |
|
168 | There are a few to choose from! Use the one that suits your
|
169 | needs best :D
|
170 |
|
171 | ## use `fs.mkdir(path, {recursive: true}, cb)` if:
|
172 |
|
173 | - You wish to optimize performance even at the expense of other
|
174 | factors.
|
175 | - You don't need to know the first dir created.
|
176 | - You are ok with getting `ENOENT` as the error when some other
|
177 | problem is the actual cause.
|
178 | - You can limit your platforms to Node.js v10.12 and above.
|
179 | - You're ok with using callbacks instead of promises.
|
180 | - You don't need/want a CLI.
|
181 | - You don't need to override the `fs` methods in use.
|
182 |
|
183 | ## use this module (mkdirp 1.x or 2.x) if:
|
184 |
|
185 | - You need to know the first directory that was created.
|
186 | - You wish to use the native implementation if available, but
|
187 | fall back when it's not.
|
188 | - You prefer promise-returning APIs to callback-taking APIs.
|
189 | - You want more useful error messages than the native recursive
|
190 | mkdir provides (at least as of Node.js v13.4), and are ok with
|
191 | re-trying on `ENOENT` to achieve this.
|
192 | - You need (or at least, are ok with) a CLI.
|
193 | - You need to override the `fs` methods in use.
|
194 |
|
195 | ## use [`make-dir`](http://npm.im/make-dir) if:
|
196 |
|
197 | - You do not need to know the first dir created (and wish to save
|
198 | a few `stat` calls when using the native implementation for
|
199 | this reason).
|
200 | - You wish to use the native implementation if available, but
|
201 | fall back when it's not.
|
202 | - You prefer promise-returning APIs to callback-taking APIs.
|
203 | - You are ok with occasionally getting `ENOENT` errors for
|
204 | failures that are actually related to something other than a
|
205 | missing file system entry.
|
206 | - You don't need/want a CLI.
|
207 | - You need to override the `fs` methods in use.
|
208 |
|
209 | ## use mkdirp 0.x if:
|
210 |
|
211 | - You need to know the first directory that was created.
|
212 | - You need (or at least, are ok with) a CLI.
|
213 | - You need to override the `fs` methods in use.
|
214 | - You're ok with using callbacks instead of promises.
|
215 | - You are not running on Windows, where the root-level ENOENT
|
216 | errors can lead to infinite regress.
|
217 | - You think vinyl just sounds warmer and richer for some weird
|
218 | reason.
|
219 | - You are supporting truly ancient Node.js versions, before even
|
220 | the advent of a `Promise` language primitive. (Please don't.
|
221 | You deserve better.)
|
222 |
|
223 | # cli
|
224 |
|
225 | This package also ships with a `mkdirp` command.
|
226 |
|
227 | ```
|
228 | $ mkdirp -h
|
229 |
|
230 | usage: mkdirp [DIR1,DIR2..] {OPTIONS}
|
231 |
|
232 | Create each supplied directory including any necessary parent directories
|
233 | that don't yet exist.
|
234 |
|
235 | If the directory already exists, do nothing.
|
236 |
|
237 | OPTIONS are:
|
238 |
|
239 | -m<mode> If a directory needs to be created, set the mode as an octal
|
240 | --mode=<mode> permission string.
|
241 |
|
242 | -v --version Print the mkdirp version number
|
243 |
|
244 | -h --help Print this helpful banner
|
245 |
|
246 | -p --print Print the first directories created for each path provided
|
247 |
|
248 | --manual Use manual implementation, even if native is available
|
249 | ```
|
250 |
|
251 | # install
|
252 |
|
253 | With [npm](http://npmjs.org) do:
|
254 |
|
255 | ```
|
256 | npm install mkdirp
|
257 | ```
|
258 |
|
259 | to get the library locally, or
|
260 |
|
261 | ```
|
262 | npm install -g mkdirp
|
263 | ```
|
264 |
|
265 | to get the command everywhere, or
|
266 |
|
267 | ```
|
268 | npx mkdirp ...
|
269 | ```
|
270 |
|
271 | to run the command without installing it globally.
|
272 |
|
273 | # platform support
|
274 |
|
275 | This module works on node v8, but only v10 and above are officially
|
276 | supported, as Node v8 reached its LTS end of life 2020-01-01, which is in
|
277 | the past, as of this writing.
|
278 |
|
279 | # license
|
280 |
|
281 | MIT
|