diff options
56 files changed, 351 insertions, 252 deletions
diff --git a/BUILDING.md b/BUILDING.md index 74b5903ed2..11378a63b5 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -34,8 +34,8 @@ Support is divided into three tiers: ### Supported platforms The community does not build or test against end-of-life distributions (EoL). -Thus we do not recommend that you use Node on end-of-life or unsupported platforms -in production. +Thus we do not recommend that you use Node on end-of-life or unsupported +platforms in production. | System | Support type | Version | Architectures | Notes | |--------------|--------------|----------------------------------|----------------------|------------------| @@ -107,9 +107,11 @@ installed, you can find them under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`. This step will install `clang`, `clang++`, and `make`. * After building, you may want to setup [firewall rules](tools/macosx-firewall.sh) -to avoid popups asking to accept incoming network connections when running tests: +to avoid popups asking to accept incoming network connections when running +tests: -If the path to your build directory contains a space, the build will likely fail. +If the path to your build directory contains a space, the build will likely +fail. ```console $ sudo ./tools/macosx-firewall.sh @@ -232,8 +234,8 @@ Prerequisites: * **Optional** (to build the MSI): the [WiX Toolset v3.11](http://wixtoolset.org/releases/) and the [Wix Toolset Visual Studio 2017 Extension](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension). -If the path to your build directory contains a space or a non-ASCII character, the -build will likely fail. +If the path to your build directory contains a space or a non-ASCII character, +the build will likely fail. ```console > .\vcbuild diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c4940d44f..cdf10f76f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Node.js Changelog +<!--lint disable maximum-line-length--> + To make the changelog easier to both use and manage, it has been split into multiple files organized according to significant major and minor Node.js release lines. diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 95ef065355..16dff4d3f5 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -154,22 +154,23 @@ The pull request should have a CI status indicator if possible. #### Useful CI Jobs * [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) -is the standard CI run we do to check Pull Requests. It triggers `node-test-commit`, -which runs the `build-ci` and `test-ci` targets on all supported platforms. +is the standard CI run we do to check Pull Requests. It triggers +`node-test-commit`, which runs the `build-ci` and `test-ci` targets on all +supported platforms. * [`node-test-linter`](https://ci.nodejs.org/job/node-test-linter/) -only runs the linter targets, which is useful for changes that only affect comments -or documentation. +only runs the linter targets, which is useful for changes that only affect +comments or documentation. * [`node-test-pull-request-lite`](https://ci.nodejs.org/job/node-test-pull-request-lite/) -only runs the linter job, as well as the tests on LinuxONE. Should only be used for -trivial changes that do not require being tested on all platforms. +only runs the linter job, as well as the tests on LinuxONE. Should only be used +for trivial changes that do not require being tested on all platforms. * [`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/) -uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run `npm install && npm test` -on a large selection of common modules. This is useful to check whether a -change will cause breakage in the ecosystem. To test Node.js ABI changes -you can run [`citgm-abi-smoker`](https://ci.nodejs.org/job/citgm-abi-smoker/). +uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run +`npm install && npm test` on a large selection of common modules. This is +useful to check whether a change will cause breakage in the ecosystem. To test +Node.js ABI changes you can run [`citgm-abi-smoker`](https://ci.nodejs.org/job/citgm-abi-smoker/). * [`node-stress-single-test`](https://ci.nodejs.org/job/node-stress-single-test/) is designed to allow one to run a group of tests over and over on a specific @@ -483,8 +484,8 @@ Apply external patches: $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix ``` -If the merge fails even though recent CI runs were successful, then a 3-way merge may -be required. In this case try: +If the merge fails even though recent CI runs were successful, then a 3-way +merge may be required. In this case try: ```text $ git am --abort @@ -492,8 +493,9 @@ $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace ``` If the 3-way merge succeeds you can proceed, but make sure to check the changes against the original PR carefully and build/test on at least one platform -before landing. If the 3-way merge fails, then it is most likely that a conflicting -PR has landed since the CI run and you will have to ask the author to rebase. +before landing. If the 3-way merge fails, then it is most likely that a +conflicting PR has landed since the CI run and you will have to ask the author +to rebase. Check and re-review the changes: diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 23c1ac8bb5..83d4d9b50a 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -159,9 +159,9 @@ repository, with a summary of the nominee's contributions, for example: * Participation in other projects, teams, and working groups of the Node.js organization * Can be shown using the links - `https://github.com/search?q=author%3A${GITHUB_ID}++org%3Anodejs&type=Issues` + `https://github.com/search?q=author%3A${GITHUB_ID}++org%3Anodejs&type=Issues` and - `https://github.com/search?q=commenter%3A${GITHUB_ID}++org%3Anodejs&type=Issues` +`https://github.com/search?q=commenter%3A${GITHUB_ID}++org%3Anodejs&type=Issues` * Other participation in the wider Node.js community Mention @nodejs/collaborators in the issue to notify other Collaborators about @@ -1,6 +1,10 @@ <p align="center"> <a href="https://nodejs.org/"> - <img alt="Node.js" src="https://nodejs.org/static/images/logo-light.svg" width="400"/> + <img + alt="Node.js" + src="https://nodejs.org/static/images/logo-light.svg" + width="400" + /> </a> </p> diff --git a/doc/api/_toc.md b/doc/api/_toc.md index 420fb362fa..69f89af5ab 100644 --- a/doc/api/_toc.md +++ b/doc/api/_toc.md @@ -1,5 +1,5 @@ -@// NB(chrisdickinson): if you move this file, be sure to update tools/doc/html.js to -@// point at the new location. +@// NB(chrisdickinson): if you move this file, be sure to update +@// tools/doc/html.js to point at the new location. * [About these Docs](documentation.html) * [Usage & Example](synopsis.html) diff --git a/doc/api/assert.md b/doc/api/assert.md index cedbc14d42..5ca1f08308 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -25,9 +25,9 @@ changes: description: Added strict mode to the assert module. --> -When using the `strict mode`, any `assert` function will use the equality used in -the strict function mode. So [`assert.deepEqual()`][] will, for example, work the -same as [`assert.deepStrictEqual()`][]. +When using the `strict mode`, any `assert` function will use the equality used +in the strict function mode. So [`assert.deepEqual()`][] will, for example, +work the same as [`assert.deepStrictEqual()`][]. On top of that, error messages which involve objects produce an error diff instead of displaying both objects. That is not the case for the legacy mode. @@ -209,8 +209,8 @@ changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15036 description: NaN is now compared using the - [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) - comparison. + [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) + comparison. - version: v8.5.0 pr-url: https://github.com/nodejs/node/pull/15001 description: Error names and messages are now properly compared @@ -621,8 +621,8 @@ changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15036 description: NaN is now compared using the - [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) - comparison. + [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) + comparison. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001 description: Error names and messages are now properly compared diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 904c32acdc..ff7b794a30 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -206,8 +206,8 @@ instance is destroyed. * `type` {string} The type of the async resource. * `triggerAsyncId` {number} The unique ID of the async resource in whose execution context this async resource was created. -* `resource` {Object} Reference to the resource representing the async operation, - needs to be released during _destroy_. +* `resource` {Object} Reference to the resource representing the async + operation, needs to be released during _destroy_. Called when a class is constructed that has the _possibility_ to emit an asynchronous event. This _does not_ mean the instance must call @@ -283,11 +283,11 @@ The `TCPSERVERWRAP` is the server which receives the connections. The `TCPWRAP` is the new connection from the client. When a new connection is made the `TCPWrap` instance is immediately constructed. This -happens outside of any JavaScript stack (side note: a `executionAsyncId()` of `0` -means it's being executed from C++, with no JavaScript stack above it). +happens outside of any JavaScript stack (side note: a `executionAsyncId()` of +`0` means it's being executed from C++, with no JavaScript stack above it). With only that information, it would be impossible to link resources together in -terms of what caused them to be created, so `triggerAsyncId` is given the task of -propagating what resource is responsible for the new resource's existence. +terms of what caused them to be created, so `triggerAsyncId` is given the task +of propagating what resource is responsible for the new resource's existence. ###### `resource` @@ -582,8 +582,8 @@ the details of the V8 [PromiseHooks][] 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 `AsyncWrap` -JavaScript API so that all the appropriate callbacks are called. +like I/O, connection pooling, or managing callback queues may use the +`AsyncWrap` JavaScript API so that all the appropriate callbacks are called. ### `class AsyncResource()` @@ -734,8 +734,8 @@ never be called. #### `asyncResource.triggerAsyncId()` -* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource` -constructor. +* Returns: {number} The same `triggerAsyncId` that is passed to the +`AsyncResource` constructor. [`after` callback]: #async_hooks_after_asyncid [`asyncResource.runInAsyncScope()`]: #async_hooks_asyncresource_runinasyncscope_fn_thisarg_args diff --git a/doc/api/buffer.md b/doc/api/buffer.md index e1911d6714..225726316a 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1,6 +1,7 @@ # Buffer <!--introduced_in=v0.10.0--> +<!--lint disable maximum-line-length--> > Stability: 2 - Stable diff --git a/doc/api/child_process.md b/doc/api/child_process.md index ac794e6a23..57a0f9296a 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,6 +1,7 @@ # Child Process <!--introduced_in=v0.10.0--> +<!--lint disable maximum-line-length--> > Stability: 2 - Stable diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 11be4d34d5..08a669e4fa 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -269,8 +269,8 @@ changes: * Returns: {cluster.Worker} A reference to `worker`. -In a worker, this function will close all servers, wait for the `'close'` event on -those servers, and then disconnect the IPC channel. +In a worker, this function will close all servers, wait for the `'close'` event +on those servers, and then disconnect the IPC channel. In the master, an internal message is sent to the worker causing it to call `.disconnect()` on itself. @@ -280,8 +280,8 @@ Causes `.exitedAfterDisconnect` to be set. Note that after a server is closed, it will no longer accept new connections, but connections may be accepted by any other listening worker. Existing connections will be allowed to close as usual. When no more connections exist, -see [`server.close()`][], the IPC channel to the worker will close allowing it to -die gracefully. +see [`server.close()`][], the IPC channel to the worker will close allowing it +to die gracefully. The above applies *only* to server connections, client connections are not automatically closed by workers, and disconnect does not wait for them to close @@ -465,9 +465,9 @@ Emitted after the worker IPC channel has disconnected. This can occur when a worker exits gracefully, is killed, or is disconnected manually (such as with worker.disconnect()). -There may be a delay between the `'disconnect'` and `'exit'` events. These events -can be used to detect if the process is stuck in a cleanup or if there are -long-living connections. +There may be a delay between the `'disconnect'` and `'exit'` events. These +events can be used to detect if the process is stuck in a cleanup or if there +are long-living connections. ```js cluster.on('disconnect', (worker) => { @@ -639,7 +639,8 @@ Calls `.disconnect()` on each worker in `cluster.workers`. When they are disconnected all internal handles will be closed, allowing the master process to die gracefully if no other event is waiting. -The method takes an optional callback argument which will be called when finished. +The method takes an optional callback argument which will be called when +finished. This can only be called from the master process. diff --git a/doc/api/console.md b/doc/api/console.md index 473c37ea04..1bd595f4b9 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -411,7 +411,8 @@ added: v8.0.0 * `label` {string} Defaults to `'default'`. This method does not display anything unless used in the inspector. The -`console.markTimeline()` method is the deprecated form of [`console.timeStamp()`][]. +`console.markTimeline()` method is the deprecated form of +[`console.timeStamp()`][]. ### console.profile([label]) <!-- YAML @@ -476,7 +477,8 @@ added: v8.0.0 * `label` {string} Defaults to `'default'`. This method does not display anything unless used in the inspector. The -`console.timelineEnd()` method is the deprecated form of [`console.timeEnd()`][]. +`console.timelineEnd()` method is the deprecated form of +[`console.timeEnd()`][]. [`console.error()`]: #console_console_error_data_args [`console.group()`]: #console_console_group_label diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e378b3705a..94e7dcd157 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1245,8 +1245,8 @@ added: v6.0.0 deprecated: REPLACEME --> -Property for checking and controlling whether a FIPS compliant crypto provider is -currently in use. Setting to true requires a FIPS build of Node.js. +Property for checking and controlling whether a FIPS compliant crypto provider +is currently in use. Setting to true requires a FIPS build of Node.js. This property is deprecated. Please use `crypto.setFips()` and `crypto.getFips()` instead. @@ -1301,7 +1301,8 @@ changes: - `options` {Object} [`stream.transform` options][] Creates and returns a `Cipher` object, with the given `algorithm`, `key` and -initialization vector (`iv`). Optional `options` argument controls stream behavior. +initialization vector (`iv`). Optional `options` argument controls stream +behavior. The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1397,7 +1398,8 @@ changes: --> - `prime` {string | Buffer | TypedArray | DataView} - `primeEncoding` {string} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to + `2`. - `generatorEncoding` {string} Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1420,7 +1422,8 @@ otherwise a number, [`Buffer`][], `TypedArray`, or `DataView` is expected. added: v0.5.0 --> - `primeLength` {number} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to + `2`. Creates a `DiffieHellman` key exchange object and generates a prime of `primeLength` bits using an optional specific numeric `generator`. diff --git a/doc/api/debugger.md b/doc/api/debugger.md index b0da263f59..00dda306d0 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -8,8 +8,8 @@ Node.js includes an out-of-process debugging utility accessible via a [V8 Inspector][] and built-in debugging client. To use it, start Node.js -with the `inspect` argument followed by the path to the script to debug; a prompt -will be displayed indicating successful launch of the debugger: +with the `inspect` argument followed by the path to the script to debug; a +prompt will be displayed indicating successful launch of the debugger: ```txt $ node inspect myscript.js @@ -173,7 +173,8 @@ breakpoint) ### V8 Inspector Integration for Node.js V8 Inspector integration allows attaching Chrome DevTools to Node.js -instances for debugging and profiling. It uses the [Chrome Debugging Protocol][]. +instances for debugging and profiling. It uses the +[Chrome Debugging Protocol][]. V8 Inspector can be enabled by passing the `--inspect` flag when starting a Node.js application. It is also possible to supply a custom port with that flag, diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index cf1e97397a..0259bd4625 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -82,16 +82,16 @@ is strongly recommended: * [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with *initialized* memory. -* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with *uninitialized* - memory. +* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with + *uninitialized* memory. * [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized* memory. * [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array` -* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - Create a `Buffer` - that wraps the given `arrayBuffer`. +* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - + Create a `Buffer` that wraps the given `arrayBuffer`. * [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`. -* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` that copies - `string`. +* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` + that copies `string`. <a id="DEP0006"></a> ### DEP0006: child\_process options.customFds @@ -699,7 +699,8 @@ Type: Runtime `Module._debug()` has been deprecated. -The `Module._debug()` function was never documented as an officially supported API. +The `Module._debug()` function was never documented as an officially +supported API. <a id="DEP0078"></a> ### DEP0078: REPLServer.turnOffEditorMode() @@ -863,14 +864,16 @@ to one of the other assert methods. Type: Runtime -`timers.enroll()` is deprecated. Please use the publicly documented [`setTimeout()`][] or [`setInterval()`][] instead. +`timers.enroll()` is deprecated. Please use the publicly documented +[`setTimeout()`][] or [`setInterval()`][] instead. <a id="DEP0096"></a> ### DEP0096: timers.unenroll() Type: Runtime -`timers.unenroll()` is deprecated. Please use the publicly documented [`clearTimeout()`][] or [`clearInterval()`][] instead. +`timers.unenroll()` is deprecated. Please use the publicly documented +[`clearTimeout()`][] or [`clearInterval()`][] instead. <a id="DEP0097"></a> ### DEP0097: MakeCallback with domain property diff --git a/doc/api/dgram.md b/doc/api/dgram.md index e44bf3eea5..9209b83a12 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -394,8 +394,8 @@ added: v8.6.0 *Note: All references to scope in this section are referring to [IPv6 Zone Indices][], which are defined by [RFC 4007][]. In string form, an IP -with a scope index is written as `'IP%scope'` where scope is an interface name or -interface number.* +with a scope index is written as `'IP%scope'` where scope is an interface name +or interface number.* Sets the default outgoing multicast interface of the socket to a chosen interface or back to system interface selection. The `multicastInterface` must diff --git a/doc/api/dns.md b/doc/api/dns.md index cda4823e3c..fa7c34f654 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -143,8 +143,8 @@ changes: - `verbatim` {boolean} When `true`, the callback receives IPv4 and IPv6 addresses in the order the DNS resolver returned them. When `false`, IPv4 addresses are placed before IPv6 addresses. - **Default:** currently `false` (addresses are reordered) but this is expected - to change in the not too distant future. + **Default:** currently `false` (addresses are reordered) but this is + expected to change in the not too distant future. New code should use `{ verbatim: true }`. - `callback` {Function} - `err` {Error} diff --git a/doc/api/documentation.md b/doc/api/documentation.md index c2413d33db..a864771f44 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -85,8 +85,8 @@ like [`fs.open()`][], will document that. The docs link to the corresponding man pages (short for manual pages) which describe how the syscalls work. Some syscalls, like lchown(2), are BSD-specific. That means, for -example, that [`fs.lchown()`][] only works on macOS and other BSD-derived systems, -and is not available on Linux. +example, that [`fs.lchown()`][] only works on macOS and other BSD-derived +systems, and is not available on Linux. Most Unix syscalls have Windows equivalents, but behavior may differ on Windows relative to Linux and macOS. For an example of the subtle ways in which it's diff --git a/doc/api/domain.md b/doc/api/domain.md index b303b0fdeb..a9ca7f2d27 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -337,9 +337,9 @@ d.on('error', (er) => { The `enter` method is plumbing used by the `run`, `bind`, and `intercept` methods to set the active domain. It sets `domain.active` and `process.domain` to the domain, and implicitly pushes the domain onto the domain stack managed -by the domain module (see [`domain.exit()`][] for details on the domain stack). The -call to `enter` delimits the beginning of a chain of asynchronous calls and I/O -operations bound to a domain. +by the domain module (see [`domain.exit()`][] for details on the domain stack). +The call to `enter` delimits the beginning of a chain of asynchronous calls and +I/O operations bound to a domain. Calling `enter` changes only the active domain, and does not alter the domain itself. `enter` and `exit` can be called an arbitrary number of times on a diff --git a/doc/api/errors.md b/doc/api/errors.md index c2475df1eb..b9c52ad0d9 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -227,7 +227,8 @@ Error.captureStackTrace(myObject); myObject.stack; // similar to `new Error().stack` ``` -The first line of the trace will be prefixed with `${myObject.name}: ${myObject.message}`. +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. The optional `constructorOpt` argument accepts a function. If given, all frames above `constructorOpt`, including `constructorOpt`, will be omitted from the @@ -1321,7 +1322,8 @@ An attempt was made to `require()` an [ES6 module][]. <a id="ERR_SCRIPT_EXECUTION_INTERRUPTED"></a> ### ERR_SCRIPT_EXECUTION_INTERRUPTED -Script execution was interrupted by `SIGINT` (For example, when Ctrl+C was pressed). +Script execution was interrupted by `SIGINT` (For example, when Ctrl+C was +pressed). <a id="ERR_SERVER_ALREADY_LISTEN"></a> ### ERR_SERVER_ALREADY_LISTEN diff --git a/doc/api/esm.md b/doc/api/esm.md index 2a56433295..adde6a199f 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -130,7 +130,8 @@ export async function resolve(specifier, } ``` -The parentURL is provided as `undefined` when performing main Node.js load itself. +The parentURL is provided as `undefined` when performing main Node.js load +itself. The default Node.js ES module resolution function is provided as a third argument to the resolver for easy compatibility workflows. diff --git a/doc/api/events.md b/doc/api/events.md index 7b510fac05..afea4f443c 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -515,10 +515,10 @@ listener array for the specified `eventName`, then `removeListener` must be called multiple times to remove each instance. Note that once an event has been emitted, all listeners attached to it at the -time of emitting will be called in order. This implies that any `removeListener()` -or `removeAllListeners()` calls *after* emitting and *before* the last listener -finishes execution will not remove them from `emit()` in progress. Subsequent -events will behave as expected. +time of emitting will be called in order. This implies that any +`removeListener()` or `removeAllListeners()` calls *after* emitting and +*before* the last listener finishes execution will not remove them from +`emit()` in progress. Subsequent events will behave as expected. ```js const myEmitter = new MyEmitter(); diff --git a/doc/api/fs.md b/doc/api/fs.md index 5062f76ff1..27650c42cd 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -2888,9 +2888,9 @@ directory. The returned object is a [`fs.FSWatcher`][]. The second argument is optional. If `options` is provided as a string, it specifies the `encoding`. Otherwise `options` should be passed as an object. -The listener callback gets two arguments `(eventType, filename)`. `eventType` is either -`'rename'` or `'change'`, and `filename` is the name of the file which triggered -the event. +The listener callback gets two arguments `(eventType, filename)`. `eventType` +is either `'rename'` or `'change'`, and `filename` is the name of the file +which triggered the event. Note that on most platforms, `'rename'` is emitted whenever a filename appears or disappears in the directory. @@ -3367,8 +3367,8 @@ and the file position will be updated. If `position` is an integer, the file position will remain unchanged. Following successful read, the `Promise` is resolved with an object with a -`bytesRead` property specifying the number of bytes read, and a `buffer` property -that is a reference to the passed in `buffer` argument. +`bytesRead` property specifying the number of bytes read, and a `buffer` +property that is a reference to the passed in `buffer` argument. #### filehandle.readFile(options) <!-- YAML @@ -3985,8 +3985,8 @@ and the file position will be updated. If `position` is an integer, the file position will remain unchanged. Following successful read, the `Promise` is resolved with an object with a -`bytesRead` property specifying the number of bytes read, and a `buffer` property -that is a reference to the passed in `buffer` argument. +`bytesRead` property specifying the number of bytes read, and a `buffer` +property that is a reference to the passed in `buffer` argument. ### fsPromises.readdir(path[, options]) <!-- YAML diff --git a/doc/api/http.md b/doc/api/http.md index c496897a73..91309e79fd 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -225,7 +225,8 @@ added: v0.11.4 --> * `options` {Object} A set of options providing information for name generation - * `host` {string} A domain name or IP address of the server to issue the request to + * `host` {string} A domain name or IP address of the server to issue the + request to * `port` {number} Port of remote server * `localAddress` {string} Local interface to bind for network connections when issuing the request @@ -330,9 +331,9 @@ added: v0.7.0 * `socket` {net.Socket} * `head` {Buffer} -Emitted each time a server responds to a request with a `CONNECT` method. If this -event is not being listened for, clients receiving a `CONNECT` method will have -their connections closed. +Emitted each time a server responds to a request with a `CONNECT` method. If +this event is not being listened for, clients receiving a `CONNECT` method will +have their connections closed. A client and server pair demonstrating how to listen for the `'connect'` event: @@ -659,7 +660,8 @@ added: v0.5.9 --> * `timeout` {number} Milliseconds before a request times out. -* `callback` {Function} Optional function to be called when a timeout occurs. Same as binding to the `timeout` event. +* `callback` {Function} Optional function to be called when a timeout occurs. + Same as binding to the `timeout` event. Once a socket is assigned to this request and is connected [`socket.setTimeout()`][] will be called. @@ -726,7 +728,8 @@ buffer. Returns `false` if all or part of the data was queued in user memory. added: v0.1.17 --> -This class inherits from [`net.Server`][] and has the following additional events: +This class inherits from [`net.Server`][] and has the following additional +events: ### Event: 'checkContinue' <!-- YAML @@ -740,10 +743,10 @@ Emitted each time a request with an HTTP `Expect: 100-continue` is received. If this event is not listened for, the server will automatically respond with a `100 Continue` as appropriate. -Handling this event involves calling [`response.writeContinue()`][] if the client -should continue to send the request body, or generating an appropriate HTTP -response (e.g. 400 Bad Request) if the client should not continue to send the -request body. +Handling this event involves calling [`response.writeContinue()`][] if the +client should continue to send the request body, or generating an appropriate +HTTP response (e.g. 400 Bad Request) if the client should not continue to send +the request body. Note that when this event is emitted and handled, the [`'request'`][] event will not be emitted. @@ -968,9 +971,10 @@ will be destroyed. If the server receives new data before the keep-alive timeout has fired, it will reset the regular inactivity timeout, i.e., [`server.timeout`][]. -A value of `0` will disable the keep-alive timeout behavior on incoming connections. -A value of `0` makes the http server behave similarly to Node.js versions prior to 8.0.0, -which did not have a keep-alive timeout. +A value of `0` will disable the keep-alive timeout behavior on incoming +connections. +A value of `0` makes the http server behave similarly to Node.js versions prior +to 8.0.0, which did not have a keep-alive timeout. The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. @@ -1224,9 +1228,9 @@ response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. -When headers have been set with [`response.setHeader()`][], they will be merged with -any headers passed to [`response.writeHead()`][], with the headers passed to -[`response.writeHead()`][] given precedence. +When headers have been set with [`response.setHeader()`][], they will be merged +with any headers passed to [`response.writeHead()`][], with the headers passed +to [`response.writeHead()`][] given precedence. ```js // returns content-type = text/plain @@ -1308,10 +1312,10 @@ added: v0.11.8 * {string} -When using implicit headers (not calling [`response.writeHead()`][] explicitly), this property -controls the status message that will be sent to the client when the headers get -flushed. If this is left as `undefined` then the standard message for the status -code will be used. +When using implicit headers (not calling [`response.writeHead()`][] explicitly), +this property controls the status message that will be sent to the client when +the headers get flushed. If this is left as `undefined` then the standard +message for the status code will be used. Example: @@ -1366,7 +1370,8 @@ added: v0.3.0 --> Sends a HTTP/1.1 100 Continue message to the client, indicating that -the request body should be sent. See the [`'checkContinue'`][] event on `Server`. +the request body should be sent. See the [`'checkContinue'`][] event on +`Server`. ### response.writeHead(statusCode[, statusMessage][, headers]) <!-- YAML @@ -1402,9 +1407,9 @@ be called before [`response.end()`][] is called. If [`response.write()`][] or [`response.end()`][] are called before calling this, the implicit/mutable headers will be calculated and call this function. -When headers have been set with [`response.setHeader()`][], they will be merged with -any headers passed to [`response.writeHead()`][], with the headers passed to -[`response.writeHead()`][] given precedence. +When headers have been set with [`response.setHeader()`][], they will be merged +with any headers passed to [`response.writeHead()`][], with the headers passed +to [`response.writeHead()`][] given precedence. ```js // returns content-type = text/plain @@ -1441,8 +1446,8 @@ added: v0.1.17 An `IncomingMessage` object is created by [`http.Server`][] or [`http.ClientRequest`][] and passed as the first argument to the [`'request'`][] -and [`'response'`][] event respectively. It may be used to access response status, -headers and data. +and [`'response'`][] event respectively. It may be used to access response +status, headers and data. It implements the [Readable Stream][] interface, as well as the following additional events, methods, and properties. @@ -1613,7 +1618,8 @@ added: v0.11.10 **Only valid for response obtained from [`http.ClientRequest`][].** -The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. +The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server +Error`. ### message.trailers <!-- YAML @@ -1840,7 +1846,8 @@ changes: * `headers` {Object} An object containing request headers. * `auth` {string} Basic authentication i.e. `'user:password'` to compute an Authorization header. - * `agent` {http.Agent | boolean} Controls [`Agent`][] behavior. Possible values: + * `agent` {http.Agent | boolean} Controls [`Agent`][] behavior. Possible + values: * `undefined` (default): use [`http.globalAgent`][] for this host and port. * `Agent` object: explicitly use the passed in `Agent`. * `false`: causes a new `Agent` with default values to be used. diff --git a/doc/api/http2.md b/doc/api/http2.md index 78e4d9609a..14dae38b49 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1452,10 +1452,10 @@ a request with an HTTP `Expect: 100-continue` is received. If this event is not listened for, the server will automatically respond with a status `100 Continue` as appropriate. -Handling this event involves calling [`response.writeContinue()`][] if the client -should continue to send the request body, or generating an appropriate HTTP -response (e.g. 400 Bad Request) if the client should not continue to send the -request body. +Handling this event involves calling [`response.writeContinue()`][] if the +client should continue to send the request body, or generating an appropriate +HTTP response (e.g. 400 Bad Request) if the client should not continue to send +the request body. Note that when this event is emitted and handled, the [`'request'`][] event will not be emitted. @@ -1555,10 +1555,10 @@ time a request with an HTTP `Expect: 100-continue` is received. If this event is not listened for, the server will automatically respond with a status `100 Continue` as appropriate. -Handling this event involves calling [`response.writeContinue()`][] if the client -should continue to send the request body, or generating an appropriate HTTP -response (e.g. 400 Bad Request) if the client should not continue to send the -request body. +Handling this event involves calling [`response.writeContinue()`][] if the +client should continue to send the request body, or generating an appropriate +HTTP response (e.g. 400 Bad Request) if the client should not continue to send +the request body. Note that when this event is emitted and handled, the [`'request'`][] event will not be emitted. diff --git a/doc/api/https.md b/doc/api/https.md index da4dbb22ab..8c95487cb5 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -12,8 +12,8 @@ separate module. added: v0.4.5 --> -An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] -for more information. +An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See +[`https.request()`][] for more information. ## Class: https.Server <!-- YAML @@ -158,8 +158,8 @@ changes: pr-url: https://github.com/nodejs/node/pull/10638 description: The `options` parameter can be a WHATWG `URL` object. --> -- `options` {Object | string | URL} Accepts all `options` from [`http.request()`][], - with some differences in default values: +- `options` {Object | string | URL} Accepts all `options` from + [`http.request()`][], with some differences in default values: - `protocol` Defaults to `https:` - `port` Defaults to `443`. - `agent` Defaults to `https.globalAgent`. @@ -251,7 +251,8 @@ const req = https.request(options, (res) => { }); ``` -Example pinning on certificate fingerprint, or the public key (similar to `pin-sha256`): +Example pinning on certificate fingerprint, or the public key (similar to +`pin-sha256`): ```js const tls = require('tls'); diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 8da4c3e2d5..ff470acfe1 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -139,9 +139,9 @@ create a scope before invoking any functions that can result in the creation of JavaScript values. Handle scopes are created using [`napi_open_handle_scope`][] and are destroyed -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. +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][]. @@ -646,7 +646,8 @@ current scope and the lifespan of the handle changes from the current scope to that of the outer scope. The methods available to open/close escapable scopes are -[`napi_open_escapable_handle_scope`][] and [`napi_close_escapable_handle_scope`][]. +[`napi_open_escapable_handle_scope`][] and +[`napi_close_escapable_handle_scope`][]. The request to promote a handle is made through [`napi_escape_handle`][] which can only be called once. @@ -1342,8 +1343,8 @@ TypedArray objects provide an array-like view over an underlying data buffer where each element has the same underlying binary scalar datatype. It's required that (length * size_of_element) + byte_offset should -be <= the size in bytes of the array passed in. If not, a RangeError exception is -raised. +be <= the size in bytes of the array passed in. If not, a RangeError exception +is raised. JavaScript TypedArray Objects are described in [Section 22.2][] of the ECMAScript Language Specification. @@ -1588,10 +1589,11 @@ its length. *WARNING*: Use caution while using this API. The lifetime of the underlying data buffer is managed by the ArrayBuffer even after it's returned. A -possible safe way to use this API is in conjunction with [`napi_create_reference`][], -which can be used to guarantee control over the lifetime of the -ArrayBuffer. It's also safe to use the returned data buffer within the same -callback as long as there are no calls to other APIs that might trigger a GC. +possible safe way to use this API is in conjunction with +[`napi_create_reference`][], which can be used to guarantee control over the +lifetime of the ArrayBuffer. It's also safe to use the returned data buffer +within the same callback as long as there are no calls to other APIs that might +trigger a GC. #### napi_get_buffer_info <!-- YAML @@ -1870,8 +1872,8 @@ napi_status napi_get_value_string_utf16(napi_env env, passed in, the length of the string (in 2-byte code units) is returned. - `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -- `[out] result`: Number of 2-byte code units copied into the buffer, excluding the null -terminator. +- `[out] result`: Number of 2-byte code units copied into the buffer, excluding +the null terminator. Returns `napi_ok` if the API succeeded. If a non-String `napi_value` is passed in it returns `napi_string_expected`. @@ -2733,8 +2735,8 @@ Returns `napi_ok` if the API succeeded. This method allows the efficient definition of multiple properties on a given object. The properties are defined using property descriptors (See -[`napi_property_descriptor`][]). Given an array of such property descriptors, this -API will set the properties on the object one at a time, as defined by +[`napi_property_descriptor`][]). Given an array of such property descriptors, +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 ECMA262 specification). ## Working with JavaScript Functions @@ -3145,8 +3147,8 @@ This API may modify the prototype chain of the wrapper object. Afterward, additional manipulation of the wrapper's prototype chain may cause `napi_unwrap()` to fail. -Calling napi_wrap() a second time on an object will return an error. To associate -another native instance with the object, use napi_remove_wrap() first. +Calling napi_wrap() a second time on an object will return an error. To +associate another native instance with the object, use napi_remove_wrap() first. ### napi_unwrap <!-- YAML diff --git a/doc/api/net.md b/doc/api/net.md index 6e2b7386b3..489659001c 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -1,6 +1,7 @@ # Net <!--introduced_in=v0.10.0--> +<!--lint disable maximum-line-length--> > Stability: 2 - Stable diff --git a/doc/api/process.md b/doc/api/process.md index 8209a07d72..6015bb2cc4 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -193,9 +193,10 @@ of allocated resources (e.g. file descriptors, handles, etc) before shutting down the process. **It is not safe to resume normal operation after `'uncaughtException'`.** -To restart a crashed application in a more reliable way, whether `uncaughtException` -is emitted or not, an external monitor should be employed in a separate process -to detect application failures and recover or restart as needed. +To restart a crashed application in a more reliable way, whether +`uncaughtException` is emitted or not, an external monitor should be employed +in a separate process to detect application failures and recover or restart as +needed. ### Event: 'unhandledRejection' <!-- YAML @@ -379,8 +380,8 @@ process.on('SIGTERM', handle); installed its default behavior will be removed. * `SIGTERM` is not supported on Windows, it can be listened on. * `SIGINT` from the terminal is supported on all platforms, and can usually be - generated with `<Ctrl>+C` (though this may be configurable). It is not generated - when terminal raw mode is enabled. + generated with `<Ctrl>+C` (though this may be configurable). It is not + generated when terminal raw mode is enabled. * `SIGBREAK` is delivered on Windows when `<Ctrl>+<Break>` is pressed, on non-Windows platforms it can be listened on, but there is no way to send or generate it. @@ -416,8 +417,8 @@ added: v0.5.0 * {string} -The `process.arch` property returns a string identifying the operating system CPU -architecture for which the Node.js binary was compiled. +The `process.arch` property returns a string identifying the operating system +CPU architecture for which the Node.js binary was compiled. The current possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'mips'`, `'mipsel'`, `'ppc'`, `'ppc64'`, `'s390'`, `'s390x'`, `'x32'`, and `'x64'`. @@ -1614,8 +1615,8 @@ added: v0.9.4 * `groups` {Array} The `process.setgroups()` method sets the supplementary group IDs for the -Node.js process. This is a privileged operation that requires the Node.js process -to have `root` or the `CAP_SETGID` capability. +Node.js process. This is a privileged operation that requires the Node.js +process to have `root` or the `CAP_SETGID` capability. The `groups` array can contain numeric group IDs, group names or both. diff --git a/doc/api/readline.md b/doc/api/readline.md index 69c49b10ea..2d6731ddb2 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -350,24 +350,26 @@ changes: --> * `options` {Object} - * `input` {stream.Readable} The [Readable][] stream to listen to. This option is - *required*. - * `output` {stream.Writable} The [Writable][] stream to write readline data to. + * `input` {stream.Readable} The [Readable][] stream to listen to. This option + is *required*. + * `output` {stream.Writable} The [Writable][] stream to write readline data + to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Defaults to checking `isTTY` on the `output` stream upon instantiation. * `historySize` {number} Maximum number of history lines retained. To disable - the history set this value to `0`. This option makes sense only if `terminal` - is set to `true` by the user or by an internal `output` check, otherwise the - history caching mechanism is not initialized at all. **Default:** `30` + the history set this value to `0`. This option makes sense only if + `terminal` is set to `true` by the user or by an internal `output` check, + otherwise the history caching mechanism is not initialized at all. + **Default:** `30` * `prompt` {string} The prompt string to use. **Default:** `'> '` * `crlfDelay` {number} If the delay between `\r` and `\n` exceeds `crlfDelay` milliseconds, both `\r` and `\n` will be treated as separate - end-of-line input. `crlfDelay` will be coerced to a number no less than `100`. - It can be set to `Infinity`, in which case `\r` followed by `\n` will always be - considered a single newline (which may be reasonable for [reading files][] - with `\r\n` line delimiter). **Default:** `100` + end-of-line input. `crlfDelay` will be coerced to a number no less than + `100`. It can be set to `Infinity`, in which case `\r` followed by `\n` + will always be considered a single newline (which may be reasonable for + [reading files][] with `\r\n` line delimiter). **Default:** `100` * `removeHistoryDuplicates` {boolean} If `true`, when a new input line added to the history list duplicates an older one, this removes the older line from the list. **Default:** `false` diff --git a/doc/api/repl.md b/doc/api/repl.md index 916d6bd0e2..873e7449f5 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -412,8 +412,8 @@ changes: * `options` {Object|string} * `prompt` {string} The input prompt to display. Defaults to `> ` (with a trailing space). - * `input` {stream.Readable} The Readable stream from which REPL input will be read. - Defaults to `process.stdin`. + * `input` {stream.Readable} The Readable stream from which REPL input will be + read. Defaults to `process.stdin`. * `output` {stream.Writable} The Writable stream to which REPL output will be written. Defaults to `process.stdout`. * `terminal` {boolean} If `true`, specifies that the `output` should be diff --git a/doc/api/stream.md b/doc/api/stream.md index 85afb631ae..4cb9907202 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -424,8 +424,8 @@ stream.write('data '); process.nextTick(() => stream.uncork()); ``` -If the [`writable.cork()`][] method is called multiple times on a stream, the same -number of calls to `writable.uncork()` must be called to flush the buffered +If the [`writable.cork()`][] method is called multiple times on a stream, the +same number of calls to `writable.uncork()` must be called to flush the buffered data. ```js @@ -620,8 +620,8 @@ possible states: When `readable.readableFlowing` is `null`, no mechanism for consuming the streams data is provided so the stream will not generate its data. While in this -state, attaching a listener for the `'data'` event, calling the `readable.pipe()` -method, or calling the `readable.resume()` method will switch +state, attaching a listener for the `'data'` event, calling the +`readable.pipe()` method, or calling the `readable.resume()` method will switch `readable.readableFlowing` to `true`, causing the Readable to begin actively emitting events as data is generated. @@ -1193,8 +1193,9 @@ async function print(readable) { print(fs.createReadStream('file')).catch(console.log); ``` -If the loop terminates with a `break` or a `throw`, the stream will be destroyed. -In other terms, iterating over a stream will consume the stream fully. +If the loop terminates with a `break` or a `throw`, the stream will be +destroyed. In other terms, iterating over a stream will consume the stream +fully. ### Duplex and Transform Streams @@ -1305,8 +1306,11 @@ on the type of stream being created, as detailed in the chart below: <p>[Writable](#stream_class_stream_writable)</p> </td> <td> - <p><code>[_write][stream-_write]</code>, <code>[_writev][stream-_writev]</code>, - <code>[_final][stream-_final]</code></p> + <p> + <code>[_write][stream-_write]</code>, + <code>[_writev][stream-_writev]</code>, + <code>[_final][stream-_final]</code> + </p> </td> </tr> <tr> @@ -1317,8 +1321,11 @@ on the type of stream being created, as detailed in the chart below: <p>[Duplex](#stream_class_stream_duplex)</p> </td> <td> - <p><code>[_read][stream-_read]</code>, <code>[_write][stream-_write]</code>, <code>[_writev][stream-_writev]</code>, - <code>[_final][stream-_final]</code></p> + <p> + <code>[_read][stream-_read]</code>, + <code>[_write][stream-_write]</code>, + <code>[_writev][stream-_writev]</code>, + <code>[_final][stream-_final]</code></p> </td> </tr> <tr> @@ -1329,8 +1336,11 @@ on the type of stream being created, as detailed in the chart below: <p>[Transform](#stream_class_stream_transform)</p> </td> <td> - <p><code>[_transform][stream-_transform]</code>, <code>[_flush][stream-_flush]</code>, - <code>[_final][stream-_final]</code></p> + <p> + <code>[_transform][stream-_transform]</code>, + <code>[_flush][stream-_flush]</code>, + <code>[_final][stream-_final]</code> + </p> </td> </tr> </table> @@ -1636,8 +1646,8 @@ constructor and implement the `readable._read()` method. a single value instead of a Buffer of size n. Defaults to `false` * `read` {Function} Implementation for the [`stream._read()`][stream-_read] method. - * `destroy` {Function} Implementation for the [`stream._destroy()`][readable-_destroy] - method. + * `destroy` {Function} Implementation for the + [`stream._destroy()`][readable-_destroy] method. ```js const { Readable } = require('stream'); diff --git a/doc/api/tls.md b/doc/api/tls.md index 5cdab4cbd3..0cfab387f2 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -710,8 +710,8 @@ added: v0.11.8 --> * `options` {Object} - * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified - against the list of supplied CAs. An `'error'` event is emitted if + * `rejectUnauthorized` {boolean} If not `false`, the server certificate is + verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. Defaults to `true`. * `requestCert` @@ -831,8 +831,8 @@ changes: connection/disconnection/destruction of `socket` is the user's responsibility, calling `tls.connect()` will not cause `net.connect()` to be called. - * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified - against the list of supplied CAs. An `'error'` event is emitted if + * `rejectUnauthorized` {boolean} If not `false`, the server certificate is + verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. Defaults to `true`. * `NPNProtocols` {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} @@ -986,7 +986,8 @@ changes: as an array of unencrypted PFX buffers, or an array of objects in the form `{buf: <string|buffer>[, passphrase: <string>]}`. The object form can only occur in an array. `object.passphrase` is optional. Encrypted PFX will be - decrypted with `object.passphrase` if provided, or `options.passphrase` if it is not. + decrypted with `object.passphrase` if provided, or `options.passphrase` if + it is not. * `key` {string|string[]|Buffer|Buffer[]|Object[]} Optional private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with `options.passphrase`. Multiple keys using @@ -1220,7 +1221,8 @@ added: v0.11.13 --> The default curve name to use for ECDH key agreement in a tls server. The -default value is `'auto'`. See [`tls.createSecureContext()`] for further information. +default value is `'auto'`. See [`tls.createSecureContext()`] for further +information. ## Deprecated APIs @@ -1287,8 +1289,8 @@ changes: opened as a server. * `requestCert` {boolean} `true` to specify whether a server should request a certificate from a connecting client. Only applies when `isServer` is `true`. -* `rejectUnauthorized` {boolean} If not `false` a server automatically reject clients - with invalid certificates. Only applies when `isServer` is `true`. +* `rejectUnauthorized` {boolean} If not `false` a server automatically reject + clients with invalid certificates. Only applies when `isServer` is `true`. * `options` * `secureContext`: An optional TLS context object from [`tls.createSecureContext()`][] diff --git a/doc/api/tracing.md b/doc/api/tracing.md index fbfa2941ef..67b3394d55 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -5,12 +5,13 @@ Trace Event provides a mechanism to centralize tracing information generated by V8, Node core, and userspace code. -Tracing can be enabled by passing the `--trace-events-enabled` flag when starting a -Node.js application. +Tracing can be enabled by passing the `--trace-events-enabled` flag when +starting a Node.js application. The set of categories for which traces are recorded can be specified using the -`--trace-event-categories` flag followed by a list of comma separated category names. -By default the `node`, `node.async_hooks`, and `v8` categories are enabled. +`--trace-event-categories` flag followed by a list of comma separated category +names. By default the `node`, `node.async_hooks`, and `v8` categories are +enabled. ```txt node --trace-events-enabled --trace-event-categories v8,node,node.async_hooks server.js diff --git a/doc/api/util.md b/doc/api/util.md index dd5620c480..ae4094b73a 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -107,7 +107,8 @@ const debuglog = util.debuglog('foo-bar'); debuglog('hi there, it\'s foo-bar [%d]', 2333); ``` -if it is run with `NODE_DEBUG=foo*` in the environment, then it will output something like: +if it is run with `NODE_DEBUG=foo*` in the environment, then it will output +something like: ```txt FOO-BAR 3257: hi there, it's foo-bar [2333] ``` @@ -206,8 +207,9 @@ corresponding argument. Supported placeholders are: contains circular references. * `%o` - Object. A string representation of an object with generic JavaScript object formatting. - Similar to `util.inspect()` with options `{ showHidden: true, showProxy: true }`. - This will show the full object including non-enumerable properties and proxies. + Similar to `util.inspect()` with options + `{ showHidden: true, showProxy: true }`. This will show the full object + including non-enumerable properties and proxies. * `%O` - Object. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` without options. This will show the full object not including non-enumerable properties and proxies. @@ -400,8 +402,8 @@ The `util.inspect()` method returns a string representation of `object` that is intended for debugging. The output of `util.inspect` may change at any time and should not be depended upon programmatically. Additional `options` may be passed that alter certain aspects of the formatted string. -`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make an -identifiable tag for an inspected value. +`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make +an identifiable tag for an inspected value. ```js class Foo { @@ -702,7 +704,8 @@ console.log(promisified === doSomething[util.promisify.custom]); This can be useful for cases where the original function does not follow the standard format of taking an error-first callback as the last argument. -For example, with a function that takes in `(foo, onSuccessCallback, onErrorCallback)`: +For example, with a function that takes in +`(foo, onSuccessCallback, onErrorCallback)`: ```js doSomething[util.promisify.custom] = (foo) => { diff --git a/doc/api/v8.md b/doc/api/v8.md index ac46e5df58..f929fe6a03 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -108,11 +108,11 @@ Returns an object with the following properties: * `peak_malloced_memory` {number} * `does_zap_garbage` {number} -`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` -option is enabled or not. This makes V8 overwrite heap garbage with a bit -pattern. The RSS footprint (resident memory set) gets bigger because it -continuously touches all heap pages and that makes them less likely to get -swapped out by the operating system. +`does_zap_garbage` is a 0/1 boolean, which signifies whether the +`--zap_code_space` option is enabled or not. This makes V8 overwrite heap +garbage with a bit pattern. The RSS footprint (resident memory set) gets bigger +because it continuously touches all heap pages and that makes them less likely +to get swapped out by the operating system. <!-- eslint-skip --> ```js @@ -299,7 +299,8 @@ added: v8.0.0 #### new Deserializer(buffer) -* `buffer` {Buffer|Uint8Array} A buffer returned by [`serializer.releaseBuffer()`][]. +* `buffer` {Buffer|Uint8Array} A buffer returned by + [`serializer.releaseBuffer()`][]. Creates a new `Deserializer` object. diff --git a/doc/api/vm.md b/doc/api/vm.md index 0a5999b7ff..12e35e9f72 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -184,9 +184,9 @@ in the ECMAScript specification. * {any} -If the `module.status` is `'errored'`, this property contains the exception thrown -by the module during evaluation. If the status is anything else, accessing this -property will result in a thrown exception. +If the `module.status` is `'errored'`, this property contains the exception +thrown by the module during evaluation. If the status is anything else, +accessing this property will result in a thrown exception. The value `undefined` cannot be used for cases where there is not a thrown exception due to possible ambiguity with `throw undefined;`. @@ -773,9 +773,9 @@ local scope, so the value `localVar` is changed. In this way ## 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 context. The code passed -to this VM context will have its own isolated scope. +When using either [`script.runInThisContext()`][] or +[`vm.runInThisContext()`][], the code is executed within the current V8 global +context. The code passed to this VM context will have its own isolated scope. In order to run a simple web server using the `http` module the code passed to the context must either call `require('http')` on its own, or have a reference diff --git a/doc/changelogs/CHANGELOG_ARCHIVE.md b/doc/changelogs/CHANGELOG_ARCHIVE.md index 35d879064f..fc56c492d9 100644 --- a/doc/changelogs/CHANGELOG_ARCHIVE.md +++ b/doc/changelogs/CHANGELOG_ARCHIVE.md @@ -1,6 +1,7 @@ # Node.js ChangeLog Archive <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_IOJS.md b/doc/changelogs/CHANGELOG_IOJS.md index daac573eab..a042e50fae 100644 --- a/doc/changelogs/CHANGELOG_IOJS.md +++ b/doc/changelogs/CHANGELOG_IOJS.md @@ -1,6 +1,7 @@ # io.js ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V010.md b/doc/changelogs/CHANGELOG_V010.md index d9ad08acf0..cdea52193b 100644 --- a/doc/changelogs/CHANGELOG_V010.md +++ b/doc/changelogs/CHANGELOG_V010.md @@ -1,6 +1,7 @@ # Node.js 0.10 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V012.md b/doc/changelogs/CHANGELOG_V012.md index a577732698..9ba23c0860 100644 --- a/doc/changelogs/CHANGELOG_V012.md +++ b/doc/changelogs/CHANGELOG_V012.md @@ -1,6 +1,7 @@ # Node.js 0.12 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md index b6cc901131..3257b14dbd 100644 --- a/doc/changelogs/CHANGELOG_V4.md +++ b/doc/changelogs/CHANGELOG_V4.md @@ -1,6 +1,7 @@ # Node.js 4 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md index 4f223e62f7..eb8c6e74ca 100644 --- a/doc/changelogs/CHANGELOG_V5.md +++ b/doc/changelogs/CHANGELOG_V5.md @@ -1,6 +1,7 @@ # Node.js 5 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index 0c9343bcad..2a0860e3f4 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -1,6 +1,7 @@ # Node.js 6 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V7.md b/doc/changelogs/CHANGELOG_V7.md index dd9fa4d269..dc9c9154b5 100644 --- a/doc/changelogs/CHANGELOG_V7.md +++ b/doc/changelogs/CHANGELOG_V7.md @@ -1,6 +1,7 @@ # Node.js 7 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V8.md b/doc/changelogs/CHANGELOG_V8.md index 60cd5ca332..be816ef0bd 100644 --- a/doc/changelogs/CHANGELOG_V8.md +++ b/doc/changelogs/CHANGELOG_V8.md @@ -1,6 +1,7 @@ # Node.js 8 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/changelogs/CHANGELOG_V9.md b/doc/changelogs/CHANGELOG_V9.md index a95c79634d..84b7a4ce08 100644 --- a/doc/changelogs/CHANGELOG_V9.md +++ b/doc/changelogs/CHANGELOG_V9.md @@ -1,6 +1,7 @@ # Node.js 9 ChangeLog <!--lint disable prohibited-strings--> +<!--lint disable maximum-line-length--> <table> <tr> diff --git a/doc/guides/building-node-with-ninja.md b/doc/guides/building-node-with-ninja.md index 5473d662be..a70d78fd7a 100644 --- a/doc/guides/building-node-with-ninja.md +++ b/doc/guides/building-node-with-ninja.md @@ -35,13 +35,15 @@ runner directly, like so: ## Alias -`alias nnode='./configure --ninja && ninja -C out/Release && ln -fs out/Release/node node'` +`alias nnode='./configure --ninja && ninja -C out/Release && ln -fs +out/Release/node node'` ## Producing a debug build The above alias can be modified slightly to produce a debug build, rather than a release build as shown below: -`alias nnodedebug='./configure --ninja && ninja -C out/Debug && ln -fs out/Debug/node node_g'` +`alias nnodedebug='./configure --ninja && ninja -C out/Debug && ln -fs +out/Debug/node node_g'` [Ninja]: https://ninja-build.org/ diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 04bc155660..cdf7f19b3d 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -243,13 +243,13 @@ V8 5.1 (since it was already abandoned). Since Node.js `v6.x` uses V8 5.1, the fix needed to be cherry-picked. To cherry-pick, here's an example workflow: * Download and apply the commit linked-to in the issue (in this case a51f429). - `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8`. - If the branches have diverged significantly, this may not apply cleanly. It - may help to try to cherry-pick the merge to the oldest branch that was done - upstream in V8. In this example, this would be the patch from the merge to - 5.2. The hope is that this would be closer to the V8 5.1, and has a better - chance of applying cleanly. If you're stuck, feel free to ping @ofrobots for - help. + `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 + --directory=deps/v8`. If the branches have diverged significantly, this may + not apply cleanly. It may help to try to cherry-pick the merge to the oldest + branch that was done upstream in V8. In this example, this would be the patch + from the merge to 5.2. The hope is that this would be closer to the V8 5.1, + and has a better chance of applying cleanly. If you're stuck, feel free to + ping @ofrobots for help. * Modify the commit message to match the format we use for V8 backports and replace yourself as the author. `git commit --amend --reset-author`. You may want to add extra description if necessary to indicate the impact of the fix diff --git a/doc/guides/maintaining-the-build-files.md b/doc/guides/maintaining-the-build-files.md index ca5ee090a6..d6e4b0be24 100644 --- a/doc/guides/maintaining-the-build-files.md +++ b/doc/guides/maintaining-the-build-files.md @@ -15,8 +15,8 @@ There are three main build files that may be directly run when building Node.js: Makefile mentioned below is maintained separately by humans). For a detailed guide on this script, see [configure](#configure). - `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a - subset of the targets available in the [Makefile](#makefile), and a few targets - of its own. For a detailed guide on this script, see + subset of the targets available in the [Makefile](#makefile), and a few + targets of its own. For a detailed guide on this script, see [vcbuild.bat](#vcbuild.bat). - `Makefile`: A Makefile that can be run with GNU Make. It provides a set of targets that build and test the Node.js binary, produce releases and diff --git a/doc/guides/writing-and-running-benchmarks.md b/doc/guides/writing-and-running-benchmarks.md index 66b5072a49..a6482c6078 100644 --- a/doc/guides/writing-and-running-benchmarks.md +++ b/doc/guides/writing-and-running-benchmarks.md @@ -31,8 +31,8 @@ either [`wrk`][wrk] or [`autocannon`][autocannon]. path. In order to compare two HTTP benchmark runs, make sure that the Node.js version in the path is not altered. -`wrk` may be available through one of the available package managers. If not, it can -be easily built [from source][wrk] via `make`. +`wrk` may be available through one of the available package managers. If not, +it can be easily built [from source][wrk] via `make`. By default, `wrk` will be used as the benchmarker. If it is not available, `autocannon` will be used in its place. When creating an HTTP benchmark, the @@ -184,7 +184,9 @@ The `compare.js` tool will then produce a csv file with the benchmark results. $ node benchmark/compare.js --old ./node-master --new ./node-pr-5134 string_decoder > compare-pr-5134.csv ``` -*Tips: there are some useful options of `benchmark/compare.js`. For example, if you want to compare the benchmark of a single script instead of a whole module, you can use the `--filter` option:* +*Tips: there are some useful options of `benchmark/compare.js`. For example, +if you want to compare the benchmark of a single script instead of a whole +module, you can use the `--filter` option:* ```console --new ./new-node-binary new node binary (required) @@ -234,9 +236,9 @@ is less than `0.05`._ The `compare.R` tool can also produce a box plot by using the `--plot filename` option. In this case there are 48 different benchmark combinations, and there may be a need to filter the csv file. This can be done while benchmarking -using the `--set` parameter (e.g. `--set encoding=ascii`) or by filtering results -afterwards using tools such as `sed` or `grep`. In the `sed` case be sure to -keep the first line since that contains the header information. +using the `--set` parameter (e.g. `--set encoding=ascii`) or by filtering +results afterwards using tools such as `sed` or `grep`. In the `sed` case be +sure to keep the first line since that contains the header information. ```console $ cat compare-pr-5134.csv | sed '1p;/encoding=ascii/!d' | Rscript benchmark/compare.R --plot compare-plot.png diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index aa4412e161..28a062d8b7 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -138,15 +138,15 @@ platforms. ### The *common* API -Make use of the helpers from the `common` module as much as possible. Please refer -to the [common file documentation](https://github.com/nodejs/node/tree/master/test/common) +Make use of the helpers from the `common` module as much as possible. Please +refer to the [common file documentation](https://github.com/nodejs/node/tree/master/test/common) for the full details of the helpers. #### common.mustCall -One interesting case is `common.mustCall`. The use of `common.mustCall` may avoid -the use of extra variables and the corresponding assertions. Let's explain this -with a real test from the test suite. +One interesting case is `common.mustCall`. The use of `common.mustCall` may +avoid the use of extra variables and the corresponding assertions. Let's +explain this with a real test from the test suite. ```javascript 'use strict'; @@ -200,9 +200,10 @@ const server = http.createServer(common.mustCall(function(req, res) { ``` #### Countdown Module -The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module) provides a simple countdown mechanism for tests that -require a particular action to be taken after a given number of completed tasks -(for instance, shutting down an HTTP server after a specific number of requests). +The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module) +provides a simple countdown mechanism for tests that require a particular +action to be taken after a given number of completed tasks (for instance, +shutting down an HTTP server after a specific number of requests). ```javascript const Countdown = require('../common/countdown'); diff --git a/tools/icu/README.md b/tools/icu/README.md index e1c753ebf3..9b7f72128f 100644 --- a/tools/icu/README.md +++ b/tools/icu/README.md @@ -1,20 +1,29 @@ # Notes about the `tools/icu` subdirectory -This directory contains tools, data, and information about the [http://icu-project.org](ICU) (International Components for Unicode) integration. ICU is used to provide internationalization functionality. - -- `patches/` are one-off patches, actually entire source file replacements, organized by ICU version number. -- `icu_small.json` controls the "small" (English only) ICU. It is input to `icutrim.py` -- `icu-generic.gyp` is the build file used for most ICU builds within ICU. <!-- have fun --> -- `icu-system.gyp` is an alternate build file used when `--with-intl=system-icu` is invoked. It builds against the `pkg-config` located ICU. -- `iculslocs.cc` is source for the `iculslocs` utility, invoked by `icutrim.py` as part of repackaging. Not used separately. See source for more details. +This directory contains tools, data, and information about the [http://icu-project.org](ICU) +(International Components for Unicode) integration. ICU is used to provide +internationalization functionality. + +- `patches/` are one-off patches, actually entire source file replacements, + organized by ICU version number. +- `icu_small.json` controls the "small" (English only) ICU. It is input to + `icutrim.py` +- `icu-generic.gyp` is the build file used for most ICU builds within ICU. + <!-- have fun --> +- `icu-system.gyp` is an alternate build file used when `--with-intl=system-icu` + is invoked. It builds against the `pkg-config` located ICU. +- `iculslocs.cc` is source for the `iculslocs` utility, invoked by `icutrim.py` + as part of repackaging. Not used separately. See source for more details. - `no-op.cc` — empty function to convince gyp to use a C++ compiler. - `README.md` — you are here - `shrink-icu-src.py` — this is used during upgrade (see guide below) ## How to upgrade ICU -- Make sure your node workspace is clean (clean `git status`) should be sufficient. -- Configure Node with the specific [ICU version](http://icu-project.org/download) you want to upgrade to, for example: +- Make sure your node workspace is clean (clean `git status`) should be + sufficient. +- Configure Node with the specific [ICU version](http://icu-project.org/download) + you want to upgrade to, for example: ```shell ./configure \ @@ -26,8 +35,10 @@ make > _Note_ in theory, the equivalent `vcbuild.bat` commands should work also, > but the commands below are makefile-centric. -- If there are ICU version-specific changes needed, you may need to make changes in `icu-generic.gyp` or add patch files to `tools/icu/patches`. - - Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for files to exclude. +- If there are ICU version-specific changes needed, you may need to make changes + in `icu-generic.gyp` or add patch files to `tools/icu/patches`. + - Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for + files to exclude. - Verify the node build works: @@ -95,7 +106,11 @@ make test-ci - commit the change to `configure` along with the updated `LICENSE` file. - - Note: To simplify review, I often will “pre-land” this patch, meaning that I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that patched branch into my PR's branch. This reduces the whitespace changes that show up in the PR, since the final land will eliminate those anyway. + - Note: To simplify review, I often will “pre-land” this patch, meaning that + I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch + | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that + patched branch into my PR's branch. This reduces the whitespace changes that + show up in the PR, since the final land will eliminate those anyway. ----- diff --git a/tools/remark-preset-lint-node/index.js b/tools/remark-preset-lint-node/index.js index a59d5d78d8..d50b30f83d 100644 --- a/tools/remark-preset-lint-node/index.js +++ b/tools/remark-preset-lint-node/index.js @@ -49,5 +49,6 @@ module.exports.plugins = [ ] ], [require('remark-lint-strong-marker'), '*'], - [require('remark-lint-table-cell-padding'), 'padded'] + [require('remark-lint-table-cell-padding'), 'padded'], + [require('remark-lint-maximum-line-length'), 80] ]; diff --git a/tools/remark-preset-lint-node/package-lock.json b/tools/remark-preset-lint-node/package-lock.json index 8c84d7f782..55f29b9aba 100644 --- a/tools/remark-preset-lint-node/package-lock.json +++ b/tools/remark-preset-lint-node/package-lock.json @@ -185,6 +185,17 @@ "unist-util-visit": "1.2.0" } }, + "remark-lint-maximum-line-length": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/remark-lint-maximum-line-length/-/remark-lint-maximum-line-length-1.0.2.tgz", + "integrity": "sha512-M4UIXAAbtLgoQbTDVwdKOEFbTKtJSZ+pCW7ZqMFs+cbIN0Svm32LM9+xpVfVU0hLYt3Ypl++EAPfguBNe1PZEw==", + "requires": { + "unified-lint-rule": "1.0.2", + "unist-util-generated": "1.1.1", + "unist-util-position": "3.0.0", + "unist-util-visit": "1.2.0" + } + }, "remark-lint-no-auto-link-without-protocol": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/remark-lint-no-auto-link-without-protocol/-/remark-lint-no-auto-link-without-protocol-1.0.1.tgz", diff --git a/tools/remark-preset-lint-node/package.json b/tools/remark-preset-lint-node/package.json index beabb75cdb..285ba74d5f 100644 --- a/tools/remark-preset-lint-node/package.json +++ b/tools/remark-preset-lint-node/package.json @@ -32,6 +32,7 @@ "remark-lint-first-heading-level": "^1.0.0", "remark-lint-hard-break-spaces": "^1.0.1", "remark-lint-heading-style": "^1.0.0", + "remark-lint-maximum-line-length": "^1.0.2", "remark-lint-no-auto-link-without-protocol": "^1.0.0", "remark-lint-no-blockquote-without-caret": "^1.0.0", "remark-lint-no-duplicate-definitions": "^1.0.0", |