Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/isaacs/node-mkdirp

Recursively mkdir, like `mkdir -p`, but in node.js
https://github.com/isaacs/node-mkdirp

Last synced: about 2 months ago
JSON representation

Recursively mkdir, like `mkdir -p`, but in node.js

Awesome Lists containing this project

README 

        
# 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