| # mkdirp |
| |
| Like `mkdir -p`, but in Node.js! |
| |
| Now with a modern API and no\* bugs! |
| |
| <small>\* may contain some bugs</small> |
| |
| # example |
| |
| ## pow.js |
| |
| ```js |
| const mkdirp = require('mkdirp') |
| |
| // return value is a Promise resolving to the first directory created |
| mkdirp('/tmp/foo/bar/baz').then(made => |
| console.log(`made directories, starting with ${made}`)) |
| ``` |
| |
| Output (where `/tmp/foo` already exists) |
| |
| ``` |
| made directories, starting with /tmp/foo/bar |
| ``` |
| |
| Or, if you don't have time to wait around for promises: |
| |
| ```js |
| const mkdirp = require('mkdirp') |
| |
| // return value is the first directory created |
| const made = mkdirp.sync('/tmp/foo/bar/baz') |
| console.log(`made directories, starting with ${made}`) |
| ``` |
| |
| And now /tmp/foo/bar/baz exists, huzzah! |
| |
| # methods |
| |
| ```js |
| const mkdirp = require('mkdirp') |
| ``` |
| |
| ## mkdirp(dir, [opts]) -> Promise<String | undefined> |
| |
| Create a new directory and any necessary subdirectories at `dir` with octal |
| permission string `opts.mode`. If `opts` is a string or number, it will be |
| treated as the `opts.mode`. |
| |
| If `opts.mode` isn't specified, it defaults to `0o777 & |
| (~process.umask())`. |
| |
| Promise resolves to first directory `made` that had to be created, or |
| `undefined` if everything already exists. Promise rejects if any errors |
| are encountered. Note that, in the case of promise rejection, some |
| directories _may_ have been created, as recursive directory creation is not |
| an atomic operation. |
| |
| You can optionally pass in an alternate `fs` implementation by passing in |
| `opts.fs`. Your implementation should have `opts.fs.mkdir(path, opts, cb)` |
| and `opts.fs.stat(path, cb)`. |
| |
| You can also override just one or the other of `mkdir` and `stat` by |
| passing in `opts.stat` or `opts.mkdir`, or providing an `fs` option that |
| only overrides one of these. |
| |
| ## mkdirp.sync(dir, opts) -> String|null |
| |
| Synchronously create a new directory and any necessary subdirectories at |
| `dir` with octal permission string `opts.mode`. If `opts` is a string or |
| number, it will be treated as the `opts.mode`. |
| |
| If `opts.mode` isn't specified, it defaults to `0o777 & |
| (~process.umask())`. |
| |
| Returns the first directory that had to be created, or undefined if |
| everything already exists. |
| |
| You can optionally pass in an alternate `fs` implementation by passing in |
| `opts.fs`. Your implementation should have `opts.fs.mkdirSync(path, mode)` |
| and `opts.fs.statSync(path)`. |
| |
| You can also override just one or the other of `mkdirSync` and `statSync` |
| by passing in `opts.statSync` or `opts.mkdirSync`, or providing an `fs` |
| option that only overrides one of these. |
| |
| ## mkdirp.manual, mkdirp.manualSync |
| |
| Use the manual implementation (not the native one). This is the default |
| when the native implementation is not available or the stat/mkdir |
| implementation is overridden. |
| |
| ## mkdirp.native, mkdirp.nativeSync |
| |
| Use the native implementation (not the manual one). This is the default |
| when the native implementation is available and stat/mkdir are not |
| overridden. |
| |
| # implementation |
| |
| On Node.js v10.12.0 and above, use the native `fs.mkdir(p, |
| {recursive:true})` option, unless `fs.mkdir`/`fs.mkdirSync` has been |
| overridden by an option. |
| |
| ## native implementation |
| |
| - If the path is a root directory, then pass it to the underlying |
| implementation and return the result/error. (In this case, it'll either |
| succeed or fail, but we aren't actually creating any dirs.) |
| - Walk up the path statting each directory, to find the first path that |
| will be created, `made`. |
| - Call `fs.mkdir(path, { recursive: true })` (or `fs.mkdirSync`) |
| - If error, raise it to the caller. |
| - Return `made`. |
| |
| ## manual implementation |
| |
| - Call underlying `fs.mkdir` implementation, with `recursive: false` |
| - If error: |
| - If path is a root directory, raise to the caller and do not handle it |
| - If ENOENT, mkdirp parent dir, store result as `made` |
| - stat(path) |
| - If error, raise original `mkdir` error |
| - If directory, return `made` |
| - Else, raise original `mkdir` error |
| - else |
| - return `undefined` if a root dir, or `made` if set, or `path` |
| |
| ## windows vs unix caveat |
| |
| On Windows file systems, attempts to create a root directory (ie, a drive |
| letter or root UNC path) will fail. If the root directory exists, then it |
| will fail with `EPERM`. If the root directory does not exist, then it will |
| fail with `ENOENT`. |
| |
| On posix file systems, attempts to create a root directory (in recursive |
| mode) will succeed silently, as it is treated like just another directory |
| that already exists. (In non-recursive mode, of course, it fails with |
| `EEXIST`.) |
| |
| In order to preserve this system-specific behavior (and because it's not as |
| if we can create the parent of a root directory anyway), attempts to create |
| a root directory are passed directly to the `fs` implementation, and any |
| errors encountered are not handled. |
| |
| ## native error caveat |
| |
| The native implementation (as of at least Node.js v13.4.0) does not provide |
| appropriate errors in some cases (see |
| [nodejs/node#31481](https://github.com/nodejs/node/issues/31481) and |
| [nodejs/node#28015](https://github.com/nodejs/node/issues/28015)). |
| |
| In order to work around this issue, the native implementation will fall |
| back to the manual implementation if an `ENOENT` error is encountered. |
| |
| # choosing a recursive mkdir implementation |
| |
| There are a few to choose from! Use the one that suits your needs best :D |
| |
| ## use `fs.mkdir(path, {recursive: true}, cb)` if: |
| |
| - You wish to optimize performance even at the expense of other factors. |
| - You don't need to know the first dir created. |
| - You are ok with getting `ENOENT` as the error when some other problem is |
| the actual cause. |
| - You can limit your platforms to Node.js v10.12 and above. |
| - You're ok with using callbacks instead of promises. |
| - You don't need/want a CLI. |
| - You don't need to override the `fs` methods in use. |
| |
| ## use this module (mkdirp 1.x) if: |
| |
| - You need to know the first directory that was created. |
| - You wish to use the native implementation if available, but fall back |
| when it's not. |
| - You prefer promise-returning APIs to callback-taking APIs. |
| - You want more useful error messages than the native recursive mkdir |
| provides (at least as of Node.js v13.4), and are ok with re-trying on |
| `ENOENT` to achieve this. |
| - You need (or at least, are ok with) a CLI. |
| - You need to override the `fs` methods in use. |
| |
| ## use [`make-dir`](http://npm.im/make-dir) if: |
| |
| - You do not need to know the first dir created (and wish to save a few |
| `stat` calls when using the native implementation for this reason). |
| - You wish to use the native implementation if available, but fall back |
| when it's not. |
| - You prefer promise-returning APIs to callback-taking APIs. |
| - You are ok with occasionally getting `ENOENT` errors for failures that |
| are actually related to something other than a missing file system entry. |
| - You don't need/want a CLI. |
| - You need to override the `fs` methods in use. |
| |
| ## use mkdirp 0.x if: |
| |
| - You need to know the first directory that was created. |
| - You need (or at least, are ok with) a CLI. |
| - You need to override the `fs` methods in use. |
| - You're ok with using callbacks instead of promises. |
| - You are not running on Windows, where the root-level ENOENT errors can |
| lead to infinite regress. |
| - You think vinyl just sounds warmer and richer for some weird reason. |
| - You are supporting truly ancient Node.js versions, before even the advent |
| of a `Promise` language primitive. (Please don't. You deserve better.) |
| |
| # cli |
| |
| This package also ships with a `mkdirp` command. |
| |
| ``` |
| $ mkdirp -h |
| |
| usage: mkdirp [DIR1,DIR2..] {OPTIONS} |
| |
| Create each supplied directory including any necessary parent directories |
| that don't yet exist. |
| |
| If the directory already exists, do nothing. |
| |
| OPTIONS are: |
| |
| -m<mode> If a directory needs to be created, set the mode as an octal |
| --mode=<mode> permission string. |
| |
| -v --version Print the mkdirp version number |
| |
| -h --help Print this helpful banner |
| |
| -p --print Print the first directories created for each path provided |
| |
| --manual Use manual implementation, even if native is available |
| ``` |
| |
| # install |
| |
| With [npm](http://npmjs.org) do: |
| |
| ``` |
| npm install mkdirp |
| ``` |
| |
| to get the library locally, or |
| |
| ``` |
| npm install -g mkdirp |
| ``` |
| |
| to get the command everywhere, or |
| |
| ``` |
| npx mkdirp ... |
| ``` |
| |
| to run the command without installing it globally. |
| |
| # platform support |
| |
| This module works on node v8, but only v10 and above are officially |
| supported, as Node v8 reached its LTS end of life 2020-01-01, which is in |
| the past, as of this writing. |
| |
| # license |
| |
| MIT |