node_modules/copyfiles/node_modules/mkdirp/readme.markdown - nifi-fds - Git at Google

 # 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
	# 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