fixup! module: add clearCache for CJS and ESM

Author: anonrig

doc/api/module.md

@@ -87,8 +87,6 @@ added: REPLACEME
     * `'module'` — clear the cached module everywhere in Node.js (not counting
       JS-level references).
     * `'all'` — clear both resolution and module caches.
-  * `importAttributes` {Object} Optional import attributes. Only meaningful when
-    `resolver` is `'import'`.
 
 Clears module resolution and/or module caches for a module. This enables
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for
@@ -101,27 +99,25 @@ the same file path are cleared even if they differ by search or hash. This means
 `'./mod.mjs?v=1'` will also clear `'./mod.mjs?v=2'` and any other query/hash variants that
 resolve to the same file.
 
-When `caches` is `'resolution'` or `'all'` with `resolver` set to `'import'`, the ESM
-resolution cache entry for the given `(specifier, parentURL, importAttributes)` tuple is
-cleared. When `resolver` is `'require'`, internal CJS resolution caches (including the
-relative resolve cache and path cache) are also cleared for the resolved filename.
-When `importAttributes` are provided for `'import'` resolution, they are used to construct the cache key; if a module
-was loaded with multiple different import attribute combinations, only the matching entry
-is cleared from the resolution cache. The module cache itself (`caches: 'module'`) clears
-all attribute variants for the URL.
+When `caches` is `'resolution'` or `'all'` with `resolver` set to `'import'`, all ESM
+resolution cache entries for the given `(specifier, parentURL)` pair are cleared regardless
+of import attributes. When `resolver` is `'require'`, the specific CJS relative resolve
+cache entry for the `(parentDir, specifier)` pair is cleared, together with any cached
+`package.json` data for the resolved module's package.
 
 Clearing a module does not clear cached entries for its dependencies. When using
 `resolver: 'import'`, resolution cache entries for other specifiers that resolve to the
-same target are not cleared — only the exact `(specifier, parentURL, importAttributes)`
-entry is removed. The module cache itself is cleared by resolved file path, so all
-specifiers pointing to the same file will see a fresh execution on next import.
+same target are not cleared — only entries for the exact `(specifier, parentURL)` pair
+are removed. The module cache itself is cleared by resolved file path, so all specifiers
+pointing to the same file will see a fresh execution on next import.
 
 #### ECMA-262 spec considerations
 
-Re-importing the exact same `(specifier, parentURL, importAttribtues)` tuple after clearing the module cache
+Re-importing the exact same `(specifier, parentURL, importAttributes)` tuple after clearing the module cache
 technically violates the idempotency invariant of the ECMA-262
 [`HostLoadImportedModule`][] host hook, which expects that the same module request always
-returns the same Module Record for a given referrer. For spec-compliant usage, use
+returns the same Module Record for a given referrer. The result of violating this requirement
+is undefined — e.g. it can lead to crashes. For spec-compliant usage, use
 cache-busting search parameters so that each reload uses a distinct module request:
 
 ```mjs
@@ -163,11 +159,12 @@ await import('./mod.mjs'); // re-executes the module
 
 ```cjs
 const { clearCache } = require('node:module');
+const { pathToFileURL } = require('node:url');
 
 require('./mod.js');
 
 clearCache('./mod.js', {
-  parentURL: __filename,
+  parentURL: pathToFileURL(__filename),
   resolver: 'require',
   caches: 'module',
 });

lib/internal/modules/cjs/loader.js

@@ -122,6 +122,7 @@ module.exports = {
   initializeCJS,
   Module,
   clearCJSResolutionCaches,
+  deleteCJSRelativeResolveCacheEntry,
   findLongestRegisteredExtension,
   resolveForCJSWithHooks,
   loadSourceForCJSWithHooks: loadSource,
@@ -250,6 +251,23 @@ function clearCJSResolutionCaches(filename) {
   }
 }
 
+/**
+ * Delete a single entry from the CJS relative resolve cache.
+ * The cache key is `${parent.path}\x00${request}` where parent.path is the
+ * directory containing the parent module (i.e. path.dirname(parentFilename)).
+ * @param {string} parentDir Directory of the parent module (path.dirname of filename).
+ * @param {string} request The specifier as originally passed to require().
+ * @returns {boolean} true if the entry existed and was deleted.
+ */
+function deleteCJSRelativeResolveCacheEntry(parentDir, request) {
+  const key = `${parentDir}\x00${request}`;
+  if (relativeResolveCache[key] !== undefined) {
+    delete relativeResolveCache[key];
+    return true;
+  }
+  return false;
+}
+
 let requireDepth = 0;
 let isPreloading = false;
 let statCache = null;

lib/internal/modules/clear.js

@@ -14,9 +14,11 @@ const {
   Module,
   resolveForCJSWithHooks,
   clearCJSResolutionCaches,
+  deleteCJSRelativeResolveCacheEntry,
 } = require('internal/modules/cjs/loader');
+const { getFilePathFromFileURL } = require('internal/modules/helpers');
 const { fileURLToPath, isURL, URLParse, pathToFileURL } = require('internal/url');
-const { emitExperimentalWarning, kEmptyObject, isWindows } = require('internal/util');
+const { emitExperimentalWarning, isWindows } = require('internal/util');
 const { validateObject, validateOneOf, validateString } = require('internal/validators');
 const {
   codes: {
@@ -75,29 +77,18 @@ function createParentModuleForClearCache(parentPath) {
 /**
  * Resolve a cache filename for CommonJS.
  * Always goes through resolveForCJSWithHooks so that registered hooks
- * are respected. CJS operates on file paths and bare specifiers. file:
- * URL objects or strings are converted to paths; non-file URLs are not
- * supported and will return null.
+ * are respected. The specifier is passed as-is: if hooks are registered,
+ * they handle any URL interpretation; if not, it is treated as a plain
+ * path/identifier (matching how require() interprets its argument).
  * @param {string|URL} specifier
  * @param {string|undefined} parentPath
  * @returns {string|null}
  */
 function resolveClearCacheFilename(specifier, parentPath) {
-  let request;
-  if (isURL(specifier)) {
-    if (specifier.protocol !== 'file:') {
-      return null;
-    }
-    request = fileURLToPath(specifier);
-  } else if (typeof specifier === 'string' && StringPrototypeStartsWith(specifier, 'file:')) {
-    const parsed = URLParse(specifier);
-    if (!parsed || parsed.protocol !== 'file:') {
-      return null;
-    }
-    request = fileURLToPath(parsed);
-  } else {
-    request = specifier;
-  }
+  // Pass the specifier through as-is. When hooks are registered they
+  // receive the raw value; without hooks CJS resolution treats it as
+  // a plain path or bare name, consistent with how require() behaves.
+  const request = isURL(specifier) ? specifier.href : specifier;
 
   if (!parentPath && isRelative(request)) {
     return null;
@@ -164,29 +155,6 @@ function deleteModuleFromParents(targetModule) {
   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?.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
@@ -195,7 +163,7 @@ function getFilePathFromClearCacheURL(url) {
  */
 function deleteLoadCacheEntries(loadCache, url) {
   let deleted = loadCache.deleteAll(url);
-  const filename = getFilePathFromClearCacheURL(url);
+  const filename = getFilePathFromFileURL(url);
   if (!filename) {
     return deleted;
   }
@@ -210,7 +178,7 @@ function deleteLoadCacheEntries(loadCache, url) {
     if (cachedURL === url) {
       continue;
     }
-    const cachedFilename = getFilePathFromClearCacheURL(cachedURL);
+    const cachedFilename = getFilePathFromFileURL(cachedURL);
     if (cachedFilename === filename) {
       loadCache.deleteAll(cachedURL);
       deleted = true;
@@ -240,7 +208,6 @@ function isRelative(pathToCheck) {
  * @param {string|URL} specifier What would've been passed into import() or require().
  * @param {{
  *   parentURL: string|URL,
- *   importAttributes?: Record<string, string>,
  *   resolver: 'import'|'require',
  *   caches: 'resolution'|'module'|'all',
  * }} options
@@ -260,11 +227,6 @@ function clearCache(specifier, options) {
   validateOneOf(resolver, 'options.resolver', ['import', 'require']);
   validateOneOf(caches, 'options.caches', ['resolution', 'module', 'all']);
 
-  const importAttributes = options.importAttributes ?? kEmptyObject;
-  if (options.importAttributes !== undefined) {
-    validateObject(options.importAttributes, 'options.importAttributes');
-  }
-
   const clearResolution = caches === 'resolution' || caches === 'all';
   const clearModule = caches === 'module' || caches === 'all';
 
@@ -283,38 +245,40 @@ function clearCache(specifier, options) {
     } else {
       resolvedURL = resolveClearCacheURL(specifier, parentURL);
       if (resolvedURL) {
-        resolvedFilename = getFilePathFromClearCacheURL(resolvedURL);
+        resolvedFilename = getFilePathFromFileURL(resolvedURL);
       }
     }
   }
 
   // Clear resolution caches.
   if (clearResolution) {
     // ESM has a structured resolution cache keyed by (specifier, parentURL,
-    // importAttributes).
+    // importAttributes). Clear all attribute variants for the given
+    // (specifier, parentURL) pair since attributes don't affect resolution
+    // per spec and it avoids partial-clear surprises.
     if (resolver === 'import') {
       const specifierStr = isSpecifierURL ? specifier.href : specifier;
       const cascadedLoader =
         require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-      cascadedLoader.deleteResolveCacheEntry(specifierStr, parentURL, importAttributes);
+      cascadedLoader.deleteAllResolveCacheEntries(specifierStr, parentURL);
     }
 
-    // CJS has relativeResolveCache and Module._pathCache that map
-    // specifiers to filenames. Clear all entries pointing to the resolved
-    // file. Module._pathCache keys are not easily reconstructable so a
-    // value-scan is required.
-    if (resolver === 'require' && resolvedFilename) {
-      clearCJSResolutionCaches(resolvedFilename);
-    }
+    // CJS resolution caches are only relevant when the resolver is 'require'.
+    if (resolver === 'require' && parentPath) {
+      // Delete the specific relativeResolveCache entry for this
+      // (parent-dir, request) pair. More targeted than a full value-scan.
+      const requestStr = isSpecifierURL ? specifier.href : specifier;
+      deleteCJSRelativeResolveCacheEntry(path.dirname(parentPath), requestStr);
 
-    if (resolvedFilename) {
       // Clear package.json caches for the resolved module's package so that
       // updated exports/imports conditions are picked up on re-resolution.
-      const { getNearestParentPackageJSON, clearPackageJSONCache } =
-        require('internal/modules/package_json_reader');
-      const pkg = getNearestParentPackageJSON(resolvedFilename);
-      if (pkg?.path) {
-        clearPackageJSONCache(pkg.path);
+      if (resolvedFilename) {
+        const { getNearestParentPackageJSON, clearPackageJSONCache } =
+          require('internal/modules/package_json_reader');
+        const pkg = getNearestParentPackageJSON(resolvedFilename);
+        if (pkg?.path) {
+          clearPackageJSONCache(pkg.path);
+        }
       }
     }
   }

lib/internal/modules/esm/loader.js

@@ -180,6 +180,17 @@ class ModuleLoader {
     return this.#resolveCache.deleteBySpecifier(specifier, parentURL, importAttributes);
   }
 
+  /**
+   * Delete all cached resolution entries for a specifier from a parent URL,
+   * regardless of import attributes.
+   * @param {string} specifier
+   * @param {string|undefined} parentURL
+   * @returns {boolean} true if at least one entry was deleted.
+   */
+  deleteAllResolveCacheEntries(specifier, parentURL) {
+    return this.#resolveCache.deleteAllBySpecifier(specifier, parentURL);
+  }
+
   /**
    * Check if a cached resolution exists for a specific request.
    * @param {string} specifier

lib/internal/modules/esm/module_map.js

@@ -8,6 +8,7 @@ const {
   ObjectKeys,
   ObjectPrototypeHasOwnProperty,
   SafeMap,
+  StringPrototypeStartsWith,
 } = primordials;
 const { kImplicitTypeAttribute } = require('internal/modules/esm/assert');
 let debug = require('internal/util/debuglog').debuglog('esm', (fn) => {
@@ -109,6 +110,34 @@ class ResolveCache extends SafeMap {
     }
     return true;
   }
+
+  /**
+   * Delete all cached resolution entries for a specifier in a parent URL,
+   * regardless of import attributes.
+   * @param {string} specifier
+   * @param {string|undefined} parentURL
+   * @returns {boolean} true if at least one entry was deleted.
+   */
+  deleteAllBySpecifier(specifier, parentURL) {
+    const entries = super.get(parentURL);
+    if (entries == null) {
+      return false;
+    }
+    // Keys are serialized as `specifier + '::' + attributes`. Match all
+    // entries whose prefix up to and including '::' matches this specifier.
+    const prefix = specifier + '::';
+    let deleted = false;
+    for (const key of ObjectKeys(entries)) {
+      if (key === prefix || StringPrototypeStartsWith(key, prefix)) {
+        delete entries[key];
+        deleted = true;
+      }
+    }
+    if (deleted && ObjectKeys(entries).length === 0) {
+      super.delete(parentURL);
+    }
+    return deleted;
+  }
 }
 
 /**

lib/internal/modules/esm/translators.js

@@ -30,6 +30,7 @@ const {
   stringify,
   stripBOM,
   urlToFilename,
+  getFilePathFromFileURL,
 } = require('internal/modules/helpers');
 const { stripTypeScriptModuleTypes } = require('internal/modules/typescript');
 const {
@@ -44,7 +45,7 @@ const {
   loadSourceForCJSWithHooks,
   populateCJSExportsFromESM,
 } = require('internal/modules/cjs/loader');
-const { fileURLToPath, pathToFileURL, URL, URLParse } = require('internal/url');
+const { fileURLToPath, pathToFileURL, URL } = require('internal/url');
 let debug = require('internal/util/debuglog').debuglog('esm', (fn) => {
   debug = fn;
 });
@@ -184,38 +185,14 @@ function loadCJSModule(module, source, url, filename, isMain) {
 // TODO: can we use a weak map instead?
 const cjsCache = new SafeMap();
 
-/**
- * Resolve a file path for a file URL, stripping search/hash.
- * @param {string} url
- * @returns {string|null}
- */
-function getFilePathFromCjsCacheURL(url) {
-  const parsedURL = URLParse(url);
-  if (!parsedURL) {
-    return null;
-  }
-  if (parsedURL.protocol !== 'file:') {
-    return null;
-  }
-  if (parsedURL.search !== '' || parsedURL.hash !== '') {
-    parsedURL.search = '';
-    parsedURL.hash = '';
-  }
-  try {
-    return fileURLToPath(parsedURL);
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Remove cjsCache entries for a URL and its file-path variants.
  * @param {string} url
  * @returns {boolean} true if any entries were deleted.
  */
 function clearCjsCache(url) {
   let deleted = cjsCache.delete(url);
-  const filename = getFilePathFromCjsCacheURL(url);
+  const filename = getFilePathFromFileURL(url);
   if (!filename) {
     return deleted;
   }
@@ -230,7 +207,7 @@ function clearCjsCache(url) {
     if (cachedURL === url) {
       continue;
     }
-    const cachedFilename = getFilePathFromCjsCacheURL(cachedURL);
+    const cachedFilename = getFilePathFromFileURL(cachedURL);
     if (cachedFilename === filename) {
       cjsCache.delete(cachedURL);
       deleted = true;