Automate synchronization of built-in ESM facades with modified CJS exports

[Siddhartha-singh01]

What is the problem this feature will solve?

Right now, Module.syncBuiltinESMExports() is a manual process. It’s a bit of a pain because if you forget to call it after changing a built-in's exports (like during mocking), the ESM imports don't actually update.

I just ran into this while working on a fix for Issue #62081 mocking node:timers/promises only worked because we manually triggered this sync. It’s very easy to miss, and it makes the native mocking system feel a bit brittle because every new test feature has to "remember" to pull this lever.

What is the feature you are proposing to solve the problem?

I think we should look into making these ESM built-in facades stay in sync automatically. Instead of having to call a sync function everywhere, maybe we could use something like a Proxy or dynamic getters on the ModuleWrap so that the ESM side always sees the latest CJS state.

Even just adding an internal observer that triggers the existing sync logic whenever those core exports objects are mutated would be a huge win. It would make the native mocking (and APM tools) a lot more reliable without developers needing to know about the sync utility.

What alternatives have you considered?

The only real alternative is sticking with the manual calls we have now, but it’s just too error-prone. We could also look at moving more of the resolution logic into C++ to "harden" it, but automating the current JS synchronization seems like a much simpler and more direct way to solve the immediate problem.

[Renegade334]

See nodejs/modules#481, #29737 for context.

[joyeecheung]

maybe we could use something like a Proxy or dynamic getters on the ModuleWrap

I think under the current semantics of ESM this would be difficult. The specification mandates that the name space object is a plan object with only data properties. It's built by the JS engine, not something embedders like Node.js get to arbitrarily offer. Now, there are some sort of getter/setter aspect within the specification (and thus hid within the JS engines) that allow the access to the exports to throw ReferenceError (when they are not yet initialized) or trigger deferred evaluation (in https://github.com/tc39/proposal-defer-import-eval), but for more generalized control over "doing something that the embedder wants" on named export access, I can't see how this can be solved with only changes in Node.js without V8 - which means changing the specification to allow this pathway, at least for Synthetic moddules

Even just adding an internal observer that triggers the existing sync logic whenever those core exports objects are mutated would be a huge win.

This can be more practical, but note that this could bring a non-trivial overhead (especially for uses that are not caching the access at the top level for the same purpose of catching the patch) and also several built-ins already intercept their own exports.

[joyeecheung]

Also in #62081, I think the issue isn't ESM, but the way it is used:

import * as NodeTest from 'node:test';
import * as NodeTimers from 'node:timers/promises';
import * as NodeAssert from 'node:assert';

This works differently from using the default exports, the result from the import * is the namespace object that Node.js has little dynamic control over. For module mocking to always work, one easy solution is to explicitly document against using import *, and instead, do this:

import NodeTest from 'node:test';
import NodeTimers from 'node:timers/promises';
import NodeAssert from 'node:assert';

If you use the default export, the default export object is fully controlled by Node.js and always in sync with what's in the real exports.

I think one thing we can do is to eliminate all examples doing things like import * as fs from 'node:fs' in our documentation and explicitly advise against it. One should not think of them as equivalent of const fs = require('fs') but instead, they are equivalent of const fs = { ...require('fs') } - everything is enumerated and cached on the first access, and won't be dynamically queried later. The real equivalent should be import fs from 'node:fs' which would maintain dynamism.