module: add clearCache for CJS and ESM

[anonrig]

Introduce Module.clearCache() to invalidate CommonJS and ESM module caches with optional resolution context, enabling HMR-like reloads. Document the API and add tests/fixtures to cover cache invalidation behavior.

[nodejs-github-bot]

Review requested:

• @nodejs/loaders

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @anonrig.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[mcollina]

I’m relatively +1 on having this in Node.js, but I recall having a a lot of discussions about this @GeoffreyBooth and @nodejs/loaders teams about this, and it would massively break the spec, expectations, and invariants regarding ESM.

(Note, this is what people have been asking us to add for a long time).

My personal objection to this API is that it would inadvertently leak memory at every turn, so while this sounds good in theory, in practice it would significantly backfire in long-running scenarios. An option could be to expose it only behind a flag, putting the user in charge of choosing this behavior.

Every single scenario where I saw HMR in Node.js ends up in memory leaks. This is the reason why I had so much interest and hopes for ShadowRealm.

[benjamingr]

I am still +1 on the feature from a user usability point of view. Code lgtm.

[benjamingr]

Every single scenario where I saw HMR in Node.js ends up in memory leaks. This is the reason why I had so much interest and hopes for ShadowRealm.

We're giving users a tool, it may be seen as a footgun by some but hopefully libraries that use the API correctly and warn users about incorrect usage emerge.

[anonrig]

@mcollina Thanks for the feedback. I agree the ESM semantics concerns are real. This API doesn’t change the core ESM invariants (single instance per URL); it only removes Node's internal cache entries to allow explicit reloads in opt‑in workflows. Even with that, existing references (namespaces, listeners, closures) can keep old graphs alive, so this is still potentially leaky unless the app does explicit disposal. I’ll make sure the docs call out the risks and the fact that this only clears Node’s internal caches, and I’d like loader team input on the final shape of the API.

This commit should address some of your concerns. b3bd79a

I am still +1 on the feature from a user usability point of view. Code lgtm.

Thanks for the review @benjamingr. Would you mind re-reviewing again so I can trigger CI?

[Nsttt]

Thanks a lot for this ❤️

[Jamesernator]

Rather than violating ESM invariants, can't node just provide a function that imports a url?

i.e. While the given example of:

const url = new URL('./mod.mjs', import.meta.url);
await import(url.href);

clearCache(url);
await import(url.href); // re-executes the module

is indeed not spec compliant, it's perfectly legal to have something like:

import { clearCache, importModule } from "node:module";

await importModule(someUrl);
clearCache();
await importModule(someUrl); // reexecute

[codecov]

Codecov Report

❌ Patch coverage is 86.15702% with 67 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.71%. Comparing base (2e1265a) to head (1410c00).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/modules/esm/loader.js	35.08%	37 Missing ⚠️
lib/internal/modules/clear.js	91.79%	26 Missing and 1 partial ⚠️
lib/internal/modules/esm/module_map.js	91.17%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61767      +/-   ##
==========================================
- Coverage   89.72%   89.71%   -0.02%     
==========================================
  Files         676      677       +1     
  Lines      206065   206553     +488     
  Branches    39508    39597      +89     
==========================================
+ Hits       184897   185301     +404     
- Misses      13315    13383      +68     
- Partials     7853     7869      +16     

Files with missing lines	Coverage Δ
lib/internal/modules/esm/translators.js	97.84% <100.00%> (+0.20%)	⬆️
lib/module.js	100.00% <100.00%> (ø)
lib/internal/modules/esm/module_map.js	96.96% <91.17%> (-1.51%)	⬇️
lib/internal/modules/clear.js	91.79% <91.79%> (ø)
lib/internal/modules/esm/loader.js	95.23% <35.08%> (-3.53%)	⬇️

... and 29 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[joyeecheung]

While I am +1 to the idea in general, I am afraid the current API may bring more problem than it solves...see the comments.

(Granted it isn't really a problem unique to this specific design, I think the issue is more that this is not a very well solved problem so far, I don't really know what it should look like, though I think I might be able to point out what it should not look like to avoid adding/re-introducing leaks/use-after-frees that user land workarounds can already manage)

[ScriptedAlchemy]

I was the one requesting this while sitting next to yagiz today.
Some context:

We take advantage of Module Federation which allows us to distribute code at runtime. However, when parts of the distributed system are updated, it gets stuck in module cache.

I've had some workarounds, like attempting to purge require cache - however when it comes to esm, it's a difficult problem. Since we do this distribution primarily in production, and there can be thousands of updates a day, I block esm from being supported because it'll leak memory - which was fine for several years but becoming more problematic in modern tooling.

On lambda we cannot just exit a process and bring a new one up without triggering a empty deploy, which has generally been a perf hit to cold start a new lambda vs try and "reset" the module cache for primitive hot reload.

Now, I know this might be controversial, or not recommended - but the reality is that many large companies use federation, most fortune 50 companies use it heavily. All of them are relying on userland cobbling I've created. If there is a solution, it would be greatly appreciated by all of my users.

I believe this would also be very useful in general for tooling like rspack etc where we have universal dev serves.

If invalidation of specific modules causes complexity, I'd be more than happy with a nuclear option like resetModuleCache() which just clears everything entirely. Would be a little slower, but nothing is slower than killing a process and bringing up a new one.

"Soft Restart" node without killing it.
Yes, I'm aware of various footguns like globals, prototype pollution etc.
These so far have been easy to mitigate and none of the user base has reported any major issues around it, whereas my cobbled together solution poses a much bigger issue vs footguns.

Don't have much opinion on spec compliance etc, can go through NAPI as well if that would avoid any spec concerns or pushback.

[jsumners-nr]

Chiming in to say that re-loading a module is very helpful in tests. We can do this with the fabulous CJS paradigm, but ESM does not have a viable equivalent and it should.

[joyeecheung]

I think there are still quite a few places that need updates/tests - I tried my best to find them, but there are some dusty corners in the module loader that I have never poked at, you might want to take a heap snapshot or write more tests with v8.queryObject() to verify:

• What happens when a closure in a module errors (or more specifically when the error stack is prepared by poking at various caches) after the cache of the original module is cleared? Especially if it has source maps and --enable-source-maps is on?
• This is tricky, but cjsModule[parent] and cjsModule[kLastModuleParent] could need an update too if you yank the parents out of the cache. Otherwise the parent can get leaked.
• When dynamic import(cjs) happens, there can be a point where the CJS module cache entry for the requested module and its dependencies are synchronously populated for export detection, but they will only be compiled and evaluated in the next microtask queue checkpoint, yet here import() itself can already return since it's async, and some code elsewhere could clear the cache before another checkpoint (likely an await) actually spins the evaluation - in the evaluation callback of cjs facades, it will then try to look up the caches again, and see a mismatch between "module whose exports are detected" v.s. "module that's actually being compiled and evaluated" - races of this kind has been a source of subtle bugs, we sort of made most of them go away by making resolution and loading entirely synchronous, but the cache clearing can expose new internal details that add another bug surface that's worth checking.
• The cjsCache in the esm translators (there's a TODO about using WeakMap instead, maybe that works?)
• The wasm facade module has a custom import.meta initializer that contains a closure (implemented in createDynamicModule), which in turn has references crossing the wasm boundary, not sure if that can create another source of leaks.

[anonrig]

I think I addressed all of your concerns @joyeecheung. Let me know if I missed anything!

[GeoffreyBooth]

I’m relatively +1 on having this in Node.js, but I recall having a a lot of discussions about this @GeoffreyBooth and @nodejs/loaders teams about this, and it would massively break the spec, expectations, and invariants regarding ESM.

Just pinging @guybedford to speak on the spec concerns. I think we should wait for him or someone similarly knowledgeable about the spec to comment before landing.

In general I'm +1 on the feature, assuming it can be safely implemented. My (dim) recollection was that the last time we considered it, it was impossible to modify an ES module after it had been loaded into V8. Has that changed in recent years? How do you handle cases like import { foo } from './bar.js' where bar.js gets reloaded and no longer has a foo export, and the importing code calls foo()? That was part of the complexity, that ESM has this linking stage and so presumably replaced modules need to have the same shapes/exports or else the linking gets invalidated.

[guybedford]

This seems very reasonable to me!

In terms of spec compatibility, formally hot reloading does break the host hook invariant, although the reality with loaders already does of course, and perhaps there are wording changes here that might accommodate this better. The resolve cache clearing has some interesting spec integration aspects, since the resolve cache is on the module records themselves in ECMA-262, and also in HTML there's a global resolved set of (specifier, parent) pairs. But the model implemented here seems like it would mostly be consistent with both of those constructs if we ever wanted to consider something standard.

I'd like to add these topics to the agenda at the next TC39 modules coming up next Thursday 26. The meeting is on the public calendar if anyone here interested would like to join. There are no concerns from my side, but I think it's a very interesting spec discussion to have nonetheless.

[ScriptedAlchemy]

This seems very reasonable to me!

In terms of spec compatibility, formally hot reloading does break the host hook invariant, although the reality with loaders already does of course, and perhaps there are wording changes here that might accommodate this better. The resolve cache clearing has some interesting spec integration aspects, since the resolve cache is on the module records themselves in ECMA-262, and also in HTML there's a global resolved set of (specifier, parent) pairs. But the model implemented here seems like it would mostly be consistent with both of those constructs if we ever wanted to consider something standard.

I'd like to add these topics to the agenda at the next TC39 modules coming up next Thursday 26. The meeting is on the public calendar if anyone here interested would like to join. There are no concerns from my side, but I think it's a very interesting spec discussion to have nonetheless.

I'd like to join. Have link to calendar?

[Nsttt]

Same thing

[nicolo-ribaudo]

I do not have the whole picture, but is we are going to discuss this at the TC39 modules meeting here is my perspective from a spec point of view.

A spec-compliant way of implementing hot reload of a module in a graph would be to re-execute the root of the graph, re-executing all the modules in the path(s) from the root to the updated module, and re-using the previous evaluations for modules in the other branches. This includes both edges created by static imports and by dynamic imports.

For example, consider a graph like this one, with A being the root:

If you want to reload F, you'd need to reload/rerun A/B/E/F (let's call them A'/B'/E'/F'), while re-using the existing D/G/H.

Once that's done, all the old copies of the modules that have been re-executed can be garbage collected. There is no module that has already run import("foo") and received the old module, and thus would need to re-receive the old module when re-running import("foo"), because that module is among those that would have been re-executed and thus has only seen the new version of foo.

At this point there is nobody that can, for example, observe that import('F') gives the new module while actually needing to receive the old one:

• B'/E' only ever saw F' when doing an import of the specifier "F", so in those modules import('F') needs to resolve to F'
• If any of A'/D/F'/G/H were to do import('F'), it would be the first time that they load the specifier "F", so there is no expectation on whether it needs to resolve to F or F'.

The spec is not incompatible with hot reloading, but it makes sure that you cannot swap the dependencies under an already evaluated module. By doing so it avoids problems like #61767 (comment).

I guess concretely, this would be implemented by counting the number of alive importers of a module, and only allowing to clear the cache from one with no importers alive.

In the example above, after the reloading happens:

• A has no importers, so it can be removed from the cache
• this decreases the number of alive importers of B and E to 0, so they can also be removed from the cache
• this decreases the number of alive importers of F to 0, so it can be removed from the cache.

[jsumners-nr]

Given the "spec compliant" post above, I think an example of what I think should be possible is warranted.

Consider the case where the thing being tested hooks into module loading. A test suite for such a thing may traditionally look like:

test.beforeEach((ctx) => {
	ctx.namespace = {}
	ctx.namespace.mod = require('something')
})

test.afterEach(() => {
	clearCache('something')
})

test('foo is added', (t) => {
	const { mod } = t.namespace
	t.assert.equal(mod.foo, 'foo')
})

test('bar is added', (t) => {
	const { mod } = t.namespace
	t.assert.equal(mod.bar, 'bar')
})

The key to that example is that the module is completely re-required between each subtest so that the module patching happens prior to each subtest.

As a user, I do not care how it happens, or what the spec folks want in order for it to happen, I just want the same concept to be 1:1 viable with ESM.

[joyeecheung]

This may need to spell out a bit more concretely how HMR is supposed to use this API without leaking more. From #61767 (comment) there are a couple of things that need to be taken care of:

1. The solution must clear the cache for the module that has changed
2. The solution must also force a "re-linking" of the module graph so that dependent of the changed module see the update (the mechanics of this may involve more cache clearing as it bubbles up).

2 has a subtle difference in CommonJS v.s. ESM dependents. If the changed module has CommonJS dependents, the solution may need to track and clear the cache of all the dependent modules and re-evaluate from the root to see the update. For ESM dependents it's easier because evaluation is separate from linking, so the solution can simply clear the cache for the changed module and the root, and re-evaluate from the root to pick up the new branch while reusing all the existing branches (so unchanged modules won't get evaluated again). This won't violate the spec as explained by Nicolo because it's technically disposing the old graph and then linking and evaluating a new graph again that just reuse some existing module records, not mutating the existing link of an old, evaluated graph.

Although, it would be much simpler if whatever that uses it enforces that the module that gets HMR can only ever be the root itself and no bottom-up dependency HMR is supported. But I am not sure if that's a limitation that all existing HMR users can enforce.

[GeoffreyBooth]

Would it be simpler if instead of a “clear cache” API, we just provided a “replace module” API? Where the new module must have the same exports as the old one, so that the linking wouldn’t need to be redone?

[joyeecheung]

I think regardless of whether the new module has the same exports or not, linking must be redone. Links exist between different module records (not Node.js ModuleJobs or ModuleWraps, but v8::Module), and we can't swap out what's inside a v8::Module - but can only compile a new one and relink.

[joyeecheung]

What does this do when you call module.clearCache('./x.js') from say path/to/y.js but do not pass in parentURL? I think the current API hints that it will resolve to path/to/x.js but in reality this actually resolves to cwd/x.js? If that's intentional this needs a test - although I think resolving relative to cwd might be rather surprising.

It might be better to just enforce that either it's a full URL, or if it's not, parentURL is mandatory. Or alternatively - never takes specifiers, always take full URLs. Users can get to the URL via import.meta.resolve or require.resolve or with more rudimentary methods like URL/path.join in the examples below. Then they can cache the URL themselves as needed. And the API is only in charge of clearing the load cache entry corresponding to that URL. That'll also simplify the implementation a lot, and it no longer needs to create a fake parent for CJS resolution.

[joyeecheung]

This still needs examples showing what clearing for non-absolute specifiers would do.

[joyeecheung]

Do we still need this and other things that clear the resolve cache?

[joyeecheung]

I think this also needs to explain that if both import('x', { with: { type: 'json' } }) and import('x', { with: { type: 'javascript' } }) have happened, the implementation clears the cache for both (I am not fully sure this is possible with type, but it can be possible when customization supports other import attributes)

[joyeecheung]

I checked out the existing HMR solutions a bit and I think this API may be enough:

/**
 * @param {string|URL} specifier  // This is what would've been passed into import(specifier) or require(specifier)
 * @param {{
 *   parentURL: string | URL,  // Mandatory, because parent identity is part of the resolution cache key
 *   importAttributes?: Record<string, string>,  // Optional, only meaningful when resolver is "import"
 *   resolver: "import" | "require",  // Specifies how resolution should be performed
 *   caches: "resolution" | "module" | "all",  // resolution: only clear resolution cache; module: clear cache for the module everywhere in Node.js (not counting JS level references)
 * }} options
 */
function clearCache(specifier, options) {}

clearing resolution cache is still useful for HMR solutions that do cache busting URLs - which I think may actually be the more spec-compliant way to implement it. The spec violation technically doesn't come from evaluation, but from module mapping specified by HostLoadImportedModule:

If this operation is called multiple times with two (referrer, moduleRequest) pairs such that:

• the first referrer is the same as the second referrer;
• ModuleRequestsEqual(the first moduleRequest, the second moduleRequest) is true;

and it performs FinishLoadingImportedModule(referrer, moduleRequest, payload, result) where result is a normal completion, then it must perform FinishLoadingImportedModule(referrer, moduleRequest, payload, result) with the same result each time.

The cache clearing API makes it possible for the same referrer + module request to get different module records in return, but it does not mean this must be violating the spec by nature, it just delegates the responsibility of correctness to whoever that uses this API, similar to how V8 delegates this to Node.js. One way to ensure this is correctly implemented is to use a cache busting referrer (i.e. import('./app.js?hmr=1'), import('./app.js?hmr=2')...when the reloaded module is app.js, then it is no longer the same module request anyway).

A minimal example of using this (ignoring some complexities from e.g. fs) can be

let app, rev = 0;

const reload = async () => {
  const prev = rev ? `./app.mjs?hmr=${rev}` : null;
  await app?.dispose?.();  // clear side effects
  if (prev) {
    module.clearCache(prev, {
      parentURL: import.meta.url,
      resolver: "import",
      caches: "all",
    });
  }
  app = await import(`./app.mjs?hmr=${++rev}`);
};

await reload();
http.createServer((req, res) => app.handle(req, res)).listen(3000);
fs.watch(new URL(import.meta.resolve('./app.mjs')), reload);

[nicolo-ribaudo]

@joyeecheung In that example, if ./app.mjs depends on ./dependency.mjs and ./dependency.mjs changes, would ./app.mjs?hmr=2 get the new version of it? Or would it still get the old version because it's in some (fullyResolvedURL -> evaluated module) cache?

[nicolo-ribaudo]

@ScriptedAlchemy @Nsttt the meeting is today at 4pm UTC. If nobody sent you the link yet, feel free to email me at the email on my GitHub profile and I'll send you the meeting URL.

[joyeecheung]

In that example, if ./app.mjs depends on ./dependency.mjs and ./dependency.mjs changes, would ./app.mjs?hmr=2 get the new version of it? Or would it still get the old version because it's in some (fullyResolvedURL -> evaluated module) cache?

This is a minimal example, but if dependencies need to be supported, the HMR solution can just append hmr parameter to all the dependencies via a loader hook that track the graph through context.parentURL and manage the lifecycle of them, which IIUC is what they already do for CJS anyway (because const { foo } = require('foo') at the top level also can't be broken once evaluated), just using a stable URL because there's no idempotency requirement for CJS. The cache busting method for ESM is already used by a few HMR solutions (e.g. https://adonisjs.com/blog/hmr-in-adonisjs#hot-hook) - what they don't have remaining is to clear the stale cache left behind.

[joyeecheung]

I think one way to test this more robustly (i.e. V8 can actually garbage collect it) might be something like this:

// Flags: --expose-internals
const { internalBinding } = require('internal/test/binding');
const { ModuleWrap } = internalBinding('module_wrap');
const { queryObjects } require('node:v8');  // Let's run the test in CJS to reduce the noise from queryObject
let app, rev = 0;
const reload = async () => {
  const prev = rev ? `./app.mjs?hmr=${rev}` : null;
  if (prev) {
    module.clearCache(prev, {
      parentURL: import.meta.url,
      resolver: "import",
      caches: "all",
    });
  }
  app = await import(`./app.mjs?hmr=${++rev}`);
};

(async() {
  await reload();  // first load
  await reload();  // second
  const result = queryObjects(ModuleWrap, { format: 'summary' });
  // Validate that result no longer includes module with a wrap whose .url includes `app.mjs?hmr=0`
})();

(Or use checkIfCollectableByCounting with ModuleWrap)

[anonrig]

@joyeecheung Pushed a new test according to your recommendations.