From 1d0acccc801da8fbd2a18f733861ca9444bae685 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 10 Feb 2026 13:14:09 -0800
Subject: [PATCH 1/7] module: add clearCache for CJS and ESM

---
 doc/api/module.md                          |  45 +++++
 lib/internal/modules/cjs/loader.js         | 196 ++++++++++++++++++++-
 lib/internal/modules/esm/module_map.js     |  10 ++
 test/es-module/test-module-clear-cache.mjs |  22 +++
 test/fixtures/module-cache/cjs-counter.js  |   5 +
 test/fixtures/module-cache/esm-counter.mjs |   4 +
 test/parallel/test-module-clear-cache.js   |  25 +++
 7 files changed, 305 insertions(+), 2 deletions(-)
 create mode 100644 test/es-module/test-module-clear-cache.mjs
 create mode 100644 test/fixtures/module-cache/cjs-counter.js
 create mode 100644 test/fixtures/module-cache/esm-counter.mjs
 create mode 100644 test/parallel/test-module-clear-cache.js

diff --git a/doc/api/module.md b/doc/api/module.md
index 81e49882def0bf..99a5658939d463 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -66,6 +66,51 @@ const require = createRequire(import.meta.url);
 const siblingModule = require('./sibling-module');
 ```
 
+### `module.clearCache(specifier[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active development
+
+* `specifier` {string|URL} The module specifier or URL to clear.
+* `options` {Object}
+  * `mode` {string} Which caches to clear. Supported values are `'all'`, `'cjs'`, and `'esm'`.
+    **Default:** `'all'`.
+  * `parentURL` {string|URL} The parent URL or absolute path used to resolve non-URL specifiers.
+    For CommonJS, pass `__filename`. For ES modules, pass `import.meta.url`.
+  * `type` {string} Import attributes `type` used for ESM resolution.
+  * `importAttributes` {Object} Import attributes for ESM resolution. Cannot be used with `type`.
+* Returns: {Object} An object with `{ cjs: boolean, esm: boolean }` indicating whether entries
+  were removed from each cache.
+
+Clears the CommonJS `require` cache and/or the ESM module cache for a module. This enables
+reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR.
+When `mode` is `'all'`, resolution failures for one module system do not throw; check the
+returned flags to see what was cleared.
+
+```mjs
+import { clearCache } from 'node:module';
+
+const url = new URL('./mod.mjs', import.meta.url);
+await import(url.href);
+
+clearCache(url);
+await import(url.href); // re-executes the module
+```
+
+```cjs
+const { clearCache } = require('node:module');
+const path = require('node:path');
+
+const file = path.join(__dirname, 'mod.js');
+require(file);
+
+clearCache(file);
+require(file); // re-executes the module
+```
+
 ### `module.findPackageJSON(specifier[, base])`
 
 <!-- YAML
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index 6a841a2f72f485..7d56da1a3d08e1 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -135,7 +135,7 @@ const { BuiltinModule } = require('internal/bootstrap/realm');
 const {
   maybeCacheSourceMap,
 } = require('internal/source_map/source_map_cache');
-const { pathToFileURL, fileURLToPath, isURL, URL } = require('internal/url');
+const { pathToFileURL, fileURLToPath, isURL, URL, URLParse } = require('internal/url');
 const {
   pendingDeprecate,
   emitExperimentalWarning,
@@ -200,7 +200,11 @@ const {
   },
   setArrowMessage,
 } = require('internal/errors');
-const { validateString } = require('internal/validators');
+const {
+  validateObject,
+  validateOneOf,
+  validateString,
+} = require('internal/validators');
 
 const {
   CHAR_BACKWARD_SLASH,
@@ -2028,6 +2032,193 @@ function createRequire(filenameOrURL) {
   return createRequireFromPath(filepath, fileURL);
 }
 
+/**
+ * Normalize the parent URL/path for cache clearing.
+ * @param {string|URL|undefined} parentURL
+ * @returns {{ parentURL: string|undefined, parentPath: string|undefined }}
+ */
+function normalizeClearCacheParent(parentURL) {
+  if (parentURL === undefined) {
+    return { __proto__: null, parentURL: undefined, parentPath: undefined };
+  }
+
+  if (isURL(parentURL)) {
+    const parentPath =
+      parentURL.protocol === 'file:' && parentURL.search === '' && parentURL.hash === '' ?
+        fileURLToPath(parentURL) :
+        undefined;
+    return { __proto__: null, parentURL: parentURL.href, parentPath };
+  }
+
+  validateString(parentURL, 'options.parentURL');
+  if (path.isAbsolute(parentURL)) {
+    return {
+      __proto__: null,
+      parentURL: pathToFileURL(parentURL).href,
+      parentPath: parentURL,
+    };
+  }
+
+  const url = URLParse(parentURL);
+  if (!url) {
+    throw new ERR_INVALID_ARG_VALUE('options.parentURL', parentURL,
+                                    'must be an absolute path or URL');
+  }
+
+  const parentPath =
+    url.protocol === 'file:' && url.search === '' && url.hash === '' ?
+      fileURLToPath(url) :
+      undefined;
+  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
+ * @returns {Module}
+ */
+function createParentModuleForClearCache(parentPath) {
+  const parent = new Module(parentPath);
+  parent.filename = parentPath;
+  parent.paths = Module._nodeModulePaths(path.dirname(parentPath));
+  return parent;
+}
+
+/**
+ * Resolve a cache filename for CommonJS.
+ * @param {string|URL} specifier
+ * @param {string|undefined} parentPath
+ * @returns {string|null}
+ */
+function resolveClearCacheFilename(specifier, parentPath) {
+  if (!parentPath && typeof specifier === 'string' && isRelative(specifier)) {
+    return null;
+  }
+
+  const parsedURL = getURLFromClearCacheSpecifier(specifier);
+  let request = specifier;
+  if (parsedURL) {
+    if (parsedURL.protocol !== 'file:' || parsedURL.search !== '' || parsedURL.hash !== '') {
+      return null;
+    }
+    request = fileURLToPath(parsedURL);
+  }
+
+  const parent = parentPath ? createParentModuleForClearCache(parentPath) : null;
+  return Module._resolveFilename(request, parent, false);
+}
+
+/**
+ * Resolve a cache URL for ESM.
+ * @param {string|URL} specifier
+ * @param {string|undefined} parentURL
+ * @param {Record<string, string>|undefined} importAttributes
+ * @returns {string}
+ */
+function resolveClearCacheURL(specifier, parentURL, importAttributes) {
+  const parsedURL = getURLFromClearCacheSpecifier(specifier);
+  if (parsedURL) {
+    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, attributes: importAttributes, __proto__: null };
+  return cascadedLoader.resolveSync(parentURL, request).url;
+}
+
+/**
+ * Clear CommonJS and/or ESM module cache entries.
+ * @param {string|URL} specifier
+ * @param {object} [options]
+ * @param {'all'|'cjs'|'esm'} [options.mode]
+ * @param {string|URL} [options.parentURL]
+ * @param {string} [options.type]
+ * @param {Record<string, string>} [options.importAttributes]
+ * @returns {{ cjs: boolean, esm: boolean }}
+ */
+function clearCache(specifier, options = kEmptyObject) {
+  const isSpecifierURL = isURL(specifier);
+  if (!isSpecifierURL) {
+    validateString(specifier, 'specifier');
+  }
+
+  validateObject(options, 'options');
+  const mode = options.mode === undefined ? 'all' : options.mode;
+  validateOneOf(mode, 'options.mode', ['all', 'cjs', 'esm']);
+
+  if (options.importAttributes !== undefined && options.type !== undefined) {
+    throw new ERR_INVALID_ARG_VALUE('options.importAttributes', options.importAttributes,
+                                    'cannot be used with options.type');
+  }
+
+  let importAttributes = options.importAttributes;
+  if (options.type !== undefined) {
+    validateString(options.type, 'options.type');
+    importAttributes = { __proto__: null, type: options.type };
+  } else if (importAttributes !== undefined) {
+    validateObject(importAttributes, 'options.importAttributes');
+  }
+
+  const { parentURL, parentPath } = normalizeClearCacheParent(options.parentURL);
+  const result = { __proto__: null, cjs: false, esm: false };
+
+  if (mode !== 'esm') {
+    try {
+      const filename = resolveClearCacheFilename(specifier, parentPath);
+      if (filename && Module._cache[filename] !== undefined) {
+        delete Module._cache[filename];
+        result.cjs = true;
+      }
+    } catch (err) {
+      if (mode === 'cjs') {
+        throw err;
+      }
+    }
+  }
+
+  if (mode !== 'cjs') {
+    try {
+      const url = resolveClearCacheURL(specifier, parentURL, importAttributes);
+      const cascadedLoader =
+        require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+      result.esm = cascadedLoader.loadCache.deleteAll(url);
+    } catch (err) {
+      if (mode === 'esm') {
+        throw err;
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Checks if a path is relative
  * @param {string} path the target path
@@ -2044,6 +2235,7 @@ function isRelative(path) {
 }
 
 Module.createRequire = createRequire;
+Module.clearCache = clearCache;
 
 /**
  * Define the paths to use for resolving a module.
diff --git a/lib/internal/modules/esm/module_map.js b/lib/internal/modules/esm/module_map.js
index 207515573c79c5..e3803ae0f9d33f 100644
--- a/lib/internal/modules/esm/module_map.js
+++ b/lib/internal/modules/esm/module_map.js
@@ -123,6 +123,16 @@ class LoadCache extends SafeMap {
       cached[type] = undefined;
     }
   }
+
+  /**
+   * Delete all cached module jobs for a URL.
+   * @param {string} url
+   * @returns {boolean} true if an entry was deleted.
+   */
+  deleteAll(url) {
+    validateString(url, 'url');
+    return super.delete(url);
+  }
 }
 
 module.exports = {
diff --git a/test/es-module/test-module-clear-cache.mjs b/test/es-module/test-module-clear-cache.mjs
new file mode 100644
index 00000000000000..d25aa349f2f0bd
--- /dev/null
+++ b/test/es-module/test-module-clear-cache.mjs
@@ -0,0 +1,22 @@
+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);
+const second = await import(specifier);
+
+assert.strictEqual(first.count, 1);
+assert.strictEqual(second.count, 1);
+assert.strictEqual(first, second);
+
+const result = clearCache(specifier, { parentURL: import.meta.url });
+assert.strictEqual(result.cjs, false);
+assert.strictEqual(result.esm, true);
+
+const third = await import(specifier);
+assert.strictEqual(third.count, 2);
+
+delete globalThis.__module_cache_esm_counter;
diff --git a/test/fixtures/module-cache/cjs-counter.js b/test/fixtures/module-cache/cjs-counter.js
new file mode 100644
index 00000000000000..bc8662960b767b
--- /dev/null
+++ b/test/fixtures/module-cache/cjs-counter.js
@@ -0,0 +1,5 @@
+globalThis.__module_cache_cjs_counter = (globalThis.__module_cache_cjs_counter ?? 0) + 1;
+
+module.exports = {
+  count: globalThis.__module_cache_cjs_counter,
+};
diff --git a/test/fixtures/module-cache/esm-counter.mjs b/test/fixtures/module-cache/esm-counter.mjs
new file mode 100644
index 00000000000000..d3b0c9eae58102
--- /dev/null
+++ b/test/fixtures/module-cache/esm-counter.mjs
@@ -0,0 +1,4 @@
+globalThis.__module_cache_esm_counter = (globalThis.__module_cache_esm_counter ?? 0) + 1;
+
+export const count = globalThis.__module_cache_esm_counter;
+export default count;
diff --git a/test/parallel/test-module-clear-cache.js b/test/parallel/test-module-clear-cache.js
new file mode 100644
index 00000000000000..956b349de9351f
--- /dev/null
+++ b/test/parallel/test-module-clear-cache.js
@@ -0,0 +1,25 @@
+'use strict';
+
+require('../common');
+
+const assert = require('node:assert');
+const path = require('node:path');
+const { clearCache } = require('node:module');
+
+const fixture = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-counter.js');
+
+const first = require(fixture);
+const second = require(fixture);
+
+assert.strictEqual(first.count, 1);
+assert.strictEqual(second.count, 1);
+assert.strictEqual(first, second);
+
+const result = clearCache(fixture);
+assert.strictEqual(result.cjs, true);
+assert.strictEqual(result.esm, false);
+
+const third = require(fixture);
+assert.strictEqual(third.count, 2);
+
+delete globalThis.__module_cache_cjs_counter;

From b3bd79aee4847f21b94a6424ce7b5381c6d7dba8 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 10 Feb 2026 14:03:17 -0800
Subject: [PATCH 2/7] fixup! module: add clearCache for CJS and ESM

---
 doc/api/module.md                           |  1 +
 lib/internal/modules/cjs/loader.js          | 57 +++++++++++++++++++--
 lib/internal/modules/esm/loader.js          |  9 ++++
 lib/internal/modules/esm/module_map.js      | 25 +++++++++
 test/es-module/test-module-clear-cache.mjs  | 12 +++++
 test/fixtures/module-cache/esm-nested-a.mjs |  3 ++
 test/fixtures/module-cache/esm-nested-b.mjs |  3 ++
 test/fixtures/module-cache/esm-nested-c.mjs |  4 ++
 8 files changed, 110 insertions(+), 4 deletions(-)
 create mode 100644 test/fixtures/module-cache/esm-nested-a.mjs
 create mode 100644 test/fixtures/module-cache/esm-nested-b.mjs
 create mode 100644 test/fixtures/module-cache/esm-nested-c.mjs

diff --git a/doc/api/module.md b/doc/api/module.md
index 99a5658939d463..3a0fdadebef084 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -89,6 +89,7 @@ Clears the CommonJS `require` cache and/or the ESM module cache for a module. Th
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR.
 When `mode` is `'all'`, resolution failures for one module system do not throw; check the
 returned flags to see what was cleared.
+This also clears internal resolution caches for the resolved module.
 
 ```mjs
 import { clearCache } from 'node:module';
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index 7d56da1a3d08e1..75de88cee9edc1 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -2153,6 +2153,43 @@ function resolveClearCacheURL(specifier, parentURL, importAttributes) {
   return cascadedLoader.resolveSync(parentURL, request).url;
 }
 
+/**
+ * Remove path cache entries that resolve to a filename.
+ * @param {string} filename
+ * @returns {boolean} true if any entries were deleted.
+ */
+function deletePathCacheEntries(filename) {
+  const cache = Module._pathCache;
+  const keys = ObjectKeys(cache);
+  let deleted = false;
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (cache[key] === filename) {
+      delete cache[key];
+      deleted = true;
+    }
+  }
+  return deleted;
+}
+
+/**
+ * Remove relative resolve cache entries that resolve to a filename.
+ * @param {string} filename
+ * @returns {boolean} true if any entries were deleted.
+ */
+function deleteRelativeResolveCacheEntries(filename) {
+  const keys = ObjectKeys(relativeResolveCache);
+  let deleted = false;
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (relativeResolveCache[key] === filename) {
+      delete relativeResolveCache[key];
+      deleted = true;
+    }
+  }
+  return deleted;
+}
+
 /**
  * Clear CommonJS and/or ESM module cache entries.
  * @param {string|URL} specifier
@@ -2192,9 +2229,19 @@ function clearCache(specifier, options = kEmptyObject) {
   if (mode !== 'esm') {
     try {
       const filename = resolveClearCacheFilename(specifier, parentPath);
-      if (filename && Module._cache[filename] !== undefined) {
-        delete Module._cache[filename];
-        result.cjs = true;
+      if (filename) {
+        let deleted = false;
+        if (Module._cache[filename] !== undefined) {
+          delete Module._cache[filename];
+          deleted = true;
+        }
+        if (deletePathCacheEntries(filename)) {
+          deleted = true;
+        }
+        if (deleteRelativeResolveCacheEntries(filename)) {
+          deleted = true;
+        }
+        result.cjs = deleted;
       }
     } catch (err) {
       if (mode === 'cjs') {
@@ -2208,7 +2255,9 @@ function clearCache(specifier, options = kEmptyObject) {
       const url = resolveClearCacheURL(specifier, parentURL, importAttributes);
       const cascadedLoader =
         require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-      result.esm = cascadedLoader.loadCache.deleteAll(url);
+      const loadDeleted = cascadedLoader.loadCache.deleteAll(url);
+      const resolveDeleted = cascadedLoader.deleteResolveCache(url);
+      result.esm = loadDeleted || resolveDeleted;
     } catch (err) {
       if (mode === 'esm') {
         throw err;
diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 41513d1b9f3658..c367581f688876 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -181,6 +181,15 @@ class ModuleLoader {
    */
   loadCache = newLoadCache();
 
+  /**
+   * Delete cached resolutions that resolve to a URL.
+   * @param {string} url
+   * @returns {boolean} true if any entries were deleted.
+   */
+  deleteResolveCache(url) {
+    return this.#resolveCache.deleteByResolvedURL(url);
+  }
+
   /**
    * Methods which translate input code or other information into ES modules
    */
diff --git a/lib/internal/modules/esm/module_map.js b/lib/internal/modules/esm/module_map.js
index e3803ae0f9d33f..259a618bfcb53e 100644
--- a/lib/internal/modules/esm/module_map.js
+++ b/lib/internal/modules/esm/module_map.js
@@ -85,6 +85,31 @@ class ResolveCache extends SafeMap {
   has(serializedKey, parentURL) {
     return serializedKey in this.#getModuleCachedImports(parentURL);
   }
+
+  /**
+   * Delete cached resolutions that resolve to a URL.
+   * @param {string} url
+   * @returns {boolean} true if any entries were deleted.
+   */
+  deleteByResolvedURL(url) {
+    validateString(url, 'url');
+    let deleted = false;
+    for (const [parentURL, entries] of this) {
+      const keys = ObjectKeys(entries);
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (entries[key]?.url === url) {
+          delete entries[key];
+          deleted = true;
+        }
+      }
+
+      if (ObjectKeys(entries).length === 0) {
+        super.delete(parentURL);
+      }
+    }
+    return deleted;
+  }
 }
 
 /**
diff --git a/test/es-module/test-module-clear-cache.mjs b/test/es-module/test-module-clear-cache.mjs
index d25aa349f2f0bd..c2072086d31f3e 100644
--- a/test/es-module/test-module-clear-cache.mjs
+++ b/test/es-module/test-module-clear-cache.mjs
@@ -19,4 +19,16 @@ assert.strictEqual(result.esm, true);
 const third = await import(specifier);
 assert.strictEqual(third.count, 2);
 
+const nested = new URL('../fixtures/module-cache/esm-nested-a.mjs', import.meta.url);
+const nestedFirst = await import(`${nested.href}?v=1`);
+assert.strictEqual(nestedFirst.value, 1);
+
+const nestedResult = clearCache(new URL('../fixtures/module-cache/esm-nested-b.mjs', import.meta.url));
+assert.strictEqual(nestedResult.cjs, false);
+assert.strictEqual(nestedResult.esm, true);
+
+const nestedSecond = await import(`${nested.href}?v=2`);
+assert.strictEqual(nestedSecond.value, 2);
+
 delete globalThis.__module_cache_esm_counter;
+delete globalThis.__module_cache_esm_nested_c_counter;
diff --git a/test/fixtures/module-cache/esm-nested-a.mjs b/test/fixtures/module-cache/esm-nested-a.mjs
new file mode 100644
index 00000000000000..57195b0cc16483
--- /dev/null
+++ b/test/fixtures/module-cache/esm-nested-a.mjs
@@ -0,0 +1,3 @@
+import { value } from './esm-nested-b.mjs';
+
+export { value };
diff --git a/test/fixtures/module-cache/esm-nested-b.mjs b/test/fixtures/module-cache/esm-nested-b.mjs
new file mode 100644
index 00000000000000..d10a97640673dc
--- /dev/null
+++ b/test/fixtures/module-cache/esm-nested-b.mjs
@@ -0,0 +1,3 @@
+import { count } from './esm-nested-c.mjs';
+
+export const value = count;
diff --git a/test/fixtures/module-cache/esm-nested-c.mjs b/test/fixtures/module-cache/esm-nested-c.mjs
new file mode 100644
index 00000000000000..bd64feebd5269c
--- /dev/null
+++ b/test/fixtures/module-cache/esm-nested-c.mjs
@@ -0,0 +1,4 @@
+globalThis.__module_cache_esm_nested_c_counter =
+  (globalThis.__module_cache_esm_nested_c_counter ?? 0) + 1;
+
+export const count = globalThis.__module_cache_esm_nested_c_counter;

From 05073087a215df59b4f1b7a43ed7ae69e81b3c8b Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 10 Feb 2026 14:16:50 -0800
Subject: [PATCH 3/7] fixup! module: add clearCache for CJS and ESM

---
 lib/internal/modules/esm/module_map.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/internal/modules/esm/module_map.js b/lib/internal/modules/esm/module_map.js
index 259a618bfcb53e..f54b01a6126d37 100644
--- a/lib/internal/modules/esm/module_map.js
+++ b/lib/internal/modules/esm/module_map.js
@@ -94,7 +94,9 @@ class ResolveCache extends SafeMap {
   deleteByResolvedURL(url) {
     validateString(url, 'url');
     let deleted = false;
-    for (const [parentURL, entries] of this) {
+    for (const entry of this) {
+      const parentURL = entry[0];
+      const entries = entry[1];
       const keys = ObjectKeys(entries);
       for (let i = 0; i < keys.length; i++) {
         const key = keys[i];

From ba8ffaa3076a5af366cff67adb7f09ab6bf29482 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 11 Feb 2026 10:46:43 -0800
Subject: [PATCH 4/7] fixup! module: add clearCache for CJS and ESM

---
 doc/api/module.md                             |  16 +-
 lib/internal/modules/cjs/loader.js            | 167 +++++++++++++-----
 lib/internal/modules/esm/loader.js            |  58 +++++-
 lib/internal/modules/esm/module_map.js        |  24 +++
 ...test-module-clear-cache-query-variants.mjs |  20 +++
 test/es-module/test-module-clear-cache.mjs    |  10 +-
 test/fixtures/module-cache/cjs-child.js       |   6 +
 test/fixtures/module-cache/cjs-parent.js      |   5 +
 test/fixtures/module-cache/esm-nested-b.mjs   |   7 +-
 .../module-cache/esm-query-counter.mjs        |   4 +
 .../test-module-hooks-clear-cache.js          |  51 ++++++
 .../test-module-clear-cache-children.js       |  28 +++
 .../test-module-clear-cache-options.js        |  38 ++++
 test/parallel/test-module-clear-cache.js      |   4 +-
 14 files changed, 382 insertions(+), 56 deletions(-)
 create mode 100644 test/es-module/test-module-clear-cache-query-variants.mjs
 create mode 100644 test/fixtures/module-cache/cjs-child.js
 create mode 100644 test/fixtures/module-cache/cjs-parent.js
 create mode 100644 test/fixtures/module-cache/esm-query-counter.mjs
 create mode 100644 test/module-hooks/test-module-hooks-clear-cache.js
 create mode 100644 test/parallel/test-module-clear-cache-children.js
 create mode 100644 test/parallel/test-module-clear-cache-options.js

diff --git a/doc/api/module.md b/doc/api/module.md
index 3a0fdadebef084..0842ee500cc71a 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -76,20 +76,22 @@ added: REPLACEME
 
 * `specifier` {string|URL} The module specifier or URL to clear.
 * `options` {Object}
-  * `mode` {string} Which caches to clear. Supported values are `'all'`, `'cjs'`, and `'esm'`.
+  * `mode` {string} Which caches to clear. Supported values are `'all'`, `'commonjs'`, and `'module'`.
     **Default:** `'all'`.
-  * `parentURL` {string|URL} The parent URL or absolute path used to resolve non-URL specifiers.
-    For CommonJS, pass `__filename`. For ES modules, pass `import.meta.url`.
-  * `type` {string} Import attributes `type` used for ESM resolution.
-  * `importAttributes` {Object} Import attributes for ESM resolution. Cannot be used with `type`.
-* Returns: {Object} An object with `{ cjs: boolean, esm: boolean }` indicating whether entries
+  * `parentURL` {string|URL} The parent URL used to resolve non-URL specifiers.
+    For CommonJS, pass `pathToFileURL(__filename)`. For ES modules, pass `import.meta.url`.
+  * `importAttributes` {Object} Import attributes for ESM resolution.
+* Returns: {Object} An object with `{ commonjs: boolean, module: boolean }` indicating whether entries
   were removed from each cache.
 
 Clears the CommonJS `require` cache and/or the ESM module cache for a module. This enables
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR.
 When `mode` is `'all'`, resolution failures for one module system do not throw; check the
 returned flags to see what was cleared.
-This also clears internal resolution caches for the resolved module.
+This also clears internal resolution caches for the resolved module. Clearing a module does
+not clear cached entries for its dependencies.
+When a `file:` URL is resolved, cached module jobs for the same file path are cleared even if
+they differ by search or hash.
 
 ```mjs
 import { clearCache } from 'node:module';
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index 75de88cee9edc1..5b00cfc37d08b8 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -2033,7 +2033,7 @@ function createRequire(filenameOrURL) {
 }
 
 /**
- * Normalize the parent URL/path for cache clearing.
+ * Normalize the parent URL for cache clearing.
  * @param {string|URL|undefined} parentURL
  * @returns {{ parentURL: string|undefined, parentPath: string|undefined }}
  */
@@ -2051,18 +2051,10 @@ function normalizeClearCacheParent(parentURL) {
   }
 
   validateString(parentURL, 'options.parentURL');
-  if (path.isAbsolute(parentURL)) {
-    return {
-      __proto__: null,
-      parentURL: pathToFileURL(parentURL).href,
-      parentPath: parentURL,
-    };
-  }
-
   const url = URLParse(parentURL);
   if (!url) {
     throw new ERR_INVALID_ARG_VALUE('options.parentURL', parentURL,
-                                    'must be an absolute path or URL');
+                                    'must be a URL');
   }
 
   const parentPath =
@@ -2122,7 +2114,11 @@ function resolveClearCacheFilename(specifier, parentPath) {
   }
 
   const parent = parentPath ? createParentModuleForClearCache(parentPath) : null;
-  return Module._resolveFilename(request, parent, false);
+  const { filename, format } = resolveForCJSWithHooks(request, parent, false, false);
+  if (format === 'builtin') {
+    return null;
+  }
+  return filename;
 }
 
 /**
@@ -2156,17 +2152,20 @@ function resolveClearCacheURL(specifier, parentURL, importAttributes) {
 /**
  * Remove path cache entries that resolve to a filename.
  * @param {string} filename
+ * @param {Set<string>|null} [existingKeys]
  * @returns {boolean} true if any entries were deleted.
  */
-function deletePathCacheEntries(filename) {
+function deletePathCacheEntries(filename, existingKeys = null) {
   const cache = Module._pathCache;
   const keys = ObjectKeys(cache);
   let deleted = false;
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     if (cache[key] === filename) {
+      if (existingKeys === null || existingKeys.has(key)) {
+        deleted = true;
+      }
       delete cache[key];
-      deleted = true;
     }
   }
   return deleted;
@@ -2175,91 +2174,179 @@ function deletePathCacheEntries(filename) {
 /**
  * Remove relative resolve cache entries that resolve to a filename.
  * @param {string} filename
+ * @param {Set<string>|null} [existingKeys]
  * @returns {boolean} true if any entries were deleted.
  */
-function deleteRelativeResolveCacheEntries(filename) {
+function deleteRelativeResolveCacheEntries(filename, existingKeys = null) {
   const keys = ObjectKeys(relativeResolveCache);
   let deleted = false;
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     if (relativeResolveCache[key] === filename) {
+      if (existingKeys === null || existingKeys.has(key)) {
+        deleted = true;
+      }
       delete relativeResolveCache[key];
+    }
+  }
+  return deleted;
+}
+
+/**
+ * Remove cached module references from parent children arrays.
+ * @param {Module} targetModule
+ * @returns {boolean} true if any references were removed.
+ */
+function deleteModuleFromParents(targetModule) {
+  const keys = ObjectKeys(Module._cache);
+  let deleted = false;
+  for (let i = 0; i < keys.length; i++) {
+    const cachedModule = Module._cache[keys[i]];
+    const children = cachedModule?.children;
+    if (!ArrayIsArray(children)) {
+      continue;
+    }
+    const index = ArrayPrototypeIndexOf(children, targetModule);
+    if (index !== -1) {
+      ArrayPrototypeSplice(children, index, 1);
       deleted = true;
     }
   }
   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 || 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
+ * @param {string} url
+ * @returns {boolean} true if any entries were deleted.
+ */
+function deleteLoadCacheEntries(loadCache, url) {
+  let deleted = loadCache.deleteAll(url);
+  const filename = getFilePathFromClearCacheURL(url);
+  if (!filename) {
+    return deleted;
+  }
+
+  const urls = [];
+  for (const entry of loadCache) {
+    ArrayPrototypePush(urls, entry[0]);
+  }
+
+  for (let i = 0; i < urls.length; i++) {
+    const cachedURL = urls[i];
+    if (cachedURL === url) {
+      continue;
+    }
+    const cachedFilename = getFilePathFromClearCacheURL(cachedURL);
+    if (cachedFilename === filename) {
+      loadCache.deleteAll(cachedURL);
+      deleted = true;
+    }
+  }
+
+  return deleted;
+}
+
 /**
  * Clear CommonJS and/or ESM module cache entries.
  * @param {string|URL} specifier
  * @param {object} [options]
- * @param {'all'|'cjs'|'esm'} [options.mode]
+ * @param {'all'|'commonjs'|'module'} [options.mode]
  * @param {string|URL} [options.parentURL]
- * @param {string} [options.type]
  * @param {Record<string, string>} [options.importAttributes]
- * @returns {{ cjs: boolean, esm: boolean }}
+ * @returns {{ commonjs: boolean, module: boolean }}
  */
 function clearCache(specifier, options = kEmptyObject) {
   const isSpecifierURL = isURL(specifier);
   if (!isSpecifierURL) {
     validateString(specifier, 'specifier');
   }
+  const specifierKey = isSpecifierURL ? specifier.href : specifier;
 
   validateObject(options, 'options');
   const mode = options.mode === undefined ? 'all' : options.mode;
-  validateOneOf(mode, 'options.mode', ['all', 'cjs', 'esm']);
-
-  if (options.importAttributes !== undefined && options.type !== undefined) {
-    throw new ERR_INVALID_ARG_VALUE('options.importAttributes', options.importAttributes,
-                                    'cannot be used with options.type');
-  }
+  validateOneOf(mode, 'options.mode', ['all', 'commonjs', 'module']);
 
-  let importAttributes = options.importAttributes;
-  if (options.type !== undefined) {
-    validateString(options.type, 'options.type');
-    importAttributes = { __proto__: null, type: options.type };
-  } else if (importAttributes !== undefined) {
+  const importAttributes = options.importAttributes;
+  if (importAttributes !== undefined) {
     validateObject(importAttributes, 'options.importAttributes');
   }
 
   const { parentURL, parentPath } = normalizeClearCacheParent(options.parentURL);
-  const result = { __proto__: null, cjs: false, esm: false };
+  const result = { __proto__: null, commonjs: false, module: false };
 
-  if (mode !== 'esm') {
+  if (mode !== 'module') {
+    const pathCacheKeys = new SafeSet(ObjectKeys(Module._pathCache));
+    const relativeResolveCacheKeys = new SafeSet(ObjectKeys(relativeResolveCache));
     try {
       const filename = resolveClearCacheFilename(specifier, parentPath);
       if (filename) {
         let deleted = false;
-        if (Module._cache[filename] !== undefined) {
+        const cachedModule = Module._cache[filename];
+        if (cachedModule !== undefined) {
           delete Module._cache[filename];
           deleted = true;
+          if (deleteModuleFromParents(cachedModule)) {
+            deleted = true;
+          }
         }
-        if (deletePathCacheEntries(filename)) {
+        if (deletePathCacheEntries(filename, pathCacheKeys)) {
           deleted = true;
         }
-        if (deleteRelativeResolveCacheEntries(filename)) {
+        if (deleteRelativeResolveCacheEntries(filename, relativeResolveCacheKeys)) {
           deleted = true;
         }
-        result.cjs = deleted;
+        result.commonjs = deleted;
       }
     } catch (err) {
-      if (mode === 'cjs') {
+      if (mode === 'commonjs') {
         throw err;
       }
     }
   }
 
-  if (mode !== 'cjs') {
+  if (mode !== 'commonjs') {
     try {
       const url = resolveClearCacheURL(specifier, parentURL, importAttributes);
       const cascadedLoader =
         require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-      const loadDeleted = cascadedLoader.loadCache.deleteAll(url);
-      const resolveDeleted = cascadedLoader.deleteResolveCache(url);
-      result.esm = loadDeleted || resolveDeleted;
+      const loadDeleted = deleteLoadCacheEntries(cascadedLoader.loadCache, url);
+      let resolveDeleted = cascadedLoader.deleteResolveCacheEntry(
+        specifierKey,
+        parentURL,
+        importAttributes ?? kEmptyObject,
+      );
+      const resolvedPath = getFilePathFromClearCacheURL(url);
+      if (resolvedPath) {
+        resolveDeleted = cascadedLoader.deleteResolveCacheByFilename(resolvedPath) || resolveDeleted;
+      }
+      result.module = loadDeleted || resolveDeleted;
     } catch (err) {
-      if (mode === 'esm') {
+      if (mode === 'module') {
         throw err;
       }
     }
diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index c367581f688876..1911ee89a45850 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -6,6 +6,7 @@ const {
   ArrayPrototypeReduce,
   FunctionPrototypeCall,
   JSONStringify,
+  ObjectKeys,
   ObjectSetPrototypeOf,
   Promise,
   PromisePrototypeThen,
@@ -30,7 +31,7 @@ const {
   ERR_UNKNOWN_MODULE_FORMAT,
 } = require('internal/errors').codes;
 const { getOptionValue } = require('internal/options');
-const { isURL, pathToFileURL } = require('internal/url');
+const { isURL, pathToFileURL, fileURLToPath, URLParse } = require('internal/url');
 const { kEmptyObject } = require('internal/util');
 const {
   compileSourceTextModule,
@@ -190,6 +191,61 @@ class ModuleLoader {
     return this.#resolveCache.deleteByResolvedURL(url);
   }
 
+  /**
+   * Delete cached resolution for a specific request.
+   * @param {string} specifier
+   * @param {string|undefined} parentURL
+   * @param {Record<string, string>} importAttributes
+   * @returns {boolean} true if any entries were deleted.
+   */
+  deleteResolveCacheEntry(specifier, parentURL, importAttributes) {
+    return this.#resolveCache.deleteBySpecifier(specifier, parentURL, importAttributes);
+  }
+
+  /**
+   * Delete cached resolutions that resolve to a file path.
+   * @param {string} filename
+   * @returns {boolean} true if any entries were deleted.
+   */
+  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;
+  }
+
   /**
    * Methods which translate input code or other information into ES modules
    */
diff --git a/lib/internal/modules/esm/module_map.js b/lib/internal/modules/esm/module_map.js
index f54b01a6126d37..29e21720502175 100644
--- a/lib/internal/modules/esm/module_map.js
+++ b/lib/internal/modules/esm/module_map.js
@@ -6,6 +6,7 @@ const {
   ArrayPrototypeSort,
   JSONStringify,
   ObjectKeys,
+  ObjectPrototypeHasOwnProperty,
   SafeMap,
 } = primordials;
 const { kImplicitTypeAttribute } = require('internal/modules/esm/assert');
@@ -112,6 +113,29 @@ class ResolveCache extends SafeMap {
     }
     return deleted;
   }
+
+  /**
+   * Delete a cached resolution for a specifier in a parent URL.
+   * @param {string} specifier
+   * @param {string|undefined} parentURL
+   * @param {Record<string,string>} importAttributes
+   * @returns {boolean} true if an entry was deleted.
+   */
+  deleteBySpecifier(specifier, parentURL, importAttributes) {
+    const entries = super.get(parentURL);
+    if (entries == null) {
+      return false;
+    }
+    const serializedKey = this.serializeKey(specifier, importAttributes);
+    if (!ObjectPrototypeHasOwnProperty(entries, serializedKey)) {
+      return false;
+    }
+    delete entries[serializedKey];
+    if (ObjectKeys(entries).length === 0) {
+      super.delete(parentURL);
+    }
+    return true;
+  }
 }
 
 /**
diff --git a/test/es-module/test-module-clear-cache-query-variants.mjs b/test/es-module/test-module-clear-cache-query-variants.mjs
new file mode 100644
index 00000000000000..5861cac548e8ea
--- /dev/null
+++ b/test/es-module/test-module-clear-cache-query-variants.mjs
@@ -0,0 +1,20 @@
+import '../common/index.mjs';
+
+import assert from 'node:assert';
+import { clearCache } from 'node:module';
+
+const url = new URL('../fixtures/module-cache/esm-query-counter.mjs', import.meta.url);
+
+const first = await import(`${url.href}?v=1`);
+const second = await import(`${url.href}?v=2`);
+assert.strictEqual(first.count, 1);
+assert.strictEqual(second.count, 2);
+
+const result = clearCache(url);
+assert.strictEqual(result.commonjs, false);
+assert.strictEqual(result.module, true);
+
+const third = await import(`${url.href}?v=1`);
+assert.strictEqual(third.count, 3);
+
+delete globalThis.__module_cache_esm_query_counter;
diff --git a/test/es-module/test-module-clear-cache.mjs b/test/es-module/test-module-clear-cache.mjs
index c2072086d31f3e..1215879eab68cf 100644
--- a/test/es-module/test-module-clear-cache.mjs
+++ b/test/es-module/test-module-clear-cache.mjs
@@ -13,8 +13,8 @@ assert.strictEqual(second.count, 1);
 assert.strictEqual(first, second);
 
 const result = clearCache(specifier, { parentURL: import.meta.url });
-assert.strictEqual(result.cjs, false);
-assert.strictEqual(result.esm, true);
+assert.strictEqual(result.commonjs, false);
+assert.strictEqual(result.module, true);
 
 const third = await import(specifier);
 assert.strictEqual(third.count, 2);
@@ -24,11 +24,13 @@ const nestedFirst = await import(`${nested.href}?v=1`);
 assert.strictEqual(nestedFirst.value, 1);
 
 const nestedResult = clearCache(new URL('../fixtures/module-cache/esm-nested-b.mjs', import.meta.url));
-assert.strictEqual(nestedResult.cjs, false);
-assert.strictEqual(nestedResult.esm, true);
+assert.strictEqual(nestedResult.commonjs, false);
+assert.strictEqual(nestedResult.module, true);
 
 const nestedSecond = await import(`${nested.href}?v=2`);
 assert.strictEqual(nestedSecond.value, 2);
+assert.strictEqual(globalThis.__module_cache_esm_nested_c_counter, 1);
 
 delete globalThis.__module_cache_esm_counter;
+delete globalThis.__module_cache_esm_nested_b_counter;
 delete globalThis.__module_cache_esm_nested_c_counter;
diff --git a/test/fixtures/module-cache/cjs-child.js b/test/fixtures/module-cache/cjs-child.js
new file mode 100644
index 00000000000000..1da382d933a9c3
--- /dev/null
+++ b/test/fixtures/module-cache/cjs-child.js
@@ -0,0 +1,6 @@
+globalThis.__module_cache_cjs_child_counter =
+  (globalThis.__module_cache_cjs_child_counter ?? 0) + 1;
+
+module.exports = {
+  count: globalThis.__module_cache_cjs_child_counter,
+};
diff --git a/test/fixtures/module-cache/cjs-parent.js b/test/fixtures/module-cache/cjs-parent.js
new file mode 100644
index 00000000000000..a03a42f9b0e1d9
--- /dev/null
+++ b/test/fixtures/module-cache/cjs-parent.js
@@ -0,0 +1,5 @@
+const child = require('./cjs-child.js');
+
+module.exports = {
+  child,
+};
diff --git a/test/fixtures/module-cache/esm-nested-b.mjs b/test/fixtures/module-cache/esm-nested-b.mjs
index d10a97640673dc..f0210cc2af9291 100644
--- a/test/fixtures/module-cache/esm-nested-b.mjs
+++ b/test/fixtures/module-cache/esm-nested-b.mjs
@@ -1,3 +1,6 @@
-import { count } from './esm-nested-c.mjs';
+import './esm-nested-c.mjs';
 
-export const value = count;
+globalThis.__module_cache_esm_nested_b_counter =
+  (globalThis.__module_cache_esm_nested_b_counter ?? 0) + 1;
+
+export const value = globalThis.__module_cache_esm_nested_b_counter;
diff --git a/test/fixtures/module-cache/esm-query-counter.mjs b/test/fixtures/module-cache/esm-query-counter.mjs
new file mode 100644
index 00000000000000..b5a6a368c2112c
--- /dev/null
+++ b/test/fixtures/module-cache/esm-query-counter.mjs
@@ -0,0 +1,4 @@
+globalThis.__module_cache_esm_query_counter =
+  (globalThis.__module_cache_esm_query_counter ?? 0) + 1;
+
+export const count = globalThis.__module_cache_esm_query_counter;
diff --git a/test/module-hooks/test-module-hooks-clear-cache.js b/test/module-hooks/test-module-hooks-clear-cache.js
new file mode 100644
index 00000000000000..c45cb95f638e42
--- /dev/null
+++ b/test/module-hooks/test-module-hooks-clear-cache.js
@@ -0,0 +1,51 @@
+'use strict';
+
+require('../common');
+
+const assert = require('node:assert');
+const { pathToFileURL } = require('node:url');
+const { clearCache, registerHooks } = require('node:module');
+
+let loadCalls = 0;
+const hook = registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier === 'virtual') {
+      return {
+        url: 'virtual://cache-clear',
+        format: 'commonjs',
+        shortCircuit: true,
+      };
+    }
+    return nextResolve(specifier, context);
+  },
+  load(url, context, nextLoad) {
+    if (url === 'virtual://cache-clear') {
+      loadCalls++;
+      return {
+        format: 'commonjs',
+        source: 'globalThis.__module_cache_virtual_counter = ' +
+          '(globalThis.__module_cache_virtual_counter ?? 0) + 1;' +
+          'module.exports = { count: globalThis.__module_cache_virtual_counter };',
+        shortCircuit: true,
+      };
+    }
+    return nextLoad(url, context);
+  },
+});
+
+const first = require('virtual');
+assert.strictEqual(first.count, 1);
+
+const result = clearCache('virtual', {
+  mode: 'commonjs',
+  parentURL: pathToFileURL(__filename),
+});
+assert.strictEqual(result.commonjs, true);
+assert.strictEqual(result.module, false);
+
+const second = require('virtual');
+assert.strictEqual(second.count, 2);
+assert.strictEqual(loadCalls, 2);
+
+hook.deregister();
+delete globalThis.__module_cache_virtual_counter;
diff --git a/test/parallel/test-module-clear-cache-children.js b/test/parallel/test-module-clear-cache-children.js
new file mode 100644
index 00000000000000..0afb8b64f0ad69
--- /dev/null
+++ b/test/parallel/test-module-clear-cache-children.js
@@ -0,0 +1,28 @@
+'use strict';
+
+require('../common');
+
+const assert = require('node:assert');
+const path = require('node:path');
+const { clearCache } = require('node:module');
+
+const parentPath = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-parent.js');
+const childPath = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-child.js');
+
+const parent = require(parentPath);
+assert.strictEqual(parent.child.count, 1);
+
+const parentModule = require.cache[parentPath];
+assert.ok(parentModule.children.some((child) => child.id === childPath));
+
+const result = clearCache(childPath, { mode: 'commonjs' });
+assert.strictEqual(result.commonjs, true);
+assert.strictEqual(result.module, false);
+
+assert.strictEqual(require.cache[childPath], undefined);
+assert.ok(!parentModule.children.some((child) => child.id === childPath));
+
+const childReloaded = require(childPath);
+assert.strictEqual(childReloaded.count, 2);
+
+delete globalThis.__module_cache_cjs_child_counter;
diff --git a/test/parallel/test-module-clear-cache-options.js b/test/parallel/test-module-clear-cache-options.js
new file mode 100644
index 00000000000000..662544b0fdf105
--- /dev/null
+++ b/test/parallel/test-module-clear-cache-options.js
@@ -0,0 +1,38 @@
+'use strict';
+
+require('../common');
+
+const assert = require('node:assert');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { clearCache } = require('node:module');
+
+const fixture = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-counter.js');
+const relativeSpecifier = '../fixtures/module-cache/cjs-counter.js';
+
+require(fixture);
+
+assert.throws(() => clearCache(fixture, { mode: 'cjs' }), {
+  code: 'ERR_INVALID_ARG_VALUE',
+});
+assert.throws(() => clearCache(fixture, { mode: 'esm' }), {
+  code: 'ERR_INVALID_ARG_VALUE',
+});
+assert.throws(() => clearCache(relativeSpecifier, { parentURL: __filename }), {
+  code: 'ERR_INVALID_ARG_VALUE',
+});
+
+const commonjsResult = clearCache(relativeSpecifier, {
+  mode: 'commonjs',
+  parentURL: pathToFileURL(__filename),
+});
+assert.strictEqual(commonjsResult.commonjs, true);
+
+const first = require(fixture);
+const moduleResult = clearCache(fixture, { mode: 'module' });
+assert.strictEqual(moduleResult.commonjs, false);
+assert.strictEqual(moduleResult.module, false);
+const second = require(fixture);
+assert.strictEqual(first, second);
+
+delete globalThis.__module_cache_cjs_counter;
diff --git a/test/parallel/test-module-clear-cache.js b/test/parallel/test-module-clear-cache.js
index 956b349de9351f..2fb5fbddf5872e 100644
--- a/test/parallel/test-module-clear-cache.js
+++ b/test/parallel/test-module-clear-cache.js
@@ -16,8 +16,8 @@ assert.strictEqual(second.count, 1);
 assert.strictEqual(first, second);
 
 const result = clearCache(fixture);
-assert.strictEqual(result.cjs, true);
-assert.strictEqual(result.esm, false);
+assert.strictEqual(result.commonjs, true);
+assert.strictEqual(result.module, false);
 
 const third = require(fixture);
 assert.strictEqual(third.count, 2);

From af0f7d0750176b9f800830ee408bb8e19fa5b246 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 11 Feb 2026 11:47:50 -0800
Subject: [PATCH 5/7] fixup! module: add clearCache for CJS and ESM

---
 doc/api/module.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index 0842ee500cc71a..7ee43f8847f9bf 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -74,7 +74,9 @@ added: REPLACEME
 
 > Stability: 1.1 - Active development
 
-* `specifier` {string|URL} The module specifier or URL to clear.
+* `specifier` {string|URL} The module specifier or URL to resolve. The resolved URL/filename
+  is cleared from the load cache; the specifier (with `parentURL` and `importAttributes`)
+  is cleared from the resolve cache.
 * `options` {Object}
   * `mode` {string} Which caches to clear. Supported values are `'all'`, `'commonjs'`, and `'module'`.
     **Default:** `'all'`.
@@ -88,8 +90,9 @@ Clears the CommonJS `require` cache and/or the ESM module cache for a module. Th
 reload patterns similar to deleting from `require.cache` in CommonJS, and is useful for HMR.
 When `mode` is `'all'`, resolution failures for one module system do not throw; check the
 returned flags to see what was cleared.
-This also clears internal resolution caches for the resolved module. Clearing a module does
-not clear cached entries for its dependencies.
+This also clears 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.
 

From 83d24024c767f870613b17767679864e43081459 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 11 Feb 2026 12:34:31 -0800
Subject: [PATCH 6/7] fixup! module: add clearCache for CJS and ESM

---
 lib/internal/modules/cjs/loader.js            | 12 +++-
 lib/internal/modules/esm/translators.js       | 64 ++++++++++++++++++-
 ...est-module-clear-cache-import-cjs-race.mjs | 17 +++++
 .../test-module-clear-cache-wasm-leak.mjs     | 26 ++++++++
 .../test-module-clear-cache-wasm.mjs          | 17 +++++
 .../source-map/cjs-closure-source-map.js      |  9 +++
 .../test-module-clear-cache-cjs-cache.js      | 25 ++++++++
 test/parallel/test-module-clear-cache-leak.js | 23 +++++++
 .../test-module-clear-cache-parent-links.js   | 35 ++++++++++
 ...t-module-clear-cache-source-map-closure.js | 29 +++++++++
 10 files changed, 254 insertions(+), 3 deletions(-)
 create mode 100644 test/es-module/test-module-clear-cache-import-cjs-race.mjs
 create mode 100644 test/es-module/test-module-clear-cache-wasm-leak.mjs
 create mode 100644 test/es-module/test-module-clear-cache-wasm.mjs
 create mode 100644 test/fixtures/source-map/cjs-closure-source-map.js
 create mode 100644 test/parallel/test-module-clear-cache-cjs-cache.js
 create mode 100644 test/parallel/test-module-clear-cache-leak.js
 create mode 100644 test/parallel/test-module-clear-cache-parent-links.js
 create mode 100644 test/parallel/test-module-clear-cache-source-map-closure.js

diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index 5b00cfc37d08b8..8cb70fa7143019 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -2202,6 +2202,14 @@ function deleteModuleFromParents(targetModule) {
   let deleted = false;
   for (let i = 0; i < keys.length; i++) {
     const cachedModule = Module._cache[keys[i]];
+    if (cachedModule?.[kFirstModuleParent] === targetModule) {
+      cachedModule[kFirstModuleParent] = undefined;
+      deleted = true;
+    }
+    if (cachedModule?.[kLastModuleParent] === targetModule) {
+      cachedModule[kLastModuleParent] = undefined;
+      deleted = true;
+    }
     const children = cachedModule?.children;
     if (!ArrayIsArray(children)) {
       continue;
@@ -2344,7 +2352,9 @@ function clearCache(specifier, options = kEmptyObject) {
       if (resolvedPath) {
         resolveDeleted = cascadedLoader.deleteResolveCacheByFilename(resolvedPath) || resolveDeleted;
       }
-      result.module = loadDeleted || resolveDeleted;
+      const { clearCjsCache } = require('internal/modules/esm/translators');
+      const cjsCacheDeleted = clearCjsCache(url);
+      result.module = loadDeleted || resolveDeleted || cjsCacheDeleted;
     } catch (err) {
       if (mode === 'module') {
         throw err;
diff --git a/lib/internal/modules/esm/translators.js b/lib/internal/modules/esm/translators.js
index f45defe9dad88a..cdd83dd9b097a7 100644
--- a/lib/internal/modules/esm/translators.js
+++ b/lib/internal/modules/esm/translators.js
@@ -44,7 +44,7 @@ const {
   loadSourceForCJSWithHooks,
   populateCJSExportsFromESM,
 } = require('internal/modules/cjs/loader');
-const { fileURLToPath, pathToFileURL, URL } = require('internal/url');
+const { fileURLToPath, pathToFileURL, URL, URLParse } = require('internal/url');
 let debug = require('internal/util/debuglog').debuglog('esm', (fn) => {
   debug = fn;
 });
@@ -193,6 +193,64 @@ 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);
+  if (!filename) {
+    return deleted;
+  }
+
+  const urls = [];
+  for (const entry of cjsCache) {
+    ArrayPrototypePush(urls, entry[0]);
+  }
+
+  for (let i = 0; i < urls.length; i++) {
+    const cachedURL = urls[i];
+    if (cachedURL === url) {
+      continue;
+    }
+    const cachedFilename = getFilePathFromCjsCacheURL(cachedURL);
+    if (cachedFilename === filename) {
+      cjsCache.delete(cachedURL);
+      deleted = true;
+    }
+  }
+
+  return deleted;
+}
+
+exports.clearCjsCache = clearCjsCache;
+
 /**
  * Creates a ModuleWrap object for a CommonJS module.
  * @param {string} url - The URL of the module.
@@ -323,7 +381,9 @@ translators.set('require-commonjs-typescript', (url, translateContext, parentURL
 
 // This goes through Module._load to accommodate monkey-patchers.
 function loadCJSModuleWithModuleLoad(module, source, url, filename, isMain) {
-  assert(module === CJSModule._cache[filename]);
+  if (CJSModule._cache[filename] !== module) {
+    CJSModule._cache[filename] = module;
+  }
   // If it gets here in the translators, the hooks must have already been invoked
   // in the loader. Skip them in the synthetic module evaluation step.
   wrapModuleLoad(filename, undefined, isMain, kShouldSkipModuleHooks);
diff --git a/test/es-module/test-module-clear-cache-import-cjs-race.mjs b/test/es-module/test-module-clear-cache-import-cjs-race.mjs
new file mode 100644
index 00000000000000..83906899130629
--- /dev/null
+++ b/test/es-module/test-module-clear-cache-import-cjs-race.mjs
@@ -0,0 +1,17 @@
+import '../common/index.mjs';
+import assert from 'node:assert';
+import { clearCache } from 'node:module';
+
+const url = new URL('../fixtures/module-cache/cjs-counter.js', import.meta.url);
+
+const importPromise = import(url.href);
+clearCache(url);
+
+const first = await importPromise;
+assert.strictEqual(first.default.count, 1);
+
+clearCache(url);
+const second = await import(url.href);
+assert.strictEqual(second.default.count, 2);
+
+delete globalThis.__module_cache_cjs_counter;
diff --git a/test/es-module/test-module-clear-cache-wasm-leak.mjs b/test/es-module/test-module-clear-cache-wasm-leak.mjs
new file mode 100644
index 00000000000000..b5f5b3829ae98c
--- /dev/null
+++ b/test/es-module/test-module-clear-cache-wasm-leak.mjs
@@ -0,0 +1,26 @@
+// Flags: --no-warnings
+
+import { mustCall } from '../common/index.mjs';
+import assert from 'node:assert';
+import { clearCache, createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { checkIfCollectableByCounting } = require('../common/gc');
+
+const baseUrl = new URL('../fixtures/simple.wasm', import.meta.url);
+
+const outer = 8;
+const inner = 4;
+
+const runIteration = mustCall(async (i) => {
+  for (let j = 0; j < inner; j++) {
+    const url = new URL(baseUrl);
+    url.search = `?v=${i}-${j}`;
+    const mod = await import(url.href);
+    assert.strictEqual(mod.add(1, 2), 3);
+    clearCache(url);
+  }
+  return inner;
+}, outer);
+
+checkIfCollectableByCounting(runIteration, WebAssembly.Instance, outer).then(mustCall());
diff --git a/test/es-module/test-module-clear-cache-wasm.mjs b/test/es-module/test-module-clear-cache-wasm.mjs
new file mode 100644
index 00000000000000..765e83c3f30481
--- /dev/null
+++ b/test/es-module/test-module-clear-cache-wasm.mjs
@@ -0,0 +1,17 @@
+// Flags: --no-warnings
+
+import assert from 'node:assert';
+import { clearCache } from 'node:module';
+
+const url = new URL('../fixtures/simple.wasm', import.meta.url);
+
+const first = await import(url.href);
+assert.strictEqual(first.add(1, 2), 3);
+
+const result = clearCache(url);
+assert.strictEqual(result.commonjs, false);
+assert.strictEqual(result.module, true);
+
+const second = await import(url.href);
+assert.strictEqual(second.add(2, 3), 5);
+assert.notStrictEqual(first, second);
diff --git a/test/fixtures/source-map/cjs-closure-source-map.js b/test/fixtures/source-map/cjs-closure-source-map.js
new file mode 100644
index 00000000000000..85c3231537e08d
--- /dev/null
+++ b/test/fixtures/source-map/cjs-closure-source-map.js
@@ -0,0 +1,9 @@
+function crash() {
+  throw new Error('boom');
+}
+
+module.exports = {
+  crash,
+};
+
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNqcy1jbG9zdXJlLXNvdXJjZS1tYXAtb3JpZ2luYWwuanMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEiLCJzb3VyY2VzQ29udGVudCI6WyJmdW5jdGlvbiBjcmFzaCgpIHtcbiAgdGhyb3cgbmV3IEVycm9yKCdib29tJyk7XG59XG4iXX0=
diff --git a/test/parallel/test-module-clear-cache-cjs-cache.js b/test/parallel/test-module-clear-cache-cjs-cache.js
new file mode 100644
index 00000000000000..de89147f17eabc
--- /dev/null
+++ b/test/parallel/test-module-clear-cache-cjs-cache.js
@@ -0,0 +1,25 @@
+// Flags: --expose-internals
+'use strict';
+
+const common = require('../common');
+
+const assert = require('node:assert');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { clearCache } = require('node:module');
+const { clearCjsCache } = require('internal/modules/esm/translators');
+
+const fixturePath = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-counter.js');
+const url = pathToFileURL(fixturePath);
+
+(async () => {
+  const first = await import(`${url.href}?v=1`);
+  assert.strictEqual(first.default.count, 1);
+
+  const result = clearCache(url);
+  assert.strictEqual(result.commonjs, true);
+  assert.strictEqual(result.module, true);
+
+  assert.strictEqual(clearCjsCache(`${url.href}?v=1`), false);
+  delete globalThis.__module_cache_cjs_counter;
+})().then(common.mustCall());
diff --git a/test/parallel/test-module-clear-cache-leak.js b/test/parallel/test-module-clear-cache-leak.js
new file mode 100644
index 00000000000000..8f349b0144810d
--- /dev/null
+++ b/test/parallel/test-module-clear-cache-leak.js
@@ -0,0 +1,23 @@
+'use strict';
+
+const common = require('../common');
+
+const path = require('node:path');
+const Module = require('node:module');
+const { clearCache } = require('node:module');
+const { checkIfCollectableByCounting } = require('../common/gc');
+
+const fixture = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-counter.js');
+
+const outer = 16;
+const inner = 64;
+
+checkIfCollectableByCounting(() => {
+  for (let i = 0; i < inner; i++) {
+    require(fixture);
+    clearCache(fixture, { mode: 'commonjs' });
+  }
+  return inner;
+}, Module, outer).then(common.mustCall(() => {
+  delete globalThis.__module_cache_cjs_counter;
+}));
diff --git a/test/parallel/test-module-clear-cache-parent-links.js b/test/parallel/test-module-clear-cache-parent-links.js
new file mode 100644
index 00000000000000..8299a3a2754d97
--- /dev/null
+++ b/test/parallel/test-module-clear-cache-parent-links.js
@@ -0,0 +1,35 @@
+// Flags: --expose-internals
+'use strict';
+
+require('../common');
+
+const assert = require('node:assert');
+const path = require('node:path');
+const { clearCache } = require('node:module');
+const { internalBinding } = require('internal/test/binding');
+
+const {
+  privateSymbols: {
+    module_first_parent_private_symbol,
+    module_last_parent_private_symbol,
+  },
+} = internalBinding('util');
+
+const parentPath = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-parent.js');
+const childPath = path.join(__dirname, '..', 'fixtures', 'module-cache', 'cjs-child.js');
+
+require(parentPath);
+
+const childModule = require.cache[childPath];
+const parentModule = require.cache[parentPath];
+
+assert.strictEqual(childModule[module_first_parent_private_symbol], parentModule);
+assert.strictEqual(childModule[module_last_parent_private_symbol], parentModule);
+
+clearCache(parentPath, { mode: 'commonjs' });
+
+assert.strictEqual(childModule[module_first_parent_private_symbol], undefined);
+assert.strictEqual(childModule[module_last_parent_private_symbol], undefined);
+
+clearCache(childPath, { mode: 'commonjs' });
+delete globalThis.__module_cache_cjs_child_counter;
diff --git a/test/parallel/test-module-clear-cache-source-map-closure.js b/test/parallel/test-module-clear-cache-source-map-closure.js
new file mode 100644
index 00000000000000..37b31f02d0fa84
--- /dev/null
+++ b/test/parallel/test-module-clear-cache-source-map-closure.js
@@ -0,0 +1,29 @@
+// Flags: --enable-source-maps
+'use strict';
+
+require('../common');
+
+const assert = require('node:assert');
+const path = require('node:path');
+const { clearCache } = require('node:module');
+
+const fixture = path.join(
+  __dirname,
+  '..',
+  'fixtures',
+  'source-map',
+  'cjs-closure-source-map.js',
+);
+
+const { crash } = require(fixture);
+
+const result = clearCache(fixture);
+assert.strictEqual(result.commonjs, true);
+assert.strictEqual(result.module, false);
+
+try {
+  crash();
+  assert.fail('Expected crash() to throw');
+} catch (err) {
+  assert.match(err.stack, /cjs-closure-source-map-original\.js/);
+}

From ee06977f0fb3394b82361043690b1e52d826f2d1 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 11 Feb 2026 12:36:58 -0800
Subject: [PATCH 7/7] fixup! module: add clearCache for CJS and ESM

---
 test/es-module/test-module-clear-cache-wasm-leak.mjs | 6 +++---
 test/es-module/test-module-clear-cache-wasm.mjs      | 1 +
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/test/es-module/test-module-clear-cache-wasm-leak.mjs b/test/es-module/test-module-clear-cache-wasm-leak.mjs
index b5f5b3829ae98c..99779ef3527eeb 100644
--- a/test/es-module/test-module-clear-cache-wasm-leak.mjs
+++ b/test/es-module/test-module-clear-cache-wasm-leak.mjs
@@ -1,6 +1,6 @@
 // Flags: --no-warnings
 
-import { mustCall } from '../common/index.mjs';
+import { mustCall, mustCallAtLeast } from '../common/index.mjs';
 import assert from 'node:assert';
 import { clearCache, createRequire } from 'node:module';
 
@@ -12,7 +12,7 @@ const baseUrl = new URL('../fixtures/simple.wasm', import.meta.url);
 const outer = 8;
 const inner = 4;
 
-const runIteration = mustCall(async (i) => {
+const runIteration = mustCallAtLeast(async (i) => {
   for (let j = 0; j < inner; j++) {
     const url = new URL(baseUrl);
     url.search = `?v=${i}-${j}`;
@@ -21,6 +21,6 @@ const runIteration = mustCall(async (i) => {
     clearCache(url);
   }
   return inner;
-}, outer);
+});
 
 checkIfCollectableByCounting(runIteration, WebAssembly.Instance, outer).then(mustCall());
diff --git a/test/es-module/test-module-clear-cache-wasm.mjs b/test/es-module/test-module-clear-cache-wasm.mjs
index 765e83c3f30481..9bc7265b2fbd9f 100644
--- a/test/es-module/test-module-clear-cache-wasm.mjs
+++ b/test/es-module/test-module-clear-cache-wasm.mjs
@@ -1,5 +1,6 @@
 // Flags: --no-warnings
 
+import '../common/index.mjs';
 import assert from 'node:assert';
 import { clearCache } from 'node:module';