package.readme.markdown Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of mkdirp Show documentation
Show all versions of mkdirp Show documentation
Recursively mkdir, like `mkdir -p`
The newest version!
# mkdirp
Like `mkdir -p`, but in Node.js!
Now with a modern API and no\* bugs!
\* may contain some bugs
# example
## pow.js
```js
// hybrid module, import or require() both work
import { mkdirp } from 'mkdirp'
// or:
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
import { mkdirp } from '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
import { mkdirp } from 'mkdirp'
```
## `mkdirp(dir: string, opts?: MkdirpOptions) => Promise`
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`.
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: string, opts: MkdirpOptions) => string|undefined`
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`.
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 or 2.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 If a directory needs to be created, set the mode as an octal
--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