Skip to main content

Module esm

Module esm 

Source
Expand description

ECMAScript modules (ECMA-262 §16.2) on the existing engine.

The pipeline, in the spec’s terms:

  • ParseModule — crate::parser::parse_module parses with the Module goal and analyze derives 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, InnerModuleEvaluation with the asynchronous-evaluation machinery for top-level await) are ported step for step in esm_loader.js, which drives the records this file produces through the @@esm.* natives in native.

  • InitializeEnvironment / ExecuteModule — lower turns 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/class bindings 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 TDZ ReferenceError. Every reference to an imported name is rewritten to %imp[k](), a call of the getter the loader resolved for import entry k; an assignment to one throws TypeError: 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§

ImportEntry
One [[ImportEntries]] record (16.2.1.6, Table 61).
IndirectExport
One indirect export (export { a as b } from "m", export * as ns from "m").
ModuleInfo
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 defaultLoad formats).
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: require is a lazily-bound global of this runtime, but in an ES module it is not defined at all. arguments is in the list too: module code runs inside the lowered function, whose own arguments the module’s top level must not see.
IMPORT_FN
The global the lowered import(…) calls (builtins::global_binding).
MAIN_FN
The global main_program calls.

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’s cjs-module-lexer detects statically, without running the module — exports.x = …, module.exports.x = …, Object.defineProperty(exports, "x", …), the keys of a module.exports = { a, b: … } literal — plus the names of a module it re-exports through module.exports = require("…").
detect_module
Node’s syntax detection, given the error the CommonJS (script-goal) compile of src failed 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 path DECLARES — by extension or its package scope’s "type" — or None when only its syntax can tell.
file_url
file:// URL of an absolute path, percent-encoded as pathToFileURL does.
has_module_syntax
Node’s syntax detection for a source of undeclared format.
is_namespace
Whether v is a module namespace object.
lower
Lower a parsed module body (see the module docs) to the function expression the loader instantiates. referrer is the module’s filename, which every import(…) in it resolves against; generator selects 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.js runMain).
namespace_refusal
V8’s TypeError for a refused op on property key of recv, when recv is a module namespace object.
native
The @@esm.<name> natives.
require_module
require() of an ES module file (node’s require(esm)): its namespace, or the value it exports under the name "module.exports".
reset
Drop every module record. Called from module::reset with the heap.
resolve
Resolve spec imported from the module file parent (None: the current directory, as for node -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 the exit event.