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