fixup! module: add clearCache for CJS and ESM

Author: anonrig

doc/api/module.md

@@ -72,7 +72,7 @@ const siblingModule = require('./sibling-module');
 added: REPLACEME
 -->
 
-> Stability: 1.1 - Active development
+> Stability: 1.0 - Early development
 
 * `specifier` {string|URL} The module specifier, as it would have been passed to
   `import()` or `require()`.
@@ -91,21 +91,61 @@ added: REPLACEME
     `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 HMR.
+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.
+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'`, the ESM
 resolution cache entry for the given `(specifier, parentURL, importAttributes)` tuple is
-cleared. CJS does not maintain a separate resolution cache.
+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, 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.
 
 Clearing a module does not clear cached entries for its dependencies, and other specifiers
 that resolve to the same target may remain. Use consistent specifiers, or call `clearCache()`
 for each specifier you want to re-execute.
 
+#### ECMA-262 spec considerations
+
+Re-importing the exact same `(specifier, parentURL)` pair 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
+cache-busting search parameters so that each reload uses a distinct module request:
+
+```mjs
+import { clearCache } from 'node:module';
+import { watch } from 'node:fs';
+
+let version = 0;
+const base = new URL('./app.mjs', import.meta.url);
+
+watch(base, async () => {
+  // Clear the module cache for the previous version.
+  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
+  // and does not violate the ECMA-262 invariant.
+  const mod = await import(`${base.href}?v=${version}`);
+  console.log('reloaded:', mod);
+});
+```
+
+#### Examples
+
 ```mjs
 import { clearCache } from 'node:module';
 
@@ -2082,6 +2122,7 @@ returned object contains the following keys:
 [`--require`]: cli.md#-r---require-module
 [`NODE_COMPILE_CACHE=dir`]: cli.md#node_compile_cachedir
 [`NODE_COMPILE_CACHE_PORTABLE=1`]: cli.md#node_compile_cache_portable1
+[`HostLoadImportedModule`]: https://tc39.es/ecma262/#sec-HostLoadImportedModule
 [`NODE_DISABLE_COMPILE_CACHE=1`]: cli.md#node_disable_compile_cache1
 [`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir
 [`SourceMap`]: #class-modulesourcemap

lib/internal/modules/cjs/loader.js

@@ -119,6 +119,7 @@ module.exports = {
   kModuleCircularVisited,
   initializeCJS,
   Module,
+  clearCJSResolutionCaches,
   findLongestRegisteredExtension,
   resolveForCJSWithHooks,
   loadSourceForCJSWithHooks: loadSource,
@@ -225,6 +226,30 @@ const onRequire = getLazy(() => tracingChannel('module.require'));
 
 const relativeResolveCache = { __proto__: null };
 
+/**
+ * Clear all entries in the CJS relative resolve cache and _pathCache
+ * that map to a given filename. This is needed by clearCache() to
+ * prevent stale resolution results after a module is removed.
+ * @param {string} filename The resolved filename to purge.
+ */
+function clearCJSResolutionCaches(filename) {
+  // Clear from relativeResolveCache (keyed by parent.path + '\x00' + request).
+  const relKeys = ObjectKeys(relativeResolveCache);
+  for (let i = 0; i < relKeys.length; i++) {
+    if (relativeResolveCache[relKeys[i]] === filename) {
+      delete relativeResolveCache[relKeys[i]];
+    }
+  }
+
+  // Clear from Module._pathCache (keyed by request + '\x00' + paths).
+  const pathKeys = ObjectKeys(Module._pathCache);
+  for (let i = 0; i < pathKeys.length; i++) {
+    if (Module._pathCache[pathKeys[i]] === filename) {
+      delete Module._pathCache[pathKeys[i]];
+    }
+  }
+}
+
 let requireDepth = 0;
 let isPreloading = false;
 let statCache = null;

lib/internal/modules/clear.js

@@ -10,9 +10,9 @@ const {
   StringPrototypeStartsWith,
 } = primordials;
 
-const { Module, resolveForCJSWithHooks } = require('internal/modules/cjs/loader');
+const { Module, resolveForCJSWithHooks, clearCJSResolutionCaches } = require('internal/modules/cjs/loader');
 const { fileURLToPath, isURL, URLParse, pathToFileURL } = require('internal/url');
-const { kEmptyObject, isWindows } = require('internal/util');
+const { emitExperimentalWarning, kEmptyObject, isWindows } = require('internal/util');
 const { validateObject, validateOneOf, validateString } = require('internal/validators');
 const {
   codes: {
@@ -87,6 +87,10 @@ function createParentModuleForClearCache(parentPath) {
 
 /**
  * Resolve a cache filename for CommonJS.
+ * Always goes through resolveForCJSWithHooks so that registered hooks
+ * are respected. For file: URLs, search/hash are stripped before resolving
+ * since CJS operates on file paths. For non-file URLs, the specifier is
+ * passed as-is to let hooks handle it.
  * @param {string|URL} specifier
  * @param {string|undefined} parentPath
  * @returns {string|null}
@@ -99,44 +103,47 @@ function resolveClearCacheFilename(specifier, parentPath) {
   const parsedURL = getURLFromClearCacheSpecifier(specifier);
   let request = specifier;
   if (parsedURL) {
-    if (parsedURL.protocol !== 'file:' || parsedURL.search !== '' || parsedURL.hash !== '') {
-      return null;
+    if (parsedURL.protocol === 'file:') {
+      // Strip search/hash - CJS operates on file paths.
+      if (parsedURL.search !== '' || parsedURL.hash !== '') {
+        parsedURL.search = '';
+        parsedURL.hash = '';
+      }
+      request = fileURLToPath(parsedURL);
+    } else {
+      // Non-file URLs (e.g. virtual://) — pass the href as-is
+      // so that registered hooks can resolve them.
+      request = parsedURL.href;
     }
-    request = fileURLToPath(parsedURL);
   }
 
   const parent = parentPath ? createParentModuleForClearCache(parentPath) : null;
-  const { filename, format } = resolveForCJSWithHooks(request, parent, false, false);
-  if (format === 'builtin') {
+  try {
+    const { filename, format } = resolveForCJSWithHooks(request, parent, false, false);
+    if (format === 'builtin') {
+      return null;
+    }
+    return filename;
+  } catch {
+    // Resolution can fail for non-file specifiers without hooks — return null
+    // to silently skip clearing rather than throwing.
     return null;
   }
-  return filename;
 }
 
 /**
  * Resolve a cache URL for ESM.
+ * Always goes through the loader's resolveSync so that registered hooks
+ * (e.g. hooks that redirect specifiers) are respected.
  * @param {string|URL} specifier
- * @param {string|undefined} parentURL
+ * @param {string} parentURL
  * @returns {string}
  */
 function resolveClearCacheURL(specifier, parentURL) {
-  const parsedURL = getURLFromClearCacheSpecifier(specifier);
-  if (parsedURL != null) {
-    return parsedURL.href;
-  }
-
-  if (path.isAbsolute(specifier)) {
-    return pathToFileURL(specifier).href;
-  }
-
-  if (parentURL === undefined) {
-    throw new ERR_INVALID_ARG_VALUE('options.parentURL', parentURL,
-                                    'must be provided for non-URL ESM specifiers');
-  }
-
   const cascadedLoader =
     require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-  const request = { specifier, __proto__: null };
+  const specifierStr = isURL(specifier) ? specifier.href : specifier;
+  const request = { specifier: specifierStr, __proto__: null };
   return cascadedLoader.resolveSync(parentURL, request).url;
 }
 
@@ -253,6 +260,8 @@ function isRelative(pathToCheck) {
  * }} options
  */
 function clearCache(specifier, options) {
+  emitExperimentalWarning('module.clearCache');
+
   const isSpecifierURL = isURL(specifier);
   if (!isSpecifierURL) {
     validateString(specifier, 'specifier');
@@ -273,13 +282,13 @@ function clearCache(specifier, options) {
   const clearResolution = caches === 'resolution' || caches === 'all';
   const clearModule = caches === 'module' || caches === 'all';
 
-  // Resolve the specifier when module cache clearing is needed.
+  // 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.
   let resolvedFilename = null;
   let resolvedURL = null;
 
-  if (clearModule) {
+  if (clearModule || clearResolution) {
     if (resolver === 'require') {
       resolvedFilename = resolveClearCacheFilename(specifier, parentPath);
       if (resolvedFilename) {
@@ -293,13 +302,31 @@ function clearCache(specifier, options) {
     }
   }
 
-  // Clear resolution cache. Only ESM has a structured resolution cache;
-  // CJS resolution results are not separately cached.
-  if (clearResolution && resolver === 'import') {
-    const specifierStr = isSpecifierURL ? specifier.href : specifier;
-    const cascadedLoader =
-      require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-    cascadedLoader.deleteResolveCacheEntry(specifierStr, parentURL, importAttributes);
+  // Clear resolution caches.
+  if (clearResolution) {
+    // ESM has a structured resolution cache 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);
+    }
+
+    // CJS has relativeResolveCache and Module._pathCache that map
+    // specifiers to filenames. Clear entries pointing to the resolved file.
+    if (resolvedFilename) {
+      clearCJSResolutionCaches(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);
+      }
+    }
   }
 
   // Clear module caches everywhere in Node.js.
@@ -311,6 +338,10 @@ function clearCache(specifier, options) {
         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);
     }
 
     // ESM load cache and translators cjsCache

lib/internal/modules/esm/loader.js

@@ -6,7 +6,6 @@ const {
   ArrayPrototypeReduce,
   FunctionPrototypeCall,
   JSONStringify,
-  ObjectKeys,
   ObjectSetPrototypeOf,
   Promise,
   PromisePrototypeThen,
@@ -31,7 +30,7 @@ const {
   ERR_UNKNOWN_MODULE_FORMAT,
 } = require('internal/errors').codes;
 const { getOptionValue } = require('internal/options');
-const { isURL, pathToFileURL, fileURLToPath, URLParse } = require('internal/url');
+const { isURL, pathToFileURL } = require('internal/url');
 const { kEmptyObject } = require('internal/util');
 const {
   compileSourceTextModule,
@@ -182,47 +181,15 @@ class ModuleLoader {
   }
 
   /**
-   * Delete cached resolutions that resolve to a file path.
-   * @param {string} filename
-   * @returns {boolean} true if any entries were deleted.
+   * Check if a cached resolution exists for a specific request.
+   * @param {string} specifier
+   * @param {string|undefined} parentURL
+   * @param {Record<string, string>} importAttributes
+   * @returns {boolean} true if an entry exists.
    */
-  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;
+  hasResolveCacheEntry(specifier, parentURL, importAttributes = { __proto__: null }) {
+    const serializedKey = this.#resolveCache.serializeKey(specifier, importAttributes);
+    return this.#resolveCache.has(serializedKey, parentURL);
   }
 
   /**

lib/internal/modules/package_json_reader.js

@@ -353,8 +353,32 @@ function findPackageJSON(specifier, base = 'data:') {
   return pkg?.path;
 }
 
+/**
+ * Clear all package.json caches for a given package directory.
+ * This removes entries from:
+ * - The C++ native package_configs_ cache (via the binding)
+ * - The JS deserializedPackageJSONCache
+ * - The JS moduleToParentPackageJSONCache
+ * @param {string} packageJSONPath Absolute path to the package.json file.
+ */
+function clearPackageJSONCache(packageJSONPath) {
+  // Clear the native C++ cache.
+  modulesBinding.clearPackageJSONCache(packageJSONPath);
+
+  // Clear the JS-level deserialized cache.
+  deserializedPackageJSONCache.delete(packageJSONPath);
+
+  // Clear moduleToParentPackageJSONCache entries that point to this package.json.
+  for (const { 0: key, 1: value } of moduleToParentPackageJSONCache) {
+    if (value === packageJSONPath) {
+      moduleToParentPackageJSONCache.delete(key);
+    }
+  }
+}
+
 module.exports = {
   read,
+  clearPackageJSONCache,
   getNearestParentPackageJSON,
   getPackageScopeConfig,
   getPackageType,