scan

This page describes @vooya/fs@0.1.1. See Node compatibility and execution policy for native fast paths, Node routes and verified limits.

Walk a directory tree, apply rooted include/exclude patterns, and return metadata in one native operation. scan is a Vooya FS extension, not a Node fs compatibility API.

Basic usage

import { scan } from '@vooya/fs'
 
const entries = await scan('./packages', {
  include: ['**/*.{ts,tsx,rs}'],
  exclude: ['**/node_modules/**', '**/dist/**'],
  skipHidden: true,
  gitIgnore: true,
  concurrency: 4,
})

Methods

scan(root, options?)

Returns Promise<ScanEntry[]>.

scanSync(root, options?)

Returns ScanEntry[] and throws on error.

Options

Result

Each result contains:

interface ScanEntry {
  path: string // relative to root
  name: string
  kind: 'file' | 'directory' | 'symlink' | 'other'
  size: number
  mode: number
  mtimeMs: number
  depth: number
}

Results are sorted by relative path for deterministic builds. Traversal and metadata errors reject the entire operation instead of returning an incomplete result.

File sizes are byte lengths. Directory sizes follow Node’s metadata convention: Windows directories report 0; Unix directories retain their filesystem-reported size. With followSymlinks: true, directory links use the target directory’s size. Unfollowed links retain link metadata and are not normalized as directories.

When it wins

scan is designed to replace recursive readdir followed by many stat/lstat calls and JavaScript-side filtering. Native worker startup can dominate tiny trees. Use the current evidence to choose workloads where traversal and metadata work are large enough to amortize that cost.

Local scale report

Generated from local performance reports. Do not edit this block by hand.

• Runtime: v22.22.0 on darwin/arm64
• Samples: 2 warmup runs, 10 measured runs
• Aggregation: trimmed mean for wall-clock time; average per-run memory delta for RSS

Competitor measurements

See the full scan comparison table for Node 22/24, peer libraries, sync/Promise modes, small and batch workloads, execution routes and measurement limits.