You can not select more than 25 topics
			Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
		
		
		
		
		
			
		
			
				
					
					
						
							266 lines
						
					
					
						
							8.3 KiB
						
					
					
				
			
		
		
	
	
							266 lines
						
					
					
						
							8.3 KiB
						
					
					
				# 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
 | 
						|
 |