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.69092% with 191 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (131fd84) to head (1639c59).
⚠️ Report is 113 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/vfs/providers/memory.js	93.64%	61 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.24%   -1.70%     
==========================================
  Files         362      726     +364     
  Lines      155999   231715   +75716     
  Branches    24057    43706   +19649     
==========================================
+ Hits       143429   209113   +65684     
- Misses      12295    14388    +2093     
- Partials      275     8214    +7939

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.32% <100.00%> (ø)`
src/node_options.cc	`76.65% <100.00%> (ø)`
src/node_options.h	`98.00% <100.00%> (ø)`
... and 8 more

... and 492 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?

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>

* 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 · 2026-05-19T20:37:02Z

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

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

Qard

LGTM. Some minor improvements which could be made, but nothing which needs to block landing. 🙂

ShogunPanda

LGTM!

nodejs-github-bot · 2026-05-21T13:51:03Z

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

The currentPath segment used for symlink resolution and for the #ensurePopulated call below was being computed twice in the loop body. Compute it once at the top of the iteration and reuse it in both branches. 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

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