# @stackline/graceful-fs 1.0.0

Canonical documentation: https://alexandro.net/docs/vanilla/graceful-fs/
Repository: https://github.com/alexandroit/stackline-graceful-fs
Registry: https://www.npmjs.com/package/@stackline/graceful-fs
License: ISC
Runtime: Node.js >=14.14.0
Browser support: none
Compatibility baseline: graceful-fs@4.2.11
Production dependencies: none

## Installation

Scoped package: npm install @stackline/graceful-fs
Compatibility alias: "graceful-fs": "npm:@stackline/graceful-fs@1.0.0"

The alias preserves require('graceful-fs') and supported historical deep
imports. Commit the package manifest and lockfile together, then test the
consumer's ordinary filesystem workload.

## Contract

The package exports a patched Node.js fs object. It preserves callback and
promise behavior from the wrapped Node APIs plus gracefulify, close,
closeSync, and the supported clone, legacy-streams, and polyfills entries.

EMFILE and ENFILE failures from affected open and readdir operations enter a
shared queue. Successful closes wake queued work. Retry delay and total queue
age are bounded. Non-retryable errors remain observable through the original
callback or promise behavior.

The implementation has zero runtime dependencies and does not patch global
Object.prototype or accept untrusted object-merge input.

## Compatibility evidence

- Exact graceful-fs 4.2.11 suite in normal and global-queue modes.
- Node.js 14.14.0 through current and forward runtime lanes.
- Windows, macOS, and Linux filesystem behavior.
- TypeScript 3.9 and current declaration checks.
- Clean direct and historical-key packed consumers.
- Downstream fs-extra, node-gyp, Jest, and npm CLI compatibility suites.
- CycloneDX SBOM, registry signatures, and zero-vulnerability audits.

## Trust boundary

This package coordinates descriptor-exhaustion recovery; it is not a sandbox,
transaction layer, path policy, cancellation framework, or workload limiter.
Applications must validate paths and permissions, limit concurrency and file
counts, and define cancellation and timeout behavior for their own workloads.

## References

README: https://alexandro.net/docs/vanilla/graceful-fs/README.md
Compatibility: https://alexandro.net/docs/vanilla/graceful-fs/COMPATIBILITY_CONTRACT.md
Migration: https://alexandro.net/docs/vanilla/graceful-fs/MIGRATION.md
Security: https://alexandro.net/docs/vanilla/graceful-fs/SECURITY.md
Changelog: https://alexandro.net/docs/vanilla/graceful-fs/CHANGELOG.md
Licenses: https://alexandro.net/docs/vanilla/graceful-fs/THIRD_PARTY_LICENSES.md
Metadata: https://alexandro.net/docs/vanilla/graceful-fs/package-meta.json