Skip to content

Commit aa7df95

Browse files
joyeecheungaduh95
joyeecheung
authored and
aduh95
committed
module: add __esModule to require()'d ESM
Tooling in the ecosystem have been using the __esModule property to recognize transpiled ESM in consuming code. For example, a 'log' package written in ESM: export function log(val) { console.log(val); } Can be transpiled as: exports.__esModule = true; exports.default = function log(val) { console.log(val); } The consuming code may be written like this in ESM: import log from 'log' Which gets transpiled to: const _mod = require('log'); const log = _mod.__esModule ? _mod.default : _mod; So to allow transpiled consuming code to recognize require()'d real ESM as ESM and pick up the default exports, we add a __esModule property by building a source text module facade for any module that has a default export and add .__esModule = true to the exports. We don't do this to modules that don't have default exports to avoid the unnecessary overhead. This maintains the enumerability of the re-exported names and the live binding of the exports. The source of the facade is defined as a constant per-isolate property required_module_facade_source_string, which looks like this export * from 'original'; export { default } from 'original'; export const __esModule = true; And the 'original' module request is always resolved by createRequiredModuleFacade() to wrap which is a ModuleWrap wrapping over the original module. PR-URL: #52166 Refs: #52134 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Filip Skokan <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Guy Bedford <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]>
1 parent eb4e370 commit aa7df95

30 files changed

+315
-55
lines changed

‎doc/api/modules.md

+27-9
Original file line numberDiff line numberDiff line change
@@ -188,33 +188,51 @@ loaded by `require()` meets the following requirements:
188188
`"type": "commonjs"`, and `--experimental-detect-module` is enabled.
189189

190190
`require()` will load the requested module as an ES Module, and return
191-
the module name space object. In this case it is similar to dynamic
191+
the module namespace object. In this case it is similar to dynamic
192192
`import()` but is run synchronously and returns the name space object
193193
directly.
194194

195+
With the following ES Modules:
196+
195197
```mjs
196-
// point.mjs
198+
// distance.mjs
197199
export function distance(a, b) { return (b.x - a.x) ** 2 + (b.y - a.y) ** 2; }
200+
```
201+
202+
```mjs
203+
// point.mjs
198204
class Point {
199205
constructor(x, y) { this.x = x; this.y = y; }
200206
}
201207
export default Point;
202208
```
203209

210+
A CommonJS module can load them with `require()` under `--experimental-detect-module`:
211+
204212
```cjs
205-
const required = require('./point.mjs');
213+
const distance = require('./distance.mjs');
214+
console.log(distance);
206215
// [Module: null prototype] {
207-
// default: [class Point],
208216
// distance: [Function: distance]
209217
// }
210-
console.log(required);
211218

212-
(async () => {
213-
const imported = await import('./point.mjs');
214-
console.log(imported === required); // true
215-
})();
219+
const point = require('./point.mjs');
220+
console.log(point);
221+
// [Module: null prototype] {
222+
// default: [class Point],
223+
// __esModule: true,
224+
// }
216225
```
217226

227+
For interoperability with existing tools that convert ES Modules into CommonJS,
228+
which could then load real ES Modules through `require()`, the returned namespace
229+
would contain a `__esModule: true` property if it has a `default` export so that
230+
consuming code generated by tools can recognize the default exports in real
231+
ES Modules. If the namespace already defines `__esModule`, this would not be added.
232+
This property is experimental and can change in the future. It should only be used
233+
by tools converting ES modules into CommonJS modules, following existing ecosystem
234+
conventions. Code authored directly in CommonJS should avoid depending on it.
235+
218236
If the module being `require()`'d contains top-level `await`, or the module
219237
graph it `import`s contains top-level `await`,
220238
[`ERR_REQUIRE_ASYNC_MODULE`][] will be thrown. In this case, users should

‎lib/internal/modules/cjs/loader.js

+51-4
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ const {
4141
ObjectFreeze,
4242
ObjectGetOwnPropertyDescriptor,
4343
ObjectGetPrototypeOf,
44+
ObjectHasOwn,
4445
ObjectKeys,
4546
ObjectPrototype,
4647
ObjectPrototypeHasOwnProperty,
@@ -71,7 +72,7 @@ const {
7172
},
7273
} = internalBinding('util');
7374

74-
const { kEvaluated } = internalBinding('module_wrap');
75+
const { kEvaluated, createRequiredModuleFacade } = internalBinding('module_wrap');
7576

7677
// Internal properties for Module instances.
7778
/**
@@ -1333,9 +1334,55 @@ function loadESMFromCJS(mod, filename) {
13331334
// ESM won't be accessible via process.mainModule.
13341335
setOwnProperty(process, 'mainModule', undefined);
13351336
} else {
1336-
// TODO(joyeecheung): we may want to invent optional special handling for default exports here.
1337-
// For now, it's good enough to be identical to what `import()` returns.
1338-
mod.exports = cascadedLoader.importSyncForRequire(mod, filename, source, isMain, mod[kModuleParent]);
1337+
const {
1338+
wrap,
1339+
namespace,
1340+
} = cascadedLoader.importSyncForRequire(mod, filename, source, isMain, mod[kModuleParent]);
1341+
// Tooling in the ecosystem have been using the __esModule property to recognize
1342+
// transpiled ESM in consuming code. For example, a 'log' package written in ESM:
1343+
//
1344+
// export default function log(val) { console.log(val); }
1345+
//
1346+
// Can be transpiled as:
1347+
//
1348+
// exports.__esModule = true;
1349+
// exports.default = function log(val) { console.log(val); }
1350+
//
1351+
// The consuming code may be written like this in ESM:
1352+
//
1353+
// import log from 'log'
1354+
//
1355+
// Which gets transpiled to:
1356+
//
1357+
// const _mod = require('log');
1358+
// const log = _mod.__esModule ? _mod.default : _mod;
1359+
//
1360+
// So to allow transpiled consuming code to recognize require()'d real ESM
1361+
// as ESM and pick up the default exports, we add a __esModule property by
1362+
// building a source text module facade for any module that has a default
1363+
// export and add .__esModule = true to the exports. This maintains the
1364+
// enumerability of the re-exported names and the live binding of the exports,
1365+
// without incurring a non-trivial per-access overhead on the exports.
1366+
//
1367+
// The source of the facade is defined as a constant per-isolate property
1368+
// required_module_default_facade_source_string, which looks like this
1369+
//
1370+
// export * from 'original';
1371+
// export { default } from 'original';
1372+
// export const __esModule = true;
1373+
//
1374+
// And the 'original' module request is always resolved by
1375+
// createRequiredModuleFacade() to `wrap` which is a ModuleWrap wrapping
1376+
// over the original module.
1377+
1378+
// We don't do this to modules that don't have default exports to avoid
1379+
// the unnecessary overhead. If __esModule is already defined, we will
1380+
// also skip the extension to allow users to override it.
1381+
if (!ObjectHasOwn(namespace, 'default') || ObjectHasOwn(namespace, '__esModule')) {
1382+
mod.exports = namespace;
1383+
} else {
1384+
mod.exports = createRequiredModuleFacade(wrap);
1385+
}
13391386
}
13401387
}
13411388

‎lib/internal/modules/esm/loader.js

+3-3
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,7 @@ class ModuleLoader {
280280
* @param {string} source Source code. TODO(joyeecheung): pass the raw buffer.
281281
* @param {string} isMain Whether this module is a main module.
282282
* @param {CJSModule|undefined} parent Parent module, if any.
283-
* @returns {{ModuleWrap}}
283+
* @returns {{wrap: ModuleWrap, namespace: ModuleNamespaceObject}}
284284
*/
285285
importSyncForRequire(mod, filename, source, isMain, parent) {
286286
const url = pathToFileURL(filename).href;
@@ -305,7 +305,7 @@ class ModuleLoader {
305305
}
306306
throw new ERR_REQUIRE_CYCLE_MODULE(message);
307307
}
308-
return job.module.getNamespaceSync();
308+
return { wrap: job.module, namespace: job.module.getNamespaceSync() };
309309
}
310310
// TODO(joyeecheung): refactor this so that we pre-parse in C++ and hit the
311311
// cache here, or use a carrier object to carry the compiled module script
@@ -317,7 +317,7 @@ class ModuleLoader {
317317
job = new ModuleJobSync(this, url, kEmptyObject, wrap, isMain, inspectBrk);
318318
this.loadCache.set(url, kImplicitTypeAttribute, job);
319319
mod[kRequiredModuleSymbol] = job.module;
320-
return job.runSync().namespace;
320+
return { wrap: job.module, namespace: job.runSync().namespace };
321321
}
322322

323323
/**

‎src/env.h

+2
Original file line numberDiff line numberDiff line change
@@ -1057,6 +1057,8 @@ class Environment : public MemoryRetainer {
10571057
std::vector<std::string> supported_hash_algorithms;
10581058
#endif // HAVE_OPENSSL
10591059

1060+
v8::Global<v8::Module> temporary_required_module_facade_original;
1061+
10601062
private:
10611063
inline void ThrowError(v8::Local<v8::Value> (*fun)(v8::Local<v8::String>,
10621064
v8::Local<v8::Value>),

‎src/env_properties.h

+6
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,7 @@
256256
V(openssl_error_stack, "opensslErrorStack") \
257257
V(options_string, "options") \
258258
V(order_string, "order") \
259+
V(original_string, "original") \
259260
V(output_string, "output") \
260261
V(overlapped_string, "overlapped") \
261262
V(parse_error_string, "Parse Error") \
@@ -289,6 +290,11 @@
289290
V(regexp_string, "regexp") \
290291
V(rename_string, "rename") \
291292
V(replacement_string, "replacement") \
293+
V(required_module_facade_url_string, \
294+
"node:internal/require_module_default_facade") \
295+
V(required_module_facade_source_string, \
296+
"export * from 'original'; export { default } from 'original'; export " \
297+
"const __esModule = true;") \
292298
V(require_string, "require") \
293299
V(resource_string, "resource") \
294300
V(retry_string, "retry") \

‎src/module_wrap.cc

+69
Original file line numberDiff line numberDiff line change
@@ -1019,6 +1019,69 @@ void ModuleWrap::CreateCachedData(const FunctionCallbackInfo<Value>& args) {
10191019
}
10201020
}
10211021

1022+
// This v8::Module::ResolveModuleCallback simply links `import 'original'`
1023+
// to the env->temporary_required_module_facade_original() which is stashed
1024+
// right before this callback is called and will be restored as soon as
1025+
// v8::Module::Instantiate() returns.
1026+
MaybeLocal<Module> LinkRequireFacadeWithOriginal(
1027+
Local<Context> context,
1028+
Local<String> specifier,
1029+
Local<FixedArray> import_attributes,
1030+
Local<Module> referrer) {
1031+
Environment* env = Environment::GetCurrent(context);
1032+
Isolate* isolate = context->GetIsolate();
1033+
CHECK(specifier->Equals(context, env->original_string()).ToChecked());
1034+
CHECK(!env->temporary_required_module_facade_original.IsEmpty());
1035+
return env->temporary_required_module_facade_original.Get(isolate);
1036+
}
1037+
1038+
// Wraps an existing source text module with a facade that adds
1039+
// .__esModule = true to the exports.
1040+
// See env->required_module_facade_source_string() for the source.
1041+
void ModuleWrap::CreateRequiredModuleFacade(
1042+
const FunctionCallbackInfo<Value>& args) {
1043+
Isolate* isolate = args.GetIsolate();
1044+
Local<Context> context = isolate->GetCurrentContext();
1045+
Environment* env = Environment::GetCurrent(context);
1046+
CHECK(args[0]->IsObject()); // original module
1047+
Local<Object> wrap = args[0].As<Object>();
1048+
ModuleWrap* original;
1049+
ASSIGN_OR_RETURN_UNWRAP(&original, wrap);
1050+
1051+
// Use the same facade source and URL to hit the compilation cache.
1052+
ScriptOrigin origin(env->required_module_facade_url_string(),
1053+
0, // line offset
1054+
0, // column offset
1055+
true, // is cross origin
1056+
-1, // script id
1057+
Local<Value>(), // source map URL
1058+
false, // is opaque (?)
1059+
false, // is WASM
1060+
true); // is ES Module
1061+
ScriptCompiler::Source source(env->required_module_facade_source_string(),
1062+
origin);
1063+
1064+
// The module facade instantiation simply links `import 'original'` in the
1065+
// facade with the original module and should never fail.
1066+
Local<Module> facade =
1067+
ScriptCompiler::CompileModule(isolate, &source).ToLocalChecked();
1068+
// Stash the original module in temporary_required_module_facade_original
1069+
// for the LinkRequireFacadeWithOriginal() callback to pick it up.
1070+
CHECK(env->temporary_required_module_facade_original.IsEmpty());
1071+
env->temporary_required_module_facade_original.Reset(
1072+
isolate, original->module_.Get(isolate));
1073+
CHECK(facade->InstantiateModule(context, LinkRequireFacadeWithOriginal)
1074+
.IsJust());
1075+
env->temporary_required_module_facade_original.Reset();
1076+
1077+
// The evaluation of the facade is synchronous.
1078+
Local<Value> evaluated = facade->Evaluate(context).ToLocalChecked();
1079+
CHECK(evaluated->IsPromise());
1080+
CHECK_EQ(evaluated.As<Promise>()->State(), Promise::PromiseState::kFulfilled);
1081+
1082+
args.GetReturnValue().Set(facade->GetModuleNamespace());
1083+
}
1084+
10221085
void ModuleWrap::CreatePerIsolateProperties(IsolateData* isolate_data,
10231086
Local<ObjectTemplate> target) {
10241087
Isolate* isolate = isolate_data->isolate();
@@ -1051,6 +1114,10 @@ void ModuleWrap::CreatePerIsolateProperties(IsolateData* isolate_data,
10511114
target,
10521115
"setInitializeImportMetaObjectCallback",
10531116
SetInitializeImportMetaObjectCallback);
1117+
SetMethod(isolate,
1118+
target,
1119+
"createRequiredModuleFacade",
1120+
CreateRequiredModuleFacade);
10541121
}
10551122

10561123
void ModuleWrap::CreatePerContextProperties(Local<Object> target,
@@ -1091,6 +1158,8 @@ void ModuleWrap::RegisterExternalReferences(
10911158
registry->Register(GetStatus);
10921159
registry->Register(GetError);
10931160

1161+
registry->Register(CreateRequiredModuleFacade);
1162+
10941163
registry->Register(SetImportModuleDynamicallyCallback);
10951164
registry->Register(SetInitializeImportMetaObjectCallback);
10961165
}

‎src/module_wrap.h

+3
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,9 @@ class ModuleWrap : public BaseObject {
8888
std::optional<v8::ScriptCompiler::CachedData*> user_cached_data,
8989
bool* cache_rejected);
9090

91+
static void CreateRequiredModuleFacade(
92+
const v8::FunctionCallbackInfo<v8::Value>& args);
93+
9194
private:
9295
ModuleWrap(Realm* realm,
9396
v8::Local<v8::Object> object,

‎test/common/index.js

+7-2
Original file line numberDiff line numberDiff line change
@@ -964,9 +964,14 @@ function getPrintedStackTrace(stderr) {
964964
* @param {object} mod result returned by require()
965965
* @param {object} expectation shape of expected namespace.
966966
*/
967-
function expectRequiredModule(mod, expectation) {
967+
function expectRequiredModule(mod, expectation, checkESModule = true) {
968+
const clone = { ...mod };
969+
if (Object.hasOwn(mod, 'default') && checkESModule) {
970+
assert.strictEqual(mod.__esModule, true);
971+
delete clone.__esModule;
972+
}
968973
assert(isModuleNamespaceObject(mod));
969-
assert.deepStrictEqual({ ...mod }, { ...expectation });
974+
assert.deepStrictEqual(clone, { ...expectation });
970975
}
971976

972977
const common = {

‎test/es-module/test-require-module-default-extension.js

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
// Flags: --experimental-require-module
22
'use strict';
33

4-
require('../common');
4+
const { expectRequiredModule } = require('../common');
55
const assert = require('assert');
6-
const { isModuleNamespaceObject } = require('util/types');
76

87
const mod = require('../fixtures/es-modules/package-default-extension/index.mjs');
9-
assert.deepStrictEqual({ ...mod }, { entry: 'mjs' });
10-
assert(isModuleNamespaceObject(mod));
8+
expectRequiredModule(mod, { entry: 'mjs' });
119

1210
assert.throws(() => {
1311
const mod = require('../fixtures/es-modules/package-default-extension');

‎test/es-module/test-require-module-defined-esmodule.js

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Flags: --experimental-require-module
2+
'use strict';
3+
const common = require('../common');
4+
5+
// If an ESM already defines __esModule to be something else,
6+
// require(esm) should allow the user override.
7+
{
8+
const mod = require('../fixtures/es-modules/export-es-module.mjs');
9+
common.expectRequiredModule(
10+
mod,
11+
{ default: { hello: 'world' }, __esModule: 'test' },
12+
false,
13+
);
14+
}
15+
16+
{
17+
const mod = require('../fixtures/es-modules/export-es-module-2.mjs');
18+
common.expectRequiredModule(
19+
mod,
20+
{ default: { hello: 'world' }, __esModule: false },
21+
false,
22+
);
23+
}

‎test/es-module/test-require-module-dynamic-import-1.js

+1-2
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,7 @@ const { pathToFileURL } = require('url');
2121
const url = pathToFileURL(path.resolve(__dirname, id));
2222
const imported = await import(url);
2323
const required = require(id);
24-
assert.strictEqual(imported, required,
25-
`import()'ed and require()'ed result of ${id} was not reference equal`);
24+
common.expectRequiredModule(required, imported);
2625
}
2726

2827
const id = '../fixtures/es-modules/data-import.mjs';

‎test/es-module/test-require-module-dynamic-import-2.js

+1-2
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,7 @@ const path = require('path');
2121
const url = pathToFileURL(path.resolve(__dirname, id));
2222
const required = require(id);
2323
const imported = await import(url);
24-
assert.strictEqual(imported, required,
25-
`import()'ed and require()'ed result of ${id} was not reference equal`);
24+
common.expectRequiredModule(required, imported);
2625
}
2726

2827
const id = '../fixtures/es-modules/data-import.mjs';

‎test/es-module/test-require-module-dynamic-import-3.js

+1-2
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,9 @@
55
// be loaded by dynamic import().
66

77
const common = require('../common');
8-
const assert = require('assert');
98

109
(async () => {
1110
const required = require('../fixtures/es-modules/require-and-import/load.cjs');
1211
const imported = await import('../fixtures/es-modules/require-and-import/load.mjs');
13-
assert.deepStrictEqual({ ...required }, { ...imported });
12+
common.expectRequiredModule(required, imported);
1413
})().then(common.mustCall());

‎test/es-module/test-require-module-dynamic-import-4.js

+1-2
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,9 @@
55
// be loaded by require().
66

77
const common = require('../common');
8-
const assert = require('assert');
98

109
(async () => {
1110
const imported = await import('../fixtures/es-modules/require-and-import/load.mjs');
1211
const required = require('../fixtures/es-modules/require-and-import/load.cjs');
13-
assert.deepStrictEqual({ ...required }, { ...imported });
12+
common.expectRequiredModule(required, imported);
1413
})().then(common.mustCall());

0 commit comments

Comments
 (0)