Stage 2 Draft / September 23, 2024

ECMAScript Module Phase Imports

1 ECMAScript Data Types and Values

1.1 ECMAScript Language Types

1.1.1 Object Type

1.1.1.1 Well-Known Intrinsic Objects

Well-known intrinsics are built-in objects that are explicitly referenced by the algorithms of this specification and which usually have realm-specific identities. Unless otherwise specified each intrinsic object actually corresponds to a set of similar objects, one per realm.

Within this specification a reference such as %name% means the intrinsic object, associated with the current realm, corresponding to the name. A reference such as %name.a.b% means, as if the "b" property of the value of the "a" property of the intrinsic object %name% was accessed prior to any ECMAScript code being evaluated. Determination of the current realm and its intrinsics is described in 9.4. The well-known intrinsics are listed in Table 1.

Table 1: Well-Known Intrinsic Objects
Intrinsic Name Global Name ECMAScript Language Association
%AbstractModuleSource% The %AbstractModuleSource% constructor (28.1.1)
%AggregateError% AggregateError The AggregateError constructor (20.5.7.1)
%Array% Array The Array constructor (23.1.1)
%ArrayBuffer% ArrayBuffer The ArrayBuffer constructor (25.1.3)
%ArrayIteratorPrototype% The prototype of Array iterator objects (23.1.5)
%AsyncFromSyncIteratorPrototype% The prototype of async-from-sync iterator objects (27.1.4)
%AsyncFunction% The constructor of async function objects (27.7.1)
%AsyncGeneratorFunction% The constructor of async generator function objects (27.4.1)
%AsyncGeneratorPrototype% The prototype of async generator objects (27.6)
%AsyncIteratorPrototype% An object that all standard built-in async iterator objects indirectly inherit from
%Atomics% Atomics The Atomics object (25.4)
%BigInt% BigInt The BigInt constructor (21.2.1)
%BigInt64Array% BigInt64Array The BigInt64Array constructor (23.2)
%BigUint64Array% BigUint64Array The BigUint64Array constructor (23.2)
%Boolean% Boolean The Boolean constructor (20.3.1)
%DataView% DataView The DataView constructor (25.3.2)
%Date% Date The Date constructor (21.4.2)
%decodeURI% decodeURI The decodeURI function (19.2.6.1)
%decodeURIComponent% decodeURIComponent The decodeURIComponent function (19.2.6.2)
%encodeURI% encodeURI The encodeURI function (19.2.6.3)
%encodeURIComponent% encodeURIComponent The encodeURIComponent function (19.2.6.4)
%Error% Error The Error constructor (20.5.1)
%eval% eval The eval function (19.2.1)
%EvalError% EvalError The EvalError constructor (20.5.5.1)
%FinalizationRegistry% FinalizationRegistry The FinalizationRegistry constructor (26.2.1)
%Float32Array% Float32Array The Float32Array constructor (23.2)
%Float64Array% Float64Array The Float64Array constructor (23.2)
%ForInIteratorPrototype% The prototype of For-In iterator objects (14.7.5.10)
%Function% Function The Function constructor (20.2.1)
%GeneratorFunction% The constructor of generator function objects (27.3.1)
%GeneratorPrototype% The prototype of generator objects (27.5)
%Int8Array% Int8Array The Int8Array constructor (23.2)
%Int16Array% Int16Array The Int16Array constructor (23.2)
%Int32Array% Int32Array The Int32Array constructor (23.2)
%isFinite% isFinite The isFinite function (19.2.2)
%isNaN% isNaN The isNaN function (19.2.3)
%IteratorPrototype% An object that all standard built-in iterator objects indirectly inherit from
%JSON% JSON The JSON object (25.5)
%Map% Map The Map constructor (24.1.1)
%MapIteratorPrototype% The prototype of Map iterator objects (24.1.5)
%Math% Math The Math object (21.3)
%ModuleSource% ModuleSource A ModuleSource object (28.1.4)
%Number% Number The Number constructor (21.1.1)
%Object% Object The Object constructor (20.1.1)
%parseFloat% parseFloat The parseFloat function (19.2.4)
%parseInt% parseInt The parseInt function (19.2.5)
%Promise% Promise The Promise constructor (27.2.3)
%Proxy% Proxy The Proxy constructor (28.2.1)
%RangeError% RangeError The RangeError constructor (20.5.5.2)
%ReferenceError% ReferenceError The ReferenceError constructor (20.5.5.3)
%Reflect% Reflect The Reflect object (28.1)
%RegExp% RegExp The RegExp constructor (22.2.4)
%RegExpStringIteratorPrototype% The prototype of RegExp String Iterator objects (22.2.9)
%Set% Set The Set constructor (24.2.1)
%SetIteratorPrototype% The prototype of Set iterator objects (24.2.5)
%SharedArrayBuffer% SharedArrayBuffer The SharedArrayBuffer constructor (25.2.2)
%String% String The String constructor (22.1.1)
%StringIteratorPrototype% The prototype of String iterator objects (22.1.5)
%Symbol% Symbol The Symbol constructor (20.4.1)
%SyntaxError% SyntaxError The SyntaxError constructor (20.5.5.4)
%ThrowTypeError% A function object that unconditionally throws a new instance of %TypeError%
%TypedArray% The super class of all typed Array constructors (23.2.1)
%TypeError% TypeError The TypeError constructor (20.5.5.5)
%Uint8Array% Uint8Array The Uint8Array constructor (23.2)
%Uint8ClampedArray% Uint8ClampedArray The Uint8ClampedArray constructor (23.2)
%Uint16Array% Uint16Array The Uint16Array constructor (23.2)
%Uint32Array% Uint32Array The Uint32Array constructor (23.2)
%URIError% URIError The URIError constructor (20.5.5.6)
%WeakMap% WeakMap The WeakMap constructor (24.3.1)
%WeakRef% WeakRef The WeakRef constructor (26.1.1)
%WeakSet% WeakSet The WeakSet constructor (24.4.1)
Note

Additional entries in Table 95.

13 ECMAScript Language: Expressions

13.3 Left-Hand-Side Expressions

Syntax

ImportCall[Yield, Await] : import ( AssignmentExpression[+In, ?Yield, ?Await] ) import . source ( AssignmentExpression[+In, ?Yield, ?Await] )

13.3.10 Import Calls

13.3.10.1 Runtime Semantics: Evaluation

ImportCall : import ( AssignmentExpression[+In, ?Yield, ?Await] )
  1. Return ? EvaluateImportCall(AssignmentExpression, evaluation).
 ImportCall : import . source ( AssignmentExpression[+In, ?Yield, ?Await] )
  1. Return ? EvaluateImportCall(AssignmentExpression, source).

13.3.10.2 EvaluateImportCall ( specifierExpression, phase )

The abstract operation EvaluateImportCall takes arguments specifierExpression (a Parse Node) and phase (source or evaluation) and returns either a normal completion containing a Promise or a throw completion. It performs the following steps when called:

  1. Let referrer be GetActiveScriptOrModule().
  2. If referrer is null, set referrer to the current Realm Record.
  3. Let specifierRef be ? Evaluation of evaluating specifierExpression.
  4. Let specifier be ? GetValue(specifierRef).
  5. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  6. If specifier is an Object, then
    1. Let module be Completion(HostGetModuleRecordFromSource(specifier)).
    2. IfAbruptRejectPromise(module, promiseCapability).
    3. If module is not not-a-source, then
      1. If module.[[Realm]] is not equal to current Realm Record, throw a TypeError exception.
      2. Perform ContinueDynamicImport(promiseCapability, phase, Completion(module)).
      3. Return promiseCapability.[[Promise]].
  7. Let specifierString be Completion(ToString(specifier)).
  8. IfAbruptRejectPromise(specifierString, promiseCapability).
  9. Let moduleRequest be a new ModuleRequest Record { [[Specifier]]: specifierString, [[Phase]]: phase }.
  10. Perform HostLoadImportedModule(referrer, moduleRequest, empty, promiseCapability).
  11. Return promiseCapability.[[Promise]].

13.3.11 ContinueDynamicImport ( promiseCapability, phase, moduleCompletion )

The abstract operation ContinueDynamicImport takes arguments promiseCapability (a PromiseCapability Record), phase (source or evaluation), and moduleCompletion (either a normal completion containing a Module Record or a throw completion) and returns unused. It completes the process of a dynamic import originally started by an import() call, resolving or rejecting the promise returned by that call as appropriate. It performs the following steps when called:

  1. If moduleCompletion is an abrupt completion, then
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « moduleCompletion.[[Value]] »).
    2. Return unused.
  2. Let module be moduleCompletion.[[Value]].
  3. If phase is source, then
    1. Let moduleSourceCompletion be Completion(module.GetModuleSource()).
    2. If moduleSourceCompletion is an abrupt completion, then
      1. Perform ! Call(promiseCapability.[[Reject]], undefined, « moduleSourceCompletion.[[Value]] »).
    3. Else,
      1. Perform ! Call(promiseCapability.[[Resolve]], undefined, « moduleSourceCompletion.[[Value]] »).
    4. Return unused.
  4. Let loadPromise be module.LoadRequestedModules().
  5. Let rejectedClosure be a new Abstract Closure with parameters (reason) that captures promiseCapability and performs the following steps when called:
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « reason »).
    2. Return unused.
  6. Let onRejected be CreateBuiltinFunction(rejectedClosure, 1, "", « »).
  7. Let linkAndEvaluateClosure be a new Abstract Closure with no parameters that captures module, promiseCapability, and onRejected and performs the following steps when called:
    1. Let link be Completion(module.Link()).
    2. If link is an abrupt completion, then
      1. Perform ! Call(promiseCapability.[[Reject]], undefined, « link.[[Value]] »).
      2. Return unused.
    3. Let evaluatePromise be module.Evaluate().
    4. Let fulfilledClosure be a new Abstract Closure with no parameters that captures module and promiseCapability and performs the following steps when called:
      1. Let namespace be GetModuleNamespace(module).
      2. Perform ! Call(promiseCapability.[[Resolve]], undefined, « namespace »).
      3. Return unused.
    5. Let onFulfilled be CreateBuiltinFunction(fulfilledClosure, "", 0, « »).
    6. Perform PerformPromiseThen(evaluatePromise, onFulfilled, onRejected).
  8. Let linkAndEvaluate be CreateBuiltinFunction(linkAndEvaluateClosure, "", 0, « »).
  9. Perform PerformPromiseThen(loadPromise, linkAndEvaluate, onRejected).
  10. Return unused.

16 ECMAScript Language: Scripts and Modules

16.1 Modules

16.1.1 Module Semantics

16.1.1.1 Abstract Module Records

A Module Record encapsulates structural information about the imports and exports of a single module. This information is used to link the imports and exports of sets of connected modules. A Module Record includes four fields that are only used when evaluating a module.

For specification purposes Module Record values are values of the Record specification type and can be thought of as existing in a simple object-oriented hierarchy where Module Record is an abstract class with both abstract and concrete subclasses. This specification defines the abstract subclass named Cyclic Module Record and its concrete subclass named Source Text Module Record. Other specifications and implementations may define additional Module Record subclasses corresponding to alternative module definition facilities that they defined.

Module Record defines the fields listed in Table 2. All Module Definition subclasses include at least those fields. Module Record also defines the abstract method list in Table 3. All Module definition subclasses must provide concrete implementations of these abstract methods.

Table 2: Module Record Fields
Field Name Value Type Meaning
[[Realm]] a Realm Record The Realm within which this module was created.
[[Environment]] a Module Environment Record or empty The Environment Record containing the top level bindings for this module. This field is set when the module is linked.
[[Namespace]] an Object or empty The Module Namespace Object (28.3) if one has been created for this module.
[[HostDefined]] anything (default value is undefined) Field reserved for use by host environments that need to associate additional information with a module.
Table 3: Abstract Methods of Module Records
Method Purpose
LoadRequestedModules( [ hostDefined ] )

Prepares the module for linking by recursively loading all its dependencies, and returns a promise.
Link()

Prepare the module for evaluation by transitively resolving all module dependencies and creating a Module Environment Record.

LoadRequestedModules must have completed successfully prior to invoking this method.
GetExportedNames([exportStarSet])

Return a list of all names that are either directly or indirectly exported from this module.

LoadRequestedModules must have completed successfully prior to invoking this method.
Evaluate()

Returns a promise for the evaluation of this module and its dependencies, resolving on successful evaluation or if it has already been evaluated successfully, and rejecting for an evaluation error or if it has already been evaluated unsuccessfully. If the promise is rejected, hosts are expected to handle the promise rejection and rethrow the evaluation error.

Link must have completed successfully prior to invoking this method.
ResolveExport(exportName [, resolveSet])

Return the binding of a name exported by this module. Bindings are represented by a ResolvedBinding Record, of the form { [[Module]]: Module Record, [[BindingName]]: String | namespace }. If the export is a Module Namespace Object without a direct binding in any module, [[BindingName]] will be set to namespace. Return null if the name cannot be resolved, or ambiguous if multiple bindings were found.

Each time this operation is called with a specific exportName, resolveSet pair as arguments it must return the same result.

LoadRequestedModules must have completed successfully prior to invoking this method.
GetDirectExports()

Returns a list of lists of the names of each direct export from this module, where each name is unique.
GetReexports()

Returns a list of reexports of this module. Reexports are represented by a Reexport Record, of the form { [[ExportName]]: String, [[ImportName]]: String | namespace, [[ModuleRequest]]: ModuleRequest Record }. Each exported name is unique and does not appear in any of the names returned by GetDirectExports().
GetStarExports()

Returns a list of ModuleRequest Records for the star exports of the module.
GetModuleSource()

It returns either a normal completion containing the Module Source Object corresponding to this source Module Record's source phase (28.1), or a throw completion.

When called multiple times on the same Module Record, if GetModuleSource() returns a normal completion it must always return a normal completion containing the same object.

The returned object should have a [[Prototype]] internal slot whose value is %AbstractModuleSource.prototype%.

For Module Records that do not have a source representation, GetModuleSource() must always return a throw completion whose [[Value]] is a ReferenceError.
GetModuleSourceName()

For Module Records that implement a normal completion for GetModuleSource(), returns a constant String for each concrete module record that exposes a source representation through GetModuleSource(), to be provided in the strongly branded return value of the @@toStringTag getter on %AbstractModuleSource%.

For Module Records that do not have a source representation, GetModuleSourceName() is never called.

16.1.1.1.1 GetStarExports ( )

The GetStarExports concrete method of an Abstract Module Record module takes no arguments and returns a List of Module Requests. It performs the following steps when called:

  1. Return a new empty List.
 Note

The default implementation of GetStarExports returns an empty list, while concrete Module Records may override this definition.

16.1.1.1.2 GetReexports ( )

The GetReexports concrete method of an Abstract Module Record module takes no arguments and returns a List of Module Requests. It performs the following steps when called:

  1. Return a new empty List.
 Note

The default implementation of GetReexports returns an empty list, while concrete Module Records may override this definition.

16.1.1.2 Cyclic Module Records

A Cyclic Module Record is used to represent information about a module that can participate in dependency cycles with other modules that are subclasses of the Cyclic Module Record type. Module Records that are not subclasses of the Cyclic Module Record type must not participate in dependency cycles with Source Text Module Records.

In addition to the fields defined in Table 2 Cyclic Module Records have the additional fields listed in Table 4

Table 4: Additional Fields of Cyclic Module Records
Field Name Value Type Meaning
[[Status]] unlinked, linking, linked, evaluating, evaluating-async, or evaluated Initially unlinked. Transitions to linking, linked, evaluating, possibly evaluating-async, evaluated (in that order) as the module progresses throughout its lifecycle. evaluating-async indicates this module is queued to execute on completion of its asynchronous dependencies or it is a module whose [[HasTLA]] field is true that has been executed and is pending top-level completion.
[[EvaluationError]] a throw completion or empty A throw completion representing the exception that occurred during evaluation. undefined if no exception occurred or if [[Status]] is not evaluated.
[[ModuleSource]] an Object or empty If this module has generated a module source object through GetModuleSource(), then this will be that object.
[[DFSIndex]] an integer or empty Auxiliary field used during Link and Evaluate only. If [[Status]] is linking or evaluating, this non-negative number records the point at which the module was first visited during the depth-first traversal of the dependency graph.
[[DFSAncestorIndex]] an integer or empty Auxiliary field used during Link and Evaluate only. If [[Status]] is linking or evaluating, this is either the module's own [[DFSIndex]] or that of an "earlier" module in the same strongly connected component.
[[RequestedModules]] a List of ModuleRequest Records A List of all the ModuleSpecifier strings used by the module represented by this record to request the importation of a module, along with their associated phase (source or evaluation). The List is in source text occurrence order.
[[CycleRoot]] a Cyclic Module Record or empty The first visited module of the cycle, the root DFS ancestor of the strongly connected component. For a module not in a cycle this would be the module itself. Once Evaluate has completed, a module's [[DFSAncestorIndex]] is equal to the [[DFSIndex]] of its [[CycleRoot]].
[[HasImportMeta]] a Boolean Whether this module contains an import.meta expression.
[[HasTLA]] a Boolean Whether this module is individually asynchronous (for example, if it's a Source Text Module Record containing a top-level await). Having an asynchronous dependency does not mean this field is true. This field must not change after the module is parsed.
[[AsyncEvaluation]] a Boolean Whether this module is either itself asynchronous or has an asynchronous dependency. Note: The order in which this field is set is used to order queued executions, see 16.2.1.5.3.4.
[[TopLevelCapability]] a PromiseCapability Record or empty If this module is the [[CycleRoot]] of some cycle, and Evaluate() was called on some module in that cycle, this field contains the PromiseCapability Record for that entire evaluation. It is used to settle the Promise object that is returned from the Evaluate() abstract method. This field will be empty for any dependencies of that module, unless a top-level Evaluate() has been initiated for some of those dependencies.
[[AsyncParentModules]] a List of Cyclic Module Records If this module or a dependency has [[HasTLA]] true, and execution is in progress, this tracks the parent importers of this module for the top-level execution job. These parent modules will not start executing before this module has successfully completed execution.
[[PendingAsyncDependencies]] an integer or empty If this module has any asynchronous dependencies, this tracks the number of asynchronous dependency modules remaining to execute for this module. A module with asynchronous dependencies will be executed when this field reaches 0 and there are no execution errors.

16.1.1.3 Source Text Module Records

16.1.1.3.1 ParseModule ( sourceText, realm, hostDefined )

The abstract operation ParseModule takes arguments sourceText (ECMAScript source text), realm (a Realm Record), and hostDefined (anything) and returns a Source Text Module Record or a non-empty List of SyntaxError objects. It creates a Source Text Module Record based upon the result of parsing sourceText as a Module. It performs the following steps when called:

  1. Let body be ParseText(sourceText, Module).
  2. If body is a List of errors, return body.
  3. Let requestedModules be the ModuleRequests of body.
  4. Let importEntries be ImportEntries of body.
  5. Let importedBoundNames be ImportedLocalNames(importEntries).
  6. Let indirectExportEntries be a new empty List.
  7. Let localExportEntries be a new empty List.
  8. Let starExportEntries be a new empty List.
  9. Let exportEntries be ExportEntries of body.
  10. For each ExportEntry Record ee of exportEntries, do
    1. If ee.[[ModuleRequest]] is null, then
      1. If importedBoundNames does not contain ee.[[LocalName]], then
        1. Append ee to localExportEntries.
      2. Else,
        1. Let ie be the element of importEntries whose [[LocalName]] is ee.[[LocalName]].
        2. If ie.[[ImportName]] is namespace-object, then
          1. NOTE: This is a re-export of an imported module namespace object.
          2. Append ee to localExportEntries.
        3. Else,
          1. NOTE: This is a re-export of a single name.
          2. Append the ExportEntry Record { [[ModuleRequest]]: ie.[[ModuleRequest]], [[ImportName]]: ie.[[ImportName]], [[LocalName]]: null, [[ExportName]]: ee.[[ExportName]] } to indirectExportEntries.
    2. Else if ee.[[ImportName]] is all-but-default, then
      1. Assert: ee.[[ExportName]] is null.
      2. Append ee to starExportEntries.
    3. Else,
      1. Append ee to indirectExportEntries.
  11. Let async be body Contains await.
  12. Let importMeta be body Contains ImportMeta.
  13. Return Source Text Module Record { [[Realm]]: realm, [[Environment]]: empty, [[Namespace]]: empty, [[ModuleSource]]: empty, [[CycleRoot]]: empty, [[HasImportMeta]]: importMeta, [[HasTLA]]: async, [[AsyncEvaluation]]: false, [[TopLevelCapability]]: empty, [[AsyncParentModules]]: « », [[PendingAsyncDependencies]]: empty, [[Status]]: new, [[EvaluationError]]: empty, [[HostDefined]]: hostDefined, [[ECMAScriptCode]]: body, [[Context]]: empty, [[ImportMeta]]: empty, [[RequestedModules]]: requestedModules, [[LoadedModules]]: « », [[ImportEntries]]: importEntries, [[LocalExportEntries]]: localExportEntries, [[IndirectExportEntries]]: indirectExportEntries, [[StarExportEntries]]: starExportEntries, [[DFSIndex]]: empty, [[DFSAncestorIndex]]: empty }.
 Note

An implementation may parse module source text and analyse it for Early Error conditions prior to the evaluation of ParseModule for that module source text. However, the reporting of any errors must be deferred until the point where this specification actually performs ParseModule upon that source text.

16.1.1.3.2 GetExportedNames ( optional exportStarSet: a List of Source Text Module Records, ): a List of Strings

GetDirectExports ( ): a List of Lists of Strings

for
a Source Text Module Record module
  1. Assert: module.[[Status]] is not new.
  2. If exportStarSet is not present, set exportStarSet to a new empty List.
  3. If exportStarSet contains module, then
    1. Assert: We've reached the starting point of an export * circularity.
    2. Return a new empty List.
  4. Append module to exportStarSet.
  5. Let exportedNames be a new empty List.
  6. For each ExportEntry Record e of module.[[LocalExportEntries]], do
    1. Assert: module provides the direct binding for this export.
    2. Assert: e.[[ExportName]] is not null a String.
    3. Append e.[[ExportName]] to exportedNames.
  7. For each ExportEntry Record e of module.[[StarExportEntries]], do
    1. Assert: e.[[ModuleRequest]] is not null.
    2. Let requestedModule be GetImportedModule(module, e.[[ModuleRequest]]).
    3. Let starNames be requestedModule.GetExportedNames(exportStarSet).
    4. For each element n of starNames, do
      1. If n is not "default", then
        1. If exportedNames does not contain n, then
          1. Append n to exportedNames.
  8. Return exportedNames.
 Note

GetExportedNamesGetDirectExports does not filter out or throw an exception for names that have ambiguous star export bindings.

16.1.1.3.3 GetReexports ( )

The GetReexports concrete method of a Source Text Module Record module takes no arguments and returns a List of Reexport Records. It performs the following steps when called:

  1. Let reexports be a new empty List.
  2. For each ExportEntry Record e of module.[[IndirectExportEntries]], do
    1. Assert: module imports a specific binding for this export.
    2. Assert: e.[[ExportName]] is a String.
    3. Assert: e.[[ImportName]] is not null.
    4. If e.[[ImportName]] is all, then
      1. Assert: e.[[ModuleRequest]] is not null.
      2. Assert: e.[[LocalName]] is null.
      3. Append the Reexport Record { [[ExportName]]: e.[[ExportName]], [[ImportName]]: null, [[ModuleRequest]]: e.[[ModuleRequest]] } to reexports.
    5. Else if e.[[ImportName]] is a String, then
      1. Assert: e.[[ImportName]] is a String.
      2. Assert: e.[[ModuleRequest]] is not null.
      3. Assert: e.[[LocalName]] is null.
      4. Append the Reexport Record { [[ExportName]]: e.[[ExportName]], [[ImportName]]: e.[[ImportName]], [[ModuleRequest]]: e.[[ModuleRequest]] } to reexports.
  3. Return reexports.

16.1.1.3.4 GetStarExports ( )

The GetStarExports concrete method of a Source Text Module Record module takes no arguments and returns a List of ModuleRequests. It performs the following steps when called:

  1. Let starExports be a new empty List.
  2. For each ExportEntry Record e of module.[[StarExportEntries]], do
    1. Assert: e.[[ModuleRequest]] is not null.
    2. Append e.[[ModuleRequest]] to starExports.
  3. Return starExports.

16.1.1.3.5 GetModuleSource ( )

The GetModuleSource concrete method of a Source Text Module Record module takes no arguments and returns either a normal completion containing an Object or a throw completion. It performs the following steps when called:

  1. Throw a ReferenceError exception.
  2. If module.[[ModuleSource]] is not empty, then
    1. Return module.[[ModuleSource]].
  3. Let moduleSource be OrdinaryObjectCreate(%ModuleSource.prototype%).
  4. Set moduleSource.[[SourceTextModuleRecord]] to module.
  5. Set module.[[ModuleSource]] to moduleSource.
  6. Return moduleSource.

16.1.1.4 HostGetModuleSourceName ( moduleSource )

The host-defined abstract operation HostGetModuleSourceName takes argument moduleSource (an Object) and returns either a normal completion containing a String or a throw completion.

An implementation of HostGetModuleSourceName must conform to the following requirements:

16.1.1.5 HostGetModuleRecordFromSource ( moduleSource )

The host-defined abstract operation HostGetModuleRecordFromSource takes argument moduleSource (an Object) and returns either a normal completion containing either a Module Record or not-a-source, or a throw completion.

An implementation of HostGetModuleRecordFromSource must conform to the following requirements:

  • For any object that is an instance of a concrete implementation of Abstract Module Source that was originally obtained through GetModuleSource, returns a normal completion for a concrete Module Record corresponding to the canonical module for this source.
  • For any ModuleSource Instance, this hook must always return the result of the GetModuleSourceSourceTextModuleRecord.
  • For any object which is a Module Source Object Instance, but was not originally obtained through GetModuleSource, returns a throw completion.
  • For any other object types, returns unused to indicate that the object is not a Module Source Object Instance.

16.1.1.6 GetModuleNamespace ( module )

The abstract operation GetModuleNamespace takes argument module (an instance of a concrete subclass of Module Record) and returns a Module Namespace Object or empty. It retrieves the Module Namespace Object representing module's exports, lazily creating it the first time it was requested, and storing it in module.[[Namespace]] for future retrieval. It performs the following steps when called:

  1. Assert: If module is a Cyclic Module Record, then module.[[Status]] is not new or unlinked.
  2. Let namespace be module.[[Namespace]].
  3. If namespace is empty, then
    1. Let exportedNames be module.GetExportedNames()GetExportedNames(module).
    2. Let exportStarSet be PopulateExportStarSet(module).
    3. For each element exportStarModule of exportStarSet, do
      1. Let starNames be exportStarModule.GetDirectExports().
      2. For each element n of starNames, do
        1. If n is not "default", then
          1. If exportedNames does not contain n, then
            1. Append n to exportedNames.
    4. Let unambiguousNames be a new empty List.
    5. For each element name of exportedNames, do
      1. Let resolution be module.ResolveExport(name).
      2. If resolution is a ResolvedBinding Record, append name to unambiguousNames.
    6. Set namespace to ModuleNamespaceCreate(module, unambiguousNames).
  4. Return namespace.
 Note

GetModuleNamespace never throws. Instead, unresolvable names are simply excluded from the namespace at this point. They will lead to a real linking error later unless they are all ambiguous star exports that are not explicitly requested anywhere.

16.1.1.6.1 GetExportedNames ( module )

The abstract operation GetExportedNames takes argument module (an Abstract Module Record.) and returns a List of Strings. Gathers the list of named exports of the module. It performs the following steps when called:

  1. Assert module.[[Status]] is not new.
  2. Let exportedNames be a new empty List.
  3. Let directExports be ! module.GetDirectExports().
  4. For each element directExportNames of directExports, do
    1. For each String exportName of directExportNames, do
      1. Assert: exportName does not already exist in directExports.
      2. Append exportName to directExports.
  5. Let reexports be ! module.GetReexports().
  6. For each Reexport Record reexport of reexports, do
    1. Append reexport.[[ExportName]] to exportedNames.
  7. Return exportedNames.
 Note

GetDirectExports and GetReexports must always be conformant to export name uniqueness without any duplicated export names between these lists.

16.1.1.6.2 PopulateExportStarSet ( module [ , exportStarSet ] )

The abstract operation PopulateExportStarSet takes argument module (An Abstract Module Record.) and optional argument exportStarSet (a List of Abstract Module Records) and returns a List of Strings. Walks the star export graph populating the module set. It performs the following steps when called:

  1. Assert: module.[[Status]] is not new.
  2. If exportStarSet is not present, set exportStarSet to a new empty List.
  3. If exportStarSet contains module, then
    1. Assert: We've reached the starting point of an export * circularity.
    2. Return a new empty List.
  4. Append module to exportStarSet.
  5. Let starExportRequests be ! module.GetStarExports().
  6. For each ModuleRequest request of starExportRequests, do
    1. Let requestedModule be GetImportedModule(module, request).
    2. Perform PopulateExportStarSet(requestedModule, exportStarSet).
  7. Return exportStarSet.
 Note

PopulateExportStarSet does not filter out or throw an exception for names that have ambiguous star export bindings.

28 Reflection

28.1 Module Source Objects

Module Source Objects represent modules in their source import phase, which are not linked, instantiated or executed.

A Module Source Object is an object for which HostGetModuleSourceNameHostGetModuleRecordFromSource returns a normal completion.

All Module Source Objects should have a prototype of %AbstractModuleSource%.prototype.

Hosts may define their own %AbstractModuleSource% subclasses for custom module types.

28.1.1 The %AbstractModuleSource% Constructor

The %AbstractModuleSource% constructor:

  • along with its corresponding prototype object, provides common properties that are inherited by Module Source constructors and their instances.
  • does not have a global name or appear as a property of the global object.
  • acts as a common superclass of the constructors of Module Source Objects.
  • will throw an error when invoked, because it is an abstract class constructor. The module source constructors do not perform a super call to it.

28.1.1.1 %AbstractModuleSource% ( )

This function performs the following steps when called:

  1. Throw a TypeError exception.

28.1.2 Properties of the %AbstractModuleSource% Intrinsic Object

The %AbstractModuleSource% intrinsic object:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has a "name" property whose value is "AbstractModuleSource".
  • has the following properties:

28.1.2.1 %AbstractModuleSource%.prototype

The initial value of %AbstractModuleSource%.prototype is the %AbstractModuleSource% prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

28.1.3 Properties of the %AbstractModuleSource% Prototype Object

The %AbstractModuleSource% prototype object:

28.1.3.1 %AbstractModuleSource%.prototype.constructor

The initial value of %AbstractModuleSource%.prototype.constructor is %AbstractModuleSource%.

28.1.3.2 get %AbstractModuleSource%.prototype [ @@toStringTag ]

%AbstractModuleSource%.prototype [@@toStringTag] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, return undefined.
  3. Let sourceNameResult be Completion(HostGetModuleSourceName(O)).
  4. If sourceNameResult is an abrupt completion, return undefined.
  5. Let name be ! sourceNameResult.
  6. Let moduleResult be Completion(HostGetModuleRecordFromSource(O)).
  7. If moduleResult is an abrupt completion, return undefined.
  8. Let module be ! moduleResult.
  9. If module is not-a-source, return undefined.
  10. Let name be module.GetModuleSourceName().
  11. Assert: name is a String.
  12. Return name.

This property has the attributes { [[Enumerable]]: false, [[Configurable]]: true }.

The initial value of the "name" property of this function is "get [Symbol.toStringTag]".

28.1.3.3 %AbstractModuleSource%.prototype.imports ( )

This method performs the following steps when called:

  1. Let M be the this value.
  2. Let module be ? HostGetModuleRecordFromSource(M).
  3. If module is not-a-source, throw a TypeError exception.
  4. Assert: module is a Cyclic Module Record.
  5. Let imports be a new empty List.
  6. For each ModuleRequest Record request of module.[[RequestedModules]], do
    1. Let import be OrdinaryObjectCreate(null).
    2. Perform ! CreateDataPropertyOrThrow(import, "specifier", request.[[Specifier]]).
    3. Let phase be request.[[Phase]].
    4. Let maybePhaseString be null.
    5. If phase is source, then
      1. Set maybePhaseString to "source".
    6. Perform ! CreateDataPropertyOrThrow(import, "phase", maybePhaseString).
    7. Append import to imports.
  7. Return CreateArrayFromList(imports).

28.1.3.4 %AbstractModuleSource%.prototype.exports ( )

This method performs the following steps when called:

  1. Let M be the this value.
  2. Let module be ? HostGetModuleRecordFromSource(M).
  3. If module is not-a-source, throw a TypeError exception.
  4. Assert: module is a Cyclic Module Record.
  5. Let exports be a new empty List.
  6. Let directExports be ! module.GetDirectExports().
  7. Let sortedDirectExports be a new List.
  8. For each list names in directExports, do
    1. Assert: The length of names is greater than 0.
    2. Let sortedNames be a List whose elements are the elements of names, sorted according to lexicographic code unit order.
    3. Append sortedNames to sortedDirectExports.
  9. Sort sortedDirectExports in lexicographic code unit order of the first element of each item.
  10. For each List names in sortedDirectExports, do
    1. Let directExport be OrdinaryObjectCreate(null).
    2. Perform ! CreateDataPropertyOrThrow(directExport, "type", "direct").
    3. Perform ! CreateDataPropertyOrThrow(directExport, "names", names).
    4. Append directExport to exports.
  11. Let reexports be ! module.GetReexports().
  12. Sort reexports in lexicographic code unit order of the [[ExportName]] field of each entry.
  13. For each Reexport Record reexportRecord of reexports, do
    1. Let reexport be OrdinaryObjectCreate(null).
    2. Perform ! CreateDataPropertyOrThrow(reexport, "type", "reexport").
    3. Perform ! CreateDataPropertyOrThrow(reexport, "name", reexportRecord.[[ExportName]]).
    4. If reexportRecord.[[ImportName]] is namespace, then
      1. Perform ! CreateDataPropertyOrThrow(reexport, "import", null).
    5. Else,
      1. Perform ! CreateDataPropertyOrThrow(reexport, "import", reexportRecord.[[ImportName]]).
    6. Perform ! CreateDataPropertyOrThrow(reexport, "from", reexportRecord.[[ModuleRequest]].[[Specifier]]).
    7. Append reexport to exports.
  14. Let starExportRequests be ! module.GetStarExports().
  15. Let starExportSpecifiers be an empty list.
  16. For each ModuleRequest request in starExportRequests, do
    1. Assert: request.[[Phase]] is instance.
    2. Append request.[[Specifier]] to starExportSpecifiers.
  17. Sort starExportSpecifiers in lexicographic code unit order.
  18. For each String specifier in _starExportSpecifiers, do
    1. Let starExport be OrdinaryObjectCreate(null).
    2. Perform ! CreateDataPropertyOrThrow(directExport, "type", "reexport-all").
    3. Perform ! CreateDataPropertyOrThrow(starExport, "from", specifier).
    4. Append starExport to exports.
  19. Return CreateArrayFromList(exports).
 Note

Direct exports each provide a "names" property for all aliases of the same export in order to allow distinguishing unique export slots of the module, which are semantically exposed in cases like ambiguous export detection.

Direct exports are sorted by first sorting the "names" property on each direct export entry lexicographically, and then the direct exports entries themselves are sorted based on the first item appearing in each entry's "names" property.

28.1.3.5 get AbstractModuleSource.prototype.hasImportMeta

AbstractModuleSource.prototype.hasImportMeta is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let M be the this value.
  2. Let module be ? HostGetModuleRecordFromSource(M).
  3. If module is not-a-source, throw a TypeError exception.
  4. Assert: module is a Cyclic Module Record.
  5. Return module.[[HasImportMeta]].

28.1.3.6 get AbstractModuleSource.prototype.hasTopLevelAwait

AbstractModuleSource.prototype.hasTopLevelAwait is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let M be the this value.
  2. Let module be ? HostGetModuleRecordFromSource(M).
  3. If module is not-a-source, throw a TypeError exception.
  4. Assert: module is a Cyclic Module Record.
  5. Return module.[[HasTLA]].

28.1.4 The %ModuleSource% Constructor

The %ModuleSource% constructor:

  • does not have a global name or appear as a property of the global object.
  • will throw an error when invoked, where support for dynamic construction may be added in future.

28.1.4.1 %ModuleSource% ( )

This function performs the following steps when called:

  1. Throw a TypeError exception.

28.1.5 Properties of the %ModuleSource% Prototype Object

The %ModuleSource% prototype object:

28.1.5.1 %ModuleSource%.prototype.constructor

The initial value of %ModuleSource%.prototype.constructor is %ModuleSource%.

28.1.6 Properties of ModuleSource Instances

ModuleSource instances are ordinary objects that inherit properties from the %ModuleSource% prototype object.

ModuleSource instances have a [[SourceTextModuleRecord]] internal slot.

28.1.7 Abstract Operations for ModuleSource Objects

28.1.7.1 GetModuleSourceSourceTextModuleRecord ( M )

The abstract operation GetModuleSourceSourceTextModuleRecord takes argument M (a ModuleSource Instance) and returns either a normal completion containing a Source Text Module Record, or a throw completion. It performs the following steps when called:

  1. Perform ? RequireInternalSlot(M, [[SourceTextModuleRecord]]).
  2. Return M.[[SourceTextModuleRecord]].
 Note

This abstract operation is the required implementation of HostGetModuleRecordFromSource for any object which is a ModuleSource Instance.

A Host Layering Points

A.1 Host Hooks

HostCallJobCallback(...)

HostEnqueueFinalizationRegistryCleanupJob(...)

HostEnqueueGenericJob(...)

HostEnqueuePromiseJob(...)

HostEnqueueTimeoutJob(...)

HostEnsureCanCompileStrings(...)

HostFinalizeImportMeta(...)

HostGetImportMetaProperties(...)

HostGetModuleSourceNameHostGetModuleRecordFromSource(...)

HostGrowSharedArrayBuffer(...)

HostHasSourceTextAvailable(...)

HostLoadImportedModule(...)

HostMakeJobCallback(...)

HostPromiseRejectionTracker(...)

HostResizeArrayBuffer(...)

InitializeHostDefinedRealm(...)

B Copyright & Software License

Copyright Notice

© 2024 Luca Casonato, Guy Bedford

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.