diff options
author | Rich Trott <rtrott@gmail.com> | 2021-10-11 07:55:04 +0300 |
---|---|---|
committer | Antoine du Hamel <duhamelantoine1995@gmail.com> | 2021-10-20 12:59:11 +0300 |
commit | d0b58c0287e67a139137aa906819d95f8314b093 (patch) | |
tree | e9a92870138d89b608b1c6e6568611744c32c4f2 /doc/api | |
parent | a7c17e08de658cbc0beefd8e9583803b5a62ac7e (diff) |
doc: format doc/api/*.md with markdown formatter
PR-URL: https://github.com/nodejs/node/pull/40403
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Diffstat (limited to 'doc/api')
58 files changed, 4253 insertions, 1138 deletions
diff --git a/doc/api/addons.md b/doc/api/addons.md index a906306b2cd..3635d5bd54d 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -235,6 +235,7 @@ NODE_MODULE_INIT(/* exports, module, context */) { ``` #### Worker support + <!-- YAML changes: - version: diff --git a/doc/api/assert.md b/doc/api/assert.md index 6a9d830158d..a22a6082c3a 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -10,6 +10,7 @@ The `assert` module provides a set of assertion functions for verifying invariants. ## Strict assertion mode + <!-- YAML added: v9.9.0 changes: @@ -138,6 +139,7 @@ Indicates the failure of an assertion. All errors thrown by the `assert` module will be instances of the `AssertionError` class. ### `new assert.AssertionError(options)` + <!-- YAML added: v0.1.21 --> @@ -216,6 +218,7 @@ try { ``` ## Class: `assert.CallTracker` + <!-- YAML added: - v14.2.0 @@ -227,6 +230,7 @@ added: This feature is currently experimental and behavior might still change. ### `new assert.CallTracker()` + <!-- YAML added: - v14.2.0 @@ -278,6 +282,7 @@ process.on('exit', () => { ``` ### `tracker.calls([fn][, exact])` + <!-- YAML added: - v14.2.0 @@ -320,6 +325,7 @@ const callsfunc = tracker.calls(func); ``` ### `tracker.report()` + <!-- YAML added: - v14.2.0 @@ -396,6 +402,7 @@ tracker.report(); ``` ### `tracker.verify()` + <!-- YAML added: - v14.2.0 @@ -443,6 +450,7 @@ tracker.verify(); ``` ## `assert(value[, message])` + <!-- YAML added: v0.5.9 --> @@ -453,6 +461,7 @@ added: v0.5.9 An alias of [`assert.ok()`][]. ## `assert.deepEqual(actual, expected[, message])` + <!-- YAML added: v0.1.21 changes: @@ -629,6 +638,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the [`AssertionError`][]. ## `assert.deepStrictEqual(actual, expected[, message])` + <!-- YAML added: v1.2.0 changes: @@ -879,6 +889,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## `assert.doesNotMatch(string, regexp[, message])` + <!-- YAML added: - v13.6.0 @@ -929,6 +940,7 @@ instance of an [`Error`][] then it will be thrown instead of the [`AssertionError`][]. ## `assert.doesNotReject(asyncFn[, error][, message])` + <!-- YAML added: v10.0.0 --> @@ -1001,6 +1013,7 @@ assert.doesNotReject(Promise.reject(new TypeError('Wrong value'))) ``` ## `assert.doesNotThrow(fn[, error][, message])` + <!-- YAML added: v0.1.21 changes: @@ -1117,6 +1130,7 @@ assert.doesNotThrow( ``` ## `assert.equal(actual, expected[, message])` + <!-- YAML added: v0.1.21 changes: @@ -1187,6 +1201,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## `assert.fail([message])` + <!-- YAML added: v0.1.21 --> @@ -1227,6 +1242,7 @@ Using `assert.fail()` with more than two arguments is possible but deprecated. See below for further details. ## `assert.fail(actual, expected[, message[, operator[, stackStartFn]]])` + <!-- YAML added: v0.1.21 changes: @@ -1324,6 +1340,7 @@ suppressFrame(); ``` ## `assert.ifError(value)` + <!-- YAML added: v0.1.97 changes: @@ -1397,6 +1414,7 @@ let err; ``` ## `assert.match(string, regexp[, message])` + <!-- YAML added: - v13.6.0 @@ -1447,6 +1465,7 @@ instance of an [`Error`][] then it will be thrown instead of the [`AssertionError`][]. ## `assert.notDeepEqual(actual, expected[, message])` + <!-- YAML added: v0.1.21 changes: @@ -1570,6 +1589,7 @@ If the values are deeply equal, an [`AssertionError`][] is thrown with a instead of the `AssertionError`. ## `assert.notDeepStrictEqual(actual, expected[, message])` + <!-- YAML added: v1.2.0 changes: @@ -1629,6 +1649,7 @@ the `message` parameter is an instance of an [`Error`][] then it will be thrown instead of the [`AssertionError`][]. ## `assert.notEqual(actual, expected[, message])` + <!-- YAML added: v0.1.21 changes: @@ -1693,6 +1714,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## `assert.notStrictEqual(actual, expected[, message])` + <!-- YAML added: v0.1.21 changes: @@ -1745,6 +1767,7 @@ If the values are strictly equal, an [`AssertionError`][] is thrown with a instead of the `AssertionError`. ## `assert.ok(value[, message])` + <!-- YAML added: v0.1.21 changes: @@ -1862,6 +1885,7 @@ assert(0); ``` ## `assert.rejects(asyncFn[, error][, message])` + <!-- YAML added: v10.0.0 --> @@ -1982,6 +2006,7 @@ example in [`assert.throws()`][] carefully if using a string as the second argument gets considered. ## `assert.strictEqual(actual, expected[, message])` + <!-- YAML added: v0.1.21 changes: @@ -2060,6 +2085,7 @@ If the values are not strictly equal, an [`AssertionError`][] is thrown with a instead of the [`AssertionError`][]. ## `assert.throws(fn[, error][, message])` + <!-- YAML added: v0.1.21 changes: diff --git a/doc/api/async_context.md b/doc/api/async_context.md index 78cfc084610..c944d25d34a 100644 --- a/doc/api/async_context.md +++ b/doc/api/async_context.md @@ -7,6 +7,7 @@ <!-- source_link=lib/async_hooks.js --> ## Introduction + These classes are used to associate state and propagate it throughout callbacks and promise chains. They allow storing data throughout the lifetime of a web request @@ -25,6 +26,7 @@ const async_hooks = require('async_hooks'); ``` ## Class: `AsyncLocalStorage` + <!-- YAML added: - v13.10.0 @@ -115,6 +117,7 @@ Multiple instances can safely exist simultaneously without risk of interfering with each other data. ### `new AsyncLocalStorage()` + <!-- YAML added: - v13.10.0 @@ -125,6 +128,7 @@ Creates a new instance of `AsyncLocalStorage`. Store is only provided within a `run()` call or after an `enterWith()` call. ### `asyncLocalStorage.disable()` + <!-- YAML added: - v13.10.0 @@ -149,6 +153,7 @@ Use this method when the `asyncLocalStorage` is not in use anymore in the current process. ### `asyncLocalStorage.getStore()` + <!-- YAML added: - v13.10.0 @@ -163,6 +168,7 @@ calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it returns `undefined`. ### `asyncLocalStorage.enterWith(store)` + <!-- YAML added: - v13.11.0 @@ -212,6 +218,7 @@ asyncLocalStorage.getStore(); // Returns the same object ``` ### `asyncLocalStorage.run(store, callback[, ...args])` + <!-- YAML added: - v13.10.0 @@ -251,6 +258,7 @@ try { ``` ### `asyncLocalStorage.exit(callback[, ...args])` + <!-- YAML added: - v13.10.0 @@ -326,6 +334,7 @@ the loss. When the code logs `undefined`, the last callback called is probably responsible for the context loss. ## Class: `AsyncResource` + <!-- YAML changes: - version: v16.4.0 @@ -434,6 +443,7 @@ class DBQuery extends AsyncResource { ``` ### Static method: `AsyncResource.bind(fn[, type, [thisArg]])` + <!-- YAML added: - v14.8.0 @@ -455,6 +465,7 @@ The returned function will have an `asyncResource` property referencing the `AsyncResource` to which the function is bound. ### `asyncResource.bind(fn[, thisArg])` + <!-- YAML added: - v14.8.0 @@ -474,6 +485,7 @@ The returned function will have an `asyncResource` property referencing the `AsyncResource` to which the function is bound. ### `asyncResource.runInAsyncScope(fn[, thisArg, ...args])` + <!-- YAML added: v9.6.0 --> @@ -507,6 +519,7 @@ never be called. `AsyncResource` constructor. <a id="async-resource-worker-pool"></a> + ### Using `AsyncResource` for a `Worker` thread pool The following example shows how to use the `AsyncResource` class to properly diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 132f2a6bb2e..c3170f8162f 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -190,7 +190,7 @@ const asyncHook = async_hooks.createHook(new MyAddedCallbacks()); Because promises are asynchronous resources whose lifecycle is tracked via the async hooks mechanism, the `init()`, `before()`, `after()`, and -`destroy()` callbacks *must not* be async functions that return promises. +`destroy()` callbacks _must not_ be async functions that return promises. ### Error handling @@ -350,8 +350,8 @@ listening to the hooks. `triggerAsyncId` is the `asyncId` of the resource that caused (or "triggered") the new resource to initialize and that caused `init` to call. This is different -from `async_hooks.executionAsyncId()` that only shows *when* a resource was -created, while `triggerAsyncId` shows *why* a resource was created. +from `async_hooks.executionAsyncId()` that only shows _when_ a resource was +created, while `triggerAsyncId` shows _why_ a resource was created. The following is a simple demonstration of `triggerAsyncId`: @@ -499,13 +499,13 @@ TickObject(6) The `TCPSERVERWRAP` is not part of this graph, even though it was the reason for `console.log()` being called. This is because binding to a port without a host -name is a *synchronous* operation, but to maintain a completely asynchronous +name is a _synchronous_ operation, but to maintain a completely asynchronous API the user's callback is placed in a `process.nextTick()`. Which is why `TickObject` is present in the output and is a 'parent' for `.listen()` callback. -The graph only shows *when* a resource was created, not *why*, so to track -the *why* use `triggerAsyncId`. Which can be represented with the following +The graph only shows _when_ a resource was created, not _why_, so to track +the _why_ use `triggerAsyncId`. Which can be represented with the following graph: ```console @@ -545,7 +545,7 @@ it only once. Called immediately after the callback specified in `before` is completed. If an uncaught exception occurs during execution of the callback, then `after` -will run *after* the `'uncaughtException'` event is emitted or a `domain`'s +will run _after_ the `'uncaughtException'` event is emitted or a `domain`'s handler runs. #### `destroy(asyncId)` diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 5c565724573..abe5c88bd81 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -83,6 +83,7 @@ const buf7 = Buffer.from('tést', 'latin1'); ``` ## Buffers and character encodings + <!-- YAML changes: - version: @@ -233,6 +234,7 @@ the WHATWG specification it is possible that the server actually returned the characters. ## Buffers and TypedArrays + <!-- YAML changes: - version: v3.0.0 @@ -449,6 +451,7 @@ Additionally, the [`buf.values()`][], [`buf.keys()`][], and [`buf.entries()`][] methods can be used to create iterators. ## Class: `Blob` + <!-- YAML added: - v15.7.0 @@ -461,6 +464,7 @@ A [`Blob`][] encapsulates immutable, raw data that can be safely shared across multiple worker threads. ### `new buffer.Blob([sources[, options]])` + <!-- YAML added: - v15.7.0 @@ -472,9 +476,9 @@ changes: and removed the non-standard `encoding` option. --> -* `sources` {string[]|ArrayBuffer[]|TypedArray[]|DataView[]|Blob[]} An array - of string, {ArrayBuffer}, {TypedArray}, {DataView}, or {Blob} objects, or - any mix of such objects, that will be stored within the `Blob`. +* `sources` {string\[]|ArrayBuffer\[]|TypedArray\[]|DataView\[]|Blob\[]} An + array of string, {ArrayBuffer}, {TypedArray}, {DataView}, or {Blob} objects, + or any mix of such objects, that will be stored within the `Blob`. * `options` {Object} * `endings` {string} One of either `'transparent'` or `'native'`. When set to `'native'`, line endings in string source parts will be converted to @@ -493,6 +497,7 @@ Unmatched surrogate pairs within each string part will be replaced by Unicode U+FFFD replacement characters. ### `blob.arrayBuffer()` + <!-- YAML added: - v15.7.0 @@ -505,6 +510,7 @@ Returns a promise that fulfills with an {ArrayBuffer} containing a copy of the `Blob` data. ### `blob.size` + <!-- YAML added: - v15.7.0 @@ -514,6 +520,7 @@ added: The total size of the `Blob` in bytes. ### `blob.slice([start, [end, [type]]])` + <!-- YAML added: - v15.7.0 @@ -528,6 +535,7 @@ Creates and returns a new `Blob` containing a subset of this `Blob` objects data. The original `Blob` is not altered. ### `blob.stream()` + <!-- YAML added: v16.7.0 --> @@ -537,6 +545,7 @@ added: v16.7.0 Returns a new `ReadableStream` that allows the content of the `Blob` to be read. ### `blob.text()` + <!-- YAML added: - v15.7.0 @@ -549,6 +558,7 @@ Returns a promise that fulfills with the contents of the `Blob` decoded as a UTF-8 string. ### `blob.type` + <!-- YAML added: - v15.7.0 @@ -626,6 +636,7 @@ The `Buffer` class is a global type for dealing with binary data directly. It can be constructed in a variety of ways. ### Static method: `Buffer.alloc(size[, fill[, encoding]])` + <!-- YAML added: v5.10.0 changes: @@ -728,6 +739,7 @@ data that might not have been allocated for `Buffer`s. A `TypeError` will be thrown if `size` is not a number. ### Static method: `Buffer.allocUnsafe(size)` + <!-- YAML added: v5.10.0 changes: @@ -746,9 +758,9 @@ Allocates a new `Buffer` of `size` bytes. If `size` is larger than [`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_ARG_VALUE`][] is thrown. -The underlying memory for `Buffer` instances created in this way is *not -initialized*. The contents of the newly created `Buffer` are unknown and -*may contain sensitive data*. Use [`Buffer.alloc()`][] instead to initialize +The underlying memory for `Buffer` instances created in this way is _not +initialized_. The contents of the newly created `Buffer` are unknown and +_may contain sensitive data_. Use [`Buffer.alloc()`][] instead to initialize `Buffer` instances with zeroes. ```mjs @@ -790,13 +802,14 @@ to `Buffer.poolSize >> 1` (floor of [`Buffer.poolSize`][] divided by two). Use of this pre-allocated internal memory pool is a key difference between calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`. -Specifically, `Buffer.alloc(size, fill)` will *never* use the internal `Buffer` -pool, while `Buffer.allocUnsafe(size).fill(fill)` *will* use the internal +Specifically, `Buffer.alloc(size, fill)` will _never_ use the internal `Buffer` +pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal `Buffer` pool if `size` is less than or equal to half [`Buffer.poolSize`][]. The difference is subtle but can be important when an application requires the additional performance that [`Buffer.allocUnsafe()`][] provides. ### Static method: `Buffer.allocUnsafeSlow(size)` + <!-- YAML added: v5.12.0 changes: @@ -812,9 +825,9 @@ Allocates a new `Buffer` of `size` bytes. If `size` is larger than [`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_ARG_VALUE`][] is thrown. A zero-length `Buffer` is created if `size` is 0. -The underlying memory for `Buffer` instances created in this way is *not -initialized*. The contents of the newly created `Buffer` are unknown and -*may contain sensitive data*. Use [`buf.fill(0)`][`buf.fill()`] to initialize +The underlying memory for `Buffer` instances created in this way is _not +initialized_. The contents of the newly created `Buffer` are unknown and +_may contain sensitive data_. Use [`buf.fill(0)`][`buf.fill()`] to initialize such `Buffer` instances with zeroes. When using [`Buffer.allocUnsafe()`][] to allocate new `Buffer` instances, @@ -872,6 +885,7 @@ socket.on('readable', () => { A `TypeError` will be thrown if `size` is not a number. ### Static method: `Buffer.byteLength(string[, encoding])` + <!-- YAML added: v0.1.90 changes: @@ -924,6 +938,7 @@ When `string` is a `Buffer`/[`DataView`][]/[`TypedArray`][]/[`ArrayBuffer`][]/ is returned. ### Static method: `Buffer.compare(buf1, buf2)` + <!-- YAML added: v0.11.13 changes: @@ -966,6 +981,7 @@ console.log(arr.sort(Buffer.compare)); ``` ### Static method: `Buffer.concat(list[, totalLength])` + <!-- YAML added: v0.7.11 changes: @@ -974,7 +990,7 @@ changes: description: The elements of `list` can now be `Uint8Array`s. --> -* `list` {Buffer[] | Uint8Array[]} List of `Buffer` or [`Uint8Array`][] +* `list` {Buffer\[] | Uint8Array\[]} List of `Buffer` or [`Uint8Array`][] instances to concatenate. * `totalLength` {integer} Total length of the `Buffer` instances in `list` when concatenated. @@ -1039,11 +1055,12 @@ console.log(bufA.length); [`Buffer.allocUnsafe()`][] does. ### Static method: `Buffer.from(array)` + <!-- YAML added: v5.10.0 --> -* `array` {integer[]} +* `array` {integer\[]} Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`. Array entries outside that range will be truncated to fit into it. @@ -1069,6 +1086,7 @@ appropriate for `Buffer.from()` variants. `Buffer` pool like [`Buffer.allocUnsafe()`][] does. ### Static method: `Buffer.from(arrayBuffer[, byteOffset[, length]])` + <!-- YAML added: v5.10.0 --> @@ -1184,6 +1202,7 @@ console.log(buf); ``` ### Static method: `Buffer.from(buffer)` + <!-- YAML added: v5.10.0 --> @@ -1225,6 +1244,7 @@ A `TypeError` will be thrown if `buffer` is not a `Buffer` or another type appropriate for `Buffer.from()` variants. ### Static method: `Buffer.from(object[, offsetOrEncoding[, length]])` + <!-- YAML added: v8.2.0 --> @@ -1283,6 +1303,7 @@ A `TypeError` will be thrown if `object` does not have the mentioned methods or is not of another type appropriate for `Buffer.from()` variants. ### Static method: `Buffer.from(string[, encoding])` + <!-- YAML added: v5.10.0 --> @@ -1325,6 +1346,7 @@ A `TypeError` will be thrown if `string` is not a string or another type appropriate for `Buffer.from()` variants. ### Static method: `Buffer.isBuffer(obj)` + <!-- YAML added: v0.1.101 --> @@ -1355,6 +1377,7 @@ Buffer.isBuffer(new Uint8Array(1024)); // false ``` ### Static method: `Buffer.isEncoding(encoding)` + <!-- YAML added: v0.9.1 --> @@ -1398,6 +1421,7 @@ console.log(Buffer.isEncoding('')); ``` ### Class property: `Buffer.poolSize` + <!-- YAML added: v0.11.3 --> @@ -1525,6 +1549,7 @@ new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length); ``` ### `buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])` + <!-- YAML added: v0.11.13 changes: @@ -1553,8 +1578,8 @@ comes before, after, or is the same as `target` in sort order. Comparison is based on the actual sequence of bytes in each `Buffer`. * `0` is returned if `target` is the same as `buf` -* `1` is returned if `target` should come *before* `buf` when sorted. -* `-1` is returned if `target` should come *after* `buf` when sorted. +* `1` is returned if `target` should come _before_ `buf` when sorted. +* `-1` is returned if `target` should come _after_ `buf` when sorted. ```mjs import { Buffer } from 'buffer'; @@ -1636,6 +1661,7 @@ console.log(buf1.compare(buf2, 5, 6, 5)); `targetEnd > target.byteLength`, or `sourceEnd > source.byteLength`. ### `buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])` + <!-- YAML added: v0.1.90 --> @@ -1737,6 +1763,7 @@ console.log(buf.toString()); ``` ### `buf.entries()` + <!-- YAML added: v1.1.0 --> @@ -1785,6 +1812,7 @@ for (const pair of buf.entries()) { ``` ### `buf.equals(otherBuffer)` + <!-- YAML added: v0.11.13 changes: @@ -1828,6 +1856,7 @@ console.log(buf1.equals(buf3)); ``` ### `buf.fill(value[, offset[, end]][, encoding])` + <!-- YAML added: v0.5.0 changes: @@ -1939,6 +1968,7 @@ console.log(buf.fill('zz', 'hex')); ``` ### `buf.includes(value[, byteOffset][, encoding])` + <!-- YAML added: v5.3.0 --> @@ -1995,6 +2025,7 @@ console.log(buf.includes('this', 4)); ``` ### `buf.indexOf(value[, byteOffset][, encoding])` + <!-- YAML added: v1.5.0 changes: @@ -2128,6 +2159,7 @@ than `buf.length`, `byteOffset` will be returned. If `value` is empty and `byteOffset` is at least `buf.length`, `buf.length` will be returned. ### `buf.keys()` + <!-- YAML added: v1.1.0 --> @@ -2171,6 +2203,7 @@ for (const key of buf.keys()) { ``` ### `buf.lastIndexOf(value[, byteOffset][, encoding])` + <!-- YAML added: v6.0.0 changes: @@ -2301,6 +2334,7 @@ console.log(b.lastIndexOf('b', [])); If `value` is an empty string or empty `Buffer`, `byteOffset` will be returned. ### `buf.length` + <!-- YAML added: v0.1.90 --> @@ -2342,6 +2376,7 @@ console.log(buf.length); ``` ### `buf.parent` + <!-- YAML deprecated: v8.0.0 --> @@ -2351,6 +2386,7 @@ deprecated: v8.0.0 The `buf.parent` property is a deprecated alias for `buf.buffer`. ### `buf.readBigInt64BE([offset])` + <!-- YAML added: - v12.0.0 @@ -2367,6 +2403,7 @@ Integers read from a `Buffer` are interpreted as two's complement signed values. ### `buf.readBigInt64LE([offset])` + <!-- YAML added: - v12.0.0 @@ -2384,6 +2421,7 @@ Integers read from a `Buffer` are interpreted as two's complement signed values. ### `buf.readBigUInt64BE([offset])` + <!-- YAML added: - v12.0.0 @@ -2424,6 +2462,7 @@ console.log(buf.readBigUInt64BE(0)); ``` ### `buf.readBigUInt64LE([offset])` + <!-- YAML added: - v12.0.0 @@ -2464,6 +2503,7 @@ console.log(buf.readBigUInt64LE(0)); ``` ### `buf.readDoubleBE([offset])` + <!-- YAML added: v0.11.15 changes: @@ -2498,6 +2538,7 @@ console.log(buf.readDoubleBE(0)); ``` ### `buf.readDoubleLE([offset])` + <!-- YAML added: v0.11.15 changes: @@ -2536,6 +2577,7 @@ console.log(buf.readDoubleLE(1)); ``` ### `buf.readFloatBE([offset])` + <!-- YAML added: v0.11.15 changes: @@ -2570,6 +2612,7 @@ console.log(buf.readFloatBE(0)); ``` ### `buf.readFloatLE([offset])` + <!-- YAML added: v0.11.15 changes: @@ -2608,6 +2651,7 @@ console.log(buf.readFloatLE(1)); ``` ### `buf.readInt8([offset])` + <!-- YAML added: v0.5.0 changes: @@ -2652,6 +2696,7 @@ console.log(buf.readInt8(2)); ``` ### `buf.readInt16BE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -2688,6 +2733,7 @@ console.log(buf.readInt16BE(0)); ``` ### `buf.readInt16LE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -2729,6 +2775,7 @@ console.log(buf.readInt16LE(1)); ``` ### `buf.readInt32BE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -2765,6 +2812,7 @@ console.log(buf.readInt32BE(0)); ``` ### `buf.readInt32LE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -2806,6 +2854,7 @@ console.log(buf.readInt32LE(1)); ``` ### `buf.readIntBE(offset, byteLength)` + <!-- YAML added: v0.11.15 changes: @@ -2852,6 +2901,7 @@ console.log(buf.readIntBE(1, 0).toString(16)); ``` ### `buf.readIntLE(offset, byteLength)` + <!-- YAML added: v0.11.15 changes: @@ -2890,6 +2940,7 @@ console.log(buf.readIntLE(0, 6).toString(16)); ``` ### `buf.readUInt8([offset])` + <!-- YAML added: v0.5.0 changes: @@ -2939,6 +2990,7 @@ console.log(buf.readUInt8(2)); ``` ### `buf.readUInt16BE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -2985,6 +3037,7 @@ console.log(buf.readUInt16BE(1).toString(16)); ``` ### `buf.readUInt16LE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -3035,6 +3088,7 @@ console.log(buf.readUInt16LE(2).toString(16)); ``` ### `buf.readUInt32BE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -3077,6 +3131,7 @@ console.log(buf.readUInt32BE(0).toString(16)); ``` ### `buf.readUInt32LE([offset])` + <!-- YAML added: v0.5.5 changes: @@ -3123,6 +3178,7 @@ console.log(buf.readUInt32LE(1).toString(16)); ``` ### `buf.readUIntBE(offset, byteLength)` + <!-- YAML added: v0.11.15 changes: @@ -3172,6 +3228,7 @@ console.log(buf.readUIntBE(1, 6).toString(16)); ``` ### `buf.readUIntLE(offset, byteLength)` + <!-- YAML added: v0.11.15 changes: @@ -3217,6 +3274,7 @@ console.log(buf.readUIntLE(0, 6).toString(16)); ``` ### `buf.subarray([start[, end]])` + <!-- YAML added: v3.0.0 --> @@ -3325,6 +3383,7 @@ console.log(buf.subarray(-5, -2).toString()); ``` ### `buf.slice([start[, end]])` + <!-- YAML added: v0.3.0 changes: @@ -3383,6 +3442,7 @@ console.log(buf.toString()); ``` ### `buf.swap16()` + <!-- YAML added: v5.10.0 --> @@ -3390,7 +3450,7 @@ added: v5.10.0 * Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of unsigned 16-bit integers and swaps the -byte order *in-place*. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] +byte order _in-place_. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] is not a multiple of 2. ```mjs @@ -3449,6 +3509,7 @@ buf.swap16(); // Convert to big-endian UTF-16 text. ``` ### `buf.swap32()` + <!-- YAML added: v5.10.0 --> @@ -3456,7 +3517,7 @@ added: v5.10.0 * Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of unsigned 32-bit integers and swaps the -byte order *in-place*. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] +byte order _in-place_. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] is not a multiple of 4. ```mjs @@ -3498,13 +3559,14 @@ buf2.swap32(); ``` ### `buf.swap64()` + <!-- YAML added: v6.3.0 --> * Returns: {Buffer} A reference to `buf`. -Interprets `buf` as an array of 64-bit numbers and swaps byte order *in-place*. +Interprets `buf` as an array of 64-bit numbers and swaps byte order _in-place_. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] is not a multiple of 8. ```mjs @@ -3546,6 +3608,7 @@ buf2.swap64(); ``` ### `buf.toJSON()` + <!-- YAML added: v0.9.2 --> @@ -3597,6 +3660,7 @@ console.log(copy); ``` ### `buf.toString([encoding[, start[, end]]])` + <!-- YAML added: v0.1.90 --> @@ -3667,6 +3731,7 @@ console.log(buf2.toString(undefined, 0, 3)); ``` ### `buf.values()` + <!-- YAML added: v1.1.0 --> @@ -3733,6 +3798,7 @@ for (const value of buf) { ``` ### `buf.write(string[, offset[, length]][, encoding])` + <!-- YAML added: v0.1.90 --> @@ -3787,6 +3853,7 @@ console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`); ``` ### `buf.writeBigInt64BE(value[, offset])` + <!-- YAML added: - v12.0.0 @@ -3825,6 +3892,7 @@ console.log(buf); ``` ### `buf.writeBigInt64LE(value[, offset])` + <!-- YAML added: - v12.0.0 @@ -3863,6 +3931,7 @@ console.log(buf); ``` ### `buf.writeBigUInt64BE(value[, offset])` + <!-- YAML added: - v12.0.0 @@ -3907,6 +3976,7 @@ console.log(buf); ``` ### `buf.writeBigUInt64LE(value[, offset])` + <!-- YAML added: - v12.0.0 @@ -3951,6 +4021,7 @@ console.log(buf); This function is also available under the `writeBigUint64LE` alias. ### `buf.writeDoubleBE(value[, offset])` + <!-- YAML added: v0.11.15 changes: @@ -3992,6 +4063,7 @@ console.log(buf); ``` ### `buf.writeDoubleLE(value[, offset])` + <!-- YAML added: v0.11.15 changes: @@ -4033,6 +4105,7 @@ console.log(buf); ``` ### `buf.writeFloatBE(value[, offset])` + <!-- YAML added: v0.11.15 changes: @@ -4073,6 +4146,7 @@ console.log(buf); ``` ### `buf.writeFloatLE(value[, offset])` + <!-- YAML added: v0.11.15 changes: @@ -4113,6 +4187,7 @@ console.log(buf); ``` ### `buf.writeInt8(value[, offset])` + <!-- YAML added: v0.5.0 changes: @@ -4158,6 +4233,7 @@ console.log(buf); ``` ### `buf.writeInt16BE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4201,6 +4277,7 @@ console.log(buf); ``` ### `buf.writeInt16LE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4244,6 +4321,7 @@ console.log(buf); ``` ### `buf.writeInt32BE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4287,6 +4365,7 @@ console.log(buf); ``` ### `buf.writeInt32LE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4330,6 +4409,7 @@ console.log(buf); ``` ### `buf.writeIntBE(value, offset, byteLength)` + <!-- YAML added: v0.11.15 changes: @@ -4373,6 +4453,7 @@ console.log(buf); ``` ### `buf.writeIntLE(value, offset, byteLength)` + <!-- YAML added: v0.11.15 changes: @@ -4416,6 +4497,7 @@ console.log(buf); ``` ### `buf.writeUInt8(value[, offset])` + <!-- YAML added: v0.5.0 changes: @@ -4470,6 +4552,7 @@ console.log(buf); ``` ### `buf.writeUInt16BE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4520,6 +4603,7 @@ console.log(buf); ``` ### `buf.writeUInt16LE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4570,6 +4654,7 @@ console.log(buf); ``` ### `buf.writeUInt32BE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4618,6 +4703,7 @@ console.log(buf); ``` ### `buf.writeUInt32LE(value[, offset])` + <!-- YAML added: v0.5.5 changes: @@ -4666,6 +4752,7 @@ console.log(buf); ``` ### `buf.writeUIntBE(value, offset, byteLength)` + <!-- YAML added: v0.5.5 changes: @@ -4716,6 +4803,7 @@ console.log(buf); ``` ### `buf.writeUIntLE(value, offset, byteLength)` + <!-- YAML added: v0.5.5 changes: @@ -4766,6 +4854,7 @@ console.log(buf); ``` ### `new Buffer(array)` + <!-- YAML deprecated: v6.0.0 changes: @@ -4783,11 +4872,12 @@ changes: > Stability: 0 - Deprecated: Use [`Buffer.from(array)`][] instead. -* `array` {integer[]} An array of bytes to copy from. +* `array` {integer\[]} An array of bytes to copy from. See [`Buffer.from(array)`][]. ### `new Buffer(arrayBuffer[, byteOffset[, length]])` + <!-- YAML added: v3.0.0 deprecated: v6.0.0 @@ -4821,6 +4911,7 @@ See [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][`Buffer.from(arrayBuf)`]. ### `new Buffer(buffer)` + <!-- YAML deprecated: v6.0.0 changes: @@ -4844,6 +4935,7 @@ changes: See [`Buffer.from(buffer)`][]. ### `new Buffer(size)` + <!-- YAML deprecated: v6.0.0 changes: @@ -4872,6 +4964,7 @@ See [`Buffer.alloc()`][] and [`Buffer.allocUnsafe()`][]. This variant of the constructor is equivalent to [`Buffer.alloc()`][]. ### `new Buffer(string[, encoding])` + <!-- YAML deprecated: v6.0.0 changes: @@ -4902,6 +4995,7 @@ While, the `Buffer` object is available as a global, there are additional accessed using `require('buffer')`. ### `buffer.atob(data)` + <!-- YAML added: - v15.13.0 @@ -4925,6 +5019,7 @@ and binary data should be performed using `Buffer.from(str, 'base64')` and `buf.toString('base64')`.** ### `buffer.btoa(data)` + <!-- YAML added: - v15.13.0 @@ -4948,6 +5043,7 @@ and binary data should be performed using `Buffer.from(str, 'base64')` and `buf.toString('base64')`.** ### `buffer.INSPECT_MAX_BYTES` + <!-- YAML added: v0.5.4 --> @@ -4959,6 +5055,7 @@ Returns the maximum number of bytes that will be returned when [`util.inspect()`][] for more details on `buf.inspect()` behavior. ### `buffer.kMaxLength` + <!-- YAML added: v3.0.0 --> @@ -4968,6 +5065,7 @@ added: v3.0.0 An alias for [`buffer.constants.MAX_LENGTH`][]. ### `buffer.kStringMaxLength` + <!-- YAML added: v3.0.0 --> @@ -4977,6 +5075,7 @@ added: v3.0.0 An alias for [`buffer.constants.MAX_STRING_LENGTH`][]. ### `buffer.resolveObjectURL(id)` + <!-- YAML added: v16.7.0 --> @@ -4991,6 +5090,7 @@ Resolves a `'blob:nodedata:...'` an associated {Blob} object registered using a prior call to `URL.createObjectURL()`. ### `buffer.transcode(source, fromEnc, toEnc)` + <!-- YAML added: v7.1.0 changes: @@ -5036,6 +5136,7 @@ Because the Euro (`€`) sign is not representable in US-ASCII, it is replaced with `?` in the transcoded `Buffer`. ### Class: `SlowBuffer` + <!-- YAML deprecated: v6.0.0 --> @@ -5047,6 +5148,7 @@ the constructor always returned a `Buffer` instance, rather than a `SlowBuffer` instance. #### `new SlowBuffer(size)` + <!-- YAML deprecated: v6.0.0 --> @@ -5058,11 +5160,13 @@ deprecated: v6.0.0 See [`Buffer.allocUnsafeSlow()`][]. ### Buffer constants + <!-- YAML added: v8.2.0 --> #### `buffer.constants.MAX_LENGTH` + <!-- YAML added: v8.2.0 changes: @@ -5088,6 +5192,7 @@ It reflects [`v8::TypedArray::kMaxLength`][] under the hood. This value is also available as [`buffer.kMaxLength`][]. #### `buffer.constants.MAX_STRING_LENGTH` + <!-- YAML added: v8.2.0 --> @@ -5107,11 +5212,11 @@ differently based on what arguments are provided: * Passing a number as the first argument to `Buffer()` (e.g. `new Buffer(10)`) allocates a new `Buffer` object of the specified size. Prior to Node.js 8.0.0, - the memory allocated for such `Buffer` instances is *not* initialized and - *can contain sensitive data*. Such `Buffer` instances *must* be subsequently + the memory allocated for such `Buffer` instances is _not_ initialized and + _can contain sensitive data_. Such `Buffer` instances _must_ be subsequently initialized by using either [`buf.fill(0)`][`buf.fill()`] or by writing to the entire `Buffer` before reading data from the `Buffer`. - While this behavior is *intentional* to improve performance, + While this behavior is _intentional_ to improve performance, development experience has demonstrated that a more explicit distinction is required between creating a fast-but-uninitialized `Buffer` versus creating a slower-but-safer `Buffer`. Since Node.js 8.0.0, `Buffer(num)` and `new @@ -5145,18 +5250,18 @@ the various forms of the `new Buffer()` constructor have been **deprecated** and replaced by separate `Buffer.from()`, [`Buffer.alloc()`][], and [`Buffer.allocUnsafe()`][] methods. -*Developers should migrate all existing uses of the `new Buffer()` constructors -to one of these new APIs.* +_Developers should migrate all existing uses of the `new Buffer()` constructors +to one of these new APIs._ -* [`Buffer.from(array)`][] returns a new `Buffer` that *contains a copy* of the +* [`Buffer.from(array)`][] returns a new `Buffer` that _contains a copy_ of the provided octets. * [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][`Buffer.from(arrayBuf)`] - returns a new `Buffer` that *shares the same allocated memory* as the given + returns a new `Buffer` that _shares the same allocated memory_ as the given [`ArrayBuffer`][]. -* [`Buffer.from(buffer)`][] returns a new `Buffer` that *contains a copy* of the +* [`Buffer.from(buffer)`][] returns a new `Buffer` that _contains a copy_ of the contents of the given `Buffer`. * [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] returns a new - `Buffer` that *contains a copy* of the provided string. + `Buffer` that _contains a copy_ of the provided string. * [`Buffer.alloc(size[, fill[, encoding]])`][`Buffer.alloc()`] returns a new initialized `Buffer` of the specified size. This method is slower than [`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] but guarantees that newly @@ -5169,12 +5274,13 @@ to one of these new APIs.* potentially sensitive. `Buffer` instances returned by [`Buffer.allocUnsafe()`][] and -[`Buffer.from(array)`][] *may* be allocated off a shared internal memory pool +[`Buffer.from(array)`][] _may_ be allocated off a shared internal memory pool if `size` is less than or equal to half [`Buffer.poolSize`][]. Instances -returned by [`Buffer.allocUnsafeSlow()`][] *never* use the shared internal +returned by [`Buffer.allocUnsafeSlow()`][] _never_ use the shared internal memory pool. ### The `--zero-fill-buffers` command-line option + <!-- YAML added: v5.10.0 --> @@ -5196,14 +5302,14 @@ $ node --zero-fill-buffers ### What makes `Buffer.allocUnsafe()` and `Buffer.allocUnsafeSlow()` "unsafe"? When calling [`Buffer.allocUnsafe()`][] and [`Buffer.allocUnsafeSlow()`][], the -segment of allocated memory is *uninitialized* (it is not zeroed-out). While +segment of allocated memory is _uninitialized_ (it is not zeroed-out). While this design makes the allocation of memory quite fast, the allocated segment of memory might contain old data that is potentially sensitive. Using a `Buffer` -created by [`Buffer.allocUnsafe()`][] without *completely* overwriting the +created by [`Buffer.allocUnsafe()`][] without _completely_ overwriting the memory can allow this old data to be leaked when the `Buffer` memory is read. While there are clear performance advantages to using -[`Buffer.allocUnsafe()`][], extra care *must* be taken in order to avoid +[`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid introducing security vulnerabilities into an application. [ASCII]: https://en.wikipedia.org/wiki/ASCII diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 340a0f05777..c0f980a3bb9 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -143,6 +143,7 @@ exec('"my script.cmd" a b', (err, stdout, stderr) => { ``` ### `child_process.exec(command[, options][, callback])` + <!-- YAML added: v0.1.90 changes: @@ -190,7 +191,7 @@ changes: Spawns a shell then executes the `command` within that shell, buffering any generated output. The `command` string passed to the exec function is processed directly by the shell and special characters (vary based on -[shell](https://en.wikipedia.org/wiki/List_of_command-line_interpreters)) +[shell](https://en.wikipedia.org/wiki/List\_of\_command-line\_interpreters)) need to be dealt with accordingly: ```js @@ -274,6 +275,7 @@ controller.abort(); ``` ### `child_process.execFile(file[, args][, options][, callback])` + <!-- YAML added: v0.1.91 changes: @@ -294,7 +296,7 @@ changes: --> * `file` {string} The name or path of the executable file to run. -* `args` {string[]} List of string arguments. +* `args` {string\[]} List of string arguments. * `options` {Object} * `cwd` {string|URL} Current working directory of the child process. * `env` {Object} Environment key-value pairs. **Default:** `process.env`. @@ -385,6 +387,7 @@ controller.abort(); ``` ### `child_process.fork(modulePath[, args][, options])` + <!-- YAML added: v0.5.0 changes: @@ -423,7 +426,7 @@ changes: --> * `modulePath` {string} The module to run in the child. -* `args` {string[]} List of string arguments. +* `args` {string\[]} List of string arguments. * `options` {Object} * `cwd` {string|URL} Current working directory of the child process. * `detached` {boolean} Prepare child to run independently of its parent @@ -431,7 +434,7 @@ changes: [`options.detached`][]). * `env` {Object} Environment key-value pairs. **Default:** `process.env`. * `execPath` {string} Executable used to create the child process. - * `execArgv` {string[]} List of string arguments passed to the executable. + * `execArgv` {string\[]} List of string arguments passed to the executable. **Default:** `process.execArgv`. * `gid` {number} Sets the group identity of the process (see setgid(2)). * `serialization` {string} Specify the kind of serialization used for sending @@ -506,6 +509,7 @@ if (process.argv[2] === 'child') { ``` ### `child_process.spawn(command[, args][, options])` + <!-- YAML added: v0.1.90 changes: @@ -547,7 +551,7 @@ changes: --> * `command` {string} The command to run. -* `args` {string[]} List of string arguments. +* `args` {string\[]} List of string arguments. * `options` {Object} * `cwd` {string|URL} Current working directory of the child process. * `env` {Object} Environment key-value pairs. **Default:** `process.env`. @@ -578,7 +582,6 @@ changes: is allowed to run. **Default:** `undefined`. * `killSignal` {string|integer} The signal value to be used when the spawned process will be killed by timeout or abort signal. **Default:** `'SIGTERM'`. - * Returns: {ChildProcess} The `child_process.spawn()` method spawns a new process using the given @@ -701,6 +704,7 @@ controller.abort(); // Stops the child process ``` #### `options.detached` + <!-- YAML added: v0.7.10 --> @@ -759,6 +763,7 @@ subprocess.unref(); ``` #### `options.stdio` + <!-- YAML added: v0.7.10 changes: @@ -796,13 +801,13 @@ pipes between the parent and child. The value is one of the following: `child_process` object as [`subprocess.stdio[fd]`][`subprocess.stdio`]. Pipes created for fds 0, 1, and 2 are also available as [`subprocess.stdin`][], [`subprocess.stdout`][] and [`subprocess.stderr`][], respectively. -1. `'overlapped'`: Same as `'pipe'` except that the `FILE_FLAG_OVERLAPPED` flag +2. `'overlapped'`: Same as `'pipe'` except that the `FILE_FLAG_OVERLAPPED` flag is set on the handle. This is necessary for overlapped I/O on the child process's stdio handles. See the [docs](https://docs.microsoft.com/en-us/windows/win32/fileio/synchronous-and-asynchronous-i-o) for more details. This is exactly the same as `'pipe'` on non-Windows systems. -1. `'ipc'`: Create an IPC channel for passing messages/file descriptors +3. `'ipc'`: Create an IPC channel for passing messages/file descriptors between parent and child. A [`ChildProcess`][] may have at most one IPC stdio file descriptor. Setting this option enables the [`subprocess.send()`][] method. If the child is a Node.js process, the @@ -813,25 +818,25 @@ pipes between the parent and child. The value is one of the following: Accessing the IPC channel fd in any way other than [`process.send()`][] or using the IPC channel with a child process that is not a Node.js instance is not supported. -1. `'ignore'`: Instructs Node.js to ignore the fd in the child. While Node.js +4. `'ignore'`: Instructs Node.js to ignore the fd in the child. While Node.js will always open fds 0, 1, and 2 for the processes it spawns, setting the fd to `'ignore'` will cause Node.js to open `/dev/null` and attach it to the child's fd. -1. `'inherit'`: Pass through the corresponding stdio stream to/from the +5. `'inherit'`: Pass through the corresponding stdio stream to/from the parent process. In the first three positions, this is equivalent to `process.stdin`, `process.stdout`, and `process.stderr`, respectively. In any other position, equivalent to `'ignore'`. -1. {Stream} object: Share a readable or writable stream that refers to a tty, +6. {Stream} object: Share a readable or writable stream that refers to a tty, file, socket, or a pipe with the child process. The stream's underlying file descriptor is duplicated in the child process to the fd that corresponds to the index in the `stdio` array. The stream must have an underlying descriptor (file streams do not until the `'open'` event has occurred). -1. Positive integer: The integer value is interpreted as a file descriptor +7. Positive integer: The integer value is interpreted as a file descriptor that is currently open in the parent process. It is shared with the child process, similar to how {Stream} objects can be shared. Passing sockets is not supported on Windows. -1. `null`, `undefined`: Use default value. For stdio fds 0, 1, and 2 (in other +8. `null`, `undefined`: Use default value. For stdio fds 0, 1, and 2 (in other words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is `'ignore'`. @@ -849,12 +854,12 @@ spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] }); spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] }); ``` -*It is worth noting that when an IPC channel is established between the +_It is worth noting that when an IPC channel is established between the parent and child processes, and the child is a Node.js process, the child is launched with the IPC channel unreferenced (using `unref()`) until the child registers an event handler for the [`'disconnect'`][] event or the [`'message'`][] event. This allows the child to exit -normally without the process being held open by the open IPC channel.* +normally without the process being held open by the open IPC channel._ On Unix-like operating systems, the [`child_process.spawn()`][] method performs memory operations synchronously before decoupling the event loop @@ -876,6 +881,7 @@ scripting tasks and for simplifying the loading/processing of application configuration at startup. ### `child_process.execFileSync(file[, args][, options])` + <!-- YAML added: v0.11.12 changes: @@ -903,7 +909,7 @@ changes: --> * `file` {string} The name or path of the executable file to run. -* `args` {string[]} List of string arguments. +* `args` {string\[]} List of string arguments. * `options` {Object} * `cwd` {string|URL} Current working directory of the child process. * `input` {string|Buffer|TypedArray|DataView} The value which will be passed @@ -951,6 +957,7 @@ function. Any input containing shell metacharacters may be used to trigger arbitrary command execution.** ### `child_process.execSync(command[, options])` + <!-- YAML added: v0.11.12 changes: @@ -1017,6 +1024,7 @@ The [`Error`][] object will contain the entire result from metacharacters may be used to trigger arbitrary command execution.** ### `child_process.spawnSync(command[, args][, options])` + <!-- YAML added: v0.11.12 changes: @@ -1047,7 +1055,7 @@ changes: --> * `command` {string} The command to run. -* `args` {string[]} List of string arguments. +* `args` {string\[]} List of string arguments. * `options` {Object} * `cwd` {string|URL} Current working directory of the child process. * `input` {string|Buffer|TypedArray|DataView} The value which will be passed @@ -1102,6 +1110,7 @@ function. Any input containing shell metacharacters may be used to trigger arbitrary command execution.** ## Class: `ChildProcess` + <!-- YAML added: v2.2.0 --> @@ -1116,6 +1125,7 @@ use the [`child_process.spawn()`][], [`child_process.exec()`][], instances of `ChildProcess`. ### Event: `'close'` + <!-- YAML added: v0.7.7 --> @@ -1147,6 +1157,7 @@ ls.on('exit', (code) => { ``` ### Event: `'disconnect'` + <!-- YAML added: v0.7.2 --> @@ -1174,6 +1185,7 @@ against accidentally invoking handler functions multiple times. See also [`subprocess.kill()`][] and [`subprocess.send()`][]. ### Event: `'exit'` + <!-- YAML added: v0.1.90 --> @@ -1197,6 +1209,7 @@ re-raise the handled signal. See waitpid(2). ### Event: `'message'` + <!-- YAML added: v0.5.9 --> @@ -1217,6 +1230,7 @@ to represent. See [Advanced serialization][] for more details. ### Event: `'spawn'` + <!-- YAML added: - v15.1.0 @@ -1236,6 +1250,7 @@ the `'spawn'` event will fire, though `bash` may fail to spawn `some-command`. This caveat also applies when using `{ shell: true }`. ### `subprocess.channel` + <!-- YAML added: v7.1.0 changes: @@ -1250,6 +1265,7 @@ The `subprocess.channel` property is a reference to the child's IPC channel. If no IPC channel currently exists, this property is `undefined`. #### `subprocess.channel.ref()` + <!-- YAML added: v7.1.0 --> @@ -1258,6 +1274,7 @@ This method makes the IPC channel keep the event loop of the parent process running if `.unref()` has been called before. #### `subprocess.channel.unref()` + <!-- YAML added: v7.1.0 --> @@ -1266,6 +1283,7 @@ This method makes the IPC channel not keep the event loop of the parent process running, and lets it finish even while the channel is open. ### `subprocess.connected` + <!-- YAML added: v0.7.2 --> @@ -1277,6 +1295,7 @@ send and receive messages from a child process. When `subprocess.connected` is `false`, it is no longer possible to send or receive messages. ### `subprocess.disconnect()` + <!-- YAML added: v0.7.2 --> @@ -1303,6 +1322,7 @@ The `subprocess.exitCode` property indicates the exit code of the child process. If the child process is still running, the field will be `null`. ### `subprocess.kill([signal])` + <!-- YAML added: v0.1.90 --> @@ -1370,6 +1390,7 @@ setTimeout(() => { ``` ### `subprocess.killed` + <!-- YAML added: v0.5.10 --> @@ -1382,6 +1403,7 @@ successfully received a signal from `subprocess.kill()`. The `killed` property does not indicate that the child process has been terminated. ### `subprocess.pid` + <!-- YAML added: v0.1.90 --> @@ -1401,6 +1423,7 @@ grep.stdin.end(); ``` ### `subprocess.ref()` + <!-- YAML added: v0.7.10 --> @@ -1422,6 +1445,7 @@ subprocess.ref(); ``` ### `subprocess.send(message[, sendHandle[, options]][, callback])` + <!-- YAML added: v0.5.9 changes: @@ -1629,6 +1653,7 @@ For [`child_process.exec()`][], its value will be the name of the shell in which the child process is launched. ### `subprocess.stderr` + <!-- YAML added: v0.1.90 --> @@ -1647,6 +1672,7 @@ The `subprocess.stderr` property can be `null` if the child process could not be successfully spawned. ### `subprocess.stdin` + <!-- YAML added: v0.1.90 --> @@ -1668,6 +1694,7 @@ The `subprocess.stdin` property can be `undefined` if the child process could not be successfully spawned. ### `subprocess.stdio` + <!-- YAML added: v0.7.10 --> @@ -1711,6 +1738,7 @@ The `subprocess.stdio` property can be `undefined` if the child process could not be successfully spawned. ### `subprocess.stdout` + <!-- YAML added: v0.1.90 --> @@ -1739,6 +1767,7 @@ The `subprocess.stdout` property can be `null` if the child process could not be successfully spawned. ### `subprocess.unref()` + <!-- YAML added: v0.7.10 --> @@ -1784,6 +1813,7 @@ spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is unavailable. ## Advanced serialization + <!-- YAML added: - v13.2.0 diff --git a/doc/api/cli.md b/doc/api/cli.md index 1c989b68568..7f97e50afd3 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -22,6 +22,7 @@ Execute without arguments to start the [REPL][]. For more info about `node inspect`, see the [debugger][] documentation. ## Options + <!-- YAML changes: - version: v10.12.0 @@ -40,6 +41,7 @@ command line take precedence over options passed through the [`NODE_OPTIONS`][] environment variable. ### `-` + <!-- YAML added: v8.0.0 --> @@ -49,6 +51,7 @@ meaning that the script is read from stdin, and the rest of the options are passed to that script. ### `--` + <!-- YAML added: v6.11.0 --> @@ -58,6 +61,7 @@ If no script filename or eval/print script is supplied prior to this, then the next argument is used as a script filename. ### `--abort-on-uncaught-exception` + <!-- YAML added: v0.10.8 --> @@ -70,6 +74,7 @@ If this flag is passed, the behavior can still be set to not abort through `domain` module that uses it). ### `--completion-bash` + <!-- YAML added: v10.12.0 --> @@ -82,6 +87,7 @@ $ source node_bash_completion ``` ### `-C=condition`, `--conditions=condition` + <!-- YAML added: - v14.9.0 @@ -105,6 +111,7 @@ $ node -C=development app.js ``` ### `--cpu-prof` + <!-- YAML added: v12.0.0 --> @@ -127,6 +134,7 @@ CPU.20190409.202950.15293.0.0.cpuprofile ``` ### `--cpu-prof-dir` + <!-- YAML added: v12.0.0 --> @@ -140,6 +148,7 @@ The default value is controlled by the [`--diagnostic-dir`][] command-line option. ### `--cpu-prof-interval` + <!-- YAML added: v12.2.0 --> @@ -150,6 +159,7 @@ Specify the sampling interval in microseconds for the CPU profiles generated by `--cpu-prof`. The default is 1000 microseconds. ### `--cpu-prof-name` + <!-- YAML added: v12.0.0 --> @@ -164,11 +174,13 @@ Set the directory to which all diagnostic output files are written. Defaults to current working directory. Affects the default output directory of: + * [`--cpu-prof-dir`][] * [`--heap-prof-dir`][] * [`--redirect-warnings`][] ### `--disable-proto=mode` + <!-- YAML added: - v13.12.0 @@ -180,6 +192,7 @@ property is removed entirely. If `mode` is `throw`, accesses to the property throw an exception with the code `ERR_PROTO_ACCESS`. ### `--disallow-code-generation-from-strings` + <!-- YAML added: v9.8.0 --> @@ -189,6 +202,7 @@ code from strings throw an exception instead. This does not affect the Node.js `vm` module. ### `--dns-result-order=order` + <!-- YAML added: - v16.4.0 @@ -197,6 +211,7 @@ added: Set the default value of `verbatim` in [`dns.lookup()`][] and [`dnsPromises.lookup()`][]. The value could be: + * `ipv4first`: sets default `verbatim` `false`. * `verbatim`: sets default `verbatim` `true`. @@ -204,6 +219,7 @@ The default is `ipv4first` and [`dns.setDefaultResultOrder()`][] have higher priority than `--dns-result-order`. ### `--enable-fips` + <!-- YAML added: v6.0.0 --> @@ -212,6 +228,7 @@ Enable FIPS-compliant crypto at startup. (Requires Node.js to be built against FIPS-compatible OpenSSL.) ### `--enable-source-maps` + <!-- YAML added: v12.12.0 changes: @@ -233,6 +250,7 @@ Overriding `Error.prepareStackTrace` prevents `--enable-source-maps` from modifying the stack trace. ### `--experimental-abortcontroller` + <!-- YAML added: - v15.0.0 @@ -247,6 +265,7 @@ changes: Use of this command-line flag is no longer required. ### `--experimental-import-meta-resolve` + <!-- YAML added: - v13.9.0 @@ -256,6 +275,7 @@ added: Enable experimental `import.meta.resolve()` support. ### `--experimental-json-modules` + <!-- YAML added: v12.9.0 --> @@ -263,6 +283,7 @@ added: v12.9.0 Enable experimental JSON support for the ES Module loader. ### `--experimental-loader=module` + <!-- YAML added: v9.0.0 --> @@ -271,6 +292,7 @@ Specify the `module` of a custom experimental [ECMAScript Module loader][]. `module` may be either a path to a file, or an ECMAScript Module name. ### `--experimental-modules` + <!-- YAML added: v8.5.0 --> @@ -278,6 +300,7 @@ added: v8.5.0 Enable latest experimental modules features (deprecated). ### `--experimental-policy` + <!-- YAML added: v11.8.0 --> @@ -285,12 +308,15 @@ added: v11.8.0 Use the specified file as a security policy. ### `--no-experimental-repl-await` + <!-- YAML added: v16.6.0 --> - Use this flag to disable top-level await in REPL. + +Use this flag to disable top-level await in REPL. ### `--experimental-specifier-resolution=mode` + <!-- YAML added: - v13.4.0 @@ -307,6 +333,7 @@ the ability to import a directory that has an index file. See [customizing ESM specifier resolution][] for example usage. ### `--experimental-vm-modules` + <!-- YAML added: v9.6.0 --> @@ -314,6 +341,7 @@ added: v9.6.0 Enable experimental ES Module support in the `vm` module. ### `--experimental-wasi-unstable-preview1` + <!-- YAML added: - v13.3.0 @@ -328,6 +356,7 @@ changes: Enable experimental WebAssembly System Interface (WASI) support. ### `--experimental-wasm-modules` + <!-- YAML added: v12.3.0 --> @@ -335,6 +364,7 @@ added: v12.3.0 Enable experimental WebAssembly module support. ### `--force-context-aware` + <!-- YAML added: v12.12.0 --> @@ -342,6 +372,7 @@ added: v12.12.0 Disable loading native addons that are not [context-aware][]. ### `--force-fips` + <!-- YAML added: v6.0.0 --> @@ -350,6 +381,7 @@ Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.) (Same requirements as `--enable-fips`.) ### `--frozen-intrinsics` + <!-- YAML added: v11.12.0 --> @@ -366,6 +398,7 @@ reference. Code may break under this flag. be added. ### `--heapsnapshot-near-heap-limit=max_count` + <!-- YAML added: - v15.1.0 @@ -414,6 +447,7 @@ FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaS ``` ### `--heapsnapshot-signal=signal` + <!-- YAML added: v12.0.0 --> @@ -433,6 +467,7 @@ Heap.20190718.133405.15554.0.001.heapsnapshot ``` ### `--heap-prof` + <!-- YAML added: v12.4.0 --> @@ -455,6 +490,7 @@ Heap.20190409.202950.15293.0.001.heapprofile ``` ### `--heap-prof-dir` + <!-- YAML added: v12.4.0 --> @@ -468,6 +504,7 @@ The default value is controlled by the [`--diagnostic-dir`][] command-line option. ### `--heap-prof-interval` + <!-- YAML added: v12.4.0 --> @@ -475,9 +512,10 @@ added: v12.4.0 > Stability: 1 - Experimental Specify the average sampling interval in bytes for the heap profiles generated -by `--heap-prof`. The default is 512 * 1024 bytes. +by `--heap-prof`. The default is 512 \* 1024 bytes. ### `--heap-prof-name` + <!-- YAML added: v12.4.0 --> @@ -487,6 +525,7 @@ added: v12.4.0 Specify the file name of the heap profile generated by `--heap-prof`. ### `--icu-data-dir=file` + <!-- YAML added: v0.11.15 --> @@ -494,6 +533,7 @@ added: v0.11.15 Specify ICU data load path. (Overrides `NODE_ICU_DATA`.) ### `--input-type=type` + <!-- YAML added: v12.0.0 --> @@ -504,6 +544,7 @@ module. String input is input via `--eval`, `--print`, or `STDIN`. Valid values are `"commonjs"` and `"module"`. The default is `"commonjs"`. ### `--inspect-brk[=[host:]port]` + <!-- YAML added: v7.6.0 --> @@ -512,6 +553,7 @@ Activate inspector on `host:port` and break at start of user script. Default `host:port` is `127.0.0.1:9229`. ### `--inspect-port=[host:]port` + <!-- YAML added: v7.6.0 --> @@ -525,6 +567,7 @@ See the [security warning][] below regarding the `host` parameter usage. ### `--inspect[=[host:]port]` + <!-- YAML added: v6.3.0 --> @@ -536,7 +579,9 @@ and profile Node.js instances. The tools attach to Node.js instances via a tcp port and communicate using the [Chrome DevTools Protocol][]. <!-- Anchor to make sure old links find a target --> + <a id="inspector_security"></a> + #### Warning: binding inspector to a public IP:port combination is insecure Binding the inspector to a public IP (including `0.0.0.0`) with an open port is @@ -561,6 +606,7 @@ By default inspector websocket url is available in stderr and under `/json/list` endpoint on `http://host:port/json/list`. ### `--insecure-http-parser` + <!-- YAML added: - v13.4.0 @@ -574,6 +620,7 @@ request smuggling and other HTTP attacks that rely on invalid headers being accepted. Avoid using this option. ### `--jitless` + <!-- YAML added: v12.0.0 --> @@ -586,6 +633,7 @@ This flag is inherited from V8 and is subject to change upstream. It may disappear in a non-semver-major release. ### `--max-http-header-size=size` + <!-- YAML added: - v11.6.0 @@ -599,6 +647,7 @@ changes: Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KB. ### `--napi-modules` + <!-- YAML added: v7.10.0 --> @@ -606,6 +655,7 @@ added: v7.10.0 This option is a no-op. It is kept for compatibility. ### `--no-addons` + <!-- YAML added: v16.10.0 --> @@ -615,6 +665,7 @@ native addons. When `--no-addons` is specified, calling `process.dlopen` or requiring a native C++ addon will fail and throw an exception. ### `--no-deprecation` + <!-- YAML added: v0.8.0 --> @@ -622,6 +673,7 @@ added: v0.8.0 Silence deprecation warnings. ### `--no-extra-info-on-fatal-exception` + <!-- YAML added: v17.0.0 --> @@ -629,6 +681,7 @@ added: v17.0.0 Hide extra information on fatal exception that causes exit. ### `--no-force-async-hooks-checks` + <!-- YAML added: v9.0.0 --> @@ -637,6 +690,7 @@ Disables runtime checks for `async_hooks`. These will still be enabled dynamically when `async_hooks` is enabled. ### `--no-global-search-paths` + <!-- YAML added: v16.10.0 --> @@ -645,6 +699,7 @@ Do not search modules from global paths like `$HOME/.node_modules` and `$NODE_PATH`. ### `--no-warnings` + <!-- YAML added: v6.0.0 --> @@ -652,6 +707,7 @@ added: v6.0.0 Silence all process warnings (including deprecations). ### `--node-memory-debug` + <!-- YAML added: - v15.0.0 @@ -662,6 +718,7 @@ Enable extra debug checks for memory leaks in Node.js internals. This is usually only useful for developers debugging Node.js itself. ### `--openssl-config=file` + <!-- YAML added: v6.9.0 --> @@ -671,14 +728,16 @@ used to enable FIPS-compliant crypto if Node.js is built against FIPS-enabled OpenSSL. ### `--openssl-legacy-provider` + <!-- YAML added: v17.0.0 --> Enable OpenSSL 3.0 legacy provider. For more information please see -[OSSL_PROVIDER-legacy][]. +[OSSL\_PROVIDER-legacy][OSSL_PROVIDER-legacy]. ### `--pending-deprecation` + <!-- YAML added: v8.0.0 --> @@ -686,13 +745,14 @@ added: v8.0.0 Emit pending deprecation warnings. Pending deprecations are generally identical to a runtime deprecation with the -notable exception that they are turned *off* by default and will not be emitted +notable exception that they are turned _off_ by default and will not be emitted unless either the `--pending-deprecation` command-line flag, or the `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations are used to provide a kind of selective "early warning" mechanism that developers may leverage to detect deprecated API usage. ### `--policy-integrity=sri` + <!-- YAML added: v12.7.0 --> @@ -704,6 +764,7 @@ the specified integrity. It expects a [Subresource Integrity][] string as a parameter. ### `--preserve-symlinks` + <!-- YAML added: v6.3.0 --> @@ -738,7 +799,7 @@ symlink path for modules as opposed to the real path, allowing symbolically linked peer dependencies to be found. Note, however, that using `--preserve-symlinks` can have other side effects. -Specifically, symbolically linked *native* modules can fail to load if those +Specifically, symbolically linked _native_ modules can fail to load if those are linked from more than one location in the dependency tree (Node.js would see those as two separate modules and would attempt to load the module multiple times, causing an exception to be thrown). @@ -748,6 +809,7 @@ The `--preserve-symlinks` flag does not apply to the main module, which allows behavior for the main module, also use `--preserve-symlinks-main`. ### `--preserve-symlinks-main` + <!-- YAML added: v10.2.0 --> @@ -767,6 +829,7 @@ resolving relative paths. See `--preserve-symlinks` for more information. ### `--prof` + <!-- YAML added: v2.0.0 --> @@ -774,6 +837,7 @@ added: v2.0.0 Generate V8 profiler output. ### `--prof-process` + <!-- YAML added: v5.2.0 --> @@ -781,6 +845,7 @@ added: v5.2.0 Process V8 profiler output generated using the V8 option `--prof`. ### `--redirect-warnings=file` + <!-- YAML added: v8.0.0 --> @@ -795,6 +860,7 @@ will be written to is controlled by the [`--diagnostic-dir`]() command-line option. ### `--report-compact` + <!-- YAML added: - v13.12.0 @@ -806,6 +872,7 @@ by log processing systems than the default multi-line format designed for human consumption. ### `--report-dir=directory`, `report-directory=directory` + <!-- YAML added: v11.8.0 changes: @@ -823,6 +890,7 @@ changes: Location at which the report will be generated. ### `--report-filename=filename` + <!-- YAML added: v11.8.0 changes: @@ -840,6 +908,7 @@ changes: Name of the file to which the report will be written. ### `--report-on-fatalerror` + <!-- YAML added: v11.8.0 changes: @@ -862,6 +931,7 @@ stack, event loop state, resource consumption etc. to reason about the fatal error. ### `--report-on-signal` + <!-- YAML added: v11.8.0 changes: @@ -881,6 +951,7 @@ signal to the running Node.js process. The signal to trigger the report is specified through `--report-signal`. ### `--report-signal=signal` + <!-- YAML added: v11.8.0 changes: @@ -899,6 +970,7 @@ Sets or resets the signal for report generation (not supported on Windows). Default signal is `SIGUSR2`. ### `--report-uncaught-exception` + <!-- YAML added: v11.8.0 changes: @@ -918,6 +990,7 @@ the JavaScript stack in conjunction with native stack and other runtime environment data. ### `--secure-heap=n` + <!-- YAML added: v15.6.0 --> @@ -942,6 +1015,7 @@ The secure heap is not available on Windows. See [`CRYPTO_secure_malloc_init`][] for more details. ### `--secure-heap-min=n` + <!-- YAML added: v15.6.0 --> @@ -952,6 +1026,7 @@ The maximum value is the lesser of `--secure-heap` or `2147483647`. The value given must be a power of two. ### `--throw-deprecation` + <!-- YAML added: v0.11.14 --> @@ -959,6 +1034,7 @@ added: v0.11.14 Throw errors for deprecations. ### `--title=title` + <!-- YAML added: v10.7.0 --> @@ -966,6 +1042,7 @@ added: v10.7.0 Set `process.title` on startup. ### `--tls-cipher-list=list` + <!-- YAML added: v4.0.0 --> @@ -974,6 +1051,7 @@ Specify an alternative default TLS cipher list. Requires Node.js to be built with crypto support (default). ### `--tls-keylog=file` + <!-- YAML added: - v13.2.0 @@ -985,6 +1063,7 @@ format and can be used by software (such as Wireshark) to decrypt the TLS traffic. ### `--tls-max-v1.2` + <!-- YAML added: - v12.0.0 @@ -995,6 +1074,7 @@ Set [`tls.DEFAULT_MAX_VERSION`][] to 'TLSv1.2'. Use to disable support for TLSv1.3. ### `--tls-max-v1.3` + <!-- YAML added: v12.0.0 --> @@ -1003,6 +1083,7 @@ Set default [`tls.DEFAULT_MAX_VERSION`][] to 'TLSv1.3'. Use to enable support for TLSv1.3. ### `--tls-min-v1.0` + <!-- YAML added: - v12.0.0 @@ -1013,6 +1094,7 @@ Set default [`tls.DEFAULT_MIN_VERSION`][] to 'TLSv1'. Use for compatibility with old TLS clients or servers. ### `--tls-min-v1.1` + <!-- YAML added: - v12.0.0 @@ -1023,6 +1105,7 @@ Set default [`tls.DEFAULT_MIN_VERSION`][] to 'TLSv1.1'. Use for compatibility with old TLS clients or servers. ### `--tls-min-v1.2` + <!-- YAML added: - v12.2.0 @@ -1034,6 +1117,7 @@ Set default [`tls.DEFAULT_MIN_VERSION`][] to 'TLSv1.2'. This is the default for versions. ### `--tls-min-v1.3` + <!-- YAML added: v12.0.0 --> @@ -1042,6 +1126,7 @@ Set default [`tls.DEFAULT_MIN_VERSION`][] to 'TLSv1.3'. Use to disable support for TLSv1.2, which is not as secure as TLSv1.3. ### `--trace-atomics-wait` + <!-- YAML added: v14.3.0 --> @@ -1069,6 +1154,7 @@ The fields here correspond to: * The timeout passed to `Atomics.wait` ### `--trace-deprecation` + <!-- YAML added: v0.8.0 --> @@ -1076,6 +1162,7 @@ added: v0.8.0 Print stack traces for deprecations. ### `--trace-event-categories` + <!-- YAML added: v7.7.0 --> @@ -1084,6 +1171,7 @@ A comma separated list of categories that should be traced when trace event tracing is enabled using `--trace-events-enabled`. ### `--trace-event-file-pattern` + <!-- YAML added: v9.8.0 --> @@ -1092,6 +1180,7 @@ Template string specifying the filepath for the trace event data, it supports `${rotation}` and `${pid}`. ### `--trace-events-enabled` + <!-- YAML added: v7.7.0 --> @@ -1099,6 +1188,7 @@ added: v7.7.0 Enables the collection of trace event tracing information. ### `--trace-exit` + <!-- YAML added: - v13.5.0 @@ -1109,6 +1199,7 @@ Prints a stack trace whenever an environment is exited proactively, i.e. invoking `process.exit()`. ### `--trace-sigint` + <!-- YAML added: - v13.9.0 @@ -1118,6 +1209,7 @@ added: Prints a stack trace on SIGINT. ### `--trace-sync-io` + <!-- YAML added: v2.1.0 --> @@ -1126,6 +1218,7 @@ Prints a stack trace whenever synchronous I/O is detected after the first turn of the event loop. ### `--trace-tls` + <!-- YAML added: v12.2.0 --> @@ -1134,6 +1227,7 @@ Prints TLS packet trace information to `stderr`. This can be used to debug TLS connection problems. ### `--trace-uncaught` + <!-- YAML added: v13.1.0 --> @@ -1146,6 +1240,7 @@ to be an `Error` instance). Enabling this option may affect garbage collection behavior negatively. ### `--trace-warnings` + <!-- YAML added: v6.0.0 --> @@ -1153,6 +1248,7 @@ added: v6.0.0 Print stack traces for process warnings (including deprecations). ### `--track-heap-objects` + <!-- YAML added: v2.4.0 --> @@ -1160,6 +1256,7 @@ added: v2.4.0 Track heap object allocations for heap snapshots. ### `--unhandled-rejections=mode` + <!-- YAML added: - v12.0.0 @@ -1184,6 +1281,7 @@ occurs. One of the following modes can be chosen: * `none`: Silence all warnings. ### `--use-bundled-ca`, `--use-openssl-ca` + <!-- YAML added: v6.11.0 --> @@ -1204,6 +1302,7 @@ environment variables. See `SSL_CERT_DIR` and `SSL_CERT_FILE`. ### `--use-largepages=mode` + <!-- YAML added: - v13.6.0 @@ -1215,6 +1314,7 @@ the target system, this will cause the Node.js static code to be moved onto 2 MiB pages instead of 4 KiB pages. The following values are valid for `mode`: + * `off`: No mapping will be attempted. This is the default. * `on`: If supported by the OS, mapping will be attempted. Failure to map will be ignored and a message will be printed to standard error. @@ -1222,6 +1322,7 @@ The following values are valid for `mode`: will be ignored and will not be reported. ### `--v8-options` + <!-- YAML added: v0.1.3 --> @@ -1229,6 +1330,7 @@ added: v0.1.3 Print V8 command-line options. ### `--v8-pool-size=num` + <!-- YAML added: v5.10.0 --> @@ -1242,6 +1344,7 @@ If the value provided is larger than V8's maximum, then the largest value will be chosen. ### `--zero-fill-buffers` + <!-- YAML added: v6.0.0 --> @@ -1250,6 +1353,7 @@ Automatically zero-fills all newly allocated [`Buffer`][] and [`SlowBuffer`][] instances. ### `-c`, `--check` + <!-- YAML added: - v5.0.0 @@ -1263,6 +1367,7 @@ changes: Syntax check the script without executing. ### `-e`, `--eval "script"` + <!-- YAML added: v0.5.2 changes: @@ -1279,6 +1384,7 @@ only recognizes double `"` for quoting. In Powershell or Git bash, both `'` and `"` are usable. ### `-h`, `--help` + <!-- YAML added: v0.1.3 --> @@ -1287,6 +1393,7 @@ Print node command-line options. The output of this option is less detailed than this document. ### `-i`, `--interactive` + <!-- YAML added: v0.7.7 --> @@ -1294,6 +1401,7 @@ added: v0.7.7 Opens the REPL even if stdin does not appear to be a terminal. ### `-p`, `--print "script"` + <!-- YAML added: v0.6.4 changes: @@ -1305,6 +1413,7 @@ changes: Identical to `-e` but prints the result. ### `-r`, `--require module` + <!-- YAML added: v1.6.0 --> @@ -1318,6 +1427,7 @@ Only CommonJS modules are supported. Attempting to preload a ES6 Module using `--require` will fail with an error. ### `-v`, `--version` + <!-- YAML added: v0.1.3 --> @@ -1339,7 +1449,9 @@ When `FORCE_COLOR` is used and set to a supported value, both the `NO_COLOR`, and `NODE_DISABLE_COLORS` environment variables are ignored. Any other value will result in colorized output being disabled. + ### `NODE_DEBUG=module[,…]` + <!-- YAML added: v0.1.32 --> @@ -1351,6 +1463,7 @@ added: v0.1.32 `','`-separated list of core C++ modules that should print debug information. ### `NODE_DISABLE_COLORS=1` + <!-- YAML added: v0.3.0 --> @@ -1358,6 +1471,7 @@ added: v0.3.0 When set, colors will not be used in the REPL. ### `NODE_EXTRA_CA_CERTS=file` + <!-- YAML added: v7.3.0 --> @@ -1379,6 +1493,7 @@ process is first launched. Changing the value at runtime using `process.env.NODE_EXTRA_CA_CERTS` has no effect on the current process. ### `NODE_ICU_DATA=file` + <!-- YAML added: v0.11.15 --> @@ -1387,6 +1502,7 @@ Data path for ICU (`Intl` object) data. Will extend linked-in data when compiled with small-icu support. ### `NODE_NO_WARNINGS=1` + <!-- YAML added: v6.11.0 --> @@ -1394,6 +1510,7 @@ added: v6.11.0 When set to `1`, process warnings are silenced. ### `NODE_OPTIONS=options...` + <!-- YAML added: v8.0.0 --> @@ -1429,7 +1546,9 @@ node --require "./a.js" --require "./b.js" ``` Node.js options that are allowed are: + <!-- node-options-node start --> + * `--conditions`, `-C` * `--diagnostic-dir` * `--disable-proto` @@ -1516,10 +1635,13 @@ Node.js options that are allowed are: * `--use-openssl-ca` * `--v8-pool-size` * `--zero-fill-buffers` + <!-- node-options-node end --> V8 options that are allowed are: + <!-- node-options-v8 start --> + * `--abort-on-uncaught-exception` * `--disallow-code-generation-from-strings` * `--huge-max-old-generation-size` @@ -1531,12 +1653,14 @@ V8 options that are allowed are: * `--perf-prof-unwinding-info` * `--perf-prof` * `--stack-trace-limit` + <!-- node-options-v8 end --> `--perf-basic-prof-only-functions`, `--perf-basic-prof`, `--perf-prof-unwinding-info`, and `--perf-prof` are only available on Linux. ### `NODE_PATH=path[:…]` + <!-- YAML added: v0.1.32 --> @@ -1546,6 +1670,7 @@ added: v0.1.32 On Windows, this is a `';'`-separated list instead. ### `NODE_PENDING_DEPRECATION=1` + <!-- YAML added: v8.0.0 --> @@ -1553,7 +1678,7 @@ added: v8.0.0 When set to `1`, emit pending deprecation warnings. Pending deprecations are generally identical to a runtime deprecation with the -notable exception that they are turned *off* by default and will not be emitted +notable exception that they are turned _off_ by default and will not be emitted unless either the `--pending-deprecation` command-line flag, or the `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations are used to provide a kind of selective "early warning" mechanism that @@ -1565,6 +1690,7 @@ Set the number of pending pipe instance handles when the pipe server is waiting for connections. This setting applies to Windows only. ### `NODE_PRESERVE_SYMLINKS=1` + <!-- YAML added: v7.1.0 --> @@ -1573,6 +1699,7 @@ When set to `1`, instructs the module loader to preserve symbolic links when resolving and caching modules. ### `NODE_REDIRECT_WARNINGS=file` + <!-- YAML added: v8.0.0 --> @@ -1584,6 +1711,7 @@ warning to the file, the warning will be written to stderr instead. This is equivalent to using the `--redirect-warnings=file` command-line flag. ### `NODE_REPL_HISTORY=file` + <!-- YAML added: v3.0.0 --> @@ -1593,6 +1721,7 @@ Path to the file used to store the persistent REPL history. The default path is to an empty string (`''` or `' '`) disables persistent REPL history. ### `NODE_REPL_EXTERNAL_MODULE=file` + <!-- YAML added: - v13.0.0 @@ -1603,6 +1732,7 @@ Path to a Node.js module which will be loaded in place of the built-in REPL. Overriding this value to an empty string (`''`) will use the built-in REPL. ### `NODE_SKIP_PLATFORM_CHECK=value` + <!-- YAML added: v14.5.0 --> @@ -1699,18 +1829,20 @@ and the line lengths of the source file (in the key `lineLengths`). environment variable is arbitrary. ### `OPENSSL_CONF=file` + <!-- YAML added: v6.11.0 --> Load an OpenSSL configuration file on startup. Among other uses, this can be -used to enable FIPS-compliant crypto if Node.js is built with `./configure ---openssl-fips`. +used to enable FIPS-compliant crypto if Node.js is built with +`./configure --openssl-fips`. If the [`--openssl-config`][] command-line option is used, the environment variable is ignored. ### `SSL_CERT_DIR=dir` + <!-- YAML added: v7.7.0 --> @@ -1723,6 +1855,7 @@ variable will be inherited by any child processes, and if they use OpenSSL, it may cause them to trust the same CAs as node. ### `SSL_CERT_FILE=file` + <!-- YAML added: v7.7.0 --> @@ -1735,6 +1868,7 @@ variable will be inherited by any child processes, and if they use OpenSSL, it may cause them to trust the same CAs as node. ### `TZ` + <!-- YAML added: v0.0.1 changes: diff --git a/doc/api/cluster.md b/doc/api/cluster.md index f3e7b9d535a..609a334d979 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -146,6 +146,7 @@ Although a primary use case for the `cluster` module is networking, it can also be used for other use cases requiring worker processes. ## Class: `Worker` + <!-- YAML added: v0.7.0 --> @@ -157,6 +158,7 @@ In the primary it can be obtained using `cluster.workers`. In a worker it can be obtained using `cluster.worker`. ### Event: `'disconnect'` + <!-- YAML added: v0.7.7 --> @@ -170,6 +172,7 @@ cluster.fork().on('disconnect', () => { ``` ### Event: `'error'` + <!-- YAML added: v0.7.3 --> @@ -179,6 +182,7 @@ This event is the same as the one provided by [`child_process.fork()`][]. Within a worker, `process.on('error')` may also be used. ### Event: `'exit'` + <!-- YAML added: v0.11.2 --> @@ -220,6 +224,7 @@ worker.on('exit', (code, signal) => { ``` ### Event: `'listening'` + <!-- YAML added: v0.7.0 --> @@ -247,6 +252,7 @@ cluster.fork().on('listening', (address) => { It is not emitted in the worker. ### Event: `'message'` + <!-- YAML added: v0.7.0 --> @@ -351,6 +357,7 @@ if (cluster.isPrimary) { ``` ### Event: `'online'` + <!-- YAML added: v0.7.0 --> @@ -366,6 +373,7 @@ cluster.fork().on('online', () => { It is not emitted in the worker. ### `worker.disconnect()` + <!-- YAML added: v0.7.7 changes: @@ -390,7 +398,7 @@ connections will be allowed to close as usual. When no more connections exist, see [`server.close()`][], the IPC channel to the worker will close allowing it to die gracefully. -The above applies *only* to server connections, client connections are not +The above applies _only_ to server connections, client connections are not automatically closed by workers, and disconnect does not wait for them to close before exiting. @@ -436,6 +444,7 @@ if (cluster.isPrimary) { ``` ### `worker.exitedAfterDisconnect` + <!-- YAML added: v6.0.0 --> @@ -462,6 +471,7 @@ worker.kill(); ``` ### `worker.id` + <!-- YAML added: v0.8.0 --> @@ -475,6 +485,7 @@ While a worker is alive, this is the key that indexes it in `cluster.workers`. ### `worker.isConnected()` + <!-- YAML added: v0.11.14 --> @@ -484,6 +495,7 @@ IPC channel, `false` otherwise. A worker is connected to its primary after it has been created. It is disconnected after the `'disconnect'` event is emitted. ### `worker.isDead()` + <!-- YAML added: v0.11.14 --> @@ -556,6 +568,7 @@ if (cluster.isPrimary) { ``` ### `worker.kill([signal])` + <!-- YAML added: v0.9.12 --> @@ -581,6 +594,7 @@ In a worker, `process.kill()` exists, but it is not this function; it is [`kill()`][]. ### `worker.process` + <!-- YAML added: v0.7.0 --> @@ -598,6 +612,7 @@ on `process` and `.exitedAfterDisconnect` is not `true`. This protects against accidental disconnection. ### `worker.send(message[, sendHandle[, options]][, callback])` + <!-- YAML added: v0.7.0 changes: @@ -640,6 +655,7 @@ if (cluster.isPrimary) { ``` ## Event: `'disconnect'` + <!-- YAML added: v0.7.9 --> @@ -661,6 +677,7 @@ cluster.on('disconnect', (worker) => { ``` ## Event: `'exit'` + <!-- YAML added: v0.7.9 --> @@ -685,6 +702,7 @@ cluster.on('exit', (worker, code, signal) => { See [`child_process` event: `'exit'`][]. ## Event: `'fork'` + <!-- YAML added: v0.7.0 --> @@ -713,6 +731,7 @@ cluster.on('exit', (worker, code, signal) => { ``` ## Event: `'listening'` + <!-- YAML added: v0.7.0 --> @@ -744,6 +763,7 @@ The `addressType` is one of: * `'udp4'` or `'udp6'` (UDP v4 or v6) ## Event: `'message'` + <!-- YAML added: v2.5.0 changes: @@ -761,6 +781,7 @@ Emitted when the cluster primary receives a message from any worker. See [`child_process` event: `'message'`][]. ## Event: `'online'` + <!-- YAML added: v0.7.0 --> @@ -779,6 +800,7 @@ cluster.on('online', (worker) => { ``` ## Event: `'setup'` + <!-- YAML added: v0.7.1 --> @@ -794,6 +816,7 @@ The `settings` object is the `cluster.settings` object at the time If accuracy is important, use `cluster.settings`. ## `cluster.disconnect([callback])` + <!-- YAML added: v0.7.7 --> @@ -812,6 +835,7 @@ finished. This can only be called from the primary process. ## `cluster.fork([env])` + <!-- YAML added: v0.6.0 --> @@ -824,6 +848,7 @@ Spawn a new worker process. This can only be called from the primary process. ## `cluster.isMaster` + <!-- YAML added: v0.8.1 deprecated: v16.0.0 @@ -833,6 +858,7 @@ Deprecated alias for [`cluster.isPrimary`][]. details. ## `cluster.isPrimary` + <!-- YAML added: v16.0.0 --> @@ -844,6 +870,7 @@ by the `process.env.NODE_UNIQUE_ID`. If `process.env.NODE_UNIQUE_ID` is undefined, then `isPrimary` is `true`. ## `cluster.isWorker` + <!-- YAML added: v0.6.0 --> @@ -853,6 +880,7 @@ added: v0.6.0 True if the process is not a primary (it is the negation of `cluster.isPrimary`). ## `cluster.schedulingPolicy` + <!-- YAML added: v0.11.2 --> @@ -871,6 +899,7 @@ distribute IOCP handles without incurring a large performance hit. values are `'rr'` and `'none'`. ## `cluster.settings` + <!-- YAML added: v0.7.1 changes: @@ -894,10 +923,10 @@ changes: --> * {Object} - * `execArgv` {string[]} List of string arguments passed to the Node.js + * `execArgv` {string\[]} List of string arguments passed to the Node.js executable. **Default:** `process.execArgv`. * `exec` {string} File path to worker file. **Default:** `process.argv[1]`. - * `args` {string[]} String arguments passed to worker. + * `args` {string\[]} String arguments passed to worker. **Default:** `process.argv.slice(2)`. * `cwd` {string} Current working directory of the worker process. **Default:** `undefined` (inherits from parent process). @@ -925,6 +954,7 @@ contain the settings, including the default values. This object is not intended to be changed or set manually. ## `cluster.setupMaster([settings])` + <!-- YAML added: v0.7.1 deprecated: v16.0.0 @@ -937,6 +967,7 @@ changes: Deprecated alias for [`.setupPrimary()`][]. ## `cluster.setupPrimary([settings])` + <!-- YAML added: v16.0.0 --> @@ -990,6 +1021,7 @@ cluster.fork(); // http worker This can only be called from the primary process. ## `cluster.worker` + <!-- YAML added: v0.7.0 --> @@ -1023,6 +1055,7 @@ if (cluster.isPrimary) { ``` ## `cluster.workers` + <!-- YAML added: v0.7.0 --> diff --git a/doc/api/console.md b/doc/api/console.md index 411366ab2f6..5c8b4ecc64d 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -17,7 +17,7 @@ The module exports two specific components: [`process.stderr`][]. The global `console` can be used without calling `require('console')`. -***Warning***: The global console object's methods are neither consistently +_**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [note on process I/O][] for more information. @@ -65,6 +65,7 @@ myConsole.warn(`Danger ${name}! Danger!`); ``` ## Class: `Console` + <!-- YAML changes: - version: v8.0.0 @@ -88,7 +89,9 @@ const { Console } = console; ``` ### `new Console(stdout[, stderr][, ignoreErrors])` + ### `new Console(options)` + <!-- YAML changes: - version: @@ -148,6 +151,7 @@ new Console({ stdout: process.stdout, stderr: process.stderr }); ``` ### `console.assert(value[, ...message])` + <!-- YAML added: v0.1.101 changes: @@ -178,6 +182,7 @@ console.assert(); ``` ### `console.clear()` + <!-- YAML added: v8.3.0 --> @@ -192,6 +197,7 @@ will clear only the output in the current terminal viewport for the Node.js binary. ### `console.count([label])` + <!-- YAML added: v8.3.0 --> @@ -202,6 +208,7 @@ Maintains an internal counter specific to `label` and outputs to `stdout` the number of times `console.count()` has been called with the given `label`. <!-- eslint-skip --> + ```js > console.count() default: 1 @@ -225,6 +232,7 @@ undefined ``` ### `console.countReset([label])` + <!-- YAML added: v8.3.0 --> @@ -234,6 +242,7 @@ added: v8.3.0 Resets the internal counter specific to `label`. <!-- eslint-skip --> + ```js > console.count('abc'); abc: 1 @@ -247,6 +256,7 @@ undefined ``` ### `console.debug(data[, ...args])` + <!-- YAML added: v8.0.0 changes: @@ -261,6 +271,7 @@ changes: The `console.debug()` function is an alias for [`console.log()`][]. ### `console.dir(obj[, options])` + <!-- YAML added: v0.1.101 --> @@ -273,13 +284,14 @@ added: v0.1.101 formatting the object. This is useful for inspecting large complicated objects. To make it recurse indefinitely, pass `null`. **Default:** `2`. * `colors` {boolean} If `true`, then the output will be styled with ANSI color - codes. Colors are customizable; - see [customizing `util.inspect()` colors][]. **Default:** `false`. + codes. Colors are customizable; + see [customizing `util.inspect()` colors][]. **Default:** `false`. Uses [`util.inspect()`][] on `obj` and prints the resulting string to `stdout`. This function bypasses any custom `inspect()` function defined on `obj`. ### `console.dirxml(...data)` + <!-- YAML added: v8.0.0 changes: @@ -294,6 +306,7 @@ This method calls `console.log()` passing it the arguments received. This method does not produce any XML formatting. ### `console.error([data][, ...args])` + <!-- YAML added: v0.1.100 --> @@ -319,6 +332,7 @@ If formatting elements (e.g. `%d`) are not found in the first string then values are concatenated. See [`util.format()`][] for more information. ### `console.group([...label])` + <!-- YAML added: v8.5.0 --> @@ -332,6 +346,7 @@ If one or more `label`s are provided, those are printed first without the additional indentation. ### `console.groupCollapsed()` + <!-- YAML added: v8.5.0 --> @@ -339,6 +354,7 @@ additional indentation. An alias for [`console.group()`][]. ### `console.groupEnd()` + <!-- YAML added: v8.5.0 --> @@ -347,6 +363,7 @@ Decreases indentation of subsequent lines by spaces for `groupIndentation` length. ### `console.info([data][, ...args])` + <!-- YAML added: v0.1.100 --> @@ -357,6 +374,7 @@ added: v0.1.100 The `console.info()` function is an alias for [`console.log()`][]. ### `console.log([data][, ...args])` + <!-- YAML added: v0.1.100 --> @@ -380,12 +398,13 @@ console.log('count:', count); See [`util.format()`][] for more information. ### `console.table(tabularData[, properties])` + <!-- YAML added: v10.0.0 --> * `tabularData` {any} -* `properties` {string[]} Alternate properties for constructing the table. +* `properties` {string\[]} Alternate properties for constructing the table. Try to construct a table with the columns of the properties of `tabularData` (or use `properties`) and rows of `tabularData` and log it. Falls back to just @@ -417,6 +436,7 @@ console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']); ``` ### `console.time([label])` + <!-- YAML added: v0.1.104 --> @@ -430,6 +450,7 @@ suitable time units to `stdout`. For example, if the elapsed time is 3869ms, `console.timeEnd()` displays "3.869s". ### `console.timeEnd([label])` + <!-- YAML added: v0.1.104 changes: @@ -455,6 +476,7 @@ console.timeEnd('100-elements'); ``` ### `console.timeLog([label][, ...data])` + <!-- YAML added: v10.7.0 --> @@ -475,6 +497,7 @@ console.timeEnd('process'); ``` ### `console.trace([message][, ...args])` + <!-- YAML added: v0.1.104 --> @@ -502,6 +525,7 @@ console.trace('Show me'); ``` ### `console.warn([data][, ...args])` + <!-- YAML added: v0.1.100 --> @@ -512,11 +536,13 @@ added: v0.1.100 The `console.warn()` function is an alias for [`console.error()`][]. ## Inspector only methods + The following methods are exposed by the V8 engine in the general API but do not display anything unless used in conjunction with the [inspector][] (`--inspect` flag). ### `console.profile([label])` + <!-- YAML added: v8.0.0 --> @@ -536,6 +562,7 @@ console.profileEnd('MyLabel'); ``` ### `console.profileEnd([label])` + <!-- YAML added: v8.0.0 --> @@ -551,6 +578,7 @@ If this method is called without a label, the most recently started profile is stopped. ### `console.timeStamp([label])` + <!-- YAML added: v8.0.0 --> diff --git a/doc/api/crypto.md b/doc/api/crypto.md index b01203493b0..7a64303fd65 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -52,7 +52,7 @@ try { When using the lexical ESM `import` keyword, the error can only be caught if a handler for `process.on('uncaughtException')` is registered -*before* any attempt to load the module is made -- using, for instance, +_before_ any attempt to load the module is made -- using, for instance, a preload module. When using ESM, if there is a chance that the code may be run on a build @@ -69,6 +69,7 @@ try { ``` ## Class: `Certificate` + <!-- YAML added: v0.11.8 --> @@ -84,6 +85,7 @@ data. The most common usage is handling output generated by the HTML5 `<keygen>` element. Node.js uses [OpenSSL's SPKAC implementation][] internally. ### Static method: `Certificate.exportChallenge(spkac[, encoding])` + <!-- YAML added: v9.0.0 changes: @@ -115,6 +117,7 @@ console.log(challenge.toString('utf8')); ``` ### Static method: `Certificate.exportPublicKey(spkac[, encoding])` + <!-- YAML added: v9.0.0 changes: @@ -146,6 +149,7 @@ console.log(publicKey); ``` ### Static method: `Certificate.verifySpkac(spkac[, encoding])` + <!-- YAML added: v9.0.0 changes: @@ -206,6 +210,7 @@ const cert2 = Certificate(); ``` #### `certificate.exportChallenge(spkac[, encoding])` + <!-- YAML added: v0.11.8 --> @@ -234,6 +239,7 @@ console.log(challenge.toString('utf8')); ``` #### `certificate.exportPublicKey(spkac[, encoding])` + <!-- YAML added: v0.11.8 --> @@ -262,6 +268,7 @@ console.log(publicKey); ``` #### `certificate.verifySpkac(spkac[, encoding])` + <!-- YAML added: v0.11.8 --> @@ -292,6 +299,7 @@ console.log(cert.verifySpkac(Buffer.from(spkac))); ``` ## Class: `Cipher` + <!-- YAML added: v0.1.94 --> @@ -515,6 +523,7 @@ scrypt(password, 'salt', 24, (err, key) => { ``` ### `cipher.final([outputEncoding])` + <!-- YAML added: v0.1.94 --> @@ -529,6 +538,7 @@ longer be used to encrypt data. Attempts to call `cipher.final()` more than once will result in an error being thrown. ### `cipher.getAuthTag()` + <!-- YAML added: v1.0.0 --> @@ -542,6 +552,7 @@ The `cipher.getAuthTag()` method should only be called after encryption has been completed using the [`cipher.final()`][] method. ### `cipher.setAAD(buffer[, options])` + <!-- YAML added: v1.0.0 --> @@ -563,6 +574,7 @@ length of the plaintext in bytes. See [CCM mode][]. The `cipher.setAAD()` method must be called before [`cipher.update()`][]. ### `cipher.setAutoPadding([autoPadding])` + <!-- YAML added: v0.7.1 --> @@ -583,6 +595,7 @@ The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][]. ### `cipher.update(data[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.1.94 changes: @@ -613,6 +626,7 @@ The `cipher.update()` method can be called multiple times with new data until [`cipher.final()`][] will result in an error being thrown. ## Class: `Decipher` + <!-- YAML added: v0.1.94 --> @@ -812,6 +826,7 @@ console.log(decrypted); ``` ### `decipher.final([outputEncoding])` + <!-- YAML added: v0.1.94 --> @@ -826,6 +841,7 @@ no longer be used to decrypt data. Attempts to call `decipher.final()` more than once will result in an error being thrown. ### `decipher.setAAD(buffer[, options])` + <!-- YAML added: v1.0.0 changes: @@ -858,6 +874,7 @@ When passing a string as the `buffer`, please consider [caveats when using strings as inputs to cryptographic APIs][]. ### `decipher.setAuthTag(buffer[, encoding])` + <!-- YAML added: v1.0.0 changes: @@ -893,6 +910,7 @@ When passing a string as the authentication tag, please consider [caveats when using strings as inputs to cryptographic APIs][]. ### `decipher.setAutoPadding([autoPadding])` + <!-- YAML added: v0.7.1 --> @@ -911,6 +929,7 @@ The `decipher.setAutoPadding()` method must be called before [`decipher.final()`][]. ### `decipher.update(data[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.1.94 changes: @@ -940,6 +959,7 @@ The `decipher.update()` method can be called multiple times with new data until [`decipher.final()`][] will result in an error being thrown. ## Class: `DiffieHellman` + <!-- YAML added: v0.5.0 --> @@ -997,6 +1017,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); ``` ### `diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.5.0 --> @@ -1018,6 +1039,7 @@ If `outputEncoding` is given a string is returned; otherwise, a [`Buffer`][] is returned. ### `diffieHellman.generateKeys([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1032,6 +1054,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getGenerator([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1044,6 +1067,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getPrime([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1056,6 +1080,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getPrivateKey([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1068,6 +1093,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getPublicKey([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1080,6 +1106,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.setPrivateKey(privateKey[, encoding])` + <!-- YAML added: v0.5.0 --> @@ -1093,6 +1120,7 @@ to be a string. If no `encoding` is provided, `privateKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. ### `diffieHellman.setPublicKey(publicKey[, encoding])` + <!-- YAML added: v0.5.0 --> @@ -1106,6 +1134,7 @@ to be a string. If no `encoding` is provided, `publicKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. ### `diffieHellman.verifyError` + <!-- YAML added: v0.11.12 --> @@ -1122,6 +1151,7 @@ module): * `DH_NOT_SUITABLE_GENERATOR` ## Class: `DiffieHellmanGroup` + <!-- YAML added: v0.7.5 --> @@ -1157,6 +1187,7 @@ modp18 ``` ## Class: `ECDH` + <!-- YAML added: v0.11.14 --> @@ -1214,6 +1245,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); ``` ### Static method: `ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])` + <!-- YAML added: v10.0.0 --> @@ -1286,6 +1318,7 @@ console.log(uncompressedKey === ecdh.getPublicKey('hex')); ``` ### `ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.11.14 changes: @@ -1321,6 +1354,7 @@ usually supplied from a remote user over an insecure network, be sure to handle this exception accordingly. ### `ecdh.generateKeys([encoding[, format]])` + <!-- YAML added: v0.11.14 --> @@ -1341,6 +1375,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `ecdh.getPrivateKey([encoding])` + <!-- YAML added: v0.11.14 --> @@ -1352,6 +1387,7 @@ If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. ### `ecdh.getPublicKey([encoding][, format])` + <!-- YAML added: v0.11.14 --> @@ -1369,6 +1405,7 @@ If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. ### `ecdh.setPrivateKey(privateKey[, encoding])` + <!-- YAML added: v0.11.14 --> @@ -1386,6 +1423,7 @@ created, an error is thrown. Upon setting the private key, the associated public point (key) is also generated and set in the `ECDH` object. ### `ecdh.setPublicKey(publicKey[, encoding])` + <!-- YAML added: v0.11.14 deprecated: v5.2.0 @@ -1464,6 +1502,7 @@ console.log(aliceSecret === bobSecret); ``` ## Class: `Hash` + <!-- YAML added: v0.1.92 --> @@ -1580,6 +1619,7 @@ console.log(hash.digest('hex')); ``` ### `hash.copy([options])` + <!-- YAML added: v13.1.0 --> @@ -1638,6 +1678,7 @@ console.log(hash.copy().digest('hex')); ``` ### `hash.digest([encoding])` + <!-- YAML added: v0.1.92 --> @@ -1654,6 +1695,7 @@ The `Hash` object can not be used again after `hash.digest()` method has been called. Multiple calls will cause an error to be thrown. ### `hash.update(data[, inputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -1674,6 +1716,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ## Class: `Hmac` + <!-- YAML added: v0.1.94 --> @@ -1796,6 +1839,7 @@ console.log(hmac.digest('hex')); ``` ### `hmac.digest([encoding])` + <!-- YAML added: v0.1.94 --> @@ -1811,6 +1855,7 @@ The `Hmac` object can not be used again after `hmac.digest()` has been called. Multiple calls to `hmac.digest()` will result in an error being thrown. ### `hmac.update(data[, inputEncoding])` + <!-- YAML added: v0.1.94 changes: @@ -1831,6 +1876,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ## Class: `KeyObject` + <!-- YAML added: v11.6.0 changes: @@ -1860,6 +1906,7 @@ The receiver obtains a cloned `KeyObject`, and the `KeyObject` does not need to be listed in the `transferList` argument. ### Static method: `KeyObject.from(key)` + <!-- YAML added: v15.0.0 --> @@ -1906,6 +1953,7 @@ const { ``` ### `keyObject.asymmetricKeyDetails` + <!-- YAML added: v15.7.0 changes: @@ -1937,6 +1985,7 @@ set. Other key details might be exposed via this API using additional attributes. ### `keyObject.asymmetricKeyType` + <!-- YAML added: v11.6.0 changes: @@ -1979,6 +2028,7 @@ This property is `undefined` for unrecognized `KeyObject` types and symmetric keys. ### `keyObject.export([options])` + <!-- YAML added: v11.6.0 changes: @@ -2005,8 +2055,8 @@ For private keys, the following encoding options can be used: `'sec1'` (EC only). * `format`: {string} Must be `'pem'`, `'der'`, or `'jwk'`. * `cipher`: {string} If specified, the private key will be encrypted with - the given `cipher` and `passphrase` using PKCS#5 v2.0 password based - encryption. + the given `cipher` and `passphrase` using PKCS#5 v2.0 password based + encryption. * `passphrase`: {string | Buffer} The passphrase to use for encryption, see `cipher`. @@ -2028,6 +2078,7 @@ a PKCS#8 key. See [RFC 5208][] for PKCS#8 encryption and [RFC 1421][] for PKCS#1 and SEC1 encryption. ### `keyObject.symmetricKeySize` + <!-- YAML added: v11.6.0 --> @@ -2038,6 +2089,7 @@ For secret keys, this property represents the size of the key in bytes. This property is `undefined` for asymmetric keys. ### `keyObject.type` + <!-- YAML added: v11.6.0 --> @@ -2049,6 +2101,7 @@ Depending on the type of this `KeyObject`, this property is either or `'private'` for private (asymmetric) keys. ## Class: `Sign` + <!-- YAML added: v0.1.92 --> @@ -2164,6 +2217,7 @@ console.log(verify.verify(publicKey, signature)); ``` ### `sign.sign(privateKey[, outputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2187,12 +2241,14 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `privateKey` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `dsaEncoding` {string} * `padding` {integer} * `saltLength` {integer} * `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} + <!--lint enable maximum-line-length remark-lint--> Calculates the signature on all the data passed through using either @@ -2207,6 +2263,7 @@ object, the following additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -2227,6 +2284,7 @@ The `Sign` object can not be again used after `sign.sign()` method has been called. Multiple calls to `sign.sign()` will result in an error being thrown. ### `sign.update(data[, inputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2247,6 +2305,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ## Class: `Verify` + <!-- YAML added: v0.1.92 --> @@ -2267,6 +2326,7 @@ The [`crypto.createVerify()`][] method is used to create `Verify` instances. See [`Sign`][] for examples. ### `verify.update(data[, inputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2287,6 +2347,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ### `verify.verify(object, signature[, signatureEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2310,6 +2371,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `object` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `dsaEncoding` {string} * `padding` {integer} @@ -2318,6 +2380,7 @@ changes: * `signatureEncoding` {string} The [encoding][] of the `signature` string. * Returns: {boolean} `true` or `false` depending on the validity of the signature for the data and public key. + <!--lint enable maximum-line-length remark-lint--> Verifies the provided data using the given `object` and `signature`. @@ -2331,6 +2394,7 @@ object, the following additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -2358,6 +2422,7 @@ Because public keys can be derived from private keys, a private key may be passed instead of a public key. ## Class: `X509Certificate` + <!-- YAML added: v15.6.0 --> @@ -2382,6 +2447,7 @@ console.log(x509.subject); ``` ### `new X509Certificate(buffer)` + <!-- YAML added: v15.6.0 --> @@ -2390,6 +2456,7 @@ added: v15.6.0 X509 Certificate. ### `x509.ca` + <!-- YAML added: v15.6.0 --> @@ -2398,6 +2465,7 @@ added: v15.6.0 certificate. ### `x509.checkEmail(email[, options])` + <!-- YAML added: v15.6.0 --> @@ -2415,6 +2483,7 @@ added: v15.6.0 Checks whether the certificate matches the given email address. ### `x509.checkHost(name[, options])` + <!-- YAML added: v15.6.0 --> @@ -2432,6 +2501,7 @@ added: v15.6.0 Checks whether the certificate matches the given host name. ### `x509.checkIP(ip[, options])` + <!-- YAML added: v15.6.0 --> @@ -2449,6 +2519,7 @@ added: v15.6.0 Checks whether the certificate matches the given IP address (IPv4 or IPv6). ### `x509.checkIssued(otherCert)` + <!-- YAML added: v15.6.0 --> @@ -2459,6 +2530,7 @@ added: v15.6.0 Checks whether this certificate was issued by the given `otherCert`. ### `x509.checkPrivateKey(privateKey)` + <!-- YAML added: v15.6.0 --> @@ -2470,6 +2542,7 @@ Checks whether the public key for this certificate is consistent with the given private key. ### `x509.fingerprint` + <!-- YAML added: v15.6.0 --> @@ -2479,6 +2552,7 @@ added: v15.6.0 The SHA-1 fingerprint of this certificate. ### `x509.fingerprint256` + <!-- YAML added: v15.6.0 --> @@ -2488,6 +2562,7 @@ added: v15.6.0 The SHA-256 fingerprint of this certificate. ### `x509.infoAccess` + <!-- YAML added: v15.6.0 --> @@ -2497,6 +2572,7 @@ added: v15.6.0 The information access content of this certificate. ### `x509.issuer` + <!-- YAML added: v15.6.0 --> @@ -2506,6 +2582,7 @@ added: v15.6.0 The issuer identification included in this certificate. ### `x509.issuerCertificate` + <!-- YAML added: v15.9.0 --> @@ -2516,15 +2593,17 @@ The issuer certificate or `undefined` if the issuer certificate is not available. ### `x509.keyUsage` + <!-- YAML added: v15.6.0 --> -* Type: {string[]} +* Type: {string\[]} An array detailing the key usages for this certificate. ### `x509.publicKey` + <!-- YAML added: v15.6.0 --> @@ -2534,6 +2613,7 @@ added: v15.6.0 The public key {KeyObject} for this certificate. ### `x509.raw` + <!-- YAML added: v15.6.0 --> @@ -2543,6 +2623,7 @@ added: v15.6.0 A `Buffer` containing the DER encoding of this certificate. ### `x509.serialNumber` + <!-- YAML added: v15.6.0 --> @@ -2552,6 +2633,7 @@ added: v15.6.0 The serial number of this certificate. ### `x509.subject` + <!-- YAML added: v15.6.0 --> @@ -2561,6 +2643,7 @@ added: v15.6.0 The complete subject of this certificate. ### `x509.subjectAltName` + <!-- YAML added: v15.6.0 --> @@ -2570,6 +2653,7 @@ added: v15.6.0 The subject alternative name specified for this certificate. ### `x509.toJSON()` + <!-- YAML added: v15.6.0 --> @@ -2581,6 +2665,7 @@ There is no standard JSON encoding for X509 certificates. The certificate. ### `x509.toLegacyObject()` + <!-- YAML added: v15.6.0 --> @@ -2591,6 +2676,7 @@ Returns information about this certificate using the legacy [certificate object][] encoding. ### `x509.toString()` + <!-- YAML added: v15.6.0 --> @@ -2600,6 +2686,7 @@ added: v15.6.0 Returns the PEM-encoded certificate. ### `x509.validFrom` + <!-- YAML added: v15.6.0 --> @@ -2609,6 +2696,7 @@ added: v15.6.0 The date/time from which this certificate is considered valid. ### `x509.validTo` + <!-- YAML added: v15.6.0 --> @@ -2618,6 +2706,7 @@ added: v15.6.0 The date/time until which this certificate is considered valid. ### `x509.verify(publicKey)` + <!-- YAML added: v15.6.0 --> @@ -2631,6 +2720,7 @@ Does not perform any other validation checks on the certificate. ## `crypto` module methods and properties ### `crypto.constants` + <!-- YAML added: v6.3.0 --> @@ -2640,6 +2730,7 @@ added: v6.3.0 described in [Crypto constants][]. ### `crypto.DEFAULT_ENCODING` + <!-- YAML added: v0.9.3 deprecated: v10.0.0 @@ -2659,6 +2750,7 @@ New applications should expect the default to be `'buffer'`. This property is deprecated. ### `crypto.fips` + <!-- YAML added: v6.0.0 deprecated: v10.0.0 @@ -2673,6 +2765,7 @@ This property is deprecated. Please use `crypto.setFips()` and `crypto.getFips()` instead. ### `crypto.checkPrime(candidate[, options, [callback]])` + <!-- YAML added: v15.8.0 --> @@ -2695,6 +2788,7 @@ added: v15.8.0 Checks the primality of the `candidate`. ### `crypto.checkPrimeSync(candidate[, options])` + <!-- YAML added: v15.8.0 --> @@ -2715,6 +2809,7 @@ added: v15.8.0 Checks the primality of the `candidate`. ### `crypto.createCipher(algorithm, password[, options])` + <!-- YAML added: v0.1.94 deprecated: v10.0.0 @@ -2775,6 +2870,7 @@ vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting Adversaries][] for details. ### `crypto.createCipheriv(algorithm, key, iv[, options])` + <!-- YAML added: v0.1.94 changes: @@ -2841,6 +2937,7 @@ remember that an attacker must not be able to predict ahead of time what a given IV will be. ### `crypto.createDecipher(algorithm, password[, options])` + <!-- YAML added: v0.1.94 deprecated: v10.0.0 @@ -2878,6 +2975,7 @@ their own using [`crypto.scrypt()`][] and to use [`crypto.createDecipheriv()`][] to create the `Decipher` object. ### `crypto.createDecipheriv(algorithm, key, iv[, options])` + <!-- YAML added: v0.1.94 changes: @@ -2940,6 +3038,7 @@ remember that an attacker must not be able to predict ahead of time what a given IV will be. ### `crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])` + <!-- YAML added: v0.11.12 changes: @@ -2975,6 +3074,7 @@ If `generatorEncoding` is specified, `generator` is expected to be a string; otherwise a number, [`Buffer`][], `TypedArray`, or `DataView` is expected. ### `crypto.createDiffieHellman(primeLength[, generator])` + <!-- YAML added: v0.5.0 --> @@ -2988,6 +3088,7 @@ Creates a `DiffieHellman` key exchange object and generates a prime of If `generator` is not specified, the value `2` is used. ### `crypto.createDiffieHellmanGroup(name)` + <!-- YAML added: v0.9.3 --> @@ -2998,6 +3099,7 @@ added: v0.9.3 An alias for [`crypto.getDiffieHellman()`][] ### `crypto.createECDH(curveName)` + <!-- YAML added: v0.11.14 --> @@ -3012,6 +3114,7 @@ OpenSSL releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. ### `crypto.createHash(algorithm[, options])` + <!-- YAML added: v0.1.92 changes: @@ -3090,6 +3193,7 @@ input.on('readable', () => { ``` ### `crypto.createHmac(algorithm, key[, options])` + <!-- YAML added: v0.1.94 changes: @@ -3176,6 +3280,7 @@ input.on('readable', () => { ``` ### `crypto.createPrivateKey(key)` + <!-- YAML added: v11.6.0 changes: @@ -3189,16 +3294,18 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView} * `key`: {string|ArrayBuffer|Buffer|TypedArray|DataView|Object} The key material, either in PEM, DER, or JWK format. * `format`: {string} Must be `'pem'`, `'der'`, or '`'jwk'`. **Default:** `'pem'`. * `type`: {string} Must be `'pkcs1'`, `'pkcs8'` or `'sec1'`. This option is - required only if the `format` is `'der'` and ignored otherwise. + required only if the `format` is `'der'` and ignored otherwise. * `passphrase`: {string | Buffer} The passphrase to use for decryption. * `encoding`: {string} The string encoding to use when `key` is a string. * Returns: {KeyObject} + <!--lint enable maximum-line-length remark-lint--> Creates and returns a new key object containing a private key. If `key` is a @@ -3209,6 +3316,7 @@ If the private key is encrypted, a `passphrase` must be specified. The length of the passphrase is limited to 1024 bytes. ### `crypto.createPublicKey(key)` + <!-- YAML added: v11.6.0 changes: @@ -3229,15 +3337,17 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView} * `key`: {string|ArrayBuffer|Buffer|TypedArray|DataView|Object} The key material, either in PEM, DER, or JWK format. * `format`: {string} Must be `'pem'`, `'der'`, or `'jwk'`. **Default:** `'pem'`. * `type`: {string} Must be `'pkcs1'` or `'spki'`. This option is - required only if the `format` is `'der'` and ignored otherwise. + required only if the `format` is `'der'` and ignored otherwise. * `encoding` {string} The string encoding to use when `key` is a string. * Returns: {KeyObject} + <!--lint enable maximum-line-length remark-lint--> Creates and returns a new key object containing a public key. If `key` is a @@ -3256,6 +3366,7 @@ extracted from the returned `KeyObject`. Similarly, if a `KeyObject` with type and it will be impossible to extract the private key from the returned object. ### `crypto.createSecretKey(key[, encoding])` + <!-- YAML added: v11.6.0 changes: @@ -3274,6 +3385,7 @@ Creates and returns a new key object containing a secret key for symmetric encryption or `Hmac`. ### `crypto.createSign(algorithm[, options])` + <!-- YAML added: v0.1.92 --> @@ -3293,6 +3405,7 @@ algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest algorithm names. ### `crypto.createVerify(algorithm[, options])` + <!-- YAML added: v0.1.92 --> @@ -3313,6 +3426,7 @@ algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest algorithm names. ### `crypto.diffieHellman(options)` + <!-- YAML added: - v13.9.0 @@ -3329,6 +3443,7 @@ Both keys must have the same `asymmetricKeyType`, which must be one of `'dh'` (for Diffie-Hellman), `'ec'` (for ECDH), `'x448'`, or `'x25519'` (for ECDH-ES). ### `crypto.generateKey(type, options, callback)` + <!-- YAML added: v15.0.0 --> @@ -3372,6 +3487,7 @@ generateKey('hmac', { length: 64 }, (err, key) => { ``` ### `crypto.generateKeyPair(type, options, callback)` + <!-- YAML added: v10.12.0 changes: @@ -3483,6 +3599,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a `Promise` for an `Object` with `publicKey` and `privateKey` properties. ### `crypto.generateKeyPairSync(type, options)` + <!-- YAML added: v10.12.0 changes: @@ -3594,6 +3711,7 @@ When PEM encoding was selected, the respective key will be a string, otherwise it will be a buffer containing the data encoded as DER. ### `crypto.generateKeySync(type, options)` + <!-- YAML added: v15.0.0 --> @@ -3630,6 +3748,7 @@ console.log(key.export().toString('hex')); // e89..........41e ``` ### `crypto.generatePrime(size[, options[, callback]])` + <!-- YAML added: v15.8.0 --> @@ -3672,6 +3791,7 @@ in an {ArrayBuffer}. If the `bigint` option is `true`, then a {bigint} is provided. ### `crypto.generatePrimeSync(size[, options])` + <!-- YAML added: v15.8.0 --> @@ -3712,6 +3832,7 @@ in an {ArrayBuffer}. If the `bigint` option is `true`, then a {bigint} is provided. ### `crypto.getCipherInfo(nameOrNid[, options])` + <!-- YAML added: v15.0.0 --> @@ -3741,11 +3862,12 @@ cipher, use the `keyLength` and `ivLength` options. If the given values are unacceptable, `undefined` will be returned. ### `crypto.getCiphers()` + <!-- YAML added: v0.9.3 --> -* Returns: {string[]} An array with the names of the supported cipher +* Returns: {string\[]} An array with the names of the supported cipher algorithms. ```mjs @@ -3765,11 +3887,12 @@ console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...] ``` ### `crypto.getCurves()` + <!-- YAML added: v2.3.0 --> -* Returns: {string[]} An array with the names of the supported elliptic curves. +* Returns: {string\[]} An array with the names of the supported elliptic curves. ```mjs const { @@ -3788,6 +3911,7 @@ console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...] ``` ### `crypto.getDiffieHellman(groupName)` + <!-- YAML added: v0.7.5 --> @@ -3844,6 +3968,7 @@ console.log(aliceSecret === bobSecret); ``` ### `crypto.getFips()` + <!-- YAML added: v10.0.0 --> @@ -3853,11 +3978,12 @@ added: v10.0.0 the return type of this API to a {boolean}. ### `crypto.getHashes()` + <!-- YAML added: v0.9.3 --> -* Returns: {string[]} An array of the names of the supported hash algorithms, +* Returns: {string\[]} An array of the names of the supported hash algorithms, such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms. ```mjs @@ -3877,6 +4003,7 @@ console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...] ``` ### `crypto.hkdf(digest, ikm, salt, info, keylen, callback)` + <!-- YAML added: v15.0.0 --> @@ -3930,6 +4057,7 @@ hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => { ``` ### `crypto.hkdfSync(digest, ikm, salt, info, keylen)` + <!-- YAML added: v15.0.0 --> @@ -3977,6 +4105,7 @@ console.log(Buffer.from(derivedKey).toString('hex')); // '24156e2...5391653' ``` ### `crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)` + <!-- YAML added: v0.5.5 changes: @@ -4086,6 +4215,7 @@ negative performance implications for some applications; see the [`UV_THREADPOOL_SIZE`][] documentation for more information. ### `crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)` + <!-- YAML added: v0.9.3 changes: @@ -4171,6 +4301,7 @@ An array of supported digest functions can be retrieved using [`crypto.getHashes()`][]. ### `crypto.privateDecrypt(privateKey, buffer)` + <!-- YAML added: v0.11.14 changes: @@ -4192,17 +4323,19 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `privateKey` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `oaepHash` {string} The hash function to use for OAEP padding and MGF1. **Default:** `'sha1'` * `oaepLabel` {string|ArrayBuffer|Buffer|TypedArray|DataView} The label to - use for OAEP padding. If not specified, no label is used. + use for OAEP padding. If not specified, no label is used. * `padding` {crypto.constants} An optional padding value defined in `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`, `crypto.constants.RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the decrypted content. + <!--lint enable maximum-line-length remark-lint--> Decrypts `buffer` with `privateKey`. `buffer` was previously encrypted using @@ -4214,6 +4347,7 @@ object, the `padding` property can be passed. Otherwise, this function uses `RSA_PKCS1_OAEP_PADDING`. ### `crypto.privateEncrypt(privateKey, buffer)` + <!-- YAML added: v1.1.0 changes: @@ -4229,6 +4363,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `privateKey` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `key` {string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} A PEM encoded private key. @@ -4241,6 +4376,7 @@ changes: or `passphrase` are strings. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the encrypted content. + <!--lint enable maximum-line-length remark-lint--> Encrypts `buffer` with `privateKey`. The returned data can be decrypted using @@ -4252,6 +4388,7 @@ object, the `padding` property can be passed. Otherwise, this function uses `RSA_PKCS1_PADDING`. ### `crypto.publicDecrypt(key, buffer)` + <!-- YAML added: v1.1.0 changes: @@ -4267,6 +4404,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `passphrase` {string|ArrayBuffer|Buffer|TypedArray|DataView} An optional passphrase for the private key. @@ -4277,6 +4415,7 @@ changes: or `passphrase` are strings. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the decrypted content. + <!--lint enable maximum-line-length remark-lint--> Decrypts `buffer` with `key`.`buffer` was previously encrypted using @@ -4291,6 +4430,7 @@ Because RSA public keys can be derived from private keys, a private key may be passed instead of a public key. ### `crypto.publicEncrypt(key, buffer)` + <!-- YAML added: v0.11.14 changes: @@ -4312,6 +4452,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `key` {string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} A PEM encoded public or private key, {KeyObject}, or {CryptoKey}. @@ -4329,6 +4470,7 @@ changes: `oaepLabel`, or `passphrase` are strings. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the encrypted content. + <!--lint enable maximum-line-length remark-lint--> Encrypts the content of `buffer` with `key` and returns a new @@ -4344,6 +4486,7 @@ Because RSA public keys can be derived from private keys, a private key may be passed instead of a public key. ### `crypto.randomBytes(size[, callback])` + <!-- YAML added: v0.5.8 changes: @@ -4434,6 +4577,7 @@ large `randomBytes` requests when doing so as part of fulfilling a client request. ### `crypto.randomFillSync(buffer[, offset][, size])` + <!-- YAML added: - v7.10.0 @@ -4520,6 +4664,7 @@ console.log(Buffer.from(randomFillSync(c)).toString('hex')); ``` ### `crypto.randomFill(buffer[, offset][, size], callback)` + <!-- YAML added: - v7.10.0 @@ -4656,6 +4801,7 @@ large `randomFill` requests when doing so as part of fulfilling a client request. ### `crypto.randomInt([min, ]max[, callback])` + <!-- YAML added: - v14.10.0 @@ -4740,6 +4886,7 @@ console.log(`The dice rolled: ${n}`); ``` ### `crypto.randomUUID([options])` + <!-- YAML added: - v15.6.0 @@ -4758,6 +4905,7 @@ Generates a random [RFC 4122][] version 4 UUID. The UUID is generated using a cryptographic pseudorandom number generator. ### `crypto.scrypt(password, salt, keylen[, options], callback)` + <!-- YAML added: v10.5.0 changes: @@ -4845,6 +4993,7 @@ scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => { ``` ### `crypto.scryptSync(password, salt, keylen[, options])` + <!-- YAML added: v10.5.0 changes: @@ -4917,6 +5066,7 @@ console.log(key2.toString('hex')); // '3745e48...aa39b34' ``` ### `crypto.secureHeapUsed()` + <!-- YAML added: v15.6.0 --> @@ -4932,6 +5082,7 @@ added: v15.6.0 allocated bytes. ### `crypto.setEngine(engine[, flags])` + <!-- YAML added: v0.11.11 --> @@ -4966,6 +5117,7 @@ The flags below are deprecated in OpenSSL-1.1.0. * `crypto.constants.ENGINE_METHOD_STORE` ### `crypto.setFips(bool)` + <!-- YAML added: v10.0.0 --> @@ -4976,6 +5128,7 @@ Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. Throws an error if FIPS mode is not available. ### `crypto.sign(algorithm, data, key[, callback])` + <!-- YAML added: v12.0.0 changes: @@ -4990,6 +5143,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm` {string | null | undefined} * `data` {ArrayBuffer|Buffer|TypedArray|DataView} * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} @@ -4997,6 +5151,7 @@ changes: * `err` {Error} * `signature` {Buffer} * Returns: {Buffer} if the `callback` function is not provided. + <!--lint enable maximum-line-length remark-lint--> Calculates and returns the signature for `data` using the given private key and @@ -5012,6 +5167,7 @@ additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -5026,6 +5182,7 @@ additional properties can be passed: If the `callback` function is provided this function uses libuv's threadpool. ### `crypto.timingSafeEqual(a, b)` + <!-- YAML added: v6.6.0 changes: @@ -5051,11 +5208,12 @@ If at least one of `a` and `b` is a `TypedArray` with more than one byte per entry, such as `Uint16Array`, the result will be computed using the platform byte order. -Use of `crypto.timingSafeEqual` does not guarantee that the *surrounding* code +Use of `crypto.timingSafeEqual` does not guarantee that the _surrounding_ code is timing-safe. Care should be taken to ensure that the surrounding code does not introduce timing vulnerabilities. ### `crypto.verify(algorithm, data, key, signature[, callback])` + <!-- YAML added: v12.0.0 changes: @@ -5073,6 +5231,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm` {string|null|undefined} * `data` {ArrayBuffer| Buffer|TypedArray|DataView} * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} @@ -5083,6 +5242,7 @@ changes: * Returns: {boolean} `true` or `false` depending on the validity of the signature for the data and public key if the `callback` function is not provided. + <!--lint enable maximum-line-length remark-lint--> Verifies the given signature for `data` using the given key and algorithm. If @@ -5098,6 +5258,7 @@ additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -5117,6 +5278,7 @@ key may be passed for `key`. If the `callback` function is provided this function uses libuv's threadpool. ### `crypto.webcrypto` + <!-- YAML added: v15.0.0 --> @@ -5244,7 +5406,7 @@ mode must adhere to certain restrictions when using the cipher API: * As CCM processes the whole message at once, `update()` must be called exactly once. * Even though calling `update()` is sufficient to encrypt/decrypt the message, - applications *must* call `final()` to compute or verify the + applications _must_ call `final()` to compute or verify the authentication tag. ```mjs diff --git a/doc/api/debugger.md b/doc/api/debugger.md index b155738b073..c5e019e5412 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -32,6 +32,7 @@ Inserting the statement `debugger;` into the source code of a script will enable a breakpoint at that position in the code: <!-- eslint-disable no-debugger --> + ```js // myscript.js global.x = 5; diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 6acd98db64d..c8526f55c32 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -42,6 +42,7 @@ However, the deprecation identifier will not be modified. ## List of deprecated APIs ### DEP0001: `http.OutgoingMessage.prototype.flush` + <!-- YAML changes: - version: v14.0.0 @@ -63,6 +64,7 @@ Type: End-of-Life `OutgoingMessage.prototype.flushHeaders()` instead. ### DEP0002: `require('_linklist')` + <!-- YAML changes: - version: v8.0.0 @@ -81,6 +83,7 @@ Type: End-of-Life The `_linklist` module is deprecated. Please use a userland alternative. ### DEP0003: `_writableState.buffer` + <!-- YAML changes: - version: v14.0.0 @@ -102,6 +105,7 @@ The `_writableState.buffer` has been removed. Use `_writableState.getBuffer()` instead. ### DEP0004: `CryptoStream.prototype.readyState` + <!-- YAML changes: - version: v10.0.0 @@ -122,6 +126,7 @@ Type: End-of-Life The `CryptoStream.prototype.readyState` property was removed. ### DEP0005: `Buffer()` constructor + <!-- YAML changes: - version: v10.0.0 @@ -144,11 +149,11 @@ As an alternative, use one of the following methods of constructing `Buffer` objects: * [`Buffer.alloc(size[, fill[, encoding]])`][alloc]: Create a `Buffer` with - *initialized* memory. + _initialized_ memory. * [`Buffer.allocUnsafe(size)`][alloc_unsafe_size]: Create a `Buffer` with - *uninitialized* memory. -* [`Buffer.allocUnsafeSlow(size)`][]: Create a `Buffer` with *uninitialized* - memory. + _uninitialized_ memory. +* [`Buffer.allocUnsafeSlow(size)`][]: Create a `Buffer` with _uninitialized_ + memory. * [`Buffer.from(array)`][]: Create a `Buffer` with a copy of `array` * [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - Create a `Buffer` that wraps the given `arrayBuffer`. @@ -162,6 +167,7 @@ Without `--pending-deprecation`, runtime warnings occur only for code not in warning results no matter where the `Buffer()` usage occurs. ### DEP0006: `child_process` `options.customFds` + <!-- YAML changes: - version: v12.0.0 @@ -185,6 +191,7 @@ methods, the `options.customFds` option is deprecated. The `options.stdio` option should be used instead. ### DEP0007: Replace `cluster` `worker.suicide` with `worker.exitedAfterDisconnect` + <!-- YAML changes: - version: v9.0.0 @@ -211,6 +218,7 @@ provide an indication of how and why the `Worker` instance exited. In Node.js precisely describe the actual semantics and was unnecessarily emotion-laden. ### DEP0008: `require('constants')` + <!-- YAML changes: - version: v6.12.0 @@ -229,6 +237,7 @@ to the `constants` property exposed by the relevant module. For instance, `require('fs').constants` and `require('os').constants`. ### DEP0009: `crypto.pbkdf2` without digest + <!-- YAML changes: - version: v14.0.0 @@ -263,6 +272,7 @@ is `undefined`. Now, however, passing either `undefined` or `null` will throw a `TypeError`. ### DEP0010: `crypto.createCredentials` + <!-- YAML changes: - version: v11.0.0 @@ -284,6 +294,7 @@ The `crypto.createCredentials()` API was removed. Please use [`tls.createSecureContext()`][] instead. ### DEP0011: `crypto.Credentials` + <!-- YAML changes: - version: v11.0.0 @@ -305,6 +316,7 @@ The `crypto.Credentials` class was removed. Please use [`tls.SecureContext`][] instead. ### DEP0012: `Domain.dispose` + <!-- YAML changes: - version: v9.0.0 @@ -326,6 +338,7 @@ Type: End-of-Life explicitly via error event handlers set on the domain instead. ### DEP0013: `fs` asynchronous function without callback + <!-- YAML changes: - version: v10.0.0 @@ -342,6 +355,7 @@ Calling an asynchronous function without a callback throws a `TypeError` in Node.js 10.0.0 onwards. See <https://github.com/nodejs/node/pull/12562>. ### DEP0014: `fs.read` legacy String interface + <!-- YAML changes: - version: v8.0.0 @@ -366,6 +380,7 @@ The [`fs.read()`][] legacy `String` interface is deprecated. Use the `Buffer` API as mentioned in the documentation instead. ### DEP0015: `fs.readSync` legacy String interface + <!-- YAML changes: - version: v8.0.0 @@ -390,6 +405,7 @@ The [`fs.readSync()`][] legacy `String` interface is deprecated. Use the `Buffer` API as mentioned in the documentation instead. ### DEP0016: `GLOBAL`/`root` + <!-- YAML changes: - version: v14.0.0 @@ -409,6 +425,7 @@ The `GLOBAL` and `root` aliases for the `global` property were deprecated in Node.js 6.0.0 and have since been removed. ### DEP0017: `Intl.v8BreakIterator` + <!-- YAML changes: - version: v9.0.0 @@ -425,6 +442,7 @@ Type: End-of-Life See [`Intl.Segmenter`](https://github.com/tc39/proposal-intl-segmenter). ### DEP0018: Unhandled promise rejections + <!-- YAML changes: - version: v15.0.0 @@ -443,6 +461,7 @@ code. To change the way Node.js treats unhandled rejections, use the [`--unhandled-rejections`][] command-line option. ### DEP0019: `require('.')` resolved outside directory + <!-- YAML changes: - version: v12.0.0 @@ -464,6 +483,7 @@ In certain cases, `require('.')` could resolve outside the package directory. This behavior has been removed. ### DEP0020: `Server.connections` + <!-- YAML changes: - version: v15.0.0 @@ -485,6 +505,7 @@ The `Server.connections` property was deprecated in Node.js v0.9.7 and has been removed. Please use the [`Server.getConnections()`][] method instead. ### DEP0021: `Server.listenFD` + <!-- YAML changes: - version: v12.0.0 @@ -506,6 +527,7 @@ The `Server.listenFD()` method was deprecated and removed. Please use [`Server.listen({fd: <number>})`][] instead. ### DEP0022: `os.tmpDir()` + <!-- YAML changes: - version: v14.0.0 @@ -522,6 +544,7 @@ The `os.tmpDir()` API was deprecated in Node.js 7.0.0 and has since been removed. Please use [`os.tmpdir()`][] instead. ### DEP0023: `os.getNetworkInterfaces()` + <!-- YAML changes: - version: v12.0.0 @@ -543,6 +566,7 @@ The `os.getNetworkInterfaces()` method is deprecated. Please use the [`os.networkInterfaces()`][] method instead. ### DEP0024: `REPLServer.prototype.convertToContext()` + <!-- YAML changes: - version: v9.0.0 @@ -558,6 +582,7 @@ Type: End-of-Life The `REPLServer.prototype.convertToContext()` API has been removed. ### DEP0025: `require('sys')` + <!-- YAML changes: - version: @@ -575,6 +600,7 @@ Type: Runtime The `sys` module is deprecated. Please use the [`util`][] module instead. ### DEP0026: `util.print()` + <!-- YAML changes: - version: v12.0.0 @@ -595,6 +621,7 @@ Type: End-of-Life `util.print()` has been removed. Please use [`console.log()`][] instead. ### DEP0027: `util.puts()` + <!-- YAML changes: - version: v12.0.0 @@ -615,6 +642,7 @@ Type: End-of-Life `util.puts()` has been removed. Please use [`console.log()`][] instead. ### DEP0028: `util.debug()` + <!-- YAML changes: - version: v12.0.0 @@ -635,6 +663,7 @@ Type: End-of-Life `util.debug()` has been removed. Please use [`console.error()`][] instead. ### DEP0029: `util.error()` + <!-- YAML changes: - version: v12.0.0 @@ -655,6 +684,7 @@ Type: End-of-Life `util.error()` has been removed. Please use [`console.error()`][] instead. ### DEP0030: `SlowBuffer` + <!-- YAML changes: - version: v6.12.0 @@ -671,6 +701,7 @@ The [`SlowBuffer`][] class is deprecated. Please use [`Buffer.allocUnsafeSlow(size)`][] instead. ### DEP0031: `ecdh.setPublicKey()` + <!-- YAML changes: - version: v6.12.0 @@ -687,6 +718,7 @@ The [`ecdh.setPublicKey()`][] method is now deprecated as its inclusion in the API is not useful. ### DEP0032: `domain` module + <!-- YAML changes: - version: @@ -704,6 +736,7 @@ Type: Documentation-only The [`domain`][] module is deprecated and should not be used. ### DEP0033: `EventEmitter.listenerCount()` + <!-- YAML changes: - version: @@ -722,6 +755,7 @@ The [`events.listenerCount(emitter, eventName)`][] API is deprecated. Please use [`emitter.listenerCount(eventName)`][] instead. ### DEP0034: `fs.exists(path, callback)` + <!-- YAML changes: - version: @@ -740,6 +774,7 @@ The [`fs.exists(path, callback)`][] API is deprecated. Please use [`fs.stat()`][] or [`fs.access()`][] instead. ### DEP0035: `fs.lchmod(path, mode, callback)` + <!-- YAML changes: - version: @@ -756,6 +791,7 @@ Type: Documentation-only The [`fs.lchmod(path, mode, callback)`][] API is deprecated. ### DEP0036: `fs.lchmodSync(path, mode)` + <!-- YAML changes: - version: @@ -772,6 +808,7 @@ Type: Documentation-only The [`fs.lchmodSync(path, mode)`][] API is deprecated. ### DEP0037: `fs.lchown(path, uid, gid, callback)` + <!-- YAML changes: - version: v10.6.0 @@ -793,6 +830,7 @@ deprecation was revoked because the requisite supporting APIs were added in libuv. ### DEP0038: `fs.lchownSync(path, uid, gid)` + <!-- YAML changes: - version: v10.6.0 @@ -813,6 +851,7 @@ The [`fs.lchownSync(path, uid, gid)`][] API was deprecated. The deprecation was revoked because the requisite supporting APIs were added in libuv. ### DEP0039: `require.extensions` + <!-- YAML changes: - version: @@ -830,6 +869,7 @@ Type: Documentation-only The [`require.extensions`][] property is deprecated. ### DEP0040: `punycode` module + <!-- YAML changes: - version: v16.6.0 @@ -846,6 +886,7 @@ The [`punycode`][] module is deprecated. Please use a userland alternative instead. ### DEP0041: `NODE_REPL_HISTORY_FILE` environment variable + <!-- YAML changes: - version: v10.0.0 @@ -867,6 +908,7 @@ The `NODE_REPL_HISTORY_FILE` environment variable was removed. Please use `NODE_REPL_HISTORY` instead. ### DEP0042: `tls.CryptoStream` + <!-- YAML changes: - version: v10.0.0 @@ -888,6 +930,7 @@ The [`tls.CryptoStream`][] class was removed. Please use [`tls.TLSSocket`][] instead. ### DEP0043: `tls.SecurePair` + <!-- YAML changes: - version: v8.0.0 @@ -915,6 +958,7 @@ The [`tls.SecurePair`][] class is deprecated. Please use [`tls.TLSSocket`][] instead. ### DEP0044: `util.isArray()` + <!-- YAML changes: - version: @@ -935,6 +979,7 @@ The [`util.isArray()`][] API is deprecated. Please use `Array.isArray()` instead. ### DEP0045: `util.isBoolean()` + <!-- YAML changes: - version: @@ -954,6 +999,7 @@ Type: Documentation-only The [`util.isBoolean()`][] API is deprecated. ### DEP0046: `util.isBuffer()` + <!-- YAML changes: - version: @@ -974,6 +1020,7 @@ The [`util.isBuffer()`][] API is deprecated. Please use [`Buffer.isBuffer()`][] instead. ### DEP0047: `util.isDate()` + <!-- YAML changes: - version: @@ -993,6 +1040,7 @@ Type: Documentation-only The [`util.isDate()`][] API is deprecated. ### DEP0048: `util.isError()` + <!-- YAML changes: - version: @@ -1012,6 +1060,7 @@ Type: Documentation-only The [`util.isError()`][] API is deprecated. ### DEP0049: `util.isFunction()` + <!-- YAML changes: - version: @@ -1031,6 +1080,7 @@ Type: Documentation-only The [`util.isFunction()`][] API is deprecated. ### DEP0050: `util.isNull()` + <!-- YAML changes: - version: @@ -1050,6 +1100,7 @@ Type: Documentation-only The [`util.isNull()`][] API is deprecated. ### DEP0051: `util.isNullOrUndefined()` + <!-- YAML changes: - version: @@ -1069,6 +1120,7 @@ Type: Documentation-only The [`util.isNullOrUndefined()`][] API is deprecated. ### DEP0052: `util.isNumber()` + <!-- YAML changes: - version: @@ -1088,6 +1140,7 @@ Type: Documentation-only The [`util.isNumber()`][] API is deprecated. ### DEP0053: `util.isObject()` + <!-- YAML changes: - version: @@ -1107,6 +1160,7 @@ Type: Documentation-only The [`util.isObject()`][] API is deprecated. ### DEP0054: `util.isPrimitive()` + <!-- YAML changes: - version: @@ -1126,6 +1180,7 @@ Type: Documentation-only The [`util.isPrimitive()`][] API is deprecated. ### DEP0055: `util.isRegExp()` + <!-- YAML changes: - version: @@ -1145,6 +1200,7 @@ Type: Documentation-only The [`util.isRegExp()`][] API is deprecated. ### DEP0056: `util.isString()` + <!-- YAML changes: - version: @@ -1164,6 +1220,7 @@ Type: Documentation-only The [`util.isString()`][] API is deprecated. ### DEP0057: `util.isSymbol()` + <!-- YAML changes: - version: @@ -1183,6 +1240,7 @@ Type: Documentation-only The [`util.isSymbol()`][] API is deprecated. ### DEP0058: `util.isUndefined()` + <!-- YAML changes: - version: @@ -1202,6 +1260,7 @@ Type: Documentation-only The [`util.isUndefined()`][] API is deprecated. ### DEP0059: `util.log()` + <!-- YAML changes: - version: v6.12.0 @@ -1217,6 +1276,7 @@ Type: Documentation-only The [`util.log()`][] API is deprecated. ### DEP0060: `util._extend()` + <!-- YAML changes: - version: v6.12.0 @@ -1232,6 +1292,7 @@ Type: Documentation-only The [`util._extend()`][] API is deprecated. ### DEP0061: `fs.SyncWriteStream` + <!-- YAML changes: - version: v11.0.0 @@ -1252,6 +1313,7 @@ API and has been removed. No alternative API is available. Please use a userland alternative. ### DEP0062: `node --debug` + <!-- YAML changes: - version: v12.0.0 @@ -1269,6 +1331,7 @@ of V8 5.8. It is replaced by Inspector which is activated with `--inspect` instead. ### DEP0063: `ServerResponse.prototype.writeHeader()` + <!-- YAML changes: - version: v8.0.0 @@ -1285,6 +1348,7 @@ The `ServerResponse.prototype.writeHeader()` method was never documented as an officially supported API. ### DEP0064: `tls.createSecurePair()` + <!-- YAML changes: - version: v8.0.0 @@ -1312,6 +1376,7 @@ The `tls.createSecurePair()` API was deprecated in documentation in Node.js 0.11.3. Users should use `tls.Socket` instead. ### DEP0065: `repl.REPL_MODE_MAGIC` and `NODE_REPL_MODE=magic` + <!-- YAML changes: - version: v10.0.0 @@ -1334,6 +1399,7 @@ The `NODE_REPL_MODE` environment variable is used to set the underlying removed. Please use `sloppy` instead. ### DEP0066: `OutgoingMessage.prototype._headers, OutgoingMessage.prototype._headerNames` + <!-- YAML changes: - version: v12.0.0 @@ -1361,6 +1427,7 @@ The `OutgoingMessage.prototype._headers` and officially supported properties. ### DEP0067: `OutgoingMessage.prototype._renderHeaders` + <!-- YAML changes: - version: v8.0.0 @@ -1377,6 +1444,7 @@ The `OutgoingMessage.prototype._renderHeaders` property was never documented as an officially supported API. ### DEP0068: `node debug` + <!-- YAML changes: - version: v15.0.0 @@ -1393,6 +1461,7 @@ Type: End-of-Life a V8-inspector based CLI debugger available through `node inspect`. ### DEP0069: `vm.runInDebugContext(string)` + <!-- YAML changes: - version: v10.0.0 @@ -1413,6 +1482,7 @@ DebugContext has been removed in V8 and is not available in Node.js 10+. DebugContext was an experimental API. ### DEP0070: `async_hooks.currentId()` + <!-- YAML changes: - version: v9.0.0 @@ -1431,6 +1501,7 @@ clarity. This change was made while `async_hooks` was an experimental API. ### DEP0071: `async_hooks.triggerId()` + <!-- YAML changes: - version: v9.0.0 @@ -1449,6 +1520,7 @@ clarity. This change was made while `async_hooks` was an experimental API. ### DEP0072: `async_hooks.AsyncResource.triggerId()` + <!-- YAML changes: - version: v9.0.0 @@ -1467,6 +1539,7 @@ Type: End-of-Life This change was made while `async_hooks` was an experimental API. ### DEP0073: Several internal properties of `net.Server` + <!-- YAML changes: - version: v10.0.0 @@ -1486,6 +1559,7 @@ As the original API was undocumented and not generally useful for non-internal code, no replacement API is provided. ### DEP0074: `REPLServer.bufferedCommand` + <!-- YAML changes: - version: v15.0.0 @@ -1502,6 +1576,7 @@ The `REPLServer.bufferedCommand` property was deprecated in favor of [`REPLServer.clearBufferedCommand()`][]. ### DEP0075: `REPLServer.parseREPLKeyword()` + <!-- YAML changes: - version: v15.0.0 @@ -1517,6 +1592,7 @@ Type: End-of-Life `REPLServer.parseREPLKeyword()` was removed from userland visibility. ### DEP0076: `tls.parseCertString()` + <!-- YAML changes: - version: v9.0.0 @@ -1548,6 +1624,7 @@ difference is that `querystring.parse()` does url decoding: ``` ### DEP0077: `Module._debug()` + <!-- YAML changes: - version: v9.0.0 @@ -1563,6 +1640,7 @@ The `Module._debug()` function was never documented as an officially supported API. ### DEP0078: `REPLServer.turnOffEditorMode()` + <!-- YAML changes: - version: v15.0.0 @@ -1578,6 +1656,7 @@ Type: End-of-Life `REPLServer.turnOffEditorMode()` was removed from userland visibility. ### DEP0079: Custom inspection function on objects via `.inspect()` + <!-- YAML changes: - version: v11.0.0 @@ -1599,6 +1678,7 @@ instead. For backward compatibility with Node.js prior to version 6.4.0, both can be specified. ### DEP0080: `path._makeLong()` + <!-- YAML changes: - version: v9.0.0 @@ -1613,6 +1693,7 @@ userland modules have found it useful. The internal API is deprecated and replaced with an identical, public `path.toNamespacedPath()` method. ### DEP0081: `fs.truncate()` using a file descriptor + <!-- YAML changes: - version: v9.0.0 @@ -1627,6 +1708,7 @@ deprecated. Please use `fs.ftruncate()` or `fs.ftruncateSync()` to work with file descriptors. ### DEP0082: `REPLServer.prototype.memory()` + <!-- YAML changes: - version: v15.0.0 @@ -1643,6 +1725,7 @@ Type: End-of-Life the `REPLServer` itself. Do not use this function. ### DEP0083: Disabling ECDH by setting `ecdhCurve` to `false` + <!-- YAML changes: - version: v10.0.0 @@ -1661,6 +1744,7 @@ deprecated in preparation for migrating to OpenSSL 1.1.0 and consistency with the client and is now unsupported. Use the `ciphers` parameter instead. ### DEP0084: requiring bundled internal dependencies + <!-- YAML changes: - version: v12.0.0 @@ -1700,6 +1784,7 @@ manager, as it is published on the npm registry under the same name. No source code modification is necessary if that is done. ### DEP0085: AsyncHooks sensitive API + <!-- YAML changes: - version: v10.0.0 @@ -1719,6 +1804,7 @@ Use the `AsyncResource` API instead. See <https://github.com/nodejs/node/issues/15572>. ### DEP0086: Remove `runInAsyncIdScope` + <!-- YAML changes: - version: v10.0.0 @@ -1737,6 +1823,7 @@ Type: End-of-Life cause a lot of issues. See <https://github.com/nodejs/node/issues/14328>. ### DEP0089: `require('assert')` + <!-- YAML changes: - version: v12.8.0 @@ -1756,6 +1843,7 @@ loose equality checks. The deprecation was revoked because use of the `assert` module is not discouraged, and the deprecation caused developer confusion. ### DEP0090: Invalid GCM authentication tag lengths + <!-- YAML changes: - version: v11.0.0 @@ -1775,6 +1863,7 @@ bits are allowed. Authentication tags of other lengths are invalid per [NIST SP 800-38D][]. ### DEP0091: `crypto.DEFAULT_ENCODING` + <!-- YAML changes: - version: v10.0.0 @@ -1787,6 +1876,7 @@ Type: Runtime The [`crypto.DEFAULT_ENCODING`][] property is deprecated. ### DEP0092: Top-level `this` bound to `module.exports` + <!-- YAML changes: - version: v10.0.0 @@ -1801,6 +1891,7 @@ to `module.exports` is deprecated. Developers should use `exports` or `module.exports` instead. ### DEP0093: `crypto.fips` is deprecated and replaced + <!-- YAML changes: - version: v10.0.0 @@ -1814,6 +1905,7 @@ The [`crypto.fips`][] property is deprecated. Please use `crypto.setFips()` and `crypto.getFips()` instead. ### DEP0094: Using `assert.fail()` with more than one argument + <!-- YAML changes: - version: v10.0.0 @@ -1828,6 +1920,7 @@ Using `assert.fail()` with more than one argument is deprecated. Use method. ### DEP0095: `timers.enroll()` + <!-- YAML changes: - version: v10.0.0 @@ -1841,6 +1934,7 @@ Type: Runtime [`setTimeout()`][] or [`setInterval()`][] instead. ### DEP0096: `timers.unenroll()` + <!-- YAML changes: - version: v10.0.0 @@ -1854,6 +1948,7 @@ Type: Runtime [`clearTimeout()`][] or [`clearInterval()`][] instead. ### DEP0097: `MakeCallback` with `domain` property + <!-- YAML changes: - version: v10.0.0 @@ -1868,6 +1963,7 @@ should start using the `async_context` variant of `MakeCallback` or `CallbackScope`, or the high-level `AsyncResource` class. ### DEP0098: AsyncHooks embedder `AsyncResource.emitBefore` and `AsyncResource.emitAfter` APIs + <!-- YAML changes: - version: v12.0.0 @@ -1892,6 +1988,7 @@ safer, and more convenient, alternative. See <https://github.com/nodejs/node/pull/18513>. ### DEP0099: Async context-unaware `node::MakeCallback` C++ APIs + <!-- YAML changes: - version: v10.0.0 @@ -1906,6 +2003,7 @@ deprecated. Please use the versions of the API that accept an `async_context` parameter. ### DEP0100: `process.assert()` + <!-- YAML changes: - version: v10.0.0 @@ -1922,6 +2020,7 @@ Type: Runtime This was never a documented feature. ### DEP0101: `--with-lttng` + <!-- YAML changes: - version: v10.0.0 @@ -1934,6 +2033,7 @@ Type: End-of-Life The `--with-lttng` compile-time option has been removed. ### DEP0102: Using `noAssert` in `Buffer#(read|write)` operations + <!-- YAML changes: - version: v10.0.0 @@ -1948,6 +2048,7 @@ to be verified, no matter if it is set to true or not. Skipping the verification could lead to hard to find errors and crashes. ### DEP0103: `process.binding('util').is[...]` typechecks + <!-- YAML changes: - version: v10.9.0 @@ -1967,6 +2068,7 @@ This deprecation has been superseded by the deprecation of the `process.binding()` API ([DEP0111](#DEP0111)). ### DEP0104: `process.env` string coercion + <!-- YAML changes: - version: v10.0.0 @@ -1983,6 +2085,7 @@ result in a thrown error. Please convert the property to a string before assigning it to `process.env`. ### DEP0105: `decipher.finaltol` + <!-- YAML changes: - version: v11.0.0 @@ -2000,6 +2103,7 @@ Type: End-of-Life [`decipher.final()`][] instead. ### DEP0106: `crypto.createCipher` and `crypto.createDecipher` + <!-- YAML changes: - version: v11.0.0 @@ -2020,6 +2124,7 @@ initialization vectors. It is recommended to derive a key using [`Cipher`][] and [`Decipher`][] objects respectively. ### DEP0107: `tls.convertNPNProtocols()` + <!-- YAML changes: - version: v11.0.0 @@ -2036,6 +2141,7 @@ This was an undocumented helper function not intended for use outside Node.js core and obsoleted by the removal of NPN (Next Protocol Negotiation) support. ### DEP0108: `zlib.bytesRead` + <!-- YAML changes: - version: v11.0.0 @@ -2054,6 +2160,7 @@ read by the engine, but is inconsistent with other streams in Node.js that expose values under these names. ### DEP0109: `http`, `https`, and `tls` support for invalid URLs + <!-- YAML changes: - version: v16.0.0 @@ -2074,6 +2181,7 @@ URL parser that requires strictly valid URLs. Passing an invalid URL is deprecated and support will be removed in the future. ### DEP0110: `vm.Script` cached data + <!-- YAML changes: - version: v10.6.0 @@ -2087,6 +2195,7 @@ The `produceCachedData` option is deprecated. Use [`script.createCachedData()`][] instead. ### DEP0111: `process.binding()` + <!-- YAML changes: - version: v11.12.0 @@ -2102,6 +2211,7 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) `process.binding()` is for use by Node.js internal code only. ### DEP0112: `dgram` private APIs + <!-- YAML changes: - version: v11.0.0 @@ -2119,6 +2229,7 @@ accessed outside of Node.js core: `Socket.prototype._handle`, `dgram._createSocketHandle()`. ### DEP0113: `Cipher.setAuthTag()`, `Decipher.getAuthTag()` + <!-- YAML changes: - version: v12.0.0 @@ -2135,6 +2246,7 @@ Type: End-of-Life were never documented and would throw when called. ### DEP0114: `crypto._toBuf()` + <!-- YAML changes: - version: v12.0.0 @@ -2175,6 +2287,7 @@ deprecated along with the undocumented aliases `crypto.prng()` and future release. ### DEP0116: Legacy URL API + <!-- YAML changes: - version: @@ -2194,6 +2307,7 @@ The [Legacy URL API][] is deprecated. This includes [`url.format()`][], use the [WHATWG URL API][] instead. ### DEP0117: Native crypto handles + <!-- YAML changes: - version: v12.0.0 @@ -2213,6 +2327,7 @@ The `_handle` property has been removed because improper use of the native object can lead to crashing the application. ### DEP0118: `dns.lookup()` support for a falsy host name + <!-- YAML changes: - version: v11.0.0 @@ -2228,6 +2343,7 @@ This behavior is undocumented and is thought to be unused in real world apps. It will become an error in future versions of Node.js. ### DEP0119: `process.binding('uv').errname()` private API + <!-- YAML changes: - version: v11.0.0 @@ -2241,6 +2357,7 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) [`util.getSystemErrorName()`][] instead. ### DEP0120: Windows Performance Counter support + <!-- YAML changes: - version: v12.0.0 @@ -2260,6 +2377,7 @@ undocumented `COUNTER_NET_SERVER_CONNECTION()`, `COUNTER_HTTP_CLIENT_RESPONSE()` functions have been deprecated. ### DEP0121: `net._setSimultaneousAccepts()` + <!-- YAML changes: - version: v12.0.0 @@ -2276,6 +2394,7 @@ is being removed. See discussion here: <https://github.com/nodejs/node/issues/18391> ### DEP0122: `tls` `Server.prototype.setOptions()` + <!-- YAML changes: - version: v12.0.0 @@ -2288,6 +2407,7 @@ Type: Runtime Please use `Server.prototype.setSecureContext()` instead. ### DEP0123: setting the TLS ServerName to an IP address + <!-- YAML changes: - version: v12.0.0 @@ -2301,6 +2421,7 @@ Setting the TLS ServerName to an IP address is not permitted by [RFC 6066][]. This will be ignored in a future version. ### DEP0124: using `REPLServer.rli` + <!-- YAML changes: - version: v15.0.0 @@ -2316,6 +2437,7 @@ Type: End-of-Life This property is a reference to the instance itself. ### DEP0125: `require('_stream_wrap')` + <!-- YAML changes: - version: v12.0.0 @@ -2328,6 +2450,7 @@ Type: Runtime The `_stream_wrap` module is deprecated. ### DEP0126: `timers.active()` + <!-- YAML changes: - version: v11.14.0 @@ -2343,6 +2466,7 @@ If re-referencing the timeout is necessary, [`timeout.ref()`][] can be used with no performance impact since Node.js 10. ### DEP0127: `timers._unrefActive()` + <!-- YAML changes: - version: v11.14.0 @@ -2358,6 +2482,7 @@ If unreferencing the timeout is necessary, [`timeout.unref()`][] can be used with no performance impact since Node.js 10. ### DEP0128: modules with an invalid `main` entry and an `index.js` file + <!-- YAML changes: - version: v16.0.0 @@ -2376,6 +2501,7 @@ also have an `index.js` file in the top level directory will resolve the Node.js versions. ### DEP0129: `ChildProcess._channel` + <!-- YAML changes: - version: v13.0.0 @@ -2393,6 +2519,7 @@ similar functions is not intended for public use. Use `ChildProcess.channel` instead. ### DEP0130: `Module.createRequireFromPath()` + <!-- YAML changes: - version: v16.0.0 @@ -2411,6 +2538,7 @@ Type: End-of-Life Use [`module.createRequire()`][] instead. ### DEP0131: Legacy HTTP parser + <!-- YAML changes: - version: v13.0.0 @@ -2432,6 +2560,7 @@ is deprecated and has been removed in v13.0.0. Prior to v13.0.0, the legacy parser. ### DEP0132: `worker.terminate()` with callback + <!-- YAML changes: - version: v12.5.0 @@ -2445,6 +2574,7 @@ Passing a callback to [`worker.terminate()`][] is deprecated. Use the returned `Promise` instead, or a listener to the worker’s `'exit'` event. ### DEP0133: `http` `connection` + <!-- YAML changes: - version: v12.12.0 @@ -2458,18 +2588,21 @@ Prefer [`response.socket`][] over [`response.connection`][] and [`request.socket`][] over [`request.connection`][]. ### DEP0134: `process._tickCallback` + <!-- YAML changes: - version: v12.12.0 pr-url: https://github.com/nodejs/node/pull/29781 description: Documentation-only deprecation. --> + Type: Documentation-only (supports [`--pending-deprecation`][]) The `process._tickCallback` property was never documented as an officially supported API. ### DEP0135: `WriteStream.open()` and `ReadStream.open()` are internal + <!-- YAML changes: - version: v13.0.0 @@ -2485,6 +2618,7 @@ opened through their corresponding factory methods [`fs.createWriteStream()`][] and [`fs.createReadStream()`][]) or by passing a file descriptor in options. ### DEP0136: `http` `finished` + <!-- YAML changes: - version: @@ -2507,6 +2641,7 @@ To maintain existing behavior `response.finished` should be replaced with `response.writableEnded`. ### DEP0137: Closing fs.FileHandle on garbage collection + <!-- YAML changes: - version: v14.0.0 @@ -2537,6 +2672,7 @@ async function openAndClose() { ``` ### DEP0138: `process.mainModule` + <!-- YAML changes: - version: v14.0.0 @@ -2554,6 +2690,7 @@ It is deprecated in favor of [`require.main`][], because it serves the same purpose and is only available on CommonJS environment. ### DEP0139: `process.umask()` with no arguments + <!-- YAML changes: - version: @@ -2571,6 +2708,7 @@ potential security vulnerability. There is no safe, cross-platform alternative API. ### DEP0140: Use `request.destroy()` instead of `request.abort()` + <!-- YAML changes: - version: @@ -2585,6 +2723,7 @@ Type: Documentation-only Use [`request.destroy()`][] instead of [`request.abort()`][]. ### DEP0141: `repl.inputStream` and `repl.outputStream` + <!-- YAML changes: - version: v14.3.0 @@ -2598,6 +2737,7 @@ The `repl` module exported the input and output stream twice. Use `.input` instead of `.inputStream` and `.output` instead of `.outputStream`. ### DEP0142: `repl._builtinLibs` + <!-- YAML changes: - version: v14.3.0 @@ -2612,17 +2752,20 @@ native modules. It was incomplete so far and instead it's better to rely upon `require('module').builtinModules`. ### DEP0143: `Transform._transformState` + <!-- YAML changes: - version: v14.5.0 pr-url: https://github.com/nodejs/node/pull/33126 description: Runtime deprecation. --> + Type: Runtime `Transform._transformState` will be removed in future versions where it is no longer required due to simplification of the implementation. ### DEP0144: `module.parent` + <!-- YAML changes: - version: @@ -2657,6 +2800,7 @@ const moduleParents = Object.values(require.cache) ``` ### DEP0145: `socket.bufferSize` + <!-- YAML changes: - version: v14.6.0 @@ -2669,6 +2813,7 @@ Type: Documentation-only [`socket.bufferSize`][] is just an alias for [`writable.writableLength`][]. ### DEP0146: `new crypto.Certificate()` + <!-- YAML changes: - version: v14.9.0 @@ -2682,6 +2827,7 @@ The [`crypto.Certificate()` constructor][] is deprecated. Use [static methods of `crypto.Certificate()`][] instead. ### DEP0147: `fs.rmdir(path, { recursive: true })` + <!-- YAML changes: - version: v16.0.0 @@ -2705,6 +2851,7 @@ Use `fs.rm(path, { recursive: true, force: true })`, `fs.promises.rm(path, { recursive: true, force: true })` instead. ### DEP0148: Folder mappings in `"exports"` (trailing `"/"`) + <!-- YAML changes: - version: v17.0.0 @@ -2728,6 +2875,7 @@ Using a trailing `"/"` to define subpath folder mappings in the [subpath patterns][] instead. ### DEP0149: `http.IncomingMessage#connection` + <!-- YAML changes: - version: v16.0.0 @@ -2740,6 +2888,7 @@ Type: Documentation-only. Prefer [`message.socket`][] over [`message.connection`][]. ### DEP0150: Changing the value of `process.config` + <!-- YAML changes: - version: v16.0.0 @@ -2755,6 +2904,7 @@ been mutable by user code making it impossible to rely on. The ability to change the value has been deprecated and will be disabled in the future. ### DEP0151: Main index lookup and extension searching + <!-- YAML changes: - version: v16.0.0 @@ -2777,6 +2927,7 @@ With this deprecation, all ES module main entry point resolutions require an explicit [`"exports"` or `"main"` entry][] with the exact file extension. ### DEP0152: Extension PerformanceEntry properties + <!-- YAML changes: - version: v16.0.0 @@ -2793,6 +2944,7 @@ of the `PerformanceEntry` object. The existing accessors have been deprecated and should no longer be used. ### DEP0153: `dns.lookup` and `dnsPromises.lookup` options type coercion + <!-- YAML changes: - version: v17.0.0 @@ -2811,6 +2963,7 @@ option, or a non-nullish non-boolean value for `verbatim` option in [`dns.lookup()`][] and [`dnsPromises.lookup()`][] is deprecated. ### DEP0154: RSA-PSS generate key pair options + <!-- YAML changes: - version: v16.10.0 @@ -2824,6 +2977,7 @@ The `'hash'` and `'mgf1Hash'` options are replaced with `'hashAlgorithm'` and `'mgf1HashAlgorithm'`. ### DEP0155: Trailing slashes in pattern specifier resolutions + <!-- YAML changes: - version: v17.0.0 @@ -2841,6 +2995,7 @@ The remapping of specifiers ending in `"/"` like `import 'pkg/x/'` is deprecated for package `"exports"` and `"imports"` pattern resolutions. ### DEP0156: `.aborted` property and `'abort'`, `'aborted'` event in `http` + <!-- YAML changes: - version: v17.0.0 diff --git a/doc/api/dgram.md b/doc/api/dgram.md index d23249afd95..27efdfb186b 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -56,6 +56,7 @@ server.bind(41234); ``` ## Class: `dgram.Socket` + <!-- YAML added: v0.1.99 --> @@ -68,6 +69,7 @@ New instances of `dgram.Socket` are created using [`dgram.createSocket()`][]. The `new` keyword is not to be used to create `dgram.Socket` instances. ### Event: `'close'` + <!-- YAML added: v0.1.99 --> @@ -76,6 +78,7 @@ The `'close'` event is emitted after a socket is closed with [`close()`][]. Once triggered, no new `'message'` events will be emitted on this socket. ### Event: `'connect'` + <!-- YAML added: v12.0.0 --> @@ -84,6 +87,7 @@ The `'connect'` event is emitted after a socket is associated to a remote address as a result of a successful [`connect()`][] call. ### Event: `'error'` + <!-- YAML added: v0.1.99 --> @@ -94,6 +98,7 @@ The `'error'` event is emitted whenever any error occurs. The event handler function is passed a single `Error` object. ### Event: `'listening'` + <!-- YAML added: v0.1.99 --> @@ -105,6 +110,7 @@ Until the `dgram.Socket` is listening, the underlying system resources do not exist and calls such as `socket.address()` and `socket.setTTL()` will fail. ### Event: `'message'` + <!-- YAML added: v0.1.99 --> @@ -126,6 +132,7 @@ address field set to `'fe80::2618:1234:ab11:3b9c%en0'`, where `'%en0'` is the interface name as a zone ID suffix. ### `socket.addMembership(multicastAddress[, multicastInterface])` + <!-- YAML added: v0.6.9 --> @@ -177,11 +184,13 @@ if (cluster.isPrimary) { ``` ### `socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])` + <!-- YAML added: - v13.1.0 - v12.16.0 --> + * `sourceAddress` {string} * `groupAddress` {string} * `multicastInterface` {string} @@ -197,6 +206,7 @@ When called on an unbound socket, this method will implicitly bind to a random port, listening on all interfaces. ### `socket.address()` + <!-- YAML added: v0.1.99 --> @@ -210,6 +220,7 @@ properties. This method throws `EBADF` if called on an unbound socket. ### `socket.bind([port][, address][, callback])` + <!-- YAML added: v0.1.99 changes: @@ -290,6 +301,7 @@ server.bind(41234); ``` ### `socket.bind(options[, callback])` + <!-- YAML added: v0.11.14 --> @@ -343,6 +355,7 @@ socket.bind({ ``` ### `socket.close([callback])` + <!-- YAML added: v0.1.99 --> @@ -353,6 +366,7 @@ Close the underlying socket and stop listening for data on it. If a callback is provided, it is added as a listener for the [`'close'`][] event. ### `socket.connect(port[, address][, callback])` + <!-- YAML added: v12.0.0 --> @@ -372,6 +386,7 @@ is emitted and the optional `callback` function is called. In case of failure, the `callback` is called or, failing this, an `'error'` event is emitted. ### `socket.disconnect()` + <!-- YAML added: v12.0.0 --> @@ -382,6 +397,7 @@ disconnected socket will result in an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception. ### `socket.dropMembership(multicastAddress[, multicastInterface])` + <!-- YAML added: v0.6.9 --> @@ -398,6 +414,7 @@ If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. ### `socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])` + <!-- YAML added: - v13.1.0 @@ -418,6 +435,7 @@ If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. ### `socket.getRecvBufferSize()` + <!-- YAML added: v8.7.0 --> @@ -427,6 +445,7 @@ added: v8.7.0 This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket. ### `socket.getSendBufferSize()` + <!-- YAML added: v8.7.0 --> @@ -436,6 +455,7 @@ added: v8.7.0 This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket. ### `socket.ref()` + <!-- YAML added: v0.9.1 --> @@ -454,6 +474,7 @@ The `socket.ref()` method returns a reference to the socket so calls can be chained. ### `socket.remoteAddress()` + <!-- YAML added: v12.0.0 --> @@ -465,6 +486,7 @@ endpoint. This method throws an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception if the socket is not connected. ### `socket.send(msg[, offset, length][, port][, address][, callback])` + <!-- YAML added: v0.1.99 changes: @@ -538,7 +560,7 @@ The only way to know for sure that the datagram has been sent is by using a passed as the first argument to the `callback`. If a `callback` is not given, the error is emitted as an `'error'` event on the `socket` object. -Offset and length are optional but both *must* be set if either are used. +Offset and length are optional but both _must_ be set if either are used. They are supported only when the first argument is a `Buffer`, a `TypedArray`, or a `DataView`. @@ -657,6 +679,7 @@ not work because the packet will get silently dropped without informing the source that the data did not reach its intended recipient. ### `socket.setBroadcast(flag)` + <!-- YAML added: v0.6.9 --> @@ -669,16 +692,17 @@ packets may be sent to a local interface's broadcast address. This method throws `EBADF` if called on an unbound socket. ### `socket.setMulticastInterface(multicastInterface)` + <!-- YAML added: v8.6.0 --> * `multicastInterface` {string} -*All references to scope in this section are referring to +_All references to scope in this section are referring to [IPv6 Zone Indices][], which are defined by [RFC 4007][]. In string form, an IP with a scope index is written as `'IP%scope'` where scope is an interface name -or interface number.* +or interface number._ Sets the default outgoing multicast interface of the socket to a chosen interface or back to system interface selection. The `multicastInterface` must @@ -719,6 +743,7 @@ socket.bind(1234, () => { ``` #### Example: IPv4 outgoing multicast interface + All systems use an IP of the host on the desired physical interface: ```js @@ -731,10 +756,10 @@ socket.bind(1234, () => { #### Call results -A call on a socket that is not ready to send or no longer open may throw a *Not -running* [`Error`][]. +A call on a socket that is not ready to send or no longer open may throw a _Not +running_ [`Error`][]. -If `multicastInterface` can not be parsed into an IP then an *EINVAL* +If `multicastInterface` can not be parsed into an IP then an _EINVAL_ [`System Error`][] is thrown. On IPv4, if `multicastInterface` is a valid address but does not match any @@ -749,6 +774,7 @@ used to return control of the sockets default outgoing interface to the system for future multicast packets. ### `socket.setMulticastLoopback(flag)` + <!-- YAML added: v0.3.8 --> @@ -761,6 +787,7 @@ multicast packets will also be received on the local interface. This method throws `EBADF` if called on an unbound socket. ### `socket.setMulticastTTL(ttl)` + <!-- YAML added: v0.3.8 --> @@ -778,6 +805,7 @@ The `ttl` argument may be between 0 and 255. The default on most systems is `1`. This method throws `EBADF` if called on an unbound socket. ### `socket.setRecvBufferSize(size)` + <!-- YAML added: v8.7.0 --> @@ -790,6 +818,7 @@ in bytes. This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket. ### `socket.setSendBufferSize(size)` + <!-- YAML added: v8.7.0 --> @@ -802,6 +831,7 @@ in bytes. This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket. ### `socket.setTTL(ttl)` + <!-- YAML added: v0.1.101 --> @@ -820,6 +850,7 @@ is 64. This method throws `EBADF` if called on an unbound socket. ### `socket.unref()` + <!-- YAML added: v0.9.1 --> @@ -840,6 +871,7 @@ chained. ## `dgram` module functions ### `dgram.createSocket(options[, callback])` + <!-- YAML added: v0.11.13 changes: @@ -897,6 +929,7 @@ controller.abort(); ``` ### `dgram.createSocket(type[, callback])` + <!-- YAML added: v0.1.99 --> diff --git a/doc/api/dns.md b/doc/api/dns.md index b5bcff0820e..63d0fbba9ab 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -52,6 +52,7 @@ dns.resolve4('archive.org', (err, addresses) => { See the [Implementation considerations section][] for more information. ## Class: `dns.Resolver` + <!-- YAML added: v8.3.0 --> @@ -94,6 +95,7 @@ The following methods from the `dns` module are available: * [`resolver.setServers()`][`dns.setServers()`] ### `Resolver([options])` + <!-- YAML added: v8.3.0 changes: @@ -117,6 +119,7 @@ Create a new resolver. each name server before giving up. **Default:** `4` ### `resolver.cancel()` + <!-- YAML added: v8.3.0 --> @@ -125,6 +128,7 @@ Cancel all outstanding DNS queries made by this resolver. The corresponding callbacks will be called with an error with code `ECANCELLED`. ### `resolver.setLocalAddress([ipv4][, ipv6])` + <!-- YAML added: - v15.1.0 @@ -148,17 +152,19 @@ servers, and the v6 local address when making requests to IPv6 DNS servers. The `rrtype` of resolution requests has no impact on the local address used. ## `dns.getServers()` + <!-- YAML added: v0.11.3 --> -* Returns: {string[]} +* Returns: {string\[]} Returns an array of IP address strings, formatted according to [RFC 5952][], that are currently configured for DNS resolution. A string will include a port section if a custom port is used. <!-- eslint-disable semi--> + ```js [ '4.4.4.4', @@ -169,6 +175,7 @@ section if a custom port is used. ``` ## `dns.lookup(hostname[, options], callback)` + <!-- YAML added: v0.1.90 changes: @@ -250,6 +257,7 @@ is not set to `true`, it returns a `Promise` for an `Object` with `address` and `family` properties. ### Supported getaddrinfo flags + <!-- YAML changes: - version: @@ -271,6 +279,7 @@ The following flags can be passed as hints to [`dns.lookup()`][]. well as IPv4 mapped IPv6 addresses. ## `dns.lookupService(address, port, callback)` + <!-- YAML added: v0.11.14 --> @@ -303,6 +312,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a `Promise` for an `Object` with `hostname` and `service` properties. ## `dns.resolve(hostname[, rrtype], callback)` + <!-- YAML added: v0.1.27 --> @@ -311,15 +321,15 @@ added: v0.1.27 * `rrtype` {string} Resource record type. **Default:** `'A'`. * `callback` {Function} * `err` {Error} - * `records` {string[] | Object[] | Object} + * `records` {string\[] | Object\[] | Object} Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array of the resource records. The `callback` function has arguments `(err, records)`. When successful, `records` will be an array of resource records. The type and structure of individual results varies based on `rrtype`: -| `rrtype` | `records` contains | Result type | Shorthand method | -|-----------|--------------------------------|-------------|--------------------------| +| `rrtype` | `records` contains | Result type | Shorthand method | +| --------- | ------------------------------ | ----------- | ------------------------ | | `'A'` | IPv4 addresses (default) | {string} | [`dns.resolve4()`][] | | `'AAAA'` | IPv6 addresses | {string} | [`dns.resolve6()`][] | | `'ANY'` | any records | {Object} | [`dns.resolveAny()`][] | @@ -331,12 +341,13 @@ records. The type and structure of individual results varies based on `rrtype`: | `'PTR'` | pointer records | {string} | [`dns.resolvePtr()`][] | | `'SOA'` | start of authority records | {Object} | [`dns.resolveSoa()`][] | | `'SRV'` | service records | {Object} | [`dns.resolveSrv()`][] | -| `'TXT'` | text records | {string[]} | [`dns.resolveTxt()`][] | +| `'TXT'` | text records | {string\[]} | [`dns.resolveTxt()`][] | On error, `err` is an [`Error`][] object, where `err.code` is one of the [DNS error codes](). ## `dns.resolve4(hostname[, options], callback)` + <!-- YAML added: v0.1.16 changes: @@ -354,7 +365,7 @@ changes: with the TTL expressed in seconds. * `callback` {Function} * `err` {Error} - * `addresses` {string[] | Object[]} + * `addresses` {string\[] | Object\[]} Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the `hostname`. The `addresses` argument passed to the `callback` function @@ -362,6 +373,7 @@ will contain an array of IPv4 addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). ## `dns.resolve6(hostname[, options], callback)` + <!-- YAML added: v0.1.16 changes: @@ -379,7 +391,7 @@ changes: strings, with the TTL expressed in seconds. * `callback` {Function} * `err` {Error} - * `addresses` {string[] | Object[]} + * `addresses` {string\[] | Object\[]} Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the `hostname`. The `addresses` argument passed to the `callback` function @@ -390,7 +402,7 @@ will contain an array of IPv6 addresses. * `hostname` {string} * `callback` {Function} * `err` {Error} - * `ret` {Object[]} + * `ret` {Object\[]} Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query). The `ret` argument passed to the `callback` function will be an array containing @@ -398,22 +410,23 @@ various types of records. Each object has a property `type` that indicates the type of the current record. And depending on the `type`, additional properties will be present on the object: -| Type | Properties | -|------|------------| -| `'A'` | `address`/`ttl` | -| `'AAAA'` | `address`/`ttl` | -| `'CNAME'` | `value` | -| `'MX'` | Refer to [`dns.resolveMx()`][] | -| `'NAPTR'` | Refer to [`dns.resolveNaptr()`][] | -| `'NS'` | `value` | -| `'PTR'` | `value` | -| `'SOA'` | Refer to [`dns.resolveSoa()`][] | -| `'SRV'` | Refer to [`dns.resolveSrv()`][] | -| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dns.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | +| Type | Properties | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `'A'` | `address`/`ttl` | +| `'AAAA'` | `address`/`ttl` | +| `'CNAME'` | `value` | +| `'MX'` | Refer to [`dns.resolveMx()`][] | +| `'NAPTR'` | Refer to [`dns.resolveNaptr()`][] | +| `'NS'` | `value` | +| `'PTR'` | `value` | +| `'SOA'` | Refer to [`dns.resolveSoa()`][] | +| `'SRV'` | Refer to [`dns.resolveSrv()`][] | +| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dns.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | Here is an example of the `ret` object passed to the callback: <!-- eslint-disable semi --> + ```js [ { type: 'A', address: '127.0.0.1', ttl: 299 }, { type: 'CNAME', value: 'example.com' }, @@ -435,6 +448,7 @@ queries. It may be better to call individual methods like [`dns.resolve4()`][], [`dns.resolveMx()`][], and so on. For more details, see [RFC 8482][]. ## `dns.resolveCname(hostname, callback)` + <!-- YAML added: v0.3.2 --> @@ -442,7 +456,7 @@ added: v0.3.2 * `hostname` {string} * `callback` {Function} * `err` {Error} - * `addresses` {string[]} + * `addresses` {string\[]} Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The `addresses` argument passed to the `callback` function @@ -450,6 +464,7 @@ will contain an array of canonical name records available for the `hostname` (e.g. `['bar.example.com']`). ## `dns.resolveCaa(hostname, callback)` + <!-- YAML added: - v15.0.0 @@ -459,7 +474,7 @@ added: * `hostname` {string} * `callback` {Function} * `err` {Error} - * `records` {Object[]} + * `records` {Object\[]} Uses the DNS protocol to resolve `CAA` records for the `hostname`. The `addresses` argument passed to the `callback` function @@ -468,6 +483,7 @@ available for the `hostname` (e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]`). ## `dns.resolveMx(hostname, callback)` + <!-- YAML added: v0.1.27 --> @@ -475,7 +491,7 @@ added: v0.1.27 * `hostname` {string} * `callback` {Function} * `err` {Error} - * `addresses` {Object[]} + * `addresses` {Object\[]} Uses the DNS protocol to resolve mail exchange records (`MX` records) for the `hostname`. The `addresses` argument passed to the `callback` function will @@ -483,6 +499,7 @@ contain an array of objects containing both a `priority` and `exchange` property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). ## `dns.resolveNaptr(hostname, callback)` + <!-- YAML added: v0.9.12 --> @@ -490,7 +507,7 @@ added: v0.9.12 * `hostname` {string} * `callback` {Function} * `err` {Error} - * `addresses` {Object[]} + * `addresses` {Object\[]} Uses the DNS protocol to resolve regular expression based records (`NAPTR` records) for the `hostname`. The `addresses` argument passed to the `callback` @@ -504,6 +521,7 @@ function will contain an array of objects with the following properties: * `preference` <!-- eslint-skip --> + ```js { flags: 's', @@ -516,6 +534,7 @@ function will contain an array of objects with the following properties: ``` ## `dns.resolveNs(hostname, callback)` + <!-- YAML added: v0.1.90 --> @@ -523,7 +542,7 @@ added: v0.1.90 * `hostname` {string} * `callback` {Function} * `err` {Error} - * `addresses` {string[]} + * `addresses` {string\[]} Uses the DNS protocol to resolve name server records (`NS` records) for the `hostname`. The `addresses` argument passed to the `callback` function will @@ -531,6 +550,7 @@ contain an array of name server records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`). ## `dns.resolvePtr(hostname, callback)` + <!-- YAML added: v6.0.0 --> @@ -538,13 +558,14 @@ added: v6.0.0 * `hostname` {string} * `callback` {Function} * `err` {Error} - * `addresses` {string[]} + * `addresses` {string\[]} Uses the DNS protocol to resolve pointer records (`PTR` records) for the `hostname`. The `addresses` argument passed to the `callback` function will be an array of strings containing the reply records. ## `dns.resolveSoa(hostname, callback)` + <!-- YAML added: v0.11.10 --> @@ -567,6 +588,7 @@ be an object with the following properties: * `minttl` <!-- eslint-skip --> + ```js { nsname: 'ns.example.com', @@ -580,6 +602,7 @@ be an object with the following properties: ``` ## `dns.resolveSrv(hostname, callback)` + <!-- YAML added: v0.1.27 --> @@ -587,7 +610,7 @@ added: v0.1.27 * `hostname` {string} * `callback` {Function} * `err` {Error} - * `addresses` {Object[]} + * `addresses` {Object\[]} Uses the DNS protocol to resolve service records (`SRV` records) for the `hostname`. The `addresses` argument passed to the `callback` function will @@ -599,6 +622,7 @@ be an array of objects with the following properties: * `name` <!-- eslint-skip --> + ```js { priority: 10, @@ -609,15 +633,18 @@ be an array of objects with the following properties: ``` ## `dns.resolveTxt(hostname, callback)` + <!-- YAML added: v0.1.27 --> <!--lint disable no-undefined-references list-item-bullet-indent--> + * `hostname` {string} * `callback` {Function} * `err` {Error} - * `records` <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[][]></a> + * `records` <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">\<string\[]\[]></a> + <!--lint enable no-undefined-references list-item-bullet-indent--> Uses the DNS protocol to resolve text queries (`TXT` records) for the @@ -628,6 +655,7 @@ one record. Depending on the use case, these could be either joined together or treated separately. ## `dns.reverse(ip, callback)` + <!-- YAML added: v0.1.16 --> @@ -635,7 +663,7 @@ added: v0.1.16 * `ip` {string} * `callback` {Function} * `err` {Error} - * `hostnames` {string[]} + * `hostnames` {string\[]} Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an array of host names. @@ -644,6 +672,7 @@ On error, `err` is an [`Error`][] object, where `err.code` is one of the [DNS error codes][]. ## `dns.setDefaultResultOrder(order)` + <!-- YAML added: - v16.4.0 @@ -654,6 +683,7 @@ added: Set the default value of `verbatim` in [`dns.lookup()`][] and [`dnsPromises.lookup()`][]. The value could be: + * `ipv4first`: sets default `verbatim` `false`. * `verbatim`: sets default `verbatim` `true`. @@ -663,11 +693,12 @@ priority than [`--dns-result-order`][]. When using [worker threads][], dns orders in workers. ## `dns.setServers(servers)` + <!-- YAML added: v0.11.3 --> -* `servers` {string[]} array of [RFC 5952][] formatted addresses +* `servers` {string\[]} array of [RFC 5952][] formatted addresses Sets the IP address and port of servers to be used when performing DNS resolution. The `servers` argument is an array of [RFC 5952][] formatted @@ -688,17 +719,18 @@ The `dns.setServers()` method must not be called while a DNS query is in progress. The [`dns.setServers()`][] method affects only [`dns.resolve()`][], -`dns.resolve*()` and [`dns.reverse()`][] (and specifically *not* +`dns.resolve*()` and [`dns.reverse()`][] (and specifically _not_ [`dns.lookup()`][]). This method works much like [resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html). That is, if attempting to resolve with the first server provided results in a -`NOTFOUND` error, the `resolve()` method will *not* attempt to resolve with +`NOTFOUND` error, the `resolve()` method will _not_ attempt to resolve with subsequent servers provided. Fallback DNS servers will only be used if the earlier ones time out or result in some other error. ## DNS promises API + <!-- YAML added: v10.6.0 changes: @@ -717,6 +749,7 @@ that return `Promise` objects rather than using callbacks. The API is accessible via `require('dns').promises` or `require('dns/promises')`. ### Class: `dnsPromises.Resolver` + <!-- YAML added: v10.6.0 --> @@ -764,6 +797,7 @@ The following methods from the `dnsPromises` API are available: * [`resolver.setServers()`][`dnsPromises.setServers()`] ### `resolver.cancel()` + <!-- YAML added: - v15.3.0 @@ -774,17 +808,19 @@ Cancel all outstanding DNS queries made by this resolver. The corresponding promises will be rejected with an error with code `ECANCELLED`. ### `dnsPromises.getServers()` + <!-- YAML added: v10.6.0 --> -* Returns: {string[]} +* Returns: {string\[]} Returns an array of IP address strings, formatted according to [RFC 5952][], that are currently configured for DNS resolution. A string will include a port section if a custom port is used. <!-- eslint-disable semi--> + ```js [ '4.4.4.4', @@ -795,6 +831,7 @@ section if a custom port is used. ``` ### `dnsPromises.lookup(hostname[, options])` + <!-- YAML added: v10.6.0 --> @@ -861,6 +898,7 @@ dnsPromises.lookup('example.com', options).then((result) => { ``` ### `dnsPromises.lookupService(address, port)` + <!-- YAML added: v10.6.0 --> @@ -887,6 +925,7 @@ dnsPromises.lookupService('127.0.0.1', 22).then((result) => { ``` ### `dnsPromises.resolve(hostname[, rrtype])` + <!-- YAML added: v10.6.0 --> @@ -899,12 +938,12 @@ of the resource records. When successful, the `Promise` is resolved with an array of resource records. The type and structure of individual results vary based on `rrtype`: -| `rrtype` | `records` contains | Result type | Shorthand method | -|-----------|--------------------------------|-------------|--------------------------| +| `rrtype` | `records` contains | Result type | Shorthand method | +| --------- | ------------------------------ | ----------- | -------------------------------- | | `'A'` | IPv4 addresses (default) | {string} | [`dnsPromises.resolve4()`][] | | `'AAAA'` | IPv6 addresses | {string} | [`dnsPromises.resolve6()`][] | | `'ANY'` | any records | {Object} | [`dnsPromises.resolveAny()`][] | -| `'CAA'` | CA authorization records | {Object} | [`dnsPromises.resolveCaa()`][] | +| `'CAA'` | CA authorization records | {Object} | [`dnsPromises.resolveCaa()`][] | | `'CNAME'` | canonical name records | {string} | [`dnsPromises.resolveCname()`][] | | `'MX'` | mail exchange records | {Object} | [`dnsPromises.resolveMx()`][] | | `'NAPTR'` | name authority pointer records | {Object} | [`dnsPromises.resolveNaptr()`][] | @@ -912,12 +951,13 @@ based on `rrtype`: | `'PTR'` | pointer records | {string} | [`dnsPromises.resolvePtr()`][] | | `'SOA'` | start of authority records | {Object} | [`dnsPromises.resolveSoa()`][] | | `'SRV'` | service records | {Object} | [`dnsPromises.resolveSrv()`][] | -| `'TXT'` | text records | {string[]} | [`dnsPromises.resolveTxt()`][] | +| `'TXT'` | text records | {string\[]} | [`dnsPromises.resolveTxt()`][] | On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` is one of the [DNS error codes](). ### `dnsPromises.resolve4(hostname[, options])` + <!-- YAML added: v10.6.0 --> @@ -934,6 +974,7 @@ Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). ### `dnsPromises.resolve6(hostname[, options])` + <!-- YAML added: v10.6.0 --> @@ -950,6 +991,7 @@ Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the addresses. ### `dnsPromises.resolveAny(hostname)` + <!-- YAML added: v10.6.0 --> @@ -962,22 +1004,23 @@ records. Each object has a property `type` that indicates the type of the current record. And depending on the `type`, additional properties will be present on the object: -| Type | Properties | -|------|------------| -| `'A'` | `address`/`ttl` | -| `'AAAA'` | `address`/`ttl` | -| `'CNAME'` | `value` | -| `'MX'` | Refer to [`dnsPromises.resolveMx()`][] | -| `'NAPTR'` | Refer to [`dnsPromises.resolveNaptr()`][] | -| `'NS'` | `value` | -| `'PTR'` | `value` | -| `'SOA'` | Refer to [`dnsPromises.resolveSoa()`][] | -| `'SRV'` | Refer to [`dnsPromises.resolveSrv()`][] | -| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dnsPromises.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | +| Type | Properties | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `'A'` | `address`/`ttl` | +| `'AAAA'` | `address`/`ttl` | +| `'CNAME'` | `value` | +| `'MX'` | Refer to [`dnsPromises.resolveMx()`][] | +| `'NAPTR'` | Refer to [`dnsPromises.resolveNaptr()`][] | +| `'NS'` | `value` | +| `'PTR'` | `value` | +| `'SOA'` | Refer to [`dnsPromises.resolveSoa()`][] | +| `'SRV'` | Refer to [`dnsPromises.resolveSrv()`][] | +| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dnsPromises.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | Here is an example of the result object: <!-- eslint-disable semi --> + ```js [ { type: 'A', address: '127.0.0.1', ttl: 299 }, { type: 'CNAME', value: 'example.com' }, @@ -995,6 +1038,7 @@ Here is an example of the result object: ``` ### `dnsPromises.resolveCaa(hostname)` + <!-- YAML added: - v15.0.0 @@ -1010,6 +1054,7 @@ certification authority authorization records available for the `hostname` 'pki.example.com'}]`). ### `dnsPromises.resolveCname(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1021,6 +1066,7 @@ the `Promise` is resolved with an array of canonical name records available for the `hostname` (e.g. `['bar.example.com']`). ### `dnsPromises.resolveMx(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1033,6 +1079,7 @@ containing both a `priority` and `exchange` property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). ### `dnsPromises.resolveNaptr(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1051,6 +1098,7 @@ of objects with the following properties: * `preference` <!-- eslint-skip --> + ```js { flags: 's', @@ -1063,6 +1111,7 @@ of objects with the following properties: ``` ### `dnsPromises.resolveNs(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1075,6 +1124,7 @@ records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`). ### `dnsPromises.resolvePtr(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1086,6 +1136,7 @@ Uses the DNS protocol to resolve pointer records (`PTR` records) for the containing the reply records. ### `dnsPromises.resolveSoa(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1105,6 +1156,7 @@ following properties: * `minttl` <!-- eslint-skip --> + ```js { nsname: 'ns.example.com', @@ -1118,6 +1170,7 @@ following properties: ``` ### `dnsPromises.resolveSrv(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1134,6 +1187,7 @@ the following properties: * `name` <!-- eslint-skip --> + ```js { priority: 10, @@ -1144,6 +1198,7 @@ the following properties: ``` ### `dnsPromises.resolveTxt(hostname)` + <!-- YAML added: v10.6.0 --> @@ -1158,6 +1213,7 @@ one record. Depending on the use case, these could be either joined together or treated separately. ### `dnsPromises.reverse(ip)` + <!-- YAML added: v10.6.0 --> @@ -1171,6 +1227,7 @@ On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` is one of the [DNS error codes](). ### `dnsPromises.setDefaultResultOrder(order)` + <!-- YAML added: - v16.4.0 @@ -1181,6 +1238,7 @@ added: Set the default value of `verbatim` in [`dns.lookup()`][] and [`dnsPromises.lookup()`][]. The value could be: + * `ipv4first`: sets default `verbatim` `false`. * `verbatim`: sets default `verbatim` `true`. @@ -1190,11 +1248,12 @@ higher priority than [`--dns-result-order`][]. When using [worker threads][], default dns orders in workers. ### `dnsPromises.setServers(servers)` + <!-- YAML added: v10.6.0 --> -* `servers` {string[]} array of [RFC 5952][] formatted addresses +* `servers` {string\[]} array of [RFC 5952][] formatted addresses Sets the IP address and port of servers to be used when performing DNS resolution. The `servers` argument is an array of [RFC 5952][] formatted @@ -1217,7 +1276,7 @@ progress. This method works much like [resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html). That is, if attempting to resolve with the first server provided results in a -`NOTFOUND` error, the `resolve()` method will *not* attempt to resolve with +`NOTFOUND` error, the `resolve()` method will _not_ attempt to resolve with subsequent servers provided. Fallback DNS servers will only be used if the earlier ones time out or result in some other error. diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 9100354b361..be5e7671f8d 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -51,11 +51,13 @@ modifications occur. To avoid surprises, use of an Experimental feature may need a command-line flag. Experimental features may also emit a [warning][]. ## Stability overview + <!-- STABILITY_OVERVIEW_SLOT_BEGIN --> <!-- STABILITY_OVERVIEW_SLOT_END --> ## JSON output + <!-- YAML added: v0.6.12 --> diff --git a/doc/api/domain.md b/doc/api/domain.md index 02833e36e7b..9552b3bbcd4 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -1,4 +1,5 @@ # Domain + <!-- YAML deprecated: v1.4.2 changes: diff --git a/doc/api/embedding.md b/doc/api/embedding.md index b386772eb6c..ec6af9180de 100644 --- a/doc/api/embedding.md +++ b/doc/api/embedding.md @@ -67,6 +67,7 @@ int main(int argc, char** argv) { ``` ### Per-instance state + <!-- YAML changes: - version: v15.0.0 diff --git a/doc/api/errors.md b/doc/api/errors.md index b0b0753f400..78106c93801 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -19,7 +19,7 @@ errors: All JavaScript and system errors raised by Node.js inherit from, or are instances of, the standard JavaScript {Error} class and are guaranteed -to provide *at least* the properties available on that class. +to provide _at least_ the properties available on that class. ## Error propagation and interception @@ -30,7 +30,7 @@ occur while an application is running. How these errors are reported and handled depends entirely on the type of `Error` and the style of the API that is called. -All JavaScript errors are handled as exceptions that *immediately* generate +All JavaScript errors are handled as exceptions that _immediately_ generate and throw an error using the standard JavaScript `throw` mechanism. These are handled using the [`try…catch` construct][try-catch] provided by the JavaScript language. @@ -46,7 +46,7 @@ try { ``` Any use of the JavaScript `throw` mechanism will raise an exception that -*must* be handled using `try…catch` or the Node.js process will exit +_must_ be handled using `try…catch` or the Node.js process will exit immediately. With few exceptions, _Synchronous_ APIs (any blocking method that does not @@ -60,7 +60,8 @@ Errors that occur within _Asynchronous APIs_ may be reported in multiple ways: argument is not `null` and is an instance of `Error`, then an error occurred that should be handled. -<!-- eslint-disable no-useless-return --> + <!-- eslint-disable no-useless-return --> + ```js const fs = require('fs'); fs.readFile('a file that does not exist', (err, data) => { @@ -101,7 +102,7 @@ and [event emitter-based][] APIs, which themselves represent a series of asynchronous operations over time (as opposed to a single operation that may pass or fail). -For *all* [`EventEmitter`][] objects, if an `'error'` event handler is not +For _all_ [`EventEmitter`][] objects, if an `'error'` event handler is not provided, the error will be thrown, causing the Node.js process to report an uncaught exception and crash unless either: The [`domain`][domains] module is used appropriately or a handler has been registered for the @@ -118,8 +119,8 @@ setImmediate(() => { }); ``` -Errors generated in this way *cannot* be intercepted using `try…catch` as -they are thrown *after* the calling code has already exited. +Errors generated in this way _cannot_ be intercepted using `try…catch` as +they are thrown _after_ the calling code has already exited. Developers must refer to the documentation for each method to determine exactly how errors raised by those methods are propagated. @@ -199,7 +200,7 @@ provided text message. If an object is passed as `message`, the text message is generated by calling `message.toString()`. The `error.stack` property will represent the point in the code at which `new Error()` was called. Stack traces are dependent on [V8's stack trace API][]. Stack traces extend only to either -(a) the beginning of *synchronous code execution*, or (b) the number of frames +(a) the beginning of _synchronous code execution_, or (b) the number of frames given by the property `Error.stackTraceLimit`, whichever is smaller. ### `Error.captureStackTrace(targetObject[, constructorOpt])` @@ -247,7 +248,7 @@ collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes -will affect any stack trace captured *after* the value has been changed. +will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. @@ -269,7 +270,7 @@ about specific codes. The `error.message` property is the string description of the error as set by calling `new Error(message)`. The `message` passed to the constructor will also appear in the first line of the stack trace of the `Error`, however changing -this property after the `Error` object is created *may not* change the first +this property after the `Error` object is created _may not_ change the first line of the stack trace (for example, when `error.stack` is read before this property is changed). @@ -341,7 +342,7 @@ The location information will be one of: * `native`, if the frame represents a call internal to V8 (as in `[].forEach`). * `plain-filename.js:line:column`, if the frame represents a call internal - to Node.js. + to Node.js. * `/absolute/path/to/file.js:line:column`, if the frame represents a call in a user program, or its dependencies. @@ -372,7 +373,7 @@ require('net').connect(-1); // Throws "RangeError: "port" option should be >= 0 and < 65536: -1" ``` -Node.js will generate and throw `RangeError` instances *immediately* as a form +Node.js will generate and throw `RangeError` instances _immediately_ as a form of argument validation. ## Class: `ReferenceError` @@ -570,7 +571,7 @@ require('url').parse(() => { }); // Throws TypeError, since it expected a string. ``` -Node.js will generate and throw `TypeError` instances *immediately* as a form +Node.js will generate and throw `TypeError` instances _immediately_ as a form of argument validation. ## Exceptions vs. errors @@ -580,11 +581,11 @@ of argument validation. A JavaScript exception is a value that is thrown as a result of an invalid operation or as the target of a `throw` statement. While it is not required that these values are instances of `Error` or classes which inherit from -`Error`, all exceptions thrown by Node.js or the JavaScript runtime *will* be +`Error`, all exceptions thrown by Node.js or the JavaScript runtime _will_ be instances of `Error`. -Some exceptions are *unrecoverable* at the JavaScript layer. Such exceptions -will *always* cause the Node.js process to crash. Examples include `assert()` +Some exceptions are _unrecoverable_ at the JavaScript layer. Such exceptions +will _always_ cause the Node.js process to crash. Examples include `assert()` checks or `abort()` calls in the C++ layer. ## OpenSSL errors @@ -611,13 +612,17 @@ The OpenSSL library the error originates in. A human-readable string describing the reason for the error. <a id="nodejs-error-codes"></a> + ## Node.js error codes <a id="ABORT_ERR"></a> + ### `ABORT_ERR` + <!-- YAML added: v15.0.0 --> + Used when an operation has been aborted (typically using an `AbortController`). APIs _not_ using `AbortSignal`s typically do not raise an error with this code. @@ -626,6 +631,7 @@ This code does not use the regular `ERR_*` convention Node.js errors use in order to be compatible with the web platform's `AbortError`. <a id="ERR_AMBIGUOUS_ARGUMENT"></a> + ### `ERR_AMBIGUOUS_ARGUMENT` A function argument is being used in a way that suggests that the function @@ -636,12 +642,14 @@ is the expected message rather than the message the `AssertionError` will display if `block` does not throw. <a id="ERR_ARG_NOT_ITERABLE"></a> + ### `ERR_ARG_NOT_ITERABLE` An iterable argument (i.e. a value that works with `for...of` loops) was required, but not provided to a Node.js API. <a id="ERR_ASSERTION"></a> + ### `ERR_ASSERTION` A special type of error that can be triggered whenever Node.js detects an @@ -649,28 +657,33 @@ exceptional logic violation that should never occur. These are raised typically by the `assert` module. <a id="ERR_ASYNC_CALLBACK"></a> + ### `ERR_ASYNC_CALLBACK` An attempt was made to register something that is not a function as an `AsyncHooks` callback. <a id="ERR_ASYNC_TYPE"></a> + ### `ERR_ASYNC_TYPE` The type of an asynchronous resource was invalid. Users are also able to define their own types if using the public embedder API. <a id="ERR_BROTLI_COMPRESSION_FAILED"></a> + ### `ERR_BROTLI_COMPRESSION_FAILED` Data passed to a Brotli stream was not successfully compressed. <a id="ERR_BROTLI_INVALID_PARAM"></a> + ### `ERR_BROTLI_INVALID_PARAM` An invalid parameter key was passed during construction of a Brotli stream. <a id="ERR_BUFFER_CONTEXT_NOT_AVAILABLE"></a> + ### `ERR_BUFFER_CONTEXT_NOT_AVAILABLE` An attempt was made to create a Node.js `Buffer` instance from addon or embedder @@ -684,39 +697,47 @@ prototype of the resulting object. `Uint8Array`s are generally accepted in all Node.js core APIs where `Buffer`s are; they are available in all Contexts. <a id="ERR_BUFFER_OUT_OF_BOUNDS"></a> + ### `ERR_BUFFER_OUT_OF_BOUNDS` An operation outside the bounds of a `Buffer` was attempted. <a id="ERR_BUFFER_TOO_LARGE"></a> + ### `ERR_BUFFER_TOO_LARGE` An attempt has been made to create a `Buffer` larger than the maximum allowed size. <a id="ERR_CANNOT_WATCH_SIGINT"></a> + ### `ERR_CANNOT_WATCH_SIGINT` Node.js was unable to watch for the `SIGINT` signal. <a id="ERR_CHILD_CLOSED_BEFORE_REPLY"></a> + ### `ERR_CHILD_CLOSED_BEFORE_REPLY` A child process was closed before the parent received a reply. <a id="ERR_CHILD_PROCESS_IPC_REQUIRED"></a> + ### `ERR_CHILD_PROCESS_IPC_REQUIRED` Used when a child process is being forked without specifying an IPC channel. <a id="ERR_CHILD_PROCESS_STDIO_MAXBUFFER"></a> + ### `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` Used when the main process is trying to read data from the child process's STDERR/STDOUT, and the data's length is longer than the `maxBuffer` option. <a id="ERR_CLOSED_MESSAGE_PORT"></a> + ### `ERR_CLOSED_MESSAGE_PORT` + <!-- added: - v16.2.0 @@ -736,13 +757,16 @@ There was an attempt to use a `MessagePort` instance in a closed state, usually after `.close()` has been called. <a id="ERR_CONSOLE_WRITABLE_STREAM"></a> + ### `ERR_CONSOLE_WRITABLE_STREAM` `Console` was instantiated without `stdout` stream, or `Console` has a non-writable `stdout` or `stderr` stream. <a id="ERR_CONSTRUCT_CALL_INVALID"></a> + ### `ERR_CONSTRUCT_CALL_INVALID` + <!-- added: v12.5.0 --> @@ -750,11 +774,13 @@ added: v12.5.0 A class constructor was called that is not callable. <a id="ERR_CONSTRUCT_CALL_REQUIRED"></a> + ### `ERR_CONSTRUCT_CALL_REQUIRED` A constructor for a class was called without `new`. <a id="ERR_CONTEXT_NOT_INITIALIZED"></a> + ### `ERR_CONTEXT_NOT_INITIALIZED` The vm context passed into the API is not yet initialized. This could happen @@ -763,18 +789,21 @@ context, for example, when the allocation fails or the maximum call stack size is reached when the context is created. <a id="ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED"></a> + ### `ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED` A client certificate engine was requested that is not supported by the version of OpenSSL being used. <a id="ERR_CRYPTO_ECDH_INVALID_FORMAT"></a> + ### `ERR_CRYPTO_ECDH_INVALID_FORMAT` An invalid value for the `format` argument was passed to the `crypto.ECDH()` class `getPublicKey()` method. <a id="ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY"></a> + ### `ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY` An invalid value for the `key` argument has been passed to the @@ -782,46 +811,55 @@ An invalid value for the `key` argument has been passed to the key lies outside of the elliptic curve. <a id="ERR_CRYPTO_ENGINE_UNKNOWN"></a> + ### `ERR_CRYPTO_ENGINE_UNKNOWN` An invalid crypto engine identifier was passed to [`require('crypto').setEngine()`][]. <a id="ERR_CRYPTO_FIPS_FORCED"></a> + ### `ERR_CRYPTO_FIPS_FORCED` The [`--force-fips`][] command-line argument was used but there was an attempt to enable or disable FIPS mode in the `crypto` module. <a id="ERR_CRYPTO_FIPS_UNAVAILABLE"></a> + ### `ERR_CRYPTO_FIPS_UNAVAILABLE` An attempt was made to enable or disable FIPS mode, but FIPS mode was not available. <a id="ERR_CRYPTO_HASH_FINALIZED"></a> + ### `ERR_CRYPTO_HASH_FINALIZED` [`hash.digest()`][] was called multiple times. The `hash.digest()` method must be called no more than one time per instance of a `Hash` object. <a id="ERR_CRYPTO_HASH_UPDATE_FAILED"></a> + ### `ERR_CRYPTO_HASH_UPDATE_FAILED` [`hash.update()`][] failed for any reason. This should rarely, if ever, happen. <a id="ERR_CRYPTO_INCOMPATIBLE_KEY"></a> + ### `ERR_CRYPTO_INCOMPATIBLE_KEY` The given crypto keys are incompatible with the attempted operation. <a id="ERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS"></a> + ### `ERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS` The selected public or private key encoding is incompatible with other options. <a id="ERR_CRYPTO_INITIALIZATION_FAILED"></a> + ### `ERR_CRYPTO_INITIALIZATION_FAILED` + <!-- YAML added: v15.0.0 --> @@ -829,7 +867,9 @@ added: v15.0.0 Initialization of the crypto subsystem failed. <a id="ERR_CRYPTO_INVALID_AUTH_TAG"></a> + ### `ERR_CRYPTO_INVALID_AUTH_TAG` + <!-- YAML added: v15.0.0 --> @@ -837,7 +877,9 @@ added: v15.0.0 An invalid authentication tag was provided. <a id="ERR_CRYPTO_INVALID_COUNTER"></a> + ### `ERR_CRYPTO_INVALID_COUNTER` + <!-- YAML added: v15.0.0 --> @@ -845,7 +887,9 @@ added: v15.0.0 An invalid counter was provided for a counter-mode cipher. <a id="ERR_CRYPTO_INVALID_CURVE"></a> + ### `ERR_CRYPTO_INVALID_CURVE` + <!-- YAML added: v15.0.0 --> @@ -853,12 +897,15 @@ added: v15.0.0 An invalid elliptic-curve was provided. <a id="ERR_CRYPTO_INVALID_DIGEST"></a> + ### `ERR_CRYPTO_INVALID_DIGEST` An invalid [crypto digest algorithm][] was specified. <a id="ERR_CRYPTO_INVALID_IV"></a> + ### `ERR_CRYPTO_INVALID_IV` + <!-- YAML added: v15.0.0 --> @@ -866,7 +913,9 @@ added: v15.0.0 An invalid initialization vector was provided. <a id="ERR_CRYPTO_INVALID_JWK"></a> + ### `ERR_CRYPTO_INVALID_JWK` + <!-- YAML added: v15.0.0 --> @@ -874,12 +923,15 @@ added: v15.0.0 An invalid JSON Web Key was provided. <a id="ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE"></a> + ### `ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE` The given crypto key object's type is invalid for the attempted operation. <a id="ERR_CRYPTO_INVALID_KEYLEN"></a> + ### `ERR_CRYPTO_INVALID_KEYLEN` + <!-- YAML added: v15.0.0 --> @@ -887,7 +939,9 @@ added: v15.0.0 An invalid key length was provided. <a id="ERR_CRYPTO_INVALID_KEYPAIR"></a> + ### `ERR_CRYPTO_INVALID_KEYPAIR` + <!-- YAML added: v15.0.0 --> @@ -895,7 +949,9 @@ added: v15.0.0 An invalid key pair was provided. <a id="ERR_CRYPTO_INVALID_KEYTYPE"></a> + ### `ERR_CRYPTO_INVALID_KEYTYPE` + <!-- YAML added: v15.0.0 --> @@ -903,7 +959,9 @@ added: v15.0.0 An invalid key type was provided. <a id="ERR_CRYPTO_INVALID_MESSAGELEN"></a> + ### `ERR_CRYPTO_INVALID_MESSAGELEN` + <!-- YAML added: v15.0.0 --> @@ -911,7 +969,9 @@ added: v15.0.0 An invalid message length was provided. <a id="ERR_CRYPTO_INVALID_SCRYPT_PARAMS"></a> + ### `ERR_CRYPTO_INVALID_SCRYPT_PARAMS` + <!-- YAML added: v15.0.0 --> @@ -919,13 +979,16 @@ added: v15.0.0 Invalid scrypt algorithm parameters were provided. <a id="ERR_CRYPTO_INVALID_STATE"></a> + ### `ERR_CRYPTO_INVALID_STATE` A crypto method was used on an object that was in an invalid state. For instance, calling [`cipher.getAuthTag()`][] before calling `cipher.final()`. <a id="ERR_CRYPTO_INVALID_TAG_LENGTH"></a> + ### `ERR_CRYPTO_INVALID_TAG_LENGTH` + <!-- YAML added: v15.0.0 --> @@ -933,7 +996,9 @@ added: v15.0.0 An invalid authentication tag length was provided. <a id="ERR_CRYPTO_JOB_INIT_FAILED"></a> + ### `ERR_CRYPTO_JOB_INIT_FAILED` + <!-- YAML added: v15.0.0 --> @@ -941,19 +1006,23 @@ added: v15.0.0 Initialization of an asynchronous crypto operation failed. <a id="ERR_CRYPTO_JWK_UNSUPPORTED_CURVE"></a> + ### `ERR_CRYPTO_JWK_UNSUPPORTED_CURVE` Key's Elliptic Curve is not registered for use in the [JSON Web Key Elliptic Curve Registry][]. <a id="ERR_CRYPTO_JWK_UNSUPPORTED_KEY_TYPE"></a> + ### `ERR_CRYPTO_JWK_UNSUPPORTED_KEY_TYPE` Key's Asymmetric Key Type is not registered for use in the [JSON Web Key Types Registry][]. <a id="ERR_CRYPTO_OPERATION_FAILED"></a> + ### `ERR_CRYPTO_OPERATION_FAILED` + <!-- YAML added: v15.0.0 --> @@ -961,47 +1030,56 @@ added: v15.0.0 A crypto operation failed for an otherwise unspecified reason. <a id="ERR_CRYPTO_PBKDF2_ERROR"></a> + ### `ERR_CRYPTO_PBKDF2_ERROR` The PBKDF2 algorithm failed for unspecified reasons. OpenSSL does not provide more details and therefore neither does Node.js. <a id="ERR_CRYPTO_SCRYPT_INVALID_PARAMETER"></a> + ### `ERR_CRYPTO_SCRYPT_INVALID_PARAMETER` One or more [`crypto.scrypt()`][] or [`crypto.scryptSync()`][] parameters are outside their legal range. <a id="ERR_CRYPTO_SCRYPT_NOT_SUPPORTED"></a> + ### `ERR_CRYPTO_SCRYPT_NOT_SUPPORTED` Node.js was compiled without `scrypt` support. Not possible with the official release binaries but can happen with custom builds, including distro builds. <a id="ERR_CRYPTO_SIGN_KEY_REQUIRED"></a> + ### `ERR_CRYPTO_SIGN_KEY_REQUIRED` A signing `key` was not provided to the [`sign.sign()`][] method. <a id="ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH"></a> + ### `ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH` [`crypto.timingSafeEqual()`][] was called with `Buffer`, `TypedArray`, or `DataView` arguments of different lengths. <a id="ERR_CRYPTO_UNKNOWN_CIPHER"></a> + ### `ERR_CRYPTO_UNKNOWN_CIPHER` An unknown cipher was specified. <a id="ERR_CRYPTO_UNKNOWN_DH_GROUP"></a> + ### `ERR_CRYPTO_UNKNOWN_DH_GROUP` An unknown Diffie-Hellman group name was given. See [`crypto.getDiffieHellman()`][] for a list of valid group names. <a id="ERR_CRYPTO_UNSUPPORTED_OPERATION"></a> + ### `ERR_CRYPTO_UNSUPPORTED_OPERATION` + <!-- YAML added: - v15.0.0 @@ -1011,7 +1089,9 @@ added: An attempt to invoke an unsupported crypto operation was made. <a id="ERR_DEBUGGER_ERROR"></a> + ### `ERR_DEBUGGER_ERROR` + <!-- YAML added: - v16.4.0 @@ -1021,7 +1101,9 @@ added: An error occurred with the [debugger][]. <a id="ERR_DEBUGGER_STARTUP_ERROR"></a> + ### `ERR_DEBUGGER_STARTUP_ERROR` + <!-- YAML added: - v16.4.0 @@ -1031,7 +1113,9 @@ added: The [debugger][] timed out waiting for the required host/port to be free. <a id="ERR_DLOPEN_DISABLED"></a> + ### `ERR_DLOPEN_DISABLED` + <!-- YAML added: v16.10.0 --> @@ -1039,7 +1123,9 @@ added: v16.10.0 Loading native addons has been disabled using [`--no-addons`][]. <a id="ERR_DLOPEN_FAILED"></a> + ### `ERR_DLOPEN_FAILED` + <!-- YAML added: v15.0.0 --> @@ -1047,12 +1133,15 @@ added: v15.0.0 A call to `process.dlopen()` failed. <a id="ERR_DIR_CLOSED"></a> + ### `ERR_DIR_CLOSED` The [`fs.Dir`][] was previously closed. <a id="ERR_DIR_CONCURRENT_OPERATION"></a> + ### `ERR_DIR_CONCURRENT_OPERATION` + <!-- YAML added: v14.3.0 --> @@ -1061,11 +1150,13 @@ A synchronous read or close call was attempted on an [`fs.Dir`][] which has ongoing asynchronous operations. <a id="ERR_DNS_SET_SERVERS_FAILED"></a> + ### `ERR_DNS_SET_SERVERS_FAILED` `c-ares` failed to set the DNS server. <a id="ERR_DOMAIN_CALLBACK_NOT_AVAILABLE"></a> + ### `ERR_DOMAIN_CALLBACK_NOT_AVAILABLE` The `domain` module was not usable since it could not establish the required @@ -1074,6 +1165,7 @@ error handling hooks, because earlier point in time. <a id="ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE"></a> + ### `ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE` [`process.setUncaughtExceptionCaptureCallback()`][] could not be called @@ -1083,28 +1175,33 @@ The stack trace is extended to include the point in time at which the `domain` module had been loaded. <a id="ERR_ENCODING_INVALID_ENCODED_DATA"></a> + ### `ERR_ENCODING_INVALID_ENCODED_DATA` Data provided to `TextDecoder()` API was invalid according to the encoding provided. <a id="ERR_ENCODING_NOT_SUPPORTED"></a> + ### `ERR_ENCODING_NOT_SUPPORTED` Encoding provided to `TextDecoder()` API was not one of the [WHATWG Supported Encodings][]. <a id="ERR_EVAL_ESM_CANNOT_PRINT"></a> + ### `ERR_EVAL_ESM_CANNOT_PRINT` `--print` cannot be used with ESM input. <a id="ERR_EVENT_RECURSION"></a> + ### `ERR_EVENT_RECURSION` Thrown when an attempt is made to recursively dispatch an event on `EventTarget`. <a id="ERR_EXECUTION_ENVIRONMENT_NOT_AVAILABLE"></a> + ### `ERR_EXECUTION_ENVIRONMENT_NOT_AVAILABLE` The JS execution context is not associated with a Node.js environment. @@ -1112,13 +1209,16 @@ This may occur when Node.js is used as an embedded library and some hooks for the JS engine are not set up properly. <a id="ERR_FALSY_VALUE_REJECTION"></a> + ### `ERR_FALSY_VALUE_REJECTION` A `Promise` that was callbackified via `util.callbackify()` was rejected with a falsy value. <a id="ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"></a> + ### `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` + <!-- YAML added: v14.0.0 --> @@ -1127,7 +1227,9 @@ Used when a feature that is not available to the current platform which is running Node.js is used. <a id="ERR_FS_CP_DIR_TO_NON_DIR"></a> + ### `ERR_FS_CP_DIR_TO_NON_DIR` + <!-- added: v16.7.0 --> @@ -1136,7 +1238,9 @@ An attempt was made to copy a directory to a non-directory (file, symlink, etc.) using [`fs.cp()`][]. <a id="ERR_FS_CP_EEXIST"></a> + ### `ERR_FS_CP_EEXIST` + <!-- added: v16.7.0 --> @@ -1145,7 +1249,9 @@ An attempt was made to copy over a file that already existed with [`fs.cp()`][], with the `force` and `errorOnExist` set to `true`. <a id="ERR_FS_CP_EINVAL"></a> + ### `ERR_FS_CP_EINVAL` + <!-- added: v16.7.0 --> @@ -1153,7 +1259,9 @@ added: v16.7.0 When using [`fs.cp()`][], `src` or `dest` pointed to an invalid path. <a id="ERR_FS_CP_FIFO_PIPE"></a> + ### `ERR_FS_CP_FIFO_PIPE` + <!-- added: v16.7.0 --> @@ -1161,7 +1269,9 @@ added: v16.7.0 An attempt was made to copy a named pipe with [`fs.cp()`][]. <a id="ERR_FS_CP_NON_DIR_TO_DIR"></a> + ### `ERR_FS_CP_NON_DIR_TO_DIR` + <!-- added: v16.7.0 --> @@ -1170,7 +1280,9 @@ An attempt was made to copy a non-directory (file, symlink, etc.) to a directory using [`fs.cp()`][]. <a id="ERR_FS_CP_SOCKET"></a> + ### `ERR_FS_CP_SOCKET` + <!-- added: v16.7.0 --> @@ -1178,7 +1290,9 @@ added: v16.7.0 An attempt was made to copy to a socket with [`fs.cp()`][]. <a id="ERR_FS_CP_SYMLINK_TO_SUBDIRECTORY"></a> + ### `ERR_FS_CP_SYMLINK_TO_SUBDIRECTORY` + <!-- added: v16.7.0 --> @@ -1187,7 +1301,9 @@ When using [`fs.cp()`][], a symlink in `dest` pointed to a subdirectory of `src`. <a id="ERR_FS_CP_UNKNOWN"></a> + ### `ERR_FS_CP_UNKNOWN` + <!-- added: v16.7.0 --> @@ -1195,137 +1311,162 @@ added: v16.7.0 An attempt was made to copy to an unknown file type with [`fs.cp()`][]. <a id="ERR_FS_EISDIR"></a> + ### `ERR_FS_EISDIR` Path is a directory. <a id="ERR_FS_FILE_TOO_LARGE"></a> + ### `ERR_FS_FILE_TOO_LARGE` An attempt has been made to read a file whose size is larger than the maximum allowed size for a `Buffer`. <a id="ERR_FS_INVALID_SYMLINK_TYPE"></a> + ### `ERR_FS_INVALID_SYMLINK_TYPE` An invalid symlink type was passed to the [`fs.symlink()`][] or [`fs.symlinkSync()`][] methods. <a id="ERR_HTTP_HEADERS_SENT"></a> + ### `ERR_HTTP_HEADERS_SENT` An attempt was made to add more headers after the headers had already been sent. <a id="ERR_HTTP_INVALID_HEADER_VALUE"></a> + ### `ERR_HTTP_INVALID_HEADER_VALUE` An invalid HTTP header value was specified. <a id="ERR_HTTP_INVALID_STATUS_CODE"></a> + ### `ERR_HTTP_INVALID_STATUS_CODE` Status code was outside the regular status code range (100-999). <a id="ERR_HTTP_REQUEST_TIMEOUT"></a> + ### `ERR_HTTP_REQUEST_TIMEOUT` The client has not sent the entire request within the allowed time. <a id="ERR_HTTP_SOCKET_ENCODING"></a> + ### `ERR_HTTP_SOCKET_ENCODING` Changing the socket encoding is not allowed per [RFC 7230 Section 3][]. <a id="ERR_HTTP_TRAILER_INVALID"></a> + ### `ERR_HTTP_TRAILER_INVALID` The `Trailer` header was set even though the transfer encoding does not support that. <a id="ERR_HTTP2_ALTSVC_INVALID_ORIGIN"></a> + ### `ERR_HTTP2_ALTSVC_INVALID_ORIGIN` HTTP/2 ALTSVC frames require a valid origin. <a id="ERR_HTTP2_ALTSVC_LENGTH"></a> + ### `ERR_HTTP2_ALTSVC_LENGTH` HTTP/2 ALTSVC frames are limited to a maximum of 16,382 payload bytes. <a id="ERR_HTTP2_CONNECT_AUTHORITY"></a> + ### `ERR_HTTP2_CONNECT_AUTHORITY` For HTTP/2 requests using the `CONNECT` method, the `:authority` pseudo-header is required. <a id="ERR_HTTP2_CONNECT_PATH"></a> + ### `ERR_HTTP2_CONNECT_PATH` For HTTP/2 requests using the `CONNECT` method, the `:path` pseudo-header is forbidden. <a id="ERR_HTTP2_CONNECT_SCHEME"></a> + ### `ERR_HTTP2_CONNECT_SCHEME` For HTTP/2 requests using the `CONNECT` method, the `:scheme` pseudo-header is forbidden. <a id="ERR_HTTP2_ERROR"></a> + ### `ERR_HTTP2_ERROR` A non-specific HTTP/2 error has occurred. <a id="ERR_HTTP2_GOAWAY_SESSION"></a> + ### `ERR_HTTP2_GOAWAY_SESSION` New HTTP/2 Streams may not be opened after the `Http2Session` has received a `GOAWAY` frame from the connected peer. <a id="ERR_HTTP2_HEADER_SINGLE_VALUE"></a> + ### `ERR_HTTP2_HEADER_SINGLE_VALUE` Multiple values were provided for an HTTP/2 header field that was required to have only a single value. <a id="ERR_HTTP2_HEADERS_AFTER_RESPOND"></a> + ### `ERR_HTTP2_HEADERS_AFTER_RESPOND` An additional headers was specified after an HTTP/2 response was initiated. <a id="ERR_HTTP2_HEADERS_SENT"></a> + ### `ERR_HTTP2_HEADERS_SENT` An attempt was made to send multiple response headers. <a id="ERR_HTTP2_INFO_STATUS_NOT_ALLOWED"></a> + ### `ERR_HTTP2_INFO_STATUS_NOT_ALLOWED` Informational HTTP status codes (`1xx`) may not be set as the response status code on HTTP/2 responses. <a id="ERR_HTTP2_INVALID_CONNECTION_HEADERS"></a> + ### `ERR_HTTP2_INVALID_CONNECTION_HEADERS` HTTP/1 connection specific headers are forbidden to be used in HTTP/2 requests and responses. <a id="ERR_HTTP2_INVALID_HEADER_VALUE"></a> + ### `ERR_HTTP2_INVALID_HEADER_VALUE` An invalid HTTP/2 header value was specified. <a id="ERR_HTTP2_INVALID_INFO_STATUS"></a> + ### `ERR_HTTP2_INVALID_INFO_STATUS` An invalid HTTP informational status code has been specified. Informational status codes must be an integer between `100` and `199` (inclusive). <a id="ERR_HTTP2_INVALID_ORIGIN"></a> + ### `ERR_HTTP2_INVALID_ORIGIN` HTTP/2 `ORIGIN` frames require a valid origin. <a id="ERR_HTTP2_INVALID_PACKED_SETTINGS_LENGTH"></a> + ### `ERR_HTTP2_INVALID_PACKED_SETTINGS_LENGTH` Input `Buffer` and `Uint8Array` instances passed to the @@ -1333,28 +1474,33 @@ Input `Buffer` and `Uint8Array` instances passed to the six. <a id="ERR_HTTP2_INVALID_PSEUDOHEADER"></a> + ### `ERR_HTTP2_INVALID_PSEUDOHEADER` Only valid HTTP/2 pseudoheaders (`:status`, `:path`, `:authority`, `:scheme`, and `:method`) may be used. <a id="ERR_HTTP2_INVALID_SESSION"></a> + ### `ERR_HTTP2_INVALID_SESSION` An action was performed on an `Http2Session` object that had already been destroyed. <a id="ERR_HTTP2_INVALID_SETTING_VALUE"></a> + ### `ERR_HTTP2_INVALID_SETTING_VALUE` An invalid value has been specified for an HTTP/2 setting. <a id="ERR_HTTP2_INVALID_STREAM"></a> + ### `ERR_HTTP2_INVALID_STREAM` An operation was performed on a stream that had already been destroyed. <a id="ERR_HTTP2_MAX_PENDING_SETTINGS_ACK"></a> + ### `ERR_HTTP2_MAX_PENDING_SETTINGS_ACK` Whenever an HTTP/2 `SETTINGS` frame is sent to a connected peer, the peer is @@ -1364,68 +1510,80 @@ be sent at any given time. This error code is used when that limit has been reached. <a id="ERR_HTTP2_NESTED_PUSH"></a> + ### `ERR_HTTP2_NESTED_PUSH` An attempt was made to initiate a new push stream from within a push stream. Nested push streams are not permitted. <a id="ERR_HTTP2_NO_MEM"></a> + ### `ERR_HTTP2_NO_MEM` Out of memory when using the `http2session.setLocalWindowSize(windowSize)` API. <a id="ERR_HTTP2_NO_SOCKET_MANIPULATION"></a> + ### `ERR_HTTP2_NO_SOCKET_MANIPULATION` An attempt was made to directly manipulate (read, write, pause, resume, etc.) a socket attached to an `Http2Session`. <a id="ERR_HTTP2_ORIGIN_LENGTH"></a> + ### `ERR_HTTP2_ORIGIN_LENGTH` HTTP/2 `ORIGIN` frames are limited to a length of 16382 bytes. <a id="ERR_HTTP2_OUT_OF_STREAMS"></a> + ### `ERR_HTTP2_OUT_OF_STREAMS` The number of streams created on a single HTTP/2 session reached the maximum limit. <a id="ERR_HTTP2_PAYLOAD_FORBIDDEN"></a> + ### `ERR_HTTP2_PAYLOAD_FORBIDDEN` A message payload was specified for an HTTP response code for which a payload is forbidden. <a id="ERR_HTTP2_PING_CANCEL"></a> + ### `ERR_HTTP2_PING_CANCEL` An HTTP/2 ping was canceled. <a id="ERR_HTTP2_PING_LENGTH"></a> + ### `ERR_HTTP2_PING_LENGTH` HTTP/2 ping payloads must be exactly 8 bytes in length. <a id="ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED"></a> + ### `ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED` An HTTP/2 pseudo-header has been used inappropriately. Pseudo-headers are header key names that begin with the `:` prefix. <a id="ERR_HTTP2_PUSH_DISABLED"></a> + ### `ERR_HTTP2_PUSH_DISABLED` An attempt was made to create a push stream, which had been disabled by the client. <a id="ERR_HTTP2_SEND_FILE"></a> + ### `ERR_HTTP2_SEND_FILE` An attempt was made to use the `Http2Stream.prototype.responseWithFile()` API to send a directory. <a id="ERR_HTTP2_SEND_FILE_NOSEEK"></a> + ### `ERR_HTTP2_SEND_FILE_NOSEEK` An attempt was made to use the `Http2Stream.prototype.responseWithFile()` API to @@ -1433,50 +1591,59 @@ send something other than a regular file, but `offset` or `length` options were provided. <a id="ERR_HTTP2_SESSION_ERROR"></a> + ### `ERR_HTTP2_SESSION_ERROR` The `Http2Session` closed with a non-zero error code. <a id="ERR_HTTP2_SETTINGS_CANCEL"></a> + ### `ERR_HTTP2_SETTINGS_CANCEL` The `Http2Session` settings canceled. <a id="ERR_HTTP2_SOCKET_BOUND"></a> + ### `ERR_HTTP2_SOCKET_BOUND` An attempt was made to connect a `Http2Session` object to a `net.Socket` or `tls.TLSSocket` that had already been bound to another `Http2Session` object. <a id="ERR_HTTP2_SOCKET_UNBOUND"></a> + ### `ERR_HTTP2_SOCKET_UNBOUND` An attempt was made to use the `socket` property of an `Http2Session` that has already been closed. <a id="ERR_HTTP2_STATUS_101"></a> + ### `ERR_HTTP2_STATUS_101` Use of the `101` Informational status code is forbidden in HTTP/2. <a id="ERR_HTTP2_STATUS_INVALID"></a> + ### `ERR_HTTP2_STATUS_INVALID` An invalid HTTP status code has been specified. Status codes must be an integer between `100` and `599` (inclusive). <a id="ERR_HTTP2_STREAM_CANCEL"></a> + ### `ERR_HTTP2_STREAM_CANCEL` An `Http2Stream` was destroyed before any data was transmitted to the connected peer. <a id="ERR_HTTP2_STREAM_ERROR"></a> + ### `ERR_HTTP2_STREAM_ERROR` A non-zero error code was been specified in an `RST_STREAM` frame. <a id="ERR_HTTP2_STREAM_SELF_DEPENDENCY"></a> + ### `ERR_HTTP2_STREAM_SELF_DEPENDENCY` When setting the priority for an HTTP/2 stream, the stream may be marked as @@ -1484,7 +1651,9 @@ a dependency for a parent stream. This error code is used when an attempt is made to mark a stream and dependent of itself. <a id="ERR_HTTP2_TOO_MANY_INVALID_FRAMES"></a> + ### `ERR_HTTP2_TOO_MANY_INVALID_FRAMES` + <!-- added: v15.14.0 --> @@ -1493,11 +1662,13 @@ The limit of acceptable invalid HTTP/2 protocol frames sent by the peer, as specified through the `maxSessionInvalidFrames` option, has been exceeded. <a id="ERR_HTTP2_TRAILERS_ALREADY_SENT"></a> + ### `ERR_HTTP2_TRAILERS_ALREADY_SENT` Trailing headers have already been sent on the `Http2Stream`. <a id="ERR_HTTP2_TRAILERS_NOT_READY"></a> + ### `ERR_HTTP2_TRAILERS_NOT_READY` The `http2stream.sendTrailers()` method cannot be called until after the @@ -1506,23 +1677,27 @@ The `http2stream.sendTrailers()` method cannot be called until after the is set for the `Http2Stream`. <a id="ERR_HTTP2_UNSUPPORTED_PROTOCOL"></a> + ### `ERR_HTTP2_UNSUPPORTED_PROTOCOL` `http2.connect()` was passed a URL that uses any protocol other than `http:` or `https:`. <a id="ERR_ILLEGAL_CONSTRUCTOR"></a> + ### `ERR_ILLEGAL_CONSTRUCTOR` An attempt was made to construct an object using a non-public constructor. <a id="ERR_INCOMPATIBLE_OPTION_PAIR"></a> + ### `ERR_INCOMPATIBLE_OPTION_PAIR` An option pair is incompatible with each other and cannot be used at the same time. <a id="ERR_INPUT_TYPE_NOT_ALLOWED"></a> + ### `ERR_INPUT_TYPE_NOT_ALLOWED` > Stability: 1 - Experimental @@ -1531,6 +1706,7 @@ The `--input-type` flag was used to attempt to execute a file. This flag can only be used with input via `--eval`, `--print` or `STDIN`. <a id="ERR_INSPECTOR_ALREADY_ACTIVATED"></a> + ### `ERR_INSPECTOR_ALREADY_ACTIVATED` While using the `inspector` module, an attempt was made to activate the @@ -1538,104 +1714,123 @@ inspector when it already started to listen on a port. Use `inspector.close()` before activating it on a different address. <a id="ERR_INSPECTOR_ALREADY_CONNECTED"></a> + ### `ERR_INSPECTOR_ALREADY_CONNECTED` While using the `inspector` module, an attempt was made to connect when the inspector was already connected. <a id="ERR_INSPECTOR_CLOSED"></a> + ### `ERR_INSPECTOR_CLOSED` While using the `inspector` module, an attempt was made to use the inspector after the session had already closed. <a id="ERR_INSPECTOR_COMMAND"></a> + ### `ERR_INSPECTOR_COMMAND` An error occurred while issuing a command via the `inspector` module. <a id="ERR_INSPECTOR_NOT_ACTIVE"></a> + ### `ERR_INSPECTOR_NOT_ACTIVE` The `inspector` is not active when `inspector.waitForDebugger()` is called. <a id="ERR_INSPECTOR_NOT_AVAILABLE"></a> + ### `ERR_INSPECTOR_NOT_AVAILABLE` The `inspector` module is not available for use. <a id="ERR_INSPECTOR_NOT_CONNECTED"></a> + ### `ERR_INSPECTOR_NOT_CONNECTED` While using the `inspector` module, an attempt was made to use the inspector before it was connected. <a id="ERR_INSPECTOR_NOT_WORKER"></a> + ### `ERR_INSPECTOR_NOT_WORKER` An API was called on the main thread that can only be used from the worker thread. <a id="ERR_INTERNAL_ASSERTION"></a> + ### `ERR_INTERNAL_ASSERTION` There was a bug in Node.js or incorrect usage of Node.js internals. To fix the error, open an issue at <https://github.com/nodejs/node/issues>. <a id="ERR_INVALID_ADDRESS_FAMILY"></a> + ### `ERR_INVALID_ADDRESS_FAMILY` The provided address family is not understood by the Node.js API. <a id="ERR_INVALID_ARG_TYPE"></a> + ### `ERR_INVALID_ARG_TYPE` An argument of the wrong type was passed to a Node.js API. <a id="ERR_INVALID_ARG_VALUE"></a> + ### `ERR_INVALID_ARG_VALUE` An invalid or unsupported value was passed for a given argument. <a id="ERR_INVALID_ASYNC_ID"></a> + ### `ERR_INVALID_ASYNC_ID` An invalid `asyncId` or `triggerAsyncId` was passed using `AsyncHooks`. An id less than -1 should never happen. <a id="ERR_INVALID_BUFFER_SIZE"></a> + ### `ERR_INVALID_BUFFER_SIZE` A swap was performed on a `Buffer` but its size was not compatible with the operation. <a id="ERR_INVALID_CALLBACK"></a> + ### `ERR_INVALID_CALLBACK` A callback function was required but was not been provided to a Node.js API. <a id="ERR_INVALID_CHAR"></a> + ### `ERR_INVALID_CHAR` Invalid characters were detected in headers. <a id="ERR_INVALID_CURSOR_POS"></a> + ### `ERR_INVALID_CURSOR_POS` A cursor on a given stream cannot be moved to a specified row without a specified column. <a id="ERR_INVALID_FD"></a> + ### `ERR_INVALID_FD` A file descriptor ('fd') was not valid (e.g. it was a negative value). <a id="ERR_INVALID_FD_TYPE"></a> + ### `ERR_INVALID_FD_TYPE` A file descriptor ('fd') type was not valid. <a id="ERR_INVALID_FILE_URL_HOST"></a> + ### `ERR_INVALID_FILE_URL_HOST` A Node.js API that consumes `file:` URLs (such as certain functions in the @@ -1644,6 +1839,7 @@ situation can only occur on Unix-like systems where only `localhost` or an empty host is supported. <a id="ERR_INVALID_FILE_URL_PATH"></a> + ### `ERR_INVALID_FILE_URL_PATH` A Node.js API that consumes `file:` URLs (such as certain functions in the @@ -1651,6 +1847,7 @@ A Node.js API that consumes `file:` URLs (such as certain functions in the semantics for determining whether a path can be used is platform-dependent. <a id="ERR_INVALID_HANDLE_TYPE"></a> + ### `ERR_INVALID_HANDLE_TYPE` An attempt was made to send an unsupported "handle" over an IPC communication @@ -1658,17 +1855,21 @@ channel to a child process. See [`subprocess.send()`][] and [`process.send()`][] for more information. <a id="ERR_INVALID_HTTP_TOKEN"></a> + ### `ERR_INVALID_HTTP_TOKEN` An invalid HTTP token was supplied. <a id="ERR_INVALID_IP_ADDRESS"></a> + ### `ERR_INVALID_IP_ADDRESS` An IP address is not valid. <a id="ERR_INVALID_MODULE"></a> + ### `ERR_INVALID_MODULE` + <!-- YAML added: - v15.0.0 @@ -1679,65 +1880,77 @@ An attempt was made to load a module that does not exist or was otherwise not valid. <a id="ERR_INVALID_MODULE_SPECIFIER"></a> + ### `ERR_INVALID_MODULE_SPECIFIER` The imported module string is an invalid URL, package name, or package subpath specifier. <a id="ERR_INVALID_PACKAGE_CONFIG"></a> + ### `ERR_INVALID_PACKAGE_CONFIG` An invalid [`package.json`][] file failed parsing. <a id="ERR_INVALID_PACKAGE_TARGET"></a> + ### `ERR_INVALID_PACKAGE_TARGET` The `package.json` [`"exports"`][] field contains an invalid target mapping value for the attempted module resolution. <a id="ERR_INVALID_PERFORMANCE_MARK"></a> + ### `ERR_INVALID_PERFORMANCE_MARK` While using the Performance Timing API (`perf_hooks`), a performance mark is invalid. <a id="ERR_INVALID_PROTOCOL"></a> + ### `ERR_INVALID_PROTOCOL` An invalid `options.protocol` was passed to `http.request()`. <a id="ERR_INVALID_REPL_EVAL_CONFIG"></a> + ### `ERR_INVALID_REPL_EVAL_CONFIG` Both `breakEvalOnSigint` and `eval` options were set in the [`REPL`][] config, which is not supported. <a id="ERR_INVALID_REPL_INPUT"></a> + ### `ERR_INVALID_REPL_INPUT` The input may not be used in the [`REPL`][]. The conditions under which this error is used are described in the [`REPL`][] documentation. <a id="ERR_INVALID_RETURN_PROPERTY"></a> + ### `ERR_INVALID_RETURN_PROPERTY` Thrown in case a function option does not provide a valid value for one of its returned object properties on execution. <a id="ERR_INVALID_RETURN_PROPERTY_VALUE"></a> + ### `ERR_INVALID_RETURN_PROPERTY_VALUE` Thrown in case a function option does not provide an expected value type for one of its returned object properties on execution. <a id="ERR_INVALID_RETURN_VALUE"></a> + ### `ERR_INVALID_RETURN_VALUE` Thrown in case a function option does not return an expected value type on execution, such as when a function is expected to return a promise. <a id="ERR_INVALID_STATE"></a> + ### `ERR_INVALID_STATE` + <!-- YAML added: v15.0.0 --> @@ -1747,6 +1960,7 @@ For instance, an object may have already been destroyed, or may be performing another operation. <a id="ERR_INVALID_SYNC_FORK_INPUT"></a> + ### `ERR_INVALID_SYNC_FORK_INPUT` A `Buffer`, `TypedArray`, `DataView` or `string` was provided as stdio input to @@ -1754,6 +1968,7 @@ an asynchronous fork. See the documentation for the [`child_process`][] module for more information. <a id="ERR_INVALID_THIS"></a> + ### `ERR_INVALID_THIS` A Node.js API function was called with an incompatible `this` value. @@ -1767,11 +1982,13 @@ urlSearchParams.has.call(buf, 'foo'); ``` <a id="ERR_INVALID_TRANSFER_OBJECT"></a> + ### `ERR_INVALID_TRANSFER_OBJECT` An invalid transfer object was passed to `postMessage()`. <a id="ERR_INVALID_TUPLE"></a> + ### `ERR_INVALID_TUPLE` An element in the `iterable` provided to the [WHATWG][WHATWG URL API] @@ -1780,11 +1997,13 @@ represent a `[name, value]` tuple – that is, if an element is not iterable, or does not consist of exactly two elements. <a id="ERR_INVALID_URI"></a> + ### `ERR_INVALID_URI` An invalid URI was passed. <a id="ERR_INVALID_URL"></a> + ### `ERR_INVALID_URL` An invalid URL was passed to the [WHATWG][WHATWG URL API] [`URL` @@ -1793,6 +2012,7 @@ The thrown error object typically has an additional property `'input'` that contains the URL that failed to parse. <a id="ERR_INVALID_URL_SCHEME"></a> + ### `ERR_INVALID_URL_SCHEME` An attempt was made to use a URL of an incompatible scheme (protocol) for a @@ -1801,11 +2021,13 @@ specific purpose. It is only used in the [WHATWG URL API][] support in the in other Node.js APIs as well in the future. <a id="ERR_IPC_CHANNEL_CLOSED"></a> + ### `ERR_IPC_CHANNEL_CLOSED` An attempt was made to use an IPC communication channel that was already closed. <a id="ERR_IPC_DISCONNECTED"></a> + ### `ERR_IPC_DISCONNECTED` An attempt was made to disconnect an IPC communication channel that was already @@ -1813,6 +2035,7 @@ disconnected. See the documentation for the [`child_process`][] module for more information. <a id="ERR_IPC_ONE_PIPE"></a> + ### `ERR_IPC_ONE_PIPE` An attempt was made to create a child Node.js process using more than one IPC @@ -1820,6 +2043,7 @@ communication channel. See the documentation for the [`child_process`][] module for more information. <a id="ERR_IPC_SYNC_FORK"></a> + ### `ERR_IPC_SYNC_FORK` An attempt was made to open an IPC communication channel with a synchronously @@ -1827,6 +2051,7 @@ forked Node.js process. See the documentation for the [`child_process`][] module for more information. <a id="ERR_MANIFEST_ASSERT_INTEGRITY"></a> + ### `ERR_MANIFEST_ASSERT_INTEGRITY` An attempt was made to load a resource, but the resource did not match the @@ -1834,6 +2059,7 @@ integrity defined by the policy manifest. See the documentation for [policy][] manifests for more information. <a id="ERR_MANIFEST_DEPENDENCY_MISSING"></a> + ### `ERR_MANIFEST_DEPENDENCY_MISSING` An attempt was made to load a resource, but the resource was not listed as a @@ -1841,6 +2067,7 @@ dependency from the location that attempted to load it. See the documentation for [policy][] manifests for more information. <a id="ERR_MANIFEST_INTEGRITY_MISMATCH"></a> + ### `ERR_MANIFEST_INTEGRITY_MISMATCH` An attempt was made to load a policy manifest, but the manifest had multiple @@ -1849,6 +2076,7 @@ entries to match in order to resolve this error. See the documentation for [policy][] manifests for more information. <a id="ERR_MANIFEST_INVALID_RESOURCE_FIELD"></a> + ### `ERR_MANIFEST_INVALID_RESOURCE_FIELD` A policy manifest resource had an invalid value for one of its fields. Update @@ -1856,6 +2084,7 @@ the manifest entry to match in order to resolve this error. See the documentation for [policy][] manifests for more information. <a id="ERR_MANIFEST_INVALID_SPECIFIER"></a> + ### `ERR_MANIFEST_INVALID_SPECIFIER` A policy manifest resource had an invalid value for one of its dependency @@ -1863,31 +2092,37 @@ mappings. Update the manifest entry to match to resolve this error. See the documentation for [policy][] manifests for more information. <a id="ERR_MANIFEST_PARSE_POLICY"></a> + ### `ERR_MANIFEST_PARSE_POLICY` An attempt was made to load a policy manifest, but the manifest was unable to be parsed. See the documentation for [policy][] manifests for more information. <a id="ERR_MANIFEST_TDZ"></a> + ### `ERR_MANIFEST_TDZ` An attempt was made to read from a policy manifest, but the manifest initialization has not yet taken place. This is likely a bug in Node.js. <a id="ERR_MANIFEST_UNKNOWN_ONERROR"></a> + ### `ERR_MANIFEST_UNKNOWN_ONERROR` A policy manifest was loaded, but had an unknown value for its "onerror" behavior. See the documentation for [policy][] manifests for more information. <a id="ERR_MEMORY_ALLOCATION_FAILED"></a> + ### `ERR_MEMORY_ALLOCATION_FAILED` An attempt was made to allocate memory (usually in the C++ layer) but it failed. <a id="ERR_MESSAGE_TARGET_CONTEXT_UNAVAILABLE"></a> + ### `ERR_MESSAGE_TARGET_CONTEXT_UNAVAILABLE` + <!-- YAML added: - v14.5.0 @@ -1900,11 +2135,13 @@ any context at this time, and attempting to transfer them using `postMessage()` can fail on the receiving side in that case. <a id="ERR_METHOD_NOT_IMPLEMENTED"></a> + ### `ERR_METHOD_NOT_IMPLEMENTED` A method is required but not implemented. <a id="ERR_MISSING_ARGS"></a> + ### `ERR_MISSING_ARGS` A required argument of a Node.js API was not passed. This is only used for @@ -1914,17 +2151,20 @@ strict compliance with the API specification (which in some cases may accept [`ERR_INVALID_ARG_TYPE`][] error code may be used instead. <a id="ERR_MISSING_OPTION"></a> + ### `ERR_MISSING_OPTION` For APIs that accept options objects, some options might be mandatory. This code is thrown if a required option is missing. <a id="ERR_MISSING_PASSPHRASE"></a> + ### `ERR_MISSING_PASSPHRASE` An attempt was made to read an encrypted key without specifying a passphrase. <a id="ERR_MISSING_PLATFORM_FOR_WORKER"></a> + ### `ERR_MISSING_PLATFORM_FOR_WORKER` The V8 platform used by this instance of Node.js does not support creating @@ -1932,7 +2172,9 @@ Workers. This is caused by lack of embedder support for Workers. In particular, this error will not occur with standard builds of Node.js. <a id="ERR_MISSING_TRANSFERABLE_IN_TRANSFER_LIST"></a> + ### `ERR_MISSING_TRANSFERABLE_IN_TRANSFER_LIST` + <!-- YAML added: v15.0.0 --> @@ -1947,6 +2189,7 @@ transferable object types has been expanded to cover more types than `MessagePort`. <a id="ERR_MODULE_NOT_FOUND"></a> + ### `ERR_MODULE_NOT_FOUND` > Stability: 1 - Experimental @@ -1954,6 +2197,7 @@ transferable object types has been expanded to cover more types than An [ES Module][] could not be resolved. <a id="ERR_MULTIPLE_CALLBACK"></a> + ### `ERR_MULTIPLE_CALLBACK` A callback was called more than once. @@ -1963,41 +2207,48 @@ can either be fulfilled or rejected but not both at the same time. The latter would be possible by calling a callback more than once. <a id="ERR_NAPI_CONS_FUNCTION"></a> + ### `ERR_NAPI_CONS_FUNCTION` While using `Node-API`, a constructor passed was not a function. <a id="ERR_NAPI_INVALID_DATAVIEW_ARGS"></a> + ### `ERR_NAPI_INVALID_DATAVIEW_ARGS` While calling `napi_create_dataview()`, a given `offset` was outside the bounds of the dataview or `offset + length` was larger than a length of given `buffer`. <a id="ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT"></a> + ### `ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT` While calling `napi_create_typedarray()`, the provided `offset` was not a multiple of the element size. <a id="ERR_NAPI_INVALID_TYPEDARRAY_LENGTH"></a> + ### `ERR_NAPI_INVALID_TYPEDARRAY_LENGTH` While calling `napi_create_typedarray()`, `(length * size_of_element) + byte_offset` was larger than the length of given `buffer`. <a id="ERR_NAPI_TSFN_CALL_JS"></a> + ### `ERR_NAPI_TSFN_CALL_JS` An error occurred while invoking the JavaScript portion of the thread-safe function. <a id="ERR_NAPI_TSFN_GET_UNDEFINED"></a> + ### `ERR_NAPI_TSFN_GET_UNDEFINED` An error occurred while attempting to retrieve the JavaScript `undefined` value. <a id="ERR_NAPI_TSFN_START_IDLE_LOOP"></a> + ### `ERR_NAPI_TSFN_START_IDLE_LOOP` On the main thread, values are removed from the queue associated with the @@ -2005,40 +2256,47 @@ thread-safe function in an idle loop. This error indicates that an error has occurred when attempting to start the loop. <a id="ERR_NAPI_TSFN_STOP_IDLE_LOOP"></a> + ### `ERR_NAPI_TSFN_STOP_IDLE_LOOP` Once no more items are left in the queue, the idle loop must be suspended. This error indicates that the idle loop has failed to stop. <a id="ERR_NO_CRYPTO"></a> + ### `ERR_NO_CRYPTO` An attempt was made to use crypto features while Node.js was not compiled with OpenSSL crypto support. <a id="ERR_NO_ICU"></a> + ### `ERR_NO_ICU` An attempt was made to use features that require [ICU][], but Node.js was not compiled with ICU support. <a id="ERR_NON_CONTEXT_AWARE_DISABLED"></a> + ### `ERR_NON_CONTEXT_AWARE_DISABLED` A non-context-aware native addon was loaded in a process that disallows them. <a id="ERR_OUT_OF_RANGE"></a> + ### `ERR_OUT_OF_RANGE` A given value is out of the accepted range. <a id="ERR_PACKAGE_IMPORT_NOT_DEFINED"></a> + ### `ERR_PACKAGE_IMPORT_NOT_DEFINED` The `package.json` [`"imports"`][] field does not define the given internal package specifier mapping. <a id="ERR_PACKAGE_PATH_NOT_EXPORTED"></a> + ### `ERR_PACKAGE_PATH_NOT_EXPORTED` The `package.json` [`"exports"`][] field does not export the requested subpath. @@ -2046,16 +2304,19 @@ Because exports are encapsulated, private internal modules that are not exported cannot be imported through the package resolution, unless using an absolute URL. <a id="ERR_PERFORMANCE_INVALID_TIMESTAMP"></a> + ### `ERR_PERFORMANCE_INVALID_TIMESTAMP` An invalid timestamp value was provided for a performance mark or measure. <a id="ERR_PERFORMANCE_MEASURE_INVALID_OPTIONS"></a> + ### `ERR_PERFORMANCE_MEASURE_INVALID_OPTIONS` Invalid options were provided for a performance measure. <a id="ERR_PROTO_ACCESS"></a> + ### `ERR_PROTO_ACCESS` Accessing `Object.prototype.__proto__` has been forbidden using @@ -2064,6 +2325,7 @@ Accessing `Object.prototype.__proto__` has been forbidden using object. <a id="ERR_REQUIRE_ESM"></a> + ### `ERR_REQUIRE_ESM` > Stability: 1 - Experimental @@ -2071,17 +2333,20 @@ object. An attempt was made to `require()` an [ES Module][]. <a id="ERR_SCRIPT_EXECUTION_INTERRUPTED"></a> + ### `ERR_SCRIPT_EXECUTION_INTERRUPTED` -Script execution was interrupted by `SIGINT` (For example, -<kbd>Ctrl</kbd>+<kbd>C</kbd> was pressed.) +Script execution was interrupted by `SIGINT` (For +example, <kbd>Ctrl</kbd>+<kbd>C</kbd> was pressed.) <a id="ERR_SCRIPT_EXECUTION_TIMEOUT"></a> + ### `ERR_SCRIPT_EXECUTION_TIMEOUT` Script execution timed out, possibly due to bugs in the script being executed. <a id="ERR_SERVER_ALREADY_LISTEN"></a> + ### `ERR_SERVER_ALREADY_LISTEN` The [`server.listen()`][] method was called while a `net.Server` was already @@ -2089,6 +2354,7 @@ listening. This applies to all instances of `net.Server`, including HTTP, HTTPS, and HTTP/2 `Server` instances. <a id="ERR_SERVER_NOT_RUNNING"></a> + ### `ERR_SERVER_NOT_RUNNING` The [`server.close()`][] method was called when a `net.Server` was not @@ -2096,55 +2362,65 @@ running. This applies to all instances of `net.Server`, including HTTP, HTTPS, and HTTP/2 `Server` instances. <a id="ERR_SOCKET_ALREADY_BOUND"></a> + ### `ERR_SOCKET_ALREADY_BOUND` An attempt was made to bind a socket that has already been bound. <a id="ERR_SOCKET_BAD_BUFFER_SIZE"></a> + ### `ERR_SOCKET_BAD_BUFFER_SIZE` An invalid (negative) size was passed for either the `recvBufferSize` or `sendBufferSize` options in [`dgram.createSocket()`][]. <a id="ERR_SOCKET_BAD_PORT"></a> + ### `ERR_SOCKET_BAD_PORT` An API function expecting a port >= 0 and < 65536 received an invalid value. <a id="ERR_SOCKET_BAD_TYPE"></a> + ### `ERR_SOCKET_BAD_TYPE` An API function expecting a socket type (`udp4` or `udp6`) received an invalid value. <a id="ERR_SOCKET_BUFFER_SIZE"></a> + ### `ERR_SOCKET_BUFFER_SIZE` While using [`dgram.createSocket()`][], the size of the receive or send `Buffer` could not be determined. <a id="ERR_SOCKET_CLOSED"></a> + ### `ERR_SOCKET_CLOSED` An attempt was made to operate on an already closed socket. <a id="ERR_SOCKET_DGRAM_IS_CONNECTED"></a> + ### `ERR_SOCKET_DGRAM_IS_CONNECTED` A [`dgram.connect()`][] call was made on an already connected socket. <a id="ERR_SOCKET_DGRAM_NOT_CONNECTED"></a> + ### `ERR_SOCKET_DGRAM_NOT_CONNECTED` A [`dgram.disconnect()`][] or [`dgram.remoteAddress()`][] call was made on a disconnected socket. <a id="ERR_SOCKET_DGRAM_NOT_RUNNING"></a> + ### `ERR_SOCKET_DGRAM_NOT_RUNNING` A call was made and the UDP subsystem was not running. <a id="ERR_SRI_PARSE"></a> + ### `ERR_SRI_PARSE` A string was provided for a Subresource Integrity check, but was unable to be @@ -2152,46 +2428,54 @@ parsed. Check the format of integrity attributes by looking at the [Subresource Integrity specification][]. <a id="ERR_STREAM_ALREADY_FINISHED"></a> + ### `ERR_STREAM_ALREADY_FINISHED` A stream method was called that cannot complete because the stream was finished. <a id="ERR_STREAM_CANNOT_PIPE"></a> + ### `ERR_STREAM_CANNOT_PIPE` An attempt was made to call [`stream.pipe()`][] on a [`Writable`][] stream. <a id="ERR_STREAM_DESTROYED"></a> + ### `ERR_STREAM_DESTROYED` A stream method was called that cannot complete because the stream was destroyed using `stream.destroy()`. <a id="ERR_STREAM_NULL_VALUES"></a> + ### `ERR_STREAM_NULL_VALUES` An attempt was made to call [`stream.write()`][] with a `null` chunk. <a id="ERR_STREAM_PREMATURE_CLOSE"></a> + ### `ERR_STREAM_PREMATURE_CLOSE` An error returned by `stream.finished()` and `stream.pipeline()`, when a stream or a pipeline ends non gracefully with no explicit error. <a id="ERR_STREAM_PUSH_AFTER_EOF"></a> + ### `ERR_STREAM_PUSH_AFTER_EOF` An attempt was made to call [`stream.push()`][] after a `null`(EOF) had been pushed to the stream. <a id="ERR_STREAM_UNSHIFT_AFTER_END_EVENT"></a> + ### `ERR_STREAM_UNSHIFT_AFTER_END_EVENT` An attempt was made to call [`stream.unshift()`][] after the `'end'` event was emitted. <a id="ERR_STREAM_WRAP"></a> + ### `ERR_STREAM_WRAP` Prevents an abort if a string decoder was set on the Socket or if the decoder @@ -2205,24 +2489,28 @@ instance.setEncoding('utf8'); ``` <a id="ERR_STREAM_WRITE_AFTER_END"></a> + ### `ERR_STREAM_WRITE_AFTER_END` An attempt was made to call [`stream.write()`][] after `stream.end()` has been called. <a id="ERR_STRING_TOO_LONG"></a> + ### `ERR_STRING_TOO_LONG` An attempt has been made to create a string longer than the maximum allowed length. <a id="ERR_SYNTHETIC"></a> + ### `ERR_SYNTHETIC` An artificial error object used to capture the call stack for diagnostic reports. <a id="ERR_SYSTEM_ERROR"></a> + ### `ERR_SYSTEM_ERROR` An unspecified or non-specific system error has occurred within the Node.js @@ -2230,12 +2518,14 @@ process. The error object will have an `err.info` object property with additional details. <a id="ERR_TLS_CERT_ALTNAME_INVALID"></a> + ### `ERR_TLS_CERT_ALTNAME_INVALID` While using TLS, the host name/IP of the peer did not match any of the `subjectAltNames` in its certificate. <a id="ERR_TLS_DH_PARAM_SIZE"></a> + ### `ERR_TLS_DH_PARAM_SIZE` While using TLS, the parameter offered for the Diffie-Hellman (`DH`) @@ -2244,13 +2534,16 @@ than or equal to 1024 bits to avoid vulnerabilities, even though it is strongly recommended to use 2048 bits or larger for stronger security. <a id="ERR_TLS_HANDSHAKE_TIMEOUT"></a> + ### `ERR_TLS_HANDSHAKE_TIMEOUT` A TLS/SSL handshake timed out. In this case, the server must also abort the connection. <a id="ERR_TLS_INVALID_CONTEXT"></a> + ### `ERR_TLS_INVALID_CONTEXT` + <!-- YAML added: v13.3.0 --> @@ -2258,18 +2551,22 @@ added: v13.3.0 The context must be a `SecureContext`. <a id="ERR_TLS_INVALID_PROTOCOL_METHOD"></a> + ### `ERR_TLS_INVALID_PROTOCOL_METHOD` The specified `secureProtocol` method is invalid. It is either unknown, or disabled because it is insecure. <a id="ERR_TLS_INVALID_PROTOCOL_VERSION"></a> + ### `ERR_TLS_INVALID_PROTOCOL_VERSION` Valid TLS protocol versions are `'TLSv1'`, `'TLSv1.1'`, or `'TLSv1.2'`. <a id="ERR_TLS_INVALID_STATE"></a> + ### `ERR_TLS_INVALID_STATE` + <!-- YAML added: - v13.10.0 @@ -2280,73 +2577,86 @@ The TLS socket must be connected and securily established. Ensure the 'secure' event is emitted before continuing. <a id="ERR_TLS_PROTOCOL_VERSION_CONFLICT"></a> + ### `ERR_TLS_PROTOCOL_VERSION_CONFLICT` Attempting to set a TLS protocol `minVersion` or `maxVersion` conflicts with an attempt to set the `secureProtocol` explicitly. Use one mechanism or the other. <a id="ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED"></a> + ### `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` Failed to set PSK identity hint. Hint may be too long. <a id="ERR_TLS_RENEGOTIATION_DISABLED"></a> + ### `ERR_TLS_RENEGOTIATION_DISABLED` An attempt was made to renegotiate TLS on a socket instance with TLS disabled. <a id="ERR_TLS_REQUIRED_SERVER_NAME"></a> + ### `ERR_TLS_REQUIRED_SERVER_NAME` While using TLS, the `server.addContext()` method was called without providing a host name in the first parameter. <a id="ERR_TLS_SESSION_ATTACK"></a> + ### `ERR_TLS_SESSION_ATTACK` An excessive amount of TLS renegotiations is detected, which is a potential vector for denial-of-service attacks. <a id="ERR_TLS_SNI_FROM_SERVER"></a> + ### `ERR_TLS_SNI_FROM_SERVER` An attempt was made to issue Server Name Indication from a TLS server-side socket, which is only valid from a client. <a id="ERR_TRACE_EVENTS_CATEGORY_REQUIRED"></a> + ### `ERR_TRACE_EVENTS_CATEGORY_REQUIRED` The `trace_events.createTracing()` method requires at least one trace event category. <a id="ERR_TRACE_EVENTS_UNAVAILABLE"></a> + ### `ERR_TRACE_EVENTS_UNAVAILABLE` The `trace_events` module could not be loaded because Node.js was compiled with the `--without-v8-platform` flag. <a id="ERR_TRANSFORM_ALREADY_TRANSFORMING"></a> + ### `ERR_TRANSFORM_ALREADY_TRANSFORMING` A `Transform` stream finished while it was still transforming. <a id="ERR_TRANSFORM_WITH_LENGTH_0"></a> + ### `ERR_TRANSFORM_WITH_LENGTH_0` A `Transform` stream finished with data still in the write buffer. <a id="ERR_TTY_INIT_FAILED"></a> + ### `ERR_TTY_INIT_FAILED` The initialization of a TTY failed due to a system error. <a id="ERR_UNAVAILABLE_DURING_EXIT"></a> + ### `ERR_UNAVAILABLE_DURING_EXIT` Function was called within a [`process.on('exit')`][] handler that shouldn't be called within [`process.on('exit')`][] handler. <a id="ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET"></a> + ### `ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET` [`process.setUncaughtExceptionCaptureCallback()`][] was called twice, @@ -2356,17 +2666,20 @@ This error is designed to prevent accidentally overwriting a callback registered from another module. <a id="ERR_UNESCAPED_CHARACTERS"></a> + ### `ERR_UNESCAPED_CHARACTERS` A string that contained unescaped characters was received. <a id="ERR_UNHANDLED_ERROR"></a> + ### `ERR_UNHANDLED_ERROR` An unhandled error occurred (for instance, when an `'error'` event is emitted by an [`EventEmitter`][] but an `'error'` handler is not registered). <a id="ERR_UNKNOWN_BUILTIN_MODULE"></a> + ### `ERR_UNKNOWN_BUILTIN_MODULE` Used to identify a specific kind of internal Node.js error that should not @@ -2374,16 +2687,19 @@ typically be triggered by user code. Instances of this error point to an internal bug within the Node.js binary itself. <a id="ERR_UNKNOWN_CREDENTIAL"></a> + ### `ERR_UNKNOWN_CREDENTIAL` A Unix group or user identifier that does not exist was passed. <a id="ERR_UNKNOWN_ENCODING"></a> + ### `ERR_UNKNOWN_ENCODING` An invalid or unknown encoding option was passed to an API. <a id="ERR_UNKNOWN_FILE_EXTENSION"></a> + ### `ERR_UNKNOWN_FILE_EXTENSION` > Stability: 1 - Experimental @@ -2392,6 +2708,7 @@ An attempt was made to load a module with an unknown or unsupported file extension. <a id="ERR_UNKNOWN_MODULE_FORMAT"></a> + ### `ERR_UNKNOWN_MODULE_FORMAT` > Stability: 1 - Experimental @@ -2399,12 +2716,14 @@ extension. An attempt was made to load a module with an unknown or unsupported format. <a id="ERR_UNKNOWN_SIGNAL"></a> + ### `ERR_UNKNOWN_SIGNAL` An invalid or unknown process signal was passed to an API expecting a valid signal (such as [`subprocess.kill()`][]). <a id="ERR_UNSUPPORTED_DIR_IMPORT"></a> + ### `ERR_UNSUPPORTED_DIR_IMPORT` `import` a directory URL is unsupported. Instead, @@ -2412,6 +2731,7 @@ signal (such as [`subprocess.kill()`][]). the [`"exports"`][] field of the [`package.json`][] file. <!-- eslint-skip --> + ```js import './'; // unsupported import './index.js'; // supported @@ -2419,22 +2739,26 @@ import 'package-name'; // supported ``` <a id="ERR_UNSUPPORTED_ESM_URL_SCHEME"></a> + ### `ERR_UNSUPPORTED_ESM_URL_SCHEME` `import` with URL schemes other than `file` and `data` is unsupported. <a id="ERR_VALID_PERFORMANCE_ENTRY_TYPE"></a> + ### `ERR_VALID_PERFORMANCE_ENTRY_TYPE` While using the Performance Timing API (`perf_hooks`), no valid performance entry types are found. <a id="ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING"></a> + ### `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING` A dynamic import callback was not specified. <a id="ERR_VM_MODULE_ALREADY_LINKED"></a> + ### `ERR_VM_MODULE_ALREADY_LINKED` The module attempted to be linked is not eligible for linking, because of one of @@ -2445,96 +2769,115 @@ the following reasons: * Linking has failed for this module (`linkingStatus` is `'errored'`) <a id="ERR_VM_MODULE_CACHED_DATA_REJECTED"></a> + ### `ERR_VM_MODULE_CACHED_DATA_REJECTED` The `cachedData` option passed to a module constructor is invalid. <a id="ERR_VM_MODULE_CANNOT_CREATE_CACHED_DATA"></a> + ### `ERR_VM_MODULE_CANNOT_CREATE_CACHED_DATA` Cached data cannot be created for modules which have already been evaluated. <a id="ERR_VM_MODULE_DIFFERENT_CONTEXT"></a> + ### `ERR_VM_MODULE_DIFFERENT_CONTEXT` The module being returned from the linker function is from a different context than the parent module. Linked modules must share the same context. <a id="ERR_VM_MODULE_LINKING_ERRORED"></a> + ### `ERR_VM_MODULE_LINKING_ERRORED` The linker function returned a module for which linking has failed. <a id="ERR_VM_MODULE_LINK_FAILURE"></a> + ### `ERR_VM_MODULE_LINK_FAILURE` The module was unable to be linked due to a failure. <a id="ERR_VM_MODULE_NOT_MODULE"></a> + ### `ERR_VM_MODULE_NOT_MODULE` The fulfilled value of a linking promise is not a `vm.Module` object. <a id="ERR_VM_MODULE_STATUS"></a> + ### `ERR_VM_MODULE_STATUS` The current module's status does not allow for this operation. The specific meaning of the error depends on the specific function. <a id="ERR_WASI_ALREADY_STARTED"></a> + ### `ERR_WASI_ALREADY_STARTED` The WASI instance has already started. <a id="ERR_WASI_NOT_STARTED"></a> + ### `ERR_WASI_NOT_STARTED` The WASI instance has not been started. <a id="ERR_WORKER_INIT_FAILED"></a> + ### `ERR_WORKER_INIT_FAILED` The `Worker` initialization failed. <a id="ERR_WORKER_INVALID_EXEC_ARGV"></a> + ### `ERR_WORKER_INVALID_EXEC_ARGV` The `execArgv` option passed to the `Worker` constructor contains invalid flags. <a id="ERR_WORKER_NOT_RUNNING"></a> + ### `ERR_WORKER_NOT_RUNNING` An operation failed because the `Worker` instance is not currently running. <a id="ERR_WORKER_OUT_OF_MEMORY"></a> + ### `ERR_WORKER_OUT_OF_MEMORY` The `Worker` instance terminated because it reached its memory limit. <a id="ERR_WORKER_PATH"></a> + ### `ERR_WORKER_PATH` The path for the main script of a worker is neither an absolute path nor a relative path starting with `./` or `../`. <a id="ERR_WORKER_UNSERIALIZABLE_ERROR"></a> + ### `ERR_WORKER_UNSERIALIZABLE_ERROR` All attempts at serializing an uncaught exception from a worker thread failed. <a id="ERR_WORKER_UNSUPPORTED_OPERATION"></a> + ### `ERR_WORKER_UNSUPPORTED_OPERATION` The requested functionality is not supported in worker threads. <a id="ERR_ZLIB_INITIALIZATION_FAILED"></a> + ### `ERR_ZLIB_INITIALIZATION_FAILED` Creation of a [`zlib`][] object failed due to incorrect configuration. <a id="HPE_HEADER_OVERFLOW"></a> + ### `HPE_HEADER_OVERFLOW` + <!-- YAML changes: - version: @@ -2551,6 +2894,7 @@ HTTP parsing will abort without a request or response object being created, and an `Error` with this code will be emitted. <a id="HPE_UNEXPECTED_CONTENT_LENGTH"></a> + ### `HPE_UNEXPECTED_CONTENT_LENGTH` Server is sending both a `Content-Length` header and `Transfer-Encoding: chunked`. @@ -2562,13 +2906,16 @@ In this case, the `Content-Length` HTTP header cannot be used. Use `Content-Length` or `Transfer-Encoding: chunked`. <a id="MODULE_NOT_FOUND"></a> + ### `MODULE_NOT_FOUND` + <!-- YAML changes: - version: v12.0.0 pr-url: https://github.com/nodejs/node/pull/25690 description: Added `requireStack` property. --> + A module file could not be resolved while attempting a [`require()`][] or `import` operation. @@ -2578,7 +2925,9 @@ A module file could not be resolved while attempting a [`require()`][] or > been removed. <a id="ERR_CANNOT_TRANSFER_OBJECT"></a> + ### `ERR_CANNOT_TRANSFER_OBJECT` + <!-- added: v10.5.0 removed: v12.5.0 @@ -2588,7 +2937,9 @@ The value passed to `postMessage()` contained an object that is not supported for transferring. <a id="ERR_CRYPTO_HASH_DIGEST_NO_UTF16"></a> + ### `ERR_CRYPTO_HASH_DIGEST_NO_UTF16` + <!-- YAML added: v9.0.0 removed: v12.12.0 @@ -2600,7 +2951,9 @@ causing the method to return a string rather than a `Buffer`, the UTF-16 encoding (e.g. `ucs` or `utf16le`) is not supported. <a id="ERR_HTTP2_FRAME_ERROR"></a> + ### `ERR_HTTP2_FRAME_ERROR` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2610,7 +2963,9 @@ Used when a failure occurs sending an individual frame on the HTTP/2 session. <a id="ERR_HTTP2_HEADERS_OBJECT"></a> + ### `ERR_HTTP2_HEADERS_OBJECT` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2619,7 +2974,9 @@ removed: v10.0.0 Used when an HTTP/2 Headers Object is expected. <a id="ERR_HTTP2_HEADER_REQUIRED"></a> + ### `ERR_HTTP2_HEADER_REQUIRED` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2628,17 +2985,21 @@ removed: v10.0.0 Used when a required header is missing in an HTTP/2 message. <a id="ERR_HTTP2_INFO_HEADERS_AFTER_RESPOND"></a> + ### `ERR_HTTP2_INFO_HEADERS_AFTER_RESPOND` + <!-- YAML added: v9.0.0 removed: v10.0.0 --> -HTTP/2 informational headers must only be sent *prior* to calling the +HTTP/2 informational headers must only be sent _prior_ to calling the `Http2Stream.prototype.respond()` method. <a id="ERR_HTTP2_STREAM_CLOSED"></a> + ### `ERR_HTTP2_STREAM_CLOSED` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2648,7 +3009,9 @@ Used when an action has been performed on an HTTP/2 Stream that has already been closed. <a id="ERR_HTTP_INVALID_CHAR"></a> + ### `ERR_HTTP_INVALID_CHAR` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2658,15 +3021,20 @@ Used when an invalid character is found in an HTTP response status message (reason phrase). <a id="ERR_INDEX_OUT_OF_RANGE"></a> + ### `ERR_INDEX_OUT_OF_RANGE` + <!-- YAML added: v10.0.0 removed: v11.0.0 --> + A given index was out of the accepted range (e.g. negative offsets). <a id="ERR_INVALID_OPT_VALUE"></a> + ### `ERR_INVALID_OPT_VALUE` + <!-- YAML added: v8.0.0 removed: v15.0.0 @@ -2675,7 +3043,9 @@ removed: v15.0.0 An invalid or unexpected value was passed in an options object. <a id="ERR_INVALID_OPT_VALUE_ENCODING"></a> + ### `ERR_INVALID_OPT_VALUE_ENCODING` + <!-- YAML added: v9.0.0 removed: v15.0.0 @@ -2684,7 +3054,9 @@ removed: v15.0.0 An invalid or unknown file encoding was passed. <a id="ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST"></a> + ### `ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST` + <!-- YAML removed: v15.0.0 --> @@ -2694,7 +3066,9 @@ in Node.js v15.0.0, because it is no longer accurate as other types of transferable objects also exist now. <a id="ERR_NAPI_CONS_PROTOTYPE_OBJECT"></a> + ### `ERR_NAPI_CONS_PROTOTYPE_OBJECT` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2703,13 +3077,16 @@ removed: v10.0.0 Used by the `Node-API` when `Constructor.prototype` is not an object. <a id="ERR_NO_LONGER_SUPPORTED"></a> + ### `ERR_NO_LONGER_SUPPORTED` A Node.js API was called in an unsupported manner, such as `Buffer.write(string, encoding, offset[, length])`. <a id="ERR_OPERATION_FAILED"></a> + ### `ERR_OPERATION_FAILED` + <!-- YAML added: v15.0.0 --> @@ -2718,7 +3095,9 @@ An operation failed. This is typically used to signal the general failure of an asynchronous operation. <a id="ERR_OUTOFMEMORY"></a> + ### `ERR_OUTOFMEMORY` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2728,7 +3107,9 @@ Used generically to identify that an operation caused an out of memory condition. <a id="ERR_PARSE_HISTORY_DATA"></a> + ### `ERR_PARSE_HISTORY_DATA` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2737,7 +3118,9 @@ removed: v10.0.0 The `repl` module was unable to parse data from the REPL history file. <a id="ERR_SOCKET_CANNOT_SEND"></a> + ### `ERR_SOCKET_CANNOT_SEND` + <!-- YAML added: v9.0.0 removed: v14.0.0 @@ -2746,7 +3129,9 @@ removed: v14.0.0 Data could not be sent on a socket. <a id="ERR_STDERR_CLOSE"></a> + ### `ERR_STDERR_CLOSE` + <!-- YAML removed: v10.12.0 changes: @@ -2761,7 +3146,9 @@ An attempt was made to close the `process.stderr` stream. By design, Node.js does not allow `stdout` or `stderr` streams to be closed by user code. <a id="ERR_STDOUT_CLOSE"></a> + ### `ERR_STDOUT_CLOSE` + <!-- YAML removed: v10.12.0 changes: @@ -2776,7 +3163,9 @@ An attempt was made to close the `process.stdout` stream. By design, Node.js does not allow `stdout` or `stderr` streams to be closed by user code. <a id="ERR_STREAM_READ_NOT_IMPLEMENTED"></a> + ### `ERR_STREAM_READ_NOT_IMPLEMENTED` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2786,7 +3175,9 @@ Used when an attempt is made to use a readable stream that has not implemented [`readable._read()`][]. <a id="ERR_TLS_RENEGOTIATION_FAILED"></a> + ### `ERR_TLS_RENEGOTIATION_FAILED` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2795,7 +3186,9 @@ removed: v10.0.0 Used when a TLS renegotiation request has failed in a non-specific way. <a id="ERR_TRANSFERRING_EXTERNALIZED_SHAREDARRAYBUFFER"></a> + ### `ERR_TRANSFERRING_EXTERNALIZED_SHAREDARRAYBUFFER` + <!-- YAML added: v10.5.0 removed: v14.0.0 @@ -2809,7 +3202,9 @@ This can only happen when native addons create `SharedArrayBuffer`s in "externalized" mode, or put existing `SharedArrayBuffer` into externalized mode. <a id="ERR_UNKNOWN_STDIN_TYPE"></a> + ### `ERR_UNKNOWN_STDIN_TYPE` + <!-- YAML added: v8.0.0 removed: v11.7.0 @@ -2820,7 +3215,9 @@ type. This error is usually an indication of a bug within Node.js itself, although it is possible for user code to trigger it. <a id="ERR_UNKNOWN_STREAM_TYPE"></a> + ### `ERR_UNKNOWN_STREAM_TYPE` + <!-- YAML added: v8.0.0 removed: v11.7.0 @@ -2831,12 +3228,15 @@ An attempt was made to launch a Node.js process with an unknown `stdout` or itself, although it is possible for user code to trigger it. <a id="ERR_V8BREAKITERATOR"></a> + ### `ERR_V8BREAKITERATOR` The V8 `BreakIterator` API was used but the full ICU data set is not installed. <a id="ERR_VALUE_OUT_OF_RANGE"></a> + ### `ERR_VALUE_OUT_OF_RANGE` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2845,12 +3245,15 @@ removed: v10.0.0 Used when a given value is out of the accepted range. <a id="ERR_VM_MODULE_NOT_LINKED"></a> + ### `ERR_VM_MODULE_NOT_LINKED` The module must be successfully linked before instantiation. <a id="ERR_WORKER_UNSUPPORTED_EXTENSION"></a> + ### `ERR_WORKER_UNSUPPORTED_EXTENSION` + <!-- YAML added: v11.0.0 removed: v16.9.0 @@ -2860,7 +3263,9 @@ The pathname used for the main script of a worker has an unknown file extension. <a id="ERR_ZLIB_BINDING_CLOSED"></a> + ### `ERR_ZLIB_BINDING_CLOSED` + <!-- YAML added: v9.0.0 removed: v10.0.0 @@ -2870,7 +3275,9 @@ Used when an attempt is made to use a `zlib` object after it has already been closed. <a id="ERR_CPU_USAGE"></a> + ### `ERR_CPU_USAGE` + <!-- YAML removed: v15.0.0 --> diff --git a/doc/api/esm.md b/doc/api/esm.md index 80c67ef602a..04f8fe28135 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -83,9 +83,8 @@ provides interoperability between them and its original module format, [CommonJS][]. <!-- Anchors to make sure old links find a target --> -<i id="esm_package_json_type_field"></i> -<i id="esm_package_scope_and_file_extensions"></i> -<i id="esm_input_type_flag"></i> + +<i id="esm_package_json_type_field"></i><i id="esm_package_scope_and_file_extensions"></i><i id="esm_input_type_flag"></i> ## Enabling @@ -99,20 +98,8 @@ via the `.mjs` file extension, the `package.json` [`"type"`][] field, or the details. <!-- Anchors to make sure old links find a target --> -<i id="esm_package_entry_points"></i> -<i id="esm_main_entry_point_export"></i> -<i id="esm_subpath_exports"></i> -<i id="esm_package_exports_fallbacks"></i> -<i id="esm_exports_sugar"></i> -<i id="esm_conditional_exports"></i> -<i id="esm_nested_conditions"></i> -<i id="esm_self_referencing_a_package_using_its_name"></i> -<i id="esm_internal_package_imports"></i> -<i id="esm_dual_commonjs_es_module_packages"></i> -<i id="esm_dual_package_hazard"></i> -<i id="esm_writing_dual_packages_while_avoiding_or_minimizing_hazards"></i> -<i id="esm_approach_1_use_an_es_module_wrapper"></i> -<i id="esm_approach_2_isolate_state"></i> + +<i id="esm_package_entry_points"></i><i id="esm_main_entry_point_export"></i><i id="esm_subpath_exports"></i><i id="esm_package_exports_fallbacks"></i><i id="esm_exports_sugar"></i><i id="esm_conditional_exports"></i><i id="esm_nested_conditions"></i><i id="esm_self_referencing_a_package_using_its_name"></i><i id="esm_internal_package_imports"></i><i id="esm_dual_commonjs_es_module_packages"></i><i id="esm_dual_package_hazard"></i><i id="esm_writing_dual_packages_while_avoiding_or_minimizing_hazards"></i><i id="esm_approach_1_use_an_es_module_wrapper"></i><i id="esm_approach_2_isolate_state"></i> ## Packages @@ -294,6 +281,7 @@ const buffer = readFileSync(new URL('./data.proto', import.meta.url)); ``` ### `import.meta.resolve(specifier[, parent])` + <!-- added: - v13.9.0 @@ -320,6 +308,7 @@ Provides a module-relative resolution function scoped to each module, returning the URL string. <!-- eslint-skip --> + ```js const dependencyAsset = await import.meta.resolve('component-lib/asset.css'); ``` @@ -328,6 +317,7 @@ const dependencyAsset = await import.meta.resolve('component-lib/asset.css'); from which to resolve from: <!-- eslint-skip --> + ```js await import.meta.resolve('./dep', import.meta.url); ``` @@ -364,6 +354,7 @@ When importing a CommonJS module, it can be reliably imported using the ES module default import or its corresponding sugar syntax: <!-- eslint-disable no-duplicate-imports --> + ```js import { default as cjs } from 'cjs'; @@ -386,6 +377,7 @@ This Module Namespace Exotic Object can be directly observed either when using `import * as m from 'cjs'` or a dynamic import: <!-- eslint-skip --> + ```js import * as m from 'cjs'; console.log(m); @@ -410,6 +402,7 @@ exports.name = 'exported'; The preceding module supports named imports in ES modules: <!-- eslint-disable no-duplicate-imports --> + ```js import { name } from './cjs.cjs'; console.log(name); @@ -463,6 +456,7 @@ JSON imports are still experimental and only supported via the Local JSON files can be loaded relative to `import.meta.url` with `fs` directly: <!-- eslint-skip --> + ```js import { readFile } from 'fs/promises'; const json = JSON.parse(await readFile(new URL('./dat.json', import.meta.url))); @@ -523,6 +517,7 @@ same path. Assuming an `index.mjs` with <!-- eslint-skip --> + ```js import packageConfig from './package.json'; ``` @@ -575,6 +570,7 @@ within modules as per the [ECMAScript Top-Level `await` proposal][]. Assuming an `a.mjs` with <!-- eslint-skip --> + ```js export const five = await Promise.resolve(5); ``` @@ -616,7 +612,7 @@ CommonJS modules loaded. * `specifier` {string} * `context` {Object} - * `conditions` {string[]} + * `conditions` {string\[]} * `parentURL` {string|undefined} * `defaultResolve` {Function} The Node.js default resolver. * Returns: {Object} @@ -1025,16 +1021,16 @@ The resolver has the following properties: * Relative and absolute URL resolution * No default extensions * No folder mains -* Bare specifier package resolution lookup through node_modules +* Bare specifier package resolution lookup through node\_modules ### Resolver algorithm The algorithm to load an ES module specifier is given through the -**ESM_RESOLVE** method below. It returns the resolved URL for a +**ESM\_RESOLVE** method below. It returns the resolved URL for a module specifier relative to a parentURL. The algorithm to determine the module format of a resolved URL is -provided by **ESM_FORMAT**, which returns the unique module +provided by **ESM\_FORMAT**, which returns the unique module format for any file. The _"module"_ format is returned for an ECMAScript Module, while the _"commonjs"_ format is used to indicate loading through the legacy CommonJS loader. Additional formats such as _"addon"_ can be extended in @@ -1047,6 +1043,7 @@ _defaultConditions_ is the conditional environment name array, `["node", "import"]`. The resolver can throw the following errors: + * _Invalid Module Specifier_: Module specifier is an invalid URL, package name or package subpath specifier. * _Invalid Package Configuration_: package.json configuration is invalid or @@ -1062,261 +1059,263 @@ The resolver can throw the following errors: ### Resolver Algorithm Specification -**ESM_RESOLVE**(_specifier_, _parentURL_) +**ESM\_RESOLVE**(_specifier_, _parentURL_) > 1. Let _resolved_ be **undefined**. -> 1. If _specifier_ is a valid URL, then +> 2. If _specifier_ is a valid URL, then > 1. Set _resolved_ to the result of parsing and reserializing > _specifier_ as a URL. -> 1. Otherwise, if _specifier_ starts with _"/"_, _"./"_ or _"../"_, then +> 3. Otherwise, if _specifier_ starts with _"/"_, _"./"_ or _"../"_, then > 1. Set _resolved_ to the URL resolution of _specifier_ relative to > _parentURL_. -> 1. Otherwise, if _specifier_ starts with _"#"_, then -> 1. Set _resolved_ to the result of **PACKAGE_IMPORTS_RESOLVE**(_specifier_, +> 4. Otherwise, if _specifier_ starts with _"#"_, then +> 1. Set _resolved_ to the result of +> **PACKAGE\_IMPORTS\_RESOLVE**(_specifier_, > _parentURL_, _defaultConditions_). -> 1. Otherwise, +> 5. Otherwise, > 1. Note: _specifier_ is now a bare specifier. -> 1. Set _resolved_ the result of -> **PACKAGE_RESOLVE**(_specifier_, _parentURL_). -> 1. If _resolved_ contains any percent encodings of _"/"_ or _"\\"_ (_"%2f"_ +> 2. Set _resolved_ the result of +> **PACKAGE\_RESOLVE**(_specifier_, _parentURL_). +> 6. If _resolved_ contains any percent encodings of _"/"_ or _"\\"_ (_"%2f"_ > and _"%5C"_ respectively), then > 1. Throw an _Invalid Module Specifier_ error. -> 1. If the file at _resolved_ is a directory, then +> 7. If the file at _resolved_ is a directory, then > 1. Throw an _Unsupported Directory Import_ error. -> 1. If the file at _resolved_ does not exist, then +> 8. If the file at _resolved_ does not exist, then > 1. Throw a _Module Not Found_ error. -> 1. Set _resolved_ to the real path of _resolved_. -> 1. Let _format_ be the result of **ESM_FORMAT**(_resolved_). -> 1. Load _resolved_ as module format, _format_. -> 1. Return _resolved_. +> 9. Set _resolved_ to the real path of _resolved_. +> 10. Let _format_ be the result of **ESM\_FORMAT**(_resolved_). +> 11. Load _resolved_ as module format, _format_. +> 12. Return _resolved_. -**PACKAGE_RESOLVE**(_packageSpecifier_, _parentURL_) +**PACKAGE\_RESOLVE**(_packageSpecifier_, _parentURL_) > 1. Let _packageName_ be **undefined**. -> 1. If _packageSpecifier_ is an empty string, then +> 2. If _packageSpecifier_ is an empty string, then > 1. Throw an _Invalid Module Specifier_ error. -> 1. If _packageSpecifier_ does not start with _"@"_, then +> 3. If _packageSpecifier_ does not start with _"@"_, then > 1. Set _packageName_ to the substring of _packageSpecifier_ until the first > _"/"_ separator or the end of the string. -> 1. Otherwise, +> 4. Otherwise, > 1. If _packageSpecifier_ does not contain a _"/"_ separator, then > 1. Throw an _Invalid Module Specifier_ error. -> 1. Set _packageName_ to the substring of _packageSpecifier_ +> 2. Set _packageName_ to the substring of _packageSpecifier_ > until the second _"/"_ separator or the end of the string. -> 1. If _packageName_ starts with _"."_ or contains _"\\"_ or _"%"_, then +> 5. If _packageName_ starts with _"."_ or contains _"\\"_ or _"%"_, then > 1. Throw an _Invalid Module Specifier_ error. -> 1. Let _packageSubpath_ be _"."_ concatenated with the substring of +> 6. Let _packageSubpath_ be _"."_ concatenated with the substring of > _packageSpecifier_ from the position at the length of _packageName_. -> 1. If _packageSubpath_ ends in _"/"_, then +> 7. If _packageSubpath_ ends in _"/"_, then > 1. Throw an _Invalid Module Specifier_ error. -> 1. Let _selfUrl_ be the result of -> **PACKAGE_SELF_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_). -> 1. If _selfUrl_ is not **undefined**, return _selfUrl_. -> 1. If _packageSubpath_ is _"."_ and _packageName_ is a Node.js builtin -> module, then -> 1. Return the string _"node:"_ concatenated with _packageSpecifier_. -> 1. While _parentURL_ is not the file system root, -> 1. Let _packageURL_ be the URL resolution of _"node_modules/"_ -> concatenated with _packageSpecifier_, relative to _parentURL_. -> 1. Set _parentURL_ to the parent folder URL of _parentURL_. -> 1. If the folder at _packageURL_ does not exist, then -> 1. Continue the next loop iteration. -> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). -> 1. If _pjson_ is not **null** and _pjson_._exports_ is not **null** or -> **undefined**, then -> 1. Return the result of **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, -> _packageSubpath_, _pjson.exports_, _defaultConditions_). -> 1. Otherwise, if _packageSubpath_ is equal to _"."_, then -> 1. If _pjson.main_ is a string, then -> 1. Return the URL resolution of _main_ in _packageURL_. -> 1. Otherwise, -> 1. Return the URL resolution of _packageSubpath_ in _packageURL_. -> 1. Throw a _Module Not Found_ error. - -**PACKAGE_SELF_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_) - -> 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_). -> 1. If _packageURL_ is **null**, then +> 8. Let _selfUrl_ be the result of +> **PACKAGE\_SELF\_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_). +> 9. If _selfUrl_ is not **undefined**, return _selfUrl_. +> 10. If _packageSubpath_ is _"."_ and _packageName_ is a Node.js builtin +> module, then +> 1. Return the string _"node:"_ concatenated with _packageSpecifier_. +> 11. While _parentURL_ is not the file system root, +> 1. Let _packageURL_ be the URL resolution of _"node\_modules/"_ +> concatenated with _packageSpecifier_, relative to _parentURL_. +> 2. Set _parentURL_ to the parent folder URL of _parentURL_. +> 3. If the folder at _packageURL_ does not exist, then +> 1. Continue the next loop iteration. +> 4. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_). +> 5. If _pjson_ is not **null** and _pjson_._exports_ is not **null** or +> **undefined**, then +> 1. Return the result of **PACKAGE\_EXPORTS\_RESOLVE**(_packageURL_, +> _packageSubpath_, _pjson.exports_, _defaultConditions_). +> 6. Otherwise, if _packageSubpath_ is equal to _"."_, then +> 1. If _pjson.main_ is a string, then +> 1. Return the URL resolution of _main_ in _packageURL_. +> 7. Otherwise, +> 1. Return the URL resolution of _packageSubpath_ in _packageURL_. +> 12. Throw a _Module Not Found_ error. + +**PACKAGE\_SELF\_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_) + +> 1. Let _packageURL_ be the result of **READ\_PACKAGE\_SCOPE**(_parentURL_). +> 2. If _packageURL_ is **null**, then > 1. Return **undefined**. -> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). -> 1. If _pjson_ is **null** or if _pjson_._exports_ is **null** or +> 3. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_). +> 4. If _pjson_ is **null** or if _pjson_._exports_ is **null** or > **undefined**, then > 1. Return **undefined**. -> 1. If _pjson.name_ is equal to _packageName_, then -> 1. Return the result of **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, +> 5. If _pjson.name_ is equal to _packageName_, then +> 1. Return the result of **PACKAGE\_EXPORTS\_RESOLVE**(_packageURL_, > _packageSubpath_, _pjson.exports_, _defaultConditions_). -> 1. Otherwise, return **undefined**. +> 6. Otherwise, return **undefined**. -**PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _subpath_, _exports_, _conditions_) +**PACKAGE\_EXPORTS\_RESOLVE**(_packageURL_, _subpath_, _exports_, _conditions_) > 1. If _exports_ is an Object with both a key starting with _"."_ and a key not > starting with _"."_, throw an _Invalid Package Configuration_ error. -> 1. If _subpath_ is equal to _"."_, then +> 2. If _subpath_ is equal to _"."_, then > 1. Let _mainExport_ be **undefined**. -> 1. If _exports_ is a String or Array, or an Object containing no keys +> 2. If _exports_ is a String or Array, or an Object containing no keys > starting with _"."_, then > 1. Set _mainExport_ to _exports_. -> 1. Otherwise if _exports_ is an Object containing a _"."_ property, then -> 1. Set _mainExport_ to _exports_\[_"."_\]. -> 1. If _mainExport_ is not **undefined**, then -> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> 3. Otherwise if _exports_ is an Object containing a _"."_ property, then +> 1. Set _mainExport_ to _exports_\[_"."_]. +> 4. If _mainExport_ is not **undefined**, then +> 1. Let _resolved_ be the result of **PACKAGE\_TARGET\_RESOLVE**( > _packageURL_, _mainExport_, _""_, **false**, **false**, > _conditions_). -> 1. If _resolved_ is not **null** or **undefined**, return _resolved_. -> 1. Otherwise, if _exports_ is an Object and all keys of _exports_ start with +> 2. If _resolved_ is not **null** or **undefined**, return _resolved_. +> 3. Otherwise, if _exports_ is an Object and all keys of _exports_ start with > _"."_, then > 1. Let _matchKey_ be the string _"./"_ concatenated with _subpath_. -> 1. Let _resolved_ be the result of **PACKAGE_IMPORTS_EXPORTS_RESOLVE**( +> 2. Let _resolved_ be the result of **PACKAGE\_IMPORTS\_EXPORTS\_RESOLVE**( > _matchKey_, _exports_, _packageURL_, **false**, _conditions_). -> 1. If _resolved_ is not **null** or **undefined**, return _resolved_. -> 1. Throw a _Package Path Not Exported_ error. +> 3. If _resolved_ is not **null** or **undefined**, return _resolved_. +> 4. Throw a _Package Path Not Exported_ error. -**PACKAGE_IMPORTS_RESOLVE**(_specifier_, _parentURL_, _conditions_) +**PACKAGE\_IMPORTS\_RESOLVE**(_specifier_, _parentURL_, _conditions_) > 1. Assert: _specifier_ begins with _"#"_. -> 1. If _specifier_ is exactly equal to _"#"_ or starts with _"#/"_, then +> 2. If _specifier_ is exactly equal to _"#"_ or starts with _"#/"_, then > 1. Throw an _Invalid Module Specifier_ error. -> 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_). -> 1. If _packageURL_ is not **null**, then -> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). -> 1. If _pjson.imports_ is a non-null Object, then -> 1. Let _resolved_ be the result of **PACKAGE_IMPORTS_EXPORTS_RESOLVE**( +> 3. Let _packageURL_ be the result of **READ\_PACKAGE\_SCOPE**(_parentURL_). +> 4. If _packageURL_ is not **null**, then +> 1. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_). +> 2. If _pjson.imports_ is a non-null Object, then +> 1. Let _resolved_ be the result of +> **PACKAGE\_IMPORTS\_EXPORTS\_RESOLVE**( > _specifier_, _pjson.imports_, _packageURL_, **true**, _conditions_). -> 1. If _resolved_ is not **null** or **undefined**, return _resolved_. -> 1. Throw a _Package Import Not Defined_ error. +> 2. If _resolved_ is not **null** or **undefined**, return _resolved_. +> 5. Throw a _Package Import Not Defined_ error. -**PACKAGE_IMPORTS_EXPORTS_RESOLVE**(_matchKey_, _matchObj_, _packageURL_, +**PACKAGE\_IMPORTS\_EXPORTS\_RESOLVE**(_matchKey_, _matchObj_, _packageURL_, _isImports_, _conditions_) -> 1. If _matchKey_ is a key of _matchObj_ and does not contain _"*"_, then -> 1. Let _target_ be the value of _matchObj_\[_matchKey_\]. -> 1. Return the result of **PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, -> _""_, **false**, _isImports_, _conditions_). -> 1. Let _expansionKeys_ be the list of keys of _matchObj_ containing only a -> single _"*"_, sorted by the sorting function **PATTERN_KEY_COMPARE** which -> orders in descending order of specificity. -> 1. For each key _expansionKey_ in _expansionKeys_, do +> 1. If _matchKey_ is a key of _matchObj_ and does not contain _"\*"_, then +> 1. Let _target_ be the value of _matchObj_\[_matchKey_]. +> 2. Return the result of **PACKAGE\_TARGET\_RESOLVE**(_packageURL_, +> _target_, _""_, **false**, _isImports_, _conditions_). +> 2. Let _expansionKeys_ be the list of keys of _matchObj_ containing only a +> single _"\*"_, sorted by the sorting function **PATTERN\_KEY\_COMPARE** +> which orders in descending order of specificity. +> 3. For each key _expansionKey_ in _expansionKeys_, do > 1. Let _patternBase_ be the substring of _expansionKey_ up to but excluding -> the first _"*"_ character. -> 1. If _matchKey_ starts with but is not equal to _patternBase_, then +> the first _"\*"_ character. +> 2. If _matchKey_ starts with but is not equal to _patternBase_, then > 1. Let _patternTrailer_ be the substring of _expansionKey_ from the -> index after the first _"*"_ character. -> 1. If _patternTrailer_ has zero length, or if _matchKey_ ends with +> index after the first _"\*"_ character. +> 2. If _patternTrailer_ has zero length, or if _matchKey_ ends with > _patternTrailer_ and the length of _matchKey_ is greater than or > equal to the length of _expansionKey_, then -> 1. Let _target_ be the value of _matchObj_\[_expansionKey_\]. -> 1. Let _subpath_ be the substring of _matchKey_ starting at the +> 1. Let _target_ be the value of _matchObj_\[_expansionKey_]. +> 2. Let _subpath_ be the substring of _matchKey_ starting at the > index of the length of _patternBase_ up to the length of > _matchKey_ minus the length of _patternTrailer_. -> 1. Return the result of **PACKAGE_TARGET_RESOLVE**(_packageURL_, +> 3. Return the result of **PACKAGE\_TARGET\_RESOLVE**(_packageURL_, > _target_, _subpath_, **true**, _isImports_, _conditions_). -> 1. Return **null**. - -**PATTERN_KEY_COMPARE**(_keyA_, _keyB_) - -> 1. Assert: _keyA_ ends with _"/"_ or contains only a single _"*"_. -> 1. Assert: _keyB_ ends with _"/"_ or contains only a single _"*"_. -> 1. Let _baseLengthA_ be the index of _"*"_ in _keyA_ plus one, if _keyA_ -> contains _"*"_, or the length of _keyA_ otherwise. -> 1. Let _baseLengthB_ be the index of _"*"_ in _keyB_ plus one, if _keyB_ -> contains _"*"_, or the length of _keyB_ otherwise. -> 1. If _baseLengthA_ is greater than _baseLengthB_, return -1. -> 1. If _baseLengthB_ is greater than _baseLengthA_, return 1. -> 1. If _keyA_ does not contain _"*"_, return 1. -> 1. If _keyB_ does not contain _"*"_, return -1. -> 1. If the length of _keyA_ is greater than the length of _keyB_, return -1. -> 1. If the length of _keyB_ is greater than the length of _keyA_, return 1. -> 1. Return 0. - -**PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_, _pattern_, +> 4. Return **null**. + +**PATTERN\_KEY\_COMPARE**(_keyA_, _keyB_) + +> 1. Assert: _keyA_ ends with _"/"_ or contains only a single _"\*"_. +> 2. Assert: _keyB_ ends with _"/"_ or contains only a single _"\*"_. +> 3. Let _baseLengthA_ be the index of _"\*"_ in _keyA_ plus one, if _keyA_ +> contains _"\*"_, or the length of _keyA_ otherwise. +> 4. Let _baseLengthB_ be the index of _"\*"_ in _keyB_ plus one, if _keyB_ +> contains _"\*"_, or the length of _keyB_ otherwise. +> 5. If _baseLengthA_ is greater than _baseLengthB_, return -1. +> 6. If _baseLengthB_ is greater than _baseLengthA_, return 1. +> 7. If _keyA_ does not contain _"\*"_, return 1. +> 8. If _keyB_ does not contain _"\*"_, return -1. +> 9. If the length of _keyA_ is greater than the length of _keyB_, return -1. +> 10. If the length of _keyB_ is greater than the length of _keyA_, return 1. +> 11. Return 0. + +**PACKAGE\_TARGET\_RESOLVE**(_packageURL_, _target_, _subpath_, _pattern_, _internal_, _conditions_) > 1. If _target_ is a String, then > 1. If _pattern_ is **false**, _subpath_ has non-zero length and _target_ > does not end with _"/"_, throw an _Invalid Module Specifier_ error. -> 1. If _target_ does not start with _"./"_, then +> 2. If _target_ does not start with _"./"_, then > 1. If _internal_ is **true** and _target_ does not start with _"../"_ or > _"/"_ and is not a valid URL, then > 1. If _pattern_ is **true**, then -> 1. Return **PACKAGE_RESOLVE**(_target_ with every instance of -> _"*"_ replaced by _subpath_, _packageURL_ + _"/"_)_. -> 1. Return **PACKAGE_RESOLVE**(_target_ + _subpath_, -> _packageURL_ + _"/"_)_. -> 1. Otherwise, throw an _Invalid Package Target_ error. -> 1. If _target_ split on _"/"_ or _"\\"_ contains any _"."_, _".."_ or -> _"node_modules"_ segments after the first segment, throw an +> 1. Return **PACKAGE\_RESOLVE**(_target_ with every instance of +> _"\*"_ replaced by _subpath_, _packageURL_ + _"/"_)\_. +> 2. Return **PACKAGE\_RESOLVE**(_target_ + _subpath_, +> _packageURL_ + _"/"_)\_. +> 2. Otherwise, throw an _Invalid Package Target_ error. +> 3. If _target_ split on _"/"_ or _"\\"_ contains any _"."_, _".."_ or +> _"node\_modules"_ segments after the first segment, throw an > _Invalid Package Target_ error. -> 1. Let _resolvedTarget_ be the URL resolution of the concatenation of +> 4. Let _resolvedTarget_ be the URL resolution of the concatenation of > _packageURL_ and _target_. -> 1. Assert: _resolvedTarget_ is contained in _packageURL_. -> 1. If _subpath_ split on _"/"_ or _"\\"_ contains any _"."_, _".."_ or -> _"node_modules"_ segments, throw an _Invalid Module Specifier_ error. -> 1. If _pattern_ is **true**, then +> 5. Assert: _resolvedTarget_ is contained in _packageURL_. +> 6. If _subpath_ split on _"/"_ or _"\\"_ contains any _"."_, _".."_ or +> _"node\_modules"_ segments, throw an _Invalid Module Specifier_ error. +> 7. If _pattern_ is **true**, then > 1. Return the URL resolution of _resolvedTarget_ with every instance of -> _"*"_ replaced with _subpath_. -> 1. Otherwise, +> _"\*"_ replaced with _subpath_. +> 8. Otherwise, > 1. Return the URL resolution of the concatenation of _subpath_ and > _resolvedTarget_. -> 1. Otherwise, if _target_ is a non-null Object, then +> 2. Otherwise, if _target_ is a non-null Object, then > 1. If _exports_ contains any index property keys, as defined in ECMA-262 > [6.1.7 Array Index][], throw an _Invalid Package Configuration_ error. -> 1. For each property _p_ of _target_, in object insertion order as, +> 2. For each property _p_ of _target_, in object insertion order as, > 1. If _p_ equals _"default"_ or _conditions_ contains an entry for _p_, > then > 1. Let _targetValue_ be the value of the _p_ property in _target_. -> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> 2. Let _resolved_ be the result of **PACKAGE\_TARGET\_RESOLVE**( > _packageURL_, _targetValue_, _subpath_, _pattern_, _internal_, > _conditions_). -> 1. If _resolved_ is equal to **undefined**, continue the loop. -> 1. Return _resolved_. -> 1. Return **undefined**. -> 1. Otherwise, if _target_ is an Array, then -> 1. If _target.length is zero, return **null**. -> 1. For each item _targetValue_ in _target_, do -> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> 3. If _resolved_ is equal to **undefined**, continue the loop. +> 4. Return _resolved_. +> 3. Return **undefined**. +> 3. Otherwise, if _target_ is an Array, then +> 1. If \_target.length is zero, return **null**. +> 2. For each item _targetValue_ in _target_, do +> 1. Let _resolved_ be the result of **PACKAGE\_TARGET\_RESOLVE**( > _packageURL_, _targetValue_, _subpath_, _pattern_, _internal_, > _conditions_), continuing the loop on any _Invalid Package Target_ > error. -> 1. If _resolved_ is **undefined**, continue the loop. -> 1. Return _resolved_. -> 1. Return or throw the last fallback resolution **null** return or error. -> 1. Otherwise, if _target_ is _null_, return **null**. -> 1. Otherwise throw an _Invalid Package Target_ error. +> 2. If _resolved_ is **undefined**, continue the loop. +> 3. Return _resolved_. +> 3. Return or throw the last fallback resolution **null** return or error. +> 4. Otherwise, if _target_ is _null_, return **null**. +> 5. Otherwise throw an _Invalid Package Target_ error. -**ESM_FORMAT**(_url_) +**ESM\_FORMAT**(_url_) > 1. Assert: _url_ corresponds to an existing file. -> 1. Let _pjson_ be the result of **READ_PACKAGE_SCOPE**(_url_). -> 1. If _url_ ends in _".mjs"_, then +> 2. Let _pjson_ be the result of **READ\_PACKAGE\_SCOPE**(_url_). +> 3. If _url_ ends in _".mjs"_, then > 1. Return _"module"_. -> 1. If _url_ ends in _".cjs"_, then +> 4. If _url_ ends in _".cjs"_, then > 1. Return _"commonjs"_. -> 1. If _pjson?.type_ exists and is _"module"_, then +> 5. If _pjson?.type_ exists and is _"module"_, then > 1. If _url_ ends in _".js"_, then > 1. Return _"module"_. -> 1. Throw an _Unsupported File Extension_ error. -> 1. Otherwise, +> 2. Throw an _Unsupported File Extension_ error. +> 6. Otherwise, > 1. Throw an _Unsupported File Extension_ error. -**READ_PACKAGE_SCOPE**(_url_) +**READ\_PACKAGE\_SCOPE**(_url_) > 1. Let _scopeURL_ be _url_. -> 1. While _scopeURL_ is not the file system root, +> 2. While _scopeURL_ is not the file system root, > 1. Set _scopeURL_ to the parent URL of _scopeURL_. -> 1. If _scopeURL_ ends in a _"node_modules"_ path segment, return **null**. -> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_scopeURL_). -> 1. If _pjson_ is not **null**, then +> 2. If _scopeURL_ ends in a _"node\_modules"_ path segment, return **null**. +> 3. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_scopeURL_). +> 4. If _pjson_ is not **null**, then > 1. Return _pjson_. -> 1. Return **null**. +> 3. Return **null**. -**READ_PACKAGE_JSON**(_packageURL_) +**READ\_PACKAGE\_JSON**(_packageURL_) > 1. Let _pjsonURL_ be the resolution of _"package.json"_ within _packageURL_. -> 1. If the file at _pjsonURL_ does not exist, then +> 2. If the file at _pjsonURL_ does not exist, then > 1. Return **null**. -> 1. If the file at _packageURL_ does not parse as valid JSON, then +> 3. If the file at _packageURL_ does not parse as valid JSON, then > 1. Throw an _Invalid Package Configuration_ error. -> 1. Return the parsed JSON source of the file at _pjsonURL_. +> 4. Return the parsed JSON source of the file at _pjsonURL_. ### Customizing ESM specifier resolution algorithm @@ -1343,6 +1342,7 @@ success! ``` <!-- Note: The cjs-module-lexer link should be kept in-sync with the deps version --> + [6.1.7 Array Index]: https://tc39.es/ecma262/#integer-index [CommonJS]: modules.md [Conditional exports]: packages.md#conditional-exports diff --git a/doc/api/events.md b/doc/api/events.md index 5d34a311cf5..f3ef831a484 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -113,7 +113,7 @@ myEmitter.emit('event'); Using the `eventEmitter.once()` method, it is possible to register a listener that is called at most once for a particular event. Once the event is emitted, -the listener is unregistered and *then* called. +the listener is unregistered and _then_ called. ```js const myEmitter = new MyEmitter(); @@ -226,6 +226,7 @@ do not have a catch handler to avoid infinite error loops: the recommendation is to **not use `async` functions as `'error'` event handlers**. ## Class: `EventEmitter` + <!-- YAML added: v0.1.26 changes: @@ -252,6 +253,7 @@ It supports the following option: **Default:** `false`. ### Event: `'newListener'` + <!-- YAML added: v0.1.26 --> @@ -259,15 +261,15 @@ added: v0.1.26 * `eventName` {string|symbol} The name of the event being listened for * `listener` {Function} The event handler function -The `EventEmitter` instance will emit its own `'newListener'` event *before* +The `EventEmitter` instance will emit its own `'newListener'` event _before_ a listener is added to its internal array of listeners. Listeners registered for the `'newListener'` event are passed the event name and a reference to the listener being added. The fact that the event is triggered before adding the listener has a subtle -but important side effect: any *additional* listeners registered to the same -`name` *within* the `'newListener'` callback are inserted *before* the +but important side effect: any _additional_ listeners registered to the same +`name` _within_ the `'newListener'` callback are inserted _before_ the listener that is in the process of being added. ```js @@ -293,6 +295,7 @@ myEmitter.emit('event'); ``` ### Event: `'removeListener'` + <!-- YAML added: v0.9.3 changes: @@ -307,9 +310,10 @@ changes: * `eventName` {string|symbol} The event name * `listener` {Function} The event handler function -The `'removeListener'` event is emitted *after* the `listener` is removed. +The `'removeListener'` event is emitted _after_ the `listener` is removed. ### `emitter.addListener(eventName, listener)` + <!-- YAML added: v0.1.26 --> @@ -320,6 +324,7 @@ added: v0.1.26 Alias for `emitter.on(eventName, listener)`. ### `emitter.emit(eventName[, ...args])` + <!-- YAML added: v0.1.26 --> @@ -368,6 +373,7 @@ myEmitter.emit('event', 1, 2, 3, 4, 5); ``` ### `emitter.eventNames()` + <!-- YAML added: v6.0.0 --> @@ -391,6 +397,7 @@ console.log(myEE.eventNames()); ``` ### `emitter.getMaxListeners()` + <!-- YAML added: v1.0.0 --> @@ -402,6 +409,7 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to [`events.defaultMaxListeners`][]. ### `emitter.listenerCount(eventName)` + <!-- YAML added: v3.2.0 --> @@ -412,6 +420,7 @@ added: v3.2.0 Returns the number of listeners listening to the event named `eventName`. ### `emitter.listeners(eventName)` + <!-- YAML added: v0.1.26 changes: @@ -422,7 +431,7 @@ changes: --> * `eventName` {string|symbol} -* Returns: {Function[]} +* Returns: {Function\[]} Returns a copy of the array of listeners for the event named `eventName`. @@ -435,6 +444,7 @@ console.log(util.inspect(server.listeners('connection'))); ``` ### `emitter.off(eventName, listener)` + <!-- YAML added: v10.0.0 --> @@ -446,6 +456,7 @@ added: v10.0.0 Alias for [`emitter.removeListener()`][]. ### `emitter.on(eventName, listener)` + <!-- YAML added: v0.1.101 --> @@ -483,6 +494,7 @@ myEE.emit('foo'); ``` ### `emitter.once(eventName, listener)` + <!-- YAML added: v0.3.0 --> @@ -517,6 +529,7 @@ myEE.emit('foo'); ``` ### `emitter.prependListener(eventName, listener)` + <!-- YAML added: v6.0.0 --> @@ -525,7 +538,7 @@ added: v6.0.0 * `listener` {Function} The callback function * Returns: {EventEmitter} -Adds the `listener` function to the *beginning* of the listeners array for the +Adds the `listener` function to the _beginning_ of the listeners array for the event named `eventName`. No checks are made to see if the `listener` has already been added. Multiple calls passing the same combination of `eventName` and `listener` will result in the `listener` being added, and called, multiple @@ -540,6 +553,7 @@ server.prependListener('connection', (stream) => { Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.prependOnceListener(eventName, listener)` + <!-- YAML added: v6.0.0 --> @@ -549,7 +563,7 @@ added: v6.0.0 * Returns: {EventEmitter} Adds a **one-time** `listener` function for the event named `eventName` to the -*beginning* of the listeners array. The next time `eventName` is triggered, this +_beginning_ of the listeners array. The next time `eventName` is triggered, this listener is removed, and then invoked. ```js @@ -561,6 +575,7 @@ server.prependOnceListener('connection', (stream) => { Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.removeAllListeners([eventName])` + <!-- YAML added: v0.1.26 --> @@ -577,6 +592,7 @@ component or module (e.g. sockets or file streams). Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.removeListener(eventName, listener)` + <!-- YAML added: v0.1.26 --> @@ -604,8 +620,8 @@ called multiple times to remove each instance. Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any -`removeListener()` or `removeAllListeners()` calls *after* emitting and -*before* the last listener finishes execution will not remove them from +`removeListener()` or `removeAllListeners()` calls _after_ emitting and +_before_ the last listener finishes execution will not remove them from `emit()` in progress. Subsequent events behave as expected. ```js @@ -639,7 +655,7 @@ myEmitter.emit('event'); ``` Because listeners are managed using an internal array, calling this will -change the position indices of any listener registered *after* the listener +change the position indices of any listener registered _after_ the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the `emitter.listeners()` method will need to be recreated. @@ -667,6 +683,7 @@ ee.emit('ping'); Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.setMaxListeners(n)` + <!-- YAML added: v0.3.5 --> @@ -683,12 +700,13 @@ modified for this specific `EventEmitter` instance. The value can be set to Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.rawListeners(eventName)` + <!-- YAML added: v9.4.0 --> * `eventName` {string|symbol} -* Returns: {Function[]} +* Returns: {Function\[]} Returns a copy of the array of listeners for the event named `eventName`, including any wrappers (such as those created by `.once()`). @@ -718,6 +736,7 @@ emitter.emit('log'); ``` ### `emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])` + <!-- YAML added: - v13.4.0 @@ -756,6 +775,7 @@ class MyClass extends EventEmitter { ``` ## `events.defaultMaxListeners` + <!-- YAML added: v0.11.2 --> @@ -763,12 +783,12 @@ added: v0.11.2 By default, a maximum of `10` listeners can be registered for any single event. This limit can be changed for individual `EventEmitter` instances using the [`emitter.setMaxListeners(n)`][] method. To change the default -for *all* `EventEmitter` instances, the `events.defaultMaxListeners` +for _all_ `EventEmitter` instances, the `events.defaultMaxListeners` property can be used. If this value is not a positive number, a `RangeError` is thrown. Take caution when setting the `events.defaultMaxListeners` because the -change affects *all* `EventEmitter` instances, including those created before +change affects _all_ `EventEmitter` instances, including those created before the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has precedence over `events.defaultMaxListeners`. @@ -796,6 +816,7 @@ listeners, respectively. Its `name` property is set to `'MaxListenersExceededWarning'`. ## `events.errorMonitor` + <!-- YAML added: - v13.6.0 @@ -811,14 +832,16 @@ Installing a listener using this symbol does not change the behavior once an regular `'error'` listener is installed. ## `events.getEventListeners(emitterOrTarget, eventName)` + <!-- YAML added: - v15.2.0 - v14.17.0 --> + * `emitterOrTarget` {EventEmitter|EventTarget} * `eventName` {string|symbol} -* Returns: {Function[]} +* Returns: {Function\[]} Returns a copy of the array of listeners for the event named `eventName`. @@ -846,6 +869,7 @@ const { getEventListeners, EventEmitter } = require('events'); ``` ## `events.once(emitter, name[, options])` + <!-- YAML added: - v11.13.0 @@ -976,7 +1000,7 @@ process.nextTick(() => { foo().then(() => console.log('done')); ``` -To catch both events, create each of the Promises *before* awaiting either +To catch both events, create each of the Promises _before_ awaiting either of them, then it becomes possible to use `Promise.all()`, `Promise.race()`, or `Promise.allSettled()`: @@ -999,6 +1023,7 @@ foo().then(() => console.log('done')); ``` ## `events.captureRejections` + <!-- YAML added: - v13.4.0 @@ -1012,6 +1037,7 @@ Value: {boolean} Change the default `captureRejections` option on all new `EventEmitter` objects. ## `events.captureRejectionSymbol` + <!-- YAML added: - v13.4.0 @@ -1025,6 +1051,7 @@ Value: `Symbol.for('nodejs.rejection')` See how to write a custom [rejection handler][rejection]. ## `events.listenerCount(emitter, eventName)` + <!-- YAML added: v0.9.12 deprecated: v3.2.0 @@ -1048,6 +1075,7 @@ console.log(listenerCount(myEmitter, 'event')); ``` ## `events.on(emitter, eventName[, options])` + <!-- YAML added: - v13.6.0 @@ -1115,13 +1143,14 @@ process.nextTick(() => ac.abort()); ``` ## `events.setMaxListeners(n[, ...eventTargets])` + <!-- YAML added: v15.4.0 --> * `n` {number} A non-negative number. The maximum number of listeners per `EventTarget` event. -* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget} +* `...eventsTargets` {EventTarget\[]|EventEmitter\[]} Zero or more {EventTarget} or {EventEmitter} instances. If none are specified, `n` is set as the default max for all newly created {EventTarget} and {EventEmitter} objects. @@ -1138,7 +1167,9 @@ setMaxListeners(5, target, emitter); ``` <a id="event-target-and-event-api"></a> + ## `EventTarget` and `Event` API + <!-- YAML added: v14.5.0 changes: @@ -1170,7 +1201,7 @@ target.addEventListener('foo', (event) => { There are two key differences between the Node.js `EventTarget` and the [`EventTarget` Web API][]: -1. Whereas DOM `EventTarget` instances *may* be hierarchical, there is no +1. Whereas DOM `EventTarget` instances _may_ be hierarchical, there is no concept of hierarchy and event propagation in Node.js. That is, an event dispatched to an `EventTarget` does not propagate through a hierarchy of nested target objects that may each have their own set of handlers for the @@ -1183,8 +1214,8 @@ There are two key differences between the Node.js `EventTarget` and the ### `NodeEventTarget` vs. `EventEmitter` The `NodeEventTarget` object implements a modified subset of the -`EventEmitter` API that allows it to closely *emulate* an `EventEmitter` in -certain situations. A `NodeEventTarget` is *not* an instance of `EventEmitter` +`EventEmitter` API that allows it to closely _emulate_ an `EventEmitter` in +certain situations. A `NodeEventTarget` is _not_ an instance of `EventEmitter` and cannot be used in place of an `EventEmitter` in most cases. 1. Unlike `EventEmitter`, any given `listener` can be registered at most once @@ -1197,7 +1228,7 @@ and cannot be used in place of an `EventEmitter` in most cases. `'removeListener'` events will also not be emitted. 3. The `NodeEventTarget` does not implement any special default behavior for events with type `'error'`. -3. The `NodeEventTarget` supports `EventListener` objects as well as +4. The `NodeEventTarget` supports `EventListener` objects as well as functions as handlers for all event types. ### Event listener @@ -1259,7 +1290,7 @@ by default the error is treated as an uncaught exception on `process.nextTick()`. This means uncaught exceptions in `EventTarget`s will terminate the Node.js process by default. -Throwing within an event listener will *not* stop the other registered handlers +Throwing within an event listener will _not_ stop the other registered handlers from being invoked. The `EventTarget` does not implement any special default handling for `'error'` @@ -1272,6 +1303,7 @@ other Node.js APIs. Any code relying on the `process.on('error')` event should be aligned with the new behavior. ### Class: `Event` + <!-- YAML added: v14.5.0 changes: @@ -1284,6 +1316,7 @@ The `Event` object is an adaptation of the [`Event` Web API][]. Instances are created internally by Node.js. #### `event.bubbles` + <!-- YAML added: v14.5.0 --> @@ -1293,6 +1326,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.cancelBubble()` + <!-- YAML added: v14.5.0 --> @@ -1301,6 +1335,7 @@ Alias for `event.stopPropagation()`. This is not used in Node.js and is provided purely for completeness. #### `event.cancelable` + <!-- YAML added: v14.5.0 --> @@ -1308,6 +1343,7 @@ added: v14.5.0 * Type: {boolean} True if the event was created with the `cancelable` option. #### `event.composed` + <!-- YAML added: v14.5.0 --> @@ -1317,6 +1353,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.composedPath()` + <!-- YAML added: v14.5.0 --> @@ -1326,6 +1363,7 @@ empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness. #### `event.currentTarget` + <!-- YAML added: v14.5.0 --> @@ -1335,6 +1373,7 @@ added: v14.5.0 Alias for `event.target`. #### `event.defaultPrevented` + <!-- YAML added: v14.5.0 --> @@ -1345,6 +1384,7 @@ Is `true` if `cancelable` is `true` and `event.preventDefault()` has been called. #### `event.eventPhase` + <!-- YAML added: v14.5.0 --> @@ -1355,6 +1395,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.isTrusted` + <!-- YAML added: v14.5.0 --> @@ -1365,6 +1406,7 @@ The {AbortSignal} `"abort"` event is emitted with `isTrusted` set to `true`. The value is `false` in all other cases. #### `event.preventDefault()` + <!-- YAML added: v14.5.0 --> @@ -1372,6 +1414,7 @@ added: v14.5.0 Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. #### `event.returnValue` + <!-- YAML added: v14.5.0 --> @@ -1381,6 +1424,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.srcElement` + <!-- YAML added: v14.5.0 --> @@ -1390,6 +1434,7 @@ added: v14.5.0 Alias for `event.target`. #### `event.stopImmediatePropagation()` + <!-- YAML added: v14.5.0 --> @@ -1397,6 +1442,7 @@ added: v14.5.0 Stops the invocation of event listeners after the current one completes. #### `event.stopPropagation()` + <!-- YAML added: v14.5.0 --> @@ -1404,6 +1450,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.target` + <!-- YAML added: v14.5.0 --> @@ -1411,6 +1458,7 @@ added: v14.5.0 * Type: {EventTarget} The `EventTarget` dispatching the event. #### `event.timeStamp` + <!-- YAML added: v14.5.0 --> @@ -1420,6 +1468,7 @@ added: v14.5.0 The millisecond timestamp when the `Event` object was created. #### `event.type` + <!-- YAML added: v14.5.0 --> @@ -1429,6 +1478,7 @@ added: v14.5.0 The event type identifier. ### Class: `EventTarget` + <!-- YAML added: v14.5.0 changes: @@ -1439,6 +1489,7 @@ changes: --> #### `eventTarget.addEventListener(type, listener[, options])` + <!-- YAML added: v14.5.0 --> @@ -1481,6 +1532,7 @@ target.removeEventListener('foo', handler, { capture: true }); ``` #### `eventTarget.dispatchEvent(event)` + <!-- YAML added: v14.5.0 --> @@ -1495,6 +1547,7 @@ The registered event listeners is synchronously invoked in the order they were registered. #### `eventTarget.removeEventListener(type, listener)` + <!-- YAML added: v14.5.0 --> @@ -1507,6 +1560,7 @@ added: v14.5.0 Removes the `listener` from the list of handlers for event `type`. ### Class: `NodeEventTarget` + <!-- YAML added: v14.5.0 --> @@ -1517,12 +1571,15 @@ The `NodeEventTarget` is a Node.js-specific extension to `EventTarget` that emulates a subset of the `EventEmitter` API. #### `nodeEventTarget.addListener(type, listener[, options])` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} + * `options` {Object} * `once` {boolean} @@ -1534,16 +1591,18 @@ equivalent `EventEmitter` API. The only difference between `addListener()` and `EventTarget`. #### `nodeEventTarget.eventNames()` + <!-- YAML added: v14.5.0 --> -* Returns: {string[]} +* Returns: {string\[]} Node.js-specific extension to the `EventTarget` class that returns an array of event `type` names for which event listeners are registered. #### `nodeEventTarget.listenerCount(type)` + <!-- YAML added: v14.5.0 --> @@ -1556,11 +1615,13 @@ Node.js-specific extension to the `EventTarget` class that returns the number of event listeners registered for the `type`. #### `nodeEventTarget.off(type, listener)` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} * Returns: {EventTarget} this @@ -1568,12 +1629,15 @@ added: v14.5.0 Node.js-specific alias for `eventTarget.removeListener()`. #### `nodeEventTarget.on(type, listener[, options])` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} + * `options` {Object} * `once` {boolean} @@ -1582,12 +1646,15 @@ added: v14.5.0 Node.js-specific alias for `eventTarget.addListener()`. #### `nodeEventTarget.once(type, listener[, options])` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} + * `options` {Object} * Returns: {EventTarget} this @@ -1597,6 +1664,7 @@ listener for the given event `type`. This is equivalent to calling `on` with the `once` option set to `true`. #### `nodeEventTarget.removeAllListeners([type])` + <!-- YAML added: v14.5.0 --> @@ -1610,11 +1678,13 @@ removes all registered listeners for `type`, otherwise removes all registered listeners. #### `nodeEventTarget.removeListener(type, listener)` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} * Returns: {EventTarget} this diff --git a/doc/api/fs.md b/doc/api/fs.md index 2a58e4877e5..d0c0635bead 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -122,6 +122,7 @@ try { ``` ## Promises API + <!-- YAML added: v10.0.0 changes: @@ -147,6 +148,7 @@ synchronized or threadsafe. Care must be taken when performing multiple concurrent modifications on the same file or data corruption may occur. ### Class: `FileHandle` + <!-- YAML added: v10.0.0 --> @@ -165,6 +167,7 @@ it can be unreliable and the file may not be closed. Instead, always explicitly close {FileHandle}s. Node.js may change this behavior in the future. #### Event: `'close'` + <!-- YAML added: v15.4.0 --> @@ -173,6 +176,7 @@ The `'close'` event is emitted when the {FileHandle} has been closed and can no longer be used. #### `filehandle.appendFile(data[, options])` + <!-- YAML added: v10.0.0 --> @@ -189,6 +193,7 @@ to with [`fsPromises.open()`][]. Therefore, this is equivalent to [`filehandle.writeFile()`][]. #### `filehandle.chmod(mode)` + <!-- YAML added: v10.0.0 --> @@ -199,6 +204,7 @@ added: v10.0.0 Modifies the permissions on the file. See chmod(2). #### `filehandle.chown(uid, gid)` + <!-- YAML added: v10.0.0 --> @@ -210,6 +216,7 @@ added: v10.0.0 Changes the ownership of the file. A wrapper for chown(2). #### `filehandle.close()` + <!-- YAML added: v10.0.0 --> @@ -231,6 +238,7 @@ try { ``` #### `filehandle.createReadStream([options])` + <!-- YAML added: v16.11.0 --> @@ -250,7 +258,7 @@ returned by this method has a default `highWaterMark` of 64 kb. `options` can include `start` and `end` values to read a range of bytes from the file instead of the entire file. Both `start` and `end` are inclusive and start counting at 0, allowed values are in the -[0, [`Number.MAX_SAFE_INTEGER`][]] range. If `start` is +\[0, [`Number.MAX_SAFE_INTEGER`][]] range. If `start` is omitted or `undefined`, `filehandle.createReadStream()` reads sequentially from the current file position. The `encoding` can be any one of those accepted by {Buffer}. @@ -297,6 +305,7 @@ fd.createReadStream({ start: 90, end: 99 }); ``` #### `filehandle.createWriteStream([options])` + <!-- YAML added: v16.11.0 --> @@ -310,9 +319,9 @@ added: v16.11.0 `options` may also include a `start` option to allow writing data at some position past the beginning of the file, allowed values are in the -[0, [`Number.MAX_SAFE_INTEGER`][]] range. Modifying a file rather than replacing -it may require the `flags` `open` option to be set to `r+` rather than the -default `r`. The `encoding` can be any one of those accepted by {Buffer}. +\[0, [`Number.MAX_SAFE_INTEGER`][]] range. Modifying a file rather than +replacing it may require the `flags` `open` option to be set to `r+` rather than +the default `r`. The `encoding` can be any one of those accepted by {Buffer}. If `autoClose` is set to true (default behavior) on `'error'` or `'finish'` the file descriptor will be closed automatically. If `autoClose` is false, @@ -324,6 +333,7 @@ By default, the stream will emit a `'close'` event after it has been destroyed. Set the `emitClose` option to `false` to change this behavior. #### `filehandle.datasync()` + <!-- YAML added: v10.0.0 --> @@ -337,6 +347,7 @@ fdatasync(2) documentation for details. Unlike `filehandle.sync` this method does not flush modified metadata. #### `filehandle.fd` + <!-- YAML added: v10.0.0 --> @@ -344,6 +355,7 @@ added: v10.0.0 * {number} The numeric file descriptor managed by the {FileHandle} object. #### `filehandle.read(buffer, offset, length, position)` + <!-- YAML added: v10.0.0 --> @@ -367,11 +379,13 @@ If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero. #### `filehandle.read([options])` + <!-- YAML added: - v13.11.0 - v12.17.0 --> + * `options` {Object} * `buffer` {Buffer|TypedArray|DataView} A buffer that will be filled with the file data read. **Default:** `Buffer.alloc(16384)` @@ -394,6 +408,7 @@ If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero. #### `filehandle.readableWebStream()` + <!-- YAML added: v17.0.0 --> @@ -440,6 +455,7 @@ close the `FileHandle` automatically. User code must still call the `fileHandle.close()` method. #### `filehandle.readFile(options)` + <!-- YAML added: v10.0.0 --> @@ -463,24 +479,26 @@ position till the end of the file. It doesn't always read from the beginning of the file. #### `filehandle.readv(buffers[, position])` + <!-- YAML added: - v13.13.0 - v12.17.0 --> -* `buffers` {Buffer[]|TypedArray[]|DataView[]} +* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} * `position` {integer} The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position. * Returns: {Promise} Fulfills upon success an object containing two properties: * `bytesRead` {integer} the number of bytes read - * `buffers` {Buffer[]|TypedArray[]|DataView[]} property containing + * `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} property containing a reference to the `buffers` input. Read from a file and write to an array of {ArrayBufferView}s #### `filehandle.stat([options])` + <!-- YAML added: v10.0.0 changes: @@ -496,6 +514,7 @@ changes: * Returns: {Promise} Fulfills with an {fs.Stats} for the file. #### `filehandle.sync()` + <!-- YAML added: v10.0.0 --> @@ -507,6 +526,7 @@ device. The specific implementation is operating system and device specific. Refer to the POSIX fsync(2) documentation for more detail. #### `filehandle.truncate(len)` + <!-- YAML added: v10.0.0 --> @@ -539,6 +559,7 @@ extended part is filled with null bytes (`'\0'`): If `len` is negative then `0` will be used. #### `filehandle.utimes(atime, mtime)` + <!-- YAML added: v10.0.0 --> @@ -551,6 +572,7 @@ Change the file system timestamps of the object referenced by the {FileHandle} then resolves the promise with no arguments upon success. #### `filehandle.write(buffer[, offset[, length[, position]]])` + <!-- YAML added: v10.0.0 changes: @@ -595,6 +617,7 @@ The kernel ignores the position argument and always appends the data to the end of the file. #### `filehandle.write(string[, position[, encoding]])` + <!-- YAML added: v10.0.0 changes: @@ -633,6 +656,7 @@ The kernel ignores the position argument and always appends the data to the end of the file. #### `filehandle.writeFile(data, options)` + <!-- YAML added: v10.0.0 changes: @@ -676,11 +700,12 @@ current position till the end of the file. It doesn't always write from the beginning of the file. #### `filehandle.writev(buffers[, position])` + <!-- YAML added: v12.9.0 --> -* `buffers` {Buffer[]|TypedArray[]|DataView[]} +* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} * `position` {integer} The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current position. @@ -691,7 +716,7 @@ Write an array of {ArrayBufferView}s to the file. The promise is resolved with an object containing a two properties: * `bytesWritten` {integer} the number of bytes written -* `buffers` {Buffer[]|TypedArray[]|DataView[]} a reference to the `buffers` +* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} a reference to the `buffers` input. It is unsafe to call `writev()` multiple times on the same file without waiting @@ -702,6 +727,7 @@ The kernel ignores the position argument and always appends the data to the end of the file. ### `fsPromises.access(path[, mode])` + <!-- YAML added: v10.0.0 --> @@ -740,6 +766,7 @@ calls. Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible. ### `fsPromises.appendFile(path, data[, options])` + <!-- YAML added: v10.0.0 --> @@ -764,6 +791,7 @@ The `path` may be specified as a {FileHandle} that has been opened for appending (using `fsPromises.open()`). ### `fsPromises.chmod(path, mode)` + <!-- YAML added: v10.0.0 --> @@ -775,6 +803,7 @@ added: v10.0.0 Changes the permissions of a file. ### `fsPromises.chown(path, uid, gid)` + <!-- YAML added: v10.0.0 --> @@ -787,6 +816,7 @@ added: v10.0.0 Changes the ownership of a file. ### `fsPromises.copyFile(src, dest[, mode])` + <!-- YAML added: v10.0.0 changes: @@ -841,6 +871,7 @@ try { ``` ### `fsPromises.cp(src, dest[, options])` + <!-- YAML added: v16.7.0 --> @@ -856,7 +887,7 @@ added: v16.7.0 * `filter` {Function} Function to filter copied files/directories. Return `true` to copy the item, `false` to ignore it. Can also return a `Promise` that resolves to `true` or `false` **Default:** `undefined`. - * `force` {boolean} overwrite existing file or directory. _The copy + * `force` {boolean} overwrite existing file or directory. The copy operation will ignore errors if you set this to false and the destination exists. Use the `errorOnExist` option to change this behavior. **Default:** `true`. @@ -872,6 +903,7 @@ When copying a directory to another directory, globs are not supported and behavior is similar to `cp dir1/ dir2/`. ### `fsPromises.lchmod(path, mode)` + <!-- YAML deprecated: v10.0.0 --> @@ -885,6 +917,7 @@ Changes the permissions on a symbolic link. This method is only implemented on macOS. ### `fsPromises.lchown(path, uid, gid)` + <!-- YAML added: v10.0.0 changes: @@ -901,6 +934,7 @@ changes: Changes the ownership on a symbolic link. ### `fsPromises.lutimes(path, atime, mtime)` + <!-- YAML added: - v14.5.0 @@ -918,6 +952,7 @@ symbolic link, then the link is not dereferenced: instead, the timestamps of the symbolic link itself are changed. ### `fsPromises.link(existingPath, newPath)` + <!-- YAML added: v10.0.0 --> @@ -930,6 +965,7 @@ Creates a new link from the `existingPath` to the `newPath`. See the POSIX link(2) documentation for more detail. ### `fsPromises.lstat(path[, options])` + <!-- YAML added: v10.0.0 changes: @@ -951,6 +987,7 @@ in which case the link itself is stat-ed, not the file that it refers to. Refer to the POSIX lstat(2) document for more detail. ### `fsPromises.mkdir(path[, options])` + <!-- YAML added: v10.0.0 --> @@ -971,6 +1008,7 @@ property indicating whether parent directories should be created. Calling rejection only when `recursive` is false. ### `fsPromises.mkdtemp(prefix[, options])` + <!-- YAML added: v10.0.0 changes: @@ -1008,11 +1046,12 @@ try { The `fsPromises.mkdtemp()` method will append the six randomly selected characters directly to the `prefix` string. For instance, given a directory -`/tmp`, if the intention is to create a temporary directory *within* `/tmp`, the +`/tmp`, if the intention is to create a temporary directory _within_ `/tmp`, the `prefix` must end with a trailing platform-specific path separator (`require('path').sep`). ### `fsPromises.open(path, flags[, mode])` + <!-- YAML added: v10.0.0 changes: @@ -1038,6 +1077,7 @@ a colon, Node.js will open a file system stream, as described by [this MSDN page][MSDN-Using-Streams]. ### `fsPromises.opendir(path[, options])` + <!-- YAML added: v12.12.0 changes: @@ -1083,6 +1123,7 @@ When using the async iterator, the {fs.Dir} object will be automatically closed after the iterator exits. ### `fsPromises.readdir(path[, options])` + <!-- YAML added: v10.0.0 changes: @@ -1121,6 +1162,7 @@ try { ``` ### `fsPromises.readFile(path[, options])` + <!-- YAML added: v10.0.0 changes: @@ -1178,9 +1220,11 @@ system requests but rather the internal buffering `fs.readFile` performs. Any specified {FileHandle} has to support reading. ### `fsPromises.readlink(path[, options])` + <!-- YAML added: v10.0.0 --> + * `path` {string|Buffer|URL} * `options` {string|Object} * `encoding` {string} **Default:** `'utf8'` @@ -1196,6 +1240,7 @@ the link path returned. If the `encoding` is set to `'buffer'`, the link path returned will be passed as a {Buffer} object. ### `fsPromises.realpath(path[, options])` + <!-- YAML added: v10.0.0 --> @@ -1220,6 +1265,7 @@ be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. ### `fsPromises.rename(oldPath, newPath)` + <!-- YAML added: v10.0.0 --> @@ -1231,6 +1277,7 @@ added: v10.0.0 Renames `oldPath` to `newPath`. ### `fsPromises.rmdir(path[, options])` + <!-- YAML added: v10.0.0 changes: @@ -1291,6 +1338,7 @@ To get a behavior similar to the `rm -rf` Unix command, use [`fsPromises.rm()`][] with options `{ recursive: true, force: true }`. ### `fsPromises.rm(path[, options])` + <!-- YAML added: v14.14.0 --> @@ -1314,6 +1362,7 @@ added: v14.14.0 Removes files and directories (modeled on the standard POSIX `rm` utility). ### `fsPromises.stat(path[, options])` + <!-- YAML added: v10.0.0 changes: @@ -1331,6 +1380,7 @@ changes: given `path`. ### `fsPromises.symlink(target, path[, type])` + <!-- YAML added: v10.0.0 --> @@ -1348,6 +1398,7 @@ to be absolute. When using `'junction'`, the `target` argument will automatically be normalized to absolute path. ### `fsPromises.truncate(path[, len])` + <!-- YAML added: v10.0.0 --> @@ -1360,6 +1411,7 @@ Truncates (shortens or extends the length) of the content at `path` to `len` bytes. ### `fsPromises.unlink(path)` + <!-- YAML added: v10.0.0 --> @@ -1373,6 +1425,7 @@ path that is not a symbolic link, the file is deleted. See the POSIX unlink(2) documentation for more detail. ### `fsPromises.utimes(path, atime, mtime)` + <!-- YAML added: v10.0.0 --> @@ -1392,6 +1445,7 @@ The `atime` and `mtime` arguments follow these rules: `-Infinity`, an `Error` will be thrown. ### `fsPromises.watch(filename[, options])` + <!-- YAML added: - v15.9.0 @@ -1407,7 +1461,7 @@ added: specified, and only on supported platforms (See [caveats][]). **Default:** `false`. * `encoding` {string} Specifies the character encoding to be used for the - filename passed to the listener. **Default:** `'utf8'`. + filename passed to the listener. **Default:** `'utf8'`. * `signal` {AbortSignal} An {AbortSignal} used to signal when the watcher should stop. * Returns: {AsyncIterator} of objects with the properties: @@ -1443,6 +1497,7 @@ disappears in the directory. All the [caveats][] for `fs.watch()` also apply to `fsPromises.watch()`. ### `fsPromises.writeFile(file, data[, options])` + <!-- YAML added: v10.0.0 changes: @@ -1536,6 +1591,7 @@ synchronized or threadsafe. Care must be taken when performing multiple concurrent modifications on the same file or data corruption may occur. ### `fs.access(path[, mode], callback)` + <!-- YAML added: v0.11.15 changes: @@ -1723,6 +1779,7 @@ ACL and therefore may report that a path is accessible even if the ACL restricts the user from reading or writing to it. ### `fs.appendFile(path, data[, options], callback)` + <!-- YAML added: v0.6.7 changes: @@ -1803,6 +1860,7 @@ open('message.txt', 'a', (err, fd) => { ``` ### `fs.chmod(path, mode, callback)` + <!-- YAML added: v0.1.30 changes: @@ -1845,7 +1903,7 @@ The `mode` argument used in both the `fs.chmod()` and `fs.chmodSync()` methods is a numeric bitmask created using a logical OR of the following constants: -| Constant | Octal | Description | +| Constant | Octal | Description | | ---------------------- | ------- | ------------------------ | | `fs.constants.S_IRUSR` | `0o400` | read by owner | | `fs.constants.S_IWUSR` | `0o200` | write by owner | @@ -1890,6 +1948,7 @@ distinction among the permissions of group, owner or others is not implemented. ### `fs.chown(path, uid, gid, callback)` + <!-- YAML added: v0.1.97 changes: @@ -1919,6 +1978,7 @@ possible exception are given to the completion callback. See the POSIX chown(2) documentation for more detail. ### `fs.close(fd[, callback])` + <!-- YAML added: v0.0.2 changes: @@ -1950,6 +2010,7 @@ through any other `fs` operation may lead to undefined behavior. See the POSIX close(2) documentation for more detail. ### `fs.copyFile(src, dest[, mode], callback)` + <!-- YAML added: v8.5.0 changes: @@ -2000,6 +2061,7 @@ copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback); ``` ### `fs.cp(src, dest[, options], callback)` + <!-- YAML added: v16.7.0 --> @@ -2015,7 +2077,7 @@ added: v16.7.0 * `filter` {Function} Function to filter copied files/directories. Return `true` to copy the item, `false` to ignore it. Can also return a `Promise` that resolves to `true` or `false` **Default:** `undefined`. - * `force` {boolean} overwrite existing file or directory. _The copy + * `force` {boolean} overwrite existing file or directory. The copy operation will ignore errors if you set this to false and the destination exists. Use the `errorOnExist` option to change this behavior. **Default:** `true`. @@ -2031,6 +2093,7 @@ When copying a directory to another directory, globs are not supported and behavior is similar to `cp dir1/ dir2/`. ### `fs.createReadStream(path[, options])` + <!-- YAML added: v0.1.31 changes: @@ -2094,7 +2157,7 @@ returned by this method has a default `highWaterMark` of 64 kb. `options` can include `start` and `end` values to read a range of bytes from the file instead of the entire file. Both `start` and `end` are inclusive and start counting at 0, allowed values are in the -[0, [`Number.MAX_SAFE_INTEGER`][]] range. If `fd` is specified and `start` is +\[0, [`Number.MAX_SAFE_INTEGER`][]] range. If `fd` is specified and `start` is omitted or `undefined`, `fs.createReadStream()` reads sequentially from the current file position. The `encoding` can be any one of those accepted by {Buffer}. @@ -2155,6 +2218,7 @@ createReadStream('sample.txt', { start: 90, end: 99 }); If `options` is a string, then it specifies the encoding. ### `fs.createWriteStream(path[, options])` + <!-- YAML added: v0.1.31 changes: @@ -2210,9 +2274,9 @@ changes: `options` may also include a `start` option to allow writing data at some position past the beginning of the file, allowed values are in the -[0, [`Number.MAX_SAFE_INTEGER`][]] range. Modifying a file rather than replacing -it may require the `flags` option to be set to `r+` rather than the default `w`. -The `encoding` can be any one of those accepted by {Buffer}. +\[0, [`Number.MAX_SAFE_INTEGER`][]] range. Modifying a file rather than +replacing it may require the `flags` option to be set to `r+` rather than the +default `w`. The `encoding` can be any one of those accepted by {Buffer}. If `autoClose` is set to true (default behavior) on `'error'` or `'finish'` the file descriptor will be closed automatically. If `autoClose` is false, @@ -2239,6 +2303,7 @@ should be passed to {net.Socket}. If `options` is a string, then it specifies the encoding. ### `fs.exists(path, callback)` + <!-- YAML added: v0.0.2 deprecated: v1.0.0 @@ -2384,6 +2449,7 @@ used directly, for example when its existence is a signal from another process. ### `fs.fchmod(fd, mode, callback)` + <!-- YAML added: v0.4.7 changes: @@ -2408,6 +2474,7 @@ are given to the completion callback. See the POSIX fchmod(2) documentation for more detail. ### `fs.fchown(fd, uid, gid, callback)` + <!-- YAML added: v0.4.7 changes: @@ -2433,6 +2500,7 @@ given to the completion callback. See the POSIX fchown(2) documentation for more detail. ### `fs.fdatasync(fd, callback)` + <!-- YAML added: v0.1.96 changes: @@ -2456,6 +2524,7 @@ fdatasync(2) documentation for details. No arguments other than a possible exception are given to the completion callback. ### `fs.fstat(fd[, options], callback)` + <!-- YAML added: v0.1.95 changes: @@ -2486,6 +2555,7 @@ Invokes the callback with the {fs.Stats} for the file descriptor. See the POSIX fstat(2) documentation for more detail. ### `fs.fsync(fd, callback)` + <!-- YAML added: v0.1.96 changes: @@ -2509,6 +2579,7 @@ Refer to the POSIX fsync(2) documentation for more detail. No arguments other than a possible exception are given to the completion callback. ### `fs.ftruncate(fd[, len], callback)` + <!-- YAML added: v0.8.6 changes: @@ -2568,6 +2639,7 @@ extended part is filled with null bytes (`'\0'`): If `len` is negative then `0` will be used. ### `fs.futimes(fd, atime, mtime, callback)` + <!-- YAML added: v0.4.2 changes: @@ -2595,6 +2667,7 @@ Change the file system timestamps of the object referenced by the supplied file descriptor. See [`fs.utimes()`][]. ### `fs.lchmod(path, mode, callback)` + <!-- YAML deprecated: v0.4.7 changes: @@ -2625,6 +2698,7 @@ This method is only implemented on macOS. See the POSIX lchmod(2) documentation for more detail. ### `fs.lchown(path, uid, gid, callback)` + <!-- YAML changes: - version: v10.6.0 @@ -2654,6 +2728,7 @@ exception are given to the completion callback. See the POSIX lchown(2) documentation for more detail. ### `fs.lutimes(path, atime, mtime, callback)` + <!-- YAML added: - v14.5.0 @@ -2675,6 +2750,7 @@ No arguments other than a possible exception are given to the completion callback. ### `fs.link(existingPath, newPath, callback)` + <!-- YAML added: v0.1.31 changes: @@ -2703,6 +2779,7 @@ link(2) documentation for more detail. No arguments other than a possible exception are given to the completion callback. ### `fs.lstat(path[, options], callback)` + <!-- YAML added: v0.1.30 changes: @@ -2740,6 +2817,7 @@ link, then the link itself is stat-ed, not the file that it refers to. See the POSIX lstat(2) documentation for more details. ### `fs.mkdir(path[, options], callback)` + <!-- YAML added: v0.1.8 changes: @@ -2810,6 +2888,7 @@ mkdir('/', { recursive: true }, (err) => { See the POSIX mkdir(2) documentation for more details. ### `fs.mkdtemp(prefix[, options], callback)` + <!-- YAML added: v5.10.0 changes: @@ -2864,7 +2943,7 @@ mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, directory) => { The `fs.mkdtemp()` method will append the six randomly selected characters directly to the `prefix` string. For instance, given a directory `/tmp`, if the -intention is to create a temporary directory *within* `/tmp`, the `prefix` +intention is to create a temporary directory _within_ `/tmp`, the `prefix` must end with a trailing platform-specific path separator (`require('path').sep`). @@ -2896,6 +2975,7 @@ mkdtemp(`${tmpDir}${sep}`, (err, directory) => { ``` ### `fs.open(path[, flags[, mode]], callback)` + <!-- YAML added: v0.0.2 changes: @@ -2936,6 +3016,7 @@ Functions based on `fs.open()` exhibit this behavior as well: `fs.writeFile()`, `fs.readFile()`, etc. ### `fs.opendir(path[, options], callback)` + <!-- YAML added: v12.12.0 changes: @@ -2966,6 +3047,7 @@ The `encoding` option sets the encoding for the `path` while opening the directory and subsequent read operations. ### `fs.read(fd, buffer, offset, length, position, callback)` + <!-- YAML added: v0.0.2 changes: @@ -3006,6 +3088,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a promise for an `Object` with `bytesRead` and `buffer` properties. ### `fs.read(fd, [options,] callback)` + <!-- YAML added: - v13.11.0 @@ -3018,6 +3101,7 @@ changes: description: Options object can be passed in to make Buffer, offset, length and position optional. --> + * `fd` {integer} * `options` {Object} * `buffer` {Buffer|TypedArray|DataView} **Default:** `Buffer.alloc(16384)` @@ -3034,6 +3118,7 @@ Similar to the [`fs.read()`][] function, this version takes an optional above values. ### `fs.readdir(path[, options], callback)` + <!-- YAML added: v0.1.8 changes: @@ -3063,7 +3148,7 @@ changes: * `withFileTypes` {boolean} **Default:** `false` * `callback` {Function} * `err` {Error} - * `files` {string[]|Buffer[]|fs.Dirent[]} + * `files` {string\[]|Buffer\[]|fs.Dirent\[]} Reads the contents of a directory. The callback gets two arguments `(err, files)` where `files` is an array of the names of the files in the directory excluding @@ -3080,6 +3165,7 @@ If `options.withFileTypes` is set to `true`, the `files` array will contain {fs.Dirent} objects. ### `fs.readFile(path[, options], callback)` + <!-- YAML added: v0.1.29 changes: @@ -3220,6 +3306,7 @@ analysis on the performance of `fs.readFile()` for multiple file sizes in different Node.js versions. ### `fs.readlink(path[, options], callback)` + <!-- YAML added: v0.1.31 changes: @@ -3255,6 +3342,7 @@ the link path passed to the callback. If the `encoding` is set to `'buffer'`, the link path returned will be passed as a {Buffer} object. ### `fs.readv(fd, buffers[, position], callback)` + <!-- YAML added: - v13.13.0 @@ -3262,12 +3350,12 @@ added: --> * `fd` {integer} -* `buffers` {ArrayBufferView[]} +* `buffers` {ArrayBufferView\[]} * `position` {integer} * `callback` {Function} * `err` {Error} * `bytesRead` {integer} - * `buffers` {ArrayBufferView[]} + * `buffers` {ArrayBufferView\[]} Read from a file specified by `fd` and write to an array of `ArrayBufferView`s using `readv()`. @@ -3283,6 +3371,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a promise for an `Object` with `bytesRead` and `buffers` properties. ### `fs.realpath(path[, options], callback)` + <!-- YAML added: v0.1.31 changes: @@ -3344,6 +3433,7 @@ If `path` resolves to a socket or a pipe, the function will return a system dependent name for that object. ### `fs.realpath.native(path[, options], callback)` + <!-- YAML added: v9.2.0 --> @@ -3371,6 +3461,7 @@ be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. ### `fs.rename(oldPath, newPath, callback)` + <!-- YAML added: v0.0.2 changes: @@ -3412,6 +3503,7 @@ rename('oldFile.txt', 'newFile.txt', (err) => { ``` ### `fs.rmdir(path[, options], callback)` + <!-- YAML added: v0.0.2 changes: @@ -3485,6 +3577,7 @@ To get a behavior similar to the `rm -rf` Unix command, use [`fs.rm()`][] with options `{ recursive: true, force: true }`. ### `fs.rm(path[, options], callback)` + <!-- YAML added: v14.14.0 --> @@ -3511,6 +3604,7 @@ utility). No arguments other than a possible exception are given to the completion callback. ### `fs.stat(path[, options], callback)` + <!-- YAML added: v0.0.2 changes: @@ -3624,6 +3718,7 @@ Stats { ``` ### `fs.symlink(target, path[, type], callback)` + <!-- YAML added: v0.1.31 changes: @@ -3675,6 +3770,7 @@ example/ ``` ### `fs.truncate(path[, len], callback)` + <!-- YAML added: v0.8.6 changes: @@ -3725,6 +3821,7 @@ in the future. See the POSIX truncate(2) documentation for more details. ### `fs.unlink(path, callback)` + <!-- YAML added: v0.0.2 changes: @@ -3764,6 +3861,7 @@ directory, use [`fs.rmdir()`][]. See the POSIX unlink(2) documentation for more details. ### `fs.unwatchFile(filename[, listener])` + <!-- YAML added: v0.1.31 --> @@ -3773,7 +3871,7 @@ added: v0.1.31 `fs.watchFile()` Stop watching for changes on `filename`. If `listener` is specified, only that -particular listener is removed. Otherwise, *all* listeners are removed, +particular listener is removed. Otherwise, _all_ listeners are removed, effectively stopping watching of `filename`. Calling `fs.unwatchFile()` with a filename that is not being watched is a @@ -3784,6 +3882,7 @@ Using [`fs.watch()`][] is more efficient than `fs.watchFile()` and and `fs.unwatchFile()` when possible. ### `fs.utimes(path, atime, mtime, callback)` + <!-- YAML added: v0.4.2 changes: @@ -3825,6 +3924,7 @@ The `atime` and `mtime` arguments follow these rules: `-Infinity`, an `Error` will be thrown. ### `fs.watch(filename[, options][, listener])` + <!-- YAML added: v0.5.10 changes: @@ -3851,7 +3951,7 @@ changes: specified, and only on supported platforms (See [caveats][]). **Default:** `false`. * `encoding` {string} Specifies the character encoding to be used for the - filename passed to the listener. **Default:** `'utf8'`. + filename passed to the listener. **Default:** `'utf8'`. * `signal` {AbortSignal} allows closing the watcher with an AbortSignal. * `listener` {Function|undefined} **Default:** `undefined` * `eventType` {string} @@ -3924,7 +4024,7 @@ this method is slower and less reliable. On Linux and macOS systems, `fs.watch()` resolves the path to an [inode][] and watches the inode. If the watched path is deleted and recreated, it is assigned a new inode. The watch will emit an event for the delete but will continue -watching the *original* inode. Events for the new inode will not be emitted. +watching the _original_ inode. Events for the new inode will not be emitted. This is expected behavior. AIX files retain the same inode for the lifetime of a file. Saving and closing a @@ -3953,6 +4053,7 @@ watch('somedir', (eventType, filename) => { ``` ### `fs.watchFile(filename[, options], listener)` + <!-- YAML added: v0.1.31 changes: @@ -4023,6 +4124,7 @@ This happens when: * the file is renamed and then renamed a second time back to its original name ### `fs.write(fd, buffer[, offset[, length[, position]]], callback)` + <!-- YAML added: v0.0.2 changes: @@ -4089,6 +4191,7 @@ The kernel ignores the position argument and always appends the data to the end of the file. ### `fs.write(fd, string[, position[, encoding]], callback)` + <!-- YAML added: v0.11.5 changes: @@ -4152,6 +4255,7 @@ active codepage with the `chcp 65001` command. See the [chcp][] docs for more details. ### `fs.writeFile(file, data[, options], callback)` + <!-- YAML added: v0.1.29 changes: @@ -4296,17 +4400,18 @@ a file name had been used instead of a descriptor, the file would be guaranteed to contain only `', World'`. ### `fs.writev(fd, buffers[, position], callback)` + <!-- YAML added: v12.9.0 --> * `fd` {integer} -* `buffers` {ArrayBufferView[]} +* `buffers` {ArrayBufferView\[]} * `position` {integer} * `callback` {Function} * `err` {Error} * `bytesWritten` {integer} - * `buffers` {ArrayBufferView[]} + * `buffers` {ArrayBufferView\[]} Write an array of `ArrayBufferView`s to the file specified by `fd` using `writev()`. @@ -4334,6 +4439,7 @@ The synchronous APIs perform all operations synchronously, blocking the event loop until the operation completes or fails. ### `fs.accessSync(path[, mode])` + <!-- YAML added: v0.11.15 changes: @@ -4368,6 +4474,7 @@ try { ``` ### `fs.appendFileSync(path, data[, options])` + <!-- YAML added: v0.6.7 changes: @@ -4432,6 +4539,7 @@ try { ``` ### `fs.chmodSync(path, mode)` + <!-- YAML added: v0.6.7 changes: @@ -4450,6 +4558,7 @@ this API: [`fs.chmod()`][]. See the POSIX chmod(2) documentation for more detail. ### `fs.chownSync(path, uid, gid)` + <!-- YAML added: v0.1.97 changes: @@ -4469,6 +4578,7 @@ This is the synchronous version of [`fs.chown()`][]. See the POSIX chown(2) documentation for more detail. ### `fs.closeSync(fd)` + <!-- YAML added: v0.1.21 --> @@ -4483,6 +4593,7 @@ through any other `fs` operation may lead to undefined behavior. See the POSIX close(2) documentation for more detail. ### `fs.copyFileSync(src, dest[, mode])` + <!-- YAML added: v8.5.0 changes: @@ -4527,6 +4638,7 @@ copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL); ``` ### `fs.cpSync(src, dest[, options])` + <!-- YAML added: v16.7.0 --> @@ -4541,7 +4653,7 @@ added: v16.7.0 exists, throw an error. **Default:** `false`. * `filter` {Function} Function to filter copied files/directories. Return `true` to copy the item, `false` to ignore it. **Default:** `undefined` - * `force` {boolean} overwrite existing file or directory. _The copy + * `force` {boolean} overwrite existing file or directory. The copy operation will ignore errors if you set this to false and the destination exists. Use the `errorOnExist` option to change this behavior. **Default:** `true`. @@ -4556,6 +4668,7 @@ When copying a directory to another directory, globs are not supported and behavior is similar to `cp dir1/ dir2/`. ### `fs.existsSync(path)` + <!-- YAML added: v0.1.21 changes: @@ -4585,6 +4698,7 @@ if (existsSync('/etc/passwd')) ``` ### `fs.fchmodSync(fd, mode)` + <!-- YAML added: v0.4.7 --> @@ -4597,6 +4711,7 @@ Sets the permissions on the file. Returns `undefined`. See the POSIX fchmod(2) documentation for more detail. ### `fs.fchownSync(fd, uid, gid)` + <!-- YAML added: v0.4.7 --> @@ -4610,6 +4725,7 @@ Sets the owner of the file. Returns `undefined`. See the POSIX fchown(2) documentation for more detail. ### `fs.fdatasyncSync(fd)` + <!-- YAML added: v0.1.96 --> @@ -4621,6 +4737,7 @@ operating system's synchronized I/O completion state. Refer to the POSIX fdatasync(2) documentation for details. Returns `undefined`. ### `fs.fstatSync(fd[, options])` + <!-- YAML added: v0.1.95 changes: @@ -4641,6 +4758,7 @@ Retrieves the {fs.Stats} for the file descriptor. See the POSIX fstat(2) documentation for more detail. ### `fs.fsyncSync(fd)` + <!-- YAML added: v0.1.96 --> @@ -4652,6 +4770,7 @@ device. The specific implementation is operating system and device specific. Refer to the POSIX fsync(2) documentation for more detail. Returns `undefined`. ### `fs.ftruncateSync(fd[, len])` + <!-- YAML added: v0.8.6 --> @@ -4665,6 +4784,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.ftruncate()`][]. ### `fs.futimesSync(fd, atime, mtime)` + <!-- YAML added: v0.4.2 changes: @@ -4681,6 +4801,7 @@ changes: Synchronous version of [`fs.futimes()`][]. Returns `undefined`. ### `fs.lchmodSync(path, mode)` + <!-- YAML deprecated: v0.4.7 --> @@ -4695,6 +4816,7 @@ This method is only implemented on macOS. See the POSIX lchmod(2) documentation for more detail. ### `fs.lchownSync(path, uid, gid)` + <!-- YAML changes: - version: v10.6.0 @@ -4713,6 +4835,7 @@ Set the owner for the path. Returns `undefined`. See the POSIX lchown(2) documentation for more details. ### `fs.lutimesSync(path, atime, mtime)` + <!-- YAML added: - v14.5.0 @@ -4728,6 +4851,7 @@ Returns `undefined`, or throws an exception when parameters are incorrect or the operation fails. This is the synchronous version of [`fs.lutimes()`][]. ### `fs.linkSync(existingPath, newPath)` + <!-- YAML added: v0.1.31 changes: @@ -4745,6 +4869,7 @@ Creates a new link from the `existingPath` to the `newPath`. See the POSIX link(2) documentation for more detail. Returns `undefined`. ### `fs.lstatSync(path[, options])` + <!-- YAML added: v0.1.30 changes: @@ -4778,6 +4903,7 @@ Retrieves the {fs.Stats} for the symbolic link referred to by `path`. See the POSIX lstat(2) documentation for more details. ### `fs.mkdirSync(path[, options])` + <!-- YAML added: v0.1.21 changes: @@ -4809,6 +4935,7 @@ This is the synchronous version of [`fs.mkdir()`][]. See the POSIX mkdir(2) documentation for more details. ### `fs.mkdtempSync(prefix[, options])` + <!-- YAML added: v5.10.0 changes: @@ -4833,6 +4960,7 @@ The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use. ### `fs.opendirSync(path[, options])` + <!-- YAML added: v12.12.0 changes: @@ -4860,6 +4988,7 @@ The `encoding` option sets the encoding for the `path` while opening the directory and subsequent read operations. ### `fs.openSync(path[, flags[, mode]])` + <!-- YAML added: v0.1.21 changes: @@ -4877,7 +5006,7 @@ changes: * `path` {string|Buffer|URL} * `flags` {string|number} **Default:** `'r'`. - See [support of file system `flags`][]. + See [support of file system `flags`][]. * `mode` {string|integer} **Default:** `0o666` * Returns: {number} @@ -4887,6 +5016,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.open()`][]. ### `fs.readdirSync(path[, options])` + <!-- YAML added: v0.1.21 changes: @@ -4903,7 +5033,7 @@ changes: * `options` {string|Object} * `encoding` {string} **Default:** `'utf8'` * `withFileTypes` {boolean} **Default:** `false` -* Returns: {string[]|Buffer[]|fs.Dirent[]} +* Returns: {string\[]|Buffer\[]|fs.Dirent\[]} Reads the contents of the directory. @@ -4918,6 +5048,7 @@ If `options.withFileTypes` is set to `true`, the result will contain {fs.Dirent} objects. ### `fs.readFileSync(path[, options])` + <!-- YAML added: v0.1.8 changes: @@ -4959,6 +5090,7 @@ readFileSync('<directory>'); // => <data> ``` ### `fs.readlinkSync(path[, options])` + <!-- YAML added: v0.1.31 changes: @@ -4983,6 +5115,7 @@ the link path returned. If the `encoding` is set to `'buffer'`, the link path returned will be passed as a {Buffer} object. ### `fs.readSync(fd, buffer, offset, length, position)` + <!-- YAML added: v0.1.21 changes: @@ -5008,6 +5141,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.read()`][]. ### `fs.readSync(fd, buffer[, options])` + <!-- YAML added: - v13.13.0 @@ -5038,6 +5172,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.read()`][]. ### `fs.readvSync(fd, buffers[, position])` + <!-- YAML added: - v13.13.0 @@ -5045,7 +5180,7 @@ added: --> * `fd` {integer} -* `buffers` {ArrayBufferView[]} +* `buffers` {ArrayBufferView\[]} * `position` {integer} * Returns: {number} The number of bytes read. @@ -5053,6 +5188,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.readv()`][]. ### `fs.realpathSync(path[, options])` + <!-- YAML added: v0.1.31 changes: @@ -5083,6 +5219,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.realpath()`][]. ### `fs.realpathSync.native(path[, options])` + <!-- YAML added: v9.2.0 --> @@ -5106,6 +5243,7 @@ be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. ### `fs.renameSync(oldPath, newPath)` + <!-- YAML added: v0.1.21 changes: @@ -5124,6 +5262,7 @@ Renames the file from `oldPath` to `newPath`. Returns `undefined`. See the POSIX rename(2) documentation for more details. ### `fs.rmdirSync(path[, options])` + <!-- YAML added: v0.1.21 changes: @@ -5186,6 +5325,7 @@ To get a behavior similar to the `rm -rf` Unix command, use [`fs.rmSync()`][] with options `{ recursive: true, force: true }`. ### `fs.rmSync(path[, options])` + <!-- YAML added: v14.14.0 --> @@ -5209,6 +5349,7 @@ Synchronously removes files and directories (modeled on the standard POSIX `rm` utility). Returns `undefined`. ### `fs.statSync(path[, options])` + <!-- YAML added: v0.1.21 changes: @@ -5240,6 +5381,7 @@ changes: Retrieves the {fs.Stats} for the path. ### `fs.symlinkSync(target, path[, type])` + <!-- YAML added: v0.1.31 changes: @@ -5264,6 +5406,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.symlink()`][]. ### `fs.truncateSync(path[, len])` + <!-- YAML added: v0.8.6 --> @@ -5278,6 +5421,7 @@ Passing a file descriptor is deprecated and may result in an error being thrown in the future. ### `fs.unlinkSync(path)` + <!-- YAML added: v0.1.21 changes: @@ -5292,6 +5436,7 @@ changes: Synchronous unlink(2). Returns `undefined`. ### `fs.utimesSync(path, atime, mtime)` + <!-- YAML added: v0.4.2 changes: @@ -5319,6 +5464,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.utimes()`][]. ### `fs.writeFileSync(file, data[, options])` + <!-- YAML added: v0.1.29 changes: @@ -5361,6 +5507,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.writeFile()`][]. ### `fs.writeSync(fd, buffer[, offset[, length[, position]]])` + <!-- YAML added: v0.1.21 changes: @@ -5398,6 +5545,7 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.write(fd, buffer...)`][]. ### `fs.writeSync(fd, string[, position[, encoding]])` + <!-- YAML added: v0.11.5 changes: @@ -5427,12 +5575,13 @@ For detailed information, see the documentation of the asynchronous version of this API: [`fs.write(fd, string...)`][]. ### `fs.writevSync(fd, buffers[, position])` + <!-- YAML added: v12.9.0 --> * `fd` {integer} -* `buffers` {ArrayBufferView[]} +* `buffers` {ArrayBufferView\[]} * `position` {integer} * Returns: {number} The number of bytes written. @@ -5445,6 +5594,7 @@ The common objects are shared by all of the file system API variants (promise, callback, and synchronous). ### Class: `fs.Dir` + <!-- YAML added: v12.12.0 --> @@ -5470,6 +5620,7 @@ When using the async iterator, the {fs.Dir} object will be automatically closed after the iterator exits. #### `dir.close()` + <!-- YAML added: v12.12.0 --> @@ -5483,6 +5634,7 @@ A promise is returned that will be resolved after the resource has been closed. #### `dir.close(callback)` + <!-- YAML added: v12.12.0 --> @@ -5496,6 +5648,7 @@ Subsequent reads will result in errors. The `callback` will be called after the resource handle has been closed. #### `dir.closeSync()` + <!-- YAML added: v12.12.0 --> @@ -5504,6 +5657,7 @@ Synchronously close the directory's underlying resource handle. Subsequent reads will result in errors. #### `dir.path` + <!-- YAML added: v12.12.0 --> @@ -5514,6 +5668,7 @@ The read-only path of this directory as was provided to [`fs.opendir()`][], [`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. #### `dir.read()` + <!-- YAML added: v12.12.0 --> @@ -5532,6 +5687,7 @@ Entries added or removed while iterating over the directory might not be included in the iteration results. #### `dir.read(callback)` + <!-- YAML added: v12.12.0 --> @@ -5552,6 +5708,7 @@ Entries added or removed while iterating over the directory might not be included in the iteration results. #### `dir.readSync()` + <!-- YAML added: v12.12.0 --> @@ -5569,6 +5726,7 @@ Entries added or removed while iterating over the directory might not be included in the iteration results. #### `dir[Symbol.asyncIterator]()` + <!-- YAML added: v12.12.0 --> @@ -5589,6 +5747,7 @@ Entries added or removed while iterating over the directory might not be included in the iteration results. ### Class: `fs.Dirent` + <!-- YAML added: v10.10.0 --> @@ -5602,6 +5761,7 @@ the `withFileTypes` option set to `true`, the resulting array is filled with {fs.Dirent} objects, rather than strings or {Buffer}s. #### `dirent.isBlockDevice()` + <!-- YAML added: v10.10.0 --> @@ -5611,6 +5771,7 @@ added: v10.10.0 Returns `true` if the {fs.Dirent} object describes a block device. #### `dirent.isCharacterDevice()` + <!-- YAML added: v10.10.0 --> @@ -5620,6 +5781,7 @@ added: v10.10.0 Returns `true` if the {fs.Dirent} object describes a character device. #### `dirent.isDirectory()` + <!-- YAML added: v10.10.0 --> @@ -5630,6 +5792,7 @@ Returns `true` if the {fs.Dirent} object describes a file system directory. #### `dirent.isFIFO()` + <!-- YAML added: v10.10.0 --> @@ -5640,6 +5803,7 @@ Returns `true` if the {fs.Dirent} object describes a first-in-first-out (FIFO) pipe. #### `dirent.isFile()` + <!-- YAML added: v10.10.0 --> @@ -5649,6 +5813,7 @@ added: v10.10.0 Returns `true` if the {fs.Dirent} object describes a regular file. #### `dirent.isSocket()` + <!-- YAML added: v10.10.0 --> @@ -5658,6 +5823,7 @@ added: v10.10.0 Returns `true` if the {fs.Dirent} object describes a socket. #### `dirent.isSymbolicLink()` + <!-- YAML added: v10.10.0 --> @@ -5667,6 +5833,7 @@ added: v10.10.0 Returns `true` if the {fs.Dirent} object describes a symbolic link. #### `dirent.name` + <!-- YAML added: v10.10.0 --> @@ -5678,6 +5845,7 @@ value is determined by the `options.encoding` passed to [`fs.readdir()`][] or [`fs.readdirSync()`][]. ### Class: `fs.FSWatcher` + <!-- YAML added: v0.5.8 --> @@ -5691,6 +5859,7 @@ All {fs.FSWatcher} objects emit a `'change'` event whenever a specific watched file is modified. #### Event: `'change'` + <!-- YAML added: v0.5.8 --> @@ -5718,6 +5887,7 @@ watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => { ``` #### Event: `'close'` + <!-- YAML added: v10.0.0 --> @@ -5726,6 +5896,7 @@ Emitted when the watcher stops watching for changes. The closed {fs.FSWatcher} object is no longer usable in the event handler. #### Event: `'error'` + <!-- YAML added: v0.5.8 --> @@ -5736,6 +5907,7 @@ Emitted when an error occurs while watching the file. The errored {fs.FSWatcher} object is no longer usable in the event handler. #### `watcher.close()` + <!-- YAML added: v0.5.8 --> @@ -5744,6 +5916,7 @@ Stop watching for changes on the given {fs.FSWatcher}. Once stopped, the {fs.FSWatcher} object is no longer usable. #### `watcher.ref()` + <!-- YAML added: - v14.3.0 @@ -5752,7 +5925,7 @@ added: * Returns: {fs.FSWatcher} -When called, requests that the Node.js event loop *not* exit so long as the +When called, requests that the Node.js event loop _not_ exit so long as the {fs.FSWatcher} is active. Calling `watcher.ref()` multiple times will have no effect. @@ -5761,6 +5934,7 @@ unnecessary to call `watcher.ref()` unless `watcher.unref()` had been called previously. #### `watcher.unref()` + <!-- YAML added: - v14.3.0 @@ -5776,6 +5950,7 @@ callback is invoked. Calling `watcher.unref()` multiple times will have no effect. ### Class: `fs.StatWatcher` + <!-- YAML added: - v14.3.0 @@ -5788,6 +5963,7 @@ A successful call to `fs.watchFile()` method will return a new {fs.StatWatcher} object. #### `watcher.ref()` + <!-- YAML added: - v14.3.0 @@ -5796,7 +5972,7 @@ added: * Returns: {fs.StatWatcher} -When called, requests that the Node.js event loop *not* exit so long as the +When called, requests that the Node.js event loop _not_ exit so long as the {fs.StatWatcher} is active. Calling `watcher.ref()` multiple times will have no effect. @@ -5805,6 +5981,7 @@ unnecessary to call `watcher.ref()` unless `watcher.unref()` had been called previously. #### `watcher.unref()` + <!-- YAML added: - v14.3.0 @@ -5820,6 +5997,7 @@ callback is invoked. Calling `watcher.unref()` multiple times will have no effect. ### Class: `fs.ReadStream` + <!-- YAML added: v0.1.93 --> @@ -5830,6 +6008,7 @@ Instances of {fs.ReadStream} are created and returned using the [`fs.createReadStream()`][] function. #### Event: `'close'` + <!-- YAML added: v0.1.93 --> @@ -5837,6 +6016,7 @@ added: v0.1.93 Emitted when the {fs.ReadStream}'s underlying file descriptor has been closed. #### Event: `'open'` + <!-- YAML added: v0.1.93 --> @@ -5846,6 +6026,7 @@ added: v0.1.93 Emitted when the {fs.ReadStream}'s file descriptor has been opened. #### Event: `'ready'` + <!-- YAML added: v9.11.0 --> @@ -5855,6 +6036,7 @@ Emitted when the {fs.ReadStream} is ready to be used. Fires immediately after `'open'`. #### `readStream.bytesRead` + <!-- YAML added: v6.4.0 --> @@ -5864,6 +6046,7 @@ added: v6.4.0 The number of bytes that have been read so far. #### `readStream.path` + <!-- YAML added: v0.1.93 --> @@ -5877,6 +6060,7 @@ argument to `fs.createReadStream()`. If `path` is passed as a string, then `readStream.path` will be `undefined`. #### `readStream.pending` + <!-- YAML added: - v11.2.0 @@ -5889,6 +6073,7 @@ This property is `true` if the underlying file has not been opened yet, i.e. before the `'ready'` event is emitted. ### Class: `fs.Stats` + <!-- YAML added: v0.1.21 changes: @@ -5956,6 +6141,7 @@ BigIntStats { ``` #### `stats.isBlockDevice()` + <!-- YAML added: v0.1.10 --> @@ -5965,6 +6151,7 @@ added: v0.1.10 Returns `true` if the {fs.Stats} object describes a block device. #### `stats.isCharacterDevice()` + <!-- YAML added: v0.1.10 --> @@ -5974,6 +6161,7 @@ added: v0.1.10 Returns `true` if the {fs.Stats} object describes a character device. #### `stats.isDirectory()` + <!-- YAML added: v0.1.10 --> @@ -5987,6 +6175,7 @@ always return `false`. This is because [`fs.lstat()`][] returns information about a symbolic link itself and not the path it resolves to. #### `stats.isFIFO()` + <!-- YAML added: v0.1.10 --> @@ -5997,6 +6186,7 @@ Returns `true` if the {fs.Stats} object describes a first-in-first-out (FIFO) pipe. #### `stats.isFile()` + <!-- YAML added: v0.1.10 --> @@ -6006,6 +6196,7 @@ added: v0.1.10 Returns `true` if the {fs.Stats} object describes a regular file. #### `stats.isSocket()` + <!-- YAML added: v0.1.10 --> @@ -6015,6 +6206,7 @@ added: v0.1.10 Returns `true` if the {fs.Stats} object describes a socket. #### `stats.isSymbolicLink()` + <!-- YAML added: v0.1.10 --> @@ -6086,6 +6278,7 @@ The file system block size for i/o operations. The number of blocks allocated for this file. #### `stats.atimeMs` + <!-- YAML added: v8.1.0 --> @@ -6096,6 +6289,7 @@ The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch. #### `stats.mtimeMs` + <!-- YAML added: v8.1.0 --> @@ -6106,6 +6300,7 @@ The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch. #### `stats.ctimeMs` + <!-- YAML added: v8.1.0 --> @@ -6116,6 +6311,7 @@ The timestamp indicating the last time the file status was changed expressed in milliseconds since the POSIX Epoch. #### `stats.birthtimeMs` + <!-- YAML added: v8.1.0 --> @@ -6126,6 +6322,7 @@ The timestamp indicating the creation time of this file expressed in milliseconds since the POSIX Epoch. #### `stats.atimeNs` + <!-- YAML added: v12.10.0 --> @@ -6138,6 +6335,7 @@ The timestamp indicating the last time this file was accessed expressed in nanoseconds since the POSIX Epoch. #### `stats.mtimeNs` + <!-- YAML added: v12.10.0 --> @@ -6150,6 +6348,7 @@ The timestamp indicating the last time this file was modified expressed in nanoseconds since the POSIX Epoch. #### `stats.ctimeNs` + <!-- YAML added: v12.10.0 --> @@ -6162,6 +6361,7 @@ The timestamp indicating the last time the file status was changed expressed in nanoseconds since the POSIX Epoch. #### `stats.birthtimeNs` + <!-- YAML added: v12.10.0 --> @@ -6174,6 +6374,7 @@ The timestamp indicating the creation time of this file expressed in nanoseconds since the POSIX Epoch. #### `stats.atime` + <!-- YAML added: v0.11.13 --> @@ -6183,6 +6384,7 @@ added: v0.11.13 The timestamp indicating the last time this file was accessed. #### `stats.mtime` + <!-- YAML added: v0.11.13 --> @@ -6192,6 +6394,7 @@ added: v0.11.13 The timestamp indicating the last time this file was modified. #### `stats.ctime` + <!-- YAML added: v0.11.13 --> @@ -6201,6 +6404,7 @@ added: v0.11.13 The timestamp indicating the last time the file status was changed. #### `stats.birthtime` + <!-- YAML added: v0.11.13 --> @@ -6250,6 +6454,7 @@ Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As of 0.12, `ctime` is not "creation time", and on Unix systems, it never was. ### Class: `fs.WriteStream` + <!-- YAML added: v0.1.93 --> @@ -6260,6 +6465,7 @@ Instances of {fs.WriteStream} are created and returned using the [`fs.createWriteStream()`][] function. #### Event: `'close'` + <!-- YAML added: v0.1.93 --> @@ -6267,6 +6473,7 @@ added: v0.1.93 Emitted when the {fs.WriteStream}'s underlying file descriptor has been closed. #### Event: `'open'` + <!-- YAML added: v0.1.93 --> @@ -6276,6 +6483,7 @@ added: v0.1.93 Emitted when the {fs.WriteStream}'s file is opened. #### Event: `'ready'` + <!-- YAML added: v9.11.0 --> @@ -6285,6 +6493,7 @@ Emitted when the {fs.WriteStream} is ready to be used. Fires immediately after `'open'`. #### `writeStream.bytesWritten` + <!-- YAML added: v0.4.7 --> @@ -6293,6 +6502,7 @@ The number of bytes written so far. Does not include data that is still queued for writing. #### `writeStream.close([callback])` + <!-- YAML added: v0.9.4 --> @@ -6305,6 +6515,7 @@ callback that will be executed once the `writeStream` is closed. #### `writeStream.path` + <!-- YAML added: v0.1.93 --> @@ -6315,6 +6526,7 @@ argument to [`fs.createWriteStream()`][]. If `path` is passed as a string, then `writeStream.path` will be a {Buffer}. #### `writeStream.pending` + <!-- YAML added: v11.2.0 --> @@ -6734,9 +6946,11 @@ try { ``` #### File URL paths + <!-- YAML added: v7.6.0 --> + For most `fs` module functions, the `path` or `filename` argument may be passed as a {URL} object using the `file:` protocol. @@ -6858,7 +7072,7 @@ example `fs.readdirSync('C:\\')` can potentially return a different result than On POSIX systems, for every process, the kernel maintains a table of currently open files and resources. Each open file is assigned a simple numeric -identifier called a *file descriptor*. At the system-level, all file system +identifier called a _file descriptor_. At the system-level, all file system operations use these file descriptors to identify and track each specific file. Windows systems use a different but conceptually similar mechanism for tracking resources. To simplify things for users, Node.js abstracts away the diff --git a/doc/api/globals.md b/doc/api/globals.md index abb992ebe9a..3d2155176a9 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -19,6 +19,7 @@ that are part of the JavaScript language itself, which are also globally accessible. ## Class: `AbortController` + <!-- YAML added: - v15.0.0 @@ -46,6 +47,7 @@ console.log(ac.signal.aborted); // Prints True ``` ### `abortController.abort()` + <!-- YAML added: - v15.0.0 @@ -56,6 +58,7 @@ Triggers the abort signal, causing the `abortController.signal` to emit the `'abort'` event. ### `abortController.signal` + <!-- YAML added: - v15.0.0 @@ -65,6 +68,7 @@ added: * Type: {AbortSignal} ### Class: `AbortSignal` + <!-- YAML added: - v15.0.0 @@ -77,6 +81,7 @@ The `AbortSignal` is used to notify observers when the `abortController.abort()` method is called. #### Static method: `AbortSignal.abort()` + <!-- YAML added: - v15.12.0 @@ -88,6 +93,7 @@ added: Returns a new already aborted `AbortSignal`. #### Event: `'abort'` + <!-- YAML added: - v15.0.0 @@ -124,6 +130,7 @@ removed as soon as the `'abort'` event is handled. Failure to do so may result in memory leaks. #### `abortSignal.aborted` + <!-- YAML added: - v15.0.0 @@ -133,6 +140,7 @@ added: * Type: {boolean} True after the `AbortController` has been aborted. #### `abortSignal.onabort` + <!-- YAML added: - v15.0.0 @@ -145,6 +153,7 @@ An optional callback function that may be set by user code to be notified when the `abortController.abort()` function has been called. ## Class: `Buffer` + <!-- YAML added: v0.1.103 --> @@ -164,6 +173,7 @@ This variable may appear to be global but is not. See [`__dirname`][]. This variable may appear to be global but is not. See [`__filename`][]. ## `atob(data)` + <!-- YAML added: v16.0.0 --> @@ -173,6 +183,7 @@ added: v16.0.0 Global alias for [`buffer.atob()`][]. ## `btoa(data)` + <!-- YAML added: v16.0.0 --> @@ -182,6 +193,7 @@ added: v16.0.0 Global alias for [`buffer.btoa()`][]. ## `clearImmediate(immediateObject)` + <!-- YAML added: v0.9.1 --> @@ -191,6 +203,7 @@ added: v0.9.1 [`clearImmediate`][] is described in the [timers][] section. ## `clearInterval(intervalObject)` + <!-- YAML added: v0.0.1 --> @@ -200,6 +213,7 @@ added: v0.0.1 [`clearInterval`][] is described in the [timers][] section. ## `clearTimeout(timeoutObject)` + <!-- YAML added: v0.0.1 --> @@ -209,6 +223,7 @@ added: v0.0.1 [`clearTimeout`][] is described in the [timers][] section. ## `console` + <!-- YAML added: v0.1.100 --> @@ -220,6 +235,7 @@ added: v0.1.100 Used to print to stdout and stderr. See the [`console`][] section. ## `Event` + <!-- YAML added: v15.0.0 changes: @@ -234,6 +250,7 @@ A browser-compatible implementation of the `Event` class. See [`EventTarget` and `Event` API][] for more details. ## `EventTarget` + <!-- YAML added: v15.0.0 changes: @@ -252,6 +269,7 @@ A browser-compatible implementation of the `EventTarget` class. See This variable may appear to be global but is not. See [`exports`][]. ## `global` + <!-- YAML added: v0.1.27 --> @@ -266,6 +284,7 @@ Node.js this is different. The top-level scope is not the global scope; `var something` inside a Node.js module will be local to that module. ## `MessageChannel` + <!-- YAML added: v15.0.0 --> @@ -275,6 +294,7 @@ added: v15.0.0 The `MessageChannel` class. See [`MessageChannel`][] for more details. ## `MessageEvent` + <!-- YAML added: v15.0.0 --> @@ -284,6 +304,7 @@ added: v15.0.0 The `MessageEvent` class. See [`MessageEvent`][] for more details. ## `MessagePort` + <!-- YAML added: v15.0.0 --> @@ -301,6 +322,7 @@ This variable may appear to be global but is not. See [`module`][]. The [`perf_hooks.performance`][] object. ## `process` + <!-- YAML added: v0.1.7 --> @@ -312,6 +334,7 @@ added: v0.1.7 The process object. See the [`process` object][] section. ## `queueMicrotask(callback)` + <!-- YAML added: v11.0.0 --> @@ -355,6 +378,7 @@ DataHandler.prototype.load = async function load(key) { This variable may appear to be global but is not. See [`require()`][]. ## `setImmediate(callback[, ...args])` + <!-- YAML added: v0.9.1 --> @@ -364,6 +388,7 @@ added: v0.9.1 [`setImmediate`][] is described in the [timers][] section. ## `setInterval(callback, delay[, ...args])` + <!-- YAML added: v0.0.1 --> @@ -373,6 +398,7 @@ added: v0.0.1 [`setInterval`][] is described in the [timers][] section. ## `setTimeout(callback, delay[, ...args])` + <!-- YAML added: v0.0.1 --> @@ -382,6 +408,7 @@ added: v0.0.1 [`setTimeout`][] is described in the [timers][] section. ## `DOMException` + <!-- YAML added: v17.0.0 --> @@ -391,6 +418,7 @@ added: v17.0.0 The WHATWG `DOMException` class. See [`DOMException`][] for more details. ## `TextDecoder` + <!-- YAML added: v11.0.0 --> @@ -400,6 +428,7 @@ added: v11.0.0 The WHATWG `TextDecoder` class. See the [`TextDecoder`][] section. ## `TextEncoder` + <!-- YAML added: v11.0.0 --> @@ -409,6 +438,7 @@ added: v11.0.0 The WHATWG `TextEncoder` class. See the [`TextEncoder`][] section. ## `URL` + <!-- YAML added: v10.0.0 --> @@ -418,6 +448,7 @@ added: v10.0.0 The WHATWG `URL` class. See the [`URL`][] section. ## `URLSearchParams` + <!-- YAML added: v10.0.0 --> @@ -427,6 +458,7 @@ added: v10.0.0 The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section. ## `WebAssembly` + <!-- YAML added: v8.0.0 --> diff --git a/doc/api/http.md b/doc/api/http.md index 09aa425b0f9..722defc987d 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -17,6 +17,7 @@ user is able to stream data. HTTP message headers are represented by an object like this: <!-- eslint-skip --> + ```js { 'content-length': '123', 'content-type': 'text/plain', @@ -40,6 +41,7 @@ example, the previous message header object might have a `rawHeaders` list like the following: <!-- eslint-disable semi --> + ```js [ 'ConTent-Length', '123456', 'content-LENGTH', '123', @@ -50,6 +52,7 @@ list like the following: ``` ## Class: `http.Agent` + <!-- YAML added: v0.3.4 --> @@ -110,6 +113,7 @@ http.get({ ``` ### `new Agent([options])` + <!-- YAML added: v0.3.4 changes: @@ -146,13 +150,13 @@ changes: for TCP Keep-Alive packets. Ignored when the `keepAlive` option is `false` or `undefined`. **Default:** `1000`. * `maxSockets` {number} Maximum number of sockets to allow per host. - If the same host opens multiple concurrent connections, each request - will use new socket until the `maxSockets` value is reached. - If the host attempts to open more connections than `maxSockets`, - the additional requests will enter into a pending request queue, and - will enter active connection state when an existing connection terminates. - This makes sure there are at most `maxSockets` active connections at - any point in time, from a given host. + If the same host opens multiple concurrent connections, each request + will use new socket until the `maxSockets` value is reached. + If the host attempts to open more connections than `maxSockets`, + the additional requests will enter into a pending request queue, and + will enter active connection state when an existing connection terminates. + This makes sure there are at most `maxSockets` active connections at + any point in time, from a given host. **Default:** `Infinity`. * `maxTotalSockets` {number} Maximum number of sockets allowed for all hosts in total. Each request will use a new socket @@ -191,6 +195,7 @@ http.request(options, onResponseCallback); ``` ### `agent.createConnection(options[, callback])` + <!-- YAML added: v0.11.4 --> @@ -215,6 +220,7 @@ type other than {net.Socket}. `callback` has a signature of `(err, stream)`. ### `agent.keepSocketAlive(socket)` + <!-- YAML added: v8.1.0 --> @@ -238,6 +244,7 @@ The `socket` argument can be an instance of {net.Socket}, a subclass of {stream.Duplex}. ### `agent.reuseSocket(socket, request)` + <!-- YAML added: v8.1.0 --> @@ -258,6 +265,7 @@ The `socket` argument can be an instance of {net.Socket}, a subclass of {stream.Duplex}. ### `agent.destroy()` + <!-- YAML added: v0.11.4 --> @@ -271,6 +279,7 @@ sockets might stay open for quite a long time before the server terminates them. ### `agent.freeSockets` + <!-- YAML added: v0.11.4 changes: @@ -288,6 +297,7 @@ Sockets in the `freeSockets` list will be automatically destroyed and removed from the array on `'timeout'`. ### `agent.getName(options)` + <!-- YAML added: v0.11.4 --> @@ -308,6 +318,7 @@ the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options that determine socket reusability. ### `agent.maxFreeSockets` + <!-- YAML added: v0.11.7 --> @@ -319,6 +330,7 @@ sets the maximum number of sockets that will be left open in the free state. ### `agent.maxSockets` + <!-- YAML added: v0.3.6 --> @@ -329,6 +341,7 @@ By default set to `Infinity`. Determines how many concurrent sockets the agent can have open per origin. Origin is the returned value of [`agent.getName()`][]. ### `agent.maxTotalSockets` + <!-- YAML added: - v14.5.0 @@ -341,6 +354,7 @@ By default set to `Infinity`. Determines how many concurrent sockets the agent can have open. Unlike `maxSockets`, this parameter applies across all origins. ### `agent.requests` + <!-- YAML added: v0.5.9 changes: @@ -355,6 +369,7 @@ An object which contains queues of requests that have not yet been assigned to sockets. Do not modify. ### `agent.sockets` + <!-- YAML added: v0.3.6 changes: @@ -369,6 +384,7 @@ An object which contains arrays of sockets currently in use by the agent. Do not modify. ## Class: `http.ClientRequest` + <!-- YAML added: v0.1.17 --> @@ -378,7 +394,7 @@ added: v0.1.17 This object is created internally and returned from [`http.request()`][]. It represents an _in-progress_ request whose header has already been queued. The header is still mutable using the [`setHeader(name, value)`][], - [`getHeader(name)`][], [`removeHeader(name)`][] API. The actual header will +[`getHeader(name)`][], [`removeHeader(name)`][] API. The actual header will be sent along with the first data chunk or when calling [`request.end()`][]. To get the response, add a listener for [`'response'`][] to the request object. @@ -405,6 +421,7 @@ Node.js does not check whether Content-Length and the length of the body which has been transmitted are equal or not. ### Event: `'abort'` + <!-- YAML added: v1.4.1 deprecated: v17.0.0 @@ -416,6 +433,7 @@ Emitted when the request has been aborted by the client. This event is only emitted on the first call to `abort()`. ### Event: `'connect'` + <!-- YAML added: v0.7.0 --> @@ -490,6 +508,7 @@ proxy.listen(1337, '127.0.0.1', () => { ``` ### Event: `'continue'` + <!-- YAML added: v0.3.2 --> @@ -499,6 +518,7 @@ the request contained 'Expect: 100-continue'. This is an instruction that the client should send the request body. ### Event: `'information'` + <!-- YAML added: v10.0.0 --> @@ -510,7 +530,7 @@ added: v10.0.0 * `statusCode` {integer} * `statusMessage` {string} * `headers` {Object} - * `rawHeaders` {string[]} + * `rawHeaders` {string\[]} Emitted when the server sends a 1xx intermediate response (excluding 101 Upgrade). The listeners of this event will receive an object containing the @@ -541,6 +561,7 @@ upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the [`'upgrade'`][] event instead. ### Event: `'response'` + <!-- YAML added: v0.1.0 --> @@ -551,6 +572,7 @@ Emitted when a response is received to this request. This event is emitted only once. ### Event: `'socket'` + <!-- YAML added: v0.5.3 --> @@ -562,6 +584,7 @@ a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. ### Event: `'timeout'` + <!-- YAML added: v0.7.8 --> @@ -572,6 +595,7 @@ that the socket has been idle. The request must be destroyed manually. See also: [`request.setTimeout()`][]. ### Event: `'upgrade'` + <!-- YAML added: v0.1.94 --> @@ -633,6 +657,7 @@ server.listen(1337, '127.0.0.1', () => { ``` ### `request.abort()` + <!-- YAML added: v0.3.8 deprecated: @@ -646,6 +671,7 @@ Marks the request as aborting. Calling this will cause remaining data in the response to be dropped and the socket to be destroyed. ### `request.aborted` + <!-- YAML added: v0.11.14 deprecated: v17.0.0 @@ -663,6 +689,7 @@ The `request.aborted` property will be `true` if the request has been aborted. ### `request.connection` + <!-- YAML added: v0.3.0 deprecated: v13.0.0 @@ -675,6 +702,7 @@ deprecated: v13.0.0 See [`request.socket`][]. ### `request.end([data[, encoding]][, callback])` + <!-- YAML added: v0.1.90 changes: @@ -699,6 +727,7 @@ If `callback` is specified, it will be called when the request stream is finished. ### `request.destroy([error])` + <!-- YAML added: v0.3.0 changes: @@ -718,6 +747,7 @@ in the response to be dropped and the socket to be destroyed. See [`writable.destroy()`][] for further details. #### `request.destroyed` + <!-- YAML added: - v14.1.0 @@ -731,6 +761,7 @@ Is `true` after [`request.destroy()`][] has been called. See [`writable.destroyed`][] for further details. ### `request.finished` + <!-- YAML added: v0.0.1 deprecated: @@ -747,6 +778,7 @@ has been called. `request.end()` will automatically be called if the request was initiated via [`http.get()`][]. ### `request.flushHeaders()` + <!-- YAML added: v1.6.0 --> @@ -762,6 +794,7 @@ data is not sent until possibly much later. `request.flushHeaders()` bypasses the optimization and kickstarts the request. ### `request.getHeader(name)` + <!-- YAML added: v1.6.0 --> @@ -786,13 +819,14 @@ const cookie = request.getHeader('Cookie'); ``` ### `request.getRawHeaderNames()` + <!-- YAML added: - v15.13.0 - v14.17.0 --> -* Returns: {string[]} +* Returns: {string\[]} Returns an array containing the unique names of the current outgoing raw headers. Header names are returned with their exact casing being set. @@ -812,6 +846,7 @@ const headerNames = request.getRawHeaderNames(); Limits maximum response headers count. If set to 0, no limit will be applied. ### `request.path` + <!-- YAML added: v0.4.0 --> @@ -819,6 +854,7 @@ added: v0.4.0 * {string} The request path. ### `request.method` + <!-- YAML added: v0.1.97 --> @@ -826,6 +862,7 @@ added: v0.1.97 * {string} The request method. ### `request.host` + <!-- YAML added: - v14.5.0 @@ -835,6 +872,7 @@ added: * {string} The request host. ### `request.protocol` + <!-- YAML added: - v14.5.0 @@ -844,6 +882,7 @@ added: * {string} The request protocol. ### `request.removeHeader(name)` + <!-- YAML added: v1.6.0 --> @@ -857,6 +896,7 @@ request.removeHeader('Content-Type'); ``` ### `request.reusedSocket` + <!-- YAML added: - v13.0.0 @@ -914,6 +954,7 @@ retriableRequest(); ``` ### `request.setHeader(name, value)` + <!-- YAML added: v1.6.0 --> @@ -939,6 +980,7 @@ request.setHeader('Cookie', ['type=ninja', 'language=javascript']); ``` ### `request.setNoDelay([noDelay])` + <!-- YAML added: v0.5.9 --> @@ -949,6 +991,7 @@ Once a socket is assigned to this request and is connected [`socket.setNoDelay()`][] will be called. ### `request.setSocketKeepAlive([enable][, initialDelay])` + <!-- YAML added: v0.5.9 --> @@ -960,6 +1003,7 @@ Once a socket is assigned to this request and is connected [`socket.setKeepAlive()`][] will be called. ### `request.setTimeout(timeout[, callback])` + <!-- YAML added: v0.5.9 changes: @@ -977,6 +1021,7 @@ Once a socket is assigned to this request and is connected [`socket.setTimeout()`][] will be called. ### `request.socket` + <!-- YAML added: v0.3.0 --> @@ -1007,6 +1052,7 @@ a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. ### `request.writableEnded` + <!-- YAML added: v12.9.0 --> @@ -1018,6 +1064,7 @@ does not indicate whether the data has been flushed, for this use [`request.writableFinished`][] instead. ### `request.writableFinished` + <!-- YAML added: v12.7.0 --> @@ -1028,6 +1075,7 @@ Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. ### `request.write(chunk[, encoding][, callback])` + <!-- YAML added: v0.1.29 --> @@ -1057,6 +1105,7 @@ When `write` function is called with empty string or buffer, it does nothing and waits for more input. ## Class: `http.Server` + <!-- YAML added: v0.1.17 --> @@ -1064,6 +1113,7 @@ added: v0.1.17 * Extends: {net.Server} ### Event: `'checkContinue'` + <!-- YAML added: v0.3.0 --> @@ -1084,6 +1134,7 @@ When this event is emitted and handled, the [`'request'`][] event will not be emitted. ### Event: `'checkExpectation'` + <!-- YAML added: v5.5.0 --> @@ -1099,6 +1150,7 @@ When this event is emitted and handled, the [`'request'`][] event will not be emitted. ### Event: `'clientError'` + <!-- YAML added: v0.1.94 changes: @@ -1151,7 +1203,7 @@ server.listen(8000); When the `'clientError'` event occurs, there is no `request` or `response` object, so any HTTP response sent, including response headers and payload, -*must* be written directly to the `socket` object. Care must be taken to +_must_ be written directly to the `socket` object. Care must be taken to ensure the response is a properly formatted HTTP response message. `err` is an instance of `Error` with two extra columns: @@ -1176,6 +1228,7 @@ server.on('clientError', (err, socket) => { ``` ### Event: `'close'` + <!-- YAML added: v0.1.4 --> @@ -1183,6 +1236,7 @@ added: v0.1.4 Emitted when the server closes. ### Event: `'connect'` + <!-- YAML added: v0.7.0 --> @@ -1205,6 +1259,7 @@ event listener, meaning it will need to be bound in order to handle data sent to the server on that socket. ### Event: `'connection'` + <!-- YAML added: v0.1.0 --> @@ -1229,6 +1284,7 @@ a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. ### Event: `'request'` + <!-- YAML added: v0.1.0 --> @@ -1240,6 +1296,7 @@ Emitted each time there is a request. There may be multiple requests per connection (in the case of HTTP Keep-Alive connections). ### Event: `'upgrade'` + <!-- YAML added: v0.1.94 changes: @@ -1266,6 +1323,7 @@ a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. ### `server.close([callback])` + <!-- YAML added: v0.1.90 --> @@ -1275,6 +1333,7 @@ added: v0.1.90 Stops the server from accepting new connections. See [`net.Server.close()`][]. ### `server.headersTimeout` + <!-- YAML added: - v11.3.0 @@ -1302,6 +1361,7 @@ Starts the HTTP server listening for connections. This method is identical to [`server.listen()`][] from [`net.Server`][]. ### `server.listening` + <!-- YAML added: v5.7.0 --> @@ -1309,6 +1369,7 @@ added: v5.7.0 * {boolean} Indicates whether or not the server is listening for connections. ### `server.maxHeadersCount` + <!-- YAML added: v0.7.0 --> @@ -1318,6 +1379,7 @@ added: v0.7.0 Limits maximum incoming headers count. If set to 0, no limit will be applied. ### `server.requestTimeout` + <!-- YAML added: v14.11.0 --> @@ -1335,6 +1397,7 @@ potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front. ### `server.setTimeout([msecs][, callback])` + <!-- YAML added: v0.9.12 changes: @@ -1359,6 +1422,7 @@ is assigned to the Server's `'timeout'` event, timeouts must be handled explicitly. ### `server.maxRequestsPerSocket` + <!-- YAML added: v16.10.0 --> @@ -1375,6 +1439,7 @@ but will not actually close the connection, subsequent requests sent after the limit is reached will get `503 Service Unavailable` as a response. ### `server.timeout` + <!-- YAML added: v0.9.12 changes: @@ -1394,6 +1459,7 @@ The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. ### `server.keepAliveTimeout` + <!-- YAML added: v8.0.0 --> @@ -1415,6 +1481,7 @@ The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. ## Class: `http.ServerResponse` + <!-- YAML added: v0.1.17 --> @@ -1425,6 +1492,7 @@ This object is created internally by an HTTP server, not by the user. It is passed as the second parameter to the [`'request'`][] event. ### Event: `'close'` + <!-- YAML added: v0.6.7 --> @@ -1433,6 +1501,7 @@ Indicates that the response is completed, or its underlying connection was terminated prematurely (before the response completion). ### Event: `'finish'` + <!-- YAML added: v0.3.6 --> @@ -1443,6 +1512,7 @@ handed off to the operating system for transmission over the network. It does not imply that the client has received anything yet. ### `response.addTrailers(headers)` + <!-- YAML added: v0.3.0 --> @@ -1471,6 +1541,7 @@ Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. ### `response.connection` + <!-- YAML added: v0.3.0 deprecated: v13.0.0 @@ -1483,6 +1554,7 @@ deprecated: v13.0.0 See [`response.socket`][]. ### `response.cork()` + <!-- YAML added: - v13.2.0 @@ -1492,6 +1564,7 @@ added: See [`writable.cork()`][]. ### `response.end([data[, encoding]][, callback])` + <!-- YAML added: v0.1.90 changes: @@ -1516,6 +1589,7 @@ If `callback` is specified, it will be called when the response stream is finished. ### `response.finished` + <!-- YAML added: v0.0.2 deprecated: @@ -1531,6 +1605,7 @@ The `response.finished` property will be `true` if [`response.end()`][] has been called. ### `response.flushHeaders()` + <!-- YAML added: v1.6.0 --> @@ -1538,6 +1613,7 @@ added: v1.6.0 Flushes the response headers. See also: [`request.flushHeaders()`][]. ### `response.getHeader(name)` + <!-- YAML added: v0.4.0 --> @@ -1562,11 +1638,12 @@ const setCookie = response.getHeader('set-cookie'); ``` ### `response.getHeaderNames()` + <!-- YAML added: v7.7.0 --> -* Returns: {string[]} +* Returns: {string\[]} Returns an array containing the unique names of the current outgoing headers. All header names are lowercase. @@ -1580,6 +1657,7 @@ const headerNames = response.getHeaderNames(); ``` ### `response.getHeaders()` + <!-- YAML added: v7.7.0 --> @@ -1595,7 +1673,7 @@ are lowercase. The object returned by the `response.getHeaders()` method _does not_ prototypically inherit from the JavaScript `Object`. This means that typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others -are not defined and *will not work*. +are not defined and _will not work_. ```js response.setHeader('Foo', 'bar'); @@ -1606,6 +1684,7 @@ const headers = response.getHeaders(); ``` ### `response.hasHeader(name)` + <!-- YAML added: v7.7.0 --> @@ -1621,6 +1700,7 @@ const hasContentType = response.hasHeader('content-type'); ``` ### `response.headersSent` + <!-- YAML added: v0.9.3 --> @@ -1630,6 +1710,7 @@ added: v0.9.3 Boolean (read-only). True if headers were sent, false otherwise. ### `response.removeHeader(name)` + <!-- YAML added: v0.4.0 --> @@ -1643,6 +1724,7 @@ response.removeHeader('Content-Encoding'); ``` ### `response.req` + <!-- YAML added: v15.7.0 --> @@ -1652,6 +1734,7 @@ added: v15.7.0 A reference to the original HTTP `request` object. ### `response.sendDate` + <!-- YAML added: v0.7.5 --> @@ -1665,6 +1748,7 @@ This should only be disabled for testing; HTTP requires the Date header in responses. ### `response.setHeader(name, value)` + <!-- YAML added: v0.4.0 --> @@ -1718,6 +1802,7 @@ is desired with potential future retrieval and modification, use [`response.setHeader()`][] instead of [`response.writeHead()`][]. ### `response.setTimeout(msecs[, callback])` + <!-- YAML added: v0.9.12 --> @@ -1736,6 +1821,7 @@ assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. ### `response.socket` + <!-- YAML added: v0.3.0 --> @@ -1761,6 +1847,7 @@ a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. ### `response.statusCode` + <!-- YAML added: v0.4.0 --> @@ -1779,6 +1866,7 @@ After response header was sent to the client, this property indicates the status code which was sent out. ### `response.statusMessage` + <!-- YAML added: v0.11.8 --> @@ -1798,6 +1886,7 @@ After response header was sent to the client, this property indicates the status message which was sent out. ### `response.uncork()` + <!-- YAML added: - v13.2.0 @@ -1807,6 +1896,7 @@ added: See [`writable.uncork()`][]. ### `response.writableEnded` + <!-- YAML added: v12.9.0 --> @@ -1818,6 +1908,7 @@ does not indicate whether the data has been flushed, for this use [`response.writableFinished`][] instead. ### `response.writableFinished` + <!-- YAML added: v12.7.0 --> @@ -1828,6 +1919,7 @@ Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. ### `response.write(chunk[, encoding][, callback])` + <!-- YAML added: v0.1.29 --> @@ -1865,6 +1957,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory. `'drain'` will be emitted when the buffer is free again. ### `response.writeContinue()` + <!-- YAML added: v0.3.0 --> @@ -1874,6 +1967,7 @@ the request body should be sent. See the [`'checkContinue'`][] event on `Server`. ### `response.writeHead(statusCode[, statusMessage][, headers])` + <!-- YAML added: v0.1.30 changes: @@ -1905,7 +1999,7 @@ Optionally one can give a human-readable `statusMessage` as the second argument. `headers` may be an `Array` where the keys and values are in the same list. -It is *not* a list of tuples. So, the even-numbered offsets are key values, +It is _not_ a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. The array is in the same format as `request.rawHeaders`. @@ -1957,6 +2051,7 @@ Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. ### `response.writeProcessing()` + <!-- YAML added: v10.0.0 --> @@ -1965,6 +2060,7 @@ Sends a HTTP/1.1 102 Processing message to the client, indicating that the request body should be sent. ## Class: `http.IncomingMessage` + <!-- YAML added: v0.1.17 changes: @@ -1992,6 +2088,7 @@ parse and emit the incoming HTTP headers and payload, as the underlying socket may be reused multiple times in case of keep-alive. ### Event: `'aborted'` + <!-- YAML added: v0.3.8 deprecated: v17.0.0 @@ -2002,6 +2099,7 @@ deprecated: v17.0.0 Emitted when the request has been aborted. ### Event: `'close'` + <!-- YAML added: v0.4.2 --> @@ -2009,6 +2107,7 @@ added: v0.4.2 Indicates that the underlying connection was closed. ### `message.aborted` + <!-- YAML added: v10.1.0 deprecated: v17.0.0 @@ -2022,6 +2121,7 @@ The `message.aborted` property will be `true` if the request has been aborted. ### `message.complete` + <!-- YAML added: v0.3.0 --> @@ -2050,6 +2150,7 @@ const req = http.request({ ``` ### `message.connection` + <!-- YAML added: v0.1.90 deprecated: v16.0.0 @@ -2060,6 +2161,7 @@ deprecated: v16.0.0 Alias for [`message.socket`][]. ### `message.destroy([error])` + <!-- YAML added: v0.3.0 changes: @@ -2079,6 +2181,7 @@ is provided, an `'error'` event is emitted on the socket and `error` is passed as an argument to any listeners on the event. ### `message.headers` + <!-- YAML added: v0.1.5 changes: @@ -2116,6 +2219,7 @@ header name: * For all other headers, the values are joined together with ', '. ### `message.httpVersion` + <!-- YAML added: v0.1.1 --> @@ -2130,6 +2234,7 @@ Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. ### `message.method` + <!-- YAML added: v0.1.1 --> @@ -2141,15 +2246,16 @@ added: v0.1.1 The request method as a string. Read only. Examples: `'GET'`, `'DELETE'`. ### `message.rawHeaders` + <!-- YAML added: v0.11.6 --> -* {string[]} +* {string\[]} The raw request/response headers list exactly as they were received. -The keys and values are in the same list. It is *not* a +The keys and values are in the same list. It is _not_ a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. @@ -2170,16 +2276,18 @@ console.log(request.rawHeaders); ``` ### `message.rawTrailers` + <!-- YAML added: v0.11.6 --> -* {string[]} +* {string\[]} The raw request/response trailer keys and values exactly as they were received. Only populated at the `'end'` event. ### `message.setTimeout(msecs[, callback])` + <!-- YAML added: v0.5.9 --> @@ -2191,6 +2299,7 @@ added: v0.5.9 Calls `message.socket.setTimeout(msecs, callback)`. ### `message.socket` + <!-- YAML added: v0.3.0 --> @@ -2207,6 +2316,7 @@ a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. ### `message.statusCode` + <!-- YAML added: v0.1.1 --> @@ -2218,6 +2328,7 @@ added: v0.1.1 The 3-digit HTTP response status code. E.G. `404`. ### `message.statusMessage` + <!-- YAML added: v0.11.10 --> @@ -2230,6 +2341,7 @@ The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. ### `message.trailers` + <!-- YAML added: v0.3.0 --> @@ -2239,6 +2351,7 @@ added: v0.3.0 The request/response trailers object. Only populated at the `'end'` event. ### `message.url` + <!-- YAML added: v0.1.90 --> @@ -2284,6 +2397,7 @@ URL { ``` ## Class: `http.OutgoingMessage` + <!-- YAML added: v0.1.17 --> @@ -2295,6 +2409,7 @@ and [`http.ServerResponse`][]. It is an abstract of outgoing message from the perspective of the participants of HTTP transaction. ### Event: `drain` + <!-- YAML added: v0.3.6 --> @@ -2302,6 +2417,7 @@ added: v0.3.6 Emitted when the buffer of the message is free again. ### Event: `finish` + <!-- YAML added: v0.1.17 --> @@ -2309,6 +2425,7 @@ added: v0.1.17 Emitted when the transmission is finished successfully. ### Event: `prefinish` + <!-- YAML added: v0.11.6 --> @@ -2318,6 +2435,7 @@ When the event is emitted, all data has been processed but not necessarily completely flushed. ### `outgoingMessage.addTrailers(headers)` + <!-- YAML added: v0.3.0 --> @@ -2344,6 +2462,7 @@ Attempting to set a header field name or value that contains invalid characters will result in a `TypeError` being thrown. ### `outgoingMessage.connection` + <!-- YAML added: v0.3.0 deprecated: @@ -2354,7 +2473,9 @@ deprecated: > Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead. Aliases of `outgoingMessage.socket` + ### `outgoingMessage.cork()` + <!-- YAML added: v14.0.0 --> @@ -2362,6 +2483,7 @@ added: v14.0.0 See [`writable.cork()`][]. ### `outgoingMessage.destroy([error])` + <!-- YAML added: v0.3.0 --> @@ -2373,6 +2495,7 @@ Destroys the message. Once a socket is associated with the message and is connected, that socket will be destroyed as well. ### `outgoingMessage.end(chunk[, encoding][, callback])` + <!-- YAML added: v0.1.90 changes: @@ -2397,6 +2520,7 @@ If `callback` is provided, it will be called when the message is finished. (equivalent to the callback to event `finish`) ### `outgoingMessage.flushHeaders()` + <!-- YAML added: v1.6.0 --> @@ -2413,6 +2537,7 @@ data is not sent until possibly much later. `outgoingMessage.flushHeaders()` bypasses the optimization and kickstarts the request. ### `outgoingMessage.getHeader(name)` + <!-- YAML added: v0.4.0 --> @@ -2424,16 +2549,18 @@ Gets the value of HTTP header with the given name. If such a name doesn't exist in message, it will be `undefined`. ### `outgoingMessage.getHeaderNames()` + <!-- YAML added: v8.0.0 --> -* Returns {string[]} +* Returns {string\[]} Returns an array of names of headers of the outgoing outgoingMessage. All names are lowercase. ### `outgoingMessage.getHeaders()` + <!-- YAML added: v8.0.0 --> @@ -2460,6 +2587,7 @@ const headers = outgoingMessage.getHeaders(); ``` ### `outgoingMessage.hasHeader(name)` + <!-- YAML added: v8.0.0 --> @@ -2475,6 +2603,7 @@ const hasContentType = outgoingMessage.hasHeader('content-type'); ``` ### `outgoingMessage.headersSent` + <!-- YAML added: v0.9.3 --> @@ -2484,6 +2613,7 @@ added: v0.9.3 Read-only. `true` if the headers were sent, otherwise `false`. ### `outgoingMessage.pipe()` + <!-- YAML added: v9.0.0 --> @@ -2498,6 +2628,7 @@ it inherits from `Stream`. The User should not call this function directly. ### `outgoingMessage.removeHeader()` + <!-- YAML added: v0.4.0 --> @@ -2509,6 +2640,7 @@ outgoingMessage.removeHeader('Content-Encoding'); ``` ### `outgoingMessage.setHeader(name, value)` + <!-- YAML added: v0.4.0 --> @@ -2520,6 +2652,7 @@ added: v0.4.0 Sets a single header value for the header object. ### `outgoingMessage.setTimeout(msesc[, callback])` + <!-- YAML added: v0.9.12 --> @@ -2533,6 +2666,7 @@ Once a socket is associated with the message and is connected, [`socket.setTimeout()`][] will be called with `msecs` as the first parameter. ### `outgoingMessage.socket` + <!-- YAML added: v0.3.0 --> @@ -2545,6 +2679,7 @@ this property. After calling `outgoingMessage.end()`, this property will be nulled. ### `outgoingMessage.uncork()` + <!-- YAML added: v14.0.0 --> @@ -2552,6 +2687,7 @@ added: v14.0.0 See [`writable.uncork()`][] ### `outgoingMessage.writableCorked` + <!-- YAML added: v14.0.0 --> @@ -2562,6 +2698,7 @@ This `outgoingMessage.writableCorked` will return the time how many `outgoingMessage.cork()` have been called. ### `outgoingMessage.writableEnded` + <!-- YAML added: v13.0.0 --> @@ -2573,6 +2710,7 @@ this property does not reflect whether the data has been flush. For that purpose, use `message.writableFinished` instead. ### `outgoingMessage.writableFinished` + <!-- YAML added: v13.0.0 --> @@ -2582,6 +2720,7 @@ added: v13.0.0 Readonly. `true` if all data has been flushed to the underlying system. ### `outgoingMessage.writableHighWaterMark` + <!-- YAML added: v13.0.0 --> @@ -2596,6 +2735,7 @@ underlying socket if socket exists. Else, it would be the default buffered by the socket. ### `outgoingMessage.writableLength` + <!-- YAML added: v13.0.0 --> @@ -2606,6 +2746,7 @@ Readonly, This `outgoingMessage.writableLength` contains the number of bytes (or objects) in the buffer ready to send. ### `outgoingMessage.writableObjectMode` + <!-- YAML added: v13.0.0 --> @@ -2615,6 +2756,7 @@ added: v13.0.0 Readonly, always returns `false`. ### `outgoingMessage.write(chunk[, encoding][, callback])` + <!-- YAML added: v0.1.29 changes: @@ -2658,15 +2800,17 @@ buffer. Returns `false` if all or part of the data was queued in the user memory. Event `drain` will be emitted when the buffer is free again. ## `http.METHODS` + <!-- YAML added: v0.11.8 --> -* {string[]} +* {string\[]} A list of the HTTP methods that are supported by the parser. ## `http.STATUS_CODES` + <!-- YAML added: v0.1.22 --> @@ -2678,6 +2822,7 @@ short description of each. For example, `http.STATUS_CODES[404] === 'Not Found'`. ## `http.createServer([options][, requestListener])` + <!-- YAML added: v0.1.13 changes: @@ -2712,6 +2857,7 @@ changes: [`--max-http-header-size`][] for requests received by this server, i.e. the maximum length of request headers in bytes. **Default:** 16384 (16 KB). + * `requestListener` {Function} * Returns: {http.Server} @@ -2753,7 +2899,9 @@ server.listen(8000); ``` ## `http.get(options[, callback])` + ## `http.get(url[, options][, callback])` + <!-- YAML added: v0.3.6 changes: @@ -2833,6 +2981,7 @@ server.listen(8000); ``` ## `http.globalAgent` + <!-- YAML added: v0.5.9 --> @@ -2843,6 +2992,7 @@ Global instance of `Agent` which is used as the default for all HTTP client requests. ## `http.maxHeaderSize` + <!-- YAML added: - v11.6.0 @@ -2859,7 +3009,9 @@ This can be overridden for servers and client requests by passing the `maxHeaderSize` option. ## `http.request(options[, callback])` + ## `http.request(url[, options][, callback])` + <!-- YAML added: v0.3.6 changes: @@ -2940,7 +3092,7 @@ changes: * `setHost` {boolean}: Specifies whether or not to automatically add the `Host` header. Defaults to `true`. * `socketPath` {string} Unix Domain Socket (cannot be used if one of `host` - or `port` is specified, those specify a TCP Socket). + or `port` is specified, those specify a TCP Socket). * `timeout` {number}: A number specifying the socket timeout in milliseconds. This will set the timeout before the socket is connected. * `signal` {AbortSignal}: An AbortSignal that may be used to abort an ongoing @@ -3145,6 +3297,7 @@ Passing an `AbortSignal` and then calling `abort` on the corresponding request itself. ## `http.validateHeaderName(name)` + <!-- YAML added: v14.3.0 --> @@ -3162,6 +3315,7 @@ or response. The HTTP module will automatically validate such headers. Examples: Example: + ```js const { validateHeaderName } = require('http'); @@ -3175,6 +3329,7 @@ try { ``` ## `http.validateHeaderValue(name, value)` + <!-- YAML added: v14.3.0 --> @@ -3186,6 +3341,7 @@ Performs the low-level validations on the provided `value` that are done when `res.setHeader(name, value)` is called. Passing illegal value as `value` will result in a [`TypeError`][] being thrown. + * Undefined value error is identified by `code: 'ERR_HTTP_INVALID_HEADER_VALUE'`. * Invalid value character error is identified by `code: 'ERR_INVALID_CHAR'`. diff --git a/doc/api/http2.md b/doc/api/http2.md index f620e1b40c3..6932742ca7d 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1,4 +1,5 @@ # HTTP/2 + <!-- YAML added: v8.4.0 changes: @@ -15,6 +16,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/22466 description: HTTP/2 is now Stable. Previously, it had been Experimental. --> + <!--introduced_in=v8.4.0--> > Stability: 2 - Stable @@ -31,7 +33,7 @@ const http2 = require('http2'); ## Core API The Core API provides a low-level interface designed specifically around -support for HTTP/2 protocol features. It is specifically *not* designed for +support for HTTP/2 protocol features. It is specifically _not_ designed for compatibility with the existing [HTTP/1][] module API. However, the [Compatibility API][] is. @@ -107,6 +109,7 @@ req.end(); ``` ### Class: `Http2Session` + <!-- YAML added: v8.4.0 --> @@ -114,7 +117,7 @@ added: v8.4.0 * Extends: {EventEmitter} Instances of the `http2.Http2Session` class represent an active communications -session between an HTTP/2 client and server. Instances of this class are *not* +session between an HTTP/2 client and server. Instances of this class are _not_ intended to be constructed directly by user code. Each `Http2Session` instance will exhibit slightly different behaviors @@ -146,6 +149,7 @@ Once a `Socket` has been bound to an `Http2Session`, user code should rely solely on the API of the `Http2Session`. #### Event: `'close'` + <!-- YAML added: v8.4.0 --> @@ -154,6 +158,7 @@ The `'close'` event is emitted once the `Http2Session` has been destroyed. Its listener does not expect any arguments. #### Event: `'connect'` + <!-- YAML added: v8.4.0 --> @@ -167,6 +172,7 @@ connected to the remote peer and communication may begin. User code will typically not listen for this event directly. #### Event: `'error'` + <!-- YAML added: v8.4.0 --> @@ -177,6 +183,7 @@ The `'error'` event is emitted when an error occurs during the processing of an `Http2Session`. #### Event: `'frameError'` + <!-- YAML added: v8.4.0 --> @@ -197,6 +204,7 @@ event is not associated with a stream, the `Http2Session` will be shut down immediately following the `'frameError'` event. #### Event: `'goaway'` + <!-- YAML added: v8.4.0 --> @@ -213,6 +221,7 @@ The `Http2Session` instance will be shut down automatically when the `'goaway'` event is emitted. #### Event: `'localSettings'` + <!-- YAML added: v8.4.0 --> @@ -234,6 +243,7 @@ session.on('localSettings', (settings) => { ``` #### Event: `'ping'` + <!-- YAML added: v10.12.0 --> @@ -244,6 +254,7 @@ The `'ping'` event is emitted whenever a `PING` frame is received from the connected peer. #### Event: `'remoteSettings'` + <!-- YAML added: v8.4.0 --> @@ -260,6 +271,7 @@ session.on('remoteSettings', (settings) => { ``` #### Event: `'stream'` + <!-- YAML added: v8.4.0 --> @@ -315,6 +327,7 @@ a network error will destroy each individual stream and must be handled on the stream level, as shown above. #### Event: `'timeout'` + <!-- YAML added: v8.4.0 --> @@ -330,6 +343,7 @@ session.on('timeout', () => { /* .. */ }); ``` #### `http2session.alpnProtocol` + <!-- YAML added: v9.4.0 --> @@ -342,6 +356,7 @@ will return the value of the connected `TLSSocket`'s own `alpnProtocol` property. #### `http2session.close([callback])` + <!-- YAML added: v9.4.0 --> @@ -350,13 +365,14 @@ added: v9.4.0 Gracefully closes the `Http2Session`, allowing any existing streams to complete on their own and preventing new `Http2Stream` instances from being -created. Once closed, `http2session.destroy()` *might* be called if there +created. Once closed, `http2session.destroy()` _might_ be called if there are no open `Http2Stream` instances. If specified, the `callback` function is registered as a handler for the `'close'` event. #### `http2session.closed` + <!-- YAML added: v9.4.0 --> @@ -367,6 +383,7 @@ Will be `true` if this `Http2Session` instance has been closed, otherwise `false`. #### `http2session.connecting` + <!-- YAML added: v10.0.0 --> @@ -378,6 +395,7 @@ to `false` before emitting `connect` event and/or calling the `http2.connect` callback. #### `http2session.destroy([error][, code])` + <!-- YAML added: v8.4.0 --> @@ -399,6 +417,7 @@ If there are any remaining open `Http2Streams` associated with the `Http2Session`, those will also be destroyed. #### `http2session.destroyed` + <!-- YAML added: v8.4.0 --> @@ -409,6 +428,7 @@ Will be `true` if this `Http2Session` instance has been destroyed and must no longer be used, otherwise `false`. #### `http2session.encrypted` + <!-- YAML added: v9.4.0 --> @@ -421,6 +441,7 @@ and `false` if the `Http2Session` is connected to any other kind of socket or stream. #### `http2session.goaway([code[, lastStreamID[, opaqueData]]])` + <!-- YAML added: v9.4.0 --> @@ -430,10 +451,11 @@ added: v9.4.0 * `opaqueData` {Buffer|TypedArray|DataView} A `TypedArray` or `DataView` instance containing additional data to be carried within the `GOAWAY` frame. -Transmits a `GOAWAY` frame to the connected peer *without* shutting down the +Transmits a `GOAWAY` frame to the connected peer _without_ shutting down the `Http2Session`. #### `http2session.localSettings` + <!-- YAML added: v8.4.0 --> @@ -441,14 +463,15 @@ added: v8.4.0 * {HTTP/2 Settings Object} A prototype-less object describing the current local settings of this -`Http2Session`. The local settings are local to *this* `Http2Session` instance. +`Http2Session`. The local settings are local to _this_ `Http2Session` instance. #### `http2session.originSet` + <!-- YAML added: v9.4.0 --> -* {string[]|undefined} +* {string\[]|undefined} If the `Http2Session` is connected to a `TLSSocket`, the `originSet` property will return an `Array` of origins for which the `Http2Session` may be @@ -457,6 +480,7 @@ considered authoritative. The `originSet` property is only available when using a secure TLS connection. #### `http2session.pendingSettingsAck` + <!-- YAML added: v8.4.0 --> @@ -469,6 +493,7 @@ a sent `SETTINGS` frame. Will be `true` after calling the frames have been acknowledged. #### `http2session.ping([payload, ]callback)` + <!-- YAML added: v8.9.3 --> @@ -507,6 +532,7 @@ If the `payload` argument is not specified, the default payload will be the 64-bit timestamp (little endian) marking the start of the `PING` duration. #### `http2session.ref()` + <!-- YAML added: v9.4.0 --> @@ -515,6 +541,7 @@ Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session` instance's underlying [`net.Socket`][]. #### `http2session.remoteSettings` + <!-- YAML added: v8.4.0 --> @@ -522,9 +549,10 @@ added: v8.4.0 * {HTTP/2 Settings Object} A prototype-less object describing the current remote settings of this -`Http2Session`. The remote settings are set by the *connected* HTTP/2 peer. +`Http2Session`. The remote settings are set by the _connected_ HTTP/2 peer. #### `http2session.setLocalWindowSize(windowSize)` + <!-- YAML added: - v15.3.0 @@ -550,6 +578,7 @@ server.on('connect', (session) => { ``` #### `http2session.setTimeout(msecs, callback)` + <!-- YAML added: v8.4.0 --> @@ -562,6 +591,7 @@ the `Http2Session` after `msecs` milliseconds. The given `callback` is registered as a listener on the `'timeout'` event. #### `http2session.socket` + <!-- YAML added: v8.4.0 --> @@ -580,6 +610,7 @@ an error with code `ERR_HTTP2_NO_SOCKET_MANIPULATION`. See All other interactions will be routed directly to the socket. #### `http2session.state` + <!-- YAML added: v8.4.0 --> @@ -610,6 +641,7 @@ Provides miscellaneous information about the current state of the An object describing the current status of this `Http2Session`. #### `http2session.settings([settings][, callback])` + <!-- YAML added: v8.4.0 --> @@ -633,6 +665,7 @@ is received and the `'localSettings'` event is emitted. It is possible to send multiple `SETTINGS` frames while acknowledgment is still pending. #### `http2session.type` + <!-- YAML added: v8.4.0 --> @@ -645,6 +678,7 @@ server, and `http2.constants.NGHTTP2_SESSION_CLIENT` if the instance is a client. #### `http2session.unref()` + <!-- YAML added: v9.4.0 --> @@ -653,6 +687,7 @@ Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session` instance's underlying [`net.Socket`][]. ### Class: `ServerHttp2Session` + <!-- YAML added: v8.4.0 --> @@ -660,6 +695,7 @@ added: v8.4.0 * Extends: {Http2Session} #### `serverhttp2session.altsvc(alt, originOrStream)` + <!-- YAML added: v9.4.0 --> @@ -691,7 +727,7 @@ server.on('stream', (stream) => { Sending an `ALTSVC` frame with a specific stream ID indicates that the alternate service is associated with the origin of the given `Http2Stream`. -The `alt` and origin string *must* contain only ASCII bytes and are +The `alt` and origin string _must_ contain only ASCII bytes and are strictly interpreted as a sequence of ASCII bytes. The special value `'clear'` may be passed to clear any previously set alternative service for a given domain. @@ -704,7 +740,7 @@ cannot be parsed as a URL or if a valid origin cannot be derived. A `URL` object, or any object with an `origin` property, may be passed as `originOrStream`, in which case the value of the `origin` property will be -used. The value of the `origin` property *must* be a properly serialized +used. The value of the `origin` property _must_ be a properly serialized ASCII origin. #### Specifying alternative services @@ -715,7 +751,7 @@ associated with a specific host and port. For example, the value `'h2="example.org:81"'` indicates that the HTTP/2 protocol is available on the host `'example.org'` on TCP/IP port 81. The -host and port *must* be contained within the quote (`"`) characters. +host and port _must_ be contained within the quote (`"`) characters. Multiple alternatives may be specified, for instance: `'h2="example.org:81", h2=":82"'`. @@ -727,6 +763,7 @@ The syntax of these values is not validated by the Node.js implementation and are passed through as provided by the user or received from the peer. #### `serverhttp2session.origin(...origins)` + <!-- YAML added: v10.12.0 --> @@ -759,7 +796,7 @@ cannot be parsed as a URL or if a valid origin cannot be derived. A `URL` object, or any object with an `origin` property, may be passed as an `origin`, in which case the value of the `origin` property will be -used. The value of the `origin` property *must* be a properly serialized +used. The value of the `origin` property _must_ be a properly serialized ASCII origin. Alternatively, the `origins` option may be used when creating a new HTTP/2 @@ -777,6 +814,7 @@ server.on('stream', (stream) => { ``` ### Class: `ClientHttp2Session` + <!-- YAML added: v8.4.0 --> @@ -784,6 +822,7 @@ added: v8.4.0 * Extends: {Http2Session} #### Event: `'altsvc'` + <!-- YAML added: v9.4.0 --> @@ -809,11 +848,12 @@ client.on('altsvc', (alt, origin, streamId) => { ``` #### Event: `'origin'` + <!-- YAML added: v10.12.0 --> -* `origins` {string[]} +* `origins` {string\[]} The `'origin'` event is emitted whenever an `ORIGIN` frame is received by the client. The event is emitted with an array of `origin` strings. The @@ -833,13 +873,15 @@ client.on('origin', (origins) => { The `'origin'` event is only emitted when using a secure TLS connection. #### `clienthttp2session.request(headers[, options])` + <!-- YAML added: v8.4.0 --> * `headers` {HTTP/2 Headers Object} + * `options` {Object} - * `endStream` {boolean} `true` if the `Http2Stream` *writable* side should + * `endStream` {boolean} `true` if the `Http2Stream` _writable_ side should be closed initially, such as when sending a `GET` request that should not expect a payload body. * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, @@ -902,6 +944,7 @@ they respectively default to: * `:path` = `/` ### Class: `Http2Stream` + <!-- YAML added: v8.4.0 --> @@ -987,6 +1030,7 @@ property will be `true` and the `http2stream.rstCode` property will specify the destroyed. #### Event: `'aborted'` + <!-- YAML added: v8.4.0 --> @@ -999,6 +1043,7 @@ The `'aborted'` event will only be emitted if the `Http2Stream` writable side has not been ended. #### Event: `'close'` + <!-- YAML added: v8.4.0 --> @@ -1011,6 +1056,7 @@ the `http2stream.rstCode` property. If the code is any value other than `NGHTTP2_NO_ERROR` (`0`), an `'error'` event will have also been emitted. #### Event: `'error'` + <!-- YAML added: v8.4.0 --> @@ -1021,6 +1067,7 @@ The `'error'` event is emitted when an error occurs during the processing of an `Http2Stream`. #### Event: `'frameError'` + <!-- YAML added: v8.4.0 --> @@ -1037,6 +1084,7 @@ error code. The `Http2Stream` instance will be destroyed immediately after the `'frameError'` event is emitted. #### Event: `'ready'` + <!-- YAML added: v8.4.0 --> @@ -1046,6 +1094,7 @@ been assigned an `id`, and can be used. The listener does not expect any arguments. #### Event: `'timeout'` + <!-- YAML added: v8.4.0 --> @@ -1056,6 +1105,7 @@ The `'timeout'` event is emitted after no activity is received for this Its listener does not expect any arguments. #### Event: `'trailers'` + <!-- YAML added: v8.4.0 --> @@ -1078,6 +1128,7 @@ stream.on('trailers', (headers, flags) => { ``` #### Event: `'wantTrailers'` + <!-- YAML added: v10.0.0 --> @@ -1088,6 +1139,7 @@ trailing headers. When initiating a request or response, the `waitForTrailers` option must be set for this event to be emitted. #### `http2stream.aborted` + <!-- YAML added: v8.4.0 --> @@ -1098,6 +1150,7 @@ Set to `true` if the `Http2Stream` instance was aborted abnormally. When set, the `'aborted'` event will have been emitted. #### `http2stream.bufferSize` + <!-- YAML added: - v11.2.0 @@ -1110,6 +1163,7 @@ This property shows the number of characters currently buffered to be written. See [`net.Socket.bufferSize`][] for details. #### `http2stream.close(code[, callback])` + <!-- YAML added: v8.4.0 --> @@ -1123,6 +1177,7 @@ Closes the `Http2Stream` instance by sending an `RST_STREAM` frame to the connected HTTP/2 peer. #### `http2stream.closed` + <!-- YAML added: v9.4.0 --> @@ -1132,6 +1187,7 @@ added: v9.4.0 Set to `true` if the `Http2Stream` instance has been closed. #### `http2stream.destroyed` + <!-- YAML added: v8.4.0 --> @@ -1142,6 +1198,7 @@ Set to `true` if the `Http2Stream` instance has been destroyed and is no longer usable. #### `http2stream.endAfterHeaders` + <!-- YAML added: v10.11.0 --> @@ -1153,6 +1210,7 @@ HEADERS frame received, indicating that no additional data should be received and the readable side of the `Http2Stream` will be closed. #### `http2stream.id` + <!-- YAML added: v8.4.0 --> @@ -1163,6 +1221,7 @@ The numeric stream identifier of this `Http2Stream` instance. Set to `undefined` if the stream identifier has not yet been assigned. #### `http2stream.pending` + <!-- YAML added: v9.4.0 --> @@ -1173,6 +1232,7 @@ Set to `true` if the `Http2Stream` instance has not yet been assigned a numeric stream identifier. #### `http2stream.priority(options)` + <!-- YAML added: v8.4.0 --> @@ -1193,6 +1253,7 @@ added: v8.4.0 Updates the priority for this `Http2Stream` instance. #### `http2stream.rstCode` + <!-- YAML added: v8.4.0 --> @@ -1205,6 +1266,7 @@ calling `http2stream.close()`, or `http2stream.destroy()`. Will be `undefined` if the `Http2Stream` has not been closed. #### `http2stream.sentHeaders` + <!-- YAML added: v9.5.0 --> @@ -1214,16 +1276,18 @@ added: v9.5.0 An object containing the outbound headers sent for this `Http2Stream`. #### `http2stream.sentInfoHeaders` + <!-- YAML added: v9.5.0 --> -* {HTTP/2 Headers Object[]} +* {HTTP/2 Headers Object\[]} An array of objects containing the outbound informational (additional) headers sent for this `Http2Stream`. #### `http2stream.sentTrailers` + <!-- YAML added: v9.5.0 --> @@ -1233,6 +1297,7 @@ added: v9.5.0 An object containing the outbound trailers sent for this `HttpStream`. #### `http2stream.session` + <!-- YAML added: v8.4.0 --> @@ -1243,6 +1308,7 @@ A reference to the `Http2Session` instance that owns this `Http2Stream`. The value will be `undefined` after the `Http2Stream` instance is destroyed. #### `http2stream.setTimeout(msecs, callback)` + <!-- YAML added: v8.4.0 --> @@ -1261,9 +1327,11 @@ req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL)); ``` #### `http2stream.state` + <!-- YAML added: v8.4.0 --> + Provides miscellaneous information about the current state of the `Http2Stream`. @@ -1283,6 +1351,7 @@ Provides miscellaneous information about the current state of the A current state of this `Http2Stream`. #### `http2stream.sendTrailers(headers)` + <!-- YAML added: v10.0.0 --> @@ -1312,6 +1381,7 @@ The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header fields (e.g. `':method'`, `':path'`, etc). ### Class: `ClientHttp2Stream` + <!-- YAML added: v8.4.0 --> @@ -1324,6 +1394,7 @@ provide events such as `'response'` and `'push'` that are only relevant on the client. #### Event: `'continue'` + <!-- YAML added: v8.5.0 --> @@ -1333,6 +1404,7 @@ the request contained `Expect: 100-continue`. This is an instruction that the client should send the request body. #### Event: `'headers'` + <!-- YAML added: v8.4.0 --> @@ -1349,6 +1421,7 @@ stream.on('headers', (headers, flags) => { ``` #### Event: `'push'` + <!-- YAML added: v8.4.0 --> @@ -1364,6 +1437,7 @@ stream.on('push', (headers, flags) => { ``` #### Event: `'response'` + <!-- YAML added: v8.4.0 --> @@ -1383,6 +1457,7 @@ req.on('response', (headers, flags) => { ``` ### Class: `ServerHttp2Stream` + <!-- YAML added: v8.4.0 --> @@ -1395,6 +1470,7 @@ provide additional methods such as `http2stream.pushStream()` and `http2stream.respond()` that are only relevant on the server. #### `http2stream.additionalHeaders(headers)` + <!-- YAML added: v8.4.0 --> @@ -1404,6 +1480,7 @@ added: v8.4.0 Sends an additional informational `HEADERS` frame to the connected HTTP/2 peer. #### `http2stream.headersSent` + <!-- YAML added: v8.4.0 --> @@ -1413,6 +1490,7 @@ added: v8.4.0 True if headers were sent, false otherwise (read-only). #### `http2stream.pushAllowed` + <!-- YAML added: v8.4.0 --> @@ -1425,6 +1503,7 @@ accepts push streams, `false` otherwise. Settings are the same for every `Http2Stream` in the same `Http2Session`. #### `http2stream.pushStream(headers[, options], callback)` + <!-- YAML added: v8.4.0 --> @@ -1470,6 +1549,7 @@ Calling `http2stream.pushStream()` from within a pushed stream is not permitted and will throw an error. #### `http2stream.respond([headers[, options]])` + <!-- YAML added: v8.4.0 changes: @@ -1519,6 +1599,7 @@ server.on('stream', (stream) => { ``` #### `http2stream.respondWithFD(fd[, headers[, options]])` + <!-- YAML added: v8.4.0 changes: @@ -1594,7 +1675,7 @@ sent. The `http2stream.sendTrailers()` method can then be used to sent trailing header fields to the peer. When `options.waitForTrailers` is set, the `Http2Stream` will not automatically -close when the final `DATA` frame is transmitted. User code *must* call either +close when the final `DATA` frame is transmitted. User code _must_ call either `http2stream.sendTrailers()` or `http2stream.close()` to close the `Http2Stream`. @@ -1622,6 +1703,7 @@ server.on('stream', (stream) => { ``` #### `http2stream.respondWithFile(path[, headers[, options]])` + <!-- YAML added: v8.4.0 changes: @@ -1748,6 +1830,7 @@ server.on('stream', (stream) => { ``` ### Class: `Http2Server` + <!-- YAML added: v8.4.0 --> @@ -1759,6 +1842,7 @@ function. The `Http2Server` class is not exported directly by the `http2` module. #### Event: `'checkContinue'` + <!-- YAML added: v8.5.0 --> @@ -1781,6 +1865,7 @@ When this event is emitted and handled, the [`'request'`][] event will not be emitted. #### Event: `'connection'` + <!-- YAML added: v8.4.0 --> @@ -1795,6 +1880,7 @@ This event can also be explicitly emitted by users to inject connections into the HTTP server. In that case, any [`Duplex`][] stream can be passed. #### Event: `'request'` + <!-- YAML added: v8.4.0 --> @@ -1806,6 +1892,7 @@ Emitted each time there is a request. There may be multiple requests per session. See the [Compatibility API][]. #### Event: `'session'` + <!-- YAML added: v8.4.0 --> @@ -1814,6 +1901,7 @@ The `'session'` event is emitted when a new `Http2Session` is created by the `Http2Server`. #### Event: `'sessionError'` + <!-- YAML added: v8.4.0 --> @@ -1822,6 +1910,7 @@ The `'sessionError'` event is emitted when an `'error'` event is emitted by an `Http2Session` object associated with the `Http2Server`. #### Event: `'stream'` + <!-- YAML added: v8.4.0 --> @@ -1861,6 +1950,7 @@ server.on('stream', (stream, headers, flags) => { ``` #### Event: `'timeout'` + <!-- YAML added: v8.4.0 changes: @@ -1874,6 +1964,7 @@ a given number of milliseconds set using `http2server.setTimeout()`. **Default:** 0 (no timeout) #### `server.close([callback])` + <!-- YAML added: v8.4.0 --> @@ -1890,6 +1981,7 @@ closed, although the server has already stopped allowing new sessions. See [`net.Server.close()`][] for more details. #### `server.setTimeout([msecs][, callback])` + <!-- YAML added: v8.4.0 changes: @@ -1912,6 +2004,7 @@ In case if `callback` is not a function, a new `ERR_INVALID_CALLBACK` error will be thrown. #### `server.timeout` + <!-- YAML added: v8.4.0 changes: @@ -1931,6 +2024,7 @@ The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. #### `server.updateSettings([settings])` + <!-- YAML added: - v15.1.0 @@ -1946,6 +2040,7 @@ Throws `ERR_HTTP2_INVALID_SETTING_VALUE` for invalid `settings` values. Throws `ERR_INVALID_ARG_TYPE` for invalid `settings` argument. ### Class: `Http2SecureServer` + <!-- YAML added: v8.4.0 --> @@ -1957,6 +2052,7 @@ Instances of `Http2SecureServer` are created using the exported directly by the `http2` module. #### Event: `'checkContinue'` + <!-- YAML added: v8.5.0 --> @@ -1979,6 +2075,7 @@ When this event is emitted and handled, the [`'request'`][] event will not be emitted. #### Event: `'connection'` + <!-- YAML added: v8.4.0 --> @@ -1993,6 +2090,7 @@ This event can also be explicitly emitted by users to inject connections into the HTTP server. In that case, any [`Duplex`][] stream can be passed. #### Event: `'request'` + <!-- YAML added: v8.4.0 --> @@ -2004,6 +2102,7 @@ Emitted each time there is a request. There may be multiple requests per session. See the [Compatibility API][]. #### Event: `'session'` + <!-- YAML added: v8.4.0 --> @@ -2012,6 +2111,7 @@ The `'session'` event is emitted when a new `Http2Session` is created by the `Http2SecureServer`. #### Event: `'sessionError'` + <!-- YAML added: v8.4.0 --> @@ -2020,6 +2120,7 @@ The `'sessionError'` event is emitted when an `'error'` event is emitted by an `Http2Session` object associated with the `Http2SecureServer`. #### Event: `'stream'` + <!-- YAML added: v8.4.0 --> @@ -2061,6 +2162,7 @@ server.on('stream', (stream, headers, flags) => { ``` #### Event: `'timeout'` + <!-- YAML added: v8.4.0 --> @@ -2070,6 +2172,7 @@ a given number of milliseconds set using `http2secureServer.setTimeout()`. **Default:** 2 minutes. #### Event: `'unknownProtocol'` + <!-- YAML added: v8.4.0 --> @@ -2082,6 +2185,7 @@ the connection is terminated. A timeout may be specified using the See the [Compatibility API][]. #### `server.close([callback])` + <!-- YAML added: v8.4.0 --> @@ -2098,6 +2202,7 @@ closed, although the server has already stopped allowing new sessions. See [`tls.Server.close()`][] for more details. #### `server.setTimeout([msecs][, callback])` + <!-- YAML added: v8.4.0 --> @@ -2116,6 +2221,7 @@ In case if `callback` is not a function, a new `ERR_INVALID_CALLBACK` error will be thrown. #### `server.timeout` + <!-- YAML added: v8.4.0 changes: @@ -2135,6 +2241,7 @@ The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. #### `server.updateSettings([settings])` + <!-- YAML added: - v15.1.0 @@ -2150,6 +2257,7 @@ Throws `ERR_HTTP2_INVALID_SETTING_VALUE` for invalid `settings` values. Throws `ERR_INVALID_ARG_TYPE` for invalid `settings` argument. ### `http2.createServer(options[, onRequestHandler])` + <!-- YAML added: v8.4.0 changes: @@ -2303,6 +2411,7 @@ server.listen(80); ``` ### `http2.createSecureServer(options[, onRequestHandler])` + <!-- YAML added: v8.4.0 changes: @@ -2407,7 +2516,7 @@ changes: remote peer upon connection. * ...: Any [`tls.createServer()`][] options can be provided. For servers, the identity options (`pfx` or `key`/`cert`) are usually required. - * `origins` {string[]} An array of origin strings to send within an `ORIGIN` + * `origins` {string\[]} An array of origin strings to send within an `ORIGIN` frame immediately following creation of a new server `Http2Session`. * `unknownProtocolTimeout` {number} Specifies a timeout in milliseconds that a server should wait when an [`'unknownProtocol'`][] event is emitted. If @@ -2443,6 +2552,7 @@ server.listen(80); ``` ### `http2.connect(authority[, options][, listener])` + <!-- YAML added: v8.4.0 changes: @@ -2556,6 +2666,7 @@ client.close(); ``` ### `http2.constants` + <!-- YAML added: v8.4.0 --> @@ -2563,7 +2674,7 @@ added: v8.4.0 #### Error codes for `RST_STREAM` and `GOAWAY` | Value | Name | Constant | -|--------|---------------------|-----------------------------------------------| +| ------ | ------------------- | --------------------------------------------- | | `0x00` | No Error | `http2.constants.NGHTTP2_NO_ERROR` | | `0x01` | Protocol Error | `http2.constants.NGHTTP2_PROTOCOL_ERROR` | | `0x02` | Internal Error | `http2.constants.NGHTTP2_INTERNAL_ERROR` | @@ -2583,6 +2694,7 @@ The `'timeout'` event is emitted when there is no activity on the Server for a given number of milliseconds set using `http2server.setTimeout()`. ### `http2.getDefaultSettings()` + <!-- YAML added: v8.4.0 --> @@ -2594,6 +2706,7 @@ instance. This method returns a new object instance every time it is called so instances returned may be safely modified for use. ### `http2.getPackedSettings([settings])` + <!-- YAML added: v8.4.0 --> @@ -2615,6 +2728,7 @@ console.log(packed.toString('base64')); ``` ### `http2.getUnpackedSettings(buf)` + <!-- YAML added: v8.4.0 --> @@ -2626,6 +2740,7 @@ Returns a [HTTP/2 Settings Object][] containing the deserialized settings from the given `Buffer` as generated by `http2.getPackedSettings()`. ### `http2.sensitiveHeaders` + <!-- YAML added: - v15.0.0 @@ -2713,6 +2828,7 @@ This property is also set for received headers. It will contain the names of all headers marked as sensitive, including ones marked that way automatically. ### Settings object + <!-- YAML added: v8.4.0 changes: @@ -2723,6 +2839,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/16676 description: The `maxHeaderListSize` setting is now strictly enforced. --> + The `http2.getDefaultSettings()`, `http2.getPackedSettings()`, `http2.createServer()`, `http2.createSecureServer()`, `http2session.settings()`, `http2session.localSettings`, and @@ -2736,7 +2853,7 @@ properties. is 2<sup>32</sup>-1. **Default:** `4096`. * `enablePush` {boolean} Specifies `true` if HTTP/2 Push Streams are to be permitted on the `Http2Session` instances. **Default:** `true`. -* `initialWindowSize` {number} Specifies the *sender's* initial window size in +* `initialWindowSize` {number} Specifies the _sender's_ initial window size in bytes for stream-level flow control. The minimum allowed value is 0. The maximum allowed value is 2<sup>32</sup>-1. **Default:** `65535`. * `maxFrameSize` {number} Specifies the size in bytes of the largest frame @@ -2787,20 +2904,20 @@ on where and when the error occurs. The HTTP/2 implementation applies stricter handling of invalid characters in HTTP header names and values than the HTTP/1 implementation. -Header field names are *case-insensitive* and are transmitted over the wire +Header field names are _case-insensitive_ and are transmitted over the wire strictly as lower-case strings. The API provided by Node.js allows header names to be set as mixed-case strings (e.g. `Content-Type`) but will convert those to lower-case (e.g. `content-type`) upon transmission. -Header field-names *must only* contain one or more of the following ASCII +Header field-names _must only_ contain one or more of the following ASCII characters: `a`-`z`, `A`-`Z`, `0`-`9`, `!`, `#`, `$`, `%`, `&`, `'`, `*`, `+`, `-`, `.`, `^`, `_`, `` ` `` (backtick), `|`, and `~`. Using invalid characters within an HTTP header field name will cause the stream to be closed with a protocol error being reported. -Header field values are handled with more leniency but *should* not contain -new-line or carriage return characters and *should* be limited to US-ASCII +Header field values are handled with more leniency but _should_ not contain +new-line or carriage return characters and _should_ be limited to US-ASCII characters, per the requirements of the HTTP specification. ### Push streams on the client @@ -2999,6 +3116,7 @@ The `'request'` event works identically on both [HTTPS][] and HTTP/2. ### Class: `http2.Http2ServerRequest` + <!-- YAML added: v8.4.0 --> @@ -3011,6 +3129,7 @@ A `Http2ServerRequest` object is created by [`http2.Server`][] or data. #### Event: `'aborted'` + <!-- YAML added: v8.4.0 --> @@ -3022,6 +3141,7 @@ The `'aborted'` event will only be emitted if the `Http2ServerRequest` writable side has not been ended. #### Event: `'close'` + <!-- YAML added: v8.4.0 --> @@ -3030,6 +3150,7 @@ Indicates that the underlying [`Http2Stream`][] was closed. Just like `'end'`, this event occurs only once per response. #### `request.aborted` + <!-- YAML added: v10.1.0 --> @@ -3040,6 +3161,7 @@ The `request.aborted` property will be `true` if the request has been aborted. #### `request.authority` + <!-- YAML added: v8.4.0 --> @@ -3052,6 +3174,7 @@ to set either `:authority` or `host`, this value is derived from `req.headers['host']`. #### `request.complete` + <!-- YAML added: v12.10.0 --> @@ -3062,6 +3185,7 @@ The `request.complete` property will be `true` if the request has been completed, aborted, or destroyed. #### `request.connection` + <!-- YAML added: v8.4.0 deprecated: v13.0.0 @@ -3074,6 +3198,7 @@ deprecated: v13.0.0 See [`request.socket`][]. #### `request.destroy([error])` + <!-- YAML added: v8.4.0 --> @@ -3087,6 +3212,7 @@ is emitted and `error` is passed as an argument to any listeners on the event. It does nothing if the stream was already destroyed. #### `request.headers` + <!-- YAML added: v8.4.0 --> @@ -3120,6 +3246,7 @@ assert(request.url); // Fails because the :path header has been removed ``` #### `request.httpVersion` + <!-- YAML added: v8.4.0 --> @@ -3134,6 +3261,7 @@ Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. #### `request.method` + <!-- YAML added: v8.4.0 --> @@ -3143,15 +3271,16 @@ added: v8.4.0 The request method as a string. Read-only. Examples: `'GET'`, `'DELETE'`. #### `request.rawHeaders` + <!-- YAML added: v8.4.0 --> -* {string[]} +* {string\[]} The raw request/response headers list exactly as they were received. -The keys and values are in the same list. It is *not* a +The keys and values are in the same list. It is _not_ a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. @@ -3172,16 +3301,18 @@ console.log(request.rawHeaders); ``` #### `request.rawTrailers` + <!-- YAML added: v8.4.0 --> -* {string[]} +* {string\[]} The raw request/response trailer keys and values exactly as they were received. Only populated at the `'end'` event. #### `request.scheme` + <!-- YAML added: v8.4.0 --> @@ -3192,6 +3323,7 @@ The request scheme pseudo header field indicating the scheme portion of the target URL. #### `request.setTimeout(msecs, callback)` + <!-- YAML added: v8.4.0 --> @@ -3210,6 +3342,7 @@ handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. #### `request.socket` + <!-- YAML added: v8.4.0 --> @@ -3236,6 +3369,7 @@ use [`request.socket.getPeerCertificate()`][] to obtain the client's authentication details. #### `request.stream` + <!-- YAML added: v8.4.0 --> @@ -3245,6 +3379,7 @@ added: v8.4.0 The [`Http2Stream`][] object backing the request. #### `request.trailers` + <!-- YAML added: v8.4.0 --> @@ -3254,6 +3389,7 @@ added: v8.4.0 The request/response trailers object. Only populated at the `'end'` event. #### `request.url` + <!-- YAML added: v8.4.0 --> @@ -3271,6 +3407,7 @@ Accept: text/plain Then `request.url` will be: <!-- eslint-disable semi --> + ```js '/status?name=ryan' ``` @@ -3297,6 +3434,7 @@ URL { ``` ### Class: `http2.Http2ServerResponse` + <!-- YAML added: v8.4.0 --> @@ -3307,6 +3445,7 @@ This object is created internally by an HTTP server, not by the user. It is passed as the second parameter to the [`'request'`][] event. #### Event: `'close'` + <!-- YAML added: v8.4.0 --> @@ -3315,6 +3454,7 @@ Indicates that the underlying [`Http2Stream`][] was terminated before [`response.end()`][] was called or able to flush. #### Event: `'finish'` + <!-- YAML added: v8.4.0 --> @@ -3327,6 +3467,7 @@ does not imply that the client has received anything yet. After this event, no more events will be emitted on the response object. #### `response.addTrailers(headers)` + <!-- YAML added: v8.4.0 --> @@ -3340,6 +3481,7 @@ Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. #### `response.connection` + <!-- YAML added: v8.4.0 deprecated: v13.0.0 @@ -3352,6 +3494,7 @@ deprecated: v13.0.0 See [`response.socket`][]. #### `response.createPushResponse(headers, callback)` + <!-- YAML added: v8.4.0 --> @@ -3371,6 +3514,7 @@ parameter if successful. When `Http2ServerRequest` is closed, the callback is called with an error `ERR_HTTP2_INVALID_STREAM`. #### `response.end([data[, encoding]][, callback])` + <!-- YAML added: v8.4.0 changes: @@ -3395,6 +3539,7 @@ If `callback` is specified, it will be called when the response stream is finished. #### `response.finished` + <!-- YAML added: v8.4.0 deprecated: @@ -3410,6 +3555,7 @@ Boolean value that indicates whether the response has completed. Starts as `false`. After [`response.end()`][] executes, the value will be `true`. #### `response.getHeader(name)` + <!-- YAML added: v8.4.0 --> @@ -3425,11 +3571,12 @@ const contentType = response.getHeader('content-type'); ``` #### `response.getHeaderNames()` + <!-- YAML added: v8.4.0 --> -* Returns: {string[]} +* Returns: {string\[]} Returns an array containing the unique names of the current outgoing headers. All header names are lowercase. @@ -3443,6 +3590,7 @@ const headerNames = response.getHeaderNames(); ``` #### `response.getHeaders()` + <!-- YAML added: v8.4.0 --> @@ -3458,7 +3606,7 @@ are lowercase. The object returned by the `response.getHeaders()` method _does not_ prototypically inherit from the JavaScript `Object`. This means that typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others -are not defined and *will not work*. +are not defined and _will not work_. ```js response.setHeader('Foo', 'bar'); @@ -3469,6 +3617,7 @@ const headers = response.getHeaders(); ``` #### `response.hasHeader(name)` + <!-- YAML added: v8.4.0 --> @@ -3484,6 +3633,7 @@ const hasContentType = response.hasHeader('content-type'); ``` #### `response.headersSent` + <!-- YAML added: v8.4.0 --> @@ -3493,6 +3643,7 @@ added: v8.4.0 True if headers were sent, false otherwise (read-only). #### `response.removeHeader(name)` + <!-- YAML added: v8.4.0 --> @@ -3506,6 +3657,7 @@ response.removeHeader('Content-Encoding'); ``` ### `response.req` + <!-- YAML added: v15.7.0 --> @@ -3515,6 +3667,7 @@ added: v15.7.0 A reference to the original HTTP2 `request` object. #### `response.sendDate` + <!-- YAML added: v8.4.0 --> @@ -3528,12 +3681,13 @@ This should only be disabled for testing; HTTP requires the Date header in responses. #### `response.setHeader(name, value)` + <!-- YAML added: v8.4.0 --> * `name` {string} -* `value` {string|string[]} +* `value` {string|string\[]} Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings @@ -3567,6 +3721,7 @@ const server = http2.createServer((req, res) => { ``` #### `response.setTimeout(msecs[, callback])` + <!-- YAML added: v8.4.0 --> @@ -3585,6 +3740,7 @@ handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. #### `response.socket` + <!-- YAML added: v8.4.0 --> @@ -3618,6 +3774,7 @@ const server = http2.createServer((req, res) => { ``` #### `response.statusCode` + <!-- YAML added: v8.4.0 --> @@ -3636,6 +3793,7 @@ After response header was sent to the client, this property indicates the status code which was sent out. #### `response.statusMessage` + <!-- YAML added: v8.4.0 --> @@ -3646,6 +3804,7 @@ Status message is not supported by HTTP/2 (RFC 7540 8.1.2.4). It returns an empty string. #### `response.stream` + <!-- YAML added: v8.4.0 --> @@ -3655,6 +3814,7 @@ added: v8.4.0 The [`Http2Stream`][] object backing the response. #### `response.writableEnded` + <!-- YAML added: v12.9.0 --> @@ -3666,6 +3826,7 @@ does not indicate whether the data has been flushed, for this use [`writable.writableFinished`][] instead. #### `response.write(chunk[, encoding][, callback])` + <!-- YAML added: v8.4.0 --> @@ -3704,6 +3865,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory. `'drain'` will be emitted when the buffer is free again. #### `response.writeContinue()` + <!-- YAML added: v8.4.0 --> @@ -3713,6 +3875,7 @@ should be sent. See the [`'checkContinue'`][] event on `Http2Server` and `Http2SecureServer`. #### `response.writeHead(statusCode[, statusMessage][, headers])` + <!-- YAML added: v8.4.0 changes: diff --git a/doc/api/https.md b/doc/api/https.md index a2dbeb473a9..a8155384077 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -10,6 +10,7 @@ HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a separate module. ## Class: `https.Agent` + <!-- YAML added: v0.4.5 changes: @@ -26,6 +27,7 @@ An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] for more information. ### `new Agent([options])` + <!-- YAML changes: - version: v12.5.0 @@ -48,6 +50,7 @@ changes: See [`Session Resumption`][] for information about TLS session reuse. #### Event: `'keylog'` + <!-- YAML added: - v13.2.0 @@ -75,6 +78,7 @@ https.globalAgent.on('keylog', (line, tlsSocket) => { ``` ## Class: `https.Server` + <!-- YAML added: v0.3.4 --> @@ -84,6 +88,7 @@ added: v0.3.4 See [`http.Server`][] for more information. ### `server.close([callback])` + <!-- YAML added: v0.1.90 --> @@ -94,6 +99,7 @@ added: v0.1.90 See [`server.close()`][`http.close()`] from the HTTP module for details. ### `server.headersTimeout` + <!-- YAML added: v11.3.0 --> @@ -114,6 +120,7 @@ This method is identical to [`server.listen()`][] from [`net.Server`][]. See [`http.Server#maxHeadersCount`][]. ### `server.requestTimeout` + <!-- YAML added: v14.11.0 --> @@ -123,6 +130,7 @@ added: v14.11.0 See [`http.Server#requestTimeout`][]. ### `server.setTimeout([msecs][, callback])` + <!-- YAML added: v0.11.2 --> @@ -134,6 +142,7 @@ added: v0.11.2 See [`http.Server#setTimeout()`][]. ### `server.timeout` + <!-- YAML added: v0.11.2 changes: @@ -147,6 +156,7 @@ changes: See [`http.Server#timeout`][]. ### `server.keepAliveTimeout` + <!-- YAML added: v8.0.0 --> @@ -156,6 +166,7 @@ added: v8.0.0 See [`http.Server#keepAliveTimeout`][]. ## `https.createServer([options][, requestListener])` + <!-- YAML added: v0.3.4 --> @@ -199,7 +210,9 @@ https.createServer(options, (req, res) => { ``` ## `https.get(options[, callback])` + ## `https.get(url[, options][, callback])` + <!-- YAML added: v0.3.6 changes: @@ -240,6 +253,7 @@ https.get('https://encrypted.google.com/', (res) => { ``` ## `https.globalAgent` + <!-- YAML added: v0.5.9 --> @@ -247,7 +261,9 @@ added: v0.5.9 Global instance of [`https.Agent`][] for all HTTPS client requests. ## `https.request(options[, callback])` + ## `https.request(url[, options][, callback])` + <!-- YAML added: v0.3.6 changes: diff --git a/doc/api/index.md b/doc/api/index.md index 8ea274ec47e..0e7bf073d28 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -11,13 +11,13 @@ <hr class="line"/> * [Assertion testing](assert.md) -* [Async_context](async_context.md) -* [Async hooks](async_hooks.md) +* [Async\_context](async\_context.md) +* [Async hooks](async\_hooks.md) * [Buffer](buffer.md) * [C++ addons](addons.md) * [C/C++ addons with Node-API](n-api.md) * [C++ embedder API](embedding.md) -* [Child processes](child_process.md) +* [Child processes](child\_process.md) * [Cluster](cluster.md) * [Command-line options](cli.md) * [Console](console.md) @@ -25,7 +25,7 @@ * [Crypto](crypto.md) * [Debugger](debugger.md) * [Deprecated APIs](deprecations.md) -* [Diagnostics Channel](diagnostics_channel.md) +* [Diagnostics Channel](diagnostics\_channel.md) * [DNS](dns.md) * [Domain](domain.md) * [Errors](errors.md) @@ -44,7 +44,7 @@ * [Net](net.md) * [OS](os.md) * [Path](path.md) -* [Performance hooks](perf_hooks.md) +* [Performance hooks](perf\_hooks.md) * [Policies](policy.md) * [Process](process.md) * [Punycode](punycode.md) @@ -53,7 +53,7 @@ * [REPL](repl.md) * [Report](report.md) * [Stream](stream.md) -* [String decoder](string_decoder.md) +* [String decoder](string\_decoder.md) * [Timers](timers.md) * [TLS/SSL](tls.md) * [Trace events](tracing.md) @@ -66,7 +66,7 @@ * [WASI](wasi.md) * [Web Crypto API](webcrypto.md) * [Web Streams API](webstreams.md) -* [Worker threads](worker_threads.md) +* [Worker threads](worker\_threads.md) * [Zlib](zlib.md) <hr class="line"/> diff --git a/doc/api/inspector.md b/doc/api/inspector.md index 04b0283d8cc..3d0dbf7799e 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -38,8 +38,8 @@ console. * `wait` {boolean} Block until a client has connected. Optional. **Default:** `false`. -Activate inspector on host and port. Equivalent to `node ---inspect=[[host:]port]`, but can be done programmatically after node has +Activate inspector on host and port. Equivalent to +`node --inspect=[[host:]port]`, but can be done programmatically after node has started. If wait is `true`, will block until a client has connected to the inspect port @@ -70,6 +70,7 @@ undefined ``` ## `inspector.waitForDebugger()` + <!-- YAML added: v12.7.0 --> @@ -87,6 +88,7 @@ The `inspector.Session` is used for dispatching messages to the V8 inspector back-end and receiving message responses and notifications. ### `new inspector.Session()` + <!-- YAML added: v8.0.0 --> @@ -96,6 +98,7 @@ needs to be connected through [`session.connect()`][] before the messages can be dispatched to the inspector backend. ### Event: `'inspectorNotification'` + <!-- YAML added: v8.0.0 --> @@ -113,6 +116,7 @@ session.on('inspectorNotification', (message) => console.log(message.method)); It is also possible to subscribe only to notifications with specific method: ### Event: `<inspector-protocol-method>`; + <!-- YAML added: v8.0.0 --> @@ -134,6 +138,7 @@ session.on('Debugger.paused', ({ params }) => { ``` ### `session.connect()` + <!-- YAML added: v8.0.0 --> @@ -141,6 +146,7 @@ added: v8.0.0 Connects a session to the inspector back-end. ### `session.connectToMainThread()` + <!-- YAML added: v12.11.0 --> @@ -149,6 +155,7 @@ Connects a session to the main thread inspector back-end. An exception will be thrown if this API was not called on a Worker thread. ### `session.disconnect()` + <!-- YAML added: v8.0.0 --> @@ -159,6 +166,7 @@ messages again. Reconnected session will lose all inspector state, such as enabled agents or configured breakpoints. ### `session.post(method[, params][, callback])` + <!-- YAML added: v8.0.0 --> diff --git a/doc/api/intl.md b/doc/api/intl.md index 716047a7c39..cf4a852035d 100644 --- a/doc/api/intl.md +++ b/doc/api/intl.md @@ -45,7 +45,7 @@ An overview of available Node.js and JavaScript features for each `configure` option: | Feature | `none` | `system-icu` | `small-icu` | `full-icu` | -|-----------------------------------------|-----------------------------------|------------------------------|------------------------|------------| +| --------------------------------------- | --------------------------------- | ---------------------------- | ---------------------- | ---------- | | [`String.prototype.normalize()`][] | none (function is no-op) | full | full | full | | `String.prototype.to*Case()` | full | full | full | full | | [`Intl`][] | none (object does not exist) | partial/full (depends on OS) | partial (English-only) | full | @@ -80,7 +80,7 @@ OS. Functionalities that only require the ICU library itself, such as [`String.prototype.normalize()`][] and the [WHATWG URL parser][], are fully supported under `system-icu`. Features that require ICU locale data in -addition, such as [`Intl.DateTimeFormat`][] *may* be fully or partially +addition, such as [`Intl.DateTimeFormat`][] _may_ be fully or partially supported, depending on the completeness of the ICU data installed on the system. diff --git a/doc/api/module.md b/doc/api/module.md index 519240841a6..749bd350ba9 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -15,6 +15,7 @@ Provides general utility methods when interacting with instances of via `import 'module'` or `require('module')`. ### `module.builtinModules` + <!-- YAML added: - v9.3.0 @@ -22,7 +23,7 @@ added: - v6.13.0 --> -* {string[]} +* {string\[]} A list of the names of all modules provided by Node.js. Can be used to verify if a module is maintained by a third party or not. @@ -43,6 +44,7 @@ const builtin = require('module').builtinModules; ``` ### `module.createRequire(filename)` + <!-- YAML added: v12.2.0 --> @@ -61,6 +63,7 @@ const siblingModule = require('./sibling-module'); ``` ### `module.syncBuiltinESMExports()` + <!-- YAML added: v12.12.0 --> @@ -99,6 +102,7 @@ import('fs').then((esmFS) => { ``` ## Source map v3 support + <!-- YAML added: - v13.7.0 @@ -128,7 +132,9 @@ const { findSourceMap, SourceMap } = require('module'); ``` <!-- Anchors to make sure old links find a target --> + <a id="module_module_findsourcemap_path_error"></a> + ### `module.findSourceMap(path)` <!-- YAML @@ -144,6 +150,7 @@ added: should be fetched. ### Class: `module.SourceMap` + <!-- YAML added: - v13.7.0 @@ -160,9 +167,9 @@ Creates a new `sourceMap` instance. * `file`: {string} * `version`: {number} -* `sources`: {string[]} -* `sourcesContent`: {string[]} -* `names`: {string[]} +* `sources`: {string\[]} +* `sourcesContent`: {string\[]} +* `names`: {string\[]} * `mappings`: {string} * `sourceRoot`: {string} diff --git a/doc/api/modules.md b/doc/api/modules.md index 900c2c158b5..44e79592544 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -99,7 +99,7 @@ package may itself have dependencies, and in some cases, these may even collide or form cyclic dependencies. Because Node.js looks up the `realpath` of any modules it loads (that is, it -resolves symlinks) and then [looks for their dependencies in `node_modules` folders](#loading-from-node_modules-folders), +resolves symlinks) and then [looks for their dependencies in `node_modules` folders](#loading-from-node\_modules-folders), this situation can be resolved with the following architecture: * `/usr/lib/node/foo/1.2.3/`: Contents of the `foo` package, version 1.2.3. @@ -268,7 +268,7 @@ function. Modules are cached based on their resolved filename. Since modules may resolve to a different filename based on the location of the calling module (loading -from `node_modules` folders), it is not a *guarantee* that `require('foo')` will +from `node_modules` folders), it is not a _guarantee_ that `require('foo')` will always return the exact same object, if it would resolve to different files. Additionally, on case-insensitive file systems or operating systems, different @@ -487,7 +487,7 @@ when people are unaware that `NODE_PATH` must be set. Sometimes a module's dependencies change, causing a different version (or even a different module) to be loaded as the `NODE_PATH` is searched. -Additionally, Node.js will search in the following list of GLOBAL_FOLDERS: +Additionally, Node.js will search in the following list of GLOBAL\_FOLDERS: * 1: `$HOME/.node_modules` * 2: `$HOME/.node_libraries` @@ -528,6 +528,7 @@ By doing this, Node.js achieves a few things: ## The module scope ### `__dirname` + <!-- YAML added: v0.1.27 --> @@ -549,6 +550,7 @@ console.log(path.dirname(__filename)); ``` ### `__filename` + <!-- YAML added: v0.0.1 --> @@ -587,6 +589,7 @@ References to `__filename` within `b.js` will return `a.js` will return `/Users/mjr/app/a.js`. ### `exports` + <!-- YAML added: v0.1.12 --> @@ -600,6 +603,7 @@ See the section about the [exports shortcut][] for details on when to use `exports` and when to use `module.exports`. ### `module` + <!-- YAML added: v0.1.16 --> @@ -613,6 +617,7 @@ A reference to the current module, see the section about the a module exports and makes available through `require()`. ### `require(id)` + <!-- YAML added: v0.1.13 --> @@ -643,6 +648,7 @@ const crypto = require('crypto'); ``` #### `require.cache` + <!-- YAML added: v0.3.0 --> @@ -660,6 +666,7 @@ only `node:`-prefixed require calls are going to receive the native module. Use with care! <!-- eslint-disable node-core/no-duplicate-requires --> + ```js const assert = require('assert'); const realFs = require('fs'); @@ -672,6 +679,7 @@ assert.strictEqual(require('node:fs'), realFs); ``` #### `require.extensions` + <!-- YAML added: v0.3.0 deprecated: v0.10.6 @@ -698,6 +706,7 @@ Avoid using `require.extensions`. Use could cause subtle bugs and resolving the extensions gets slower with each registered extension. #### `require.main` + <!-- YAML added: v0.1.17 --> @@ -719,6 +728,7 @@ node entry.js ``` <!-- eslint-skip --> + ```js Module { id: '.', @@ -735,6 +745,7 @@ Module { ``` #### `require.resolve(request[, options])` + <!-- YAML added: v0.3.0 changes: @@ -745,10 +756,10 @@ changes: * `request` {string} The module path to resolve. * `options` {Object} - * `paths` {string[]} Paths to resolve module location from. If present, these + * `paths` {string\[]} Paths to resolve module location from. If present, these paths are used instead of the default resolution paths, with the exception - of [GLOBAL_FOLDERS][] like `$HOME/.node_modules`, which are always - included. Each of these paths is used as a starting point for + of [GLOBAL\_FOLDERS][GLOBAL_FOLDERS] like `$HOME/.node_modules`, which are + always included. Each of these paths is used as a starting point for the module resolution algorithm, meaning that the `node_modules` hierarchy is checked from this location. * Returns: {string} @@ -759,18 +770,20 @@ but rather than loading the module, just return the resolved filename. If the module can not be found, a `MODULE_NOT_FOUND` error is thrown. ##### `require.resolve.paths(request)` + <!-- YAML added: v8.9.0 --> * `request` {string} The module path whose lookup paths are being retrieved. -* Returns: {string[]|null} +* Returns: {string\[]|null} Returns an array containing the paths searched during resolution of `request` or `null` if the `request` string references a core module, for example `http` or `fs`. ## The `module` object + <!-- YAML added: v0.1.16 --> @@ -787,15 +800,17 @@ also accessible via the `exports` module-global. `module` is not actually a global but rather local to each module. ### `module.children` + <!-- YAML added: v0.1.16 --> -* {module[]} +* {module\[]} The module objects required for the first time by this one. ### `module.exports` + <!-- YAML added: v0.1.16 --> @@ -850,6 +865,7 @@ console.log(x.a); ``` #### `exports` shortcut + <!-- YAML added: v0.1.16 --> @@ -870,6 +886,7 @@ When the `module.exports` property is being completely replaced by a new object, it is common to also reassign `exports`: <!-- eslint-disable func-name-matching --> + ```js module.exports = exports = function Constructor() { // ... etc. @@ -897,6 +914,7 @@ function require(/* ... */) { ``` ### `module.filename` + <!-- YAML added: v0.1.16 --> @@ -906,6 +924,7 @@ added: v0.1.16 The fully resolved filename of the module. ### `module.id` + <!-- YAML added: v0.1.16 --> @@ -916,6 +935,7 @@ The identifier for the module. Typically this is the fully resolved filename. ### `module.isPreloading` + <!-- YAML added: - v15.4.0 @@ -926,6 +946,7 @@ added: phase. ### `module.loaded` + <!-- YAML added: v0.1.16 --> @@ -936,6 +957,7 @@ Whether or not the module is done loading, or is in the process of loading. ### `module.parent` + <!-- YAML added: v0.1.16 deprecated: @@ -953,6 +975,7 @@ entry point of the current process, or `undefined` if the module was loaded by something that is not a CommonJS module (E.G.: REPL or `import`). ### `module.path` + <!-- YAML added: v11.14.0 --> @@ -963,15 +986,17 @@ The directory name of the module. This is usually the same as the [`path.dirname()`][] of the [`module.id`][]. ### `module.paths` + <!-- YAML added: v0.4.0 --> -* {string[]} +* {string\[]} The search paths for the module. ### `module.require(id)` + <!-- YAML added: v0.5.1 --> @@ -984,7 +1009,7 @@ The `module.require()` method provides a way to load a module as if In order to do this, it is necessary to get a reference to the `module` object. Since `require()` returns the `module.exports`, and the `module` is typically -*only* available within a specific module's code, it must be explicitly exported +_only_ available within a specific module's code, it must be explicitly exported in order to be used. ## The `Module` object @@ -993,6 +1018,7 @@ This section was moved to [Modules: `module` core module](module.md#the-module-object). <!-- Anchors to make sure old links find a target --> + * <a id="modules_module_builtinmodules" href="module.html#modulebuiltinmodules">`module.builtinModules`</a> * <a id="modules_module_createrequire_filename" href="module.html#modulecreaterequirefilename">`module.createRequire(filename)`</a> * <a id="modules_module_syncbuiltinesmexports" href="module.html#modulesyncbuiltinesmexports">`module.syncBuiltinESMExports()`</a> @@ -1003,6 +1029,7 @@ This section was moved to [Modules: `module` core module](module.md#source-map-v3-support). <!-- Anchors to make sure old links find a target --> + * <a id="modules_module_findsourcemap_path_error" href="module.html#modulefindsourcemappath">`module.findSourceMap(path)`</a> * <a id="modules_class_module_sourcemap" href="module.html#class-modulesourcemap">Class: `module.SourceMap`</a> * <a id="modules_new_sourcemap_payload" href="module.html#new-sourcemappayload">`new SourceMap(payload)`</a> diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 9c1d9b896e6..7bddf9a7df8 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -91,24 +91,24 @@ versions: * the Node.js C++ APIs available via any of - ```cpp - #include <node.h> - #include <node_buffer.h> - #include <node_version.h> - #include <node_object_wrap.h> - ``` + ```cpp + #include <node.h> + #include <node_buffer.h> + #include <node_version.h> + #include <node_object_wrap.h> + ``` * the libuv APIs which are also included with Node.js and available via - ```cpp - #include <uv.h> - ``` + ```cpp + #include <uv.h> + ``` * the V8 API available via - ```cpp - #include <v8.h> - ``` + ```cpp + #include <v8.h> + ``` Thus, for an addon to remain ABI-compatible across Node.js major versions, it must use Node-API exclusively by restricting itself to using @@ -126,7 +126,7 @@ Unlike modules written in JavaScript, developing and deploying Node.js native addons using Node-API requires an additional set of tools. Besides the basic tools required to develop for Node.js, the native addon developer requires a toolchain that can compile C and C++ code into a binary. In -addition, depending upon how the native addon is deployed, the *user* of +addition, depending upon how the native addon is deployed, the _user_ of the native addon will also need to have a C/C++ toolchain installed. For Linux developers, the necessary C/C++ toolchain packages are readily @@ -155,7 +155,7 @@ and deploying Node.js native addons. ### Build tools -Both the tools listed here require that *users* of the native +Both the tools listed here require that _users_ of the native addon have a C/C++ toolchain installed in order to successfully install the native addon. @@ -482,7 +482,8 @@ the addon. To this end, Node-API provides a way to allocate data such that its life cycle is tied to the life cycle of the Agent. -### napi_set_instance_data +### `napi_set_instance_data` + <!-- YAML added: - v12.8.0 @@ -513,7 +514,8 @@ the currently running Agent which was set by means of a previous call to `napi_set_instance_data()` will be overwritten. If a `finalize_cb` was provided by the previous call, it will not be called. -### napi_get_instance_data +### `napi_get_instance_data` + <!-- YAML added: - v12.8.0 @@ -542,11 +544,13 @@ Node-API exposes the following fundamental datatypes as abstractions that are consumed by the various APIs. These APIs should be treated as opaque, introspectable only with other Node-API calls. -### napi_status +### `napi_status` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Integral status code indicating the success or failure of a Node-API call. Currently, the following status codes are supported. @@ -580,7 +584,8 @@ typedef enum { If additional information is required upon an API returning a failed status, it can be obtained by calling `napi_get_last_error_info`. -### napi_extended_error_info +### `napi_extended_error_info` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -605,7 +610,7 @@ typedef struct { See the [Error handling][] section for additional information. -### napi_env +### `napi_env` `napi_env` is used to represent a context that the underlying Node-API implementation can use to persist VM-specific state. This structure is passed @@ -619,11 +624,12 @@ when an instance of a native addon is unloaded. Notification of this event is delivered through the callbacks given to [`napi_add_env_cleanup_hook`][] and [`napi_set_instance_data`][]. -### napi_value +### `napi_value` This is an opaque pointer that is used to represent a JavaScript value. -### napi_threadsafe_function +### `napi_threadsafe_function` + <!-- YAML added: v10.6.0 napiVersion: 4 @@ -633,7 +639,8 @@ This is an opaque pointer that represents a JavaScript function which can be called asynchronously from multiple threads via `napi_call_threadsafe_function()`. -### napi_threadsafe_function_release_mode +### `napi_threadsafe_function_release_mode` + <!-- YAML added: v10.6.0 napiVersion: 4 @@ -651,7 +658,8 @@ typedef enum { } napi_threadsafe_function_release_mode; ``` -### napi_threadsafe_function_call_mode +### `napi_threadsafe_function_call_mode` + <!-- YAML added: v10.6.0 napiVersion: 4 @@ -669,7 +677,8 @@ typedef enum { ``` ### Node-API memory management types -#### napi_handle_scope + +#### `napi_handle_scope` This is an abstraction used to control and modify the lifetime of objects created within a particular scope. In general, Node-API values are created @@ -688,26 +697,31 @@ longer referenced from the current stack frame. For more details, review the [Object lifetime management][]. -#### napi_escapable_handle_scope +#### `napi_escapable_handle_scope` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Escapable handle scopes are a special type of handle scope to return values created within a particular handle scope to a parent scope. -#### napi_ref +#### `napi_ref` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + This is the abstraction to use to reference a `napi_value`. This allows for users to manage the lifetimes of JavaScript values, including defining their minimum lifetimes explicitly. For more details, review the [Object lifetime management][]. -#### napi_type_tag +#### `napi_type_tag` + <!-- YAML added: - v14.8.0 @@ -731,7 +745,8 @@ typedef struct { } napi_type_tag; ``` -#### napi_async_cleanup_hook_handle +#### `napi_async_cleanup_hook_handle` + <!-- YAML added: - v14.10.0 @@ -744,20 +759,24 @@ events completes. ### Node-API callback types -#### napi_callback_info +#### `napi_callback_info` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Opaque datatype that is passed to a callback function. It can be used for getting additional information about the context in which the callback was invoked. -#### napi_callback +#### `napi_callback` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Function pointer type for user-provided native functions which are to be exposed to JavaScript via Node-API. Callback functions should satisfy the following signature: @@ -769,11 +788,13 @@ typedef napi_value (*napi_callback)(napi_env, napi_callback_info); Unless for reasons discussed in [Object Lifetime Management][], creating a handle and/or callback scope inside a `napi_callback` is not necessary. -#### napi_finalize +#### `napi_finalize` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Function pointer type for add-on provided functions that allow the user to be notified when externally-owned data is ready to be cleaned up because the object with which it was associated with, has been garbage-collected. The user @@ -790,11 +811,13 @@ typedef void (*napi_finalize)(napi_env env, Unless for reasons discussed in [Object Lifetime Management][], creating a handle and/or callback scope inside the function body is not necessary. -#### napi_async_execute_callback +#### `napi_async_execute_callback` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature: @@ -807,11 +830,13 @@ JavaScript or interact with JavaScript objects. Node-API calls should be in the `napi_async_complete_callback` instead. Do not use the `napi_env` parameter as it will likely result in execution of JavaScript. -#### napi_async_complete_callback +#### `napi_async_complete_callback` + <!-- YAML added: v8.0.0 napiVersion: 1 --> + Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature: @@ -824,7 +849,8 @@ typedef void (*napi_async_complete_callback)(napi_env env, Unless for reasons discussed in [Object Lifetime Management][], creating a handle and/or callback scope inside the function body is not necessary. -#### napi_threadsafe_function_call_js +#### `napi_threadsafe_function_call_js` + <!-- YAML added: v10.6.0 napiVersion: 4 @@ -870,7 +896,8 @@ typedef void (*napi_threadsafe_function_call_js)(napi_env env, Unless for reasons discussed in [Object Lifetime Management][], creating a handle and/or callback scope inside the function body is not necessary. -#### napi_async_cleanup_hook +#### `napi_async_cleanup_hook` + <!-- YAML added: - v14.10.0 @@ -955,7 +982,8 @@ Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes. -#### napi_get_last_error_info +#### `napi_get_last_error_info` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1065,7 +1093,8 @@ is `'ERR_ERROR_1'` and a `TypeError` is being created the name will be: TypeError [ERR_ERROR_1] ``` -#### napi_throw +#### `napi_throw` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1082,7 +1111,8 @@ Returns `napi_ok` if the API succeeded. This API throws the JavaScript value provided. -#### napi_throw_error +#### `napi_throw_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1102,7 +1132,8 @@ Returns `napi_ok` if the API succeeded. This API throws a JavaScript `Error` with the text provided. -#### napi_throw_type_error +#### `napi_throw_type_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1122,7 +1153,8 @@ Returns `napi_ok` if the API succeeded. This API throws a JavaScript `TypeError` with the text provided. -#### napi_throw_range_error +#### `napi_throw_range_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1142,7 +1174,8 @@ Returns `napi_ok` if the API succeeded. This API throws a JavaScript `RangeError` with the text provided. -#### napi_is_error +#### `napi_is_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1163,7 +1196,8 @@ Returns `napi_ok` if the API succeeded. This API queries a `napi_value` to check if it represents an error object. -#### napi_create_error +#### `napi_create_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1187,7 +1221,8 @@ Returns `napi_ok` if the API succeeded. This API returns a JavaScript `Error` with the text provided. -#### napi_create_type_error +#### `napi_create_type_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1211,7 +1246,8 @@ Returns `napi_ok` if the API succeeded. This API returns a JavaScript `TypeError` with the text provided. -#### napi_create_range_error +#### `napi_create_range_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1235,7 +1271,8 @@ Returns `napi_ok` if the API succeeded. This API returns a JavaScript `RangeError` with the text provided. -#### napi_get_and_clear_last_exception +#### `napi_get_and_clear_last_exception` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1253,7 +1290,8 @@ Returns `napi_ok` if the API succeeded. This API can be called even if there is a pending JavaScript exception. -#### napi_is_exception_pending +#### `napi_is_exception_pending` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1270,7 +1308,8 @@ Returns `napi_ok` if the API succeeded. This API can be called even if there is a pending JavaScript exception. -#### napi_fatal_exception +#### `napi_fatal_exception` + <!-- YAML added: v9.10.0 napiVersion: 3 @@ -1291,7 +1330,8 @@ callback throws an exception with no way to recover. In the event of an unrecoverable error in a native module, a fatal error can be thrown to immediately terminate the process. -#### napi_fatal_error +#### `napi_fatal_error` + <!-- YAML added: v8.2.0 napiVersion: 1 @@ -1335,6 +1375,7 @@ The sections which follow describe the Node-API functions that can be used to change the handle lifespan from the default. ### Making handle lifespan shorter than that of the native method + It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. For example, consider a native method that has a loop which iterates through the elements in a large array: @@ -1405,7 +1446,8 @@ The methods available to open/close escapable scopes are The request to promote a handle is made through [`napi_escape_handle`][] which can only be called once. -#### napi_open_handle_scope +#### `napi_open_handle_scope` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1423,7 +1465,8 @@ Returns `napi_ok` if the API succeeded. This API opens a new scope. -#### napi_close_handle_scope +#### `napi_close_handle_scope` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1444,7 +1487,8 @@ reverse order from which they were created. This API can be called even if there is a pending JavaScript exception. -#### napi_open_escapable_handle_scope +#### `napi_open_escapable_handle_scope` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1464,7 +1508,8 @@ Returns `napi_ok` if the API succeeded. This API opens a new scope from which one object can be promoted to the outer scope. -#### napi_close_escapable_handle_scope +#### `napi_close_escapable_handle_scope` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1486,7 +1531,8 @@ reverse order from which they were created. This API can be called even if there is a pending JavaScript exception. -#### napi_escape_handle +#### `napi_escape_handle` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1553,7 +1599,8 @@ There can be multiple persistent references created which refer to the same object, each of which will either keep the object live or not based on its individual count. -#### napi_create_reference +#### `napi_create_reference` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1577,7 +1624,8 @@ Returns `napi_ok` if the API succeeded. This API creates a new reference with the specified reference count to the `Object` passed in. -#### napi_delete_reference +#### `napi_delete_reference` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1596,7 +1644,8 @@ This API deletes the reference passed in. This API can be called even if there is a pending JavaScript exception. -#### napi_reference_ref +#### `napi_reference_ref` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1617,7 +1666,8 @@ Returns `napi_ok` if the API succeeded. This API increments the reference count for the reference passed in and returns the resulting reference count. -#### napi_reference_unref +#### `napi_reference_unref` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1638,7 +1688,8 @@ Returns `napi_ok` if the API succeeded. This API decrements the reference count for the reference passed in and returns the resulting reference count. -#### napi_get_reference_value +#### `napi_get_reference_value` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -1674,7 +1725,8 @@ Node-API provides functions for registering and un-registering such callbacks. When those callbacks are run, all resources that are being held by the addon should be freed up. -#### napi_add_env_cleanup_hook +#### `napi_add_env_cleanup_hook` + <!-- YAML added: v10.2.0 napiVersion: 3 @@ -1703,7 +1755,8 @@ is being torn down anyway. For asynchronous cleanup, [`napi_add_async_cleanup_hook`][] is available. -#### napi_remove_env_cleanup_hook +#### `napi_remove_env_cleanup_hook` + <!-- YAML added: v10.2.0 napiVersion: 3 @@ -1722,7 +1775,8 @@ need to be exact matches. The function must have originally been registered with `napi_add_env_cleanup_hook`, otherwise the process will abort. -#### napi_add_async_cleanup_hook +#### `napi_add_async_cleanup_hook` + <!-- YAML added: - v14.8.0 @@ -1764,7 +1818,8 @@ regardless of whether the hook has already been invoked. Typically, that happens when the resource for which this hook was added is being torn down anyway. -#### napi_remove_async_cleanup_hook +#### `napi_remove_async_cleanup_hook` + <!-- YAML added: - v14.8.0 @@ -1791,6 +1846,7 @@ This must be called on any `napi_async_cleanup_hook_handle` value obtained from [`napi_add_async_cleanup_hook`][]. ## Module registration + Node-API modules are registered in a manner similar to other modules except that instead of using the `NODE_MODULE` macro the following is used: @@ -1906,6 +1962,7 @@ For more details on building addon modules in general, refer to the existing API. ## Working with JavaScript values + Node-API exposes a set of APIs to create all types of JavaScript values. Some of these types are documented under [Section 6][] of the [ECMAScript Language Specification][]. @@ -1924,7 +1981,9 @@ However, for better performance, it's better for the caller to make sure that the `napi_value` in question is of the JavaScript type expected by the API. ### Enum types -#### napi_key_collection_mode + +#### `napi_key_collection_mode` + <!-- YAML added: - v13.7.0 @@ -1948,7 +2007,8 @@ Describes the `Keys/Properties` filter enums: object only. `napi_key_include_prototypes` will include all keys of the objects's prototype chain as well. -#### napi_key_filter +#### `napi_key_filter` + <!-- YAML added: - v13.7.0 @@ -1970,7 +2030,8 @@ typedef enum { Property filter bits. They can be or'ed to build a composite filter. -#### napi_key_conversion +#### `napi_key_conversion` + <!-- YAML added: - v13.7.0 @@ -1990,7 +2051,7 @@ typedef enum { strings. `napi_key_keep_numbers` will return numbers for integer indices. -#### napi_valuetype +#### `napi_valuetype` ```c typedef enum { @@ -2016,7 +2077,7 @@ In addition to types in that section, `napi_valuetype` can also represent A JavaScript value of type `napi_external` appears in JavaScript as a plain object such that no properties can be set on it, and no prototype. -#### napi_typedarray_type +#### `napi_typedarray_type` ```c typedef enum { @@ -2039,7 +2100,9 @@ Elements of this enum correspond to [Section 22.2][] of the [ECMAScript Language Specification][]. ### Object creation functions -#### napi_create_array + +#### `napi_create_array` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2058,7 +2121,8 @@ This API returns a Node-API value corresponding to a JavaScript `Array` type. JavaScript arrays are described in [Section 22.1][] of the ECMAScript Language Specification. -#### napi_create_array_with_length +#### `napi_create_array_with_length` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2087,7 +2151,8 @@ directly read and/or written via C, consider using JavaScript arrays are described in [Section 22.1][] of the ECMAScript Language Specification. -#### napi_create_arraybuffer +#### `napi_create_arraybuffer` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2120,7 +2185,8 @@ a typed array or `DataView` object would need to be created. JavaScript `ArrayBuffer` objects are described in [Section 24.1][] of the ECMAScript Language Specification. -#### napi_create_buffer +#### `napi_create_buffer` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2143,7 +2209,8 @@ Returns `napi_ok` if the API succeeded. This API allocates a `node::Buffer` object. While this is still a fully-supported data structure, in most cases using a `TypedArray` will suffice. -#### napi_create_buffer_copy +#### `napi_create_buffer_copy` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2170,7 +2237,8 @@ This API allocates a `node::Buffer` object and initializes it with data copied from the passed-in buffer. While this is still a fully-supported data structure, in most cases using a `TypedArray` will suffice. -#### napi_create_date +#### `napi_create_date` + <!-- YAML added: - v11.11.0 @@ -2198,7 +2266,8 @@ This API allocates a JavaScript `Date` object. JavaScript `Date` objects are described in [Section 20.3][] of the ECMAScript Language Specification. -#### napi_create_external +#### `napi_create_external` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2238,7 +2307,8 @@ The created value is not an object, and therefore does not support additional properties. It is considered a distinct value type: calling `napi_typeof()` with an external value yields `napi_external`. -#### napi_create_external_arraybuffer +#### `napi_create_external_arraybuffer` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2282,7 +2352,8 @@ object just created is ready for garbage collection. It is similar to JavaScript `ArrayBuffer`s are described in [Section 24.1][] of the ECMAScript Language Specification. -#### napi_create_external_buffer +#### `napi_create_external_buffer` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2323,7 +2394,8 @@ object just created is ready for garbage collection. It is similar to For Node.js >=4 `Buffers` are `Uint8Array`s. -#### napi_create_object +#### `napi_create_object` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2344,7 +2416,8 @@ It is the equivalent of doing `new Object()` in JavaScript. The JavaScript `Object` type is described in [Section 6.1.7][] of the ECMAScript Language Specification. -#### napi_create_symbol +#### `napi_create_symbol` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2368,7 +2441,8 @@ This API creates a JavaScript `symbol` value from a UTF8-encoded C string. The JavaScript `symbol` type is described in [Section 19.4][] of the ECMAScript Language Specification. -#### napi_create_typedarray +#### `napi_create_typedarray` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2405,7 +2479,8 @@ is raised. JavaScript `TypedArray` objects are described in [Section 22.2][] of the ECMAScript Language Specification. -#### napi_create_dataview +#### `napi_create_dataview` + <!-- YAML added: v8.3.0 napiVersion: 1 @@ -2440,7 +2515,9 @@ JavaScript `DataView` objects are described in [Section 24.3][] of the ECMAScript Language Specification. ### Functions to convert from C types to Node-API -#### napi_create_int32 + +#### `napi_create_int32` + <!-- YAML added: v8.4.0 napiVersion: 1 @@ -2462,7 +2539,8 @@ This API is used to convert from the C `int32_t` type to the JavaScript The JavaScript `number` type is described in [Section 6.1.6][] of the ECMAScript Language Specification. -#### napi_create_uint32 +#### `napi_create_uint32` + <!-- YAML added: v8.4.0 napiVersion: 1 @@ -2484,7 +2562,8 @@ This API is used to convert from the C `uint32_t` type to the JavaScript The JavaScript `number` type is described in [Section 6.1.6][] of the ECMAScript Language Specification. -#### napi_create_int64 +#### `napi_create_int64` + <!-- YAML added: v8.4.0 napiVersion: 1 @@ -2509,7 +2588,8 @@ cannot be represented with full precision in JavaScript. Integer values outside the range of [`Number.MIN_SAFE_INTEGER`][] `-(2**53 - 1)` - [`Number.MAX_SAFE_INTEGER`][] `(2**53 - 1)` will lose precision. -#### napi_create_double +#### `napi_create_double` + <!-- YAML added: v8.4.0 napiVersion: 1 @@ -2531,7 +2611,8 @@ This API is used to convert from the C `double` type to the JavaScript The JavaScript `number` type is described in [Section 6.1.6][] of the ECMAScript Language Specification. -#### napi_create_bigint_int64 +#### `napi_create_bigint_int64` + <!-- YAML added: v10.7.0 napiVersion: 6 @@ -2551,7 +2632,8 @@ Returns `napi_ok` if the API succeeded. This API converts the C `int64_t` type to the JavaScript `BigInt` type. -#### napi_create_bigint_uint64 +#### `napi_create_bigint_uint64` + <!-- YAML added: v10.7.0 napiVersion: 6 @@ -2571,7 +2653,8 @@ Returns `napi_ok` if the API succeeded. This API converts the C `uint64_t` type to the JavaScript `BigInt` type. -#### napi_create_bigint_words +#### `napi_create_bigint_words` + <!-- YAML added: v10.7.0 napiVersion: 6 @@ -2600,7 +2683,8 @@ value. The resulting `BigInt` is calculated as: (–1)<sup>`sign_bit`</sup> (`words[0]` × (2<sup>64</sup>)<sup>0</sup> + `words[1]` × (2<sup>64</sup>)<sup>1</sup> + …) -#### napi_create_string_latin1 +#### `napi_create_string_latin1` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2627,7 +2711,8 @@ string. The native string is copied. The JavaScript `string` type is described in [Section 6.1.4][] of the ECMAScript Language Specification. -#### napi_create_string_utf16 +#### `napi_create_string_utf16` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2654,7 +2739,8 @@ The native string is copied. The JavaScript `string` type is described in [Section 6.1.4][] of the ECMAScript Language Specification. -#### napi_create_string_utf8 +#### `napi_create_string_utf8` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2682,7 +2768,9 @@ The JavaScript `string` type is described in [Section 6.1.4][] of the ECMAScript Language Specification. ### Functions to convert from Node-API to C types -#### napi_get_array_length + +#### `napi_get_array_length` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2706,7 +2794,8 @@ This API returns the length of an array. `Array` length is described in [Section 22.1.4.1][] of the ECMAScript Language Specification. -#### napi_get_arraybuffer_info +#### `napi_get_arraybuffer_info` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2721,7 +2810,7 @@ napi_status napi_get_arraybuffer_info(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] arraybuffer`: `napi_value` representing the `ArrayBuffer` being queried. -* `[out] data`: The underlying data buffer of the `ArrayBuffer`. If byte_length +* `[out] data`: The underlying data buffer of the `ArrayBuffer`. If byte\_length is `0`, this may be `NULL` or any other pointer value. * `[out] byte_length`: Length in bytes of the underlying data buffer. @@ -2730,7 +2819,7 @@ Returns `napi_ok` if the API succeeded. This API is used to retrieve the underlying data buffer of an `ArrayBuffer` and its length. -*WARNING*: Use caution while using this API. The lifetime of the underlying data +_WARNING_: Use caution while using this API. The lifetime of the underlying data buffer is managed by the `ArrayBuffer` even after it's returned. A possible safe way to use this API is in conjunction with [`napi_create_reference`][], which can be used to guarantee control over the @@ -2738,7 +2827,8 @@ lifetime of the `ArrayBuffer`. It's also safe to use the returned data buffer within the same callback as long as there are no calls to other APIs that might trigger a GC. -#### napi_get_buffer_info +#### `napi_get_buffer_info` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2762,10 +2852,11 @@ Returns `napi_ok` if the API succeeded. This API is used to retrieve the underlying data buffer of a `node::Buffer` and its length. -*Warning*: Use caution while using this API since the underlying data buffer's +_Warning_: Use caution while using this API since the underlying data buffer's lifetime is not guaranteed if it's managed by the VM. -#### napi_get_prototype +#### `napi_get_prototype` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2785,7 +2876,8 @@ napi_status napi_get_prototype(napi_env env, Returns `napi_ok` if the API succeeded. -#### napi_get_typedarray_info +#### `napi_get_typedarray_info` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2823,10 +2915,11 @@ This API returns various properties of a typed array. Any of the out parameters may be `NULL` if that property is unneeded. -*Warning*: Use caution while using this API since the underlying data buffer +_Warning_: Use caution while using this API since the underlying data buffer is managed by the VM. -#### napi_get_dataview_info +#### `napi_get_dataview_info` + <!-- YAML added: v8.3.0 napiVersion: 1 @@ -2846,7 +2939,7 @@ napi_status napi_get_dataview_info(napi_env env, properties to query. * `[out] byte_length`: Number of bytes in the `DataView`. * `[out] data`: The data buffer underlying the `DataView`. - If byte_length is `0`, this may be `NULL` or any other pointer value. + If byte\_length is `0`, this may be `NULL` or any other pointer value. * `[out] arraybuffer`: `ArrayBuffer` underlying the `DataView`. * `[out] byte_offset`: The byte offset within the data buffer from which to start projecting the `DataView`. @@ -2857,7 +2950,8 @@ Any of the out parameters may be `NULL` if that property is unneeded. This API returns various properties of a `DataView`. -#### napi_get_date_value +#### `napi_get_date_value` + <!-- YAML added: - v11.11.0 @@ -2885,7 +2979,8 @@ in it returns `napi_date_expected`. This API returns the C double primitive of time value for the given JavaScript `Date`. -#### napi_get_value_bool +#### `napi_get_value_bool` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2906,7 +3001,8 @@ passed in it returns `napi_boolean_expected`. This API returns the C boolean primitive equivalent of the given JavaScript `Boolean`. -#### napi_get_value_double +#### `napi_get_value_double` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -2929,7 +3025,8 @@ in it returns `napi_number_expected`. This API returns the C double primitive equivalent of the given JavaScript `number`. -#### napi_get_value_bigint_int64 +#### `napi_get_value_bigint_int64` + <!-- YAML added: v10.7.0 napiVersion: 6 @@ -2955,7 +3052,8 @@ returns `napi_bigint_expected`. This API returns the C `int64_t` primitive equivalent of the given JavaScript `BigInt`. If needed it will truncate the value, setting `lossless` to `false`. -#### napi_get_value_bigint_uint64 +#### `napi_get_value_bigint_uint64` + <!-- YAML added: v10.7.0 napiVersion: 6 @@ -2981,7 +3079,8 @@ returns `napi_bigint_expected`. This API returns the C `uint64_t` primitive equivalent of the given JavaScript `BigInt`. If needed it will truncate the value, setting `lossless` to `false`. -#### napi_get_value_bigint_words +#### `napi_get_value_bigint_words` + <!-- YAML added: v10.7.0 napiVersion: 6 @@ -2998,10 +3097,10 @@ napi_status napi_get_value_bigint_words(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript `BigInt`. * `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive - or negative. + or negative. * `[in/out] word_count`: Must be initialized to the length of the `words` - array. Upon return, it will be set to the actual number of words that - would be needed to store this `BigInt`. + array. Upon return, it will be set to the actual number of words that + would be needed to store this `BigInt`. * `[out] words`: Pointer to a pre-allocated 64-bit word array. Returns `napi_ok` if the API succeeded. @@ -3010,7 +3109,8 @@ This API converts a single `BigInt` value into a sign bit, 64-bit little-endian array, and the number of elements in the array. `sign_bit` and `words` may be both set to `NULL`, in order to get only `word_count`. -#### napi_get_value_external +#### `napi_get_value_external` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3032,7 +3132,8 @@ passed in it returns `napi_invalid_arg`. This API retrieves the external data pointer that was previously passed to `napi_create_external()`. -#### napi_get_value_int32 +#### `napi_get_value_int32` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3062,7 +3163,8 @@ positive number becoming a negative number if the value is > 2<sup>31</sup> - 1. Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the result to zero. -#### napi_get_value_int64 +#### `napi_get_value_int64` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3092,7 +3194,8 @@ precision. Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the result to zero. -#### napi_get_value_string_latin1 +#### `napi_get_value_string_latin1` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3122,7 +3225,8 @@ is passed in it returns `napi_string_expected`. This API returns the ISO-8859-1-encoded string corresponding the value passed in. -#### napi_get_value_string_utf8 +#### `napi_get_value_string_utf8` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3151,7 +3255,8 @@ is passed in it returns `napi_string_expected`. This API returns the UTF8-encoded string corresponding the value passed in. -#### napi_get_value_string_utf16 +#### `napi_get_value_string_utf16` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3180,7 +3285,8 @@ is passed in it returns `napi_string_expected`. This API returns the UTF16-encoded string corresponding the value passed in. -#### napi_get_value_uint32 +#### `napi_get_value_uint32` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3204,7 +3310,9 @@ This API returns the C primitive equivalent of the given `napi_value` as a `uint32_t`. ### Functions to get global instances -#### napi_get_boolean + +#### `napi_get_boolean` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3224,7 +3332,8 @@ Returns `napi_ok` if the API succeeded. This API is used to return the JavaScript singleton object that is used to represent the given boolean value. -#### napi_get_global +#### `napi_get_global` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3241,7 +3350,8 @@ Returns `napi_ok` if the API succeeded. This API returns the `global` object. -#### napi_get_null +#### `napi_get_null` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3258,7 +3368,8 @@ Returns `napi_ok` if the API succeeded. This API returns the `null` object. -#### napi_get_undefined +#### `napi_get_undefined` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3288,7 +3399,8 @@ These APIs support doing one of the following: 2. Check the type of a JavaScript value. 3. Check for equality between two JavaScript values. -### napi_coerce_to_bool +### `napi_coerce_to_bool` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3309,7 +3421,8 @@ Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToBoolean()` as defined in [Section 7.1.2][] of the ECMAScript Language Specification. -### napi_coerce_to_number +### `napi_coerce_to_number` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3332,7 +3445,8 @@ This API implements the abstract operation `ToNumber()` as defined in This function potentially runs JS code if the passed-in value is an object. -### napi_coerce_to_object +### `napi_coerce_to_object` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3353,7 +3467,8 @@ Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToObject()` as defined in [Section 7.1.13][] of the ECMAScript Language Specification. -### napi_coerce_to_string +### `napi_coerce_to_string` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3376,7 +3491,8 @@ This API implements the abstract operation `ToString()` as defined in This function potentially runs JS code if the passed-in value is an object. -### napi_typeof +### `napi_typeof` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3405,7 +3521,8 @@ Specification. However, there are some differences: If `value` has a type that is invalid, an error is returned. -### napi_instanceof +### `napi_instanceof` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3430,7 +3547,8 @@ Returns `napi_ok` if the API succeeded. This API represents invoking the `instanceof` Operator on the object as defined in [Section 12.10.4][] of the ECMAScript Language Specification. -### napi_is_array +### `napi_is_array` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3449,7 +3567,8 @@ Returns `napi_ok` if the API succeeded. This API represents invoking the `IsArray` operation on the object as defined in [Section 7.2.2][] of the ECMAScript Language Specification. -### napi_is_arraybuffer +### `napi_is_arraybuffer` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3467,7 +3586,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in is an array buffer. -### napi_is_buffer +### `napi_is_buffer` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3486,7 +3606,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in is a buffer. -### napi_is_date +### `napi_is_date` + <!-- YAML added: - v11.11.0 @@ -3507,7 +3628,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in is a date. -### napi_is_error +### `napi_is_error` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3525,7 +3647,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in is an `Error`. -### napi_is_typedarray +### `napi_is_typedarray` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3543,7 +3666,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in is a typed array. -### napi_is_dataview +### `napi_is_dataview` + <!-- YAML added: v8.3.0 napiVersion: 1 @@ -3561,7 +3685,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in is a `DataView`. -### napi_strict_equals +### `napi_strict_equals` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3584,7 +3709,8 @@ Returns `napi_ok` if the API succeeded. This API represents the invocation of the Strict Equality algorithm as defined in [Section 7.2.14][] of the ECMAScript Language Specification. -### napi_detach_arraybuffer +### `napi_detach_arraybuffer` + <!-- YAML added: - v13.0.0 @@ -3612,7 +3738,8 @@ that is, created with [`napi_create_external_arraybuffer`][]. This API represents the invocation of the `ArrayBuffer` detach operation as defined in [Section 24.1.1.3][] of the ECMAScript Language Specification. -### napi_is_detached_arraybuffer +### `napi_is_detached_arraybuffer` + <!-- YAML added: - v13.3.0 @@ -3780,7 +3907,9 @@ if (status != napi_ok) return status; ``` ### Structures -#### napi_property_attributes + +#### `napi_property_attributes` + <!-- YAML changes: - version: v14.12.0 @@ -3829,7 +3958,7 @@ They can be one or more of the following bitflags: * `napi_default_jsproperty`: Like a property set via assignment in JavaScript, the property is writable, enumerable, and configurable. -#### napi_property_descriptor +#### `napi_property_descriptor` ```c typedef struct { @@ -3876,7 +4005,9 @@ typedef struct { function is invoked. ### Functions -#### napi_get_property_names + +#### `napi_get_property_names` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3901,7 +4032,8 @@ This API returns the names of the enumerable properties of `object` as an array of strings. The properties of `object` whose key is a symbol will not be included. -#### napi_get_all_property_names +#### `napi_get_all_property_names` + <!-- YAML added: - v13.7.0 @@ -3934,7 +4066,8 @@ Returns `napi_ok` if the API succeeded. This API returns an array containing the names of the available properties of this object. -#### napi_set_property +#### `napi_set_property` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3956,7 +4089,8 @@ Returns `napi_ok` if the API succeeded. This API set a property on the `Object` passed in. -#### napi_get_property +#### `napi_get_property` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -3978,7 +4112,8 @@ Returns `napi_ok` if the API succeeded. This API gets the requested property from the `Object` passed in. -#### napi_has_property +#### `napi_has_property` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4000,7 +4135,8 @@ Returns `napi_ok` if the API succeeded. This API checks if the `Object` passed in has the named property. -#### napi_delete_property +#### `napi_delete_property` + <!-- YAML added: v8.2.0 napiVersion: 1 @@ -4023,7 +4159,8 @@ Returns `napi_ok` if the API succeeded. This API attempts to delete the `key` own property from `object`. -#### napi_has_own_property +#### `napi_has_own_property` + <!-- YAML added: v8.2.0 napiVersion: 1 @@ -4047,7 +4184,8 @@ This API checks if the `Object` passed in has the named own property. `key` must be a `string` or a `symbol`, or an error will be thrown. Node-API will not perform any conversion between data types. -#### napi_set_named_property +#### `napi_set_named_property` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4070,7 +4208,8 @@ Returns `napi_ok` if the API succeeded. This method is equivalent to calling [`napi_set_property`][] with a `napi_value` created from the string passed in as `utf8Name`. -#### napi_get_named_property +#### `napi_get_named_property` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4093,7 +4232,8 @@ Returns `napi_ok` if the API succeeded. This method is equivalent to calling [`napi_get_property`][] with a `napi_value` created from the string passed in as `utf8Name`. -#### napi_has_named_property +#### `napi_has_named_property` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4116,7 +4256,8 @@ Returns `napi_ok` if the API succeeded. This method is equivalent to calling [`napi_has_property`][] with a `napi_value` created from the string passed in as `utf8Name`. -#### napi_set_element +#### `napi_set_element` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4138,7 +4279,8 @@ Returns `napi_ok` if the API succeeded. This API sets an element on the `Object` passed in. -#### napi_get_element +#### `napi_get_element` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4160,7 +4302,8 @@ Returns `napi_ok` if the API succeeded. This API gets the element at the requested index. -#### napi_has_element +#### `napi_has_element` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4183,7 +4326,8 @@ Returns `napi_ok` if the API succeeded. This API returns if the `Object` passed in has an element at the requested index. -#### napi_delete_element +#### `napi_delete_element` + <!-- YAML added: v8.2.0 napiVersion: 1 @@ -4206,7 +4350,8 @@ Returns `napi_ok` if the API succeeded. This API attempts to delete the specified `index` from `object`. -#### napi_define_properties +#### `napi_define_properties` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4233,7 +4378,8 @@ this API will set the properties on the object one at a time, as defined by `DefineOwnProperty()` (described in [Section 9.1.6][] of the ECMA-262 specification). -#### napi_object_freeze +#### `napi_object_freeze` + <!-- YAML added: - v14.14.0 @@ -4259,7 +4405,8 @@ It also prevents the object's prototype from being changed. This is described in [Section 19.1.2.6](https://tc39.es/ecma262/#sec-object.freeze) of the ECMA-262 specification. -#### napi_object_seal +#### `napi_object_seal` + <!-- YAML added: - v14.14.0 @@ -4306,7 +4453,8 @@ Any non-`NULL` data which is passed to this API via the `data` field of the whenever `object` is garbage-collected by passing both `object` and the data to [`napi_add_finalizer`][]. -### napi_call_function +### `napi_call_function` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4332,8 +4480,8 @@ NAPI_EXTERN napi_status napi_call_function(napi_env env, Returns `napi_ok` if the API succeeded. This method allows a JavaScript function object to be called from a native -add-on. This is the primary mechanism of calling back *from* the add-on's -native code *into* JavaScript. For the special case of calling into JavaScript +add-on. This is the primary mechanism of calling back _from_ the add-on's +native code _into_ JavaScript. For the special case of calling into JavaScript after an async operation, see [`napi_make_callback`][]. A sample use case might look as follows. Consider the following JavaScript @@ -4375,7 +4523,8 @@ status = napi_get_value_int32(env, return_val, &result); if (status != napi_ok) return; ``` -### napi_create_function +### `napi_create_function` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4405,8 +4554,8 @@ napi_status napi_create_function(napi_env env, Returns `napi_ok` if the API succeeded. This API allows an add-on author to create a function object in native code. -This is the primary mechanism to allow calling *into* the add-on's native code -*from* JavaScript. +This is the primary mechanism to allow calling _into_ the add-on's native code +_from_ JavaScript. The newly created function is not automatically visible from script after this call. Instead, a property must be explicitly set on any object that is visible @@ -4456,7 +4605,8 @@ passing both the JavaScript function and the data to [`napi_add_finalizer`][]. JavaScript `Function`s are described in [Section 19.2][] of the ECMAScript Language Specification. -### napi_get_cb_info +### `napi_get_cb_info` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4488,7 +4638,8 @@ Returns `napi_ok` if the API succeeded. This method is used within a callback function to retrieve details about the call like the arguments and the `this` pointer from a given callback info. -### napi_get_new_target +### `napi_get_new_target` + <!-- YAML added: v8.6.0 napiVersion: 1 @@ -4509,7 +4660,8 @@ Returns `napi_ok` if the API succeeded. This API returns the `new.target` of the constructor call. If the current callback is not a constructor call, the result is `NULL`. -### napi_new_instance +### `napi_new_instance` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4575,15 +4727,15 @@ Node-API offers a way to "wrap" C++ classes and instances so that the class constructor and methods can be called from JavaScript. 1. The [`napi_define_class`][] API defines a JavaScript class with constructor, - static properties and methods, and instance properties and methods that - correspond to the C++ class. + static properties and methods, and instance properties and methods that + correspond to the C++ class. 2. When JavaScript code invokes the constructor, the constructor callback - uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object, - then returns the wrapper object. + uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object, + then returns the wrapper object. 3. When JavaScript code invokes a method or property accessor on the class, - the corresponding `napi_callback` C++ function is invoked. For an instance - callback, [`napi_unwrap`][] obtains the C++ instance that is the target of - the call. + the corresponding `napi_callback` C++ function is invoked. For an instance + callback, [`napi_unwrap`][] obtains the C++ instance that is the target of + the call. For wrapped objects it may be difficult to distinguish between a function called on a class prototype and a function called on an instance of a class. @@ -4743,7 +4895,8 @@ query(napi_env env, napi_callback_info info) { } ``` -### napi_define_class +### `napi_define_class` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4815,7 +4968,8 @@ with the resulting JavaScript constructor (which is returned in the `result` parameter) and freed whenever the class is garbage-collected by passing both the JavaScript function and the data to [`napi_add_finalizer`][]. -### napi_wrap +### `napi_wrap` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4863,7 +5017,7 @@ The optional returned reference is initially a weak reference, meaning it has a reference count of 0. Typically this reference count would be incremented temporarily during async operations that require the instance to remain valid. -*Caution*: The optional returned reference (if obtained) should be deleted via +_Caution_: The optional returned reference (if obtained) should be deleted via [`napi_delete_reference`][] ONLY in response to the finalize callback invocation. If it is deleted before then, then the finalize callback may never be invoked. Therefore, when obtaining a reference a finalize callback is also @@ -4873,7 +5027,8 @@ Calling `napi_wrap()` a second time on an object will return an error. To associate another native instance with the object, use `napi_remove_wrap()` first. -### napi_unwrap +### `napi_unwrap` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -4900,7 +5055,8 @@ method or accessor, then the `this` argument to the callback is the wrapper object; the wrapped C++ instance that is the target of the call can be obtained then by calling `napi_unwrap()` on the wrapper object. -### napi_remove_wrap +### `napi_remove_wrap` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -4923,7 +5079,8 @@ object `js_object` using `napi_wrap()` and removes the wrapping. If a finalize callback was associated with the wrapping, it will no longer be called when the JavaScript object becomes garbage-collected. -### napi_type_tag_object +### `napi_type_tag_object` + <!-- YAML added: - v14.8.0 @@ -4951,7 +5108,8 @@ has the right type. If the object already has an associated type tag, this API will return `napi_invalid_arg`. -### napi_check_object_type_tag +### `napi_check_object_type_tag` + <!-- YAML added: - v14.8.0 @@ -4979,7 +5137,7 @@ Compares the pointer given as `type_tag` with any that can be found on not match `type_tag`, then `result` is set to `false`. If a tag is found and it matches `type_tag`, then `result` is set to `true`. -### napi_add_finalizer +### `napi_add_finalizer` <!-- YAML added: v8.0.0 @@ -5019,7 +5177,7 @@ in `js_object` is ready for garbage collection. This API is similar to attach each of them to the JavaScript object, and * the object manipulated by the API can be used with `napi_wrap()`. -*Caution*: The optional returned reference (if obtained) should be deleted via +_Caution_: The optional returned reference (if obtained) should be deleted via [`napi_delete_reference`][] ONLY in response to the finalize callback invocation. If it is deleted before then, then the finalize callback may never be invoked. Therefore, when obtaining a reference a finalize callback is also @@ -5080,7 +5238,8 @@ will be invoked with a status value of `napi_cancelled`. The work should not be deleted before the `complete` callback invocation, even when it was cancelled. -### napi_create_async_work +### `napi_create_async_work` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -5130,7 +5289,8 @@ representative of the type of async work being performed. It is also recommended to apply namespacing to the identifier, e.g. by including the module name. See the [`async_hooks` documentation][async_hooks `type`] for more information. -### napi_delete_async_work +### `napi_delete_async_work` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -5150,7 +5310,8 @@ This API frees a previously allocated work object. This API can be called even if there is a pending JavaScript exception. -### napi_queue_async_work +### `napi_queue_async_work` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -5170,7 +5331,8 @@ This API requests that the previously allocated work be scheduled for execution. Once it returns successfully, this API must not be called again with the same `napi_async_work` item or the result will be undefined. -### napi_cancel_async_work +### `napi_cancel_async_work` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -5202,7 +5364,8 @@ scenario. When using any other asynchronous mechanism, the following APIs are necessary to ensure an asynchronous operation is properly tracked by the runtime. -### napi_async_init +### `napi_async_init` + <!-- YAML added: v8.6.0 napiVersion: 1 @@ -5242,7 +5405,8 @@ recommended as this will result poor results with `async_hooks` now required by the underlying `async_hooks` implementation in order to provide the linkage between async callbacks. -### napi_async_destroy +### `napi_async_destroy` + <!-- YAML added: v8.6.0 napiVersion: 1 @@ -5260,7 +5424,8 @@ Returns `napi_ok` if the API succeeded. This API can be called even if there is a pending JavaScript exception. -### napi_make_callback +### `napi_make_callback` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -5282,12 +5447,12 @@ NAPI_EXTERN napi_status napi_make_callback(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] async_context`: Context for the async operation that is - invoking the callback. This should normally be a value previously - obtained from [`napi_async_init`][]. - In order to retain ABI compatibility with previous versions, passing `NULL` - for `async_context` does not result in an error. However, this results - in incorrect operation of async hooks. Potential issues include loss of - async context when using the `AsyncLocalStorage` API. + invoking the callback. This should normally be a value previously + obtained from [`napi_async_init`][]. + In order to retain ABI compatibility with previous versions, passing `NULL` + for `async_context` does not result in an error. However, this results + in incorrect operation of async hooks. Potential issues include loss of + async context when using the `AsyncLocalStorage` API. * `[in] recv`: The `this` value passed to the called function. * `[in] func`: `napi_value` representing the JavaScript function to be invoked. * `[in] argc`: The count of elements in the `argv` array. @@ -5299,11 +5464,11 @@ Returns `napi_ok` if the API succeeded. This method allows a JavaScript function object to be called from a native add-on. This API is similar to `napi_call_function`. However, it is used to call -*from* native code back *into* JavaScript *after* returning from an async +_from_ native code back _into_ JavaScript _after_ returning from an async operation (when there is no other script on the stack). It is a fairly simple wrapper around `node::MakeCallback`. -Note it is *not* necessary to use `napi_make_callback` from within a +Note it is _not_ necessary to use `napi_make_callback` from within a `napi_async_complete_callback`; in that situation the callback's async context has already been set up, so a direct call to `napi_call_function` is sufficient and appropriate. Use of the `napi_make_callback` function @@ -5313,7 +5478,8 @@ may be required when implementing custom async behavior that does not use Any `process.nextTick`s or Promises scheduled on the microtask queue by JavaScript during the callback are ran before returning back to C/C++. -### napi_open_callback_scope +### `napi_open_callback_scope` + <!-- YAML added: v9.6.0 napiVersion: 3 @@ -5342,7 +5508,8 @@ the stack the [`napi_open_callback_scope`][] and [`napi_close_callback_scope`][] functions can be used to open/close the required scope. -### napi_close_callback_scope +### `napi_close_callback_scope` + <!-- YAML added: v9.6.0 napiVersion: 3 @@ -5360,7 +5527,8 @@ This API can be called even if there is a pending JavaScript exception. ## Version management -### napi_get_node_version +### `napi_get_node_version` + <!-- YAML added: v8.4.0 napiVersion: 1 @@ -5389,7 +5557,8 @@ value of [`process.release.name`][`process.release`]. The returned buffer is statically allocated and does not need to be freed. -### napi_get_version +### `napi_get_version` + <!-- YAML added: v8.0.0 napiVersion: 1 @@ -5421,7 +5590,8 @@ support it: ## Memory management -### napi_adjust_external_memory +### `napi_adjust_external_memory` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -5502,7 +5672,8 @@ if (status != napi_ok) return NULL; deferred = NULL; ``` -### napi_create_promise +### `napi_create_promise` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -5524,7 +5695,8 @@ Returns `napi_ok` if the API succeeded. This API creates a deferred object and a JavaScript promise. -### napi_resolve_deferred +### `napi_resolve_deferred` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -5549,7 +5721,8 @@ have been retained in order to be passed to this API. The deferred object is freed upon successful completion. -### napi_reject_deferred +### `napi_reject_deferred` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -5574,7 +5747,8 @@ have been retained in order to be passed to this API. The deferred object is freed upon successful completion. -### napi_is_promise +### `napi_is_promise` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -5596,7 +5770,8 @@ napi_status napi_is_promise(napi_env env, Node-API provides an API for executing a string containing JavaScript using the underlying JavaScript engine. -### napi_run_script +### `napi_run_script` + <!-- YAML added: v8.5.0 napiVersion: 1 @@ -5630,7 +5805,8 @@ the following caveats: Node-API provides a function for getting the current event loop associated with a specific `napi_env`. -### napi_get_uv_event_loop +### `napi_get_uv_event_loop` + <!-- YAML added: - v9.3.0 @@ -5770,7 +5946,7 @@ Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from being destroyed. -### napi_create_threadsafe_function +### `napi_create_threadsafe_function` <!-- YAML added: v10.6.0 @@ -5822,7 +5998,7 @@ napi_create_threadsafe_function(napi_env env, [`napi_threadsafe_function_call_js`][] provides more details. * `[out] result`: The asynchronous thread-safe JavaScript function. -### napi_get_threadsafe_function_context +### `napi_get_threadsafe_function_context` <!-- YAML added: v10.6.0 @@ -5840,7 +6016,7 @@ napi_get_threadsafe_function_context(napi_threadsafe_function func, This API may be called from any thread which makes use of `func`. -### napi_call_threadsafe_function +### `napi_call_threadsafe_function` <!-- YAML added: v10.6.0 @@ -5881,7 +6057,7 @@ added to the queue if the API returns `napi_ok`. This API may be called from any thread which makes use of `func`. -### napi_acquire_threadsafe_function +### `napi_acquire_threadsafe_function` <!-- YAML added: v10.6.0 @@ -5903,7 +6079,7 @@ it. This API may be called from any thread which will start making use of `func`. -### napi_release_threadsafe_function +### `napi_release_threadsafe_function` <!-- YAML added: v10.6.0 @@ -5932,7 +6108,7 @@ to any thread-safe APIs after having called this API has undefined results, as This API may be called from any thread which will stop making use of `func`. -### napi_ref_threadsafe_function +### `napi_ref_threadsafe_function` <!-- YAML added: v10.6.0 @@ -5958,7 +6134,7 @@ being destroyed. `napi_acquire_threadsafe_function` and This API may only be called from the main thread. -### napi_unref_threadsafe_function +### `napi_unref_threadsafe_function` <!-- YAML added: v10.6.0 @@ -5981,7 +6157,7 @@ This API may only be called from the main thread. ## Miscellaneous utilities -## node_api_get_module_file_name +### `node_api_get_module_file_name` <!-- YAML added: diff --git a/doc/api/net.md b/doc/api/net.md index 6d5487b6748..8d3aaf1b6c5 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -40,11 +40,11 @@ applies when a Node.js API creates a Unix domain socket but the program then crashes. In short, a Unix domain socket will be visible in the filesystem and will persist until unlinked. -On Windows, the local domain is implemented using a named pipe. The path *must* +On Windows, the local domain is implemented using a named pipe. The path _must_ refer to an entry in `\\?\pipe\` or `\\.\pipe\`. Any characters are permitted, but the latter may do some processing of pipe names, such as resolving `..` sequences. Despite how it might look, the pipe namespace is flat. Pipes will -*not persist*. They are removed when the last reference to them is closed. +_not persist_. They are removed when the last reference to them is closed. Unlike Unix domain sockets, Windows will close and remove the pipe when the owning process exits. @@ -57,6 +57,7 @@ net.createServer().listen( ``` ## Class: `net.BlockList` + <!-- YAML added: - v15.0.0 @@ -68,6 +69,7 @@ disabling inbound or outbound access to specific IP addresses, IP ranges, or IP subnets. ### `blockList.addAddress(address[, type])` + <!-- YAML added: - v15.0.0 @@ -80,6 +82,7 @@ added: Adds a rule to block the given IP address. ### `blockList.addRange(start, end[, type])` + <!-- YAML added: - v15.0.0 @@ -95,6 +98,7 @@ Adds a rule to block a range of IP addresses from `start` (inclusive) to `end` (inclusive). ### `blockList.addSubnet(net, prefix[, type])` + <!-- YAML added: - v15.0.0 @@ -110,6 +114,7 @@ added: Adds a rule to block a range of IP addresses specified as a subnet mask. ### `blockList.check(address[, type])` + <!-- YAML added: - v15.0.0 @@ -139,23 +144,27 @@ console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true ``` ### `blockList.rules` + <!-- YAML added: - v15.0.0 - v14.18.0 --> -* Type: {string[]} +* Type: {string\[]} The list of rules added to the blocklist. ## Class: `net.SocketAddress` + <!-- YAML added: - v15.14.0 - v14.18.0 --> + ### `new net.SocketAddress([options])` + <!-- YAML added: - v15.14.0 @@ -166,11 +175,13 @@ added: * `address` {string} The network address as either an IPv4 or IPv6 string. **Default**: `'127.0.0.1'` if `family` is `'ipv4'`; `'::'` if `family` is `'ipv6'`. - * `family` {string} One of either `'ipv4'` or 'ipv6'`. **Default**: `'ipv4'`. + * `family` {string} One of either `'ipv4'` or `'ipv6'`. + **Default**: `'ipv4'`. * `flowlabel` {number} An IPv6 flow-label used only if `family` is `'ipv6'`. * `port` {number} An IP port. ### `socketaddress.address` + <!-- YAML added: - v15.14.0 @@ -180,6 +191,7 @@ added: * Type {string} ### `socketaddress.family` + <!-- YAML added: - v15.14.0 @@ -189,6 +201,7 @@ added: * Type {string} Either `'ipv4'` or `'ipv6'`. ### `socketaddress.flowlabel` + <!-- YAML added: - v15.14.0 @@ -198,6 +211,7 @@ added: * Type {number} ### `socketaddress.port` + <!-- YAML added: - v15.14.0 @@ -207,6 +221,7 @@ added: * Type {number} ## Class: `net.Server` + <!-- YAML added: v0.1.90 --> @@ -226,6 +241,7 @@ This class is used to create a TCP or [IPC][] server. `net.Server` is an [`EventEmitter`][] with the following events: ### Event: `'close'` + <!-- YAML added: v0.5.0 --> @@ -234,6 +250,7 @@ Emitted when the server closes. If connections exist, this event is not emitted until all connections are ended. ### Event: `'connection'` + <!-- YAML added: v0.1.90 --> @@ -244,6 +261,7 @@ Emitted when a new connection is made. `socket` is an instance of `net.Socket`. ### Event: `'error'` + <!-- YAML added: v0.1.90 --> @@ -256,6 +274,7 @@ event will **not** be emitted directly following this event unless [`server.listen()`][]. ### Event: `'listening'` + <!-- YAML added: v0.1.90 --> @@ -263,6 +282,7 @@ added: v0.1.90 Emitted when the server has been bound after calling [`server.listen()`][]. ### `server.address()` + <!-- YAML added: v0.1.90 --> @@ -295,6 +315,7 @@ server.listen(() => { emitted or after calling `server.close()`. ### `server.close([callback])` + <!-- YAML added: v0.1.90 --> @@ -310,6 +331,7 @@ that event, it will be called with an `Error` as its only argument if the server was not open when it was closed. ### `server.getConnections(callback)` + <!-- YAML added: v0.9.7 --> @@ -329,15 +351,12 @@ an [IPC][] server depending on what it listens to. Possible signatures: -<!--lint disable no-undefined-references--> * [`server.listen(handle[, backlog][, callback])`][`server.listen(handle)`] * [`server.listen(options[, callback])`][`server.listen(options)`] * [`server.listen(path[, backlog][, callback])`][`server.listen(path)`] for [IPC][] servers -* <a href="#serverlistenport-host-backlog-callback"> - <code>server.listen([port[, host[, backlog]]][, callback])</code></a> +* [`server.listen([port[, host[, backlog]]][, callback])`][`server.listen(port)`] for TCP servers -<!--lint enable no-undefined-references--> This function is asynchronous. When the server starts listening, the [`'listening'`][] event will be emitted. The last parameter `callback` @@ -373,6 +392,7 @@ server.on('error', (e) => { ``` #### `server.listen(handle[, backlog][, callback])` + <!-- YAML added: v0.5.10 --> @@ -392,6 +412,7 @@ valid file descriptor. Listening on a file descriptor is not supported on Windows. #### `server.listen(options[, callback])` + <!-- YAML added: v0.11.14 changes: @@ -423,14 +444,11 @@ changes: functions. * Returns: {net.Server} -<!--lint disable no-undefined-references--> If `port` is specified, it behaves the same as -<a href="#serverlistenport-host-backlog-callback"> -<code>server.listen([port[, host[, backlog]]][, callback])</code></a>. +[`server.listen([port[, host[, backlog]]][, callback])`][`server.listen(port)`]. Otherwise, if `path` is specified, it behaves the same as [`server.listen(path[, backlog][, callback])`][`server.listen(path)`]. If none of them is specified, an error will be thrown. -<!--lint enable no-undefined-references--> If `exclusive` is `false` (default), then cluster workers will use the same underlying handle, allowing connection handling duties to be shared. When @@ -465,6 +483,7 @@ controller.abort(); ``` #### `server.listen(path[, backlog][, callback])` + <!-- YAML added: v0.1.90 --> @@ -478,6 +497,7 @@ added: v0.1.90 Start an [IPC][] server listening for connections on the given `path`. #### `server.listen([port[, host[, backlog]]][, callback])` + <!-- YAML added: v0.1.90 --> @@ -503,6 +523,7 @@ may cause the `net.Server` to also listen on the [unspecified IPv4 address][] (`0.0.0.0`). ### `server.listening` + <!-- YAML added: v5.7.0 --> @@ -510,6 +531,7 @@ added: v5.7.0 * {boolean} Indicates whether or not the server is listening for connections. ### `server.maxConnections` + <!-- YAML added: v0.2.0 --> @@ -523,6 +545,7 @@ It is not recommended to use this option once a socket has been sent to a child with [`child_process.fork()`][]. ### `server.ref()` + <!-- YAML added: v0.9.1 --> @@ -530,10 +553,11 @@ added: v0.9.1 * Returns: {net.Server} Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will -*not* let the program exit if it's the only server left (the default behavior). +_not_ let the program exit if it's the only server left (the default behavior). If the server is `ref`ed calling `ref()` again will have no effect. ### `server.unref()` + <!-- YAML added: v0.9.1 --> @@ -545,6 +569,7 @@ active server in the event system. If the server is already `unref`ed calling `unref()` again will have no effect. ## Class: `net.Socket` + <!-- YAML added: v0.3.4 --> @@ -565,6 +590,7 @@ is received. For example, it is passed to the listeners of a it to interact with the client. ### `new net.Socket([options])` + <!-- YAML added: v0.3.4 changes: @@ -594,6 +620,7 @@ The newly created socket can be either a TCP socket or a streaming [IPC][] endpoint, depending on what it [`connect()`][`socket.connect()`] to. ### Event: `'close'` + <!-- YAML added: v0.1.90 --> @@ -604,6 +631,7 @@ Emitted once the socket is fully closed. The argument `hadError` is a boolean which says if the socket was closed due to a transmission error. ### Event: `'connect'` + <!-- YAML added: v0.1.90 --> @@ -612,6 +640,7 @@ Emitted when a socket connection is successfully established. See [`net.createConnection()`][]. ### Event: `'data'` + <!-- YAML added: v0.1.90 --> @@ -625,6 +654,7 @@ The data will be lost if there is no listener when a `Socket` emits a `'data'` event. ### Event: `'drain'` + <!-- YAML added: v0.1.90 --> @@ -634,6 +664,7 @@ Emitted when the write buffer becomes empty. Can be used to throttle uploads. See also: the return values of `socket.write()`. ### Event: `'end'` + <!-- YAML added: v0.1.90 --> @@ -650,6 +681,7 @@ allowing the user to write arbitrary amounts of data. The user must call FIN packet back). ### Event: `'error'` + <!-- YAML added: v0.1.90 --> @@ -660,6 +692,7 @@ Emitted when an error occurs. The `'close'` event will be called directly following this event. ### Event: `'lookup'` + <!-- YAML added: v0.11.3 changes: @@ -677,6 +710,7 @@ Not applicable to Unix sockets. * `host` {string} The host name. ### Event: `'ready'` + <!-- YAML added: v9.11.0 --> @@ -686,6 +720,7 @@ Emitted when a socket is ready to be used. Triggered immediately after `'connect'`. ### Event: `'timeout'` + <!-- YAML added: v0.1.90 --> @@ -696,6 +731,7 @@ the socket has been idle. The user must manually close the connection. See also: [`socket.setTimeout()`][]. ### `socket.address()` + <!-- YAML added: v0.1.90 --> @@ -707,6 +743,7 @@ socket as reported by the operating system: `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` ### `socket.bufferSize` + <!-- YAML added: v0.3.8 deprecated: @@ -733,6 +770,7 @@ Users who experience large or growing `bufferSize` should attempt to [`socket.pause()`][] and [`socket.resume()`][]. ### `socket.bytesRead` + <!-- YAML added: v0.5.3 --> @@ -742,6 +780,7 @@ added: v0.5.3 The amount of received bytes. ### `socket.bytesWritten` + <!-- YAML added: v0.5.3 --> @@ -775,6 +814,7 @@ This function should only be used for reconnecting a socket after behavior. #### `socket.connect(options[, connectListener])` + <!-- YAML added: v0.1.90 changes: @@ -865,6 +905,7 @@ Alias to called with `{ path: path }` as `options`. #### `socket.connect(port[, host][, connectListener])` + <!-- YAML added: v0.1.90 --> @@ -882,6 +923,7 @@ Alias to called with `{port: port, host: host}` as `options`. ### `socket.connecting` + <!-- YAML added: v6.1.0 --> @@ -897,6 +939,7 @@ that the callback is a listener for the `'connect'` event. ### `socket.destroy([error])` + <!-- YAML added: v0.1.90 --> @@ -917,6 +960,7 @@ See [`writable.destroy()`][] for further details. See [`writable.destroyed`][] for further details. ### `socket.end([data[, encoding]][, callback])` + <!-- YAML added: v0.1.90 --> @@ -932,6 +976,7 @@ server will still send some data. See [`writable.end()`][] for further details. ### `socket.localAddress` + <!-- YAML added: v0.9.6 --> @@ -944,6 +989,7 @@ connects on `'192.168.1.1'`, the value of `socket.localAddress` would be `'192.168.1.1'`. ### `socket.localPort` + <!-- YAML added: v0.9.6 --> @@ -960,6 +1006,7 @@ Pauses the reading of data. That is, [`'data'`][] events will not be emitted. Useful to throttle back an upload. ### `socket.pending` + <!-- YAML added: - v11.2.0 @@ -973,6 +1020,7 @@ has not yet been called or because it is still in the process of connecting (see [`socket.connecting`][]). ### `socket.ref()` + <!-- YAML added: v0.9.1 --> @@ -980,10 +1028,11 @@ added: v0.9.1 * Returns: {net.Socket} The socket itself. Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will -*not* let the program exit if it's the only socket left (the default behavior). +_not_ let the program exit if it's the only socket left (the default behavior). If the socket is `ref`ed calling `ref` again will have no effect. ### `socket.remoteAddress` + <!-- YAML added: v0.5.10 --> @@ -995,6 +1044,7 @@ The string representation of the remote IP address. For example, the socket is destroyed (for example, if the client disconnected). ### `socket.remoteFamily` + <!-- YAML added: v0.11.14 --> @@ -1004,6 +1054,7 @@ added: v0.11.14 The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. ### `socket.remotePort` + <!-- YAML added: v0.5.10 --> @@ -1019,6 +1070,7 @@ The numeric representation of the remote port. For example, `80` or `21`. Resumes reading after a call to [`socket.pause()`][]. ### `socket.setEncoding([encoding])` + <!-- YAML added: v0.1.90 --> @@ -1030,6 +1082,7 @@ Set the encoding for the socket as a [Readable Stream][]. See [`readable.setEncoding()`][] for more information. ### `socket.setKeepAlive([enable][, initialDelay])` + <!-- YAML added: v0.1.92 changes: @@ -1053,12 +1106,14 @@ data packet received and the first keepalive probe. Setting `0` for (or previous) setting. Enabling the keep-alive functionality will set the following socket options: + * `SO_KEEPALIVE=1` * `TCP_KEEPIDLE=initialDelay` * `TCP_KEEPCNT=10` * `TCP_KEEPINTVL=1` ### `socket.setNoDelay([noDelay])` + <!-- YAML added: v0.1.90 --> @@ -1078,6 +1133,7 @@ algorithm for the socket. Passing `false` for `noDelay` will enable Nagle's algorithm. ### `socket.setTimeout(timeout[, callback])` + <!-- YAML added: v0.1.90 --> @@ -1107,6 +1163,7 @@ The optional `callback` parameter will be added as a one-time listener for the [`'timeout'`][] event. ### `socket.timeout` + <!-- YAML added: v10.7.0 --> @@ -1117,6 +1174,7 @@ The socket timeout in milliseconds as set by [`socket.setTimeout()`][]. It is `undefined` if a timeout has not been set. ### `socket.unref()` + <!-- YAML added: v0.9.1 --> @@ -1128,6 +1186,7 @@ active socket in the event system. If the socket is already `unref`ed calling `unref()` again will have no effect. ### `socket.write(data[, encoding][, callback])` + <!-- YAML added: v0.1.90 --> @@ -1151,6 +1210,7 @@ See `Writable` stream [`write()`][stream_writable_write] method for more information. ### `socket.readyState` + <!-- YAML added: v0.5.0 --> @@ -1178,6 +1238,7 @@ Possible signatures: for TCP connections. ### `net.connect(options[, connectListener])` + <!-- YAML added: v0.7.0 --> @@ -1190,6 +1251,7 @@ Alias to [`net.createConnection(options[, connectListener])`][`net.createConnection(options)`]. ### `net.connect(path[, connectListener])` + <!-- YAML added: v0.1.90 --> @@ -1202,6 +1264,7 @@ Alias to [`net.createConnection(path[, connectListener])`][`net.createConnection(path)`]. ### `net.connect(port[, host][, connectListener])` + <!-- YAML added: v0.1.90 --> @@ -1235,6 +1298,7 @@ Possible signatures: The [`net.connect()`][] function is an alias to this function. ### `net.createConnection(options[, connectListener])` + <!-- YAML added: v0.1.90 --> @@ -1284,6 +1348,7 @@ const client = net.createConnection({ path: '/tmp/echo.sock' }); ``` ### `net.createConnection(path[, connectListener])` + <!-- YAML added: v0.1.90 --> @@ -1305,6 +1370,7 @@ immediately initiates connection with then returns the `net.Socket` that starts the connection. ### `net.createConnection(port[, host][, connectListener])` + <!-- YAML added: v0.1.90 --> @@ -1313,7 +1379,7 @@ added: v0.1.90 [`socket.connect(port[, host][, connectListener])`][`socket.connect(port)`]. * `host` {string} Host the socket should connect to. Will be passed to [`socket.connect(port[, host][, connectListener])`][`socket.connect(port)`]. - **Default:** `'localhost'`. + **Default:** `'localhost'`. * `connectListener` {Function} Common parameter of the [`net.createConnection()`][] functions, an "once" listener for the `'connect'` event on the initiating socket. Will be passed to @@ -1328,6 +1394,7 @@ immediately initiates connection with then returns the `net.Socket` that starts the connection. ## `net.createServer([options][, connectionListener])` + <!-- YAML added: v0.5.0 --> @@ -1404,6 +1471,7 @@ $ nc -U /tmp/echo.sock ``` ## `net.isIP(input)` + <!-- YAML added: v0.3.0 --> @@ -1416,6 +1484,7 @@ returns `4` for IP version 4 addresses, and returns `6` for IP version 6 addresses. ## `net.isIPv4(input)` + <!-- YAML added: v0.3.0 --> @@ -1426,6 +1495,7 @@ added: v0.3.0 Returns `true` if input is a version 4 IP address, otherwise returns `false`. ## `net.isIPv6(input)` + <!-- YAML added: v0.3.0 --> @@ -1469,6 +1539,7 @@ Returns `true` if input is a version 6 IP address, otherwise returns `false`. [`server.listen(handle)`]: #serverlistenhandle-backlog-callback [`server.listen(options)`]: #serverlistenoptions-callback [`server.listen(path)`]: #serverlistenpath-backlog-callback +[`server.listen(port)`]: #serverlistenport-host-backlog-callback [`socket(7)`]: https://man7.org/linux/man-pages/man7/socket.7.html [`socket.connect()`]: #socketconnect [`socket.connect(options)`]: #socketconnectoptions-connectlistener diff --git a/doc/api/os.md b/doc/api/os.md index 990d4cce9e4..ca941bb8618 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -14,6 +14,7 @@ const os = require('os'); ``` ## `os.EOL` + <!-- YAML added: v0.7.8 --> @@ -26,6 +27,7 @@ The operating system-specific end-of-line marker. * `\r\n` on Windows ## `os.arch()` + <!-- YAML added: v0.5.0 --> @@ -39,6 +41,7 @@ compiled. Possible values are `'arm'`, `'arm64'`, `'ia32'`, `'mips'`, The return value is equivalent to [`process.arch`][]. ## `os.constants` + <!-- YAML added: v6.3.0 --> @@ -50,11 +53,12 @@ process signals, and so on. The specific constants defined are described in [OS constants](#os-constants). ## `os.cpus()` + <!-- YAML added: v0.3.3 --> -* Returns: {Object[]} +* Returns: {Object\[]} Returns an array of objects containing information about each logical CPU core. @@ -70,6 +74,7 @@ The properties included on each object include: * `irq` {number} The number of milliseconds the CPU has spent in irq mode. <!-- eslint-disable semi --> + ```js [ { @@ -123,6 +128,7 @@ The properties included on each object include: are always 0. ## `os.devNull` + <!-- YAML added: - v16.3.0 @@ -137,6 +143,7 @@ The platform-specific file path of the null device. * `/dev/null` on POSIX ## `os.endianness()` + <!-- YAML added: v0.9.4 --> @@ -149,6 +156,7 @@ binary was compiled. Possible values are `'BE'` for big endian and `'LE'` for little endian. ## `os.freemem()` + <!-- YAML added: v0.3.3 --> @@ -158,6 +166,7 @@ added: v0.3.3 Returns the amount of free system memory in bytes as an integer. ## `os.getPriority([pid])` + <!-- YAML added: v10.10.0 --> @@ -170,6 +179,7 @@ Returns the scheduling priority for the process specified by `pid`. If `pid` is not provided or is `0`, the priority of the current process is returned. ## `os.homedir()` + <!-- YAML added: v2.3.0 --> @@ -185,6 +195,7 @@ On Windows, it uses the `USERPROFILE` environment variable if defined. Otherwise it uses the path to the profile directory of the current user. ## `os.hostname()` + <!-- YAML added: v0.3.3 --> @@ -194,11 +205,12 @@ added: v0.3.3 Returns the host name of the operating system as a string. ## `os.loadavg()` + <!-- YAML added: v0.3.3 --> -* Returns: {number[]} +* Returns: {number\[]} Returns an array containing the 1, 5, and 15 minute load averages. @@ -209,6 +221,7 @@ The load average is a Unix-specific concept. On Windows, the return value is always `[0, 0, 0]`. ## `os.networkInterfaces()` + <!-- YAML added: v0.6.0 --> @@ -236,6 +249,7 @@ The properties available on the assigned network address object include: to `null`. <!-- eslint-skip --> + ```js { lo: [ @@ -280,6 +294,7 @@ The properties available on the assigned network address object include: ``` ## `os.platform()` + <!-- YAML added: v0.5.0 --> @@ -296,6 +311,7 @@ The value `'android'` may also be returned if Node.js is built on the Android operating system. [Android support is experimental][Android building]. ## `os.release()` + <!-- YAML added: v0.3.3 --> @@ -309,6 +325,7 @@ On POSIX systems, the operating system release is determined by calling <https://en.wikipedia.org/wiki/Uname#Examples> for more information. ## `os.setPriority([pid, ]priority)` + <!-- YAML added: v10.10.0 --> @@ -332,6 +349,7 @@ privileges. Otherwise the set priority will be silently reduced to `PRIORITY_HIGH`. ## `os.tmpdir()` + <!-- YAML added: v0.9.9 changes: @@ -347,6 +365,7 @@ Returns the operating system's default directory for temporary files as a string. ## `os.totalmem()` + <!-- YAML added: v0.3.3 --> @@ -356,6 +375,7 @@ added: v0.3.3 Returns the total amount of system memory in bytes as an integer. ## `os.type()` + <!-- YAML added: v0.3.3 --> @@ -369,6 +389,7 @@ See <https://en.wikipedia.org/wiki/Uname#Examples> for additional information about the output of running [`uname(3)`][] on various operating systems. ## `os.uptime()` + <!-- YAML added: v0.3.3 changes: @@ -383,6 +404,7 @@ changes: Returns the system uptime in number of seconds. ## `os.userInfo([options])` + <!-- YAML added: v6.0.0 --> @@ -406,6 +428,7 @@ operating system response. Throws a [`SystemError`][] if a user has no `username` or `homedir`. ## `os.version()` + <!-- YAML added: - v13.11.0 @@ -428,6 +451,7 @@ The following constants are exported by `os.constants`. Not all constants will be available on every operating system. ### Signal constants + <!-- YAML changes: - version: v5.11.0 @@ -1217,6 +1241,7 @@ information. </table> ### Priority constants + <!-- YAML added: v10.10.0 --> diff --git a/doc/api/packages.md b/doc/api/packages.md index a04e18421b8..94b4a1e1057 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -140,6 +140,7 @@ package: `"commonjs"` package). ### `--input-type` flag + <!-- YAML added: v12.0.0 --> @@ -275,6 +276,7 @@ absolute subpath of the package such as `require('/path/to/node_modules/pkg/subpath.js')` will still load `subpath.js`. ### Subpath exports + <!-- YAML added: v12.7.0 --> @@ -308,6 +310,7 @@ import submodule from 'es-module-package/private-module.js'; ``` ### Subpath imports + <!-- YAML added: - v14.6.0 @@ -350,6 +353,7 @@ The resolution rules for the imports field are otherwise analogous to the exports field. ### Subpath patterns + <!-- YAML added: - v14.13.0 @@ -423,6 +427,7 @@ import featureX from 'es-module-package/features/x'; ``` ### Exports sugar + <!-- YAML added: v12.11.0 --> @@ -450,6 +455,7 @@ can be written: ``` ### Conditional exports + <!-- YAML added: - v13.2.0 @@ -483,25 +489,25 @@ For example, a package that wants to provide different ES module exports for Node.js implements the following conditions: * `"import"` - matches when the package is loaded via `import` or - `import()`, or via any top-level import or resolve operation by the - ECMAScript module loader. Applies regardless of the module format of the - target file. _Always mutually exclusive with `"require"`._ + `import()`, or via any top-level import or resolve operation by the + ECMAScript module loader. Applies regardless of the module format of the + target file. _Always mutually exclusive with `"require"`._ * `"require"` - matches when the package is loaded via `require()`. The - referenced file should be loadable with `require()` although the condition - matches regardless of the module format of the target file. Expected - formats include CommonJS, JSON, and native addons but not ES modules as - `require()` doesn't support them. _Always mutually exclusive with - `"import"`._ + referenced file should be loadable with `require()` although the condition + matches regardless of the module format of the target file. Expected + formats include CommonJS, JSON, and native addons but not ES modules as + `require()` doesn't support them. _Always mutually exclusive with + `"import"`._ * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES - module file. _This condition should always come after `"import"` or - `"require"`._ + module file. _This condition should always come after `"import"` or + `"require"`._ * `"node-addons"` - similar to `"node"` and matches for any Node.js environment. - This condition can be used to provide an entry point which uses native C++ - addons as opposed to an entry point which is more universal and doesn't rely - on native addons. This condition can be disabled via the - [`--no-addons` flag][]. + This condition can be used to provide an entry point which uses native C++ + addons as opposed to an entry point which is more universal and doesn't rely + on native addons. This condition can be disabled via the + [`--no-addons` flag][]. * `"default"` - the generic fallback that always matches. Can be a CommonJS - or ES module file. _This condition should always come last._ + or ES module file. _This condition should always come last._ Within the [`"exports"`][] object, key order is significant. During condition matching, earlier entries have higher priority and take precedence over later @@ -564,6 +570,7 @@ the remaining conditions of the parent condition. In this way nested conditions behave analogously to nested JavaScript `if` statements. ### Resolving user conditions + <!-- YAML added: - v14.9.0 @@ -603,12 +610,12 @@ These user conditions can be enabled in Node.js via the [`--conditions` flag][]. The following condition definitions are currently endorsed by Node.js: * `"browser"` - any environment which implements a standard subset of global - browser APIs available from JavaScript in web browsers, including the DOM - APIs. + browser APIs available from JavaScript in web browsers, including the DOM + APIs. * `"development"` - can be used to define a development-only environment - entry point. _Must always be mutually exclusive with `"production"`._ + entry point. _Must always be mutually exclusive with `"production"`._ * `"production"` - can be used to define a production environment entry - point. _Must always be mutually exclusive with `"development"`._ + point. _Must always be mutually exclusive with `"development"`._ The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. @@ -635,6 +642,7 @@ The above definitions may be moved to a dedicated conditions registry in due course. ### Self-referencing a package using its name + <!-- YAML added: - v13.1.0 @@ -779,16 +787,16 @@ Every pattern has tradeoffs, but there are two broad approaches that satisfy the following conditions: 1. The package is usable via both `require` and `import`. -1. The package is usable in both current Node.js and older versions of Node.js +2. The package is usable in both current Node.js and older versions of Node.js that lack support for ES modules. -1. The package main entry point, e.g. `'pkg'` can be used by both `require` to +3. The package main entry point, e.g. `'pkg'` can be used by both `require` to resolve to a CommonJS file and by `import` to resolve to an ES module file. (And likewise for exported paths, e.g. `'pkg/feature'`.) -1. The package provides named exports, e.g. `import { name } from 'pkg'` rather +4. The package provides named exports, e.g. `import { name } from 'pkg'` rather than `import pkg from 'pkg'; pkg.name`. -1. The package is potentially usable in other ES module environments such as +5. The package is potentially usable in other ES module environments such as browsers. -1. The hazards described in the previous section are avoided or minimized. +6. The hazards described in the previous section are avoided or minimized. #### Approach #1: Use an ES module wrapper @@ -844,6 +852,7 @@ export default cjsModule; ``` This approach is appropriate for any of the following use cases: + * The package is currently written in CommonJS and the author would prefer not to refactor it into ES module syntax, but wishes to provide named exports for ES module consumers. @@ -914,33 +923,33 @@ CommonJS and ES module instances of the package: `Date`, for example, needs to be instantiated to contain state; if it were a package, it would be used like this: - ```js - import Date from 'date'; - const someDate = new Date(); - // someDate contains state; Date does not - ``` + ```js + import Date from 'date'; + const someDate = new Date(); + // someDate contains state; Date does not + ``` The `new` keyword isn’t required; a package’s function can return a new object, or modify a passed-in object, to keep the state external to the package. -1. Isolate the state in one or more CommonJS files that are shared between the +2. Isolate the state in one or more CommonJS files that are shared between the CommonJS and ES module versions of the package. For example, if the CommonJS and ES module entry points are `index.cjs` and `index.mjs`, respectively: - ```cjs - // ./node_modules/pkg/index.cjs - const state = require('./state.cjs'); - module.exports.state = state; - ``` + ```cjs + // ./node_modules/pkg/index.cjs + const state = require('./state.cjs'); + module.exports.state = state; + ``` - ```js - // ./node_modules/pkg/index.mjs - import state from './state.cjs'; - export { - state - }; - ``` + ```js + // ./node_modules/pkg/index.mjs + import state from './state.cjs'; + export { + state + }; + ``` Even if `pkg` is used via both `require` and `import` in an application (for example, via `import` in application code and via `require` by a dependency) @@ -951,6 +960,7 @@ Any plugins that attach to the package’s singleton would need to separately attach to both the CommonJS and ES module singletons. This approach is appropriate for any of the following use cases: + * The package is currently written in ES module syntax and the package author wants that version to be used wherever such syntax is supported. * The package is stateless or its state can be isolated without too much @@ -1000,6 +1010,7 @@ The following fields in `package.json` files are used in Node.js: itself. ### `"name"` + <!-- YAML added: - v13.1.0 @@ -1028,6 +1039,7 @@ The `"name"` field can be used in addition to the [`"exports"`][] field to [self-reference][] a package using its name. ### `"main"` + <!-- YAML added: v0.4.0 --> @@ -1052,6 +1064,7 @@ When a package has an [`"exports"`][] field, this will take precedence over the `"main"` field when importing the package by name. ### `"packageManager"` + <!-- YAML added: v16.9.0 --> @@ -1076,6 +1089,7 @@ This field is currently experimental and needs to be opted-in; check the [Corepack][] page for details about the procedure. ### `"type"` + <!-- YAML added: v12.0.0 changes: @@ -1097,7 +1111,7 @@ Files ending with `.js` are loaded as ES modules when the nearest parent The nearest parent `package.json` is defined as the first `package.json` found when searching in the current folder, that folder’s parent, and so on up -until a node_modules folder or the volume root is reached. +until a node\_modules folder or the volume root is reached. ```json // package.json @@ -1128,6 +1142,7 @@ Regardless of the value of the `"type"` field, `.mjs` files are always treated as ES modules and `.cjs` files are always treated as CommonJS. ### `"exports"` + <!-- YAML added: v12.7.0 changes: @@ -1153,7 +1168,7 @@ changes: description: Implement conditional exports. --> -* Type: {Object} | {string} | {string[]} +* Type: {Object} | {string} | {string\[]} ```json { @@ -1175,6 +1190,7 @@ All paths defined in the `"exports"` must be relative file URLs starting with `./`. ### `"imports"` + <!-- YAML added: - v14.6.0 diff --git a/doc/api/path.md b/doc/api/path.md index 8dc3f4558a2..cc2bb4d1a8a 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -63,6 +63,7 @@ example, `path.resolve('C:\\')` can potentially return a different result than [this MSDN page][MSDN-Rel-Path]. ## `path.basename(path[, ext])` + <!-- YAML added: v0.1.25 changes: @@ -104,6 +105,7 @@ A [`TypeError`][] is thrown if `path` is not a string or if `ext` is given and is not a string. ## `path.delimiter` + <!-- YAML added: v0.9.3 --> @@ -136,6 +138,7 @@ process.env.PATH.split(path.delimiter); ``` ## `path.dirname(path)` + <!-- YAML added: v0.1.16 changes: @@ -159,6 +162,7 @@ path.dirname('/foo/bar/baz/asdf/quux'); A [`TypeError`][] is thrown if `path` is not a string. ## `path.extname(path)` + <!-- YAML added: v0.1.25 changes: @@ -199,6 +203,7 @@ path.extname('.index.md'); A [`TypeError`][] is thrown if `path` is not a string. ## `path.format(pathObject)` + <!-- YAML added: v0.11.15 --> @@ -263,6 +268,7 @@ path.format({ ``` ## `path.isAbsolute(path)` + <!-- YAML added: v0.11.2 --> @@ -298,6 +304,7 @@ path.isAbsolute('.'); // false A [`TypeError`][] is thrown if `path` is not a string. ## `path.join([...paths])` + <!-- YAML added: v0.1.16 --> @@ -323,6 +330,7 @@ path.join('foo', {}, 'bar'); A [`TypeError`][] is thrown if any of the path segments is not a string. ## `path.normalize(path)` + <!-- YAML added: v0.1.23 --> @@ -366,6 +374,7 @@ path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar'); A [`TypeError`][] is thrown if `path` is not a string. ## `path.parse(path)` + <!-- YAML added: v0.11.15 --> @@ -432,6 +441,7 @@ path.parse('C:\\path\\dir\\file.txt'); A [`TypeError`][] is thrown if `path` is not a string. ## `path.posix` + <!-- YAML added: v0.11.15 changes: @@ -448,6 +458,7 @@ of the `path` methods. The API is accessible via `require('path').posix` or `require('path/posix')`. ## `path.relative(from, to)` + <!-- YAML added: v0.5.0 changes: @@ -485,6 +496,7 @@ path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb'); A [`TypeError`][] is thrown if either `from` or `to` is not a string. ## `path.resolve([...paths])` + <!-- YAML added: v0.3.4 --> @@ -527,6 +539,7 @@ path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif'); A [`TypeError`][] is thrown if any of the arguments is not a string. ## `path.sep` + <!-- YAML added: v0.7.9 --> @@ -557,6 +570,7 @@ as path segment separators; however, the `path` methods only add backward slashes (`\`). ## `path.toNamespacedPath(path)` + <!-- YAML added: v9.0.0 --> @@ -572,6 +586,7 @@ This method is meaningful only on Windows systems. On POSIX systems, the method is non-operational and always returns `path` without modifications. ## `path.win32` + <!-- YAML added: v0.11.15 changes: diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 553cf3dc799..34d2a58bd01 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -36,6 +36,7 @@ doSomeLongRunningProcess(() => { ``` ## `perf_hooks.performance` + <!-- YAML added: v8.5.0 --> @@ -44,6 +45,7 @@ An object that can be used to collect performance metrics from the current Node.js instance. It is similar to [`window.performance`][] in browsers. ### `performance.clearMarks([name])` + <!-- YAML added: v8.5.0 --> @@ -54,6 +56,7 @@ If `name` is not provided, removes all `PerformanceMark` objects from the Performance Timeline. If `name` is provided, removes only the named mark. ### `performance.eventLoopUtilization([utilization1[, utilization2]])` + <!-- YAML added: - v14.10.0 @@ -61,9 +64,9 @@ added: --> * `utilization1` {Object} The result of a previous call to - `eventLoopUtilization()`. + `eventLoopUtilization()`. * `utilization2` {Object} The result of a previous call to - `eventLoopUtilization()` prior to `utilization1`. + `eventLoopUtilization()` prior to `utilization1`. * Returns {Object} * `idle` {number} * `active` {number} @@ -116,6 +119,7 @@ Passing in a user-defined object instead of the result of a previous call to are not guaranteed to reflect any correct state of the event loop. ### `performance.mark([name[, options]])` + <!-- YAML added: v8.5.0 changes: @@ -137,6 +141,7 @@ Creates a new `PerformanceMark` entry in the Performance Timeline. A to mark specific significant moments in the Performance Timeline. ### `performance.measure(name[, startMarkOrOptions[, endMark]])` + <!-- YAML added: v8.5.0 changes: @@ -167,18 +172,19 @@ Creates a new `PerformanceMeasure` entry in the Performance Timeline. A `performanceEntry.duration` measures the number of milliseconds elapsed since `startMark` and `endMark`. -The `startMark` argument may identify any *existing* `PerformanceMark` in the -Performance Timeline, or *may* identify any of the timestamp properties +The `startMark` argument may identify any _existing_ `PerformanceMark` in the +Performance Timeline, or _may_ identify any of the timestamp properties provided by the `PerformanceNodeTiming` class. If the named `startMark` does not exist, an error is thrown. -The optional `endMark` argument must identify any *existing* `PerformanceMark` +The optional `endMark` argument must identify any _existing_ `PerformanceMark` in the Performance Timeline or any of the timestamp properties provided by the `PerformanceNodeTiming` class. `endMark` will be `performance.now()` if no parameter is passed, otherwise if the named `endMark` does not exist, an error will be thrown. ### `performance.nodeTiming` + <!-- YAML added: v8.5.0 --> @@ -191,6 +197,7 @@ An instance of the `PerformanceNodeTiming` class that provides performance metrics for specific Node.js operational milestones. ### `performance.now()` + <!-- YAML added: v8.5.0 --> @@ -201,6 +208,7 @@ Returns the current high resolution millisecond timestamp, where 0 represents the start of the current `node` process. ### `performance.timeOrigin` + <!-- YAML added: v8.5.0 --> @@ -211,6 +219,7 @@ The [`timeOrigin`][] specifies the high resolution millisecond timestamp at which the current `node` process began, measured in Unix time. ### `performance.timerify(fn[, options])` + <!-- YAML added: v8.5.0 changes: @@ -262,6 +271,7 @@ to the promise and the duration will be reported once the finally handler is invoked. ### `performance.toJSON()` + <!-- YAML added: v16.1.0 --> @@ -270,11 +280,13 @@ An object which is JSON representation of the `performance` object. It is similar to [`window.performance.toJSON`][] in browsers. ## Class: `PerformanceEntry` + <!-- YAML added: v8.5.0 --> ### `performanceEntry.detail` + <!-- YAML added: v16.0.0 --> @@ -284,6 +296,7 @@ added: v16.0.0 Additional detail specific to the `entryType`. ### `performanceEntry.duration` + <!-- YAML added: v8.5.0 --> @@ -294,6 +307,7 @@ The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types. ### `performanceEntry.entryType` + <!-- YAML added: v8.5.0 --> @@ -311,6 +325,7 @@ The type of the performance entry. It may be one of: * `'http'` (Node.js only) ### `performanceEntry.flags` + <!-- YAML added: - v13.9.0 @@ -339,6 +354,7 @@ The value may be one of: * `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE` ### `performanceEntry.name` + <!-- YAML added: v8.5.0 --> @@ -348,6 +364,7 @@ added: v8.5.0 The name of the performance entry. ### `performanceEntry.kind` + <!-- YAML added: v8.5.0 changes: @@ -371,6 +388,7 @@ The value may be one of: * `perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB` ### `performanceEntry.startTime` + <!-- YAML added: v8.5.0 --> @@ -447,6 +465,7 @@ When `performanceEntry.type` is equal to `'function'`, the the input arguments to the timed function. ## Class: `PerformanceNodeTiming` + <!-- YAML added: v8.5.0 --> @@ -459,6 +478,7 @@ Provides timing details for Node.js itself. The constructor of this class is not exposed to users. ### `performanceNodeTiming.bootstrapComplete` + <!-- YAML added: v8.5.0 --> @@ -470,6 +490,7 @@ completed bootstrapping. If bootstrapping has not yet finished, the property has the value of -1. ### `performanceNodeTiming.environment` + <!-- YAML added: v8.5.0 --> @@ -480,6 +501,7 @@ The high resolution millisecond timestamp at which the Node.js environment was initialized. ### `performanceNodeTiming.idleTime` + <!-- YAML added: - v14.10.0 @@ -495,6 +517,7 @@ started (e.g., in the first tick of the main script), the property has the value of 0. ### `performanceNodeTiming.loopExit` + <!-- YAML added: v8.5.0 --> @@ -506,6 +529,7 @@ exited. If the event loop has not yet exited, the property has the value of -1. It can only have a value of not -1 in a handler of the [`'exit'`][] event. ### `performanceNodeTiming.loopStart` + <!-- YAML added: v8.5.0 --> @@ -517,6 +541,7 @@ started. If the event loop has not yet started (e.g., in the first tick of the main script), the property has the value of -1. ### `performanceNodeTiming.nodeStart` + <!-- YAML added: v8.5.0 --> @@ -527,6 +552,7 @@ The high resolution millisecond timestamp at which the Node.js process was initialized. ### `performanceNodeTiming.v8Start` + <!-- YAML added: v8.5.0 --> @@ -539,6 +565,7 @@ initialized. ## Class: `perf_hooks.PerformanceObserver` ### `new PerformanceObserver(callback)` + <!-- YAML added: v8.5.0 --> @@ -576,12 +603,15 @@ notified about new `PerformanceEntry` instances. The callback receives a `PerformanceObserver`. ### `performanceObserver.disconnect()` + <!-- YAML added: v8.5.0 --> + Disconnects the `PerformanceObserver` instance from all notifications. ### `performanceObserver.observe(options)` + <!-- YAML added: v8.5.0 changes: @@ -598,7 +628,7 @@ changes: * `options` {Object} * `type` {string} A single {PerformanceEntry} type. Must not be given if `entryTypes` is already specified. - * `entryTypes` {string[]} An array of strings identifying the types of + * `entryTypes` {string\[]} An array of strings identifying the types of {PerformanceEntry} instances the observer is interested in. If not provided an error will be thrown. * `buffered` {boolean} If true, the observer callback is called with a @@ -626,6 +656,7 @@ for (let n = 0; n < 3; n++) ``` ## Class: `PerformanceObserverEntryList` + <!-- YAML added: v8.5.0 --> @@ -635,11 +666,12 @@ The `PerformanceObserverEntryList` class is used to provide access to the The constructor of this class is not exposed to users. ### `performanceObserverEntryList.getEntries()` + <!-- YAML added: v8.5.0 --> -* Returns: {PerformanceEntry[]} +* Returns: {PerformanceEntry\[]} Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime`. @@ -677,13 +709,14 @@ performance.mark('meow'); ``` ### `performanceObserverEntryList.getEntriesByName(name[, type])` + <!-- YAML added: v8.5.0 --> * `name` {string} * `type` {string} -* Returns: {PerformanceEntry[]} +* Returns: {PerformanceEntry\[]} Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime` whose `performanceEntry.name` is @@ -731,12 +764,13 @@ performance.mark('meow'); ``` ### `performanceObserverEntryList.getEntriesByType(type)` + <!-- YAML added: v8.5.0 --> * `type` {string} -* Returns: {PerformanceEntry[]} +* Returns: {PerformanceEntry\[]} Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime` whose `performanceEntry.entryType` @@ -775,6 +809,7 @@ performance.mark('meow'); ``` ## `perf_hooks.createHistogram([options])` + <!-- YAML added: - v15.9.0 @@ -793,6 +828,7 @@ added: Returns a {RecordableHistogram}. ## `perf_hooks.monitorEventLoopDelay([options])` + <!-- YAML added: v11.10.0 --> @@ -829,11 +865,13 @@ console.log(h.percentile(99)); ``` ## Class: `Histogram` + <!-- YAML added: v11.10.0 --> ### `histogram.exceeds` + <!-- YAML added: v11.10.0 --> @@ -844,6 +882,7 @@ The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold. ### `histogram.max` + <!-- YAML added: v11.10.0 --> @@ -853,6 +892,7 @@ added: v11.10.0 The maximum recorded event loop delay. ### `histogram.mean` + <!-- YAML added: v11.10.0 --> @@ -862,6 +902,7 @@ added: v11.10.0 The mean of the recorded event loop delays. ### `histogram.min` + <!-- YAML added: v11.10.0 --> @@ -871,6 +912,7 @@ added: v11.10.0 The minimum recorded event loop delay. ### `histogram.percentile(percentile)` + <!-- YAML added: v11.10.0 --> @@ -881,6 +923,7 @@ added: v11.10.0 Returns the value at the given percentile. ### `histogram.percentiles` + <!-- YAML added: v11.10.0 --> @@ -890,6 +933,7 @@ added: v11.10.0 Returns a `Map` object detailing the accumulated percentile distribution. ### `histogram.reset()` + <!-- YAML added: v11.10.0 --> @@ -897,6 +941,7 @@ added: v11.10.0 Resets the collected histogram data. ### `histogram.stddev` + <!-- YAML added: v11.10.0 --> @@ -910,6 +955,7 @@ The standard deviation of the recorded event loop delays. A `Histogram` that is periodically updated on a given interval. ### `histogram.disable()` + <!-- YAML added: v11.10.0 --> @@ -920,6 +966,7 @@ Disables the update interval timer. Returns `true` if the timer was stopped, `false` if it was already stopped. ### `histogram.enable()` + <!-- YAML added: v11.10.0 --> @@ -936,6 +983,7 @@ end, the histogram is cloned as a plain {Histogram} object that does not implement the `enable()` and `disable()` methods. ## Class: `RecordableHistogram extends Histogram` + <!-- YAML added: - v15.9.0 @@ -943,6 +991,7 @@ added: --> ### `histogram.record(val)` + <!-- YAML added: - v15.9.0 @@ -952,6 +1001,7 @@ added: * `val` {number|bigint} The amount to record in the histogram. ### `histogram.recordDelta()` + <!-- YAML added: - v15.9.0 @@ -1013,6 +1063,7 @@ The following example measures the duration of `require()` operations to load dependencies: <!-- eslint-disable no-global-assign --> + ```js 'use strict'; const { diff --git a/doc/api/process.md b/doc/api/process.md index 91b23a3f31d..12b4c9a6d6b 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -23,6 +23,7 @@ const process = require('process'); The `process` object is an instance of [`EventEmitter`][]. ### Event: `'beforeExit'` + <!-- YAML added: v0.11.12 --> @@ -36,10 +37,10 @@ continue. The listener callback function is invoked with the value of [`process.exitCode`][] passed as the only argument. -The `'beforeExit'` event is *not* emitted for conditions causing explicit +The `'beforeExit'` event is _not_ emitted for conditions causing explicit termination, such as calling [`process.exit()`][] or uncaught exceptions. -The `'beforeExit'` should *not* be used as an alternative to the `'exit'` event +The `'beforeExit'` should _not_ be used as an alternative to the `'exit'` event unless the intention is to schedule additional work. ```mjs @@ -81,6 +82,7 @@ console.log('This message is displayed first.'); ``` ### Event: `'disconnect'` + <!-- YAML added: v0.7.7 --> @@ -90,6 +92,7 @@ and [Cluster][] documentation), the `'disconnect'` event will be emitted when the IPC channel is closed. ### Event: `'exit'` + <!-- YAML added: v0.1.7 --> @@ -151,6 +154,7 @@ process.on('exit', (code) => { ``` ### Event: `'message'` + <!-- YAML added: v0.5.10 --> @@ -174,6 +178,7 @@ to represent. See [Advanced serialization for `child_process`][] for more details. ### Event: `'multipleResolves'` + <!-- YAML added: v10.12.0 --> @@ -254,6 +259,7 @@ main().then(console.log); ``` ### Event: `'rejectionHandled'` + <!-- YAML added: v1.4.1 --> @@ -315,6 +321,7 @@ likely best for long-running application) or upon process exit (which is likely most convenient for scripts). ### Event: `'uncaughtException'` + <!-- YAML added: v0.1.18 changes: @@ -389,7 +396,7 @@ default behavior to exit the process by installing a #### Warning: Using `'uncaughtException'` correctly `'uncaughtException'` is a crude mechanism for exception handling -intended to be used only as a last resort. The event *should not* be used as +intended to be used only as a last resort. The event _should not_ be used as an equivalent to `On Error Resume Next`. Unhandled exceptions inherently mean that an application is in an undefined state. Attempting to resume application code without properly recovering from the exception can cause additional @@ -414,6 +421,7 @@ in a separate process to detect application failures and recover or restart as needed. ### Event: `'uncaughtExceptionMonitor'` + <!-- YAML added: - v13.7.0 @@ -460,6 +468,7 @@ nonexistentFunc(); ``` ### Event: `'unhandledRejection'` + <!-- YAML added: v1.4.1 changes: @@ -545,6 +554,7 @@ address such failures, a non-operational being emitted. ### Event: `'warning'` + <!-- YAML added: v6.0.0 --> @@ -627,6 +637,7 @@ The `*-deprecation` command-line flags only affect warnings that use the name `'DeprecationWarning'`. ### Event: `'worker'` + <!-- YAML added: - v16.2.0 @@ -678,7 +689,7 @@ refer to signal(7) for a listing of standard POSIX signal names such as Signals are not available on [`Worker`][] threads. The signal handler will receive the signal's name (`'SIGINT'`, - `'SIGTERM'`, etc.) as the first argument. +`'SIGTERM'`, etc.) as the first argument. The name of each event will be the uppercase common name for the signal (e.g. `'SIGINT'` for `SIGINT` signals). @@ -737,8 +748,8 @@ process.on('SIGTERM', handle); * `'SIGTERM'` is not supported on Windows, it can be listened on. * `'SIGINT'` from the terminal is supported on all platforms, and can usually be generated with <kbd>Ctrl</kbd>+<kbd>C</kbd> (though this may be configurable). - It is not generated when [terminal raw mode][] is enabled and - <kbd>Ctrl</kbd>+<kbd>C</kbd> is used. + It is not generated when [terminal raw mode][] is enabled + and <kbd>Ctrl</kbd>+<kbd>C</kbd> is used. * `'SIGBREAK'` is delivered on Windows when <kbd>Ctrl</kbd>+<kbd>Break</kbd> is pressed. On non-Windows platforms, it can be listened on, but there is no way to send or generate it. @@ -749,15 +760,16 @@ process.on('SIGTERM', handle); terminate Node.js on all platforms. * `'SIGSTOP'` cannot have a listener installed. * `'SIGBUS'`, `'SIGFPE'`, `'SIGSEGV'` and `'SIGILL'`, when not raised - artificially using kill(2), inherently leave the process in a state from - which it is not safe to call JS listeners. Doing so might cause the process - to stop responding. + artificially using kill(2), inherently leave the process in a state from + which it is not safe to call JS listeners. Doing so might cause the process + to stop responding. * `0` can be sent to test for the existence of a process, it has no effect if - the process exists, but will throw an error if the process does not exist. + the process exists, but will throw an error if the process does not exist. Windows does not support signals so has no equivalent to termination by signal, but Node.js offers some emulation with [`process.kill()`][], and [`subprocess.kill()`][]: + * Sending `SIGINT`, `SIGTERM`, and `SIGKILL` will cause the unconditional termination of the target process, and afterwards, subprocess will report that the process was terminated by signal. @@ -765,6 +777,7 @@ but Node.js offers some emulation with [`process.kill()`][], and existence of a process. ## `process.abort()` + <!-- YAML added: v0.7.0 --> @@ -775,6 +788,7 @@ generate a core file. This feature is not available in [`Worker`][] threads. ## `process.allowedNodeEnvironmentFlags` + <!-- YAML added: v10.10.0 --> @@ -793,16 +807,16 @@ return `true` in the following cases: * Flags may omit leading single (`-`) or double (`--`) dashes; e.g., `inspect-brk` for `--inspect-brk`, or `r` for `-r`. * Flags passed through to V8 (as listed in `--v8-options`) may replace - one or more *non-leading* dashes for an underscore, or vice-versa; + one or more _non-leading_ dashes for an underscore, or vice-versa; e.g., `--perf_basic_prof`, `--perf-basic-prof`, `--perf_basic-prof`, etc. * Flags may contain one or more equals (`=`) characters; all characters after and including the first equals will be ignored; e.g., `--stack-trace-limit=100`. -* Flags *must* be allowable within [`NODE_OPTIONS`][]. +* Flags _must_ be allowable within [`NODE_OPTIONS`][]. When iterating over `process.allowedNodeEnvironmentFlags`, flags will -appear only *once*; each will begin with one or more dashes. Flags +appear only _once_; each will begin with one or more dashes. Flags passed through to V8 will contain underscores instead of non-leading dashes: @@ -832,11 +846,12 @@ The methods `add()`, `clear()`, and `delete()` of `process.allowedNodeEnvironmentFlags` do nothing, and will fail silently. -If Node.js was compiled *without* [`NODE_OPTIONS`][] support (shown in +If Node.js was compiled _without_ [`NODE_OPTIONS`][] support (shown in [`process.config`][]), `process.allowedNodeEnvironmentFlags` will -contain what *would have* been allowable. +contain what _would have_ been allowable. ## `process.arch` + <!-- YAML added: v0.5.0 --> @@ -860,11 +875,12 @@ console.log(`This processor architecture is ${process.arch}`); ``` ## `process.argv` + <!-- YAML added: v0.1.27 --> -* {string[]} +* {string\[]} The `process.argv` property returns an array containing the command-line arguments passed when the Node.js process was launched. The first element will @@ -910,6 +926,7 @@ Would generate the output: ``` ## `process.argv0` + <!-- YAML added: v6.4.0 --> @@ -928,6 +945,7 @@ $ bash -c 'exec -a customArgv0 ./node' ``` ## `process.channel` + <!-- YAML added: v7.1.0 changes: @@ -944,6 +962,7 @@ property is a reference to the IPC channel. If no IPC channel exists, this property is `undefined`. ### `process.channel.ref()` + <!-- YAML added: v7.1.0 --> @@ -956,6 +975,7 @@ listeners on the `process` object. However, this method can be used to explicitly request a specific behavior. ### `process.channel.unref()` + <!-- YAML added: v7.1.0 --> @@ -968,6 +988,7 @@ listeners on the `process` object. However, this method can be used to explicitly request a specific behavior. ## `process.chdir(directory)` + <!-- YAML added: v0.1.17 --> @@ -1005,6 +1026,7 @@ try { This feature is not available in [`Worker`][] threads. ## `process.config` + <!-- YAML added: v0.7.7 changes: @@ -1023,6 +1045,7 @@ running the `./configure` script. An example of the possible output looks like: <!-- eslint-skip --> + ```js { target_defaults: @@ -1060,6 +1083,7 @@ Modifying the `process.config` property, or any child-property of the read-only in a future release. ## `process.connected` + <!-- YAML added: v0.7.2 --> @@ -1075,6 +1099,7 @@ Once `process.connected` is `false`, it is no longer possible to send messages over the IPC channel using `process.send()`. ## `process.cpuUsage([previousValue])` + <!-- YAML added: v6.1.0 --> @@ -1123,6 +1148,7 @@ console.log(cpuUsage(startUsage)); ``` ## `process.cwd()` + <!-- YAML added: v0.1.8 --> @@ -1145,6 +1171,7 @@ console.log(`Current directory: ${cwd()}`); ``` ## `process.debugPort` + <!-- YAML added: v0.7.2 --> @@ -1166,6 +1193,7 @@ process.debugPort = 5858; ``` ## `process.disconnect()` + <!-- YAML added: v0.7.2 --> @@ -1182,6 +1210,7 @@ If the Node.js process was not spawned with an IPC channel, `process.disconnect()` will be `undefined`. ## `process.dlopen(module, filename[, flags])` + <!-- YAML added: v0.1.16 changes: @@ -1234,6 +1263,7 @@ module.exports.foo(); ``` ## `process.emitWarning(warning[, options])` + <!-- YAML added: v8.0.0 --> @@ -1241,7 +1271,7 @@ added: v8.0.0 * `warning` {string|Error} The warning to emit. * `options` {Object} * `type` {string} When `warning` is a `String`, `type` is the name to use - for the *type* of warning being emitted. **Default:** `'Warning'`. + for the _type_ of warning being emitted. **Default:** `'Warning'`. * `code` {string} A unique identifier for the warning instance being emitted. * `ctor` {Function} When `warning` is a `String`, `ctor` is an optional function used to limit the generated stack trace. **Default:** @@ -1309,13 +1339,14 @@ process.on('warning', (warning) => { If `warning` is passed as an `Error` object, the `options` argument is ignored. ## `process.emitWarning(warning[, type[, code]][, ctor])` + <!-- YAML added: v6.0.0 --> * `warning` {string|Error} The warning to emit. * `type` {string} When `warning` is a `String`, `type` is the name to use - for the *type* of warning being emitted. **Default:** `'Warning'`. + for the _type_ of warning being emitted. **Default:** `'Warning'`. * `code` {string} A unique identifier for the warning instance being emitted. * `ctor` {Function} When `warning` is a `String`, `ctor` is an optional function used to limit the generated stack trace. **Default:** @@ -1480,6 +1511,7 @@ emitMyWarning(); ``` ## `process.env` + <!-- YAML added: v0.1.27 changes: @@ -1501,6 +1533,7 @@ See environ(7). An example of this object looks like: <!-- eslint-skip --> + ```js { TERM: 'xterm-256color', @@ -1613,11 +1646,12 @@ across [`Worker`][] threads, and only the main thread can make changes that are visible to the operating system or to native add-ons. ## `process.execArgv` + <!-- YAML added: v0.7.7 --> -* {string[]} +* {string\[]} The `process.execArgv` property returns the set of Node.js-specific command-line options passed when the Node.js process was launched. These options do not @@ -1633,6 +1667,7 @@ $ node --harmony script.js --version Results in `process.execArgv`: <!-- eslint-disable semi --> + ```js ['--harmony'] ``` @@ -1640,6 +1675,7 @@ Results in `process.execArgv`: And `process.argv`: <!-- eslint-disable semi --> + ```js ['/usr/local/bin/node', 'script.js', '--version'] ``` @@ -1648,6 +1684,7 @@ Refer to [`Worker` constructor][] for the detailed behavior of worker threads with this property. ## `process.execPath` + <!-- YAML added: v0.1.100 --> @@ -1658,11 +1695,13 @@ The `process.execPath` property returns the absolute pathname of the executable that started the Node.js process. Symbolic links, if any, are resolved. <!-- eslint-disable semi --> + ```js '/usr/local/bin/node' ``` ## `process.exit([code])` + <!-- YAML added: v0.1.13 --> @@ -1697,11 +1736,11 @@ completed fully, including I/O operations to `process.stdout` and `process.stderr`. In most situations, it is not actually necessary to call `process.exit()` -explicitly. The Node.js process will exit on its own *if there is no additional -work pending* in the event loop. The `process.exitCode` property can be set to +explicitly. The Node.js process will exit on its own _if there is no additional +work pending_ in the event loop. The `process.exitCode` property can be set to tell the process which exit code to use when the process exits gracefully. -For instance, the following example illustrates a *misuse* of the +For instance, the following example illustrates a _misuse_ of the `process.exit()` method that could lead to data printed to stdout being truncated and lost: @@ -1726,11 +1765,11 @@ if (someConditionNotMet()) { ``` The reason this is problematic is because writes to `process.stdout` in Node.js -are sometimes *asynchronous* and may occur over multiple ticks of the Node.js +are sometimes _asynchronous_ and may occur over multiple ticks of the Node.js event loop. Calling `process.exit()`, however, forces the process to exit -*before* those additional writes to `stdout` can be performed. +_before_ those additional writes to `stdout` can be performed. -Rather than calling `process.exit()` directly, the code *should* set the +Rather than calling `process.exit()` directly, the code _should_ set the `process.exitCode` and allow the process to exit naturally by avoiding scheduling any additional work for the event loop: @@ -1757,13 +1796,14 @@ if (someConditionNotMet()) { ``` If it is necessary to terminate the Node.js process due to an error condition, -throwing an *uncaught* error and allowing the process to terminate accordingly +throwing an _uncaught_ error and allowing the process to terminate accordingly is safer than calling `process.exit()`. In [`Worker`][] threads, this function stops the current thread rather than the current process. ## `process.exitCode` + <!-- YAML added: v0.11.8 --> @@ -1778,6 +1818,7 @@ Specifying a code to [`process.exit(code)`][`process.exit()`] will override any previous setting of `process.exitCode`. ## `process.getegid()` + <!-- YAML added: v2.0.0 --> @@ -1805,6 +1846,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). ## `process.geteuid()` + <!-- YAML added: v2.0.0 --> @@ -1834,6 +1876,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). ## `process.getgid()` + <!-- YAML added: v0.1.31 --> @@ -1863,11 +1906,12 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). ## `process.getgroups()` + <!-- YAML added: v0.9.4 --> -* Returns: {integer[]} +* Returns: {integer\[]} The `process.getgroups()` method returns an array with the supplementary group IDs. POSIX leaves it unspecified if the effective group ID is included but @@ -1893,6 +1937,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). ## `process.getuid()` + <!-- YAML added: v0.1.28 --> @@ -1922,6 +1967,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). ## `process.hasUncaughtExceptionCaptureCallback()` + <!-- YAML added: v9.3.0 --> @@ -1932,14 +1978,15 @@ Indicates whether a callback has been set using [`process.setUncaughtExceptionCaptureCallback()`][]. ## `process.hrtime([time])` + <!-- YAML added: v0.7.6 --> > Stability: 3 - Legacy. Use [`process.hrtime.bigint()`][] instead. -* `time` {integer[]} The result of a previous call to `process.hrtime()` -* Returns: {integer[]} +* `time` {integer\[]} The result of a previous call to `process.hrtime()` +* Returns: {integer\[]} This is the legacy version of [`process.hrtime.bigint()`][] before `bigint` was introduced in JavaScript. @@ -1991,6 +2038,7 @@ setTimeout(() => { ``` ## `process.hrtime.bigint()` + <!-- YAML added: v10.7.0 --> @@ -2035,6 +2083,7 @@ setTimeout(() => { ``` ## `process.initgroups(user, extraGroup)` + <!-- YAML added: v0.9.4 --> @@ -2074,6 +2123,7 @@ Android). This feature is not available in [`Worker`][] threads. ## `process.kill(pid[, signal])` + <!-- YAML added: v0.0.6 --> @@ -2131,6 +2181,7 @@ When `SIGUSR1` is received by a Node.js process, Node.js will start the debugger. See [Signal Events][]. ## `process.mainModule` + <!-- YAML added: v0.1.17 deprecated: v14.0.0 @@ -2150,6 +2201,7 @@ As with [`require.main`][], `process.mainModule` will be `undefined` if there is no entry script. ## `process.memoryUsage()` + <!-- YAML added: v0.1.16 changes: @@ -2221,6 +2273,7 @@ information about memory usage which might be slow depending on the program memory allocations. ## `process.memoryUsage.rss()` + <!-- YAML added: - v15.6.0 @@ -2254,6 +2307,7 @@ console.log(memoryUsage.rss()); ``` ## `process.nextTick(callback[, ...args])` + <!-- YAML added: v0.1.26 changes: @@ -2300,7 +2354,7 @@ console.log('scheduled'); ``` This is important when developing APIs in order to give users the opportunity -to assign event handlers *after* an object has been constructed but before any +to assign event handlers _after_ an object has been constructed but before any I/O has occurred: ```mjs @@ -2426,7 +2480,7 @@ nextTick(() => console.log(1)); // 3 ``` -For *most* userland use cases, the `queueMicrotask()` API provides a portable +For _most_ userland use cases, the `queueMicrotask()` API provides a portable and reliable mechanism for deferring execution that works across multiple JavaScript platform environments and should be favored over `process.nextTick()`. In simple scenarios, `queueMicrotask()` can be a drop-in replacement for @@ -2473,6 +2527,7 @@ When in doubt, unless the specific capabilities of `process.nextTick()` are needed, use `queueMicrotask()`. ## `process.noDeprecation` + <!-- YAML added: v0.8.0 --> @@ -2486,6 +2541,7 @@ the [`'warning'` event][process_warning] and the flag's behavior. ## `process.pid` + <!-- YAML added: v0.1.15 --> @@ -2507,6 +2563,7 @@ console.log(`This process is pid ${pid}`); ``` ## `process.platform` + <!-- YAML added: v0.1.16 --> @@ -2543,6 +2600,7 @@ Android operating system. However, Android support in Node.js [is experimental][Android building]. ## `process.ppid` + <!-- YAML added: - v9.2.0 @@ -2568,6 +2626,7 @@ console.log(`The parent process is pid ${ppid}`); ``` ## `process.release` + <!-- YAML added: v3.0.0 changes: @@ -2602,9 +2661,10 @@ tarball. that are no longer supported). * `'Dubnium'` for the 10.x LTS line beginning with 10.13.0. * `'Erbium'` for the 12.x LTS line beginning with 12.13.0. - For other LTS Release code names, see [Node.js Changelog Archive](https://github.com/nodejs/node/blob/HEAD/doc/changelogs/CHANGELOG_ARCHIVE.md) + For other LTS Release code names, see [Node.js Changelog Archive](https://github.com/nodejs/node/blob/HEAD/doc/changelogs/CHANGELOG\_ARCHIVE.md) <!-- eslint-skip --> + ```js { name: 'node', @@ -2620,6 +2680,7 @@ In custom builds from non-release versions of the source tree, only the relied upon to exist. ## `process.report` + <!-- YAML added: v11.8.0 changes: @@ -2637,6 +2698,7 @@ reports for the current process. Additional documentation is available in the [report documentation][]. ### `process.report.compact` + <!-- YAML added: - v13.12.0 @@ -2662,6 +2724,7 @@ console.log(`Reports are compact? ${report.compact}`); ``` ### `process.report.directory` + <!-- YAML added: v11.12.0 changes: @@ -2691,6 +2754,7 @@ console.log(`Report directory is ${report.directory}`); ``` ### `process.report.filename` + <!-- YAML added: v11.12.0 changes: @@ -2720,6 +2784,7 @@ console.log(`Report filename is ${report.filename}`); ``` ### `process.report.getReport([err])` + <!-- YAML added: v11.8.0 changes: @@ -2762,6 +2827,7 @@ fs.writeFileSync('my-report.log', util.inspect(data), 'utf8'); Additional documentation is available in the [report documentation][]. ### `process.report.reportOnFatalError` + <!-- YAML added: v11.12.0 changes: @@ -2790,6 +2856,7 @@ console.log(`Report on fatal error: ${report.reportOnFatalError}`); ``` ### `process.report.reportOnSignal` + <!-- YAML added: v11.12.0 changes: @@ -2818,6 +2885,7 @@ console.log(`Report on signal: ${report.reportOnSignal}`); ``` ### `process.report.reportOnUncaughtException` + <!-- YAML added: v11.12.0 changes: @@ -2845,6 +2913,7 @@ console.log(`Report on exception: ${report.reportOnUncaughtException}`); ``` ### `process.report.signal` + <!-- YAML added: v11.12.0 changes: @@ -2873,6 +2942,7 @@ console.log(`Report signal: ${report.signal}`); ``` ### `process.report.writeReport([filename][, err])` + <!-- YAML added: v11.8.0 changes: @@ -2887,6 +2957,7 @@ changes: should be a relative path, that will be appended to the directory specified in `process.report.directory`, or the current working directory of the Node.js process, if unspecified. + * `err` {Error} A custom error used for reporting the JavaScript stack. * Returns: {string} Returns the filename of the generated report. @@ -2910,6 +2981,7 @@ report.writeReport(); Additional documentation is available in the [report documentation][]. ## `process.resourceUsage()` + <!-- YAML added: v12.6.0 --> @@ -3012,6 +3084,7 @@ console.log(resourceUsage()); ``` ## `process.send(message[, sendHandle[, options]][, callback])` + <!-- YAML added: v0.5.9 --> @@ -3037,6 +3110,7 @@ The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent. ## `process.setegid(id)` + <!-- YAML added: v2.0.0 --> @@ -3081,6 +3155,7 @@ Android). This feature is not available in [`Worker`][] threads. ## `process.seteuid(id)` + <!-- YAML added: v2.0.0 --> @@ -3125,6 +3200,7 @@ Android). This feature is not available in [`Worker`][] threads. ## `process.setgid(id)` + <!-- YAML added: v0.1.31 --> @@ -3169,11 +3245,12 @@ Android). This feature is not available in [`Worker`][] threads. ## `process.setgroups(groups)` + <!-- YAML added: v0.9.4 --> -* `groups` {integer[]} +* `groups` {integer\[]} The `process.setgroups()` method sets the supplementary group IDs for the Node.js process. This is a privileged operation that requires the Node.js @@ -3212,6 +3289,7 @@ Android). This feature is not available in [`Worker`][] threads. ## `process.setuid(id)` + <!-- YAML added: v0.1.28 --> @@ -3256,6 +3334,7 @@ Android). This feature is not available in [`Worker`][] threads. ## `process.setSourceMapsEnabled(val)` + <!-- YAML added: - v16.6.0 @@ -3276,6 +3355,7 @@ Only source maps in JavaScript files that are loaded after source maps has been enabled will be parsed and loaded. ## `process.setUncaughtExceptionCaptureCallback(fn)` + <!-- YAML added: v9.3.0 --> @@ -3390,9 +3470,9 @@ important ways: respectively. 2. Writes may be synchronous depending on what the stream is connected to and whether the system is Windows or POSIX: - * Files: *synchronous* on Windows and POSIX - * TTYs (Terminals): *asynchronous* on Windows, *synchronous* on POSIX - * Pipes (and sockets): *synchronous* on Windows, *asynchronous* on POSIX + * Files: _synchronous_ on Windows and POSIX + * TTYs (Terminals): _asynchronous_ on Windows, _synchronous_ on POSIX + * Pipes (and sockets): _synchronous_ on Windows, _asynchronous_ on POSIX These behaviors are partly for historical reasons, as changing them would create backward incompatibility, but they are also expected by some users. @@ -3402,7 +3482,7 @@ Synchronous writes avoid problems such as output written with `console.log()` or `process.exit()` is called before an asynchronous write completes. See [`process.exit()`][] for more information. -***Warning***: Synchronous writes block the event loop until the write has +_**Warning**_: Synchronous writes block the event loop until the write has completed. This can be near instantaneous in the case of output to a file, but under high system load, pipes that are not being read at the receiving end, or with slow terminals or file systems, its possible for the event loop to be @@ -3430,6 +3510,7 @@ false See the [TTY][] documentation for more information. ## `process.throwDeprecation` + <!-- YAML added: v0.9.12 --> @@ -3460,6 +3541,7 @@ Thrown: ``` ## `process.title` + <!-- YAML added: v0.1.104 --> @@ -3484,6 +3566,7 @@ within process manager applications such as macOS Activity Monitor or Windows Services Manager. ## `process.traceDeprecation` + <!-- YAML added: v0.8.0 --> @@ -3497,6 +3580,7 @@ documentation for the [`'warning'` event][process_warning] and the flag's behavior. ## `process.umask()` + <!-- YAML added: v0.1.19 changes: @@ -3517,6 +3601,7 @@ changes: processes inherit the mask from the parent process. ## `process.umask(mask)` + <!-- YAML added: v0.1.19 --> @@ -3549,6 +3634,7 @@ console.log( In [`Worker`][] threads, `process.umask(mask)` will throw an exception. ## `process.uptime()` + <!-- YAML added: v0.5.0 --> @@ -3562,6 +3648,7 @@ The return value includes fractions of a second. Use `Math.floor()` to get whole seconds. ## `process.version` + <!-- YAML added: v0.1.3 --> @@ -3588,6 +3675,7 @@ To get the version string without the prepended _v_, use `process.versions.node`. ## `process.versions` + <!-- YAML added: v0.2.0 changes: diff --git a/doc/api/punycode.md b/doc/api/punycode.md index b7183f6d396..6aa01a83487 100644 --- a/doc/api/punycode.md +++ b/doc/api/punycode.md @@ -1,4 +1,5 @@ # Punycode + <!-- YAML deprecated: v7.0.0 --> @@ -39,6 +40,7 @@ made available to developers as a convenience. Fixes or other modifications to the module must be directed to the [Punycode.js][] project. ## `punycode.decode(string)` + <!-- YAML added: v0.5.1 --> @@ -54,6 +56,7 @@ punycode.decode('--dqo34k'); // '☃-⌘' ``` ## `punycode.encode(string)` + <!-- YAML added: v0.5.1 --> @@ -69,6 +72,7 @@ punycode.encode('☃-⌘'); // '--dqo34k' ``` ## `punycode.toASCII(domain)` + <!-- YAML added: v0.6.1 --> @@ -88,6 +92,7 @@ punycode.toASCII('example.com'); // 'example.com' ``` ## `punycode.toUnicode(domain)` + <!-- YAML added: v0.6.1 --> @@ -106,11 +111,13 @@ punycode.toUnicode('example.com'); // 'example.com' ``` ## `punycode.ucs2` + <!-- YAML added: v0.7.0 --> ### `punycode.ucs2.decode(string)` + <!-- YAML added: v0.7.0 --> @@ -127,11 +134,12 @@ punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306] ``` ### `punycode.ucs2.encode(codePoints)` + <!-- YAML added: v0.7.0 --> -* `codePoints` {integer[]} +* `codePoints` {integer\[]} The `punycode.ucs2.encode()` method returns a string based on an array of numeric code point values. @@ -142,6 +150,7 @@ punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06' ``` ## `punycode.version` + <!-- YAML added: v0.6.1 --> diff --git a/doc/api/querystring.md b/doc/api/querystring.md index 4b7db7afc3b..32e9904553d 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -19,6 +19,7 @@ The `querystring` API is considered Legacy. While it is still maintained, new code should use the {URLSearchParams} API instead. ## `querystring.decode()` + <!-- YAML added: v0.1.99 --> @@ -26,6 +27,7 @@ added: v0.1.99 The `querystring.decode()` function is an alias for `querystring.parse()`. ## `querystring.encode()` + <!-- YAML added: v0.1.99 --> @@ -33,6 +35,7 @@ added: v0.1.99 The `querystring.encode()` function is an alias for `querystring.stringify()`. ## `querystring.escape(str)` + <!-- YAML added: v0.1.25 --> @@ -49,6 +52,7 @@ application code to provide a replacement percent-encoding implementation if necessary by assigning `querystring.escape` to an alternative function. ## `querystring.parse(str[, sep[, eq[, options]]])` + <!-- YAML added: v0.1.25 changes: @@ -83,6 +87,7 @@ collection of key and value pairs. For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into: <!-- eslint-skip --> + ```js { foo: 'bar', @@ -93,7 +98,7 @@ For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into: The object returned by the `querystring.parse()` method _does not_ prototypically inherit from the JavaScript `Object`. This means that typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others -are not defined and *will not work*. +are not defined and _will not work_. By default, percent-encoded characters within the query string will be assumed to use UTF-8 encoding. If an alternative character encoding is used, then an @@ -107,6 +112,7 @@ querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null, ``` ## `querystring.stringify(obj[, sep[, eq[, options]]])` + <!-- YAML added: v0.1.25 --> @@ -125,7 +131,7 @@ The `querystring.stringify()` method produces a URL query string from a given `obj` by iterating through the object's "own properties". It serializes the following types of values passed in `obj`: -{string|number|bigint|boolean|string[]|number[]|bigint[]|boolean[]} +{string|number|bigint|boolean|string\[]|number\[]|bigint\[]|boolean\[]} The numeric values must be finite. Any other input values will be coerced to empty strings. @@ -149,6 +155,7 @@ querystring.stringify({ w: '中文', foo: 'bar' }, null, null, ``` ## `querystring.unescape(str)` + <!-- YAML added: v0.1.25 --> diff --git a/doc/api/readline.md b/doc/api/readline.md index b9e4c286994..31d910e1b68 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -63,7 +63,9 @@ Once this code is invoked, the Node.js application will not terminate until the received on the `input` stream. <a id='readline_class_interface'></a> + ## Class: `InterfaceConstructor` + <!-- YAML added: v0.1.104 --> @@ -78,6 +80,7 @@ The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. ### Event: `'close'` + <!-- YAML added: v0.1.98 --> @@ -99,6 +102,7 @@ The `InterfaceConstructor` instance is finished once the `'close'` event is emitted. ### Event: `'line'` + <!-- YAML added: v0.1.98 --> @@ -117,6 +121,7 @@ rl.on('line', (input) => { ``` ### Event: `'history'` + <!-- YAML added: - v15.8.0 @@ -141,6 +146,7 @@ rl.on('history', (history) => { ``` ### Event: `'pause'` + <!-- YAML added: v0.7.5 --> @@ -160,6 +166,7 @@ rl.on('pause', () => { ``` ### Event: `'resume'` + <!-- YAML added: v0.7.5 --> @@ -175,6 +182,7 @@ rl.on('resume', () => { ``` ### Event: `'SIGCONT'` + <!-- YAML added: v0.7.5 --> @@ -183,7 +191,7 @@ The `'SIGCONT'` event is emitted when a Node.js process previously moved into the background using <kbd>Ctrl</kbd>+<kbd>Z</kbd> (i.e. `SIGTSTP`) is then brought back to the foreground using fg(1p). -If the `input` stream was paused *before* the `SIGTSTP` request, this event will +If the `input` stream was paused _before_ the `SIGTSTP` request, this event will not be emitted. The listener function is invoked without passing any arguments. @@ -198,14 +206,15 @@ rl.on('SIGCONT', () => { The `'SIGCONT'` event is _not_ supported on Windows. ### Event: `'SIGINT'` + <!-- YAML added: v0.3.0 --> -The `'SIGINT'` event is emitted whenever the `input` stream receives a -<kbd>Ctrl+C</kbd> input, known typically as `SIGINT`. If there are no `'SIGINT'` -event listeners registered when the `input` stream receives a `SIGINT`, the -`'pause'` event will be emitted. +The `'SIGINT'` event is emitted whenever the `input` stream receives +a <kbd>Ctrl+C</kbd> input, known typically as `SIGINT`. If there are no +`'SIGINT'` event listeners registered when the `input` stream receives a +`SIGINT`, the `'pause'` event will be emitted. The listener function is invoked without passing any arguments. @@ -218,12 +227,13 @@ rl.on('SIGINT', () => { ``` ### Event: `'SIGTSTP'` + <!-- YAML added: v0.7.5 --> -The `'SIGTSTP'` event is emitted when the `input` stream receives a -<kbd>Ctrl</kbd>+<kbd>Z</kbd> input, typically known as `SIGTSTP`. If there are +The `'SIGTSTP'` event is emitted when the `input` stream receives +a <kbd>Ctrl</kbd>+<kbd>Z</kbd> input, typically known as `SIGTSTP`. If there are no `'SIGTSTP'` event listeners registered when the `input` stream receives a `SIGTSTP`, the Node.js process will be sent to the background. @@ -246,6 +256,7 @@ rl.on('SIGTSTP', () => { The `'SIGTSTP'` event is _not_ supported on Windows. ### `rl.close()` + <!-- YAML added: v0.1.98 --> @@ -258,6 +269,7 @@ Calling `rl.close()` does not immediately stop other events (including `'line'`) from being emitted by the `InterfaceConstructor` instance. ### `rl.pause()` + <!-- YAML added: v0.3.4 --> @@ -269,6 +281,7 @@ Calling `rl.pause()` does not immediately pause other events (including `'line'`) from being emitted by the `InterfaceConstructor` instance. ### `rl.prompt([preserveCursor])` + <!-- YAML added: v0.1.98 --> @@ -287,6 +300,7 @@ If the `InterfaceConstructor` was created with `output` set to `null` or `undefined` the prompt is not written. ### `rl.question(query[, options], callback)` + <!-- YAML added: v0.3.3 --> @@ -358,6 +372,7 @@ questionExample(); ``` ### `rl.resume()` + <!-- YAML added: v0.3.4 --> @@ -365,6 +380,7 @@ added: v0.3.4 The `rl.resume()` method resumes the `input` stream if it has been paused. ### `rl.setPrompt(prompt)` + <!-- YAML added: v0.1.98 --> @@ -375,6 +391,7 @@ The `rl.setPrompt()` method sets the prompt that will be written to `output` whenever `rl.prompt()` is called. ### `rl.getPrompt()` + <!-- YAML added: - v15.3.0 @@ -386,6 +403,7 @@ added: The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`. ### `rl.write(data[, key])` + <!-- YAML added: v0.1.98 --> @@ -417,9 +435,10 @@ rl.write(null, { ctrl: true, name: 'u' }); ``` The `rl.write()` method will write the data to the `readline` `Interface`'s -`input` *as if it were provided by the user*. +`input` _as if it were provided by the user_. ### `rl[Symbol.asyncIterator]()` + <!-- YAML added: - v11.4.0 @@ -465,6 +484,7 @@ invoked. Having asynchronous operations between interface creation and asynchronous iteration may result in missed lines. ### `rl.line` + <!-- YAML added: v0.1.98 changes: @@ -506,6 +526,7 @@ process.stdin.on('keypress', (c, k) => { ``` ### `rl.cursor` + <!-- YAML added: v0.1.98 --> @@ -520,6 +541,7 @@ portion of the input string that will be modified as input is processed, as well as the column where the terminal caret will be rendered. ### `rl.getCursorPos()` + <!-- YAML added: - v13.5.0 @@ -535,6 +557,7 @@ prompt + string. Long input (wrapping) strings, as well as multiple line prompts are included in the calculations. ## Promises API + <!-- YAML added: v17.0.0 --> @@ -542,6 +565,7 @@ added: v17.0.0 > Stability: 1 - Experimental ### Class: `readlinePromises.Interface` + <!-- YAML added: v17.0.0 --> @@ -555,6 +579,7 @@ The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. #### `rl.question(query[, options])` + <!-- YAML added: v17.0.0 --> @@ -601,11 +626,13 @@ setTimeout(() => ac.abort(), 10000); ``` ### Class: `readlinePromises.Readline` + <!-- YAML added: v17.0.0 --> #### `new readlinePromises.Readline(stream[, options])` + <!-- YAML added: v17.0.0 --> @@ -615,6 +642,7 @@ added: v17.0.0 * `autoCommit` {boolean} If `true`, no need to call `rl.commit()`. #### `rl.clearLine(dir)` + <!-- YAML added: v17.0.0 --> @@ -632,6 +660,7 @@ Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.clearScreenDown()` + <!-- YAML added: v17.0.0 --> @@ -645,6 +674,7 @@ Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.commit()` + <!-- YAML added: v17.0.0 --> @@ -655,6 +685,7 @@ The `rl.commit()` method sends all the pending actions to the associated `stream` and clears the internal list of pending actions. #### `rl.cursorTo(x[, y])` + <!-- YAML added: v17.0.0 --> @@ -669,6 +700,7 @@ Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.moveCursor(dx, dy)` + <!-- YAML added: v17.0.0 --> @@ -678,12 +710,13 @@ added: v17.0.0 * Returns: this The `rl.moveCursor()` method adds to the internal list of pending action an -action that moves the cursor *relative* to its current position in the +action that moves the cursor _relative_ to its current position in the associated `stream`. Call `rl.commit()` to see the effect of this method, unless `autoCommit: true` was passed to the constructor. #### `rl.rollback()` + <!-- YAML added: v17.0.0 --> @@ -694,20 +727,21 @@ The `rl.rollback` methods clears the internal list of pending actions without sending it to the associated `stream`. ### `readlinePromises.createInterface(options)` + <!-- YAML added: v17.0.0 --> * `options` {Object} * `input` {stream.Readable} The [Readable][] stream to listen to. This option - is *required*. + is _required_. * `output` {stream.Writable} The [Writable][] stream to write readline data to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. **Default:** checking `isTTY` on the `output` stream upon instantiation. - * `history` {string[]} Initial list of history lines. This option makes sense + * `history` {string\[]} Initial list of history lines. This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check, otherwise the history caching mechanism is not initialized at all. **Default:** `[]`. @@ -789,11 +823,13 @@ async function completer(linePartial) { ``` ## Callback API + <!-- YAML added: v0.1.104 --> ### Class: `readline.Interface` + <!-- YAML added: v0.1.104 changes: @@ -811,6 +847,7 @@ The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. #### `rl.question(query[, options], callback)` + <!-- YAML added: v0.3.3 --> @@ -882,6 +919,7 @@ questionExample(); ``` ### `readline.clearLine(stream, dir[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -904,6 +942,7 @@ The `readline.clearLine()` method clears current line of given [TTY][] stream in a specified direction identified by `dir`. ### `readline.clearScreenDown(stream[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -922,6 +961,7 @@ The `readline.clearScreenDown()` method clears the given [TTY][] stream from the current position of the cursor down. ### `readline.createInterface(options)` + <!-- YAML added: v0.1.98 changes: @@ -956,14 +996,14 @@ changes: * `options` {Object} * `input` {stream.Readable} The [Readable][] stream to listen to. This option - is *required*. + is _required_. * `output` {stream.Writable} The [Writable][] stream to write readline data to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. **Default:** checking `isTTY` on the `output` stream upon instantiation. - * `history` {string[]} Initial list of history lines. This option makes sense + * `history` {string\[]} Initial list of history lines. This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check, otherwise the history caching mechanism is not initialized at all. **Default:** `[]`. @@ -1058,6 +1098,7 @@ function completer(linePartial, callback) { ``` ### `readline.cursorTo(stream, x[, y][, callback])` + <!-- YAML added: v0.7.7 changes: @@ -1078,6 +1119,7 @@ The `readline.cursorTo()` method moves cursor to the specified position in a given [TTY][] `stream`. ### `readline.moveCursor(stream, dx, dy[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -1094,10 +1136,11 @@ changes: the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. -The `readline.moveCursor()` method moves the cursor *relative* to its current +The `readline.moveCursor()` method moves the cursor _relative_ to its current position in a given [TTY][] `stream`. ## `readline.emitKeypressEvents(stream[, interface])` + <!-- YAML added: v0.7.7 --> diff --git a/doc/api/repl.md b/doc/api/repl.md index 409f70b2b39..4c75bdec2c4 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -45,8 +45,8 @@ The following special commands are supported by all REPL instances: `> .save ./file/to/save.js` * `.load`: Load a file into the current REPL session. `> .load ./file/to/load.js` -* `.editor`: Enter editor mode (<kbd>Ctrl</kbd>+<kbd>D</kbd> to finish, - <kbd>Ctrl</kbd>+<kbd>C</kbd> to cancel). +* `.editor`: Enter editor mode (<kbd>Ctrl</kbd>+<kbd>D</kbd> to + finish, <kbd>Ctrl</kbd>+<kbd>C</kbd> to cancel). ```console > .editor @@ -69,8 +69,8 @@ The following key combinations in the REPL have these special effects: When pressed twice on a blank line, has the same effect as the `.exit` command. * <kbd>Ctrl</kbd>+<kbd>D</kbd>: Has the same effect as the `.exit` command. -* <kbd>Tab</kbd>: When pressed on a blank line, displays global and local (scope) - variables. When pressed while entering other input, displays relevant +* <kbd>Tab</kbd>: When pressed on a blank line, displays global and local + (scope) variables. When pressed while entering other input, displays relevant autocompletion options. For key bindings related to the reverse-i-search, see [`reverse-i-search`][]. @@ -148,6 +148,7 @@ global or scoped variable, the input `fs` will be evaluated on-demand as ``` #### Global uncaught exceptions + <!-- YAML changes: - version: v12.3.0 @@ -180,6 +181,7 @@ This use of the [`domain`][] module in the REPL has these side effects: an [`ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE`][] error. #### Assignment of the `_` (underscore) variable + <!-- YAML changes: - version: v9.8.0 @@ -252,6 +254,7 @@ undefined [`--no-experimental-repl-await`][] shall disable top-level await in REPL. ### Reverse-i-search + <!-- YAML added: - v13.6.0 @@ -259,15 +262,14 @@ added: --> The REPL supports bi-directional reverse-i-search similar to [ZSH][]. It is -triggered with <kbd>Ctrl</kbd>+<kbd>R</kbd> to search backward and -<kbd>Ctrl</kbd>+<kbd>S</kbd> to search -forwards. +triggered with <kbd>Ctrl</kbd>+<kbd>R</kbd> to search backward +and <kbd>Ctrl</kbd>+<kbd>S</kbd> to search forwards. Duplicated history entries will be skipped. Entries are accepted as soon as any key is pressed that doesn't correspond -with the reverse search. Cancelling is possible by pressing <kbd>Esc</kbd> or -<kbd>Ctrl</kbd>+<kbd>C</kbd>. +with the reverse search. Cancelling is possible by pressing <kbd>Esc</kbd> +or <kbd>Ctrl</kbd>+<kbd>C</kbd>. Changing the direction immediately searches for the next entry in the expected direction from the current position on. @@ -367,6 +369,7 @@ function myWriter(output) { ``` ## Class: `REPLServer` + <!-- YAML added: v0.1.91 --> @@ -387,6 +390,7 @@ const secondInstance = new repl.REPLServer(options); ``` ### Event: `'exit'` + <!-- YAML added: v0.7.7 --> @@ -406,12 +410,13 @@ replServer.on('exit', () => { ``` ### Event: `'reset'` + <!-- YAML added: v0.11.0 --> The `'reset'` event is emitted when the REPL's context is reset. This occurs -whenever the `.clear` command is received as input *unless* the REPL is using +whenever the `.clear` command is received as input _unless_ the REPL is using the default evaluator and the `repl.REPLServer` instance was created with the `useGlobal` option set to `true`. The listener callback will be called with a reference to the `context` object as the only argument. @@ -451,11 +456,12 @@ Clearing context... ``` ### `replServer.defineCommand(keyword, cmd)` + <!-- YAML added: v0.3.0 --> -* `keyword` {string} The command keyword (*without* a leading `.` character). +* `keyword` {string} The command keyword (_without_ a leading `.` character). * `cmd` {Object|Function} The function to invoke when the command is processed. The `replServer.defineCommand()` method is used to add new `.`-prefixed commands @@ -497,6 +503,7 @@ Goodbye! ``` ### `replServer.displayPrompt([preserveCursor])` + <!-- YAML added: v0.1.91 --> @@ -517,6 +524,7 @@ within the action function for commands registered using the `replServer.defineCommand()` method. ### `replServer.clearBufferedCommand()` + <!-- YAML added: v9.0.0 --> @@ -527,6 +535,7 @@ called from within the action function for commands registered using the `replServer.defineCommand()` method. ### `replServer.parseREPLKeyword(keyword[, rest])` + <!-- YAML added: v0.8.9 deprecated: v9.0.0 @@ -542,6 +551,7 @@ An internal method used to parse and execute `REPLServer` keywords. Returns `true` if `keyword` is a valid keyword, otherwise `false`. ### `replServer.setupHistory(historyPath, callback)` + <!-- YAML added: v11.10.0 --> @@ -558,15 +568,17 @@ programmatically. Use this method to initialize a history log file when working with REPL instances programmatically. ## `repl.builtinModules` + <!-- YAML added: v14.5.0 --> -* {string[]} +* {string\[]} A list of the names of all Node.js modules, e.g., `'http'`. ## `repl.start([options])` + <!-- YAML added: v0.1.91 changes: @@ -611,16 +623,16 @@ changes: color support on the `output` stream if the REPL instance's `terminal` value is `true`. * `useGlobal` {boolean} If `true`, specifies that the default evaluation - function will use the JavaScript `global` as the context as opposed to - creating a new separate context for the REPL instance. The node CLI REPL - sets this value to `true`. **Default:** `false`. + function will use the JavaScript `global` as the context as opposed to + creating a new separate context for the REPL instance. The node CLI REPL + sets this value to `true`. **Default:** `false`. * `ignoreUndefined` {boolean} If `true`, specifies that the default writer - will not output the return value of a command if it evaluates to - `undefined`. **Default:** `false`. + will not output the return value of a command if it evaluates to + `undefined`. **Default:** `false`. * `writer` {Function} The function to invoke to format the output of each - command before writing to `output`. **Default:** [`util.inspect()`][]. + command before writing to `output`. **Default:** [`util.inspect()`][]. * `completer` {Function} An optional function used for custom Tab auto - completion. See [`readline.InterfaceCompleter`][] for an example. + completion. See [`readline.InterfaceCompleter`][] for an example. * `replMode` {symbol} A flag that specifies whether the default evaluator executes all JavaScript commands in strict mode or default (sloppy) mode. Acceptable values are: diff --git a/doc/api/report.md b/doc/api/report.md index a050e2c006f..cee349d0073 100644 --- a/doc/api/report.md +++ b/doc/api/report.md @@ -580,6 +580,7 @@ Specific API documentation can be found under [`process API documentation`][] section. ## Interaction with workers + <!-- YAML changes: - version: diff --git a/doc/api/stream.md b/doc/api/stream.md index ca183d14314..91fe70555d0 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -49,6 +49,7 @@ Additionally, this module includes the utility functions and [`stream.addAbortSignal()`][]. ### Streams Promises API + <!-- YAML added: v15.0.0 --> @@ -110,12 +111,12 @@ enforce a strict memory limitation in general. Specific stream implementations may choose to enforce stricter limits but doing so is optional. Because [`Duplex`][] and [`Transform`][] streams are both `Readable` and -`Writable`, each maintains *two* separate internal buffers used for reading and +`Writable`, each maintains _two_ separate internal buffers used for reading and writing, allowing each side to operate independently of the other while maintaining an appropriate and efficient flow of data. For example, [`net.Socket`][] instances are [`Duplex`][] streams whose `Readable` side allows -consumption of data received *from* the socket and whose `Writable` side allows -writing data *to* the socket. Because data may be written to the socket at a +consumption of data received _from_ the socket and whose `Writable` side allows +writing data _to_ the socket. Because data may be written to the socket at a faster or slower rate than data is received, each side should operate (and buffer) independently of the other. @@ -196,7 +197,7 @@ section [API for stream implementers][]. ### Writable streams -Writable streams are an abstraction for a *destination* to which data is +Writable streams are an abstraction for a _destination_ to which data is written. Examples of [`Writable`][] streams include: @@ -228,6 +229,7 @@ myStream.end('done writing data'); ``` #### Class: `stream.Writable` + <!-- YAML added: v0.9.4 --> @@ -235,6 +237,7 @@ added: v0.9.4 <!--type=class--> ##### Event: `'close'` + <!-- YAML added: v0.9.4 changes: @@ -252,6 +255,7 @@ A [`Writable`][] stream will always emit the `'close'` event if it is created with the `emitClose` option. ##### Event: `'drain'` + <!-- YAML added: v0.9.4 --> @@ -289,6 +293,7 @@ function writeOneMillionTimes(writer, data, encoding, callback) { ``` ##### Event: `'error'` + <!-- YAML added: v0.9.4 --> @@ -302,10 +307,11 @@ The stream is closed when the `'error'` event is emitted unless the [`autoDestroy`][writable-new] option was set to `false` when creating the stream. -After `'error'`, no further events other than `'close'` *should* be emitted +After `'error'`, no further events other than `'close'` _should_ be emitted (including `'error'` events). ##### Event: `'finish'` + <!-- YAML added: v0.9.4 --> @@ -325,6 +331,7 @@ writer.end('This is the end\n'); ``` ##### Event: `'pipe'` + <!-- YAML added: v0.9.4 --> @@ -345,6 +352,7 @@ reader.pipe(writer); ``` ##### Event: `'unpipe'` + <!-- YAML added: v0.9.4 --> @@ -371,6 +379,7 @@ reader.unpipe(writer); ``` ##### `writable.cork()` + <!-- YAML added: v0.11.2 --> @@ -391,6 +400,7 @@ to be processed. However, use of `writable.cork()` without implementing See also: [`writable.uncork()`][], [`writable._writev()`][stream-_writev]. ##### `writable.destroy([error])` + <!-- YAML added: v8.0.0 changes: @@ -447,6 +457,7 @@ Implementors should not override this method, but instead implement [`writable._destroy()`][writable-_destroy]. ##### `writable.destroyed` + <!-- YAML added: v8.0.0 --> @@ -466,6 +477,7 @@ console.log(myStream.destroyed); // true ``` ##### `writable.end([chunk[, encoding]][, callback])` + <!-- YAML added: v0.9.4 changes: @@ -509,6 +521,7 @@ file.end('world!'); ``` ##### `writable.setDefaultEncoding(encoding)` + <!-- YAML added: v0.11.15 changes: @@ -524,6 +537,7 @@ The `writable.setDefaultEncoding()` method sets the default `encoding` for a [`Writable`][] stream. ##### `writable.uncork()` + <!-- YAML added: v0.11.2 --> @@ -562,6 +576,7 @@ process.nextTick(() => { See also: [`writable.cork()`][]. ##### `writable.writable` + <!-- YAML added: v11.4.0 --> @@ -572,6 +587,7 @@ Is `true` if it is safe to call [`writable.write()`][stream-write], which means the stream has not been destroyed, errored or ended. ##### `writable.writableEnded` + <!-- YAML added: v12.9.0 --> @@ -583,6 +599,7 @@ does not indicate whether the data has been flushed, for this use [`writable.writableFinished`][] instead. ##### `writable.writableCorked` + <!-- YAML added: - v13.2.0 @@ -595,6 +612,7 @@ Number of times [`writable.uncork()`][stream-uncork] needs to be called in order to fully uncork the stream. ##### `writable.writableFinished` + <!-- YAML added: v12.6.0 --> @@ -604,6 +622,7 @@ added: v12.6.0 Is set to `true` immediately before the [`'finish'`][] event is emitted. ##### `writable.writableHighWaterMark` + <!-- YAML added: v9.3.0 --> @@ -613,6 +632,7 @@ added: v9.3.0 Return the value of `highWaterMark` passed when creating this `Writable`. ##### `writable.writableLength` + <!-- YAML added: v9.4.0 --> @@ -624,6 +644,7 @@ ready to be written. The value provides introspection data regarding the status of the `highWaterMark`. ##### `writable.writableNeedDrain` + <!-- YAML added: - v15.2.0 @@ -635,6 +656,7 @@ added: Is `true` if the stream's buffer has been full and stream will emit `'drain'`. ##### `writable.writableObjectMode` + <!-- YAML added: v12.3.0 --> @@ -644,6 +666,7 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Writable` stream. ##### `writable.write(chunk[, encoding][, callback])` + <!-- YAML added: v0.9.4 changes: @@ -720,7 +743,7 @@ A `Writable` stream in object mode will always ignore the `encoding` argument. ### Readable streams -Readable streams are an abstraction for a *source* from which data is +Readable streams are an abstraction for a _source_ from which data is consumed. Examples of `Readable` streams include: @@ -768,13 +791,13 @@ The `Readable` can switch back to paused mode using one of the following: The important concept to remember is that a `Readable` will not generate data until a mechanism for either consuming or ignoring that data is provided. If -the consuming mechanism is disabled or taken away, the `Readable` will *attempt* +the consuming mechanism is disabled or taken away, the `Readable` will _attempt_ to stop generating the data. For backward compatibility reasons, removing [`'data'`][] event handlers will **not** automatically pause the stream. Also, if there are piped destinations, then calling [`stream.pause()`][stream-pause] will not guarantee that the -stream will *remain* paused once those destinations drain and ask for more data. +stream will _remain_ paused once those destinations drain and ask for more data. If a [`Readable`][] is switched into flowing mode and there are no consumers available to handle the data, that data will be lost. This can occur, for @@ -810,7 +833,7 @@ emitting events as data is generated. Calling `readable.pause()`, `readable.unpipe()`, or receiving backpressure will cause the `readable.readableFlowing` to be set as `false`, -temporarily halting the flowing of events but *not* halting the generation of +temporarily halting the flowing of events but _not_ halting the generation of data. While in this state, attaching a listener for the `'data'` event will not switch `readable.readableFlowing` to `true`. @@ -835,7 +858,7 @@ within the stream's internal buffer. The `Readable` stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data. In general, developers should choose -*one* of the methods of consuming data and *should never* use multiple methods +_one_ of the methods of consuming data and _should never_ use multiple methods to consume data from a single stream. Specifically, using a combination of `on('data')`, `on('readable')`, `pipe()`, or async iterators could lead to unintuitive behavior. @@ -847,6 +870,7 @@ use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()` or the `readable.pause()`/`readable.resume()` APIs. #### Class: `stream.Readable` + <!-- YAML added: v0.9.4 --> @@ -854,6 +878,7 @@ added: v0.9.4 <!--type=class--> ##### Event: `'close'` + <!-- YAML added: v0.9.4 changes: @@ -871,6 +896,7 @@ A [`Readable`][] stream will always emit the `'close'` event if it is created with the `emitClose` option. ##### Event: `'data'` + <!-- YAML added: v0.9.4 --> @@ -904,6 +930,7 @@ readable.on('data', (chunk) => { ``` ##### Event: `'end'` + <!-- YAML added: v0.9.4 --> @@ -927,6 +954,7 @@ readable.on('end', () => { ``` ##### Event: `'error'` + <!-- YAML added: v0.9.4 --> @@ -941,6 +969,7 @@ to push an invalid chunk of data. The listener callback will be passed a single `Error` object. ##### Event: `'pause'` + <!-- YAML added: v0.9.4 --> @@ -949,6 +978,7 @@ The `'pause'` event is emitted when [`stream.pause()`][stream-pause] is called and `readableFlowing` is not `false`. ##### Event: `'readable'` + <!-- YAML added: v0.9.4 changes: @@ -1018,6 +1048,7 @@ will start flowing, i.e. `'data'` events will be emitted without calling `.resume()`. ##### Event: `'resume'` + <!-- YAML added: v0.9.4 --> @@ -1026,6 +1057,7 @@ The `'resume'` event is emitted when [`stream.resume()`][stream-resume] is called and `readableFlowing` is not `true`. ##### `readable.destroy([error])` + <!-- YAML added: v8.0.0 changes: @@ -1049,6 +1081,7 @@ Implementors should not override this method, but instead implement [`readable._destroy()`][readable-_destroy]. ##### `readable.destroyed` + <!-- YAML added: v8.0.0 --> @@ -1058,6 +1091,7 @@ added: v8.0.0 Is `true` after [`readable.destroy()`][readable-destroy] has been called. ##### `readable.isPaused()` + <!-- YAML added: v0.11.14 --> @@ -1080,6 +1114,7 @@ readable.isPaused(); // === false ``` ##### `readable.pause()` + <!-- YAML added: v0.9.4 --> @@ -1107,6 +1142,7 @@ The `readable.pause()` method has no effect if there is a `'readable'` event listener. ##### `readable.pipe(destination[, options])` + <!-- YAML added: v0.9.4 --> @@ -1114,7 +1150,7 @@ added: v0.9.4 * `destination` {stream.Writable} The destination for writing data * `options` {Object} Pipe options * `end` {boolean} End the writer when the reader ends. **Default:** `true`. -* Returns: {stream.Writable} The *destination*, allowing for a chain of pipes if +* Returns: {stream.Writable} The _destination_, allowing for a chain of pipes if it is a [`Duplex`][] or a [`Transform`][] stream The `readable.pipe()` method attaches a [`Writable`][] stream to the `readable`, @@ -1137,7 +1173,7 @@ readable.pipe(writable); It is possible to attach multiple `Writable` streams to a single `Readable` stream. -The `readable.pipe()` method returns a reference to the *destination* stream +The `readable.pipe()` method returns a reference to the _destination_ stream making it possible to set up chains of piped streams: ```js @@ -1161,14 +1197,15 @@ reader.on('end', () => { ``` One important caveat is that if the `Readable` stream emits an error during -processing, the `Writable` destination *is not closed* automatically. If an -error occurs, it will be necessary to *manually* close each stream in order +processing, the `Writable` destination _is not closed_ automatically. If an +error occurs, it will be necessary to _manually_ close each stream in order to prevent memory leaks. The [`process.stderr`][] and [`process.stdout`][] `Writable` streams are never closed until the Node.js process exits, regardless of the specified options. ##### `readable.read([size])` + <!-- YAML added: v0.9.4 --> @@ -1183,7 +1220,7 @@ specified using the `readable.setEncoding()` method or the stream is operating in object mode. The optional `size` argument specifies a specific number of bytes to read. If -`size` bytes are not available to be read, `null` will be returned *unless* +`size` bytes are not available to be read, `null` will be returned _unless_ the stream has ended, in which case all of the data remaining in the internal buffer will be returned. @@ -1252,6 +1289,7 @@ Calling [`stream.read([size])`][stream-read] after the [`'end'`][] event has been emitted will return `null`. No runtime error will be raised. ##### `readable.readable` + <!-- YAML added: v11.4.0 --> @@ -1262,6 +1300,7 @@ Is `true` if it is safe to call [`readable.read()`][stream-read], which means the stream has not been destroyed or emitted `'error'` or `'end'`. ##### `readable.readableAborted` + <!-- YAML added: v16.8.0 --> @@ -1273,6 +1312,7 @@ added: v16.8.0 Returns whether the stream was destroyed or errored before emitting `'end'`. ##### `readable.readableDidRead` + <!-- YAML added: - v16.7.0 @@ -1286,6 +1326,7 @@ added: Returns whether `'data'` has been emitted. ##### `readable.readableEncoding` + <!-- YAML added: v12.7.0 --> @@ -1296,6 +1337,7 @@ Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the [`readable.setEncoding()`][] method. ##### `readable.readableEnded` + <!-- YAML added: v12.9.0 --> @@ -1305,6 +1347,7 @@ added: v12.9.0 Becomes `true` when [`'end'`][] event is emitted. ##### `readable.readableFlowing` + <!-- YAML added: v9.4.0 --> @@ -1315,6 +1358,7 @@ This property reflects the current state of a `Readable` stream as described in the [Three states][] section. ##### `readable.readableHighWaterMark` + <!-- YAML added: v9.3.0 --> @@ -1324,6 +1368,7 @@ added: v9.3.0 Returns the value of `highWaterMark` passed when creating this `Readable`. ##### `readable.readableLength` + <!-- YAML added: v9.4.0 --> @@ -1335,6 +1380,7 @@ ready to be read. The value provides introspection data regarding the status of the `highWaterMark`. ##### `readable.readableObjectMode` + <!-- YAML added: v12.3.0 --> @@ -1344,6 +1390,7 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Readable` stream. ##### `readable.resume()` + <!-- YAML added: v0.9.4 changes: @@ -1373,6 +1420,7 @@ The `readable.resume()` method has no effect if there is a `'readable'` event listener. ##### `readable.setEncoding(encoding)` + <!-- YAML added: v0.9.4 --> @@ -1405,6 +1453,7 @@ readable.on('data', (chunk) => { ``` ##### `readable.unpipe([destination])` + <!-- YAML added: v0.9.4 --> @@ -1415,7 +1464,7 @@ added: v0.9.4 The `readable.unpipe()` method detaches a `Writable` stream previously attached using the [`stream.pipe()`][] method. -If the `destination` is not specified, then *all* pipes are detached. +If the `destination` is not specified, then _all_ pipes are detached. If the `destination` is specified, but no pipe is set up for it, then the method does nothing. @@ -1436,6 +1485,7 @@ setTimeout(() => { ``` ##### `readable.unshift(chunk[, encoding])` + <!-- YAML added: v0.9.11 changes: @@ -1514,6 +1564,7 @@ however it is best to simply avoid calling `readable.unshift()` while in the process of performing a read. ##### `readable.wrap(stream)` + <!-- YAML added: v0.9.4 --> @@ -1545,6 +1596,7 @@ myReader.on('readable', () => { ``` ##### `readable[Symbol.asyncIterator]()` + <!-- YAML added: v10.0.0 changes: @@ -1578,6 +1630,7 @@ has less then 64 KB of data because no `highWaterMark` option is provided to [`fs.createReadStream()`][]. ##### `readable.iterator([options])` + <!-- YAML added: v16.3.0 --> @@ -1633,6 +1686,7 @@ showBoth(); ### Duplex and transform streams #### Class: `stream.Duplex` + <!-- YAML added: v0.9.4 changes: @@ -1654,6 +1708,7 @@ Examples of `Duplex` streams include: * [crypto streams][crypto] ##### `duplex.allowHalfOpen` + <!-- YAML added: v0.9.4 --> @@ -1669,6 +1724,7 @@ This can be changed manually to change the half-open behavior of an existing emitted. #### Class: `stream.Transform` + <!-- YAML added: v0.9.4 --> @@ -1685,6 +1741,7 @@ Examples of `Transform` streams include: * [crypto streams][crypto] ##### `transform.destroy([error])` + <!-- YAML added: v8.0.0 changes: @@ -1707,6 +1764,7 @@ Once `destroy()` has been called, any further calls will be a no-op and no further errors except from `_destroy()` may be emitted as `'error'`. ### `stream.finished(stream[, options], callback)` + <!-- YAML added: v10.0.0 changes: @@ -1740,7 +1798,7 @@ changes: the stream ends even though the stream might still be writable. **Default:** `true`. * `signal` {AbortSignal} allows aborting the wait for the stream finish. The - underlying stream will *not* be aborted if the signal is aborted. The + underlying stream will _not_ be aborted if the signal is aborted. The callback will get called with an `AbortError`. All registered listeners added by this function will also be removed. * `callback` {Function} A callback function that takes an optional error @@ -1802,7 +1860,9 @@ const cleanup = finished(rs, (err) => { ``` ### `stream.pipeline(source[, ...transforms], destination, callback)` + ### `stream.pipeline(streams, callback)` + <!-- YAML added: v10.0.0 changes: @@ -1817,7 +1877,7 @@ changes: description: Add support for async generators. --> -* `streams` {Stream[]|Iterable[]|AsyncIterable[]|Function[]} +* `streams` {Stream\[]|Iterable\[]|AsyncIterable\[]|Function\[]} * `source` {Stream|Iterable|AsyncIterable|Function} * Returns: {Iterable|AsyncIterable} * `...transforms` {Stream|Function} @@ -1947,6 +2007,7 @@ run().catch(console.error); ``` `stream.pipeline()` will call `stream.destroy(err)` on all streams except: + * `Readable` streams which have emitted `'end'` or `'close'`. * `Writable` streams which have emitted `'finish'` or `'close'`. @@ -1955,13 +2016,14 @@ after the `callback` has been invoked. In the case of reuse of streams after failure, this can cause event listener leaks and swallowed errors. ### `stream.compose(...streams)` + <!-- YAML added: v16.9.0 --> > Stability: 1 - `stream.compose` is experimental. -* `streams` {Stream[]|Iterable[]|AsyncIterable[]|Function[]} +* `streams` {Stream\[]|Iterable\[]|AsyncIterable\[]|Function\[]} * Returns: {stream.Duplex} Combines two or more streams into a `Duplex` stream that writes to the @@ -2044,6 +2106,7 @@ console.log(res); // prints 'HELLOWORLD' ``` ### `stream.Readable.from(iterable[, options])` + <!-- YAML added: - v12.3.0 @@ -2052,7 +2115,7 @@ added: * `iterable` {Iterable} Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null - value is passed. + value is passed. * `options` {Object} Options provided to `new stream.Readable([options])`. By default, `Readable.from()` will set `options.objectMode` to `true`, unless this is explicitly opted out by setting `options.objectMode` to `false`. @@ -2080,6 +2143,7 @@ the strings or buffers be iterated to match the other streams semantics for performance reasons. ### `stream.Readable.fromWeb(readableStream[, options])` + <!-- YAML added: v16.11.0 --> @@ -2095,6 +2159,7 @@ added: v16.11.0 * Returns: {stream.Readable} ### `stream.Readable.isDisturbed(stream)` + <!-- YAML added: v16.8.0 --> @@ -2107,6 +2172,7 @@ added: v16.8.0 Returns whether the stream has been read from or cancelled. ### `stream.Readable.toWeb(streamReadable)` + <!-- YAML added: v17.0.0 --> @@ -2117,6 +2183,7 @@ added: v17.0.0 * Returns: {ReadableStream} ### `stream.Writable.fromWeb(writableStream[, options])` + <!-- YAML added: v17.0.0 --> @@ -2132,6 +2199,7 @@ added: v17.0.0 * Returns: {stream.Writable} ### `stream.Writable.toWeb(streamWritable)` + <!-- YAML added: v17.0.0 --> @@ -2142,6 +2210,7 @@ added: v17.0.0 * Returns: {WritableStream} ### `stream.Duplex.from(src)` + <!-- YAML added: v16.8.0 --> @@ -2170,6 +2239,7 @@ A utility method for creating duplex streams. * Returns: {stream.Duplex} ### `stream.Duplex.fromWeb(pair[, options])` + <!-- YAML added: v17.0.0 --> @@ -2189,6 +2259,7 @@ added: v17.0.0 * Returns: {stream.Duplex} ### `stream.Duplex.toWeb(streamDuplex)` + <!-- YAML added: v17.0.0 --> @@ -2201,9 +2272,11 @@ added: v17.0.0 * `writable` {WritableStream} ### `stream.addAbortSignal(signal, stream)` + <!-- YAML added: v15.4.0 --> + * `signal` {AbortSignal} A signal representing possible cancellation * `stream` {Stream} a stream to attach a signal to @@ -2249,6 +2322,7 @@ const stream = addAbortSignal( } })(); ``` + ## API for stream implementers <!--type=misc--> @@ -2262,6 +2336,7 @@ of the four basic stream classes (`stream.Writable`, `stream.Readable`, parent class constructor: <!-- eslint-disable no-useless-constructor --> + ```js const { Writable } = require('stream'); @@ -2283,14 +2358,14 @@ options are forwarded instead of implicitly forwarding all options. The new stream class must then implement one or more specific methods, depending on the type of stream being created, as detailed in the chart below: -| Use-case | Class | Method(s) to implement | -| -------- | ----- | ---------------------- | -| Reading only | [`Readable`][] | [`_read()`][stream-_read] | -| Writing only | [`Writable`][] | [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | -| Reading and writing | [`Duplex`][] | [`_read()`][stream-_read], [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | -| Operate on written data, then read the result | [`Transform`][] | [`_transform()`][stream-_transform], [`_flush()`][stream-_flush], [`_final()`][stream-_final] | +| Use-case | Class | Method(s) to implement | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | +| Reading only | [`Readable`][] | [`_read()`][stream-_read] | +| Writing only | [`Writable`][] | [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | +| Reading and writing | [`Duplex`][] | [`_read()`][stream-_read], [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | +| Operate on written data, then read the result | [`Transform`][] | [`_transform()`][stream-_transform], [`_flush()`][stream-_flush], [`_final()`][stream-_final] | -The implementation code for a stream should *never* call the "public" methods +The implementation code for a stream should _never_ call the "public" methods of a stream that are intended for use by consumers (as described in the [API for stream consumers][] section). Doing so may lead to adverse side effects in application code consuming the stream. @@ -2303,6 +2378,7 @@ and/or compatibility issues with other streams, stream utilities, and user expectations. ### Simplified construction + <!-- YAML added: v1.2.0 --> @@ -2332,11 +2408,12 @@ const myWritable = new Writable({ The `stream.Writable` class is extended to implement a [`Writable`][] stream. -Custom `Writable` streams *must* call the `new stream.Writable([options])` +Custom `Writable` streams _must_ call the `new stream.Writable([options])` constructor and implement the `writable._write()` and/or `writable._writev()` method. #### `new stream.Writable([options])` + <!-- YAML changes: - version: v15.5.0 @@ -2392,6 +2469,7 @@ changes: * `signal` {AbortSignal} A signal representing possible cancellation. <!-- eslint-disable no-useless-constructor --> + ```js const { Writable } = require('stream'); @@ -2453,7 +2531,9 @@ const myWritable = new Writable({ // Later, abort the operation closing the stream controller.abort(); ``` + #### `writable._construct(callback)` + <!-- YAML added: v15.0.0 --> @@ -2503,6 +2583,7 @@ class WriteStream extends Writable { ``` #### `writable._write(chunk, encoding, callback)` + <!-- YAML changes: - version: v12.11.0 @@ -2558,7 +2639,7 @@ user programs. #### `writable._writev(chunks, callback)` -* `chunks` {Object[]} The data to be written. The value is an array of {Object} +* `chunks` {Object\[]} The data to be written. The value is an array of {Object} that each represent a discrete chunk of data to write. The properties of these objects are: * `chunk` {Buffer|string} A buffer instance or string containing the data to @@ -2583,6 +2664,7 @@ internal to the class that defines it, and should never be called directly by user programs. #### `writable._destroy(err, callback)` + <!-- YAML added: v8.0.0 --> @@ -2595,6 +2677,7 @@ The `_destroy()` method is called by [`writable.destroy()`][writable-destroy]. It can be overridden by child classes but it **must not** be called directly. #### `writable._final(callback)` + <!-- YAML added: v8.0.0 --> @@ -2700,10 +2783,11 @@ console.log(w.data); // currency: € The `stream.Readable` class is extended to implement a [`Readable`][] stream. -Custom `Readable` streams *must* call the `new stream.Readable([options])` +Custom `Readable` streams _must_ call the `new stream.Readable([options])` constructor and implement the [`readable._read()`][] method. #### `new stream.Readable([options])` + <!-- YAML changes: - version: v15.5.0 @@ -2742,6 +2826,7 @@ changes: * `signal` {AbortSignal} A signal representing possible cancellation. <!-- eslint-disable no-useless-constructor --> + ```js const { Readable } = require('stream'); @@ -2798,6 +2883,7 @@ controller.abort(); ``` #### `readable._construct(callback)` + <!-- YAML added: v15.0.0 --> @@ -2855,6 +2941,7 @@ class ReadStream extends Readable { ``` #### `readable._read(size)` + <!-- YAML added: v0.9.4 --> @@ -2893,6 +2980,7 @@ internal to the class that defines it, and should never be called directly by user programs. #### `readable._destroy(err, callback)` + <!-- YAML added: v8.0.0 --> @@ -2905,6 +2993,7 @@ The `_destroy()` method is called by [`readable.destroy()`][readable-destroy]. It can be overridden by child classes but it **must not** be called directly. #### `readable.push(chunk[, encoding])` + <!-- YAML changes: - version: v8.0.0 @@ -3036,18 +3125,19 @@ A [`Duplex`][] stream is one that implements both [`Readable`][] and Because JavaScript does not have support for multiple inheritance, the `stream.Duplex` class is extended to implement a [`Duplex`][] stream (as opposed -to extending the `stream.Readable` *and* `stream.Writable` classes). +to extending the `stream.Readable` _and_ `stream.Writable` classes). The `stream.Duplex` class prototypically inherits from `stream.Readable` and parasitically from `stream.Writable`, but `instanceof` will work properly for both base classes due to overriding [`Symbol.hasInstance`][] on `stream.Writable`. -Custom `Duplex` streams *must* call the `new stream.Duplex([options])` -constructor and implement *both* the [`readable._read()`][] and +Custom `Duplex` streams _must_ call the `new stream.Duplex([options])` +constructor and implement _both_ the [`readable._read()`][] and `writable._write()` methods. #### `new stream.Duplex(options)` + <!-- YAML changes: - version: v8.4.0 @@ -3075,6 +3165,7 @@ changes: of the stream. Has no effect if `highWaterMark` is provided. <!-- eslint-disable no-useless-constructor --> + ```js const { Duplex } = require('stream'); @@ -3252,8 +3343,8 @@ The `stream.Transform` class is extended to implement a [`Transform`][] stream. The `stream.Transform` class prototypically inherits from `stream.Duplex` and implements its own versions of the `writable._write()` and -[`readable._read()`][] methods. Custom `Transform` implementations *must* -implement the [`transform._transform()`][stream-_transform] method and *may* +[`readable._read()`][] methods. Custom `Transform` implementations _must_ +implement the [`transform._transform()`][stream-_transform] method and _may_ also implement the [`transform._flush()`][stream-_flush] method. Care must be taken when using `Transform` streams in that data written to the @@ -3270,6 +3361,7 @@ output on the `Readable` side is not consumed. method. <!-- eslint-disable no-useless-constructor --> + ```js const { Transform } = require('stream'); @@ -3336,7 +3428,7 @@ store an amount of internal state used to optimally compress the output. When the stream ends, however, that additional data needs to be flushed so that the compressed data will be complete. -Custom [`Transform`][] implementations *may* implement the `transform._flush()` +Custom [`Transform`][] implementations _may_ implement the `transform._flush()` method. This will be called when there is no more written data to be consumed, but before the [`'end'`][] event is emitted signaling the end of the [`Readable`][] stream. @@ -3519,7 +3611,7 @@ less powerful and less useful. were required to store read data into buffers so the data would not be lost. * The [`stream.pause()`][stream-pause] method was advisory, rather than guaranteed. This meant that it was still necessary to be prepared to receive - [`'data'`][] events *even when the stream was in a paused state*. + [`'data'`][] events _even when the stream was in a paused state_. In Node.js 0.10, the [`Readable`][] class was added. For backward compatibility with older Node.js programs, `Readable` streams switch into @@ -3593,7 +3685,7 @@ situations within Node.js where this is done, particularly in the Use of `readable.push('')` is not recommended. Pushing a zero-byte string, `Buffer` or `Uint8Array` to a stream that is not in -object mode has an interesting side effect. Because it *is* a call to +object mode has an interesting side effect. Because it _is_ a call to [`readable.push()`][stream-push], the call will end the reading process. However, because the argument is an empty string, no data is added to the readable buffer so there is nothing for a user to consume. diff --git a/doc/api/string_decoder.md b/doc/api/string_decoder.md index 42a288c7c83..a628a5a8a14 100644 --- a/doc/api/string_decoder.md +++ b/doc/api/string_decoder.md @@ -47,6 +47,7 @@ console.log(decoder.end(Buffer.from([0xAC]))); ## Class: `StringDecoder` ### `new StringDecoder([encoding])` + <!-- YAML added: v0.1.99 --> @@ -57,6 +58,7 @@ added: v0.1.99 Creates a new `StringDecoder` instance. ### `stringDecoder.end([buffer])` + <!-- YAML added: v0.9.3 --> @@ -74,6 +76,7 @@ is performed before returning the remaining input. After `end()` is called, the `stringDecoder` object can be reused for new input. ### `stringDecoder.write(buffer)` + <!-- YAML added: v0.1.99 changes: @@ -88,8 +91,8 @@ changes: * Returns: {string} Returns a decoded string, ensuring that any incomplete multibyte characters at - the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the - returned string and stored in an internal buffer for the next call to - `stringDecoder.write()` or `stringDecoder.end()`. +the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the +returned string and stored in an internal buffer for the next call to +`stringDecoder.write()` or `stringDecoder.end()`. [encoding]: buffer.md#buffers-and-character-encodings diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md index 5bfdebc32c6..cbc1888e201 100644 --- a/doc/api/synopsis.md +++ b/doc/api/synopsis.md @@ -11,6 +11,7 @@ Please see the [Command-line options][] document for more information. ## Example + An example of a [web server][] written with Node.js which responds with `'Hello, World!'`: @@ -48,7 +49,7 @@ Windows PowerShell: ``` Next, create a new source file in the `projects` - folder and call it `hello-world.js`. +folder and call it `hello-world.js`. Open `hello-world.js` in any preferred text editor and paste in the following content: diff --git a/doc/api/timers.md b/doc/api/timers.md index 9105e93a9a6..725b9cb1894 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -26,6 +26,7 @@ running as long as the immediate is active. The `Immediate` object returned by functions that can be used to control this default behavior. ### `immediate.hasRef()` + <!-- YAML added: v11.0.0 --> @@ -35,13 +36,14 @@ added: v11.0.0 If true, the `Immediate` object will keep the Node.js event loop active. ### `immediate.ref()` + <!-- YAML added: v9.7.0 --> * Returns: {Immediate} a reference to `immediate` -When called, requests that the Node.js event loop *not* exit so long as the +When called, requests that the Node.js event loop _not_ exit so long as the `Immediate` is active. Calling `immediate.ref()` multiple times will have no effect. @@ -49,6 +51,7 @@ By default, all `Immediate` objects are "ref'ed", making it normally unnecessary to call `immediate.ref()` unless `immediate.unref()` had been called previously. ### `immediate.unref()` + <!-- YAML added: v9.7.0 --> @@ -73,6 +76,7 @@ export both `timeout.ref()` and `timeout.unref()` functions that can be used to control this default behavior. ### `timeout.close()` + <!-- YAML added: v0.9.1 --> @@ -84,6 +88,7 @@ added: v0.9.1 Cancels the timeout. ### `timeout.hasRef()` + <!-- YAML added: v11.0.0 --> @@ -93,19 +98,21 @@ added: v11.0.0 If true, the `Timeout` object will keep the Node.js event loop active. ### `timeout.ref()` + <!-- YAML added: v0.9.1 --> * Returns: {Timeout} a reference to `timeout` -When called, requests that the Node.js event loop *not* exit so long as the +When called, requests that the Node.js event loop _not_ exit so long as the `Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. By default, all `Timeout` objects are "ref'ed", making it normally unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called previously. ### `timeout.refresh()` + <!-- YAML added: v10.2.0 --> @@ -121,6 +128,7 @@ Using this on a timer that has already called its callback will reactivate the timer. ### `timeout.unref()` + <!-- YAML added: v0.9.1 --> @@ -137,6 +145,7 @@ event loop. Creating too many of these can adversely impact performance of the Node.js application. ### `timeout[Symbol.toPrimitive]()` + <!-- YAML added: - v14.9.0 @@ -160,6 +169,7 @@ which method was used to create the timer and what other work the Node.js event loop is doing. ### `setImmediate(callback[, ...args])` + <!-- YAML added: v0.9.1 --> @@ -184,6 +194,7 @@ This method has a custom variant for promises that is available using [`timersPromises.setImmediate()`][]. ### `setInterval(callback[, delay[, ...args]])` + <!-- YAML added: v0.0.1 --> @@ -205,6 +216,7 @@ This method has a custom variant for promises that is available using [`timersPromises.setInterval()`][]. ### `setTimeout(callback[, delay[, ...args]])` + <!-- YAML added: v0.0.1 --> @@ -277,6 +289,7 @@ ac.abort(); ``` ### `clearImmediate(immediate)` + <!-- YAML added: v0.9.1 --> @@ -287,6 +300,7 @@ added: v0.9.1 Cancels an `Immediate` object created by [`setImmediate()`][]. ### `clearInterval(timeout)` + <!-- YAML added: v0.0.1 --> @@ -297,6 +311,7 @@ added: v0.0.1 Cancels a `Timeout` object created by [`setInterval()`][]. ### `clearTimeout(timeout)` + <!-- YAML added: v0.0.1 --> @@ -307,6 +322,7 @@ added: v0.0.1 Cancels a `Timeout` object created by [`setTimeout()`][]. ## Timers Promises API + <!-- YAML added: v15.0.0 changes: @@ -336,6 +352,7 @@ const { ``` ### `timersPromises.setTimeout([delay[, value[, options]]])` + <!-- YAML added: v15.0.0 --> @@ -371,6 +388,7 @@ setTimeout(100, 'result').then((res) => { ``` ### `timersPromises.setImmediate([value[, options]])` + <!-- YAML added: v15.0.0 --> @@ -404,6 +422,7 @@ setImmediate('result').then((res) => { ``` ### `timersPromises.setInterval([delay[, value[, options]]])` + <!-- YAML added: v15.9.0 --> @@ -411,7 +430,7 @@ added: v15.9.0 Returns an async iterator that generates values in an interval of `delay` ms. * `delay` {number} The number of milliseconds to wait between iterations. - **Default:** `1`. + **Default:** `1`. * `value` {any} A value with which the iterator returns. * `options` {Object} * `ref` {boolean} Set to `false` to indicate that the scheduled `Timeout` diff --git a/doc/api/tls.md b/doc/api/tls.md index ccd1bab90e9..39353c08d00 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -17,7 +17,7 @@ const tls = require('tls'); ## TLS/SSL concepts The TLS/SSL is a public/private key infrastructure (PKI). For most common -cases, each client and server must have a *private key*. +cases, each client and server must have a _private key_. Private keys can be generated in multiple ways. The example below illustrates use of the OpenSSL command-line interface to generate a 2048-bit RSA private @@ -27,11 +27,11 @@ key: openssl genrsa -out ryans-key.pem 2048 ``` -With TLS/SSL, all servers (and some clients) must have a *certificate*. -Certificates are *public keys* that correspond to a private key, and that are +With TLS/SSL, all servers (and some clients) must have a _certificate_. +Certificates are _public keys_ that correspond to a private key, and that are digitally signed either by a Certificate Authority or by the owner of the private key (such certificates are referred to as "self-signed"). The first -step to obtaining a certificate is to create a *Certificate Signing Request* +step to obtaining a certificate is to create a _Certificate Signing Request_ (CSR) file. The OpenSSL command-line interface can be used to generate a CSR for a private @@ -64,7 +64,7 @@ Where: * `in`: is the signed certificate * `inkey`: is the associated private key * `certfile`: is a concatenation of all Certificate Authority (CA) certs into - a single file, e.g. `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` + a single file, e.g. `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` ### Perfect forward secrecy @@ -190,7 +190,7 @@ send it to the client. Clients and servers save the session state. When reconnecting, clients send the ID of their saved session state and if the server also has the state for that ID, it can agree to use it. Otherwise, the server will create a new session. See [RFC 2246][] for more information, page 23 and -30. +30\. Resumption using session identifiers is supported by most web browsers when making HTTPS requests. @@ -237,8 +237,8 @@ securely generate 48 bytes of secure random data and set them with the regenerated and server's keys can be reset with [`server.setTicketKeys()`][]. -Session ticket keys are cryptographic keys, and they ***must be stored -securely***. With TLS 1.2 and below, if they are compromised all sessions that +Session ticket keys are cryptographic keys, and they _**must be stored +securely**_. With TLS 1.2 and below, if they are compromised all sessions that used tickets encrypted with them can be decrypted. They should not be stored on disk, and they should be regenerated regularly. @@ -280,6 +280,7 @@ default cipher list can be configured when building Node.js to allow distributions to provide their own default list. The following command can be used to show the default cipher suite: + ```console node -p crypto.constants.defaultCoreCipherList | tr ':' '\n' TLS_AES_256_GCM_SHA384 @@ -329,7 +330,7 @@ The ciphers list can contain a mixture of TLSv1.3 cipher suite names, the ones that start with `'TLS_'`, and specifications for TLSv1.2 and below cipher suites. The TLSv1.2 ciphers support a legacy specification format, consult the OpenSSL [cipher list format][] documentation for details, but those -specifications do *not* apply to TLSv1.3 ciphers. The TLSv1.3 suites can only +specifications do _not_ apply to TLSv1.3 ciphers. The TLSv1.3 suites can only be enabled by including their full name in the cipher list. They cannot, for example, be enabled or disabled by using the legacy TLSv1.2 `'EECDH'` or `'!EECDH'` specification. @@ -347,7 +348,7 @@ used only if absolutely necessary. The default cipher suite prefers GCM ciphers for [Chrome's 'modern cryptography' setting][] and also prefers ECDHE and DHE ciphers for perfect -forward secrecy, while offering *some* backward compatibility. +forward secrecy, while offering _some_ backward compatibility. 128 bit AES is preferred over 192 and 256 bit AES in light of [specific attacks affecting larger AES key sizes][]. @@ -380,6 +381,7 @@ has the property `code` which can take one of the following values: values are taken from src/crypto/crypto_common.cc description are taken from deps/openssl/openssl/crypto/x509/x509_txt.c --> + * `'UNABLE_TO_GET_ISSUER_CERT'`: Unable to get issuer certificate. * `'UNABLE_TO_GET_CRL'`: Unable to get certificate CRL. * `'UNABLE_TO_DECRYPT_CERT_SIGNATURE'`: Unable to decrypt certificate's @@ -413,6 +415,7 @@ description are taken from deps/openssl/openssl/crypto/x509/x509_txt.c * `'HOSTNAME_MISMATCH'`: Hostname mismatch. ## Class: `tls.CryptoStream` + <!-- YAML added: v0.3.4 deprecated: v0.11.3 @@ -424,16 +427,18 @@ The `tls.CryptoStream` class represents a stream of encrypted data. This class is deprecated and should no longer be used. ### `cryptoStream.bytesWritten` + <!-- YAML added: v0.3.4 deprecated: v0.11.3 --> The `cryptoStream.bytesWritten` property returns the total number of bytes -written to the underlying socket *including* the bytes required for the +written to the underlying socket _including_ the bytes required for the implementation of the TLS protocol. ## Class: `tls.SecurePair` + <!-- YAML added: v0.3.2 deprecated: v0.11.3 @@ -444,6 +449,7 @@ deprecated: v0.11.3 Returned by [`tls.createSecurePair()`][]. ### Event: `'secure'` + <!-- YAML added: v0.3.2 deprecated: v0.11.3 @@ -458,6 +464,7 @@ event, `pair.cleartext.authorized` should be inspected to confirm whether the certificate used is properly authorized. ## Class: `tls.Server` + <!-- YAML added: v0.3.2 --> @@ -467,6 +474,7 @@ added: v0.3.2 Accepts encrypted connections using TLS or SSL. ### Event: `'connection'` + <!-- YAML added: v0.3.2 --> @@ -481,6 +489,7 @@ This event can also be explicitly emitted by users to inject connections into the TLS server. In that case, any [`Duplex`][] stream can be passed. ### Event: `'keylog'` + <!-- YAML added: - v12.3.0 @@ -511,6 +520,7 @@ server.on('keylog', (line, tlsSocket) => { ``` ### Event: `'newSession'` + <!-- YAML added: v0.9.2 changes: @@ -534,6 +544,7 @@ Listening for this event will have an effect only on connections established after the addition of the event listener. ### Event: `'OCSPRequest'` + <!-- YAML added: v0.11.13 --> @@ -581,6 +592,7 @@ after the addition of the event listener. An npm module like [asn1.js][] may be used to parse the certificates. ### Event: `'resumeSession'` + <!-- YAML added: v0.9.2 --> @@ -620,6 +632,7 @@ server.on('resumeSession', (id, cb) => { ``` ### Event: `'secureConnection'` + <!-- YAML added: v0.3.2 --> @@ -644,6 +657,7 @@ The `tlsSocket.servername` property is a string containing the server name requested via SNI. ### Event: `'tlsClientError'` + <!-- YAML added: v6.0.0 --> @@ -657,6 +671,7 @@ called: error originated. ### `server.addContext(hostname, context)` + <!-- YAML added: v0.5.3 --> @@ -673,6 +688,7 @@ When there are multiple matching contexts, the most recently added one is used. ### `server.address()` + <!-- YAML added: v0.6.0 --> @@ -684,6 +700,7 @@ server as reported by the operating system. See [`net.Server.address()`][] for more information. ### `server.close([callback])` + <!-- YAML added: v0.3.2 --> @@ -698,6 +715,7 @@ This function operates asynchronously. The `'close'` event will be emitted when the server has no more open connections. ### `server.getTicketKeys()` + <!-- YAML added: v3.0.0 --> @@ -714,6 +732,7 @@ Starts the server listening for encrypted connections. This method is identical to [`server.listen()`][] from [`net.Server`][]. ### `server.setSecureContext(options)` + <!-- YAML added: v11.0.0 --> @@ -726,6 +745,7 @@ The `server.setSecureContext()` method replaces the secure context of an existing server. Existing connections to the server are not interrupted. ### `server.setTicketKeys(keys)` + <!-- YAML added: v3.0.0 --> @@ -741,6 +761,7 @@ Existing or currently pending server connections will use the previous keys. See [Session Resumption][] for more information. ## Class: `tls.TLSSocket` + <!-- YAML added: v0.11.4 --> @@ -757,6 +778,7 @@ Methods that return TLS connection metadata (e.g. connection is open. ### `new tls.TLSSocket(socket[, options])` + <!-- YAML added: v0.11.4 changes: @@ -779,9 +801,9 @@ changes: instantiated as a server. **Default:** `false`. * `server` {net.Server} A [`net.Server`][] instance. * `requestCert`: Whether to authenticate the remote peer by requesting a - certificate. Clients always request a server certificate. Servers - (`isServer` is true) may set `requestCert` to true to request a client - certificate. + certificate. Clients always request a server certificate. Servers + (`isServer` is true) may set `requestCert` to true to request a client + certificate. * `rejectUnauthorized`: See [`tls.createServer()`][] * `ALPNProtocols`: See [`tls.createServer()`][] * `SNICallback`: See [`tls.createServer()`][] @@ -799,6 +821,7 @@ changes: Construct a new `tls.TLSSocket` object from an existing TCP socket. ### Event: `'keylog'` + <!-- YAML added: - v12.3.0 @@ -822,6 +845,7 @@ tlsSocket.on('keylog', (line) => logFile.write(line)); ``` ### Event: `'OCSPResponse'` + <!-- YAML added: v0.11.13 --> @@ -836,6 +860,7 @@ Typically, the `response` is a digitally signed object from the server's CA that contains information about server's certificate revocation status. ### Event: `'secureConnect'` + <!-- YAML added: v0.11.4 --> @@ -854,6 +879,7 @@ The `'secureConnect'` event is not emitted when a {tls.TLSSocket} is created using the `new tls.TLSSocket()` constructor. ### Event: `'session'` + <!-- YAML added: v11.10.0 --> @@ -893,6 +919,7 @@ tlsSocket.once('session', (session) => { ``` ### `tlsSocket.address()` + <!-- YAML added: v0.11.4 --> @@ -904,6 +931,7 @@ underlying socket as reported by the operating system: `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`. ### `tlsSocket.authorizationError` + <!-- YAML added: v0.11.4 --> @@ -912,6 +940,7 @@ Returns the reason why the peer's certificate was not been verified. This property is set only when `tlsSocket.authorized === false`. ### `tlsSocket.authorized` + <!-- YAML added: v0.11.4 --> @@ -922,6 +951,7 @@ Returns `true` if the peer certificate was signed by one of the CAs specified when creating the `tls.TLSSocket` instance, otherwise `false`. ### `tlsSocket.disableRenegotiation()` + <!-- YAML added: v8.4.0 --> @@ -930,6 +960,7 @@ Disables TLS renegotiation for this `TLSSocket` instance. Once called, attempts to renegotiate will trigger an `'error'` event on the `TLSSocket`. ### `tlsSocket.enableTrace()` + <!-- YAML added: v12.2.0 --> @@ -937,12 +968,13 @@ added: v12.2.0 When enabled, TLS packet trace information is written to `stderr`. This can be used to debug TLS connection problems. -Note: The format of the output is identical to the output of `openssl s_client --trace` or `openssl s_server -trace`. While it is produced by OpenSSL's -`SSL_trace()` function, the format is undocumented, can change without notice, -and should not be relied on. +The format of the output is identical to the output of +`openssl s_client -trace` or `openssl s_server -trace`. While it is produced by +OpenSSL's `SSL_trace()` function, the format is undocumented, can change +without notice, and should not be relied on. ### `tlsSocket.encrypted` + <!-- YAML added: v0.11.4 --> @@ -951,6 +983,7 @@ Always returns `true`. This may be used to distinguish TLS sockets from regular `net.Socket` instances. ### `tlsSocket.exportKeyingMaterial(length, label[, context])` + <!-- YAML added: - v13.10.0 @@ -958,9 +991,11 @@ added: --> * `length` {number} number of bytes to retrieve from keying material + * `label` {string} an application specific label, typically this will be a value from the [IANA Exporter Label Registry](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels). + * `context` {Buffer} Optionally provide a context. * Returns: {Buffer} requested bytes of the keying material @@ -982,10 +1017,12 @@ const keyingMaterial = tlsSocket.exportKeyingMaterial( 74 ef 2c ... 78 more bytes> */ ``` + See the OpenSSL [`SSL_export_keying_material`][] documentation for more information. ### `tlsSocket.getCertificate()` + <!-- YAML added: v11.2.0 --> @@ -1002,6 +1039,7 @@ If there is no local certificate, an empty object will be returned. If the socket has been destroyed, `null` will be returned. ### `tlsSocket.getCipher()` + <!-- YAML added: v0.11.4 changes: @@ -1025,6 +1063,7 @@ changes: Returns an object containing information on the negotiated cipher suite. For example: + ```json { "name": "AES128-SHA256", @@ -1034,10 +1073,11 @@ For example: ``` See -[SSL_CIPHER_get_name](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html) +[SSL\_CIPHER\_get\_name](https://www.openssl.org/docs/man1.1.1/man3/SSL\_CIPHER\_get\_name.html) for more information. ### `tlsSocket.getEphemeralKeyInfo()` + <!-- YAML added: v5.0.0 --> @@ -1054,6 +1094,7 @@ if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The For example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }`. ### `tlsSocket.getFinished()` + <!-- YAML added: v9.9.0 --> @@ -1071,6 +1112,7 @@ Corresponds to the `SSL_get_finished` routine in OpenSSL and may be used to implement the `tls-unique` channel binding from [RFC 5929][]. ### `tlsSocket.getPeerCertificate([detailed])` + <!-- YAML added: v0.11.4 --> @@ -1088,6 +1130,7 @@ If the full certificate chain was requested, each certificate will include an certificate. #### Certificate object + <!-- YAML changes: - version: v11.4.0 @@ -1100,28 +1143,28 @@ certificate. * `raw` {Buffer} The DER encoded X.509 certificate data. * `subject` {Object} The certificate subject, described in terms of - Country (`C:`), StateOrProvince (`ST`), Locality (`L`), Organization (`O`), - OrganizationalUnit (`OU`), and CommonName (`CN`). The CommonName is typically - a DNS name with TLS certificates. Example: - `{C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}`. + Country (`C:`), StateOrProvince (`ST`), Locality (`L`), Organization (`O`), + OrganizationalUnit (`OU`), and CommonName (`CN`). The CommonName is typically + a DNS name with TLS certificates. Example: + `{C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}`. * `issuer` {Object} The certificate issuer, described in the same terms as the - `subject`. + `subject`. * `valid_from` {string} The date-time the certificate is valid from. * `valid_to` {string} The date-time the certificate is valid to. * `serialNumber` {string} The certificate serial number, as a hex string. - Example: `'B9B0D332A1AA5635'`. + Example: `'B9B0D332A1AA5635'`. * `fingerprint` {string} The SHA-1 digest of the DER encoded certificate. It is returned as a `:` separated hexadecimal string. Example: `'2A:7A:C2:DD:...'`. * `fingerprint256` {string} The SHA-256 digest of the DER encoded certificate. - It is returned as a `:` separated hexadecimal string. Example: - `'2A:7A:C2:DD:...'`. + It is returned as a `:` separated hexadecimal string. Example: + `'2A:7A:C2:DD:...'`. * `ext_key_usage` {Array} (Optional) The extended key usage, a set of OIDs. * `subjectaltname` {string} (Optional) A string containing concatenated names - for the subject, an alternative to the `subject` names. + for the subject, an alternative to the `subject` names. * `infoAccess` {Array} (Optional) An array describing the AuthorityInfoAccess, - used with OCSP. + used with OCSP. * `issuerCertificate` {Object} (Optional) The issuer certificate object. For - self-signed certificates, this may be a circular reference. + self-signed certificates, this may be a circular reference. The certificate may contain information about the public key, depending on the key type. @@ -1132,7 +1175,7 @@ For RSA keys, the following properties may be defined: * `exponent` {string} The RSA exponent, as a string in hexadecimal number notation. Example: `'0x010001'`. * `modulus` {string} The RSA modulus, as a hexadecimal string. Example: - `'B56CE45CB7...'`. + `'B56CE45CB7...'`. * `pubkey` {Buffer} The public key. For EC keys, the following properties may be defined: @@ -1150,6 +1193,7 @@ For EC keys, the following properties may be defined: Example certificate: <!-- eslint-skip --> + ```js { subject: { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ], @@ -1178,6 +1222,7 @@ Example certificate: ``` ### `tlsSocket.getPeerFinished()` + <!-- YAML added: v9.9.0 --> @@ -1195,6 +1240,7 @@ Corresponds to the `SSL_get_peer_finished` routine in OpenSSL and may be used to implement the `tls-unique` channel binding from [RFC 5929][]. ### `tlsSocket.getPeerX509Certificate()` + <!-- YAML added: v15.9.0 --> @@ -1207,6 +1253,7 @@ If there is no peer certificate, or the socket has been destroyed, `undefined` will be returned. ### `tlsSocket.getProtocol()` + <!-- YAML added: v5.7.0 --> @@ -1229,6 +1276,7 @@ Protocol versions are: See the OpenSSL [`SSL_get_version`][] documentation for more information. ### `tlsSocket.getSession()` + <!-- YAML added: v0.11.4 --> @@ -1246,6 +1294,7 @@ Note: `getSession()` works only for TLSv1.2 and below. For TLSv1.3, applications must use the [`'session'`][] event (it also works for TLSv1.2 and below). ### `tlsSocket.getSharedSigalgs()` + <!-- YAML added: v12.11.0 --> @@ -1254,10 +1303,11 @@ added: v12.11.0 the client in the order of decreasing preference. See -[SSL_get_shared_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) +[SSL\_get\_shared\_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL\_get\_shared\_sigalgs.html) for more information. ### `tlsSocket.getTLSTicket()` + <!-- YAML added: v0.11.4 --> @@ -1272,6 +1322,7 @@ It may be useful for debugging. See [Session Resumption][] for more information. ### `tlsSocket.getX509Certificate()` + <!-- YAML added: v15.9.0 --> @@ -1284,6 +1335,7 @@ If there is no local certificate, or the socket has been destroyed, `undefined` will be returned. ### `tlsSocket.isSessionReused()` + <!-- YAML added: v0.5.6 --> @@ -1293,6 +1345,7 @@ added: v0.5.6 See [Session Resumption][] for more information. ### `tlsSocket.localAddress` + <!-- YAML added: v0.11.4 --> @@ -1302,6 +1355,7 @@ added: v0.11.4 Returns the string representation of the local IP address. ### `tlsSocket.localPort` + <!-- YAML added: v0.11.4 --> @@ -1311,6 +1365,7 @@ added: v0.11.4 Returns the numeric representation of the local port. ### `tlsSocket.remoteAddress` + <!-- YAML added: v0.11.4 --> @@ -1321,6 +1376,7 @@ Returns the string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. ### `tlsSocket.remoteFamily` + <!-- YAML added: v0.11.4 --> @@ -1330,6 +1386,7 @@ added: v0.11.4 Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`. ### `tlsSocket.remotePort` + <!-- YAML added: v0.11.4 --> @@ -1339,6 +1396,7 @@ added: v0.11.4 Returns the numeric representation of the remote port. For example, `443`. ### `tlsSocket.renegotiate(options, callback)` + <!-- YAML added: v0.11.8 --> @@ -1349,11 +1407,12 @@ added: v0.11.8 verification fails; `err.code` contains the OpenSSL error code. **Default:** `true`. * `requestCert` + * `callback` {Function} If `renegotiate()` returned `true`, callback is - attached once to the `'secure'` event. If `renegotiate()` returned `false`, - `callback` will be called in the next tick with an error, unless the - `tlsSocket` has been destroyed, in which case `callback` will not be called - at all. + attached once to the `'secure'` event. If `renegotiate()` returned `false`, + `callback` will be called in the next tick with an error, unless the + `tlsSocket` has been destroyed, in which case `callback` will not be called + at all. * Returns: {boolean} `true` if renegotiation was initiated, `false` otherwise. @@ -1371,6 +1430,7 @@ For TLSv1.3, renegotiation cannot be initiated, it is not supported by the protocol. ### `tlsSocket.setMaxSendFragment(size)` + <!-- YAML added: v0.11.11 --> @@ -1390,6 +1450,7 @@ smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput. ## `tls.checkServerIdentity(hostname, cert)` + <!-- YAML added: v0.8.4 --> @@ -1413,6 +1474,7 @@ This function is only called if the certificate passed all other checks, such as being issued by trusted CA (`options.ca`). ## `tls.connect(options[, callback])` + <!-- YAML added: v0.11.3 changes: @@ -1487,6 +1549,7 @@ changes: verification fails; `err.code` contains the OpenSSL error code. **Default:** `true`. * `pskCallback` {Function} + * hint: {string} optional message sent from the server to help client decide which identity to use during negotiation. Always `null` if TLS 1.3 is used. @@ -1504,7 +1567,7 @@ changes: of the server against the certificate but that's not applicable for PSK because there won't be a certificate present. More information can be found in the [RFC 4279][]. - * `ALPNProtocols`: {string[]|Buffer[]|TypedArray[]|DataView[]|Buffer| + * `ALPNProtocols`: {string\[]|Buffer\[]|TypedArray\[]|DataView\[]|Buffer| TypedArray|DataView} An array of strings, `Buffer`s or `TypedArray`s or `DataView`s, or a single `Buffer` or `TypedArray` or `DataView` containing the supported ALPN @@ -1592,6 +1655,7 @@ socket.on('end', () => { ``` ## `tls.connect(path[, options][, callback])` + <!-- YAML added: v0.11.3 --> @@ -1607,6 +1671,7 @@ as an argument instead of an option. A path option, if specified, will take precedence over the path argument. ## `tls.connect(port[, host][, options][, callback])` + <!-- YAML added: v0.11.3 --> @@ -1624,6 +1689,7 @@ A port or host option, if specified, will take precedence over any port or host argument. ## `tls.createSecureContext([options])` + <!-- YAML added: v0.11.13 changes: @@ -1670,7 +1736,7 @@ changes: --> * `options` {Object} - * `ca` {string|string[]|Buffer|Buffer[]} Optionally override the trusted CA + * `ca` {string|string\[]|Buffer|Buffer\[]} Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CAs are explicitly specified using this option. The value can be a string or `Buffer`, or an `Array` of @@ -1688,20 +1754,20 @@ changes: For PEM encoded certificates, supported types are "TRUSTED CERTIFICATE", "X509 CERTIFICATE", and "CERTIFICATE". See also [`tls.rootCertificates`][]. - * `cert` {string|string[]|Buffer|Buffer[]} Cert chains in PEM format. One cert - chain should be provided per private key. Each cert chain should consist of - the PEM formatted certificate for a provided private `key`, followed by the - PEM formatted intermediate certificates (if any), in order, and not - including the root CA (the root CA must be pre-known to the peer, see `ca`). - When providing multiple cert chains, they do not have to be in the same - order as their private keys in `key`. If the intermediate certificates are - not provided, the peer will not be able to validate the certificate, and the - handshake will fail. + * `cert` {string|string\[]|Buffer|Buffer\[]} Cert chains in PEM format. One + cert chain should be provided per private key. Each cert chain should + consist of the PEM formatted certificate for a provided private `key`, + followed by the PEM formatted intermediate certificates (if any), in order, + and not including the root CA (the root CA must be pre-known to the peer, + see `ca`). When providing multiple cert chains, they do not have to be in + the same order as their private keys in `key`. If the intermediate + certificates are not provided, the peer will not be able to validate the + certificate, and the handshake will fail. * `sigalgs` {string} Colon-separated list of supported signature algorithms. The list can contain digest algorithms (`SHA256`, `MD5` etc.), public key algorithms (`RSA-PSS`, `ECDSA` etc.), combination of both (e.g 'RSA+SHA384') or TLS v1.3 scheme names (e.g. `rsa_pss_pss_sha512`). - See [OpenSSL man pages](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_sigalgs_list.html) + See [OpenSSL man pages](https://www.openssl.org/docs/man1.1.1/man3/SSL\_CTX\_set1\_sigalgs\_list.html) for more info. * `ciphers` {string} Cipher suite specification, replacing the default. For more information, see [modifying the default cipher suite][]. Permitted @@ -1709,7 +1775,7 @@ changes: uppercased in order for OpenSSL to accept them. * `clientCertEngine` {string} Name of an OpenSSL engine which can provide the client certificate. - * `crl` {string|string[]|Buffer|Buffer[]} PEM formatted CRLs (Certificate + * `crl` {string|string\[]|Buffer|Buffer\[]} PEM formatted CRLs (Certificate Revocation Lists). * `dhparam` {string|Buffer} Diffie-Hellman parameters, required for [perfect forward secrecy][]. Use `openssl dhparam` to create the parameters. @@ -1728,11 +1794,11 @@ changes: preferences instead of the client's. When `true`, causes `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see [OpenSSL Options][] for more information. - * `key` {string|string[]|Buffer|Buffer[]|Object[]} Private keys in PEM format. - PEM allows the option of private keys being encrypted. Encrypted keys will - be decrypted with `options.passphrase`. Multiple keys using different - algorithms can be provided either as an array of unencrypted key strings or - buffers, or an array of objects in the form + * `key` {string|string\[]|Buffer|Buffer\[]|Object\[]} Private keys in PEM + format. PEM allows the option of private keys being encrypted. Encrypted + keys will be decrypted with `options.passphrase`. Multiple keys using + different algorithms can be provided either as an array of unencrypted key + strings or buffers, or an array of objects in the form `{pem: <string|buffer>[, passphrase: <string>]}`. The object form can only occur in an array. `object.passphrase` is optional. Encrypted keys will be decrypted with `object.passphrase` if provided, or `options.passphrase` if @@ -1755,7 +1821,7 @@ changes: **Default:** [`tls.DEFAULT_MIN_VERSION`][]. * `passphrase` {string} Shared passphrase used for a single private key and/or a PFX. - * `pfx` {string|string[]|Buffer|Buffer[]|Object[]} PFX or PKCS12 encoded + * `pfx` {string|string\[]|Buffer|Buffer\[]|Object\[]} PFX or PKCS12 encoded private key and certificate chain. `pfx` is an alternative to providing `key` and `cert` individually. PFX is usually encrypted, if it is, `passphrase` will be used to decrypt it. Multiple PFX can be provided either @@ -1772,9 +1838,9 @@ changes: version to use, it does not support independent control of the minimum and maximum version, and does not support limiting the protocol to TLSv1.3. Use `minVersion` and `maxVersion` instead. The possible values are listed as - [SSL_METHODS][], use the function names as strings. For example, use - `'TLSv1_1_method'` to force TLS version 1.1, or `'TLS_method'` to allow any - TLS protocol version up to TLSv1.3. It is not recommended to use TLS + [SSL\_METHODS][SSL_METHODS], use the function names as strings. For example, + use `'TLSv1_1_method'` to force TLS version 1.1, or `'TLS_method'` to allow + any TLS protocol version up to TLSv1.3. It is not recommended to use TLS versions less than 1.2, but it may be required for interoperability. **Default:** none, see `minVersion`. * `sessionIdContext` {string} Opaque identifier used by servers to ensure @@ -1796,13 +1862,14 @@ The `tls.createSecureContext()` method creates a `SecureContext` object. It is usable as an argument to several `tls` APIs, such as [`tls.createServer()`][] and [`server.addContext()`][], but has no public methods. -A key is *required* for ciphers that use certificates. Either `key` or +A key is _required_ for ciphers that use certificates. Either `key` or `pfx` can be used to provide it. If the `ca` option is not given, then Node.js will default to using [Mozilla's publicly trusted list of CAs][]. ## `tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])` + <!-- YAML added: v0.3.2 deprecated: v0.11.3 @@ -1866,6 +1933,7 @@ secureSocket = tls.TLSSocket(socket, options); where `secureSocket` has the same API as `pair.cleartext`. ## `tls.createServer([options][, secureConnectionListener])` + <!-- YAML added: v0.3.2 changes: @@ -1886,7 +1954,7 @@ changes: --> * `options` {Object} - * `ALPNProtocols`: {string[]|Buffer[]|TypedArray[]|DataView[]|Buffer| + * `ALPNProtocols`: {string\[]|Buffer\[]|TypedArray\[]|DataView\[]|Buffer| TypedArray|DataView} An array of strings, `Buffer`s or `TypedArray`s or `DataView`s, or a single `Buffer` or `TypedArray` or `DataView` containing the supported ALPN @@ -1925,6 +1993,7 @@ changes: * `ticketKeys`: {Buffer} 48-bytes of cryptographically strong pseudorandom data. See [Session Resumption][] for more information. * `pskCallback` {Function} + * socket: {tls.TLSSocket} the server [`tls.TLSSocket`][] instance for this connection. * identity: {string} identity parameter sent from the client. @@ -1935,10 +2004,10 @@ changes: When negotiating TLS-PSK (pre-shared keys), this function is called with the identity provided by the client. If the return value is `null` the negotiation process will stop and an - "unknown_psk_identity" alert message will be sent to the other party. + "unknown\_psk\_identity" alert message will be sent to the other party. If the server wishes to hide the fact that the PSK identity was not known, the callback must provide some random data as `psk` to make the connection - fail with "decrypt_error" before negotiation is finished. + fail with "decrypt\_error" before negotiation is finished. PSK ciphers are disabled by default, and using TLS-PSK thus requires explicitly specifying a cipher suite with the `ciphers` option. More information can be found in the [RFC 4279][]. @@ -1992,11 +2061,12 @@ The server can be tested by connecting to it using the example client from [`tls.connect()`][]. ## `tls.getCiphers()` + <!-- YAML added: v0.10.2 --> -* Returns: {string[]} +* Returns: {string\[]} Returns an array with the names of the supported TLS ciphers. The names are lower-case for historical reasons, but must be uppercased to be used in @@ -2010,11 +2080,12 @@ console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...] ``` ## `tls.rootCertificates` + <!-- YAML added: v12.3.0 --> -* {string[]} +* {string\[]} An immutable array of strings representing the root certificates (in PEM format) from the bundled Mozilla CA store as supplied by current Node.js version. @@ -2023,6 +2094,7 @@ The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store that is fixed at release time. It is identical on all supported platforms. ## `tls.DEFAULT_ECDH_CURVE` + <!-- YAML added: v0.11.13 changes: @@ -2036,6 +2108,7 @@ default value is `'auto'`. See [`tls.createSecureContext()`][] for further information. ## `tls.DEFAULT_MAX_VERSION` + <!-- YAML added: v11.4.0 --> @@ -2049,6 +2122,7 @@ added: v11.4.0 highest maximum is used. ## `tls.DEFAULT_MIN_VERSION` + <!-- YAML added: v11.4.0 --> diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 4b7a9bd8ff1..d0b5ac4250e 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -44,7 +44,7 @@ node --trace-event-categories v8,node,node.async_hooks server.js Prior versions of Node.js required the use of the `--trace-events-enabled` flag to enable trace events. This requirement has been removed. However, the -`--trace-events-enabled` flag *may* still be used and will enable the +`--trace-events-enabled` flag _may_ still be used and will enable the `node`, `node.async_hooks`, and `v8` trace event categories by default. ```bash @@ -88,11 +88,13 @@ unlike `process.hrtime()` which returns nanoseconds. The features from this module are not available in [`Worker`][] threads. ## The `trace_events` module + <!-- YAML added: v10.0.0 --> ### `Tracing` object + <!-- YAML added: v10.0.0 --> @@ -107,6 +109,7 @@ categories. Calling `tracing.disable()` will remove the categories from the set of enabled trace event categories. #### `tracing.categories` + <!-- YAML added: v10.0.0 --> @@ -117,14 +120,15 @@ A comma-separated list of the trace event categories covered by this `Tracing` object. #### `tracing.disable()` + <!-- YAML added: v10.0.0 --> Disables this `Tracing` object. -Only trace event categories *not* covered by other enabled `Tracing` objects -and *not* specified by the `--trace-event-categories` flag will be disabled. +Only trace event categories _not_ covered by other enabled `Tracing` objects +and _not_ specified by the `--trace-event-categories` flag will be disabled. ```js const trace_events = require('trace_events'); @@ -143,6 +147,7 @@ console.log(trace_events.getEnabledCategories()); ``` #### `tracing.enable()` + <!-- YAML added: v10.0.0 --> @@ -151,6 +156,7 @@ Enables this `Tracing` object for the set of categories covered by the `Tracing` object. #### `tracing.enabled` + <!-- YAML added: v10.0.0 --> @@ -158,12 +164,13 @@ added: v10.0.0 * {boolean} `true` only if the `Tracing` object has been enabled. ### `trace_events.createTracing(options)` + <!-- YAML added: v10.0.0 --> * `options` {Object} - * `categories` {string[]} An array of trace category names. Values included + * `categories` {string\[]} An array of trace category names. Values included in the array are coerced to a string when possible. An error will be thrown if the value cannot be coerced. * Returns: {Tracing}. @@ -180,6 +187,7 @@ tracing.disable(); ``` ### `trace_events.getEnabledCategories()` + <!-- YAML added: v10.0.0 --> @@ -188,7 +196,7 @@ added: v10.0.0 Returns a comma-separated list of all currently-enabled trace event categories. The current set of enabled trace event categories is determined -by the *union* of all currently-enabled `Tracing` objects and any categories +by the _union_ of all currently-enabled `Tracing` objects and any categories enabled using the `--trace-event-categories` flag. Given the file `test.js` below, the command diff --git a/doc/api/tty.md b/doc/api/tty.md index 10eb874e561..ea0640274f7 100644 --- a/doc/api/tty.md +++ b/doc/api/tty.md @@ -33,6 +33,7 @@ manually create instances of the `tty.ReadStream` and `tty.WriteStream` classes. ## Class: `tty.ReadStream` + <!-- YAML added: v0.5.8 --> @@ -44,6 +45,7 @@ Represents the readable side of a TTY. In normal circumstances process and there should be no reason to create additional instances. ### `readStream.isRaw` + <!-- YAML added: v0.7.7 --> @@ -52,6 +54,7 @@ A `boolean` that is `true` if the TTY is currently configured to operate as a raw device. Defaults to `false`. ### `readStream.isTTY` + <!-- YAML added: v0.5.8 --> @@ -59,6 +62,7 @@ added: v0.5.8 A `boolean` that is always `true` for `tty.ReadStream` instances. ### `readStream.setRawMode(mode)` + <!-- YAML added: v0.7.7 --> @@ -73,10 +77,12 @@ Allows configuration of `tty.ReadStream` so that it operates as a raw device. When in raw mode, input is always available character-by-character, not including modifiers. Additionally, all special processing of characters by the -terminal is disabled, including echoing input characters. -<kbd>Ctrl</kbd>+<kbd>C</kbd> will no longer cause a `SIGINT` when in this mode. +terminal is disabled, including echoing input +characters. <kbd>Ctrl</kbd>+<kbd>C</kbd> will no longer cause a `SIGINT` when +in this mode. ## Class: `tty.WriteStream` + <!-- YAML added: v0.5.8 --> @@ -89,6 +95,7 @@ Represents the writable side of a TTY. In normal circumstances, should be no reason to create additional instances. ### Event: `'resize'` + <!-- YAML added: v0.7.7 --> @@ -105,6 +112,7 @@ process.stdout.on('resize', () => { ``` ### `writeStream.clearLine(dir[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -126,6 +134,7 @@ changes: direction identified by `dir`. ### `writeStream.clearScreenDown([callback])` + <!-- YAML added: v0.7.7 changes: @@ -143,6 +152,7 @@ changes: cursor down. ### `writeStream.columns` + <!-- YAML added: v0.7.7 --> @@ -151,6 +161,7 @@ A `number` specifying the number of columns the TTY currently has. This property is updated whenever the `'resize'` event is emitted. ### `writeStream.cursorTo(x[, y][, callback])` + <!-- YAML added: v0.7.7 changes: @@ -170,6 +181,7 @@ changes: position. ### `writeStream.getColorDepth([env])` + <!-- YAML added: v9.9.0 --> @@ -204,11 +216,12 @@ Disabling color support is also possible by using the `NO_COLOR` and `NODE_DISABLE_COLORS` environment variables. ### `writeStream.getWindowSize()` + <!-- YAML added: v0.7.7 --> -* Returns: {number[]} +* Returns: {number\[]} `writeStream.getWindowSize()` returns the size of the TTY corresponding to this `WriteStream`. The array is of the type @@ -216,6 +229,7 @@ corresponding to this `WriteStream`. The array is of the type of columns and rows in the corresponding TTY. ### `writeStream.hasColors([count][, env])` + <!-- YAML added: - v11.13.0 @@ -247,6 +261,7 @@ process.stdout.hasColors(2 ** 24, { TMUX: '1' }); ``` ### `writeStream.isTTY` + <!-- YAML added: v0.5.8 --> @@ -254,6 +269,7 @@ added: v0.5.8 A `boolean` that is always `true`. ### `writeStream.moveCursor(dx, dy[, callback])` + <!-- YAML added: v0.7.7 changes: @@ -269,10 +285,11 @@ changes: for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. -`writeStream.moveCursor()` moves this `WriteStream`'s cursor *relative* to its +`writeStream.moveCursor()` moves this `WriteStream`'s cursor _relative_ to its current position. ### `writeStream.rows` + <!-- YAML added: v0.7.7 --> @@ -281,6 +298,7 @@ A `number` specifying the number of rows the TTY currently has. This property is updated whenever the `'resize'` event is emitted. ## `tty.isatty(fd)` + <!-- YAML added: v0.5.8 --> diff --git a/doc/api/url.md b/doc/api/url.md index e6415e2a599..4c23f091271 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -105,6 +105,7 @@ console.log(myURL.href); ## The WHATWG URL API ### Class: `URL` + <!-- YAML added: - v7.0.0 @@ -242,7 +243,7 @@ Invalid host values assigned to the `host` property are ignored. * {string} Gets and sets the host name portion of the URL. The key difference between -`url.host` and `url.hostname` is that `url.hostname` does *not* include the +`url.host` and `url.hostname` is that `url.hostname` does _not_ include the port. ```js @@ -290,6 +291,7 @@ If the value assigned to the `href` property is not a valid URL, a `TypeError` will be thrown. #### `url.origin` + <!-- YAML changes: - version: v15.0.0 @@ -360,6 +362,7 @@ to percent-encode may vary somewhat from what the [`url.parse()`][] and [`url.format()`][] methods would produce. #### `url.port` + <!-- YAML changes: - version: v15.0.0 @@ -467,6 +470,7 @@ console.log(myURL.href); Invalid URL protocol values assigned to the `protocol` property are ignored. ##### Special schemes + <!-- YAML changes: - version: v15.0.0 @@ -609,6 +613,7 @@ console.log(JSON.stringify(myURLs)); ``` #### `URL.createObjectURL(blob)` + <!-- YAML added: v16.7.0 --> @@ -644,6 +649,7 @@ Threads, `Blob` objects registered within one Worker will not be available to other workers or the main thread. #### `URL.revokeObjectURL(id)` + <!-- YAML added: v16.7.0 --> @@ -656,6 +662,7 @@ added: v16.7.0 Removes the stored {Blob} identified by the given ID. ### Class: `URLSearchParams` + <!-- YAML added: - v7.5.0 @@ -735,6 +742,7 @@ console.log(params.toString()); ``` #### `new URLSearchParams(obj)` + <!-- YAML added: - v7.10.0 @@ -762,6 +770,7 @@ console.log(params.toString()); ``` #### `new URLSearchParams(iterable)` + <!-- YAML added: - v7.10.0 @@ -869,7 +878,7 @@ are no such pairs, `null` is returned. #### `urlSearchParams.getAll(name)` * `name` {string} -* Returns: {string[]} +* Returns: {string\[]} Returns the values of all name-value pairs whose name is `name`. If there are no such pairs, an empty array is returned. @@ -922,6 +931,7 @@ console.log(params.toString()); ``` #### `urlSearchParams.sort()` + <!-- YAML added: - v7.7.0 @@ -975,6 +985,7 @@ for (const [name, value] of params) { ``` ### `url.domainToASCII(domain)` + <!-- YAML added: - v7.4.0 @@ -1015,6 +1026,7 @@ console.log(url.domainToASCII('xn--iñvalid.com')); ``` ### `url.domainToUnicode(domain)` + <!-- YAML added: - v7.4.0 @@ -1055,6 +1067,7 @@ console.log(url.domainToUnicode('xn--iñvalid.com')); ``` ### `url.fileURLToPath(url)` + <!-- YAML added: v10.12.0 --> @@ -1099,6 +1112,7 @@ fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) ``` ### `url.format(URL[, options])` + <!-- YAML added: v7.6.0 --> @@ -1153,6 +1167,7 @@ console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); ``` ### `url.pathToFileURL(path)` + <!-- YAML added: v10.12.0 --> @@ -1188,6 +1203,7 @@ pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSI ``` ### `url.urlToHttpOptions(url)` + <!-- YAML added: - v15.7.0 @@ -1253,6 +1269,7 @@ console.log(urlToHttpOptions(myUrl)); ``` ## Legacy URL API + <!-- YAML changes: - version: @@ -1268,6 +1285,7 @@ changes: > Stability: 3 - Legacy: Use the WHATWG URL API instead. ### Legacy `urlObject` + <!-- YAML changes: - version: @@ -1312,7 +1330,7 @@ For example: `'sub.example.com:8080'`. #### `urlObject.hostname` The `hostname` property is the lower-cased host name portion of the `host` -component *without* the `port` included. +component _without_ the `port` included. For example: `'sub.example.com'`. @@ -1383,6 +1401,7 @@ forward-slash characters (`/`) are required following the colon in the `protocol`. ### `url.format(urlObject)` + <!-- YAML added: v0.1.25 changes: @@ -1440,7 +1459,7 @@ The formatting process operates as follows: * If `urlObject.protocol` is a string, it is appended as-is to `result`. * Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an [`Error`][] is thrown. -* For all string values of `urlObject.protocol` that *do not end* with an ASCII +* For all string values of `urlObject.protocol` that _do not end_ with an ASCII colon (`:`) character, the literal string `:` will be appended to `result`. * If either of the following conditions is true, then the literal string `//` will be appended to `result`: @@ -1450,7 +1469,7 @@ The formatting process operates as follows: * If the value of the `urlObject.auth` property is truthy, and either `urlObject.host` or `urlObject.hostname` are not `undefined`, the value of `urlObject.auth` will be coerced into a string and appended to `result` - followed by the literal string `@`. + followed by the literal string `@`. * If the `urlObject.host` property is `undefined` then: * If the `urlObject.hostname` is a string, it is appended to `result`. * Otherwise, if `urlObject.hostname` is not `undefined` and is not a string, @@ -1463,7 +1482,7 @@ The formatting process operates as follows: * Otherwise, if the `urlObject.host` property value is truthy, the value of `urlObject.host` is coerced to a string and appended to `result`. * If the `urlObject.pathname` property is a string that is not an empty string: - * If the `urlObject.pathname` *does not start* with an ASCII forward slash + * If the `urlObject.pathname` _does not start_ with an ASCII forward slash (`/`), then the literal string `'/'` is appended to `result`. * The value of `urlObject.pathname` is appended to `result`. * Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an @@ -1473,13 +1492,13 @@ The formatting process operates as follows: followed by the output of calling the [`querystring`][] module's `stringify()` method passing the value of `urlObject.query`. * Otherwise, if `urlObject.search` is a string: - * If the value of `urlObject.search` *does not start* with the ASCII question + * If the value of `urlObject.search` _does not start_ with the ASCII question mark (`?`) character, the literal string `?` is appended to `result`. * The value of `urlObject.search` is appended to `result`. * Otherwise, if `urlObject.search` is not `undefined` and is not a string, an [`Error`][] is thrown. * If the `urlObject.hash` property is a string: - * If the value of `urlObject.hash` *does not start* with the ASCII hash (`#`) + * If the value of `urlObject.hash` _does not start_ with the ASCII hash (`#`) character, the literal string `#` is appended to `result`. * The value of `urlObject.hash` is appended to `result`. * Otherwise, if the `urlObject.hash` property is not `undefined` and is not a @@ -1487,6 +1506,7 @@ The formatting process operates as follows: * `result` is returned. ### `url.parse(urlString[, parseQueryString[, slashesDenoteHost]])` + <!-- YAML added: v0.1.25 changes: @@ -1536,6 +1556,7 @@ issues can be introduced. Specifically, issues with [host name spoofing][] and incorrect handling of usernames and passwords have been identified. ### `url.resolve(from, to)` + <!-- YAML added: v0.1.25 changes: @@ -1596,6 +1617,7 @@ resolve('http://example.com/one', '/two'); // 'http://example.com/two' ``` <a id="whatwg-percent-encoding"></a> + ## Percent-encoding in URLs URLs are permitted to only contain a certain range of characters. Any character @@ -1623,29 +1645,29 @@ selecting encoded characters than that used by the Legacy API. The WHATWG algorithm defines four "percent-encode sets" that describe ranges of characters that must be percent-encoded: -* The *C0 control percent-encode set* includes code points in range U+0000 to +* The _C0 control percent-encode set_ includes code points in range U+0000 to U+001F (inclusive) and all code points greater than U+007E. -* The *fragment percent-encode set* includes the *C0 control percent-encode set* +* The _fragment percent-encode set_ includes the _C0 control percent-encode set_ and code points U+0020, U+0022, U+003C, U+003E, and U+0060. -* The *path percent-encode set* includes the *C0 control percent-encode set* +* The _path percent-encode set_ includes the _C0 control percent-encode set_ and code points U+0020, U+0022, U+0023, U+003C, U+003E, U+003F, U+0060, U+007B, and U+007D. -* The *userinfo encode set* includes the *path percent-encode set* and code +* The _userinfo encode set_ includes the _path percent-encode set_ and code points U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, U+005E, and U+007C. -The *userinfo percent-encode set* is used exclusively for username and -passwords encoded within the URL. The *path percent-encode set* is used for the -path of most URLs. The *fragment percent-encode set* is used for URL fragments. -The *C0 control percent-encode set* is used for host and path under certain +The _userinfo percent-encode set_ is used exclusively for username and +passwords encoded within the URL. The _path percent-encode set_ is used for the +path of most URLs. The _fragment percent-encode set_ is used for URL fragments. +The _C0 control percent-encode set_ is used for host and path under certain specific conditions, in addition to all other cases. When non-ASCII characters appear within a host name, the host name is encoded -using the [Punycode][] algorithm. Note, however, that a host name *may* contain -*both* Punycode encoded and percent-encoded characters: +using the [Punycode][] algorithm. Note, however, that a host name _may_ contain +_both_ Punycode encoded and percent-encoded characters: ```js const myURL = new URL('https://%CF%80.example.com/foo'); diff --git a/doc/api/util.md b/doc/api/util.md index 24c90dd4077..3810b1145cd 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -15,6 +15,7 @@ const util = require('util'); ``` ## `util.callbackify(original)` + <!-- YAML added: v8.2.0 --> @@ -71,6 +72,7 @@ callbackFunction((err, ret) => { ``` ## `util.debuglog(section[, callback])` + <!-- YAML added: v0.11.3 --> @@ -137,6 +139,7 @@ let debuglog = util.debuglog('internals', (debug) => { ``` ### `debuglog().enabled` + <!-- YAML added: v14.9.0 --> @@ -165,6 +168,7 @@ hello from foo [123] ``` ## `util.debug(section)` + <!-- YAML added: v14.9.0 --> @@ -173,6 +177,7 @@ Alias for `util.debuglog`. Usage allows for readability of that doesn't imply logging when only using `util.debuglog().enabled`. ## `util.deprecate(fn, msg[, code])` + <!-- YAML added: v0.8.0 changes: @@ -218,7 +223,7 @@ fn2(); // Does not emit a deprecation warning because it has the same code ``` If either the `--no-deprecation` or `--no-warnings` command-line flags are -used, or if the `process.noDeprecation` property is set to `true` *prior* to +used, or if the `process.noDeprecation` property is set to `true` _prior_ to the first deprecation warning, the `util.deprecate()` method does nothing. If the `--trace-deprecation` or `--trace-warnings` command-line flags are set, @@ -235,6 +240,7 @@ property take precedence over `--trace-deprecation` and `process.traceDeprecation`. ## `util.format(format[, ...args])` + <!-- YAML added: v0.5.3 changes: @@ -340,6 +346,7 @@ Some input values can have a significant performance overhead that can block the event loop. Use this function with care and never in a hot code path. ## `util.formatWithOptions(inspectOptions, format[, ...args])` + <!-- YAML added: v10.0.0 --> @@ -358,6 +365,7 @@ util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 }); ``` ## `util.getSystemErrorName(err)` + <!-- YAML added: v9.7.0 --> @@ -377,6 +385,7 @@ fs.access('file/that/does/not/exist', (err) => { ``` ## `util.getSystemErrorMap()` + <!-- YAML added: - v16.0.0 @@ -398,6 +407,7 @@ fs.access('file/that/does/not/exist', (err) => { ``` ## `util.inherits(constructor, superConstructor)` + <!-- YAML added: v0.3.0 changes: @@ -469,7 +479,9 @@ stream.write('With ES6'); ``` ## `util.inspect(object[, options])` + ## `util.inspect(object[, showHidden[, depth[, colors]]])` + <!-- YAML added: v0.3.0 changes: @@ -894,6 +906,7 @@ util.inspect(obj); ``` ### `util.inspect.custom` + <!-- YAML added: v6.6.0 changes: @@ -933,6 +946,7 @@ console.log(password); See [Custom inspection functions on Objects][] for more details. ### `util.inspect.defaultOptions` + <!-- YAML added: v6.4.0 --> @@ -953,6 +967,7 @@ console.log(arr); // logs the full array ``` ## `util.isDeepStrictEqual(val1, val2)` + <!-- YAML added: v9.0.0 --> @@ -968,6 +983,7 @@ See [`assert.deepStrictEqual()`][] for more information about deep strict equality. ## `util.promisify(original)` + <!-- YAML added: v8.0.0 --> @@ -1081,6 +1097,7 @@ If `promisify.custom` is defined but is not a function, `promisify()` will throw an error. ### `util.promisify.custom` + <!-- YAML added: v8.0.0 changes: @@ -1112,6 +1129,7 @@ doSomething[kCustomPromisifiedSymbol] = (foo) => { ``` ## `util.stripVTControlCharacters(str)` + <!-- YAML added: v16.11.0 --> @@ -1127,6 +1145,7 @@ console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m')); ``` ## Class: `util.TextDecoder` + <!-- YAML added: v8.3.0 --> @@ -1154,47 +1173,47 @@ Different Node.js build configurations support different sets of encodings. #### Encodings supported by default (with full ICU data) -| Encoding | Aliases | -| ----------------- | -------------------------------- | -| `'ibm866'` | `'866'`, `'cp866'`, `'csibm866'` | -| `'iso-8859-2'` | `'csisolatin2'`, `'iso-ir-101'`, `'iso8859-2'`, `'iso88592'`, `'iso_8859-2'`, `'iso_8859-2:1987'`, `'l2'`, `'latin2'` | -| `'iso-8859-3'` | `'csisolatin3'`, `'iso-ir-109'`, `'iso8859-3'`, `'iso88593'`, `'iso_8859-3'`, `'iso_8859-3:1988'`, `'l3'`, `'latin3'` | -| `'iso-8859-4'` | `'csisolatin4'`, `'iso-ir-110'`, `'iso8859-4'`, `'iso88594'`, `'iso_8859-4'`, `'iso_8859-4:1988'`, `'l4'`, `'latin4'` | -| `'iso-8859-5'` | `'csisolatincyrillic'`, `'cyrillic'`, `'iso-ir-144'`, `'iso8859-5'`, `'iso88595'`, `'iso_8859-5'`, `'iso_8859-5:1988'` | -| `'iso-8859-6'` | `'arabic'`, `'asmo-708'`, `'csiso88596e'`, `'csiso88596i'`, `'csisolatinarabic'`, `'ecma-114'`, `'iso-8859-6-e'`, `'iso-8859-6-i'`, `'iso-ir-127'`, `'iso8859-6'`, `'iso88596'`, `'iso_8859-6'`, `'iso_8859-6:1987'` | -| `'iso-8859-7'` | `'csisolatingreek'`, `'ecma-118'`, `'elot_928'`, `'greek'`, `'greek8'`, `'iso-ir-126'`, `'iso8859-7'`, `'iso88597'`, `'iso_8859-7'`, `'iso_8859-7:1987'`, `'sun_eu_greek'` | -| `'iso-8859-8'` | `'csiso88598e'`, `'csisolatinhebrew'`, `'hebrew'`, `'iso-8859-8-e'`, `'iso-ir-138'`, `'iso8859-8'`, `'iso88598'`, `'iso_8859-8'`, `'iso_8859-8:1988'`, `'visual'` | -| `'iso-8859-8-i'` | `'csiso88598i'`, `'logical'` | -| `'iso-8859-10'` | `'csisolatin6'`, `'iso-ir-157'`, `'iso8859-10'`, `'iso885910'`, `'l6'`, `'latin6'` | -| `'iso-8859-13'` | `'iso8859-13'`, `'iso885913'` | -| `'iso-8859-14'` | `'iso8859-14'`, `'iso885914'` | -| `'iso-8859-15'` | `'csisolatin9'`, `'iso8859-15'`, `'iso885915'`, `'iso_8859-15'`, `'l9'` | -| `'koi8-r'` | `'cskoi8r'`, `'koi'`, `'koi8'`, `'koi8_r'` | -| `'koi8-u'` | `'koi8-ru'` | -| `'macintosh'` | `'csmacintosh'`, `'mac'`, `'x-mac-roman'` | -| `'windows-874'` | `'dos-874'`, `'iso-8859-11'`, `'iso8859-11'`, `'iso885911'`, `'tis-620'` | -| `'windows-1250'` | `'cp1250'`, `'x-cp1250'` | -| `'windows-1251'` | `'cp1251'`, `'x-cp1251'` | +| Encoding | Aliases | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `'ibm866'` | `'866'`, `'cp866'`, `'csibm866'` | +| `'iso-8859-2'` | `'csisolatin2'`, `'iso-ir-101'`, `'iso8859-2'`, `'iso88592'`, `'iso_8859-2'`, `'iso_8859-2:1987'`, `'l2'`, `'latin2'` | +| `'iso-8859-3'` | `'csisolatin3'`, `'iso-ir-109'`, `'iso8859-3'`, `'iso88593'`, `'iso_8859-3'`, `'iso_8859-3:1988'`, `'l3'`, `'latin3'` | +| `'iso-8859-4'` | `'csisolatin4'`, `'iso-ir-110'`, `'iso8859-4'`, `'iso88594'`, `'iso_8859-4'`, `'iso_8859-4:1988'`, `'l4'`, `'latin4'` | +| `'iso-8859-5'` | `'csisolatincyrillic'`, `'cyrillic'`, `'iso-ir-144'`, `'iso8859-5'`, `'iso88595'`, `'iso_8859-5'`, `'iso_8859-5:1988'` | +| `'iso-8859-6'` | `'arabic'`, `'asmo-708'`, `'csiso88596e'`, `'csiso88596i'`, `'csisolatinarabic'`, `'ecma-114'`, `'iso-8859-6-e'`, `'iso-8859-6-i'`, `'iso-ir-127'`, `'iso8859-6'`, `'iso88596'`, `'iso_8859-6'`, `'iso_8859-6:1987'` | +| `'iso-8859-7'` | `'csisolatingreek'`, `'ecma-118'`, `'elot_928'`, `'greek'`, `'greek8'`, `'iso-ir-126'`, `'iso8859-7'`, `'iso88597'`, `'iso_8859-7'`, `'iso_8859-7:1987'`, `'sun_eu_greek'` | +| `'iso-8859-8'` | `'csiso88598e'`, `'csisolatinhebrew'`, `'hebrew'`, `'iso-8859-8-e'`, `'iso-ir-138'`, `'iso8859-8'`, `'iso88598'`, `'iso_8859-8'`, `'iso_8859-8:1988'`, `'visual'` | +| `'iso-8859-8-i'` | `'csiso88598i'`, `'logical'` | +| `'iso-8859-10'` | `'csisolatin6'`, `'iso-ir-157'`, `'iso8859-10'`, `'iso885910'`, `'l6'`, `'latin6'` | +| `'iso-8859-13'` | `'iso8859-13'`, `'iso885913'` | +| `'iso-8859-14'` | `'iso8859-14'`, `'iso885914'` | +| `'iso-8859-15'` | `'csisolatin9'`, `'iso8859-15'`, `'iso885915'`, `'iso_8859-15'`, `'l9'` | +| `'koi8-r'` | `'cskoi8r'`, `'koi'`, `'koi8'`, `'koi8_r'` | +| `'koi8-u'` | `'koi8-ru'` | +| `'macintosh'` | `'csmacintosh'`, `'mac'`, `'x-mac-roman'` | +| `'windows-874'` | `'dos-874'`, `'iso-8859-11'`, `'iso8859-11'`, `'iso885911'`, `'tis-620'` | +| `'windows-1250'` | `'cp1250'`, `'x-cp1250'` | +| `'windows-1251'` | `'cp1251'`, `'x-cp1251'` | | `'windows-1252'` | `'ansi_x3.4-1968'`, `'ascii'`, `'cp1252'`, `'cp819'`, `'csisolatin1'`, `'ibm819'`, `'iso-8859-1'`, `'iso-ir-100'`, `'iso8859-1'`, `'iso88591'`, `'iso_8859-1'`, `'iso_8859-1:1987'`, `'l1'`, `'latin1'`, `'us-ascii'`, `'x-cp1252'` | -| `'windows-1253'` | `'cp1253'`, `'x-cp1253'` | -| `'windows-1254'` | `'cp1254'`, `'csisolatin5'`, `'iso-8859-9'`, `'iso-ir-148'`, `'iso8859-9'`, `'iso88599'`, `'iso_8859-9'`, `'iso_8859-9:1989'`, `'l5'`, `'latin5'`, `'x-cp1254'` | -| `'windows-1255'` | `'cp1255'`, `'x-cp1255'` | -| `'windows-1256'` | `'cp1256'`, `'x-cp1256'` | -| `'windows-1257'` | `'cp1257'`, `'x-cp1257'` | -| `'windows-1258'` | `'cp1258'`, `'x-cp1258'` | -| `'x-mac-cyrillic'` | `'x-mac-ukrainian'` | -| `'gbk'` | `'chinese'`, `'csgb2312'`, `'csiso58gb231280'`, `'gb2312'`, `'gb_2312'`, `'gb_2312-80'`, `'iso-ir-58'`, `'x-gbk'` | -| `'gb18030'` | | -| `'big5'` | `'big5-hkscs'`, `'cn-big5'`, `'csbig5'`, `'x-x-big5'` | -| `'euc-jp'` | `'cseucpkdfmtjapanese'`, `'x-euc-jp'` | -| `'iso-2022-jp'` | `'csiso2022jp'` | -| `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` | -| `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` | +| `'windows-1253'` | `'cp1253'`, `'x-cp1253'` | +| `'windows-1254'` | `'cp1254'`, `'csisolatin5'`, `'iso-8859-9'`, `'iso-ir-148'`, `'iso8859-9'`, `'iso88599'`, `'iso_8859-9'`, `'iso_8859-9:1989'`, `'l5'`, `'latin5'`, `'x-cp1254'` | +| `'windows-1255'` | `'cp1255'`, `'x-cp1255'` | +| `'windows-1256'` | `'cp1256'`, `'x-cp1256'` | +| `'windows-1257'` | `'cp1257'`, `'x-cp1257'` | +| `'windows-1258'` | `'cp1258'`, `'x-cp1258'` | +| `'x-mac-cyrillic'` | `'x-mac-ukrainian'` | +| `'gbk'` | `'chinese'`, `'csgb2312'`, `'csiso58gb231280'`, `'gb2312'`, `'gb_2312'`, `'gb_2312-80'`, `'iso-ir-58'`, `'x-gbk'` | +| `'gb18030'` | | +| `'big5'` | `'big5-hkscs'`, `'cn-big5'`, `'csbig5'`, `'x-x-big5'` | +| `'euc-jp'` | `'cseucpkdfmtjapanese'`, `'x-euc-jp'` | +| `'iso-2022-jp'` | `'csiso2022jp'` | +| `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` | +| `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` | #### Encodings supported when Node.js is built with the `small-icu` option | Encoding | Aliases | -| ----------- | ------------------------------- | +| ------------ | ------------------------------- | | `'utf-8'` | `'unicode-1-1-utf-8'`, `'utf8'` | | `'utf-16le'` | `'utf-16'` | | `'utf-16be'` | | @@ -1202,7 +1221,7 @@ Different Node.js build configurations support different sets of encodings. #### Encodings supported when ICU is disabled | Encoding | Aliases | -| ----------- | ------------------------------- | +| ------------ | ------------------------------- | | `'utf-8'` | `'unicode-1-1-utf-8'`, `'utf8'` | | `'utf-16le'` | `'utf-16'` | @@ -1210,6 +1229,7 @@ The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][] is not supported. ### `new TextDecoder([encoding[, options]])` + <!-- YAML added: v8.3.0 changes: @@ -1225,9 +1245,9 @@ changes: This option is not supported when ICU is disabled (see [Internationalization][]). **Default:** `false`. * `ignoreBOM` {boolean} When `true`, the `TextDecoder` will include the byte - order mark in the decoded result. When `false`, the byte order mark will - be removed from the output. This option is only used when `encoding` is - `'utf-8'`, `'utf-16be'` or `'utf-16le'`. **Default:** `false`. + order mark in the decoded result. When `false`, the byte order mark will + be removed from the output. This option is only used when `encoding` is + `'utf-8'`, `'utf-16be'` or `'utf-16le'`. **Default:** `false`. Creates an new `TextDecoder` instance. The `encoding` may specify one of the supported encodings or an alias. @@ -1271,6 +1291,7 @@ The value will be `true` if the decoding result will include the byte order mark. ## Class: `util.TextEncoder` + <!-- YAML added: v8.3.0 changes: @@ -1322,6 +1343,7 @@ const { read, written } = encoder.encodeInto(src, dest); The encoding supported by the `TextEncoder` instance. Always set to `'utf-8'`. ## `util.toUSVString(string)` + <!-- YAML added: - v16.8.0 @@ -1335,6 +1357,7 @@ Returns the `string` after replacing any surrogate code points Unicode "replacement character" U+FFFD. ## `util.types` + <!-- YAML added: v10.0.0 changes: @@ -1355,6 +1378,7 @@ useful for addon developers who prefer to do type checking in JavaScript. The API is accessible via `require('util').types` or `require('util/types')`. ### `util.types.isAnyArrayBuffer(value)` + <!-- YAML added: v10.0.0 --> @@ -1374,6 +1398,7 @@ util.types.isAnyArrayBuffer(new SharedArrayBuffer()); // Returns true ``` ### `util.types.isArrayBufferView(value)` + <!-- YAML added: v10.0.0 --> @@ -1393,6 +1418,7 @@ util.types.isArrayBufferView(new ArrayBuffer()); // false ``` ### `util.types.isArgumentsObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1403,6 +1429,7 @@ added: v10.0.0 Returns `true` if the value is an `arguments` object. <!-- eslint-disable prefer-rest-params --> + ```js function foo() { util.types.isArgumentsObject(arguments); // Returns true @@ -1410,6 +1437,7 @@ function foo() { ``` ### `util.types.isArrayBuffer(value)` + <!-- YAML added: v10.0.0 --> @@ -1418,7 +1446,7 @@ added: v10.0.0 * Returns: {boolean} Returns `true` if the value is a built-in [`ArrayBuffer`][] instance. -This does *not* include [`SharedArrayBuffer`][] instances. Usually, it is +This does _not_ include [`SharedArrayBuffer`][] instances. Usually, it is desirable to test for both; See [`util.types.isAnyArrayBuffer()`][] for that. ```js @@ -1427,6 +1455,7 @@ util.types.isArrayBuffer(new SharedArrayBuffer()); // Returns false ``` ### `util.types.isAsyncFunction(value)` + <!-- YAML added: v10.0.0 --> @@ -1445,6 +1474,7 @@ util.types.isAsyncFunction(async function foo() {}); // Returns true ``` ### `util.types.isBigInt64Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1460,6 +1490,7 @@ util.types.isBigInt64Array(new BigUint64Array()); // Returns false ``` ### `util.types.isBigUint64Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1475,6 +1506,7 @@ util.types.isBigUint64Array(new BigUint64Array()); // Returns true ``` ### `util.types.isBooleanObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1495,6 +1527,7 @@ util.types.isBooleanObject(Boolean(true)); // Returns false ``` ### `util.types.isBoxedPrimitive(value)` + <!-- YAML added: v10.11.0 --> @@ -1516,6 +1549,7 @@ util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true ``` ### `util.types.isCryptoKey(value)` + <!-- YAML added: v16.2.0 --> @@ -1526,6 +1560,7 @@ added: v16.2.0 Returns `true` if `value` is a {CryptoKey}, `false` otherwise. ### `util.types.isDataView(value)` + <!-- YAML added: v10.0.0 --> @@ -1544,6 +1579,7 @@ util.types.isDataView(new Float64Array()); // Returns false See also [`ArrayBuffer.isView()`][]. ### `util.types.isDate(value)` + <!-- YAML added: v10.0.0 --> @@ -1558,6 +1594,7 @@ util.types.isDate(new Date()); // Returns true ``` ### `util.types.isExternal(value)` + <!-- YAML added: v10.0.0 --> @@ -1603,6 +1640,7 @@ For further information on `napi_create_external`, refer to [`napi_create_external()`][]. ### `util.types.isFloat32Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1619,6 +1657,7 @@ util.types.isFloat32Array(new Float64Array()); // Returns false ``` ### `util.types.isFloat64Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1635,6 +1674,7 @@ util.types.isFloat64Array(new Float64Array()); // Returns true ``` ### `util.types.isGeneratorFunction(value)` + <!-- YAML added: v10.0.0 --> @@ -1653,6 +1693,7 @@ util.types.isGeneratorFunction(function* foo() {}); // Returns true ``` ### `util.types.isGeneratorObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1673,6 +1714,7 @@ util.types.isGeneratorObject(generator); // Returns true ``` ### `util.types.isInt8Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1689,6 +1731,7 @@ util.types.isInt8Array(new Float64Array()); // Returns false ``` ### `util.types.isInt16Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1705,6 +1748,7 @@ util.types.isInt16Array(new Float64Array()); // Returns false ``` ### `util.types.isInt32Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1721,6 +1765,7 @@ util.types.isInt32Array(new Float64Array()); // Returns false ``` ### `util.types.isKeyObject(value)` + <!-- YAML added: v16.2.0 --> @@ -1731,6 +1776,7 @@ added: v16.2.0 Returns `true` if `value` is a {KeyObject}, `false` otherwise. ### `util.types.isMap(value)` + <!-- YAML added: v10.0.0 --> @@ -1745,6 +1791,7 @@ util.types.isMap(new Map()); // Returns true ``` ### `util.types.isMapIterator(value)` + <!-- YAML added: v10.0.0 --> @@ -1764,6 +1811,7 @@ util.types.isMapIterator(map[Symbol.iterator]()); // Returns true ``` ### `util.types.isModuleNamespaceObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1774,6 +1822,7 @@ added: v10.0.0 Returns `true` if the value is an instance of a [Module Namespace Object][]. <!-- eslint-skip --> + ```js import * as ns from './a.js'; @@ -1781,6 +1830,7 @@ util.types.isModuleNamespaceObject(ns); // Returns true ``` ### `util.types.isNativeError(value)` + <!-- YAML added: v10.0.0 --> @@ -1797,6 +1847,7 @@ util.types.isNativeError(new RangeError()); // Returns true ``` ### `util.types.isNumberObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1813,6 +1864,7 @@ util.types.isNumberObject(new Number(0)); // Returns true ``` ### `util.types.isPromise(value)` + <!-- YAML added: v10.0.0 --> @@ -1827,6 +1879,7 @@ util.types.isPromise(Promise.resolve(42)); // Returns true ``` ### `util.types.isProxy(value)` + <!-- YAML added: v10.0.0 --> @@ -1844,6 +1897,7 @@ util.types.isProxy(proxy); // Returns true ``` ### `util.types.isRegExp(value)` + <!-- YAML added: v10.0.0 --> @@ -1859,6 +1913,7 @@ util.types.isRegExp(new RegExp('abc')); // Returns true ``` ### `util.types.isSet(value)` + <!-- YAML added: v10.0.0 --> @@ -1873,6 +1928,7 @@ util.types.isSet(new Set()); // Returns true ``` ### `util.types.isSetIterator(value)` + <!-- YAML added: v10.0.0 --> @@ -1892,6 +1948,7 @@ util.types.isSetIterator(set[Symbol.iterator]()); // Returns true ``` ### `util.types.isSharedArrayBuffer(value)` + <!-- YAML added: v10.0.0 --> @@ -1900,7 +1957,7 @@ added: v10.0.0 * Returns: {boolean} Returns `true` if the value is a built-in [`SharedArrayBuffer`][] instance. -This does *not* include [`ArrayBuffer`][] instances. Usually, it is +This does _not_ include [`ArrayBuffer`][] instances. Usually, it is desirable to test for both; See [`util.types.isAnyArrayBuffer()`][] for that. ```js @@ -1909,6 +1966,7 @@ util.types.isSharedArrayBuffer(new SharedArrayBuffer()); // Returns true ``` ### `util.types.isStringObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1925,6 +1983,7 @@ util.types.isStringObject(new String('foo')); // Returns true ``` ### `util.types.isSymbolObject(value)` + <!-- YAML added: v10.0.0 --> @@ -1942,6 +2001,7 @@ util.types.isSymbolObject(Object(symbol)); // Returns true ``` ### `util.types.isTypedArray(value)` + <!-- YAML added: v10.0.0 --> @@ -1960,6 +2020,7 @@ util.types.isTypedArray(new Float64Array()); // Returns true See also [`ArrayBuffer.isView()`][]. ### `util.types.isUint8Array(value)` + <!-- YAML added: v10.0.0 --> @@ -1976,6 +2037,7 @@ util.types.isUint8Array(new Float64Array()); // Returns false ``` ### `util.types.isUint8ClampedArray(value)` + <!-- YAML added: v10.0.0 --> @@ -1992,6 +2054,7 @@ util.types.isUint8ClampedArray(new Float64Array()); // Returns false ``` ### `util.types.isUint16Array(value)` + <!-- YAML added: v10.0.0 --> @@ -2008,6 +2071,7 @@ util.types.isUint16Array(new Float64Array()); // Returns false ``` ### `util.types.isUint32Array(value)` + <!-- YAML added: v10.0.0 --> @@ -2024,6 +2088,7 @@ util.types.isUint32Array(new Float64Array()); // Returns false ``` ### `util.types.isWeakMap(value)` + <!-- YAML added: v10.0.0 --> @@ -2038,6 +2103,7 @@ util.types.isWeakMap(new WeakMap()); // Returns true ``` ### `util.types.isWeakSet(value)` + <!-- YAML added: v10.0.0 --> @@ -2052,6 +2118,7 @@ util.types.isWeakSet(new WeakSet()); // Returns true ``` ### `util.types.isWebAssemblyCompiledModule(value)` + <!-- YAML added: v10.0.0 deprecated: v14.0.0 @@ -2075,6 +2142,7 @@ The following APIs are deprecated and should no longer be used. Existing applications and modules should be updated to find alternative approaches. ### `util._extend(target, source)` + <!-- YAML added: v0.7.5 deprecated: v6.0.0 @@ -2092,6 +2160,7 @@ It is deprecated and should not be used in new code. JavaScript comes with very similar built-in functionality through [`Object.assign()`][]. ### `util.isArray(object)` + <!-- YAML added: v0.6.0 deprecated: v4.0.0 @@ -2118,6 +2187,7 @@ util.isArray({}); ``` ### `util.isBoolean(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2142,6 +2212,7 @@ util.isBoolean(false); ``` ### `util.isBuffer(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2166,6 +2237,7 @@ util.isBuffer(Buffer.from('hello world')); ``` ### `util.isDate(object)` + <!-- YAML added: v0.6.0 deprecated: v4.0.0 @@ -2190,6 +2262,7 @@ util.isDate({}); ``` ### `util.isError(object)` + <!-- YAML added: v0.6.0 deprecated: v4.0.0 @@ -2230,6 +2303,7 @@ util.isError(obj); ``` ### `util.isFunction(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2258,6 +2332,7 @@ util.isFunction(Bar); ``` ### `util.isNull(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2283,6 +2358,7 @@ util.isNull(null); ``` ### `util.isNullOrUndefined(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2309,6 +2385,7 @@ util.isNullOrUndefined(null); ``` ### `util.isNumber(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2335,6 +2412,7 @@ util.isNumber(NaN); ``` ### `util.isObject(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2364,6 +2442,7 @@ util.isObject(() => {}); ``` ### `util.isPrimitive(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2403,6 +2482,7 @@ util.isPrimitive(new Date()); ``` ### `util.isRegExp(object)` + <!-- YAML added: v0.6.0 deprecated: v4.0.0 @@ -2427,6 +2507,7 @@ util.isRegExp({}); ``` ### `util.isString(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2453,6 +2534,7 @@ util.isString(5); ``` ### `util.isSymbol(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2477,6 +2559,7 @@ util.isSymbol(Symbol('foo')); ``` ### `util.isUndefined(object)` + <!-- YAML added: v0.11.5 deprecated: v4.0.0 @@ -2502,6 +2585,7 @@ util.isUndefined(null); ``` ### `util.log(string)` + <!-- YAML added: v0.3.0 deprecated: v6.0.0 diff --git a/doc/api/v8.md b/doc/api/v8.md index d4972163cc6..4eb6aa6f902 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -12,6 +12,7 @@ const v8 = require('v8'); ``` ## `v8.cachedDataVersionTag()` + <!-- YAML added: v8.0.0 --> @@ -33,6 +34,7 @@ console.log(v8.cachedDataVersionTag()); // 183726201 ``` ## `v8.getHeapCodeStatistics()` + <!-- YAML added: v12.8.0 --> @@ -46,6 +48,7 @@ Returns an object with the following properties: * `external_script_source_size` {number} <!-- eslint-skip --> + ```js { code_and_metadata_size: 212208, @@ -55,6 +58,7 @@ Returns an object with the following properties: ``` ## `v8.getHeapSnapshot()` + <!-- YAML added: v11.13.0 --> @@ -75,6 +79,7 @@ stream.pipe(process.stdout); ``` ## `v8.getHeapSpaceStatistics()` + <!-- YAML added: v6.0.0 changes: @@ -83,7 +88,7 @@ changes: description: Support values exceeding the 32-bit unsigned integer range. --> -* Returns: {Object[]} +* Returns: {Object\[]} Returns statistics about the V8 heap spaces, i.e. the segments which make up the V8 heap. Neither the ordering of heap spaces, nor the availability of a @@ -140,6 +145,7 @@ The value returned is an array of objects containing the following properties: ``` ## `v8.getHeapStatistics()` + <!-- YAML added: v1.0.0 changes: @@ -174,15 +180,16 @@ garbage with a bit pattern. The RSS footprint (resident set size) gets bigger because it continuously touches all heap pages and that makes them less likely to get swapped out by the operating system. -`number_of_native_contexts` The value of native_context is the number of the +`number_of_native_contexts` The value of native\_context is the number of the top-level contexts currently active. Increase of this number over time indicates a memory leak. -`number_of_detached_contexts` The value of detached_context is the number +`number_of_detached_contexts` The value of detached\_context is the number of contexts that were detached and not yet garbage collected. This number being non-zero indicates a potential memory leak. <!-- eslint-skip --> + ```js { total_heap_size: 7326976, @@ -200,6 +207,7 @@ being non-zero indicates a potential memory leak. ``` ## `v8.setFlagsFromString(flags)` + <!-- YAML added: v1.0.0 --> @@ -256,6 +264,7 @@ When the process is about to exit, one last coverage will still be written to disk unless [`v8.stopCoverage()`][] is invoked before the process exits. ## `v8.writeHeapSnapshot([filename])` + <!-- YAML added: v11.13.0 --> @@ -316,6 +325,7 @@ The format is backward-compatible (i.e. safe to store to disk). Equal JavaScript values may result in different serialized output. ### `v8.serialize(value)` + <!-- YAML added: v8.0.0 --> @@ -326,6 +336,7 @@ added: v8.0.0 Uses a [`DefaultSerializer`][] to serialize `value` into a buffer. ### `v8.deserialize(buffer)` + <!-- YAML added: v8.0.0 --> @@ -336,11 +347,13 @@ Uses a [`DefaultDeserializer`][] with default options to read a JS value from a buffer. ### Class: `v8.Serializer` + <!-- YAML added: v8.0.0 --> #### `new Serializer()` + Creates a new `Serializer` object. #### `serializer.writeHeader()` @@ -447,6 +460,7 @@ Indicate whether to treat `TypedArray` and `DataView` objects as host objects, i.e. pass them to [`serializer._writeHostObject()`][]. ### Class: `v8.Deserializer` + <!-- YAML added: v8.0.0 --> @@ -495,7 +509,7 @@ For use inside of a custom [`deserializer._readHostObject()`][]. #### `deserializer.readUint64()` -* Returns: {integer[]} +* Returns: {integer\[]} Read a raw 64-bit unsigned integer and return it as an array `[hi, lo]` with two 32-bit unsigned integer entries. @@ -528,6 +542,7 @@ This method is not present on the `Deserializer` class itself but can be provided by subclasses. ### Class: `v8.DefaultSerializer` + <!-- YAML added: v8.0.0 --> @@ -537,6 +552,7 @@ A subclass of [`Serializer`][] that serializes `TypedArray` stores the part of their underlying `ArrayBuffer`s that they are referring to. ### Class: `v8.DefaultDeserializer` + <!-- YAML added: v8.0.0 --> diff --git a/doc/api/vm.md b/doc/api/vm.md index 0eb7a36b5f8..efc677967d7 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -43,6 +43,7 @@ console.log(x); // 1; y is not defined. ``` ## Class: `vm.Script` + <!-- YAML added: v0.3.1 --> @@ -51,6 +52,7 @@ Instances of the `vm.Script` class contain precompiled scripts that can be executed in specific contexts. ### `new vm.Script(code[, options])` + <!-- YAML added: v0.3.1 changes: @@ -78,8 +80,8 @@ changes: 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. + 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 @@ -109,6 +111,7 @@ 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.createCachedData()` + <!-- YAML added: v10.6.0 --> @@ -136,6 +139,7 @@ const cacheWithX = script.createCachedData(); ``` ### `script.runInContext(contextifiedObject[, options])` + <!-- YAML added: v0.3.1 changes: @@ -192,6 +196,7 @@ and corresponding threads being started, which have a non-zero performance overhead. ### `script.runInNewContext([contextObject[, options]])` + <!-- YAML added: v0.3.1 changes: @@ -264,6 +269,7 @@ console.log(contexts); ``` ### `script.runInThisContext([options])` + <!-- YAML added: v0.3.1 changes: @@ -288,7 +294,7 @@ changes: 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. +_does_ have access to the current `global` object. The following example compiles code that increments a `global` variable then executes that code multiple times: @@ -310,6 +316,7 @@ console.log(globalVar); ``` ## Class: `vm.Module` + <!-- YAML added: - v13.0.0 @@ -485,7 +492,7 @@ const contextifiedObject = vm.createContext({ ### `module.dependencySpecifiers` -* {string[]} +* {string\[]} The specifiers of all dependencies of this module. The returned array is frozen to disallow any changes to it. @@ -548,6 +555,7 @@ The identifier of the current module, as set in the constructor. import foo from 'foo'; // ^^^^^ the module specifier ``` + * `extra` {Object} * `assert` {Object} The data from the assertion: <!-- eslint-skip --> @@ -560,6 +568,7 @@ The identifier of the current module, as set in the constructor. unsupported assertion is present. * `referencingModule` {vm.Module} The `Module` object `link()` is called on. + * Returns: {vm.Module|Promise} * Returns: {Promise} @@ -634,6 +643,7 @@ Other than `'errored'`, this status string corresponds to the specification's value that is not `undefined`. ## Class: `vm.SourceTextModule` + <!-- YAML added: v9.6.0 --> @@ -649,6 +659,7 @@ The `vm.SourceTextModule` class provides the [Source Text Module Record][] as defined in the ECMAScript specification. ### `new vm.SourceTextModule(code[, options])` + <!-- YAML changes: - version: v17.0.0 @@ -664,8 +675,8 @@ changes: index. * `cachedData` {Buffer|TypedArray|DataView} Provides an optional `Buffer` or `TypedArray`, or `DataView` with V8's code cache data for the supplied - source. The `code` must be the same as the module from which this - `cachedData` was created. + source. The `code` must be the same as the module from which this + `cachedData` was created. * `context` {Object} The [contextified][] object as returned by the `vm.createContext()` method, to compile and evaluate this `Module` in. * `lineOffset` {integer} Specifies the line number offset that is displayed @@ -750,6 +761,7 @@ const contextifiedObject = vm.createContext({ secret: 42 }); ``` ### `sourceTextModule.createCachedData()` + <!-- YAML added: - v13.7.0 @@ -774,6 +786,7 @@ const module2 = new vm.SourceTextModule('const a = 1;', { cachedData }); ``` ## Class: `vm.SyntheticModule` + <!-- YAML added: - v13.0.0 @@ -805,13 +818,15 @@ const module = new vm.SyntheticModule(['default'], function() { ``` ### `new vm.SyntheticModule(exportNames, evaluateCallback[, options])` + <!-- YAML added: - v13.0.0 - v12.16.0 --> -* `exportNames` {string[]} Array of names that will be exported from the module. +* `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. @@ -827,6 +842,7 @@ the module to access information outside the specified `context`. Use `vm.runInContext()` to create objects in a specific context. ### `syntheticModule.setExport(name, value)` + <!-- YAML added: - v13.0.0 @@ -866,6 +882,7 @@ const vm = require('vm'); ``` ## `vm.compileFunction(code[, params[, options]])` + <!-- YAML added: v10.10.0 changes: @@ -888,7 +905,7 @@ changes: --> * `code` {string} The body of the function to compile. -* `params` {string[]} An array of strings containing all parameters for the +* `params` {string\[]} An array of strings containing all parameters for the function. * `options` {Object} * `filename` {string} Specifies the filename used in stack traces produced @@ -899,12 +916,12 @@ changes: 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. + source. * `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 + * `contextExtensions` {Object\[]} An array containing a collection of context extensions (objects wrapping the current scope) to be applied while compiling. **Default:** `[]`. * `importModuleDynamically` {Function} Called during evaluation of this module @@ -927,6 +944,7 @@ supplied, the current context is used), and returns it wrapped inside a function with the given `params`. ## `vm.createContext([contextObject[, options]])` + <!-- YAML added: v0.3.1 changes: @@ -1002,6 +1020,7 @@ The provided `name` and `origin` of the context are made visible through the Inspector API. ## `vm.isContext(object)` + <!-- YAML added: v0.11.7 --> @@ -1089,6 +1108,7 @@ vm.measureMemory({ mode: 'detailed', execution: 'eager' }) ``` ## `vm.runInContext(code, contextifiedObject[, options])` + <!-- YAML added: v0.3.1 changes: @@ -1124,8 +1144,8 @@ changes: 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. When supplied, the `cachedDataRejected` value will be set to - either `true` or `false` depending on acceptance of the data by V8. + 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 @@ -1151,7 +1171,7 @@ changes: 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 +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. @@ -1173,6 +1193,7 @@ console.log(contextObject); ``` ## `vm.runInNewContext(code[, contextObject[, options]])` + <!-- YAML added: v0.3.1 changes: @@ -1229,8 +1250,8 @@ changes: 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. + 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 @@ -1282,6 +1303,7 @@ console.log(contextObject); ``` ## `vm.runInThisContext(code[, options])` + <!-- YAML added: v0.3.1 changes: @@ -1315,8 +1337,8 @@ changes: 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. When supplied, the `cachedDataRejected` value will be set to - either `true` or `false` depending on acceptance of the data by V8. + 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 @@ -1350,6 +1372,7 @@ The following example illustrates using both `vm.runInThisContext()` and the JavaScript [`eval()`][] function to run the same code: <!-- eslint-disable prefer-const --> + ```js const vm = require('vm'); let localVar = 'initial value'; @@ -1364,7 +1387,7 @@ console.log(`evalResult: '${evalResult}', localVar: '${localVar}'`); ``` Because `vm.runInThisContext()` does not have access to the local scope, -`localVar` is unchanged. In contrast, [`eval()`][] *does* have access to the +`localVar` is unchanged. In contrast, [`eval()`][] _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')`. diff --git a/doc/api/wasi.md b/doc/api/wasi.md index e0cd77a5a42..644daa217e9 100644 --- a/doc/api/wasi.md +++ b/doc/api/wasi.md @@ -107,6 +107,7 @@ The `--experimental-wasi-unstable-preview1` CLI argument is needed for this example to run. ## Class: `WASI` + <!-- YAML added: - v13.3.0 @@ -120,6 +121,7 @@ instance must have its command-line arguments, environment variables, and sandbox directory structure configured explicitly. ### `new WASI([options])` + <!-- YAML added: - v13.3.0 @@ -148,6 +150,7 @@ added: WebAssembly application. **Default:** `2`. ### `wasi.start(instance)` + <!-- YAML added: - v13.3.0 @@ -166,6 +169,7 @@ Attempt to begin execution of `instance` as a WASI command by invoking its If `start()` is called more than once, an exception is thrown. ### `wasi.initialize(instance)` + <!-- YAML added: - v14.6.0 @@ -184,6 +188,7 @@ export, then an exception is thrown. If `initialize()` is called more than once, an exception is thrown. ### `wasi.wasiImport` + <!-- YAML added: - v13.3.0 diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md index 2d89abbf1c1..0a860d74470 100644 --- a/doc/api/webcrypto.md +++ b/doc/api/webcrypto.md @@ -306,32 +306,33 @@ async function digest(data, algorithm = 'SHA-512') { The table details the algorithms supported by the Node.js Web Crypto API implementation and the APIs supported for each: -| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` | -| --------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- | -| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | | -| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'SHA-1'` | | | | | | | | | | | | ✔ | -| `'SHA-256'` | | | | | | | | | | | | ✔ | -| `'SHA-384'` | | | | | | | | | | | | ✔ | -| `'SHA-512'` | | | | | | | | | | | | ✔ | -| `'NODE-DSA'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'NODE-DH'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'NODE-ED25519'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'NODE-ED448'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` | +| ---------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- | +| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | | +| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'SHA-1'` | | | | | | | | | | | | ✔ | +| `'SHA-256'` | | | | | | | | | | | | ✔ | +| `'SHA-384'` | | | | | | | | | | | | ✔ | +| `'SHA-512'` | | | | | | | | | | | | ✔ | +| `'NODE-DSA'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'NODE-DH'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'NODE-ED25519'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'NODE-ED448'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | <sup>1</sup> Node.js-specific extension ## Class: `Crypto` + <!-- YAML added: v15.0.0 --> @@ -340,6 +341,7 @@ Calling `require('crypto').webcrypto` returns an instance of the `Crypto` class. `Crypto` is a singleton that provides access to the remainder of the crypto API. ### `crypto.subtle` + <!-- YAML added: v15.0.0 --> @@ -349,6 +351,7 @@ added: v15.0.0 Provides access to the `SubtleCrypto` API. ### `crypto.getRandomValues(typedArray)` + <!-- YAML added: v15.0.0 --> @@ -362,6 +365,7 @@ filled with random values, and a reference to `typedArray` is returned. An error will be thrown if the given `typedArray` is larger than 65,536 bytes. ### `crypto.randomUUID()` + <!-- YAML added: v16.7.0 --> @@ -372,17 +376,21 @@ Generates a random [RFC 4122][] version 4 UUID. The UUID is generated using a cryptographic pseudorandom number generator. ## Class: `CryptoKey` + <!-- YAML added: v15.0.0 --> ### `cryptoKey.algorithm` + <!-- YAML added: v15.0.0 --> <!--lint disable maximum-line-length remark-lint--> + * Type: {AesKeyGenParams|RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|NodeDsaKeyGenParams|NodeDhKeyGenParams} + <!--lint enable maximum-line-length remark-lint--> An object detailing the algorithm for which the key can be used along with @@ -391,6 +399,7 @@ additional algorithm-specific parameters. Read-only. ### `cryptoKey.extractable` + <!-- YAML added: v15.0.0 --> @@ -403,6 +412,7 @@ When `true`, the {CryptoKey} can be extracted using either Read-only. ### `cryptoKey.type` + <!-- YAML added: v15.0.0 --> @@ -413,11 +423,12 @@ A string identifying whether the key is a symmetric (`'secret'`) or asymmetric (`'private'` or `'public'`) key. ### `cryptoKey.usages` + <!-- YAML added: v15.0.0 --> -* Type: {string[]} +* Type: {string\[]} An array of strings identifying the operations for which the key may be used. @@ -436,29 +447,30 @@ The possible usages are: Valid key usages depend on the key algorithm (identified by `cryptokey.algorithm.name`). -| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` | -| -------------------- | ----------- | ----------- | -------- | ---------- | ------------- | --------------- | ----------- | ------------- | -| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'AES-KW'` | | | | | | | ✔ | ✔ | -| `'ECDH'` | | | | | ✔ | ✔ | | | -| `'ECDSA'` | | | ✔ | ✔ | | | | | -| `'HDKF'` | | | | | ✔ | ✔ | | | -| `'HMAC'` | | | ✔ | ✔ | | | | | -| `'PBKDF2'` | | | | | ✔ | ✔ | | | -| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'RSA-PSS'` | | | ✔ | ✔ | | | | | -| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | | -| `'NODE-DSA'` <sup>1</sup> | | | ✔ | ✔ | | | | | -| `'NODE-DH'` <sup>1</sup> | | | | | ✔ | ✔ | | | -| `'NODE-SCRYPT'` <sup>1</sup> | | | | | ✔ | ✔ | | | -| `'NODE-ED25519'` <sup>1</sup> | | | ✔ | ✔ | | | | | -| `'NODE-ED448'` <sup>1</sup> | | | ✔ | ✔ | | | | | +| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` | +| ----------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- | +| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'AES-KW'` | | | | | | | ✔ | ✔ | +| `'ECDH'` | | | | | ✔ | ✔ | | | +| `'ECDSA'` | | | ✔ | ✔ | | | | | +| `'HDKF'` | | | | | ✔ | ✔ | | | +| `'HMAC'` | | | ✔ | ✔ | | | | | +| `'PBKDF2'` | | | | | ✔ | ✔ | | | +| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'RSA-PSS'` | | | ✔ | ✔ | | | | | +| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | | +| `'NODE-DSA'` <sup>1</sup> | | | ✔ | ✔ | | | | | +| `'NODE-DH'` <sup>1</sup> | | | | | ✔ | ✔ | | | +| `'NODE-SCRYPT'` <sup>1</sup> | | | | | ✔ | ✔ | | | +| `'NODE-ED25519'` <sup>1</sup> | | | ✔ | ✔ | | | | | +| `'NODE-ED448'` <sup>1</sup> | | | ✔ | ✔ | | | | | <sup>1</sup> Node.js-specific extension. ## Class: `CryptoKeyPair` + <!-- YAML added: v15.0.0 --> @@ -467,6 +479,7 @@ The `CryptoKeyPair` is a simple dictionary object with `publicKey` and `privateKey` properties, representing an asymmetric key pair. ### `cryptoKeyPair.privateKey` + <!-- YAML added: v15.0.0 --> @@ -474,6 +487,7 @@ added: v15.0.0 * Type: {CryptoKey} A {CryptoKey} whose `type` will be `'private'`. ### `cryptoKeyPair.publicKey` + <!-- YAML added: v15.0.0 --> @@ -481,11 +495,13 @@ added: v15.0.0 * Type: {CryptoKey} A {CryptoKey} whose `type` will be `'public'`. ## Class: `SubtleCrypto` + <!-- YAML added: v15.0.0 --> ### `subtle.decrypt(algorithm, key, data)` + <!-- YAML added: v15.0.0 --> @@ -508,15 +524,18 @@ The algorithms currently supported include: * `'AES-GCM`' ### `subtle.deriveBits(algorithm, baseKey, length)` + <!-- YAML added: v15.0.0 --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params|NodeDhDeriveBitsParams|NodeScryptParams} * `baseKey`: {CryptoKey} * `length`: {number} * Returns: {Promise} containing {ArrayBuffer} + <!--lint enable maximum-line-length remark-lint--> Using the method and parameters specified in `algorithm` and the keying @@ -536,17 +555,20 @@ The algorithms currently supported include: <sup>1</sup> Node.js-specific extension ### `subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)` + <!-- YAML added: v15.0.0 --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm`: {EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params|NodeDhDeriveBitsParams|NodeScryptParams} * `baseKey`: {CryptoKey} * `derivedKeyAlgorithm`: {HmacKeyGenParams|AesKeyGenParams} * `extractable`: {boolean} -* `keyUsages`: {string[]} See [Key usages][]. +* `keyUsages`: {string\[]} See [Key usages][]. * Returns: {Promise} containing {CryptoKey} + <!--lint enable maximum-line-length remark-lint--> Using the method and parameters specified in `algorithm`, and the keying @@ -569,6 +591,7 @@ The algorithms currently supported include: <sup>1</sup> Node.js-specific extension ### `subtle.digest(algorithm, data)` + <!-- YAML added: v15.0.0 --> @@ -592,6 +615,7 @@ If `algorithm` is provided as an {Object}, it must have a `name` property whose value is one of the above. ### `subtle.encrypt(algorithm, key, data)` + <!-- YAML added: v15.0.0 --> @@ -613,6 +637,7 @@ The algorithms currently supported include: * `'AES-GCM`' ### `subtle.exportKey(format, key)` + <!-- YAML added: v15.0.0 changes: @@ -642,38 +667,42 @@ specification. The special `'node.keyObject'` value for `format` is a Node.js-specific extension that allows converting a {CryptoKey} into a Node.js {KeyObject}. -| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | -| --------------------- | -------- | --------- | ------- | ------- | -| `'AES-CBC'` | | | ✔ | ✔ | -| `'AES-CTR'` | | | ✔ | ✔ | -| `'AES-GCM'` | | | ✔ | ✔ | -| `'AES-KW'` | | | ✔ | ✔ | -| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | -| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | -| `'HDKF'` | | | | | -| `'HMAC'` | | | ✔ | ✔ | -| `'PBKDF2'` | | | | | -| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | -| `'RSA-PSS'` | ✔ | ✔ | ✔ | | -| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | -| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | | | -| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | | -| `'NODE-SCRYPT'` <sup>1</sup> | | | | | -| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | -| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | +| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | +| ----------------------------- | -------- | --------- | ------- | ------- | +| `'AES-CBC'` | | | ✔ | ✔ | +| `'AES-CTR'` | | | ✔ | ✔ | +| `'AES-GCM'` | | | ✔ | ✔ | +| `'AES-KW'` | | | ✔ | ✔ | +| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | +| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | +| `'HDKF'` | | | | | +| `'HMAC'` | | | ✔ | ✔ | +| `'PBKDF2'` | | | | | +| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | +| `'RSA-PSS'` | ✔ | ✔ | ✔ | | +| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | +| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | | | +| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | | +| `'NODE-SCRYPT'` <sup>1</sup> | | | | | +| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | +| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | <sup>1</sup> Node.js-specific extension ### `subtle.generateKey(algorithm, extractable, keyUsages)` + <!-- YAML added: v15.0.0 --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm`: {RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams|NodeDsaKeyGenParams|NodeDhKeyGenParams|NodeEdKeyGenParams} + <!--lint enable maximum-line-length remark-lint--> + * `extractable`: {boolean} -* `keyUsages`: {string[]} See [Key usages][]. +* `keyUsages`: {string\[]} See [Key usages][]. * Returns: {Promise} containing {CryptoKey|CryptoKeyPair} Using the method and parameters provided in `algorithm`, `subtle.generateKey()` @@ -704,6 +733,7 @@ The {CryptoKey} (secret key) generating algorithms supported include: <sup>1</sup> Non-standard Node.js extension ### `subtle.importKey(format, keyData, algorithm, extractable, keyUsages)` + <!-- YAML added: v15.0.0 changes: @@ -715,11 +745,15 @@ changes: * `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, `'jwk'`, or `'node.keyObject'`. * `keyData`: {ArrayBuffer|TypedArray|DataView|Buffer|KeyObject} + <!--lint disable maximum-line-length remark-lint--> + * `algorithm`: {RsaHashedImportParams|EcKeyImportParams|HmacImportParams|AesImportParams|Pbkdf2ImportParams|NodeDsaImportParams|NodeDhImportParams|NodeScryptImportParams|NodeEdKeyImportParams} + <!--lint enable maximum-line-length remark-lint--> + * `extractable`: {boolean} -* `keyUsages`: {string[]} See [Key usages][]. +* `keyUsages`: {string\[]} See [Key usages][]. * Returns: {Promise} containing {CryptoKey} The `subtle.importKey()` method attempts to interpret the provided `keyData` @@ -734,38 +768,41 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`. The algorithms currently supported include: -| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | -| --------------------- | -------- | --------- | ------- | ------- | -| `'AES-CBC'` | | | ✔ | ✔ | -| `'AES-CTR'` | | | ✔ | ✔ | -| `'AES-GCM'` | | | ✔ | ✔ | -| `'AES-KW'` | | | ✔ | ✔ | -| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | -| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | -| `'HDKF'` | | | | ✔ | -| `'HMAC'` | | | ✔ | ✔ | -| `'PBKDF2'` | | | | ✔ | -| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | -| `'RSA-PSS'` | ✔ | ✔ | ✔ | | -| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | -| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | | | -| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | | -| `'NODE-SCRYPT'` <sup>1</sup> | | | | ✔ | -| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | -| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | +| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | +| ----------------------------- | -------- | --------- | ------- | ------- | +| `'AES-CBC'` | | | ✔ | ✔ | +| `'AES-CTR'` | | | ✔ | ✔ | +| `'AES-GCM'` | | | ✔ | ✔ | +| `'AES-KW'` | | | ✔ | ✔ | +| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | +| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | +| `'HDKF'` | | | | ✔ | +| `'HMAC'` | | | ✔ | ✔ | +| `'PBKDF2'` | | | | ✔ | +| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | +| `'RSA-PSS'` | ✔ | ✔ | ✔ | | +| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | +| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | | | +| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | | +| `'NODE-SCRYPT'` <sup>1</sup> | | | | ✔ | +| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | +| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | <sup>1</sup> Node.js-specific extension ### `subtle.sign(algorithm, key, data)` + <!-- YAML added: v15.0.0 --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm`: {RsaSignParams|RsaPssParams|EcdsaParams|HmacParams|NodeDsaSignParams} * `key`: {CryptoKey} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} * Returns: {Promise} containing {ArrayBuffer} + <!--lint enable maximum-line-length remark-lint--> Using the method and parameters given by `algorithm` and the keying material @@ -786,6 +823,7 @@ The algorithms currently supported include: <sup>1</sup> Non-standard Node.js extension ### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)` + <!-- YAML added: v15.0.0 --> @@ -793,12 +831,16 @@ added: v15.0.0 * `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`. * `wrappedKey`: {ArrayBuffer|TypedArray|DataView|Buffer} * `unwrappingKey`: {CryptoKey} + <!--lint disable maximum-line-length remark-lint--> + * `unwrapAlgo`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams|AesKwParams} * `unwrappedKeyAlgo`: {RsaHashedImportParams|EcKeyImportParams|HmacImportParams|AesImportParams} + <!--lint enable maximum-line-length remark-lint--> + * `extractable`: {boolean} -* `keyUsages`: {string[]} See [Key usages][]. +* `keyUsages`: {string\[]} See [Key usages][]. * Returns: {Promise} containing {CryptoKey} In cryptography, "wrapping a key" refers to exporting and then encrypting the @@ -836,16 +878,19 @@ The unwrapped key algorithms supported include: <sup>1</sup> Non-standard Node.js extension ### `subtle.verify(algorithm, key, signature, data)` + <!-- YAML added: v15.0.0 --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm`: {RsaSignParams|RsaPssParams|EcdsaParams|HmacParams|NodeDsaSignParams} * `key`: {CryptoKey} * `signature`: {ArrayBuffer|TypedArray|DataView|Buffer} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} * Returns: {Promise} containing {boolean} + <!--lint enable maximum-line-length remark-lint--> Using the method and parameters given in `algorithm` and the keying material @@ -866,6 +911,7 @@ The algorithms currently supported include: <sup>1</sup> Non-standard Node.js extension ### `subtle.wrapKey(format, key, wrappingKey, wrapAlgo)` + <!-- YAML added: v15.0.0 --> @@ -901,11 +947,13 @@ the various {SubtleCrypto} methods. While described here as "classes", they are simple JavaScript dictionary objects. ### Class: `AesCbcParams` + <!-- YAML added: v15.0.0 --> #### `aesCbcParams.iv` + <!-- YAML added: v15.0.0 --> @@ -916,6 +964,7 @@ Provides the initialization vector. It must be exactly 16-bytes in length and should be unpredictable and cryptographically random. #### `aesCbcParams.name` + <!-- YAML added: v15.0.0 --> @@ -923,11 +972,13 @@ added: v15.0.0 * Type: {string} Must be `'AES-CBC'`. ### Class: `AesCtrParams` + <!-- YAML added: v15.0.0 --> #### `aesCtrParams.counter` + <!-- YAML added: v15.0.0 --> @@ -940,6 +991,7 @@ The `AES-CTR` method uses the rightmost `length` bits of the block as the counter and the remaining bits as the nonce. #### `aesCtrParams.length` + <!-- YAML added: v15.0.0 --> @@ -948,6 +1000,7 @@ added: v15.0.0 to be used as the counter. #### `aesCtrParams.name` + <!-- YAML added: v15.0.0 --> @@ -955,11 +1008,13 @@ added: v15.0.0 * Type: {string} Must be `'AES-CTR'`. ### Class: `AesGcmParams` + <!-- YAML added: v15.0.0 --> #### `aesGcmParams.additionalData` + <!-- YAML added: v15.0.0 --> @@ -971,6 +1026,7 @@ encrypted but is included in the authentication of the data. The use of `additionalData` is optional. #### `aesGcmParams.iv` + <!-- YAML added: v15.0.0 --> @@ -982,6 +1038,7 @@ using a given key. It is recommended by the AES-GCM specification that this contain at least 12 random bytes. #### `aesGcmParams.name` + <!-- YAML added: v15.0.0 --> @@ -989,6 +1046,7 @@ added: v15.0.0 * Type: {string} Must be `'AES-GCM'`. #### `aesGcmParams.tagLength` + <!-- YAML added: v15.0.0 --> @@ -998,11 +1056,13 @@ added: v15.0.0 `128`. **Default:** `128`. ### Class: `AesImportParams` + <!-- YAML added: v15.0.0 --> #### `aesImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1011,11 +1071,13 @@ added: v15.0.0 `'AES-KW'`. ### Class: `AesKeyGenParams` + <!-- YAML added: v15.0.0 --> #### `aesKeyGenParams.length` + <!-- YAML added: v15.0.0 --> @@ -1026,6 +1088,7 @@ The length of the AES key to be generated. This must be either `128`, `192`, or `256`. #### `aesKeyGenParams.name` + <!-- YAML added: v15.0.0 --> @@ -1034,11 +1097,13 @@ added: v15.0.0 `'AES-KW'` ### Class: `AesKwParams` + <!-- YAML added: v15.0.0 --> #### `aesKwParams.name` + <!-- YAML added: v15.0.0 --> @@ -1046,11 +1111,13 @@ added: v15.0.0 * Type: {string} Must be `'AES-KW'`. ### Class: `EcdhKeyDeriveParams` + <!-- YAML added: v15.0.0 --> #### `ecdhKeyDeriveParams.name` + <!-- YAML added: v15.0.0 --> @@ -1058,6 +1125,7 @@ added: v15.0.0 * Type: {string} Must be `'ECDH'`. #### `ecdhKeyDeriveParams.public` + <!-- YAML added: v15.0.0 --> @@ -1070,11 +1138,13 @@ The `ecdhKeyDeriveParams.public` property is set to the other parties public key. ### Class: `EcdsaParams` + <!-- YAML added: v15.0.0 --> #### `ecdsaParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1092,6 +1162,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `ecdsaParams.name` + <!-- YAML added: v15.0.0 --> @@ -1099,11 +1170,13 @@ added: v15.0.0 * Type: {string} Must be `'ECDSA'`. ### Class: `EcKeyGenParams` + <!-- YAML added: v15.0.0 --> #### `ecKeyGenParams.name` + <!-- YAML added: v15.0.0 --> @@ -1111,6 +1184,7 @@ added: v15.0.0 * Type: {string} Must be one of `'ECDSA'` or `'ECDH'`. #### `ecKeyGenParams.namedCurve` + <!-- YAML added: v15.0.0 --> @@ -1119,11 +1193,13 @@ added: v15.0.0 `'NODE-ED25519'`, `'NODE-ED448'`, `'NODE-X25519'`, or `'NODE-X448'`. ### Class: `EcKeyImportParams` + <!-- YAML added: v15.0.0 --> #### `ecKeyImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1131,6 +1207,7 @@ added: v15.0.0 * Type: {string} Must be one of `'ECDSA'` or `'ECDH'`. #### `ecKeyImportParams.namedCurve` + <!-- YAML added: v15.0.0 --> @@ -1139,11 +1216,13 @@ added: v15.0.0 `'NODE-ED25519'`, `'NODE-ED448'`, `'NODE-X25519'`, or `'NODE-X448'`. ### Class: `HkdfParams` + <!-- YAML added: v15.0.0 --> #### `hkdfParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1161,6 +1240,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `hkdfParams.info` + <!-- YAML added: v15.0.0 --> @@ -1171,6 +1251,7 @@ Provides application-specific contextual input to the HKDF algorithm. This can be zero-length but must be provided. #### `hkdfParams.name` + <!-- YAML added: v15.0.0 --> @@ -1178,6 +1259,7 @@ added: v15.0.0 * Type: {string} Must be `'HKDF'`. #### `hkdfParams.salt` + <!-- YAML added: v15.0.0 --> @@ -1190,11 +1272,13 @@ output of the digest function (for instance, if using `'SHA-256'` as the digest, the salt should be 256-bits of random data). ### Class: `HmacImportParams` + <!-- YAML added: v15.0.0 --> #### `hmacImportParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1212,6 +1296,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `hmacImportParams.length` + <!-- YAML added: v15.0.0 --> @@ -1222,6 +1307,7 @@ The optional number of bits in the HMAC key. This is optional and should be omitted for most cases. #### `hmacImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1229,11 +1315,13 @@ added: v15.0.0 * Type: {string} Must be `'HMAC'`. ### Class: `HmacKeyGenParams` + <!-- YAML added: v15.0.0 --> #### `hmacKeyGenParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1251,6 +1339,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `hmacKeyGenParams.length` + <!-- YAML added: v15.0.0 --> @@ -1262,6 +1351,7 @@ the length will be determined by the hash algorithm used. This is optional and should be omitted for most cases. #### `hmacKeyGenParams.name` + <!-- YAML added: v15.0.0 --> @@ -1269,11 +1359,13 @@ added: v15.0.0 * Type: {string} Must be `'HMAC'`. ### Class: `HmacParams` + <!-- YAML added: v15.0.0 --> #### `hmacParams.name` + <!-- YAML added: v15.0.0 --> @@ -1281,11 +1373,13 @@ added: v15.0.0 * Type: {string} Must be `'HMAC'`. ### Class: `Pbkdf2ImportParams` + <!-- YAML added: v15.0.0 --> #### `pbkdf2ImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1293,11 +1387,13 @@ added: v15.0.0 * Type: {string} Must be `'PBKDF2'` ### Class: `Pbkdf2Params` + <!-- YAML added: v15.0.0 --> #### `pbkdb2Params.hash` + <!-- YAML added: v15.0.0 --> @@ -1315,6 +1411,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `pbkdf2Params.iterations` + <!-- YAML added: v15.0.0 --> @@ -1324,6 +1421,7 @@ added: v15.0.0 The number of iterations the PBKDF2 algorithm should make when deriving bits. #### `pbkdf2Params.name` + <!-- YAML added: v15.0.0 --> @@ -1331,6 +1429,7 @@ added: v15.0.0 * Type: {string} Must be `'PBKDF2'`. #### `pbkdf2Params.salt` + <!-- YAML added: v15.0.0 --> @@ -1340,11 +1439,13 @@ added: v15.0.0 Should be at least 16 random or pseudorandom bytes. ### Class: `RsaHashedImportParams` + <!-- YAML added: v15.0.0 --> #### `rsaHashedImportParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1362,6 +1463,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `rsaHashedImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1370,11 +1472,13 @@ added: v15.0.0 `'RSA-OAEP'`. ### Class: `RsaHashedKeyGenParams` + <!-- YAML added: v15.0.0 --> #### `rsaHashedKeyGenParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1392,6 +1496,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. #### `rsaHashedKeyGenParams.modulusLength` + <!-- YAML added: v15.0.0 --> @@ -1402,6 +1507,7 @@ The length in bits of the RSA modulus. As a best practice, this should be at least `2048`. #### `rsaHashedKeyGenParams.name` + <!-- YAML added: v15.0.0 --> @@ -1410,6 +1516,7 @@ added: v15.0.0 `'RSA-OAEP'`. #### `rsaHashedKeyGenParams.publicExponent` + <!-- YAML added: v15.0.0 --> @@ -1423,11 +1530,13 @@ there is reason to use a different value, use `new Uint8Array([1, 0, 1])` (65537) as the public exponent. ### Class: `RsaOaepParams` + <!-- YAML added: v15.0.0 --> #### rsaOaepParams.label + <!-- YAML added: v15.0.0 --> @@ -1440,6 +1549,7 @@ to the generated ciphertext. The `rsaOaepParams.label` parameter is optional. #### rsaOaepParams.name + <!-- YAML added: v15.0.0 --> @@ -1447,11 +1557,13 @@ added: v15.0.0 * Type: {string} must be `'RSA-OAEP'`. ### Class: `RsaPssParams` + <!-- YAML added: v15.0.0 --> #### `rsaPssParams.name` + <!-- YAML added: v15.0.0 --> @@ -1459,6 +1571,7 @@ added: v15.0.0 * Type: {string} Must be `'RSA-PSS'`. #### `rsaPssParams.saltLength` + <!-- YAML added: v15.0.0 --> @@ -1468,11 +1581,13 @@ added: v15.0.0 The length (in bytes) of the random salt to use. ### Class: `RsaSignParams` + <!-- YAML added: v15.0.0 --> #### `rsaSignParams.name` + <!-- YAML added: v15.0.0 --> @@ -1492,6 +1607,7 @@ not supported by other WebCrypto implementations and reduce the portability of code to other environments. ### `NODE-DH` Algorithm + <!-- YAML added: v15.0.0 --> @@ -1500,11 +1616,13 @@ The `NODE-DH` algorithm is the common implementation of Diffie-Hellman key agreement. #### Class: `NodeDhImportParams` + <!-- YAML added: v15.0.0 --> ##### `nodeDhImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1512,11 +1630,13 @@ added: v15.0.0 * Type: {string} Must be `'NODE-DH'`. #### Class: `NodeDhKeyGenParams` + <!-- YAML added: v15.0.0 --> ##### `nodeDhKeyGenParams.generator` + <!-- YAML added: v15.0.0 --> @@ -1524,6 +1644,7 @@ added: v15.0.0 * Type: {number} A custom generator. ##### `nodeDhKeyGenParams.group` + <!-- YAML added: v15.0.0 --> @@ -1531,6 +1652,7 @@ added: v15.0.0 * Type: {string} The Diffie-Hellman group name. ##### `nodeDhKeyGenParams.prime` + <!-- YAML added: v15.0.0 --> @@ -1538,6 +1660,7 @@ added: v15.0.0 * Type: {Buffer} The prime parameter. ##### `nodeDhKeyGenParams.primeLength` + <!-- YAML added: v15.0.0 --> @@ -1545,11 +1668,13 @@ added: v15.0.0 * Type: {number} The length in bits of the prime. #### Class: NodeDhDeriveBitsParams + <!-- YAML added: v15.0.0 --> ##### `nodeDhDeriveBitsParams.public` + <!-- YAML added: v15.0.0 --> @@ -1557,6 +1682,7 @@ added: v15.0.0 * Type: {CryptoKey} The other parties public key. ### `NODE-DSA` Algorithm + <!-- YAML added: v15.0.0 --> @@ -1565,11 +1691,13 @@ The `NODE-DSA` algorithm is the common implementation of the DSA digital signature algorithm. #### Class: `NodeDsaImportParams` + <!-- YAML added: v15.0.0 --> ##### `nodeDsaImportParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1587,6 +1715,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. ##### `nodeDsaImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1594,11 +1723,13 @@ added: v15.0.0 * Type: {string} Must be `'NODE-DSA'`. #### Class: `NodeDsaKeyGenParams` + <!-- YAML added: v15.0.0 --> ##### `nodeDsaKeyGenParams.divisorLength` + <!-- YAML added: v15.0.0 --> @@ -1608,6 +1739,7 @@ added: v15.0.0 The optional length in bits of the DSA divisor. ##### `nodeDsaKeyGenParams.hash` + <!-- YAML added: v15.0.0 --> @@ -1625,6 +1757,7 @@ If represented as an {Object}, the object must have a `name` property whose value is one of the above listed values. ##### `nodeDsaKeyGenParams.modulusLength` + <!-- YAML added: v15.0.0 --> @@ -1635,6 +1768,7 @@ The length in bits of the DSA modulus. As a best practice, this should be at least `2048`. ##### `nodeDsaKeyGenParams.name` + <!-- YAML added: v15.0.0 --> @@ -1642,11 +1776,13 @@ added: v15.0.0 * Type: {string} Must be `'NODE-DSA'`. #### Class: `NodeDsaSignParams` + <!-- YAML added: v15.0.0 --> ##### `nodeDsaSignParams.name` + <!-- YAML added: v15.0.0 --> @@ -1654,16 +1790,19 @@ added: v15.0.0 * Type: {string} Must be `'NODE-DSA'` ### `NODE-ED25519` and `NODE-ED448` Algorithms + <!-- YAML added: v15.8.0 --> #### Class: `NodeEdKeyGenParams` + <!-- YAML added: v15.8.0 --> ##### `nodeEdKeyGenParams.name` + <!-- YAML added: v15.8.0 --> @@ -1671,6 +1810,7 @@ added: v15.8.0 * Type: {string} Must be one of `'NODE-ED25519'`, `'NODE-ED448'` or `'ECDH'`. ##### `nodeEdKeyGenParams.namedCurve` + <!-- YAML added: v15.8.0 --> @@ -1679,11 +1819,13 @@ added: v15.8.0 `'NODE-X25519'`, or `'NODE-X448'`. #### Class: `NodeEdKeyImportParams` + <!-- YAML added: v15.8.0 --> ##### `nodeEdKeyImportParams.name` + <!-- YAML added: v15.8.0 --> @@ -1693,6 +1835,7 @@ added: v15.8.0 an `X25519` or `X448` key. ##### `nodeEdKeyImportParams.namedCurve` + <!-- YAML added: v15.8.0 --> @@ -1701,6 +1844,7 @@ added: v15.8.0 `'NODE-X25519'`, or `'NODE-X448'`. ##### `nodeEdKeyImportParams.public` + <!-- YAML added: v15.8.0 --> @@ -1711,6 +1855,7 @@ The `public` parameter is used to specify that the `'raw'` format key is to be interpreted as a public key. **Default:** `false`. ### `NODE-SCRYPT` Algorithm + <!-- YAML added: v15.0.0 --> @@ -1719,11 +1864,13 @@ The `NODE-SCRYPT` algorithm is the common implementation of the scrypt key derivation algorithm. #### Class: `NodeScryptImportParams` + <!-- YAML added: v15.0.0 --> ##### `nodeScryptImportParams.name` + <!-- YAML added: v15.0.0 --> @@ -1731,11 +1878,13 @@ added: v15.0.0 * Type: {string} Must be `'NODE-SCRYPT'`. #### Class: `NodeScryptParams` + <!-- YAML added: v15.0.0 --> ##### `nodeScryptParams.encoding` + <!-- YAML added: v15.0.0 --> @@ -1743,6 +1892,7 @@ added: v15.0.0 * Type: {string} The string encoding when `salt` is a string. ##### `nodeScryptParams.maxmem` + <!-- YAML added: v15.0.0 --> @@ -1751,6 +1901,7 @@ added: v15.0.0 `127 * N * r > maxmem`. **Default:** `32 * 1024 * 1024`. ##### `nodeScryptParams.N` + <!-- YAML added: v15.0.0 --> @@ -1759,6 +1910,7 @@ added: v15.0.0 greater than 1. **Default:** `16384`. ##### `nodeScryptParams.p` + <!-- YAML added: v15.0.0 --> @@ -1766,6 +1918,7 @@ added: v15.0.0 * Type: {number} Parallelization parameter. **Default:** `1`. ##### `nodeScryptParams.r` + <!-- YAML added: v15.0.0 --> @@ -1773,6 +1926,7 @@ added: v15.0.0 * Type: {number} Block size parameter. **Default:** `8`. ##### `nodeScryptParams.salt` + <!-- YAML added: v15.0.0 --> diff --git a/doc/api/webstreams.md b/doc/api/webstreams.md index f020cbc618a..99514a58e91 100644 --- a/doc/api/webstreams.md +++ b/doc/api/webstreams.md @@ -98,16 +98,19 @@ const stream = new ReadableStream({ ## API ### Class: `ReadableStream` + <!-- YAML added: v16.5.0 --> #### `new ReadableStream([underlyingSource [, strategy]])` + <!-- YAML added: v16.5.0 --> <!--lint disable maximum-line-length remark-lint--> + * `underlyingSource` {Object} * `start` {Function} A user-defined function that is invoked immediately when the `ReadableStream` is created. @@ -133,9 +136,11 @@ added: v16.5.0 chunk of data. * `chunk` {any} * Returns: {number} + <!--lint enable maximum-line-length remark-lint--> #### `readableStream.locked` + <!-- YAML added: v16.5.0 --> @@ -148,6 +153,7 @@ switch to `true` while there is an active reader consuming the stream's data. #### `readableStream.cancel([reason])` + <!-- YAML added: v16.5.0 --> @@ -157,6 +163,7 @@ added: v16.5.0 been completed. #### `readableStream.getReader([options])` + <!-- YAML added: v16.5.0 --> @@ -188,6 +195,7 @@ reader.read().then(console.log); Causes the `readableStream.locked` to be `true`. #### `readableStream.pipeThrough(transform[, options])` + <!-- YAML added: v16.5.0 --> @@ -270,6 +278,7 @@ const transformedStream = stream.pipeThrough(transform); ``` #### `readableStream.pipeTo(destination, options)` + <!-- YAML added: v16.5.0 --> @@ -292,11 +301,12 @@ Causes the `readableStream.locked` to be `true` while the pipe operation is active. #### `readableStream.tee()` + <!-- YAML added: v16.5.0 --> -* Returns: {ReadableStream[]} +* Returns: {ReadableStream\[]} Returns a pair of new {ReadableStream} instances to which this `ReadableStream`'s data will be forwarded. Each will receive the @@ -305,6 +315,7 @@ same data. Causes the `readableStream.locked` to be `true`. #### `readableStream.values([options])` + <!-- YAML added: v16.5.0 --> @@ -373,6 +384,7 @@ port2.postMessage(stream, [stream]); ``` ### Class: `ReadableStreamDefaultReader` + <!-- YAML added: v16.5.0 --> @@ -384,6 +396,7 @@ values, which allows the {ReadableStream} to work with generally any JavaScript value. #### `new ReadableStreamDefaultReader(stream)` + <!-- YAML added: v16.5.0 --> @@ -394,6 +407,7 @@ Creates a new {ReadableStreamDefaultReader} that is locked to the given {ReadableStream}. #### `readableStreamDefaultReader.cancel([reason])` + <!-- YAML added: v16.5.0 --> @@ -405,6 +419,7 @@ Cancels the {ReadableStream} and returns a promise that is fulfilled when the underlying stream has been canceled. #### `readableStreamDefaultReader.closed` + <!-- YAML added: v16.5.0 --> @@ -413,6 +428,7 @@ added: v16.5.0 {ReadableStream} is closed or this reader's lock is released. #### `readableStreamDefaultReader.read()` + <!-- YAML added: v16.5.0 --> @@ -426,6 +442,7 @@ and returns a promise that is fulfilled with the data once it is available. #### `readableStreamDefaultReader.releaseLock()` + <!-- YAML added: v16.5.0 --> @@ -433,13 +450,14 @@ added: v16.5.0 Releases this reader's lock on the underlying {ReadableStream}. ### Class: `ReadableStreamBYOBReader` + <!-- YAML added: v16.5.0 --> The `ReadableStreamBYOBReader` is an alternative consumer for byte-oriented {ReadableStream}'s (those that are created with -`underlyingSource.type` set equal to `'bytes`` when the +`underlyingSource.type` set equal to `'bytes'` when the `ReadableStream` was created). The `BYOB` is short for "bring your own buffer". This is a @@ -505,6 +523,7 @@ console.log(Buffer.from(data).toString()); ``` #### `new ReadableStreamBYOBReader(stream)` + <!-- YAML added: v16.5.0 --> @@ -515,6 +534,7 @@ Creates a new `ReadableStreamBYOBReader` that is locked to the given {ReadableStream}. #### `readableStreamBYOBReader.cancel([reason])` + <!-- YAML added: v16.5.0 --> @@ -526,6 +546,7 @@ Cancels the {ReadableStream} and returns a promise that is fulfilled when the underlying stream has been canceled. #### `readableStreamBYOBReader.closed` + <!-- YAML added: v16.5.0 --> @@ -534,6 +555,7 @@ added: v16.5.0 {ReadableStream} is closed or this reader's lock is released. #### `readableStreamBYOBReader.read(view)` + <!-- YAML added: v16.5.0 --> @@ -554,11 +576,12 @@ callbacks. These types of `Buffer`s use a shared underlying {ArrayBuffer} object that contains all of the data from all of the pooled `Buffer` instances. When a `Buffer`, {TypedArray}, or {DataView} is passed in to `readableStreamBYOBReader.read()`, -the view's underlying `ArrayBuffer` is *detached*, invalidating +the view's underlying `ArrayBuffer` is _detached_, invalidating all existing views that may exist on that `ArrayBuffer`. This can have disastrous consequences for your application. #### `readableStreamBYOBReader.releaseLock()` + <!-- YAML added: v16.5.0 --> @@ -566,6 +589,7 @@ added: v16.5.0 Releases this reader's lock on the underlying {ReadableStream}. ### Class: `ReadableStreamDefaultController` + <!-- YAML added: v16.5.0 --> @@ -576,6 +600,7 @@ the internal state and management of the stream's queue. The implementation for `ReadableStream`s that are not byte-oriented. #### `readableStreamDefaultController.close()` + <!-- YAML added: v16.5.0 --> @@ -583,6 +608,7 @@ added: v16.5.0 Closes the {ReadableStream} to which this controller is associated. #### `readableStreamDefaultController.desiredSize` + <!-- YAML added: v16.5.0 --> @@ -593,6 +619,7 @@ Returns the amount of data remaining to fill the {ReadableStream}'s queue. #### `readableStreamDefaultController.enqueue(chunk)` + <!-- YAML added: v16.5.0 --> @@ -602,6 +629,7 @@ added: v16.5.0 Appends a new chunk of data to the {ReadableStream}'s queue. #### `readableStreamDefaultController.error(error)` + <!-- YAML added: v16.5.0 --> @@ -611,6 +639,7 @@ added: v16.5.0 Signals an error that causes the {ReadableStream} to error and close. ### Class: `ReadableByteStreamController` + <!-- YAML added: v16.5.0 --> @@ -620,6 +649,7 @@ the internal state and management of the stream's queue. The `ReadableByteStreamController` is for byte-oriented `ReadableStream`s. #### `readableByteStreamController.byobRequest` + <!-- YAML added: v16.5.0 --> @@ -627,6 +657,7 @@ added: v16.5.0 * Type: {ReadableStreamBYOBRequest} #### `readableByteStreamController.close()` + <!-- YAML added: v16.5.0 --> @@ -634,6 +665,7 @@ added: v16.5.0 Closes the {ReadableStream} to which this controller is associated. #### `readableByteStreamController.desiredSize` + <!-- YAML added: v16.5.0 --> @@ -644,6 +676,7 @@ Returns the amount of data remaining to fill the {ReadableStream}'s queue. #### `readableByteStreamController.enqueue(chunk)` + <!-- YAML added: v16.5.0 --> @@ -653,6 +686,7 @@ added: v16.5.0 Appends a new chunk of data to the {ReadableStream}'s queue. #### `readableByteStreamController.error(error)` + <!-- YAML added: v16.5.0 --> @@ -662,6 +696,7 @@ added: v16.5.0 Signals an error that causes the {ReadableStream} to error and close. ### Class: `ReadableStreamBYOBRequest` + <!-- YAML added: v16.5.0 --> @@ -677,6 +712,7 @@ and provides methods for signaling that the data has been provided. #### `readableStreamBYOBRequest.respond(bytesWritten)` + <!-- YAML added: v16.5.0 --> @@ -687,6 +723,7 @@ Signals that a `bytesWritten` number of bytes have been written to `readableStreamBYOBRequest.view`. #### `readableStreamBYOBRequest.respondWithNewView(view)` + <!-- YAML added: v16.5.0 --> @@ -697,6 +734,7 @@ Signals that the request has been fulfilled with bytes written to a new `Buffer`, `TypedArray`, or `DataView`. #### `readableStreamBYOBRequest.view` + <!-- YAML added: v16.5.0 --> @@ -704,6 +742,7 @@ added: v16.5.0 * Type: {Buffer|TypedArray|DataView} ### Class: `WritableStream` + <!-- YAML added: v16.5.0 --> @@ -725,6 +764,7 @@ await stream.getWriter().write('Hello World'); ``` #### `new WritableStream([underlyingSink[, strategy]])` + <!-- YAML added: v16.5.0 --> @@ -746,7 +786,7 @@ added: v16.5.0 the `WritableStream`. * `reason` {any} * Returns: A promise fulfilled with `undefined`. - * `type` {any} The `type` option is reserved for future use and *must* be + * `type` {any} The `type` option is reserved for future use and _must_ be undefined. * `strategy` {Object} * `highWaterMark` {number} The maximum internal queue size before backpressure @@ -757,6 +797,7 @@ added: v16.5.0 * Returns: {number} #### `writableStream.abort([reason])` + <!-- YAML added: v16.5.0 --> @@ -768,6 +809,7 @@ Abruptly terminates the `WritableStream`. All queued writes will be canceled with their associated promises rejected. #### `writableStream.close()` + <!-- YAML added: v16.5.0 --> @@ -777,6 +819,7 @@ added: v16.5.0 Closes the `WritableStream` when no additional writes are expected. #### `writableStream.getWriter()` + <!-- YAML added: v16.5.0 --> @@ -787,6 +830,7 @@ Creates and creates a new writer instance that can be used to write data into the `WritableStream`. #### `writableStream.locked` + <!-- YAML added: v16.5.0 --> @@ -814,11 +858,13 @@ port2.postMessage(stream, [stream]); ``` ### Class: `WritableStreamDefaultWriter` + <!-- YAML added: v16.5.0 --> #### `new WritableStreamDefaultWriter(stream)` + <!-- YAML added: v16.5.0 --> @@ -829,6 +875,7 @@ Creates a new `WritableStreamDefaultWriter` that is locked to the given `WritableStream`. #### `writableStreamDefaultWriter.abort([reason])` + <!-- YAML added: v16.5.0 --> @@ -840,6 +887,7 @@ Abruptly terminates the `WritableStream`. All queued writes will be canceled with their associated promises rejected. #### `writableStreamDefaultWriter.close()` + <!-- YAML added: v16.5.0 --> @@ -849,6 +897,7 @@ added: v16.5.0 Closes the `WritableStream` when no additional writes are expected. #### `writableStreamDefaultWriter.closed` + <!-- YAML added: v16.5.0 --> @@ -858,6 +907,7 @@ added: v16.5.0 released. #### `writableStreamDefaultWriter.desiredSize` + <!-- YAML added: v16.5.0 --> @@ -867,6 +917,7 @@ added: v16.5.0 The amount of data required to fill the {WritableStream}'s queue. #### `writableStreamDefaultWriter.ready` + <!-- YAML added: v16.5.0 --> @@ -875,6 +926,7 @@ added: v16.5.0 writer is ready to be used. #### `writableStreamDefaultWriter.releaseLock()` + <!-- YAML added: v16.5.0 --> @@ -882,6 +934,7 @@ added: v16.5.0 Releases this writer's lock on the underlying {ReadableStream}. #### `writableStreamDefaultWriter.write([chunk])` + <!-- YAML added: v16.5.0 --> @@ -892,6 +945,7 @@ added: v16.5.0 Appends a new chunk of data to the {WritableStream}'s queue. ### Class: `WritableStreamDefaultController` + <!-- YAML added: v16.5.0 --> @@ -904,6 +958,7 @@ internal state. * Type: {any} The `reason` value passed to `writableStream.abort()`. #### `writableStreamDefaultController.error(error)` + <!-- YAML added: v16.5.0 --> @@ -920,6 +975,7 @@ with currently pending writes canceled. write or close operations when a {WritableStream} is aborted. ### Class: `TransformStream` + <!-- YAML added: v16.5.0 --> @@ -947,6 +1003,7 @@ await Promise.all([ ``` #### `new TransformStream([transformer[, writableStrategy[, readableStrategy]]])` + <!-- YAML added: v16.5.0 --> @@ -968,9 +1025,9 @@ added: v16.5.0 * `controller` {TransformStreamDefaultController} * Returns: A promise fulfilled with `undefined`. * `readableType` {any} the `readableType` option is reserved for future use - and *must* be `undefined. + and _must_ be `undefined`. * `writableType` {any} the `writableType` option is reserved for future use - and *must* be `undefined. + and _must_ be `undefined`. * `writableStrategy` {Object} * `highWaterMark` {number} The maximum internal queue size before backpressure is applied. @@ -987,6 +1044,7 @@ added: v16.5.0 * Returns: {number} #### `transformStream.readable` + <!-- YAML added: v16.5.0 --> @@ -994,6 +1052,7 @@ added: v16.5.0 * Type: {ReadableStream} #### `transformStream.writable` + <!-- YAML added: v16.5.0 --> @@ -1018,6 +1077,7 @@ port2.postMessage(stream, [stream]); ``` ### Class: `TransformStreamDefaultController` + <!-- YAML added: v16.5.0 --> @@ -1026,6 +1086,7 @@ The `TransformStreamDefaultController` manages the internal state of the `TransformStream`. #### `transformStreamDefaultController.desiredSize` + <!-- YAML added: v16.5.0 --> @@ -1035,6 +1096,7 @@ added: v16.5.0 The amount of data required to fill the readable side's queue. #### `transformStreamDefaultController.enqueue([chunk])` + <!-- YAML added: v16.5.0 --> @@ -1044,6 +1106,7 @@ added: v16.5.0 Appends a chunk of data to the readable side's queue. #### `transformStreamDefaultController.error([reason])` + <!-- YAML added: v16.5.0 --> @@ -1055,6 +1118,7 @@ while processing the transform data, causing both sides to be abruptly closed. #### `transformStreamDefaultController.terminate()` + <!-- YAML added: v16.5.0 --> @@ -1063,11 +1127,13 @@ Closes the readable side of the transport and causes the writable side to be abruptly closed with an error. ### Class: `ByteLengthQueuingStrategy` + <!-- YAML added: v16.5.0 --> #### `new ByteLengthQueuingStrategy(options)` + <!-- YAML added: v16.5.0 --> @@ -1076,6 +1142,7 @@ added: v16.5.0 * `highWaterMark` {number} #### `byteLengthQueuingStrategy.highWaterMark` + <!-- YAML added: v16.5.0 --> @@ -1083,6 +1150,7 @@ added: v16.5.0 * Type: {number} #### `byteLengthQueuingStrategy.size` + <!-- YAML added: v16.5.0 --> @@ -1092,11 +1160,13 @@ added: v16.5.0 * Returns: {number} ### Class: `CountQueuingStrategy` + <!-- YAML added: v16.5.0 --> #### `new CountQueuingStrategy(options)` + <!-- YAML added: v16.5.0 --> @@ -1105,6 +1175,7 @@ added: v16.5.0 * `highWaterMark` {number} #### `countQueuingStrategy.highWaterMark` + <!-- YAML added: v16.5.0 --> @@ -1112,6 +1183,7 @@ added: v16.5.0 * Type: {number} #### `countQueuingStrategy.size` + <!-- YAML added: v16.5.0 --> @@ -1121,11 +1193,13 @@ added: v16.5.0 * Returns: {number} ### Class: `TextEncoderStream` + <!-- YAML added: v16.6.0 --> #### `new TextEncoderStream()` + <!-- YAML added: v16.6.0 --> @@ -1133,6 +1207,7 @@ added: v16.6.0 Creates a new `TextEncoderStream` instance. #### `textEncoderStream.encoding` + <!-- YAML added: v16.6.0 --> @@ -1142,6 +1217,7 @@ added: v16.6.0 The encoding supported by the `TextEncoderStream` instance. #### `textEncoderStream.readable` + <!-- YAML added: v16.6.0 --> @@ -1149,6 +1225,7 @@ added: v16.6.0 * Type: {ReadableStream} #### `textEncoderStream.writable` + <!-- YAML added: v16.6.0 --> @@ -1156,11 +1233,13 @@ added: v16.6.0 * Type: {WritableStream} ### Class: `TextDecoderStream` + <!-- YAML added: v16.6.0 --> #### `new TextDecoderStream([encoding[, options]])` + <!-- YAML added: v16.6.0 --> @@ -1177,6 +1256,7 @@ added: v16.6.0 Creates a new `TextDecoderStream` instance. #### `textDecoderStream.encoding` + <!-- YAML added: v16.6.0 --> @@ -1186,6 +1266,7 @@ added: v16.6.0 The encoding supported by the `TextDecoderStream` instance. #### `textDecoderStream.fatal` + <!-- YAML added: v16.6.0 --> @@ -1196,6 +1277,7 @@ The value will be `true` if decoding errors result in a `TypeError` being thrown. #### `textDecoderStream.ignoreBOM` + <!-- YAML added: v16.6.0 --> @@ -1206,6 +1288,7 @@ The value will be `true` if the decoding result will include the byte order mark. #### `textDecoderStream.readable` + <!-- YAML added: v16.6.0 --> @@ -1213,6 +1296,7 @@ added: v16.6.0 * Type: {ReadableStream} #### `textDecoderStream.writable` + <!-- YAML added: v16.6.0 --> @@ -1220,10 +1304,13 @@ added: v16.6.0 * Type: {WritableStream} ### Class: `CompressionStream` + <!-- YAML added: v17.0.0 --> + #### `new CompressionStream(format)` + <!-- YAML added: v17.0.0 --> @@ -1231,6 +1318,7 @@ added: v17.0.0 * `format` {string} One of either `'deflate'` or `'gzip'`. #### `compressionStream.readable` + <!-- YAML added: v17.0.0 --> @@ -1238,6 +1326,7 @@ added: v17.0.0 * Type: {ReadableStream} #### `compressionStream.writable` + <!-- YAML added: v17.0.0 --> @@ -1245,11 +1334,13 @@ added: v17.0.0 * Type: {WritableStream} ### Class: `DecompressionStream` + <!-- YAML added: v17.0.0 --> #### `new DecompressionStream(format)` + <!-- YAML added: v17.0.0 --> @@ -1257,6 +1348,7 @@ added: v17.0.0 * `format` {string} One of either `'deflate'` or `'gzip'`. #### `decompressionStream.readable` + <!-- YAML added: v17.0.0 --> @@ -1264,6 +1356,7 @@ added: v17.0.0 * Type: {ReadableStream} #### `decompressionStream.writable` + <!-- YAML added: v17.0.0 --> @@ -1271,6 +1364,7 @@ added: v17.0.0 * Type: {WritableStream} ### Utility Consumers + <!-- YAML added: v16.7.0 --> @@ -1299,6 +1393,7 @@ const { ``` #### `streamConsumers.arrayBuffer(stream)` + <!-- YAML added: v16.7.0 --> @@ -1308,6 +1403,7 @@ added: v16.7.0 contents of the stream. #### `streamConsumers.blob(stream)` + <!-- YAML added: v16.7.0 --> @@ -1317,6 +1413,7 @@ added: v16.7.0 of the stream. #### `streamConsumers.buffer(stream)` + <!-- YAML added: v16.7.0 --> @@ -1326,6 +1423,7 @@ added: v16.7.0 contents of the stream. #### `streamConsumers.json(stream)` + <!-- YAML added: v16.7.0 --> @@ -1335,6 +1433,7 @@ added: v16.7.0 UTF-8 encoded string that is then passed through `JSON.parse()`. #### `streamConsumers.text(stream)` + <!-- YAML added: v16.7.0 --> diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index f9a1d91b451..106efca846f 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -62,6 +62,7 @@ Worker threads inherit non-process-specific options by default. Refer to specifically `argv` and `execArgv` options. ## `worker.getEnvironmentData(key)` + <!-- YAML added: - v15.12.0 @@ -96,6 +97,7 @@ if (isMainThread) { ``` ## `worker.isMainThread` + <!-- YAML added: v10.5.0 --> @@ -117,6 +119,7 @@ if (isMainThread) { ``` ## `worker.markAsUntransferable(object)` + <!-- YAML added: - v14.5.0 @@ -156,11 +159,13 @@ console.log(typedArray2); There is no equivalent to this API in browsers. ## `worker.moveMessagePortToContext(port, contextifiedSandbox)` + <!-- YAML added: v11.13.0 --> * `port` {MessagePort} The message port to transfer. + * `contextifiedSandbox` {Object} A [contextified][] object as returned by the `vm.createContext()` method. @@ -180,6 +185,7 @@ However, the created `MessagePort` no longer inherits from events using it. ## `worker.parentPort` + <!-- YAML added: v10.5.0 --> @@ -211,6 +217,7 @@ if (isMainThread) { ``` ## `worker.receiveMessageOnPort(port)` + <!-- YAML added: v12.3.0 changes: @@ -243,6 +250,7 @@ When this function is used, no `'message'` event is emitted and the `onmessage` listener is not invoked. ## `worker.resourceLimits` + <!-- YAML added: - v13.2.0 @@ -262,6 +270,7 @@ this matches its values. If this is used in the main thread, its value is an empty object. ## `worker.SHARE_ENV` + <!-- YAML added: v11.14.0 --> @@ -281,6 +290,7 @@ new Worker('process.env.SET_IN_WORKER = "foo"', { eval: true, env: SHARE_ENV }) ``` ## `worker.setEnvironmentData(key[, value])` + <!-- YAML added: - v15.12.0 @@ -300,6 +310,7 @@ The `worker.setEnvironmentData()` API sets the content of instances spawned from the current context. ## `worker.threadId` + <!-- YAML added: v10.5.0 --> @@ -311,6 +322,7 @@ An integer identifier for the current thread. On the corresponding worker object This value is unique for each [`Worker`][] instance inside a single process. ## `worker.workerData` + <!-- YAML added: v10.5.0 --> @@ -332,6 +344,7 @@ if (isMainThread) { ``` ## Class: `BroadcastChannel extends EventTarget` + <!-- YAML added: v15.4.0 --> @@ -367,14 +380,16 @@ if (isMainThread) { ``` ### `new BroadcastChannel(name)` + <!-- YAML added: v15.4.0 --> * `name` {any} The name of the channel to connect to. Any JavaScript value - that can be converted to a string using ``${name}`` is permitted. + that can be converted to a string using `` `${name}` `` is permitted. ### `broadcastChannel.close()` + <!-- YAML added: v15.4.0 --> @@ -382,6 +397,7 @@ added: v15.4.0 Closes the `BroadcastChannel` connection. ### `broadcastChannel.onmessage` + <!-- YAML added: v15.4.0 --> @@ -390,6 +406,7 @@ added: v15.4.0 when a message is received. ### `broadcastChannel.onmessageerror` + <!-- YAML added: v15.4.0 --> @@ -398,6 +415,7 @@ added: v15.4.0 deserialized. ### `broadcastChannel.postMessage(message)` + <!-- YAML added: v15.4.0 --> @@ -405,16 +423,18 @@ added: v15.4.0 * `message` {any} Any cloneable JavaScript value. ### `broadcastChannel.ref()` + <!-- YAML added: v15.4.0 --> Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed -BroadcastChannel does *not* let the program exit if it's the only active handle +BroadcastChannel does _not_ let the program exit if it's the only active handle left (the default behavior). If the port is `ref()`ed, calling `ref()` again has no effect. ### `broadcastChannel.unref()` + <!-- YAML added: v15.4.0 --> @@ -424,6 +444,7 @@ is the only active handle in the event system. If the BroadcastChannel is already `unref()`ed calling `unref()` again has no effect. ## Class: `MessageChannel` + <!-- YAML added: v10.5.0 --> @@ -444,6 +465,7 @@ port2.postMessage({ foo: 'bar' }); ``` ## Class: `MessagePort` + <!-- YAML added: v10.5.0 changes: @@ -464,6 +486,7 @@ structured data, memory regions and other `MessagePort`s between different This implementation matches [browser `MessagePort`][]s. ### Event: `'close'` + <!-- YAML added: v10.5.0 --> @@ -486,6 +509,7 @@ port1.close(); ``` ### Event: `'message'` + <!-- YAML added: v10.5.0 --> @@ -499,6 +523,7 @@ Listeners on this event receive a clone of the `value` parameter as passed to `postMessage()` and no further arguments. ### Event: `'messageerror'` + <!-- YAML added: - v14.5.0 @@ -516,6 +541,7 @@ are received in a `vm.Context` (where Node.js APIs are currently unavailable). ### `port.close()` + <!-- YAML added: v10.5.0 --> @@ -528,6 +554,7 @@ The [`'close'` event][] is emitted on both `MessagePort` instances that are part of the channel. ### `port.postMessage(value[, transferList])` + <!-- YAML added: v10.5.0 changes: @@ -560,7 +587,7 @@ changes: --> * `value` {any} -* `transferList` {Object[]} +* `transferList` {Object\[]} Sends a JavaScript value to the receiving side of this channel. `value` is transferred in a way which is compatible with @@ -572,7 +599,7 @@ In particular, the significant differences to `JSON` are: * `value` may contain instances of builtin JS types such as `RegExp`s, `BigInt`s, `Map`s, `Set`s, etc. * `value` may contain typed arrays, both using `ArrayBuffer`s - and `SharedArrayBuffer`s. + and `SharedArrayBuffer`s. * `value` may contain [`WebAssembly.Module`][] instances. * `value` may not contain native (C++-backed) objects other than: * {CryptoKey}s, @@ -731,12 +758,13 @@ port2.postMessage(new URL('https://example.org')); ``` ### `port.ref()` + <!-- YAML added: v10.5.0 --> Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does -*not* let the program exit if it's the only active handle left (the default +_not_ let the program exit if it's the only active handle left (the default behavior). If the port is `ref()`ed, calling `ref()` again has no effect. If listeners are attached or removed using `.on('message')`, the port @@ -744,6 +772,7 @@ is `ref()`ed and `unref()`ed automatically depending on whether listeners for the event exist. ### `port.start()` + <!-- YAML added: v10.5.0 --> @@ -759,6 +788,7 @@ automatically calls `.start()`, but unsetting it lets messages queue up until a new handler is set or the port is discarded. ### `port.unref()` + <!-- YAML added: v10.5.0 --> @@ -772,6 +802,7 @@ If listeners are attached or removed using `.on('message')`, the port is listeners for the event exist. ## Class: `Worker` + <!-- YAML added: v10.5.0 --> @@ -847,6 +878,7 @@ if (isMainThread) { ``` ### `new Worker(filename[, options])` + <!-- YAML added: v10.5.0 changes: @@ -894,7 +926,7 @@ changes: If `options.eval` is `true`, this is a string containing JavaScript code rather than a path. * `options` {Object} - * `argv` {any[]} List of arguments which would be stringified and appended to + * `argv` {any\[]} List of arguments which would be stringified and appended to `process.argv` in the worker. This is mostly similar to the `workerData` but the values are available on the global `process.argv` as if they were passed as CLI options to the script. @@ -906,7 +938,7 @@ changes: * `eval` {boolean} If `true` and the first argument is a `string`, interpret the first argument to the constructor as a script that is executed once the worker is online. - * `execArgv` {string[]} List of node CLI options passed to the worker. + * `execArgv` {string\[]} List of node CLI options passed to the worker. V8 options (such as `--max-old-space-size`) and options that affect the process (such as `--title`) are not supported. If set, this is provided as [`process.execArgv`][] inside the worker. By default, options are @@ -929,7 +961,7 @@ changes: resources like network sockets or file descriptors managed through the [`FileHandle`][] API. This option is automatically inherited by all nested `Worker`s. **Default:** `true`. - * `transferList` {Object[]} If one or more `MessagePort`-like objects + * `transferList` {Object\[]} If one or more `MessagePort`-like objects are passed in `workerData`, a `transferList` is required for those items or [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`][] is thrown. See [`port.postMessage()`][] for more information. @@ -947,6 +979,7 @@ changes: Small values may lead to unusable Worker instances. **Default:** `4`. ### Event: `'error'` + <!-- YAML added: v10.5.0 --> @@ -957,6 +990,7 @@ The `'error'` event is emitted if the worker thread throws an uncaught exception. In that case, the worker is terminated. ### Event: `'exit'` + <!-- YAML added: v10.5.0 --> @@ -971,6 +1005,7 @@ passed exit code. If the worker was terminated, the `exitCode` parameter is This is the final event emitted by any `Worker` instance. ### Event: `'message'` + <!-- YAML added: v10.5.0 --> @@ -985,6 +1020,7 @@ All messages sent from the worker thread are emitted before the [`'exit'` event][] is emitted on the `Worker` object. ### Event: `'messageerror'` + <!-- YAML added: - v14.5.0 @@ -996,6 +1032,7 @@ added: The `'messageerror'` event is emitted when deserializing a message failed. ### Event: `'online'` + <!-- YAML added: v10.5.0 --> @@ -1004,6 +1041,7 @@ The `'online'` event is emitted when the worker thread has started executing JavaScript code. ### `worker.getHeapSnapshot()` + <!-- YAML added: - v13.9.0 @@ -1021,6 +1059,7 @@ If the Worker thread is no longer running, which may occur before the immediately with an [`ERR_WORKER_NOT_RUNNING`][] error. ### `worker.performance` + <!-- YAML added: - v15.1.0 @@ -1032,6 +1071,7 @@ An object that can be used to query performance information from a worker instance. Similar to [`perf_hooks.performance`][]. #### `performance.eventLoopUtilization([utilization1[, utilization2]])` + <!-- YAML added: - v15.1.0 @@ -1040,9 +1080,9 @@ added: --> * `utilization1` {Object} The result of a previous call to - `eventLoopUtilization()`. + `eventLoopUtilization()`. * `utilization2` {Object} The result of a previous call to - `eventLoopUtilization()` prior to `utilization1`. + `eventLoopUtilization()` prior to `utilization1`. * Returns {Object} * `idle` {number} * `active` {number} @@ -1086,28 +1126,31 @@ event][] emitted, and if called before this, or after the [`'exit'` event][], then all properties have the value of `0`. ### `worker.postMessage(value[, transferList])` + <!-- YAML added: v10.5.0 --> * `value` {any} -* `transferList` {Object[]} +* `transferList` {Object\[]} Send a message to the worker that is received via [`require('worker_threads').parentPort.on('message')`][]. See [`port.postMessage()`][] for more details. ### `worker.ref()` + <!-- YAML added: v10.5.0 --> Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does -*not* let the program exit if it's the only active handle left (the default +_not_ let the program exit if it's the only active handle left (the default behavior). If the worker is `ref()`ed, calling `ref()` again has no effect. ### `worker.resourceLimits` + <!-- YAML added: - v13.2.0 @@ -1127,6 +1170,7 @@ this matches its values. If the worker has stopped, the return value is an empty object. ### `worker.stderr` + <!-- YAML added: v10.5.0 --> @@ -1139,6 +1183,7 @@ inside the worker thread. If `stderr: true` was not passed to the [`process.stderr`][] stream. ### `worker.stdin` + <!-- YAML added: v10.5.0 --> @@ -1150,6 +1195,7 @@ writable stream. The data written to this stream will be made available in the worker thread as [`process.stdin`][]. ### `worker.stdout` + <!-- YAML added: v10.5.0 --> @@ -1162,6 +1208,7 @@ inside the worker thread. If `stdout: true` was not passed to the [`process.stdout`][] stream. ### `worker.terminate()` + <!-- YAML added: v10.5.0 changes: @@ -1180,6 +1227,7 @@ Returns a Promise for the exit code that is fulfilled when the [`'exit'` event][] is emitted. ### `worker.threadId` + <!-- YAML added: v10.5.0 --> @@ -1191,6 +1239,7 @@ it is available as [`require('worker_threads').threadId`][]. This value is unique for each `Worker` instance inside a single process. ### `worker.unref()` + <!-- YAML added: v10.5.0 --> diff --git a/doc/api/zlib.md b/doc/api/zlib.md index a2ce8fe682f..85a0e02efb4 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -265,6 +265,7 @@ From `zlib/zconf.h`, modified for Node.js usage: The memory requirements for deflate are (in bytes): <!-- eslint-disable semi --> + ```js (1 << (windowBits + 2)) + (1 << (memLevel + 9)) ``` @@ -354,6 +355,7 @@ http.createServer((request, response) => { ``` ## Constants + <!-- YAML added: v0.5.8 --> @@ -412,6 +414,7 @@ Compression strategy. * `zlib.constants.Z_DEFAULT_STRATEGY` ### Brotli constants + <!-- YAML added: - v11.7.0 @@ -430,9 +433,9 @@ The following values are valid flush operations for Brotli-based streams: * `zlib.constants.BROTLI_OPERATION_FINISH` (default for the last chunk) * `zlib.constants.BROTLI_OPERATION_EMIT_METADATA` * This particular operation may be hard to use in a Node.js context, - as the streaming layer makes it hard to know which data will end up - in this frame. Also, there is currently no way to consume this data through - the Node.js API. + as the streaming layer makes it hard to know which data will end up + in this frame. Also, there is currently no way to consume this data through + the Node.js API. #### Compressor options @@ -485,6 +488,7 @@ These advanced options are available for controlling decompression: Brotli format as standardized in [RFC 7932][]). ## Class: `Options` + <!-- YAML added: v0.11.1 changes: @@ -528,6 +532,7 @@ See the [`deflateInit2` and `inflateInit2`][] documentation for more information. ## Class: `BrotliOptions` + <!-- YAML added: v11.7.0 changes: @@ -563,6 +568,7 @@ const stream = zlib.createBrotliCompress({ ``` ## Class: `zlib.BrotliCompress` + <!-- YAML added: - v11.7.0 @@ -572,6 +578,7 @@ added: Compress data using the Brotli algorithm. ## Class: `zlib.BrotliDecompress` + <!-- YAML added: - v11.7.0 @@ -581,6 +588,7 @@ added: Decompress data using the Brotli algorithm. ## Class: `zlib.Deflate` + <!-- YAML added: v0.5.8 --> @@ -588,6 +596,7 @@ added: v0.5.8 Compress data using deflate. ## Class: `zlib.DeflateRaw` + <!-- YAML added: v0.5.8 --> @@ -595,6 +604,7 @@ added: v0.5.8 Compress data using deflate, and do not append a `zlib` header. ## Class: `zlib.Gunzip` + <!-- YAML added: v0.5.8 changes: @@ -613,6 +623,7 @@ changes: Decompress a gzip stream. ## Class: `zlib.Gzip` + <!-- YAML added: v0.5.8 --> @@ -620,6 +631,7 @@ added: v0.5.8 Compress data using gzip. ## Class: `zlib.Inflate` + <!-- YAML added: v0.5.8 changes: @@ -631,6 +643,7 @@ changes: Decompress a deflate stream. ## Class: `zlib.InflateRaw` + <!-- YAML added: v0.5.8 changes: @@ -645,6 +658,7 @@ changes: Decompress a raw deflate stream. ## Class: `zlib.Unzip` + <!-- YAML added: v0.5.8 --> @@ -653,6 +667,7 @@ Decompress either a Gzip- or Deflate-compressed stream by auto-detecting the header. ## Class: `zlib.ZlibBase` + <!-- YAML added: v0.5.8 changes: @@ -670,6 +685,7 @@ This class inherits from [`stream.Transform`][], allowing `zlib` objects to be used in pipes and similar stream operations. ### `zlib.bytesRead` + <!-- YAML added: v8.1.0 deprecated: v10.0.0 @@ -685,6 +701,7 @@ read by the engine, but is inconsistent with other streams in Node.js that expose values under these names. ### `zlib.bytesWritten` + <!-- YAML added: v10.0.0 --> @@ -696,6 +713,7 @@ the engine, before the bytes are processed (compressed or decompressed, as appropriate for the derived class). ### `zlib.close([callback])` + <!-- YAML added: v0.9.4 --> @@ -705,6 +723,7 @@ added: v0.9.4 Close the underlying handle. ### `zlib.flush([kind, ]callback)` + <!-- YAML added: v0.5.8 --> @@ -722,6 +741,7 @@ normal call to `.write()`, i.e. it will be queued up behind other pending writes and will only produce output when data is being read from the stream. ### `zlib.params(level, strategy, callback)` + <!-- YAML added: v0.11.4 --> @@ -736,6 +756,7 @@ Dynamically update the compression level and compression strategy. Only applicable to deflate algorithm. ### `zlib.reset()` + <!-- YAML added: v0.7.0 --> @@ -744,6 +765,7 @@ Reset the compressor/decompressor to factory defaults. Only applicable to the inflate and deflate algorithms. ## `zlib.constants` + <!-- YAML added: v7.0.0 --> @@ -751,6 +773,7 @@ added: v7.0.0 Provides an object enumerating Zlib-related constants. ## `zlib.createBrotliCompress([options])` + <!-- YAML added: - v11.7.0 @@ -762,6 +785,7 @@ added: Creates and returns a new [`BrotliCompress`][] object. ## `zlib.createBrotliDecompress([options])` + <!-- YAML added: - v11.7.0 @@ -773,6 +797,7 @@ added: Creates and returns a new [`BrotliDecompress`][] object. ## `zlib.createDeflate([options])` + <!-- YAML added: v0.5.8 --> @@ -782,6 +807,7 @@ added: v0.5.8 Creates and returns a new [`Deflate`][] object. ## `zlib.createDeflateRaw([options])` + <!-- YAML added: v0.5.8 --> @@ -798,6 +824,7 @@ since passing `windowBits = 9` to zlib actually results in a compressed stream that effectively uses an 8-bit window only. ## `zlib.createGunzip([options])` + <!-- YAML added: v0.5.8 --> @@ -807,6 +834,7 @@ added: v0.5.8 Creates and returns a new [`Gunzip`][] object. ## `zlib.createGzip([options])` + <!-- YAML added: v0.5.8 --> @@ -817,6 +845,7 @@ Creates and returns a new [`Gzip`][] object. See [example][zlib.createGzip example]. ## `zlib.createInflate([options])` + <!-- YAML added: v0.5.8 --> @@ -826,6 +855,7 @@ added: v0.5.8 Creates and returns a new [`Inflate`][] object. ## `zlib.createInflateRaw([options])` + <!-- YAML added: v0.5.8 --> @@ -835,6 +865,7 @@ added: v0.5.8 Creates and returns a new [`InflateRaw`][] object. ## `zlib.createUnzip([options])` + <!-- YAML added: v0.5.8 --> @@ -856,6 +887,7 @@ Every method has a `*Sync` counterpart, which accept the same arguments, but without a callback. ### `zlib.brotliCompress(buffer[, options], callback)` + <!-- YAML added: - v11.7.0 @@ -867,6 +899,7 @@ added: * `callback` {Function} ### `zlib.brotliCompressSync(buffer[, options])` + <!-- YAML added: - v11.7.0 @@ -879,6 +912,7 @@ added: Compress a chunk of data with [`BrotliCompress`][]. ### `zlib.brotliDecompress(buffer[, options], callback)` + <!-- YAML added: - v11.7.0 @@ -890,6 +924,7 @@ added: * `callback` {Function} ### `zlib.brotliDecompressSync(buffer[, options])` + <!-- YAML added: - v11.7.0 @@ -902,6 +937,7 @@ added: Decompress a chunk of data with [`BrotliDecompress`][]. ### `zlib.deflate(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -921,6 +957,7 @@ changes: * `callback` {Function} ### `zlib.deflateSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: @@ -941,6 +978,7 @@ changes: Compress a chunk of data with [`Deflate`][]. ### `zlib.deflateRaw(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -957,6 +995,7 @@ changes: * `callback` {Function} ### `zlib.deflateRawSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: @@ -977,6 +1016,7 @@ changes: Compress a chunk of data with [`DeflateRaw`][]. ### `zlib.gunzip(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -996,6 +1036,7 @@ changes: * `callback` {Function} ### `zlib.gunzipSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: @@ -1016,6 +1057,7 @@ changes: Decompress a chunk of data with [`Gunzip`][]. ### `zlib.gzip(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -1035,6 +1077,7 @@ changes: * `callback` {Function} ### `zlib.gzipSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: @@ -1055,6 +1098,7 @@ changes: Compress a chunk of data with [`Gzip`][]. ### `zlib.inflate(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -1074,6 +1118,7 @@ changes: * `callback` {Function} ### `zlib.inflateSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: @@ -1094,6 +1139,7 @@ changes: Decompress a chunk of data with [`Inflate`][]. ### `zlib.inflateRaw(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -1113,6 +1159,7 @@ changes: * `callback` {Function} ### `zlib.inflateRawSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: @@ -1133,6 +1180,7 @@ changes: Decompress a chunk of data with [`InflateRaw`][]. ### `zlib.unzip(buffer[, options], callback)` + <!-- YAML added: v0.6.0 changes: @@ -1152,6 +1200,7 @@ changes: * `callback` {Function} ### `zlib.unzipSync(buffer[, options])` + <!-- YAML added: v0.11.12 changes: |