vm.SourceTextModule

Evaluate the module and its depenendencies. Corresponds to the Evaluate() concrete method field of Cyclic Module Records in the ECMAScript specification.

If the module is a vm.SourceTextModule, evaluate() must be called after the module has been instantiated; otherwise evaluate() will return a rejected promise.

For a vm.SourceTextModule, the promise returned by evaluate() may be fulfilled either synchronously or asynchronously:

1. If the vm.SourceTextModule has no top-level await in itself or any of its dependencies, the promise will be fulfilled synchronously after the module and all its dependencies have been evaluated.
   1. If the evaluation succeeds, the promise will be synchronously resolved to undefined.
   2. If the evaluation results in an exception, the promise will be synchronously rejected with the exception that causes the evaluation to fail, which is the same as module.error.
2. If the vm.SourceTextModule has top-level await in itself or any of its dependencies, the promise will be fulfilled asynchronously after the module and all its dependencies have been evaluated.
   1. If the evaluation succeeds, the promise will be asynchronously resolved to undefined.
   2. If the evaluation results in an exception, the promise will be asynchronously rejected with the exception that causes the evaluation to fail.

If the module is a vm.SyntheticModule, evaluate() always returns a promise that fulfills synchronously, see the specification of Evaluate() of a Synthetic Module Record:

1. If the evaluateCallback passed to its constructor throws an exception synchronously, evaluate() returns a promise that will be synchronously rejected with that exception.
2. If the evaluateCallback does not throw an exception, evaluate() returns a promise that will be synchronously resolved to undefined.

The evaluateCallback of a vm.SyntheticModule is executed synchronously within the evaluate() call, and its return value is discarded. This means if evaluateCallback is an asynchronous function, the promise returned by evaluate() will not reflect its asynchronous behavior, and any rejections from an asynchronous evaluateCallback will be lost.

evaluate() could also be called again after the module has already been evaluated, in which case:

1. If the initial evaluation ended in success (module.status is 'evaluated'), it will do nothing and return a promise that resolves to undefined.
2. If the initial evaluation resulted in an exception (module.status is 'errored'), it will re-reject the exception that the initial evaluation resulted in.

This method cannot be called while the module is being evaluated (module.status is 'evaluating').

Iterates over the dependency graph and returns true if any module in its dependencies or this module itself contains top-level await expressions, otherwise returns false.

The search may be slow if the graph is big enough.

This requires the module to be instantiated first. If the module is not instantiated yet, an error will be thrown.

Returns whether the module itself contains any top-level await expressions.

This corresponds to the field [[HasTLA]] in Cyclic Module Record in the ECMAScript specification.

Instantiate the module with the linked requested modules.

This resolves the imported bindings of the module, including re-exported binding names. When there are any bindings that cannot be resolved, an error would be thrown synchronously.

If the requested modules include cyclic dependencies, the sourceTextModule.linkRequests(modules) method must be called on all modules in the cycle before calling this method.

Link module dependencies. This method must be called before evaluation, and can only be called once per module.

Use sourceTextModule.linkRequests(modules) and sourceTextModule.instantiate() to link modules either synchronously or asynchronously.

The function is expected to return a Module object or a Promise that eventually resolves to a Module object. The returned Module must satisfy the following two invariants:

• It must belong to the same context as the parent Module.
• Its status must not be 'errored'.

If the returned Module's status is 'unlinked', this method will be recursively called on the returned Module with the same provided linker function.

link() returns a Promise that will either get resolved when all linking instances resolve to a valid Module, or rejected if the linker function either throws an exception or returns an invalid Module.

The linker function roughly corresponds to the implementation-defined HostResolveImportedModule abstract operation in the ECMAScript specification, with a few key differences:

• The linker function is allowed to be asynchronous while HostResolveImportedModule is synchronous.

The actual HostResolveImportedModule implementation used during module linking is one that returns the modules linked during linking. Since at that point all modules would have been fully linked already, the HostResolveImportedModule implementation is fully synchronous per specification.

Corresponds to the Link() concrete method field of Cyclic Module Record s in the ECMAScript specification.

Link module dependencies. This method must be called before evaluation, and can only be called once per module.

The order of the module instances in the modules array should correspond to the order of sourceTextModule.moduleRequests being resolved. If two module requests have the same specifier and import attributes, they must be resolved with the same module instance or an ERR_MODULE_LINK_MISMATCH would be thrown. For example, when linking requests for this module:

import foo from 'foo';
import source Foo from 'foo';

The modules array must contain two references to the same instance, because the two module requests are identical but in two phases.

If the module has no dependencies, the modules array can be empty.

Users can use sourceTextModule.moduleRequests to implement the host-defined HostLoadImportedModule abstract operation in the ECMAScript specification, and using sourceTextModule.linkRequests() to invoke specification defined FinishLoadingImportedModule, on the module with all dependencies in a batch.

It's up to the creator of the SourceTextModule to determine if the resolution of the dependencies is synchronous or asynchronous.

After each module in the modules array is linked, call sourceTextModule.instantiate().