diff --git a/BUILDING.md b/BUILDING.md index eda74fb70f41bc..697d4bd63aa107 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 | |--------------|--------------|----------------------------------|----------------------|------------------| @@ -108,9 +108,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 @@ -233,8 +235,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 6f82ff8e86a064..87de8c4faa9b57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Node.js Changelog + + 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 f8daea5c643e52..941694ced34d1c 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -199,22 +199,23 @@ 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 @@ -554,8 +555,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 @@ -563,8 +564,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 23c1ac8bb5106e..83d4d9b50a7abe 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 diff --git a/README.md b/README.md index 9ef437bac96d0c..5cc2bf699e3295 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@

- Node.js + Node.js

diff --git a/doc/api/_toc.md b/doc/api/_toc.md index b8002fb78163ac..29b264e77b3c63 100644 --- a/doc/api/_toc.md +++ b/doc/api/_toc.md @@ -1,5 +1,4 @@ -@// 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. diff --git a/doc/api/assert.md b/doc/api/assert.md index 2ecf628e4aa80a..dc877248dc5b3c 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 @@ -595,8 +595,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 0daa4c8295e556..79276a6ef93ca9 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()` @@ -728,8 +728,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 aa82ac66bd746d..df6912c9c6a6b8 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1,6 +1,7 @@ # Buffer + > Stability: 2 - Stable diff --git a/doc/api/child_process.md b/doc/api/child_process.md index bc430897ba4ef2..be74f1fde76dc0 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,6 +1,7 @@ # Child Process + > Stability: 2 - Stable diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 11be4d34d5bed8..08a669e4fa0f1f 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 ea760e5e6ecab0..3665e9927187e0 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -449,7 +449,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]) -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. ### crypto.createCipher(algorithm, password[, options]) - `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 @@ -1404,7 +1406,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 b0da263f5947b4..00dda306d09232 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 b5339e953ec97b..99925a375d6720 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`. ### 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. ### DEP0078: REPLServer.turnOffEditorMode() diff --git a/doc/api/dgram.md b/doc/api/dgram.md index e44bf3eea5a166..9209b83a120247 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 cda4823e3ce0e7..fa7c34f654d011 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 c2413d33db8ae4..a864771f446dd9 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 b303b0fdeb1746..a9ca7f2d277be0 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 82ebbcded0400c..d334bec7fe81c6 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 diff --git a/doc/api/esm.md b/doc/api/esm.md index 4f658bc6802ad9..9fcda68776a9bf 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -126,7 +126,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 7b510fac0505c0..afea4f443c9798 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 fc9bc7e9159f92..75b6fa987100e3 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -2901,9 +2901,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. diff --git a/doc/api/http.md b/doc/api/http.md index 076d0b6223f7b3..c0d3bacd9b70c9 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: @@ -623,7 +624,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. @@ -690,7 +692,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' 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]) -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 -- `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`. diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 454a14fe1ae12e..722504bc7b2f34 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][]. @@ -667,7 +667,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. @@ -1370,8 +1371,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. @@ -1616,10 +1617,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 + > Stability: 2 - Stable diff --git a/doc/api/process.md b/doc/api/process.md index 6416376b550413..2bd7a119bf8d6c 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' * `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 581d51e99003b9..9717daaad192d5 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -429,8 +429,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 ce6b5fcf182736..ec4312a52e7ea5 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -423,8 +423,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 @@ -619,8 +619,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. @@ -1267,8 +1267,11 @@ on the type of stream being created, as detailed in the chart below:

[Writable](#stream_class_stream_writable)

-

[_write][stream-_write], [_writev][stream-_writev], - [_final][stream-_final]

+

+ [_write][stream-_write], + [_writev][stream-_writev], + [_final][stream-_final] +

@@ -1279,8 +1282,11 @@ on the type of stream being created, as detailed in the chart below:

[Duplex](#stream_class_stream_duplex)

-

[_read][stream-_read], [_write][stream-_write], [_writev][stream-_writev], - [_final][stream-_final]

+

+ [_read][stream-_read], + [_write][stream-_write], + [_writev][stream-_writev], + [_final][stream-_final]

@@ -1291,8 +1297,11 @@ on the type of stream being created, as detailed in the chart below:

[Transform](#stream_class_stream_transform)

-

[_transform][stream-_transform], [_flush][stream-_flush], - [_final][stream-_final]

+

+ [_transform][stream-_transform], + [_flush][stream-_flush], + [_final][stream-_final] +

@@ -1601,8 +1610,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 0755fbe19a16a0..cd8e05f9904496 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -742,8 +742,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` @@ -861,8 +861,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} @@ -1016,7 +1016,8 @@ changes: as an array of unencrypted PFX buffers, or an array of objects in the form `{buf: [, passphrase: ]}`. 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 @@ -1318,8 +1319,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 13caa2a509bf74..b11454b3a5c043 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 d2921421940b84..ec3102fd805227 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] ``` @@ -120,8 +121,8 @@ environment variable: `NODE_DEBUG=fs,net,tls`. added: v0.8.0 --> -The `util.deprecate()` method wraps the given `function` or class in such a way that -it is marked as deprecated. +The `util.deprecate()` method wraps the given `function` or class in such a way +that it is marked as deprecated. ```js @@ -181,12 +182,12 @@ 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, depth: 4, showProxy: true }`. - This will show the full object including non-enumerable symbols and properties. -* `%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 symbols and properties. + Similar to `util.inspect()` with options + `{ showHidden: true, depth: 4, showProxy: true }`. This will show the full + object including non-enumerable symbols and properties. +* `%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 symbols and properties. * `%%` - single percent sign (`'%'`). This does not consume an argument. * Returns: {string} The formatted string @@ -643,7 +644,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 ac46e5df585333..f929fe6a03e952 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. ```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 0ff178e51e77eb..0be8c6d50313d7 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;`. @@ -803,9 +803,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 35d879064f0283..fc56c492d9c93f 100644 --- a/doc/changelogs/CHANGELOG_ARCHIVE.md +++ b/doc/changelogs/CHANGELOG_ARCHIVE.md @@ -1,6 +1,7 @@ # Node.js ChangeLog Archive + diff --git a/doc/changelogs/CHANGELOG_IOJS.md b/doc/changelogs/CHANGELOG_IOJS.md index daac573eab7031..a042e50fae1b63 100644 --- a/doc/changelogs/CHANGELOG_IOJS.md +++ b/doc/changelogs/CHANGELOG_IOJS.md @@ -1,6 +1,7 @@ # io.js ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V010.md b/doc/changelogs/CHANGELOG_V010.md index d9ad08acf0f8ba..cdea52193bb331 100644 --- a/doc/changelogs/CHANGELOG_V010.md +++ b/doc/changelogs/CHANGELOG_V010.md @@ -1,6 +1,7 @@ # Node.js 0.10 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V012.md b/doc/changelogs/CHANGELOG_V012.md index a57773269814ee..9ba23c086055d0 100644 --- a/doc/changelogs/CHANGELOG_V012.md +++ b/doc/changelogs/CHANGELOG_V012.md @@ -1,6 +1,7 @@ # Node.js 0.12 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md index 33b4d146ea2756..2c23b99c4c09eb 100644 --- a/doc/changelogs/CHANGELOG_V4.md +++ b/doc/changelogs/CHANGELOG_V4.md @@ -1,6 +1,7 @@ # Node.js 4 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md index 4f223e62f79b73..eb8c6e74cad826 100644 --- a/doc/changelogs/CHANGELOG_V5.md +++ b/doc/changelogs/CHANGELOG_V5.md @@ -1,6 +1,7 @@ # Node.js 5 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index ae20c09c6e379f..70644458f1014d 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -1,6 +1,7 @@ # Node.js 6 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V7.md b/doc/changelogs/CHANGELOG_V7.md index dd9fa4d269a8d6..dc9c9154b5b2a4 100644 --- a/doc/changelogs/CHANGELOG_V7.md +++ b/doc/changelogs/CHANGELOG_V7.md @@ -1,6 +1,7 @@ # Node.js 7 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V8.md b/doc/changelogs/CHANGELOG_V8.md index fbbd2a18006ad0..30596253280d37 100644 --- a/doc/changelogs/CHANGELOG_V8.md +++ b/doc/changelogs/CHANGELOG_V8.md @@ -1,6 +1,7 @@ # Node.js 8 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V9.md b/doc/changelogs/CHANGELOG_V9.md index df896acb4d7101..bde1c1d627433a 100644 --- a/doc/changelogs/CHANGELOG_V9.md +++ b/doc/changelogs/CHANGELOG_V9.md @@ -1,6 +1,7 @@ # Node.js 9 ChangeLog +
diff --git a/doc/guides/building-node-with-ninja.md b/doc/guides/building-node-with-ninja.md index 5473d662be2f27..a70d78fd7aac49 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 0ede3ac5f5e332..728fb1feb46530 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -242,13 +242,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 ca5ee090a69dcc..d6e4b0be249c24 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 66b5072a4979d7..a6482c607893ca 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 aa4412e1613c2c..28a062d8b79aca 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 e1c753ebf3347e..9b7f72128fc52d 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. -- `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. + +- `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 a59d5d78d8fff8..d50b30f83dc57e 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 8c84d7f782b61d..55f29b9aba9e73 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 beabb75cdb22b6..285ba74d5f88bb 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",