stat

Get file/directory metadata. Follows symlinks; use lstat to inspect the link itself.

Basic usage


import { stat } from '@vooya/fs'
 
const s = await stat('./package.json')
console.log(s.size, s.isFile(), s.isDirectory())
console.log(s.mtime, s.atime)

Methods

`stat(path)`

Async. Returns Promise<Stats>.

Argument	Type	Description
`path`	string	File or directory path.

Stats: Numeric fields (dev, mode, nlink, uid, gid, rdev, blksize, ino, size, blocks, atimeMs, mtimeMs, ctimeMs, birthtimeMs), Date fields (atime, mtime, ctime, birthtime), methods (isFile(), isDirectory(), isSymbolicLink(), etc.). Error distinction: ENOENT vs EACCES.

`statSync(path)`

Sync. Same arguments; returns Stats or throws.

Performance

From repo benchmarks (pnpm build && pnpm bench):

Scenario	Node.js	Vooya FS	Ratio
stat (single file)	1.45 µs	1.77 µs	1.2x

On par with Node.js; small N-API overhead per call.

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
single-file	-	0.05 ms	0.03 ms	1.42x faster	27.2 KB	3.2 KB
directory	-	0.04 ms	0.03 ms	1.26x faster	0 B	0 B
batch-128-files	-	1.44 ms	1.48 ms	1.03x slower	8.0 KB	0 B

Notes

Symlinks: stat follows symlinks; use lstat for the link metadata.
Dates: atime, mtime, ctime, birthtime are Date objects; *Ms are numbers.
Known gap: Missing-path errors currently have Node-like messages, but do not expose Node-style code, path, and syscall fields yet.
Unsupported Node options: bigint, throwIfNoEntry, Buffer paths, and URL paths are not part of the current Vooya FS stat surface.

Competitor measurements

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