@zokugun/fs-extra-plus

Wraps node:fs to fully typed functions that resolve to a Result. Includes additional helpers.

Overview

@zokugun/fs-extra-plus is a TypeScript-first port and fork of fs-extra. The goal is to keep the battle-tested surface area of fs-extra while:

• rewriting everything in strict TypeScript so typings always match the implementation,
• every functions resolves to a Result object instead of throwing. So you handle errors explicitly without exceptions.
• publishing dual ESM/CJS builds with identical named exports,
• tracking the latest Node.js fs additions (including glob, mkdtempDisposable, etc.),
• shipping first-party async and sync entry points to help bundlers tree-shake unused helpers,
• documenting the mode helpers so you can translate permissions between number, octal, stat, symbolic, and object forms.

Installation

npm add @zokugun/fs-extra-plus

Usage

ESM / TypeScript

import { ensureDir, pathExists, readJson, type FsVoidResult } from '@zokugun/fs-extra-plus/async';

async function main(): Promise<FsVoidResult> {
    const dir = await ensureDir('dist/cache');
    if (dir.fails) {
        return dir;
    }

    const exists = await pathExists('package.json'); // always Success<boolean>
    if (exists.value) {
        const pkg = await readJson('package.json');
        if (pkg.fails) {
            return pkg;
        }

        console.log(pkg.value.name);
    }
}

CommonJS

const { ensureDir, copy, type FsVoidResult } = require('@zokugun/fs-extra-plus/sync');

function main(): FsVoidResult {
    const dir = ensureDir('dist/assets');
    if (dir.fails) {
        return dir;
    }

    const copy = copy('static/logo.svg', 'dist/assets/logo.svg');
    if (copy.fails) {
        return copy;
    }
}

Entry points

• @zokugun/fs-extra-plus — mixed bundle exporting both async, sync and mode helpers. Functions have Async or Sync suffixes
• @zokugun/fs-extra-plus/async — async helpers only. no suffixes.
• @zokugun/fs-extra-plus/sync — sync helpers only. no suffixes.
• @zokugun/fs-extra-plus/mode — mode helpers only.

Donations

Support this project by becoming a financial contributor.

License

Copyright © 2026-present Baptiste Augrain

Licensed under the MIT license.