VM (executing JavaScript)#
Source Code: lib/vm.js
The node:vm module enables compiling and running code within V8 Virtual
Machine contexts.
The node:vm module is not a security
mechanism. Do not use it to run untrusted code.
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 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.
const vm = require('node:vm');
const x = 1;
const context = { x: 2 };
vm.createContext(context);
const code = 'x += 40; var y = 17;';
vm.runInContext(code, context);
console.log(context.x);
console.log(context.y);
console.log(x);
Class: vm.Script#
Added in: v0.3.1
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#
Added in: v5.7.0
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()#
Added in: v10.6.0
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();
script.runInThisContext();
const cacheWithAdd = script.createCachedData();
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
(Ctrl+C) 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.
const vm = require('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);
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
(Ctrl+C) 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 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 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.
- 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.
const vm = require('node:vm');
const script = new vm.Script('globalVar = "set"');
const contexts = [{}, {}, {}];
contexts.forEach((context) => {
script.runInNewContext(context);
});
console.log(contexts);
const freezeScript = new vm.Script('Object.freeze(globalThis); globalThis;');
const frozenContext = freezeScript.runInNewContext(vm.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
(Ctrl+C) 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:
const vm = require('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);
Class: vm.Module#
Added in: v13.0.0, v12.16.0
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 Records 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,
});
const rootModule = new vm.SourceTextModule(`
import s from 'foo';
s;
print(s);
`, { context: contextifiedObject });
const moduleMap = new Map([
['root', rootModule],
]);
function resolveAndLinkDependencies(module) {
const requestedModules = module.moduleRequests.map((request) => {
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: referencingModule.context });
moduleMap.set(specifier, linkedModule);
resolveAndLinkDependencies(requestedModule);
}
return requestedModule;
});
module.linkRequests(requestedModules);
}
resolveAndLinkDependencies(rootModule);
rootModule.instantiate();
await rootModule.evaluate();const vm = require('node:vm');
const contextifiedObject = vm.createContext({
secret: 42,
print: console.log,
});
(async () => {
const rootModule = new vm.SourceTextModule(`
import s from 'foo';
s;
print(s);
`, { context: contextifiedObject });
const moduleMap = new Map([
['root', rootModule],
]);
function resolveAndLinkDependencies(module) {
const requestedModules = module.moduleRequests.map((request) => {
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: referencingModule.context });
moduleMap.set(specifier, linkedModule);
resolveAndLinkDependencies(requestedModule);
}
return requestedModule;
});
module.linkRequests(requestedModules);
}
resolveAndLinkDependencies(rootModule);
rootModule.instantiate();
await rootModule.evaluate();
})();
module.error#
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 Records
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
(Ctrl+C) 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.
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
Records in the ECMAScript specification.
module.identifier#
The identifier of the current module, as set in the constructor.
module.link(linker)#
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 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
Records in the ECMAScript specification.
module.namespace#
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#
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#
Added in: v9.6.0
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.
sourceTextModule.createCachedData()#
Added in: v13.7.0, v12.17.0
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.
const module = new vm.SourceTextModule('const a = 1;');
const cachedData = module.createCachedData();
const module2 = new vm.SourceTextModule('const a = 1;', { cachedData });
sourceTextModule.dependencySpecifiers#
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 Records in
the ECMAScript specification.
sourceTextModule.instantiate()#
Added in: v22.21.0
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)#
Added in: v22.21.0
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#
Added in: v22.20.0
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' };
The value of the sourceTextModule.moduleRequests will be:
[
{
specifier: 'foo',
attributes: {},
},
{
specifier: 'foo',
attributes: {},
},
{
specifier: './bar.js',
attributes: {},
},
{
specifier: '../with-attrs.ts',
attributes: { arbitraryAttr: 'attr-val' },
},
];
Class: vm.SyntheticModule#
Added in: v13.0.0, v12.16.0
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.
const vm = require('node:vm');
const source = '{ "a": 1 }';
const module = new vm.SyntheticModule(['default'], function() {
const obj = JSON.parse(source);
this.setExport('default', obj);
});
new vm.SyntheticModule(exportNames, evaluateCallback[, options])#
Added in: v13.0.0, v12.16.0
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.
Type: ModuleRequest#
Added in: v22.20.0
A ModuleRequest represents the request to import a module with given import attributes and phase.
vm.compileFunction(code[, params[, options]])#
code <string> The body of the function to compile.
params <string[]> An array of strings containing all parameters for the
function.
options <Object>
filename <string> Specifies the filename used in stack traces produced
by this script. Default: ''.
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. This must be produced by a prior call to vm.compileFunction()
with the same code and params.
produceCachedData <boolean> Specifies whether to produce new cache data.
Default: false.
parsingContext <Object> The contextified object in which the said
function should be compiled in.
contextExtensions <Object[]> An array containing a collection of context
extensions (objects wrapping the current scope) to be applied while
compiling. Default: [].
importModuleDynamically
<Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER>
Used to specify the how the modules should be loaded during the evaluation of
this function 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.
- Returns: <Function>
Compiles the given code into the provided context (if no context is
supplied, the current context is used), and returns it wrapped inside a
function with the given params.
vm.constants#
Added in: v21.7.0, v20.12.0
Returns an object containing commonly used constants for VM operations.
vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER#
Added in: v21.7.0, v20.12.0
A constant that can be used as the importModuleDynamically option to
vm.Script and vm.compileFunction() so that Node.js uses the default
ESM loader from the main context to load the requested module.
For detailed information, see
Support of dynamic import() in compilation APIs.
vm.createContext([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>
name <string> Human-readable name of the newly created context.
Default: 'VM Context i', where i is an ascending numerical index of
the created context.
origin <string> 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: ''.
codeGeneration <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 a script has run through script.runInContext().
They are included in the timeout and breakOnSigint scopes in that case.
importModuleDynamically
<Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER>
Used to specify the how the modules should be loaded when import() is
called in this context without a referrer script or module. 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.
- Returns: <Object> contextified object.
If the given contextObject is an object, the vm.createContext() method will prepare that
object and return a reference to it so that it can be used in
calls to vm.runInContext() or script.runInContext(). Inside such
scripts, the global object will be wrapped by the contextObject, retaining all of its
existing properties but also having the built-in objects and functions any
standard global object has. Outside of scripts run by the vm module, global
variables will remain unchanged.
const vm = require('node:vm');
global.globalVar = 3;
const context = { globalVar: 1 };
vm.createContext(context);
vm.runInContext('globalVar *= 2;', context);
console.log(context);
console.log(global.globalVar);
If contextObject is omitted (or passed explicitly as undefined), a new,
empty contextified object will be returned.
When the global object in the newly created context is contextified, it has some quirks
compared to ordinary global objects. For example, it cannot be frozen. To create a context
without the contextifying quirks, pass vm.constants.DONT_CONTEXTIFY as the contextObject
argument. See the documentation of vm.constants.DONT_CONTEXTIFY for details.
The vm.createContext() method is primarily useful for creating a single
context that can be used to run multiple scripts. For instance, if emulating a
web browser, the method can be used to create a single context representing a
window's global object, then run all <script> tags together within that
context.
The provided name and origin of the context are made visible through the
Inspector API.
vm.measureMemory([options])#
Added in: v13.10.0
Measure the memory known to V8 and used by all contexts known to the
current V8 isolate, or the main context.
options <Object> Optional.
mode <string> Either 'summary' or 'detailed'. In summary mode,
only the memory measured for the main context will be returned. In
detailed mode, the memory measured for all contexts known to the
current V8 isolate will be returned.
Default: 'summary'
execution <string> Either 'default' or 'eager'. With default
execution, the promise will not resolve until after the next scheduled
garbage collection starts, which may take a while (or never if the program
exits before the next GC). With eager execution, the GC will be started
right away to measure the memory.
Default: 'default'
- Returns: <Promise> If the memory is successfully measured, the promise will
resolve with an object containing information about the memory usage.
Otherwise it will be rejected with an
ERR_CONTEXT_NOT_INITIALIZED error.
The format of the object that the returned Promise may resolve with is
specific to the V8 engine and may change from one version of V8 to the next.
The returned result is different from the statistics returned by
v8.getHeapSpaceStatistics() in that vm.measureMemory() measure the
memory reachable by each V8 specific contexts in the current instance of
the V8 engine, while the result of v8.getHeapSpaceStatistics() measure
the memory occupied by each heap space in the current V8 instance.
const vm = require('node:vm');
vm.measureMemory({ mode: 'summary' })
.then((result) => {
console.log(result);
});
const context = vm.createContext({ a: 1 });
vm.measureMemory({ mode: 'detailed', execution: 'eager' })
.then((result) => {
console.log(context.a);
console.log(result);
});
vm.runInContext(code, contextifiedObject[, options])#
code <string> The JavaScript code to compile and run.
contextifiedObject <Object> The contextified object that will be used
as the global when the code is compiled and run.
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.
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
(Ctrl+C) 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.
cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or
TypedArray, or DataView with V8's code cache data for the supplied
source.
importModuleDynamically
<Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER>
Used to specify the 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.
The vm.runInContext() method compiles code, runs it within the context of
the contextifiedObject, then returns the result. Running code does not have
access to the local scope. The contextifiedObject object must have been
previously contextified using the vm.createContext() method.
If options is a string, then it specifies the filename.
The following example compiles and executes different scripts using a single
contextified object:
const vm = require('node:vm');
const contextObject = { globalVar: 1 };
vm.createContext(contextObject);
for (let i = 0; i < 10; ++i) {
vm.runInContext('globalVar *= 2;', contextObject);
}
console.log(contextObject);
vm.runInNewContext(code[, contextObject[, options]])#
code <string> The JavaScript code to compile and run.
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> | <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.
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
(Ctrl+C) 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 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.
cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or
TypedArray, or DataView with V8's code cache data for the supplied
source.
importModuleDynamically
<Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER>
Used to specify the 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.
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
(new vm.Script(code, options)).runInContext(vm.createContext(options), options).
If options is a string, then it specifies the filename.
It does several things at once:
- Creates a new context.
- 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.
- Compiles the code as a
vm.Script
- Runs the compield code 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 and executes code that increments a global
variable and sets a new one. These globals are contained in the contextObject.
const vm = require('node:vm');
const contextObject = {
animal: 'cat',
count: 2,
};
vm.runInNewContext('count += 1; name = "kitty"', contextObject);
console.log(contextObject);
const frozenContext = vm.runInNewContext('Object.freeze(globalThis); globalThis;', vm.constants.DONT_CONTEXTIFY);
vm.runInThisContext(code[, options])#
code <string> The JavaScript code to compile and run.
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.
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
(Ctrl+C) 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.
cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or
TypedArray, or DataView with V8's code cache data for the supplied
source.
importModuleDynamically
<Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER>
Used to specify the 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.
- Returns: <any> the result of the very last statement executed in the script.
vm.runInThisContext() compiles code, runs it within the context of the
current global and returns the result. Running code does not have access to
local scope, but does have access to the current global object.
If options is a string, then it specifies the filename.
The following example illustrates using both vm.runInThisContext() and
the JavaScript eval() function to run the same code:
const vm = require('node:vm');
let localVar = 'initial value';
const vmResult = vm.runInThisContext('localVar = "vm";');
console.log(`vmResult: '${vmResult}', localVar: '${localVar}'`);
const evalResult = eval('localVar = "eval";');
console.log(`evalResult: '${evalResult}', localVar: '${localVar}'`);
Because vm.runInThisContext() does not have access to the local scope,
localVar is unchanged. In contrast, a direct eval() call does have access
to the local scope, so the value localVar is changed. In this way
vm.runInThisContext() is much like an indirect eval() call, e.g.
(0,eval)('code').
Example: Running an HTTP server within a VM#
When using either script.runInThisContext() or
vm.runInThisContext(), the code is executed within the current V8 global
context. The code passed to this VM context will have its own isolated scope.
In order to run a simple web server using the node:http module the code passed
to the context must either call require('node:http') on its own, or have a
reference to the node:http module passed to it. For instance:
'use strict';
const vm = require('node:vm');
const code = `
((require) => {
const http = require('node:http');
http.createServer((request, response) => {
response.writeHead(200, { 'Content-Type': 'text/plain' });
response.end('Hello World\\n');
}).listen(8124);
console.log('Server running at http://127.0.0.1:8124/');
})`;
vm.runInThisContext(code)(require);
The require() in the above case shares the state with the context it is
passed from. This may introduce risks when untrusted code is executed, e.g.
altering objects in the context in unwanted ways.
What does it mean to "contextify" an object?#
All JavaScript executed within Node.js runs within the scope of a "context".
According to the V8 Embedder's Guide:
In V8, a context is an execution environment that allows separate, unrelated,
JavaScript applications to run in a single instance of V8. You must explicitly
specify the context in which you want any JavaScript code to be run.
When the method vm.createContext() is called with an object, the contextObject argument
will be used to wrap the global object of a new instance of a V8 Context
(if contextObject is undefined, a new object will be created from the current context
before its contextified). This V8 Context provides the code run using the node:vm
module's methods with an isolated global environment within which it can operate.
The process of creating the V8 Context and associating it with the contextObject
in the outer context is what this document refers to as "contextifying" the object.
The contextifying would introduce some quirks to the globalThis value in the context.
For example, it cannot be frozen, and it is not reference equal to the contextObject
in the outer context.
const vm = require('node:vm');
const context = vm.createContext();
console.log(vm.runInContext('globalThis', context) === context);
try {
vm.runInContext('Object.freeze(globalThis);', context);
} catch (e) {
console.log(e);
}
console.log(vm.runInContext('globalThis.foo = 1; foo;', context));
To create a context with an ordinary global object and get access to a global proxy in
the outer context with fewer quirks, specify vm.constants.DONT_CONTEXTIFY as the
contextObject argument.
vm.constants.DONT_CONTEXTIFY#
This constant, when used as the contextObject argument in vm APIs, instructs Node.js to create
a context without wrapping its global object with another object in a Node.js-specific manner.
As a result, the globalThis value inside the new context would behave more closely to an ordinary
one.
const vm = require('node:vm');
const context = vm.createContext(vm.constants.DONT_CONTEXTIFY);
vm.runInContext('Object.freeze(globalThis);', context);
try {
vm.runInContext('bar = 1; bar;', context);
} catch (e) {
console.log(e);
}
When vm.constants.DONT_CONTEXTIFY is used as the contextObject argument to vm.createContext(),
the returned object is a proxy-like object to the global object in the newly created context with
fewer Node.js-specific quirks. It is reference equal to the globalThis value in the new context,
can be modified from outside the context, and can be used to access built-ins in the new context directly.
const vm = require('node:vm');
const context = vm.createContext(vm.constants.DONT_CONTEXTIFY);
console.log(vm.runInContext('globalThis', context) === context);
console.log(context.Array);
vm.runInContext('foo = 1;', context);
console.log(context.foo);
context.bar = 1;
console.log(vm.runInContext('bar;', context));
Object.freeze(context);
try {
vm.runInContext('baz = 1; baz;', context);
} catch (e) {
console.log(e);
}
Timeout interactions with asynchronous tasks and Promises#
Promises and async functions can schedule tasks run by the JavaScript
engine asynchronously. By default, these tasks are run after all JavaScript
functions on the current stack are done executing.
This allows escaping the functionality of the timeout and
breakOnSigint options.
For example, the following code executed by vm.runInNewContext() with a
timeout of 5 milliseconds schedules an infinite loop to run after a promise
resolves. The scheduled loop is never interrupted by the timeout:
const vm = require('node:vm');
function loop() {
console.log('entering loop');
while (1) console.log(Date.now());
}
vm.runInNewContext(
'Promise.resolve().then(() => loop());',
{ loop, console },
{ timeout: 5 },
);
console.log('done executing');
This can be addressed by passing microtaskMode: 'afterEvaluate' to the code
that creates the Context:
const vm = require('node:vm');
function loop() {
while (1) console.log(Date.now());
}
vm.runInNewContext(
'Promise.resolve().then(() => loop());',
{ loop, console },
{ timeout: 5, microtaskMode: 'afterEvaluate' },
);
In this case, the microtask scheduled through promise.then() will be run
before returning from vm.runInNewContext(), and will be interrupted
by the timeout functionality. This applies only to code running in a
vm.Context, so e.g. vm.runInThisContext() does not take this option.
Promise callbacks are entered into the microtask queue of the context in which
they were created. For example, if () => loop() is replaced with just loop
in the above example, then loop will be pushed into the global microtask
queue, because it is a function from the outer (main) context, and thus will
also be able to escape the timeout.
If asynchronous scheduling functions such as process.nextTick(),
queueMicrotask(), setTimeout(), setImmediate(), etc. are made available
inside a vm.Context, functions passed to them will be added to global queues,
which are shared by all contexts. Therefore, callbacks passed to those functions
are not controllable through the timeout either.
When microtaskMode is 'afterEvaluate', beware sharing Promises between Contexts#
In 'afterEvaluate' mode, the Context has its own microtask queue, separate
from the global microtask queue used by the outer (main) context. While this
mode is necessary to enforce timeout and enable breakOnSigint with
asynchronous tasks, it also makes sharing promises between contexts challenging.
In the example below, a promise is created in the inner context and shared with
the outer context. When the outer context await on the promise, the execution
flow of the outer context is disrupted in a surprising way: the log statement
is never executed.
import * as vm from 'node:vm';
const inner_context = vm.createContext({}, { microtaskMode: 'afterEvaluate' });
const inner_promise = vm.runInContext(
'Promise.resolve()',
context,
);
await inner_promise;
console.log('this will NOT be printed');
To successfully share promises between contexts with different microtask queues,
it is necessary to ensure that tasks on the inner microtask queue will be run
whenever the outer context enqueues a task on the inner microtask queue.
The tasks on the microtask queue of a given context are run whenever
runInContext() or SourceTextModule.evaluate() are invoked on a script or
module using this context. In our example, the normal execution flow can be
restored by scheduling a second call to runInContext() before await inner_promise.
setImmediate(() => {
vm.runInContext('', context);
});
await inner_promise;
console.log('OK');
Note: Strictly speaking, in this mode, node:vm departs from the letter of
the ECMAScript specification for enqueing jobs, by allowing asynchronous
tasks from different contexts to run in a different order than they were
enqueued.
Support of dynamic import() in compilation APIs#
The following APIs support an importModuleDynamically option to enable dynamic
import() in code compiled by the vm module.
new vm.Script
vm.compileFunction()
new vm.SourceTextModule
vm.runInThisContext()
vm.runInContext()
vm.runInNewContext()
vm.createContext()
This option is still part of the experimental modules API. We do not recommend
using it in a production environment.
When the importModuleDynamically option is not specified or undefined#
If this option is not specified, or if it's undefined, code containing
import() can still be compiled by the vm APIs, but when the compiled code is
executed and it actually calls import(), the result will reject with
ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING.
When importModuleDynamically is vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER#
This option is currently not supported for vm.SourceTextModule.
With this option, when an import() is initiated in the compiled code, Node.js
would use the default ESM loader from the main context to load the requested
module and return it to the code being executed.
This gives access to Node.js built-in modules such as fs or http
to the code being compiled. If the code is executed in a different context,
be aware that the objects created by modules loaded from the main context
are still from the main context and not instanceof built-in classes in the
new context.
const { Script, constants } = require('node:vm');
const script = new Script(
'import("node:fs").then(({readFile}) => readFile instanceof Function)',
{ importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER });
script.runInNewContext().then(console.log);import { Script, constants } from 'node:vm';
const script = new Script(
'import("node:fs").then(({readFile}) => readFile instanceof Function)',
{ importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER });
script.runInNewContext().then(console.log);
This option also allows the script or function to load user modules:
import { Script, constants } from 'node:vm';
import { resolve } from 'node:path';
import { writeFileSync } from 'node:fs';
writeFileSync(resolve(import.meta.dirname, 'test.mjs'),
'export const filename = "./test.json";');
writeFileSync(resolve(import.meta.dirname, 'test.json'),
'{"hello": "world"}');
const script = new Script(
`(async function() {
const { filename } = await import('./test.mjs');
return import(filename, { with: { type: 'json' } })
})();`,
{
filename: resolve(import.meta.dirname, 'test-with-default.js'),
importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
});
script.runInThisContext().then(console.log);const { Script, constants } = require('node:vm');
const { resolve } = require('node:path');
const { writeFileSync } = require('node:fs');
writeFileSync(resolve(__dirname, 'test.mjs'),
'export const filename = "./test.json";');
writeFileSync(resolve(__dirname, 'test.json'),
'{"hello": "world"}');
const script = new Script(
`(async function() {
const { filename } = await import('./test.mjs');
return import(filename, { with: { type: 'json' } })
})();`,
{
filename: resolve(__dirname, 'test-with-default.js'),
importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
});
script.runInThisContext().then(console.log);
There are a few caveats with loading user modules using the default loader
from the main context:
- The module being resolved would be relative to the
filename option passed
to vm.Script or vm.compileFunction(). The resolution can work with a
filename that's either an absolute path or a URL string. If filename is
a string that's neither an absolute path or a URL, or if it's undefined,
the resolution will be relative to the current working directory
of the process. In the case of vm.createContext(), the resolution is always
relative to the current working directory since this option is only used when
there isn't a referrer script or module.
- For any given
filename that resolves to a specific path, once the process
manages to load a particular module from that path, the result may be cached,
and subsequent load of the same module from the same path would return the
same thing. If the filename is a URL string, the cache would not be hit
if it has different search parameters. For filenames that are not URL
strings, there is currently no way to bypass the caching behavior.
When importModuleDynamically is a function#
When importModuleDynamically is a function, it will be invoked when import()
is called in the compiled code for users to customize how the requested module
should be compiled and evaluated. Currently, the Node.js instance must be
launched with the --experimental-vm-modules flag for this option to work. If
the flag isn't set, this callback will be ignored. If the code evaluated
actually calls to import(), the result will reject with
ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG.
The callback importModuleDynamically(specifier, referrer, importAttributes)
has the following signature:
specifier <string> specifier passed to import()
referrer <vm.Script> | <Function> | <vm.SourceTextModule> | <Object>
The referrer is the compiled vm.Script for new vm.Script,
vm.runInThisContext, vm.runInContext and vm.runInNewContext. It's the
compiled Function for vm.compileFunction, the compiled
vm.SourceTextModule for new vm.SourceTextModule, and the context Object
for vm.createContext().
importAttributes <Object> The "with" value passed to the
optionsExpression optional parameter, or an empty object if no value was
provided.
- Returns: <Module Namespace Object> | <vm.Module> Returning a
vm.Module is
recommended in order to take advantage of error tracking, and to avoid issues
with namespaces that contain then function exports.
import { Script, SyntheticModule } from 'node:vm';
const script = new Script('import("foo.json", { with: { type: "json" } })', {
async importModuleDynamically(specifier, referrer, importAttributes) {
console.log(specifier);
console.log(referrer);
console.log(importAttributes);
const m = new SyntheticModule(['bar'], () => { });
await m.link(() => { });
m.setExport('bar', { hello: 'world' });
return m;
},
});
const result = await script.runInThisContext();
console.log(result);
const { Script, SyntheticModule } = require('node:vm');
(async function main() {
const script = new Script('import("foo.json", { with: { type: "json" } })', {
async importModuleDynamically(specifier, referrer, importAttributes) {
console.log(specifier);
console.log(referrer);
console.log(importAttributes);
const m = new SyntheticModule(['bar'], () => { });
await m.link(() => { });
m.setExport('bar', { hello: 'world' });
return m;
},
});
const result = await script.runInThisContext();
console.log(result);
})();