1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: fix, unify, formalize, and amplify vm.md

Browse Source 
`vm` module API heavily reuses common code, but the doc seems
to be a bit out of date: some options are listed in wrong places,
some options and history entries are missed.

Also some fragments need to be formalized and unified.

PR-URL: https://github.com/nodejs/node/pull/25422
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
This commit is contained in:
Vse Mozhet Byt 2019-01-09 21:49:28 +02:00
parent 56e7a7cbfe
commit c69ea3b1d5
3 changed files with 211 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/v8.md
View File

@ -414,7 +414,7 @@ A subclass of [`Deserializer`][] corresponding to the format written by
[`serializer.releaseBuffer()`]: #v8_serializer_releasebuffer [`serializer.releaseBuffer()`]: #v8_serializer_releasebuffer
[`serializer.transferArrayBuffer()`]: #v8_serializer_transferarraybuffer_id_arraybuffer [`serializer.transferArrayBuffer()`]: #v8_serializer_transferarraybuffer_id_arraybuffer
[`serializer.writeRawBytes()`]: #v8_serializer_writerawbytes_buffer [`serializer.writeRawBytes()`]: #v8_serializer_writerawbytes_buffer
[`vm.Script`]: vm.html#vm_new_vm_script_code_options [`vm.Script`]: vm.html#vm_constructor_new_vm_script_code_options
[HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
[V8]: https://developers.google.com/v8/ [V8]: https://developers.google.com/v8/
[here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md [here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md

286
doc/api/vm.md
View File

@ -164,22 +164,22 @@ const contextifiedSandbox = vm.createContext({ secret: 42 });
* `context` {Object} The [contextified][] object as returned by the * `context` {Object} The [contextified][] object as returned by the
`vm.createContext()` method, to compile and evaluate this `Module` in. `vm.createContext()` method, to compile and evaluate this `Module` in.
* `lineOffset` {integer} Specifies the line number offset that is displayed * `lineOffset` {integer} Specifies the line number offset that is displayed
in stack traces produced by this `Module`. in stack traces produced by this `Module`. **Default:** `0`.
* `columnOffset` {integer} Specifies the column number offset that is * `columnOffset` {integer} Specifies the column number offset that is
displayed in stack traces produced by this `Module`. displayed in stack traces produced by this `Module`. **Default:** `0`.
* `initializeImportMeta` {Function} Called during evaluation of this `Module` * `initializeImportMeta` {Function} Called during evaluation of this `Module`
to initialize the `import.meta`. This function has the signature `(meta, to initialize the `import.meta`.
module)`, where `meta` is the `import.meta` object in the `Module`, and * `meta` {import.meta}
`module` is this `vm.SourceTextModule` object. * `module` {vm.SourceTextModule}
* `importModuleDynamically` {Function} Called during evaluation of this * `importModuleDynamically` {Function} Called during evaluation of this module
module when `import()` is called. This function has the signature when `import()` is called. If this option is not specified, calls to
`(specifier, module)` where `specifier` is the specifier passed to `import()` will reject with [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][].
`import()` and `module` is this `vm.SourceTextModule`. If this option is * `specifier` {string} specifier passed to `import()`
not specified, calls to `import()` will reject with * `module` {vm.SourceTextModule}
[`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][]. This method can return a * Returns: {Module Namespace Object|vm.SourceTextModule} Returning a
[Module Namespace Object][], but returning a `vm.SourceTextModule` is `vm.SourceTextModule` is recommended in order to take advantage of error
recommended in order to take advantage of error tracking, and to avoid tracking, and to avoid issues with namespaces that contain `then`
issues with namespaces that contain `then` function exports. function exports.
Creates a new ES `Module` object. Creates a new ES `Module` object.
@ -253,7 +253,7 @@ in the ECMAScript specification.
`SIGINT` (Ctrl+C) is received. Existing handlers for the event that have `SIGINT` (Ctrl+C) is received. Existing handlers for the event that have
been attached via `process.on('SIGINT')` will be disabled during script been attached via `process.on('SIGINT')` will be disabled during script
execution, but will continue to work after that. If execution is execution, but will continue to work after that. If execution is
interrupted, an [`Error`][] will be thrown. interrupted, an [`Error`][] will be thrown. **Default:** `false`.
* Returns: {Promise} * Returns: {Promise}
Evaluate the module. Evaluate the module.
@ -293,20 +293,19 @@ Module Record][]s in the ECMAScript specification.
### module.link(linker) ### module.link(linker)
* `linker` {Function} * `linker` {Function}
* Returns: {Promise} * `specifier` {string} The specifier of the requested module:
Link module dependencies. This method must be called before instantiation, and
can only be called once per module.
Two parameters will be passed to the `linker` function:
- `specifier` The specifier of the requested module:
<!-- eslint-skip --> <!-- eslint-skip -->
```js ```js
import foo from 'foo'; import foo from 'foo';
// ^^^^^ the module specifier // ^^^^^ the module specifier
``` ```
- `referencingModule` The `Module` object `link()` is called on. * `referencingModule` {vm.SourceTextModule} The `Module` object `link()` is
called on.
* Returns: {vm.SourceTextModule|Promise}
* Returns: {Promise}
Link module dependencies. This method must be called before instantiation, and
can only be called once per module.
The function is expected to return a `Module` object or a `Promise` that 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 eventually resolves to a `Module` object. The returned `Module` must satisfy the
@ -412,7 +411,7 @@ added: v0.3.1
Instances of the `vm.Script` class contain precompiled scripts that can be Instances of the `vm.Script` class contain precompiled scripts that can be
executed in specific sandboxes (or "contexts"). executed in specific sandboxes (or "contexts").
### new vm.Script(code, options) ### Constructor: new vm.Script(code[, options])
<!-- YAML <!-- YAML
added: v0.3.1 added: v0.3.1
changes: changes:
@ -427,13 +426,13 @@ changes:
--> -->
* `code` {string} The JavaScript code to compile. * `code` {string} The JavaScript code to compile.
* `options` * `options` {Object|string}
* `filename` {string} Specifies the filename used in stack traces produced * `filename` {string} Specifies the filename used in stack traces produced
by this script. by this script. **Default:** `'evalmachine.<anonymous>'`.
* `lineOffset` {number} Specifies the line number offset that is displayed * `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `columnOffset` {number} Specifies the column number offset that is displayed * `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `cachedData` {Buffer|TypedArray|DataView} Provides an optional `Buffer` or * `cachedData` {Buffer|TypedArray|DataView} Provides an optional `Buffer` or
`TypedArray`, or `DataView` with V8's code cache data for the supplied `TypedArray`, or `DataView` with V8's code cache data for the supplied
source. When supplied, the `cachedDataRejected` value will be set to source. When supplied, the `cachedDataRejected` value will be set to
@ -444,16 +443,21 @@ changes:
`cachedData` property of the returned `vm.Script` instance. `cachedData` property of the returned `vm.Script` instance.
The `cachedDataProduced` value will be set to either `true` or `false` The `cachedDataProduced` value will be set to either `true` or `false`
depending on whether code cache data is produced successfully. depending on whether code cache data is produced successfully.
This option is deprecated in favor of `script.createCachedData()`. This option is **deprecated** in favor of `script.createCachedData()`.
* `importModuleDynamically` {Function} Called during evaluation of this **Default:** `false`.
module when `import()` is called. This function has the signature * `importModuleDynamically` {Function} Called during evaluation of this module
`(specifier, module)` where `specifier` is the specifier passed to when `import()` is called. If this option is not specified, calls to
`import()` and `module` is this `vm.SourceTextModule`. If this option is `import()` will reject with [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][].
not specified, calls to `import()` will reject with This option is part of the experimental API for the `--experimental-modules`
[`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][]. This method can return a flag, and should not be considered stable.
[Module Namespace Object][], but returning a `vm.SourceTextModule` is * `specifier` {string} specifier passed to `import()`
recommended in order to take advantage of error tracking, and to avoid * `module` {vm.SourceTextModule}
issues with namespaces that contain `then` function exports. * Returns: {Module Namespace Object|vm.SourceTextModule} Returning a
`vm.SourceTextModule` is recommended in order to take advantage of error
tracking, and to avoid issues with namespaces that contain `then`
function exports.
If `options` is a string, then it specifies the filename.
Creating a new `vm.Script` object compiles `code` but does not run it. The 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 compiled `vm.Script` can be run later multiple times. The `code` is not bound to
@ -498,23 +502,18 @@ changes:
* `contextifiedSandbox` {Object} A [contextified][] object as returned by the * `contextifiedSandbox` {Object} A [contextified][] object as returned by the
`vm.createContext()` method. `vm.createContext()` method.
* `options` {Object} * `options` {Object}
* `filename` {string} Specifies the filename used in stack traces produced * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs
by this script.
* `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script.
* `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script.
* `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs
while compiling the `code`, the line of code causing the error is attached while compiling the `code`, the line of code causing the error is attached
to the stack trace. to the stack trace. **Default:** `true`.
* `timeout` {integer} Specifies the number of milliseconds to execute `code` * `timeout` {integer} Specifies the number of milliseconds to execute `code`
before terminating execution. If execution is terminated, an [`Error`][] before terminating execution. If execution is terminated, an [`Error`][]
will be thrown. This value must be a strictly positive integer. will be thrown. This value must be a strictly positive integer.
* `breakOnSigint`: if `true`, the execution will be terminated when * `breakOnSigint` {boolean} If `true`, the execution will be terminated when
`SIGINT` (Ctrl+C) is received. Existing handlers for the `SIGINT` (Ctrl+C) is received. Existing handlers for the
event that have been attached via `process.on('SIGINT')` will be disabled event that have been attached via `process.on('SIGINT')` will be disabled
during script execution, but will continue to work after that. during script execution, but will continue to work after that. If execution
If execution is terminated, an [`Error`][] will be thrown. is terminated, an [`Error`][] will be thrown. **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 Runs the compiled code contained by the `vm.Script` object within the given
`contextifiedSandbox` and returns the result. Running code does not have access `contextifiedSandbox` and returns the result. Running code does not have access
@ -556,23 +555,25 @@ changes:
- version: v10.0.0 - version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/19016 pr-url: https://github.com/nodejs/node/pull/19016
description: The `contextCodeGeneration` option is supported now. description: The `contextCodeGeneration` option is supported now.
- version: v6.3.0
pr-url: https://github.com/nodejs/node/pull/6635
description: The `breakOnSigint` option is supported now.
--> -->
* `sandbox` {Object} An object that will be [contextified][]. If `undefined`, a * `sandbox` {Object} An object that will be [contextified][]. If `undefined`, a
new object will be created. new object will be created.
* `options` {Object} * `options` {Object}
* `filename` {string} Specifies the filename used in stack traces produced * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs
by this script.
* `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script.
* `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script.
* `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs
while compiling the `code`, the line of code causing the error is attached while compiling the `code`, the line of code causing the error is attached
to the stack trace. to the stack trace. **Default:** `true`.
* `timeout` {integer} Specifies the number of milliseconds to execute `code` * `timeout` {integer} Specifies the number of milliseconds to execute `code`
before terminating execution. If execution is terminated, an [`Error`][] before terminating execution. If execution is terminated, an [`Error`][]
will be thrown. This value must be a strictly positive integer. will be thrown. This value must be a strictly positive integer.
* `breakOnSigint` {boolean} 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. **Default:** `false`.
* `contextName` {string} Human-readable name of the newly created context. * `contextName` {string} Human-readable name of the newly created context.
**Default:** `'VM Context i'`, where `i` is an ascending numerical index of **Default:** `'VM Context i'`, where `i` is an ascending numerical index of
the created context. the created context.
@ -588,6 +589,7 @@ changes:
`EvalError`. **Default:** `true`. `EvalError`. **Default:** `true`.
* `wasm` {boolean} If set to false any attempt to compile a WebAssembly * `wasm` {boolean} If set to false any attempt to compile a WebAssembly
module will throw a `WebAssembly.CompileError`. **Default:** `true`. module will throw a `WebAssembly.CompileError`. **Default:** `true`.
* Returns: {any} the result of the very last statement executed in the script.
First contextifies the given `sandbox`, runs the compiled code contained by First contextifies the given `sandbox`, runs the compiled code contained by
the `vm.Script` object within the created sandbox, and returns the result. the `vm.Script` object within the created sandbox, and returns the result.
@ -616,21 +618,25 @@ console.log(util.inspect(sandboxes));
### script.runInThisContext([options]) ### script.runInThisContext([options])
<!-- YAML <!-- YAML
added: v0.3.1 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.
--> -->
* `options` {Object} * `options` {Object}
* `filename` {string} Specifies the filename used in stack traces produced * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs
by this script.
* `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script.
* `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script.
* `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs
while compiling the `code`, the line of code causing the error is attached while compiling the `code`, the line of code causing the error is attached
to the stack trace. to the stack trace. **Default:** `true`.
* `timeout` {integer} Specifies the number of milliseconds to execute `code` * `timeout` {integer} Specifies the number of milliseconds to execute `code`
before terminating execution. If execution is terminated, an [`Error`][] before terminating execution. If execution is terminated, an [`Error`][]
will be thrown. This value must be a strictly positive integer. will be thrown. This value must be a strictly positive integer.
* `breakOnSigint` {boolean} 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. **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 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 current `global` object. Running code does not have access to local scope, but
@ -679,6 +685,7 @@ added: v10.10.0
* `contextExtensions` {Object[]} An array containing a collection of context * `contextExtensions` {Object[]} An array containing a collection of context
extensions (objects wrapping the current scope) to be applied while extensions (objects wrapping the current scope) to be applied while
compiling. **Default:** `[]`. compiling. **Default:** `[]`.
* Returns: {Function}
Compiles the given code into the provided context/sandbox (if no context is Compiles the given code into the provided context/sandbox (if no context is
supplied, the current context is used), and returns it wrapped inside a supplied, the current context is used), and returns it wrapped inside a
@ -690,7 +697,7 @@ added: v0.3.1
changes: changes:
- version: v10.0.0 - version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/19398 pr-url: https://github.com/nodejs/node/pull/19398
description: The `sandbox` option can no longer be a function. description: The `sandbox` object can no longer be a function.
- version: v10.0.0 - version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/19016 pr-url: https://github.com/nodejs/node/pull/19016
description: The `codeGeneration` option is supported now. description: The `codeGeneration` option is supported now.
@ -713,6 +720,7 @@ changes:
`EvalError`. **Default:** `true`. `EvalError`. **Default:** `true`.
* `wasm` {boolean} If set to false any attempt to compile a WebAssembly * `wasm` {boolean} If set to false any attempt to compile a WebAssembly
module will throw a `WebAssembly.CompileError`. **Default:** `true`. module will throw a `WebAssembly.CompileError`. **Default:** `true`.
* Returns: {Object} contextified sandbox.
If given a `sandbox` object, the `vm.createContext()` method will [prepare If given a `sandbox` object, the `vm.createContext()` method will [prepare
that sandbox][contextified] so that it can be used in calls to that sandbox][contextified] so that it can be used in calls to
@ -762,23 +770,59 @@ Returns `true` if the given `sandbox` object has been [contextified][] using
[`vm.createContext()`][]. [`vm.createContext()`][].
## vm.runInContext(code, contextifiedSandbox[, options]) ## vm.runInContext(code, contextifiedSandbox[, options])
<!-- YAML
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.
-->
* `code` {string} The JavaScript code to compile and run. * `code` {string} The JavaScript code to compile and run.
* `contextifiedSandbox` {Object} The [contextified][] object that will be used * `contextifiedSandbox` {Object} The [contextified][] object that will be used
as the `global` when the `code` is compiled and run. as the `global` when the `code` is compiled and run.
* `options` {Object|string} * `options` {Object|string}
* `filename` {string} Specifies the filename used in stack traces produced * `filename` {string} Specifies the filename used in stack traces produced
by this script. by this script. **Default:** `'evalmachine.<anonymous>'`.
* `lineOffset` {number} Specifies the line number offset that is displayed * `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `columnOffset` {number} Specifies the column number offset that is displayed * `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs
while compiling the `code`, the line of code causing the error is attached while compiling the `code`, the line of code causing the error is attached
to the stack trace. to the stack trace. **Default:** `true`.
* `timeout` {integer} Specifies the number of milliseconds to execute `code` * `timeout` {integer} Specifies the number of milliseconds to execute `code`
before terminating execution. If execution is terminated, an [`Error`][] before terminating execution. If execution is terminated, an [`Error`][]
will be thrown. This value must be a strictly positive integer. will be thrown. This value must be a strictly positive integer.
* `breakOnSigint` {boolean} 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. **Default:** `false`.
* `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} Called during evaluation of this module
when `import()` is called. If this option is not specified, calls to
`import()` will reject with [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][].
This option is part of the experimental API for the `--experimental-modules`
flag, and should not be considered stable.
* `specifier` {string} specifier passed to `import()`
* `module` {vm.SourceTextModule}
* Returns: {Module Namespace Object|vm.SourceTextModule} Returning a
`vm.SourceTextModule` is recommended in order to take advantage of error
tracking, and to avoid issues with namespaces that contain `then`
function exports.
* Returns: {any} the result of the very last statement executed in the script.
The `vm.runInContext()` method compiles `code`, runs it within the context of The `vm.runInContext()` method compiles `code`, runs it within the context of
the `contextifiedSandbox`, then returns the result. Running code does not have the `contextifiedSandbox`, then returns the result. Running code does not have
@ -808,6 +852,13 @@ console.log(util.inspect(sandbox));
## vm.runInNewContext(code[, sandbox[, options]]) ## vm.runInNewContext(code[, sandbox[, options]])
<!-- YAML <!-- YAML
added: v0.3.1 added: v0.3.1
changes:
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/19016
description: The `contextCodeGeneration` option is supported now.
- version: v6.3.0
pr-url: https://github.com/nodejs/node/pull/6635
description: The `breakOnSigint` option is supported now.
--> -->
* `code` {string} The JavaScript code to compile and run. * `code` {string} The JavaScript code to compile and run.
@ -815,17 +866,22 @@ added: v0.3.1
new object will be created. new object will be created.
* `options` {Object|string} * `options` {Object|string}
* `filename` {string} Specifies the filename used in stack traces produced * `filename` {string} Specifies the filename used in stack traces produced
by this script. by this script. **Default:** `'evalmachine.<anonymous>'`.
* `lineOffset` {number} Specifies the line number offset that is displayed * `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `columnOffset` {number} Specifies the column number offset that is displayed * `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs
while compiling the `code`, the line of code causing the error is attached while compiling the `code`, the line of code causing the error is attached
to the stack trace. to the stack trace. **Default:** `true`.
* `timeout` {integer} Specifies the number of milliseconds to execute `code` * `timeout` {integer} Specifies the number of milliseconds to execute `code`
before terminating execution. If execution is terminated, an [`Error`][] before terminating execution. If execution is terminated, an [`Error`][]
will be thrown. This value must be a strictly positive integer. will be thrown. This value must be a strictly positive integer.
* `breakOnSigint` {boolean} 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. **Default:** `false`.
* `contextName` {string} Human-readable name of the newly created context. * `contextName` {string} Human-readable name of the newly created context.
**Default:** `'VM Context i'`, where `i` is an ascending numerical index of **Default:** `'VM Context i'`, where `i` is an ascending numerical index of
the created context. the created context.
@ -835,6 +891,36 @@ added: v0.3.1
value of the [`url.origin`][] property of a [`URL`][] object. Most notably, value of the [`url.origin`][] property of a [`URL`][] object. Most notably,
this string should omit the trailing slash, as that denotes a path. this string should omit the trailing slash, as that denotes a path.
**Default:** `''`. **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. 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} Called during evaluation of this module
when `import()` is called. If this option is not specified, calls to
`import()` will reject with [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][].
This option is part of the experimental API for the `--experimental-modules`
flag, and should not be considered stable.
* `specifier` {string} specifier passed to `import()`
* `module` {vm.SourceTextModule}
* Returns: {Module Namespace Object|vm.SourceTextModule} Returning a
`vm.SourceTextModule` is recommended in order to take advantage of error
tracking, and to avoid issues with namespaces that contain `then`
function exports.
* Returns: {any} the result of the very last statement executed in the script.
The `vm.runInNewContext()` first contextifies the given `sandbox` object (or The `vm.runInNewContext()` first contextifies the given `sandbox` object (or
creates a new `sandbox` if passed as `undefined`), compiles the `code`, runs it creates a new `sandbox` if passed as `undefined`), compiles the `code`, runs it
@ -864,22 +950,55 @@ console.log(util.inspect(sandbox));
## vm.runInThisContext(code[, options]) ## vm.runInThisContext(code[, options])
<!-- YAML <!-- YAML
added: v0.3.1 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.
--> -->
* `code` {string} The JavaScript code to compile and run. * `code` {string} The JavaScript code to compile and run.
* `options` {Object|string} * `options` {Object|string}
* `filename` {string} Specifies the filename used in stack traces produced * `filename` {string} Specifies the filename used in stack traces produced
by this script. by this script. **Default:** `'evalmachine.<anonymous>'`.
* `lineOffset` {number} Specifies the line number offset that is displayed * `lineOffset` {number} Specifies the line number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `columnOffset` {number} Specifies the column number offset that is displayed * `columnOffset` {number} Specifies the column number offset that is displayed
in stack traces produced by this script. in stack traces produced by this script. **Default:** `0`.
* `displayErrors` {boolean} When `true`, if an [`Error`][] error occurs * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs
while compiling the `code`, the line of code causing the error is attached while compiling the `code`, the line of code causing the error is attached
to the stack trace. to the stack trace. **Default:** `true`.
* `timeout` {integer} Specifies the number of milliseconds to execute `code` * `timeout` {integer} Specifies the number of milliseconds to execute `code`
before terminating execution. If execution is terminated, an [`Error`][] before terminating execution. If execution is terminated, an [`Error`][]
will be thrown. This value must be a strictly positive integer. will be thrown. This value must be a strictly positive integer.
* `breakOnSigint` {boolean} 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. **Default:** `false`.
* `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} Called during evaluation of this module
when `import()` is called. If this option is not specified, calls to
`import()` will reject with [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][].
This option is part of the experimental API for the `--experimental-modules`
flag, and should not be considered stable.
* `specifier` {string} specifier passed to `import()`
* `module` {vm.SourceTextModule}
* Returns: {Module Namespace Object|vm.SourceTextModule} Returning a
`vm.SourceTextModule` is recommended in order to take advantage of error
tracking, and to avoid issues with namespaces that contain `then`
function exports.
* Returns: {any} the result of the very last statement executed in the script.
`vm.runInThisContext()` compiles `code`, runs it within the context of the `vm.runInThisContext()` compiles `code`, runs it within the context of the
current `global` and returns the result. Running code does not have access to current `global` and returns the result. Running code does not have access to
@ -1010,9 +1129,8 @@ queues.
[GetModuleNamespace]: https://tc39.github.io/ecma262/#sec-getmodulenamespace [GetModuleNamespace]: https://tc39.github.io/ecma262/#sec-getmodulenamespace
[HostResolveImportedModule]: https://tc39.github.io/ecma262/#sec-hostresolveimportedmodule [HostResolveImportedModule]: https://tc39.github.io/ecma262/#sec-hostresolveimportedmodule
[Instantiate() concrete method]: https://tc39.github.io/ecma262/#sec-moduledeclarationinstantiation [Instantiate() concrete method]: https://tc39.github.io/ecma262/#sec-moduledeclarationinstantiation
[Module Namespace Object]: https://tc39.github.io/ecma262/#sec-module-namespace-exotic-objects
[Source Text Module Record]: https://tc39.github.io/ecma262/#sec-source-text-module-records [Source Text Module Record]: https://tc39.github.io/ecma262/#sec-source-text-module-records
[V8 Embedder's Guide]: https://github.com/v8/v8/wiki/Embedder's%20Guide#contexts [V8 Embedder's Guide]: https://v8.dev/docs/embed#contexts
[contextified]: #vm_what_does_it_mean_to_contextify_an_object [contextified]: #vm_what_does_it_mean_to_contextify_an_object
[global object]: https://es5.github.io/#x15.1 [global object]: https://es5.github.io/#x15.1
[indirect `eval()` call]: https://es5.github.io/#x10.4.2 [indirect `eval()` call]: https://es5.github.io/#x10.4.2

7
tools/doc/type-parser.js
View File

@ -35,6 +35,9 @@ const customTypesMap = {
'Iterator': 'Iterator':
`${jsDocPrefix}Reference/Iteration_protocols#The_iterator_protocol`, `${jsDocPrefix}Reference/Iteration_protocols#The_iterator_protocol`,
'Module Namespace Object':
'https://tc39.github.io/ecma262/#sec-module-namespace-exotic-objects',
'AsyncHook': 'async_hooks.html#async_hooks_async_hooks_createhook_callbacks', 'AsyncHook': 'async_hooks.html#async_hooks_async_hooks_createhook_callbacks',
'AsyncResource': 'async_hooks.html#async_hooks_class_asyncresource', 'AsyncResource': 'async_hooks.html#async_hooks_class_asyncresource',
@ -61,6 +64,8 @@ const customTypesMap = {
'Domain': 'domain.html#domain_class_domain', 'Domain': 'domain.html#domain_class_domain',
'import.meta': 'esm.html#esm_import_meta',
'EventEmitter': 'events.html#events_class_eventemitter', 'EventEmitter': 'events.html#events_class_eventemitter',
'FileHandle': 'fs.html#fs_class_filehandle', 'FileHandle': 'fs.html#fs_class_filehandle',
@ -130,6 +135,8 @@ const customTypesMap = {
'URL': 'url.html#url_the_whatwg_url_api', 'URL': 'url.html#url_the_whatwg_url_api',
'URLSearchParams': 'url.html#url_class_urlsearchparams', 'URLSearchParams': 'url.html#url_class_urlsearchparams',
'vm.SourceTextModule': 'vm.html#vm_class_vm_sourcetextmodule',
'MessagePort': 'worker_threads.html#worker_threads_class_messageport', 'MessagePort': 'worker_threads.html#worker_threads_class_messageport',
'zlib options': 'zlib.html#zlib_class_options', 'zlib options': 'zlib.html#zlib_class_options',