BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

class

vm.SourceTextModule

class SourceTextModule

This feature is only available with the --experimental-vm-modules command flag enabled.

The vm.SourceTextModule class provides the Source Text Module Record as defined in the ECMAScript specification.

  • error: any

    If the module.status is 'errored', this property contains the exception thrown by the module during evaluation. If the status is anything else, accessing this property will result in a thrown exception.

    The value undefined cannot be used for cases where there is not a thrown exception due to possible ambiguity with throw undefined;.

    Corresponds to the [[EvaluationError]] field of Cyclic Module Record s in the ECMAScript specification.

  • identifier: string

    The identifier of the current module, as set in the constructor.

  • readonly moduleRequests: readonly ModuleRequest[]

    The requested import dependencies of this module. The returned array is frozen to disallow any changes to it.

    For example, given a source text:

    import foo from 'foo';
import fooAlias from 'foo';
import bar from './bar.js';
import withAttrs from '../with-attrs.ts' with { arbitraryAttr: 'attr-val' };
import source Module from 'wasm-mod.wasm';

    The value of the sourceTextModule.moduleRequests will be:

    [
  {
    specifier: 'foo',
    attributes: {},
    phase: 'evaluation',
  },
  {
    specifier: 'foo',
    attributes: {},
    phase: 'evaluation',
  },
  {
    specifier: './bar.js',
    attributes: {},
    phase: 'evaluation',
  },
  {
    specifier: '../with-attrs.ts',
    attributes: { arbitraryAttr: 'attr-val' },
    phase: 'evaluation',
  },
  {
    specifier: 'wasm-mod.wasm',
    attributes: {},
    phase: 'source',
  },
];
  • namespace: Object

    The namespace object of the module. This is only available after linking (module.link()) has completed.

    Corresponds to the GetModuleNamespace abstract operation in the ECMAScript specification.

  • status: ModuleStatus

    The current status of the module. Will be one of:

    • 'unlinked': module.link() has not yet been called.
    • 'linking': module.link() has been called, but not all Promises returned by the linker function have been resolved yet.
    • 'linked': The module has been linked successfully, and all of its dependencies are linked, but module.evaluate() has not yet been called.
    • 'evaluating': The module is being evaluated through a module.evaluate() on itself or a parent module.
    • 'evaluated': The module has been successfully evaluated.
    • 'errored': The module has been evaluated, but an exception was thrown.

    Other than 'errored', this status string corresponds to the specification's Cyclic Module Record's [[Status]] field. 'errored' corresponds to 'evaluated' in the specification, but with [[EvaluationError]] set to a value that is not undefined.

  • options?: ModuleEvaluateOptions
    ): Promise<void>;

    Evaluate the module.

    This must be called after the module has been linked; otherwise it will reject. It could be called also when the module has already been evaluated, in which case it will either do nothing if the initial evaluation ended in success (module.status is 'evaluated') or it will re-throw the exception that the initial evaluation resulted in (module.status is 'errored').

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

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

    @returns

    Fulfills with undefined upon success.

  • hasAsyncGraph(): boolean;

    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.

  • hasTopLevelAwait(): boolean;

    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(): void;

    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.

  • modules: readonly Module[]
    ): void;

    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().

    @param modules

    Array of vm.Module objects that this module depends on. The order of the modules in the array is the order of sourceTextModule.moduleRequests.