vfs: add minimal node:vfs subsystem by mcollina · Pull Request #63115 · nodejs/node

mcollina · 2026-05-04T15:09:34Z

Adds an experimental node:vfs builtin (gated behind --experimental-vfs) with VirtualFileSystem, VirtualProvider, MemoryProvider, and RealFSProvider. No integration with node:fs, the module loader, or SEA those are intended to land in follow-up PRs.

Extracted from: #61478

Approximate line counts: code ~4k / docs ~1k / tests ~5k — total ~10k lines, with tests being the largest share.

nodejs-github-bot · 2026-05-04T15:09:40Z

Review requested:

@nodejs/config
@nodejs/loaders
@nodejs/startup

bakkot · 2026-05-04T18:37:03Z

No integration with node:fs

The docs in this PR claim that you can call myVfs.mount('/virtual') and subsequently regular node:fs operations which read from paths beginning with /virtual will read from the VFS. That sounds like integration to me. Are the docs wrong, or am I misunderstanding what "no integration" means?

Adds the node:vfs builtin module with VirtualFileSystem and provider classes. No integration with fs, modules, or SEA. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Adapts tests that exercised behavior through fs integration so they call the VFS API directly instead. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Cover VirtualDir iteration and disposal, MemoryFileHandle read/write methods via the provider, and the VirtualProvider base class (capability flags, readonly stubs, default implementations). Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Covers MemoryProvider, copyFile mode, rm edge cases, hardlinks, bigint read positions, and parent timestamps via the VFS API. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Cover the callback-style async API, additional read/write stream flows, the promises.watch async iterable, and async methods of RealFSProvider. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Removes the unused createEXDEV error helper, adds direct tests for MemoryProvider numeric flags / symlink loops / utimes variants, and adds a base-class VirtualFileHandle test. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Adds targeted tests covering the lazy population, dynamic content provider, readonly-mode, and symlink-traversal paths in MemoryProvider; the path-escape and RealFileHandle EBADF paths in RealFSProvider; the abort/buffer-encoding/recursive watch paths in VFSWatcher; and the empty-file / EBADF fd / explicit-fd-with-start paths in the streams. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Adds direct unit tests for stats default-option paths (including the process.getuid?.() fallback), file-handle base-class branches, the empty-options provider write/append paths, the access-mode permission denials, the watcher closed-state and async-iterable resolver-drain branches, and various RealFSProvider escape and EBADF paths. Brings overall branch coverage from 89% to 95.7%, and stats.js to 100% branch coverage. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Replaces the -coverage / -branches / -misc suffixes with focused files named after the API or behaviour they exercise. Splits the larger multi-topic files into one-topic-per-file. Renames: - callbacks.js → callback-api.js - stats-defaults.js → stats-helpers.js - file-handle-base.js → virtual-file-handle.js - provider-base.js → virtual-provider.js - provider-memory.js → memory-provider.js - real-provider-async.js → real-provider-promises.js - mkdir-recursive-return.js → mkdir.js New files (split out of -coverage/-branches/-misc): - access-modes, create, link, mkdtemp, rename, symlinks, utimes, write-options - memory-file-handle, memory-provider-dynamic, memory-provider-flags - real-provider-handle, real-provider-symlinks, real-provider-watch - stream-errors, stream-explicit-fd - watch, watch-abort-signal, watch-encoding, watch-promises, watch-recursive Coverage maintained at 97.6% line / 95.2% branch / 95.3% function. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Adds an --experimental-vfs runtime option that gates loading of the node:vfs builtin module, matching the pattern used by node:quic and node:stream/iter. Without the flag, require('node:vfs') / import 'node:vfs' throw ERR_UNKNOWN_BUILTIN_MODULE. All VFS test files are updated to pass --experimental-vfs. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

@returns

Fixes the JS lint warnings on the VFS subsystem and tests: primordial alphabetical ordering, em-dash → hyphen, error-codes multiline destructuring, removal of unused JSDoc @returns, and the test-side mustSucceed / async-iife-no-unused-result rules. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

internal/vfs/fd.js doesn't require any internal/vfs/* modules so there's no circular dependency to defer. Replace the getLazy wrapper with a direct import. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Removes mount/unmount, virtualCwd, overlay mode, fs/module integration sections, SEA usage, and worker-thread guidance since none of that ships in this PR. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

mcollina · 2026-05-05T10:04:50Z

No integration with node:fs

The docs in this PR claim that you can call myVfs.mount('/virtual') and subsequently regular node:fs operations which read from paths beginning with /virtual will read from the VFS. That sounds like integration to me. Are the docs wrong, or am I misunderstanding what "no integration" means?

Fixed, good spot.

codecov · 2026-05-05T11:47:05Z

Codecov Report

❌ Patch coverage is 96.67992% with 192 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.89%. Comparing base (9390c81) to head (117d09a).
⚠️ Report is 41 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/vfs/providers/memory.js	93.55%	62 Missing and 4 partials ⚠️
lib/internal/vfs/file_system.js	96.68%	38 Missing ⚠️
lib/internal/vfs/watcher.js	95.20%	31 Missing and 2 partials ⚠️
lib/internal/vfs/providers/real.js	96.54%	17 Missing ⚠️
lib/internal/vfs/streams.js	95.46%	16 Missing ⚠️
lib/internal/vfs/provider.js	98.38%	10 Missing ⚠️
lib/internal/vfs/file_handle.js	98.88%	7 Missing and 1 partial ⚠️
lib/internal/vfs/dir.js	98.16%	2 Missing ⚠️
lib/internal/vfs/fd.js	97.70%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63115      +/-   ##
==========================================
+ Coverage   89.65%   89.89%   +0.24%     
==========================================
  Files         712      725      +13     
  Lines      220829   230242    +9413     
  Branches    42375    43400    +1025     
==========================================
+ Hits       197986   206982    +8996     
- Misses      14655    15065     +410     
- Partials     8188     8195       +7

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	`96.22% <100.00%> (+<0.01%)`	⬆️
lib/internal/process/pre_execution.js	`98.28% <100.00%> (-0.11%)`	⬇️
lib/internal/vfs/errors.js	`100.00% <100.00%> (ø)`
lib/internal/vfs/stats.js	`100.00% <100.00%> (ø)`
lib/vfs.js	`100.00% <100.00%> (ø)`
src/node_builtins.cc	`76.32% <100.00%> (+0.23%)`	⬆️
src/node_options.cc	`76.63% <100.00%> (+0.02%)`	⬆️
src/node_options.h	`98.00% <100.00%> (+0.01%)`	⬆️
lib/internal/vfs/dir.js	`98.16% <98.16%> (ø)`
lib/internal/vfs/fd.js	`97.70% <97.70%> (ø)`
... and 7 more

... and 69 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Adds 'vfs' to the C++ cannot_be_required list so existing tests (test-code-cache, test-process-get-builtin, test-require-resolve) treat it like other flagged experimental modules. Adds the flag to doc/node.1 and reorders the entry in doc/api/cli.md. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

nodejs-github-bot · 2026-05-06T08:07:49Z

CI: https://ci.nodejs.org/job/node-test-pull-request/73198/

The first block used persistent: false plus setTimeout to trigger the write. The watcher's poll timer was unref'd, so on slow runners the write timer could fire before the first poll and the change event would be missed. Use the same await-once pattern as the other blocks in the file with a content-length change so the size-based stat-change detector always fires. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

nodejs-github-bot · 2026-05-07T06:23:28Z

CI: https://ci.nodejs.org/job/node-test-pull-request/73221/

aduh95 · 2026-05-07T08:22:10Z

+scenarios where you need a self-contained file system without touching the
+real disk.


There are likely no disk involved :p

Suggested change

scenarios where you need a self-contained file system without touching the

real disk.

scenarios where you need a self-contained file system without touching the

actual file-system.

aduh95 · 2026-05-07T08:22:59Z

+A `VirtualFileSystem` wraps a [`VirtualProvider`][] and exposes an
+`fs`-like API. Each instance maintains its own file tree.


Suggested change

A `VirtualFileSystem` wraps a [`VirtualProvider`][] and exposes an

`fs`-like API. Each instance maintains its own file tree.

A `VirtualFileSystem` wraps a [`VirtualProvider`][] and exposes a

`node:fs`-like API. Each instance maintains its own file tree.

aduh95 · 2026-05-07T08:25:41Z

 ]);
 // Modules that will only be enabled at run time.
-const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter']);
+const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter', 'vfs']);


We should probably make this multiline at this point (and use ASCII order)

Suggested change

const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter', 'vfs']);

const experimentalModuleList = new SafeSet([

'ffi',

'quic',

'sqlite',

'stream/iter',

'vfs',

'zlib/iter',

]);

aduh95 · 2026-05-07T08:29:20Z

Can you add a test for #63158?

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels May 4, 2026

jasnell approved these changes May 4, 2026

View reviewed changes

mcollina force-pushed the vfs-minimal branch from 6368d58 to 30f5755 Compare May 5, 2026 05:35

mcollina added 13 commits May 5, 2026 10:33

vfs: add minimal node:vfs subsystem

5bbcbad

Adds the node:vfs builtin module with VirtualFileSystem and provider classes. No integration with fs, modules, or SEA. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

test: add VFS API tests adapted from mount-based tests

fff45aa

Adapts tests that exercised behavior through fs integration so they call the VFS API directly instead. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

test: adapt more VFS tests to direct API

d01bfc1

Covers MemoryProvider, copyFile mode, rm edge cases, hardlinks, bigint read positions, and parent timestamps via the VFS API. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: import getVirtualFd eagerly in streams

cdf2a0d

internal/vfs/fd.js doesn't require any internal/vfs/* modules so there's no circular dependency to defer. Replace the getLazy wrapper with a direct import. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

doc: trim vfs docs to match the minimal API

779fc37

Removes mount/unmount, virtualCwd, overlay mode, fs/module integration sections, SEA usage, and worker-thread guidance since none of that ships in this PR. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

mcollina force-pushed the vfs-minimal branch from 30f5755 to 779fc37 Compare May 5, 2026 09:30

mcollina marked this pull request as ready for review May 5, 2026 10:04

ShogunPanda approved these changes May 5, 2026

View reviewed changes

ShogunPanda approved these changes May 6, 2026

View reviewed changes

mcollina added help wanted Issues that need assistance from volunteers or PRs that need help to proceed. request-ci Add this label to start a Jenkins CI on a PR. labels May 6, 2026

mcollina mentioned this pull request May 6, 2026

Virtual File System for Node.js #61478

Open

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label May 6, 2026

ronag approved these changes May 6, 2026

View reviewed changes

ShogunPanda approved these changes May 7, 2026

View reviewed changes

mcollina added the request-ci Add this label to start a Jenkins CI on a PR. label May 7, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label May 7, 2026

aduh95 reviewed May 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

vfs: add minimal node:vfs subsystem#63115

vfs: add minimal node:vfs subsystem#63115
mcollina wants to merge 15 commits intonodejs:mainfrom
mcollina:vfs-minimal

mcollina commented May 4, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented May 4, 2026

Uh oh!

bakkot commented May 4, 2026

Uh oh!

mcollina commented May 5, 2026

Uh oh!

codecov Bot commented May 5, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented May 6, 2026

Uh oh!

nodejs-github-bot commented May 7, 2026

Uh oh!

aduh95 May 7, 2026

Uh oh!

aduh95 May 7, 2026

Uh oh!

aduh95 May 7, 2026

Uh oh!

aduh95 commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

		scenarios where you need a self-contained file system without touching the
		real disk.

		A `VirtualFileSystem` wraps a [`VirtualProvider`][] and exposes an
		`fs`-like API. Each instance maintains its own file tree.

Uh oh!

Conversation

mcollina commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented May 4, 2026

Uh oh!

bakkot commented May 4, 2026

Uh oh!

mcollina commented May 5, 2026

Uh oh!

codecov Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nodejs-github-bot commented May 6, 2026

Uh oh!

nodejs-github-bot commented May 7, 2026

Uh oh!

aduh95 May 7, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 May 7, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 May 7, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mcollina commented May 4, 2026 •

edited

Loading

codecov Bot commented May 5, 2026 •

edited

Loading