Abstract Module Records
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
| - String + ~unlinked~ | ~linking~ | ~linked~ | ~evaluating~ | ~evaluated~ | - Initially `"unlinked"`. Transitions to `"linking"`, `"linked"`, `"evaluating"`, `"evaluated"` (in that order) as the module progresses throughout its lifecycle. + Initially ~unlinked~. Transitions to ~linking~, ~linked~, ~evaluating~, ~evaluated~ (in that order) as the module progresses throughout its lifecycle. |
| - A completion of type ~throw~ representing the exception that occurred during evaluation. *undefined* if no exception occurred, or if [[Status]] is not `"evaluated"`. + A completion of type ~throw~ representing the exception that occurred during evaluation. *undefined* if no exception occurred or if [[Status]] is not ~evaluated~. |
|
Auxiliary field used during Link and Evaluate only.
- If [[Status]] is `"linking"` |
|
Auxiliary field used during Link and Evaluate only.
- If [[Status]] is `"linking"` |
| - Initialize the Lexical Environment of the module, including resolving all imported bindings. + Initialize the Environment Record of the module, including resolving all imported bindings, and create the module's execution context. |
| - Initialize the execution context of the module and evaluate the module's code within it. If this module has *true* in [[Async]], then a Promise Capability 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 Promise Capability if necessary. + Evaluate the module's code within its execution context. + If this module has *true* in [[Async]], then a Promise Capability 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 Promise Capability if necessary. |
Link ( ) Concrete Method
-The Link concrete method of a Cyclic Module Record implements the corresponding Module Record abstract method.
-On success, Link transitions this module's [[Status]] from `"unlinked"` to `"linked"`. On failure, an exception is thrown and this module's [[Status]] remains `"unlinked"`.
- +On success, Link transitions this module's [[Status]] from ~unlinked~ to ~linked~. On failure, an exception is thrown and this module's [[Status]] remains ~unlinked~.
This abstract method performs the following steps (most of the work is done by the auxiliary function InnerModuleLinking):
InnerModuleLinking ( _module_, _stack_, _index_ )
+The abstract operation InnerModuleLinking takes arguments _module_ (a Cyclic Module Record), _stack_, and _index_. It is used by Link to perform the actual linking process for _module_, as well as recursively on all other modules in the dependency graph. The _stack_ and _index_ parameters, as well as a module's [[DFSIndex]] and [[DFSAncestorIndex]] fields, keep track of the depth-first search (DFS) traversal. In particular, [[DFSAncestorIndex]] is used to discover strongly connected components (SCCs), such that all modules in an SCC transition to ~linked~ together. It performs the following steps when called:
-The InnerModuleLinking abstract operation is used by Link to perform the actual linking process for the Cyclic Module Record _module_, as well as recursively on all other modules in the dependency graph. The _stack_ and _index_ parameters, as well as a module's [[DFSIndex]] and [[DFSAncestorIndex]] fields, keep track of the depth-first search (DFS) traversal. In particular, [[DFSAncestorIndex]] is used to discover strongly connected components (SCCs), such that all modules in an SCC transition to `"linked"` together.
- -This abstract operation performs the following steps:
InnerModuleLinking ( _module_, _stack_, _index_ )
1. Let _requiredModule_ be the last element in _stack_. 1. Remove the last element of _stack_. 1. Assert: _requiredModule_ is a Cyclic Module Record. - 1. Set _requiredModule_.[[Status]] to `"linked"`. + 1. Set _requiredModule_.[[Status]] to ~linked~. 1. If _requiredModule_ and _module_ are the same Module Record, set _done_ to *true*. 1. Return _index_.InnerModuleLinking ( _module_, _stack_, _index_ )
Evaluate ( ) Concrete Method
-The Evaluate concrete method of a Cyclic Module Record implements the corresponding Module Record abstract method.
-Evaluate transitions this module's [[Status]] from `"linked"` to `"evaluated"`.
- -If execution results in a exception, that exception is recorded in the [[EvaluationError]] field and rethrown by future invocations of Evaluate.
Evaluate transitions this module's [[Status]] from ~linked~ to ~evaluated~.
+If execution results in an exception, that exception is recorded in the [[EvaluationError]] field and rethrown by future invocations of Evaluate.
The Promise returned by Evaluate is allocated by the first invocation of Evaluate, and its capability is stored in the [[TopLevelCapability]] field. If execution results in an exception, the Promise is rejected. Future invocations of Evaluate return the same Promise.
-This abstract method performs the following steps (most of the work is done by the auxiliary function InnerModuleEvaluation):
Evaluate ( ) Concrete Method
1. Let _result_ be InnerModuleEvaluation(_module_, _stack_, 0). 1. If _result_ is an abrupt completion, then 1. For each Cyclic Module Record _m_ in _stack_, do - 1. Assert: _m_.[[Status]] is `"evaluating"`. - 1. Set _m_.[[Status]] to `"evaluated"`. + 1. Assert: _m_.[[Status]] is ~evaluating~. + 1. Set _m_.[[Status]] to ~evaluated~. 1. Set _m_.[[EvaluationError]] to _result_. - 1. Assert: _module_.[[Status]] is `"evaluated"` and _module_.[[EvaluationError]] is _result_. + 1. Assert: _module_.[[Status]] is ~evaluated~ and _module_.[[EvaluationError]] is _result_. 1.InnerModuleEvaluation( _module_, _stack_, _index_ )
+InnerModuleEvaluation ( _module_, _stack_, _index_ )
+The abstract operation InnerModuleEvaluation takes arguments _module_ (a Source Text Module Record), _stack_, and _index_. 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 performs the following steps when called:
-The InnerModuleEvaluation abstract operation is used by Evaluate to perform the actual evaluation process for the Cyclic Module Record _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 [[DFSAncestoreIndex]] fields, are used the same way as in InnerModuleLinking.
- -This abstract operation performs the following steps:
InnerModuleEvaluation( _module_, _stack_, _index_ )
1. NOTE: Link must be completed successfully prior to invoking this method, so every requested module is guaranteed to resolve successfully. 1. Set _index_ to ? InnerModuleEvaluation(_requiredModule_, _stack_, _index_). 1. If _requiredModule_ is a Cyclic Module Record, then - 1. Assert: _requiredModule_.[[Status]] is either `"evaluating"` or `"evaluated"`. - 1. Assert: _requiredModule_.[[Status]] is `"evaluating"` if and only if _requiredModule_ is in _stack_. - 1. If _requiredModule_.[[Status]] is `"evaluating"`, then + 1. Assert: _requiredModule_.[[Status]] is either ~evaluating~ or ~evaluated~. + 1. Assert: _requiredModule_.[[Status]] is ~evaluating~ if and only if _requiredModule_ is in _stack_. + 1. If _requiredModule_.[[Status]] is ~evaluating~, then 1. Set _module_.[[DFSAncestorIndex]] to min(_module_.[[DFSAncestorIndex]], _requiredModule_.[[DFSAncestorIndex]]). 1. Otherwise, 1. Set _requiredModule_ to GetAsyncCycleRoot(_requiredModule_). - 1. Assert: _requiredModule_.[[Status]] is `"evaluated"`. + 1. Assert: _requiredModule_.[[Status]] is ~evaluated~. 1. If _requiredModule_.[[EvaluationError]] is not *undefined*, return _module_.[[EvaluationError]]. 1. If _requiredModule_.[[AsyncEvaluating]] is *true*, then 1. Set _module_.[[PendingAsyncDependencies]] to _module_.[[PendingAsyncDependencies]] + 1. @@ -517,7 +510,7 @@InnerModuleEvaluation( _module_, _stack_, _index_ )
1. Let _requiredModule_ be the last element in _stack_. 1. Remove the last element of _stack_. 1. Assert: _requiredModule_ is a Cyclic Module Record. - 1. Set _requiredModule_.[[Status]] to `"evaluated"`. + 1. Set _requiredModule_.[[Status]] to ~evaluated~. 1. If _requiredModule_ and _module_ are the same Module Record, set _done_ to *true*. 1. Return _index_.AsyncModuleExecutionRejected ( _module_, _error_ )
Source Text Module Records
- -ParseModule ( _sourceText_, _realm_, _hostDefined_ )
-The abstract operation ParseModule with arguments _sourceText_, _realm_, and _hostDefined_ creates a Source Text Module Record based upon the result of parsing _sourceText_ as a |Module|. ParseModule performs the following steps:
-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.
-ExecuteModule ( [ _capability_ ] )
- -The ExecuteModule concrete method of a Source Text Module Record implements the corresponding Cyclic Module Record abstract method.
- -This abstract method performs the following steps:
- -Example Source Text Module Record Graphs
+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_.Link(), this will complete successfully by assumption, and recursively link modules _B_ and _C_ as well, such that _A_.[[Status]] = _B_.[[Status]] = _C_.[[Status]] = `"linked"`. This preparatory step 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. 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.
+Let's first assume that there are no error conditions. When a host first calls _A_.Link(), this will complete successfully by assumption, and recursively link modules _B_ and _C_ as well, such that _A_.[[Status]] = _B_.[[Status]] = _C_.[[Status]] = ~linked~. This preparatory step 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. 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. 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 Source Text Module Records; similarly, hosts are not required to expose the exception objects thrown by these methods. However, the specification enables such uses.)
+Finally, consider a case involving evaluation errors. 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.)
The difference here between linking and evaluation errors is due to how 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.
@@ -733,31 +651,29 @@Example Source Text Module Record Graphs
- In this scenario, module _A_ declares a dependency on some other module, but no Module Record exists for that module, i.e. HostResolveImportedModule throws 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 throwing an exception when trying to parse the resulting source text. Hosts can choose to expose the cause of failure via the exception they throw from HostResolveImportedModule. In any case, this exception causes an linking failure, which as before results in _A_'s [[Status]] remaining `"unlinked"`.
+In this scenario, module _A_ declares a dependency on some other module, but no Module Record exists for that module, i.e. HostResolveImportedModule throws 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 throwing an exception when trying to parse the resulting source text. Hosts can choose to expose the cause of failure via the exception they throw from HostResolveImportedModule. In any case, this exception causes a linking failure, which as before results in _A_'s [[Status]] remaining ~unlinked~.
-Now consider a module graph with a cycle:
+LastlyNow, 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_.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.
+Here we assume that the entry point is module _A_, so that 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.
An analogous story occurs for the evaluation phase of a cyclic module graph, in the success case.
-Now consider a case where _A_ has an 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 ModuleDeclarationEnvironmentSetup, 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"`.
- -Finally, 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]].
+Now consider a case where _A_ has an 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~.
-Lastly, consider a module graph with a cycle, where all modules complete asynchronously:
+Finally, 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:
+
- Linking happens as before, and all modules end up with [[Status]] set to `"linked"`.
+Linking happens as before, and all modules end up with [[Status]] set to `"linked"`.
-+
Calling _A_.Evaluate() triggers 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, which sets _D_.[[AsyncEvaluating]] to *true* and executes _D_ (up until the first `await`).
@@ -768,7 +684,7 @@ Example Source Text Module Record Graphs
We unwind once more to the original InnerModuleEvaluation on _A_, setting _C_.[[AsyncEvaluating]] to *true*.
Now we finish the loop over _A_'s dependencies, set _A_.[[AsyncEvaluating]] to *true*, and remove the entire strongly connected component from the stack, transitioning all of the modules to `"evaluated"` at once.
At this point, the fields of the modules are as given in
+
Let us assume that _E_ finishes executing first.
When that happens, AsyncModuleExecutionFulfilled is called, _E_.[[AsyncEvaluating]] is set to *false* and _C_.[[PendingAsyncDependencies]] is decremented to become 1.
The fields of the updated modules are as given in
+
_D_ is next to finish (as it was the only module that was still executing).
When that happens, AsyncModuleExecutionFulfilled is called again and _D_.[[AsyncEvaluating]] is set to *false*.
Then _B_.[[PendingAsyncDependencies]] is decremented to become 0, ExecuteAsyncModule is called on _B_, and it starts executing.
Once the synchronous part of _B_'s execution has finished, _C_.[[PendingAsyncDependencies]] is also decremented to become 0, and _C_ starts executing.
The fields of the updated modules are as given in
+
Let us assume that _C_ finishes executing next.
When that happens, AsyncModuleExecutionFulfilled is called again, _C_.[[AsyncEvaluating]] is set to *false* and _A_.[[PendingAsyncDependencies]] is decremented to become 1.
The fields of the updated modules are as given in
+
Then, _B_ finishes executing.
When that happens, AsyncModuleExecutionFulfilled is called again and _B_.[[AsyncEvaluating]] is set to *false*.
_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
+
Finally, _A_ finishes executing.
When that happens, AsyncModuleExecutionFulfilled is called again and _A_.[[AsyncEvaluating]] is set to *false*.
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
Runtime Semantics: TopLevelModuleEvaluationJob ( _sourceText_, _hostDefined_ )
-A TopLevelModuleEvaluationJob with parameters _sourceText_ and _hostDefined_ is a job that parses, validates, and evaluates _sourceText_ as a |Module|.
+Source Text Module Records
+ParseModule ( _sourceText_, _realm_, _hostDefined_ )
+The abstract operation ParseModule takes arguments _sourceText_ (ECMAScript source text), _realm_, and _hostDefined_. It creates a Source Text Module Record based upon the result of parsing _sourceText_ as a |Module|. It performs the following steps when called:
A ReportRejectedError function is an anonymous built-in function. When a ReportRejectedError function is called with argument _reason_ it performs the following steps:
-An implementation may parse a _sourceText_ as a |Module|, analyse it for Early Error conditions, and link it prior to the execution of the TopLevelModuleEvaluationJob for that _sourceText_. An implementation may also resolve, pre-parse and pre-analyse, and pre-link module dependencies of _sourceText_. However, the reporting of any errors detected by these actions must be deferred until the TopLevelModuleEvaluationJob is actually executed.
+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.
ExecuteModule ( [ _capability_ ] ) Concrete Method
+The ExecuteModule concrete method of a Source Text Module Record implements the corresponding Cyclic Module Record abstract method.
+This abstract method performs the following steps:
+ + +