VM (executing JavaScript)

VM (executing JavaScript)

Stability: 2 - Stable

The node:vm module enables compiling and running code within V8 Virtual Machine contexts.

<strong class=“critical”>The node:vm module is not a security mechanism. Do not use it to run untrusted code.</strong>

JavaScript code can be compiled and run immediately or compiled, saved, and run later.

A common use case is to run the code in a different V8 Context. This means invoked code has a different global object than the invoking code.

One can provide the context by [contextifying][contextified] an object. The invoked code treats any property in the context like a global variable. Any changes to global variables caused by the invoked code are reflected in the context object.

import { createContext, runInContext } from 'node:vm';

const x = 1;

const context = { x: 2 };
createContext(context); // Contextify the object.

const code = 'x += 40; var y = 17;';
// `x` and `y` are global variables in the context.
// Initially, x has the value 2 because that is the value of context.x.
runInContext(code, context);

console.log(context.x); // 42
console.log(context.y); // 17

console.log(x); // 1; y is not defined

const { createContext, runInContext } = require('node:vm');

const x = 1;

const context = { x: 2 };
createContext(context); // Contextify the object.

const code = 'x += 40; var y = 17;';
// `x` and `y` are global variables in the context.
// Initially, x has the value 2 because that is the value of context.x.
runInContext(code, context);

console.log(context.x); // 42
console.log(context.y); // 17

console.log(x); // 1; y is not defined

Class: `vm.Script`

Instances of the vm.Script class contain precompiled scripts that can be executed in specific contexts.

`new vm.Script(code[, options])`

code {string} The JavaScript code to compile.
options {Object|string}
filename {string} Specifies the filename used in stack traces produced by this script. Default: 'evalmachine.<anonymous>'.
lineOffset {number} Specifies the line number offset that is displayed in stack traces produced by this script. Default: 0.
columnOffset {number} Specifies the first-line column number offset that is displayed in stack traces produced by this script. Default: 0.
cachedData {Buffer|TypedArray|DataView} Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source. When supplied, the cachedDataRejected value will be set to either true or false depending on acceptance of the data by V8.
produceCachedData {boolean} When true and no cachedData is present, V8 will attempt to produce code cache data for code. Upon success, a Buffer with V8's code cache data will be produced and stored in the cachedData property of the returned vm.Script instance. The cachedDataProduced value will be set to either true or false depending on whether code cache data is produced successfully. This option is deprecated in favor of script.createCachedData(). Default: false.
importModuleDynamically {Function|vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER} Used to specify how the modules should be loaded during the evaluation of this script when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see [Support of dynamic import() in compilation APIs][].

If options is a string, then it specifies the filename.

Creating a new vm.Script object compiles code but does not run it. The compiled vm.Script can be run later multiple times. The code is not bound to any global object; rather, it is bound before each run, just for that run.

`script.cachedDataRejected`

Type: {boolean|undefined}

When cachedData is supplied to create the vm.Script, this value will be set to either true or false depending on acceptance of the data by V8. Otherwise the value is undefined.

`script.createCachedData()`

Returns: {Buffer}

Creates a code cache that can be used with the Script constructor's cachedData option. Returns a Buffer. This method may be called at any time and any number of times.

The code cache of the Script doesn't contain any JavaScript observable states. The code cache is safe to be saved along side the script source and used to construct new Script instances multiple times.

Functions in the Script source can be marked as lazily compiled and they are not compiled at construction of the Script. These functions are going to be compiled when they are invoked the first time. The code cache serializes the metadata that V8 currently knows about the Script that it can use to speed up future compilations.

const script = new vm.Script(`
function add(a, b) {
  return a + b;
}

const x = add(1, 2);
`);

const cacheWithoutAdd = script.createCachedData();
// In `cacheWithoutAdd` the function `add()` is marked for full compilation
// upon invocation.

script.runInThisContext();

const cacheWithAdd = script.createCachedData();
// `cacheWithAdd` contains fully compiled function `add()`.

`script.runInContext(contextifiedObject[, options])`

contextifiedObject {Object} A [contextified][] object as returned by the vm.createContext() method.
options {Object}
displayErrors {boolean} When true, if an [Error][] occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.
timeout {integer} Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an [Error][] will be thrown. This value must be a strictly positive integer.
breakOnSigint {boolean} If true, receiving SIGINT (<kbd>Ctrl</kbd>+<kbd>C</kbd>) will terminate execution and throw an [Error][]. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.
Returns: {any} the result of the very last statement executed in the script.

Runs the compiled code contained by the vm.Script object within the given contextifiedObject and returns the result. Running code does not have access to local scope.

The following example compiles code that increments a global variable, sets the value of another global variable, then execute the code multiple times. The globals are contained in the context object.

import { createContext, Script } from 'node:vm';

const context = {
  animal: 'cat',
  count: 2,
};

const script = new Script('count += 1; name = "kitty";');

createContext(context);
for (let i = 0; i < 10; ++i) {
  script.runInContext(context);
}

console.log(context);
// Prints: { animal: 'cat', count: 12, name: 'kitty' }

const { createContext, Script } = require('node:vm');

const context = {
  animal: 'cat',
  count: 2,
};

const script = new Script('count += 1; name = "kitty";');

createContext(context);
for (let i = 0; i < 10; ++i) {
  script.runInContext(context);
}

console.log(context);
// Prints: { animal: 'cat', count: 12, name: 'kitty' }

Using the timeout or breakOnSigint options will result in new event loops and corresponding threads being started, which have a non-zero performance overhead.

`script.runInNewContext([contextObject[, options]])`

contextObject {Object|vm.constants.DONT_CONTEXTIFY|undefined} Either [vm.constants.DONT_CONTEXTIFY][] or an object that will be [contextified][]. If undefined, an empty contextified object will be created for backwards compatibility.
options {Object}
displayErrors {boolean} When true, if an [Error][] occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.
timeout {integer} Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an [Error][] will be thrown. This value must be a strictly positive integer.
breakOnSigint {boolean} If true, receiving SIGINT (<kbd>Ctrl</kbd>+<kbd>C</kbd>) will terminate execution and throw an [Error][]. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.
contextName {string} Human-readable name of the newly created context. Default: 'VM Context i', where i is an ascending numerical index of the created context.
contextOrigin {string} [Origin][origin] corresponding to the newly created context for display purposes. The origin should be formatted like a URL, but with only the scheme, host, and port (if necessary), like the value of the [url.origin][] property of a [URL][] object. Most notably, this string should omit the trailing slash, as that denotes a path. Default: ''.
contextCodeGeneration {Object}
- strings {boolean} If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) will throw an EvalError. Default: true.
- wasm {boolean} If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. Default: true.
microtaskMode {string} If set to afterEvaluate, microtasks (tasks scheduled through Promises and async functions) will be run immediately after the script has run. They are included in the timeout and breakOnSigint scopes in that case.
Returns: {any} the result of the very last statement executed in the script.

This method is a shortcut to script.runInContext(vm.createContext(options), options). It does several things at once:

Creates a new context.
If contextObject is an object, [contextifies][contextified] it with the new context. If contextObject is undefined, creates a new object and [contextifies][contextified] it. If contextObject is [vm.constants.DONT_CONTEXTIFY][], don't [contextify][contextified] anything.
Runs the compiled code contained by the vm.Script object within the created context. The code does not have access to the scope in which this method is called.
Returns the result.

The following example compiles code that sets a global variable, then executes the code multiple times in different contexts. The globals are set on and contained within each individual context.

import { constants, Script } from 'node:vm';

const script = new Script('globalVar = "set"');

const contexts = [{}, {}, {}];
contexts.forEach((context) => {
  script.runInNewContext(context);
});

console.log(contexts);
// Prints: [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }]

// This would throw if the context is created from a contextified object.
// constants.DONT_CONTEXTIFY allows creating contexts with ordinary
// global objects that can be frozen.
const freezeScript = new Script('Object.freeze(globalThis); globalThis;');
const frozenContext = freezeScript.runInNewContext(constants.DONT_CONTEXTIFY);

const { constants, Script } = require('node:vm');

const script = new Script('globalVar = "set"');

const contexts = [{}, {}, {}];
contexts.forEach((context) => {
  script.runInNewContext(context);
});

console.log(contexts);
// Prints: [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }]

// This would throw if the context is created from a contextified object.
// constants.DONT_CONTEXTIFY allows creating contexts with ordinary
// global objects that can be frozen.
const freezeScript = new Script('Object.freeze(globalThis); globalThis;');
const frozenContext = freezeScript.runInNewContext(constants.DONT_CONTEXTIFY);

`script.runInThisContext([options])`

options {Object}
displayErrors {boolean} When true, if an [Error][] occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.
timeout {integer} Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an [Error][] will be thrown. This value must be a strictly positive integer.
breakOnSigint {boolean} If true, receiving SIGINT (<kbd>Ctrl</kbd>+<kbd>C</kbd>) will terminate execution and throw an [Error][]. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.
Returns: {any} the result of the very last statement executed in the script.

Runs the compiled code contained by the vm.Script within the context of the current global object. Running code does not have access to local scope, but does have access to the current global object.

The following example compiles code that increments a global variable then executes that code multiple times:

import { Script } from 'node:vm';

global.globalVar = 0;

const script = new Script('globalVar += 1', { filename: 'myfile.vm' });

for (let i = 0; i < 1000; ++i) {
  script.runInThisContext();
}

console.log(globalVar);

// 1000

const { Script } = require('node:vm');

global.globalVar = 0;

const script = new Script('globalVar += 1', { filename: 'myfile.vm' });

for (let i = 0; i < 1000; ++i) {
  script.runInThisContext();
}

console.log(globalVar);

// 1000

`script.sourceMapURL`

Type: {string|undefined}

When the script is compiled from a source that contains a source map magic comment, this property will be set to the URL of the source map.

import vm from 'node:vm';

const script = new vm.Script(`
function myFunc() {}
//# sourceMappingURL=sourcemap.json
`);

console.log(script.sourceMapURL);
// Prints: sourcemap.json

const vm = require('node:vm');

const script = new vm.Script(`
function myFunc() {}
//# sourceMappingURL=sourcemap.json
`);

console.log(script.sourceMapURL);
// Prints: sourcemap.json

Class: `vm.Module`

Stability: 1 - Experimental

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

The vm.Module class provides a low-level interface for using ECMAScript modules in VM contexts. It is the counterpart of the vm.Script class that closely mirrors [Module Record][]s as defined in the ECMAScript specification.

Unlike vm.Script however, every vm.Module object is bound to a context from its creation.

Using a vm.Module object requires three distinct steps: creation/parsing, linking, and evaluation. These three steps are illustrated in the following example.

This implementation lies at a lower level than the [ECMAScript Module loader][]. There is also no way to interact with the Loader yet, though support is planned.

import vm from 'node:vm';

const contextifiedObject = vm.createContext({
  secret: 42,
  print: console.log,
});

// Step 1
//
// Create a Module by constructing a new `vm.SourceTextModule` object. This
// parses the provided source text, throwing a `SyntaxError` if anything goes
// wrong. By default, a Module is created in the top context. But here, we
// specify `contextifiedObject` as the context this Module belongs to.
//
// Here, we attempt to obtain the default export from the module "foo", and
// put it into local binding "secret".

const rootModule = new vm.SourceTextModule(`
  import s from 'foo';
  s;
  print(s);
`, { context: contextifiedObject });

// Step 2
//
// "Link" the imported dependencies of this Module to it.
//
// Obtain the requested dependencies of a SourceTextModule by
// `sourceTextModule.moduleRequests` and resolve them.
//
// Even top-level Modules without dependencies must be explicitly linked. The
// array passed to `sourceTextModule.linkRequests(modules)` can be
// empty, however.
//
// Note: This is a contrived example in that the resolveAndLinkDependencies
// creates a new "foo" module every time it is called. In a full-fledged
// module system, a cache would probably be used to avoid duplicated modules.

const moduleMap = new Map([
  ['root', rootModule],
]);

function resolveAndLinkDependencies(module) {
  const requestedModules = module.moduleRequests.map((request) => {
    // In a full-fledged module system, the resolveAndLinkDependencies would
    // resolve the module with the module cache key `[specifier, attributes]`.
    // In this example, we just use the specifier as the key.
    const specifier = request.specifier;

    let requestedModule = moduleMap.get(specifier);
    if (requestedModule === undefined) {
      requestedModule = new vm.SourceTextModule(`
        // The "secret" variable refers to the global variable we added to
        // "contextifiedObject" when creating the context.
        export default secret;
      `, { context: module.context });
      moduleMap.set(specifier, requestedModule);
      // Resolve the dependencies of the new module as well.
      resolveAndLinkDependencies(requestedModule);
    }

    return requestedModule;
  });

  module.linkRequests(requestedModules);
}

resolveAndLinkDependencies(rootModule);
rootModule.instantiate();

// Step 3
//
// Evaluate the Module. The evaluate() method returns a promise which will
// resolve after the module has finished evaluating.

// Prints 42.
await rootModule.evaluate();

const vm = require('node:vm');

const contextifiedObject = vm.createContext({
  secret: 42,
  print: console.log,
});

(async () => {
  // Step 1
  //
  // Create a Module by constructing a new `vm.SourceTextModule` object. This
  // parses the provided source text, throwing a `SyntaxError` if anything goes
  // wrong. By default, a Module is created in the top context. But here, we
  // specify `contextifiedObject` as the context this Module belongs to.
  //
  // Here, we attempt to obtain the default export from the module "foo", and
  // put it into local binding "secret".

  const rootModule = new vm.SourceTextModule(`
    import s from 'foo';
    s;
    print(s);
  `, { context: contextifiedObject });

  // Step 2
  //
  // "Link" the imported dependencies of this Module to it.
  //
  // Obtain the requested dependencies of a SourceTextModule by
  // `sourceTextModule.moduleRequests` and resolve them.
  //
  // Even top-level Modules without dependencies must be explicitly linked. The
  // array passed to `sourceTextModule.linkRequests(modules)` can be
  // empty, however.
  //
  // Note: This is a contrived example in that the resolveAndLinkDependencies
  // creates a new "foo" module every time it is called. In a full-fledged
  // module system, a cache would probably be used to avoid duplicated modules.

  const moduleMap = new Map([
    ['root', rootModule],
  ]);

  function resolveAndLinkDependencies(module) {
    const requestedModules = module.moduleRequests.map((request) => {
      // In a full-fledged module system, the resolveAndLinkDependencies would
      // resolve the module with the module cache key `[specifier, attributes]`.
      // In this example, we just use the specifier as the key.
      const specifier = request.specifier;

      let requestedModule = moduleMap.get(specifier);
      if (requestedModule === undefined) {
        requestedModule = new vm.SourceTextModule(`
          // The "secret" variable refers to the global variable we added to
          // "contextifiedObject" when creating the context.
          export default secret;
        `, { context: module.context });
        moduleMap.set(specifier, requestedModule);
        // Resolve the dependencies of the new module as well.
        resolveAndLinkDependencies(requestedModule);
      }

      return requestedModule;
    });

    module.linkRequests(requestedModules);
  }

  resolveAndLinkDependencies(rootModule);
  rootModule.instantiate();

  // Step 3
  //
  // Evaluate the Module. The evaluate() method returns a promise which will
  // resolve after the module has finished evaluating.

  // Prints 42.
  await rootModule.evaluate();
})();

`module.error`

Type: {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.

`module.evaluate([options])`

options {Object}
timeout {integer} Specifies the number of milliseconds to evaluate before terminating execution. If execution is interrupted, an [Error][] will be thrown. This value must be a strictly positive integer.
breakOnSigint {boolean} If true, receiving SIGINT (<kbd>Ctrl</kbd>+<kbd>C</kbd>) will terminate execution and throw an [Error][]. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.
Returns: {Promise} Fulfills with undefined upon success.

Evaluate the module and its dependencies. Corresponds to the [Evaluate() concrete method][] field of [Cyclic Module Record][]s 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 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.
If the evaluation succeeds, the promise will be synchronously resolved to undefined.
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.
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.
If the evaluation succeeds, the promise will be asynchronously resolved to undefined.
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][]:

If the evaluateCallback passed to its constructor throws an exception synchronously, evaluate() returns a promise that will be synchronously rejected with that exception.
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:

If the initial evaluation ended in success (module.status is 'evaluated'), it will do nothing and return a promise that resolves to undefined.
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').

`module.identifier`

Type: {string}

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

`module.link(linker)`

linker {Function}
specifier {string} The specifier of the requested module: mjs import foo from 'foo'; // ^^^^^ the module specifier
referencingModule {vm.Module} The Module object link() is called on.
extra {Object}
- attributes {Object} The data from the attribute: mjs import foo from 'foo' with { name: 'value' }; // ^^^^^^^^^^^^^^^^^ the attribute Per ECMA-262, hosts are expected to trigger an error if an unsupported attribute is present.
- assert {Object} Alias for extra.attributes.
Returns: {vm.Module|Promise}
Returns: {Promise}

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.

`module.namespace`

Type: {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.

`module.status`

Type: {string}

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.

Class: `vm.SourceTextModule`

Stability: 1 - Experimental

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

Extends: {vm.Module}

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

`new vm.SourceTextModule(code[, options])`

code {string} JavaScript Module code to parse
options
identifier {string} String used in stack traces. Default: 'vm:module(i)' where i is a context-specific ascending index.
cachedData {Buffer|TypedArray|DataView} Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source. The code must be the same as the module from which this cachedData was created.
context {Object} The [contextified][] object as returned by the vm.createContext() method, to compile and evaluate this Module in. If no context is specified, the module is evaluated in the current execution context.
lineOffset {integer} Specifies the line number offset that is displayed in stack traces produced by this Module. Default: 0.
columnOffset {integer} Specifies the first-line column number offset that is displayed in stack traces produced by this Module. Default: 0.
initializeImportMeta {Function} Called during evaluation of this Module to initialize the import.meta.
- meta {import.meta}
- module {vm.SourceTextModule}
importModuleDynamically {Function} Used to specify the how the modules should be loaded during the evaluation of this module when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see [Support of dynamic import() in compilation APIs][].

Creates a new SourceTextModule instance.

Properties assigned to the import.meta object that are objects may allow the module to access information outside the specified context. Use vm.runInContext() to create objects in a specific context.

import vm from 'node:vm';

const contextifiedObject = vm.createContext({ secret: 42 });

const module = new vm.SourceTextModule(
  'Object.getPrototypeOf(import.meta.prop).secret = secret;',
  {
    context: contextifiedObject,
    initializeImportMeta(meta) {
      // Note: this object is created in the top context. As such,
      // Object.getPrototypeOf(import.meta.prop) points to the
      // Object.prototype in the top context rather than that in
      // the contextified object.
      meta.prop = {};
    },
  });
// The module has an empty `moduleRequests` array.
module.linkRequests([]);
module.instantiate();
await module.evaluate();

// Now, Object.prototype.secret will be equal to 42.
//
// To fix this problem, replace
//     meta.prop = {};
// above with
//     meta.prop = vm.runInContext('({})', contextifiedObject);

const vm = require('node:vm');
const contextifiedObject = vm.createContext({ secret: 42 });
(async () => {
  const module = new vm.SourceTextModule(
    'Object.getPrototypeOf(import.meta.prop).secret = secret;',
    {
      context: contextifiedObject,
      initializeImportMeta(meta) {
        // Note: this object is created in the top context. As such,
        // Object.getPrototypeOf(import.meta.prop) points to the
        // Object.prototype in the top context rather than that in
        // the contextified object.
        meta.prop = {};
      },
    });
  // The module has an empty `moduleRequests` array.
  module.linkRequests([]);
  module.instantiate();
  await module.evaluate();
  // Now, Object.prototype.secret will be equal to 42.
  //
  // To fix this problem, replace
  //     meta.prop = {};
  // above with
  //     meta.prop = vm.runInContext('({})', contextifiedObject);
})();

`sourceTextModule.createCachedData()`

Returns: {Buffer}

Creates a code cache that can be used with the SourceTextModule constructor's cachedData option. Returns a Buffer. This method may be called any number of times before the module has been evaluated.

The code cache of the SourceTextModule doesn't contain any JavaScript observable states. The code cache is safe to be saved along side the script source and used to construct new SourceTextModule instances multiple times.

Functions in the SourceTextModule source can be marked as lazily compiled and they are not compiled at construction of the SourceTextModule. These functions are going to be compiled when they are invoked the first time. The code cache serializes the metadata that V8 currently knows about the SourceTextModule that it can use to speed up future compilations.

// Create an initial module
const module = new vm.SourceTextModule('const a = 1;');

// Create cached data from this module
const cachedData = module.createCachedData();

// Create a new module using the cached data. The code must be the same.
const module2 = new vm.SourceTextModule('const a = 1;', { cachedData });

`sourceTextModule.dependencySpecifiers`

Stability: 0 - Deprecated: Use [sourceTextModule.moduleRequests][] instead.

Type: {string[]}

The specifiers of all dependencies of this module. The returned array is frozen to disallow any changes to it.

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

`sourceTextModule.hasAsyncGraph()`

Returns: {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.

`sourceTextModule.hasTopLevelAwait()`

Returns: {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.

`sourceTextModule.instantiate()`

Returns: {undefined}

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.

`sourceTextModule.linkRequests(modules)`

modules {vm.Module[]} Array of vm.Module objects that this module depends on. The order of the modules in the array is the order of [sourceTextModule.moduleRequests][].
Returns: {undefined}

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

`sourceTextModule.moduleRequests`

Type: {ModuleRequest[]} Dependencies of this module.

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',
  },
];

Class: `vm.SyntheticModule`

Stability: 1 - Experimental

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

Extends: {vm.Module}

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);
})();

const { SyntheticModule } = require('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);
})();

`new vm.SyntheticModule(exportNames, evaluateCallback[, options])`

exportNames {string[]} Array of names that will be exported from the module.
evaluateCallback {Function} Called when the module is evaluated.
options
identifier {string} String used in stack traces. Default: 'vm:module(i)' where i is a context-specific ascending index.
context {Object} The [contextified][] object as returned by the vm.createContext() method, to compile and evaluate this Module in.

Creates a new SyntheticModule instance.

Objects assigned to the exports of this instance may allow importers of the module to access information outside the specified context. Use vm.runInContext() to create objects in a specific context.

`syntheticModule.setExport(name, value)`

name {string} Name of the export to set.
value {any} The value to set the export to.

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);

const vm = require('node:vm');
(async () => {
  const m = new vm.SyntheticModule(['x'], () => {
    m.setExport('x', 1);
  });
  await m.evaluate();
  assert.strictEqual(m.namespace.x, 1);
})();

Type: `ModuleRequest`

Type: {Object}
specifier {string} The specifier of the requested module.
attributes {Object} The “with” value passed to the [WithClause][] in a [ImportDeclaration][], or an empty object if no value was provided.
phase {string} The phase of the requested module (“source” or “evaluation”).

A ModuleRequest represents the request to import a module with given import attributes and phase.

`vm.compileFunction(code[, params[, options]])`

code {string} T

（本文超出站点单文档体积上限，已截断）

VM (executing JavaScript)

VM (executing JavaScript)

Class: vm.Script

new vm.Script(code[, options])

script.cachedDataRejected

script.createCachedData()

script.runInContext(contextifiedObject[, options])

script.runInNewContext([contextObject[, options]])

script.runInThisContext([options])

script.sourceMapURL

Class: vm.Module

module.error

module.evaluate([options])

module.identifier

module.link(linker)

module.namespace

module.status

Class: vm.SourceTextModule

new vm.SourceTextModule(code[, options])

sourceTextModule.createCachedData()

sourceTextModule.dependencySpecifiers

sourceTextModule.hasAsyncGraph()

sourceTextModule.hasTopLevelAwait()

sourceTextModule.instantiate()

sourceTextModule.linkRequests(modules)

sourceTextModule.moduleRequests

Class: vm.SyntheticModule

new vm.SyntheticModule(exportNames, evaluateCallback[, options])

syntheticModule.setExport(name, value)

Type: ModuleRequest

vm.compileFunction(code[, params[, options]])

Class: `vm.Script`

`new vm.Script(code[, options])`

`script.cachedDataRejected`

`script.createCachedData()`

`script.runInContext(contextifiedObject[, options])`

`script.runInNewContext([contextObject[, options]])`

`script.runInThisContext([options])`

`script.sourceMapURL`

Class: `vm.Module`

`module.error`

`module.evaluate([options])`

`module.identifier`

`module.link(linker)`

`module.namespace`

`module.status`

Class: `vm.SourceTextModule`

`new vm.SourceTextModule(code[, options])`

`sourceTextModule.createCachedData()`

`sourceTextModule.dependencySpecifiers`

`sourceTextModule.hasAsyncGraph()`

`sourceTextModule.hasTopLevelAwait()`

`sourceTextModule.instantiate()`

`sourceTextModule.linkRequests(modules)`

`sourceTextModule.moduleRequests`

Class: `vm.SyntheticModule`

`new vm.SyntheticModule(exportNames, evaluateCallback[, options])`

`syntheticModule.setExport(name, value)`

Type: `ModuleRequest`

`vm.compileFunction(code[, params[, options]])`