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

doc: remove **Note:** tags

Browse Source 
Remove the various **Note:** prefixes throughout the docs.

PR-URL: https://github.com/nodejs/node/pull/18592
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
James M Snell 2018-02-05 21:55:16 -08:00 committed by Anatoli Papirovski
parent 809af1fe8a
commit d3569b623c
No known key found for this signature in database
GPG Key ID: 614E2E1ABEB4B2C0
32 changed files with 493 additions and 522 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/addons.md
View File

@ -115,7 +115,7 @@ specifically to compile Node.js Addons.
} }
``` ```
*Note*: A version of the `node-gyp` utility is bundled and distributed with A version of the `node-gyp` utility is bundled and distributed with
Node.js as part of `npm`. This version is not made directly available for Node.js as part of `npm`. This version is not made directly available for
developers to use and is intended only to support the ability to use the developers to use and is intended only to support the ability to use the
`npm install` command to compile and install Addons. Developers who wish to `npm install` command to compile and install Addons. Developers who wish to

12
doc/api/async_hooks.md
View File

@ -306,8 +306,8 @@ set to the `asyncId` of a parent Promise, if there is one, and `undefined`
otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered
a parent Promise of `b`. a parent Promise of `b`.
*Note*: In some cases the resource object is reused for performance reasons, In some cases the resource object is reused for performance reasons, it is
it is thus not safe to use it as a key in a `WeakMap` or add properties to it. thus not safe to use it as a key in a `WeakMap` or add properties to it.
###### Asynchronous context example ###### Asynchronous context example
@ -377,9 +377,9 @@ destroy: 9
destroy: 5 destroy: 5
``` ```
*Note*: As illustrated in the example, `executionAsyncId()` and `execution` As illustrated in the example, `executionAsyncId()` and `execution` each specify
each specify the value of the current execution context; which is delineated by the value of the current execution context; which is delineated by calls to
calls to `before` and `after`. `before` and `after`.
Only using `execution` to graph resource allocation results in the following: Only using `execution` to graph resource allocation results in the following:
@ -599,7 +599,7 @@ own resources.
The `init` hook will trigger when an `AsyncResource` is instantiated. The `init` hook will trigger when an `AsyncResource` is instantiated.
*Note*: `before` and `after` calls must be unwound in the same order that they The `before` and `after` calls must be unwound in the same order that they
are called. Otherwise, an unrecoverable exception will occur and the process are called. Otherwise, an unrecoverable exception will occur and the process
will abort. will abort.

18
doc/api/buffer.md
View File

@ -195,10 +195,10 @@ The character encodings currently supported by Node.js include:
* `'hex'` - Encode each byte as two hexadecimal characters. * `'hex'` - Encode each byte as two hexadecimal characters.
*Note*: Today's browsers follow the [WHATWG Encoding Standard][] which aliases Modern Web browsers follow the [WHATWG Encoding Standard][] which aliases
both 'latin1' and ISO-8859-1 to win-1252. This means that while doing something both `'latin1'` and `'ISO-8859-1'` to `'win-1252'`. This means that while doing
like `http.get()`, if the returned charset is one of those listed in the WHATWG something like `http.get()`, if the returned charset is one of those listed in
specification it is possible that the server actually returned the WHATWG specification it is possible that the server actually returned
win-1252-encoded data, and using `'latin1'` encoding may incorrectly decode the win-1252-encoded data, and using `'latin1'` encoding may incorrectly decode the
characters. characters.
@ -702,9 +702,9 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in [`String.prototype.length`] since that returns the number of *characters* in
a string. a string.
*Note*: For `'base64'` and `'hex'`, this function assumes valid input. For For `'base64'` and `'hex'`, this function assumes valid input. For strings that
strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return contain non-Base64/Hex-encoded data (e.g. whitespace), the return value might be
value might be greater than the length of a `Buffer` created from the string. greater than the length of a `Buffer` created from the string.
Example: Example:
@ -1948,8 +1948,8 @@ offset and cropped by the `start` and `end` indices.
Specifying `end` greater than [`buf.length`] will return the same result as Specifying `end` greater than [`buf.length`] will return the same result as
that of `end` equal to [`buf.length`]. that of `end` equal to [`buf.length`].
*Note*: Modifying the new `Buffer` slice will modify the memory in the Modifying the new `Buffer` slice will modify the memory in the original `Buffer`
original `Buffer` because the allocated memory of the two objects overlap. because the allocated memory of the two objects overlap.
Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify
one byte from the original `Buffer` one byte from the original `Buffer`

68
doc/api/child_process.md
View File

@ -170,9 +170,8 @@ exec('echo "The \\$HOME variable is $HOME"');
//The $HOME variable is escaped in the first instance, but not in the second //The $HOME variable is escaped in the first instance, but not in the second
``` ```
*Note*: Never pass unsanitized user input to this function. Any input **Never pass unsanitized user input to this function. Any input containing shell
containing shell metacharacters may be used to trigger arbitrary command metacharacters may be used to trigger arbitrary command execution.**
execution.
```js ```js
const { exec } = require('child_process'); const { exec } = require('child_process');
@ -218,8 +217,8 @@ If `timeout` is greater than `0`, the parent will send the signal
identified by the `killSignal` property (the default is `'SIGTERM'`) if the identified by the `killSignal` property (the default is `'SIGTERM'`) if the
child runs longer than `timeout` milliseconds. child runs longer than `timeout` milliseconds.
*Note*: Unlike the exec(3) POSIX system call, `child_process.exec()` does not Unlike the exec(3) POSIX system call, `child_process.exec()` does not replace
replace the existing process and uses a shell to execute the command. the existing process and uses a shell to execute the command.
If this method is invoked as its [`util.promisify()`][]ed version, it returns If this method is invoked as its [`util.promisify()`][]ed version, it returns
a Promise for an object with `stdout` and `stderr` properties. In case of an a Promise for an object with `stdout` and `stderr` properties. In case of an
@ -316,9 +315,9 @@ async function getVersion() {
getVersion(); getVersion();
``` ```
*Note*: If the `shell` option is enabled, do not pass unsanitized user input **If the `shell` option is enabled, do not pass unsanitized user input to this
to this function. Any input containing shell metacharacters may be used to function. Any input containing shell metacharacters may be used to trigger
trigger arbitrary command execution. arbitrary command execution.**
### child_process.fork(modulePath[, args][, options]) ### child_process.fork(modulePath[, args][, options])
<!-- YAML <!-- YAML
@ -376,11 +375,11 @@ Node.js processes launched with a custom `execPath` will communicate with the
parent process using the file descriptor (fd) identified using the parent process using the file descriptor (fd) identified using the
environment variable `NODE_CHANNEL_FD` on the child process. environment variable `NODE_CHANNEL_FD` on the child process.
*Note*: Unlike the fork(2) POSIX system call, `child_process.fork()` does Unlike the fork(2) POSIX system call, `child_process.fork()` does not clone the
not clone the current process. current process.
*Note*: The `shell` option available in [`child_process.spawn()`][] is not The `shell` option available in [`child_process.spawn()`][] is not supported by
supported by `child_process.fork()` and will be ignored if set. `child_process.fork()` and will be ignored if set.
### child_process.spawn(command[, args][, options]) ### child_process.spawn(command[, args][, options])
<!-- YAML <!-- YAML
@ -426,9 +425,9 @@ The `child_process.spawn()` method spawns a new process using the given
`command`, with command line arguments in `args`. If omitted, `args` defaults `command`, with command line arguments in `args`. If omitted, `args` defaults
to an empty array. to an empty array.
*Note*: If the `shell` option is enabled, do not pass unsanitized user input to **If the `shell` option is enabled, do not pass unsanitized user input to this
this function. Any input containing shell metacharacters may be used to function. Any input containing shell metacharacters may be used to trigger
trigger arbitrary command execution. arbitrary command execution.**
A third argument may be used to specify additional options, with these defaults: A third argument may be used to specify additional options, with these defaults:
@ -517,12 +516,12 @@ subprocess.on('error', (err) => {
}); });
``` ```
*Note*: Certain platforms (macOS, Linux) will use the value of `argv[0]` for Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
the process title while others (Windows, SunOS) will use `command`. title while others (Windows, SunOS) will use `command`.
*Note*: Node.js currently overwrites `argv[0]` with `process.execPath` on Node.js currently overwrites `argv[0]` with `process.execPath` on startup, so
startup, so `process.argv[0]` in a Node.js child process will not match the `process.argv[0]` in a Node.js child process will not match the `argv0`
`argv0` parameter passed to `spawn` from the parent, retrieve it with the parameter passed to `spawn` from the parent, retrieve it with the
`process.argv0` property instead. `process.argv0` property instead.
#### options.detached #### options.detached
@ -725,7 +724,7 @@ until the child process has fully closed. When a timeout has been encountered
and `killSignal` is sent, the method won't return until the process has and `killSignal` is sent, the method won't return until the process has
completely exited. completely exited.
*Note*: If the child process intercepts and handles the `SIGTERM` signal and If the child process intercepts and handles the `SIGTERM` signal and
does not exit, the parent process will still wait until the child process has does not exit, the parent process will still wait until the child process has
exited. exited.
@ -733,9 +732,9 @@ If the process times out or has a non-zero exit code, this method ***will***
throw an [`Error`][] that will include the full result of the underlying throw an [`Error`][] that will include the full result of the underlying
[`child_process.spawnSync()`][]. [`child_process.spawnSync()`][].
*Note*: If the `shell` option is enabled, do not pass unsanitized user input **If the `shell` option is enabled, do not pass unsanitized user input to this
to this function. Any input containing shell metacharacters may be used to function. Any input containing shell metacharacters may be used to trigger
trigger arbitrary command execution. arbitrary command execution.**
### child_process.execSync(command[, options]) ### child_process.execSync(command[, options])
<!-- YAML <!-- YAML
@ -789,9 +788,8 @@ If the process times out or has a non-zero exit code, this method ***will***
throw. The [`Error`][] object will contain the entire result from throw. The [`Error`][] object will contain the entire result from
[`child_process.spawnSync()`][] [`child_process.spawnSync()`][]
*Note*: Never pass unsanitized user input to this function. Any input **Never pass unsanitized user input to this function. Any input containing shell
containing shell metacharacters may be used to trigger arbitrary command metacharacters may be used to trigger arbitrary command execution.**
execution.
### child_process.spawnSync(command[, args][, options]) ### child_process.spawnSync(command[, args][, options])
<!-- YAML <!-- YAML
@ -857,9 +855,9 @@ completely exited. Note that if the process intercepts and handles the
`SIGTERM` signal and doesn't exit, the parent process will wait until the child `SIGTERM` signal and doesn't exit, the parent process will wait until the child
process has exited. process has exited.
*Note*: If the `shell` option is enabled, do not pass unsanitized user input **If the `shell` option is enabled, do not pass unsanitized user input to this
to this function. Any input containing shell metacharacters may be used to function. Any input containing shell metacharacters may be used to trigger
trigger arbitrary command execution. arbitrary command execution.**
## Class: ChildProcess ## Class: ChildProcess
<!-- YAML <!-- YAML
@ -907,9 +905,9 @@ The `'error'` event is emitted whenever:
2. The process could not be killed, or 2. The process could not be killed, or
3. Sending a message to the child process failed. 3. Sending a message to the child process failed.
*Note*: The `'exit'` event may or may not fire after an error has occurred. The `'exit'` event may or may not fire after an error has occurred. When
When listening to both the `'exit'` and `'error'` events, it is important listening to both the `'exit'` and `'error'` events, it is important to guard
to guard against accidentally invoking handler functions multiple times. against accidentally invoking handler functions multiple times.
See also [`subprocess.kill()`][] and [`subprocess.send()`][]. See also [`subprocess.kill()`][] and [`subprocess.send()`][].
@ -948,7 +946,7 @@ added: v0.5.9
The `'message'` event is triggered when a child process uses [`process.send()`][] The `'message'` event is triggered when a child process uses [`process.send()`][]
to send messages. to send messages.
*Note*: The message goes through serialization and parsing. The resulting The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent. message might not be the same as what is originally sent.
### subprocess.channel ### subprocess.channel
@ -1111,7 +1109,7 @@ be used to send messages to the child process. When the child process is a
Node.js instance, these messages can be received via the Node.js instance, these messages can be received via the
[`process.on('message')`][] event. [`process.on('message')`][] event.
*Note*: The message goes through serialization and parsing. The resulting The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent. message might not be the same as what is originally sent.
For example, in the parent script: For example, in the parent script:

40
doc/api/cli.md
View File

@ -53,9 +53,9 @@ changes:
Evaluate the following argument as JavaScript. The modules which are Evaluate the following argument as JavaScript. The modules which are
predefined in the REPL can also be used in `script`. predefined in the REPL can also be used in `script`.
*Note*: On Windows, using `cmd.exe` a single quote will not work correctly On Windows, using `cmd.exe` a single quote will not work correctly because it
because it only recognizes double `"` for quoting. In Powershell or only recognizes double `"` for quoting. In Powershell or Git bash, both `'`
Git bash, both `'` and `"` are usable. and `"` are usable.
### `-p`, `--print "script"` ### `-p`, `--print "script"`
@ -161,9 +161,9 @@ added: v8.0.0
Emit pending deprecation warnings. Emit pending deprecation warnings.
*Note*: Pending deprecations are generally identical to a runtime deprecation Pending deprecations are generally identical to a runtime deprecation with the
with the notable exception that they are turned *off* by default and will not notable exception that they are turned *off* by default and will not be emitted
be emitted unless either the `--pending-deprecation` command line flag, or the unless either the `--pending-deprecation` command line flag, or the
`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
are used to provide a kind of selective "early warning" mechanism that are used to provide a kind of selective "early warning" mechanism that
developers may leverage to detect deprecated API usage. developers may leverage to detect deprecated API usage.
@ -183,9 +183,9 @@ added: v0.10
Aborting instead of exiting causes a core file to be generated for post-mortem Aborting instead of exiting causes a core file to be generated for post-mortem
analysis using a debugger (such as `lldb`, `gdb`, and `mdb`). analysis using a debugger (such as `lldb`, `gdb`, and `mdb`).
*Note*: If this flag is passed, the behavior can still be set to not abort If this flag is passed, the behavior can still be set to not abort through
through [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage of the
of the `domain` module that uses it). `domain` module that uses it).
### `--trace-warnings` ### `--trace-warnings`
<!-- YAML <!-- YAML
@ -307,7 +307,7 @@ added: v0.1.3
Print V8 command line options. Print V8 command line options.
*Note*: V8 options allow words to be separated by both dashes (`-`) or V8 options allow words to be separated by both dashes (`-`) or
underscores (`_`). underscores (`_`).
For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`. For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`.
@ -411,7 +411,7 @@ added: v0.1.32
`':'`-separated list of directories prefixed to the module search path. `':'`-separated list of directories prefixed to the module search path.
*Note*: On Windows, this is a `';'`-separated list instead. On Windows, this is a `';'`-separated list instead.
### `NODE_DISABLE_COLORS=1` ### `NODE_DISABLE_COLORS=1`
@ -486,9 +486,9 @@ added: v8.0.0
When set to `1`, emit pending deprecation warnings. When set to `1`, emit pending deprecation warnings.
*Note*: Pending deprecations are generally identical to a runtime deprecation Pending deprecations are generally identical to a runtime deprecation with the
with the notable exception that they are turned *off* by default and will not notable exception that they are turned *off* by default and will not be emitted
be emitted unless either the `--pending-deprecation` command line flag, or the unless either the `--pending-deprecation` command line flag, or the
`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
are used to provide a kind of selective "early warning" mechanism that are used to provide a kind of selective "early warning" mechanism that
developers may leverage to detect deprecated API usage. developers may leverage to detect deprecated API usage.
@ -545,9 +545,9 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory
containing trusted certificates. containing trusted certificates.
*Note*: Be aware that unless the child environment is explicitly set, this Be aware that unless the child environment is explicitly set, this environment
environment variable will be inherited by any child processes, and if they use variable will be inherited by any child processes, and if they use OpenSSL, it
OpenSSL, it may cause them to trust the same CAs as node. may cause them to trust the same CAs as node.
### `SSL_CERT_FILE=file` ### `SSL_CERT_FILE=file`
<!-- YAML <!-- YAML
@ -557,9 +557,9 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file
containing trusted certificates. containing trusted certificates.
*Note*: Be aware that unless the child environment is explicitly set, this Be aware that unless the child environment is explicitly set, this environment
environment variable will be inherited by any child processes, and if they use variable will be inherited by any child processes, and if they use OpenSSL, it
OpenSSL, it may cause them to trust the same CAs as node. may cause them to trust the same CAs as node.
### `NODE_REDIRECT_WARNINGS=file` ### `NODE_REDIRECT_WARNINGS=file`
<!-- YAML <!-- YAML

6
doc/api/cluster.md
View File

@ -97,9 +97,9 @@ Node.js process and a cluster worker differs:
port is random the first time, but predictable thereafter. To listen port is random the first time, but predictable thereafter. To listen
on a unique port, generate a port number based on the cluster worker ID. on a unique port, generate a port number based on the cluster worker ID.
*Note*: Node.js does not provide routing logic. It is, therefore important to Node.js does not provide routing logic. It is, therefore important to design an
design an application such that it does not rely too heavily on in-memory data application such that it does not rely too heavily on in-memory data objects for
objects for things like sessions and login. things like sessions and login.
Because workers are all separate processes, they can be killed or Because workers are all separate processes, they can be killed or
re-spawned depending on a program's needs, without affecting other re-spawned depending on a program's needs, without affecting other

9
doc/api/console.md
View File

@ -127,9 +127,8 @@ console.assert(false, 'Whoops %s work', 'didn\'t');
// Assertion failed: Whoops didn't work // Assertion failed: Whoops didn't work
``` ```
*Note*: Calling `console.assert()` with a falsy assertion will only cause the Calling `console.assert()` with a falsy assertion will only cause the `message`
`message` to be printed to the console without interrupting execution of to be printed to the console without interrupting execution of subsequent code.
subsequent code.
### console.clear() ### console.clear()
<!-- YAML <!-- YAML
@ -139,8 +138,8 @@ added: v8.3.0
When `stdout` is a TTY, calling `console.clear()` will attempt to clear the When `stdout` is a TTY, calling `console.clear()` will attempt to clear the
TTY. When `stdout` is not a TTY, this method does nothing. TTY. When `stdout` is not a TTY, this method does nothing.
*Note*: The specific operation of `console.clear()` can vary across operating The specific operation of `console.clear()` can vary across operating systems
systems and terminal types. For most Linux operating systems, `console.clear()` and terminal types. For most Linux operating systems, `console.clear()`
operates similarly to the `clear` shell command. On Windows, `console.clear()` operates similarly to the `clear` shell command. On Windows, `console.clear()`
will clear only the output in the current terminal viewport for the Node.js will clear only the output in the current terminal viewport for the Node.js
binary. binary.

22
doc/api/crypto.md
View File

@ -1865,10 +1865,10 @@ Note that this API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications, see the negative performance implications for some applications, see the
[`UV_THREADPOOL_SIZE`][] documentation for more information. [`UV_THREADPOOL_SIZE`][] documentation for more information.
*Note*: The asynchronous version of `crypto.randomBytes()` is carried out The asynchronous version of `crypto.randomBytes()` is carried out in a single
in a single threadpool request. To minimize threadpool task length variation, threadpool request. To minimize threadpool task length variation, partition
partition large `randomBytes` requests when doing so as part of fulfilling a large `randomBytes` requests when doing so as part of fulfilling a client
client request. request.
### crypto.randomFillSync(buffer[, offset][, size]) ### crypto.randomFillSync(buffer[, offset][, size])
<!-- YAML <!-- YAML
@ -1977,10 +1977,10 @@ Note that this API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications, see the negative performance implications for some applications, see the
[`UV_THREADPOOL_SIZE`][] documentation for more information. [`UV_THREADPOOL_SIZE`][] documentation for more information.
*Note*: The asynchronous version of `crypto.randomFill()` is carried out The asynchronous version of `crypto.randomFill()` is carried out in a single
in a single threadpool request. To minimize threadpool task length variation, threadpool request. To minimize threadpool task length variation, partition
partition large `randomFill` requests when doing so as part of fulfilling a large `randomFill` requests when doing so as part of fulfilling a client
client request. request.
### crypto.setEngine(engine[, flags]) ### crypto.setEngine(engine[, flags])
<!-- YAML <!-- YAML
@ -2036,9 +2036,9 @@ comparing HMAC digests or secret values like authentication cookies or
`a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they
must have the same length. must have the same length.
*Note*: Use of `crypto.timingSafeEqual` does not guarantee that the Use of `crypto.timingSafeEqual` does not guarantee that the *surrounding* code
*surrounding* code is timing-safe. Care should be taken to ensure that the is timing-safe. Care should be taken to ensure that the surrounding code does
surrounding code does not introduce timing vulnerabilities. not introduce timing vulnerabilities.
## Notes ## Notes

26
doc/api/deprecations.md
View File

@ -544,8 +544,8 @@ Type: Documentation-only
The `http` module `ServerResponse.prototype.writeHeader()` API has been The `http` module `ServerResponse.prototype.writeHeader()` API has been
deprecated. Please use `ServerResponse.prototype.writeHead()` instead. deprecated. Please use `ServerResponse.prototype.writeHead()` instead.
*Note*: The `ServerResponse.prototype.writeHeader()` method was never The `ServerResponse.prototype.writeHeader()` method was never documented as an
documented as an officially supported API. officially supported API.
<a id="DEP0064"></a> <a id="DEP0064"></a>
### DEP0064: tls.createSecurePair() ### DEP0064: tls.createSecurePair()
@ -581,8 +581,8 @@ properties have been deprecated. Please instead use one of the public methods
`outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working `outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working
with outgoing headers. with outgoing headers.
*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were The `outgoingMessage._headers` and `outgoingMessage._headerNames` properties
never documented as officially supported properties. were never documented as officially supported properties.
<a id="DEP0067"></a> <a id="DEP0067"></a>
### DEP0067: OutgoingMessage.prototype.\_renderHeaders ### DEP0067: OutgoingMessage.prototype.\_renderHeaders
@ -592,7 +592,7 @@ Type: Documentation-only
The `http` module `OutgoingMessage.prototype._renderHeaders()` API has been The `http` module `OutgoingMessage.prototype._renderHeaders()` API has been
deprecated. deprecated.
*Note*: `OutgoingMessage.prototype._renderHeaders` was never documented as The `OutgoingMessage.prototype._renderHeaders` property was never documented as
an officially supported API. an officially supported API.
<a id="DEP0068"></a> <a id="DEP0068"></a>
@ -610,7 +610,7 @@ Type: End-of-Life
DebugContext has been removed in V8 and is not available in Node 10+. DebugContext has been removed in V8 and is not available in Node 10+.
*Note*: DebugContext was an experimental API. DebugContext was an experimental API.
<a id="DEP0070"></a> <a id="DEP0070"></a>
### DEP0070: async_hooks.currentId() ### DEP0070: async_hooks.currentId()
@ -620,7 +620,7 @@ Type: End-of-Life
`async_hooks.currentId()` was renamed to `async_hooks.executionAsyncId()` for `async_hooks.currentId()` was renamed to `async_hooks.executionAsyncId()` for
clarity. clarity.
*Note*: change was made while `async_hooks` was an experimental API. This change was made while `async_hooks` was an experimental API.
<a id="DEP0071"></a> <a id="DEP0071"></a>
### DEP0071: async_hooks.triggerId() ### DEP0071: async_hooks.triggerId()
@ -630,7 +630,7 @@ Type: End-of-Life
`async_hooks.triggerId()` was renamed to `async_hooks.triggerAsyncId()` for `async_hooks.triggerId()` was renamed to `async_hooks.triggerAsyncId()` for
clarity. clarity.
*Note*: change was made while `async_hooks` was an experimental API. This change was made while `async_hooks` was an experimental API.
<a id="DEP0072"></a> <a id="DEP0072"></a>
### DEP0072: async_hooks.AsyncResource.triggerId() ### DEP0072: async_hooks.AsyncResource.triggerId()
@ -640,7 +640,7 @@ Type: End-of-Life
`async_hooks.AsyncResource.triggerId()` was renamed to `async_hooks.AsyncResource.triggerId()` was renamed to
`async_hooks.AsyncResource.triggerAsyncId()` for clarity. `async_hooks.AsyncResource.triggerAsyncId()` for clarity.
*Note*: change was made while `async_hooks` was an experimental API. This change was made while `async_hooks` was an experimental API.
<a id="DEP0073"></a> <a id="DEP0073"></a>
### DEP0073: Several internal properties of net.Server ### DEP0073: Several internal properties of net.Server
@ -650,8 +650,8 @@ Type: End-of-Life
Accessing several internal, undocumented properties of `net.Server` instances Accessing several internal, undocumented properties of `net.Server` instances
with inappropriate names has been deprecated. with inappropriate names has been deprecated.
*Note*: As the original API was undocumented and not generally useful for As the original API was undocumented and not generally useful for non-internal
non-internal code, no replacement API is provided. code, no replacement API is provided.
<a id="DEP0074"></a> <a id="DEP0074"></a>
### DEP0074: REPLServer.bufferedCommand ### DEP0074: REPLServer.bufferedCommand
@ -681,7 +681,7 @@ const querystring = require('querystring');
querystring.parse(str, '\n', '='); querystring.parse(str, '\n', '=');
``` ```
*Note*: This function is not completely equivalent to `querystring.parse()`. One This function is not completely equivalent to `querystring.parse()`. One
difference is that `querystring.parse()` does url decoding: difference is that `querystring.parse()` does url decoding:
```sh ```sh
@ -698,7 +698,7 @@ Type: Runtime
`Module._debug()` has been deprecated. `Module._debug()` has been deprecated.
*Note*: `Module._debug()` was never documented as an officially supported API. The `Module._debug()` function was never documented as an officially supported API.
<a id="DEP0078"></a> <a id="DEP0078"></a>
### DEP0078: REPLServer.turnOffEditorMode() ### DEP0078: REPLServer.turnOffEditorMode()

6
doc/api/documentation.md
View File

@ -55,9 +55,9 @@ The API has proven satisfactory. Compatibility with the npm ecosystem
is a high priority, and will not be broken unless absolutely necessary. is a high priority, and will not be broken unless absolutely necessary.
``` ```
*Note*: Caution must be used when making use of `Experimental` features, Caution must be used when making use of `Experimental` features, particularly
particularly within modules that may be used as dependencies (or dependencies within modules that may be used as dependencies (or dependencies of
of dependencies) within a Node.js application. End users may not be aware that dependencies) within a Node.js application. End users may not be aware that
experimental features are being used, and therefore may experience unexpected experimental features are being used, and therefore may experience unexpected
failures or behavior changes when API modifications occur. To help avoid such failures or behavior changes when API modifications occur. To help avoid such
surprises, `Experimental` features may require a command-line flag to surprises, `Experimental` features may require a command-line flag to

2
doc/api/errors.md
View File

@ -1307,7 +1307,7 @@ A failure occurred resolving imports in an [ES6 module][].
A callback was called more than once. A callback was called more than once.
*Note*: A callback is almost always meant to only be called once as the query A callback is almost always meant to only be called once as the query
can either be fulfilled or rejected but not both at the same time. The latter 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. would be possible by calling a callback more than once.

107
doc/api/fs.md
View File

@ -86,8 +86,8 @@ be omitted, in which case a default callback is used that rethrows errors. To
get a trace to the original call site, set the `NODE_DEBUG` environment get a trace to the original call site, set the `NODE_DEBUG` environment
variable: variable:
*Note*: Omitting the callback function on asynchronous fs functions is Omitting the callback function on asynchronous fs functions is deprecated and
deprecated and may result in an error being thrown in the future. may result in an error being thrown in the future.
```txt ```txt
$ cat script.js $ cat script.js
@ -178,7 +178,7 @@ const fileUrl = new URL('file:///tmp/hello');
fs.readFileSync(fileUrl); fs.readFileSync(fileUrl);
``` ```
*Note*: `file:` URLs are always absolute paths. `file:` URLs are always absolute paths.
Using WHATWG [`URL`][] objects might introduce platform-specific behaviors. Using WHATWG [`URL`][] objects might introduce platform-specific behaviors.
@ -203,7 +203,7 @@ fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute // TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute
``` ```
*Note*: `file:` URLs with drive letters must use `:` as a separator just after `file:` URLs with drive letters must use `:` as a separator just after
the drive letter. Using another separator will result in a throw. the drive letter. Using another separator will result in a throw.
On all other platforms, `file:` URLs with a hostname are unsupported and will On all other platforms, `file:` URLs with a hostname are unsupported and will
@ -471,7 +471,7 @@ Returns `true` if the `fs.Stats` object describes a socket.
Returns `true` if the `fs.Stats` object describes a symbolic link. Returns `true` if the `fs.Stats` object describes a symbolic link.
*Note*: This method is only valid when using [`fs.lstat()`][] This method is only valid when using [`fs.lstat()`][]
### stats.dev ### stats.dev
@ -581,12 +581,13 @@ The timestamp indicating the creation time of this file.
### Stat Time Values ### Stat Time Values
*Note*: `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` are [numbers][MDN-Number] The `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` properties are
that hold the corresponding times in milliseconds. Their precision is platform [numbers][MDN-Number] that hold the corresponding times in milliseconds. Their
specific. `atime`, `mtime`, `ctime`, and `birthtime` are [`Date`][MDN-Date] precision is platform specific. `atime`, `mtime`, `ctime`, and `birthtime` are
object alternate representations of the various times. The `Date` and number [`Date`][MDN-Date] object alternate representations of the various times. The
values are not connected. Assigning a new number value, or mutating the `Date` `Date` and number values are not connected. Assigning a new number value, or
value, will not be reflected in the corresponding alternate representation. mutating the `Date` value, will not be reflected in the corresponding alternate
representation.
The times in the stat object have the following semantics: The times in the stat object have the following semantics:
@ -1679,8 +1680,8 @@ changes:
Change the file system timestamps of the object referenced by the supplied file Change the file system timestamps of the object referenced by the supplied file
descriptor. See [`fs.utimes()`][]. descriptor. See [`fs.utimes()`][].
*Note*: This function does not work on AIX versions before 7.1, it will return This function does not work on AIX versions before 7.1, it will return the
the error `UV_ENOSYS`. error `UV_ENOSYS`.
## fs.futimesSync(fd, atime, mtime) ## fs.futimesSync(fd, atime, mtime)
<!-- YAML <!-- YAML
@ -1918,10 +1919,10 @@ fs.mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, folder) => {
}); });
``` ```
*Note*: The `fs.mkdtemp()` method will append the six randomly selected The `fs.mkdtemp()` method will append the six randomly selected characters
characters directly to the `prefix` string. For instance, given a directory directly to the `prefix` string. For instance, given a directory `/tmp`, if the
`/tmp`, if the intention is to create a temporary directory *within* `/tmp`, intention is to create a temporary directory *within* `/tmp`, the `prefix`
the `prefix` *must* end with a trailing platform-specific path separator *must* end with a trailing platform-specific path separator
(`require('path').sep`). (`require('path').sep`).
```js ```js
@ -2038,8 +2039,8 @@ On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to The kernel ignores the position argument and always appends the data to
the end of the file. the end of the file.
*Note*: The behavior of `fs.open()` is platform-specific for some flags. As The behavior of `fs.open()` is platform-specific for some flags. As such,
such, opening a directory on macOS and Linux with the `'a+'` flag - see example opening a directory on macOS and Linux with the `'a+'` flag - see example
below - will return an error. In contrast, on Windows and FreeBSD, a file below - will return an error. In contrast, on Windows and FreeBSD, a file
descriptor will be returned. descriptor will be returned.
@ -2228,10 +2229,11 @@ If `options` is a string, then it specifies the encoding. Example:
```js ```js
fs.readFile('/etc/passwd', 'utf8', callback); fs.readFile('/etc/passwd', 'utf8', callback);
``` ```
*Note*: When the path is a directory, the behavior of
`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS, When the path is a directory, the behavior of `fs.readFile()` and
Linux, and Windows, an error will be returned. On FreeBSD, a representation [`fs.readFileSync()`][] is platform-specific. On macOS, Linux, and Windows, an
of the directory's contents will be returned. error will be returned. On FreeBSD, a representation of the directory's contents
will be returned.
```js ```js
// macOS, Linux, and Windows // macOS, Linux, and Windows
@ -2247,12 +2249,11 @@ fs.readFile('<directory>', (err, data) => {
Any specified file descriptor has to support reading. Any specified file descriptor has to support reading.
*Note*: If a file descriptor is specified as the `path`, it will not be closed If a file descriptor is specified as the `path`, it will not be closed
automatically. automatically.
*Note*: `fs.readFile()` buffers the entire file. The `fs.readFile()` function buffers the entire file. To minimize memory costs,
To minimize memory costs, when possible prefer streaming via when possible prefer streaming via `fs.createReadStream()`.
`fs.createReadStream()`.
## fs.readFileSync(path[, options]) ## fs.readFileSync(path[, options])
<!-- YAML <!-- YAML
@ -2277,8 +2278,8 @@ Synchronous version of [`fs.readFile()`][]. Returns the contents of the `path`.
If the `encoding` option is specified then this function returns a If the `encoding` option is specified then this function returns a
string. Otherwise it returns a buffer. string. Otherwise it returns a buffer.
*Note*: Similar to [`fs.readFile()`][], when the path is a directory, the Similar to [`fs.readFile()`][], when the path is a directory, the behavior of
behavior of `fs.readFileSync()` is platform-specific. `fs.readFileSync()` is platform-specific.
```js ```js
// macOS, Linux, and Windows // macOS, Linux, and Windows
@ -2410,8 +2411,8 @@ object with an `encoding` property specifying the character encoding to use for
the path passed to the callback. If the `encoding` is set to `'buffer'`, the path passed to the callback. If the `encoding` is set to `'buffer'`,
the path returned will be passed as a `Buffer` object. the path returned will be passed as a `Buffer` object.
*Note*: If `path` resolves to a socket or a pipe, the function will return a If `path` resolves to a socket or a pipe, the function will return a system
system dependent name for that object. dependent name for that object.
## fs.realpath.native(path[, options], callback) ## fs.realpath.native(path[, options], callback)
<!-- YAML <!-- YAML
@ -2436,9 +2437,9 @@ object with an `encoding` property specifying the character encoding to use for
the path passed to the callback. If the `encoding` is set to `'buffer'`, the path passed to the callback. If the `encoding` is set to `'buffer'`,
the path returned will be passed as a `Buffer` object. the path returned will be passed as a `Buffer` object.
*Note*: On Linux, when Node.js is linked against musl libc, the procfs file On Linux, when Node.js is linked against musl libc, the procfs file system must
system must be mounted on `/proc` in order for this function to work. Glibc be mounted on `/proc` in order for this function to work. Glibc does not have
does not have this restriction. this restriction.
## fs.realpathSync(path[, options]) ## fs.realpathSync(path[, options])
<!-- YAML <!-- YAML
@ -2482,8 +2483,8 @@ object with an `encoding` property specifying the character encoding to use for
the returned value. If the `encoding` is set to `'buffer'`, the path returned the returned value. If the `encoding` is set to `'buffer'`, the path returned
will be passed as a `Buffer` object. will be passed as a `Buffer` object.
*Note*: If `path` resolves to a socket or a pipe, the function will return a If `path` resolves to a socket or a pipe, the function will return a system
system dependent name for that object. dependent name for that object.
## fs.realpathSync.native(path[, options]) ## fs.realpathSync.native(path[, options])
<!-- YAML <!-- YAML
@ -2503,9 +2504,9 @@ object with an `encoding` property specifying the character encoding to use for
the path passed to the callback. If the `encoding` is set to `'buffer'`, the path passed to the callback. If the `encoding` is set to `'buffer'`,
the path returned will be passed as a `Buffer` object. the path returned will be passed as a `Buffer` object.
*Note*: On Linux, when Node.js is linked against musl libc, the procfs file On Linux, when Node.js is linked against musl libc, the procfs file system must
system must be mounted on `/proc` in order for this function to work. Glibc be mounted on `/proc` in order for this function to work. Glibc does not have
does not have this restriction. this restriction.
## fs.rename(oldPath, newPath, callback) ## fs.rename(oldPath, newPath, callback)
<!-- YAML <!-- YAML
@ -2567,8 +2568,8 @@ changes:
Asynchronous rmdir(2). No arguments other than a possible exception are given Asynchronous rmdir(2). No arguments other than a possible exception are given
to the completion callback. to the completion callback.
*Note*: Using `fs.rmdir()` on a file (not a directory) results in an `ENOENT` Using `fs.rmdir()` on a file (not a directory) results in an `ENOENT` error on
error on Windows and an `ENOTDIR` error on POSIX. Windows and an `ENOTDIR` error on POSIX.
## fs.rmdirSync(path) ## fs.rmdirSync(path)
<!-- YAML <!-- YAML
@ -2584,8 +2585,8 @@ changes:
Synchronous rmdir(2). Returns `undefined`. Synchronous rmdir(2). Returns `undefined`.
*Note*: Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error
error on Windows and an `ENOTDIR` error on POSIX. on Windows and an `ENOTDIR` error on POSIX.
## fs.stat(path, callback) ## fs.stat(path, callback)
<!-- YAML <!-- YAML
@ -2701,8 +2702,8 @@ Asynchronous truncate(2). No arguments other than a possible exception are
given to the completion callback. A file descriptor can also be passed as the given to the completion callback. A file descriptor can also be passed as the
first argument. In this case, `fs.ftruncate()` is called. first argument. In this case, `fs.ftruncate()` is called.
*Note*: Passing a file descriptor is deprecated and may result in an error Passing a file descriptor is deprecated and may result in an error being thrown
being thrown in the future. in the future.
## fs.truncateSync(path[, len]) ## fs.truncateSync(path[, len])
<!-- YAML <!-- YAML
@ -2715,8 +2716,8 @@ added: v0.8.6
Synchronous truncate(2). Returns `undefined`. A file descriptor can also be Synchronous truncate(2). Returns `undefined`. A file descriptor can also be
passed as the first argument. In this case, `fs.ftruncateSync()` is called. passed as the first argument. In this case, `fs.ftruncateSync()` is called.
*Note*: Passing a file descriptor is deprecated and may result in an error Passing a file descriptor is deprecated and may result in an error being thrown
being thrown in the future. in the future.
## fs.unlink(path, callback) ## fs.unlink(path, callback)
<!-- YAML <!-- YAML
@ -2769,7 +2770,7 @@ effectively stopping watching of `filename`.
Calling `fs.unwatchFile()` with a filename that is not being watched is a Calling `fs.unwatchFile()` with a filename that is not being watched is a
no-op, not an error. no-op, not an error.
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and Using [`fs.watch()`][] is more efficient than `fs.watchFile()` and
`fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()` `fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()`
and `fs.unwatchFile()` when possible. and `fs.unwatchFile()` when possible.
@ -2986,18 +2987,18 @@ These stat objects are instances of `fs.Stat`.
To be notified when the file was modified, not just accessed, it is necessary To be notified when the file was modified, not just accessed, it is necessary
to compare `curr.mtime` and `prev.mtime`. to compare `curr.mtime` and `prev.mtime`.
*Note*: When an `fs.watchFile` operation results in an `ENOENT` error, it When an `fs.watchFile` operation results in an `ENOENT` error, it
will invoke the listener once, with all the fields zeroed (or, for dates, the will invoke the listener once, with all the fields zeroed (or, for dates, the
Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`,
instead of zero. If the file is created later on, the listener will be called instead of zero. If the file is created later on, the listener will be called
again, with the latest stat objects. This is a change in functionality since again, with the latest stat objects. This is a change in functionality since
v0.10. v0.10.
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and Using [`fs.watch()`][] is more efficient than `fs.watchFile` and
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
`fs.unwatchFile` when possible. `fs.unwatchFile` when possible.
*Note:* When a file being watched by `fs.watchFile()` disappears and reappears, When a file being watched by `fs.watchFile()` disappears and reappears,
then the `previousStat` reported in the second callback event (the file's then the `previousStat` reported in the second callback event (the file's
reappearance) will be the same as the `previousStat` of the first callback reappearance) will be the same as the `previousStat` of the first callback
event (its disappearance). event (its disappearance).
@ -3154,7 +3155,7 @@ Note that it is unsafe to use `fs.writeFile` multiple times on the same file
without waiting for the callback. For this scenario, without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended. `fs.createWriteStream` is strongly recommended.
*Note*: If a file descriptor is specified as the `file`, it will not be closed If a file descriptor is specified as the `file`, it will not be closed
automatically. automatically.
## fs.writeFileSync(file, data[, options]) ## fs.writeFileSync(file, data[, options])
@ -4207,7 +4208,7 @@ without waiting for the `Promise` to be resolved (or rejected).
The following constants are exported by `fs.constants`. The following constants are exported by `fs.constants`.
*Note*: Not every constant will be available on every operating system. Not every constant will be available on every operating system.
### File Access Constants ### File Access Constants

16
doc/api/http.md
View File

@ -307,7 +307,7 @@ Until the data is consumed, the `'end'` event will not fire. Also, until
the data is read it will consume memory that can eventually lead to a the data is read it will consume memory that can eventually lead to a
'process out of memory' error. 'process out of memory' error.
*Note*: Node.js does not check whether Content-Length and the length of the Node.js does not check whether Content-Length and the length of the
body which has been transmitted are equal or not. body which has been transmitted are equal or not.
The request implements the [Writable Stream][] interface. This is an The request implements the [Writable Stream][] interface. This is an
@ -816,7 +816,7 @@ access this event. In particular, the socket will not emit `'readable'` events
because of how the protocol parser attaches to the socket. The `socket` can because of how the protocol parser attaches to the socket. The `socket` can
also be accessed at `request.connection`. also be accessed at `request.connection`.
*Note*: This event can also be explicitly emitted by users to inject connections 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. into the HTTP server. In that case, any [`Duplex`][] stream can be passed.
### Event: 'request' ### Event: 'request'
@ -915,7 +915,7 @@ to have timed out.
A value of `0` will disable the timeout behavior on incoming connections. A value of `0` will disable the timeout behavior on incoming connections.
*Note*: The socket timeout logic is set up on connection, so changing this The socket timeout logic is set up on connection, so changing this
value only affects new connections to the server, not any existing connections. value only affects new connections to the server, not any existing connections.
### server.keepAliveTimeout ### server.keepAliveTimeout
@ -935,8 +935,8 @@ A value of `0` will disable the keep-alive timeout behavior on incoming connecti
A value of `0` makes the http server behave similarly to Node.js versions prior to 8.0.0, A value of `0` makes the http server behave similarly to Node.js versions prior to 8.0.0,
which did not have a keep-alive timeout. which did not have a keep-alive timeout.
*Note*: The socket timeout logic is set up on connection, so changing this The socket timeout logic is set up on connection, so changing this value only
value only affects new connections to the server, not any existing connections. affects new connections to the server, not any existing connections.
## Class: http.ServerResponse ## Class: http.ServerResponse
<!-- YAML <!-- YAML
@ -1086,7 +1086,7 @@ header-related http module methods. The keys of the returned object are the
header names and the values are the respective header values. All header names header names and the values are the respective header values. All header names
are lowercase. are lowercase.
*Note*: The object returned by the `response.getHeaders()` method _does not_ The object returned by the `response.getHeaders()` method _does not_
prototypically inherit from the JavaScript `Object`. This means that typical prototypically inherit from the JavaScript `Object`. This means that typical
`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
are not defined and *will not work*. are not defined and *will not work*.
@ -1305,8 +1305,8 @@ the second parameter specifies how to encode it into a byte stream.
By default the `encoding` is `'utf8'`. `callback` will be called when this chunk By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
of data is flushed. of data is flushed.
*Note*: This is the raw HTTP body and has nothing to do with This is the raw HTTP body and has nothing to do with higher-level multi-part
higher-level multi-part body encodings that may be used. body encodings that may be used.
The first time [`response.write()`][] is called, it will send the buffered The first time [`response.write()`][] is called, it will send the buffered
header information and the first chunk of the body to the client. The second header information and the first chunk of the body to the client. The second

97
doc/api/http2.md
View File

@ -135,7 +135,7 @@ added: v8.4.0
The `'connect'` event is emitted once the `Http2Session` has been successfully The `'connect'` event is emitted once the `Http2Session` has been successfully
connected to the remote peer and communication may begin. connected to the remote peer and communication may begin.
*Note*: User code will typically not listen for this event directly. User code will typically not listen for this event directly.
#### Event: 'error' #### Event: 'error'
<!-- YAML <!-- YAML
@ -181,8 +181,8 @@ the handler function will receive three arguments:
* `opaqueData` {Buffer} If additional opaque data was included in the GOAWAY * `opaqueData` {Buffer} If additional opaque data was included in the GOAWAY
frame, a `Buffer` instance will be passed containing that data. frame, a `Buffer` instance will be passed containing that data.
*Note*: The `Http2Session` instance will be shut down automatically when the The `Http2Session` instance will be shut down automatically when the `'goaway'`
`'goaway'` event is emitted. event is emitted.
#### Event: 'localSettings' #### Event: 'localSettings'
<!-- YAML <!-- YAML
@ -193,9 +193,8 @@ The `'localSettings'` event is emitted when an acknowledgment SETTINGS frame
has been received. When invoked, the handler function will receive a copy of has been received. When invoked, the handler function will receive a copy of
the local settings. the local settings.
*Note*: When using `http2session.settings()` to submit new settings, the When using `http2session.settings()` to submit new settings, the modified
modified settings do not take effect until the `'localSettings'` event is settings do not take effect until the `'localSettings'` event is emitted.
emitted.
```js ```js
session.settings({ enablePush: false }); session.settings({ enablePush: false });
@ -540,10 +539,9 @@ Once called, the `http2session.pendingSettingsAck` property will be `true`
while the session is waiting for the remote peer to acknowledge the new while the session is waiting for the remote peer to acknowledge the new
settings. settings.
*Note*: The new settings will not become effective until the SETTINGS The new settings will not become effective until the SETTINGS acknowledgment is
acknowledgment is received and the `'localSettings'` event is emitted. It received and the `'localSettings'` event is emitted. It is possible to send
is possible to send multiple SETTINGS frames while acknowledgment is still multiple SETTINGS frames while acknowledgment is still pending.
pending.
#### http2session.type #### http2session.type
<!-- YAML <!-- YAML
@ -718,10 +716,9 @@ queuing the last chunk of payload data to be sent. The callback is passed a
single object (with a `null` prototype) that the listener may use to specify single object (with a `null` prototype) that the listener may use to specify
the trailing header fields to send to the peer. the trailing header fields to send to the peer.
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
pseudo-header fields (e.g. `':method'`, `':path'`, etc). An `'error'` event fields (e.g. `':method'`, `':path'`, etc). An `'error'` event will be emitted
will be emitted if the `getTrailers` callback attempts to set such header if the `getTrailers` callback attempts to set such header fields.
fields.
The `:method` and `:path` pseudo-headers are not specified within `headers`, The `:method` and `:path` pseudo-headers are not specified within `headers`,
they respectively default to: they respectively default to:
@ -749,7 +746,7 @@ On the client, `Http2Stream` instances are created and returned when either the
`http2session.request()` method is called, or in response to an incoming `http2session.request()` method is called, or in response to an incoming
`'push'` event. `'push'` event.
*Note*: The `Http2Stream` class is a base for the [`ServerHttp2Stream`][] and The `Http2Stream` class is a base for the [`ServerHttp2Stream`][] and
[`ClientHttp2Stream`][] classes, each of which is used specifically by either [`ClientHttp2Stream`][] classes, each of which is used specifically by either
the Server or Client side, respectively. the Server or Client side, respectively.
@ -770,14 +767,13 @@ when:
On the client side, instances of [`ClientHttp2Stream`][] are created when the On the client side, instances of [`ClientHttp2Stream`][] are created when the
`http2session.request()` method is called. `http2session.request()` method is called.
*Note*: On the client, the `Http2Stream` instance returned by On the client, the `Http2Stream` instance returned by `http2session.request()`
`http2session.request()` may not be immediately ready for use if the parent may not be immediately ready for use if the parent `Http2Session` has not yet
`Http2Session` has not yet been fully established. In such cases, operations been fully established. In such cases, operations called on the `Http2Stream`
called on the `Http2Stream` will be buffered until the `'ready'` event is will be buffered until the `'ready'` event is emitted. User code should rarely,
emitted. User code should rarely, if ever, need to handle the `'ready'` if ever, need to handle the `'ready'` event directly. The ready status of an
event directly. The ready status of an `Http2Stream` can be determined by `Http2Stream` can be determined by checking the value of `http2stream.id`. If
checking the value of `http2stream.id`. If the value is `undefined`, the stream the value is `undefined`, the stream is not yet ready for use.
is not yet ready for use.
##### Destruction ##### Destruction
@ -809,8 +805,8 @@ added: v8.4.0
The `'aborted'` event is emitted whenever a `Http2Stream` instance is The `'aborted'` event is emitted whenever a `Http2Stream` instance is
abnormally aborted in mid-communication. abnormally aborted in mid-communication.
*Note*: The `'aborted'` event will only be emitted if the `Http2Stream` The `'aborted'` event will only be emitted if the `Http2Stream` writable side
writable side has not been ended. has not been ended.
#### Event: 'close' #### Event: 'close'
<!-- YAML <!-- YAML
@ -1231,10 +1227,9 @@ server.on('stream', (stream) => {
}); });
``` ```
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted
will be emitted if the `getTrailers` callback attempts to set such header if the `getTrailers` callback attempts to set such header fields.
fields.
#### http2stream.respondWithFD(fd[, headers[, options]]) #### http2stream.respondWithFD(fd[, headers[, options]])
<!-- YAML <!-- YAML
@ -1315,10 +1310,9 @@ server.on('stream', (stream) => {
server.on('close', () => fs.closeSync(fd)); server.on('close', () => fs.closeSync(fd));
``` ```
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted
will be emitted if the `getTrailers` callback attempts to set such header if the `getTrailers` callback attempts to set such header fields.
fields.
#### http2stream.respondWithFile(path[, headers[, options]]) #### http2stream.respondWithFile(path[, headers[, options]])
<!-- YAML <!-- YAML
@ -1424,10 +1418,9 @@ server.on('stream', (stream) => {
}); });
``` ```
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted
will be emitted if the `getTrailers` callback attempts to set such header if the `getTrailers` callback attempts to set such header fields.
fields.
### Class: Http2Server ### Class: Http2Server
<!-- YAML <!-- YAML
@ -2005,8 +1998,8 @@ const headers = {
stream.respond(headers); stream.respond(headers);
``` ```
*Note*: Header objects passed to callback functions will have a `null` Header objects passed to callback functions will have a `null` prototype. This
prototype. This means that normal JavaScript object methods such as means that normal JavaScript object methods such as
`Object.prototype.toString()` and `Object.prototype.hasOwnProperty()` will `Object.prototype.toString()` and `Object.prototype.hasOwnProperty()` will
not work. not work.
@ -2078,9 +2071,8 @@ const server = http2.createServer({
}); });
``` ```
*Note*: The `options.selectPadding` function is invoked once for *every* The `options.selectPadding` function is invoked once for *every* HEADERS and
HEADERS and DATA frame. This has a definite noticeable impact on DATA frame. This has a definite noticeable impact on performance.
performance.
### Error Handling ### Error Handling
@ -2310,8 +2302,8 @@ added: v8.4.0
The `'aborted'` event is emitted whenever a `Http2ServerRequest` instance is The `'aborted'` event is emitted whenever a `Http2ServerRequest` instance is
abnormally aborted in mid-communication. abnormally aborted in mid-communication.
*Note*: The `'aborted'` event will only be emitted if the The `'aborted'` event will only be emitted if the `Http2ServerRequest` writable
`Http2ServerRequest` writable side has not been ended. side has not been ended.
#### Event: 'close' #### Event: 'close'
<!-- YAML <!-- YAML
@ -2357,12 +2349,11 @@ console.log(request.headers);
See [HTTP2 Headers Object][]. See [HTTP2 Headers Object][].
*Note*: In HTTP/2, the request path, hostname, protocol, and method are In HTTP/2, the request path, hostname, protocol, and method are represented as
represented as special headers prefixed with the `:` character (e.g. `':path'`). special headers prefixed with the `:` character (e.g. `':path'`). These special
These special headers will be included in the `request.headers` object. Care headers will be included in the `request.headers` object. Care must be taken not
must be taken not to inadvertently modify these special headers or errors may to inadvertently modify these special headers or errors may occur. For instance,
occur. For instance, removing all headers from the request will cause errors removing all headers from the request will cause errors to occur:
to occur:
```js ```js
removeAllHeaders(request.headers); removeAllHeaders(request.headers);
@ -2694,7 +2685,7 @@ header-related http module methods. The keys of the returned object are the
header names and the values are the respective header values. All header names header names and the values are the respective header values. All header names
are lowercase. are lowercase.
*Note*: The object returned by the `response.getHeaders()` method _does not_ The object returned by the `response.getHeaders()` method _does not_
prototypically inherit from the JavaScript `Object`. This means that typical prototypically inherit from the JavaScript `Object`. This means that typical
`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
are not defined and *will not work*. are not defined and *will not work*.
@ -2922,8 +2913,8 @@ the second parameter specifies how to encode it into a byte stream.
By default the `encoding` is `'utf8'`. `callback` will be called when this chunk By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
of data is flushed. of data is flushed.
*Note*: This is the raw HTTP body and has nothing to do with This is the raw HTTP body and has nothing to do with higher-level multi-part
higher-level multi-part body encodings that may be used. body encodings that may be used.
The first time [`response.write()`][] is called, it will send the buffered The first time [`response.write()`][] is called, it will send the buffered
header information and the first chunk of the body to the client. The second header information and the first chunk of the body to the client. The second

4
doc/api/intl.md
View File

@ -56,8 +56,8 @@ option:
| [REPL][] | partial (inaccurate line editing) | full | full | full | | [REPL][] | partial (inaccurate line editing) | full | full | full |
| [`require('util').TextDecoder`][] | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full | | [`require('util').TextDecoder`][] | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full |
*Note*: The "(not locale-aware)" designation denotes that the function carries The "(not locale-aware)" designation denotes that the function carries out its
out its operation just like the non-`Locale` version of the function, if one operation just like the non-`Locale` version of the function, if one
exists. For example, under `none` mode, `Date.prototype.toLocaleString()`'s exists. For example, under `none` mode, `Date.prototype.toLocaleString()`'s
operation is identical to that of `Date.prototype.toString()`. operation is identical to that of `Date.prototype.toString()`.

20
doc/api/modules.md
View File

@ -352,9 +352,9 @@ If this was in a folder at `./some-library`, then
This is the extent of Node.js's awareness of package.json files. This is the extent of Node.js's awareness of package.json files.
*Note*: If the file specified by the `"main"` entry of `package.json` is If the file specified by the `"main"` entry of `package.json` is missing and
missing and can not be resolved, Node.js will report the entire module as can not be resolved, Node.js will report the entire module as missing with the
missing with the default error: default error:
```txt ```txt
Error: Cannot find module 'some-library' Error: Cannot find module 'some-library'
@ -407,7 +407,7 @@ If the `NODE_PATH` environment variable is set to a colon-delimited list
of absolute paths, then Node.js will search those paths for modules if they of absolute paths, then Node.js will search those paths for modules if they
are not found elsewhere. are not found elsewhere.
*Note*: On Windows, `NODE_PATH` is delimited by semicolons instead of colons. On Windows, `NODE_PATH` is delimited by semicolons (`;`) instead of colons.
`NODE_PATH` was originally created to support loading modules from `NODE_PATH` was originally created to support loading modules from
varying paths before the current [module resolution][] algorithm was frozen. varying paths before the current [module resolution][] algorithm was frozen.
@ -430,8 +430,8 @@ configured `node_prefix`.
These are mostly for historic reasons. These are mostly for historic reasons.
*Note*: It is strongly encouraged to place dependencies in the local It is strongly encouraged to place dependencies in the local `node_modules`
`node_modules` folder. These will be loaded faster, and more reliably. folder. These will be loaded faster, and more reliably.
## The module wrapper ## The module wrapper
@ -816,10 +816,10 @@ added: v0.5.1
The `module.require` method provides a way to load a module as if The `module.require` method provides a way to load a module as if
`require()` was called from the original module. `require()` was called from the original module.
*Note*: In order to do this, it is necessary to get a reference to the In order to do this, it is necessary to get a reference to the `module` object.
`module` object. Since `require()` returns the `module.exports`, and the Since `require()` returns the `module.exports`, and the `module` is typically
`module` is typically *only* available within a specific module's code, it must *only* available within a specific module's code, it must be explicitly exported
be explicitly exported in order to be used. in order to be used.
## The `Module` Object ## The `Module` Object

46
doc/api/n-api.md
View File

@ -250,9 +250,9 @@ typedef struct napi_extended_error_info {
[`napi_get_last_error_info`][] returns the information for the last [`napi_get_last_error_info`][] returns the information for the last
N-API call that was made. N-API call that was made.
*Note*: Do not rely on the content or format of any of the extended Do not rely on the content or format of any of the extended information as it
information as it is not subject to SemVer and may change at any time. is not subject to SemVer and may change at any time. It is intended only for
It is intended only for logging purposes. logging purposes.
#### napi_get_last_error_info #### napi_get_last_error_info
<!-- YAML <!-- YAML
@ -272,12 +272,12 @@ Returns `napi_ok` if the API succeeded.
This API retrieves a `napi_extended_error_info` structure with information This API retrieves a `napi_extended_error_info` structure with information
about the last error that occurred. about the last error that occurred.
*Note*: The content of the `napi_extended_error_info` returned is only The content of the `napi_extended_error_info` returned is only valid up until
valid up until an n-api function is called on the same `env`. an n-api function is called on the same `env`.
*Note*: Do not rely on the content or format of any of the extended Do not rely on the content or format of any of the extended information as it
information as it is not subject to SemVer and may change at any time. is not subject to SemVer and may change at any time. It is intended only for
It is intended only for logging purposes. logging purposes.
### Exceptions ### Exceptions
@ -1169,9 +1169,9 @@ later by native code. The API allows the caller to pass in a finalize callback,
in case the underlying native resource needs to be cleaned up when the external in case the underlying native resource needs to be cleaned up when the external
JavaScript value gets collected. JavaScript value gets collected.
*Note*: The created value is not an object, and therefore does not support The created value is not an object, and therefore does not support additional
additional properties. It is considered a distinct value type: calling properties. It is considered a distinct value type: calling `napi_typeof()` with
`napi_typeof()` with an external value yields `napi_external`. an external value yields `napi_external`.
#### napi_create_external_arraybuffer #### napi_create_external_arraybuffer
<!-- YAML <!-- YAML
@ -1236,7 +1236,7 @@ This API allocates a `node::Buffer` object and initializes it with data
backed by the passed in buffer. While this is still a fully-supported data backed by the passed in buffer. While this is still a fully-supported data
structure, in most cases using a TypedArray will suffice. structure, in most cases using a TypedArray will suffice.
*Note*: For Node.js >=4 `Buffers` are Uint8Arrays. For Node.js >=4 `Buffers` are Uint8Arrays.
#### napi_create_function #### napi_create_function
<!-- YAML <!-- YAML
@ -2850,10 +2850,9 @@ 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 This is the primary mechanism to allow calling *into* the add-on's native code
*from* JavaScript. *from* JavaScript.
*Note*: The newly created function is not automatically visible from The newly created function is not automatically visible from script after this
script after this call. Instead, a property must be explicitly set on any call. Instead, a property must be explicitly set on any object that is visible
object that is visible to JavaScript, in order for the function to be accessible to JavaScript, in order for the function to be accessible from script.
from script.
In order to expose a function as part of the In order to expose a function as part of the
add-on's module exports, set the newly created function on the exports add-on's module exports, set the newly created function on the exports
@ -2886,7 +2885,7 @@ const myaddon = require('./addon');
myaddon.sayHello(); myaddon.sayHello();
``` ```
*Note*: The string passed to require is not necessarily the name passed into The string passed to require is not necessarily the name passed into
`NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp` `NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp`
responsible for creating the `.node` file. responsible for creating the `.node` file.
@ -3142,8 +3141,8 @@ 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 be invoked.) Therefore, when obtaining a reference a finalize callback is also
required in order to enable correct proper of the reference. required in order to enable correct proper of the reference.
*Note*: This API may modify the prototype chain of the wrapper object. This API may modify the prototype chain of the wrapper object. Afterward,
Afterward, additional manipulation of the wrapper's prototype chain may cause additional manipulation of the wrapper's prototype chain may cause
`napi_unwrap()` to fail. `napi_unwrap()` to fail.
Calling napi_wrap() a second time on an object will return an error. To associate Calling napi_wrap() a second time on an object will return an error. To associate
@ -3284,11 +3283,10 @@ required.
`async_resource_name` should be a null-terminated, UTF-8-encoded string. `async_resource_name` should be a null-terminated, UTF-8-encoded string.
*Note*: The `async_resource_name` identifier is provided by the user and should The `async_resource_name` identifier is provided by the user and should be
be representative of the type of async work being performed. It is also representative of the type of async work being performed. It is also recommended
recommended to apply namespacing to the identifier, e.g. by including the to apply namespacing to the identifier, e.g. by including the module name. See
module name. See the [`async_hooks` documentation][async_hooks `type`] the [`async_hooks` documentation][async_hooks `type`] for more information.
for more information.
### napi_delete_async_work ### napi_delete_async_work
<!-- YAML <!-- YAML

21
doc/api/net.md
View File

@ -194,14 +194,11 @@ length of the queue of pending connections. The actual length will be determined
by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn` by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn`
on Linux. The default value of this parameter is 511 (not 512). on Linux. The default value of this parameter is 511 (not 512).
All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for details).
*Note*: The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
* All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.
details).
* The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.
One of the most common errors raised when listening is `EADDRINUSE`. One of the most common errors raised when listening is `EADDRINUSE`.
This happens when another server is already listening on the requested This happens when another server is already listening on the requested
@ -237,7 +234,7 @@ The `handle` object can be either a server, a socket (anything with an
underlying `_handle` member), or an object with an `fd` member that is a underlying `_handle` member), or an object with an `fd` member that is a
valid file descriptor. valid file descriptor.
*Note*: Listening on a file descriptor is not supported on Windows. Listening on a file descriptor is not supported on Windows.
#### server.listen(options[, callback]) #### server.listen(options[, callback])
<!-- YAML <!-- YAML
@ -309,9 +306,9 @@ If `host` is omitted, the server will accept connections on the
[unspecified IPv6 address][] (`::`) when IPv6 is available, or the [unspecified IPv6 address][] (`::`) when IPv6 is available, or the
[unspecified IPv4 address][] (`0.0.0.0`) otherwise. [unspecified IPv4 address][] (`0.0.0.0`) otherwise.
*Note*: In most operating systems, listening to the In most operating systems, listening to the [unspecified IPv6 address][] (`::`)
[unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on may cause the `net.Server` to also listen on the [unspecified IPv4 address][]
the [unspecified IPv4 address][] (`0.0.0.0`). (`0.0.0.0`).
### server.listening ### server.listening
<!-- YAML <!-- YAML
@ -885,7 +882,7 @@ Possible signatures:
* [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`] * [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`]
for TCP connections. for TCP connections.
*Note*: The [`net.connect()`][] function is an alias to this function. The [`net.connect()`][] function is an alias to this function.
### net.createConnection(options[, connectListener]) ### net.createConnection(options[, connectListener])
<!-- YAML <!-- YAML

18
doc/api/os.md
View File

@ -166,8 +166,8 @@ For example:
] ]
``` ```
*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values Because `nice` values are UNIX-specific, on Windows the `nice` values of all
of all processors are always 0. processors are always 0.
## os.endianness() ## os.endianness()
<!-- YAML <!-- YAML
@ -322,8 +322,8 @@ Currently possible values are:
Equivalent to [`process.platform`][]. Equivalent to [`process.platform`][].
*Note*: The value `'android'` may also be returned if the Node.js is built on The value `'android'` may also be returned if the Node.js is built on the
the Android operating system. However, Android support in Node.js is considered Android operating system. However, Android support in Node.js is considered
to be experimental at this time. to be experimental at this time.
## os.release() ## os.release()
@ -336,8 +336,8 @@ added: v0.3.3
The `os.release()` method returns a string identifying the operating system The `os.release()` method returns a string identifying the operating system
release. release.
*Note*: On POSIX systems, the operating system release is determined by On POSIX systems, the operating system release is determined by calling
calling [uname(3)][]. On Windows, `GetVersionExW()` is used. Please see [uname(3)][]. On Windows, `GetVersionExW()` is used. Please see
https://en.wikipedia.org/wiki/Uname#Examples for more information. https://en.wikipedia.org/wiki/Uname#Examples for more information.
## os.tmpdir() ## os.tmpdir()
@ -389,8 +389,8 @@ added: v0.3.3
The `os.uptime()` method returns the system uptime in number of seconds. The `os.uptime()` method returns the system uptime in number of seconds.
*Note*: On Windows the returned value includes fractions of a second. On Windows the returned value includes fractions of a second. Use `Math.floor()`
Use `Math.floor()` to get whole seconds. to get whole seconds.
## os.userInfo([options]) ## os.userInfo([options])
<!-- YAML <!-- YAML
@ -417,7 +417,7 @@ operating system response.
The following constants are exported by `os.constants`. The following constants are exported by `os.constants`.
*Note*: Not all constants will be available on every operating system. Not all constants will be available on every operating system.
### Signal Constants ### Signal Constants
<!-- YAML <!-- YAML

6
doc/api/path.md
View File

@ -539,9 +539,9 @@ On Windows:
// Returns: ['foo', 'bar', 'baz'] // Returns: ['foo', 'bar', 'baz']
``` ```
*Note*: On Windows, both the forward slash (`/`) and backward slash (`\`) are On Windows, both the forward slash (`/`) and backward slash (`\`) are accepted
accepted as path segment separators; however, the `path` methods only add as path segment separators; however, the `path` methods only add backward
backward slashes (`\`). slashes (`\`).
## path.toNamespacedPath(path) ## path.toNamespacedPath(path)
<!-- YAML <!-- YAML

127
doc/api/process.md
View File

@ -94,8 +94,8 @@ The listener callback is invoked with the following arguments:
* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or * `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
undefined. undefined.
*Note*: The message goes through serialization and parsing. The resulting The message goes through serialization and parsing. The resulting message might
message might not be the same as what is originally sent. not be the same as what is originally sent.
### Event: 'rejectionHandled' ### Event: 'rejectionHandled'
<!-- YAML <!-- YAML
@ -406,11 +406,10 @@ process.on('SIGTERM', handle);
hanging in an endless loop, since listeners attached using `process.on()` are hanging in an endless loop, since listeners attached using `process.on()` are
called asynchronously and therefore unable to correct the underlying problem. called asynchronously and therefore unable to correct the underlying problem.
*Note*: Windows does not support sending signals, but Node.js offers some Windows does not support sending signals, but Node.js offers some emulation
emulation with [`process.kill()`][], and [`subprocess.kill()`][]. Sending with [`process.kill()`][], and [`subprocess.kill()`][]. Sending signal `0` can
signal `0` can be used to test for the existence of a process. Sending `SIGINT`, be used to test for the existence of a process. Sending `SIGINT`, `SIGTERM`,
`SIGTERM`, and `SIGKILL` cause the unconditional termination of the target and `SIGKILL` cause the unconditional termination of the target process.
process.
## process.abort() ## process.abort()
<!-- YAML <!-- YAML
@ -567,9 +566,9 @@ An example of the possible output looks like:
} }
``` ```
*Note*: The `process.config` property is **not** read-only and there are The `process.config` property is **not** read-only and there are existing
existing modules in the ecosystem that are known to extend, modify, or entirely modules in the ecosystem that are known to extend, modify, or entirely replace
replace the value of `process.config`. the value of `process.config`.
## process.connected ## process.connected
<!-- YAML <!-- YAML
@ -674,9 +673,9 @@ If there are specific reasons to use `process.dlopen()` (for instance,
to specify dlopen flags), it's often useful to use [`require.resolve()`][] to specify dlopen flags), it's often useful to use [`require.resolve()`][]
to look up the module's path. to look up the module's path.
*Note*: An important drawback when calling `process.dlopen()` is that the An important drawback when calling `process.dlopen()` is that the `module`
`module` instance must be passed. Functions exported by the C++ Addon will instance must be passed. Functions exported by the C++ Addon will be accessible
be accessible via `module.exports`. via `module.exports`.
The example below shows how to load a C++ Addon, named as `binding`, The example below shows how to load a C++ Addon, named as `binding`,
that exports a `foo` function. All the symbols will be loaded before that exports a `foo` function. All the symbols will be loaded before
@ -1057,8 +1056,8 @@ if (process.getegid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.geteuid() ## process.geteuid()
<!-- YAML <!-- YAML
@ -1076,8 +1075,8 @@ if (process.geteuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.getgid() ## process.getgid()
<!-- YAML <!-- YAML
@ -1095,9 +1094,8 @@ if (process.getgid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.getgroups() ## process.getgroups()
<!-- YAML <!-- YAML
@ -1110,8 +1108,8 @@ The `process.getgroups()` method returns an array with the supplementary group
IDs. POSIX leaves it unspecified if the effective group ID is included but IDs. POSIX leaves it unspecified if the effective group ID is included but
Node.js ensures it always is. Node.js ensures it always is.
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.getuid() ## process.getuid()
<!-- YAML <!-- YAML
@ -1129,8 +1127,8 @@ if (process.getuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.hasUncaughtExceptionCaptureCallback() ## process.hasUncaughtExceptionCaptureCallback()
<!-- YAML <!-- YAML
@ -1202,8 +1200,8 @@ process.setgid(1000); // drop root gid
console.log(process.getgroups()); // [ 27, 30, 46, 1000 ] console.log(process.getgroups()); // [ 27, 30, 46, 1000 ]
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.kill(pid[, signal]) ## process.kill(pid[, signal])
<!-- YAML <!-- YAML
@ -1225,9 +1223,9 @@ case, a signal of `0` can be used to test for the existence of a process.
Windows platforms will throw an error if the `pid` is used to kill a process Windows platforms will throw an error if the `pid` is used to kill a process
group. group.
*Note*: Even though the name of this function is `process.kill()`, it is Even though the name of this function is `process.kill()`, it is really just a
really just a signal sender, like the `kill` system call. The signal sent may signal sender, like the `kill` system call. The signal sent may do something
do something other than kill the target process. other than kill the target process.
For example: For example:
@ -1244,8 +1242,8 @@ setTimeout(() => {
process.kill(process.pid, 'SIGHUP'); process.kill(process.pid, 'SIGHUP');
``` ```
*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start When `SIGUSR1` is received by a Node.js process, Node.js will start the
the debugger, see [Signal Events][]. debugger, see [Signal Events][].
## process.mainModule ## process.mainModule
<!-- YAML <!-- YAML
@ -1400,10 +1398,10 @@ function definitelyAsync(arg, cb) {
} }
``` ```
*Note*: The next tick queue is completely drained on each pass of the The next tick queue is completely drained on each pass of the event loop
event loop **before** additional I/O is processed. As a result, **before** additional I/O is processed. As a result, recursively setting
recursively setting nextTick callbacks will block any I/O from nextTick callbacks will block any I/O from happening, just like a
happening, just like a `while(true);` loop. `while(true);` loop.
## process.noDeprecation ## process.noDeprecation
<!-- YAML <!-- YAML
@ -1541,8 +1539,8 @@ used to send messages to the parent process. Messages will be received as a
If Node.js was not spawned with an IPC channel, `process.send()` will be If Node.js was not spawned with an IPC channel, `process.send()` will be
`undefined`. `undefined`.
*Note*: The message goes through serialization and parsing. The resulting The message goes through serialization and parsing. The resulting message might
message might not be the same as what is originally sent. not be the same as what is originally sent.
## process.setegid(id) ## process.setegid(id)
<!-- YAML <!-- YAML
@ -1568,8 +1566,8 @@ if (process.getegid && process.setegid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.seteuid(id) ## process.seteuid(id)
@ -1596,8 +1594,8 @@ if (process.geteuid && process.seteuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.setgid(id) ## process.setgid(id)
<!-- YAML <!-- YAML
@ -1623,8 +1621,8 @@ if (process.getgid && process.setgid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.setgroups(groups) ## process.setgroups(groups)
<!-- YAML <!-- YAML
@ -1639,8 +1637,8 @@ to have `root` or the `CAP_SETGID` capability.
The `groups` array can contain numeric group IDs, group names or both. The `groups` array can contain numeric group IDs, group names or both.
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.setuid(id) ## process.setuid(id)
<!-- YAML <!-- YAML
@ -1664,9 +1662,8 @@ if (process.getuid && process.setuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows This function is only available on POSIX platforms (i.e. not Windows or
or Android). Android).
## process.setUncaughtExceptionCaptureCallback(fn) ## process.setUncaughtExceptionCaptureCallback(fn)
<!-- YAML <!-- YAML
@ -1688,8 +1685,8 @@ To unset the capture function, `process.setUncaughtExceptionCapture(null)`
may be used. Calling this method with a non-`null` argument while another may be used. Calling this method with a non-`null` argument while another
capture function is set will throw an error. capture function is set will throw an error.
*Note*: Using this function is mutually exclusive with using the Using this function is mutually exclusive with using the deprecated
deprecated [`domain`][] built-in module. [`domain`][] built-in module.
## process.stderr ## process.stderr
@ -1700,8 +1697,8 @@ The `process.stderr` property returns a stream connected to
stream) unless fd `2` refers to a file, in which case it is stream) unless fd `2` refers to a file, in which case it is
a [Writable][] stream. a [Writable][] stream.
*Note*: `process.stderr` differs from other Node.js streams in important ways, `process.stderr` differs from other Node.js streams in important ways, see
see [note on process I/O][] for more information. [note on process I/O][] for more information.
## process.stdin ## process.stdin
@ -1733,7 +1730,7 @@ As a [Duplex][] stream, `process.stdin` can also be used in "old" mode that
is compatible with scripts written for Node.js prior to v0.10. is compatible with scripts written for Node.js prior to v0.10.
For more information see [Stream compatibility][]. For more information see [Stream compatibility][].
*Note*: In "old" streams mode the `stdin` stream is paused by default, so one In "old" streams mode the `stdin` stream is paused by default, so one
must call `process.stdin.resume()` to read from it. Note also that calling must call `process.stdin.resume()` to read from it. Note also that calling
`process.stdin.resume()` itself would switch stream to "old" mode. `process.stdin.resume()` itself would switch stream to "old" mode.
@ -1752,8 +1749,8 @@ For example, to copy process.stdin to process.stdout:
process.stdin.pipe(process.stdout); process.stdin.pipe(process.stdout);
``` ```
*Note*: `process.stdout` differs from other Node.js streams in important ways, `process.stdout` differs from other Node.js streams in important ways, see
see [note on process I/O][] for more information. [note on process I/O][] for more information.
### A note on process I/O ### A note on process I/O
@ -1828,14 +1825,14 @@ The `process.title` property returns the current process title (i.e. returns
the current value of `ps`). Assigning a new value to `process.title` modifies the current value of `ps`). Assigning a new value to `process.title` modifies
the current value of `ps`. the current value of `ps`.
*Note*: When a new value is assigned, different platforms will impose When a new value is assigned, different platforms will impose different maximum
different maximum length restrictions on the title. Usually such restrictions length restrictions on the title. Usually such restrictions are quite limited.
are quite limited. For instance, on Linux and macOS, `process.title` is limited For instance, on Linux and macOS, `process.title` is limited to the size of the
to the size of the binary name plus the length of the command line arguments binary name plus the length of the command line arguments because setting the
because setting the `process.title` overwrites the `argv` memory of the `process.title` overwrites the `argv` memory of the process. Node.js v0.8
process. Node.js v0.8 allowed for longer process title strings by also allowed for longer process title strings by also overwriting the `environ`
overwriting the `environ` memory but that was potentially insecure and memory but that was potentially insecure and confusing in some (rather obscure)
confusing in some (rather obscure) cases. cases.
## process.traceDeprecation ## process.traceDeprecation
<!-- YAML <!-- YAML
@ -1881,8 +1878,8 @@ added: v0.5.0
The `process.uptime()` method returns the number of seconds the current Node.js The `process.uptime()` method returns the number of seconds the current Node.js
process has been running. process has been running.
*Note*: The return value includes fractions of a second. Use `Math.floor()` The return value includes fractions of a second. Use `Math.floor()` to get whole
to get whole seconds. seconds.
## process.version ## process.version
<!-- YAML <!-- YAML

2
doc/api/punycode.md
View File

@ -33,7 +33,7 @@ to `'example.com'`) is represented by Punycode as the ASCII string
The `punycode` module provides a simple implementation of the Punycode standard. The `punycode` module provides a simple implementation of the Punycode standard.
*Note*: The `punycode` module is a third-party dependency used by Node.js and The `punycode` module is a third-party dependency used by Node.js and
made available to developers as a convenience. Fixes or other modifications to made available to developers as a convenience. Fixes or other modifications to
the module must be directed to the [Punycode.js][] project. the module must be directed to the [Punycode.js][] project.

2
doc/api/querystring.md
View File

@ -69,7 +69,7 @@ For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into:
} }
``` ```
*Note*: The object returned by the `querystring.parse()` method _does not_ The object returned by the `querystring.parse()` method _does not_
prototypically inherit from the JavaScript `Object`. This means that typical prototypically inherit from the JavaScript `Object`. This means that typical
`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
are not defined and *will not work*. are not defined and *will not work*.

22
doc/api/readline.md
View File

@ -29,9 +29,9 @@ rl.question('What do you think of Node.js? ', (answer) => {
}); });
``` ```
*Note*: Once this code is invoked, the Node.js application will not Once this code is invoked, the Node.js application will not terminate until the
terminate until the `readline.Interface` is closed because the interface `readline.Interface` is closed because the interface waits for data to be
waits for data to be received on the `input` stream. received on the `input` stream.
## Class: Interface ## Class: Interface
<!-- YAML <!-- YAML
@ -142,7 +142,7 @@ rl.on('SIGCONT', () => {
}); });
``` ```
*Note*: The `'SIGCONT'` event is _not_ supported on Windows. The `'SIGCONT'` event is _not_ supported on Windows.
### Event: 'SIGINT' ### Event: 'SIGINT'
<!-- YAML <!-- YAML
@ -194,7 +194,7 @@ rl.on('SIGTSTP', () => {
}); });
``` ```
*Note*: The `'SIGTSTP'` event is _not_ supported on Windows. The `'SIGTSTP'` event is _not_ supported on Windows.
### rl.close() ### rl.close()
<!-- YAML <!-- YAML
@ -262,8 +262,8 @@ rl.question('What is your favorite food? ', (answer) => {
}); });
``` ```
*Note*: The `callback` function passed to `rl.question()` does not follow the The `callback` function passed to `rl.question()` does not follow the typical
typical pattern of accepting an `Error` object or `null` as the first argument. pattern of accepting an `Error` object or `null` as the first argument.
The `callback` is called with the provided answer as the only argument. The `callback` is called with the provided answer as the only argument.
### rl.resume() ### rl.resume()
@ -315,8 +315,8 @@ rl.write('Delete this!');
rl.write(null, { ctrl: true, name: 'u' }); rl.write(null, { ctrl: true, name: 'u' });
``` ```
*Note*: The `rl.write()` method will write the data to the `readline` The `rl.write()` method will write the data to the `readline` Interface's
Interface's `input` *as if it were provided by the user*. `input` *as if it were provided by the user*.
## readline.clearLine(stream, dir) ## readline.clearLine(stream, dir)
<!-- YAML <!-- YAML
@ -467,8 +467,8 @@ autocompletion is disabled when copy-pasted input is detected.
If the `stream` is a [TTY][], then it must be in raw mode. If the `stream` is a [TTY][], then it must be in raw mode.
*Note*: This is automatically called by any readline instance on its `input` This is automatically called by any readline instance on its `input` if the
if the `input` is a terminal. Closing the `readline` instance does not stop `input` is a terminal. Closing the `readline` instance does not stop
the `input` from emitting `'keypress'` events. the `input` from emitting `'keypress'` events.
```js ```js

143
doc/api/stream.md
View File

@ -188,8 +188,8 @@ Examples of [Writable][] streams include:
* [child process stdin][] * [child process stdin][]
* [`process.stdout`][], [`process.stderr`][] * [`process.stdout`][], [`process.stderr`][]
*Note*: Some of these examples are actually [Duplex][] streams that implement Some of these examples are actually [Duplex][] streams that implement the
the [Writable][] interface. [Writable][] interface.
All [Writable][] streams implement the interface defined by the All [Writable][] streams implement the interface defined by the
`stream.Writable` class. `stream.Writable` class.
@ -270,7 +270,7 @@ added: v0.9.4
The `'error'` event is emitted if an error occurred while writing or piping The `'error'` event is emitted if an error occurred while writing or piping
data. The listener callback is passed a single `Error` argument when called. data. The listener callback is passed a single `Error` argument when called.
*Note*: The stream is not closed when the `'error'` event is emitted. The stream is not closed when the `'error'` event is emitted.
##### Event: 'finish' ##### Event: 'finish'
<!-- YAML <!-- YAML
@ -589,15 +589,14 @@ 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. to stop generating the data.
*Note*: For backwards compatibility reasons, removing [`'data'`][] event For backwards compatibility reasons, removing [`'data'`][] event handlers will
handlers will **not** automatically pause the stream. Also, if there are piped **not** automatically pause the stream. Also, if there are piped destinations,
destinations, then calling [`stream.pause()`][stream-pause] will not guarantee then calling [`stream.pause()`][stream-pause] will not guarantee that the
that the stream will *remain* paused once those destinations drain and ask for stream will *remain* paused once those destinations drain and ask for more data.
more data.
*Note*: If a [Readable][] is switched into flowing mode and there are no If a [Readable][] is switched into flowing mode and there are no consumers
consumers available to handle the data, that data will be lost. This can occur, available to handle the data, that data will be lost. This can occur, for
for instance, when the `readable.resume()` method is called without a listener instance, when the `readable.resume()` method is called without a listener
attached to the `'data'` event, or when a `'data'` event handler is removed attached to the `'data'` event, or when a `'data'` event handler is removed
from the stream. from the stream.
@ -715,10 +714,10 @@ added: v0.9.4
The `'end'` event is emitted when there is no more data to be consumed from The `'end'` event is emitted when there is no more data to be consumed from
the stream. the stream.
*Note*: The `'end'` event **will not be emitted** unless the data is The `'end'` event **will not be emitted** unless the data is completely
completely consumed. This can be accomplished by switching the stream into consumed. This can be accomplished by switching the stream into flowing mode,
flowing mode, or by calling [`stream.read()`][stream-read] repeatedly until or by calling [`stream.read()`][stream-read] repeatedly until all data has been
all data has been consumed. consumed.
```js ```js
const readable = getReadableStreamSomehow(); const readable = getReadableStreamSomehow();
@ -793,9 +792,9 @@ readable: null
end end
``` ```
*Note*: In general, the `readable.pipe()` and `'data'` event mechanisms are In general, the `readable.pipe()` and `'data'` event mechanisms are easier to
easier to understand than the `'readable'` event. understand than the `'readable'` event. However, handling `'readable'` might
However, handling `'readable'` might result in increased throughput. result in increased throughput.
##### readable.isPaused() ##### readable.isPaused()
<!-- YAML <!-- YAML
@ -897,9 +896,8 @@ processing, the Writable destination *is not closed* automatically. If an
error occurs, it will be necessary to *manually* close each stream in order error occurs, it will be necessary to *manually* close each stream in order
to prevent memory leaks. to prevent memory leaks.
*Note*: The [`process.stderr`][] and [`process.stdout`][] Writable streams are The [`process.stderr`][] and [`process.stdout`][] Writable streams are never
never closed until the Node.js process exits, regardless of the specified closed until the Node.js process exits, regardless of the specified options.
options.
##### readable.readableHighWaterMark ##### readable.readableHighWaterMark
<!-- YAML <!-- YAML
@ -953,11 +951,11 @@ A Readable stream in object mode will always return a single item from
a call to [`readable.read(size)`][stream-read], regardless of the value of the a call to [`readable.read(size)`][stream-read], regardless of the value of the
`size` argument. `size` argument.
*Note*: If the `readable.read()` method returns a chunk of data, a `'data'` If the `readable.read()` method returns a chunk of data, a `'data'` event will
event will also be emitted. also be emitted.
*Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][] Calling [`stream.read([size])`][stream-read] after the [`'end'`][] event has
event has been emitted will return `null`. No runtime error will be raised. been emitted will return `null`. No runtime error will be raised.
##### readable.readableLength ##### readable.readableLength
<!-- YAML <!-- YAML
@ -1070,8 +1068,8 @@ buffer. This is useful in certain situations where a stream is being consumed by
code that needs to "un-consume" some amount of data that it has optimistically code that needs to "un-consume" some amount of data that it has optimistically
pulled out of the source, so that the data can be passed on to some other party. pulled out of the source, so that the data can be passed on to some other party.
*Note*: The `stream.unshift(chunk)` method cannot be called after the The `stream.unshift(chunk)` method cannot be called after the [`'end'`][] event
[`'end'`][] event has been emitted or a runtime error will be thrown. has been emitted or a runtime error will be thrown.
Developers using `stream.unshift()` often should consider switching to Developers using `stream.unshift()` often should consider switching to
use of a [Transform][] stream instead. See the [API for Stream Implementers][] use of a [Transform][] stream instead. See the [API for Stream Implementers][]
@ -1113,14 +1111,14 @@ function parseHeader(stream, callback) {
} }
``` ```
*Note*: Unlike [`stream.push(chunk)`][stream-push], `stream.unshift(chunk)` Unlike [`stream.push(chunk)`][stream-push], `stream.unshift(chunk)` will not
will not end the reading process by resetting the internal reading state of the end the reading process by resetting the internal reading state of the stream.
stream. This can cause unexpected results if `readable.unshift()` is called This can cause unexpected results if `readable.unshift()` is called during a
during a read (i.e. from within a [`stream._read()`][stream-_read] read (i.e. from within a [`stream._read()`][stream-_read] implementation on a
implementation on a custom stream). Following the call to `readable.unshift()` custom stream). Following the call to `readable.unshift()` with an immediate
with an immediate [`stream.push('')`][stream-push] will reset the reading state [`stream.push('')`][stream-push] will reset the reading state appropriately,
appropriately, however it is best to simply avoid calling `readable.unshift()` however it is best to simply avoid calling `readable.unshift()` while in the
while in the process of performing a read. process of performing a read.
##### readable.wrap(stream) ##### readable.wrap(stream)
<!-- YAML <!-- YAML
@ -1329,10 +1327,10 @@ on the type of stream being created, as detailed in the chart below:
</tr> </tr>
</table> </table>
*Note*: The implementation code for a stream should *never* call the "public" The implementation code for a stream should *never* call the "public" methods
methods of a stream that are intended for use by consumers (as described in of a stream that are intended for use by consumers (as described in the
the [API for Stream Consumers][] section). Doing so may lead to adverse [API for Stream Consumers][] section). Doing so may lead to adverse side effects
side effects in application code consuming the stream. in application code consuming the stream.
### Simplified Construction ### Simplified Construction
<!-- YAML <!-- YAML
@ -1445,12 +1443,12 @@ All Writable stream implementations must provide a
[`writable._write()`][stream-_write] method to send data to the underlying [`writable._write()`][stream-_write] method to send data to the underlying
resource. resource.
*Note*: [Transform][] streams provide their own implementation of the [Transform][] streams provide their own implementation of the
[`writable._write()`][stream-_write]. [`writable._write()`][stream-_write].
*Note*: This function MUST NOT be called by application code directly. It This function MUST NOT be called by application code directly. It should be
should be implemented by child classes, and called by the internal Writable implemented by child classes, and called by the internal Writable class methods
class methods only. only.
The `callback` method must be called to signal either that the write completed The `callback` method must be called to signal either that the write completed
successfully or failed with an error. The first argument passed to the successfully or failed with an error. The first argument passed to the
@ -1482,9 +1480,9 @@ user programs.
* `callback` {Function} A callback function (optionally with an error * `callback` {Function} A callback function (optionally with an error
argument) to be invoked when processing is complete for the supplied chunks. argument) to be invoked when processing is complete for the supplied chunks.
*Note*: This function MUST NOT be called by application code directly. It This function MUST NOT be called by application code directly. It should be
should be implemented by child classes, and called by the internal Writable implemented by child classes, and called by the internal Writable class methods
class methods only. only.
The `writable._writev()` method may be implemented in addition to The `writable._writev()` method may be implemented in addition to
`writable._write()` in stream implementations that are capable of processing `writable._write()` in stream implementations that are capable of processing
@ -1688,9 +1686,9 @@ changes:
* `size` {number} Number of bytes to read asynchronously * `size` {number} Number of bytes to read asynchronously
*Note*: This function MUST NOT be called by application code directly. It This function MUST NOT be called by application code directly. It should be
should be implemented by child classes, and called by the internal Readable implemented by child classes, and called by the internal Readable class methods
class methods only. only.
All Readable stream implementations must provide an implementation of the All Readable stream implementations must provide an implementation of the
`readable._read()` method to fetch data from the underlying resource. `readable._read()` method to fetch data from the underlying resource.
@ -1702,10 +1700,10 @@ from the resource and pushing data until `readable.push()` returns `false`. Only
when `_read()` is called again after it has stopped should it resume pushing when `_read()` is called again after it has stopped should it resume pushing
additional data onto the queue. additional data onto the queue.
*Note*: Once the `readable._read()` method has been called, it will not be Once the `readable._read()` method has been called, it will not be called again
called again until the [`readable.push()`][stream-push] method is called. until the [`readable.push()`][stream-push] method is called. `readable._read()`
`readable._read()` is guaranteed to be called only once within a is guaranteed to be called only once within a synchronous execution, i.e. a
synchronous execution, i.e. a microtick. microtick.
The `size` argument is advisory. For implementations where a "read" is a The `size` argument is advisory. For implementations where a "read" is a
single operation that returns data can use the `size` argument to determine how single operation that returns data can use the `size` argument to determine how
@ -1794,7 +1792,8 @@ class SourceWrapper extends Readable {
} }
} }
``` ```
*Note*: The `readable.push()` method is intended be called only by Readable
The `readable.push()` method is intended be called only by Readable
Implementers, and only from within the `readable._read()` method. Implementers, and only from within the `readable._read()` method.
#### Errors While Reading #### Errors While Reading
@ -1860,10 +1859,10 @@ Because JavaScript does not have support for multiple inheritance, the
`stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed `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).
*Note*: The `stream.Duplex` class prototypically inherits from The `stream.Duplex` class prototypically inherits from `stream.Readable` and
`stream.Readable` and parasitically from `stream.Writable`, but `instanceof` parasitically from `stream.Writable`, but `instanceof` will work properly for
will work properly for both base classes due to overriding both base classes due to overriding [`Symbol.hasInstance`][] on
[`Symbol.hasInstance`][] on `stream.Writable`. `stream.Writable`.
Custom Duplex streams *must* call the `new stream.Duplex([options])` Custom Duplex streams *must* call the `new stream.Duplex([options])`
constructor and implement *both* the `readable._read()` and constructor and implement *both* the `readable._read()` and
@ -2023,11 +2022,11 @@ A [Transform][] stream is a [Duplex][] stream where the output is computed
in some way from the input. Examples include [zlib][] streams or [crypto][] in some way from the input. Examples include [zlib][] streams or [crypto][]
streams that compress, encrypt, or decrypt data. streams that compress, encrypt, or decrypt data.
*Note*: There is no requirement that the output be the same size as the input, There is no requirement that the output be the same size as the input, the same
the same number of chunks, or arrive at the same time. For example, a number of chunks, or arrive at the same time. For example, a Hash stream will
Hash stream will only ever have a single chunk of output which is only ever have a single chunk of output which is provided when the input is
provided when the input is ended. A `zlib` stream will produce output ended. A `zlib` stream will produce output that is either much smaller or much
that is either much smaller or much larger than its input. larger than its input.
The `stream.Transform` class is extended to implement a [Transform][] stream. The `stream.Transform` class is extended to implement a [Transform][] stream.
@ -2037,9 +2036,9 @@ methods. Custom Transform implementations *must* implement the
[`transform._transform()`][stream-_transform] method and *may* also implement [`transform._transform()`][stream-_transform] method and *may* also implement
the [`transform._flush()`][stream-_flush] method. the [`transform._flush()`][stream-_flush] method.
*Note*: Care must be taken when using Transform streams in that data written Care must be taken when using Transform streams in that data written to the
to the stream can cause the Writable side of the stream to become paused if stream can cause the Writable side of the stream to become paused if the output
the output on the Readable side is not consumed. on the Readable side is not consumed.
#### new stream.Transform([options]) #### new stream.Transform([options])
@ -2103,9 +2102,9 @@ after all data has been output, which occurs after the callback in
* `callback` {Function} A callback function (optionally with an error * `callback` {Function} A callback function (optionally with an error
argument and data) to be called when remaining data has been flushed. argument and data) to be called when remaining data has been flushed.
*Note*: This function MUST NOT be called by application code directly. It This function MUST NOT be called by application code directly. It should be
should be implemented by child classes, and called by the internal Readable implemented by child classes, and called by the internal Readable class methods
class methods only. only.
In some cases, a transform operation may need to emit an additional bit of In some cases, a transform operation may need to emit an additional bit of
data at the end of the stream. For example, a `zlib` compression stream will data at the end of the stream. For example, a `zlib` compression stream will
@ -2138,9 +2137,9 @@ user programs.
argument and data) to be called after the supplied `chunk` has been argument and data) to be called after the supplied `chunk` has been
processed. processed.
*Note*: This function MUST NOT be called by application code directly. It This function MUST NOT be called by application code directly. It should be
should be implemented by child classes, and called by the internal Readable implemented by child classes, and called by the internal Readable class methods
class methods only. only.
All Transform stream implementations must provide a `_transform()` All Transform stream implementations must provide a `_transform()`
method to accept input and produce output. The `transform._transform()` method to accept input and produce output. The `transform._transform()`

20
doc/api/timers.md
View File

@ -32,9 +32,8 @@ 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 `Immediate` is active. Calling `immediate.ref()` multiple times will have no
effect. effect.
*Note*: By default, all `Immediate` objects are "ref'd", making it normally By default, all `Immediate` objects are "ref'd", making it normally unnecessary
unnecessary to call `immediate.ref()` unless `immediate.unref()` had been called to call `immediate.ref()` unless `immediate.unref()` had been called previously.
previously.
Returns a reference to the `Immediate`. Returns a reference to the `Immediate`.
@ -70,9 +69,8 @@ added: v0.9.1
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. `Timeout` is active. Calling `timeout.ref()` multiple times will have no effect.
*Note*: By default, all `Timeout` objects are "ref'd", making it normally By default, all `Timeout` objects are "ref'd", making it normally unnecessary
unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called to call `timeout.ref()` unless `timeout.unref()` had been called previously.
previously.
Returns a reference to the `Timeout`. Returns a reference to the `Timeout`.
@ -86,8 +84,8 @@ to remain active. If there is no other activity keeping the event loop running,
the process may exit before the `Timeout` object's callback is invoked. Calling the process may exit before the `Timeout` object's callback is invoked. Calling
`timeout.unref()` multiple times will have no effect. `timeout.unref()` multiple times will have no effect.
*Note*: Calling `timeout.unref()` creates an internal timer that will wake the Calling `timeout.unref()` creates an internal timer that will wake the Node.js
Node.js event loop. Creating too many of these can adversely impact performance event loop. Creating too many of these can adversely impact performance
of the Node.js application. of the Node.js application.
Returns a reference to the `Timeout`. Returns a reference to the `Timeout`.
@ -119,7 +117,7 @@ next event loop iteration.
If `callback` is not a function, a [`TypeError`][] will be thrown. If `callback` is not a function, a [`TypeError`][] will be thrown.
*Note*: This method has a custom variant for promises that is available using This method has a custom variant for promises that is available using
[`util.promisify()`][]: [`util.promisify()`][]:
```js ```js
@ -176,12 +174,12 @@ Node.js makes no guarantees about the exact timing of when callbacks will fire,
nor of their ordering. The callback will be called as close as possible to the nor of their ordering. The callback will be called as close as possible to the
time specified. time specified.
*Note*: When `delay` is larger than `2147483647` or less than `1`, the `delay` When `delay` is larger than `2147483647` or less than `1`, the `delay`
will be set to `1`. will be set to `1`.
If `callback` is not a function, a [`TypeError`][] will be thrown. If `callback` is not a function, a [`TypeError`][] will be thrown.
*Note*: This method has a custom variant for promises that is available using This method has a custom variant for promises that is available using
[`util.promisify()`][]: [`util.promisify()`][]:
```js ```js

84
doc/api/tls.md
View File

@ -117,7 +117,7 @@ handshake extensions:
* SNI - Allows the use of one TLS server for multiple hostnames with different * SNI - Allows the use of one TLS server for multiple hostnames with different
SSL certificates. SSL certificates.
*Note*: Use of ALPN is recommended over NPN. The NPN extension has never been Use of ALPN is recommended over NPN. The NPN extension has never been
formally defined or documented and generally not recommended for use. formally defined or documented and generally not recommended for use.
### Client-initiated renegotiation attack mitigation ### Client-initiated renegotiation attack mitigation
@ -138,7 +138,7 @@ threshold is exceeded. The limits are configurable:
* `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window * `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window
in seconds. Defaults to `600` (10 minutes). in seconds. Defaults to `600` (10 minutes).
*Note*: The default renegotiation limits should not be modified without a full The default renegotiation limits should not be modified without a full
understanding of the implications and risks. understanding of the implications and risks.
To test the renegotiation limits on a server, connect to it using the OpenSSL To test the renegotiation limits on a server, connect to it using the OpenSSL
@ -189,7 +189,7 @@ in [`tls.createServer()`], [`tls.connect()`], and when creating new
Consult [OpenSSL cipher list format documentation][] for details on the format. Consult [OpenSSL cipher list format documentation][] for details on the format.
*Note*: The default cipher suite included within Node.js has been carefully The default cipher suite included within Node.js has been carefully
selected to reflect current security best practices and risk mitigation. selected to reflect current security best practices and risk mitigation.
Changing the default cipher suite can have a significant impact on the security Changing the default cipher suite can have a significant impact on the security
of an application. The `--tls-cipher-list` switch and `ciphers` option should by of an application. The `--tls-cipher-list` switch and `ciphers` option should by
@ -230,8 +230,8 @@ three arguments when called:
* `callback` {Function} A callback function taking no arguments that must be * `callback` {Function} A callback function taking no arguments that must be
invoked in order for data to be sent or received over the secure connection. invoked in order for data to be sent or received over the secure connection.
*Note*: Listening for this event will have an effect only on connections Listening for this event will have an effect only on connections established
established after the addition of the event listener. after the addition of the event listener.
### Event: 'OCSPRequest' ### Event: 'OCSPRequest'
<!-- YAML <!-- YAML
@ -271,14 +271,14 @@ The typical flow of an OCSP Request is as follows:
5. Client validates the response and either destroys the socket or performs a 5. Client validates the response and either destroys the socket or performs a
handshake. handshake.
*Note*: The `issuer` can be `null` if the certificate is either self-signed or The `issuer` can be `null` if the certificate is either self-signed or the
the issuer is not in the root certificates list. (An issuer may be provided issuer is not in the root certificates list. (An issuer may be provided
via the `ca` option when establishing the TLS connection.) via the `ca` option when establishing the TLS connection.)
*Note*: Listening for this event will have an effect only on connections Listening for this event will have an effect only on connections established
established after the addition of the event listener. after the addition of the event listener.
*Note*: An npm module like [asn1.js] may be used to parse the certificates. An npm module like [asn1.js] may be used to parse the certificates.
### Event: 'resumeSession' ### Event: 'resumeSession'
<!-- YAML <!-- YAML
@ -299,8 +299,8 @@ the session cannot be resumed (i.e., doesn't exist in storage) the callback may
be invoked as `callback(null, null)`. Calling `callback(err)` will terminate the be invoked as `callback(null, null)`. Calling `callback(err)` will terminate the
incoming connection and destroy the socket. incoming connection and destroy the socket.
*Note*: Listening for this event will have an effect only on connections Listening for this event will have an effect only on connections established
established after the addition of the event listener. after the addition of the event listener.
The following illustrates resuming a TLS session: The following illustrates resuming a TLS session:
@ -423,13 +423,12 @@ added: v3.0.0
Updates the keys for encryption/decryption of the [TLS Session Tickets][]. Updates the keys for encryption/decryption of the [TLS Session Tickets][].
*Note*: The key's `Buffer` should be 48 bytes long. See `ticketKeys` option in The key's `Buffer` should be 48 bytes long. See `ticketKeys` option in
[tls.createServer](#tls_tls_createserver_options_secureconnectionlistener) for [tls.createServer](#tls_tls_createserver_options_secureconnectionlistener) for
more information on how it is used. more information on how it is used.
*Note*: Changes to the ticket keys are effective only for future server Changes to the ticket keys are effective only for future server connections.
connections. Existing or currently pending server connections will use the Existing or currently pending server connections will use the previous keys.
previous keys.
## Class: tls.TLSSocket ## Class: tls.TLSSocket
@ -442,7 +441,7 @@ encryption of written data and all required TLS negotiation.
Instances of `tls.TLSSocket` implement the duplex [Stream][] interface. Instances of `tls.TLSSocket` implement the duplex [Stream][] interface.
*Note*: Methods that return TLS connection metadata (e.g. Methods that return TLS connection metadata (e.g.
[`tls.TLSSocket.getPeerCertificate()`][] will only return data while the [`tls.TLSSocket.getPeerCertificate()`][] will only return data while the
connection is open. connection is open.
@ -664,8 +663,8 @@ added: v0.11.4
Returns the TLS session ticket or `undefined` if no session was negotiated. Returns the TLS session ticket or `undefined` if no session was negotiated.
*Note*: This only works with client TLS sockets. Useful only for debugging, This only works with client TLS sockets. Useful only for debugging, for session
for session reuse provide `session` option to [`tls.connect()`][]. reuse provide `session` option to [`tls.connect()`][].
### tlsSocket.localAddress ### tlsSocket.localAddress
<!-- YAML <!-- YAML
@ -721,11 +720,11 @@ The `tlsSocket.renegotiate()` method initiates a TLS renegotiation process.
Upon completion, the `callback` function will be passed a single argument Upon completion, the `callback` function will be passed a single argument
that is either an `Error` (if the request failed) or `null`. that is either an `Error` (if the request failed) or `null`.
*Note*: This method can be used to request a peer's certificate after the This method can be used to request a peer's certificate after the secure
secure connection has been established. connection has been established.
*Note*: When running as the server, the socket will be destroyed with an error When running as the server, the socket will be destroyed with an error after
after `handshakeTimeout` timeout. `handshakeTimeout` timeout.
### tlsSocket.setMaxSendFragment(size) ### tlsSocket.setMaxSendFragment(size)
<!-- YAML <!-- YAML
@ -759,15 +758,16 @@ Verifies the certificate `cert` is issued to host `host`.
Returns {Error} object, populating it with the reason, host, and cert on Returns {Error} object, populating it with the reason, host, and cert on
failure. On success, returns {undefined}. failure. On success, returns {undefined}.
*Note*: This function can be overwritten by providing alternative function This function can be overwritten by providing alternative function as part of
as part of the `options.checkServerIdentity` option passed to `tls.connect()`. the `options.checkServerIdentity` option passed to `tls.connect()`. The
The overwriting function can call `tls.checkServerIdentity()` of course, to augment overwriting function can call `tls.checkServerIdentity()` of course, to augment
the checks done with additional verification. the checks done with additional verification.
*Note*: This function is only called if the certificate passed all other checks, such as This function is only called if the certificate passed all other checks, such as
being issued by trusted CA (`options.ca`). being issued by trusted CA (`options.ca`).
The cert object contains the parsed certificate and will have a structure similar to: The cert object contains the parsed certificate and will have a structure
similar to:
```text ```text
{ subject: { subject:
@ -937,8 +937,7 @@ added: v0.11.3
Same as [`tls.connect()`][] except that `path` can be provided Same as [`tls.connect()`][] except that `path` can be provided
as an argument instead of an option. as an argument instead of an option.
*Note*: A path option, if specified, will take precedence over the path A path option, if specified, will take precedence over the path argument.
argument.
## tls.connect(port[, host][, options][, callback]) ## tls.connect(port[, host][, options][, callback])
<!-- YAML <!-- YAML
@ -953,8 +952,8 @@ added: v0.11.3
Same as [`tls.connect()`][] except that `port` and `host` can be provided Same as [`tls.connect()`][] except that `port` and `host` can be provided
as arguments instead of options. as arguments instead of options.
*Note*: A port or host option, if specified, will take precedence over any A port or host option, if specified, will take precedence over any port or host
port or host argument. argument.
## tls.createSecureContext(options) ## tls.createSecureContext(options)
@ -1052,15 +1051,12 @@ changes:
* `sessionIdContext` {string} Optional opaque identifier used by servers to * `sessionIdContext` {string} Optional opaque identifier used by servers to
ensure session state is not shared between applications. Unused by clients. ensure session state is not shared between applications. Unused by clients.
*Note*: [`tls.createServer()`][] sets the default value of the `honorCipherOrder` option
to `true`, other APIs that create secure contexts leave it unset.
* [`tls.createServer()`][] sets the default value of the [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value generated
`honorCipherOrder` option to `true`, other APIs that create secure contexts from `process.argv` as the default value of the `sessionIdContext` option, other
leave it unset. APIs that create secure contexts have no default value.
* [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value
generated from `process.argv` as the default value of the `sessionIdContext`
option, other APIs that create secure contexts have no default value.
The `tls.createSecureContext()` method creates a credentials object. The `tls.createSecureContext()` method creates a credentials object.
@ -1137,8 +1133,8 @@ changes:
Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is
automatically set as a listener for the [`'secureConnection'`][] event. automatically set as a listener for the [`'secureConnection'`][] event.
*Note*: The `ticketKeys` options is automatically shared between `cluster` The `ticketKeys` options is automatically shared between `cluster` module
module workers. workers.
The following illustrates a simple echo server: The following illustrates a simple echo server:
@ -1314,9 +1310,9 @@ stream.
`tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and `tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and
`encrypted` stream properties. `encrypted` stream properties.
*Note*: `cleartext` has the same API as [`tls.TLSSocket`][]. Using `cleartext` has the same API as [`tls.TLSSocket`][].
*Note*: The `tls.createSecurePair()` method is now deprecated in favor of The `tls.createSecurePair()` method is now deprecated in favor of
`tls.TLSSocket()`. For example, the code: `tls.TLSSocket()`. For example, the code:
```js ```js

18
doc/api/url.md
View File

@ -21,8 +21,8 @@ The `url` module provides two APIs for working with URLs: a legacy API that is
Node.js specific, and a newer API that implements the same Node.js specific, and a newer API that implements the same
[WHATWG URL Standard][] used by web browsers. [WHATWG URL Standard][] used by web browsers.
*Note*: While the Legacy API has not been deprecated, it is maintained solely While the Legacy API has not been deprecated, it is maintained solely for
for backwards compatibility with existing applications. New application code backwards compatibility with existing applications. New application code
should use the WHATWG API. should use the WHATWG API.
A comparison between the WHATWG and Legacy APIs is provided below. Above the URL A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
@ -30,7 +30,7 @@ A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
an object returned by the legacy `url.parse()` are shown. Below it are an object returned by the legacy `url.parse()` are shown. Below it are
properties of a WHATWG `URL` object. properties of a WHATWG `URL` object.
*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not WHATWG URL's `origin` property includes `protocol` and `host`, but not
`username` or `password`. `username` or `password`.
```txt ```txt
@ -84,7 +84,7 @@ Browser-compatible `URL` class, implemented by following the WHATWG URL
Standard. [Examples of parsed URLs][] may be found in the Standard itself. Standard. [Examples of parsed URLs][] may be found in the Standard itself.
The `URL` class is also available on the global object. The `URL` class is also available on the global object.
*Note*: In accordance with browser conventions, all properties of `URL` objects In accordance with browser conventions, all properties of `URL` objects
are implemented as getters and setters on the class prototype, rather than as are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself. Thus, unlike [legacy urlObject][]s, using data properties on the object itself. Thus, unlike [legacy urlObject][]s, using
the `delete` keyword on any properties of `URL` objects (e.g. `delete the `delete` keyword on any properties of `URL` objects (e.g. `delete
@ -122,8 +122,8 @@ const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba/ // https://xn--6qqa088eba/
``` ```
*Note*: This feature is only available if the `node` executable was compiled This feature is only available if the `node` executable was compiled with
with [ICU][] enabled. If not, the domain names are passed through unchanged. [ICU][] enabled. If not, the domain names are passed through unchanged.
#### url.hash #### url.hash
@ -515,9 +515,9 @@ added: v7.10.0
Instantiate a new `URLSearchParams` object with a query hash map. The key and Instantiate a new `URLSearchParams` object with a query hash map. The key and
value of each property of `obj` are always coerced to strings. value of each property of `obj` are always coerced to strings.
*Note*: Unlike [`querystring`][] module, duplicate keys in the form of array Unlike [`querystring`][] module, duplicate keys in the form of array values are
values are not allowed. Arrays are stringified using [`array.toString()`][], not allowed. Arrays are stringified using [`array.toString()`][], which simply
which simply joins all array elements with commas. joins all array elements with commas.
```js ```js
const params = new URLSearchParams({ const params = new URLSearchParams({

12
doc/api/util.md
View File

@ -48,13 +48,11 @@ Will print:
hello world hello world
``` ```
*Note*: The callback is executed asynchronously, and will have a limited stack trace.
* The callback is executed asynchronously, and will have a limited stack trace.
If the callback throws, the process will emit an [`'uncaughtException'`][] If the callback throws, the process will emit an [`'uncaughtException'`][]
event, and if not handled will exit. event, and if not handled will exit.
* Since `null` has a special meaning as the first argument to a callback, if a Since `null` has a special meaning as the first argument to a callback, if a
wrapped function rejects a `Promise` with a falsy value as a reason, the value wrapped function rejects a `Promise` with a falsy value as a reason, the value
is wrapped in an `Error` with the original value stored in a field named is wrapped in an `Error` with the original value stored in a field named
`reason`. `reason`.
@ -285,8 +283,8 @@ changes:
description: The `constructor` parameter can refer to an ES6 class now. description: The `constructor` parameter can refer to an ES6 class now.
--> -->
*Note*: Usage of `util.inherits()` is discouraged. Please use the ES6 `class` Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and
and `extends` keywords to get language level inheritance support. Also note `extends` keywords to get language level inheritance support. Also note
that the two styles are [semantically incompatible][]. that the two styles are [semantically incompatible][].
* `constructor` {Function} * `constructor` {Function}
@ -812,7 +810,7 @@ with ICU and using the full ICU data (see [Internationalization][]).
| `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` | | `'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'` | | `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` |
*Note*: The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][] The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][]
is not supported. is not supported.
### new TextDecoder([encoding[, options]]) ### new TextDecoder([encoding[, options]])

4
doc/api/v8.md
View File

@ -9,7 +9,7 @@ built into the Node.js binary. It can be accessed using:
const v8 = require('v8'); const v8 = require('v8');
``` ```
*Note*: The APIs and implementation are subject to change at any time. The APIs and implementation are subject to change at any time.
## v8.cachedDataVersionTag() ## v8.cachedDataVersionTag()
<!-- YAML <!-- YAML
@ -165,7 +165,7 @@ The serialization API provides means of serializing JavaScript values in a way
that is compatible with the [HTML structured clone algorithm][]. that is compatible with the [HTML structured clone algorithm][].
The format is backward-compatible (i.e. safe to store to disk). The format is backward-compatible (i.e. safe to store to disk).
*Note*: This API is under development, and changes (including incompatible This API is under development, and changes (including incompatible
changes to the API or wire format) may occur until this warning is removed. changes to the API or wire format) may occur until this warning is removed.
### v8.serialize(value) ### v8.serialize(value)

18
doc/api/vm.md
View File

@ -40,8 +40,8 @@ console.log(sandbox.y); // 17
console.log(x); // 1; y is not defined. console.log(x); // 1; y is not defined.
``` ```
*Note*: The vm module is not a security mechanism. **The vm module is not a security mechanism. Do not use it to run untrusted
**Do not use it to run untrusted code**. code**.
## Class: vm.Module ## Class: vm.Module
<!-- YAML <!-- YAML
@ -68,7 +68,7 @@ Using a `vm.Module` object requires four distinct steps: creation/parsing,
linking, instantiation, and evaluation. These four steps are illustrated in the linking, instantiation, and evaluation. These four steps are illustrated in the
following example. following example.
*Note*: This implementation lies at a lower level than the [ECMAScript Module This implementation lies at a lower level than the [ECMAScript Module
loader][]. There is also currently no way to interact with the Loader, though loader][]. There is also currently no way to interact with the Loader, though
support is planned. support is planned.
@ -191,7 +191,7 @@ If the `module.status` is `'errored'`, this property contains the exception thro
by the module during evaluation. If the status is anything else, accessing this by the module during evaluation. If the status is anything else, accessing this
property will result in a thrown exception. property will result in a thrown exception.
*Note*: `undefined` cannot be used for cases where there is not a thrown The value `undefined` cannot be used for cases where there is not a thrown
exception due to possible ambiguity with `throw undefined;`. exception due to possible ambiguity with `throw undefined;`.
Corresponds to the [[EvaluationError]] field of [Source Text Module Record][]s Corresponds to the [[EvaluationError]] field of [Source Text Module Record][]s
@ -465,9 +465,9 @@ console.log(util.inspect(sandbox));
// { animal: 'cat', count: 12, name: 'kitty' } // { animal: 'cat', count: 12, name: 'kitty' }
``` ```
*Note*: Using the `timeout` or `breakOnSigint` options will result in new Using the `timeout` or `breakOnSigint` options will result in new event loops
event loops and corresponding threads being started, which have a non-zero and corresponding threads being started, which have a non-zero performance
performance overhead. overhead.
### script.runInNewContext([sandbox[, options]]) ### script.runInNewContext([sandbox[, options]])
<!-- YAML <!-- YAML
@ -803,8 +803,8 @@ const code = `
vm.runInThisContext(code)(require); vm.runInThisContext(code)(require);
``` ```
*Note*: The `require()` in the above case shares the state with the context it The `require()` in the above case shares the state with the context it is
is passed from. This may introduce risks when untrusted code is executed, e.g. passed from. This may introduce risks when untrusted code is executed, e.g.
altering objects in the context in unwanted ways. altering objects in the context in unwanted ways.
## What does it mean to "contextify" an object? ## What does it mean to "contextify" an object?

17
doc/api/zlib.md
View File

@ -63,10 +63,10 @@ the compression encodings accepted by the client. The [`Content-Encoding`][]
header is used to identify the compression encodings actually applied to a header is used to identify the compression encodings actually applied to a
message. message.
*Note*: the examples given below are drastically simplified to show The examples given below are drastically simplified to show the basic concept.
the basic concept. Using `zlib` encoding can be expensive, and the results Using `zlib` encoding can be expensive, and the results ought to be cached.
ought to be cached. See [Memory Usage Tuning][] for more information See [Memory Usage Tuning][] for more information on the speed/memory/compression
on the speed/memory/compression tradeoffs involved in `zlib` usage. tradeoffs involved in `zlib` usage.
```js ```js
// client request example // client request example
@ -238,10 +238,9 @@ not surprising. This section is taken almost directly from the
[zlib documentation][]. See <https://zlib.net/manual.html#Constants> for more [zlib documentation][]. See <https://zlib.net/manual.html#Constants> for more
details. details.
*Note*: Previously, the constants were available directly from Previously, the constants were available directly from `require('zlib')`, for
`require('zlib')`, for instance `zlib.Z_NO_FLUSH`. Accessing the constants instance `zlib.Z_NO_FLUSH`. Accessing the constants directly from the module is
directly from the module is currently still possible but should be considered currently still possible but is deprecated.
deprecated.
Allowed flush values. Allowed flush values.
@ -468,7 +467,7 @@ added: v0.5.8
Creates and returns a new [DeflateRaw][] object with the given [options][]. Creates and returns a new [DeflateRaw][] object with the given [options][].
*Note*: An upgrade of zlib from 1.2.8 to 1.2.11 changed behavior when windowBits An upgrade of zlib from 1.2.8 to 1.2.11 changed behavior when windowBits
is set to 8 for raw deflate streams. zlib would automatically set windowBits is set to 8 for raw deflate streams. zlib would automatically set windowBits
to 9 if was initially set to 8. Newer versions of zlib will throw an exception, to 9 if was initially set to 8. Newer versions of zlib will throw an exception,
so Node.js restored the original behavior of upgrading a value of 8 to 9, so Node.js restored the original behavior of upgrading a value of 8 to 9,