Expand description
ECMAScript modules (ECMA-262 §16.2) on the existing engine.
The pipeline, in the spec’s terms:
-
ParseModule —
crate::parser::parse_moduleparses with the Module goal andanalyzederives the module record’s static fields: its[[RequestedModules]],[[ImportEntries]], and the local / indirect / star export entries (16.2.1.6.1), with the early errors that depend on them (duplicate exports, exporting an undeclared name, an import binding colliding with a declaration). -
Link / Evaluate — the module-record algorithms (
InnerModuleLinking,ResolveExport,GetExportedNames,InnerModuleEvaluationwith the asynchronous-evaluation machinery for top-levelawait) are ported step for step inesm_loader.js, which drives the records this file produces through the@@esm.*natives innative. -
InitializeEnvironment / ExecuteModule —
lowerturns a module body into one ordinary function the compiler already knows how to build:(function [*] (%imp, %meta, %reg) { %reg([() => local₀, () => local₁, …]); // the export bindings [yield;] // only for a module in a cycle …body… })The function’s scope IS the module environment: its hoisted function declarations exist on entry and its
let/const/classbindings sit in their temporal dead zone until evaluation reaches them. Each exported binding is handed to the loader as a getter closure over that scope, so a read is always the binding’s CURRENT value (a live binding), and a read before initialisation throws the TDZReferenceError. Every reference to an imported name is rewritten to%imp[k](), a call of the getter the loader resolved for import entryk; an assignment to one throwsTypeError: Assignment to constant variable.(an import binding is immutable, 9.1.1.5.5). A module that is part of an import cycle is built as a GENERATOR instead, so the loader can run its prologue — creating the environment and registering its getters — before any module in the cycle evaluates, which is what lets a cycle call a hoisted function of a module that has not started yet. An acyclic module runs as a plain function, on the ordinary stack.
Structs§
- Import
Entry - One
[[ImportEntries]]record (16.2.1.6, Table 61). - Indirect
Export - One indirect export (
export { a as b } from "m",export * as ns from "m"). - Module
Info - The static half of a Source Text Module Record.
- Resolved
- A module the resolver found: its URL (the module-map key), its file (empty for a builtin), and its format.
Enums§
- Format
- What a resolved module is (node’s
defaultLoadformats). - Refused
- The refused-write operations of a module namespace object, which V8 reports in its own words rather than as a proxy trap’s.
Constants§
- CJS_
FREE_ PREFIX - Prefix a free reference to a CommonJS wrapper name gets in module code, so
that it resolves to nothing:
requireis a lazily-bound global of this runtime, but in an ES module it is not defined at all.argumentsis in the list too: module code runs inside the lowered function, whose ownargumentsthe module’s top level must not see. - IMPORT_
FN - The global the lowered
import(…)calls (builtins::global_binding). - MAIN_FN
- The global
main_programcalls.
Functions§
- analyze
- ParseModule’s static semantics for
stmts(16.2.1.6.1), plus the module early errors (16.2.1.1). - cjs_
export_ names - The names an
import { … }of a CommonJS module may use: the exports node’scjs-module-lexerdetects statically, without running the module —exports.x = …,module.exports.x = …,Object.defineProperty(exports, "x", …), the keys of amodule.exports = { a, b: … }literal — plus the names of a module it re-exports throughmodule.exports = require("…"). - detect_
module - Node’s syntax detection, given the error the CommonJS (script-goal)
compile of
srcfailed with: the source is an ES module when module syntax explains that error and the module-goal parse succeeds. - file_
format - The format of the file at
path(ESM_FILE_FORMAT): by extension, then by the package scope’s"type", then by syntax detection. - file_
format_ declared - The format
pathDECLARES — by extension or its package scope’s"type"— orNonewhen only its syntax can tell. - file_
url file://URL of an absolute path, percent-encoded aspathToFileURLdoes.- has_
module_ syntax - Node’s syntax detection for a source of undeclared format.
- is_
namespace - Whether
vis a module namespace object. - lower
- Lower a parsed module body (see the module docs) to the function
expression the loader instantiates.
referreris the module’s filename, which everyimport(…)in it resolves against;generatorselects the form a module in an import cycle needs. - main_
program - The statements that run an ES module ENTRY point: one call that loads and
links its graph and queues its evaluation (
esm_loader.jsrunMain). - namespace_
refusal - V8’s
TypeErrorfor a refusedopon propertykeyofrecv, whenrecvis a module namespace object. - native
- The
@@esm.<name>natives. - require_
module require()of an ES module file (node’srequire(esm)): its namespace, or the value it exports under the name"module.exports".- reset
- Drop every module record. Called from
module::resetwith the heap. - resolve
- Resolve
specimported from the module fileparent(None: the current directory, as fornode -e). - settle_
unfinished_ entry - When the event loop has drained with the ENTRY module still suspended in a
top-level
await, node warns and exits 13 (unless the program chose an exit code). Called once the loop is empty, before theexitevent.