SyntheticModule.constructor constructor | Node.js vm module | Bun

Creates a new SyntheticModule instance.

Array of names that will be exported from the module.

Called when the module is evaluated.

The contextified object as returned by the vm.createContext() method, to compile and evaluate this module in.

String used in stack traces.

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

The vm.SyntheticModule class provides the Synthetic Module Record as defined in the WebIDL specification. The purpose of synthetic modules is to provide a generic interface for exposing non-JavaScript sources to ECMAScript module graphs.

import { SyntheticModule } from 'node:vm';

const source = '{ "a": 1 }';
const syntheticModule = new SyntheticModule(['default'], function() {
const obj = JSON.parse(source);
this.setExport('default', obj);
});

// Use `syntheticModule` in linking
(async () => {
await syntheticModule.link(() => {});
await syntheticModule.evaluate();

console.log('Default export:', syntheticModule.namespace.default);
})();

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.

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

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.

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

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.

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:

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:

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:

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

Fulfills with undefined upon success.

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:

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

This method sets the module export binding slots with the given value.

import vm from 'node:vm';

const m = new vm.SyntheticModule(['x'], () => {
m.setExport('x', 1);
});

await m.evaluate();

assert.strictEqual(m.namespace.x, 1);

Name of the export to set.

The value to set the export to.