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

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) ? '/' : ''));