fixup! module: add clearCache for CJS and ESM

Author: anonrig

doc/api/module.md

@@ -82,34 +82,31 @@ added: REPLACEME
     For ES modules, pass `import.meta.url`.
   * `resolver` {string} Specifies how resolution should be performed. Must be either
     `'import'` or `'require'`.
-  * `caches` {string} Specifies which caches to clear. Must be one of:
-    * `'resolution'` — only clear the resolution cache entry for this specifier.
-    * `'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
+Clears the module resolution and module caches for a module. This enables
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for
 hot module reload.
 
-When `caches` is `'module'` or `'all'`, the specifier is resolved using the chosen `resolver`
-and the resolved module is removed from all internal caches (CommonJS `require` cache, ESM
-load cache, and ESM translators cache). When a `file:` URL is resolved, cached module jobs for
-the same file path are cleared even if they differ by search or hash. This means clearing
-`'./mod.mjs?v=1'` will also clear `'./mod.mjs?v=2'` and any other query/hash variants that
-resolve to the same file.
+The specifier is resolved using the chosen `resolver`, then the resolved module is removed
+from all internal caches (CommonJS `require` cache, CommonJS resolution caches, ESM resolve
+cache, ESM load cache, and ESM translators cache). When `resolver` is `'import'`,
+`importAttributes` are part of the ESM resolve-cache key, so only the exact
+`(specifier, parentURL, importAttributes)` resolution entry is removed. When a `file:` URL is
+resolved, cached module jobs for the same file path are cleared even if they differ by search
+or hash. This means clearing `'./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'`, 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.
+When `resolver` is `'require'`, cached `package.json` data for the resolved module's package
+is also cleared so that updated exports/imports conditions are picked up on the next
+resolution.
 
 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 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.
+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.
 
 #### Memory retention and static imports
 
@@ -161,7 +158,6 @@ watch(base, async () => {
   clearCache(new URL(`${base.href}?v=${version}`), {
     parentURL: import.meta.url,
     resolver: 'import',
-    caches: 'all',
   });
   version++;
   // Re-import with a new search parameter — this is a distinct module request
@@ -181,7 +177,6 @@ await import('./mod.mjs');
 clearCache('./mod.mjs', {
   parentURL: import.meta.url,
   resolver: 'import',
-  caches: 'module',
 });
 await import('./mod.mjs'); // re-executes the module
 ```
@@ -195,7 +190,6 @@ require('./mod.js');
 clearCache('./mod.js', {
   parentURL: pathToFileURL(__filename),
   resolver: 'require',
-  caches: 'module',
 });
 require('./mod.js'); // eslint-disable-line node-core/no-duplicate-requires
 // re-executes the module

lib/internal/modules/cjs/loader.js

@@ -122,7 +122,6 @@ module.exports = {
   initializeCJS,
   Module,
   clearCJSResolutionCaches,
-  deleteCJSRelativeResolveCacheEntry,
   findLongestRegisteredExtension,
   resolveForCJSWithHooks,
   loadSourceForCJSWithHooks: loadSource,
@@ -251,23 +250,6 @@ 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,11 +14,10 @@ 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, isWindows } = require('internal/util');
+const { emitExperimentalWarning, kEmptyObject, isWindows } = require('internal/util');
 const { validateObject, validateOneOf, validateString } = require('internal/validators');
 const {
   codes: {
@@ -204,12 +203,12 @@ function isRelative(pathToCheck) {
 }
 
 /**
- * Clear module resolution and/or module caches.
+ * Clear module resolution and module caches.
  * @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
  */
 function clearCache(specifier, options) {
@@ -223,89 +222,65 @@ function clearCache(specifier, options) {
   validateObject(options, 'options');
   const { parentURL, parentPath } = normalizeClearCacheParent(options.parentURL);
 
-  const { resolver, caches } = options;
+  const { resolver } = options;
   validateOneOf(resolver, 'options.resolver', ['import', 'require']);
-  validateOneOf(caches, 'options.caches', ['resolution', 'module', 'all']);
 
-  const clearResolution = caches === 'resolution' || caches === 'all';
-  const clearModule = caches === 'module' || caches === 'all';
+  const importAttributes = options.importAttributes ?? kEmptyObject;
+  if (options.importAttributes !== undefined) {
+    validateObject(options.importAttributes, 'options.importAttributes');
+  }
 
-  // Resolve the specifier when module or resolution cache clearing is needed.
-  // Must be done BEFORE clearing resolution caches since resolution
-  // may rely on the resolve cache.
+  // Resolve before clearing so resolution-cache entries are still available.
   let resolvedFilename = null;
   let resolvedURL = null;
 
-  if (clearModule || clearResolution) {
-    if (resolver === 'require') {
-      resolvedFilename = resolveClearCacheFilename(specifier, parentPath);
-      if (resolvedFilename) {
-        resolvedURL = pathToFileURL(resolvedFilename).href;
-      }
-    } else {
-      resolvedURL = resolveClearCacheURL(specifier, parentURL);
-      if (resolvedURL) {
-        resolvedFilename = getFilePathFromFileURL(resolvedURL);
-      }
+  if (resolver === 'require') {
+    resolvedFilename = resolveClearCacheFilename(specifier, parentPath);
+    if (resolvedFilename) {
+      resolvedURL = pathToFileURL(resolvedFilename).href;
     }
-  }
-
-  // Clear resolution caches.
-  if (clearResolution) {
-    // ESM has a structured resolution cache keyed by (specifier, parentURL,
-    // 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.deleteAllResolveCacheEntries(specifierStr, parentURL);
+  } else {
+    resolvedURL = resolveClearCacheURL(specifier, parentURL);
+    if (resolvedURL) {
+      resolvedFilename = getFilePathFromFileURL(resolvedURL);
     }
+  }
 
-    // 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);
+  // ESM resolution cache entries are keyed by
+  // (specifier, parentURL, importAttributes).
+  if (resolver === 'import') {
+    const specifierStr = isSpecifierURL ? specifier.href : specifier;
+    const cascadedLoader =
+      require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+    cascadedLoader.deleteResolveCacheEntry(specifierStr, parentURL, importAttributes);
+  }
 
-      // Clear package.json caches for the resolved module's package so that
-      // updated exports/imports conditions are picked up on re-resolution.
-      if (resolvedFilename) {
-        const { getNearestParentPackageJSON, clearPackageJSONCache } =
-          require('internal/modules/package_json_reader');
-        const pkg = getNearestParentPackageJSON(resolvedFilename);
-        if (pkg?.path) {
-          clearPackageJSONCache(pkg.path);
-        }
-      }
+  if (resolver === 'require' && resolvedFilename) {
+    const { getNearestParentPackageJSON, clearPackageJSONCache } =
+      require('internal/modules/package_json_reader');
+    const pkg = getNearestParentPackageJSON(resolvedFilename);
+    if (pkg?.path) {
+      clearPackageJSONCache(pkg.path);
     }
   }
 
   // Clear module caches everywhere in Node.js.
-  if (clearModule) {
-    // CJS Module._cache
-    if (resolvedFilename) {
-      const cachedModule = Module._cache[resolvedFilename];
-      if (cachedModule !== undefined) {
-        delete Module._cache[resolvedFilename];
-        deleteModuleFromParents(cachedModule);
-      }
-      // Also clear CJS resolution caches that point to this filename,
-      // even if only 'module' was requested, to avoid stale resolution
-      // results pointing to a purged module.
-      clearCJSResolutionCaches(resolvedFilename);
+  if (resolvedFilename) {
+    const cachedModule = Module._cache[resolvedFilename];
+    if (cachedModule !== undefined) {
+      delete Module._cache[resolvedFilename];
+      deleteModuleFromParents(cachedModule);
     }
+    // Also clear CJS resolution caches that point to this filename.
+    clearCJSResolutionCaches(resolvedFilename);
+  }
 
-    // ESM load cache and translators cjsCache
-    if (resolvedURL) {
-      const cascadedLoader =
-        require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-      deleteLoadCacheEntries(cascadedLoader.loadCache, resolvedURL);
-      const { clearCjsCache } = require('internal/modules/esm/translators');
-      clearCjsCache(resolvedURL);
-    }
+  if (resolvedURL) {
+    const cascadedLoader =
+      require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+    deleteLoadCacheEntries(cascadedLoader.loadCache, resolvedURL);
+    const { clearCjsCache } = require('internal/modules/esm/translators');
+    clearCjsCache(resolvedURL);
   }
 }
 

lib/internal/modules/esm/loader.js

@@ -180,17 +180,6 @@ 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,7 +8,6 @@ const {
   ObjectKeys,
   ObjectPrototypeHasOwnProperty,
   SafeMap,
-  StringPrototypeStartsWith,
 } = primordials;
 const { kImplicitTypeAttribute } = require('internal/modules/esm/assert');
 let debug = require('internal/util/debuglog').debuglog('esm', (fn) => {
@@ -110,34 +109,6 @@ 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;
-  }
 }
 
 /**