module: add clearCache for CJS and ESM

Author: anonrig

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

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.

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 = {

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;

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,
+};

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;

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;