vm.runInNewContext

History

vm.runInNewContext(code, contextObject?, options?): any

Attributes

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

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

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

runInNewContext('count += 1; name = "kitty"', contextObject);
console.log(contextObject);
// Prints: { animal: 'cat', count: 3, name: 'kitty' }

// 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 frozenContext = runInNewContext(
  'Object.freeze(globalThis); globalThis;',
  constants.DONT_CONTEXTIFY,
);

JavaScript

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

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

runInNewContext('count += 1; name = "kitty"', contextObject);
console.log(contextObject);
// Prints: { animal: 'cat', count: 3, name: 'kitty' }

// 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 frozenContext = runInNewContext(
  'Object.freeze(globalThis); globalThis;',
  constants.DONT_CONTEXTIFY,
);

JavaScript