Node.js filesystem compatibility / ISC

@stackline/graceful-fs

A maintained, dependency-free continuation of the established [email protected] contract, with bounded descriptor-exhaustion retries and current compatibility gates.

npm install @stackline/graceful-fs

Preserve an existing import with "graceful-fs": "npm:@stackline/[email protected]".

Release: 1.0.0
Runtime: Node 14.14+
Formats: CommonJS + types
Production graph: 0 dependencies
Baseline: graceful-fs 4.2.11

01 / Compatibility contract

Filesystem semantics stay familiar.

The package exports the patched Node fs object and preserves historical helpers such as gracefulify, close, closeSync, and supported deep entries. Callback and promise forms continue to follow the Node APIs they wrap.

Existing code can keep require('graceful-fs') through the npm alias. The migration changes package provenance, not the runtime import key.

02 / Bounded recovery

Descriptor pressure is queued, not ignored.

open / readdirEMFILE or ENFILEshared queuebounded backoffretry or callback

What is retried. Operations affected by process or system file-descriptor exhaustion join the shared queue. Successful closes wake queued work.

What remains observable. Non-retryable errors are returned normally. Retry time and queue state are bounded; the package does not turn persistent resource exhaustion into an infinite wait.

What callers still own. Concurrency, file-count limits, cancellation, paths, permissions, and workload admission remain application responsibilities.

03 / Migration

Choose the import identity.

Keep the historical key

"graceful-fs": "npm:@stackline/[email protected]"

Existing require('graceful-fs') and supported deep imports remain unchanged.

Use the scoped package

const fs = require('@stackline/graceful-fs')

Use this form when changing the import is acceptable and explicit provenance is preferred.

04 / Release evidence

The packed artifact is tested as a consumer sees it.

Exact upstream 4.2.11 suite in normal and global-queue modes
Node 14.14 through current and future runtime lanes
Windows, macOS, and Linux filesystem behavior
TypeScript 3.9 and current compiler declarations
Direct and historical-key clean production installs
Downstream checks for fs-extra, node-gyp, Jest, and npm CLI
CycloneDX SBOM and zero-vulnerability production audit

05 / Reference

Read the maintained contract.

READMEInstallation and API use CompatibilityPreserved behavior and limits MigrationAlias, rollback, and checks SecurityTrust boundary and reporting ChangelogRelease history LicensesAttribution and production graph Machine referenceCompact complete contract MetadataVersioned package identity