readdir
This page describes
@vooya/fs@0.1.1. See Node compatibility and execution policy for native fast paths, Node routes and verified limits.
Read the contents of a directory. Supports non-recursive and recursive modes; recursive mode uses parallel traversal and benefits most from Vooya FS.
Basic usage
import { readdir } from '@vooya/fs'
// Names only (default)
const names = await readdir('./src')
// e.g. ['a.ts', 'b.ts', 'utils']
// With file types (like Dirent)
const entries = await readdir('./src', { withFileTypes: true })
// entries[0].name, entries[0].parentPath, entries[0].isDirectory()
// Recursive with concurrency (Vooya FS extension)
const all = await readdir('./src', {
recursive: true,
withFileTypes: true,
concurrency: 4,
})Methods
readdir(path, options?)
Async. Returns a Promise of names (string[] or Buffer[]) or Dirents when
withFileTypes: true. Dirents expose name, parentPath and type predicates.
| Argument | Type | Description |
|---|---|---|
path | string / Buffer / URL | Directory path to read. |
options | object | Optional. See below. |
Options:
| Option | Type | Default | Description |
|---|---|---|---|
encoding | string | 'utf8' | Node filename encodings; 'buffer' returns raw bytes. |
withFileTypes | boolean | false | If true, returns Dirent objects with name, parentPath and type methods. |
recursive | boolean | false | If true, walks the directory tree recursively. |
concurrency | number | auto | (Vooya FS) Max concurrent tasks for recursive walk. |
readdirSync(path, options?)
Sync. Same arguments and return types; throws on error.
An explicit encoding: null uses UTF-8 filenames, just like omitting the encoding.
This applies to both names and Dirent results, including recursive reads.
Performance
- Recursive (
recursive: true): Vooya FS can be faster on medium and large trees because it uses jwalk for parallel directory traversal. The checked-in scale report below is the current evidence; rerun it for your storage and tree shape. - Tiny / non-recursive directories: Node.js can be faster because the fixed N-API bridge cost dominates. Use Vooya FS for recursive or larger directory walks where traversal work can amortize the bridge overhead.
See Batch API evidence for the current measurements and their limits.
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
| Scale | Fixture | Node.js | Vooya FS | Ratio | Node RSS | Vooya FS RSS |
|---|---|---|---|---|---|---|
| tiny | 8 files / 2 dirs | 0.18 ms | 0.20 ms | 1.11x slower | 0 B | 4.8 KB |
| small | 104 files / 13 dirs | 0.77 ms | 0.33 ms | 2.31x faster | 0 B | 1.6 KB |
| medium | 2728 files / 341 dirs | 19.30 ms | 4.60 ms | 4.19x faster | 1.6 KB | 9.6 KB |
Notes
- Encoding:
encoding: 'buffer'returns Buffer names. Other encodings return strings; advanced encoding combinations use Node. - Symbolic links: Recursive names-only traversal follows directory links; Promise Dirent traversal does not. Sync Dirent traversal follows them. The link itself retains its symlink type.
- Errors: Same error codes as Node.js (e.g.
ENOENT,EACCES). Promises reject; synchronous methods throw. - Scale guidance:
test/performance/readdirtracks tiny/small/medium/large behavior so the docs can keep the bridge-overhead boundary visible.
Path and result forms
The public entry accepts strings, UTF-8 Buffer paths and file URLs. Non-UTF-8
Buffer paths use Node. Encoding can be passed as a string or options object;
buffer preserves filename bytes, including Dirent names. Recursive Buffer
requests use Node to retain runtime-specific behavior. Symlink traversal follows
the supported runtime’s sync/Promise distinction. Empty paths reject.
Competitor measurements
See the full readdir comparison table for Node 22/24, peer libraries, sync/Promise modes, small and batch workloads, execution routes and measurement limits.