vfs: add async glob support, experimental warning, and moduleHooks option

- Add hooks for fs/promises.readdir and fs/promises.lstat to enable
  async glob patterns (fs.glob callback and fs/promises.glob)
- Emit experimental warning when fs.createVirtual() is called
- Add moduleHooks option (default: true) to control whether require/import
  hooks are installed, allowing VFS to be used for fs operations only
- Move require('internal/vfs/errors') to top of module_hooks.js
- Update documentation to reflect async glob support and moduleHooks option
- Remove "all tests passed" console.log statements from test files

Author: mcollina

doc/api/fs.md

@@ -8323,6 +8323,8 @@ added: REPLACEME
 * `options` {Object}
   * `fallthrough` {boolean} When `true`, operations on paths not in the VFS
     fall through to the real file system. **Default:** `true`.
+  * `moduleHooks` {boolean} When `true`, enables hooks for `require()` and
+    `import` to load modules from the VFS. **Default:** `true`.
 * Returns: {VirtualFileSystem}
 
 Creates a new virtual file system instance.
@@ -8335,6 +8337,9 @@ const vfs = fs.createVirtual({ fallthrough: true });
 
 // Create a VFS that only serves virtual files
 const isolatedVfs = fs.createVirtual({ fallthrough: false });
+
+// Create a VFS without module loading hooks (fs operations only)
+const fsOnlyVfs = fs.createVirtual({ moduleHooks: false });
 ```
 
 ### Class: `VirtualFileSystem`
@@ -8661,7 +8666,8 @@ console.log(mod.default()); // 'Hello'
 
 ### Glob support
 
-The VFS integrates with `fs.globSync()` when mounted or in overlay mode:
+The VFS integrates with `fs.glob()`, `fs.globSync()`, and `fs/promises.glob()`
+when mounted or in overlay mode:
 
 ```cjs
 const fs = require('node:fs');
@@ -8672,10 +8678,21 @@ vfs.addFile('/src/utils.js', 'export const util = 1;');
 vfs.addFile('/src/lib/helper.js', 'export const helper = 1;');
 vfs.mount('/virtual');
 
-// Glob patterns work with virtual files
+// Sync glob
 const files = fs.globSync('/virtual/src/**/*.js');
 console.log(files);
 // ['/virtual/src/index.js', '/virtual/src/utils.js', '/virtual/src/lib/helper.js']
+
+// Async glob with callback
+fs.glob('/virtual/src/*.js', (err, matches) => {
+  console.log(matches); // ['/virtual/src/index.js', '/virtual/src/utils.js']
+});
+
+// Async glob with promises (returns async iterator)
+const { glob } = require('fs/promises');
+for await (const file of glob('/virtual/src/**/*.js')) {
+  console.log(file);
+}
 ```
 
 ### Limitations
@@ -8687,8 +8704,6 @@ The current VFS implementation has the following limitations:
 * **No symbolic links**: Symbolic links are not supported.
 * **No file watching**: `fs.watch()` and `fs.watchFile()` do not work with
   virtual files.
-* **Async glob**: Only `fs.globSync()` is supported. The async `fs.glob()` API
-  does not support VFS paths.
 * **No real file descriptor**: Virtual file descriptors (10000+) are managed
   separately from real file descriptors.
 

lib/internal/vfs/module_hooks.js

@@ -10,6 +10,7 @@ const {
 
 const { normalizePath } = require('internal/vfs/router');
 const { pathToFileURL, fileURLToPath } = require('internal/url');
+const { createENOENT } = require('internal/vfs/errors');
 
 // Registry of active VFS instances
 const activeVFSList = [];
@@ -26,6 +27,10 @@ let originalLstatSync = null;
 let originalStatSync = null;
 // Original fs.readdirSync function
 let originalReaddirSync = null;
+// Original fs/promises.readdir function
+let originalPromisesReaddir = null;
+// Original fs/promises.lstat function
+let originalPromisesLstat = null;
 // Track if hooks are installed
 let hooksInstalled = false;
 // ESM hooks instance (for potential cleanup)
@@ -111,7 +116,6 @@ function findVFSForRead(filename, options) {
       } else if (vfs.isMounted) {
         // In mounted mode, if path is under mount point but doesn't exist,
         // don't fall through to real fs - throw ENOENT
-        const { createENOENT } = require('internal/vfs/errors');
         throw createENOENT('open', filename);
       }
     }
@@ -139,7 +143,6 @@ function findVFSForRealpath(filename) {
           }
         }
       } else if (vfs.isMounted) {
-        const { createENOENT } = require('internal/vfs/errors');
         throw createENOENT('realpath', filename);
       }
     }
@@ -167,7 +170,6 @@ function findVFSForFsStat(filename) {
           }
         }
       } else if (vfs.isMounted) {
-        const { createENOENT } = require('internal/vfs/errors');
         throw createENOENT('stat', filename);
       }
     }
@@ -196,14 +198,68 @@ function findVFSForReaddir(dirname, options) {
           }
         }
       } else if (vfs.isMounted) {
-        const { createENOENT } = require('internal/vfs/errors');
         throw createENOENT('scandir', dirname);
       }
     }
   }
   return null;
 }
 
+/**
+ * Async version: Checks all active VFS instances for readdir.
+ * @param {string} dirname The directory path
+ * @param {object} options The readdir options
+ * @returns {Promise<{ vfs: VirtualFileSystem, entries: string[]|Dirent[] }|null>}
+ */
+async function findVFSForReaddirAsync(dirname, options) {
+  const normalized = normalizePath(dirname);
+  for (let i = 0; i < activeVFSList.length; i++) {
+    const vfs = activeVFSList[i];
+    if (vfs.shouldHandle(normalized)) {
+      if (vfs.existsSync(normalized)) {
+        try {
+          const entries = await vfs.promises.readdir(normalized, options);
+          return { vfs, entries };
+        } catch (e) {
+          if (vfs.isMounted) {
+            throw e;
+          }
+        }
+      } else if (vfs.isMounted) {
+        throw createENOENT('scandir', dirname);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Async version: Checks all active VFS instances for lstat.
+ * @param {string} filename The path to stat
+ * @returns {Promise<{ vfs: VirtualFileSystem, stats: Stats }|null>}
+ */
+async function findVFSForLstatAsync(filename) {
+  const normalized = normalizePath(filename);
+  for (let i = 0; i < activeVFSList.length; i++) {
+    const vfs = activeVFSList[i];
+    if (vfs.shouldHandle(normalized)) {
+      if (vfs.existsSync(normalized)) {
+        try {
+          const stats = await vfs.promises.lstat(normalized);
+          return { vfs, stats };
+        } catch (e) {
+          if (vfs.isMounted) {
+            throw e;
+          }
+        }
+      } else if (vfs.isMounted) {
+        throw createENOENT('lstat', filename);
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Determine module format from file extension.
  * @param {string} url The file URL
@@ -444,6 +500,35 @@ function installHooks() {
     return originalReaddirSync.call(fs, path, options);
   };
 
+  // Hook fs/promises for async glob support
+  const fsPromises = require('fs/promises');
+
+  // Override fs/promises.readdir (needed for async glob support)
+  originalPromisesReaddir = fsPromises.readdir;
+  fsPromises.readdir = async function vfsPromisesReaddir(path, options) {
+    if (typeof path === 'string' || path instanceof URL) {
+      const pathStr = typeof path === 'string' ? path : path.pathname;
+      const vfsResult = await findVFSForReaddirAsync(pathStr, options);
+      if (vfsResult !== null) {
+        return vfsResult.entries;
+      }
+    }
+    return originalPromisesReaddir.call(fsPromises, path, options);
+  };
+
+  // Override fs/promises.lstat (needed for async glob support)
+  originalPromisesLstat = fsPromises.lstat;
+  fsPromises.lstat = async function vfsPromisesLstat(path, options) {
+    if (typeof path === 'string' || path instanceof URL) {
+      const pathStr = typeof path === 'string' ? path : path.pathname;
+      const vfsResult = await findVFSForLstatAsync(pathStr);
+      if (vfsResult !== null) {
+        return vfsResult.stats;
+      }
+    }
+    return originalPromisesLstat.call(fsPromises, path, options);
+  };
+
   // Register ESM hooks using Module.registerHooks
   esmHooksInstance = Module.registerHooks({
     resolve: vfsResolveHook,

lib/internal/vfs/virtual_fs.js

@@ -40,6 +40,7 @@ const {
   registerVFS,
   unregisterVFS,
 } = require('internal/vfs/module_hooks');
+const { emitExperimentalWarning } = require('internal/util');
 const {
   fs: {
     UV_DIRENT_FILE,
@@ -53,6 +54,7 @@ const kMountPoint = Symbol('kMountPoint');
 const kMounted = Symbol('kMounted');
 const kOverlay = Symbol('kOverlay');
 const kFallthrough = Symbol('kFallthrough');
+const kModuleHooks = Symbol('kModuleHooks');
 const kPromises = Symbol('kPromises');
 
 /**
@@ -63,13 +65,16 @@ class VirtualFileSystem {
   /**
    * @param {object} [options] Configuration options
    * @param {boolean} [options.fallthrough=true] Whether to fall through to real fs on miss
+   * @param {boolean} [options.moduleHooks=true] Whether to enable require/import hooks
    */
   constructor(options = {}) {
+    emitExperimentalWarning('fs.createVirtual');
     this[kRoot] = new VirtualDirectory('/');
     this[kMountPoint] = null;
     this[kMounted] = false;
     this[kOverlay] = false;
     this[kFallthrough] = options.fallthrough !== false;
+    this[kModuleHooks] = options.moduleHooks !== false;
     this[kPromises] = null; // Lazy-initialized
   }
 
@@ -229,7 +234,9 @@ class VirtualFileSystem {
     }
     this[kMountPoint] = normalizePath(prefix);
     this[kMounted] = true;
-    registerVFS(this);
+    if (this[kModuleHooks]) {
+      registerVFS(this);
+    }
   }
 
   /**
@@ -240,7 +247,9 @@ class VirtualFileSystem {
       throw new Error('VFS is already mounted or in overlay mode');
     }
     this[kOverlay] = true;
-    registerVFS(this);
+    if (this[kModuleHooks]) {
+      registerVFS(this);
+    }
   }
 
   /**

test/parallel/test-vfs-basic.js

@@ -213,4 +213,3 @@ const fs = require('fs');
   }, { code: 'ENOENT' });
 }
 
-console.log('All VFS basic tests passed');

test/parallel/test-vfs-fd.js

@@ -317,4 +317,3 @@ const fs = require('fs');
   myVfs.closeSync(fd2);
 }
 
-console.log('All VFS fd tests passed');

test/parallel/test-vfs-glob.js

@@ -57,8 +57,61 @@ const fs = require('fs');
   myVfs.unmount();
 }
 
-// Note: Async glob (fs.glob with callback) requires hooking fs/promises
-// which is not implemented yet. The globSync version works with VFS.
+// Test async glob (callback API) with VFS mounted directory
+{
+  const myVfs = fs.createVirtual();
+  myVfs.addFile('/async-src/index.js', 'export default 1;');
+  myVfs.addFile('/async-src/utils.js', 'export const util = 1;');
+  myVfs.addFile('/async-src/lib/helper.js', 'export const helper = 1;');
+  myVfs.mount('/async-virtual');
+
+  fs.glob('/async-virtual/async-src/*.js', common.mustCall((err, files) => {
+    assert.strictEqual(err, null);
+    assert.strictEqual(files.length, 2);
+    assert.ok(files.includes('/async-virtual/async-src/index.js'));
+    assert.ok(files.includes('/async-virtual/async-src/utils.js'));
+
+    // Test recursive pattern with callback
+    fs.glob('/async-virtual/async-src/**/*.js', common.mustCall((err, allFiles) => {
+      assert.strictEqual(err, null);
+      assert.strictEqual(allFiles.length, 3);
+      assert.ok(allFiles.includes('/async-virtual/async-src/index.js'));
+      assert.ok(allFiles.includes('/async-virtual/async-src/utils.js'));
+      assert.ok(allFiles.includes('/async-virtual/async-src/lib/helper.js'));
+
+      myVfs.unmount();
+    }));
+  }));
+}
+
+// Test async glob (promise API) with VFS
+(async () => {
+  const myVfs = fs.createVirtual();
+  myVfs.addFile('/promise-src/a.ts', 'const a = 1;');
+  myVfs.addFile('/promise-src/b.ts', 'const b = 2;');
+  myVfs.addFile('/promise-src/c.js', 'const c = 3;');
+  myVfs.mount('/promise-virtual');
+
+  const { glob } = require('fs/promises');
+
+  // glob returns an async iterator, need to collect results
+  const tsFiles = [];
+  for await (const file of glob('/promise-virtual/promise-src/*.ts')) {
+    tsFiles.push(file);
+  }
+  assert.strictEqual(tsFiles.length, 2);
+  assert.ok(tsFiles.includes('/promise-virtual/promise-src/a.ts'));
+  assert.ok(tsFiles.includes('/promise-virtual/promise-src/b.ts'));
+
+  // Test multiple patterns
+  const allFiles = [];
+  for await (const file of glob(['/promise-virtual/promise-src/*.ts', '/promise-virtual/promise-src/*.js'])) {
+    allFiles.push(file);
+  }
+  assert.strictEqual(allFiles.length, 3);
+
+  myVfs.unmount();
+})().then(common.mustCall());
 
 // Test glob with withFileTypes option
 {
@@ -142,4 +195,3 @@ const fs = require('fs');
   myVfs.unmount();
 }
 
-console.log('All VFS glob tests passed');

test/parallel/test-vfs-import.mjs

@@ -146,4 +146,3 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
   myVfs.unmount();
 }
 
-console.log('All VFS import tests passed');

test/parallel/test-vfs-promises.js

@@ -298,4 +298,3 @@ const fs = require('fs');
   assert.strictEqual(data2, 'count: 2');
 })().then(common.mustCall());
 
-console.log('All VFS promises tests passed');

test/parallel/test-vfs-require.js

@@ -204,4 +204,3 @@ const fs = require('fs');
   }, { code: 'MODULE_NOT_FOUND' });
 }
 
-console.log('All VFS require tests passed');

test/parallel/test-vfs-streams.js

@@ -233,4 +233,3 @@ const fs = require('fs');
   }));
 }
 
-console.log('All VFS streams tests passed');