fixup! module: add clearCache for CJS and ESM

Author: anonrig

doc/api/module.md

@@ -66,55 +66,73 @@ const require = createRequire(import.meta.url);
 const siblingModule = require('./sibling-module');
 ```
 
-### `module.clearCache(specifier[, options])`
+### `module.clearCache(specifier, options)`
 
 <!-- YAML
 added: REPLACEME
 -->
 
 > Stability: 1.1 - Active development
 
-* `specifier` {string|URL} The module specifier or URL to resolve. The resolved URL/filename
-  is cleared from the load cache; the specifier (with `parentURL`) is cleared from the
-  resolve cache.
+* `specifier` {string|URL} The module specifier, as it would have been passed to
+  `import()` or `require()`.
 * `options` {Object}
-  * `parentURL` {string|URL} The parent URL used to resolve non-URL specifiers.
-    For CommonJS, pass `pathToFileURL(__filename)`. For ES modules, pass `import.meta.url`.
-* Returns: {Object} An object with `{ require: boolean, import: boolean }` indicating whether entries
-  were removed from each cache.
-
-Clears the CommonJS `require` cache and the ESM module cache for a module. This enables
+  * `parentURL` {string|URL} The parent URL used to resolve the specifier. Parent identity
+    is part of the resolution cache key. For CommonJS, pass `pathToFileURL(__filename)`.
+    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
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR.
-Resolution failures for one module system do not throw; check the returned flags to see what
-was cleared.
-This does not clear resolution cache entries for that specifier. Clearing a module does not
-clear cached entries for its dependencies, and other specifiers that resolve to the same target
-may remain.
-When a `file:` URL is resolved, cached module jobs for the same file path are cleared even if
-they differ by search or hash.
-If the same file is loaded via multiple specifiers (for example `require('./x')` alongside
-`import('./x.js?t=1')` and `import('./x.js?t=2')`), resolution cache entries for each specifier
-remain. Use consistent specifiers, or call `clearCache()` for each specifier you want to
-re-execute.
+
+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.
+
+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.
+
+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.
 
 ```mjs
 import { clearCache } from 'node:module';
 
 const url = new URL('./mod.mjs', import.meta.url);
 await import(url.href);
 
-clearCache(url);
+clearCache(url, {
+  parentURL: import.meta.url,
+  resolver: 'import',
+  caches: 'module',
+});
 await import(url.href); // re-executes the module
 ```
 
 ```cjs
 const { clearCache } = require('node:module');
+const { pathToFileURL } = require('node:url');
 const path = require('node:path');
 
 const file = path.join(__dirname, 'mod.js');
 require(file);
 
-clearCache(file);
+clearCache(file, {
+  parentURL: pathToFileURL(__filename),
+  resolver: 'require',
+  caches: 'module',
+});
 require(file); // re-executes the module
 ```
 

lib/internal/modules/clear.js

@@ -34,7 +34,7 @@ const {
 const { Module, resolveForCJSWithHooks } = require('internal/modules/cjs/loader');
 const { fileURLToPath, isURL, URLParse, pathToFileURL } = require('internal/url');
 const { kEmptyObject, isWindows } = require('internal/util');
-const { validateObject, validateString } = require('internal/validators');
+const { validateObject, validateOneOf, validateString } = require('internal/validators');
 const {
   codes: {
     ERR_INVALID_ARG_VALUE,
@@ -51,14 +51,10 @@ const {
 
 /**
  * Normalize the parent URL for cache clearing.
- * @param {string|URL|undefined} parentURL
- * @returns {{ parentURL: string|undefined, parentPath: string|undefined }}
+ * @param {string|URL} parentURL
+ * @returns {{ parentURL: string, parentPath: string|undefined }}
  */
 function normalizeClearCacheParent(parentURL) {
-  if (parentURL === undefined) {
-    return { __proto__: null, parentURL: undefined, parentPath: undefined };
-  }
-
   if (isURL(parentURL)) {
     let parentPath;
     if (parentURL.protocol === 'file:' && parentURL.search === '' && parentURL.hash === '') {
@@ -268,61 +264,85 @@ function isRelative(pathToCheck) {
 }
 
 /**
- * Clear CommonJS and/or ESM module cache entries.
- * @param {string|URL} specifier
- * @param {object} [options]
- * @param {string|URL} [options.parentURL]
- * @returns {{ require: boolean, import: boolean }}
+ * Clear module resolution and/or 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 = kEmptyObject) {
+function clearCache(specifier, options) {
   const isSpecifierURL = isURL(specifier);
   if (!isSpecifierURL) {
     validateString(specifier, 'specifier');
   }
 
   validateObject(options, 'options');
   const { parentURL, parentPath } = normalizeClearCacheParent(options.parentURL);
-  const result = { __proto__: null, require: false, import: false };
 
-  try {
-    const deleteCommonjsCachesForFilename = (filename) => {
-      let deleted = false;
-      const cachedModule = Module._cache[filename];
-      if (cachedModule !== undefined) {
-        delete Module._cache[filename];
-        deleted = true;
-        deleteModuleFromParents(cachedModule);
-      }
-      return deleted;
-    };
+  const { resolver, caches } = options;
+  validateOneOf(resolver, 'options.resolver', ['import', 'require']);
+  validateOneOf(caches, 'options.caches', ['resolution', 'module', 'all']);
 
-    const filename = resolveClearCacheFilename(specifier, parentPath);
-    if (filename) {
-      result.require = deleteCommonjsCachesForFilename(filename);
-    }
+  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';
 
-    if (parentURL !== undefined) {
-      const url = resolveClearCacheURL(specifier, parentURL);
-      const resolvedPath = getFilePathFromClearCacheURL(url);
-      if (resolvedPath && resolvedPath !== filename) {
-        if (deleteCommonjsCachesForFilename(resolvedPath)) {
-          result.require = true;
-        }
+  // Resolve the specifier when module 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 (resolver === 'require') {
+      resolvedFilename = resolveClearCacheFilename(specifier, parentPath);
+      if (resolvedFilename) {
+        resolvedURL = pathToFileURL(resolvedFilename).href;
+      }
+    } else {
+      resolvedURL = resolveClearCacheURL(specifier, parentURL);
+      if (resolvedURL) {
+        resolvedFilename = getFilePathFromClearCacheURL(resolvedURL);
       }
     }
+  }
 
-    const url = resolveClearCacheURL(specifier, parentURL);
+  // 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();
-    const loadDeleted = deleteLoadCacheEntries(cascadedLoader.loadCache, url);
-    const { clearCjsCache } = require('internal/modules/esm/translators');
-    const cjsCacheDeleted = clearCjsCache(url);
-    result.import = loadDeleted || cjsCacheDeleted;
-  } catch {
-    // Best effort: avoid throwing for require cache clearing.
+    cascadedLoader.deleteResolveCacheEntry(specifierStr, parentURL, importAttributes);
   }
 
-  return result;
+  // 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);
+      }
+    }
+
+    // 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);
+    }
+  }
 }
 
 module.exports = {

test/es-module/test-module-clear-cache-caches-all.mjs

@@ -0,0 +1,35 @@
+// Tests that caches: 'all' clears both the resolution cache
+// and the module cache. The module IS re-evaluated after clearing.
+
+import '../common/index.mjs';
+
+import assert from 'node:assert';
+import { clearCache } from 'node:module';
+
+const specifier = '../fixtures/module-cache/esm-counter.mjs';
+
+const first = await import(specifier);
+assert.strictEqual(first.count, 1);
+
+// caches: 'all' — clears both resolution and module caches.
+clearCache(specifier, {
+  parentURL: import.meta.url,
+  resolver: 'import',
+  caches: 'all',
+});
+
+// Module should be re-evaluated.
+const second = await import(specifier);
+assert.strictEqual(second.count, 2);
+
+// Clearing again with 'all' should also work.
+clearCache(specifier, {
+  parentURL: import.meta.url,
+  resolver: 'import',
+  caches: 'all',
+});
+
+const third = await import(specifier);
+assert.strictEqual(third.count, 3);
+
+delete globalThis.__module_cache_esm_counter;

test/es-module/test-module-clear-cache-caches-resolution.mjs

@@ -0,0 +1,63 @@
+// Tests that caches: 'resolution' only clears the ESM resolution cache.
+// The module itself is NOT re-evaluated because the load cache still holds it.
+// Also tests that caches: 'resolution' with resolver: 'require' is harmless
+// (CJS has no separate resolution cache).
+
+import '../common/index.mjs';
+
+import assert from 'node:assert';
+import { clearCache, createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+// --- ESM: resolution-only clearing should NOT re-evaluate ---
+
+const specifier = '../fixtures/module-cache/esm-counter.mjs';
+
+const first = await import(specifier);
+assert.strictEqual(first.count, 1);
+
+// Clear only resolution cache.
+clearCache(specifier, {
+  parentURL: import.meta.url,
+  resolver: 'import',
+  caches: 'resolution',
+});
+
+// Module must NOT be re-evaluated — load cache still holds it.
+const second = await import(specifier);
+assert.strictEqual(second.count, 1);
+assert.strictEqual(first, second);
+
+// Now clear the module cache — module SHOULD be re-evaluated.
+clearCache(specifier, {
+  parentURL: import.meta.url,
+  resolver: 'import',
+  caches: 'module',
+});
+
+const third = await import(specifier);
+assert.strictEqual(third.count, 2);
+
+// --- CJS: resolution-only clearing should be a no-op ---
+
+const cjsFixturePath = fileURLToPath(
+  new URL('../fixtures/module-cache/cjs-counter.js', import.meta.url),
+);
+
+require(cjsFixturePath);
+assert.notStrictEqual(require.cache[cjsFixturePath], undefined);
+
+// caches: 'resolution' + resolver: 'require' → no-op for CJS.
+clearCache(cjsFixturePath, {
+  parentURL: import.meta.url,
+  resolver: 'require',
+  caches: 'resolution',
+});
+
+// Module._cache should be unaffected.
+assert.notStrictEqual(require.cache[cjsFixturePath], undefined);
+
+delete globalThis.__module_cache_esm_counter;
+delete globalThis.__module_cache_cjs_counter;