diff options
| author | Rich Trott <rtrott@gmail.com> | 2020-06-15 00:49:34 +0300 |
|---|---|---|
| committer | Myles Borins <mylesborins@github.com> | 2020-07-14 18:22:34 +0300 |
| commit | 3b268094ccc60703987060434829e24bb4043f6a (patch) | |
| tree | 97286bb156ac7d83e853cad3bee4c0265346eae2 /doc | |
| parent | 8b4d0967ffa1d53dbceae1736d67b418ae479102 (diff) | |
doc: use sentence-case for headings in docs
Backport-PR-URL: https://github.com/nodejs/node/pull/33961
PR-URL: https://github.com/nodejs/node/pull/33889
Refs: https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings
Refs: https://docs.microsoft.com/en-us/style-guide/capitalization
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'doc')
46 files changed, 346 insertions, 342 deletions
diff --git a/doc/api/addons.md b/doc/api/addons.md index 34f49d9a24a..9a2b6d1a536 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -1,4 +1,4 @@ -# C++ Addons +# C++ addons <!--introduced_in=v0.10.0--> <!-- type=misc --> @@ -395,7 +395,7 @@ only the symbols exported by Node.js will be available. source image. Using this option, the Addon will have access to the full set of dependencies. -### Loading Addons using `require()` +### Loading addons using `require()` The filename extension of the compiled Addon binary is `.node` (as opposed to `.dll` or `.so`). The [`require()`][require] function is written to look for @@ -410,7 +410,7 @@ there is a file `addon.js` in the same directory as the binary `addon.node`, then [`require('addon')`][require] will give precedence to the `addon.js` file and load it instead. -## Native Abstractions for Node.js +## Native abstractions for Node.js Each of the examples illustrated in this document make direct use of the Node.js and V8 APIs for implementing Addons. The V8 API can, and has, changed diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index cdac6287f4d..49aac3dc445 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -1,4 +1,4 @@ -# Async Hooks +# Async hooks <!--introduced_in=v8.1.0--> @@ -127,7 +127,7 @@ class MyAddedCallbacks extends MyAsyncCallbacks { const asyncHook = async_hooks.createHook(new MyAddedCallbacks()); ``` -##### Error Handling +##### Error handling If any `AsyncHook` callbacks throw, the application will print the stack trace and exit. The exit path does follow that of an uncaught exception, but @@ -201,7 +201,7 @@ be called again until enabled. For API consistency `disable()` also returns the `AsyncHook` instance. -#### Hook Callbacks +#### Hook callbacks Key events in the lifetime of asynchronous events have been categorized into four areas: instantiation, before/after the callback is called, and when the @@ -626,7 +626,7 @@ only on chained promises. That means promises not created by `then()`/`catch()` will not have the `before` and `after` callbacks fired on them. For more details see the details of the V8 [PromiseHooks][] API. -## JavaScript Embedder API +## JavaScript embedder API Library developers that handle their own asynchronous resources performing tasks like I/O, connection pooling, or managing callback queues may use the diff --git a/doc/api/buffer.md b/doc/api/buffer.md index b43b7eded24..2df4fe79508 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -53,7 +53,7 @@ const buf6 = Buffer.from('tést'); const buf7 = Buffer.from('tést', 'latin1'); ``` -## Buffers and Character Encodings +## Buffers and character encodings <!-- YAML changes: - version: v6.4.0 @@ -2640,7 +2640,7 @@ deprecated: v6.0.0 See [`Buffer.allocUnsafeSlow()`][]. -## Buffer Constants +## Buffer constants <!-- YAML added: v8.2.0 --> diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 1c1f736ed1b..779542c00fe 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,4 +1,4 @@ -# Child Process +# Child process <!--introduced_in=v0.10.0--> @@ -70,7 +70,7 @@ For certain use cases, such as automating shell scripts, the the synchronous methods can have significant impact on performance due to stalling the event loop while spawned processes complete. -## Asynchronous Process Creation +## Asynchronous process creation The [`child_process.spawn()`][], [`child_process.fork()`][], [`child_process.exec()`][], and [`child_process.execFile()`][] methods all follow the idiomatic asynchronous @@ -153,7 +153,7 @@ changes: * `env` {Object} Environment key-value pairs. **Default:** `process.env`. * `encoding` {string} **Default:** `'utf8'` * `shell` {string} Shell to execute the command with. See - [Shell Requirements][] and [Default Windows Shell][]. **Default:** + [Shell requirements][] and [Default Windows shell][]. **Default:** `'/bin/sh'` on Unix, `process.env.ComSpec` on Windows. * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or @@ -270,8 +270,8 @@ changes: done on Windows. Ignored on Unix. **Default:** `false`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * `callback` {Function} Called with the output when process terminates. * `error` {Error} * `stdout` {string|Buffer} @@ -355,7 +355,7 @@ changes: **Default:** `process.execArgv`. * `serialization` {string} Specify the kind of serialization used for sending messages between processes. Possible values are `'json'` and `'advanced'`. - See [Advanced Serialization][] for more details. **Default:** `'json'`. + See [Advanced serialization][] for more details. **Default:** `'json'`. * `silent` {boolean} If `true`, stdin, stdout, and stderr of the child will be piped to the parent, otherwise they will be inherited from the parent, see the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s @@ -434,11 +434,11 @@ changes: * `gid` {number} Sets the group identity of the process (see setgid(2)). * `serialization` {string} Specify the kind of serialization used for sending messages between processes. Possible values are `'json'` and `'advanced'`. - See [Advanced Serialization][] for more details. **Default:** `'json'`. + See [Advanced serialization][] for more details. **Default:** `'json'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * `windowsVerbatimArguments` {boolean} No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to `true` automatically when `shell` is specified and is CMD. **Default:** `false`. @@ -699,7 +699,7 @@ see [V8 issue 7381](https://bugs.chromium.org/p/v8/issues/detail?id=7381). See also: [`child_process.exec()`][] and [`child_process.fork()`][]. -## Synchronous Process Creation +## Synchronous process creation The [`child_process.spawnSync()`][], [`child_process.execSync()`][], and [`child_process.execFileSync()`][] methods are synchronous and will block the @@ -755,8 +755,8 @@ changes: normally be created on Windows systems. **Default:** `false`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * Returns: {Buffer|string} The stdout from the command. The `child_process.execFileSync()` method is generally identical to @@ -804,7 +804,7 @@ changes: **Default:** `'pipe'`. * `env` {Object} Environment key-value pairs. **Default:** `process.env`. * `shell` {string} Shell to execute the command with. See - [Shell Requirements][] and [Default Windows Shell][]. **Default:** + [Shell requirements][] and [Default Windows shell][]. **Default:** `'/bin/sh'` on Unix, `process.env.ComSpec` on Windows. * `uid` {number} Sets the user identity of the process. (See setuid(2)). * `gid` {number} Sets the group identity of the process. (See setgid(2)). @@ -884,8 +884,8 @@ changes: **Default:** `'buffer'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * `windowsVerbatimArguments` {boolean} No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to `true` automatically when `shell` is specified and is CMD. **Default:** `false`. @@ -1025,7 +1025,7 @@ message might not be the same as what is originally sent. If the `serialization` option was set to `'advanced'` used when spawning the child process, the `message` argument can contain data that JSON is not able to represent. -See [Advanced Serialization][] for more details. +See [Advanced serialization][] for more details. ### `subprocess.channel` <!-- YAML @@ -1544,13 +1544,13 @@ This impacts output that includes multibyte character encodings such as UTF-8 or UTF-16. For instance, `console.log('中文测试')` will send 13 UTF-8 encoded bytes to `stdout` although there are only 4 characters. -## Shell Requirements +## Shell requirements The shell should understand the `-c` switch. If the shell is `'cmd.exe'`, it should understand the `/d /s /c` switches and command line parsing should be compatible. -## Default Windows Shell +## Default Windows shell Although Microsoft specifies `%COMSPEC%` must contain the path to `'cmd.exe'` in the root environment, child processes are not always subject to @@ -1558,7 +1558,7 @@ the same requirement. Thus, in `child_process` functions where a shell can be spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is unavailable. -## Advanced Serialization +## Advanced serialization <!-- YAML added: - v13.2.0 @@ -1579,7 +1579,7 @@ Therefore, this feature requires opting in by setting the `serialization` option to `'advanced'` when calling [`child_process.spawn()`][] or [`child_process.fork()`][]. -[Advanced Serialization]: #child_process_advanced_serialization +[Advanced serialization]: #child_process_advanced_serialization [`'disconnect'`]: process.html#process_event_disconnect [`'error'`]: #child_process_event_error [`'exit'`]: #child_process_event_exit @@ -1612,8 +1612,8 @@ or [`child_process.fork()`][]. [`subprocess.stdio`]: #child_process_subprocess_stdio [`subprocess.stdout`]: #child_process_subprocess_stdout [`util.promisify()`]: util.html#util_util_promisify_original -[Default Windows Shell]: #child_process_default_windows_shell +[Default Windows shell]: #child_process_default_windows_shell [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm -[Shell Requirements]: #child_process_shell_requirements +[Shell requirements]: #child_process_shell_requirements [synchronous counterparts]: #child_process_synchronous_process_creation [v8.serdes]: v8.html#v8_serialization_api diff --git a/doc/api/cli.md b/doc/api/cli.md index d8c1c9651b1..1d04b01a0b5 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1,4 +1,4 @@ -# Command Line Options +# Command line options <!--introduced_in=v5.9.1--> <!--type=misc--> @@ -160,7 +160,7 @@ added: v12.12.0 > Stability: 1 - Experimental -Enable experimental Source Map V3 support for stack traces. +Enable experimental Source Map v3 support for stack traces. Currently, overriding `Error.prepareStackTrace` is ignored when the `--enable-source-maps` flag is set. @@ -1099,7 +1099,7 @@ added: v0.1.3 Print node's version. -## Environment Variables +## Environment variables ### `NODE_DEBUG=module[,…]` <!-- YAML @@ -1375,7 +1375,7 @@ easier to instrument applications that call the `child_process.spawn()` family of functions. `NODE_V8_COVERAGE` can be set to an empty string, to prevent propagation. -#### Coverage Output +#### Coverage output Coverage is output as an array of [ScriptCoverage][] objects on the top-level key `result`: @@ -1392,16 +1392,16 @@ key `result`: } ``` -#### Source Map Cache +#### Source map cache > Stability: 1 - Experimental -If found, Source Map data is appended to the top-level key `source-map-cache` +If found, source map data is appended to the top-level key `source-map-cache` on the JSON coverage object. `source-map-cache` is an object with keys representing the files source maps were extracted from, and values which include the raw source-map URL -(in the key `url`), the parsed Source Map V3 information (in the key `data`), +(in the key `url`), the parsed Source Map v3 information (in the key `data`), and the line lengths of the source file (in the key `lineLengths`). ```json @@ -1510,7 +1510,7 @@ options are of interest only to V8 developers. Despite this, there is a small set of V8 options that are widely applicable to Node.js, and they are documented here: -### `--max-old-space-size=SIZE` (in Mbytes) +### `--max-old-space-size=SIZE` (in megabytes) Sets the max memory size of V8's old memory section. As memory consumption approaches the limit, V8 will spend more time on diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 62412da0bf5..3c67d4cf1ed 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -52,7 +52,7 @@ Worker 5644 started On Windows, it is not yet possible to set up a named pipe server in a worker. -## How It Works +## How it works <!--type=misc--> @@ -753,7 +753,7 @@ changes: `undefined` (inherits from parent process). * `serialization` {string} Specify the kind of serialization used for sending messages between processes. Possible values are `'json'` and `'advanced'`. - See [Advanced Serialization for `child_process`][] for more details. + See [Advanced serialization for `child_process`][] for more details. **Default:** `false`. * `silent` {boolean} Whether or not to send output to parent's stdio. **Default:** `false`. @@ -883,5 +883,5 @@ socket.on('data', (id) => { [`process` event: `'message'`]: process.html#process_event_message [`server.close()`]: net.html#net_event_close [`worker.exitedAfterDisconnect`]: #cluster_worker_exitedafterdisconnect -[Advanced Serialization for `child_process`]: child_process.html#child_process_advanced_serialization +[Advanced serialization for `child_process`]: child_process.html#child_process_advanced_serialization [Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e45d41586cf..016a60802c4 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1585,7 +1585,7 @@ added: v6.3.0 * Returns: {Object} An object containing commonly used constants for crypto and security related operations. The specific constants currently defined are - described in [Crypto Constants][]. + described in [Crypto constants][]. ### `crypto.DEFAULT_ENCODING` <!-- YAML @@ -3045,7 +3045,7 @@ key may be passed for `key`. ## Notes -### Legacy Streams API (prior to Node.js 0.10) +### Legacy streams API (prior to Node.js 0.10) The Crypto module was added to Node.js before there was the concept of a unified Stream API, and before there were [`Buffer`][] objects for handling @@ -3056,7 +3056,7 @@ and returned `'latin1'` encoded strings by default rather than `Buffer`s. This default was changed after Node.js v0.8 to use [`Buffer`][] objects by default instead. -### Recent ECDH Changes +### Recent ECDH changes Usage of `ECDH` with non-dynamically generated key pairs has been simplified. Now, [`ecdh.setPrivateKey()`][] can be called with a preselected private key @@ -3164,12 +3164,12 @@ try { console.log(receivedPlaintext); ``` -## Crypto Constants +## Crypto constants The following constants exported by `crypto.constants` apply to various uses of the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. -### OpenSSL Options +### OpenSSL options <table> <tr> @@ -3325,7 +3325,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. </tr> </table> -### OpenSSL Engine Constants +### OpenSSL engine constants <table> <tr> @@ -3378,7 +3378,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. </tr> </table> -### Other OpenSSL Constants +### Other OpenSSL constants <table> <tr> @@ -3458,7 +3458,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. </tr> </table> -### Node.js Crypto Constants +### Node.js crypto constants <table> <tr> @@ -3529,7 +3529,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. [AEAD algorithms]: https://en.wikipedia.org/wiki/Authenticated_encryption [CCM mode]: #crypto_ccm_mode [Caveats]: #crypto_support_for_weak_or_compromised_algorithms -[Crypto Constants]: #crypto_crypto_constants_1 +[Crypto constants]: #crypto_crypto_constants_1 [HTML 5.2]: https://www.w3.org/TR/html52/changes.html#features-removed [HTML5's `keygen` element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen [NIST SP 800-131A]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf diff --git a/doc/api/debugger.md b/doc/api/debugger.md index a82b252a878..8253c176e43 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -168,9 +168,9 @@ breakpoint) * `scripts`: List all loaded scripts * `version`: Display V8's version -## Advanced Usage +## Advanced usage -### V8 Inspector Integration for Node.js +### V8 inspector integration for Node.js V8 Inspector integration allows attaching Chrome DevTools to Node.js instances for debugging and profiling. It uses the @@ -196,10 +196,10 @@ debugging sessions.) If the Chrome browser is older than 66.0.3345.0, use `inspector.html` instead of `js_app.html` in the above URL. -Chrome DevTools doesn't support debugging [Worker Threads][] yet. +Chrome DevTools doesn't support debugging [worker threads][] yet. [ndb][] can be used to debug them. [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/ [V8 Inspector]: #debugger_v8_inspector_integration_for_node_js -[Worker Threads]: worker_threads.html +[worker threads]: worker_threads.html [ndb]: https://github.com/GoogleChromeLabs/ndb/ diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index f0b4043cf8d..6cd0f4278f2 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -38,7 +38,7 @@ Occasionally, the deprecation of an API may be reversed. In such situations, this document will be updated with information relevant to the decision. However, the deprecation identifier will not be modified. -## List of Deprecated APIs +## List of deprecated APIs <a id="DEP0001"></a> ### DEP0001: `http.OutgoingMessage.prototype.flush` @@ -1632,7 +1632,7 @@ Type: Runtime `REPLServer.turnOffEditorMode()` was removed from userland visibility. <a id="DEP0079"></a> -### DEP0079: Custom inspection function on Objects via `.inspect()` +### DEP0079: Custom inspection function on objects via `.inspect()` <!-- YAML changes: - version: v11.0.0 @@ -1757,7 +1757,7 @@ manager, as it is published on the npm registry under the same name. No source code modification is necessary if that is done. <a id="DEP0085"></a> -### DEP0085: AsyncHooks Sensitive API +### DEP0085: AsyncHooks sensitive API <!-- YAML changes: - version: 10.0.0 @@ -1772,7 +1772,7 @@ changes: Type: End-of-Life -The AsyncHooks Sensitive API was never documented and had various minor issues. +The AsyncHooks sensitive API was never documented and had various minor issues. Use the `AsyncResource` API instead. See <https://github.com/nodejs/node/issues/15572>. @@ -1936,7 +1936,7 @@ should start using the `async_context` variant of `MakeCallback` or `CallbackScope`, or the high-level `AsyncResource` class. <a id="DEP0098"></a> -### DEP0098: AsyncHooks Embedder `AsyncResource.emitBefore` and `AsyncResource.emitAfter` APIs +### DEP0098: AsyncHooks embedder `AsyncResource.emitBefore` and `AsyncResource.emitAfter` APIs <!-- YAML changes: - version: v12.0.0 @@ -1961,7 +1961,7 @@ safer, and more convenient, alternative. See <https://github.com/nodejs/node/pull/18513>. <a id="DEP0099"></a> -### DEP0099: async context-unaware `node::MakeCallback` C++ APIs +### DEP0099: Async context-unaware `node::MakeCallback` C++ APIs <!-- YAML changes: - version: v10.0.0 @@ -2318,7 +2318,7 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) [`util.getSystemErrorName()`][] instead. <a id="DEP0120"></a> -### DEP0120: Windows Performance Counter Support +### DEP0120: Windows Performance Counter support <!-- YAML changes: - version: v12.0.0 diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 73cacc7195d..db93e1f2089 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -1,4 +1,4 @@ -# UDP/Datagram Sockets +# UDP/datagram sockets <!--introduced_in=v0.10.0--> @@ -6,7 +6,7 @@ <!-- name=dgram --> -The `dgram` module provides an implementation of UDP Datagram sockets. +The `dgram` module provides an implementation of UDP datagram sockets. ```js const dgram = require('dgram'); @@ -558,7 +558,7 @@ also use explicit scope in addresses, so only packets sent to a multicast address without specifying an explicit scope are affected by the most recent successful use of this call. -#### Examples: IPv6 Outgoing Multicast Interface +#### Example: IPv6 outgoing multicast interface On most systems, where scope format uses the interface name: @@ -580,7 +580,7 @@ socket.bind(1234, () => { }); ``` -#### Example: IPv4 Outgoing Multicast Interface +#### Example: IPv4 outgoing multicast interface All systems use an IP of the host on the desired physical interface: ```js @@ -591,7 +591,7 @@ socket.bind(1234, () => { }); ``` -#### Call Results +#### Call results A call on a socket that is not ready to send or no longer open may throw a *Not running* [`Error`][]. diff --git a/doc/api/dns.md b/doc/api/dns.md index b89be2f1046..8a4ee45fe10 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -621,7 +621,7 @@ That is, if attempting to resolve with the first server provided results in a subsequent servers provided. Fallback DNS servers will only be used if the earlier ones time out or result in some other error. -## DNS Promises API +## DNS promises API The `dns.promises` API provides an alternative set of asynchronous DNS methods that return `Promise` objects rather than using callbacks. The API is accessible diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 7059c4d33e1..f15936b3f43 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -1,4 +1,4 @@ -# About this Documentation +# About this documentation <!--introduced_in=v0.10.0--> <!-- type=misc --> @@ -12,7 +12,7 @@ Node.js is a JavaScript runtime built on the [V8 JavaScript engine][]. Report errors in this documentation in [the issue tracker][]. See [the contributing guide][] for directions on how to submit pull requests. -## Stability Index +## Stability index <!--type=misc--> @@ -43,7 +43,7 @@ Bugs or behavior changes may surprise end users when Experimental API modifications occur. To avoid surprises, use of an Experimental feature may need a command-line flag. Experimental features may also emit a [warning][]. -## JSON Output +## JSON output <!-- YAML added: v0.6.12 --> diff --git a/doc/api/domain.md b/doc/api/domain.md index fa3aef66b98..b9219fbb4d7 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -30,7 +30,7 @@ will be notified, rather than losing the context of the error in the `process.on('uncaughtException')` handler, or causing the program to exit immediately with an error code. -## Warning: Don't Ignore Errors! +## Warning: Don't ignore errors! <!-- type=misc --> @@ -199,7 +199,7 @@ are added to it. * `error.domainThrown` A boolean indicating whether the error was thrown, emitted, or passed to a bound callback function. -## Implicit Binding +## Implicit binding <!--type=misc--> @@ -225,7 +225,7 @@ Implicit binding routes thrown errors and `'error'` events to the `Domain`. Implicit binding only takes care of thrown errors and `'error'` events. -## Explicit Binding +## Explicit binding <!--type=misc--> @@ -432,9 +432,9 @@ d.run(() => { In this example, the `d.on('error')` handler will be triggered, rather than crashing the program. -## Domains and Promises +## Domains and promises -As of Node.js 8.0.0, the handlers of Promises are run inside the domain in +As of Node.js 8.0.0, the handlers of promises are run inside the domain in which the call to `.then()` or `.catch()` itself was made: ```js @@ -472,7 +472,7 @@ d2.run(() => { ``` Domains will not interfere with the error handling mechanisms for -Promises. In other words, no `'error'` event will be emitted for unhandled +promises. In other words, no `'error'` event will be emitted for unhandled `Promise` rejections. [`Error`]: errors.html#errors_class_error diff --git a/doc/api/embedding.md b/doc/api/embedding.md index a8fe2de72c9..1a416f52c60 100644 --- a/doc/api/embedding.md +++ b/doc/api/embedding.md @@ -1,4 +1,4 @@ -# C++ Embedder API +# C++ embedder API <!--introduced_in=v14.0.0--> diff --git a/doc/api/errors.md b/doc/api/errors.md index bbec1313c5d..d59c4029e60 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -16,11 +16,11 @@ errors: Node.js detects an exceptional logic violation that should never occur. These are raised typically by the `assert` module. -All JavaScript and System errors raised by Node.js inherit from, or are +All JavaScript and system errors raised by Node.js inherit from, or are instances of, the standard JavaScript {Error} class and are guaranteed to provide *at least* the properties available on that class. -## Error Propagation and Interception +## Error propagation and interception <!--type=misc--> @@ -186,7 +186,7 @@ circumstance of why the error occurred. `Error` objects capture a "stack trace" detailing the point in the code at which the `Error` was instantiated, and may provide a text description of the error. -All errors generated by Node.js, including all System and JavaScript errors, +All errors generated by Node.js, including all system and JavaScript errors, will either be instances of, or inherit from, the `Error` class. ### `new Error(message)` @@ -258,7 +258,7 @@ not capture any frames. The `error.code` property is a string label that identifies the kind of error. `error.code` is the most stable way to identify an error. It will only change between major versions of Node.js. In contrast, `error.message` strings may -change between any versions of Node.js. See [Node.js Error Codes][] for details +change between any versions of Node.js. See [Node.js error codes][] for details about specific codes. ### `error.message` @@ -497,7 +497,7 @@ If present, `error.port` is the network connection port that is not available. The `error.syscall` property is a string describing the [syscall][] that failed. -### Common System Errors +### Common system errors This is a list of system errors commonly-encountered when writing a Node.js program. For a comprehensive list, see the [`errno`(3) man page][]. @@ -574,7 +574,7 @@ require('url').parse(() => { }); Node.js will generate and throw `TypeError` instances *immediately* as a form of argument validation. -## Exceptions vs. Errors +## Exceptions vs. errors <!--type=misc--> @@ -588,7 +588,7 @@ Some exceptions are *unrecoverable* at the JavaScript layer. Such exceptions will *always* cause the Node.js process to crash. Examples include `assert()` checks or `abort()` calls in the C++ layer. -## OpenSSL Errors +## OpenSSL errors Errors originating in `crypto` or `tls` are of class `Error`, and in addition to the standard `.code` and `.message` properties, may have some additional @@ -612,7 +612,7 @@ The OpenSSL library the error originates in. A human-readable string describing the reason for the error. <a id="nodejs-error-codes"></a> -## Node.js Error Codes +## Node.js error codes <a id="ERR_AMBIGUOUS_ARGUMENT"></a> ### `ERR_AMBIGUOUS_ARGUMENT` @@ -2213,7 +2213,7 @@ changes: A module file could not be resolved while attempting a [`require()`][] or `import` operation. -## Legacy Node.js Error Codes +## Legacy Node.js error codes > Stability: 0 - Deprecated. These error codes are either inconsistent, or have > been removed. @@ -2618,7 +2618,7 @@ such as `process.stdout.on('data')`. [`zlib`]: zlib.html [ES Module]: esm.html [ICU]: intl.html#intl_internationalization_support -[Node.js Error Codes]: #nodejs-error-codes +[Node.js error codes]: #nodejs-error-codes [V8's stack trace API]: https://github.com/v8/v8/wiki/Stack-Trace-API [WHATWG Supported Encodings]: util.html#util_whatwg_supported_encodings [WHATWG URL API]: url.html#url_the_whatwg_url_api diff --git a/doc/api/esm.md b/doc/api/esm.md index b92ae3138e9..9252eaeed23 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -1,4 +1,4 @@ -# ECMAScript Modules +# ECMAScript modules <!--introduced_in=v8.5.0--> <!-- type=misc --> @@ -121,7 +121,7 @@ files in the package should be interpreted. Regardless of the value of the `"type"` field, `.mjs` files are always treated as ES modules and `.cjs` files are always treated as CommonJS. -### Package Scope and File Extensions +### Package scope and file extensions A folder containing a `package.json` file, and all subfolders below that folder down until the next folder containing another `package.json`, is considered a @@ -196,7 +196,7 @@ unspecified. ## Packages -### Package Entry Points +### Package entry points In a package’s `package.json` file, two fields can define entry points for a package: `"main"` and `"exports"`. The `"main"` field is supported in all @@ -216,7 +216,7 @@ CommonJS; `"main"` will be overridden by `"exports"` if it exists. As such fallback for legacy versions of Node.js that do not support the `"exports"` field. -[Conditional Exports][] can be used within `"exports"` to define different +[Conditional exports][] can be used within `"exports"` to define different package entry points per environment, including whether the package is referenced via `require` or via `import`. For more information about supporting both CommonJS and ES Modules in a single package please consult @@ -274,7 +274,7 @@ will encapsulation be lost but module consumers will be unable to `import feature from 'my-mod/feature'` as they will need to provide the full path `import feature from 'my-mod/feature/index.js`. -#### Main Entry Point Export +#### Main entry point export To set the main entry point for a package, it is advisable to define both `"exports"` and `"main"` in the package’s `package.json` file: @@ -298,7 +298,7 @@ package. It is not a strong encapsulation since a direct require of any absolute subpath of the package such as `require('/path/to/node_modules/pkg/subpath.js')` will still load `subpath.js`. -#### Subpath Exports +#### Subpath exports When using the `"exports"` field, custom subpaths can be defined along with the main entry point by treating the main entry point as the @@ -355,7 +355,7 @@ module inside the subfolder. Any modules which are not public should be moved to another folder to retain the encapsulation benefits of exports. -#### Package Exports Fallbacks +#### Package exports fallbacks For possible new specifier support in future, array fallbacks are supported for all invalid specifiers: @@ -372,7 +372,7 @@ supported for all invalid specifiers: Since `"not:valid"` is not a valid specifier, `"./submodule.js"` is used instead as the fallback, as if it were the only target. -#### Exports Sugar +#### Exports sugar If the `"."` export is the only export, the `"exports"` field provides sugar for this case being the direct `"exports"` field value. @@ -398,7 +398,7 @@ can be written: } ``` -#### Conditional Exports +#### Conditional exports Conditional exports provide a way to map to different paths depending on certain conditions. They are supported for both CommonJS and ES module imports. @@ -536,7 +536,7 @@ and in a CommonJS one. For example, this code will also work: const { something } = require('a-package/foo'); // Loads from ./foo.js. ``` -### Dual CommonJS/ES Module Packages +### Dual CommonJS/ES module packages Prior to the introduction of support for ES modules in Node.js, it was a common pattern for package authors to include both CommonJS and ES module JavaScript @@ -549,12 +549,12 @@ ignores) the top-level `"module"` field. Node.js can now run ES module entry points, and a package can contain both CommonJS and ES module entry points (either via separate specifiers such as `'pkg'` and `'pkg/es-module'`, or both at the same specifier via [Conditional -Exports][]). Unlike in the scenario where `"module"` is only used by bundlers, +exports][]). Unlike in the scenario where `"module"` is only used by bundlers, or ES module files are transpiled into CommonJS on the fly before evaluation by Node.js, the files referenced by the ES module entry point are evaluated as ES modules. -#### Dual Package Hazard +#### Dual package hazard When an application is using a package that provides both CommonJS and ES module sources, there is a risk of certain bugs if both versions of the package get @@ -577,7 +577,7 @@ all-CommonJS or all-ES module environments, respectively, and therefore is surprising to users. It also differs from the behavior users are familiar with when using transpilation via tools like [Babel][] or [`esm`][]. -#### Writing Dual Packages While Avoiding or Minimizing Hazards +#### Writing dual packages while avoiding or minimizing hazards First, the hazard described in the previous section occurs when a package contains both CommonJS and ES module sources and both sources are provided for @@ -607,11 +607,11 @@ following conditions: browsers. 1. The hazards described in the previous section are avoided or minimized. -##### Approach #1: Use an ES Module Wrapper +##### Approach #1: Use an ES module wrapper Write the package in CommonJS or transpile ES module sources into CommonJS, and create an ES module wrapper file that defines the named exports. Using -[Conditional Exports][], the ES module wrapper is used for `import` and the +[Conditional exports][], the ES module wrapper is used for `import` and the CommonJS entry point for `require`. <!-- eslint-skip --> @@ -689,7 +689,7 @@ stateless): } ``` -##### Approach #2: Isolate State +##### Approach #2: Isolate state A `package.json` file can define the separate CommonJS and ES module entry points directly: @@ -859,7 +859,7 @@ property: * `url` {string} The absolute `file:` URL of the module. -## Differences Between ES Modules and CommonJS +## Differences between ES modules and CommonJS ### Mandatory file extensions @@ -955,7 +955,7 @@ To include an ES module into CommonJS, use [`import()`][]. ### `import` statements An `import` statement can reference an ES module or a CommonJS module. Other -file types such as JSON or Native modules are not supported. For those, use +file types such as JSON or native modules are not supported. For those, use [`module.createRequire()`][]. `import` statements are permitted only in ES modules. For similar functionality @@ -991,9 +991,9 @@ It is also possible to [Dynamic `import()`][] is supported in both CommonJS and ES modules. It can be used to include ES module files from CommonJS code. -## CommonJS, JSON, and Native Modules +## CommonJS, JSON, and native modules -CommonJS, JSON, and Native modules can be used with +CommonJS, JSON, and native modules can be used with [`module.createRequire()`][]. ```js @@ -1043,7 +1043,7 @@ syncBuiltinESMExports(); fs.readFileSync === readFileSync; ``` -## Experimental JSON Modules +## Experimental JSON modules Currently importing JSON modules are only supported in the `commonjs` mode and are loaded using the CJS loader. [WHATWG JSON modules specification][] are @@ -1073,7 +1073,7 @@ node index.mjs # fails node --experimental-json-modules index.mjs # works ``` -## Experimental Wasm Modules +## Experimental Wasm modules Importing Web Assembly modules is supported under the `--experimental-wasm-modules` flag, allowing any `.wasm` files to be @@ -1097,7 +1097,7 @@ node --experimental-wasm-modules index.mjs would provide the exports interface for the instantiation of `module.wasm`. -## Experimental Top-Level `await` +## Experimental top-level `await` When the `--experimental-top-level-await` flag is provided, `await` may be used in the top level (outside of async functions) within modules. This implements @@ -1123,7 +1123,7 @@ node b.mjs # fails node --experimental-top-level-await b.mjs # works ``` -## Experimental Loaders +## Experimental loaders **Note: This API is currently being redesigned and will still change.** @@ -1148,11 +1148,11 @@ and parent URL. The module specifier is the string in an `import` statement or this one, or `undefined` if this is the main entry point for the application. The `conditions` property on the `context` is an array of conditions for -[Conditional Exports][] that apply to this resolution request. They can be used +[Conditional exports][] that apply to this resolution request. They can be used for looking up conditional mappings elsewhere or to modify the list when calling the default resolution logic. -The [current set of Node.js default conditions][Conditional Exports] will always +The [current set of Node.js default conditions][Conditional exports] will always be in the `context.conditions` list passed to the hook. If the hook wants to ensure Node.js-compatible resolution logic, all items from this default condition list **must** be passed through to the `defaultResolve` function. @@ -1512,7 +1512,7 @@ loaded from disk but before Node.js executes it; and so on for any `.coffee`, `.litcoffee` or `.coffee.md` files referenced via `import` statements of any loaded file. -## Resolution Algorithm +## Resolution algorithm ### Features @@ -1525,7 +1525,7 @@ The resolver has the following properties: * No folder mains * Bare specifier package resolution lookup through node_modules -### Resolver Algorithm +### Resolver algorithm The algorithm to load an ES module specifier is given through the **ESM_RESOLVE** method below. It returns the resolved URL for a @@ -1797,7 +1797,7 @@ success! [Babel]: https://babeljs.io/ [CommonJS]: modules.html -[Conditional Exports]: #esm_conditional_exports +[Conditional exports]: #esm_conditional_exports [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports [ECMAScript-modules implementation]: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md [ECMAScript Top-Level `await` proposal]: https://github.com/tc39/proposal-top-level-await/ diff --git a/doc/api/events.md b/doc/api/events.md index e5d8e41c049..80e9ccf6fef 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -74,7 +74,7 @@ myEmitter.on('event', (a, b) => { myEmitter.emit('event', 'a', 'b'); ``` -## Asynchronous vs. Synchronous +## Asynchronous vs. synchronous The `EventEmitter` calls all listeners synchronously in the order in which they were registered. This ensures the proper sequencing of @@ -167,7 +167,7 @@ myEmitter.emit('error', new Error('whoops!')); // Still throws and crashes Node.js ``` -## Capture Rejections of Promises +## Capture rejections of promises > Stability: 1 - captureRejections is experimental. @@ -968,7 +968,7 @@ There are two key differences between the Node.js `EventTarget` and the 2. In the Node.js `EventTarget`, if an event listener is an async function or returns a `Promise`, and the returned `Promise` rejects, the rejection will be automatically captured and handled the same way as a listener that - throws synchronously (see [`EventTarget` Error Handling][] for details). + throws synchronously (see [`EventTarget` error handling][] for details). ### `NodeEventTarget` vs. `EventEmitter` @@ -990,7 +990,7 @@ and cannot be used in place of an `EventEmitter` in most cases. 3. The `NodeEventTarget` supports `EventListener` objects as well as functions as handlers for all event types. -### Event Listener +### Event listener Event listeners registered for an event `type` may either be JavaScript functions or objects with a `handleEvent` property whose value is a function. @@ -1000,7 +1000,7 @@ passed to the `eventTarget.dispatchEvent()` function. Async functions may be used as event listeners. If an async handler function rejects, the rejection will be captured and be will handled as described in -[`EventTarget` Error Handling][]. +[`EventTarget` error handling][]. An error thrown by one handler function will not prevent the other handlers from being invoked. @@ -1042,7 +1042,7 @@ target.addEventListener('foo', handler3); target.addEventListener('foo', handler4, { once: true }); ``` -### `EventTarget` Error Handling +### `EventTarget` error handling When a registered event listener throws (or returns a Promise that rejects), by default the error will be forwarded to the `process.on('error')` event @@ -1399,7 +1399,7 @@ to the `EventTarget`. [`emitter.removeListener()`]: #events_emitter_removelistener_eventname_listener [`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n [`Event` Web API]: https://dom.spec.whatwg.org/#event -[`EventTarget` Error Handling]: #events_eventtarget_error_handling +[`EventTarget` error handling]: #events_eventtarget_error_handling [`EventTarget` Web API]: https://dom.spec.whatwg.org/#eventtarget [`fs.ReadStream`]: fs.html#fs_class_fs_readstream [`net.Server`]: net.html#net_class_net_server diff --git a/doc/api/fs.md b/doc/api/fs.md index fe89d169cce..317a1ca174c 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1,4 +1,4 @@ -# File System +# File system <!--introduced_in=v0.10.0--> @@ -242,7 +242,7 @@ fs.readFileSync(new URL('file:///C:/path/%5c')); \ or / characters */ ``` -## File Descriptors +## File descriptors On POSIX systems, for every process, the kernel maintains a table of currently open files and resources. Each open file is assigned a simple numeric @@ -277,7 +277,7 @@ at any given time so it is critical to close the descriptor when operations are completed. Failure to do so will result in a memory leak that will eventually cause an application to crash. -## Threadpool Usage +## Threadpool usage All file system APIs except `fs.FSWatcher()` and those that are explicitly synchronous use libuv's threadpool, which can have surprising and negative @@ -1030,7 +1030,7 @@ added: v0.11.13 The timestamp indicating the creation time of this file. -### Stat Time Values +### Stat time values The `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` properties are numeric values that hold the corresponding times in milliseconds. Their @@ -1155,7 +1155,7 @@ changes: Tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the accessibility -checks to be performed. Check [File Access Constants][] for possible values +checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). @@ -1297,7 +1297,7 @@ changes: Synchronously tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the -accessibility checks to be performed. Check [File Access Constants][] for +accessibility checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). @@ -1623,7 +1623,7 @@ through any other `fs` operation may lead to undefined behavior. Returns an object containing commonly used constants for file system operations. The specific constants currently defined are described in -[FS Constants][]. +[FS constants][]. ## `fs.copyFile(src, dest[, mode], callback)` <!-- YAML @@ -3045,7 +3045,7 @@ fs.readFile('<directory>', (err, data) => { The `fs.readFile()` function buffers the entire file. To minimize memory costs, when possible prefer streaming via `fs.createReadStream()`. -### File Descriptors +### File descriptors 1. Any specified file descriptor has to support reading. 2. If a file descriptor is specified as the `path`, it will not be closed @@ -4018,7 +4018,7 @@ AIX files retain the same inode for the lifetime of a file. Saving and closing a watched file on AIX will result in two notifications (one for adding new content, and one for truncation). -#### Filename Argument +#### Filename argument <!--type=misc--> @@ -4290,7 +4290,7 @@ It is unsafe to use `fs.writeFile()` multiple times on the same file without waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is recommended. -### Using `fs.writeFile()` with File Descriptors +### Using `fs.writeFile()` with file descriptors When `file` is a file descriptor, the behavior is almost identical to directly calling `fs.write()` like: @@ -4893,7 +4893,7 @@ added: v10.0.0 Tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the accessibility -checks to be performed. Check [File Access Constants][] for possible values +checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). @@ -5480,7 +5480,7 @@ Any specified `FileHandle` has to support writing. It is unsafe to use `fsPromises.writeFile()` multiple times on the same file without waiting for the `Promise` to be resolved (or rejected). -## FS Constants +## FS constants The following constants are exported by `fs.constants`. @@ -5504,7 +5504,7 @@ fs.open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => { }); ``` -### File Access Constants +### File access constants The following constants are meant for use with [`fs.access()`][]. @@ -5536,7 +5536,7 @@ The following constants are meant for use with [`fs.access()`][]. </tr> </table> -### File Copy Constants +### File copy constants The following constants are meant for use with [`fs.copyFile()`][]. @@ -5564,7 +5564,7 @@ The following constants are meant for use with [`fs.copyFile()`][]. </tr> </table> -### File Open Constants +### File open constants The following constants are meant for use with `fs.open()`. @@ -5658,7 +5658,7 @@ The following constants are meant for use with `fs.open()`. </tr> </table> -### File Type Constants +### File type constants The following constants are meant for use with the [`fs.Stats`][] object's `mode` property for determining a file's type. @@ -5702,7 +5702,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's </tr> </table> -### File Mode Constants +### File mode constants The following constants are meant for use with the [`fs.Stats`][] object's `mode` property for determining the access permissions for a file. @@ -5762,7 +5762,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's </tr> </table> -## File System Flags +## File system flags The following flags are available wherever the `flag` option takes a string. @@ -5910,8 +5910,8 @@ the file contents. [`util.promisify()`]: util.html#util_util_promisify_original [Caveats]: #fs_caveats [Common System Errors]: errors.html#errors_common_system_errors -[FS Constants]: #fs_fs_constants_1 -[File Access Constants]: #fs_file_access_constants +[FS constants]: #fs_fs_constants_1 +[File access constants]: #fs_file_access_constants [MDN-Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date [MDN-Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type [MSDN-Rel-Path]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths diff --git a/doc/api/globals.md b/doc/api/globals.md index 7e6129e9038..4e2e362bcde 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -1,4 +1,4 @@ -# Global Objects +# Global objects <!--introduced_in=v0.10.0--> <!-- type=misc --> diff --git a/doc/api/http2.md b/doc/api/http2.md index 956196dff22..67bb4c27e4d 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -119,7 +119,7 @@ User code will not create `Http2Session` instances directly. Server-side new HTTP/2 connection is received. Client-side `Http2Session` instances are created using the `http2.connect()` method. -#### `Http2Session` and Sockets +#### `Http2Session` and sockets Every `Http2Session` instance is associated with exactly one [`net.Socket`][] or [`tls.TLSSocket`][] when it is created. When either the `Socket` or the @@ -2366,7 +2366,7 @@ client.close(); added: v8.4.0 --> -#### Error Codes for `RST_STREAM` and `GOAWAY` +#### Error codes for `RST_STREAM` and `GOAWAY` <a id="error_codes"></a> | Value | Name | Constant | @@ -2432,7 +2432,7 @@ added: v8.4.0 Returns a [HTTP/2 Settings Object][] containing the deserialized settings from the given `Buffer` as generated by `http2.getPackedSettings()`. -### Headers Object +### Headers object Headers are represented as own-properties on JavaScript objects. The property keys will be serialized to lower-case. Property values should be strings (if @@ -2480,7 +2480,7 @@ server.on('stream', (stream, headers) => { }); ``` -### Settings Object +### Settings object <!-- YAML added: v8.4.0 changes: @@ -2527,7 +2527,7 @@ properties. All additional properties on the settings object are ignored. -### Error Handling +### Error handling There are several types of error conditions that may arise when using the `http2` module: @@ -2667,7 +2667,7 @@ req.on('end', () => { req.end('Jane'); ``` -### The Extended `CONNECT` Protocol +### The extended `CONNECT` protocol [RFC 8441][] defines an "Extended CONNECT Protocol" extension to HTTP/2 that may be used to bootstrap the use of an `Http2Stream` using the `CONNECT` @@ -3554,7 +3554,7 @@ given [`Http2Stream`][] on a newly created `Http2ServerResponse` as the callback parameter if successful. When `Http2ServerRequest` is closed, the callback is called with an error `ERR_HTTP2_INVALID_STREAM`. -## Collecting HTTP/2 Performance Metrics +## Collecting HTTP/2 performance metrics The [Performance Observer][] API can be used to collect basic performance metrics for each `Http2Session` and `Http2Stream` instance. diff --git a/doc/api/index.md b/doc/api/index.md index e4d488f43f4..c3d0790842d 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -5,30 +5,30 @@ <!--introduced_in=v0.10.0--> -* [About these Docs](documentation.html) -* [Usage & Example](synopsis.html) +* [About these docs](documentation.html) +* [Usage and example](synopsis.html) <div class="line"></div> -* [Assertion Testing](assert.html) -* [Async Hooks](async_hooks.html) +* [Assertion testing](assert.html) +* [Async hooks](async_hooks.html) * [Buffer](buffer.html) -* [C++ Addons](addons.html) -* [C/C++ Addons with N-API](n-api.html) -* [C++ Embedder API](embedding.html) -* [Child Processes](child_process.html) +* [C++ addons](addons.html) +* [C/C++ addons with N-API](n-api.html) +* [C++ embedder API](embedding.html) +* [Child processes](child_process.html) * [Cluster](cluster.html) -* [Command Line Options](cli.html) +* [Command line options](cli.html) * [Console](console.html) * [Crypto](crypto.html) * [Debugger](debugger.html) * [Deprecated APIs](deprecations.html) * [DNS](dns.html) * [Domain](domain.html) -* [ECMAScript Modules](esm.html) +* [ECMAScript modules](esm.html) * [Errors](errors.html) * [Events](events.html) -* [File System](fs.html) +* [File system](fs.html) * [Globals](globals.html) * [HTTP](http.html) * [HTTP/2](http2.html) @@ -39,27 +39,27 @@ * [Net](net.html) * [OS](os.html) * [Path](path.html) -* [Performance Hooks](perf_hooks.html) +* [Performance hooks](perf_hooks.html) * [Policies](policy.html) * [Process](process.html) * [Punycode](punycode.html) -* [Query Strings](querystring.html) +* [Query strings](querystring.html) * [Readline](readline.html) * [REPL](repl.html) * [Report](report.html) * [Stream](stream.html) -* [String Decoder](string_decoder.html) +* [String decoder](string_decoder.html) * [Timers](timers.html) * [TLS/SSL](tls.html) -* [Trace Events](tracing.html) +* [Trace events](tracing.html) * [TTY](tty.html) -* [UDP/Datagram](dgram.html) +* [UDP/datagram](dgram.html) * [URL](url.html) * [Utilities](util.html) * [V8](v8.html) * [VM](vm.html) * [WASI](wasi.html) -* [Worker Threads](worker_threads.html) +* [Worker threads](worker_threads.html) * [Zlib](zlib.html) <div class="line"></div> diff --git a/doc/api/inspector.md b/doc/api/inspector.md index ece84aa2c1f..4f9501a5f86 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -188,7 +188,7 @@ to the run-time events. Apart from the debugger, various V8 Profilers are available through the DevTools protocol. -### CPU Profiler +### CPU profiler Here's an example showing how to use the [CPU Profiler][]: @@ -213,7 +213,7 @@ session.post('Profiler.enable', () => { }); ``` -### Heap Profiler +### Heap profiler Here's an example showing how to use the [Heap Profiler][]: diff --git a/doc/api/intl.md b/doc/api/intl.md index 25f7e61cd18..8b7dee489b4 100644 --- a/doc/api/intl.md +++ b/doc/api/intl.md @@ -1,4 +1,4 @@ -# Internationalization Support +# Internationalization support <!--introduced_in=v8.2.0--> <!-- type=misc --> diff --git a/doc/api/modules.md b/doc/api/modules.md index 0d23edcbe7e..eccf4ed68d3 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -78,7 +78,7 @@ Because `module` provides a `filename` property (normally equivalent to `__filename`), the entry point of the current application can be obtained by checking `require.main.filename`. -## Addenda: Package Manager Tips +## Addenda: Package manager tips <!-- type=misc --> @@ -139,7 +139,7 @@ Attempting to do so will throw [an error][]. The `.mjs` extension is reserved for [ECMAScript Modules][] which cannot be loaded via `require()`. See [ECMAScript Modules][] for more details. -## All Together... +## All together... <!-- type=misc --> @@ -254,7 +254,7 @@ allowing transitive dependencies to be loaded even when they would cause cycles. To have a module execute code multiple times, export a function, and call that function. -### Module Caching Caveats +### Module caching caveats <!--type=misc--> @@ -269,7 +269,7 @@ them as different modules and will reload the file multiple times. For example, `require('./foo')` and `require('./FOO')` return two different objects, irrespective of whether or not `./foo` and `./FOO` are the same file. -## Core Modules +## Core modules <!--type=misc--> @@ -347,7 +347,7 @@ in main, a.done = true, b.done = true Careful planning is required to allow cyclic module dependencies to work correctly within an application. -## File Modules +## File modules <!--type=misc--> @@ -373,7 +373,7 @@ either be a core module or is loaded from a `node_modules` folder. If the given path does not exist, `require()` will throw an [`Error`][] with its `code` property set to `'MODULE_NOT_FOUND'`. -## Folders as Modules +## Folders as modules <!--type=misc--> @@ -413,7 +413,7 @@ with the default error: Error: Cannot find module 'some-library' ``` -## Loading from `node_modules` Folders +## Loading from `node_modules` folders <!--type=misc--> @@ -737,7 +737,7 @@ Returns an array containing the paths searched during resolution of `request` or `null` if the `request` string references a core module, for example `http` or `fs`. -## The `module` Object +## The `module` object <!-- YAML added: v0.1.16 --> @@ -935,7 +935,7 @@ Since `require()` returns the `module.exports`, and the `module` is typically *only* available within a specific module's code, it must be explicitly exported in order to be used. -## The `Module` Object +## The `Module` object <!-- YAML added: v0.3.7 @@ -1035,7 +1035,7 @@ import('fs').then((esmFS) => { }); ``` -## Source Map V3 Support +## Source map v3 support <!-- YAML added: v13.7.0 --> @@ -1083,7 +1083,7 @@ added: v13.7.0 Creates a new `sourceMap` instance. -`payload` is an object with keys matching the [Source Map V3 format][]: +`payload` is an object with keys matching the [Source map v3 format][]: * `file`: {string} * `version`: {number} @@ -1134,4 +1134,4 @@ consists of the following keys: [`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir [`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces [`SourceMap`]: modules.html#modules_class_module_sourcemap -[Source Map V3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej +[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej diff --git a/doc/api/n-api.md b/doc/api/n-api.md index e375616d23d..902cb883aee 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -31,7 +31,7 @@ properties: `napi_value`. * In case of an error status code, additional information can be obtained using `napi_get_last_error_info`. More information can be found in the error - handling section [Error Handling][]. + handling section [Error handling][]. The N-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. @@ -78,7 +78,7 @@ it still gets the benefits of the ABI stability provided by the C API. When using `node-addon-api` instead of the C APIs, start with the API [docs][] for `node-addon-api`. -## Implications of ABI Stability +## Implications of ABI stability Although N-API provides an ABI stability guarantee, other parts of Node.js do not, and any external libraries used from the addon may not. In particular, @@ -196,7 +196,7 @@ GitHub projects using CMake.js. #### prebuildify -[prebuildify][] is tool based on node-gyp. The advantage of prebuildify is +[prebuildify][] is a tool based on node-gyp. The advantage of prebuildify is that the built binaries are bundled with the native module when it's uploaded to npm. The binaries are downloaded from npm and are immediately available to the module user when the native module is installed. @@ -233,7 +233,7 @@ opt-in to access those APIs: In this case the entire API surface, including any experimental APIs, will be available to the module code. -## N-API Version Matrix +## N-API version matrix N-API versions are additive and versioned independently from Node.js. Version 4 is an extension to version 3 in that it has all of the APIs @@ -343,7 +343,7 @@ NAPI_MODULE_INIT() { } ``` -## Environment Life Cycle APIs +## Environment life cycle APIs > Stability: 1 - Experimental @@ -425,7 +425,7 @@ This API retrieves data that was previously associated with the currently running Agent via `napi_set_instance_data()`. If no data is set, the call will succeed and `data` will be set to `NULL`. -## Basic N-API Data Types +## Basic N-API data types N-API exposes the following fundamental datatypes as abstractions that are consumed by the various APIs. These APIs should be treated as opaque, @@ -492,7 +492,7 @@ typedef struct { not implemented for any VM. * `error_code`: The N-API status code that originated with the last error. -See the [Error Handling][] section for additional information. +See the [Error handling][] section for additional information. ### napi_env @@ -557,7 +557,7 @@ typedef enum { } napi_threadsafe_function_call_mode; ``` -### N-API Memory Management types +### N-API memory management types #### napi_handle_scope This is an abstraction used to control and modify the lifetime of objects @@ -575,7 +575,7 @@ using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC that all `napi_value`s created during the lifetime of the handle scope are no longer referenced from the current stack frame. -For more details, review the [Object Lifetime Management][]. +For more details, review the [Object lifetime management][]. #### napi_escapable_handle_scope <!-- YAML @@ -594,9 +594,9 @@ This is the abstraction to use to reference a `napi_value`. This allows for users to manage the lifetimes of JavaScript values, including defining their minimum lifetimes explicitly. -For more details, review the [Object Lifetime Management][]. +For more details, review the [Object lifetime management][]. -### N-API Callback types +### N-API callback types #### napi_callback_info <!-- YAML added: v8.0.0 @@ -713,7 +713,7 @@ typedef void (*napi_threadsafe_function_call_js)(napi_env env, This pointer is managed entirely by the threads and this callback. Thus this callback should free the data. -## Error Handling +## Error handling N-API uses both return values and JavaScript exceptions for error handling. The following sections explain the approach for each case. @@ -1103,7 +1103,7 @@ napi_status napi_fatal_exception(napi_env env, napi_value err); Trigger an `'uncaughtException'` in JavaScript. Useful if an async callback throws an exception with no way to recover. -### Fatal Errors +### Fatal errors In the event of an unrecoverable error in a native module, a fatal error can be thrown to immediately terminate the process. @@ -1132,7 +1132,7 @@ The function call does not return, the process will be terminated. This API can be called even if there is a pending JavaScript exception. -## Object Lifetime management +## Object lifetime management As N-API calls are made, handles to objects in the heap for the underlying VM may be returned as `napi_values`. These handles must hold the @@ -1586,7 +1586,7 @@ napi_value Init(napi_env env, napi_value exports) { ``` To define a class so that new instances can be created (often used with -[Object Wrap][]): +[Object wrap][]): ```c // NOTE: partial example, not all referenced code is included @@ -1643,12 +1643,12 @@ The variables `env` and `exports` will be available inside the function body following the macro invocation. For more details on setting properties on objects, see the section on -[Working with JavaScript Properties][]. +[Working with JavaScript properties][]. For more details on building addon modules in general, refer to the existing API. -## Working with JavaScript Values +## Working with JavaScript values N-API exposes a set of APIs to create all types of JavaScript values. Some of these types are documented under [Section 6][] of the [ECMAScript Language Specification][]. @@ -1778,7 +1778,7 @@ This represents the underlying binary scalar datatype of the `TypedArray`. Elements of this enum correspond to [Section 22.2][] of the [ECMAScript Language Specification][]. -### Object Creation Functions +### Object creation functions #### napi_create_array <!-- YAML added: v8.0.0 @@ -3007,7 +3007,7 @@ Returns `napi_ok` if the API succeeded. This API returns the Undefined object. -## Working with JavaScript Values and Abstract Operations +## Working with JavaScript values and abstract operations N-API exposes a set of APIs to perform some abstract operations on JavaScript values. Some of these operations are documented under [Section 7][] @@ -3366,7 +3366,7 @@ This API represents the invocation of the `ArrayBuffer` `IsDetachedBuffer` operation as defined in [Section 24.1.1.2][] of the ECMAScript Language Specification. -## Working with JavaScript Properties +## Working with JavaScript properties N-API exposes a set of APIs to get and set properties on JavaScript objects. Some of these types are documented under [Section 7][] of the @@ -3941,7 +3941,7 @@ this API will set the properties on the object one at a time, as defined by `DefineOwnProperty()` (described in [Section 9.1.6][] of the ECMA-262 specification). -## Working with JavaScript Functions +## Working with JavaScript functions N-API provides a set of APIs that allow JavaScript code to call back into native code. N-API APIs that support calling back @@ -4228,7 +4228,7 @@ status = napi_new_instance(env, constructor, argc, argv, &value); Returns `napi_ok` if the API succeeded. -## Object Wrap +## Object wrap N-API offers a way to "wrap" C++ classes and instances so that the class constructor and methods can be called from JavaScript. @@ -4482,7 +4482,7 @@ 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 required in order to enable correct disposal of the reference. -## Simple Asynchronous Operations +## Simple asynchronous operations Addon modules often need to leverage async helpers from libuv as part of their implementation. This allows them to schedule work to be executed asynchronously @@ -4651,7 +4651,7 @@ callback invocation, even if it has been successfully cancelled. This API can be called even if there is a pending JavaScript exception. -## Custom Asynchronous Operations +## Custom asynchronous operations The simple asynchronous work APIs above may not be appropriate for every scenario. When using any other asynchronous mechanism, the following APIs @@ -4797,7 +4797,7 @@ NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, This API can be called even if there is a pending JavaScript exception. -## Version Management +## Version management ### napi_get_node_version <!-- YAML @@ -4858,7 +4858,7 @@ support it: * If the function is not available, provide an alternate implementation that does not use the function. -## Memory Management +## Memory management ### napi_adjust_external_memory <!-- YAML @@ -5085,7 +5085,7 @@ NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[out] loop`: The current libuv loop instance. -## Asynchronous Thread-safe Function Calls +## Asynchronous thread-safe function calls JavaScript functions can normally only be called from a native addon's main thread. If an addon creates additional threads, then N-API functions that @@ -5424,14 +5424,14 @@ This API may only be called from the main thread. [CMake.js]: https://github.com/cmake-js/cmake-js [CMake]: https://cmake.org [ECMAScript Language Specification]: https://tc39.github.io/ecma262/ -[Error Handling]: #n_api_error_handling +[Error handling]: #n_api_error_handling [GCC]: https://gcc.gnu.org [GYP]: https://gyp.gsrc.io [GitHub releases]: https://help.github.com/en/github/administering-a-repository/about-releases [LLVM]: https://llvm.org [Native Abstractions for Node.js]: https://github.com/nodejs/nan -[Object Lifetime Management]: #n_api_object_lifetime_management -[Object Wrap]: #n_api_object_wrap +[Object lifetime management]: #n_api_object_lifetime_management +[Object wrap]: #n_api_object_wrap [Section 12.10.4]: https://tc39.github.io/ecma262/#sec-instanceofoperator [Section 12.5.5]: https://tc39.github.io/ecma262/#sec-typeof-operator [Section 19.2]: https://tc39.github.io/ecma262/#sec-function-objects @@ -5461,7 +5461,7 @@ This API may only be called from the main thread. [Section 24.1.1.2]: https://tc39.es/ecma262/#sec-isdetachedbuffer [Travis CI]: https://travis-ci.org [Visual Studio]: https://visualstudio.microsoft.com -[Working with JavaScript Properties]: #n_api_working_with_javascript_properties +[Working with JavaScript properties]: #n_api_working_with_javascript_properties [Xcode]: https://developer.apple.com/xcode/ [`Number.MAX_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.max_safe_integer [`Number.MIN_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.min_safe_integer diff --git a/doc/api/net.md b/doc/api/net.md index d445e417ca3..6fedabf0d2c 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -15,7 +15,7 @@ It can be accessed using: const net = require('net'); ``` -## IPC Support +## IPC support The `net` module supports IPC with named pipes on Windows, and Unix domain sockets on other operating systems. diff --git a/doc/api/os.md b/doc/api/os.md index d70bd2d260b..a6c83e0206f 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -45,7 +45,7 @@ added: v6.3.0 Contains commonly used operating system-specific constants for error codes, process signals, and so on. The specific constants defined are described in -[OS Constants](#os_os_constants_1). +[OS constants](#os_os_constants_1). ## `os.cpus()` <!-- YAML @@ -403,13 +403,13 @@ On POSIX systems, the operating system release is determined by calling `GetVersionExW()` will be used. See <https://en.wikipedia.org/wiki/Uname#Examples> for more information. -## OS Constants +## OS constants The following constants are exported by `os.constants`. Not all constants will be available on every operating system. -### Signal Constants +### Signal constants <!-- YAML changes: - version: v5.11.0 @@ -580,11 +580,11 @@ The following signal constants are exported by `os.constants.signals`. </tr> </table> -### Error Constants +### Error constants The following error constants are exported by `os.constants.errno`. -#### POSIX Error Constants +#### POSIX error constants <table> <tr> @@ -916,7 +916,7 @@ The following error constants are exported by `os.constants.errno`. </tr> </table> -#### Windows Specific Error Constants +#### Windows-specific error constants The following error codes are specific to the Windows operating system. @@ -1161,7 +1161,7 @@ The following error codes are specific to the Windows operating system. </tr> </table> -### dlopen Constants +### dlopen constants If available on the operating system, the following constants are exported in `os.constants.dlopen`. See dlopen(3) for detailed @@ -1198,7 +1198,7 @@ information. </tr> </table> -### Priority Constants +### Priority constants <!-- YAML added: v10.10.0 --> @@ -1252,7 +1252,7 @@ The following process scheduling constants are exported by </tr> </table> -### libuv Constants +### libuv constants <table> <tr> diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 20f0cc0c4bb..8d540491604 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -1,4 +1,4 @@ -# Performance Measurement APIs +# Performance measurement APIs <!--introduced_in=v8.5.0--> diff --git a/doc/api/policy.md b/doc/api/policy.md index e7ccbaa9db0..05918500fca 100644 --- a/doc/api/policy.md +++ b/doc/api/policy.md @@ -49,7 +49,7 @@ node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+D ## Features -### Error Behavior +### Error behavior When a policy check fails, Node.js by default will throw an error. It is possible to change the error behavior to one of a few possibilities @@ -73,7 +73,7 @@ available to change the behavior: } ``` -### Integrity Checks +### Integrity checks Policy files must use integrity checks with Subresource Integrity strings compatible with the browser @@ -115,7 +115,7 @@ body for the resource which can be useful for local development. It is not recommended in production since it would allow unexpected alteration of resources to be considered valid. -### Dependency Redirection +### Dependency redirection An application may need to ship patched versions of modules or to prevent modules from allowing all modules access to all other modules. Redirection @@ -164,7 +164,7 @@ module to load any specifier without redirection. This can be useful for local development and may have some valid usage in production, but should be used only with care after auditing a module to ensure its behavior is valid. -#### Example: Patched Dependency +#### Example: Patched dependency Redirected dependencies can provide attenuated or modified functionality as fits the application. For example, log data about timing of function durations by diff --git a/doc/api/process.md b/doc/api/process.md index 820b95f4d66..eda3ac16f7a 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -12,7 +12,7 @@ accessed using `require()`: const process = require('process'); ``` -## Process Events +## Process events The `process` object is an instance of [`EventEmitter`][]. @@ -122,7 +122,7 @@ not be the same as what is originally sent. If the `serialization` option was set to `advanced` used when spawning the process, the `message` argument can contain data that JSON is not able to represent. -See [Advanced Serialization for `child_process`][] for more details. +See [Advanced serialization for `child_process`][] for more details. ### Event: `'multipleResolves'` <!-- YAML @@ -455,7 +455,7 @@ The `*-deprecation` command line flags only affect warnings that use the name See the [`process.emitWarning()`][process_emit_warning] method for issuing custom or application-specific warnings. -### Signal Events +### Signal events <!--type=event--> <!--name=SIGINT, SIGHUP, etc.--> @@ -2533,7 +2533,7 @@ Will generate an object similar to: unicode: '11.0' } ``` -## Exit Codes +## Exit codes Node.js will normally exit with a `0` status code when no more async operations are pending. The following status codes are used in other @@ -2614,7 +2614,7 @@ cases: [`require.resolve()`]: modules.html#modules_require_resolve_request_options [`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal [`v8.setFlagsFromString()`]: v8.html#v8_v8_setflagsfromstring_flags -[Advanced Serialization for `child_process`]: child_process.html#child_process_advanced_serialization +[Advanced serialization for `child_process`]: child_process.html#child_process_advanced_serialization [Android building]: https://github.com/nodejs/node/blob/master/BUILDING.md#androidandroid-based-devices-eg-firefox-os [Child Process]: child_process.html [Cluster]: cluster.html diff --git a/doc/api/querystring.md b/doc/api/querystring.md index c7fafd23d95..0797e3ee220 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -1,4 +1,4 @@ -# Query String +# Query string <!--introduced_in=v0.1.25--> diff --git a/doc/api/readline.md b/doc/api/readline.md index d70a49304ce..a737e4bd24d 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -536,7 +536,7 @@ the best compatibility if it defines an `output.columns` property and emits a `'resize'` event on the `output` if or when the columns ever change ([`process.stdout`][] does this automatically when it is a TTY). -### Use of the `completer` Function +### Use of the `completer` function The `completer` function takes the current line entered by the user as an argument, and returns an `Array` with 2 entries: @@ -661,7 +661,7 @@ rl.on('line', (line) => { }); ``` -## Example: Read File Stream Line-by-Line +## Example: Read file stream line-by-Line A common use case for `readline` is to consume an input file one line at a time. The easiest way to do so is leveraging the [`fs.ReadStream`][] API as diff --git a/doc/api/repl.md b/doc/api/repl.md index 42926ca0f1c..4940001a4eb 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -12,7 +12,7 @@ It can be accessed using: const repl = require('repl'); ``` -## Design and Features +## Design and features The `repl` module exports the [`repl.REPLServer`][] class. While running, instances of [`repl.REPLServer`][] will accept individual lines of user input, @@ -28,7 +28,7 @@ recovery, and customizable evaluation functions. Terminals that do not support ANSI styles and Emacs-style line editing automatically fall back to a limited feature set. -### Commands and Special Keys +### Commands and special keys The following special commands are supported by all REPL instances: @@ -72,14 +72,14 @@ The following key combinations in the REPL have these special effects: For key bindings related to the reverse-i-search, see [`reverse-i-search`][]. For all other key bindings, see [TTY keybindings][]. -### Default Evaluation +### Default evaluation By default, all instances of [`repl.REPLServer`][] use an evaluation function that evaluates JavaScript expressions and provides access to Node.js built-in modules. This default behavior can be overridden by passing in an alternative evaluation function when the [`repl.REPLServer`][] instance is created. -#### JavaScript Expressions +#### JavaScript expressions The default evaluator supports direct evaluation of JavaScript expressions: @@ -96,7 +96,7 @@ Unless otherwise scoped within blocks or functions, variables declared either implicitly or using the `const`, `let`, or `var` keywords are declared at the global scope. -#### Global and Local Scope +#### Global and local scope The default evaluator provides access to any variables that exist in the global scope. It is possible to expose a variable to the REPL explicitly by assigning @@ -132,7 +132,7 @@ Object.defineProperty(r.context, 'm', { }); ``` -#### Accessing Core Node.js Modules +#### Accessing core Node.js modules The default evaluator will automatically load Node.js core modules into the REPL environment when used. For instance, unless otherwise declared as a @@ -143,7 +143,7 @@ global or scoped variable, the input `fs` will be evaluated on-demand as > fs.createReadStream('./some/file'); ``` -#### Global Uncaught Exceptions +#### Global uncaught exceptions <!-- YAML changes: - version: v12.3.0 @@ -256,7 +256,7 @@ with the reverse search. Cancelling is possible by pressing `escape` or Changing the direction immediately searches for the next entry in the expected direction from the current position on. -### Custom Evaluation Functions +### Custom evaluation functions When a new [`repl.REPLServer`][] is created, a custom evaluation function may be provided. This can be used, for instance, to implement fully customized REPL @@ -278,7 +278,7 @@ function myEval(cmd, context, filename, callback) { repl.start({ prompt: '> ', eval: myEval }); ``` -#### Recoverable Errors +#### Recoverable errors As a user is typing input into the REPL prompt, pressing the `<enter>` key will send the current line of input to the `eval` function. In order to support @@ -306,7 +306,7 @@ function isRecoverableError(error) { } ``` -### Customizing REPL Output +### Customizing REPL output By default, [`repl.REPLServer`][] instances format output using the [`util.inspect()`][] method before writing the output to the provided `Writable` @@ -645,7 +645,7 @@ undefined 3 ``` -### Environment Variable Options +### Environment variable options Various behaviors of the Node.js REPL can be customized using the following environment variables: @@ -662,7 +662,7 @@ environment variables: * `NODE_REPL_MODE`: May be either `'sloppy'` or `'strict'`. **Default:** `'sloppy'`, which will allow non-strict mode code to be run. -### Persistent History +### Persistent history By default, the Node.js REPL will persist history between `node` REPL sessions by saving inputs to a `.node_repl_history` file located in the user's home diff --git a/doc/api/report.md b/doc/api/report.md index 39a4cc91c25..95d53697f0d 100644 --- a/doc/api/report.md +++ b/doc/api/report.md @@ -1,4 +1,4 @@ -# Diagnostic Report +# Diagnostic report <!--introduced_in=v11.8.0--> <!-- type=misc --> @@ -577,7 +577,7 @@ NODE_OPTIONS="--report-uncaught-exception \ Specific API documentation can be found under [`process API documentation`][] section. -## Interaction with Workers +## Interaction with workers <!-- YAML changes: - version: diff --git a/doc/api/stream.md b/doc/api/stream.md index b1bdf6903f8..7afa52c2f95 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -23,13 +23,13 @@ const stream = require('stream'); The `stream` module is useful for creating new types of stream instances. It is usually not necessary to use the `stream` module to consume streams. -## Organization of this Document +## Organization of this document This document contains two primary sections and a third section for notes. The first section explains how to use existing streams within an application. The second section explains how to create new types of streams. -## Types of Streams +## Types of streams There are four fundamental stream types within Node.js: @@ -46,7 +46,7 @@ Additionally, this module includes the utility functions [`stream.pipeline()`][], [`stream.finished()`][] and [`stream.Readable.from()`][]. -### Object Mode +### Object mode All streams created by Node.js APIs operate exclusively on strings and `Buffer` (or `Uint8Array`) objects. It is possible, however, for stream implementations @@ -108,7 +108,7 @@ writing data *to* the socket. Because data may be written to the socket at a faster or slower rate than data is received, each side should operate (and buffer) independently of the other. -## API for Stream Consumers +## API for stream consumers <!--type=misc--> @@ -120,8 +120,8 @@ that implements an HTTP server: const http = require('http'); const server = http.createServer((req, res) => { - // `req` is an http.IncomingMessage, which is a Readable Stream. - // `res` is an http.ServerResponse, which is a Writable Stream. + // `req` is an http.IncomingMessage, which is a readable stream. + // `res` is an http.ServerResponse, which is a writable stream. let body = ''; // Get the data as utf8 strings. @@ -176,9 +176,9 @@ are not required to implement the stream interfaces directly and will generally have no reason to call `require('stream')`. Developers wishing to implement new types of streams should refer to the -section [API for Stream Implementers][]. +section [API for stream implementers][]. -### Writable Streams +### Writable streams Writable streams are an abstraction for a *destination* to which data is written. @@ -649,7 +649,7 @@ write('hello', () => { A `Writable` stream in object mode will always ignore the `encoding` argument. -### Readable Streams +### Readable streams Readable streams are an abstraction for a *source* from which data is consumed. @@ -668,7 +668,7 @@ Examples of `Readable` streams include: All [`Readable`][] streams implement the interface defined by the `stream.Readable` class. -#### Two Reading Modes +#### Two reading modes `Readable` streams effectively operate in one of two modes: flowing and paused. These modes are separate from [object mode][object-mode]. @@ -719,7 +719,7 @@ stop flowing, and the data to be consumed via removed, then the stream will start flowing again if there is a [`'data'`][] event handler. -#### Three States +#### Three states The "two modes" of operation for a `Readable` stream are a simplified abstraction for the more complicated internal state management that is happening @@ -762,7 +762,7 @@ pass.resume(); // Must be called to make stream emit 'data'. While `readable.readableFlowing` is `false`, data may be accumulating within the stream's internal buffer. -#### Choose One API Style +#### Choose one API style The `Readable` stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data. In general, developers should choose @@ -1184,7 +1184,7 @@ added: v9.4.0 * {boolean} This property reflects the current state of a `Readable` stream as described -in the [Stream Three States][] section. +in the [Three states][] section. ##### `readable.readableHighWaterMark` <!-- YAML @@ -1338,7 +1338,7 @@ The `stream.unshift(chunk)` method cannot be called after the [`'end'`][] event has been emitted or a runtime error will be thrown. 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][] section for more information. ```js @@ -1450,7 +1450,7 @@ option. In the code example above, data will be in a single chunk if the file has less then 64KB of data because no `highWaterMark` option is provided to [`fs.createReadStream()`][]. -### Duplex and Transform Streams +### Duplex and transform streams #### Class: `stream.Duplex` <!-- YAML @@ -1713,7 +1713,7 @@ added: this is explicitly opted out by setting `options.objectMode` to `false`. * Returns: {stream.Readable} -A utility method for creating Readable Streams out of iterators. +A utility method for creating readable streams out of iterators. ```js const { Readable } = require('stream'); @@ -1734,7 +1734,7 @@ Calling `Readable.from(string)` or `Readable.from(buffer)` will not have the strings or buffers be iterated to match the other streams semantics for performance reasons. -## API for Stream Implementers +## API for stream implementers <!--type=misc--> @@ -1777,7 +1777,7 @@ on the type of stream being created, as detailed in the chart below: The implementation code for a stream should *never* call the "public" methods of a stream that are intended for use by consumers (as described in the -[API for Stream Consumers][] section). Doing so may lead to adverse side effects +[API for stream consumers][] section). Doing so may lead to adverse side effects in application code consuming the stream. Avoid overriding public methods such as `write()`, `end()`, `cork()`, @@ -1787,7 +1787,7 @@ Doing so can break current and future stream invariants leading to behavior and/or compatibility issues with other streams, stream utilities, and user expectations. -### Simplified Construction +### Simplified construction <!-- YAML added: v1.2.0 --> @@ -1807,7 +1807,7 @@ const myWritable = new Writable({ }); ``` -### Implementing a Writable Stream +### Implementing a writable stream The `stream.Writable` class is extended to implement a [`Writable`][] stream. @@ -1891,7 +1891,7 @@ function MyWritable(options) { util.inherits(MyWritable, Writable); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Writable } = require('stream'); @@ -2008,7 +2008,7 @@ This optional function will be called before the stream closes, delaying the `'finish'` event until `callback` is called. This is useful to close resources or write buffered data before a stream ends. -#### Errors While Writing +#### Errors while writing Errors occurring during the processing of the [`writable._write()`][], [`writable._writev()`][] and [`writable._final()`][] methods must be propagated @@ -2033,7 +2033,7 @@ const myWritable = new Writable({ }); ``` -#### An Example Writable Stream +#### An example writable stream The following illustrates a rather simplistic (and somewhat pointless) custom `Writable` stream implementation. While this specific `Writable` stream instance @@ -2054,7 +2054,7 @@ class MyWritable extends Writable { } ``` -#### Decoding buffers in a Writable Stream +#### Decoding buffers in a writable stream Decoding buffers is a common task, for instance, when using transformers whose input is a string. This is not a trivial process when using multi-byte @@ -2094,7 +2094,7 @@ w.end(euro[1]); console.log(w.data); // currency: € ``` -### Implementing a Readable Stream +### Implementing a readable stream The `stream.Readable` class is extended to implement a [`Readable`][] stream. @@ -2160,7 +2160,7 @@ function MyReadable(options) { util.inherits(MyReadable, Readable); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Readable } = require('stream'); @@ -2293,7 +2293,7 @@ For streams not operating in object mode, if the `chunk` parameter of `readable.push()` is `undefined`, it will be treated as empty string or buffer. See [`readable.push('')`][] for more information. -#### Errors While Reading +#### Errors while reading Errors occurring during processing of the [`readable._read()`][] must be propagated through the [`readable.destroy(err)`][readable-_destroy] method. @@ -2315,7 +2315,7 @@ const myReadable = new Readable({ }); ``` -#### An Example Counting Stream +#### An example counting stream <!--type=example--> @@ -2345,7 +2345,7 @@ class Counter extends Readable { } ``` -### Implementing a Duplex Stream +### Implementing a duplex stream A [`Duplex`][] stream is one that implements both [`Readable`][] and [`Writable`][], such as a TCP socket connection. @@ -2412,7 +2412,7 @@ function MyDuplex(options) { util.inherits(MyDuplex, Duplex); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Duplex } = require('stream'); @@ -2427,7 +2427,7 @@ const myDuplex = new Duplex({ }); ``` -#### An Example Duplex Stream +#### An example duplex stream The following illustrates a simple example of a `Duplex` stream that wraps a hypothetical lower-level source object to which data can be written, and @@ -2467,7 +2467,7 @@ The most important aspect of a `Duplex` stream is that the `Readable` and `Writable` sides operate independently of one another despite co-existing within a single object instance. -#### Object Mode Duplex Streams +#### Object mode duplex streams For `Duplex` streams, `objectMode` can be set exclusively for either the `Readable` or `Writable` side using the `readableObjectMode` and @@ -2508,7 +2508,7 @@ myTransform.write(100); // Prints: 64 ``` -### Implementing a Transform Stream +### Implementing a transform stream A [`Transform`][] stream is a [`Duplex`][] stream where the output is computed in some way from the input. Examples include [zlib][] streams or [crypto][] @@ -2567,7 +2567,7 @@ function MyTransform(options) { util.inherits(MyTransform, Transform); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Transform } = require('stream'); @@ -2682,11 +2682,11 @@ stream that simply passes the input bytes across to the output. Its purpose is primarily for examples and testing, but there are some use cases where `stream.PassThrough` is useful as a building block for novel sorts of streams. -## Additional Notes +## Additional notes <!--type=misc--> -### Streams Compatibility with Async Generators and Async Iterators +### Streams compatibility with async generators and async iterators With the support of async generators and iterators in JavaScript, async generators are effectively a first-class language-level stream construct at @@ -2695,7 +2695,7 @@ this point. Some common interop cases of using Node.js streams with async generators and async iterators are provided below. -#### Consuming Readable Streams with Async Iterators +#### Consuming readable streams with async iterators ```js (async function() { @@ -2708,9 +2708,9 @@ and async iterators are provided below. Async iterators register a permanent error handler on the stream to prevent any unhandled post-destroy errors. -#### Creating Readable Streams with Async Generators +#### Creating readable streams with async generators -We can construct a Node.js Readable Stream from an asynchronous generator +We can construct a Node.js readable stream from an asynchronous generator using the `Readable.from()` utility method: ```js @@ -2729,7 +2729,7 @@ readable.on('data', (chunk) => { }); ``` -#### Piping to Writable Streams from Async Iterators +#### Piping to writable streams from async iterators When writing to a writable stream from an async iterator, ensure correct handling of backpressure and errors. [`stream.pipeline()`][] abstracts away @@ -2762,7 +2762,7 @@ pipelinePromise(iterator, writable) <!--type=misc--> -### Compatibility with Older Node.js Versions +### Compatibility with older Node.js versions <!--type=misc--> @@ -2903,8 +2903,8 @@ contain multi-byte characters. [`writable.uncork()`]: #stream_writable_uncork [`writable.writableFinished`]: #stream_writable_writablefinished [`zlib.createDeflate()`]: zlib.html#zlib_zlib_createdeflate_options -[API for Stream Consumers]: #stream_api_for_stream_consumers -[API for Stream Implementers]: #stream_api_for_stream_implementers +[API for stream consumers]: #stream_api_for_stream_consumers +[API for stream implementers]: #stream_api_for_stream_implementers [Compatibility]: #stream_compatibility_with_older_node_js_versions [HTTP requests, on the client]: http.html#http_class_http_clientrequest [HTTP responses, on the server]: http.html#http_class_http_serverresponse @@ -2932,7 +2932,7 @@ contain multi-byte characters. [stream-resume]: #stream_readable_resume [stream-uncork]: #stream_writable_uncork [stream-write]: #stream_writable_write_chunk_encoding_callback -[Stream Three States]: #stream_three_states +[Three states]: #stream_three_states [writable-_destroy]: #stream_writable_destroy_err_callback [writable-destroy]: #stream_writable_destroy_error [writable-new]: #stream_new_stream_writable_options diff --git a/doc/api/string_decoder.md b/doc/api/string_decoder.md index 54fcc876c9a..5cd6121d50d 100644 --- a/doc/api/string_decoder.md +++ b/doc/api/string_decoder.md @@ -1,4 +1,4 @@ -# String Decoder +# String decoder <!--introduced_in=v0.10.0--> diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md index c296ffb0fa4..8ae933a499a 100644 --- a/doc/api/synopsis.md +++ b/doc/api/synopsis.md @@ -1,4 +1,4 @@ -# Usage & Example +# Usage and example ## Usage diff --git a/doc/api/timers.md b/doc/api/timers.md index a312022791f..8b080b16ffb 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -123,7 +123,7 @@ Calling `timeout.unref()` creates an internal timer that will wake the Node.js event loop. Creating too many of these can adversely impact performance of the Node.js application. -## Scheduling Timers +## Scheduling timers A timer in Node.js is an internal construct that calls a given function after a certain period of time. When a timer's function is called varies depending on @@ -226,7 +226,7 @@ setTimeoutPromise(40, 'foobar').then((value) => { }); ``` -## Cancelling Timers +## Cancelling timers The [`setImmediate()`][], [`setInterval()`][], and [`setTimeout()`][] methods each return objects that represent the scheduled timers. These can be used to diff --git a/doc/api/tls.md b/doc/api/tls.md index 4b49260e266..71c127ca6cc 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -12,7 +12,7 @@ The module can be accessed using: const tls = require('tls'); ``` -## TLS/SSL Concepts +## TLS/SSL concepts The TLS/SSL is a public/private key infrastructure (PKI). For most common cases, each client and server must have a *private key*. @@ -64,11 +64,11 @@ Where: * `certfile`: is a concatenation of all Certificate Authority (CA) certs into a single file, e.g. `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` -### Perfect Forward Secrecy +### Perfect forward secrecy <!-- type=misc --> -The term "[Forward Secrecy][]" or "Perfect Forward Secrecy" describes a feature +The term _[forward secrecy][]_ or _perfect forward secrecy_ describes a feature of key-agreement (i.e., key-exchange) methods. That is, the server and client keys are used to negotiate new temporary keys that are used specifically and only for the current communication session. Practically, this means that even @@ -76,11 +76,11 @@ if the server's private key is compromised, communication can only be decrypted by eavesdroppers if the attacker manages to obtain the key-pair specifically generated for the session. -Perfect Forward Secrecy is achieved by randomly generating a key pair for +Perfect forward secrecy is achieved by randomly generating a key pair for key-agreement on every TLS/SSL handshake (in contrast to using the same key for all sessions). Methods implementing this technique are called "ephemeral". -Currently two methods are commonly used to achieve Perfect Forward Secrecy (note +Currently two methods are commonly used to achieve perfect forward secrecy (note the character "E" appended to the traditional abbreviations): * [DHE][]: An ephemeral version of the Diffie Hellman key-agreement protocol. @@ -90,7 +90,7 @@ the character "E" appended to the traditional abbreviations): Ephemeral methods may have some performance drawbacks, because key generation is expensive. -To use Perfect Forward Secrecy using `DHE` with the `tls` module, it is required +To use perfect forward secrecy using `DHE` with the `tls` module, it is required to generate Diffie-Hellman parameters and specify them with the `dhparam` option to [`tls.createSecureContext()`][]. The following illustrates the use of the OpenSSL command-line interface to generate such parameters: @@ -99,12 +99,12 @@ the OpenSSL command-line interface to generate such parameters: openssl dhparam -outform PEM -out dhparam.pem 2048 ``` -If using Perfect Forward Secrecy using `ECDHE`, Diffie-Hellman parameters are +If using perfect forward secrecy using `ECDHE`, Diffie-Hellman parameters are not required and a default ECDHE curve will be used. The `ecdhCurve` property can be used when creating a TLS Server to specify the list of names of supported curves to use, see [`tls.createServer()`][] for more info. -Perfect Forward Secrecy was optional up to TLSv1.2, but it is not optional for +Perfect forward secrecy was optional up to TLSv1.2, but it is not optional for TLSv1.3, because all TLSv1.3 cipher suites use ECDHE. ### ALPN and SNI @@ -175,13 +175,15 @@ understanding of the implications and risks. TLSv1.3 does not support renegotiation. -### Session Resumption +### Session resumption Establishing a TLS session can be relatively slow. The process can be sped up by saving and later reusing the session state. There are several mechanisms to do so, discussed here from oldest to newest (and preferred). -***Session Identifiers*** Servers generate a unique ID for new connections and +#### Session identifiers + +Servers generate a unique ID for new connections and send it to the client. Clients and servers save the session state. When reconnecting, clients send the ID of their saved session state and if the server also has the state for that ID, it can agree to use it. Otherwise, the server @@ -200,7 +202,9 @@ reuse sessions. To reuse sessions across load balancers or cluster workers, servers must use a shared session cache (such as Redis) in their session handlers. -***Session Tickets*** The servers encrypt the entire session state and send it +#### Session tickets + +The servers encrypt the entire session state and send it to the client as a "ticket". When reconnecting, the state is sent to the server in the initial connection. This mechanism avoids the need for server-side session cache. If the server doesn't use the ticket, for any reason (failure @@ -267,7 +271,7 @@ Subsequent connections should say "Reused", for example: Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 ``` -## Modifying the Default TLS Cipher suite +## Modifying the default TLS cipher suite Node.js is built with a default suite of enabled and disabled TLS ciphers. This default cipher list can be configured when building Node.js to allow @@ -340,8 +344,8 @@ of an application. The `--tls-cipher-list` switch and `ciphers` option should by used only if absolutely necessary. The default cipher suite prefers GCM ciphers for [Chrome's 'modern -cryptography' setting][] and also prefers ECDHE and DHE ciphers for Perfect -Forward Secrecy, while offering *some* backward compatibility. +cryptography' setting][] and also prefers ECDHE and DHE ciphers for perfect +forward secrecy, while offering *some* backward compatibility. 128 bit AES is preferred over 192 and 256 bit AES in light of [specific attacks affecting larger AES key sizes][]. @@ -904,7 +908,7 @@ added: v5.0.0 * Returns: {Object} Returns an object representing the type, name, and size of parameter of -an ephemeral key exchange in [Perfect Forward Secrecy][] on a client +an ephemeral key exchange in [perfect forward secrecy][] on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; `null` is returned if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The @@ -946,7 +950,7 @@ If the full certificate chain was requested, each certificate will include an `issuerCertificate` property containing an object representing its issuer's certificate. -#### Certificate Object +#### Certificate object <!-- YAML changes: - version: v11.4.0 @@ -1565,7 +1569,7 @@ changes: * `crl` {string|string[]|Buffer|Buffer[]} PEM formatted CRLs (Certificate Revocation Lists). * `dhparam` {string|Buffer} Diffie Hellman parameters, required for - [Perfect Forward Secrecy][]. Use `openssl dhparam` to create the parameters. + [perfect forward secrecy][]. Use `openssl dhparam` to create the parameters. The key length must be greater than or equal to 1024 bits or else an error will be thrown. Although 1024 bits is permissible, use 2048 bits or larger for stronger security. If omitted or invalid, the parameters are silently @@ -1991,11 +1995,11 @@ where `secureSocket` has the same API as `pair.cleartext`. [Chrome's 'modern cryptography' setting]: https://www.chromium.org/Home/chromium-security/education/tls#TOC-Cipher-Suites [DHE]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange [ECDHE]: https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman -[Forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy +[forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy [Mozilla's publicly trusted list of CAs]: https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt [OCSP request]: https://en.wikipedia.org/wiki/OCSP_stapling [OpenSSL Options]: crypto.html#crypto_openssl_options -[Perfect Forward Secrecy]: #tls_perfect_forward_secrecy +[perfect forward secrecy]: #tls_perfect_forward_secrecy [RFC 2246]: https://www.ietf.org/rfc/rfc2246.txt [RFC 5077]: https://tools.ietf.org/html/rfc5077 [RFC 5929]: https://tools.ietf.org/html/rfc5929 diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 4a684be4b19..907fc2bbe23 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -1,11 +1,11 @@ -# Trace Events +# Trace events <!--introduced_in=v7.7.0--> > Stability: 1 - Experimental -Trace Event provides a mechanism to centralize tracing information generated by -V8, Node.js core, and userspace code. +The `trace_events` module provides a mechanism to centralize tracing information +generated by V8, Node.js core, and userspace code. Tracing can be enabled with the `--trace-event-categories` command-line flag or by using the `trace_events` module. The `--trace-event-categories` flag diff --git a/doc/api/url.md b/doc/api/url.md index dfe312bef80..fbe8aa39791 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -11,7 +11,7 @@ accessed using: const url = require('url'); ``` -## URL Strings and URL Objects +## URL strings and URL objects A URL string is a structured string containing multiple meaningful components. When parsed, a URL object is returned containing properties for each of these @@ -406,7 +406,7 @@ console.log(myURL.href); Invalid URL protocol values assigned to the `protocol` property are ignored. -##### Special Schemes +##### Special schemes The [WHATWG URL Standard][] considers a handful of URL protocol schemes to be _special_ in terms of how they are parsed and serialized. When a URL is @@ -1276,7 +1276,7 @@ url.resolve('http://example.com/one', '/two'); // 'http://example.com/two' ``` <a id="whatwg-percent-encoding"></a> -## Percent-Encoding in URLs +## Percent-encoding in URLs URLs are permitted to only contain a certain range of characters. Any character falling outside of that range must be encoded. How such characters are encoded, diff --git a/doc/api/util.md b/doc/api/util.md index bc57d8ee061..269210c1a38 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -756,7 +756,7 @@ ignored, if not supported. * `bgCyanBright` * `bgWhiteBright` -### Custom inspection functions on Objects +### Custom inspection functions on objects <!-- type=misc --> @@ -1047,7 +1047,7 @@ while (buffer = getNextChunkSomehow()) { string += decoder.decode(); // end-of-stream ``` -### WHATWG Supported Encodings +### WHATWG supported encodings Per the [WHATWG Encoding Standard][], the encodings supported by the `TextDecoder` API are outlined in the tables below. For each encoding, @@ -1056,7 +1056,7 @@ one or more aliases may be used. Different Node.js build configurations support different sets of encodings. (see [Internationalization][]) -#### Encodings Supported by Default (With Full ICU Data) +#### Encodings supported by default (with full ICU data) | Encoding | Aliases | | ----------------- | -------------------------------- | @@ -1095,7 +1095,7 @@ Different Node.js build configurations support different sets of encodings. | `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` | | `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` | -#### Encodings Supported when Node.js is built with the `small-icu` option +#### Encodings supported when Node.js is built with the `small-icu` option | Encoding | Aliases | | ----------- | --------------------------------- | @@ -1103,7 +1103,7 @@ Different Node.js build configurations support different sets of encodings. | `'utf-16le'` | `'utf-16'` | | `'utf-16be'` | | -#### Encodings Supported when ICU is disabled +#### Encodings supported when ICU is disabled | Encoding | Aliases | | ----------- | --------------------------------- | @@ -2427,7 +2427,7 @@ util.log('Timestamped message.'); [`util.types.isNativeError()`]: #util_util_types_isnativeerror_value [`util.types.isSharedArrayBuffer()`]: #util_util_types_issharedarraybuffer_value [Common System Errors]: errors.html#errors_common_system_errors -[Custom inspection functions on Objects]: #util_custom_inspection_functions_on_objects +[Custom inspection functions on objects]: #util_custom_inspection_functions_on_objects [Custom promisified functions]: #util_custom_promisified_functions [Customizing `util.inspect` colors]: #util_customizing_util_inspect_colors [Internationalization]: intl.html diff --git a/doc/api/v8.md b/doc/api/v8.md index ec6a6ea9a05..531612330f0 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -231,7 +231,7 @@ DevTools. The JSON schema is undocumented and specific to the V8 engine, and may change from one version of V8 to the next. A heap snapshot is specific to a single V8 isolate. When using -[Worker Threads][], a heap snapshot generated from the main thread will +[worker threads][], a heap snapshot generated from the main thread will not contain any information about the workers, and vice versa. ```js @@ -519,4 +519,4 @@ A subclass of [`Deserializer`][] corresponding to the format written by [`vm.Script`]: vm.html#vm_new_vm_script_code_options [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [V8]: https://developers.google.com/v8/ -[Worker Threads]: worker_threads.html +[worker threads]: worker_threads.html diff --git a/doc/api/vm.md b/doc/api/vm.md index 7d16b48b04a..7ef5ff62279 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -1,4 +1,4 @@ -# VM (Executing JavaScript) +# VM (executing JavaScript) <!--introduced_in=v0.10.0--> @@ -1168,7 +1168,7 @@ local scope, so the value `localVar` is changed. In this way `vm.runInThisContext()` is much like an [indirect `eval()` call][], e.g. `(0,eval)('code')`. -## Example: Running an HTTP Server within a VM +## Example: Running an HTTP server within a VM When using either [`script.runInThisContext()`][] or [`vm.runInThisContext()`][], the code is executed within the current V8 global @@ -1218,7 +1218,7 @@ within which it can operate. The process of creating the V8 Context and associating it with the `contextObject` is what this document refers to as "contextifying" the object. -## Timeout limitations when using `process.nextTick()`, Promises, and `queueMicrotask()` +## Timeout limitations when using `process.nextTick()`, promises, and `queueMicrotask()` Because of the internal mechanics of how the `process.nextTick()` queue and the microtask queue that underlies Promises are implemented within V8 and diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 33d9aa0eb41..45b9a5f0fd2 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -1,4 +1,4 @@ -# Worker Threads +# Worker threads <!--introduced_in=v10.5.0--> diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 439b9d85e05..d5079266484 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -93,7 +93,7 @@ do_unzip(buffer) }); ``` -## Threadpool Usage and Performance Considerations +## Threadpool usage and performance considerations All `zlib` APIs, except those that are explicitly synchronous, use the Node.js internal threadpool. This can lead to surprising effects and performance @@ -133,7 +133,7 @@ message. The examples given below are drastically simplified to show the basic concept. Using `zlib` encoding can be expensive, and the results ought to be cached. -See [Memory Usage Tuning][] for more information on the speed/memory/compression +See [Memory usage tuning][] for more information on the speed/memory/compression tradeoffs involved in `zlib` usage. ```js @@ -252,7 +252,7 @@ possible to determine whether the input ended prematurely or lacks the integrity checks, making it necessary to manually check that the decompressed result is valid. -## Memory Usage Tuning +## Memory usage tuning <!--type=misc--> @@ -837,7 +837,7 @@ added: v0.5.8 Creates and returns a new [`Unzip`][] object. -## Convenience Methods +## Convenience methods <!--type=misc--> @@ -1186,7 +1186,7 @@ Decompress a chunk of data with [`Unzip`][]. [`stream.Transform`]: stream.html#stream_class_stream_transform [`zlib.bytesWritten`]: #zlib_zlib_byteswritten [Brotli parameters]: #zlib_brotli_constants -[Memory Usage Tuning]: #zlib_memory_usage_tuning +[Memory usage tuning]: #zlib_memory_usage_tuning [RFC 7932]: https://www.rfc-editor.org/rfc/rfc7932.txt [Streams API]: stream.md [convenience methods]: #zlib_convenience_methods |