API Overview
Vooya FS exposes two related surfaces:
- Node-aligned operations keep familiar promise and synchronous shapes for a
documented subset of
node:fs. - Batch extensions combine work or make native execution policy explicit.
Compatibility is defined by the conformance suite, not by “drop-in replacement” marketing. Core batch APIs accept string, Buffer and file URL paths. A public compatibility layer uses Node for options outside the measured native path. Other exports retain their documented subsets; callback API forms remain absent.
This page describes the published 0.1.1 API. See Quick Start for the release boundary and installation instructions.
See the Node compatibility policy for remaining API and behavioral gaps.
Batch extensions
| API / option | Purpose |
|---|---|
scan | Fuse recursive walk, rooted glob filters, ignore rules, and metadata collection. |
concurrency | Bound native workers for supported recursive readdir, glob, cp, rm, and scan calls. |
readFile(..., { lines }) | Select a text line range before returning data to JavaScript. |
glob(..., { gitIgnore }) | Apply standard ignore files during traversal. |
Node-aligned operations
| API | Status | Current scope |
|---|---|---|
readdir | ✅ | withFileTypes, recursive; adds concurrency |
glob | ✅ | rooted patterns, cwd, exclude, withFileTypes; adds concurrency, gitIgnore |
readFile / writeFile / appendFile | ✅ | readFile supports core path/options routing; writes retain documented subsets |
copyFile / cp | ✅ | recursive copy options; cp adds concurrency |
mkdir / rm / rmdir | ✅ | recursive options; rm adds concurrency |
stat / lstat | ✅ | Stats dates and type methods |
access / exists | ✅ | string paths; Unix access uses OS permission checks |
link / symlink / readlink / realpath | ✅ | string paths |
rename / unlink / truncate | ✅ | path-based variants |
chmod / chown / utimes | ✅ | platform filesystem semantics |
mkdtemp | ✅ | string prefix |
exists is a Vooya Promise extension; Node has no Promise exists method.
All APIs above provide promise and sync variants, for example readdir and
readdirSync. Native async routes run Rust work away from the JavaScript event-loop
thread; other routes use Node. Sync calls block like their Node counterparts.
Deliberately not implemented
| Surface | Reason / current alternative |
|---|---|
open, close, read, write, fstat, ftruncate | A safe cross-boundary file-descriptor lifecycle is a separate design problem. Use node:fs for fd workflows. |
opendir | Native directory iterator lifetime and backpressure are not part of the current batch surface. Use readdir. |
watch, watchFile | Cross-platform event delivery needs a long-lived event bridge. Use Node watchers. |
createReadStream, createWriteStream | Streams require Node-native backpressure and piping semantics. Use Node streams. |
| callback APIs | The current library is promise-first plus synchronous APIs. |
URL / Buffer paths outside the core batch surface | Check each operation; core batch APIs support these through the public entry. |
The SDDs in test/conformance record the precise oracle, functional matrix, known
gaps, and documentation obligations for each supported API.