fixup! module: add clearCache for CJS and ESM

Author: anonrig

doc/api/module.md

@@ -105,18 +105,20 @@ When `caches` is `'resolution'` or `'all'` with `resolver` set to `'import'`, th
 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, they are used to construct the cache key; if a module
+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.
 
-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.
+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.
 
 #### ECMA-262 spec considerations
 
-Re-importing the exact same `(specifier, parentURL)` pair after clearing the module cache
+Re-importing the exact same `(specifier, parentURL, importAttribtues)` 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
@@ -149,31 +151,28 @@ watch(base, async () => {
 ```mjs
 import { clearCache } from 'node:module';
 
-const url = new URL('./mod.mjs', import.meta.url);
-await import(url.href);
+await import('./mod.mjs');
 
-clearCache(url, {
+clearCache('./mod.mjs', {
   parentURL: import.meta.url,
   resolver: 'import',
   caches: 'module',
 });
-await import(url.href); // re-executes the module
+await import('./mod.mjs'); // 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);
+require('./mod.js');
 
-clearCache(file, {
-  parentURL: pathToFileURL(__filename),
+clearCache('./mod.js', {
+  parentURL: __filename,
   resolver: 'require',
   caches: 'module',
 });
-require(file); // re-executes the module
+require('./mod.js'); // eslint-disable-line node-core/no-duplicate-requires
+// re-executes the module
 ```
 
 ### `module.findPackageJSON(specifier[, base])`

lib/internal/modules/cjs/loader.js

@@ -111,6 +111,8 @@ const kIsExecuting = Symbol('kIsExecuting');
 const kURL = Symbol('kURL');
 const kFormat = Symbol('kFormat');
 
+const relativeResolveCache = { __proto__: null };
+
 // Set first due to cycle with ESM loader functions.
 module.exports = {
   kModuleSource,
@@ -120,6 +122,7 @@ module.exports = {
   initializeCJS,
   Module,
   clearCJSResolutionCaches,
+  relativeResolveCache,
   findLongestRegisteredExtension,
   resolveForCJSWithHooks,
   loadSourceForCJSWithHooks: loadSource,
@@ -224,8 +227,6 @@ let { startTimer, endTimer } = debugWithTimer('module_timer', (start, end) => {
 const { tracingChannel } = require('diagnostics_channel');
 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

lib/internal/modules/clear.js

@@ -10,7 +10,12 @@ const {
   StringPrototypeStartsWith,
 } = primordials;
 
-const { Module, resolveForCJSWithHooks, clearCJSResolutionCaches } = require('internal/modules/cjs/loader');
+const {
+  Module,
+  resolveForCJSWithHooks,
+  clearCJSResolutionCaches,
+  relativeResolveCache,
+} = require('internal/modules/cjs/loader');
 const { fileURLToPath, isURL, URLParse, pathToFileURL } = require('internal/url');
 const { emitExperimentalWarning, kEmptyObject, isWindows } = require('internal/util');
 const { validateObject, validateOneOf, validateString } = require('internal/validators');
@@ -56,23 +61,6 @@ function normalizeClearCacheParent(parentURL) {
   return { __proto__: null, parentURL: url.href, parentPath };
 }
 
-/**
- * Parse a specifier as a URL when possible.
- * @param {string|URL} specifier
- * @returns {URL|null}
- */
-function getURLFromClearCacheSpecifier(specifier) {
-  if (isURL(specifier)) {
-    return specifier;
-  }
-
-  if (typeof specifier !== 'string' || path.isAbsolute(specifier)) {
-    return null;
-  }
-
-  return URLParse(specifier) ?? null;
-}
-
 /**
  * Create a synthetic parent module for CJS resolution.
  * @param {string} parentPath
@@ -88,10 +76,9 @@ 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
+ * are respected. CJS operates on file paths and bare specifiers; URL
+ * objects are not valid require() arguments so they are not supported.
+ * @param {string} specifier
  * @param {string|undefined} parentPath
  * @returns {string|null}
  */
@@ -100,26 +87,9 @@ function resolveClearCacheFilename(specifier, parentPath) {
     return null;
   }
 
-  const parsedURL = getURLFromClearCacheSpecifier(specifier);
-  let request = specifier;
-  if (parsedURL) {
-    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;
-    }
-  }
-
   const parent = parentPath ? createParentModuleForClearCache(parentPath) : null;
   try {
-    const { filename, format } = resolveForCJSWithHooks(request, parent, false, false);
+    const { filename, format } = resolveForCJSWithHooks(specifier, parent, false, false);
     if (format === 'builtin') {
       return null;
     }
@@ -314,10 +284,13 @@ function clearCache(specifier, options) {
     }
 
     // CJS has relativeResolveCache and Module._pathCache that map
-    // specifiers to filenames. Clear entries pointing to the resolved file.
-    if (resolvedFilename) {
-      clearCJSResolutionCaches(resolvedFilename);
+    // specifiers to filenames. Only clear the exact entry for this request.
+    if (resolver === 'require') {
+      const request = isSpecifierURL ? specifier.href : specifier;
+      delete relativeResolveCache[`${parentPath}\x00${request}`];
+    }
 
+    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 } =