Virtual File System for Node.js

doc/api/fs.md

@@ -121,6 +121,36 @@ try {
 }
 ```
 
+## Virtual File System (VFS) support
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+The `node:fs` module can operate on virtual files when the [`node:vfs`][] module is
+used. When a virtual file system is mounted, `node:fs` operations on paths under
+the mount point are automatically routed to the VFS instead of the real file
+system.
+
+```cjs
+const vfs = require('node:vfs');
+const fs = require('node:fs');
+
+const myVfs = vfs.create();
+myVfs.writeFileSync('/data.txt', 'Hello from VFS');
+myVfs.mount('/virtual');
+
+// This reads from the virtual file system
+fs.readFileSync('/virtual/data.txt', 'utf8'); // 'Hello from VFS'
+
+myVfs.unmount();
+```
+
+Not all `node:fs` operations are supported with VFS. See the [`node:vfs`][]
+documentation for the complete list of supported operations and limitations.
+
 ## Promises API
 
 <!-- YAML
@@ -8787,6 +8817,7 @@ the file contents.
 [`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html
 [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 [`minimatch`]: https://github.com/isaacs/minimatch
+[`node:vfs`]: vfs.md
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [bigints]: https://tc39.github.io/proposal-bigint
 [caveats]: #caveats

doc/api/index.md

@@ -63,6 +63,7 @@
 * [URL](url.md)
 * [Utilities](util.md)
 * [V8](v8.md)
+* [Virtual File System](vfs.md)
 * [VM](vm.md)
 * [WASI](wasi.md)
 * [Web Crypto API](webcrypto.md)

doc/api/single-executable-applications.md

@@ -116,6 +116,7 @@ The configuration currently reads the following top-level fields:
   "disableExperimentalSEAWarning": true, // Default: false
   "useSnapshot": false,  // Default: false
   "useCodeCache": true, // Default: false
+  "useVfs": true, // Default: false
   "execArgv": ["--no-warnings", "--max-old-space-size=4096"], // Optional
   "execArgvExtension": "env", // Default: "env", options: "none", "env", "cli"
   "assets": {  // Optional
@@ -175,6 +176,84 @@ const raw = getRawAsset('a.jpg');
 See documentation of the [`sea.getAsset()`][], [`sea.getAssetAsBlob()`][],
 [`sea.getRawAsset()`][] and [`sea.getAssetKeys()`][] APIs for more information.
 
+### Virtual File System (VFS) for assets
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+In addition to using the `node:sea` API to access individual assets, you can use
+the Virtual File System (VFS) to access bundled assets through standard `node:fs`
+APIs. To enable VFS, set `"useVfs": true` in the SEA configuration. When
+enabled, the VFS is automatically initialized and mounted at `/sea`. All
+assets defined in the SEA configuration are accessible through this virtual
+path.
+
+```cjs
+const fs = require('node:fs');
+
+// Assets are automatically available at /sea when running as SEA
+const rawConfig = fs.readFileSync('/sea/config.json', 'utf8');
+const data = fs.readFileSync('/sea/data/file.txt');
+
+const config = JSON.parse(rawConfig);
+
+// Directory operations work too
+const files = fs.readdirSync('/sea/assets');
+
+// Check if a bundled file exists
+if (fs.existsSync('/sea/optional.json')) {
+  // ...
+}
+```
+
+The VFS supports all common `node:fs` operations for reading files and directories.
+Since the SEA VFS is read-only, write operations are not supported. See the
+[VFS documentation][] for the full list of supported and unsupported operations.
+
+#### Loading modules from VFS in SEA
+
+When `useVfs` is enabled, `require()` in the injected main script uses the
+registered module hooks to load modules from the virtual file system. This
+supports both absolute VFS paths and relative requires (e.g.,
+`require('./helper.js')` from a VFS module), as well as `node_modules` package
+lookups.
+
+```cjs
+// Require bundled modules using relative paths
+const myModule = require('./lib/mymodule.js');
+const utils = require('./utils/helpers.js');
+
+// Absolute VFS paths also work
+const config = require('/sea/config.json');
+```
+
+When `useVfs` is enabled, `__filename` and `__dirname` in the injected main
+script reflect VFS paths (e.g., `/sea/main.js`) instead of
+[`process.execPath`][].
+
+#### ESM limitations
+
+The `useVfs` option does not currently support ESM entry points. Using
+`"useVfs": true` together with `"mainFormat": "module"` is not supported.
+The main script must use CommonJS (`require()`) when VFS is enabled.
+
+#### Code caching limitations
+
+The `useCodeCache` option in the SEA configuration does not currently apply to
+modules loaded from the VFS. This is a current limitation due to incomplete
+implementation, not a technical impossibility. Consider bundling the application
+to enable code caching and do not rely on module loading in VFS.
+
+#### Native addon limitations
+
+Native addons (`.node` files) cannot be loaded directly from the VFS because
+`process.dlopen()` requires files on the real file system. To use native
+addons in a SEA with VFS, write the asset to a temporary file first. See
+[Using native addons in the injected main script][] for an example.
+
 ### Startup snapshot support
 
 The `useSnapshot` field can be used to enable startup snapshot support. In this
@@ -647,6 +726,8 @@ to help us document them.
 [Generating single executable preparation blobs]: #1-generating-single-executable-preparation-blobs
 [Mach-O]: https://en.wikipedia.org/wiki/Mach-O
 [PE]: https://en.wikipedia.org/wiki/Portable_Executable
+[Using native addons in the injected main script]: #using-native-addons-in-the-injected-main-script
+[VFS documentation]: vfs.md
 [Windows SDK]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
 [`process.execPath`]: process.md#processexecpath
 [`require()`]: modules.md#requireid

doc/api/test.md

@@ -2393,6 +2393,98 @@ test('mocks a counting function', (t) => {
 });
 ```
 
+### `mock.fs([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+* `options` {Object} Optional configuration options for the mock file system.
+  The following properties are supported:
+  * `prefix` {string} The mount point prefix for the virtual file system.
+    **Default:** `'/mock'`.
+  * `files` {Object} An optional object where keys are file paths (relative to
+    the VFS root) and values are the file contents. Contents can be strings,
+    Buffers, or functions that return strings/Buffers.
+* Returns: {MockFSContext} An object that can be used to manage the mock file
+  system.
+
+This function creates a mock file system using the [Virtual File System (VFS)][].
+The mock file system is automatically cleaned up when the test completes.
+
+## Class: `MockFSContext`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The `MockFSContext` object is returned by `mock.fs()` and provides the
+following methods and properties:
+
+* `vfs` {VirtualFileSystem} The underlying VFS instance.
+* `prefix` {string} The mount prefix.
+* `addFile(path, content)` Adds a file to the mock file system.
+* `addDirectory(path[, populate])` Adds a directory to the mock file system.
+* `existsSync(path)` Checks if a path exists (path is relative to prefix).
+* `restore()` Manually restores the file system to its original state.
+
+The following example demonstrates how to create a mock file system for testing:
+
+```js
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+
+test('reads configuration from mock file', (t) => {
+  const mockFs = t.mock.fs({
+    prefix: '/app',
+    files: {
+      '/config.json': JSON.stringify({ debug: true }),
+      '/data/users.txt': 'user1\nuser2\nuser3',
+    },
+  });
+
+  // Files are accessible via standard fs APIs
+  const config = JSON.parse(fs.readFileSync('/app/config.json', 'utf8'));
+  assert.strictEqual(config.debug, true);
+
+  // Check file existence
+  assert.strictEqual(fs.existsSync('/app/config.json'), true);
+  assert.strictEqual(fs.existsSync('/app/missing.txt'), false);
+
+  // Use mockFs.existsSync for paths relative to prefix
+  assert.strictEqual(mockFs.existsSync('/config.json'), true);
+});
+
+test('supports dynamic file content', (t) => {
+  let counter = 0;
+  const mockFs = t.mock.fs({ prefix: '/dynamic' });
+
+  mockFs.addFile('/counter.txt', () => {
+    counter++;
+    return String(counter);
+  });
+
+  // Each read calls the function
+  assert.strictEqual(fs.readFileSync('/dynamic/counter.txt', 'utf8'), '1');
+  assert.strictEqual(fs.readFileSync('/dynamic/counter.txt', 'utf8'), '2');
+});
+
+test('supports require from mock files', (t) => {
+  t.mock.fs({
+    prefix: '/modules',
+    files: {
+      '/math.js': 'module.exports = { add: (a, b) => a + b };',
+    },
+  });
+
+  const math = require('/modules/math.js');
+  assert.strictEqual(math.add(2, 3), 5);
+});
+```
+
 ### `mock.getter(object, methodName[, implementation][, options])`
 
 <!-- YAML
@@ -4259,3 +4351,4 @@ Can be used to abort test subtasks when the test has been aborted.
 [suite options]: #suitename-options-fn
 [test reporters]: #test-reporters
 [test runner execution model]: #test-runner-execution-model
+[virtual file system (vfs)]: vfs.md