vfs: add minimal node:vfs subsystem#63115
Draft
mcollina wants to merge 11 commits intonodejs:mainfrom
Draft
Conversation
Adds the node:vfs builtin module with VirtualFileSystem and provider classes. No integration with fs, modules, or SEA. Assisted-by: Claude-Opus4.7
Adapts tests that exercised behavior through fs integration so they call the VFS API directly instead. Assisted-by: Claude-Opus4.7
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
Covers MemoryProvider, copyFile mode, rm edge cases, hardlinks, bigint read positions, and parent timestamps via the VFS API. Assisted-by: Claude-Opus4.7
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
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
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
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
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
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
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
Collaborator
|
Review requested:
|
nodejs-github-bot
added
lib / src
jasnell
approved these changes
May 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an experimental
node:vfsbuiltin (gated behind--experimental-vfs) withVirtualFileSystem,VirtualProvider,MemoryProvider, andRealFSProvider. No integration withnode: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.