Troubleshooting and FAQ

Which version does this site describe?

The API guide covers @vooya/fs@0.1.1. Use its release source  to identify the shipped implementation. Historical benchmark reports retain their measured revisions and limits. For common tasks, start with the 0.1.0 → 0.1.1 comparison.

Cannot find the native binding

Check the runtime, architecture and installed package from your application:

node -p "process.version + ' ' + process.platform + '/' + process.arch"
npm ls @vooya/fs

Version 0.1.1 ships binaries for macOS arm64/x64, Linux x64 glibc and Windows x64. The architecture is that of the Node process, which can differ from the host under emulation. Ensure your package manager installs optional dependencies and install on the target platform; copying node_modules from a different OS is not portable.

Check the platform package as well as the main package. Choose the name for your Node process from this table, then run npm ls with that name:

For example, on Apple Silicon Node:

npm ls @vooya/fs-darwin-arm64

If the matching package is missing on a supported platform, run this in the application directory to include optional packages, then verify the import:

npm install --include=optional @vooya/fs@0.1.1
node -e "require('@vooya/fs'); console.log('native binding loaded')"

Keep your lockfile. If the package is present but loading still fails, retain the full error and the two npm ls outputs when reporting it. Linux arm64 and Alpine/musl have no 0.1.1 prebuilt package; enabling optional dependencies cannot add support for those targets.

There is no WASM fallback or automatic Node-only fallback when the addon is missing. For a source checkout, run pnpm install --frozen-lockfile and pnpm build with Rust stable installed. Source builds on other targets are not a promise of support.

Can I replace every Node fs import?

Adopt supported operations individually. There is no global patch, callback API, @vooya/fs/promises entry, or replacement for streams/watchers/fd lifecycle. Core methods support more path and option combinations than some of the smaller exports; check the specific API page. exists is an async extension, while Node provides existsSync and a legacy callback exists.

Why is Rust slower on my workload?

Native scheduling, argument conversion and result construction are part of the cost. Tiny calls may not do enough work to recover that cost. More workers can increase startup and contention. Compare the same output, options and side effects using a release build, and measure both the default and explicit worker counts. The per-API tables include losses, and Benchmarks provides repeatable commands and raw samples.

Does async mean streaming or bounded memory?

No. Promise operations return complete results. In particular, 0.1.1’s glob iterator still materializes the full array; scan returns sorted metadata for all matches. Prefer Node streams or iterators when incremental consumption and backpressure are the requirement. Async native work runs off the JavaScript thread, but conversion and consumption of a large result can still affect it.

Why does a supported option use Node?

The public entry selects Node for combinations outside a native fast path, such as copy filters or some glob patterns. This preserves the documented behavior. In 0.1.1, cpSync and rmSync always use Node. A successful call or a speed ratio alone is not proof of Rust acceleration; consult the execution policy.

Why does a line range return the whole file?

The readFile / readFileSync extension needs an explicit text encoding: { encoding: 'utf8', lines: { from: 110, to: 120 } }. With no encoding, it returns the entire file as a Buffer on both npm 0.1.0 and 0.1.1. Explicit encoding: null rejects with InvalidArg on npm 0.1.0; omit the encoding for Buffer reads on that release. See the line-range example.

There are also release-specific limits. Given one\n\nthree\n, lines 2–3 with UTF-8 return "three" on npm 0.1.0, but "\nthree" on npm 0.1.1. Upgrade to 0.1.1 to preserve selected blank lines and accept explicit encoding: null for whole-file Buffer reads.

Why does a missing file have code GenericFailure?

In npm 0.1.0, readFile and readFileSync report a missing file with code: 'GenericFailure' and an ENOENT message; path, syscall and errno are absent. Version 0.1.1 reports code: 'ENOENT' with those structured fields. Do not assume the newer fields exist when maintaining a 0.1.0 installation. Catch the Promise rejection (or the synchronous exception), log the complete error, and record the package version when reporting it. Applications that require Node’s structured error handling can keep this operation on node:fs / node:fs/promises or upgrade to 0.1.1 and verify their expected error handling.

Report a mismatch or performance regression

Open an issue  with Node/package versions, OS/architecture, checkout commit if applicable, exact options, a minimal fixture, and expected versus actual results. For performance, include release-build raw samples, workload sizes, worker count and the equivalent Node/peer baseline.