fs-result

Typed Result wrappers for Node.js filesystem operations. Filesystem failures are returned as serializable plain objects instead of being thrown, so callers can branch on native error codes such as ENOENT, EACCES, and EEXIST.

Install

npm install fs-result

ESM-only. Requires Node.js 20+ and uses plain-result for the Result contract.

Usage

import { isErr } from 'plain-result'
import { readJsonFile, writeFile } from 'fs-result'

const settings = await readJsonFile<{ theme: string }>('settings.json')

if (isErr(settings)) {
  if (settings.error.name === 'FsError' && settings.error.code === 'ENOENT') {
    await writeFile('settings.json', JSON.stringify({ theme: 'system' }))
  } else {
    console.error(settings.error.message)
  }
}

Every filesystem wrapper returns a PResult:

interface FsErr {
  name: 'FsError'
  message: string
  code?: string
}

The package provides wrappers for reading, writing, appending, copying, renaming, removing, listing, creating, resolving, and statting files and directories. It also provides readJsonFile() and exists().

exists() returns false for any failed stat, not only ENOENT. Use stat() directly when callers need to distinguish a missing path from errors such as EACCES.

Releasing

Maintainers can run npm run release from a clean main branch. The command publishes the current version when it is not on npm yet; subsequent runs bump the patch version. Use npm run release -- minor or npm run release -- major to select a larger version bump. The workflow verifies the package, creates and pushes the Git tag, and publishes to npm using the current npm credentials.