mk-dirs

mk-dirs

A tiny (384B to 417B) utility to make a directory and its parents, recursively

This is a Promise-based utility that recursively creates directories. It's effectively mkdir -p for Node.js.

This module is a fast and lightweight alternative to mkdirp. Check out Comparisons for more info!

Notice: Node v10.12.0 includes the recursive option for fs.mkdir and fs.mkdirSync.

const { mkdir } = require('fs');
const { promisify } = require('util');

const mkdirp = promisify(mkdir);

function mkdirs(str, opts={}) {
  return mkdirp(str, { ...opts, recursive:true });
}

Install

$ npm install --save mk-dirs

Modes

There are two "versions" of mk-dirs available:

"async"

Node.js: >= 8.x
Size (gzip): 417 bytes
Availability: CommonJS, ES Module

This is the primary/default mode. It makes use of async/await and util.promisify.

"sync"

Node.js: >= 6.x
Size (gzip): 384 bytes
Availability: CommonJS, ES Module

This is the opt-in mode, ideal for scenarios where async usage cannot be supported.
In order to use it, simply make the following changes:

-import mkdirs from 'mk-dirs';
+import mkdirs from 'mk-dirs/sync';

Usage

$ pwd
# /Users/hello/world

$ tree
# .

import mkdirs from 'mk-dirs';
import { resolve } from 'path';

// Async/await
try {
  let output = await mkdirs('foo/bar/baz');
  console.log(output); //=> "/Users/hello/world/foo/bar/baz"
} catch (err) {
  //
}

// Promises
mkdirs('foo/bar/baz').then(output => {
  console.log(output); //=> "/Users/hello/world/foo/bar/baz"
}).catch(err => {
  //
});

// Using `cwd` option
let dir = resolve('foo/bar');
await mkdirs('hola/mundo', { cwd: dir });
//=> "/Users/hello/world/foo/bar/hola/mundo"

$ tree
# .
# └── foo
#     └── bar
#         └── baz
#         └── hola
#             └── mundo

API

mkdir(path, options={})

Returns: Promise<String>

Returns a Promise, which resolves with the full path (string) of the created directory.
Any file system errors will be thrown and must be caught manually.

path

Type: String

The directory to create.

options.cwd

Type: String
Default: .

The directory to resolve your path from.
Defaults to the process.cwd() – aka, the directory that your command is run within.

options.mode

Type: Number
Default: 0o777 & (~process.umask())

The directory permissions to set.

Important: Must be in octal format!

Comparisons

Versus make-dir

• mk-dirs is slightly faster
• ...has zero dependencies
• ...does offer cwd option
• ...does not re-wrap an existing Promise
• ...does not ship with a sync method
• ...does not allow custom fs option

Versus mkdirp

• mk-dirs is much faster
• ...has zero dependencies
• ...is a Promise-based API
• ...is async/await ready!
• ...is tested on macOS, Linux, and Windows
• ... has fixes for mkdirp issues: #96, #70, #66
• ...includes a cwd option
• ...does not ship with a sync method
• ...does not allow custom fs option
• ...does not bundle a CLI runtime

Related

• totalist - A tiny (195B to 224B) utility to recursively list all (total) files in a directory
• escalade - A tiny (183B) and fast utility to ascend parent directories
• premove – A tiny (247B) utility to remove items recursively

License

MIT © Luke Edwards