Node.js: fs-guard

fs-guard adds file system methods that aren't included in the native fs module and adds promise support to the fs methods. It also uses graceful-fs to prevent EMFILE errors. It should be a drop in replacement for fs.

Why?

I got tired of including mkdirp, rimraf, and ncp in most of my projects.

Installation

npm install fs-guard

Usage

CommonJS

fs-guard is a drop in replacement for native fs. All methods in fs are attached to fs-guard. All fs methods return promises if the callback isn't passed.

You don't ever need to include the original fs module again:

const fs = require('fs') // this is no longer necessary

you can now do this:

const fs = require('fs-guard')

or if you prefer to make it clear that you're using fs-guard and not fs, you may want to name your fs variable fse like so:

const fse = require('fs-guard')

you can also keep both, but it's redundant:

const fs = require('fs')
const fse = require('fs-guard')

NOTE: The deprecated constants fs.F_OK, fs.R_OK, fs.W_OK, & fs.X_OK are not exported on Node.js v24.0.0+; please use their fs.constants equivalents.

ESM

There is also an fs-guard/esm import, that supports both default and named exports. However, note that fs methods are not included in fs-guard/esm; you still need to import fs and/or fs/promises seperately:

import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-guard/esm'

Default exports are supported:

import fs from 'fs'
import fse from 'fs-guard/esm'
// fse.readFileSync is not a function; must use fs.readFileSync

but you probably want to just use regular fs-guard instead of fs-guard/esm for default exports:

import fs from 'fs-guard'
// both fs and fs-guard methods are defined

Sync vs Async vs Async/Await

Most methods are async by default. All async methods will return a promise if the callback isn't passed.

Sync methods on the other hand will throw if an error occurs.

Also Async/Await will throw an error if one occurs.

Example:

const fs = require('fs-guard')

// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
  .then(() => console.log('success!'))
  .catch(err => console.error(err))

// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
  if (err) return console.error(err)
  console.log('success!')
})

// Sync:
try {
  fs.copySync('/tmp/myfile', '/tmp/mynewfile')
  console.log('success!')
} catch (err) {
  console.error(err)
}

// Async/Await:
async function copyFiles () {
  try {
    await fs.copy('/tmp/myfile', '/tmp/mynewfile')
    console.log('success!')
  } catch (err) {
    console.error(err)
  }
}

copyFiles()

Methods

Async

• copy
• emptyDir
• ensureFile
• ensureDir
• ensureLink
• ensureSymlink
• mkdirp
• mkdirs
• move
• outputFile
• outputJson
• pathExists
• readJson
• remove
• writeJson

Sync

• copySync
• emptyDirSync
• ensureFileSync
• ensureDirSync
• ensureLinkSync
• ensureSymlinkSync
• mkdirpSync
• mkdirsSync
• moveSync
• outputFileSync
• outputJsonSync
• pathExistsSync
• readJsonSync
• removeSync
• writeJsonSync

NOTE: You can still use the native Node.js methods. They are promisified and copied over to fs-guard. See notes on fs.read(), fs.write(), & fs.writev()

What happened to walk() and walkSync()?

They were removed from fs-guard in v2.0.0. If you need the functionality, walk and walkSync are available as separate packages, klaw and klaw-sync.

Credit

fs-guard wouldn't be possible without using the modules from the following authors:

• Isaac Shlueter
• Charlie McConnel
• James Halliday
• Andrew Kelley

License

Licensed under MIT

Copyright (c) 2011-2024 JP Richardson