Use Cases

Use Vooya FS when the unit of work is a tree or a batch, and keep ordinary one-off calls in node:fs.

Choose by the result you need

These are candidates to measure against your existing implementation. Evidence below comes from historical source builds on macOS; it is not a speed guarantee for an npm installation or another operating system.

Needed result	Candidate	Check before adopting
Names from a directory tree	readdir	Compare with fdir as well as Node; worker count matters.
Paths matching patterns	glob	Pattern and symlink semantics may select Node; async does not lead every peer.
Paths plus metadata and filters	scan	Avoid repeated JS metadata calls, but tiny trees lose.
Whole-file Buffer or text	readFile	Compare your sizes and encodings; batch results differ from single calls.
Copy or delete a tree	cp, rm	Measure worker counts and required options; sync forms on main use Node. cp and rm include losses.
Streams, watchers, open handles	Node	Retain Node’s lifecycle, backpressure and event APIs.

Workload examples

Repository and monorepo indexing

Use scan to discover source files and obtain size, mode, modification time, kind, and depth in one pass. This fits build graphs, language tooling, code search, and incremental cache inputs.

Build input discovery

Use rooted glob or scan include/exclude patterns to avoid returning every entry to JavaScript before filtering. Keep generated directories and dependencies out of the traversal when possible.

Package and dependency inspection

Recursive readdir and glob('**/package.json') are useful for large dependency trees where the fixed bridge cost is amortized over thousands of entries.

Cache lifecycle and workspace cleanup

Use recursive cp and rm for cache snapshots, staging directories, build output, and workspace cleanup. Bounded concurrency makes the execution policy explicit.

Partial text extraction

readFile(path, { encoding: 'utf8', lines: { from, to } }) is a Vooya FS extension for selecting a line range without decoding the complete file into a JavaScript string. Benchmark it for large text files; for streaming pipelines, continue to use Node streams.

Weak candidates

a single existence, stat, rename, or truncate call;
tiny directories repeatedly queried in a latency-sensitive path;
callback- or stream-oriented code that would need an adapter;
file-descriptor workflows, watchers, URL paths, or Buffer paths outside the current compatibility surface.

The decision rule is simple: if the application still performs thousands of native calls and JS transformations after invoking Vooya FS, look for a fused API; if the operation contains almost no work, stay with Node.