vfs: integrate with CJS and ESM module loaders

Route loader fs and package.json operations through toggleable
wrappers so the VFS can resolve and load modules from mounted paths.
When no VFS is mounted, the wrappers take a null-check fast path with
zero overhead.

Hooks:
- loaderStat / loaderReadFile / toRealPath / loaderLegacyMainResolve /
  loaderGetFormatOfExtensionlessFile in
  lib/internal/modules/helpers.js, consumed by cjs/loader.js,
  esm/resolve.js, esm/load.js and esm/get_format.js.
- loaderReadPackageJSON / loaderGetNearestParentPackageJSON /
  loaderGetPackageScopeConfig / loaderGetPackageType, consumed by
  package_json_reader.js.
- setLoaderFsOverrides / setLoaderPackageOverrides install / clear
  all hooks; clearRealpathCache exposes the helpers.js realpath
  cache so deregister can flush it.

lib/internal/vfs/setup.js installs the overrides on first
registerVFS and clears every JS-side loader cache (CJS _pathCache,
CJS stat cache, realpath cache, package.json cache) on every
deregister. The overrides themselves are uninstalled when the last
VFS is removed so the fast path is fully restored.
legacyMainResolve / extensionless-format behavior matches the C++
binding; package.json validation matches src/node_modules.cc
(silently omit non-string main, throw on non-string name/type, etc).

The "DO NOT depend on patchability" warnings in esm/load.js and
esm/resolve.js are preserved and now point at node:vfs and
module.registerHooks() as the formal hook mechanisms.

Tests cover require / import / module-hooks / package.json / cache
invalidation / cleanup-cycle scenarios under --experimental-vfs.

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

Author: mcollina

doc/api/vfs.md

@@ -46,6 +46,11 @@ callback-based, and promise-based file system methods that mirror the
 shape of the [`node:fs`][] API. All paths are POSIX-style and absolute
 (starting with `/`).
 
+By default, the file tree is private to the VFS instance. To expose
+it through the global `node:fs` module, `require()`, and `import`,
+call [`vfs.mount(prefix)`][]; call [`vfs.unmount()`][] (or rely on a
+`using` declaration) to detach again.
+
 ## `vfs.create([provider][, options])`
 
 <!-- YAML
@@ -92,6 +97,93 @@ added: REPLACEME
   * `emitExperimentalWarning` {boolean} Whether to emit the experimental
     warning. **Default:** `true`.
 
+### `vfs.mount(prefix)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `prefix` {string} The path prefix where the VFS will be mounted.
+* Returns: {VirtualFileSystem} The VFS instance, for chaining or `using`.
+
+Mounts the virtual file system at the specified path prefix. After
+mounting, files in the VFS can be accessed through the `node:fs`
+module — and resolved through `require()` and `import` — using paths
+that start with the prefix.
+
+If a real file-system path already exists at the mount prefix, the
+VFS **shadows** that path: every operation against a path under the
+mount point is directed to the VFS until the VFS is unmounted.
+
+```cjs
+const vfs = require('node:vfs');
+const fs = require('node:fs');
+
+const myVfs = vfs.create();
+myVfs.writeFileSync('/data.txt', 'Hello');
+myVfs.mount('/virtual');
+
+fs.readFileSync('/virtual/data.txt', 'utf8'); // 'Hello'
+```
+
+Each `VirtualFileSystem` instance may be mounted at most once at a
+time. Attempting to mount an already-mounted instance throws
+`ERR_INVALID_STATE`. Mounting two instances at overlapping prefixes
+(e.g., `/virtual` and `/virtual/sub`) also throws `ERR_INVALID_STATE`.
+
+The VFS supports the [Explicit Resource Management][] proposal. Use
+a `using` declaration to unmount automatically when leaving scope:
+
+```cjs
+const vfs = require('node:vfs');
+const fs = require('node:fs');
+
+{
+  using myVfs = vfs.create();
+  myVfs.writeFileSync('/data.txt', 'Hello');
+  myVfs.mount('/virtual');
+
+  fs.readFileSync('/virtual/data.txt', 'utf8'); // 'Hello'
+} // VFS is automatically unmounted here
+
+fs.existsSync('/virtual/data.txt'); // false
+```
+
+### `vfs.unmount()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Unmounts the virtual file system. After unmounting, virtual files
+are no longer reachable through `node:fs`, `require()`, or `import`.
+The same instance may be mounted again, at the same or a different
+prefix, by calling `mount()`.
+
+This method is idempotent: calling `unmount()` on a VFS that is not
+currently mounted has no effect.
+
+### `vfs.mounted`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+`true` while the VFS is mounted; `false` otherwise.
+
+### `vfs.mountPoint`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string | null}
+
+The current mount-point path as an absolute string, or `null` when
+the VFS is not mounted.
+
 ### `vfs.provider`
 
 <!-- YAML
@@ -302,9 +394,12 @@ fields use synthetic but stable values:
 * `blocks` is `Math.ceil(size / 512)`.
 * Times default to the moment the entry was created/last modified.
 
+[Explicit Resource Management]: https://github.com/tc39/proposal-explicit-resource-management
 [`MemoryProvider`]: #class-memoryprovider
 [`VirtualFileSystem`]: #class-virtualfilesystem
 [`VirtualProvider`]: #class-virtualprovider
 [`fs.BigIntStats`]: fs.md#class-fsbigintstats
 [`fs.Stats`]: fs.md#class-fsstats
 [`node:fs`]: fs.md
+[`vfs.mount(prefix)`]: #vfsmountprefix
+[`vfs.unmount()`]: #vfsunmount

lib/internal/modules/cjs/loader.js

@@ -113,6 +113,7 @@ const kFormat = Symbol('kFormat');
 
 // Set first due to cycle with ESM loader functions.
 module.exports = {
+  clearStatCache,
   kModuleSource,
   kModuleExport,
   kModuleExportNames,
@@ -155,14 +156,14 @@ const {
 } = internalBinding('contextify');
 
 const assert = require('internal/assert');
-const fs = require('fs');
 const path = require('path');
-const internalFsBinding = internalBinding('fs');
 const { safeGetenv } = internalBinding('credentials');
 const {
   getCjsConditions,
   getCjsConditionsArray,
   initializeCjsConditions,
+  loaderReadFile,
+  loaderStat,
   loadBuiltinModule,
   makeRequireFunction,
   setHasStartedUserCJSExecution,
@@ -272,14 +273,24 @@ function stat(filename) {
     const result = statCache.get(filename);
     if (result !== undefined) { return result; }
   }
-  const result = internalFsBinding.internalModuleStat(filename);
+  const result = loaderStat(filename);
   if (statCache !== null && result >= 0) {
     // Only set cache when `internalModuleStat(filename)` succeeds.
     statCache.set(filename, result);
   }
   return result;
 }
 
+/**
+ * Clear the stat cache. Called when VFS instances are unmounted
+ * to prevent stale stat results from being returned.
+ */
+function clearStatCache() {
+  if (statCache !== null) {
+    statCache = new SafeMap();
+  }
+}
+
 let _stat = stat;
 ObjectDefineProperty(Module, '_stat', {
   __proto__: null,
@@ -1201,7 +1212,7 @@ function defaultLoadImpl(filename, format) {
     case 'module-typescript':
     case 'commonjs-typescript':
     case 'typescript': {
-      return fs.readFileSync(filename, 'utf8');
+      return loaderReadFile(filename, 'utf8');
     }
     case 'builtin':
       return null;

lib/internal/modules/esm/get_format.js

@@ -10,7 +10,6 @@ const {
 } = primordials;
 const { getOptionValue } = require('internal/options');
 const { getValidatedPath } = require('internal/fs/utils');
-const fsBindings = internalBinding('fs');
 const { internal: internalConstants } = internalBinding('constants');
 
 const extensionFormatMap = {
@@ -59,7 +58,8 @@ function mimeToFormat(mime) {
  */
 function getFormatOfExtensionlessFile(url) {
   const path = getValidatedPath(url);
-  switch (fsBindings.getFormatOfExtensionlessFile(path)) {
+  const { loaderGetFormatOfExtensionlessFile } = require('internal/modules/helpers');
+  switch (loaderGetFormatOfExtensionlessFile(path)) {
     case internalConstants.EXTENSIONLESS_FORMAT_WASM:
       return 'wasm';
     default:

lib/internal/modules/esm/load.js

@@ -9,7 +9,7 @@ const {
 
 const { defaultGetFormat } = require('internal/modules/esm/get_format');
 const { validateAttributes, emitImportAssertionWarning } = require('internal/modules/esm/assert');
-const fs = require('fs');
+const { loaderReadFile } = require('internal/modules/helpers');
 
 const { Buffer: { from: BufferFrom } } = require('buffer');
 
@@ -34,11 +34,13 @@ function getSourceSync(url, context) {
   const responseURL = href;
   let source;
   if (protocol === 'file:') {
-    // If you are reading this code to figure out how to patch Node.js module loading
-    // behavior - DO NOT depend on the patchability in new code: Node.js
+    // If you are reading this code to figure out how to patch Node.js module
+    // loading behavior - DO NOT depend on the patchability in new code: Node.js
     // internals may stop going through the JavaScript fs module entirely.
-    // Prefer module.registerHooks() or other more formal fs hooks released in the future.
-    source = fs.readFileSync(url);
+    // Prefer module.registerHooks(), node:vfs, or other more formal fs hooks
+    // released in the future. loaderReadFile is the toggleable hook used by
+    // node:vfs and is not part of the public API.
+    source = loaderReadFile(url);
   } else if (protocol === 'data:') {
     const result = dataURLProcessor(url);
     if (result === 'failure') {

lib/internal/modules/esm/resolve.js

@@ -9,7 +9,6 @@ const {
   ObjectPrototypeHasOwnProperty,
   RegExpPrototypeExec,
   RegExpPrototypeSymbolReplace,
-  SafeMap,
   SafeSet,
   String,
   StringPrototypeEndsWith,
@@ -23,16 +22,13 @@ const {
   encodeURIComponent,
 } = primordials;
 const assert = require('internal/assert');
-const internalFS = require('internal/fs/utils');
 const { BuiltinModule } = require('internal/bootstrap/realm');
-const fs = require('fs');
 const { getOptionValue } = require('internal/options');
 // Do not eagerly grab .manifest, it may be in TDZ
 const { sep, posix: { relative: relativePosixPath }, resolve } = require('path');
 const { URL, pathToFileURL, fileURLToPath, isURL, URLParse } = require('internal/url');
 const { getCWDURL, setOwnProperty } = require('internal/util');
 const { canParse: URLCanParse } = internalBinding('url');
-const { legacyMainResolve: FSLegacyMainResolve } = internalBinding('fs');
 const {
   ERR_INPUT_TYPE_NOT_ALLOWED,
   ERR_INVALID_ARG_TYPE,
@@ -49,7 +45,7 @@ const {
 const { defaultGetFormatWithoutErrors } = require('internal/modules/esm/get_format');
 const { getConditionsSet } = require('internal/modules/esm/utils');
 const packageJsonReader = require('internal/modules/package_json_reader');
-const internalFsBinding = internalBinding('fs');
+const { loaderLegacyMainResolve, loaderStat, toRealPath } = require('internal/modules/helpers');
 
 /**
  * @typedef {import('internal/modules/esm/package_config.js').PackageConfig} PackageConfig
@@ -149,8 +145,6 @@ function emitLegacyIndexDeprecation(url, path, pkgPath, base, main) {
   }
 }
 
-const realpathCache = new SafeMap();
-
 const legacyMainResolveExtensions = [
   '',
   '.js',
@@ -198,7 +192,7 @@ function legacyMainResolve(packageJSONUrl, packageConfig, base) {
 
   const baseStringified = isURL(base) ? base.href : base;
 
-  const resolvedOption = FSLegacyMainResolve(pkgPath, packageConfig.main, baseStringified);
+  const resolvedOption = loaderLegacyMainResolve(pkgPath, packageConfig.main, baseStringified);
 
   const maybeMain = resolvedOption <= legacyMainResolveExtensionsIndexes.kResolvedByMainIndexNode ?
     packageConfig.main || './' : '';
@@ -244,7 +238,7 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
     throw err;
   }
 
-  const stats = internalFsBinding.internalModuleStat(
+  const stats = loaderStat(
     StringPrototypeEndsWith(path, '/') ? StringPrototypeSlice(path, -1) : path,
   );
 
@@ -273,13 +267,13 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
   }
 
   if (!preserveSymlinks) {
-    // If you are reading this code to figure out how to patch Node.js module loading
-    // behavior - DO NOT depend on the patchability in new code: Node.js
+    // If you are reading this code to figure out how to patch Node.js module
+    // loading behavior - DO NOT depend on the patchability in new code: Node.js
     // internals may stop going through the JavaScript fs module entirely.
-    // Prefer module.registerHooks() or other more formal fs hooks released in the future.
-    const real = fs.realpathSync(path, {
-      [internalFS.realpathCacheKey]: realpathCache,
-    });
+    // Prefer module.registerHooks(), node:vfs, or other more formal fs hooks
+    // released in the future. toRealPath is the toggleable hook used by
+    // node:vfs and is not part of the public API.
+    const real = toRealPath(path);
     const { search, hash } = resolved;
     resolved =
         pathToFileURL(real + (StringPrototypeEndsWith(path, sep) ? '/' : ''));