ECMAScript Language: Expressions
@@ -327,10 +23,11 @@ contributors: Guy Bedford, Marco Ippolito ImportCall[Yield, Await] : `import` ImportCallArguments[?Yield, ?Await] `import` `.` `defer` ImportCallArguments[?Yield, ?Await] + `import` `.` `sync` ImportCallArguments[?Yield, ?Await] - ImportCallArguments[Yield, Await] : - `(` AssignmentExpression[+In, ?Yield, ?Await] `,`? `)` - `(` AssignmentExpression[+In, ?Yield, ?Await] `,` AssignmentExpression[+In, ?Yield, ?Await] `,`? `)` + ImportCallArguments[Yield, Await] : + `(` AssignmentExpression[+In, ?Yield, ?Await] `,`? `)` + `(` AssignmentExpression[+In, ?Yield, ?Await] `,` AssignmentExpression[+In, ?Yield, ?Await] `,`? `)`Runtime Semantics: EvaluateImportCallSpecifier
- -Runtime Semantics: EvaluateImportCallOptions
- -- EvaluateImportCall ( - _arguments_: a Parse Node, - _phase_: ~defer~ or ~evaluation~, - ): either a normal completion containing a Promise or an abrupt completion + ImportCallSync ( + _arguments_: a Parse Node + ): either a normal completion or an abrupt completion
- ContinueDynamicImport ( - _promiseCapability_: a PromiseCapability Record, - _moduleCompletion_: either a normal completion containing a Module Record or a throw completion, - _phase_: ~defer~ or ~evaluation~, - ): ~unused~ -
--
-
- description -
- 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.
-
Module Semantics
-ModuleRequest Records
- -A ModuleRequest Record represents the request to import a module with given import attributes and import phase. It consists of the following fields:
-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
| Field Name @@ -538,157 +155,321 @@ contributors: Guy Bedford, Marco Ippolito 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 ( |
+
| + [[HostDefined]] + | ++ anything (default value is *undefined*) + | ++ Field reserved for use by host environments that need to associate additional information with a module. + | +
| - [[Specifier]] - | -- a String - | -- The module specifier - | -||
| - [[Attributes]] - | -- a List of ImportAttribute Records - | -- The import attributes - | -||
| - [[Phase]] - | -- ~defer~ or ~evaluation~ - | -- The target import phase - | ++ Method + | ++ Purpose + |
|---|---|---|---|---|
| + LoadRequestedModules([_hostDefined_]) + | +
+ Prepares the module for linking by recursively loading all its dependencies, and returns a promise. + |
+ |||
| + LoadRequestedModulesSync([_hostDefined_]) + | +
+ Prepares the module for linking by recursively loading all its dependencies synchronously. + |
+ |||
| + 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. + |
+ |||
| + 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. + |
+ |||
| + 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. + |
+ |||
| + 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. + |
+
- ModuleRequestsEqual ( - _left_: a ModuleRequest Record or a LoadedModuleRequest Record, - _right_: a ModuleRequest Record or a LoadedModuleRequest Record, - ): a Boolean + EvaluateModuleSync ( + _module_: a Module Record, + ): either a normal completion containing ~unused~ or a throw completion
- description -
- It checks whether the two ModuleRequest Records have the same specifier and attributes. +
- It synchronously evaluates _module_, provided that the caller guarantees that _module_'s evaluation will return an already settled promise.
Static Semantics: ModuleRequests ( ): a List of ModuleRequest Records
--
-
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
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
| + Field Name + | ++ Value Type + | ++ Meaning + | +
|---|---|---|
| + [[Status]] + | ++ ~new~, ~unlinked~, ~linking~, ~linked~, ~evaluating~, ~evaluating-async~, or ~evaluated~ + | ++ Initially ~new~. Transitions to ~unlinked~, ~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~. + | +
| + [[DFSAncestorIndex]] + | ++ an integer or ~empty~ + | ++ Auxiliary field used during Link and Evaluate only. If [[Status]] is either ~linking~ or ~evaluating~, this is either the module's depth-first traversal index or that of an "earlier" module in the same strongly connected component. + | +
| + [[RequestedModules]] + | ++ a List of ModuleRequest Records + | ++ A List of the ModuleRequest Records associated with the imports in this module. The List is in source text occurrence order of the imports. + | +
| + [[LoadedModules]] + | ++ a List of LoadedModuleRequest Records + | ++ A map from the specifier strings used by the module represented by this record to request the importation of a module with the relative import attributes to the resolved Module Record. The list does not contain two different Records _r1_ and _r2_ such that ModuleRequestsEqual(_r1_, _r2_) is *true*. + | +
| + [[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 the depth-first traversal index of its [[CycleRoot]]. + | +
| + [[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. + | +
| + [[AsyncEvaluationOrder]] + | ++ ~unset~, an integer, or ~done~ + | +
+ This field is initially set to ~unset~, and remains ~unset~ for fully synchronous modules. For modules that are either themselves asynchronous or have an asynchronous dependency, it is set to an integer that determines the order in which execution of pending modules is queued by |
+
| + [[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. + | +
In addition to the methods defined in
| + Method + | ++ Purpose + | +
|---|---|
| + InitializeEnvironment() + | ++ Initialize the Environment Record of the module, including resolving all imported bindings, and create the module's execution context. + | +
| + ExecuteModule( [ _promiseCapability_ ] ) + | ++ Evaluate the module's code within its execution context. If this module has *true* in [[HasTLA]], then a PromiseCapability Record is passed as an argument, and the method is expected to resolve or reject the given capability. In this case, the method must not throw an exception, but instead reject the PromiseCapability Record if necessary. + | +
A GraphLoadingState Record is a Record that contains information about the loading process of a module graph. It's used to continue loading after a call to HostLoadImportedModule. Each GraphLoadingState Record has the fields defined in
| - [[Realm]] + [[PromiseCapability]] | - a Realm Record + a PromiseCapability Record or ~syncImport~ | - The Realm within which this module was created. + The promise to resolve when the loading process finishes, or ~syncImport~ for a synchronous loading operation. |
| - [[Environment]] + [[IsLoading]] | - a Module Environment Record or ~empty~ + a Boolean | - The Environment Record containing the top level bindings for this module. This field is set when the module is linked. + It is true if the loading process has not finished yet, neither successfully nor with an error. |
| - [[Namespace]] + [[PendingModulesCount]] | - an Object or ~empty~ + a non-negative integer |
- The Module Namespace Object ( |
| - [[DeferredNamespace]] + [[Visited]] | - an Object or ~empty~ + a List of Cyclic Module Records |
- The Module Namespace Object ( |
| - anything (default value is *undefined*) + anything (default value is ~empty~) | - Field reserved for use by host environments that need to associate additional information with a module. + It contains host-defined data to pass from the LoadRequestedModules caller to HostLoadImportedModule. |
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.
@@ -776,8 +551,41 @@ contributors: Guy Bedford, Marco Ippolito
- for
- a Cyclic Module Record _module_
+
+ - description
+ - It populates the [[LoadedModules]] of all the Module Records in the dependency graph of _module_ (most of the work is done by the auxiliary function InnerModuleLoading). It takes an optional _hostDefined_ parameter that is passed to the HostLoadImportedModule hook.
+
+ 1. If _hostDefined_ is not present, let _hostDefined_ be ~empty~.
+ 1. Let _pc_ be ! NewPromiseCapability(%Promise%).
+ 1. Let _state_ be the GraphLoadingState Record { [[IsLoading]]: *true*, [[PendingModulesCount]]: 1, [[Visited]]: « », [[PromiseCapability]]: _pc_, [[HostDefined]]: _hostDefined_ }.
+ 1. Perform InnerModuleLoading(_state_, _module_).
+ 1. Return _pc_.[[Promise]].
+
+
+
+ The _hostDefined_ parameter can be used to pass additional information necessary to fetch the imported modules. It is used, for example, by HTML to set the correct fetch destination for <link rel="preload" as="..."> tags.
+ import() expressions never set the _hostDefined_ parameter.
+
+
+
+
+ InnerModuleLoadingSync (
+ _state_: a GraphLoadingState Record,
+ _module_: a Module Record,
+ ): ~unused~
+
+
+ - description
+ - It is used by LoadRequestedModules to recursively perform the actual loading process for _module_'s dependency graph.
+
+
+
+ 1. TODO.
+
+
+
InnerModuleLoading (
@@ -786,35 +594,58 @@ contributors: Guy Bedford, Marco Ippolito
): ~unused~
+ - description
+ - It is used by LoadRequestedModules to recursively perform the actual loading process for _module_'s dependency graph.
-
- There is no special handling for ModuleRequests whose [[Phase]] is ~defer~: any error from loading or parsing the corresponding modules will make InnerModuleLoading fail.
-
+
+ 1. Assert: _state_.[[IsLoading]] is *true*.
+ 1. If _module_ is a Cyclic Module Record, _module_.[[Status]] is ~new~, and _state_.[[Visited]] does not contain _module_, then
+ 1. Append _module_ to _state_.[[Visited]].
+ 1. Let _requestedModulesCount_ be the number of elements in _module_.[[RequestedModules]].
+ 1. Set _state_.[[PendingModulesCount]] to _state_.[[PendingModulesCount]] + _requestedModulesCount_.
+ 1. For each ModuleRequest Record _request_ of _module_.[[RequestedModules]], do
+ 1. If AllImportAttributesSupported(_request_.[[Attributes]]) is *false*, then
+ 1. Let _error_ be ThrowCompletion(a newly created *SyntaxError* object).
+ 1. Perform ContinueModuleLoading(_state_, _error_).
+ 1. Else if _module_.[[LoadedModules]] contains a LoadedModuleRequest Record _record_ such that ModuleRequestsEqual(_record_, _request_) is *true*, then
+ 1. Perform InnerModuleLoading(_state_, _record_.[[Module]]).
+ 1. Else,
+ 1. Perform HostLoadImportedModule(_module_, _request_, _state_.[[HostDefined]], _state_).
+ 1. NOTE: HostLoadImportedModule will call FinishLoadingImportedModule, which re-enters the graph loading process through ContinueModuleLoading.
+ 1. If _state_.[[IsLoading]] is *false*, return ~unused~.
+ 1. Assert: _state_.[[PendingModulesCount]] ≥ 1.
+ 1. Set _state_.[[PendingModulesCount]] to _state_.[[PendingModulesCount]] - 1.
+ 1. If _state_.[[PendingModulesCount]] = 0, then
+ 1. Set _state_.[[IsLoading]] to *false*.
+ 1. For each Record _loaded_ of _state_.[[Visited]], do
+ 1. If _loaded_.[[Status]] is ~new~, set _loaded_.[[Status]] to ~unlinked~.
+ 1. Perform ! Call(_state_.[[PromiseCapability]].[[Resolve]], *undefined*, « *undefined* »).
+ 1. Return ~unused~.
+
-
<link rel="preload" as="..."> tags.
+ import() expressions never set the _hostDefined_ parameter.
+ + InnerModuleLoadingSync ( + _state_: a GraphLoadingState Record, + _module_: a Module Record, + ): ~unused~ +
+-
+
- description +
- It is used by LoadRequestedModules to recursively perform the actual loading process for _module_'s dependency graph. +
InnerModuleLoading ( @@ -786,35 +594,58 @@ contributors: Guy Bedford, Marco Ippolito ): ~unused~
-
+
- description +
- It is used by LoadRequestedModules to recursively perform the actual loading process for _module_'s dependency graph.
Link ( ): either a normal completion containing ~unused~ or a throw completion
--
-
- for -
- a Cyclic Module Record _module_ -
- InnerModuleLinking ( - _module_: a Module Record, - _stack_: a List of Cyclic Module Records, - _index_: a non-negative integer, - ): either a normal completion containing a non-negative integer or a throw completion + ContinueModuleLoading ( + _state_: a GraphLoadingState Record, + _moduleCompletion_: either a normal completion containing a Module Record or a throw completion, + ): ~unused~
-
+
- description +
- It is used to re-enter the loading process after a call to HostLoadImportedModule.
- description -
- It is used by Evaluate to perform the actual evaluation process for _module_, as well as recursively on all other modules in the dependency graph. The _stack_ and _index_ parameters, as well as _module_'s [[DFSIndex]] and [[DFSAncestorIndex]] fields, are used the same way as in InnerModuleLinking. +
- It is used by Evaluate to perform the actual evaluation process for _module_, as well as recursively on all other modules in the dependency graph. The _stack_ and _index_ parameters, as well as _module_'s [[DFSAncestorIndex]] field, are used the same way as in InnerModuleLinking.
- EvaluateSync ( - _module_: a Module Record, - ): either a normal completion containing ~unused~ or a throw completion -
--
-
- description -
- It synchronously evaluates _module_ provided it is ready for synchronous execution. -
- GatherAsynchronousTransitiveDependencies ( - _module_: a Module Record, - optional _seen_: a List of Module Records - ): a List of Module Records + GatherAsynchronousTransitiveDependencies ( + _module_: a Module Record, + optional _seen_: a List of Module Records + ): a List of Module Records
- description @@ -983,8 +791,8 @@ contributors: Guy Bedford, Marco Ippolito 1. If _module_.[[HasTLA]] is *true*, then 1. Append _module_ to _result_. 1. Return _result_. - 1. For each ModuleRequest Record _request_ of _module_.[[RequestedModules]], do - 1. Let _requiredModule_ be GetImportedModule(_module_, _request_). + 1. For each ModuleRequest Record _required_ of _module_.[[RequestedModules]], do + 1. Let _requiredModule_ be GetImportedModule(_module_, _required_). 1. Let _additionalModules_ be GatherAsynchronousTransitiveDependencies(_requiredModule_, _seen_). 1. For each Module Record _m_ of _additionalModules_, do 1. If _result_ does not contain _m_, append _m_ to _result_. @@ -992,734 +800,60 @@ contributors: Guy Bedford, Marco Ippolito
Example Cyclic Module Record Graphs
- -This non-normative section gives a series of examples of the linking and evaluation of a few common module graphs, with a specific focus on how errors can occur.
- -First consider the following simple module graph:
- -
- Let's first assume that there are no error conditions. When a host first calls _A_.LoadRequestedModules(), this will complete successfully by assumption, and recursively load the dependencies of _B_ and _C_ as well (respectively, _C_ and none), and then set _A_.[[Status]] = _B_.[[Status]] = _C_.[[Status]] = ~unlinked~. Then, when the host calls _A_.Link(), it will complete successfully (again by assumption) such that _A_.[[Status]] = _B_.[[Status]] = _C_.[[Status]] = linked. These preparatory steps can be performed at any time. Later, when the host is ready to incur any possible side effects of the modules, it can call _A_.Evaluate(), which will complete successfully, returning a Promise resolving to *undefined* (again by assumption), recursively having evaluated first _C_ and then _B_. Each module's [[Status]] at this point will be ~evaluated~.
- -Consider then cases involving linking errors, after a successful call to _A_.LoadRequestedModules(). If InnerModuleLinking of _C_ succeeds but, thereafter, fails for _B_, for example because it imports something that _C_ does not provide, then the original _A_.Link() will fail, and both _A_ and _B_'s [[Status]] remain ~unlinked~. _C_'s [[Status]] has become ~linked~, though.
- -Finally, consider a case involving evaluation errors after a successful call to Link(). If InnerModuleEvaluation of _C_ succeeds but, thereafter, fails for _B_, for example because _B_ contains code that throws an exception, then the original _A_.Evaluate() will fail, returning a rejected Promise. The resulting exception will be recorded in both _A_ and _B_'s [[EvaluationError]] fields, and their [[Status]] will become ~evaluated~. _C_ will also become ~evaluated~ but, in contrast to _A_ and _B_, will remain without an [[EvaluationError]], as it successfully completed evaluation. Storing the exception ensures that any time a host tries to reuse _A_ or _B_ by calling their Evaluate() method, it will encounter the same exception. (Hosts are not required to reuse Cyclic Module Records; similarly, hosts are not required to expose the exception objects thrown by these methods. However, the specification enables such uses.)
- -Now consider a different type of error condition:
- -
- In this scenario, module _A_ declares a dependency on some other module, but no Module Record exists for that module, i.e. HostLoadImportedModule calls FinishLoadingImportedModule with an exception when asked for it. This could occur for a variety of reasons, such as the corresponding resource not existing, or the resource existing but ParseModule returning some errors when trying to parse the resulting source text. Hosts can choose to expose the cause of failure via the completion they pass to FinishLoadingImportedModule. In any case, this exception causes a loading failure, which results in _A_'s [[Status]] remaining ~new~.
- -The difference here between loading, linking and evaluation errors is due to the following characteristic:
--
-
- Evaluation must be only performed once, as it can cause side effects; it is thus important to remember whether evaluation has already been performed, even if unsuccessfully. (In the error case, it makes sense to also remember the exception because otherwise subsequent Evaluate() calls would have to synthesize a new one.) -
- Linking, on the other hand, is side-effect-free, and thus even if it fails, it can be retried at a later time with no issues. -
- Loading closely interacts with the host, and it may be desiderable for some of them to allow users to retry failed loads (for example, if the failure is caused by temporarily bad network conditions). -
Now, consider a module graph with a cycle:
- -
- Here we assume that the entry point is module _A_, so that the host proceeds by calling _A_.LoadRequestedModules(), which performs InnerModuleLoading on _A_. This in turn calls InnerModuleLoading on _B_ and _C_. Because of the cycle, this again triggers InnerModuleLoading on _A_, but at this point it is a no-op since _A_'s dependencies loading has already been triggered during this LoadRequestedModules process. When all the modules in the graph have been successfully loaded, their [[Status]] transitions from ~new~ to ~unlinked~ at the same time.
- -Then the host proceeds by calling _A_.Link(), which performs InnerModuleLinking on _A_. This in turn calls InnerModuleLinking on _B_. Because of the cycle, this again triggers InnerModuleLinking on _A_, but at this point it is a no-op since _A_.[[Status]] is already ~linking~. _B_.[[Status]] itself remains ~linking~ when control gets back to _A_ and InnerModuleLinking is triggered on _C_. After this returns with _C_.[[Status]] being ~linked~, both _A_ and _B_ transition from ~linking~ to ~linked~ together; this is by design, since they form a strongly connected component. It's possible to transition the status of modules in the same SCC at the same time because during this phase the module graph is traversed with a depth-first search.
- -An analogous story occurs for the evaluation phase of a cyclic module graph, in the success case.
- -Now consider a case where _A_ has a linking error; for example, it tries to import a binding from _C_ that does not exist. In that case, the above steps still occur, including the early return from the second call to InnerModuleLinking on _A_. However, once we unwind back to the original InnerModuleLinking on _A_, it fails during InitializeEnvironment, namely right after _C_.ResolveExport(). The thrown *SyntaxError* exception propagates up to _A_.Link, which resets all modules that are currently on its _stack_ (these are always exactly the modules that are still ~linking~). Hence both _A_ and _B_ become ~unlinked~. Note that _C_ is left as ~linked~.
- -Alternatively, consider a case where _A_ has an evaluation error; for example, its source code throws an exception. In that case, the evaluation-time analog of the above steps still occurs, including the early return from the second call to InnerModuleEvaluation on _A_. However, once we unwind back to the original InnerModuleEvaluation on _A_, it fails by assumption. The exception thrown propagates up to _A_.Evaluate(), which records the error in all modules that are currently on its _stack_ (i.e., the modules that are still ~evaluating~) as well as via [[AsyncParentModules]], which form a chain for modules which contain or depend on top-level `await` through the whole dependency graph through the AsyncModuleExecutionRejected algorithm. Hence both _A_ and _B_ become ~evaluated~ and the exception is recorded in both _A_ and _B_'s [[EvaluationError]] fields, while _C_ is left as ~evaluated~ with no [[EvaluationError]].
- -Lastly, consider a module graph with a cycle, where all modules complete asynchronously:
-
- Loading and linking happen as before, and all modules end up with [[Status]] set to ~linked~.
- -Calling _A_.Evaluate() calls InnerModuleEvaluation on _A_, _B_, and _D_, which all transition to ~evaluating~. Then InnerModuleEvaluation is called on _A_ again, which is a no-op because it is already ~evaluating~. At this point, _D_.[[PendingAsyncDependencies]] is 0, so ExecuteAsyncModule(_D_) is called and we call _D_.ExecuteModule with a new PromiseCapability tracking the asynchronous execution of _D_. We unwind back to the InnerModuleEvaluation on _B_, setting _B_.[[PendingAsyncDependencies]] to 1 and _B_.[[AsyncEvaluation]] to *true*. We unwind back to the original InnerModuleEvaluation on _A_, setting _A_.[[PendingAsyncDependencies]] to 1. In the next iteration of the loop over _A_'s dependencies, we call InnerModuleEvaluation on _C_ and thus on _D_ (again a no-op) and _E_. As _E_ has no dependencies and is not part of a cycle, we call ExecuteAsyncModule(_E_) in the same manner as _D_ and _E_ is immediately removed from the stack. We unwind once more to the original InnerModuleEvaluation on _A_, setting _C_.[[AsyncEvaluation]] to *true*. Now we finish the loop over _A_'s dependencies, set _A_.[[AsyncEvaluation]] to *true*, and remove the entire strongly connected component from the stack, transitioning all of the modules to ~evaluating-async~ at once. At this point, the fields of the modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluating-async~ | -*true* | -« » | -2 (_B_ and _C_) | -
| _B_ | -1 | -0 | -~evaluating-async~ | -*true* | -« _A_ » | -1 (_D_) | -
| _C_ | -2 | -0 | -~evaluating-async~ | -*true* | -« _A_ » | -2 (_D_ and _E_) | -
| _D_ | -3 | -0 | -~evaluating-async~ | -*true* | -« _B_, _C_ » | -0 | -
| _E_ | -4 | -4 | -~evaluating-async~ | -*true* | -« _C_ » | -0 | -
Let us assume that _E_ finishes executing first. When that happens, AsyncModuleExecutionFulfilled is called, _E_.[[Status]] is set to ~evaluated~ and _C_.[[PendingAsyncDependencies]] is decremented to become 1. The fields of the updated modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|---|---|
| _C_ | -2 | -0 | -~evaluating-async~ | -*true* | -« _A_ » | -1 (_D_) | -
| _E_ | -4 | -4 | -~evaluated~ | -*true* | -« _C_ » | -0 | -
_D_ is next to finish (as it was the only module that was still executing). When that happens, AsyncModuleExecutionFulfilled is called again and _D_.[[Status]] is set to ~evaluated~. Then _B_.[[PendingAsyncDependencies]] is decremented to become 0, ExecuteAsyncModule is called on _B_, and it starts executing. _C_.[[PendingAsyncDependencies]] is also decremented to become 0, and _C_ starts executing (potentially in parallel to _B_ if _B_ contains an `await`). The fields of the updated modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|---|---|
| _B_ | -1 | -0 | -~evaluating-async~ | -*true* | -« _A_ » | -0 | -
| _C_ | -2 | -0 | -~evaluating-async~ | -*true* | -« _A_ » | -0 | -
| _D_ | -3 | -0 | -~evaluated~ | -*true* | -« _B_, _C_ » | -0 | -
Let us assume that _C_ finishes executing next. When that happens, AsyncModuleExecutionFulfilled is called again, _C_.[[Status]] is set to ~evaluated~ and _A_.[[PendingAsyncDependencies]] is decremented to become 1. The fields of the updated modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluating-async~ | -*true* | -« » | -1 (_B_) | -
| _C_ | -2 | -0 | -~evaluated~ | -*true* | -« _A_ » | -0 | -
Then, _B_ finishes executing. When that happens, AsyncModuleExecutionFulfilled is called again and _B_.[[Status]] is set to ~evaluated~. _A_.[[PendingAsyncDependencies]] is decremented to become 0, so ExecuteAsyncModule is called and it starts executing. The fields of the updated modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluating-async~ | -*true* | -« » | -0 | -
| _B_ | -1 | -0 | -~evaluated~ | -*true* | -« _A_ » | -0 | -
Finally, _A_ finishes executing. When that happens, AsyncModuleExecutionFulfilled is called again and _A_.[[Status]] is set to ~evaluated~. At this point, the Promise in _A_.[[TopLevelCapability]] (which was returned from _A_.Evaluate()) is resolved, and this concludes the handling of this module graph. The fields of the updated module are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluated~ | -*true* | -« » | -0 | -
Alternatively, consider a failure case where _C_ fails execution and returns an error before _B_ has finished executing. When that happens, AsyncModuleExecutionRejected is called, which sets _C_.[[Status]] to ~evaluated~ and _C_.[[EvaluationError]] to the error. It then propagates this error to all of the AsyncParentModules by performing AsyncModuleExecutionRejected on each of them. The fields of the updated modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -[[EvaluationError]] | -
|---|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluated~ | -*true* | -« » | -1 (_B_) | -~empty~ | -
| _C_ | -2 | -1 | -~evaluated~ | -*true* | -« _A_ » | -0 | -_C_'s evaluation error | -
_A_ will be rejected with the same error as _C_ since _C_ will call AsyncModuleExecutionRejected on _A_ with _C_'s error. _A_.[[Status]] is set to ~evaluated~. At this point the Promise in _A_.[[TopLevelCapability]] (which was returned from _A_.Evaluate()) is rejected. The fields of the updated module are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -[[EvaluationError]] | -
|---|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluated~ | -*true* | -« » | -0 | -_C_'s Evaluation Error | -
Then, _B_ finishes executing without an error. When that happens, AsyncModuleExecutionFulfilled is called again and _B_.[[Status]] is set to ~evaluated~. GatherAvailableAncestors is called on _B_. However, _A_.[[CycleRoot]] is _A_ which has an evaluation error, so it will not be added to the returned _sortedExecList_ and AsyncModuleExecutionFulfilled will return without further processing. Any future importer of _B_ will resolve the rejection of _B_.[[CycleRoot]].[[EvaluationError]] from the evaluation error from _C_ that was set on the cycle root _A_. The fields of the updated modules are as given in
| Module | -[[DFSIndex]] | -[[DFSAncestorIndex]] | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -[[EvaluationError]] | -
|---|---|---|---|---|---|---|---|
| _A_ | -0 | -0 | -~evaluated~ | -*true* | -« » | -0 | -_C_'s Evaluation Error | -
| _B_ | -1 | -0 | -~evaluated~ | -*true* | -« _A_ » | -0 | -~empty~ | -
Example Cyclic Module Record Graphs with Deferred Imports
- -Deferred imports complicate handling of module graphs, because they allow deferring evaluation of part of the graph while still eagerly evaluating the asynchronous subgraphs of a deferred portion. In this section, deferred imports are marked with dashed arrows and modules using top-level await are marked with TLA.
- -Consider the following graph, assuming that all the modules have already their [[Status]] set to ~linked~:
- -
- Calling _A_.Evaluate() calls InnerModuleEvaluation _A_, which transitions _A_.[[Status]] to ~evaluating~. _A_ has a deferred import for _B_, so it performs GatherAsynchronousTransitiveDependencies(_B_). _B_ doesn't have any transitive dependency using top-level await, so that AO doesn't collect any module. _A_ also imports _D_, so the list of modules that _A_'s evaluation depends on is « _D_ »: the InnerModuleEvaluation algorithm run on _A_ performs InnerModuleEvaluation on _D_, transitioning its [[Status]] to ~evaluating~ and then ~evaluated~, and then it calls _A_.ExecuteModule(). If _A_'s execution triggers _B_.Evaluate(), then InnerModuleEvaluation will be called on _B_ and _C_ executing them and transitioning their [[Status]] to ~evaluated~. Finally, _A_.[[Status]] transitions to ~evaluated~.
- -Consider the same graph, but with _C_ using top-level await:
- -
- Calling _A_.Evaluate() calls InnerModuleEvaluation _A_, which transitions _A_.[[Status]] to ~evaluating~. It then performs GatherAsynchronousTransitiveDependencies(_B_), finding the module _C_: the list of modules whose evaluation _A_'s evaluation depends on is « _C_, _D_ ». It then calls InnerModuleEvaluation on _C_ and _D_, transitioning their [[Status]] respectively to ~evaluating-async~ and ~evaluated~ and registering _A_'s evaluation as pending on the asynchronous dependency _C_. At this point, the fields of the modules are given in
| Module | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|
| _A_ | -~evaluating-async~ | -*true* | -« » | -1 (_C_) | -
| _B_ | -~linked~ | -*false* | -« » | -0 | -
| _C_ | -~evaluating-async~ | -*true* | -« _A_ » | -0 | -
| _D_ | -~evaluated~ | -*false* | -« » | -0 | -
Let us assume that _C_ succesfully finishes evaluating. When that happens, AsyncModuleExecutionFulfilled(_C_) is called, _C_.[[Status]] is set to ~evaluated~, _A_.ExecuteModule() is called and upon successful completion _A_.[[Status]] is set to ~evaluted~. The fields of the modules are now as given in
| Module | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -
|---|---|---|---|---|
| _A_ | -~evaluated~ | -*true* | -« » | -0 | -
| _B_ | -~linked~ | -*false* | -« » | -0 | -
| _C_ | -~evaluated~ | -*true* | -« _A_ » | -0 | -
| _D_ | -~evaluated~ | -*false* | -« » | -0 | -
If later _B_.Evaluate() is called, then the InnerModuleEvaluation call on _B_ will transition _B_.[[Status]] to ~evaluating~ and will call InnerModuleEvaluation on _C_. Since at this point _C_.[[Status]] is already ~evaluated~, _B_.ExecuteModule() will be called synchronously and _B_.[[Status]] will synchronously transition to ~evaluated~.
- -Alternatively, consider a failure case where _C_ fails to execute with an exception _error_. When that happens, AsyncModuleExecutionRejected(_C_, _error_) is called, it sets _C_.[[Status]] = _A_.[[Status]] to ~evaluated~ and _C_.[[EvaluationError]] = _A_.[[EvaluationError]] to ThrowCompletion(_error_). The fields of the modules are this as given in
| Module | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -[[EvaluationError]] | -
|---|---|---|---|---|---|
| _A_ | -~evaluated~ | -*true* | -« » | -1 (_C_) | -_error_ | -
| _B_ | -~linked~ | -*false* | -« » | -0 | -~empty~ | -
| _C_ | -~evaluated~ | -*true* | -« _B_ » | -0 | -_error_ | -
| _D_ | -~evaluated~ | -*false* | -« » | -0 | -~empty~ | -
If at any later point in time _B_.Evaluate() is called, it will perform InnerModuleEvaluation on _C_ which immediately returns with ThrowCompletion(_error_), transitioning _B_.[[Status]] to ~evalauted~ and setting _B_.[[EvaluationError]] to _error_.
- -Consider now a graph with a deferred import taking part in a dependencies cycle, and assume that the evaluation of _A_ calls _B_.Evaluate():
- -
- As in the previous example, calling _A_.Evaluate() calls InnerModuleEvaluation on _A_, GatherAsynchronousTransitiveDependencies on _B_ will find _C_ and thus it performs InnerModuleEvaluation on _C_, transitioning their _A_ and _C_'s [[Status]] to ~evaluating-async~. When InnerModuleEvaluation iterates over _C_'s dependencies, it finds _A_ and sets _A_.[[CycleRoot]] = _C_.[[CycleRoot]] = _A_. At this point, the fields of the modules are given in
| Module | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -[[CycleRoot]] | -
|---|---|---|---|---|---|
| _A_ | -~evaluating-async~ | -*true* | -« » | -1 (_C_) | -_A_ | -
| _B_ | -~linked~ | -*false* | -« » | -0 | -~empty~ | -
| _C_ | -~evaluating-async~ | -*true* | -« _A_ » | -0 | -_A_ | -
+ HostLoadImportedModule (
+ _referrer_: a Script Record, a Cyclic Module Record, or a Realm Record,
+ _moduleRequest_: a ModuleRequest Record,
+ _hostDefined_: anything,
+ _payload_: a GraphLoadingState Record or a PromiseCapability Record,
+ _payload_: a GraphLoadingState Record, a PromiseCapability Record, or a Completion Record,
+ ): ~unused~
+
+ -
+
- description + +
Assume now that _C_ succesfully finishes evaluating. When that happens AsyncModuleExecutionFulfilled(_C_) is called, it sets _C_.[[Status]] to ~evaluated~, and it performs _A_.ExecuteModule(). As stated, _A_'s execution causes a call to _B_.Evaluate(), which calls InnerModuleEvaluation on _B_ and on _C_. Since _C_.[[Status]] is ~evaluated~, _B_.ExecuteModule() is called synchronously and, assuming it completes succesfully, transitions _B_.[[Status]] to ~evaluated~. At this point, the fields of the modules are given in
An example of when _referrer_ can be a Realm Record is in a web browser host. There, if a user clicks on a control given by
-| Module | -[[Status]] | -[[AsyncEvaluation]] | -[[AsyncParentModules]] | -[[PendingAsyncDependencies]] | -[[CycleRoot]] | -
|---|---|---|---|---|---|
| _A_ | -~evaluating-async~ | -*true* | -« » | -0 | -_A_ | -
| _B_ | -~evaluated~ | -*false* | -« » | -0 | -_B_ | -
| _C_ | -~evaluated~ | -*true* | -« _A_ » | -0 | -_A_ | -
<button type="button" onclick="import('./foo.mjs')">Click me</button>Once the call to _A_.ExecuteModule() completes, _A_.[[Status]] transitions to ~evaluated~.
-there will be no active script or module at the time the
Source Text Module Records
+An implementation of HostLoadImportedModule must conform to the following requirements:
+-
+
- + The host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either a normal completion containing the loaded Module Record or a throw completion, either synchronously or asynchronously. + +
- + If _payload_ is a CompletionRecord, or _payload_ is a GraphLoadingState and _payload_.[[PromiseCapability]] is ~syncImport~, then the host environment must call FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) synchronously. + +
-
+
If this operation is called multiple times with two (_referrer_, _moduleRequest_) pairs such that:
+-
+
- the first _referrer_ is the same as the second _referrer_; +
- ModuleRequestsEqual(the first _moduleRequest_, the second _moduleRequest_) is *true*; +
and it performs FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) where _result_ is a normal completion, then it must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) with the same _result_ each time.
+
+ -
+
If _moduleRequest_.[[Attributes]] has an entry _entry_ such that _entry_.[[Key]] is *"type"* and _entry_.[[Value]] is *"json"*, when the host environment performs FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), _result_ must either be the Completion Record returned by an invocation of ParseJSONModule or a throw completion.
+
+ - + The operation must treat _payload_ as an opaque value to be passed through to FinishLoadingImportedModule. + +
InitializeEnvironment ( ): either a normal completion containing ~unused~ or a throw completion
--
-
- for -
- a Source Text Module Record _module_ -
The actual process performed is host-defined, but typically consists of performing whatever I/O operations are necessary to load the appropriate Module Record. Multiple different (_referrer_, _moduleRequest_.[[Specifier]], _moduleRequest_.[[Attributes]]) triples may map to the same Module Record instance. The actual mapping semantics is host-defined but typically a normalization process is applied to _specifier_ as part of the mapping process. A typical normalization process would include actions such as expansion of relative and abbreviated path specifiers.
-The above text requires that hosts support JSON modules when imported with `type: "json"` (and HostLoadImportedModule completes normally), but it does not prohibit hosts from supporting JSON modules when imported without `type: "json"`.
+- GetModuleNamespace ( - _module_: an instance of a concrete subclass of Module Record, - _phase_: ~defer~ or ~evaluation~, - ): a Module Namespace Object -
--
-
- description -
- 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. -
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.
-Imports
-Syntax
-Static Semantics: Early Errors
--
-
- - It is a Syntax Error if the BoundNames of |ImportDeclaration| contains any duplicate entries. - -
Static Semantics: ImportEntries ( ): a List of ImportEntry Records
--
-