Explain dual-instantiation #11
Conversation
Resolve the open issue of what happens when a file is requested to be loaded in both modes: ESM and CommonJS. See GeoffreyBooth#1 for discussion.
|
@bmeck do you mind reviewing this? |
README.md
Outdated
| @@ -281,18 +281,14 @@ To preserve backward compatibility, we expect that `node file.js` will continue | |||
|
|
|||
| A package can be “dual mode” if its `package.json` contains both a `"main"` field and an `"exports"` field (or some other ESM-signifying field). An `import` statement of such a package will treat the package as ESM and ignore the `"main"` field. To explicitly import a dual-mode package via its CommonJS entry point, [`module.createRequireFromPath`][nodejs-docs-modules-create-require-from-path] could be used. | |||
|
|
|||
| The ESM and CommonJS versions of a dual-mode package are really two distinct packages, and would be treated as such by Node if both were imported. It is an implementation detail to be worked out what Node should do in such a situation. Of particular concern are race conditions that could occur if it might be unpredictable which version (ESM or CommonJS) of a dual-mode package gets loaded first. | |||
| The ESM and CommonJS module systems have independent namespaces. Therefore the ESM and CommonJS versions of a file have separate identities when instantiated. The module loader's previous invariant was: a file will only be loaded at-most once within a Node application. This invariant now becomes: a version of a file (ESM or CommonJS) will only be loaded at-most once within a Node application. | |||
There was a problem hiding this comment.
I'm confused on "previous invariant". What invariant? Also, are we talking purely about how CJS works, because the loader does not guarantee a file on disk is only loaded once (throw on require/case insensitive filesystems/removal from require.cache).
Also, unclear on if
a version of a file (ESM or CommonJS) will only be loaded at-most once within a Node application.
Is trying to state that a file/url can only be loaded once and only in either CJS or ESM but not in both. It seems unlikely that we can stop CJS from loading all sorts of things.
There was a problem hiding this comment.
Thanks for the clarification. I have attempted a fix.
I'm trying to refer to the resolved specifier identity that gets used as a key in the virtual registry of all instantiated modules (CJS and ESM). This key is effectively being expanded to include a bit that indicates whether the module is CJS or ESM. Maybe you can guide me on the precise terminology.
An alternative mental model (not written up) would be view them as distinct registries (ESM & CJS) and say that require only operates on the CJS registry whereas import/import() can operate on both registries.
There was a problem hiding this comment.
There are 2 "Registry"s of sorts, the Global Module Map in ESM and require.cache in CJS. They are not intertwined in part due to the ecosystem reliance on require.cache which is not compatible with how ESM modules are keyed or cached.
There was a problem hiding this comment.
I have reworded in terms of two registries. Please let me know if this is better.
|
I'm happy to merge in whenever @bmeck is satisfied. |
|
This seems fine. |
Resolve the open issue of what happens when a file is requested to be loaded in both modes: ESM and CommonJS.
See #1 for discussion.
The wording is under "Dual-mode packages" section title, but the semantics are more for the general topic of dual-mode files. If we're agreed on the behavior, we can relocate the wording into a more appropriate section.