Your IP : 216.73.216.213
{
"source": "doc/api/vm.md",
"modules": [
{
"textRaw": "VM (Executing JavaScript)",
"name": "vm",
"introduced_in": "v0.10.0",
"stability": 2,
"stabilityText": "Stable",
"desc": "<p>The <code>vm</code> module provides APIs for compiling and running code within V8 Virtual\nMachine contexts.</p>\n<p>JavaScript code can be compiled and run immediately or\ncompiled, saved, and run later.</p>\n<p>A common use case is to run the code in a sandboxed environment.\nThe sandboxed code uses a different V8 Context, meaning that\nit has a different global object than the rest of the code.</p>\n<p>One can provide the context by <a href=\"#vm_what_does_it_mean_to_contextify_an_object\">"contextifying"</a> a sandbox\nobject. The sandboxed code treats any property on the sandbox like a\nglobal variable. Any changes on global variables caused by the sandboxed\ncode are reflected in the sandbox object.</p>\n<pre><code class=\"lang-js\">const vm = require('vm');\n\nconst x = 1;\n\nconst sandbox = { x: 2 };\nvm.createContext(sandbox); // Contextify the sandbox.\n\nconst code = 'x += 40; var y = 17;';\n// x and y are global variables in the sandboxed environment.\n// Initially, x has the value 2 because that is the value of sandbox.x.\nvm.runInContext(code, sandbox);\n\nconsole.log(sandbox.x); // 42\nconsole.log(sandbox.y); // 17\n\nconsole.log(x); // 1; y is not defined.\n</code></pre>\n<p><em>Note</em>: The vm module is not a security mechanism.\n<strong>Do not use it to run untrusted code</strong>.</p>\n",
"classes": [
{
"textRaw": "Class: vm.Script",
"type": "class",
"name": "vm.Script",
"meta": {
"added": [
"v0.3.1"
],
"changes": []
},
"desc": "<p>Instances of the <code>vm.Script</code> class contain precompiled scripts that can be\nexecuted in specific sandboxes (or "contexts").</p>\n",
"methods": [
{
"textRaw": "new vm.Script(code, options)",
"type": "method",
"name": "Script",
"meta": {
"added": [
"v0.3.1"
],
"changes": [
{
"version": "v5.7.0",
"pr-url": "https://github.com/nodejs/node/pull/4777",
"description": "The `cachedData` and `produceCachedData` options are supported now."
}
]
},
"signatures": [
{
"params": [
{
"textRaw": "`code` {string} The JavaScript code to compile. ",
"name": "code",
"type": "string",
"desc": "The JavaScript code to compile."
},
{
"textRaw": "`options` ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
},
{
"textRaw": "`cachedData` {Buffer} Provides an optional `Buffer` 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. ",
"name": "cachedData",
"type": "Buffer",
"desc": "Provides an optional `Buffer` 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."
},
{
"textRaw": "`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. ",
"name": "produceCachedData",
"type": "boolean",
"desc": "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."
}
],
"name": "options"
}
]
},
{
"params": [
{
"name": "code"
},
{
"name": "options"
}
]
}
],
"desc": "<p>Creating a new <code>vm.Script</code> object compiles <code>code</code> but does not run it. The\ncompiled <code>vm.Script</code> can be run later multiple times. The <code>code</code> is not bound to\nany global object; rather, it is bound before each run, just for that run.</p>\n"
},
{
"textRaw": "script.runInContext(contextifiedSandbox[, options])",
"type": "method",
"name": "runInContext",
"meta": {
"added": [
"v0.3.1"
],
"changes": [
{
"version": "v6.3.0",
"pr-url": "https://github.com/nodejs/node/pull/6635",
"description": "The `breakOnSigint` option is supported now."
}
]
},
"signatures": [
{
"params": [
{
"textRaw": "`contextifiedSandbox` {Object} A [contextified][] object as returned by the `vm.createContext()` method. ",
"name": "contextifiedSandbox",
"type": "Object",
"desc": "A [contextified][] object as returned by the `vm.createContext()` method."
},
{
"textRaw": "`options` {Object} ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
},
{
"textRaw": "`breakOnSigint`: 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. ",
"name": "breakOnSigint",
"desc": "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."
}
],
"name": "options",
"type": "Object",
"optional": true
}
]
},
{
"params": [
{
"name": "contextifiedSandbox"
},
{
"name": "options",
"optional": true
}
]
}
],
"desc": "<p>Runs the compiled code contained by the <code>vm.Script</code> object within the given\n<code>contextifiedSandbox</code> and returns the result. Running code does not have access\nto local scope.</p>\n<p>The following example compiles code that increments a global variable, sets\nthe value of another global variable, then execute the code multiple times.\nThe globals are contained in the <code>sandbox</code> object.</p>\n<pre><code class=\"lang-js\">const util = require('util');\nconst vm = require('vm');\n\nconst sandbox = {\n animal: 'cat',\n count: 2\n};\n\nconst script = new vm.Script('count += 1; name = "kitty";');\n\nconst context = vm.createContext(sandbox);\nfor (let i = 0; i < 10; ++i) {\n script.runInContext(context);\n}\n\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 12, name: 'kitty' }\n</code></pre>\n<p><em>Note</em>: Using the <code>timeout</code> or <code>breakOnSigint</code> options will result in new\nevent loops and corresponding threads being started, which have a non-zero\nperformance overhead.</p>\n"
},
{
"textRaw": "script.runInNewContext([sandbox[, options]])",
"type": "method",
"name": "runInNewContext",
"meta": {
"added": [
"v0.3.1"
],
"changes": []
},
"signatures": [
{
"params": [
{
"textRaw": "`sandbox` {Object} An object that will be [contextified][]. If `undefined`, a new object will be created. ",
"name": "sandbox",
"type": "Object",
"desc": "An object that will be [contextified][]. If `undefined`, a new object will be created.",
"optional": true
},
{
"textRaw": "`options` {Object} ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
}
],
"name": "options",
"type": "Object",
"optional": true
}
]
},
{
"params": [
{
"name": "sandbox",
"optional": true
},
{
"name": "options",
"optional": true
}
]
}
],
"desc": "<p>First contextifies the given <code>sandbox</code>, runs the compiled code contained by\nthe <code>vm.Script</code> object within the created sandbox, and returns the result.\nRunning code does not have access to local scope.</p>\n<p>The following example compiles code that sets a global variable, then executes\nthe code multiple times in different contexts. The globals are set on and\ncontained within each individual <code>sandbox</code>.</p>\n<pre><code class=\"lang-js\">const util = require('util');\nconst vm = require('vm');\n\nconst script = new vm.Script('globalVar = "set"');\n\nconst sandboxes = [{}, {}, {}];\nsandboxes.forEach((sandbox) => {\n script.runInNewContext(sandbox);\n});\n\nconsole.log(util.inspect(sandboxes));\n\n// [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }]\n</code></pre>\n"
},
{
"textRaw": "script.runInThisContext([options])",
"type": "method",
"name": "runInThisContext",
"meta": {
"added": [
"v0.3.1"
],
"changes": []
},
"signatures": [
{
"params": [
{
"textRaw": "`options` {Object} ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
}
],
"name": "options",
"type": "Object",
"optional": true
}
]
},
{
"params": [
{
"name": "options",
"optional": true
}
]
}
],
"desc": "<p>Runs the compiled code contained by the <code>vm.Script</code> within the context of the\ncurrent <code>global</code> object. Running code does not have access to local scope, but\n<em>does</em> have access to the current <code>global</code> object.</p>\n<p>The following example compiles code that increments a <code>global</code> variable then\nexecutes that code multiple times:</p>\n<pre><code class=\"lang-js\">const vm = require('vm');\n\nglobal.globalVar = 0;\n\nconst script = new vm.Script('globalVar += 1', { filename: 'myfile.vm' });\n\nfor (let i = 0; i < 1000; ++i) {\n script.runInThisContext();\n}\n\nconsole.log(globalVar);\n\n// 1000\n</code></pre>\n"
}
]
}
],
"methods": [
{
"textRaw": "vm.createContext([sandbox])",
"type": "method",
"name": "createContext",
"meta": {
"added": [
"v0.3.1"
],
"changes": []
},
"signatures": [
{
"params": [
{
"textRaw": "`sandbox` {Object} ",
"name": "sandbox",
"type": "Object",
"optional": true
}
]
},
{
"params": [
{
"name": "sandbox",
"optional": true
}
]
}
],
"desc": "<p>If given a <code>sandbox</code> object, the <code>vm.createContext()</code> method will <a href=\"#vm_what_does_it_mean_to_contextify_an_object\">prepare\nthat sandbox</a> so that it can be used in calls to\n<a href=\"#vm_vm_runincontext_code_contextifiedsandbox_options\"><code>vm.runInContext()</code></a> or <a href=\"#vm_script_runincontext_contextifiedsandbox_options\"><code>script.runInContext()</code></a>. Inside such scripts,\nthe <code>sandbox</code> object will be the global object, retaining all of its existing\nproperties but also having the built-in objects and functions any standard\n<a href=\"https://es5.github.io/#x15.1\">global object</a> has. Outside of scripts run by the vm module, global variables\nwill remain unchanged.</p>\n<pre><code class=\"lang-js\">const util = require('util');\nconst vm = require('vm');\n\nglobal.globalVar = 3;\n\nconst sandbox = { globalVar: 1 };\nvm.createContext(sandbox);\n\nvm.runInContext('globalVar *= 2;', sandbox);\n\nconsole.log(util.inspect(sandbox)); // { globalVar: 2 }\n\nconsole.log(util.inspect(globalVar)); // 3\n</code></pre>\n<p>If <code>sandbox</code> is omitted (or passed explicitly as <code>undefined</code>), a new, empty\n<a href=\"#vm_what_does_it_mean_to_contextify_an_object\">contextified</a> sandbox object will be returned.</p>\n<p>The <code>vm.createContext()</code> method is primarily useful for creating a single\nsandbox that can be used to run multiple scripts. For instance, if emulating a\nweb browser, the method can be used to create a single sandbox representing a\nwindow's global object, then run all <code><script></code> tags together within the context\nof that sandbox.</p>\n"
},
{
"textRaw": "vm.isContext(sandbox)",
"type": "method",
"name": "isContext",
"meta": {
"added": [
"v0.11.7"
],
"changes": []
},
"signatures": [
{
"params": [
{
"textRaw": "`sandbox` {Object} ",
"name": "sandbox",
"type": "Object"
}
]
},
{
"params": [
{
"name": "sandbox"
}
]
}
],
"desc": "<p>Returns <code>true</code> if the given <code>sandbox</code> object has been <a href=\"#vm_what_does_it_mean_to_contextify_an_object\">contextified</a> using\n<a href=\"#vm_vm_createcontext_sandbox\"><code>vm.createContext()</code></a>.</p>\n"
},
{
"textRaw": "vm.runInContext(code, contextifiedSandbox[, options])",
"type": "method",
"name": "runInContext",
"signatures": [
{
"params": [
{
"textRaw": "`code` {string} The JavaScript code to compile and run. ",
"name": "code",
"type": "string",
"desc": "The JavaScript code to compile and run."
},
{
"textRaw": "`contextifiedSandbox` {Object} The [contextified][] object that will be used as the `global` when the `code` is compiled and run. ",
"name": "contextifiedSandbox",
"type": "Object",
"desc": "The [contextified][] object that will be used as the `global` when the `code` is compiled and run."
},
{
"textRaw": "`options` ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
}
],
"name": "options",
"optional": true
}
]
},
{
"params": [
{
"name": "code"
},
{
"name": "contextifiedSandbox"
},
{
"name": "options",
"optional": true
}
]
}
],
"desc": "<p>The <code>vm.runInContext()</code> method compiles <code>code</code>, runs it within the context of\nthe <code>contextifiedSandbox</code>, then returns the result. Running code does not have\naccess to the local scope. The <code>contextifiedSandbox</code> object <em>must</em> have been\npreviously <a href=\"#vm_what_does_it_mean_to_contextify_an_object\">contextified</a> using the <a href=\"#vm_vm_createcontext_sandbox\"><code>vm.createContext()</code></a> method.</p>\n<p>The following example compiles and executes different scripts using a single\n<a href=\"#vm_what_does_it_mean_to_contextify_an_object\">contextified</a> object:</p>\n<pre><code class=\"lang-js\">const util = require('util');\nconst vm = require('vm');\n\nconst sandbox = { globalVar: 1 };\nvm.createContext(sandbox);\n\nfor (let i = 0; i < 10; ++i) {\n vm.runInContext('globalVar *= 2;', sandbox);\n}\nconsole.log(util.inspect(sandbox));\n\n// { globalVar: 1024 }\n</code></pre>\n"
},
{
"textRaw": "vm.runInDebugContext(code)",
"type": "method",
"name": "runInDebugContext",
"meta": {
"added": [
"v0.11.14"
],
"changes": []
},
"stability": 0,
"stabilityText": "Deprecated. An alternative is in development.",
"signatures": [
{
"params": [
{
"textRaw": "`code` {string} The JavaScript code to compile and run. ",
"name": "code",
"type": "string",
"desc": "The JavaScript code to compile and run."
}
]
},
{
"params": [
{
"name": "code"
}
]
}
],
"desc": "<p>The <code>vm.runInDebugContext()</code> method compiles and executes <code>code</code> inside the V8\ndebug context. The primary use case is to gain access to the V8 <code>Debug</code> object:</p>\n<pre><code class=\"lang-js\">const vm = require('vm');\nconst Debug = vm.runInDebugContext('Debug');\nconsole.log(Debug.findScript(process.emit).name); // 'events.js'\nconsole.log(Debug.findScript(process.exit).name); // 'internal/process.js'\n</code></pre>\n<p><em>Note</em>: The debug context and object are intrinsically tied to V8's debugger\nimplementation and may change (or even be removed) without prior warning.</p>\n<p>The <code>Debug</code> object can also be made available using the V8-specific\n<code>--expose_debug_as=</code> <a href=\"cli.html\">command line option</a>.</p>\n"
},
{
"textRaw": "vm.runInNewContext(code[, sandbox][, options])",
"type": "method",
"name": "runInNewContext",
"meta": {
"added": [
"v0.3.1"
],
"changes": []
},
"signatures": [
{
"params": [
{
"textRaw": "`code` {string} The JavaScript code to compile and run. ",
"name": "code",
"type": "string",
"desc": "The JavaScript code to compile and run."
},
{
"textRaw": "`sandbox` {Object} An object that will be [contextified][]. If `undefined`, a new object will be created. ",
"name": "sandbox",
"type": "Object",
"desc": "An object that will be [contextified][]. If `undefined`, a new object will be created.",
"optional": true
},
{
"textRaw": "`options` ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
}
],
"name": "options",
"optional": true
}
]
},
{
"params": [
{
"name": "code"
},
{
"name": "sandbox",
"optional": true
},
{
"name": "options",
"optional": true
}
]
}
],
"desc": "<p>The <code>vm.runInNewContext()</code> first contextifies the given <code>sandbox</code> object (or\ncreates a new <code>sandbox</code> if passed as <code>undefined</code>), compiles the <code>code</code>, runs it\nwithin the context of the created context, then returns the result. Running code\ndoes not have access to the local scope.</p>\n<p>The following example compiles and executes code that increments a global\nvariable and sets a new one. These globals are contained in the <code>sandbox</code>.</p>\n<pre><code class=\"lang-js\">const util = require('util');\nconst vm = require('vm');\n\nconst sandbox = {\n animal: 'cat',\n count: 2\n};\n\nvm.runInNewContext('count += 1; name = "kitty"', sandbox);\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 3, name: 'kitty' }\n</code></pre>\n"
},
{
"textRaw": "vm.runInThisContext(code[, options])",
"type": "method",
"name": "runInThisContext",
"meta": {
"added": [
"v0.3.1"
],
"changes": []
},
"signatures": [
{
"params": [
{
"textRaw": "`code` {string} The JavaScript code to compile and run. ",
"name": "code",
"type": "string",
"desc": "The JavaScript code to compile and run."
},
{
"textRaw": "`options` ",
"options": [
{
"textRaw": "`filename` {string} Specifies the filename used in stack traces produced by this script. ",
"name": "filename",
"type": "string",
"desc": "Specifies the filename used in stack traces produced by this script."
},
{
"textRaw": "`lineOffset` {number} Specifies the line number offset that is displayed in stack traces produced by this script. ",
"name": "lineOffset",
"type": "number",
"desc": "Specifies the line number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`columnOffset` {number} Specifies the column number offset that is displayed in stack traces produced by this script. ",
"name": "columnOffset",
"type": "number",
"desc": "Specifies the column number offset that is displayed in stack traces produced by this script."
},
{
"textRaw": "`displayErrors` {boolean} When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace. ",
"name": "displayErrors",
"type": "boolean",
"desc": "When `true`, if an [`Error`][] error occurs while compiling the `code`, the line of code causing the error is attached to the stack trace."
},
{
"textRaw": "`timeout` {number} Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown. ",
"name": "timeout",
"type": "number",
"desc": "Specifies the number of milliseconds to execute `code` before terminating execution. If execution is terminated, an [`Error`][] will be thrown."
}
],
"name": "options",
"optional": true
}
]
},
{
"params": [
{
"name": "code"
},
{
"name": "options",
"optional": true
}
]
}
],
"desc": "<p><code>vm.runInThisContext()</code> compiles <code>code</code>, runs it within the context of the\ncurrent <code>global</code> and returns the result. Running code does not have access to\nlocal scope, but does have access to the current <code>global</code> object.</p>\n<p>The following example illustrates using both <code>vm.runInThisContext()</code> and\nthe JavaScript <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval\"><code>eval()</code></a> function to run the same code:</p>\n<!-- eslint-disable prefer-const -->\n<pre><code class=\"lang-js\">const vm = require('vm');\nlet localVar = 'initial value';\n\nconst vmResult = vm.runInThisContext('localVar = "vm";');\nconsole.log('vmResult:', vmResult);\nconsole.log('localVar:', localVar);\n\nconst evalResult = eval('localVar = "eval";');\nconsole.log('evalResult:', evalResult);\nconsole.log('localVar:', localVar);\n\n// vmResult: 'vm', localVar: 'initial value'\n// evalResult: 'eval', localVar: 'eval'\n</code></pre>\n<p>Because <code>vm.runInThisContext()</code> does not have access to the local scope,\n<code>localVar</code> is unchanged. In contrast, <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval\"><code>eval()</code></a> <em>does</em> have access to the\nlocal scope, so the value <code>localVar</code> is changed. In this way\n<code>vm.runInThisContext()</code> is much like an <a href=\"https://es5.github.io/#x10.4.2\">indirect <code>eval()</code> call</a>, e.g.\n<code>(0,eval)('code')</code>.</p>\n<h2>Example: Running an HTTP Server within a VM</h2>\n<p>When using either <a href=\"#vm_script_runinthiscontext_options\"><code>script.runInThisContext()</code></a> or <a href=\"#vm_vm_runinthiscontext_code_options\"><code>vm.runInThisContext()</code></a>, the\ncode is executed within the current V8 global context. The code passed\nto this VM context will have its own isolated scope.</p>\n<p>In order to run a simple web server using the <code>http</code> module the code passed to\nthe context must either call <code>require('http')</code> on its own, or have a reference\nto the <code>http</code> module passed to it. For instance:</p>\n<pre><code class=\"lang-js\">'use strict';\nconst vm = require('vm');\n\nconst code = `\n((require) => {\n const http = require('http');\n\n http.createServer((request, response) => {\n response.writeHead(200, { 'Content-Type': 'text/plain' });\n response.end('Hello World\\\\n');\n }).listen(8124);\n\n console.log('Server running at http://127.0.0.1:8124/');\n})`;\n\nvm.runInThisContext(code)(require);\n</code></pre>\n<p><em>Note</em>: The <code>require()</code> in the above case shares the state with the context it\nis passed from. This may introduce risks when untrusted code is executed, e.g.\naltering objects in the context in unwanted ways.</p>\n"
}
],
"modules": [
{
"textRaw": "What does it mean to \"contextify\" an object?",
"name": "what_does_it_mean_to_\"contextify\"_an_object?",
"desc": "<p>All JavaScript executed within Node.js runs within the scope of a "context".\nAccording to the <a href=\"https://github.com/v8/v8/wiki/Embedder's%20Guide#contexts\">V8 Embedder's Guide</a>:</p>\n<blockquote>\n<p>In V8, a context is an execution environment that allows separate, unrelated,\nJavaScript applications to run in a single instance of V8. You must explicitly\nspecify the context in which you want any JavaScript code to be run.</p>\n</blockquote>\n<p>When the method <code>vm.createContext()</code> is called, the <code>sandbox</code> object that is\npassed in (or a newly created object if <code>sandbox</code> is <code>undefined</code>) is associated\ninternally with a new instance of a V8 Context. This V8 Context provides the\n<code>code</code> run using the <code>vm</code> module's methods with an isolated global environment\nwithin which it can operate. The process of creating the V8 Context and\nassociating it with the <code>sandbox</code> object is what this document refers to as\n"contextifying" the <code>sandbox</code>.</p>\n",
"type": "module",
"displayName": "What does it mean to \"contextify\" an object?"
}
],
"type": "module",
"displayName": "vm"
}
]
}