Quick Start

Install @vooya/fs@0.1.1, the published release covered by this guide. Its release source identifies the implementation. Upgrading from 0.1.0? Check the version comparison for common tasks.

Requirements

Use Node.js 22 or newer; the current conformance matrix checks Node 22 and 24. Prebuilt 0.1.1 packages cover macOS arm64/x64, Linux x64 with glibc, and Windows x64. Rust is needed to build a checkout, not to use a supported prebuilt package. Linux arm64 and Alpine/musl do not have published binaries in this release.

Install the published release


npm install @vooya/fs@0.1.1
# Or: pnpm add @vooya/fs@0.1.1

Keep optional dependencies enabled: the package manager selects the native binary for your platform. See installation troubleshooting if the module cannot load.

Run your first scan

Save this as scan.mjs in the project where you installed the package. This string-path example works with 0.1.1:


import { scan } from '@vooya/fs'
 
try {
  const entries = await scan('.', {
    include: ['**/*.{js,ts,rs}'],
    exclude: ['**/node_modules/**', '**/dist/**'],
    skipHidden: true,
    concurrency: 4,
  })
  console.table(entries.slice(0, 10))
  console.log(`${entries.length} matching entries`)
} catch (error) {
  console.error(error)
  process.exitCode = 1
}


node scan.mjs

scan returns an array of metadata objects sorted by relative path. An empty array is valid when no files match. It is a Vooya extension, not a Node API. Four workers are an explicit starting point for this example, not a universal optimum; tiny trees can be slower than Node. Read the scan contract and workload guide before applying it to a hot path.

For CommonJS, use const { scan } = require('@vooya/fs') and call it inside an async function or with .then(). Promise methods are exported directly from @vooya/fs; there is no @vooya/fs/promises entry. Synchronous variants such as scanSync block the JavaScript thread.

Upgrading from 0.1.0 to 0.1.1

Use this small comparison when upgrading from npm 0.1.0 to 0.1.1. It covers the operations below, not every API/option combination.

Task	npm `@vooya/fs@0.1.0`	npm `@vooya/fs@0.1.1`
Run the string-path scan example	Supported	Supported
Read lines with `encoding: 'utf8'`	Supported, but can drop leading blank lines in the selected range	Preserves selected blank lines
Pass `lines` without an encoding	Returns the whole file as a Buffer	Returns the whole file as a Buffer
Handle a missing file from `readFile` / `readFileSync`	`code: 'GenericFailure'`; ENOENT appears in the message, without structured `path`, `syscall` or `errno`	`code: 'ENOENT'` with those structured fields

The read behavior above was checked in both sync and Promise forms against separate registry installations of 0.1.0 and 0.1.1 on Node 22, macOS arm64. The 0.1.1 acceptance also ran on Node 24. This is local runtime verification, not a new cross-platform performance result. See the line-range example and error guidance.

Try the current source

To develop changes or reproduce the source-build benchmark evidence, install Git, Rust stable and pnpm 9, then build a release binding:


git clone https://github.com/vooyajs/fs.git
cd fs
pnpm install --frozen-lockfile
pnpm build
node --input-type=module -e "import { scan } from '@vooya/fs'; console.log((await scan('src')).length)"

Run that command from the repository root: the package’s self-reference resolves the local public entry. Record git rev-parse HEAD when comparing results. A checkout can contain changes beyond the published version; record the commit as well as the package version when reporting its behavior.

Adopt one operation at a time

Keep Node streams, watchers and fd workflows in node:fs. For each candidate, check its supported options and execution route, verify your application’s outputs/errors, then measure an equivalent workload. Importing Vooya FS does not patch Node or replace filesystem calls made by your dependencies.

Continue with use cases, migration, or the reproducible benchmark matrix. Contributor checks are documented in CONTRIBUTING.md .