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?

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.67417% with 192 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.21%. Comparing base (131fd84) to head (ac2b81e).
⚠️ Report is 52 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%	32 Missing and 1 partial ⚠️
lib/internal/vfs/providers/real.js	96.01%	19 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/fd.js	97.70%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63115      +/-   ##
==========================================
- Coverage   91.94%   90.21%   -1.73%     
==========================================
  Files         362      726     +364     
  Lines      155999   231648   +75649     
  Branches    24057    43692   +19635     
==========================================
+ Hits       143429   208989   +65560     
- Misses      12295    14433    +2138     
- Partials      275     8226    +7951

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	`96.28% <100.00%> (+0.69%)`	⬆️
lib/internal/modules/cjs/loader.js	`98.04% <100.00%> (+19.43%)`	⬆️
lib/internal/process/pre_execution.js	`98.28% <100.00%> (+15.17%)`	⬆️
lib/internal/vfs/dir.js	`100.00% <100.00%> (ø)`
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.51% <100.00%> (ø)`
src/node_options.cc	`76.55% <100.00%> (ø)`
src/node_options.h	`98.00% <100.00%> (ø)`
... and 8 more

... and 486 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.

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

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

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

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

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

Can you add a test for #63158?

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

The getter exposed the raw real-fs file descriptor of a virtual file handle, which is a leaky abstraction: it lets user code bypass the VFS layer. The only consumer was a test that closed the real fd to trigger the EBADF rejection paths in the async fd ops; those branches are defensive and unreachable from the public API, so the test block is dropped along with the getter. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com>

* file_handle: import SymbolDispose from primordials so the SymbolDispose prototype binding doesn't throw at load time. * providers/real: import getValidatedPath and setOwnProperty that the code-review rewrite of the rootPath validator referenced without importing. * test-vfs-real-provider: getValidatedPath rejects non-strings with ERR_INVALID_ARG_TYPE (not ERR_INVALID_ARG_VALUE) and now accepts the empty string, so the assertions are updated and the empty-string case dropped. * test-vfs-memory-provider-dynamic: the object-literal rewrite left a stray ');' instead of '}', which crashed the parser. Signed-off-by: Matteo Collina <hello@matteocollina.com>

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Tracks the suggestion from review to delegate the async fd ops in RealFileHandle to FileHandle methods instead of manually wrapping fs.read/write/fstat/ftruncate/close in Promises. The refactor is blocked on a way to wrap an existing numeric fd in a FileHandle so a sync-opened handle can share one underlying handle for async ops. Signed-off-by: Matteo Collina <hello@matteocollina.com>

nodejs-github-bot · 2026-05-17T10:08:07Z

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

RealFSProvider.realpath fed the resolved path through StringPrototype startsWith against the stored rootPath plus a separator. On Windows fs.realpathSync is a JS implementation that preserves case while fs.promises.realpath calls the native binding, which canonicalizes the drive letter (and potentially other components). The async path then fails the startsWith check and rejects with EACCES, even for valid paths inside the root. Use path.relative to test containment instead, which treats the comparison as case-insensitive on Windows. Both realpathSync and realpath now share the same helper. Fixes failure in test-vfs-real-provider-symlinks on test-binary-windows-js-suites. Signed-off-by: Matteo Collina <hello@matteocollina.com>

nodejs-github-bot · 2026-05-17T11:51:06Z

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

nodejs-github-bot · 2026-05-18T09:28:34Z

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

aduh95 · 2026-05-18T13:46:41Z

+  let data = '';
+
+  stream.on('open', common.mustCall((fd) => {
+    assert.ok((fd & 0x40000000) !== 0);


Suggested change

assert.ok((fd & 0x40000000) !== 0);

assert.notStrictEqual(fd & 0x40000000, 0);

aduh95 · 2026-05-18T13:48:45Z

+  ws.on('error', common.mustCall((err) => {
+    assert.ok(err);
+  }));


Suggested change

ws.on('error', common.mustCall((err) => {

assert.ok(err);

}));

ws.on('error', common.expectsError());

aduh95 · 2026-05-18T13:49:10Z

+  ws.on('error', common.mustCall((err) => {
+    assert.ok(err);
+  }));


Suggested change

ws.on('error', common.mustCall((err) => {

assert.ok(err);

}));

ws.on('error', common.expectsError());

aduh95 · 2026-05-18T13:49:43Z

+  const fd = myVfs.openSync('/cl.txt');
+  const rs = myVfs.createReadStream('/cl.txt', { fd, autoClose: true });
+  myVfs.closeSync(fd);
+  rs.on('error', common.mustCall());


Suggested change

rs.on('error', common.mustCall());

rs.on('error', common.expectsError());

aduh95 · 2026-05-18T13:50:32Z

+  rs.on('error', common.mustCall((err) => {
+    assert.strictEqual(err.code, 'EBADF');
+  }));


Suggested change

rs.on('error', common.mustCall((err) => {

assert.strictEqual(err.code, 'EBADF');

}));

rs.on('error', common.expectsError({

code: 'EBADF',

}));

aduh95 · 2026-05-18T13:50:47Z

+  stream.on('error', common.mustCall((err) => {
+    assert.strictEqual(err.code, 'ENOENT');
+  }));


Suggested change

stream.on('error', common.mustCall((err) => {

assert.strictEqual(err.code, 'ENOENT');

}));

stream.on('error', common.expectsError({

code: 'ENOENT',

}));

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> Co-authored-by: Matteo Collina <matteo.collina@gmail.com>

aduh95 · 2026-05-18T14:33:07Z

+  const fh = await myVfs.promises.open('/hello.txt', 'r');
+  assert.ok(fh);
+  assert.ok(typeof fh === 'number' || typeof fh === 'object');


That's a strangely loose assertion. Why? Do we expect this to change?

* test-vfs-stream-errors: drop the unused `assert` import. * test-vfs-streams: capitalize a lowercase comment to satisfy capitalized-comments. Signed-off-by: Matteo Collina <hello@matteocollina.com>

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

spawnSyncAndAssert handles the expected stderr/status, so the top-level `assert` is no longer referenced. Signed-off-by: Matteo Collina <hello@matteocollina.com>

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 2 times, most recently 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

Comment thread doc/api/vfs.md Outdated

aduh95 reviewed May 7, 2026

View reviewed changes

Comment thread doc/api/vfs.md Outdated

aduh95 reviewed May 7, 2026

View reviewed changes

Comment thread lib/internal/bootstrap/realm.js Outdated

mcollina force-pushed the vfs-minimal branch from de4882c to cb420d9 Compare May 11, 2026 06:53

ShogunPanda approved these changes May 11, 2026

View reviewed changes

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

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

mcollina and others added 2 commits May 15, 2026 07:06

Apply suggestions from code review

e947d94

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

ljharb reviewed May 15, 2026

View reviewed changes

Comment thread doc/api/vfs.md Outdated

mcollina added 3 commits May 16, 2026 12:03

fixup typo

a58b46b

Signed-off-by: Matteo Collina <hello@matteocollina.com>

ShogunPanda approved these changes May 17, 2026

View reviewed changes

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

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

ShogunPanda approved these changes May 18, 2026

View reviewed changes

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

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