docs for new version

Author: isaacs

readme.markdown

@@ -1,82 +1,236 @@
 # mkdirp
 
-Like `mkdir -p`, but in node.js!
+Like `mkdir -p`, but in Node.js!
 
-[![build status](https://secure.travis-ci.org/substack/node-mkdirp.png)](http://travis-ci.org/substack/node-mkdirp)
+Now with a modern API and no\* bugs!
+
+<small>\* may contain some bugs</small>
 
 # example
 
 ## pow.js
 
 ```js
-var mkdirp = require('mkdirp');
-    
-mkdirp('/tmp/foo/bar/baz', function (err) {
-    if (err) console.error(err)
-    else console.log('pow!')
-});
+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
+Output (where `/tmp/foo` already exists)
 
 ```
-pow!
+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
-var mkdirp = require('mkdirp');
+const mkdirp = require('mkdirp')
 ```
 
-## mkdirp(dir, opts, cb)
+## 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 non-object, it will be treated as
-the `opts.mode`.
+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 `0777 & (~process.umask())`.
+If `opts.mode` isn't specified, it defaults to `0o777 &
+(~process.umask())`.
 
-`cb(err, made)` fires with the error or the first directory `made`
-that had to be created, if any.
+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, mode, cb)` and
-`opts.fs.stat(path, cb)`.
+`opts.fs`. Your implementation should have `opts.fs.mkdir(path, opts, cb)`
+and `opts.fs.stat(path, cb)`.
 
-## mkdirp.sync(dir, opts)
+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.
 
-Synchronously create a new directory and any necessary subdirectories at `dir`
-with octal permission string `opts.mode`. If `opts` is a non-object, it will be
-treated as the `opts.mode`.
+## mkdirp.sync(dir, opts) -> String|null
 
-If `opts.mode` isn't specified, it defaults to `0777 & (~process.umask())`.
+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`.
 
-Returns the first directory that had to be created, if any.
+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)`.
+`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.
 
-# usage
+## 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.
-  
+  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
-               permission string.
+  -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
@@ -87,13 +241,25 @@ With [npm](http://npmjs.org) do:
 npm install mkdirp
 ```
 
-to get the library, or
+to get the library locally, or
 
 ```
 npm install -g mkdirp
 ```
 
-to get the command.
+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