mkdirp vs graceful-fs
File System Utilities in Node.js Comparison
1 Year
mkdirpgraceful-fsSimilar Packages:
What's File System Utilities in Node.js?

Both 'graceful-fs' and 'mkdirp' are npm packages that provide functionalities for file system operations in Node.js. 'graceful-fs' enhances the native 'fs' module to handle file system operations more gracefully, particularly in terms of error handling and performance. It aims to prevent common issues such as EMFILE errors that occur when too many file descriptors are opened simultaneously. On the other hand, 'mkdirp' is a utility for creating directories recursively, ensuring that all parent directories are created if they do not exist, thus simplifying the process of directory creation in file system operations.

Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
mkdirp89,366,373189107 kB12 years agoMIT
graceful-fs65,793,7831,28332.5 kB502 years agoISC
Feature Comparison: mkdirp vs graceful-fs

Error Handling

  • mkdirp:

    'mkdirp' does not specifically focus on error handling but ensures that the directory creation process does not fail silently. If a directory cannot be created due to permission issues or other errors, it will throw an error, allowing developers to handle it appropriately.

  • graceful-fs:

    'graceful-fs' improves error handling by automatically retrying file operations that fail due to EMFILE errors, which occur when too many files are opened at once. This package uses a queue system to manage file operations, ensuring that they are executed without overwhelming the system's file descriptor limit, thus providing a more reliable experience when dealing with file I/O.

Functionality

  • mkdirp:

    'mkdirp' is specifically designed for creating directories recursively. It simplifies the process of ensuring that a complete directory path exists before performing file operations. This utility is essential when working with dynamic paths where parent directories may not exist.

  • graceful-fs:

    'graceful-fs' extends the functionality of the native 'fs' module by providing a drop-in replacement that maintains the same API while enhancing performance and reliability. It supports all standard file operations like reading, writing, and deleting files, but with improved handling of concurrent operations, making it suitable for high-load applications.

Performance

  • mkdirp:

    'mkdirp' is efficient for its purpose of creating directories, but its performance is primarily dependent on the underlying file system. It handles the creation of multiple directories in a single call, which can be more efficient than creating them one by one, but it does not focus on performance enhancements beyond this.

  • graceful-fs:

    'graceful-fs' is optimized for performance, especially in scenarios with high concurrency. By managing the number of simultaneous file operations, it reduces the likelihood of hitting system limits and improves overall throughput for file operations, making it suitable for applications that require frequent file access.

Use Cases

  • mkdirp:

    Use 'mkdirp' when you need to ensure that a directory structure exists before performing file operations. It is ideal for scripts and applications that dynamically generate files and need to create the necessary directories on-the-fly.

  • graceful-fs:

    Use 'graceful-fs' in applications that perform numerous file operations concurrently, such as web servers, build tools, or any application that requires extensive file I/O. It is particularly beneficial in environments where file descriptor limits are a concern, ensuring smooth operation without crashes due to too many open files.

Installation and Usage

  • mkdirp:

    'mkdirp' can also be easily installed via npm. Its usage is simple and involves calling the mkdirp function with the desired path. It returns a promise, making it easy to integrate into modern async workflows, or it can accept a callback for traditional error handling.

  • graceful-fs:

    Installing 'graceful-fs' is straightforward as it can be added to your project using npm. It requires minimal changes to your existing code, as it can be used as a direct replacement for the native 'fs' module. Simply require 'graceful-fs' instead of 'fs' to start benefiting from its enhancements.

How to Choose: mkdirp vs graceful-fs
  • mkdirp:

    Choose 'mkdirp' if your primary requirement is to create directories and ensure that the entire path is created if it does not exist. It is ideal for scenarios where you need to set up directory structures dynamically without worrying about whether the parent directories are already present.

  • graceful-fs:

    Choose 'graceful-fs' if you need a more robust file system module that can handle high concurrency and prevent common file operation errors. It is particularly useful in scenarios where you are performing multiple file operations simultaneously and want to avoid issues related to file descriptor limits.

README for mkdirp

mkdirp

Like mkdir -p, but in Node.js!

Now with a modern API and no* bugs!

* may contain some bugs

example

pow.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:

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

import { mkdirp } from 'mkdirp'

mkdirp(dir: string, opts?: MkdirpOptions) => 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.

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 and nodejs/node#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 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 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