vm

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.

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:

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

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.

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

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.

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.

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

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

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 vm from 'node:vm';

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

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

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

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

1. Creates a new context.
2. If contextObject is an object, contextifies it with the new context. If contextObject is undefined, creates a new object and contextifies it. If contextObject is vm.constants.DONT_CONTEXTIFY, don't contextify anything.
3. 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.
4. 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.

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

const script = new vm.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.
// vm.constants.DONT_CONTEXTIFY allows creating contexts with ordinary
// global objects that can be frozen.
const freezeScript = new vm.Script('Object.freeze(globalThis); globalThis;');
const frozenContext = freezeScript.runInNewContext(vm.constants.DONT_CONTEXTIFY);

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 vm from 'node:vm';

global.globalVar = 0;

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

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

console.log(globalVar);

// 1000

Creates a new SourceTextModule instance.

Creates a new SyntheticModule instance.

This method is used after the module is linked to set the values of exports. If it is called before the module is linked, an ERR_VM_MODULE_STATUS error will be thrown.

import vm from 'node:vm';

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

await m.link(() => {});
await m.evaluate();

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

Specifies the filename used in stack traces produced by this script.

Specifies the line number offset that is displayed in stack traces produced by this script.

Specifies the column number offset that is displayed in stack traces produced by this script.

Provides an optional data with V8's code cache data for the supplied source.

Specifies whether to produce new cache data.

The sandbox/context in which the said function should be compiled in.

An array containing a collection of context extensions (objects wrapping the current scope) to be applied while compiling

Human-readable name of the newly created context.

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

If set to afterEvaluate, microtasks will be run immediately after the script has run.

Human-readable name of the newly created context.

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.

If set to afterEvaluate, microtasks will be run immediately after the script has run.

When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace.

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.

If true, the execution will be terminated when SIGINT (Ctrl+C) is received. Existing handlers for the event that have been attached via process.on('SIGINT') will be disabled during script execution, but will continue to work after that. If execution is terminated, an Error will be thrown.

V8's code cache data for the supplied source.

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.

String used in stack traces.

Called during evaluation of this module to initialize the import.meta.

String used in stack traces.

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