Files
node_modules
.bin
@ampproject
@babel
@discoveryjs
@gar
@istanbuljs
@jridgewell
@leichtgewicht
@npmcli
@riotjs
@tootallnate
@types
@ungap
@webassemblyjs
@webpack-cli
@xtuc
abab
abbrev
accepts
acorn
acorn-globals
acorn-import-assertions
acorn-walk
agent-base
agentkeepalive
aggregate-error
ajv
ajv-formats
ajv-keywords
ansi-colors
ansi-html-community
ansi-regex
ansi-styles
anymatch
append-transform
aproba
archy
are-we-there-yet
argparse
array-flatten
arrify
assertion-error
ast-types
async-foreach
asynckit
babel-plugin-dynamic-import-node
babel-plugin-polyfill-corejs2
babel-plugin-polyfill-corejs3
babel-plugin-polyfill-regenerator
balanced-match
batch
bianco.attr
bianco.dom-to-array
bianco.events
bianco.query
big.js
binary-extensions
body-parser
bonjour-service
boolbase
brace-expansion
braces
browser-process-hrtime
browser-stdout
browserslist
buffer-from
bytes
cacache
caching-transform
call-bind
camel-case
camelcase
camelcase-keys
caniuse-lite
chai
chalk
check-error
chokidar
chownr
chrome-trace-event
clean-css
clean-stack
cliui
clone-deep
color-convert
color-name
color-support
colorette
combined-stream
commander
commondir
compressible
compression
concat-map
connect-history-api-fallback
console-control-strings
content-disposition
content-type
convert-source-map
cookie
cookie-signature
core-js-compat
core-util-is
cross-spawn
css-select
css-what
cssesc
cssom
cssstyle
cumpa
curri
data-urls
debug
decamelize
decamelize-keys
decimal.js
deep-eql
deep-is
default-gateway
default-require-extensions
define-lazy-prop
define-properties
delayed-stream
delegates
depd
destroy
detect-node
diff
dns-equal
dns-packet
dom-converter
dom-nodes
dom-serializer
domelementtype
domexception
domhandler
domutils
dot-case
ee-first
electron-to-chromium
emoji-regex
emojis-list
encodeurl
encoding
enhanced-resolve
entities
env-paths
envinfo
err-code
erre
error-ex
es-module-lexer
es6-error
escalade
escape-html
escape-string-regexp
escodegen
eslint-scope
esm
esprima
esrecurse
estraverse
esutils
etag
eventemitter3
events
execa
express
fast-deep-equal
fast-json-stable-stringify
fast-levenshtein
fastest-levenshtein
faye-websocket
fill-range
finalhandler
find-up
flat
follow-redirects
foreground-child
form-data
forwarded
fresh
fromentries
fs-minipass
fs-monkey
fs.realpath
function-bind
gauge
gaze
gensync
get-caller-file
get-func-name
get-intrinsic
get-package-type
get-stdin
get-stream
glob
glob-parent
glob-to-regexp
globals
globule
graceful-fs
growl
handle-thing
hard-rejection
has
has-flag
has-property-descriptors
has-symbols
has-unicode
hasha
he
hosted-git-info
hpack.js
html-encoding-sniffer
html-entities
html-escaper
html-minifier-terser
html-webpack-plugin
htmlparser2
http-cache-semantics
http-deceiver
http-errors
http-parser-js
http-proxy
http-proxy-agent
http-proxy-middleware
https-proxy-agent
human-signals
humanize-ms
iconv-lite
imurmurhash
indent-string
infer-owner
inflight
inherits
interpret
ip
ipaddr.js
is-arrayish
is-binary-path
is-core-module
is-docker
is-extglob
is-fullwidth-code-point
is-glob
is-lambda
is-number
is-plain-obj
is-plain-object
is-potential-custom-element-name
is-stream
is-typedarray
is-windows
is-wsl
isarray
isexe
isobject
istanbul-lib-coverage
istanbul-lib-hook
istanbul-lib-instrument
istanbul-lib-processinfo
istanbul-lib-report
istanbul-lib-source-maps
istanbul-reports
jest-worker
js-base64
js-tokens
js-yaml
jsdom
jsdom-global
jsesc
json-parse-even-better-errors
json-schema-traverse
json5
kind-of
levn
lines-and-columns
loader-runner
locate-path
lodash
lodash.debounce
lodash.flattendeep
log-symbols
loupe
lower-case
lru-cache
make-fetch-happen
map-obj
media-typer
memfs
meow
merge-descriptors
merge-stream
methods
micromatch
mime
mime-db
mime-types
mimic-fn
min-indent
minimalistic-assert
minimatch
minimist-options
minipass
minipass-collect
minipass-fetch
minipass-flush
minipass-pipeline
minipass-sized
minizlib
mkdirp
bin
lib
CHANGELOG.md
LICENSE
index.js
package.json
readme.markdown
mocha
ms
multicast-dns
nan
nanoid
negotiator
neo-async
no-case
node-forge
node-gyp
node-preload
node-releases
node-sass
nopt
normalize-package-data
normalize-path
npm-run-path
npmlog
nth-check
nwsapi
nyc
object-inspect
object-keys
object.assign
obuf
on-finished
on-headers
once
onetime
open
optionator
p-limit
p-locate
p-map
p-retry
p-try
package-hash
param-case
parse-json
parse5
parseurl
pascal-case
path-exists
path-is-absolute
path-key
path-parse
path-to-regexp
pathval
picocolors
picomatch
pirates
prelude-ls
pretty-error
process-nextick-args
process-on-spawn
promise-inflight
promise-retry
proxy-addr
psl
punycode
qs
quick-lru
randombytes
range-parser
raw-body
rawth
read-pkg
read-pkg-up
readable-stream
readdirp
recast
rechoir
redent
regenerate
regenerate-unicode-properties
regenerator-runtime
regenerator-transform
regexpu-core
regjsgen
regjsparser
relateurl
release-zalgo
renderkid
require-directory
require-from-string
require-main-filename
requires-port
resolve
retry
rimraf
riot
ruit
safe-buffer
safer-buffer
sass-graph
saxes
schema-utils
scss-tokenizer
select-hose
selfsigned
semver
send
serialize-javascript
serve-index
serve-static
set-blocking
setprototypeof
shallow-clone
shebang-command
shebang-regex
side-channel
signal-exit
smart-buffer
sockjs
socks
socks-proxy-agent
source-map
source-map-support
spawn-wrap
spdx-correct
spdx-exceptions
spdx-expression-parse
spdx-license-ids
spdy
spdy-transport
sprintf-js
ssri
statuses
stdout-stream
string-width
string_decoder
strip-ansi
strip-final-newline
strip-indent
strip-json-comments
supports-color
symbol-tree
tapable
tar
terser
terser-webpack-plugin
test-exclude
thunky
to-fast-properties
to-regex-range
toidentifier
tough-cookie
tr46
trim-newlines
true-case-path
tslib
type-check
type-detect
type-fest
type-is
typedarray-to-buffer
unicode-canonical-property-names-ecmascript
unicode-match-property-ecmascript
unicode-match-property-value-ecmascript
unicode-property-aliases-ecmascript
unique-filename
unique-slug
universalify
unpipe
update-browserslist-db
uri-js
util-deprecate
utila
utils-merge
uuid
validate-npm-package-license
vary
w3c-hr-time
w3c-xmlserializer
watchpack
wbuf
webidl-conversions
webpack
webpack-cli
webpack-dev-middleware
webpack-dev-server
webpack-merge
webpack-sources
websocket-driver
websocket-extensions
whatwg-encoding
whatwg-mimetype
whatwg-url
which
which-module
wide-align
wildcard
word-wrap
workerpool
wrap-ansi
wrappy
write-file-atomic
ws
xml-name-validator
xmlchars
y18n
yallist
yargs
yargs-parser
yargs-unparser
yocto-queue
.package-lock.json
src
LICENSE
package-lock.json
package.json
readme.md
webpack.config.js
parcoursup/node_modules/mkdirp/readme.markdown

267 lines
8.3 KiB
Markdown
Raw Normal View History

2023-03-05 13:23:23 +01:00
# 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