fixup! module: add clearCache for CJS and ESM

Author: anonrig

doc/api/module.md

@@ -76,20 +76,22 @@ added: REPLACEME
 
 * `specifier` {string|URL} The module specifier or URL to clear.
 * `options` {Object}
-  * `mode` {string} Which caches to clear. Supported values are `'all'`, `'cjs'`, and `'esm'`.
+  * `mode` {string} Which caches to clear. Supported values are `'all'`, `'commonjs'`, and `'module'`.
     **Default:** `'all'`.
-  * `parentURL` {string|URL} The parent URL or absolute path used to resolve non-URL specifiers.
-    For CommonJS, pass `__filename`. For ES modules, pass `import.meta.url`.
-  * `type` {string} Import attributes `type` used for ESM resolution.
-  * `importAttributes` {Object} Import attributes for ESM resolution. Cannot be used with `type`.
-* Returns: {Object} An object with `{ cjs: boolean, esm: boolean }` indicating whether entries
+  * `parentURL` {string|URL} The parent URL used to resolve non-URL specifiers.
+    For CommonJS, pass `pathToFileURL(__filename)`. For ES modules, pass `import.meta.url`.
+  * `importAttributes` {Object} Import attributes for ESM resolution.
+* Returns: {Object} An object with `{ commonjs: boolean, module: boolean }` indicating whether entries
   were removed from each cache.
 
 Clears the CommonJS `require` cache and/or the ESM module cache for a module. This enables
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR.
 When `mode` is `'all'`, resolution failures for one module system do not throw; check the
 returned flags to see what was cleared.
-This also clears internal resolution caches for the resolved module.
+This also clears internal resolution caches for the resolved module. Clearing a module does
+not clear cached entries for its dependencies.
+When a `file:` URL is resolved, cached module jobs for the same file path are cleared even if
+they differ by search or hash.
 
 ```mjs
 import { clearCache } from 'node:module';

lib/internal/modules/cjs/loader.js

@@ -2042,7 +2042,7 @@ function createRequire(filenameOrURL) {
 }
 
 /**
- * Normalize the parent URL/path for cache clearing.
+ * Normalize the parent URL for cache clearing.
  * @param {string|URL|undefined} parentURL
  * @returns {{ parentURL: string|undefined, parentPath: string|undefined }}
  */
@@ -2060,18 +2060,10 @@ function normalizeClearCacheParent(parentURL) {
   }
 
   validateString(parentURL, 'options.parentURL');
-  if (path.isAbsolute(parentURL)) {
-    return {
-      __proto__: null,
-      parentURL: pathToFileURL(parentURL).href,
-      parentPath: parentURL,
-    };
-  }
-
   const url = URLParse(parentURL);
   if (!url) {
     throw new ERR_INVALID_ARG_VALUE('options.parentURL', parentURL,
-                                    'must be an absolute path or URL');
+                                    'must be a URL');
   }
 
   const parentPath =
@@ -2131,7 +2123,11 @@ function resolveClearCacheFilename(specifier, parentPath) {
   }
 
   const parent = parentPath ? createParentModuleForClearCache(parentPath) : null;
-  return Module._resolveFilename(request, parent, false);
+  const { filename, format } = resolveForCJSWithHooks(request, parent, false, false);
+  if (format === 'builtin') {
+    return null;
+  }
+  return filename;
 }
 
 /**
@@ -2165,17 +2161,20 @@ function resolveClearCacheURL(specifier, parentURL, importAttributes) {
 /**
  * Remove path cache entries that resolve to a filename.
  * @param {string} filename
+ * @param {Set<string>|null} [existingKeys]
  * @returns {boolean} true if any entries were deleted.
  */
-function deletePathCacheEntries(filename) {
+function deletePathCacheEntries(filename, existingKeys = null) {
   const cache = Module._pathCache;
   const keys = ObjectKeys(cache);
   let deleted = false;
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     if (cache[key] === filename) {
+      if (existingKeys === null || existingKeys.has(key)) {
+        deleted = true;
+      }
       delete cache[key];
-      deleted = true;
     }
   }
   return deleted;
@@ -2184,91 +2183,179 @@ function deletePathCacheEntries(filename) {
 /**
  * Remove relative resolve cache entries that resolve to a filename.
  * @param {string} filename
+ * @param {Set<string>|null} [existingKeys]
  * @returns {boolean} true if any entries were deleted.
  */
-function deleteRelativeResolveCacheEntries(filename) {
+function deleteRelativeResolveCacheEntries(filename, existingKeys = null) {
   const keys = ObjectKeys(relativeResolveCache);
   let deleted = false;
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     if (relativeResolveCache[key] === filename) {
+      if (existingKeys === null || existingKeys.has(key)) {
+        deleted = true;
+      }
       delete relativeResolveCache[key];
+    }
+  }
+  return deleted;
+}
+
+/**
+ * Remove cached module references from parent children arrays.
+ * @param {Module} targetModule
+ * @returns {boolean} true if any references were removed.
+ */
+function deleteModuleFromParents(targetModule) {
+  const keys = ObjectKeys(Module._cache);
+  let deleted = false;
+  for (let i = 0; i < keys.length; i++) {
+    const cachedModule = Module._cache[keys[i]];
+    const children = cachedModule?.children;
+    if (!ArrayIsArray(children)) {
+      continue;
+    }
+    const index = ArrayPrototypeIndexOf(children, targetModule);
+    if (index !== -1) {
+      ArrayPrototypeSplice(children, index, 1);
       deleted = true;
     }
   }
   return deleted;
 }
 
+/**
+ * Resolve a file path for a file URL, stripping search/hash.
+ * @param {string} url
+ * @returns {string|null}
+ */
+function getFilePathFromClearCacheURL(url) {
+  const parsedURL = URLParse(url);
+  if (!parsedURL || parsedURL.protocol !== 'file:') {
+    return null;
+  }
+
+  if (parsedURL.search !== '' || parsedURL.hash !== '') {
+    parsedURL.search = '';
+    parsedURL.hash = '';
+  }
+
+  try {
+    return fileURLToPath(parsedURL);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove load cache entries for a URL and its file-path variants.
+ * @param {import('internal/modules/esm/module_map').LoadCache} loadCache
+ * @param {string} url
+ * @returns {boolean} true if any entries were deleted.
+ */
+function deleteLoadCacheEntries(loadCache, url) {
+  let deleted = loadCache.deleteAll(url);
+  const filename = getFilePathFromClearCacheURL(url);
+  if (!filename) {
+    return deleted;
+  }
+
+  const urls = [];
+  for (const entry of loadCache) {
+    ArrayPrototypePush(urls, entry[0]);
+  }
+
+  for (let i = 0; i < urls.length; i++) {
+    const cachedURL = urls[i];
+    if (cachedURL === url) {
+      continue;
+    }
+    const cachedFilename = getFilePathFromClearCacheURL(cachedURL);
+    if (cachedFilename === filename) {
+      loadCache.deleteAll(cachedURL);
+      deleted = true;
+    }
+  }
+
+  return deleted;
+}
+
 /**
  * Clear CommonJS and/or ESM module cache entries.
  * @param {string|URL} specifier
  * @param {object} [options]
- * @param {'all'|'cjs'|'esm'} [options.mode]
+ * @param {'all'|'commonjs'|'module'} [options.mode]
  * @param {string|URL} [options.parentURL]
- * @param {string} [options.type]
  * @param {Record<string, string>} [options.importAttributes]
- * @returns {{ cjs: boolean, esm: boolean }}
+ * @returns {{ commonjs: boolean, module: boolean }}
  */
 function clearCache(specifier, options = kEmptyObject) {
   const isSpecifierURL = isURL(specifier);
   if (!isSpecifierURL) {
     validateString(specifier, 'specifier');
   }
+  const specifierKey = isSpecifierURL ? specifier.href : specifier;
 
   validateObject(options, 'options');
   const mode = options.mode === undefined ? 'all' : options.mode;
-  validateOneOf(mode, 'options.mode', ['all', 'cjs', 'esm']);
-
-  if (options.importAttributes !== undefined && options.type !== undefined) {
-    throw new ERR_INVALID_ARG_VALUE('options.importAttributes', options.importAttributes,
-                                    'cannot be used with options.type');
-  }
+  validateOneOf(mode, 'options.mode', ['all', 'commonjs', 'module']);
 
-  let importAttributes = options.importAttributes;
-  if (options.type !== undefined) {
-    validateString(options.type, 'options.type');
-    importAttributes = { __proto__: null, type: options.type };
-  } else if (importAttributes !== undefined) {
+  const importAttributes = options.importAttributes;
+  if (importAttributes !== undefined) {
     validateObject(importAttributes, 'options.importAttributes');
   }
 
   const { parentURL, parentPath } = normalizeClearCacheParent(options.parentURL);
-  const result = { __proto__: null, cjs: false, esm: false };
+  const result = { __proto__: null, commonjs: false, module: false };
 
-  if (mode !== 'esm') {
+  if (mode !== 'module') {
+    const pathCacheKeys = new SafeSet(ObjectKeys(Module._pathCache));
+    const relativeResolveCacheKeys = new SafeSet(ObjectKeys(relativeResolveCache));
     try {
       const filename = resolveClearCacheFilename(specifier, parentPath);
       if (filename) {
         let deleted = false;
-        if (Module._cache[filename] !== undefined) {
+        const cachedModule = Module._cache[filename];
+        if (cachedModule !== undefined) {
           delete Module._cache[filename];
           deleted = true;
+          if (deleteModuleFromParents(cachedModule)) {
+            deleted = true;
+          }
         }
-        if (deletePathCacheEntries(filename)) {
+        if (deletePathCacheEntries(filename, pathCacheKeys)) {
           deleted = true;
         }
-        if (deleteRelativeResolveCacheEntries(filename)) {
+        if (deleteRelativeResolveCacheEntries(filename, relativeResolveCacheKeys)) {
           deleted = true;
         }
-        result.cjs = deleted;
+        result.commonjs = deleted;
       }
     } catch (err) {
-      if (mode === 'cjs') {
+      if (mode === 'commonjs') {
         throw err;
       }
     }
   }
 
-  if (mode !== 'cjs') {
+  if (mode !== 'commonjs') {
     try {
       const url = resolveClearCacheURL(specifier, parentURL, importAttributes);
       const cascadedLoader =
         require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-      const loadDeleted = cascadedLoader.loadCache.deleteAll(url);
-      const resolveDeleted = cascadedLoader.deleteResolveCache(url);
-      result.esm = loadDeleted || resolveDeleted;
+      const loadDeleted = deleteLoadCacheEntries(cascadedLoader.loadCache, url);
+      let resolveDeleted = cascadedLoader.deleteResolveCacheEntry(
+        specifierKey,
+        parentURL,
+        importAttributes ?? kEmptyObject,
+      );
+      const resolvedPath = getFilePathFromClearCacheURL(url);
+      if (resolvedPath) {
+        resolveDeleted = cascadedLoader.deleteResolveCacheByFilename(resolvedPath) || resolveDeleted;
+      }
+      result.module = loadDeleted || resolveDeleted;
     } catch (err) {
-      if (mode === 'esm') {
+      if (mode === 'module') {
         throw err;
       }
     }

lib/internal/modules/esm/loader.js

@@ -6,6 +6,7 @@ const {
   ArrayPrototypeReduce,
   FunctionPrototypeCall,
   JSONStringify,
+  ObjectKeys,
   ObjectSetPrototypeOf,
   Promise,
   PromisePrototypeThen,
@@ -30,7 +31,7 @@ const {
   ERR_UNKNOWN_MODULE_FORMAT,
 } = require('internal/errors').codes;
 const { getOptionValue } = require('internal/options');
-const { isURL, pathToFileURL } = require('internal/url');
+const { isURL, pathToFileURL, fileURLToPath, URLParse } = require('internal/url');
 const { kEmptyObject } = require('internal/util');
 const {
   compileSourceTextModule,
@@ -178,6 +179,61 @@ class ModuleLoader {
     return this.#resolveCache.deleteByResolvedURL(url);
   }
 
+  /**
+   * Delete cached resolution for a specific request.
+   * @param {string} specifier
+   * @param {string|undefined} parentURL
+   * @param {Record<string, string>} importAttributes
+   * @returns {boolean} true if any entries were deleted.
+   */
+  deleteResolveCacheEntry(specifier, parentURL, importAttributes) {
+    return this.#resolveCache.deleteBySpecifier(specifier, parentURL, importAttributes);
+  }
+
+  /**
+   * Delete cached resolutions that resolve to a file path.
+   * @param {string} filename
+   * @returns {boolean} true if any entries were deleted.
+   */
+  deleteResolveCacheByFilename(filename) {
+    let deleted = false;
+    for (const entry of this.#resolveCache) {
+      const parentURL = entry[0];
+      const entries = entry[1];
+      const keys = ObjectKeys(entries);
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const resolvedURL = entries[key]?.url;
+        if (!resolvedURL) {
+          continue;
+        }
+        const parsedURL = URLParse(resolvedURL);
+        if (!parsedURL || parsedURL.protocol !== 'file:') {
+          continue;
+        }
+        if (parsedURL.search !== '' || parsedURL.hash !== '') {
+          parsedURL.search = '';
+          parsedURL.hash = '';
+        }
+        let resolvedFilename;
+        try {
+          resolvedFilename = fileURLToPath(parsedURL);
+        } catch {
+          continue;
+        }
+        if (resolvedFilename === filename) {
+          delete entries[key];
+          deleted = true;
+        }
+      }
+
+      if (ObjectKeys(entries).length === 0) {
+        this.#resolveCache.delete(parentURL);
+      }
+    }
+    return deleted;
+  }
+
   /**
    * @see {AsyncLoaderHooks.isForAsyncLoaderHookWorker}
    * Shortcut to this.#asyncLoaderHooks.isForAsyncLoaderHookWorker.