From 2ec69955556bf92f49355659b6126e08fa2c3298 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Fri, 23 Mar 2018 11:23:22 -0700 Subject: [PATCH 01/22] perf_hooks: simplify perf_hooks Remove the `performance.getEntries()` and `performance.clear*()` variants and eliminate the accumulation of the global timeline entries. The design of this particular bit of the API is a memory leak and performance footgun. The `PerformanceObserver` API is a better approach to consuming the data in a more transient way. PR-URL: https://github.com/nodejs/node/pull/19563 Reviewed-By: Anna Henningsen Reviewed-By: Matteo Collina --- doc/api/perf_hooks.md | 106 ++------------------- lib/perf_hooks.js | 101 ++------------------ src/node_perf.cc | 14 ++- test/parallel/test-http2-perf_hooks.js | 10 +- test/parallel/test-performance-function.js | 10 -- test/parallel/test-performance-gc.js | 13 --- test/parallel/test-performance-warning.js | 29 ------ test/parallel/test-performanceobserver.js | 16 ++-- test/sequential/test-performance.js | 59 +----------- 9 files changed, 38 insertions(+), 320 deletions(-) delete mode 100644 test/parallel/test-performance-warning.js diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 0a81874adb7..3e05ba285fd 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -10,14 +10,18 @@ is to support collection of high resolution performance metrics. This is the same Performance API as implemented in modern Web browsers. ```js -const { performance } = require('perf_hooks'); +const { PerformanceObserver, performance } = require('perf_hooks'); + +const obs = new PerformanceObserver((items) => { + console.log(items.getEntries()[0].duration); + performance.clearMarks(); +}); +obs.observe({ entryTypes: ['measure'] }); + performance.mark('A'); doSomeLongRunningProcess(() => { performance.mark('B'); performance.measure('A to B', 'A', 'B'); - const measure = performance.getEntriesByName('A to B')[0]; - console.log(measure.duration); - // Prints the number of milliseconds between Mark 'A' and Mark 'B' }); ``` @@ -26,35 +30,6 @@ doSomeLongRunningProcess(() => { added: v8.5.0 --> -The `Performance` provides access to performance metric data. A single -instance of this class is provided via the `performance` property. - -### performance.clearEntries(name) - - -Remove all performance entry objects with `entryType` equal to `name` from the -Performance Timeline. - -### performance.clearFunctions([name]) - - -* `name` {string} - -If `name` is not provided, removes all `PerformanceFunction` objects from the -Performance Timeline. If `name` is provided, removes entries with `name`. - -### performance.clearGC() - - -Remove all performance entry objects with `entryType` equal to `gc` from the -Performance Timeline. - ### performance.clearMarks([name]) - -* `name` {string} - -If `name` is not provided, removes all `PerformanceMeasure` objects from the -Performance Timeline. If `name` is provided, removes only objects whose -`performanceEntry.name` matches `name`. - -### performance.getEntries() - - -* Returns: {Array} - -Returns a list of all `PerformanceEntry` objects in chronological order -with respect to `performanceEntry.startTime`. - -### performance.getEntriesByName(name[, type]) - - -* `name` {string} -* `type` {string} -* Returns: {Array} - -Returns a list of all `PerformanceEntry` objects in chronological order -with respect to `performanceEntry.startTime` whose `performanceEntry.name` is -equal to `name`, and optionally, whose `performanceEntry.entryType` is equal to -`type`. - -### performance.getEntriesByType(type) - - -* `type` {string} -* Returns: {Array} - -Returns a list of all `PerformanceEntry` objects in chronological order -with respect to `performanceEntry.startTime` whose `performanceEntry.entryType` -is equal to `type`. - ### performance.mark([name]) - -Value: {number} - -The maximum number of Performance Entry items that should be added to the -Performance Timeline. This limit is not strictly enforced, but a process -warning will be emitted if the number of entries in the timeline exceeds -this limit. - -Defaults to 150. - ### performance.measure(name, startMark, endMark) * `string` {string} A string to encode. -* `encoding` {string} The encoding of `string`. **Default:** `'utf8'` +* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`. Creates a new `Buffer` containing `string`. The `encoding` parameter identifies the character encoding of `string`. @@ -984,13 +984,13 @@ changes: * `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to. * `targetStart` {integer} The offset within `target` at which to begin - comparison. **Default:** `0` + comparison. **Default:** `0`. * `targetEnd` {integer} The offset with `target` at which to end comparison - (not inclusive). **Default:** `target.length` + (not inclusive). **Default:** `target.length`. * `sourceStart` {integer} The offset within `buf` at which to begin comparison. - **Default:** `0` + **Default:** `0`. * `sourceEnd` {integer} The offset within `buf` at which to end comparison - (not inclusive). **Default:** [`buf.length`] + (not inclusive). **Default:** [`buf.length`]. * Returns: {integer} Compares `buf` with `target` and returns a number indicating whether `buf` @@ -1047,11 +1047,11 @@ added: v0.1.90 * `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to copy into. * `targetStart` {integer} The offset within `target` at which to begin - copying to. **Default:** `0` + copying to. **Default:** `0`. * `sourceStart` {integer} The offset within `buf` at which to begin copying from. - **Default:** `0` + **Default:** `0`. * `sourceEnd` {integer} The offset within `buf` at which to stop copying (not - inclusive). **Default:** [`buf.length`] + inclusive). **Default:** [`buf.length`]. * Returns: {integer} The number of bytes copied. Copies data from a region of `buf` to a region in `target` even if the `target` @@ -1165,10 +1165,10 @@ changes: --> * `value` {string|Buffer|integer} The value to fill `buf` with. -* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0` -* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`] +* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`. +* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`]. * `encoding` {string} If `value` is a string, this is its encoding. - **Default:** `'utf8'` + **Default:** `'utf8'`. * Returns: {Buffer} A reference to `buf`. Fills `buf` with the specified `value`. If the `offset` and `end` are not given, @@ -1216,9 +1216,9 @@ added: v5.3.0 --> * `value` {string|Buffer|integer} What to search for. -* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0` +* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`. * `encoding` {string} If `value` is a string, this is its encoding. - **Default:** `'utf8'` + **Default:** `'utf8'`. * Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise. Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`]. @@ -1256,9 +1256,9 @@ changes: --> * `value` {string|Buffer|Uint8Array|integer} What to search for. -* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0` +* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`. * `encoding` {string} If `value` is a string, this is its encoding. - **Default:** `'utf8'` + **Default:** `'utf8'`. * Returns: {integer} The index of the first occurrence of `value` in `buf` or `-1` if `buf` does not contain `value`. @@ -1358,9 +1358,9 @@ changes: * `value` {string|Buffer|Uint8Array|integer} What to search for. * `byteOffset` {integer} Where to begin searching in `buf`. - **Default:** [`buf.length`]` - 1` + **Default:** [`buf.length`]` - 1`. * `encoding` {string} If `value` is a string, this is its encoding. - **Default:** `'utf8'` + **Default:** `'utf8'`. * Returns: {integer} The index of the last occurrence of `value` in `buf` or `-1` if `buf` does not contain `value`. @@ -1792,9 +1792,9 @@ changes: calculations with them. --> -* `start` {integer} Where the new `Buffer` will start. **Default:** `0` +* `start` {integer} Where the new `Buffer` will start. **Default:** `0`. * `end` {integer} Where the new `Buffer` will end (not inclusive). - **Default:** [`buf.length`] + **Default:** [`buf.length`]. * Returns: {Buffer} Returns a new `Buffer` that references the same memory as the original, but @@ -1963,10 +1963,10 @@ console.log(copy); added: v0.1.90 --> -* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'` -* `start` {integer} The byte offset to start decoding at. **Default:** `0` +* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`. +* `start` {integer} The byte offset to start decoding at. **Default:** `0`. * `end` {integer} The byte offset to stop decoding at (not inclusive). - **Default:** [`buf.length`] + **Default:** [`buf.length`]. * Returns: {string} Decodes `buf` to a string according to the specified character encoding in @@ -2040,9 +2040,9 @@ added: v0.1.90 --> * `string` {string} String to be written to `buf`. -* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0` -* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset` -* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'` +* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`. +* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`. +* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`. * Returns: {integer} Number of bytes written. Writes `string` to `buf` at `offset` according to the character encoding in `encoding`. @@ -2369,7 +2369,7 @@ changes: * `value` {integer} Number to be written to `buf`. * `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - byteLength`. * `byteLength` {integer} Number of bytes to write. Must satisfy: `0 < byteLength <= 6`. - **Default:** `false` + **Default:** `false`. * Returns: {integer} `offset` plus the number of bytes written. Writes `byteLength` bytes of `value` to `buf` at the specified `offset`. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 7a01038d58f..929788486de 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -139,15 +139,16 @@ changes: * `command` {string} The command to run, with space-separated arguments. * `options` {Object} * `cwd` {string} Current working directory of the child process. - * `env` {Object} Environment key-value pairs. + **Default:** `null`. + * `env` {Object} Environment key-value pairs. **Default:** `null`. * `encoding` {string} **Default:** `'utf8'` - * `shell` {string} Shell to execute the command with. - **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See - [Shell Requirements][] and [Default Windows Shell][]. + * `shell` {string} Shell to execute the command with. See + [Shell Requirements][] and [Default Windows Shell][]. **Default:** + `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. **Default:** `200*1024`. If exceeded, the child process is terminated. - See caveat at [`maxBuffer` and Unicode][]. + stderr. If exceeded, the child process is terminated. See caveat at + [`maxBuffer` and Unicode][]. **Default:** `200*1024`. * `killSignal` {string|integer} **Default:** `'SIGTERM'` * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). @@ -202,20 +203,6 @@ can be used to specify the character encoding used to decode the stdout and stderr output. If `encoding` is `'buffer'`, or an unrecognized character encoding, `Buffer` objects will be passed to the callback instead. -The `options` argument may be passed as the second argument to customize how -the process is spawned. The default options are: - -```js -const defaults = { - encoding: 'utf8', - timeout: 0, - maxBuffer: 200 * 1024, - killSignal: 'SIGTERM', - cwd: null, - env: null -}; -``` - If `timeout` is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `'SIGTERM'`) if the child runs longer than `timeout` milliseconds. @@ -258,8 +245,8 @@ changes: * `encoding` {string} **Default:** `'utf8'` * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. **Default:** `200*1024` If exceeded, the child process is terminated. - See caveat at [`maxBuffer` and Unicode][]. + stderr. If exceeded, the child process is terminated. See caveat at + [`maxBuffer` and Unicode][]. **Default:** `200*1024`. * `killSignal` {string|integer} **Default:** `'SIGTERM'` * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). @@ -341,11 +328,11 @@ changes: * `env` {Object} Environment key-value pairs. * `execPath` {string} Executable used to create the child process. * `execArgv` {Array} List of string arguments passed to the executable. - **Default:** `process.execArgv` + **Default:** `process.execArgv`. * `silent` {boolean} If `true`, stdin, stdout, and stderr of the child will be piped to the parent, otherwise they will be inherited from the parent, see the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s - [`stdio`][] for more details. **Default:** `false` + [`stdio`][] for more details. **Default:** `false`. * `stdio` {Array|string} See [`child_process.spawn()`][]'s [`stdio`][]. When this option is provided, it overrides `silent`. If the array variant is used, it must contain exactly one item with value `'ipc'` or an error @@ -701,22 +688,22 @@ changes: * `options` {Object} * `cwd` {string} Current working directory of the child process. * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin - to the spawned process. - - supplying this value will override `stdio[0]` - * `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'` - - `stderr` by default will be output to the parent process' stderr unless - `stdio` is specified + to the spawned process. Supplying this value will override `stdio[0]`. + * `stdio` {string|Array} Child's stdio configuration. `stderr` by default will + be output to the parent process' stderr unless `stdio` is specified. + **Default:** `'pipe'`. * `env` {Object} Environment key-value pairs. * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). * `timeout` {number} In milliseconds the maximum amount of time the process - is allowed to run. **Default:** `undefined` + is allowed to run. **Default:** `undefined`. * `killSignal` {string|integer} The signal value to be used when the spawned - process will be killed. **Default:** `'SIGTERM'` + process will be killed. **Default:** `'SIGTERM'`. * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. **Default:** `200*1024` If exceeded, the child process is terminated. - See caveat at [`maxBuffer` and Unicode][]. - * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'` + stderr. If exceeded, the child process is terminated. See caveat at + [`maxBuffer` and Unicode][]. **Default:** `200*1024`. + * `encoding` {string} The encoding used for all stdio inputs and outputs. + **Default:** `'buffer'`. * `windowsHide` {boolean} Hide the subprocess console window that would normally be created on Windows systems. **Default:** `false`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses @@ -759,26 +746,25 @@ changes: * `options` {Object} * `cwd` {string} Current working directory of the child process. * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin - to the spawned process. - - supplying this value will override `stdio[0]`. - * `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'` - - `stderr` by default will be output to the parent process' stderr unless - `stdio` is specified + to the spawned process. Supplying this value will override `stdio[0]`. + * `stdio` {string|Array} Child's stdio configuration. `stderr` by default will + be output to the parent process' stderr unless `stdio` is specified. + **Default:** `'pipe'`. * `env` {Object} Environment key-value pairs. - * `shell` {string} Shell to execute the command with. - **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See - [Shell Requirements][] and [Default Windows Shell][]. + * `shell` {string} Shell to execute the command with. See + [Shell Requirements][] and [Default Windows Shell][]. **Default:** + `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. * `uid` {number} Sets the user identity of the process. (See setuid(2)). * `gid` {number} Sets the group identity of the process. (See setgid(2)). * `timeout` {number} In milliseconds the maximum amount of time the process - is allowed to run. **Default:** `undefined` + is allowed to run. **Default:** `undefined`. * `killSignal` {string|integer} The signal value to be used when the spawned - process will be killed. **Default:** `'SIGTERM'` + process will be killed. **Default:** `'SIGTERM'`. * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. **Default:** `200*1024` If exceeded, the child process is terminated. - See caveat at [`maxBuffer` and Unicode][]. + stderr. If exceeded, the child process is terminated. See caveat at + [`maxBuffer` and Unicode][]. **Default:** `200*1024`. * `encoding` {string} The encoding used for all stdio inputs and outputs. - **Default:** `'buffer'` + **Default:** `'buffer'`. * `windowsHide` {boolean} Hide the subprocess console window that would normally be created on Windows systems. **Default:** `false`. * Returns: {Buffer|string} The stdout from the command. @@ -821,21 +807,20 @@ changes: * `options` {Object} * `cwd` {string} Current working directory of the child process. * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin - to the spawned process. - - supplying this value will override `stdio[0]`. + to the spawned process. Supplying this value will override `stdio[0]`. * `stdio` {string|Array} Child's stdio configuration. * `env` {Object} Environment key-value pairs. * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). * `timeout` {number} In milliseconds the maximum amount of time the process - is allowed to run. **Default:** `undefined` + is allowed to run. **Default:** `undefined`. * `killSignal` {string|integer} The signal value to be used when the spawned - process will be killed. **Default:** `'SIGTERM'` + process will be killed. **Default:** `'SIGTERM'`. * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. **Default:** `200*1024` If exceeded, the child process is terminated. - See caveat at [`maxBuffer` and Unicode][]. + stderr. If exceeded, the child process is terminated. See caveat at + [`maxBuffer` and Unicode][]. **Default:** `200*1024`. * `encoding` {string} The encoding used for all stdio inputs and outputs. - **Default:** `'buffer'` + **Default:** `'buffer'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different shell can be specified as a string. See [Shell Requirements][] and @@ -1106,7 +1091,12 @@ changes: * `message` {Object} * `sendHandle` {Handle} -* `options` {Object} +* `options` {Object} The `options` argument, if present, is an object used to + parameterize the sending of certain types of handles. `options` supports + the following properties: + * `keepOpen` - A Boolean value that can be used when passing instances of + `net.Socket`. When `true`, the socket is kept open in the sending process. + **Default:** `false`. * `callback` {Function} * Returns: {boolean} @@ -1161,14 +1151,6 @@ receive the object as the second argument passed to the callback function registered on the [`process.on('message')`][] event. Any data that is received and buffered in the socket will not be sent to the child. -The `options` argument, if present, is an object used to parameterize the -sending of certain types of handles. `options` supports the following -properties: - - * `keepOpen` - A Boolean value that can be used when passing instances of - `net.Socket`. When `true`, the socket is kept open in the sending process. - Defaults to `false`. - The optional `callback` is a function that is invoked after the message is sent but before the child may have received it. The function is called with a single argument: `null` on success, or an [`Error`][] object on failure. diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 09558d299e4..66a4be91373 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -714,14 +714,14 @@ changes: * {Object} * `execArgv` {Array} List of string arguments passed to the Node.js - executable. **Default:** `process.execArgv` - * `exec` {string} File path to worker file. **Default:** `process.argv[1]` + executable. **Default:** `process.execArgv`. + * `exec` {string} File path to worker file. **Default:** `process.argv[1]`. * `args` {Array} String arguments passed to worker. - **Default:** `process.argv.slice(2)` + **Default:** `process.argv.slice(2)`. * `cwd` {string} Current working directory of the worker process. **Default:** - `undefined` (inherits from parent process) + `undefined` (inherits from parent process). * `silent` {boolean} Whether or not to send output to parent's stdio. - **Default:** `false` + **Default:** `false`. * `stdio` {Array} Configures the stdio of forked processes. Because the cluster module relies on IPC to function, this configuration must contain an `'ipc'` entry. When this option is provided, it overrides `silent`. @@ -732,7 +732,7 @@ changes: number. By default each worker gets its own port, incremented from the master's `process.debugPort`. * `windowsHide` {boolean} Hide the forked processes console window that would - normally be created on Windows systems. **Default:** `false` + normally be created on Windows systems. **Default:** `false`. After calling `.setupMaster()` (or `.fork()`) this settings object will contain the settings, including the default values. diff --git a/doc/api/console.md b/doc/api/console.md index 72d80ab9e79..f0df6ffde62 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -149,7 +149,7 @@ binary. added: v8.3.0 --> -* `label` {string} The display label for the counter. Defaults to `'default'`. +* `label` {string} The display label for the counter. **Default:** `'default'`. Maintains an internal counter specific to `label` and outputs to `stdout` the number of times `console.count()` has been called with the given `label`. @@ -182,7 +182,7 @@ undefined added: v8.3.0 --> -* `label` {string} The display label for the counter. Defaults to `'default'`. +* `label` {string} The display label for the counter. **Default:** `'default'`. Resets the internal counter specific to `label`. @@ -218,25 +218,17 @@ added: v0.1.101 --> * `obj` {any} * `options` {Object} - * `showHidden` {boolean} - * `depth` {number} - * `colors` {boolean} + * `showHidden` {boolean} If `true` then the object's non-enumerable and symbol + properties will be shown too. **Default:** `false`. + * `depth` {number} Tells [`util.inspect()`][] how many times to recurse while + formatting the object. This is useful for inspecting large complicated + objects. To make it recurse indefinitely, pass `null`. **Default:** `2`. + * `colors` {boolean} If `true`, then the output will be styled with ANSI color + codes. Colors are customizable; + see [customizing `util.inspect()` colors][]. **Default:** `false`. Uses [`util.inspect()`][] on `obj` and prints the resulting string to `stdout`. -This function bypasses any custom `inspect()` function defined on `obj`. An -optional `options` object may be passed to alter certain aspects of the -formatted string: - -- `showHidden` - if `true` then the object's non-enumerable and symbol -properties will be shown too. Defaults to `false`. - -- `depth` - tells [`util.inspect()`][] how many times to recurse while -formatting the object. This is useful for inspecting large complicated objects. -Defaults to `2`. To make it recurse indefinitely, pass `null`. - -- `colors` - if `true`, then the output will be styled with ANSI color codes. -Defaults to `false`. Colors are customizable; see -[customizing `util.inspect()` colors][]. +This function bypasses any custom `inspect()` function defined on `obj`. ### console.dirxml(...data) -* `label` {string} Defaults to `'default'`. +* `label` {string} **Default:** `'default'` Starts a timer that can be used to compute the duration of an operation. Timers are identified by a unique `label`. Use the same `label` when calling @@ -393,7 +385,7 @@ changes: description: This method no longer supports multiple calls that don’t map to individual `console.time()` calls; see below for details. --> -* `label` {string} Defaults to `'default'`. +* `label` {string} **Default:** `'default'` Stops a timer that was previously started by calling [`console.time()`][] and prints the result to `stdout`: @@ -449,7 +441,7 @@ not display anything unless used in conjunction with the [inspector][] -* `label` {string} Defaults to `'default'`. +* `label` {string} **Default:** `'default'` This method does not display anything unless used in the inspector. The `console.markTimeline()` method is the deprecated form of @@ -506,7 +498,7 @@ This method does not display anything unless used in the inspector. The -* `label` {string} Defaults to `'default'`. +* `label` {string} **Default:** `'default'` This method does not display anything unless used in the inspector. The `console.timeline()` method is the deprecated form of [`console.time()`][]. @@ -515,7 +507,7 @@ This method does not display anything unless used in the inspector. The -* `label` {string} Defaults to `'default'`. +* `label` {string} **Default:** `'default'` This method does not display anything unless used in the inspector. The `console.timelineEnd()` method is the deprecated form of diff --git a/doc/api/crypto.md b/doc/api/crypto.md index f90c2cfe2e3..ac14ab8499c 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -270,7 +270,7 @@ been completed using the [`cipher.final()`][] method. -- `autoPadding` {boolean} Defaults to `true`. +- `autoPadding` {boolean} **Default:** `true` - Returns the {Cipher} for method chaining. When using block encryption algorithms, the `Cipher` class will automatically @@ -443,7 +443,7 @@ The `decipher.setAuthTag()` method must be called before -- `autoPadding` {boolean} Defaults to `true`. +- `autoPadding` {boolean} **Default:** `true` - Returns the {Cipher} for method chaining. When data has been encrypted without standard block padding, calling @@ -665,7 +665,7 @@ added: REPLACEME - `curve` {string} - `inputEncoding` {string} - `outputEncoding` {string} -- `format` {string} Defaults to `uncompressed`. +- `format` {string} **Default:** `uncompressed` Converts the EC Diffie-Hellman public key specified by `key` and `curve` to the format specified by `format`. The `format` argument specifies point encoding @@ -742,7 +742,7 @@ its recommended for developers to handle this exception accordingly. added: v0.11.14 --> - `encoding` {string} -- `format` {string} Defaults to `uncompressed`. +- `format` {string} **Default:** `uncompressed` Generates private and public EC Diffie-Hellman key values, and returns the public key in the specified `format` and `encoding`. This key should be @@ -771,7 +771,7 @@ a string is returned; otherwise a [`Buffer`][] is returned. added: v0.11.14 --> - `encoding` {string} -- `format` {string} Defaults to `uncompressed`. +- `format` {string} **Default:** `uncompressed` Returns the EC Diffie-Hellman public key in the specified `encoding` and `format`. @@ -1454,8 +1454,8 @@ changes: --> - `prime` {string | Buffer | TypedArray | DataView} - `primeEncoding` {string} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to - `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} **Default:** + `2` - `generatorEncoding` {string} Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1478,8 +1478,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} **Default:** + `2` Creates a `DiffieHellman` key exchange object and generates a prime of `primeLength` bits using an optional specific numeric `generator`. @@ -1957,8 +1957,8 @@ changes: --> * `buffer` {Buffer|TypedArray|DataView} Must be supplied. -* `offset` {number} Defaults to `0`. -* `size` {number} Defaults to `buffer.length - offset`. +* `offset` {number} **Default:** `0` +* `size` {number} **Default:** `buffer.length - offset` Synchronous version of [`crypto.randomFill()`][]. @@ -1999,8 +1999,8 @@ changes: --> * `buffer` {Buffer|TypedArray|DataView} Must be supplied. -* `offset` {number} Defaults to `0`. -* `size` {number} Defaults to `buffer.length - offset`. +* `offset` {number} **Default:** `0` +* `size` {number} **Default:** `buffer.length - offset` * `callback` {Function} `function(err, buf) {}`. This function is similar to [`crypto.randomBytes()`][] but requires the first @@ -2064,7 +2064,7 @@ request. added: v0.11.11 --> - `engine` {string} -- `flags` {crypto.constants} Defaults to `crypto.constants.ENGINE_METHOD_ALL`. +- `flags` {crypto.constants} **Default:** `crypto.constants.ENGINE_METHOD_ALL` Load and set the `engine` for some or all OpenSSL functions (selected by flags). diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 32c8eee49fe..7cbf81623d6 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -583,10 +583,10 @@ changes: Required. * `reuseAddr` {boolean} When `true` [`socket.bind()`][] will reuse the address, even if another process has already bound a socket on it. - Defaults to `false`. + **Default:** `false`. * `recvBufferSize` {number} - Sets the `SO_RCVBUF` socket value. * `sendBufferSize` {number} - Sets the `SO_SNDBUF` socket value. - * `lookup` {Function} Custom lookup function. Defaults to [`dns.lookup()`][]. + * `lookup` {Function} Custom lookup function. **Default:** [`dns.lookup()`][]. * `callback` {Function} Attached as a listener for `'message'` events. Optional. * Returns: {dgram.Socket} diff --git a/doc/api/dns.md b/doc/api/dns.md index fa7c34f654d..27c41bbf4b2 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -139,7 +139,7 @@ changes: - `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple flags may be passed by bitwise `OR`ing their values. - `all` {boolean} When `true`, the callback returns all resolved addresses in - an array. Otherwise, returns a single address. **Default:** `false` + an array. Otherwise, returns a single address. **Default:** `false`. - `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. @@ -243,7 +243,7 @@ Promise for an object with `hostname` and `service` properties. added: v0.1.27 --> - `hostname` {string} Hostname to resolve. -- `rrtype` {string} Resource record type. **Default:** `'A'` +- `rrtype` {string} Resource record type. **Default:** `'A'`. - `callback` {Function} - `err` {Error} - `records` {string[] | Object[] | Object} diff --git a/doc/api/fs.md b/doc/api/fs.md index 1d244ea21dd..61b87581a43 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1165,7 +1165,7 @@ added: v8.5.0 * `src` {string|Buffer|URL} source filename to copy * `dest` {string|Buffer|URL} destination filename of the copy operation -* `flags` {number} modifiers for copy operation. **Default:** `0` +* `flags` {number} modifiers for copy operation. **Default:** `0`. * `callback` {Function} Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it @@ -1208,7 +1208,7 @@ added: v8.5.0 * `src` {string|Buffer|URL} source filename to copy * `dest` {string|Buffer|URL} destination filename of the copy operation -* `flags` {number} modifiers for copy operation. **Default:** `0` +* `flags` {number} modifiers for copy operation. **Default:** `0`. Synchronously copies `src` to `dest`. By default, `dest` is overwritten if it already exists. Returns `undefined`. Node.js makes no guarantees about the @@ -1964,7 +1964,7 @@ changes: * `err` {Error} Asynchronously creates a directory. No arguments other than a possible exception -are given to the completion callback. `mode` defaults to `0o777`. +are given to the completion callback. See also: mkdir(2) @@ -2093,7 +2093,7 @@ changes: * `path` {string|Buffer|URL} * `flags` {string|number} -* `mode` {integer} **Default:** `0o666` +* `mode` {integer} **Default:** `0o666` (readable and writable) * `callback` {Function} * `err` {Error} * `fd` {integer} @@ -2143,7 +2143,7 @@ The file is created if it does not exist. The file is created if it does not exist. `mode` sets the file mode (permission and sticky bits), but only if the file was -created. It defaults to `0o666` (readable and writable). +created. The callback gets two arguments `(err, fd)`. @@ -2822,7 +2822,7 @@ changes: Asynchronous symlink(2). No arguments other than a possible exception are given to the completion callback. The `type` argument can be set to `'dir'`, -`'file'`, or `'junction'` (default is `'file'`) and is only available on +`'file'`, or `'junction'` and is only available on Windows (ignored on other platforms). Note that Windows junction points require the destination path to be absolute. When using `'junction'`, the `target` argument will automatically be normalized to absolute path. @@ -3044,13 +3044,13 @@ changes: * `filename` {string|Buffer|URL} * `options` {string|Object} * `persistent` {boolean} Indicates whether the process should continue to run - as long as files are being watched. **Default:** `true` + as long as files are being watched. **Default:** `true`. * `recursive` {boolean} Indicates whether all subdirectories should be watched, or only the current directory. This applies when a directory is specified, and only on supported platforms (See [Caveats][]). **Default:** - `false` + `false`. * `encoding` {string} Specifies the character encoding to be used for the - filename passed to the listener. **Default:** `'utf8'` + filename passed to the listener. **Default:** `'utf8'`. * `listener` {Function|undefined} **Default:** `undefined` * `eventType` {string} * `filename` {string|Buffer} @@ -3163,8 +3163,7 @@ The `options` argument may be omitted. If provided, it should be an object. The `options` object may contain a boolean named `persistent` that indicates whether the process should continue to run as long as files are being watched. The `options` object may specify an `interval` property indicating how often the -target should be polled in milliseconds. The default is -`{ persistent: true, interval: 5007 }`. +target should be polled in milliseconds. The `listener` gets two arguments the current stat object and the previous stat object: @@ -3337,8 +3336,7 @@ changes: Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string or a buffer. -The `encoding` option is ignored if `data` is a buffer. It defaults -to `'utf8'`. +The `encoding` option is ignored if `data` is a buffer. Example: @@ -3702,8 +3700,7 @@ Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string or a buffer. The `Promise` will be resolved with no arguments upon success. -The `encoding` option is ignored if `data` is a buffer. It defaults -to `'utf8'`. +The `encoding` option is ignored if `data` is a buffer. If `options` is a string, then it specifies the encoding. @@ -3806,7 +3803,7 @@ added: REPLACEME * `src` {string|Buffer|URL} source filename to copy * `dest` {string|Buffer|URL} destination filename of the copy operation -* `flags` {number} modifiers for copy operation. **Default:** `0` +* `flags` {number} modifiers for copy operation. **Default:** `0`. * Returns: {Promise} Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it @@ -4062,7 +4059,7 @@ added: REPLACEME * `path` {string|Buffer|URL} * `flags` {string|number} -* `mode` {integer} **Default:** `0o666` +* `mode` {integer} **Default:** `0o666` (readable and writable) * Return: {Promise} Asynchronous file open that returns a `Promise` that, when resolved, yields a @@ -4113,7 +4110,7 @@ The file is created if it does not exist. The file is created if it does not exist. `mode` sets the file mode (permission and sticky bits), but only if the file was -created. It defaults to `0o666` (readable and writable). +created. The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly created. On POSIX systems, `path` is considered to exist even if it is a symlink @@ -4311,7 +4308,7 @@ Creates a symbolic link then resolves the `Promise` with no arguments upon success. The `type` argument is only used on Windows platforms and can be one of `'dir'`, -`'file'`, or `'junction'` (default is `'file'`). Note that Windows junction +`'file'`, or `'junction'`. Note that Windows junction points require the destination path to be absolute. When using `'junction'`, the `target` argument will automatically be normalized to absolute path. @@ -4407,8 +4404,7 @@ Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string or a buffer. The `Promise` will be resolved with no arguments upon success. -The `encoding` option is ignored if `data` is a buffer. It defaults -to `'utf8'`. +The `encoding` option is ignored if `data` is a buffer. If `options` is a string, then it specifies the encoding. diff --git a/doc/api/http.md b/doc/api/http.md index fc19be72d14..07b77d77399 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -116,16 +116,16 @@ added: v0.3.4 Can have the following fields: * `keepAlive` {boolean} Keep sockets around even when there are no outstanding requests, so they can be used for future requests without - having to reestablish a TCP connection. Defaults to `false` + having to reestablish a TCP connection. **Default:** `false`. * `keepAliveMsecs` {number} When using the `keepAlive` option, specifies the [initial delay](net.html#net_socket_setkeepalive_enable_initialdelay) for TCP Keep-Alive packets. Ignored when the - `keepAlive` option is `false` or `undefined`. Defaults to `1000`. + `keepAlive` option is `false` or `undefined`. **Default:** `1000`. * `maxSockets` {number} Maximum number of sockets to allow per - host. Defaults to `Infinity`. + host. **Default:** `Infinity`. * `maxFreeSockets` {number} Maximum number of sockets to leave open in a free state. Only relevant if `keepAlive` is set to `true`. - Defaults to `256`. + **Default:** `256`. The default [`http.globalAgent`][] that is used by [`http.request()`][] has all of these values set to their respective defaults. @@ -917,17 +917,16 @@ connections. added: v0.7.0 --> -* {number} Defaults to 2000. +* {number} **Default:** `2000` -Limits maximum incoming headers count, equal to 2000 by default. If set to 0 - -no limit will be applied. +Limits maximum incoming headers count. If set to 0 - no limit will be applied. ### server.setTimeout([msecs][, callback]) -* `msecs` {number} Defaults to 120000 (2 minutes). +* `msecs` {number} **Default:** `120000` (2 minutes) * `callback` {Function} Sets the timeout value for sockets, and emits a `'timeout'` event on @@ -948,7 +947,7 @@ Returns `server`. added: v0.9.12 --> -* {number} Timeout in milliseconds. Defaults to 120000 (2 minutes). +* {number} Timeout in milliseconds. **Default:** `120000` (2 minutes). The number of milliseconds of inactivity before a socket is presumed to have timed out. @@ -963,7 +962,7 @@ value only affects new connections to the server, not any existing connections. added: v8.0.0 --> -* {number} Timeout in milliseconds. Defaults to 5000 (5 seconds). +* {number} Timeout in milliseconds. **Default:** `5000` (5 seconds). The number of milliseconds of inactivity a server needs to wait for additional incoming data, after it has finished writing the last response, before a socket @@ -1332,7 +1331,7 @@ added: v0.1.29 --> * `chunk` {string|Buffer} -* `encoding` {string} +* `encoding` {string} **Default:** `'utf8'` * `callback` {Function} * Returns: {boolean} @@ -1348,8 +1347,7 @@ _must not_ include a message body. `chunk` can be a string or a buffer. If `chunk` is a string, the second parameter specifies how to encode it into a byte stream. -By default the `encoding` is `'utf8'`. `callback` will be called when this chunk -of data is flushed. +`callback` will be called when this chunk of data is flushed. This is the raw HTTP body and has nothing to do with higher-level multi-part body encodings that may be used. @@ -1729,11 +1727,11 @@ changes: --> - `options` {Object} * `IncomingMessage` {http.IncomingMessage} Specifies the IncomingMessage class - to be used. Useful for extending the original `IncomingMessage`. Defaults - to: `IncomingMessage` + to be used. Useful for extending the original `IncomingMessage`. + **Default:** `IncomingMessage`. * `ServerResponse` {http.ServerResponse} Specifies the ServerResponse class to - be used. Useful for extending the original `ServerResponse`. Defaults to: - `ServerResponse` + be used. Useful for extending the original `ServerResponse`. **Default:** + `ServerResponse`. - `requestListener` {Function} * Returns: {http.Server} @@ -1825,24 +1823,24 @@ changes: --> * `options` {Object | string | URL} - * `protocol` {string} Protocol to use. Defaults to `http:`. + * `protocol` {string} Protocol to use. **Default:** `http:`. * `host` {string} A domain name or IP address of the server to issue the - request to. Defaults to `localhost`. + request to. **Default:** `localhost`. * `hostname` {string} Alias for `host`. To support [`url.parse()`][], `hostname` is preferred over `host`. * `family` {number} IP address family to use when resolving `host` and `hostname`. Valid values are `4` or `6`. When unspecified, both IP v4 and v6 will be used. - * `port` {number} Port of remote server. Defaults to 80. + * `port` {number} Port of remote server. **Default:** `80`. * `localAddress` {string} Local interface to bind for network connections. * `socketPath` {string} Unix Domain Socket (use one of host:port or socketPath). - * `method` {string} A string specifying the HTTP request method. Defaults to + * `method` {string} A string specifying the HTTP request method. **Default:** `'GET'`. - * `path` {string} Request path. Defaults to `'/'`. Should include query - string if any. E.G. `'/index.html?page=12'`. An exception is thrown when - the request path contains illegal characters. Currently, only spaces are - rejected but that may change in the future. + * `path` {string} Request path. Should include query string if any. + E.G. `'/index.html?page=12'`. An exception is thrown when the request path + contains illegal characters. Currently, only spaces are rejected but that + may change in the future. **Default:** `'/'`. * `headers` {Object} An object containing request headers. * `auth` {string} Basic authentication i.e. `'user:password'` to compute an Authorization header. diff --git a/doc/api/http2.md b/doc/api/http2.md index 193dd147d56..7eea50faa10 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -677,7 +677,7 @@ added: v8.4.0 * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, the created stream is made the sole direct dependency of the parent, with all other existing dependents made a dependent of the newly created stream. - **Default:** `false` + **Default:** `false`. * `parent` {number} Specifies the numeric identifier of a stream the newly created stream is dependent on. * `weight` {number} Specifies the relative dependency of a stream in relation @@ -879,7 +879,7 @@ added: v8.4.0 --> * code {number} Unsigned 32-bit integer identifying the error code. **Default:** - `http2.constants.NGHTTP2_NO_ERROR` (`0x00`) + `http2.constants.NGHTTP2_NO_ERROR` (`0x00`). * `callback` {Function} An optional function registered to listen for the `'close'` event. @@ -924,7 +924,7 @@ added: v8.4.0 * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, this stream is made the sole direct dependency of the parent, with all other existing dependents made a dependent of this stream. **Default:** - `false` + `false`. * `parent` {number} Specifies the numeric identifier of a stream this stream is dependent on. * `weight` {number} Specifies the relative dependency of a stream in relation @@ -1148,7 +1148,7 @@ added: v8.4.0 * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, the created stream is made the sole direct dependency of the parent, with all other existing dependents made a dependent of the newly created stream. - **Default:** `false` + **Default:** `false`. * `parent` {number} Specifies the numeric identifier of a stream the newly created stream is dependent on. * `callback` {Function} Callback that is called once the push stream has been @@ -1665,20 +1665,20 @@ changes: * `options` {Object} * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size - for deflating header fields. **Default:** `4Kib` + for deflating header fields. **Default:** `4Kib`. * `maxSessionMemory`{number} Sets the maximum memory that the `Http2Session` is permitted to use. The value is expressed in terms of number of megabytes, - e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. **Default:** - `10`. This is a credit based limit, existing `Http2Stream`s may cause this + e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. + This is a credit based limit, existing `Http2Stream`s may cause this limit to be exceeded, but new `Http2Stream` instances will be rejected while this limit is exceeded. The current number of `Http2Stream` sessions, the current memory use of the header compression tables, current data queued to be sent, and unacknowledged PING and SETTINGS frames are all - counted towards the current limit. + counted towards the current limit. **Default:** `10`. * `maxHeaderListPairs` {number} Sets the maximum number of header entries. - **Default:** `128`. The minimum value is `4`. + The minimum value is `4`. **Default:** `128`. * `maxOutstandingPings` {number} Sets the maximum number of outstanding, - unacknowledged pings. The default is `10`. + unacknowledged pings. **Default:** `10`. * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a serialized, compressed block of headers. Attempts to send headers that exceed this limit will result in a `'frameError'` event being emitted @@ -1704,7 +1704,7 @@ changes: * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a SETTINGS frame had been received. Will be overridden if the remote peer sets its own value for - `maxConcurrentStreams`. **Default:** `100` + `maxConcurrentStreams`. **Default:** `100`. * `selectPadding` {Function} When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function used to determine the padding. See [Using options.selectPadding][]. @@ -1712,18 +1712,18 @@ changes: remote peer upon connection. * `Http1IncomingMessage` {http.IncomingMessage} Specifies the IncomingMessage class to used for HTTP/1 fallback. Useful for extending the original - `http.IncomingMessage`. **Default:** `http.IncomingMessage` + `http.IncomingMessage`. **Default:** `http.IncomingMessage`. * `Http1ServerResponse` {http.ServerResponse} Specifies the ServerResponse class to used for HTTP/1 fallback. Useful for extending the original - `http.ServerResponse`. **Default:** `http.ServerResponse` + `http.ServerResponse`. **Default:** `http.ServerResponse`. * `Http2ServerRequest` {http2.Http2ServerRequest} Specifies the Http2ServerRequest class to use. Useful for extending the original `Http2ServerRequest`. - **Default:** `Http2ServerRequest` + **Default:** `Http2ServerRequest`. * `Http2ServerResponse` {http2.Http2ServerResponse} Specifies the Http2ServerResponse class to use. Useful for extending the original `Http2ServerResponse`. - **Default:** `Http2ServerResponse` + **Default:** `Http2ServerResponse`. * `onRequestHandler` {Function} See [Compatibility API][] * Returns: {Http2Server} @@ -1771,23 +1771,24 @@ changes: * `options` {Object} * `allowHTTP1` {boolean} Incoming client connections that do not support - HTTP/2 will be downgraded to HTTP/1.x when set to `true`. **Default:** - `false`. See the [`'unknownProtocol'`][] event. See [ALPN negotiation][]. + HTTP/2 will be downgraded to HTTP/1.x when set to `true`. + See the [`'unknownProtocol'`][] event. See [ALPN negotiation][]. + **Default:** `false`. * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size - for deflating header fields. **Default:** `4Kib` + for deflating header fields. **Default:** `4Kib`. * `maxSessionMemory`{number} Sets the maximum memory that the `Http2Session` is permitted to use. The value is expressed in terms of number of megabytes, - e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. **Default:** - `10`. This is a credit based limit, existing `Http2Stream`s may cause this + e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. This is a + credit based limit, existing `Http2Stream`s may cause this limit to be exceeded, but new `Http2Stream` instances will be rejected while this limit is exceeded. The current number of `Http2Stream` sessions, the current memory use of the header compression tables, current data queued to be sent, and unacknowledged PING and SETTINGS frames are all - counted towards the current limit. + counted towards the current limit. **Default:** `10`. * `maxHeaderListPairs` {number} Sets the maximum number of header entries. - **Default:** `128`. The minimum value is `4`. + The minimum value is `4`. **Default:** `128`. * `maxOutstandingPings` {number} Sets the maximum number of outstanding, - unacknowledged pings. The default is `10`. + unacknowledged pings. **Default:** `10`. * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a serialized, compressed block of headers. Attempts to send headers that exceed this limit will result in a `'frameError'` event being emitted @@ -1813,7 +1814,7 @@ changes: * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a SETTINGS frame had been received. Will be overridden if the remote peer sets its own value for - `maxConcurrentStreams`. **Default:** `100` + `maxConcurrentStreams`. **Default:** `100`. * `selectPadding` {Function} When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function used to determine the padding. See [Using options.selectPadding][]. @@ -1866,20 +1867,20 @@ changes: * `authority` {string|URL} * `options` {Object} * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size - for deflating header fields. **Default:** `4Kib` + for deflating header fields. **Default:** `4Kib`. * `maxSessionMemory`{number} Sets the maximum memory that the `Http2Session` is permitted to use. The value is expressed in terms of number of megabytes, - e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. **Default:** - `10`. This is a credit based limit, existing `Http2Stream`s may cause this + e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. + This is a credit based limit, existing `Http2Stream`s may cause this limit to be exceeded, but new `Http2Stream` instances will be rejected while this limit is exceeded. The current number of `Http2Stream` sessions, the current memory use of the header compression tables, current data queued to be sent, and unacknowledged PING and SETTINGS frames are all - counted towards the current limit. + counted towards the current limit. **Default:** `10`. * `maxHeaderListPairs` {number} Sets the maximum number of header entries. - **Default:** `128`. The minimum value is `1`. + The minimum value is `1`. **Default:** `128`. * `maxOutstandingPings` {number} Sets the maximum number of outstanding, - unacknowledged pings. The default is `10`. + unacknowledged pings. **Default:** `10`. * `maxReservedRemoteStreams` {number} Sets the maximum number of reserved push streams the client will accept at any given time. Once the current number of currently reserved push streams exceeds reaches this limit, new push streams @@ -1909,7 +1910,7 @@ changes: * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a SETTINGS frame had been received. Will be overridden if the remote peer sets its own value for - `maxConcurrentStreams`. **Default:** `100` + `maxConcurrentStreams`. **Default:** `100`. * `selectPadding` {Function} When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function used to determine the padding. See [Using options.selectPadding][]. @@ -2052,16 +2053,16 @@ These objects are ordinary JavaScript objects containing the following properties. * `headerTableSize` {number} Specifies the maximum number of bytes used for - header compression. **Default:** `4,096 octets`. The minimum allowed - value is 0. The maximum allowed value is 232-1. + header compression. The minimum allowed value is 0. The maximum allowed value + is 232-1. **Default:** `4,096 octets`. * `enablePush` {boolean} Specifies `true` if HTTP/2 Push Streams are to be permitted on the `Http2Session` instances. * `initialWindowSize` {number} Specifies the *senders* initial window size - for stream-level flow control. **Default:** `65,535 bytes`. The minimum - allowed value is 0. The maximum allowed value is 232-1. + for stream-level flow control. The minimum allowed value is 0. The maximum + allowed value is 232-1. **Default:** `65,535 bytes`. * `maxFrameSize` {number} Specifies the size of the largest frame payload. - **Default:** `16,384 bytes`. The minimum allowed value is 16,384. The maximum - allowed value is 224-1. + The minimum allowed value is 16,384. The maximum allowed value + is 224-1. **Default:** `16,384 bytes`. * `maxConcurrentStreams` {number} Specifies the maximum number of concurrent streams permitted on an `Http2Session`. There is no default value which implies, at least theoretically, 231-1 streams may be open @@ -2069,7 +2070,7 @@ properties. is 0. The maximum allowed value is 231-1. * `maxHeaderListSize` {number} Specifies the maximum size (uncompressed octets) of header list that will be accepted. The minimum allowed value is 0. The - maximum allowed value is 232-1. **Default:** 65535. + maximum allowed value is 232-1. **Default:** `65535`. All additional properties on the settings object are ignored. diff --git a/doc/api/https.md b/doc/api/https.md index 8c95487cb5b..131553c2119 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -40,7 +40,7 @@ This method is identical to [`server.listen()`][] from [`net.Server`][]. -- `msecs` {number} Defaults to 120000 (2 minutes). +- `msecs` {number} **Default:** `120000` (2 minutes) - `callback` {Function} See [`http.Server#setTimeout()`][]. @@ -49,7 +49,7 @@ See [`http.Server#setTimeout()`][]. -- {number} Defaults to 120000 (2 minutes). +- {number} **Default:** `120000` (2 minutes) See [`http.Server#timeout`][]. @@ -57,7 +57,7 @@ See [`http.Server#timeout`][]. -- {number} Defaults to 5000 (5 seconds). +- {number} **Default:** `5000` (5 seconds) See [`http.Server#keepAliveTimeout`][]. @@ -160,9 +160,9 @@ changes: --> - `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`. + - `protocol` **Default:** `https:` + - `port` **Default:** `443` + - `agent` **Default:** `https.globalAgent` - `callback` {Function} diff --git a/doc/api/inspector.md b/doc/api/inspector.md index 9dafdb7e1b3..8a6dc188b08 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -14,12 +14,12 @@ const inspector = require('inspector'); ## inspector.open([port[, host[, wait]]]) -* port {number} Port to listen on for inspector connections. Optional, - defaults to what was specified on the CLI. -* host {string} Host to listen on for inspector connections. Optional, - defaults to what was specified on the CLI. -* wait {boolean} Block until a client has connected. Optional, defaults - to false. +* `port` {number} Port to listen on for inspector connections. Optional. + **Default:** what was specified on the CLI. +* `host` {string} Host to listen on for inspector connections. Optional. + **Default:** what was specified on the CLI. +* `wait` {boolean} Block until a client has connected. Optional. + **Default:** `false`. Activate inspector on host and port. Equivalent to `node --inspect=[[host:]port]`, but can be done programmatically after node has diff --git a/doc/api/net.md b/doc/api/net.md index 121dc552e84..1df54122290 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -383,11 +383,11 @@ Creates a new socket object. the given file descriptor, otherwise a new socket will be created. * `allowHalfOpen` {boolean} Indicates whether half-opened TCP connections are allowed. See [`net.createServer()`][] and the [`'end'`][] event - for details. **Default:** `false` + for details. **Default:** `false`. * `readable` {boolean} Allow reads on the socket when an `fd` is passed, - otherwise ignored. **Default:** `false` + otherwise ignored. **Default:** `false`. * `writable` {boolean} Allow writes on the socket when an `fd` is passed, - otherwise ignored. **Default:** `false` + otherwise ignored. **Default:** `false`. * Returns: {net.Socket} The newly created socket can be either a TCP socket or a streaming [IPC][] @@ -578,12 +578,13 @@ this only when implementing a custom Socket. For TCP connections, available `options` are: * `port` {number} Required. Port the socket should connect to. -* `host` {string} Host the socket should connect to. **Default:** `'localhost'` +* `host` {string} Host the socket should connect to. **Default:** `'localhost'`. * `localAddress` {string} Local address the socket should connect from. * `localPort` {number} Local port the socket should connect from. -* `family` {number}: Version of IP stack, can be either 4 or 6. **Default:** `4` +* `family` {number}: Version of IP stack, can be either `4` or `6`. + **Default:** `4`. * `hints` {number} Optional [`dns.lookup()` hints][]. -* `lookup` {Function} Custom lookup function. **Default:** [`dns.lookup()`][] +* `lookup` {Function} Custom lookup function. **Default:** [`dns.lookup()`][]. For [IPC][] connections, available `options` are: @@ -752,28 +753,29 @@ Set the encoding for the socket as a [Readable Stream][]. See added: v0.1.92 --> +* `enable` {boolean} **Default:** `false` +* `initialDelay` {number} **Default:** `0` * Returns: {net.Socket} The socket itself. Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. -`enable` defaults to `false`. Set `initialDelay` (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Setting 0 for initialDelay will leave the value unchanged from the default -(or previous) setting. Defaults to `0`. +(or previous) setting. ### socket.setNoDelay([noDelay]) +* `noDelay` {boolean} **Default:** `true` * Returns: {net.Socket} The socket itself. Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off. Setting `true` for `noDelay` will immediately fire off data each time `socket.write()` is called. -`noDelay` defaults to `true`. ### socket.setTimeout(timeout[, callback]) -* `code` {integer} The exit code. Defaults to `0`. +* `code` {integer} The exit code. **Default:** `0`. The `process.exit()` method instructs Node.js to terminate the process synchronously with an exit status of `code`. If `code` is omitted, exit uses @@ -1214,7 +1214,7 @@ added: v0.0.6 * `pid` {number} A process ID * `signal` {string|number} The signal to send, either as a string or number. - Defaults to `'SIGTERM'`. + **Default:** `'SIGTERM'`. The `process.kill()` method sends the `signal` to the process identified by `pid`. diff --git a/doc/api/querystring.md b/doc/api/querystring.md index cbf503af916..693bb0a8a40 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -46,15 +46,15 @@ changes: * `str` {string} The URL query string to parse * `sep` {string} The substring used to delimit key and value pairs in the - query string. Defaults to `'&'`. + query string. **Default:** `'&'`. * `eq` {string}. The substring used to delimit keys and values in the - query string. Defaults to `'='`. + query string. **Default:** `'='`. * `options` {Object} * `decodeURIComponent` {Function} The function to use when decoding - percent-encoded characters in the query string. Defaults to + percent-encoded characters in the query string. **Default:** `querystring.unescape()`. * `maxKeys` {number} Specifies the maximum number of keys to parse. - Defaults to `1000`. Specify `0` to remove key counting limitations. + Specify `0` to remove key counting limitations. **Default:** `1000`. The `querystring.parse()` method parses a URL query string (`str`) into a collection of key and value pairs. @@ -93,12 +93,12 @@ added: v0.1.25 * `obj` {Object} The object to serialize into a URL query string * `sep` {string} The substring used to delimit key and value pairs in the - query string. Defaults to `'&'`. + query string. **Default:** `'&'`. * `eq` {string}. The substring used to delimit keys and values in the - query string. Defaults to `'='`. + query string. **Default:** `'='`. * `options` * `encodeURIComponent` {Function} The function to use when converting - URL-unsafe characters to percent-encoding in the query string. Defaults to + URL-unsafe characters to percent-encoding in the query string. **Default:** `querystring.escape()`. The `querystring.stringify()` method produces a URL query string from a diff --git a/doc/api/readline.md b/doc/api/readline.md index 2d6731ddb2a..a1411a621c7 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -357,22 +357,22 @@ changes: * `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. + **Default:** 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` - * `prompt` {string} The prompt string to use. **Default:** `'> '` + **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` + [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` + from the list. **Default:** `false`. The `readline.createInterface()` method creates a new `readline.Interface` instance. diff --git a/doc/api/repl.md b/doc/api/repl.md index 9e6d1e8a1ed..a834862a607 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -430,33 +430,33 @@ changes: --> * `options` {Object|string} - * `prompt` {string} The input prompt to display. Defaults to `> ` + * `prompt` {string} The input prompt to display. **Default:** `> `. (with a trailing space). * `input` {stream.Readable} The Readable stream from which REPL input will be - read. Defaults to `process.stdin`. + read. **Default:** `process.stdin`. * `output` {stream.Writable} The Writable stream to which REPL output will be - written. Defaults to `process.stdout`. + written. **Default:** `process.stdout`. * `terminal` {boolean} If `true`, specifies that the `output` should be treated as a TTY terminal, and have ANSI/VT100 escape codes written to it. - Defaults to checking the value of the `isTTY` property on the `output` + **Default:** checking the value of the `isTTY` property on the `output` stream upon instantiation. * `eval` {Function} The function to be used when evaluating each given line - of input. Defaults to an async wrapper for the JavaScript `eval()` + of input. **Default:** an async wrapper for the JavaScript `eval()` function. An `eval` function can error with `repl.Recoverable` to indicate the input was incomplete and prompt for additional lines. * `useColors` {boolean} If `true`, specifies that the default `writer` function should include ANSI color styling to REPL output. If a custom - `writer` function is provided then this has no effect. Defaults to the + `writer` function is provided then this has no effect. **Default:** the REPL instances `terminal` value. * `useGlobal` {boolean} If `true`, specifies that the default evaluation function will use the JavaScript `global` as the context as opposed to creating a new separate context for the REPL instance. The node CLI REPL - sets this value to `true`. Defaults to `false`. + sets this value to `true`. **Default:** `false`. * `ignoreUndefined` {boolean} If `true`, specifies that the default writer will not output the return value of a command if it evaluates to - `undefined`. Defaults to `false`. + `undefined`. **Default:** `false`. * `writer` {Function} The function to invoke to format the output of each - command before writing to `output`. Defaults to [`util.inspect()`][]. + command before writing to `output`. **Default:** [`util.inspect()`][]. * `completer` {Function} An optional function used for custom Tab auto completion. See [`readline.InterfaceCompleter`][] for an example. * `replMode` {symbol} A flag that specifies whether the default evaluator @@ -467,7 +467,7 @@ changes: equivalent to prefacing every repl statement with `'use strict'`. * `breakEvalOnSigint` - Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is pressed. This cannot be used together - with a custom `eval` function. Defaults to `false`. + with a custom `eval` function. **Default:** `false`. The `repl.start()` method creates and starts a `repl.REPLServer` instance. @@ -510,10 +510,11 @@ environment variables: will be saved to the specified file rather than `.node_repl_history` in the user's home directory. Setting this value to `""` will disable persistent REPL history. Whitespace will be trimmed from the value. - - `NODE_REPL_HISTORY_SIZE` - Defaults to `1000`. Controls how many lines of - history will be persisted if history is available. Must be a positive number. - - `NODE_REPL_MODE` - May be either `sloppy` or `strict`. Defaults - to `sloppy`, which will allow non-strict mode code to be run. + - `NODE_REPL_HISTORY_SIZE` - Controls how many lines of history will be + persisted if history is available. Must be a positive number. + **Default:** `1000`. + - `NODE_REPL_MODE` - May be either `sloppy` or `strict`. **Default:** `sloppy`, + which will allow non-strict mode code to be run. ### Persistent History diff --git a/doc/api/stream.md b/doc/api/stream.md index 252ed15ceae..c2e5de79efe 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -873,7 +873,7 @@ added: v0.9.4 * `destination` {stream.Writable} The destination for writing data * `options` {Object} Pipe options - * `end` {boolean} End the writer when the reader ends. Defaults to `true`. + * `end` {boolean} End the writer when the reader ends. **Default:** `true`. * Returns: {stream.Writable} making it possible to set up chains of piped streams @@ -1405,18 +1405,18 @@ changes: * `options` {Object} * `highWaterMark` {number} Buffer level when - [`stream.write()`][stream-write] starts returning `false`. Defaults to + [`stream.write()`][stream-write] starts returning `false`. **Default:** `16384` (16kb), or `16` for `objectMode` streams. * `decodeStrings` {boolean} Whether or not to decode strings into Buffers before passing them to [`stream._write()`][stream-_write]. - Defaults to `true` + **Default:** `true`. * `objectMode` {boolean} Whether or not the [`stream.write(anyObj)`][stream-write] is a valid operation. When set, it becomes possible to write JavaScript values other than string, `Buffer` or `Uint8Array` if supported by the stream implementation. - Defaults to `false` + **Default:** `false`. * `emitClose` {boolean} Whether or not the stream should emit `close` - after it has been destroyed. Defaults to `true` + after it has been destroyed. **Default:** `true`. * `write` {Function} Implementation for the [`stream._write()`][stream-_write] method. * `writev` {Function} Implementation for the @@ -1666,12 +1666,12 @@ constructor and implement the `readable._read()` method. * `options` {Object} * `highWaterMark` {number} The maximum [number of bytes][hwm-gotcha] to store in the internal buffer before ceasing to read from the underlying resource. - Defaults to `16384` (16kb), or `16` for `objectMode` streams + **Default:** `16384` (16kb), or `16` for `objectMode` streams. * `encoding` {string} If specified, then buffers will be decoded to - strings using the specified encoding. Defaults to `null` + strings using the specified encoding. **Default:** `null`. * `objectMode` {boolean} Whether this stream should behave as a stream of objects. Meaning that [`stream.read(n)`][stream-read] returns - a single value instead of a Buffer of size n. Defaults to `false` + a single value instead of a Buffer of size n. **Default:** `false`. * `read` {Function} Implementation for the [`stream._read()`][stream-_read] method. * `destroy` {Function} Implementation for the @@ -1923,15 +1923,13 @@ changes: * `options` {Object} Passed to both Writable and Readable constructors. Also has the following fields: - * `allowHalfOpen` {boolean} Defaults to `true`. If set to `false`, then - the stream will automatically end the writable side when the - readable side ends. - * `readableObjectMode` {boolean} Defaults to `false`. Sets `objectMode` - for readable side of the stream. Has no effect if `objectMode` - is `true`. - * `writableObjectMode` {boolean} Defaults to `false`. Sets `objectMode` - for writable side of the stream. Has no effect if `objectMode` - is `true`. + * `allowHalfOpen` {boolean} If set to `false`, then the stream will + automatically end the writable side when the readable side ends. + **Default:** `true`. + * `readableObjectMode` {boolean} Sets `objectMode` for readable side of the + stream. Has no effect if `objectMode` is `true`. **Default:** `false`. + * `writableObjectMode` {boolean} Sets `objectMode` for writable side of the + stream. Has no effect if `objectMode` is `true`. **Default:** `false`. * `readableHighWaterMark` {number} Sets `highWaterMark` for the readable side of the stream. Has no effect if `highWaterMark` is provided. * `writableHighWaterMark` {number} Sets `highWaterMark` for the writable side diff --git a/doc/api/string_decoder.md b/doc/api/string_decoder.md index cde81e6ae5e..224d208e9cc 100644 --- a/doc/api/string_decoder.md +++ b/doc/api/string_decoder.md @@ -48,7 +48,7 @@ added: v0.1.99 --> * `encoding` {string} The character encoding the `StringDecoder` will use. - Defaults to `'utf8'`. + **Default:** `'utf8'`. Creates a new `StringDecoder` instance. diff --git a/doc/api/tls.md b/doc/api/tls.md index f519681c62a..a4328eda31c 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -129,9 +129,9 @@ An `'error'` event is emitted on the [`tls.TLSSocket`][] instance when this threshold is exceeded. The limits are configurable: * `tls.CLIENT_RENEG_LIMIT` {number} Specifies the number of renegotiation - requests. Defaults to `3`. + requests. **Default:** `3`. * `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window - in seconds. Defaults to `600` (10 minutes). + in seconds. **Default:** `600` (10 minutes). The default renegotiation limits should not be modified without a full understanding of the implications and risks. @@ -453,7 +453,7 @@ changes: * `options` {Object} * `isServer`: The SSL/TLS protocol is asymmetrical, TLSSockets must know if they are to behave as a server or a client. If `true` the TLS socket will be - instantiated as a server. Defaults to `false`. + instantiated as a server. **Default:** `false`. * `server` {net.Server} An optional [`net.Server`][] instance. * `requestCert`: Whether to authenticate the remote peer by requesting a certificate. Clients always request a server certificate. Servers @@ -737,7 +737,7 @@ 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 - verification fails; `err.code` contains the OpenSSL error code. Defaults to + verification fails; `err.code` contains the OpenSSL error code. **Default:** `true`. * `requestCert` * `callback` {Function} A function that will be called when the renegotiation @@ -758,8 +758,8 @@ When running as the server, the socket will be destroyed with an error after added: v0.11.11 --> -* `size` {number} The maximum TLS fragment size. Defaults to `16384`. The - maximum value is `16384`. +* `size` {number} The maximum TLS fragment size. The maximum value is `16384`. + **Default:** `16384`. The `tlsSocket.setMaxSendFragment()` method sets the maximum TLS fragment size. Returns `true` if setting the limit succeeded; `false` otherwise. @@ -842,7 +842,8 @@ changes: --> * `options` {Object} - * `host` {string} Host the client should connect to, defaults to 'localhost'. + * `host` {string} Host the client should connect to. **Default:** + `'localhost'`. * `port` {number} Port the client should connect to. * `path` {string} Creates unix socket connection to path. If this option is specified, `host` and `port` are ignored. @@ -857,7 +858,7 @@ changes: called. * `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 + verification fails; `err.code` contains the OpenSSL error code. **Default:** `true`. * `ALPNProtocols`: {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or @@ -877,12 +878,13 @@ changes: * `minDHSize` {number} Minimum size of the DH parameter in bits to accept a TLS connection. When a server offers a DH parameter with a size less than `minDHSize`, the TLS connection is destroyed and an error is thrown. - Defaults to `1024`. + **Default:** `1024`. * `secureContext`: Optional TLS context object created with [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one will be created by passing the entire `options` object to `tls.createSecureContext()`. - * `lookup`: {Function} Custom lookup function. Defaults to [`dns.lookup()`][]. + * `lookup`: {Function} Custom lookup function. **Default:** + [`dns.lookup()`][]. * ...: Optional [`tls.createSecureContext()`][] options that are used if the `secureContext` option is missing, otherwise they are ignored. * `callback` {Function} @@ -1049,10 +1051,10 @@ changes: * `ecdhCurve` {string} A string describing a named curve or a colon separated list of curve NIDs or names, for example `P-521:P-384:P-256`, to use for ECDH key agreement, or `false` to disable ECDH. Set to `auto` to select the - curve automatically. Defaults to [`tls.DEFAULT_ECDH_CURVE`]. Use - [`crypto.getCurves()`][] to obtain a list of available curve names. On - recent releases, `openssl ecparam -list_curves` will also display the name - and description of each available elliptic curve. + curve automatically. Use [`crypto.getCurves()`][] to obtain a list of + available curve names. On recent releases, `openssl ecparam -list_curves` + will also display the name and description of each available elliptic curve. + **Default:** [`tls.DEFAULT_ECDH_CURVE`]. * `clientCertEngine` {string} Optional name of an OpenSSL engine which can provide the client certificate. * `crl` {string|string[]|Buffer|Buffer[]} Optional PEM formatted @@ -1067,10 +1069,10 @@ changes: which is not usually necessary. This should be used carefully if at all! Value is a numeric bitmask of the `SSL_OP_*` options from [OpenSSL Options][]. - * `secureProtocol` {string} Optional SSL method to use, default is - `"SSLv23_method"`. The possible values are listed as [SSL_METHODS][], use - the function names as strings. For example, `"SSLv3_method"` to force SSL - version 3. + * `secureProtocol` {string} Optional SSL method to use. The possible values + are listed as [SSL_METHODS][], use the function names as strings. + For example, `'SSLv3_method'` to force SSL version 3. **Default:** + `'SSLv23_method'`. * `sessionIdContext` {string} Optional opaque identifier used by servers to ensure session state is not shared between applications. Unused by clients. @@ -1110,15 +1112,15 @@ changes: * `clientCertEngine` {string} Optional name of an OpenSSL engine which can provide the client certificate. * `handshakeTimeout` {number} Abort the connection if the SSL/TLS handshake - does not finish in the specified number of milliseconds. Defaults to - `120000` (120 seconds). A `'tlsClientError'` is emitted on the `tls.Server` - object whenever a handshake times out. + does not finish in the specified number of milliseconds. + A `'tlsClientError'` is emitted on the `tls.Server` object whenever + a handshake times out. **Default:** `120000` (120 seconds). * `requestCert` {boolean} If `true` the server will request a certificate from - clients that connect and attempt to verify that certificate. Defaults to + clients that connect and attempt to verify that certificate. **Default:** `false`. * `rejectUnauthorized` {boolean} If not `false` the server will reject any connection which is not authorized with the list of supplied CAs. This - option only has an effect if `requestCert` is `true`. Defaults to `true`. + option only has an effect if `requestCert` is `true`. **Default:** `true`. * `ALPNProtocols`: {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or `Uint8Array` containing the supported ALPN protocols. `Buffer`s should have @@ -1302,7 +1304,7 @@ changes: * `secureContext`: An optional TLS context object from [`tls.createSecureContext()`][] * `isServer`: If `true` the TLS socket will be instantiated in server-mode. - Defaults to `false`. + **Default:** `false`. * `server` {net.Server} An optional [`net.Server`][] instance * `requestCert`: Optional, see [`tls.createServer()`][] * `rejectUnauthorized`: Optional, see [`tls.createServer()`][] diff --git a/doc/api/tty.md b/doc/api/tty.md index 3aa5eb8e4a2..193005c017d 100644 --- a/doc/api/tty.md +++ b/doc/api/tty.md @@ -127,7 +127,7 @@ added: v9.9.0 --> * `env` {Object} A object containing the environment variables to check. - Defaults to `process.env`. + **Default:** `process.env`. * Returns: {number} Returns: diff --git a/doc/api/url.md b/doc/api/url.md index 2c12e9ac293..46b3a40f94f 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -793,14 +793,14 @@ added: v7.6.0 * `URL` {URL} A [WHATWG URL][] object * `options` {Object} * `auth` {boolean} `true` if the serialized URL string should include the - username and password, `false` otherwise. Defaults to `true`. + username and password, `false` otherwise. **Default:** `true`. * `fragment` {boolean} `true` if the serialized URL string should include the - fragment, `false` otherwise. Defaults to `true`. + fragment, `false` otherwise. **Default:** `true`. * `search` {boolean} `true` if the serialized URL string should include the - search query, `false` otherwise. Defaults to `true`. + search query, `false` otherwise. **Default:** `true`. * `unicode` {boolean} `true` if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to being - Punycode encoded. Defaults to `false`. + Punycode encoded. **Default:** `false`. Returns a customizable serialization of a URL String representation of a [WHATWG URL][] object. @@ -1032,12 +1032,12 @@ changes: * `parseQueryString` {boolean} If `true`, the `query` property will always be set to an object returned by the [`querystring`][] module's `parse()` method. If `false`, the `query` property on the returned URL object will be an - unparsed, undecoded string. Defaults to `false`. + unparsed, undecoded string. **Default:** `false`. * `slashesDenoteHost` {boolean} If `true`, the first token after the literal string `//` and preceding the next `/` will be interpreted as the `host`. For instance, given `//foo/bar`, the result would be `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`. - Defaults to `false`. + **Default:** `false`. The `url.parse()` method takes a URL string, parses it, and returns a URL object. diff --git a/doc/api/util.md b/doc/api/util.md index 9253d46351d..caee5990fb1 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -373,37 +373,37 @@ changes: * `options` {Object} * `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and properties will be included in the formatted result as well as [`WeakMap`][] - and [`WeakSet`][] entries. Defaults to `false`. + and [`WeakSet`][] entries. **Default:** `false`. * `colors` {boolean} If `true`, the output will be styled with ANSI color - codes. Defaults to `false`. Colors are customizable, see - [Customizing `util.inspect` colors][]. + codes. Colors are customizable, see [Customizing `util.inspect` colors][]. + **Default:** `false`. * `customInspect` {boolean} If `false`, then custom `inspect(depth, opts)` - functions will not be called. Defaults to `true`. + functions will not be called. **Default:** `true`. * `showProxy` {boolean} If `true`, then objects and functions that are `Proxy` objects will be introspected to show their `target` and `handler` - objects. Defaults to `false`. + objects. **Default:** `false`. * `maxArrayLength` {number} Specifies the maximum number of `Array`, [`TypedArray`][], [`WeakMap`][] and [`WeakSet`][] elements to include when - formatting. Defaults to `100`. Set to `null` or `Infinity` to show all - elements. Set to `0` or negative to show no elements. + formatting. Set to `null` or `Infinity` to show all elements. Set to `0` or + negative to show no elements. **Default:** `100`. * `breakLength` {number} The length at which an object's keys are split across multiple lines. Set to `Infinity` to format an object as a single - line. Defaults to 60 for legacy compatibility. + line. **Default:** `60` for legacy compatibility. * `compact` {boolean} Setting this to `false` changes the default indentation to use a line break for each object key instead of lining up multiple properties in one line. It will also break text that is above the `breakLength` size into smaller and better readable chunks and indents objects the same as arrays. Note that no text will be reduced below 16 characters, no matter the `breakLength` size. For more information, see the - example below. Defaults to `true`. + example below. **Default:** `true`. * `depth` {number} Specifies the number visible nested Objects in an `object`. This is useful to minimize the inspection output for large complicated - objects. To make it recurse indefinitely pass `null` or `Infinity`. Defaults - to `Infinity`. + objects. To make it recurse indefinitely pass `null` or `Infinity`. + **Default:** `Infinity`. * Returns: {string} The representation of passed object The `util.inspect()` method returns a string representation of `object` that is @@ -842,15 +842,15 @@ is not supported. ### new TextDecoder([encoding[, options]]) * `encoding` {string} Identifies the `encoding` that this `TextDecoder` instance - supports. Defaults to `'utf-8'`. + supports. **Default:** `'utf-8'`. * `options` {Object} - * `fatal` {boolean} `true` if decoding failures are fatal. Defaults to - `false`. This option is only supported when ICU is enabled (see - [Internationalization][]). + * `fatal` {boolean} `true` if decoding failures are fatal. This option is only + supported when ICU is enabled (see [Internationalization][]). **Default:** + `false`. * `ignoreBOM` {boolean} When `true`, the `TextDecoder` will include the byte order mark in the decoded result. When `false`, the byte order mark will be removed from the output. This option is only used when `encoding` is - `'utf-8'`, `'utf-16be'` or `'utf-16le'`. Defaults to `false`. + `'utf-8'`, `'utf-16be'` or `'utf-16le'`. **Default:** `false`. Creates an new `TextDecoder` instance. The `encoding` may specify one of the supported encodings or an alias. @@ -861,7 +861,7 @@ supported encodings or an alias. Typed Array instance containing the encoded data. * `options` {Object} * `stream` {boolean} `true` if additional chunks of data are expected. - Defaults to `false`. + **Default:** `false`. * Returns: {string} Decodes the `input` and returns a string. If `options.stream` is `true`, any @@ -906,7 +906,7 @@ const uint8array = encoder.encode('this is some data'); ### textEncoder.encode([input]) -* `input` {string} The text to encode. Defaults to an empty string. +* `input` {string} The text to encode. **Default:** an empty string. * Returns: {Uint8Array} UTF-8 encodes the `input` string and returns a `Uint8Array` containing the diff --git a/doc/api/v8.md b/doc/api/v8.md index f929fe6a03e..c18e2691f64 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -285,13 +285,11 @@ by subclasses. #### serializer.\_setTreatArrayBufferViewsAsHostObjects(flag) -* `flag` {boolean} +* `flag` {boolean} **Default:** `false` Indicate whether to treat `TypedArray` and `DataView` objects as host objects, i.e. pass them to [`serializer._writeHostObject()`][]. -The default is not to treat those objects as host objects. - ### class: v8.Deserializer -`kind` defaults to `zlib.constants.Z_FULL_FLUSH`. +* `kind` **Default:** `zlib.constants.Z_FULL_FLUSH` Flush pending data. Don't call this frivolously, premature flushes negatively impact the effectiveness of the compression algorithm. diff --git a/tools/doc/json.js b/tools/doc/json.js index 87122cea70f..fe0d9526f5b 100644 --- a/tools/doc/json.js +++ b/tools/doc/json.js @@ -399,10 +399,10 @@ function parseListItem(item) { } text = text.trim(); - const defaultExpr = /\(default\s*[:=]?\s*['"`]?([^, '"`]*)['"`]?\)/i; + const defaultExpr = /\s*\*\*Default:\*\*\s*([^]+)$/i; const def = text.match(defaultExpr); if (def) { - item.default = def[1]; + item.default = def[1].replace(/\.$/, ''); text = text.replace(defaultExpr, ''); } From de0053cc3280bdf72c9010f383290f79120a1e98 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Mon, 2 Apr 2018 08:38:48 +0300 Subject: [PATCH 15/22] doc: fix various nits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Replace 2 hyphens (--) by spaced m-dashes (—) as per STYLE_GUIDE.md. * Space infix operators. * Unify quotes in inline code spans (use only single quotes). * Unify `* Returns:` (eliminate deviations). * Dedupe spaces. PR-URL: https://github.com/nodejs/node/pull/19743 Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat --- doc/api/addons.md | 2 +- doc/api/async_hooks.md | 2 +- doc/api/buffer.md | 12 ++++----- doc/api/child_process.md | 22 +++++++-------- doc/api/cli.md | 4 +-- doc/api/cluster.md | 12 ++++----- doc/api/console.md | 2 +- doc/api/crypto.md | 6 ++--- doc/api/debugger.md | 2 +- doc/api/deprecations.md | 2 +- doc/api/dgram.md | 30 ++++++++++----------- doc/api/dns.md | 22 +++++++-------- doc/api/domain.md | 30 ++++++++++----------- doc/api/errors.md | 16 +++++------ doc/api/esm.md | 14 +++++----- doc/api/fs.md | 46 +++++++++++++++---------------- doc/api/http.md | 58 ++++++++++++++++++++-------------------- doc/api/http2.md | 26 +++++++++--------- doc/api/https.md | 2 +- doc/api/modules.md | 46 +++++++++++++++---------------- doc/api/n-api.md | 26 +++++++++--------- doc/api/net.md | 16 +++++------ doc/api/os.md | 4 +-- doc/api/path.md | 6 ++--- doc/api/process.md | 40 +++++++++++++-------------- doc/api/readline.md | 2 +- doc/api/repl.md | 6 ++--- doc/api/stream.md | 6 ++--- doc/api/tls.md | 16 +++++------ doc/api/url.md | 4 +-- doc/api/util.md | 10 +++---- doc/api/v8.md | 2 +- doc/api/vm.md | 4 +-- doc/api/zlib.md | 16 +++++------ 34 files changed, 257 insertions(+), 257 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index bc3cf2d41f5..e52e43153e6 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -102,7 +102,7 @@ Addon module name is `addon`. Once the source code has been written, it must be compiled into the binary `addon.node` file. To do so, create a file called `binding.gyp` in the top-level of the project describing the build configuration of the module -using a JSON-like format. This file is used by [node-gyp][] -- a tool written +using a JSON-like format. This file is used by [node-gyp][] — a tool written specifically to compile Node.js Addons. ```json diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 77f843f0471..1f0ffe766e1 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -634,7 +634,7 @@ asyncResource.emitAfter(); * `type` {string} The type of async event. * `options` {Object} * `triggerAsyncId` {number} The ID of the execution context that created this - async event. **Default:** `executionAsyncId()`. + async event. **Default:** `executionAsyncId()`. * `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the object is garbage collected. This usually does not need to be set (even if `emitDestroy` is called manually), unless the resource's asyncId is retrieved diff --git a/doc/api/buffer.md b/doc/api/buffer.md index f3514f20b70..eb3b93e0f0c 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -59,7 +59,7 @@ differently based on what arguments are provided: entire `Buffer`. While this behavior is *intentional* to improve performance, development experience has demonstrated that a more explicit distinction is required between creating a fast-but-uninitialized `Buffer` versus creating a - slower-but-safer `Buffer`. Starting in Node.js 8.0.0, `Buffer(num)` and + slower-but-safer `Buffer`. Starting in Node.js 8.0.0, `Buffer(num)` and `new Buffer(num)` will return a `Buffer` with initialized memory. * Passing a string, array, or `Buffer` as the first argument copies the passed object's data into the `Buffer`. @@ -426,7 +426,7 @@ changes: * `size` {integer} The desired length of the new `Buffer`. -Allocates a new `Buffer` of `size` bytes. If the `size` is larger than +Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be thrown. A zero-length `Buffer` will be created if `size` is 0. @@ -510,7 +510,7 @@ console.log(buf); // Prints: ``` -Allocates a new `Buffer` of `size` bytes. If the `size` is larger than +Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be thrown. A zero-length `Buffer` will be created if `size` is 0. @@ -551,7 +551,7 @@ changes: * `size` {integer} The desired length of the new `Buffer`. -Allocates a new `Buffer` of `size` bytes. If the `size` is larger than +Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be thrown. A zero-length `Buffer` will be created if `size` is 0. @@ -595,7 +595,7 @@ added: v5.12.0 * `size` {integer} The desired length of the new `Buffer`. -Allocates a new `Buffer` of `size` bytes. If the `size` is larger than +Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be thrown. A zero-length `Buffer` will be created if `size` is 0. @@ -2498,7 +2498,7 @@ deprecated: v6.0.0 * `size` {integer} The desired length of the new `SlowBuffer`. -Allocates a new `Buffer` of `size` bytes. If the `size` is larger than +Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be thrown. A zero-length `Buffer` will be created if `size` is 0. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 929788486de..7921a88c3d9 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -41,7 +41,7 @@ the event loop until the spawned process either exits or is terminated. For convenience, the `child_process` module provides a handful of synchronous and asynchronous alternatives to [`child_process.spawn()`][] and -[`child_process.spawnSync()`][]. *Note that each of these alternatives are +[`child_process.spawnSync()`][]. *Note that each of these alternatives are implemented on top of [`child_process.spawn()`][] or [`child_process.spawnSync()`][].* * [`child_process.exec()`][]: spawns a shell and runs a command within that shell, @@ -148,7 +148,7 @@ changes: * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated. See caveat at - [`maxBuffer` and Unicode][]. **Default:** `200*1024`. + [`maxBuffer` and Unicode][]. **Default:** `200 * 1024`. * `killSignal` {string|integer} **Default:** `'SIGTERM'` * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). @@ -190,7 +190,7 @@ exec('cat *.js bad_file | wc -l', (error, stdout, stderr) => { ``` If a `callback` function is provided, it is called with the arguments -`(error, stdout, stderr)`. On success, `error` will be `null`. On error, +`(error, stdout, stderr)`. On success, `error` will be `null`. On error, `error` will be an instance of [`Error`][]. The `error.code` property will be the exit code of the child process while `error.signal` will be set to the signal that terminated the process. Any exit code other than `0` is considered @@ -246,7 +246,7 @@ changes: * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated. See caveat at - [`maxBuffer` and Unicode][]. **Default:** `200*1024`. + [`maxBuffer` and Unicode][]. **Default:** `200 * 1024`. * `killSignal` {string|integer} **Default:** `'SIGTERM'` * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). @@ -527,7 +527,7 @@ disabled*. On non-Windows platforms, if `options.detached` is set to `true`, the child process will be made the leader of a new process group and session. Note that child processes may continue running after the parent exits regardless of -whether they are detached or not. See setsid(2) for more information. +whether they are detached or not. See setsid(2) for more information. By default, the parent will wait for the detached child to exit. To prevent the parent from waiting for a given `subprocess`, use the `subprocess.unref()` @@ -701,7 +701,7 @@ changes: process will be killed. **Default:** `'SIGTERM'`. * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated. See caveat at - [`maxBuffer` and Unicode][]. **Default:** `200*1024`. + [`maxBuffer` and Unicode][]. **Default:** `200 * 1024`. * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'`. * `windowsHide` {boolean} Hide the subprocess console window that would @@ -762,7 +762,7 @@ changes: process will be killed. **Default:** `'SIGTERM'`. * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated. See caveat at - [`maxBuffer` and Unicode][]. **Default:** `200*1024`. + [`maxBuffer` and Unicode][]. **Default:** `200 * 1024`. * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'`. * `windowsHide` {boolean} Hide the subprocess console window that would @@ -773,12 +773,12 @@ The `child_process.execSync()` method is generally identical to [`child_process.exec()`][] with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and `killSignal` is sent, the method won't return until the process has completely -exited. *Note that if the child process intercepts and handles the `SIGTERM` +exited. *Note that if the child process intercepts and handles the `SIGTERM` signal and doesn't exit, the parent process will wait until the child process has exited.* If the process times out or has a non-zero exit code, this method ***will*** -throw. The [`Error`][] object will contain the entire result from +throw. The [`Error`][] object will contain the entire result from [`child_process.spawnSync()`][] **Never pass unsanitized user input to this function. Any input containing shell @@ -818,7 +818,7 @@ changes: process will be killed. **Default:** `'SIGTERM'`. * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated. See caveat at - [`maxBuffer` and Unicode][]. **Default:** `200*1024`. + [`maxBuffer` and Unicode][]. **Default:** `200 * 1024`. * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses @@ -1152,7 +1152,7 @@ registered on the [`process.on('message')`][] event. Any data that is received and buffered in the socket will not be sent to the child. The optional `callback` is a function that is invoked after the message is -sent but before the child may have received it. The function is called with a +sent but before the child may have received it. The function is called with a single argument: `null` on success, or an [`Error`][] object on failure. If no `callback` function is provided and the message cannot be sent, an diff --git a/doc/api/cli.md b/doc/api/cli.md index 840a6cad3b6..1a200b26fee 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -517,7 +517,7 @@ added: v3.0.0 Path to the file used to store the persistent REPL history. The default path is `~/.node_repl_history`, which is overridden by this variable. Setting the value -to an empty string (`""` or `" "`) disables persistent REPL history. +to an empty string (`''` or `' '`) disables persistent REPL history. ### `NODE_EXTRA_CA_CERTS=file` @@ -602,7 +602,7 @@ reason any of these APIs takes a long time, other (seemingly unrelated) APIs that run in libuv's threadpool will experience degraded performance. In order to mitigate this issue, one potential solution is to increase the size of libuv's threadpool by setting the `'UV_THREADPOOL_SIZE'` environment variable to a value -greater than `4` (its current default value). For more information, see the +greater than `4` (its current default value). For more information, see the [libuv threadpool documentation][]. [`--openssl-config`]: #cli_openssl_config_file diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 66a4be91373..7385e9ba78b 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -93,7 +93,7 @@ Node.js process and a cluster worker differs: process. 3. `server.listen(0)` Normally, this will cause servers to listen on a random port. However, in a cluster, each worker will receive the - same "random" port each time they do `listen(0)`. In essence, the + same "random" port each time they do `listen(0)`. In essence, the port is random the first time, but predictable thereafter. To listen on a unique port, generate a port number based on the cluster worker ID. @@ -103,8 +103,8 @@ things like sessions and login. Because workers are all separate processes, they can be killed or re-spawned depending on a program's needs, without affecting other -workers. As long as there are some workers still alive, the server will -continue to accept connections. If no workers are alive, existing connections +workers. As long as there are some workers still alive, the server will +continue to accept connections. If no workers are alive, existing connections will be dropped and new connections will be refused. Node.js does not automatically manage the number of workers, however. It is the application's responsibility to manage the worker pool based on its own needs. @@ -465,7 +465,7 @@ 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 +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. @@ -556,7 +556,7 @@ The `addressType` is one of: * `4` (TCPv4) * `6` (TCPv6) * `-1` (unix domain socket) -* `"udp4"` or `"udp6"` (UDP v4 or v6) +* `'udp4'` or `'udp6'` (UDP v4 or v6) ## Event: 'message' -* Returns {number} the `SO_RCVBUF` socket receive buffer size in bytes. +* Returns: {number} the `SO_RCVBUF` socket receive buffer size in bytes. ### socket.getSendBufferSize() -* Returns {number} the `SO_SNDBUF` socket send buffer size in bytes. +* Returns: {number} the `SO_SNDBUF` socket send buffer size in bytes. ### socket.ref() Sometimes, the domain in use is not the one that ought to be used for a -specific event emitter. Or, the event emitter could have been created +specific event emitter. Or, the event emitter could have been created in the context of one domain, but ought to instead be bound to some other domain. @@ -278,7 +278,7 @@ Returns a new Domain object. The Domain class encapsulates the functionality of routing errors and uncaught exceptions to the active Domain object. -Domain is a child class of [`EventEmitter`][]. To handle the errors that it +Domain is a child class of [`EventEmitter`][]. To handle the errors that it catches, listen to its `'error'` event. ### domain.members @@ -292,13 +292,13 @@ to the domain. * `emitter` {EventEmitter|Timer} emitter or timer to be added to the domain -Explicitly adds an emitter to the domain. If any event handlers called by +Explicitly adds an emitter to the domain. If any event handlers called by the emitter throw an error, or if the emitter emits an `'error'` event, it will be routed to the domain's `'error'` event, just like with implicit binding. This also works with timers that are returned from [`setInterval()`][] and -[`setTimeout()`][]. If their callback function throws, it will be caught by +[`setTimeout()`][]. If their callback function throws, it will be caught by the domain 'error' handler. If the Timer or EventEmitter was already bound to a domain, it is removed @@ -310,7 +310,7 @@ from that one, and bound to this one instead. * Returns: {Function} The bound function The returned function will be a wrapper around the supplied callback -function. When the returned function is called, any errors that are +function. When the returned function is called, any errors that are thrown will be routed to the domain's `'error'` event. #### Example @@ -365,7 +365,7 @@ single domain. * `callback` {Function} The callback function * Returns: {Function} The intercepted function -This method is almost identical to [`domain.bind(callback)`][]. However, in +This method is almost identical to [`domain.bind(callback)`][]. However, in addition to catching thrown errors, it will also intercept [`Error`][] objects sent as the first argument to the function. @@ -402,7 +402,7 @@ d.on('error', (er) => { * `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain -The opposite of [`domain.add(emitter)`][]. Removes domain handling from the +The opposite of [`domain.add(emitter)`][]. Removes domain handling from the specified emitter. ### domain.run(fn[, ...args]) diff --git a/doc/api/errors.md b/doc/api/errors.md index 62a62d76656..2c854085915 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -107,7 +107,7 @@ pass or fail). For *all* [`EventEmitter`][] objects, if an `'error'` event handler is not provided, the error will be thrown, causing the Node.js process to report an -unhandled exception and crash unless either: The [`domain`][domains] module is +unhandled exception and crash unless either: The [`domain`][domains] module is used appropriately or a handler has been registered for the [`process.on('uncaughtException')`][] event. @@ -133,7 +133,7 @@ exactly how errors raised by those methods are propagated. Most asynchronous methods exposed by the Node.js core API follow an idiomatic -pattern referred to as an _error-first callback_ (sometimes referred to as +pattern referred to as an _error-first callback_ (sometimes referred to as a _Node.js style callback_). With this pattern, a callback function is passed to the method as an argument. When the operation either completes or an error is raised, the callback function is called with @@ -156,7 +156,7 @@ fs.readFile('/some/file/that/does-exist', errorFirstCallback); ``` The JavaScript `try / catch` mechanism **cannot** be used to intercept errors -generated by asynchronous APIs. A common mistake for beginners is to try to +generated by asynchronous APIs. A common mistake for beginners is to try to use `throw` inside an error-first callback: ```js @@ -209,7 +209,7 @@ provided text message. If an object is passed as `message`, the text message is generated by calling `message.toString()`. The `error.stack` property will represent the point in the code at which `new Error()` was called. Stack traces are dependent on [V8's stack trace API][]. Stack traces extend only to either -(a) the beginning of *synchronous code execution*, or (b) the number of frames +(a) the beginning of *synchronous code execution*, or (b) the number of frames given by the property `Error.stackTraceLimit`, whichever is smaller. ### Error.captureStackTrace(targetObject[, constructorOpt]) @@ -538,7 +538,7 @@ found [here][online]. - `EACCES` (Permission denied): An attempt was made to access a file in a way forbidden by its file access permissions. -- `EADDRINUSE` (Address already in use): An attempt to bind a server +- `EADDRINUSE` (Address already in use): An attempt to bind a server ([`net`][], [`http`][], or [`https`][]) to a local address failed due to another server on the local system already occupying that address. @@ -566,14 +566,14 @@ found [here][online]. `ulimit -n 2048` in the same shell that will run the Node.js process. - `ENOENT` (No such file or directory): Commonly raised by [`fs`][] operations - to indicate that a component of the specified pathname does not exist -- no + to indicate that a component of the specified pathname does not exist — no entity (file or directory) could be found by the given path. - `ENOTDIR` (Not a directory): A component of the given pathname existed, but was not a directory as expected. Commonly raised by [`fs.readdir`][]. - `ENOTEMPTY` (Directory not empty): A directory with entries was the target - of an operation that requires an empty directory -- usually [`fs.unlink`][]. + of an operation that requires an empty directory — usually [`fs.unlink`][]. - `EPERM` (Operation not permitted): An attempt was made to perform an operation that requires elevated privileges. @@ -585,7 +585,7 @@ found [here][online]. - `ETIMEDOUT` (Operation timed out): A connect or send request failed because the connected party did not properly respond after a period of time. Usually - encountered by [`http`][] or [`net`][] -- often a sign that a `socket.end()` + encountered by [`http`][] or [`net`][] — often a sign that a `socket.end()` was not properly called. diff --git a/doc/api/esm.md b/doc/api/esm.md index 0db3db1d290..ea2cc65f952 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -142,12 +142,12 @@ module. This can be one of the following: | `format` | Description | | --- | --- | -| `"esm"` | Load a standard JavaScript module | -| `"cjs"` | Load a node-style CommonJS module | -| `"builtin"` | Load a node builtin CommonJS module | -| `"json"` | Load a JSON file | -| `"addon"` | Load a [C++ Addon][addons] | -| `"dynamic"` | Use a [dynamic instantiate hook][] | +| `'esm'` | Load a standard JavaScript module | +| `'cjs'` | Load a node-style CommonJS module | +| `'builtin'` | Load a node builtin CommonJS module | +| `'json'` | Load a JSON file | +| `'addon'` | Load a [C++ Addon][addons] | +| `'dynamic'` | Use a [dynamic instantiate hook][] | For example, a dummy loader to load JavaScript restricted to browser resolution rules with only JS file extension and Node.js builtin modules support could @@ -203,7 +203,7 @@ would load the module `x.js` as an ES module with relative resolution support To create a custom dynamic module that doesn't correspond to one of the existing `format` interpretations, the `dynamicInstantiate` hook can be used. -This hook is called only for modules that return `format: "dynamic"` from +This hook is called only for modules that return `format: 'dynamic'` from the `resolve` hook. ```js diff --git a/doc/api/fs.md b/doc/api/fs.md index 61b87581a43..d705a78f990 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -75,7 +75,7 @@ fs.rename('/tmp/hello', '/tmp/world', (err) => { In busy processes, the programmer is _strongly encouraged_ to use the asynchronous versions of these calls. The synchronous versions will block -the entire process until they complete--halting all connections. +the entire process until they complete — halting all connections. While it is not recommended, most fs functions allow the callback argument to be omitted, in which case a default callback is used that rethrows errors. To @@ -634,16 +634,16 @@ representation. The times in the stat object have the following semantics: -* `atime` "Access Time" - Time when file data last accessed. Changed +* `atime` "Access Time" - Time when file data last accessed. Changed by the mknod(2), utimes(2), and read(2) system calls. * `mtime` "Modified Time" - Time when file data last modified. Changed by the mknod(2), utimes(2), and write(2) system calls. * `ctime` "Change Time" - Time when file status was last changed - (inode data modification). Changed by the chmod(2), chown(2), + (inode data modification). Changed by the chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), and write(2) system calls. -* `birthtime` "Birth Time" - Time of file creation. Set once when the - file is created. On filesystems where birthtime is not available, +* `birthtime` "Birth Time" - Time of file creation. Set once when the + file is created. On filesystems where birthtime is not available, this field may instead hold either the `ctime` or `1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). Note that this value may be greater than `atime` or `mtime` in this case. On Darwin @@ -652,7 +652,7 @@ The times in the stat object have the following semantics: utimes(2) system call. Prior to Node.js v0.12, the `ctime` held the `birthtime` on Windows -systems. Note that as of v0.12, `ctime` is not "creation time", and +systems. Note that as of v0.12, `ctime` is not "creation time", and on Unix systems, it never was. ## Class: fs.WriteStream @@ -1140,7 +1140,7 @@ changes: * `callback` {Function} * `err` {Error} -Asynchronous close(2). No arguments other than a possible exception are given +Asynchronous close(2). No arguments other than a possible exception are given to the completion callback. ## fs.closeSync(fd) @@ -1288,7 +1288,7 @@ const defaults = { ``` `options` can include `start` and `end` values to read a range of bytes from -the file instead of the entire file. Both `start` and `end` are inclusive and +the file instead of the entire file. Both `start` and `end` are inclusive and start counting at 0. If `fd` is specified and `start` is omitted or `undefined`, `fs.createReadStream()` reads sequentially from the current file position. The `encoding` can be any one of those accepted by [`Buffer`][]. @@ -1359,7 +1359,7 @@ const defaults = { ``` `options` may also include a `start` option to allow writing data at -some position past the beginning of the file. Modifying a file rather +some position past the beginning of the file. Modifying a file rather than replacing it may require a `flags` mode of `r+` rather than the default mode `w`. The `encoding` can be any one of those accepted by [`Buffer`][]. @@ -1395,7 +1395,7 @@ deprecated: v1.0.0 * `exists` {boolean} Test whether or not the given path exists by checking with the file system. -Then call the `callback` argument with either true or false. Example: +Then call the `callback` argument with either true or false. Example: ```js fs.exists('/etc/passwd', (exists) => { @@ -2153,7 +2153,7 @@ to a non-existent file. The exclusive flag may or may not work with network file systems. `flags` can also be a number as documented by open(2); commonly used constants -are available from `fs.constants`. On Windows, flags are translated to +are available from `fs.constants`. On Windows, flags are translated to their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`, or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW. @@ -2277,7 +2277,7 @@ changes: * `err` {Error} * `files` {string[]|Buffer[]} -Asynchronous readdir(3). Reads the contents of a directory. +Asynchronous readdir(3). Reads the contents of a directory. The callback gets two arguments `(err, files)` where `files` is an array of the names of the files in the directory excluding `'.'` and `'..'`. @@ -2581,7 +2581,7 @@ the path passed to the callback. If the `encoding` is set to `'buffer'`, the path returned will be passed as a `Buffer` object. On Linux, when Node.js is linked against musl libc, the procfs file system must -be mounted on `/proc` in order for this function to work. Glibc does not have +be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. ## fs.realpathSync(path[, options]) @@ -2650,7 +2650,7 @@ the path passed to the callback. If the `encoding` is set to `'buffer'`, the path returned will be passed as a `Buffer` object. On Linux, when Node.js is linked against musl libc, the procfs file system must -be mounted on `/proc` in order for this function to work. Glibc does not have +be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. ## fs.rename(oldPath, newPath, callback) @@ -2961,7 +2961,7 @@ Calling `fs.unwatchFile()` with a filename that is not being watched is a no-op, not an error. Using [`fs.watch()`][] is more efficient than `fs.watchFile()` and -`fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()` +`fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()` when possible. ## fs.utimes(path, atime, mtime, callback) @@ -3056,12 +3056,12 @@ changes: * `filename` {string|Buffer} Watch for changes on `filename`, where `filename` is either a file or a -directory. The returned object is a [`fs.FSWatcher`][]. +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` +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. @@ -3123,7 +3123,7 @@ content, and one for truncation). Providing `filename` argument in the callback is only supported on Linux, -macOS, Windows, and AIX. Even on supported platforms, `filename` is not always +macOS, Windows, and AIX. Even on supported platforms, `filename` is not always guaranteed to be provided. Therefore, don't assume that `filename` argument is always provided in the callback, and have some fallback logic if it is null. @@ -3279,7 +3279,7 @@ changes: * `written` {integer} * `string` {string} -Write `string` to the file specified by `fd`. If `string` is not a string, then +Write `string` to the file specified by `fd`. If `string` is not a string, then the value will be coerced to one. `position` refers to the offset from the beginning of the file where this data @@ -3442,7 +3442,7 @@ Instances of the `FileHandle` object are created internally by the `fsPromises.open()` method. Unlike callback-based such as `fs.fstat()`, `fs.fchown()`, `fs.fchmod()`, -`fs.ftruncate()`, `fs.read()`, and `fs.write()`, operations -- all of which +`fs.ftruncate()`, `fs.read()`, and `fs.write()`, operations — all of which use a simple numeric file descriptor, all `fsPromises.*` variations use the `FileHandle` class in order to help protect against accidental leaking of unclosed file descriptors after a `Promise` is resolved or rejected. @@ -4060,7 +4060,7 @@ added: REPLACEME * `path` {string|Buffer|URL} * `flags` {string|number} * `mode` {integer} **Default:** `0o666` (readable and writable) -* Return: {Promise} +* Returns: {Promise} Asynchronous file open that returns a `Promise` that, when resolved, yields a `FileHandle` object. See open(2). @@ -4118,7 +4118,7 @@ to a non-existent file. The exclusive flag may or may not work with network file systems. `flags` can also be a number as documented by open(2); commonly used constants -are available from `fs.constants`. On Windows, flags are translated to +are available from `fs.constants`. On Windows, flags are translated to their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`, or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW. @@ -4254,7 +4254,7 @@ the path. If the `encoding` is set to `'buffer'`, the path returned will be passed as a `Buffer` object. On Linux, when Node.js is linked against musl libc, the procfs file system must -be mounted on `/proc` in order for this function to work. Glibc does not have +be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. ### fsPromises.rename(oldPath, newPath) diff --git a/doc/api/http.md b/doc/api/http.md index 07b77d77399..4218bbf7e6e 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -9,7 +9,7 @@ To use the HTTP server and client one must `require('http')`. The HTTP interfaces in Node.js are designed to support many features of the protocol which have been traditionally difficult to use. In particular, large, possibly chunk-encoded, messages. The interface is -careful to never buffer entire requests or responses--the +careful to never buffer entire requests or responses — the user is able to stream data. HTTP message headers are represented by an object like this: @@ -33,7 +33,7 @@ parse the actual headers or the body. See [`message.headers`][] for details on how duplicate headers are handled. The raw headers as they were received are retained in the `rawHeaders` -property, which is an array of `[key, value, key2, value2, ...]`. For +property, which is an array of `[key, value, key2, value2, ...]`. For example, the previous message header object might have a `rawHeaders` list like the following: @@ -124,7 +124,7 @@ added: v0.3.4 * `maxSockets` {number} Maximum number of sockets to allow per host. **Default:** `Infinity`. * `maxFreeSockets` {number} Maximum number of sockets to leave open - in a free state. Only relevant if `keepAlive` is set to `true`. + in a free state. Only relevant if `keepAlive` is set to `true`. **Default:** `256`. The default [`http.globalAgent`][] that is used by [`http.request()`][] has all @@ -203,9 +203,9 @@ added: v0.11.4 Destroy any sockets that are currently in use by the agent. -It is usually not necessary to do this. However, if using an +It is usually not necessary to do this. However, if using an agent with `keepAlive` enabled, then it is best to explicitly shut down -the agent when it will no longer be used. Otherwise, +the agent when it will no longer be used. Otherwise, sockets may hang open for quite a long time before the server terminates them. @@ -217,7 +217,7 @@ added: v0.11.4 * {Object} An object which contains arrays of sockets currently awaiting use by -the agent when `keepAlive` is enabled. Do not modify. +the agent when `keepAlive` is enabled. Do not modify. ### agent.getName(options) -This object is created internally and returned from [`http.request()`][]. It -represents an _in-progress_ request whose header has already been queued. The +This object is created internally and returned from [`http.request()`][]. It +represents an _in-progress_ request whose header has already been queued. The header is still mutable using the [`setHeader(name, value)`][], - [`getHeader(name)`][], [`removeHeader(name)`][] API. The actual header will + [`getHeader(name)`][], [`removeHeader(name)`][] API. The actual header will be sent along with the first data chunk or when calling [`request.end()`][]. To get the response, add a listener for [`'response'`][] to the request object. [`'response'`][] will be emitted from the request object when the response -headers have been received. The [`'response'`][] event is executed with one +headers have been received. The [`'response'`][] event is executed with one argument which is an instance of [`http.IncomingMessage`][]. During the [`'response'`][] event, one can add listeners to the response object; particularly to listen for the `'data'` event. If no [`'response'`][] handler is added, then the response will be -entirely discarded. However, if a [`'response'`][] event handler is added, +entirely discarded. However, if a [`'response'`][] event handler is added, then the data from the response object **must** be consumed, either by calling `response.read()` whenever there is a `'readable'` event, or by adding a `'data'` handler, or by calling the `.resume()` method. -Until the data is consumed, the `'end'` event will not fire. Also, until +Until the data is consumed, the `'end'` event will not fire. Also, until the data is read it will consume memory that can eventually lead to a 'process out of memory' error. @@ -578,7 +578,7 @@ For efficiency reasons, Node.js normally buffers the request headers until then tries to pack the request headers and data into a single TCP packet. That's usually desired (it saves a TCP round-trip), but not when the first -data is not sent until possibly much later. `request.flushHeaders()` bypasses +data is not sent until possibly much later. `request.flushHeaders()` bypasses the optimization and kickstarts the request. ### request.getHeader(name) @@ -707,9 +707,9 @@ added: v0.1.29 * `encoding` {string} * `callback` {Function} -Sends a chunk of the body. By calling this method +Sends a chunk of the body. By calling this method many times, a request body can be sent to a -server--in that case it is suggested to use the +server — in that case it is suggested to use the `['Transfer-Encoding', 'chunked']` header line when creating the request. @@ -895,7 +895,7 @@ added: v0.1.90 * `callback` {Function} -Stops the server from accepting new connections. See [`net.Server.close()`][]. +Stops the server from accepting new connections. See [`net.Server.close()`][]. ### server.listen() @@ -937,7 +937,7 @@ If there is a `'timeout'` event listener on the Server object, then it will be called with the timed-out socket as an argument. By default, the Server's timeout value is 2 minutes, and sockets are -destroyed automatically if they time out. However, if a callback is assigned +destroyed automatically if they time out. However, if a callback is assigned to the Server's `'timeout'` event, timeouts must be handled explicitly. Returns `server`. @@ -983,7 +983,7 @@ affects new connections to the server, not any existing connections. added: v0.1.17 --> -This object is created internally by an HTTP server--not by the user. It is +This object is created internally by an HTTP server — not by the user. It is passed as the second parameter to the [`'request'`][] event. The response implements, but does not inherit from, the [Writable Stream][] @@ -1208,8 +1208,8 @@ added: v0.4.0 * `name` {string} * `value` {string | string[]} -Sets a single header value for implicit headers. If this header already exists -in the to-be-sent headers, its value will be replaced. Use an array of strings +Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Example: @@ -1249,12 +1249,12 @@ added: v0.9.12 * `msecs` {number} * `callback` {Function} -Sets the Socket's timeout value to `msecs`. If a callback is +Sets the Socket's timeout value to `msecs`. If a callback is provided, then it is added as a listener on the `'timeout'` event on the response object. If no `'timeout'` listener is added to the request, the response, or -the server, then sockets are destroyed when they time out. If a handler is +the server, then sockets are destroyed when they time out. If a handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. @@ -1542,8 +1542,8 @@ added: v0.11.6 The raw request/response headers list exactly as they were received. -Note that the keys and values are in the same list. It is *not* a -list of tuples. So, the even-numbered offsets are key values, and the +Note that the keys and values are in the same list. It is *not* a +list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. Header names are not lowercased, and duplicates are not merged. @@ -1570,7 +1570,7 @@ added: v0.11.6 * {Array} The raw request/response trailer keys and values exactly as they were -received. Only populated at the `'end'` event. +received. Only populated at the `'end'` event. ### message.setTimeout(msecs, callback) -This object is created internally by an HTTP server--not by the user. It is +This object is created internally by an HTTP server — not by the user. It is passed as the second parameter to the [`'request'`][] event. The response implements, but does not inherit from, the [Writable Stream][] @@ -2791,8 +2791,8 @@ added: v8.4.0 * `name` {string} * `value` {string|string[]} -Sets a single header value for implicit headers. If this header already exists -in the to-be-sent headers, its value will be replaced. Use an array of strings +Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Example: @@ -2832,7 +2832,7 @@ added: v8.4.0 * `msecs` {number} * `callback` {Function} -Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is +Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is provided, then it is added as a listener on the `'timeout'` event on the response object. @@ -2991,7 +2991,7 @@ response.writeHead(200, { ``` Note that Content-Length is given in bytes not characters. The -`Buffer.byteLength()` API may be used to determine the number of bytes in a +`Buffer.byteLength()` API may be used to determine the number of bytes in a given encoding. On outbound messages, Node.js does not check if Content-Length and the length of the body being transmitted are equal or not. However, when receiving messages, Node.js will automatically reject messages when the diff --git a/doc/api/https.md b/doc/api/https.md index 131553c2119..bcaf46a09b3 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -12,7 +12,7 @@ separate module. added: v0.4.5 --> -An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See +An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] for more information. ## Class: https.Server diff --git a/doc/api/modules.md b/doc/api/modules.md index aa03b414c35..277dff8f6b6 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -123,12 +123,12 @@ the version that is symlinked into Furthermore, to make the module lookup process even more optimal, rather than putting packages directly in `/usr/lib/node`, we could put them in -`/usr/lib/node_modules//`. Then Node.js will not bother +`/usr/lib/node_modules//`. Then Node.js will not bother looking for missing dependencies in `/usr/node_modules` or `/node_modules`. In order to make modules available to the Node.js REPL, it might be useful to also add the `/usr/lib/node_modules` folder to the `$NODE_PATH` environment -variable. Since the module lookups using `node_modules` folders are all +variable. Since the module lookups using `node_modules` folders are all relative, and based on the real path of the files making the calls to `require()`, the packages themselves can be anywhere. @@ -196,12 +196,12 @@ NODE_MODULES_PATHS(START) -Modules are cached after the first time they are loaded. This means +Modules are cached after the first time they are loaded. This means (among other things) that every call to `require('foo')` will get exactly the same object returned, if it would resolve to the same file. Multiple calls to `require('foo')` may not cause the module code to be -executed multiple times. This is an important feature. With it, +executed multiple times. This is an important feature. With it, "partially done" objects can be returned, thus allowing transitive dependencies to be loaded even when they would cause cycles. @@ -212,7 +212,7 @@ that function. -Modules are cached based on their resolved filename. Since modules may +Modules are cached based on their resolved filename. Since modules may resolve to a different filename based on the location of the calling module (loading from `node_modules` folders), it is not a *guarantee* that `require('foo')` will always return the exact same object, if it @@ -228,14 +228,14 @@ irrespective of whether or not `./foo` and `./FOO` are the same file. -Node.js has several modules compiled into the binary. These modules are +Node.js has several modules compiled into the binary. These modules are described in greater detail elsewhere in this documentation. The core modules are defined within Node.js's source and are located in the `lib/` folder. Core modules are always preferentially loaded if their identifier is -passed to `require()`. For instance, `require('http')` will always +passed to `require()`. For instance, `require('http')` will always return the built in HTTP module, even if there is a file by that name. ## Cycles @@ -275,13 +275,13 @@ console.log('b done'); console.log('main starting'); const a = require('./a.js'); const b = require('./b.js'); -console.log('in main, a.done=%j, b.done=%j', a.done, b.done); +console.log('in main, a.done = %j, b.done = %j', a.done, b.done); ``` -When `main.js` loads `a.js`, then `a.js` in turn loads `b.js`. At that -point, `b.js` tries to load `a.js`. In order to prevent an infinite +When `main.js` loads `a.js`, then `a.js` in turn loads `b.js`. At that +point, `b.js` tries to load `a.js`. In order to prevent an infinite loop, an **unfinished copy** of the `a.js` exports object is returned to the -`b.js` module. `b.js` then finishes loading, and its `exports` object is +`b.js` module. `b.js` then finishes loading, and its `exports` object is provided to the `a.js` module. By the time `main.js` has loaded both modules, they're both finished. @@ -296,7 +296,7 @@ in b, a.done = false b done in a, b.done = true a done -in main, a.done=true, b.done=true +in main, a.done = true, b.done = true ``` Careful planning is required to allow cyclic module dependencies to work @@ -314,7 +314,7 @@ required filename with the added extensions: `.js`, `.json`, and finally parsed as JSON text files. `.node` files are interpreted as compiled addon modules loaded with `dlopen`. -A required module prefixed with `'/'` is an absolute path to the file. For +A required module prefixed with `'/'` is an absolute path to the file. For example, `require('/home/marco/foo.js')` will load the file at `/home/marco/foo.js`. @@ -338,7 +338,7 @@ There are three ways in which a folder may be passed to `require()` as an argument. The first is to create a `package.json` file in the root of the folder, -which specifies a `main` module. An example package.json file might +which specifies a `main` module. An example package.json file might look like this: ```json @@ -352,7 +352,7 @@ If this was in a folder at `./some-library`, then This is the extent of Node.js's awareness of package.json files. -If the file specified by the `"main"` entry of `package.json` is missing and +If the file specified by the `'main'` entry of `package.json` is missing and can not be resolved, Node.js will report the entire module as missing with the default error: @@ -362,7 +362,7 @@ Error: Cannot find module 'some-library' If there is no package.json file present in the directory, then Node.js will attempt to load an `index.js` or `index.node` file out of that -directory. For example, if there was no package.json file in the above +directory. For example, if there was no package.json file in the above example, then `require('./some-library')` would attempt to load: * `./some-library/index.js` @@ -415,7 +415,7 @@ varying paths before the current [module resolution][] algorithm was frozen. `NODE_PATH` is still supported, but is less necessary now that the Node.js ecosystem has settled on a convention for locating dependent modules. Sometimes deployments that rely on `NODE_PATH` show surprising behavior -when people are unaware that `NODE_PATH` must be set. Sometimes a +when people are unaware that `NODE_PATH` must be set. Sometimes a module's dependencies change, causing a different version (or even a different module) to be loaded as the `NODE_PATH` is searched. @@ -583,14 +583,14 @@ Process files with the extension `.sjs` as `.js`: require.extensions['.sjs'] = require.extensions['.js']; ``` -**Deprecated** In the past, this list has been used to load +**Deprecated** In the past, this list has been used to load non-JavaScript modules into Node.js by compiling them on-demand. However, in practice, there are much better ways to do this, such as loading modules via some other Node.js program, or compiling them to JavaScript ahead of time. Since the module system is locked, this feature will probably never go -away. However, it may have subtle bugs and complexities that are best +away. However, it may have subtle bugs and complexities that are best left untouched. Note that the number of file system operations that the module system @@ -680,7 +680,7 @@ added: v0.1.16 * {Object} In each module, the `module` free variable is a reference to the object -representing the current module. For convenience, `module.exports` is +representing the current module. For convenience, `module.exports` is also accessible via the `exports` module-global. `module` is not actually a global but rather local to each module. @@ -731,7 +731,7 @@ a.on('ready', () => { Note that assignment to `module.exports` must be done immediately. It cannot be -done in any callbacks. This does not work: +done in any callbacks. This does not work: x.js: @@ -811,7 +811,7 @@ added: v0.1.16 * {string} -The identifier for the module. Typically this is the fully resolved +The identifier for the module. Typically this is the fully resolved filename. ### module.loaded @@ -867,7 +867,7 @@ added: v0.3.7 * {Object} Provides general utility methods when interacting with instances of -`Module` -- the `module` variable often seen in file modules. Accessed +`Module` — the `module` variable often seen in file modules. Accessed via `require('module')`. ### module.builtinModules diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 59db76d888b..673766df169 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -14,7 +14,7 @@ compiled for one version to run on later versions of Node.js without recompilation. Addons are built/packaged with the same approach/tools -outlined in the section titled [C++ Addons](addons.html). +outlined in the section titled [C++ Addons](addons.html). The only difference is the set of APIs that are used by the native code. Instead of using the V8 or [Native Abstractions for Node.js][] APIs, the functions available in the N-API are used. @@ -310,7 +310,7 @@ where the native code can catch the exception, take the appropriate action, and then continue. This is only recommended in specific cases where it is known that the exception can be safely handled. In these cases [`napi_get_and_clear_last_exception`][] can be used to get and -clear the exception. On success, result will contain the handle to +clear the exception. On success, result will contain the handle to the last JavaScript Object thrown. If it is determined, after retrieving the exception, the exception cannot be handled after all it can be re-thrown it with [`napi_throw`][] where error is the @@ -318,7 +318,7 @@ JavaScript Error object to be thrown. The following utility functions are also available in case native code needs to throw an exception or determine if a `napi_value` is an instance -of a JavaScript `Error` object: [`napi_throw_error`][], +of a JavaScript `Error` object: [`napi_throw_error`][], [`napi_throw_type_error`][], [`napi_throw_range_error`][] and [`napi_is_error`][]. @@ -329,7 +329,7 @@ where result is the napi_value that refers to the newly created JavaScript Error object. The Node.js project is adding error codes to all of the errors -generated internally. The goal is for applications to use these +generated internally. The goal is for applications to use these error codes for all error checking. The associated error messages will remain, but will only be meant to be used for logging and display with the expectation that the message can change without @@ -337,7 +337,7 @@ SemVer applying. In order to support this model with N-API, both in internal functionality and for module specific functionality (as its good practice), the `throw_` and `create_` functions take an optional code parameter which is the string for the code -to be added to the error object. If the optional parameter is NULL +to be added to the error object. If the optional parameter is NULL then no code will be associated with the error. If a code is provided, the name associated with the error is also updated to be: @@ -346,7 +346,7 @@ originalName [code] ``` where originalName is the original name associated with the error -and code is the code that was provided. For example if the code +and code is the code that was provided. For example if the code is 'ERR_ERROR_1' and a TypeError is being created the name will be: ```text @@ -2409,7 +2409,7 @@ They can be one or more of the following bitflags: - `napi_default` - Used to indicate that no explicit attributes are set on the given property. By default, a property is read only, not enumerable and not configurable. -- `napi_writable` - Used to indicate that a given property is writable. +- `napi_writable` - Used to indicate that a given property is writable. - `napi_enumerable` - Used to indicate that a given property is enumerable. - `napi_configurable` - Used to indicate that a given property is configurable, as defined in [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. @@ -2439,7 +2439,7 @@ typedef struct { encoded as UTF8. One of `utf8name` or `name` must be provided for the property. - `name`: Optional napi_value that points to a JavaScript string or symbol -to be used as the key for the property. One of `utf8name` or `name` must +to be used as the key for the property. One of `utf8name` or `name` must be provided for the property. - `value`: The value that's retrieved by a get access of the property if the property is a data property. If this is passed in, set `getter`, `setter`, @@ -2891,7 +2891,7 @@ napi_value Init(napi_env env, napi_value exports) { napi_status status; napi_value fn; - status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn); + status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn); if (status != napi_ok) return NULL; status = napi_set_named_property(env, exports, "sayHello", fn); @@ -3259,7 +3259,7 @@ napi_status napi_queue_async_work(napi_env env, napi_async_work work); ``` -[`napi_cancel_async_work`][] can be used if the work needs +[`napi_cancel_async_work`][] can be used if the work needs to be cancelled before the work has started execution. After calling [`napi_cancel_async_work`][], the `complete` callback @@ -3364,7 +3364,7 @@ napi_status napi_cancel_async_work(napi_env env, Returns `napi_ok` if the API succeeded. This API cancels queued work if it has not yet -been started. If it has already started executing, it cannot be +been started. If it has already started executing, it cannot be cancelled and `napi_generic_failure` will be returned. If successful, the `complete` callback will be invoked with a status value of `napi_cancelled`. The work should not be deleted before the `complete` @@ -3481,7 +3481,7 @@ from [`napi_async_init`][]. There are cases (for example resolving promises) where it is necessary to have the equivalent of the scope associated with a callback -in place when making certain N-API calls. If there is no other script on +in place when making certain N-API calls. If there is no other script on the stack the [`napi_open_callback_scope`][] and [`napi_close_callback_scope`][] functions can be used to open/close the required scope. @@ -3544,7 +3544,7 @@ napi_status napi_get_version(napi_env env, Returns `napi_ok` if the API succeeded. This API returns the highest N-API version supported by the -Node.js runtime. N-API is planned to be additive such that +Node.js runtime. N-API is planned to be additive such that newer releases of Node.js may support additional API functions. In order to allow an addon to use a newer function when running with versions of Node.js that support it, while providing diff --git a/doc/api/net.md b/doc/api/net.md index 1df54122290..4e76878d6e8 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -186,8 +186,8 @@ Possible signatures: * [`server.listen([port][, host][, backlog][, callback])`][`server.listen(port, host)`] for TCP servers -This function is asynchronous. When the server starts listening, the -[`'listening'`][] event will be emitted. The last parameter `callback` +This function is asynchronous. When the server starts listening, the +[`'listening'`][] event will be emitted. The last parameter `callback` will be added as a listener for the [`'listening'`][] event. All `listen()` methods can take a `backlog` parameter to specify the maximum @@ -418,8 +418,8 @@ added: v0.1.90 * {Buffer} -Emitted when data is received. The argument `data` will be a `Buffer` or -`String`. Encoding of data is set by [`socket.setEncoding()`][]. +Emitted when data is received. The argument `data` will be a `Buffer` or +`String`. Encoding of data is set by [`socket.setEncoding()`][]. Note that the **data will be lost** if there is no listener when a `Socket` emits a `'data'` event. @@ -456,7 +456,7 @@ added: v0.1.90 * {Error} -Emitted when an error occurs. The `'close'` event will be called directly +Emitted when an error occurs. The `'close'` event will be called directly following this event. ### Event: 'lookup' @@ -471,9 +471,9 @@ changes: Emitted after resolving the hostname but before connecting. Not applicable to UNIX sockets. -* `err` {Error|null} The error object. See [`dns.lookup()`][]. +* `err` {Error|null} The error object. See [`dns.lookup()`][]. * `address` {string} The IP address. -* `family` {string|null} The address type. See [`dns.lookup()`][]. +* `family` {string|null} The address type. See [`dns.lookup()`][]. * `host` {string} The hostname. ### Event: 'timeout' @@ -821,7 +821,7 @@ added: v0.1.90 --> Sends data on the socket. The second parameter specifies the encoding in the -case of a string--it defaults to UTF8 encoding. +case of a string — it defaults to UTF8 encoding. Returns `true` if the entire data was flushed successfully to the kernel buffer. Returns `false` if all or part of the data was queued in user memory. diff --git a/doc/api/os.md b/doc/api/os.md index 31b167f6d1b..9210abcb51c 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -223,7 +223,7 @@ The `os.loadavg()` method returns an array containing the 1, 5, and 15 minute load averages. The load average is a measure of system activity, calculated by the operating -system and expressed as a fractional number. As a rule of thumb, the load +system and expressed as a fractional number. As a rule of thumb, the load average should ideally be less than the number of logical CPUs in the system. The load average is a UNIX-specific concept with no real equivalent on @@ -402,7 +402,7 @@ added: v6.0.0 * Returns: {Object} The `os.userInfo()` method returns information about the currently effective -user -- on POSIX platforms, this is typically a subset of the password file. The +user — on POSIX platforms, this is typically a subset of the password file. The returned object includes the `username`, `uid`, `gid`, `shell`, and `homedir`. On Windows, the `uid` and `gid` fields are `-1`, and `shell` is `null`. diff --git a/doc/api/path.md b/doc/api/path.md index 5cfeba53402..51202195f3c 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -159,7 +159,7 @@ changes: The `path.extname()` method returns the extension of the `path`, from the last occurrence of the `.` (period) character to end of string in the last portion of -the `path`. If there is no `.` in the last portion of the `path`, or if the +the `path`. If there is no `.` in the last portion of the `path`, or if the first character of the basename of `path` (see `path.basename()`) is `.`, then an empty string is returned. @@ -388,7 +388,7 @@ path.parse('/home/user/dir/file.txt'); │ root │ │ name │ ext │ " / home/user/dir / file .txt " └──────┴──────────────┴──────┴─────┘ -(all spaces in the "" line should be ignored -- they are purely for formatting) +(all spaces in the "" line should be ignored — they are purely for formatting) ``` On Windows: @@ -410,7 +410,7 @@ path.parse('C:\\path\\dir\\file.txt'); │ root │ │ name │ ext │ " C:\ path\dir \ file .txt " └──────┴──────────────┴──────┴─────┘ -(all spaces in the "" line should be ignored -- they are purely for formatting) +(all spaces in the "" line should be ignored — they are purely for formatting) ``` A [`TypeError`][] is thrown if `path` is not a string. diff --git a/doc/api/process.md b/doc/api/process.md index 4f274fe1bdb..6338da49aa5 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -185,7 +185,7 @@ process will exit with a non-zero exit code and the stack trace will be printed. This is to avoid infinite recursion. Attempting to resume normally after an uncaught exception can be similar to -pulling out of the power cord when upgrading a computer -- nine out of ten +pulling out of the power cord when upgrading a computer — nine out of ten times nothing happens - but the 10th time, the system becomes corrupted. The correct use of `'uncaughtException'` is to perform synchronous cleanup @@ -353,7 +353,7 @@ The name of each event will be the uppercase common name for the signal (e.g. process.stdin.resume(); process.on('SIGINT', () => { - console.log('Received SIGINT. Press Control-D to exit.'); + console.log('Received SIGINT. Press Control-D to exit.'); }); // Using a single function to handle multiple signals @@ -437,7 +437,7 @@ added: v0.1.27 The `process.argv` property returns an array containing the command line arguments passed when the Node.js process was launched. The first element will be [`process.execPath`]. See `process.argv0` if access to the original value of -`argv[0]` is needed. The second element will be the path to the JavaScript +`argv[0]` is needed. The second element will be the path to the JavaScript file being executed. The remaining elements will be any additional command line arguments. @@ -976,7 +976,7 @@ added: v0.1.13 The `process.exit()` method instructs Node.js to terminate the process synchronously with an exit status of `code`. If `code` is omitted, exit uses either the 'success' code `0` or the value of `process.exitCode` if it has been -set. Node.js will not terminate until all the [`'exit'`] event listeners are +set. Node.js will not terminate until all the [`'exit'`] event listeners are called. To exit with a 'failure' code: @@ -1228,7 +1228,7 @@ Windows platforms will throw an error if the `pid` is used to kill a process group. Even though the name of this function is `process.kill()`, it is really just a -signal sender, like the `kill` system call. The signal sent may do something +signal sender, like the `kill` system call. The signal sent may do something other than kill the target process. ```js @@ -1326,7 +1326,7 @@ Once the current turn of the event loop turn runs to completion, all callbacks currently in the next tick queue will be called. This is *not* a simple alias to [`setTimeout(fn, 0)`][]. It is much more -efficient. It runs before any additional I/O events (including +efficient. It runs before any additional I/O events (including timers) fire in subsequent ticks of the event loop. ```js @@ -1361,7 +1361,7 @@ thing.getReadyForStuff(); ``` It is very important for APIs to be either 100% synchronous or 100% -asynchronous. Consider this example: +asynchronous. Consider this example: ```js // WARNING! DO NOT USE! BAD UNSAFE HAZARD! @@ -1403,7 +1403,7 @@ function definitelyAsync(arg, cb) { ``` The next tick queue is completely drained on each pass of the event loop -**before** additional I/O is processed. As a result, recursively setting +**before** additional I/O is processed. As a result, recursively setting nextTick callbacks will block any I/O from happening, just like a `while(true);` loop. @@ -1505,7 +1505,7 @@ tarball. builds of Node.js and will be missing on all other platforms._ * `lts` {string} a string label identifying the [LTS][] label for this release. This property only exists for LTS releases and is `undefined` for all other - release types, including _Current_ releases. Currently the valid values are: + release types, including _Current_ releases. Currently the valid values are: - `'Argon'` for the 4.x LTS line beginning with 4.2.0. - `'Boron'` for the 6.x LTS line beginning with 6.9.0. - `'Carbon'` for the 8.x LTS line beginning with 8.9.1. @@ -1583,7 +1583,7 @@ added: v2.0.0 The `process.seteuid()` method sets the effective user identity of the process. (See seteuid(2).) The `id` can be passed as either a numeric ID or a username -string. If a username is specified, the method blocks while resolving the +string. If a username is specified, the method blocks while resolving the associated numeric ID. ```js @@ -1609,7 +1609,7 @@ added: v0.1.31 * `id` {string|number} The group name or ID The `process.setgid()` method sets the group identity of the process. (See -setgid(2).) The `id` can be passed as either a numeric ID or a group name +setgid(2).) The `id` can be passed as either a numeric ID or a group name string. If a group name is specified, this method blocks while resolving the associated numeric ID. @@ -1650,7 +1650,7 @@ added: v0.1.28 --> The `process.setuid(id)` method sets the user identity of the process. (See -setuid(2).) The `id` can be passed as either a numeric ID or a username string. +setuid(2).) The `id` can be passed as either a numeric ID or a username string. If a username is specified, the method blocks while resolving the associated numeric ID. @@ -1831,7 +1831,7 @@ When a new value is assigned, different platforms will impose different maximum length restrictions on the title. Usually such restrictions are quite limited. For instance, on Linux and macOS, `process.title` is limited to the size of the binary name plus the length of the command line arguments because setting the -`process.title` overwrites the `argv` memory of the process. Node.js v0.8 +`process.title` overwrites the `argv` memory of the process. Node.js v0.8 allowed for longer process title strings by also overwriting the `environ` memory but that was potentially insecure and confusing in some (rather obscure) cases. @@ -1942,7 +1942,7 @@ Will generate an object similar to: ## Exit Codes Node.js will normally exit with a `0` status code when no more async -operations are pending. The following status codes are used in other +operations are pending. The following status codes are used in other cases: * `1` **Uncaught Fatal Exception** - There was an uncaught exception, @@ -1950,12 +1950,12 @@ cases: handler. * `2` - Unused (reserved by Bash for builtin misuse) * `3` **Internal JavaScript Parse Error** - The JavaScript source code - internal in Node.js's bootstrapping process caused a parse error. This + internal in Node.js's bootstrapping process caused a parse error. This is extremely rare, and generally can only happen during development of Node.js itself. * `4` **Internal JavaScript Evaluation Failure** - The JavaScript source code internal in Node.js's bootstrapping process failed to - return a function value when evaluated. This is extremely rare, and + return a function value when evaluated. This is extremely rare, and generally can only happen during development of Node.js itself. * `5` **Fatal Error** - There was a fatal unrecoverable error in V8. Typically a message will be printed to stderr with the prefix `FATAL @@ -1965,22 +1965,22 @@ cases: function was somehow set to a non-function, and could not be called. * `7` **Internal Exception Handler Run-Time Failure** - There was an uncaught exception, and the internal fatal exception handler - function itself threw an error while attempting to handle it. This + function itself threw an error while attempting to handle it. This can happen, for example, if a [`'uncaughtException'`][] or `domain.on('error')` handler throws an error. -* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes +* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes indicated an uncaught exception. * `9` - **Invalid Argument** - Either an unknown option was specified, or an option requiring a value was provided without a value. * `10` **Internal JavaScript Run-Time Failure** - The JavaScript source code internal in Node.js's bootstrapping process threw an error - when the bootstrapping function was called. This is extremely rare, + when the bootstrapping function was called. This is extremely rare, and generally can only happen during development of Node.js itself. * `12` **Invalid Debug Argument** - The `--inspect` and/or `--inspect-brk` options were set, but the port number chosen was invalid or unavailable. * `>128` **Signal Exits** - If Node.js receives a fatal signal such as `SIGKILL` or `SIGHUP`, then its exit code will be `128` plus the - value of the signal code. This is a standard POSIX practice, since + value of the signal code. This is a standard POSIX practice, since exit codes are defined to be 7-bit integers, and signal exits set the high-order bit, and then contain the value of the signal code. For example, signal `SIGABRT` has value `6`, so the expected exit diff --git a/doc/api/readline.md b/doc/api/readline.md index a1411a621c7..94151dfa62a 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -285,7 +285,7 @@ added: v0.1.98 * `shift` {boolean} `true` to indicate the `` key. * `name` {string} The name of the a key. -The `rl.write()` method will write either `data` or a key sequence identified +The `rl.write()` method will write either `data` or a key sequence identified by `key` to the `output`. The `key` argument is supported only if `output` is a [TTY][] text terminal. diff --git a/doc/api/repl.md b/doc/api/repl.md index a834862a607..f3f2fead575 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -442,7 +442,7 @@ changes: stream upon instantiation. * `eval` {Function} The function to be used when evaluating each given line of input. **Default:** an async wrapper for the JavaScript `eval()` - function. An `eval` function can error with `repl.Recoverable` to indicate + function. An `eval` function can error with `repl.Recoverable` to indicate the input was incomplete and prompt for additional lines. * `useColors` {boolean} If `true`, specifies that the default `writer` function should include ANSI color styling to REPL output. If a custom @@ -508,7 +508,7 @@ environment variables: - `NODE_REPL_HISTORY` - When a valid path is given, persistent REPL history will be saved to the specified file rather than `.node_repl_history` in the - user's home directory. Setting this value to `""` will disable persistent + user's home directory. Setting this value to `''` will disable persistent REPL history. Whitespace will be trimmed from the value. - `NODE_REPL_HISTORY_SIZE` - Controls how many lines of history will be persisted if history is available. Must be a positive number. @@ -521,7 +521,7 @@ environment variables: By default, the Node.js REPL will persist history between `node` REPL sessions by saving inputs to a `.node_repl_history` file located in the user's home directory. This can be disabled by setting the environment variable -`NODE_REPL_HISTORY=""`. +`NODE_REPL_HISTORY=''`. ### Using the Node.js REPL with advanced line-editors diff --git a/doc/api/stream.md b/doc/api/stream.md index c2e5de79efe..9f233cd3251 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1567,7 +1567,7 @@ It is recommended that errors occurring during the processing of the the callback and passing the error as the first argument. This will cause an `'error'` event to be emitted by the Writable. Throwing an Error from within `writable._write()` can result in unexpected and inconsistent behavior depending -on how the stream is being used. Using the callback ensures consistent and +on how the stream is being used. Using the callback ensures consistent and predictable handling of errors. If a Readable stream pipes into a Writable stream when Writable emits an @@ -1779,7 +1779,7 @@ changes: read queue. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any JavaScript value. -* `encoding` {string} Encoding of string chunks. Must be a valid +* `encoding` {string} Encoding of string chunks. Must be a valid Buffer encoding, such as `'utf8'` or `'ascii'` * Returns: {boolean} `true` if additional chunks of data may continued to be pushed; `false` otherwise. @@ -2211,7 +2211,7 @@ The `transform._transform()` method is prefixed with an underscore because it is internal to the class that defines it, and should never be called directly by user programs. -`transform._transform()` is never called in parallel; streams implement a +`transform._transform()` is never called in parallel; streams implement a queue mechanism, and to receive the next chunk, `callback` must be called, either synchronously or asynchronously. diff --git a/doc/api/tls.md b/doc/api/tls.md index a4328eda31c..4eb4898a326 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -366,7 +366,7 @@ added: v0.6.0 --> Returns the bound address, the address family name, and port of the -server as reported by the operating system. See [`net.Server.address()`][] for +server as reported by the operating system. See [`net.Server.address()`][] for more information. ### server.close([callback]) @@ -628,7 +628,7 @@ For example: raw: < RAW DER buffer >, pubkey: < RAW DER buffer >, valid_from: 'Nov 11 09:52:22 2009 GMT', - valid_to: 'Nov 6 09:52:22 2029 GMT', + valid_to: 'Nov 6 09:52:22 2029 GMT', fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF', fingerprint256: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF:00:11:22:33:44:55:66:77:88:99:AA:BB', serialNumber: 'B9B0D332A1AA5635' } @@ -851,7 +851,7 @@ changes: rather than creating a new socket. Typically, this is an instance of [`net.Socket`][], but any `Duplex` stream is allowed. If this option is specified, `path`, `host` and `port` are ignored, - except for certificate validation. Usually, a socket is already connected + except for certificate validation. Usually, a socket is already connected when passed to `tls.connect()`, but it can be connected later. Note that connection/disconnection/destruction of `socket` is the user's responsibility, calling `tls.connect()` will not cause `net.connect()` to be @@ -1010,7 +1010,7 @@ changes: 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 + keys will be decrypted with `options.passphrase`. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form `{pem: [, passphrase: ]}`. The object form can only occur in @@ -1023,7 +1023,7 @@ changes: consist of the PEM formatted certificate for a provided private `key`, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, - see `ca`). When providing multiple cert chains, they do not have to be in + see `ca`). When providing multiple cert chains, they do not have to be in the same order as their private keys in `key`. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail. @@ -1033,7 +1033,7 @@ changes: using this option. The value can be a string or Buffer, or an Array of strings and/or Buffers. Any string or Buffer can contain multiple PEM CAs concatenated together. The peer's certificate must be chainable to a CA - trusted by the server for the connection to be authenticated. When using + trusted by the server for the connection to be authenticated. When using certificates that are not chainable to a well-known CA, the certificate's CA must be explicitly specified as a trusted or the connection will fail to authenticate. @@ -1043,7 +1043,7 @@ changes: For self-signed certificates, the certificate is its own CA, and must be provided. * `ciphers` {string} Optional cipher suite specification, replacing the - default. For more information, see [modifying the default cipher suite][]. + default. For more information, see [modifying the default cipher suite][]. * `honorCipherOrder` {boolean} Attempt to use the server's cipher suite preferences instead of the client's. When `true`, causes `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see @@ -1144,7 +1144,7 @@ changes: servers, the identity options (`pfx` or `key`/`cert`) are usually required. * `secureConnectionListener` {Function} -Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is +Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is automatically set as a listener for the [`'secureConnection'`][] event. The `ticketKeys` options is automatically shared between `cluster` module diff --git a/doc/api/url.md b/doc/api/url.md index 46b3a40f94f..62d19d9c90d 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -51,7 +51,7 @@ WHATWG URL's `origin` property includes `protocol` and `host`, but not ├─────────────┴─────────────────────┴─────────────────────┴──────────┴────────────────┴───────┤ │ href │ └─────────────────────────────────────────────────────────────────────────────────────────────┘ -(all spaces in the "" line should be ignored -- they are purely for formatting) +(all spaces in the "" line should be ignored — they are purely for formatting) ``` Parsing the URL string using the WHATWG API: @@ -541,7 +541,7 @@ Instantiate a new `URLSearchParams` object with an iterable map in a way that is similar to [`Map`][]'s constructor. `iterable` can be an Array or any iterable object. That means `iterable` can be another `URLSearchParams`, in which case the constructor will simply create a clone of the provided -`URLSearchParams`. Elements of `iterable` are key-value pairs, and can +`URLSearchParams`. Elements of `iterable` are key-value pairs, and can themselves be any iterable object. Duplicate keys are allowed. diff --git a/doc/api/util.md b/doc/api/util.md index caee5990fb1..e5d57759e5f 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -78,9 +78,9 @@ added: v0.11.3 The `util.debuglog()` method is used to create a function that conditionally writes debug messages to `stderr` based on the existence of the `NODE_DEBUG` -environment variable. If the `section` name appears within the value of that +environment variable. If the `section` name appears within the value of that environment variable, then the returned function operates similar to -[`console.error()`][]. If not, then the returned function is a no-op. +[`console.error()`][]. If not, then the returned function is a no-op. ```js const util = require('util'); @@ -96,7 +96,7 @@ it will output something like: FOO 3245: hello from foo [123] ``` -where `3245` is the process id. If it is not run with that +where `3245` is the process id. If it is not run with that environment variable set, then it will not print anything. The `section` supports wildcard also: @@ -203,7 +203,7 @@ corresponding argument. Supported placeholders are: * `%d` - Number (integer or floating point value). * `%i` - Integer. * `%f` - Floating point value. -* `%j` - JSON. Replaced with the string `'[Circular]'` if the argument +* `%j` - JSON. Replaced with the string `'[Circular]'` if the argument contains circular references. * `%o` - Object. A string representation of an object with generic JavaScript object formatting. @@ -289,7 +289,7 @@ that the two styles are [semantically incompatible][]. * `constructor` {Function} * `superConstructor` {Function} -Inherit the prototype methods from one [constructor][] into another. The +Inherit the prototype methods from one [constructor][] into another. The prototype of `constructor` will be set to a new object created from `superConstructor`. diff --git a/doc/api/v8.md b/doc/api/v8.md index c18e2691f64..a72d7fa51e4 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -141,7 +141,7 @@ after the VM has started may result in unpredictable behavior, including crashes and data loss; or it may simply do nothing. The V8 options available for a version of Node.js may be determined by running -`node --v8-options`. An unofficial, community-maintained list of options +`node --v8-options`. An unofficial, community-maintained list of options and their effects is available [here][]. Usage: diff --git a/doc/api/vm.md b/doc/api/vm.md index 5797294ef98..95585955614 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -307,7 +307,7 @@ The URL of the current module, as set in the constructor. will be thrown. * `breakOnSigint` {boolean} If `true`, the execution will be terminated when `SIGINT` (Ctrl+C) is received. Existing handlers for the event that have - been attached via `process.on("SIGINT")` will be disabled during script + been attached via `process.on('SIGINT')` will be disabled during script execution, but will continue to work after that. If execution is interrupted, an [`Error`][] will be thrown. * Returns: {Promise} @@ -468,7 +468,7 @@ changes: will be thrown. * `breakOnSigint`: if `true`, the execution will be terminated when `SIGINT` (Ctrl+C) is received. Existing handlers for the - event that have been attached via `process.on("SIGINT")` will be disabled + event that have been attached via `process.on('SIGINT')` will be disabled during script execution, but will continue to work after that. If execution is terminated, an [`Error`][] will be thrown. diff --git a/doc/api/zlib.md b/doc/api/zlib.md index cf9cb34a357..4a9103a9793 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -165,7 +165,7 @@ The memory requirements for deflate are (in bytes): (1 << (windowBits + 2)) + (1 << (memLevel + 9)) ``` -That is: 128K for windowBits=15 + 128K for memLevel = 8 +That is: 128K for windowBits = 15 + 128K for memLevel = 8 (default values) plus a few kilobytes for small objects. For example, to reduce the default memory requirements from 256K to 128K, the @@ -178,20 +178,20 @@ const options = { windowBits: 14, memLevel: 7 }; This will, however, generally degrade compression. The memory requirements for inflate are (in bytes) `1 << windowBits`. -That is, 32K for windowBits=15 (default value) plus a few kilobytes +That is, 32K for windowBits = 15 (default value) plus a few kilobytes for small objects. This is in addition to a single internal output slab buffer of size `chunkSize`, which defaults to 16K. The speed of `zlib` compression is affected most dramatically by the -`level` setting. A higher level will result in better compression, but -will take longer to complete. A lower level will result in less +`level` setting. A higher level will result in better compression, but +will take longer to complete. A lower level will result in less compression, but will be much faster. In general, greater memory usage options will mean that Node.js has to make fewer calls to `zlib` because it will be able to process more data on -each `write` operation. So, this is another factor that affects the +each `write` operation. So, this is another factor that affects the speed, at the cost of memory usage. ## Flushing @@ -233,9 +233,9 @@ added: v0.5.8 All of the constants defined in `zlib.h` are also defined on `require('zlib').constants`. In the normal course of operations, it will not be -necessary to use these constants. They are documented so that their presence is +necessary to use these constants. They are documented so that their presence is not surprising. This section is taken almost directly from the -[zlib documentation][]. See for more +[zlib documentation][]. See for more details. Previously, the constants were available directly from `require('zlib')`, for @@ -298,7 +298,7 @@ changes: -Each class takes an `options` object. All options are optional. +Each class takes an `options` object. All options are optional. Note that some options are only relevant when compressing, and are ignored by the decompression classes. From 3d61e14704bb82ffc1442e6f6c3756f4432b03b4 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 1 Apr 2018 22:03:59 -0700 Subject: [PATCH 16/22] buffer: shorten deprecation warning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shorten the deprecation warning for Buffer constructor. PR-URL: https://github.com/nodejs/node/pull/19741 Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat Reviewed-By: Сковорода Никита Андреевич --- lib/buffer.js | 8 +++----- test/parallel/test-buffer-pending-deprecation.js | 8 +++----- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/lib/buffer.js b/lib/buffer.js index 42862c02da9..73e3bc44209 100644 --- a/lib/buffer.js +++ b/lib/buffer.js @@ -140,11 +140,9 @@ function alignPool() { } var bufferWarn = true; -const bufferWarning = 'The Buffer() and new Buffer() constructors are not ' + - 'recommended for use due to security and usability ' + - 'concerns. Please use the Buffer.alloc(), ' + - 'Buffer.allocUnsafe(), or Buffer.from() construction ' + - 'methods instead.'; +const bufferWarning = 'Buffer() is deprecated due to security and usability ' + + 'issues. Please use the Buffer.alloc(), ' + + 'Buffer.allocUnsafe(), or Buffer.from() methods instead.'; function showFlaggedDeprecation() { if (bufferWarn) { diff --git a/test/parallel/test-buffer-pending-deprecation.js b/test/parallel/test-buffer-pending-deprecation.js index ba9f1b7bd7b..1bb7b0bee19 100644 --- a/test/parallel/test-buffer-pending-deprecation.js +++ b/test/parallel/test-buffer-pending-deprecation.js @@ -3,11 +3,9 @@ const common = require('../common'); -const bufferWarning = 'The Buffer() and new Buffer() constructors are not ' + - 'recommended for use due to security and usability ' + - 'concerns. Please use the Buffer.alloc(), ' + - 'Buffer.allocUnsafe(), or Buffer.from() construction ' + - 'methods instead.'; +const bufferWarning = 'Buffer() is deprecated due to security and usability ' + + 'issues. Please use the Buffer.alloc(), ' + + 'Buffer.allocUnsafe(), or Buffer.from() methods instead.'; common.expectWarning('DeprecationWarning', bufferWarning, 'DEP0005'); From 1b715221b9b875fc24d6aae3480c4c55d7f3dd76 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Sun, 1 Apr 2018 11:27:01 +0200 Subject: [PATCH 17/22] tty: add attribution for chalk This adds attributions for the getColorDepth function as it got inspired by https://github.com/chalk/supports-color and more sources. PR-URL: https://github.com/nodejs/node/pull/19730 Reviewed-By: Anna Henningsen Reviewed-By: Richard Lau Reviewed-By: Matteo Collina Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat --- lib/internal/tty.js | 104 ++++++++++++++++++++++++++++++++++++++++++++ lib/tty.js | 74 +------------------------------ node.gyp | 1 + 3 files changed, 107 insertions(+), 72 deletions(-) create mode 100644 lib/internal/tty.js diff --git a/lib/internal/tty.js b/lib/internal/tty.js new file mode 100644 index 00000000000..a581ac312f5 --- /dev/null +++ b/lib/internal/tty.js @@ -0,0 +1,104 @@ +// MIT License + +// Copyright (c) Sindre Sorhus (sindresorhus.com) + +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: + +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. + +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +// SOFTWARE. + +'use strict'; + +const { release } = require('os'); + +const OSRelease = release().split('.'); + +const COLORS_2 = 1; +const COLORS_16 = 4; +const COLORS_256 = 8; +const COLORS_16m = 24; + +// The `getColorDepth` API got inspired by multiple sources such as +// https://github.com/chalk/supports-color, +// https://github.com/isaacs/color-support. +function getColorDepth(env = process.env) { + if (env.NODE_DISABLE_COLORS || env.TERM === 'dumb' && !env.COLORTERM) { + return COLORS_2; + } + + if (process.platform === 'win32') { + // Windows 10 build 10586 is the first Windows release that supports 256 + // colors. Windows 10 build 14931 is the first release that supports + // 16m/TrueColor. + if (+OSRelease[0] >= 10) { + const build = +OSRelease[2]; + if (build >= 14931) + return COLORS_16m; + if (build >= 10586) + return COLORS_256; + } + + return COLORS_16; + } + + if (env.TMUX) { + return COLORS_256; + } + + if (env.CI) { + if ('TRAVIS' in env || 'CIRCLECI' in env || 'APPVEYOR' in env || + 'GITLAB_CI' in env || env.CI_NAME === 'codeship') { + return COLORS_256; + } + return COLORS_2; + } + + if ('TEAMCITY_VERSION' in env) { + return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? + COLORS_16 : COLORS_2; + } + + switch (env.TERM_PROGRAM) { + case 'iTerm.app': + if (!env.TERM_PROGRAM_VERSION || + /^[0-2]\./.test(env.TERM_PROGRAM_VERSION)) { + return COLORS_256; + } + return COLORS_16m; + case 'HyperTerm': + case 'Hyper': + case 'MacTerm': + return COLORS_16m; + case 'Apple_Terminal': + return COLORS_256; + } + + if (env.TERM) { + if (/^xterm-256/.test(env.TERM)) + return COLORS_256; + if (/^screen|^xterm|^vt100|color|ansi|cygwin|linux/i.test(env.TERM)) + return COLORS_16; + } + + if (env.COLORTERM) + return COLORS_16; + + return COLORS_2; +} + +module.exports = { + getColorDepth +}; diff --git a/lib/tty.js b/lib/tty.js index 51ec1cf8981..dfb76bbe53d 100644 --- a/lib/tty.js +++ b/lib/tty.js @@ -27,14 +27,7 @@ const { TTY, isTTY } = process.binding('tty_wrap'); const errors = require('internal/errors'); const { ERR_INVALID_FD } = errors.codes; const readline = require('readline'); -const { release } = require('os'); - -const OSRelease = release().split('.'); - -const COLORS_2 = 1; -const COLORS_16 = 4; -const COLORS_256 = 8; -const COLORS_16m = 24; +const { getColorDepth } = require('internal/tty'); function isatty(fd) { return Number.isInteger(fd) && fd >= 0 && isTTY(fd); @@ -108,70 +101,7 @@ inherits(WriteStream, net.Socket); WriteStream.prototype.isTTY = true; -WriteStream.prototype.getColorDepth = function(env = process.env) { - if (env.NODE_DISABLE_COLORS || env.TERM === 'dumb' && !env.COLORTERM) { - return COLORS_2; - } - - if (process.platform === 'win32') { - // Windows 10 build 10586 is the first Windows release that supports 256 - // colors. Windows 10 build 14931 is the first release that supports - // 16m/TrueColor. - if (+OSRelease[0] >= 10) { - const build = +OSRelease[2]; - if (build >= 14931) - return COLORS_16m; - if (build >= 10586) - return COLORS_256; - } - - return COLORS_16; - } - - if (env.TMUX) { - return COLORS_256; - } - - if (env.CI) { - if ('TRAVIS' in env || 'CIRCLECI' in env || 'APPVEYOR' in env || - 'GITLAB_CI' in env || env.CI_NAME === 'codeship') { - return COLORS_256; - } - return COLORS_2; - } - - if ('TEAMCITY_VERSION' in env) { - return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? - COLORS_16 : COLORS_2; - } - - switch (env.TERM_PROGRAM) { - case 'iTerm.app': - if (!env.TERM_PROGRAM_VERSION || - /^[0-2]\./.test(env.TERM_PROGRAM_VERSION)) { - return COLORS_256; - } - return COLORS_16m; - case 'HyperTerm': - case 'Hyper': - case 'MacTerm': - return COLORS_16m; - case 'Apple_Terminal': - return COLORS_256; - } - - if (env.TERM) { - if (/^xterm-256/.test(env.TERM)) - return COLORS_256; - if (/^screen|^xterm|^vt100|color|ansi|cygwin|linux/i.test(env.TERM)) - return COLORS_16; - } - - if (env.COLORTERM) - return COLORS_16; - - return COLORS_2; -}; +WriteStream.prototype.getColorDepth = getColorDepth; WriteStream.prototype._refreshSize = function() { const oldCols = this.columns; diff --git a/node.gyp b/node.gyp index cb305b93e9f..dc1cd5f72fd 100644 --- a/node.gyp +++ b/node.gyp @@ -133,6 +133,7 @@ 'lib/internal/timers.js', 'lib/internal/tls.js', 'lib/internal/trace_events_async_hooks.js', + 'lib/internal/tty.js', 'lib/internal/url.js', 'lib/internal/util.js', 'lib/internal/util/comparisons.js', From ceaeee012066e7e56332ba9d9f9306401c971560 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Sun, 1 Apr 2018 11:37:13 +0200 Subject: [PATCH 18/22] tty: add color support for more terminals This adds support for a couple more terminals. PR-URL: https://github.com/nodejs/node/pull/19730 Reviewed-By: Anna Henningsen Reviewed-By: Richard Lau Reviewed-By: Matteo Collina Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat --- lib/internal/tty.js | 50 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/lib/internal/tty.js b/lib/internal/tty.js index a581ac312f5..c4edab24fb8 100644 --- a/lib/internal/tty.js +++ b/lib/internal/tty.js @@ -31,6 +31,41 @@ const COLORS_16 = 4; const COLORS_256 = 8; const COLORS_16m = 24; +// Some entries were taken from `dircolors` +// (https://linux.die.net/man/1/dircolors). The corresponding terminals might +// support more than 16 colors, but this was not tested for. +// +// Copyright (C) 1996-2016 Free Software Foundation, Inc. Copying and +// distribution of this file, with or without modification, are permitted +// provided the copyright notice and this notice are preserved. +const TERM_ENVS = [ + 'Eterm', + 'cons25', + 'console', + 'cygwin', + 'dtterm', + 'gnome', + 'hurd', + 'jfbterm', + 'konsole', + 'kterm', + 'mlterm', + 'putty', + 'st', + 'terminator' +]; + +const TERM_ENVS_REG_EXP = [ + /ansi/, + /color/, + /linux/, + /^con[0-9]*x[0-9]/, + /^rxvt/, + /^screen/, + /^xterm/, + /^vt100/ +]; + // The `getColorDepth` API got inspired by multiple sources such as // https://github.com/chalk/supports-color, // https://github.com/isaacs/color-support. @@ -89,8 +124,19 @@ function getColorDepth(env = process.env) { if (env.TERM) { if (/^xterm-256/.test(env.TERM)) return COLORS_256; - if (/^screen|^xterm|^vt100|color|ansi|cygwin|linux/i.test(env.TERM)) - return COLORS_16; + + const termEnv = env.TERM.toLowerCase(); + + for (const term of TERM_ENVS) { + if (termEnv === term) { + return COLORS_16; + } + } + for (const term of TERM_ENVS_REG_EXP) { + if (term.test(termEnv)) { + return COLORS_16; + } + } } if (env.COLORTERM) From 5bdd6a7b9e9f0cae02e441affba80a5f49098e1a Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Sun, 1 Apr 2018 10:11:24 +0200 Subject: [PATCH 19/22] doc: properly document AssertionError The AssertionError was always exposed but never properly documented. This explains how it is used and what options it accepts. PR-URL: https://github.com/nodejs/node/pull/19724 Reviewed-By: Vse Mozhet Byt Reviewed-By: Luigi Pinca Reviewed-By: James M Snell --- doc/api/assert.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++ doc/api/errors.md | 10 +++----- 2 files changed, 67 insertions(+), 7 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 63e6950f6ab..4e9ff82774c 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -13,6 +13,70 @@ A `strict` and a `legacy` mode exist, while it is recommended to only use For more information about the used equality comparisons see [MDN's guide on equality comparisons and sameness][mdn-equality-guide]. +## Class: assert.AssertionError + +A subclass of `Error` that indicates the failure of an assertion. All errors +thrown by the `assert` module will be instances of the `AssertionError` class. + +### new assert.AssertionError(options) + +* `options` {Object} + * `message` {string} If provided, the error message is going to be set to this + value. + * `actual` {any} The `actual` property on the error instance is going to + contain this value. Internally used for the `actual` error input in case + e.g., [`assert.strictEqual()`] is used. + * `expected` {any} The `expected` property on the error instance is going to + contain this value. Internally used for the `expected` error input in case + e.g., [`assert.strictEqual()`] is used. + * `operator` {string} The `operator` property on the error instance is going + to contain this value. Internally used to indicate what operation was used + for comparison (or what assertion function triggered the error). + * `stackStartFn` {Function} If provided, the generated stack trace is going to + remove all frames up to the provided function. + +A subclass of `Error` that indicates the failure of an assertion. + +All instances contain the built-in `Error` properties (`message` and `name`) +and: + +* `actual` {any} Set to the actual value in case e.g., + [`assert.strictEqual()`] is used. +* `expected` {any} Set to the expected value in case e.g., + [`assert.strictEqual()`] is used. +* `generatedMessage` {boolean} Indicates if the message was auto-generated + (`true`) or not. +* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate + that the error is actually an assertion error. +* `operator` {string} Set to the passed in operator value. + +```js +const assert = require('assert'); + +// Generate an AssertionError to compare the error message later: +const { message } = new assert.AssertionError({ + actual: 1, + expected: 2, + operator: 'strictEqual' +}); + +// Verify error output: +try { + assert.strictEqual(1, 2); +} catch (err) { + assert(err instanceof assert.AssertionError); + assert.strictEqual(err.message, message); + assert.strictEqual(err.name, 'AssertionError [ERR_ASSERTION]'); + assert.strictEqual(err.actual, 1); + assert.strictEqual(err.expected, 2); + assert.strictEqual(err.code, 'ERR_ASSERTION'); + assert.strictEqual(err.operator, 'strictEqual'); + assert.strictEqual(err.generatedMessage, true); +} +``` + ## Strict mode + > Stability: 2 - Stable From a972ed4d508e536fec96d4be20e3172bca1f6665 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Tue, 27 Mar 2018 09:55:18 -0400 Subject: [PATCH 21/22] build: allow vcbuild to merely build addon tests RE: https://github.com/nodejs/build/issues/1097 PR-URL: https://github.com/nodejs/node/pull/19637 Reviewed-By: James M Snell Reviewed-By: Richard Lau Reviewed-By: Gibson Fahnestock --- vcbuild.bat | 2 ++ 1 file changed, 2 insertions(+) diff --git a/vcbuild.bat b/vcbuild.bat index 0129319034b..7b902a59c9a 100644 --- a/vcbuild.bat +++ b/vcbuild.bat @@ -72,6 +72,8 @@ if /i "%1"=="noperfctr" set noperfctr=1&goto arg-ok if /i "%1"=="licensertf" set licensertf=1&goto arg-ok if /i "%1"=="test" set test_args=%test_args% -J %common_test_suites%&set lint_cpp=1&set lint_js=1&goto arg-ok if /i "%1"=="test-ci" set test_args=%test_args% %test_ci_args% -p tap --logfile test.tap %common_test_suites%&set cctest_args=%cctest_args% --gtest_output=tap:cctest.tap&goto arg-ok +if /i "%1"=="build-addons" set build_addons=1&goto arg-ok +if /i "%1"=="build-addons-napi" set build_addons_napi=1&goto arg-ok if /i "%1"=="test-addons" set test_args=%test_args% addons&set build_addons=1&goto arg-ok if /i "%1"=="test-addons-napi" set test_args=%test_args% addons-napi&set build_addons_napi=1&goto arg-ok if /i "%1"=="test-simple" set test_args=%test_args% sequential parallel -J&goto arg-ok From b22a189b430e87d225279b43148b11f68fca8f49 Mon Sep 17 00:00:00 2001 From: Daniel Bevenius Date: Wed, 4 Apr 2018 12:46:44 +0200 Subject: [PATCH 22/22] deps: fix typo in openssl upgrading doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/19789 Reviewed-By: Tobias Nießen Reviewed-By: Gibson Fahnestock Reviewed-By: Colin Ihrig Reviewed-By: Luigi Pinca Reviewed-By: Trivikram Kamat --- deps/openssl/doc/UPGRADING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deps/openssl/doc/UPGRADING.md b/deps/openssl/doc/UPGRADING.md index fc229f19757..8b25962a952 100644 --- a/deps/openssl/doc/UPGRADING.md +++ b/deps/openssl/doc/UPGRADING.md @@ -80,7 +80,7 @@ Since perl is not a build requirement in node, they all should be generated in advance and statically stored in the repository. We provide two sets of asm files, one is asm_latest(avx2 and addx supported) in `deps/openssl/asm` and the other asm_obsolete(without -avx1/2 and addx) in `deps/openssl/asm_obsolute`, which depends on +avx1/2 and addx) in `deps/openssl/asm_obsolete`, which depends on supported features in assemblers. Each directory has a `Makefile` to generate asm files with perl scripts in openssl sources.