diff options
| author | Vse Mozhet Byt <vsemozhetbyt@gmail.com> | 2018-04-29 20:46:41 +0300 |
|---|---|---|
| committer | Vse Mozhet Byt <vsemozhetbyt@gmail.com> | 2018-05-03 02:12:07 +0300 |
| commit | 7588ceaf353af0f257d4d832bace4600edac704e (patch) | |
| tree | cd01b69085d5c1134c43e61d8acc84586d1a188d | |
| parent | bdf5be98dd901f6c312938198439dbda0b20d517 (diff) | |
| download | android-node-v8-7588ceaf353af0f257d4d832bace4600edac704e.tar.gz android-node-v8-7588ceaf353af0f257d4d832bace4600edac704e.tar.bz2 android-node-v8-7588ceaf353af0f257d4d832bace4600edac704e.zip | |
doc: add more missing backticks
Also, fix some other nits in passing
(formatting, punctuation, typos, redundancy, obsoleteness).
PR-URL: https://github.com/nodejs/node/pull/20438
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
35 files changed, 649 insertions, 648 deletions
diff --git a/doc/api/addons.md b/doc/api/addons.md index 46bc1e7522..a207a71b71 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -9,7 +9,7 @@ just as if they were an ordinary Node.js module. They are used primarily to provide an interface between JavaScript running in Node.js and C/C++ libraries. At the moment, the method for implementing Addons is rather complicated, -involving knowledge of several components and APIs : +involving knowledge of several components and APIs: - V8: the C++ library Node.js currently uses to provide the JavaScript implementation. V8 provides the mechanisms for creating objects, @@ -93,7 +93,7 @@ There is no semi-colon after `NODE_MODULE` as it's not a function (see `node.h`). The `module_name` must match the filename of the final binary (excluding -the .node suffix). +the `.node` suffix). In the `hello.cc` example, then, the initialization function is `init` and the Addon module name is `addon`. @@ -1085,9 +1085,9 @@ console.log(result); ### AtExit hooks -An "AtExit" hook is a function that is invoked after the Node.js event loop +An `AtExit` hook is a function that is invoked after the Node.js event loop has ended but before the JavaScript VM is terminated and Node.js shuts down. -"AtExit" hooks are registered using the `node::AtExit` API. +`AtExit` hooks are registered using the `node::AtExit` API. #### void AtExit(callback, args) @@ -1099,12 +1099,12 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down. Registers exit hooks that run after the event loop has ended but before the VM is killed. -AtExit takes two parameters: a pointer to a callback function to run at exit, +`AtExit` takes two parameters: a pointer to a callback function to run at exit, and a pointer to untyped context data to be passed to that callback. Callbacks are run in last-in first-out order. -The following `addon.cc` implements AtExit: +The following `addon.cc` implements `AtExit`: ```cpp // addon.cc diff --git a/doc/api/assert.md b/doc/api/assert.md index 468293b208..43e5800ff0 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -165,10 +165,10 @@ added: v0.1.21 changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001 - description: Error names and messages are now properly compared + description: The `Error` names and messages are now properly compared - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12142 - description: Set and Map content is also compared + description: The `Set` and `Map` content is also compared - version: v6.4.0, v4.7.1 pr-url: https://github.com/nodejs/node/pull/8002 description: Typed array slices are handled correctly now. @@ -208,7 +208,7 @@ the [`RegExp`][] object are not enumerable: assert.deepEqual(/a/gi, new Date()); ``` -An exception is made for [`Map`][] and [`Set`][]. Maps and Sets have their +An exception is made for [`Map`][] and [`Set`][]. `Map`s and `Set`s have their contained items compared too, as expected. "Deep" equality means that the enumerable "own" properties of child objects @@ -264,15 +264,15 @@ changes: description: Enumerable symbol properties are now compared. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15036 - description: NaN is now compared using the + description: The `NaN` is now compared using the [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) comparison. - version: v8.5.0 pr-url: https://github.com/nodejs/node/pull/15001 - description: Error names and messages are now properly compared + description: The `Error` names and messages are now properly compared - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12142 - description: Set and Map content is also compared + description: The `Set` and `Map` content is also compared - version: v6.4.0, v4.7.1 pr-url: https://github.com/nodejs/node/pull/8002 description: Typed array slices are handled correctly now. @@ -303,8 +303,8 @@ are recursively evaluated also by the following rules. enumerable properties. * Enumerable own [`Symbol`][] properties are compared as well. * [Object wrappers][] are compared both as objects and unwrapped values. -* Object properties are compared unordered. -* Map keys and Set items are compared unordered. +* `Object` properties are compared unordered. +* `Map` keys and `Set` items are compared unordered. * Recursion stops when both sides differ or both sides encounter a circular reference. * [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values. See @@ -413,10 +413,10 @@ function and awaits the returned promise to complete. It will then check that the promise is not rejected. If `block` is a function and it throws an error synchronously, -`assert.doesNotReject()` will return a rejected Promise with that error. If the -function does not return a promise, `assert.doesNotReject()` will return a -rejected Promise with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the -error handler is skipped. +`assert.doesNotReject()` will return a rejected `Promise` with that error. If +the function does not return a promise, `assert.doesNotReject()` will return a +rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases +the error handler is skipped. Please note: Using `assert.doesNotReject()` is actually not useful because there is little benefit by catching a rejection and then rejecting it again. Instead, @@ -494,7 +494,7 @@ assert.doesNotThrow( ``` However, the following will result in an `AssertionError` with the message -'Got unwanted exception (TypeError)..': +'Got unwanted exception...': <!-- eslint-disable no-restricted-syntax --> ```js @@ -519,7 +519,7 @@ assert.doesNotThrow( /Wrong value/, 'Whoops' ); -// Throws: AssertionError: Got unwanted exception (TypeError). Whoops +// Throws: AssertionError: Got unwanted exception: Whoops ``` ## assert.equal(actual, expected[, message]) @@ -656,7 +656,7 @@ changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18247 description: Instead of throwing the original error it is now wrapped into - a AssertionError that contains the full stack trace. + an `AssertionError` that contains the full stack trace. - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18247 description: Value may now only be `undefined` or `null`. Before any truthy @@ -701,10 +701,10 @@ added: v0.1.21 changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001 - description: Error names and messages are now properly compared + description: The `Error` names and messages are now properly compared - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12142 - description: Set and Map content is also compared + description: The `Set` and `Map` content is also compared - version: v6.4.0, v4.7.1 pr-url: https://github.com/nodejs/node/pull/8002 description: Typed array slices are handled correctly now. @@ -774,18 +774,18 @@ added: v1.2.0 changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15398 - description: -0 and +0 are not considered equal anymore. + description: The `-0` and `+0` are not considered equal anymore. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15036 - description: NaN is now compared using the + description: The `NaN` is now compared using the [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) comparison. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001 - description: Error names and messages are now properly compared + description: The `Error` names and messages are now properly compared - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12142 - description: Set and Map content is also compared + description: The `Set` and `Map` content is also compared - version: v6.4.0, v4.7.1 pr-url: https://github.com/nodejs/node/pull/8002 description: Typed array slices are handled correctly now. @@ -893,7 +893,8 @@ added: v0.1.21 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18319 - description: assert.ok() (no arguments) will now use a predefined error msg. + description: The `assert.ok()` (no arguments) will now use a predefined + error message. --> * `value` {any} * `message` {any} @@ -907,7 +908,7 @@ parameter is `undefined`, a default error message is assigned. If the `message` parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. If no arguments are passed in at all `message` will be set to the string: -"No value argument passed to assert.ok". +``'No value argument passed to `assert.ok()`'``. Be aware that in the `repl` the error message will be different to the one thrown in a file! See below for further details. @@ -966,9 +967,9 @@ function and awaits the returned promise to complete. It will then check that the promise is rejected. If `block` is a function and it throws an error synchronously, -`assert.rejects()` will return a rejected Promise with that error. If the +`assert.rejects()` will return a rejected `Promise` with that error. If the function does not return a promise, `assert.rejects()` will return a rejected -Promise with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error +`Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error handler is skipped. Besides the async nature to await the completion behaves identically to diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 601dad93e7..b97bc73304 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -17,8 +17,8 @@ const async_hooks = require('async_hooks'); An asynchronous resource represents an object with an associated callback. This callback may be called multiple times, for example, the `'connection'` event in `net.createServer()`, or just a single time like in `fs.open()`. -A resource can also be closed before the callback is called. AsyncHook does not -explicitly distinguish between these different cases but will represent them +A resource can also be closed before the callback is called. `AsyncHook` does +not explicitly distinguish between these different cases but will represent them as the abstract concept that is a resource. ## Public API @@ -188,7 +188,7 @@ const hook = async_hooks.createHook(callbacks).enable(); * Returns: {AsyncHook} A reference to `asyncHook`. Disable the callbacks for a given `AsyncHook` instance from the global pool of -AsyncHook callbacks to be executed. Once a hook has been disabled it will not +`AsyncHook` callbacks to be executed. Once a hook has been disabled it will not be called again until enabled. For API consistency `disable()` also returns the `AsyncHook` instance. @@ -299,10 +299,10 @@ and document their own resource objects. For example, such a resource object could contain the SQL query being executed. In the case of Promises, the `resource` object will have `promise` property -that refers to the Promise that is being initialized, and a `isChainedPromise` -property, set to `true` if the promise has a parent promise, and `false` -otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered -a parent Promise of `b`. Here, `b` is considered a chained promise. +that refers to the `Promise` that is being initialized, and an +`isChainedPromise` property, set to `true` if the promise has a parent promise, +and `false` otherwise. For example, in the case of `b = a.then(handler)`, `a` is +considered a parent `Promise` of `b`. Here, `b` is considered a chained promise. In some cases the resource object is reused for performance reasons, it is thus not safe to use it as a key in a `WeakMap` or add properties to it. @@ -466,7 +466,7 @@ added: v8.1.0 changes: - version: v8.2.0 pr-url: https://github.com/nodejs/node/pull/13490 - description: Renamed from currentId + description: Renamed from `currentId` --> * Returns: {number} The `asyncId` of the current execution context. Useful to @@ -498,7 +498,7 @@ const server = net.createServer(function onConnection(conn) { }); ``` -Note that promise contexts may not get precise executionAsyncIds by default. +Note that promise contexts may not get precise `executionAsyncIds` by default. See the section on [promise execution tracking][]. #### async_hooks.triggerAsyncId() @@ -521,12 +521,12 @@ const server = net.createServer((conn) => { }); ``` -Note that promise contexts may not get valid triggerAsyncIds by default. See +Note that promise contexts may not get valid `triggerAsyncId`s by default. See the section on [promise execution tracking][]. ## Promise execution tracking -By default, promise executions are not assigned asyncIds due to the relatively +By default, promise executions are not assigned `asyncId`s due to the relatively expensive nature of the [promise introspection API][PromiseHooks] provided by V8. This means that programs using promises or `async`/`await` will not get correct execution and trigger ids for promise callback contexts by default. @@ -542,10 +542,10 @@ Promise.resolve(1729).then(() => { // eid 1 tid 0 ``` -Observe that the `then` callback claims to have executed in the context of the +Observe that the `then()` callback claims to have executed in the context of the outer scope even though there was an asynchronous hop involved. Also note that -the triggerAsyncId value is 0, which means that we are missing context about the -resource that caused (triggered) the `then` callback to be executed. +the `triggerAsyncId` value is `0`, which means that we are missing context about +the resource that caused (triggered) the `then()` callback to be executed. Installing async hooks via `async_hooks.createHook` enables promise execution tracking. Example: @@ -562,15 +562,16 @@ Promise.resolve(1729).then(() => { In this example, adding any actual hook function enabled the tracking of promises. There are two promises in the example above; the promise created by -`Promise.resolve()` and the promise returned by the call to `then`. In the -example above, the first promise got the asyncId 6 and the latter got asyncId 7. -During the execution of the `then` callback, we are executing in the context of -promise with asyncId 7. This promise was triggered by async resource 6. +`Promise.resolve()` and the promise returned by the call to `then()`. In the +example above, the first promise got the `asyncId` `6` and the latter got +`asyncId` `7`. During the execution of the `then()` callback, we are executing +in the context of promise with `asyncId` `7`. This promise was triggered by +async resource `6`. Another subtlety with promises is that `before` and `after` callbacks are run -only on chained promises. That means promises not created by `then`/`catch` will -not have the `before` and `after` callbacks fired on them. For more details see -the details of the V8 [PromiseHooks][] API. +only on chained promises. That means promises not created by `then()`/`catch()` +will not have the `before` and `after` callbacks fired on them. For more details +see the details of the V8 [PromiseHooks][] API. ## JavaScript Embedder API @@ -632,8 +633,9 @@ asyncResource.emitAfter(); 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 - and the sensitive API's `emitDestroy` is called with it. **Default:** `false`. + `emitDestroy` is called manually), unless the resource's `asyncId` is + retrieved and the sensitive API's `emitDestroy` is called with it. + **Default:** `false`. Example usage: diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 312b4f7c17..c219f00e4a 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -221,7 +221,7 @@ elements, and not as a byte array of the target type. That is, `[0x1020304]` or `[0x4030201]`. It is possible to create a new `Buffer` that shares the same allocated memory as -a [`TypedArray`] instance by using the TypeArray object's `.buffer` property. +a [`TypedArray`] instance by using the `TypeArray` object's `.buffer` property. ```js const arr = new Uint16Array(2); @@ -427,7 +427,8 @@ changes: run from code outside the `node_modules` directory. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12141 - description: new Buffer(size) will return zero-filled memory by default. + description: The `new Buffer(size)` will return zero-filled memory by + default. - version: v7.2.1 pr-url: https://github.com/nodejs/node/pull/9529 description: Calling this constructor no longer emits a deprecation warning. @@ -980,8 +981,8 @@ console.log(buf.toString('ascii')); ### buf.buffer -The `buffer` property references the underlying `ArrayBuffer` object based on -which this Buffer object is created. +* {ArrayBuffer} The underlying `ArrayBuffer` object based on + which this `Buffer` object is created. ```js const arrayBuffer = new ArrayBuffer(16); @@ -1507,8 +1508,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1537,8 +1538,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1566,8 +1567,8 @@ added: v0.5.0 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1596,8 +1597,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1628,8 +1629,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1660,8 +1661,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset and - byteLength to uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + and `byteLength` to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1693,8 +1694,8 @@ added: v0.5.0 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1721,8 +1722,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1755,8 +1756,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -1785,8 +1786,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset and - byteLength to uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + and `byteLength` to `uint32` anymore. --> * `offset` {integer} Number of bytes to skip before starting to read. Must @@ -2102,8 +2103,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {number} Number to be written to `buf`. @@ -2137,8 +2138,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {number} Number to be written to `buf`. @@ -2171,8 +2172,8 @@ added: v0.5.0 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2203,8 +2204,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2236,8 +2237,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2269,8 +2270,8 @@ added: v0.11.15 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset and - byteLength to uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + and `byteLength` to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2304,8 +2305,8 @@ added: v0.5.0 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2336,8 +2337,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2373,8 +2374,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset to - uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. @@ -2408,8 +2409,8 @@ added: v0.5.5 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/18395 - description: Removed noAssert and no implicit coercion of the offset and - byteLength to uint32 anymore. + description: Removed `noAssert` and no implicit coercion of the offset + and `byteLength` to `uint32` anymore. --> * `value` {integer} Number to be written to `buf`. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 47d68928e4..1fc2855e4f 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -211,7 +211,7 @@ Unlike the exec(3) POSIX system call, `child_process.exec()` does not replace the existing process and uses a shell to execute the command. If this method is invoked as its [`util.promisify()`][]ed version, it returns -a Promise for an object with `stdout` and `stderr` properties. In case of an +a `Promise` for an `Object` with `stdout` and `stderr` properties. In case of an error (including any error resulting in an exit code other than 0), a rejected promise is returned, with the same `error` object given in the callback, but with an additional two properties `stdout` and `stderr`. @@ -290,7 +290,7 @@ stderr output. If `encoding` is `'buffer'`, or an unrecognized character encoding, `Buffer` objects will be passed to the callback instead. If this method is invoked as its [`util.promisify()`][]ed version, it returns -a Promise for an object with `stdout` and `stderr` properties. In case of an +a `Promise` for an `Object` with `stdout` and `stderr` properties. In case of an error (including any error resulting in an exit code other than 0), a rejected promise is returned, with the same `error` object given in the callback, but with an additional two properties `stdout` and `stderr`. diff --git a/doc/api/cli.md b/doc/api/cli.md index 5bc673f597..6d055d9d03 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -101,25 +101,25 @@ Specify ICU data load path. (Overrides `NODE_ICU_DATA`.) added: v7.6.0 --> -Activate inspector on host:port and break at start of user script. -Default host:port is 127.0.0.1:9229. +Activate inspector on `host:port` and break at start of user script. +Default `host:port` is `127.0.0.1:9229`. ### `--inspect-port=[host:]port` <!-- YAML added: v7.6.0 --> -Set the host:port to be used when the inspector is activated. +Set the `host:port` to be used when the inspector is activated. Useful when activating the inspector by sending the `SIGUSR1` signal. -Default host is 127.0.0.1. +Default host is `127.0.0.1`. ### `--inspect[=[host:]port]` <!-- YAML added: v6.3.0 --> -Activate inspector on host:port. Default is 127.0.0.1:9229. +Activate inspector on `host:port`. Default is `127.0.0.1:9229`. V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Node.js instances. The tools attach to Node.js instances via a @@ -461,7 +461,7 @@ options property is explicitly specified for a TLS or HTTPS client or server. added: v0.11.15 --> -Data path for ICU (Intl object) data. Will extend linked-in data when compiled +Data path for ICU (`Intl` object) data. Will extend linked-in data when compiled with small-icu support. ### `NODE_NO_WARNINGS=1` diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 7c0baa36ff..b420645bb4 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -117,7 +117,7 @@ also be used for other use cases requiring worker processes. added: v0.7.0 --> -A Worker object contains all public information and method about a worker. +A `Worker` object contains all public information and method about a worker. In the master it can be obtained using `cluster.workers`. In a worker it can be obtained using `cluster.worker`. @@ -497,7 +497,7 @@ cluster.on('exit', (worker, code, signal) => { }); ``` -See [child_process event: `'exit'`][]. +See [`child_process` event: `'exit'`][]. ## Event: 'fork' <!-- YAML @@ -573,7 +573,7 @@ changes: Emitted when the cluster master receives a message from any worker. -See [child_process event: `'message'`][]. +See [`child_process` event: `'message'`][]. Before Node.js v6.0, this event emitted only the message and the handle, but not the worker object, contrary to what the documentation stated. @@ -813,10 +813,10 @@ A hash that stores the active worker objects, keyed by `id` field. Makes it easy to loop through all the workers. It is only available in the master process. -A worker is removed from cluster.workers after the worker has disconnected _and_ -exited. The order between these two events cannot be determined in advance. -However, it is guaranteed that the removal from the cluster.workers list happens -before last `'disconnect'` or `'exit'` event is emitted. +A worker is removed from `cluster.workers` after the worker has disconnected +_and_ exited. The order between these two events cannot be determined in +advance. However, it is guaranteed that the removal from the `cluster.workers` +list happens before last `'disconnect'` or `'exit'` event is emitted. ```js // Go through all workers @@ -840,12 +840,12 @@ socket.on('data', (id) => { [`ChildProcess.send()`]: child_process.html#child_process_subprocess_send_message_sendhandle_options_callback [`child_process.fork()`]: child_process.html#child_process_child_process_fork_modulepath_args_options +[`child_process` event: `'exit'`]: child_process.html#child_process_event_exit +[`child_process` event: `'message'`]: child_process.html#child_process_event_message +[`cluster.settings`]: #cluster_cluster_settings [`disconnect`]: child_process.html#child_process_subprocess_disconnect [`kill`]: process.html#process_process_kill_pid_signal [`process` event: `'message'`]: process.html#process_event_message [`server.close()`]: net.html#net_event_close [`worker.exitedAfterDisconnect`]: #cluster_worker_exitedafterdisconnect [Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options -[child_process event: `'exit'`]: child_process.html#child_process_event_exit -[child_process event: `'message'`]: child_process.html#child_process_event_message -[`cluster.settings`]: #cluster_cluster_settings diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 010251342d..dc84255386 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -282,7 +282,7 @@ add padding to the input data to the appropriate block size. To disable the default padding call `cipher.setAutoPadding(false)`. When `autoPadding` is `false`, the length of the entire input data must be a -multiple of the cipher's block size or [`cipher.final()`][] will throw an Error. +multiple of the cipher's block size or [`cipher.final()`][] will throw an error. Disabling automatic padding is useful for non-standard padding, for instance using `0x0` instead of PKCS padding. @@ -815,7 +815,7 @@ to be a string; otherwise `privateKey` is expected to be a [`Buffer`][], If `privateKey` is not valid for the curve specified when the `ECDH` object was created, an error is thrown. Upon setting the private key, the associated -public point (key) is also generated and set in the ECDH object. +public point (key) is also generated and set in the `ECDH` object. ### ecdh.setPublicKey(publicKey[, encoding]) <!-- YAML @@ -1788,7 +1788,7 @@ applied to derive a key of the requested byte length (`keylen`) from the The supplied `callback` function is called with two arguments: `err` and `derivedKey`. If an error occurs while deriving the key, `err` will be set; -otherwise `err` will be null. By default, the successfully generated +otherwise `err` will be `null`. By default, the successfully generated `derivedKey` will be passed to the callback as a [`Buffer`][]. An error will be thrown if any of the input arguments specify invalid values or types. @@ -1855,7 +1855,7 @@ implementation. A selected HMAC digest algorithm specified by `digest` is applied to derive a key of the requested byte length (`keylen`) from the `password`, `salt` and `iterations`. -If an error occurs an Error will be thrown, otherwise the derived key will be +If an error occurs an `Error` will be thrown, otherwise the derived key will be returned as a [`Buffer`][]. The `iterations` argument must be a number set as high as possible. The @@ -1987,7 +1987,7 @@ is a number indicating the number of bytes to generate. If a `callback` function is provided, the bytes are generated asynchronously and the `callback` function is invoked with two arguments: `err` and `buf`. -If an error occurs, `err` will be an Error object; otherwise it is null. The +If an error occurs, `err` will be an `Error` object; otherwise it is `null`. The `buf` argument is a [`Buffer`][] containing the generated bytes. ```js @@ -2208,7 +2208,7 @@ unified Stream API, and before there were [`Buffer`][] objects for handling binary data. As such, the many of the `crypto` defined classes have methods not typically found on other Node.js classes that implement the [streams][stream] API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted -and returned `'latin1'` encoded strings by default rather than Buffers. This +and returned `'latin1'` encoded strings by default rather than `Buffer`s. This default was changed after Node.js v0.8 to use [`Buffer`][] objects by default instead. diff --git a/doc/api/debugger.md b/doc/api/debugger.md index 51e6d98283..e7e39e5634 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -117,8 +117,8 @@ To begin watching an expression, type `watch('my_expression')`. The command * `setBreakpoint('fn()')`, `sb(...)` - Set breakpoint on a first statement in functions body * `setBreakpoint('script.js', 1)`, `sb(...)` - Set breakpoint on first line of -script.js -* `clearBreakpoint('script.js', 1)`, `cb(...)` - Clear breakpoint in script.js +`script.js` +* `clearBreakpoint('script.js', 1)`, `cb(...)` - Clear breakpoint in `script.js` on line 1 It is also possible to set a breakpoint in a file (module) that diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 5b64ca7cd3..2101f46240 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -177,16 +177,16 @@ v10.0.0 onwards. Refer: [PR 12562](https://github.com/nodejs/node/pull/12562). Type: End-of-Life -The [`fs.read()`][] legacy String interface is deprecated. Use the Buffer API as -mentioned in the documentation instead. +The [`fs.read()`][] legacy `String` interface is deprecated. Use the `Buffer` +API as mentioned in the documentation instead. <a id="DEP0015"></a> ### DEP0015: fs.readSync legacy String interface Type: End-of-Life -The [`fs.readSync()`][] legacy String interface is deprecated. Use the Buffer -API as mentioned in the documentation instead. +The [`fs.readSync()`][] legacy `String` interface is deprecated. Use the +`Buffer` API as mentioned in the documentation instead. <a id="DEP0016"></a> ### DEP0016: GLOBAL/root diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 31eeed4395..cd3e1de15a 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -57,7 +57,7 @@ added: v0.1.99 * `exception` {Error} The `'error'` event is emitted whenever any error occurs. The event handler -function is passed a single Error object. +function is passed a single `Error` object. ### Event: 'listening' <!-- YAML @@ -264,7 +264,7 @@ added: v0.1.99 changes: - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/11985 - description: The `msg` parameter can be an Uint8Array now. + description: The `msg` parameter can be an `Uint8Array` now. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/10473 description: The `address` parameter is always optional now. diff --git a/doc/api/dns.md b/doc/api/dns.md index 46d8995fe9..e8932be9e3 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -194,7 +194,7 @@ dns.lookup('example.com', options, (err, addresses) => ``` If this method is invoked as its [`util.promisify()`][]ed version, and `all` -is not set to `true`, it returns a Promise for an object with `address` and +is not set to `true`, it returns a `Promise` for an `Object` with `address` and `family` properties. ### Supported getaddrinfo flags @@ -238,7 +238,7 @@ dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { ``` If this method is invoked as its [`util.promisify()`][]ed version, it returns a -Promise for an object with `hostname` and `service` properties. +`Promise` for an `Object` with `hostname` and `service` properties. ## dns.resolve(hostname[, rrtype], callback) <!-- YAML @@ -593,8 +593,8 @@ Each DNS query can return one of the following error codes: - `dns.NONAME`: Given hostname is not numeric. - `dns.BADHINTS`: Illegal hints flags specified. - `dns.NOTINITIALIZED`: c-ares library initialization not yet performed. -- `dns.LOADIPHLPAPI`: Error loading iphlpapi.dll. -- `dns.ADDRGETNETWORKPARAMS`: Could not find GetNetworkParams function. +- `dns.LOADIPHLPAPI`: Error loading `iphlpapi.dll`. +- `dns.ADDRGETNETWORKPARAMS`: Could not find `GetNetworkParams` function. - `dns.CANCELLED`: DNS query cancelled. ## Implementation considerations diff --git a/doc/api/domain.md b/doc/api/domain.md index 4db649af78..8a0f383934 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -203,26 +203,26 @@ are added to it. <!--type=misc--> -If domains are in use, then all **new** EventEmitter objects (including +If domains are in use, then all **new** `EventEmitter` objects (including Stream objects, requests, responses, etc.) will be implicitly bound to the active domain at the time of their creation. Additionally, callbacks passed to lowlevel event loop requests (such as -to fs.open, or other callback-taking methods) will automatically be +to `fs.open()`, or other callback-taking methods) will automatically be bound to the active domain. If they throw, then the domain will catch the error. -In order to prevent excessive memory usage, Domain objects themselves +In order to prevent excessive memory usage, `Domain` objects themselves are not implicitly added as children of the active domain. If they were, then it would be too easy to prevent request and response objects from being properly garbage collected. -To nest Domain objects as children of a parent Domain they must be explicitly -added. +To nest `Domain` objects as children of a parent `Domain` they must be +explicitly added. Implicit binding routes thrown errors and `'error'` events to the -Domain's `'error'` event, but does not register the EventEmitter on the -Domain. +`Domain`'s `'error'` event, but does not register the `EventEmitter` on the +`Domain`. Implicit binding only takes care of thrown errors and `'error'` events. ## Explicit Binding @@ -271,14 +271,12 @@ serverDomain.run(() => { * Returns: {Domain} -Returns a new Domain object. - ## Class: Domain -The Domain class encapsulates the functionality of routing errors and -uncaught exceptions to the active 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 @@ -301,7 +299,7 @@ This also works with timers that are returned from [`setInterval()`][] and [`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 +If the Timer or `EventEmitter` was already bound to a domain, it is removed from that one, and bound to this one instead. ### domain.bind(callback) @@ -444,7 +442,7 @@ than crashing the program. ## Domains and Promises As of Node.js 8.0.0, the handlers of Promises are run inside the domain in -which the call to `.then` or `.catch` itself was made: +which the call to `.then()` or `.catch()` itself was made: ```js const d1 = domain.create(); @@ -481,7 +479,7 @@ d2.run(() => { ``` Note that domains will not interfere with the error handling mechanisms for -Promises, i.e. no `'error'` event will be emitted for unhandled Promise +Promises, i.e. no `'error'` event will be emitted for unhandled `Promise` rejections. [`Error`]: errors.html#errors_class_error diff --git a/doc/api/errors.md b/doc/api/errors.md index c34559303c..99c830b895 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -18,7 +18,7 @@ errors: as attempting to open a file that does not exist, attempting to send data over a closed socket, etc; - And User-specified errors triggered by application code. -- Assertion Errors are a special class of error that can be triggered whenever +- `AssertionError`s are a special class of error that can be triggered whenever Node.js detects an exceptional logic violation that should never occur. These are raised typically by the `assert` module. @@ -32,7 +32,7 @@ to provide *at least* the properties available on that class. Node.js supports several mechanisms for propagating and handling errors that occur while an application is running. How these errors are reported and -handled depends entirely on the type of Error and the style of the API that is +handled depends entirely on the type of `Error` and the style of the API that is called. All JavaScript errors are handled as exceptions that *immediately* generate @@ -137,7 +137,7 @@ 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 -the Error object (if any) passed as the first argument. If no error was +the `Error` object (if any) passed as the first argument. If no error was raised, the first argument will be passed as `null`. ```js @@ -422,7 +422,7 @@ they may only be caught by other contexts. A subclass of `Error` that indicates that a provided argument is not an allowable type. For example, passing a function to a parameter which expects a -string would be considered a TypeError. +string would be considered a `TypeError`. ```js require('url').parse(() => { }); @@ -440,7 +440,7 @@ A JavaScript exception is a value that is thrown as a result of an invalid operation or as the target of a `throw` statement. While it is not required that these values are instances of `Error` or classes which inherit from `Error`, all exceptions thrown by Node.js or the JavaScript runtime *will* be -instances of Error. +instances of `Error`. Some exceptions are *unrecoverable* at the JavaScript layer. Such exceptions will *always* cause the Node.js process to crash. Examples include `assert()` @@ -492,7 +492,7 @@ typically `E` followed by a sequence of capital letters. The `error.errno` property is a number or a string. The number is a **negative** value which corresponds to the error code defined -in [`libuv Error handling`]. See uv-errno.h header file +in [`libuv Error handling`]. See `uv-errno.h` header file (`deps/uv/include/uv-errno.h` in the Node.js source tree) for details. In case of a string, it is the same as `error.code`. @@ -1081,7 +1081,7 @@ An invalid or unsupported value was passed for a given argument. <a id="ERR_INVALID_ARRAY_LENGTH"></a> ### ERR_INVALID_ARRAY_LENGTH -An Array was not of the expected length or in a valid range. +An array was not of the expected length or in a valid range. <a id="ERR_INVALID_ASYNC_ID"></a> ### ERR_INVALID_ASYNC_ID @@ -1515,7 +1515,7 @@ length. ### ERR_TLS_CERT_ALTNAME_INVALID While using TLS, the hostname/IP of the peer did not match any of the -subjectAltNames in its certificate. +`subjectAltNames` in its certificate. <a id="ERR_TLS_DH_PARAM_SIZE"></a> ### ERR_TLS_DH_PARAM_SIZE @@ -1569,12 +1569,12 @@ the `--without-v8-platform` flag. <a id="ERR_TRANSFORM_ALREADY_TRANSFORMING"></a> ### ERR_TRANSFORM_ALREADY_TRANSFORMING -A Transform stream finished while it was still transforming. +A `Transform` stream finished while it was still transforming. <a id="ERR_TRANSFORM_WITH_LENGTH_0"></a> ### ERR_TRANSFORM_WITH_LENGTH_0 -A Transform stream finished with data still in the write buffer. +A `Transform` stream finished with data still in the write buffer. <a id="ERR_TTY_INIT_FAILED"></a> ### ERR_TTY_INIT_FAILED @@ -1649,7 +1649,7 @@ itself, although it is possible for user code to trigger it. <a id="ERR_V8BREAKITERATOR"></a> ### ERR_V8BREAKITERATOR -The V8 BreakIterator API was used but the full ICU data set is not installed. +The V8 `BreakIterator` API was used but the full ICU data set is not installed. <a id="ERR_VALID_PERFORMANCE_ENTRY_TYPE"></a> ### ERR_VALID_PERFORMANCE_ENTRY_TYPE diff --git a/doc/api/esm.md b/doc/api/esm.md index 4090e545fd..a1e3cb149a 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -134,8 +134,8 @@ export async function resolve(specifier, } ``` -The parentURL is provided as `undefined` when performing main Node.js load -itself. +The `parentModuleURL` is provided as `undefined` when performing main Node.js +load itself. The default Node.js ES module resolution function is provided as a third argument to the resolver for easy compatibility workflows. diff --git a/doc/api/events.md b/doc/api/events.md index e5ae1e3fe7..536a87d1b4 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -8,7 +8,7 @@ Much of the Node.js core API is built around an idiomatic asynchronous event-driven architecture in which certain kinds of objects (called "emitters") -periodically emit named events that cause Function objects ("listeners") to be +periodically emit named events that cause `Function` objects ("listeners") to be called. For instance: a [`net.Server`][] object emits an event each time a peer @@ -167,7 +167,7 @@ The `EventEmitter` class is defined and exposed by the `events` module: const EventEmitter = require('events'); ``` -All EventEmitters emit the event `'newListener'` when new listeners are +All `EventEmitter`s emit the event `'newListener'` when new listeners are added and `'removeListener'` when existing listeners are removed. ### Event: 'newListener' @@ -314,7 +314,7 @@ added: v6.0.0 - Returns: {Array} Returns an array listing the events for which the emitter has registered -listeners. The values in the array will be strings or Symbols. +listeners. The values in the array will be strings or `Symbol`s. ```js const EventEmitter = require('events'); @@ -589,7 +589,7 @@ added: v0.3.5 - `n` {integer} - Returns: {EventEmitter} -By default EventEmitters will print a warning if more than `10` listeners are +By default `EventEmitter`s will print a warning if more than `10` listeners are added for a particular event. This is a useful default that helps finding memory leaks. Obviously, not all events should be limited to just 10 listeners. The `emitter.setMaxListeners()` method allows the limit to be modified for this diff --git a/doc/api/fs.md b/doc/api/fs.md index 6e3628c8fb..8ac0cf4833 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -177,7 +177,7 @@ Using WHATWG [`URL`][] objects might introduce platform-specific behaviors. On Windows, `file:` URLs with a hostname convert to UNC paths, while `file:` URLs with drive letters convert to local absolute paths. `file:` URLs without a -hostname nor a drive letter will result in a throw : +hostname nor a drive letter will result in a throw: ```js // On Windows : @@ -1730,7 +1730,7 @@ fs.ftruncate(fd, 4, (err) => { ``` If the file previously was shorter than `len` bytes, it is extended, and the -extended part is filled with null bytes ('\0'). For example, +extended part is filled with null bytes (`'\0'`). For example, ```js console.log(fs.readFileSync('temp.txt', 'utf8')); @@ -1748,7 +1748,7 @@ fs.ftruncate(fd, 10, (err) => { // ('Node.js\0\0\0' in UTF8) ``` -The last three bytes are null bytes ('\0'), to compensate the over-truncation. +The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. ## fs.ftruncateSync(fd[, len]) <!-- YAML @@ -2189,7 +2189,7 @@ If `position` is an integer, the file position will remain unchanged. The callback is given the three arguments, `(err, bytesRead, buffer)`. If this method is invoked as its [`util.promisify()`][]ed version, it returns -a Promise for an object with `bytesRead` and `buffer` properties. +a `Promise` for an `Object` with `bytesRead` and `buffer` properties. ## fs.readdir(path[, options], callback) <!-- YAML @@ -2943,7 +2943,7 @@ The `atime` and `mtime` arguments follow these rules: - Values can be either numbers representing Unix epoch time, `Date`s, or a numeric string like `'123456789.0'`. - If the value can not be converted to a number, or is `NaN`, `Infinity` or - `-Infinity`, a `Error` will be thrown. + `-Infinity`, an `Error` will be thrown. ## fs.utimesSync(path, atime, mtime) <!-- YAML @@ -3067,7 +3067,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 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. +always provided in the callback, and have some fallback logic if it is `null`. ```js fs.watch('somedir', (eventType, filename) => { @@ -3185,7 +3185,7 @@ The callback will be given three arguments `(err, bytesWritten, buffer)` where `bytesWritten` specifies how many _bytes_ were written from `buffer`. If this method is invoked as its [`util.promisify()`][]ed version, it returns -a Promise for an object with `bytesWritten` and `buffer` properties. +a `Promise` for an `Object` with `bytesWritten` and `buffer` properties. Note that it is unsafe to use `fs.write` multiple times on the same file without waiting for the callback. For this scenario, @@ -3561,7 +3561,7 @@ doTruncate().catch(console.error); ``` If the file previously was shorter than `len` bytes, it is extended, and the -extended part is filled with null bytes ('\0'). For example, +extended part is filled with null bytes (`'\0'`). For example, ```js console.log(fs.readFileSync('temp.txt', 'utf8')); @@ -3576,14 +3576,14 @@ async function doTruncate() { doTruncate().catch(console.error); ``` -The last three bytes are null bytes ('\0'), to compensate the over-truncation. +The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. #### filehandle.utimes(atime, mtime) <!-- YAML added: v10.0.0 --> * `atime` {number|string|Date} -* `mtime` {number|string|Date}` +* `mtime` {number|string|Date} * Returns: {Promise} Change the file system timestamps of the object referenced by the `FileHandle` @@ -3878,7 +3878,7 @@ doTruncate().catch(console.error); ``` If the file previously was shorter than `len` bytes, it is extended, and the -extended part is filled with null bytes ('\0'). For example, +extended part is filled with null bytes (`'\0'`). For example, ```js console.log(fs.readFileSync('temp.txt', 'utf8')); @@ -3893,7 +3893,7 @@ async function doTruncate() { doTruncate().catch(console.error); ``` -The last three bytes are null bytes ('\0'), to compensate the over-truncation. +The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. ### fsPromises.futimes(filehandle, atime, mtime) <!-- YAML @@ -3902,7 +3902,7 @@ added: v10.0.0 * `filehandle` {FileHandle} * `atime` {number|string|Date} -* `mtime` {number|string|Date}` +* `mtime` {number|string|Date} * Returns: {Promise} Change the file system timestamps of the object referenced by the supplied @@ -4599,7 +4599,7 @@ The file is created (if it does not exist) or truncated (if it exists). `flag` can also be a number as documented by open(2); commonly used constants 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. +or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by `CreateFileW`. 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 diff --git a/doc/api/http.md b/doc/api/http.md index 61ef6edfd2..713edd0218 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -71,7 +71,7 @@ the requests to that server, but each one will occur over a new connection. When a connection is closed by the client or the server, it is removed from the pool. Any unused sockets in the pool will be unrefed so as not to keep the Node.js process running when there are no outstanding requests. -(see [socket.unref()]). +(see [`socket.unref()`]). It is good practice, to [`destroy()`][] an `Agent` instance when it is no longer in use, because unused sockets consume OS resources. @@ -167,7 +167,7 @@ added: v8.1.0 * `socket` {net.Socket} Called when `socket` is detached from a request and could be persisted by the -Agent. Default behavior is to: +`Agent`. Default behavior is to: ```js socket.setKeepAlive(true, this.keepAliveMsecs); @@ -257,7 +257,7 @@ added: v0.3.6 * {number} -By default set to Infinity. Determines how many concurrent sockets the agent +By default set to `Infinity`. Determines how many concurrent sockets the agent can have open per origin. Origin is the returned value of [`agent.getName()`][]. ### agent.requests @@ -790,7 +790,7 @@ changes: for `'clientError'`. - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/17672 - description: The rawPacket is the current buffer that just parsed. Adding + description: The `rawPacket` is the current buffer that just parsed. Adding this buffer to the error object of `'clientError'` event is to make it possible that developers can log the broken packet. --> @@ -924,10 +924,7 @@ This method is identical to [`server.listen()`][] from [`net.Server`][]. added: v5.7.0 --> -* {boolean} - -A Boolean indicating whether or not the server is listening for -connections. +* {boolean} Indicates whether or not the server is listening for connections. ### server.maxHeadersCount <!-- YAML @@ -1761,11 +1758,11 @@ changes: description: The `options` argument is supported now. --> - `options` {Object} - * `IncomingMessage` {http.IncomingMessage} Specifies the IncomingMessage class - to be used. Useful for extending the original `IncomingMessage`. + * `IncomingMessage` {http.IncomingMessage} Specifies the `IncomingMessage` + class 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`. **Default:** + * `ServerResponse` {http.ServerResponse} Specifies the `ServerResponse` class + to be used. Useful for extending the original `ServerResponse`. **Default:** `ServerResponse`. - `requestListener` {Function} @@ -1868,8 +1865,8 @@ changes: v6 will be used. * `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). + * `socketPath` {string} Unix Domain Socket (use one of `host:port` or + `socketPath`). * `method` {string} A string specifying the HTTP request method. **Default:** `'GET'`. * `path` {string} Request path. Should include query string if any. @@ -2073,7 +2070,7 @@ not abort the request or do anything besides add a `'timeout'` event. [`socket.setKeepAlive()`]: net.html#net_socket_setkeepalive_enable_initialdelay [`socket.setNoDelay()`]: net.html#net_socket_setnodelay_nodelay [`socket.setTimeout()`]: net.html#net_socket_settimeout_timeout_callback +[`socket.unref()`]: net.html#net_socket_unref [`url.parse()`]: url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost [Readable Stream]: stream.html#stream_class_stream_readable [Writable Stream]: stream.html#stream_class_stream_writable -[socket.unref()]: net.html#net_socket_unref diff --git a/doc/api/http2.md b/doc/api/http2.md index b3aac4741e..566cdc065e 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -108,7 +108,7 @@ have occasion to work with the `Http2Session` object directly, with most actions typically taken through interactions with either the `Http2Server` or `Http2Stream` objects. -#### Http2Session and Sockets +#### `Http2Session` and Sockets Every `Http2Session` instance is associated with exactly one [`net.Socket`][] or [`tls.TLSSocket`][] when it is created. When either the `Socket` or the @@ -410,7 +410,7 @@ added: v9.4.0 * {string[]|undefined} If the `Http2Session` is connected to a `TLSSocket`, the `originSet` property -will return an Array of origins for which the `Http2Session` may be +will return an `Array` of origins for which the `Http2Session` may be considered authoritative. #### http2session.pendingSettingsAck @@ -500,12 +500,12 @@ added: v8.4.0 * {net.Socket|tls.TLSSocket} -Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but +Returns a `Proxy` object that acts as a `net.Socket` (or `tls.TLSSocket`) but limits available methods to ones safe to use with HTTP/2. `destroy`, `emit`, `end`, `pause`, `read`, `resume`, and `write` will throw an error with code `ERR_HTTP2_NO_SOCKET_MANIPULATION`. See -[Http2Session and Sockets][] for more information. +[`Http2Session` and Sockets][] for more information. `setTimeout` method will be called on this `Http2Session`. @@ -592,8 +592,9 @@ added: v9.4.0 * `alt` {string} A description of the alternative service configuration as defined by [RFC 7838][]. * `originOrStream` {number|string|URL|Object} Either a URL string specifying - the origin (or an Object with an `origin` property) or the numeric identifier - of an active `Http2Stream` as given by the `http2stream.id` property. + the origin (or an `Object` with an `origin` property) or the numeric + identifier of an active `Http2Stream` as given by the `http2stream.id` + property. Submits an `ALTSVC` frame (as defined by [RFC 7838][]) to the connected client. @@ -1041,7 +1042,7 @@ Provides miscellaneous information about the current state of the * `localWindowSize` {number} The number of bytes the connected peer may send for this `Http2Stream` without receiving a `WINDOW_UPDATE`. * `state` {number} A flag indicating the low-level current state of the - `Http2Stream` as determined by nghttp2. + `Http2Stream` as determined by `nghttp2`. * `localClose` {number} `true` if this `Http2Stream` has been closed locally. * `remoteClose` {number} `true` if this `Http2Stream` has been closed remotely. @@ -1140,7 +1141,7 @@ added: v8.4.0 The `'response'` event is emitted when a response `HEADERS` frame has been received for this stream from the connected HTTP/2 server. The listener is -invoked with two arguments: an Object containing the received +invoked with two arguments: an `Object` containing the received [HTTP/2 Headers Object][], and flags associated with the headers. ```js @@ -1180,7 +1181,7 @@ added: v8.4.0 * {boolean} -Boolean (read-only). True if headers were sent, false otherwise. +True if headers were sent, false otherwise (read-only). #### http2stream.pushAllowed <!-- YAML @@ -1210,8 +1211,8 @@ added: v8.4.0 * `callback` {Function} Callback that is called once the push stream has been initiated. * `err` {Error} - * `pushStream` {ServerHttp2Stream} The returned pushStream object. - * `headers` {HTTP/2 Headers Object} Headers object the pushStream was + * `pushStream` {ServerHttp2Stream} The returned `pushStream` object. + * `headers` {HTTP/2 Headers Object} Headers object the `pushStream` was initiated with. Initiates a push stream. The callback is invoked with the new `Http2Stream` @@ -1303,7 +1304,7 @@ validation is performed on the given file descriptor. If an error occurs while attempting to read data using the file descriptor, the `Http2Stream` will be closed using an `RST_STREAM` frame using the standard `INTERNAL_ERROR` code. -When used, the `Http2Stream` object's Duplex interface will be closed +When used, the `Http2Stream` object's `Duplex` interface will be closed automatically. ```js @@ -1389,7 +1390,7 @@ changes: * `options` {Object} * `statCheck` {Function} * `onError` {Function} Callback function invoked in the case of an - Error before send. + error before send. * `waitForTrailers` {boolean} When `true`, the `Http2Stream` will emit the `'wantTrailers'` event after the final `DATA` frame has been sent. * `offset` {number} The offset position at which to begin reading. @@ -1398,7 +1399,7 @@ changes: Sends a regular file as the response. The `path` must specify a regular file or an `'error'` event will be emitted on the `Http2Stream` object. -When used, the `Http2Stream` object's Duplex interface will be closed +When used, the `Http2Stream` object's `Duplex` interface will be closed automatically. The optional `options.statCheck` function may be specified to give user code @@ -1773,8 +1774,8 @@ changes: amount of padding, as determined by the internal implementation, is to be applied. * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user - provided `options.selectPadding` callback is to be used to determine the - amount of padding. + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply enough padding to ensure that the total frame length, including the 9-byte header, is a multiple of 8. For each frame, however, there is a @@ -1788,21 +1789,21 @@ changes: `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][]. + used to determine the padding. See [Using `options.selectPadding()`][]. * `settings` {HTTP/2 Settings Object} The initial settings to send to the 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`. - * `Http1ServerResponse` {http.ServerResponse} Specifies the ServerResponse + * `Http1IncomingMessage` {http.IncomingMessage} Specifies the + `IncomingMessage` class to used for HTTP/1 fallback. Useful for extending + the original `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`. * `Http2ServerRequest` {http2.Http2ServerRequest} Specifies the - Http2ServerRequest class to use. + `Http2ServerRequest` class to use. Useful for extending the original `Http2ServerRequest`. **Default:** `Http2ServerRequest`. * `Http2ServerResponse` {http2.Http2ServerResponse} Specifies the - Http2ServerResponse class to use. + `Http2ServerResponse` class to use. Useful for extending the original `Http2ServerResponse`. **Default:** `Http2ServerResponse`. * `onRequestHandler` {Function} See [Compatibility API][] @@ -1883,8 +1884,8 @@ changes: amount of padding, as determined by the internal implementation, is to be applied. * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user - provided `options.selectPadding` callback is to be used to determine the - amount of padding. + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply enough padding to ensure that the total frame length, including the 9-byte header, is a multiple of 8. For each frame, however, there is a @@ -1898,7 +1899,7 @@ changes: `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][]. + used to determine the padding. See [Using `options.selectPadding()`][]. * `settings` {HTTP/2 Settings Object} The initial settings to send to the remote peer upon connection. * ...: Any [`tls.createServer()`][] options can be provided. For @@ -1979,8 +1980,8 @@ changes: amount of padding, as determined by the internal implementation, is to be applied. * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user - provided `options.selectPadding` callback is to be used to determine the - amount of padding. + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply enough padding to ensure that the total frame length, including the 9-byte header, is a multiple of 8. For each frame, however, there is a @@ -1994,7 +1995,7 @@ changes: `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][]. + used to determine the padding. See [Using `options.selectPadding()`][]. * `settings` {HTTP/2 Settings Object} The initial settings to send to the remote peer upon connection. * `createConnection` {Function} An optional callback that receives the `URL` @@ -2023,22 +2024,22 @@ added: v8.4.0 #### Error Codes for RST_STREAM and GOAWAY <a id="error_codes"></a> -| Value | Name | Constant | -|-------|---------------------|-----------------------------------------------| -| 0x00 | No Error | `http2.constants.NGHTTP2_NO_ERROR` | -| 0x01 | Protocol Error | `http2.constants.NGHTTP2_PROTOCOL_ERROR` | -| 0x02 | Internal Error | `http2.constants.NGHTTP2_INTERNAL_ERROR` | -| 0x03 | Flow Control Error | `http2.constants.NGHTTP2_FLOW_CONTROL_ERROR` | -| 0x04 | Settings Timeout | `http2.constants.NGHTTP2_SETTINGS_TIMEOUT` | -| 0x05 | Stream Closed | `http2.constants.NGHTTP2_STREAM_CLOSED` | -| 0x06 | Frame Size Error | `http2.constants.NGHTTP2_FRAME_SIZE_ERROR` | -| 0x07 | Refused Stream | `http2.constants.NGHTTP2_REFUSED_STREAM` | -| 0x08 | Cancel | `http2.constants.NGHTTP2_CANCEL` | -| 0x09 | Compression Error | `http2.constants.NGHTTP2_COMPRESSION_ERROR` | -| 0x0a | Connect Error | `http2.constants.NGHTTP2_CONNECT_ERROR` | -| 0x0b | Enhance Your Calm | `http2.constants.NGHTTP2_ENHANCE_YOUR_CALM` | -| 0x0c | Inadequate Security | `http2.constants.NGHTTP2_INADEQUATE_SECURITY` | -| 0x0d | HTTP/1.1 Required | `http2.constants.NGHTTP2_HTTP_1_1_REQUIRED` | +| Value | Name | Constant | +|--------|---------------------|-----------------------------------------------| +| `0x00` | No Error | `http2.constants.NGHTTP2_NO_ERROR` | +| `0x01` | Protocol Error | `http2.constants.NGHTTP2_PROTOCOL_ERROR` | +| `0x02` | Internal Error | `http2.constants.NGHTTP2_INTERNAL_ERROR` | +| `0x03` | Flow Control Error | `http2.constants.NGHTTP2_FLOW_CONTROL_ERROR` | +| `0x04` | Settings Timeout | `http2.constants.NGHTTP2_SETTINGS_TIMEOUT` | +| `0x05` | Stream Closed | `http2.constants.NGHTTP2_STREAM_CLOSED` | +| `0x06` | Frame Size Error | `http2.constants.NGHTTP2_FRAME_SIZE_ERROR` | +| `0x07` | Refused Stream | `http2.constants.NGHTTP2_REFUSED_STREAM` | +| `0x08` | Cancel | `http2.constants.NGHTTP2_CANCEL` | +| `0x09` | Compression Error | `http2.constants.NGHTTP2_COMPRESSION_ERROR` | +| `0x0a` | Connect Error | `http2.constants.NGHTTP2_CONNECT_ERROR` | +| `0x0b` | Enhance Your Calm | `http2.constants.NGHTTP2_ENHANCE_YOUR_CALM` | +| `0x0c` | Inadequate Security | `http2.constants.NGHTTP2_INADEQUATE_SECURITY` | +| `0x0d` | HTTP/1.1 Required | `http2.constants.NGHTTP2_HTTP_1_1_REQUIRED` | The `'timeout'` event is emitted when there is no activity on the Server for a given number of milliseconds set using `http2server.setTimeout()`. @@ -2090,7 +2091,7 @@ the given `Buffer` as generated by `http2.getPackedSettings()`. Headers are represented as own-properties on JavaScript objects. The property keys will be serialized to lower-case. Property values should be strings (if -they are not they will be coerced to strings) or an Array of strings (in order +they are not they will be coerced to strings) or an `Array` of strings (in order to send more than one value per header field). ```js @@ -2155,14 +2156,14 @@ properties. All additional properties on the settings object are ignored. -### Using `options.selectPadding` +### Using `options.selectPadding()` When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, the HTTP/2 implementation will -consult the `options.selectPadding` callback function, if provided, to determine -the specific amount of padding to use per `HEADERS` and `DATA` frame. +consult the `options.selectPadding()` callback function, if provided, to +determine the specific amount of padding to use per `HEADERS` and `DATA` frame. -The `options.selectPadding` function receives two numeric arguments, +The `options.selectPadding()` function receives two numeric arguments, `frameLen` and `maxFrameLen` and must return a number `N` such that `frameLen <= N <= maxFrameLen`. @@ -2176,7 +2177,7 @@ const server = http2.createServer({ }); ``` -The `options.selectPadding` function is invoked once for *every* `HEADERS` and +The `options.selectPadding()` function is invoked once for *every* `HEADERS` and `DATA` frame. This has a definite noticeable impact on performance. ### Error Handling @@ -2184,19 +2185,19 @@ The `options.selectPadding` function is invoked once for *every* `HEADERS` and There are several types of error conditions that may arise when using the `http2` module: -Validation Errors occur when an incorrect argument, option, or setting value is +Validation errors occur when an incorrect argument, option, or setting value is passed in. These will always be reported by a synchronous `throw`. -State Errors occur when an action is attempted at an incorrect time (for +State errors occur when an action is attempted at an incorrect time (for instance, attempting to send data on a stream after it has closed). These will be reported using either a synchronous `throw` or via an `'error'` event on the `Http2Stream`, `Http2Session` or HTTP/2 Server objects, depending on where and when the error occurs. -Internal Errors occur when an HTTP/2 session fails unexpectedly. These will be +Internal errors occur when an HTTP/2 session fails unexpectedly. These will be reported via an `'error'` event on the `Http2Session` or HTTP/2 Server objects. -Protocol Errors occur when various HTTP/2 protocol constraints are violated. +Protocol errors occur when various HTTP/2 protocol constraints are violated. These will be reported using either a synchronous `throw` or via an `'error'` event on the `Http2Stream`, `Http2Session` or HTTP/2 Server objects, depending on where and when the error occurs. @@ -2563,7 +2564,7 @@ added: v8.4.0 * {net.Socket|tls.TLSSocket} -Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but +Returns a `Proxy` object that acts as a `net.Socket` (or `tls.TLSSocket`) but applies getters, setters, and methods based on HTTP/2 logic. `destroyed`, `readable`, and `writable` properties will be retrieved from and @@ -2575,7 +2576,7 @@ set on `request.stream`. `setTimeout` method will be called on `request.stream.session`. `pause`, `read`, `resume`, and `write` will throw an error with code -`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [Http2Session and Sockets][] for +`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [`Http2Session` and Sockets][] for more information. All other interactions will be routed directly to the socket. With TLS support, @@ -2843,7 +2844,7 @@ added: v8.4.0 * {boolean} -Boolean (read-only). True if headers were sent, false otherwise. +True if headers were sent, false otherwise (read-only). #### response.removeHeader(name) <!-- YAML @@ -2939,7 +2940,7 @@ added: v8.4.0 * {net.Socket|tls.TLSSocket} -Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but +Returns a `Proxy` object that acts as a `net.Socket` (or `tls.TLSSocket`) but applies getters, setters, and methods based on HTTP/2 logic. `destroyed`, `readable`, and `writable` properties will be retrieved from and @@ -2951,7 +2952,7 @@ set on `response.stream`. `setTimeout` method will be called on `response.stream.session`. `pause`, `read`, `resume`, and `write` will throw an error with code -`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [Http2Session and Sockets][] for +`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [`Http2Session` and Sockets][] for more information. All other interactions will be routed directly to the socket. @@ -3189,11 +3190,10 @@ following additional properties: [HTTP/2 Headers Object]: #http2_headers_object [HTTP/2 Settings Object]: #http2_settings_object [HTTPS]: https.html -[Http2Session and Sockets]: #http2_http2session_and_sockets [Performance Observer]: perf_hooks.html [Readable Stream]: stream.html#stream_class_stream_readable [RFC 7838]: https://tools.ietf.org/html/rfc7838 -[Using options.selectPadding]: #http2_using_options_selectpadding +[Using `options.selectPadding()`]: #http2_using_options_selectpadding [Writable Stream]: stream.html#stream_writable_streams [`'checkContinue'`]: #http2_event_checkcontinue [`'request'`]: #http2_event_request @@ -3202,6 +3202,7 @@ following additional properties: [`Duplex`]: stream.html#stream_class_stream_duplex [`EventEmitter`]: events.html#events_class_eventemitter [`Http2ServerRequest`]: #http2_class_http2_http2serverrequest +[`Http2Session` and Sockets]: #http2_http2session_and_sockets [`Http2Stream`]: #http2_class_http2stream [`ServerHttp2Stream`]: #http2_class_serverhttp2stream [`TypeError`]: errors.html#errors_class_typeerror diff --git a/doc/api/intl.md b/doc/api/intl.md index 9fa4d438fa..fe5c4ef9d0 100644 --- a/doc/api/intl.md +++ b/doc/api/intl.md @@ -20,7 +20,7 @@ programs. Some of them are: - [`require('buffer').transcode()`][] - More accurate [REPL][] line editing - [`require('util').TextDecoder`][] -- [RegExp Unicode Property Escapes][] +- [`RegExp` Unicode Property Escapes][] Node.js (and its underlying V8 engine) uses [ICU][] to implement these features in native C/C++ code. However, some of them require a very large ICU data file @@ -57,7 +57,7 @@ option: | [`require('buffer').transcode()`][] | none (function does not exist) | full | full | full | | [REPL][] | partial (inaccurate line editing) | full | full | full | | [`require('util').TextDecoder`][] | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full | -| [RegExp Unicode Property Escapes][] | none (invalid RegExp error) | full | full | full | +| [`RegExp` Unicode Property Escapes][] | none (invalid `RegExp` error) | full | full | full | The "(not locale-aware)" designation denotes that the function carries out its operation just like the non-`Locale` version of the function, if one @@ -198,6 +198,7 @@ to be helpful: [`Intl.DateTimeFormat`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat [`NODE_ICU_DATA`]: cli.html#cli_node_icu_data_file [`Number.prototype.toLocaleString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString +[`RegExp` Unicode Property Escapes]: https://github.com/tc39/proposal-regexp-unicode-property-escapes [`require('buffer').transcode()`]: buffer.html#buffer_buffer_transcode_source_fromenc_toenc [`require('util').TextDecoder`]: util.html#util_class_util_textdecoder [`String.prototype.localeCompare()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare @@ -210,7 +211,6 @@ to be helpful: [ECMA-402]: https://tc39.github.io/ecma402/ [ICU]: http://icu-project.org/ [REPL]: repl.html#repl_repl -[RegExp Unicode Property Escapes]: https://github.com/tc39/proposal-regexp-unicode-property-escapes [Test262]: https://github.com/tc39/test262/tree/master/test/intl402 [WHATWG URL parser]: url.html#url_the_whatwg_url_api [btest402]: https://github.com/srl295/btest402 diff --git a/doc/api/modules.md b/doc/api/modules.md index 5204a0ca61..c9b83859d9 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -322,7 +322,7 @@ A required module prefixed with `'./'` is relative to the file calling `require()`. That is, `circle.js` must be in the same directory as `foo.js` for `require('./circle')` to find it. -Without a leading '/', './', or '../' to indicate a file, the module must +Without a leading `'/'`, `'./'`, or `'../'` to indicate a file, the module must either be a core module or is loaded from a `node_modules` folder. If the given path does not exist, `require()` will throw an [`Error`][] with its @@ -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 @@ -350,7 +350,7 @@ If this was in a folder at `./some-library`, then `require('./some-library')` would attempt to load `./some-library/lib/some-library.js`. -This is the extent of Node.js's awareness of package.json files. +This is the extent of Node.js's awareness of `package.json` files. 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 @@ -360,9 +360,9 @@ default error: Error: Cannot find module 'some-library' ``` -If there is no package.json file present in the directory, then Node.js +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` @@ -563,7 +563,7 @@ added: v0.3.0 Modules are cached in this object when they are required. By deleting a key value from this object, the next `require` will reload the module. Note that this does not apply to [native addons][], for which reloading will result in an -Error. +error. #### require.extensions <!-- YAML @@ -700,7 +700,7 @@ added: v0.1.16 * {Object} -The `module.exports` object is created by the Module system. Sometimes this is +The `module.exports` object is created by the `Module` system. Sometimes this is not acceptable; many want their module to be an instance of some class. To do this, assign the desired export object to `module.exports`. Note that assigning the desired object to `exports` will simply rebind the local `exports` variable, @@ -725,14 +725,14 @@ Then in another file we could do: ```js const a = require('./a'); a.on('ready', () => { - console.log('module a is ready'); + console.log('module "a" is ready'); }); ``` Note that assignment to `module.exports` must be done immediately. It cannot be done in any callbacks. This does not work: -x.js: +`x.js`: ```js setTimeout(() => { @@ -740,7 +740,7 @@ setTimeout(() => { }, 0); ``` -y.js: +`y.js`: ```js const x = require('./x'); @@ -828,7 +828,7 @@ loading. added: v0.1.16 --> -* {Object} Module object +* {module} The module that first required this one. diff --git a/doc/api/n-api.md b/doc/api/n-api.md index fcbd4decb3..3ba902f1df 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -43,7 +43,7 @@ part of N-API, nor will they be maintained as part of Node.js. One such example is: [node-api](https://github.com/nodejs/node-api). In order to use the N-API functions, include the file -[node_api.h](https://github.com/nodejs/node/blob/master/src/node_api.h) +[`node_api.h`](https://github.com/nodejs/node/blob/master/src/node_api.h) which is located in the src directory in the node development tree: ```C @@ -434,7 +434,7 @@ NODE_EXTERN napi_status napi_create_error(napi_env env, ``` - `[in] env`: The environment that the API is invoked under. - `[in] code`: Optional `napi_value` with the string for the error code to - be associated with the error. +be associated with the error. - `[in] msg`: `napi_value` that references a JavaScript `String` to be used as the message for the `Error`. - `[out] result`: `napi_value` representing the error created. @@ -455,7 +455,7 @@ NODE_EXTERN napi_status napi_create_type_error(napi_env env, ``` - `[in] env`: The environment that the API is invoked under. - `[in] code`: Optional `napi_value` with the string for the error code to - be associated with the error. +be associated with the error. - `[in] msg`: `napi_value` that references a JavaScript `String` to be used as the message for the `Error`. - `[out] result`: `napi_value` representing the error created. @@ -476,7 +476,7 @@ NODE_EXTERN napi_status napi_create_range_error(napi_env env, ``` - `[in] env`: The environment that the API is invoked under. - `[in] code`: Optional `napi_value` with the string for the error code to - be associated with the error. +be associated with the error. - `[in] msg`: `napi_value` that references a JavaScript `String` to be used as the message for the `Error`. - `[out] result`: `napi_value` representing the error created. @@ -1275,7 +1275,7 @@ This API allocates a `node::Buffer` object and initializes it with data backed by the passed in buffer. While this is still a fully-supported data structure, in most cases using a `TypedArray` will suffice. -For Node.js >=4 `Buffers` are Uint8Arrays. +For Node.js >=4 `Buffers` are `Uint8Array`s. #### napi_create_function <!-- YAML @@ -1293,7 +1293,7 @@ napi_status napi_create_function(napi_env env, - `[in] env`: The environment that the API is invoked under. - `[in] utf8name`: A string representing the name of the function encoded as UTF8. -- `[in] length`: The length of the utf8name in bytes, or +- `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. - `[in] cb`: A function pointer to the native function to be invoked when the created function is invoked from JavaScript. @@ -1306,7 +1306,7 @@ Returns `napi_ok` if the API succeeded. This API returns an N-API value corresponding to a JavaScript `Function` object. It's used to wrap native functions so that they can be invoked from JavaScript. -JavaScript Functions are described in +JavaScript `Function`s are described in [Section 19.2](https://tc39.github.io/ecma262/#sec-function-objects) of the ECMAScript Language Specification. @@ -1520,14 +1520,14 @@ napi_status napi_create_string_latin1(napi_env env, ``` - `[in] env`: The environment that the API is invoked under. -- `[in] str`: Character buffer representing a ISO-8859-1-encoded string. +- `[in] str`: Character buffer representing an ISO-8859-1-encoded string. - `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. - `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. -This API creates a JavaScript `String` object from a ISO-8859-1-encoded C +This API creates a JavaScript `String` object from an ISO-8859-1-encoded C string. The native string is copied. The JavaScript `String` type is described in @@ -1807,19 +1807,20 @@ napi_status napi_get_value_int32(napi_env env, - `[in] env`: The environment that the API is invoked under. - `[in] value`: `napi_value` representing JavaScript `Number`. -- `[out] result`: C int32 primitive equivalent of the given JavaScript `Number`. +- `[out] result`: C `int32` primitive equivalent of the given JavaScript + `Number`. Returns `napi_ok` if the API succeeded. If a non-number `napi_value` is passed in `napi_number_expected`. -This API returns the C int32 primitive equivalent +This API returns the C `int32` primitive equivalent of the given JavaScript `Number`. If the number exceeds the range of the 32 bit integer, then the result is truncated to the equivalent of the bottom 32 bits. This can result in a large positive number becoming a negative number if the value is > 2^31 -1. -Non-finite number values (NaN, positive infinity, or negative infinity) set the +Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the result to zero. #### napi_get_value_int64 @@ -1834,12 +1835,13 @@ napi_status napi_get_value_int64(napi_env env, - `[in] env`: The environment that the API is invoked under. - `[in] value`: `napi_value` representing JavaScript `Number`. -- `[out] result`: C int64 primitive equivalent of the given JavaScript `Number`. +- `[out] result`: C `int64` primitive equivalent of the given JavaScript + `Number`. Returns `napi_ok` if the API succeeded. If a non-number `napi_value` is passed in it returns `napi_number_expected`. -This API returns the C int64 primitive equivalent of the given JavaScript +This API returns the C `int64` primitive equivalent of the given JavaScript `Number`. `Number` values outside the range of @@ -1848,7 +1850,7 @@ This API returns the C int64 primitive equivalent of the given JavaScript [`Number.MAX_SAFE_INTEGER`](https://tc39.github.io/ecma262/#sec-number.max_safe_integer) (2^53 - 1) will lose precision. -Non-finite number values (NaN, positive infinity, or negative infinity) set the +Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the result to zero. #### napi_get_value_string_latin1 @@ -3100,7 +3102,7 @@ napi_status napi_define_class(napi_env env, - `[in] utf8name`: Name of the JavaScript constructor function; this is not required to be the same as the C++ class name, though it is recommended for clarity. - - `[in] length`: The length of the utf8name in bytes, or `NAPI_AUTO_LENGTH` + - `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. - `[in] constructor`: Callback function that handles constructing instances of the class. (This should be a static method on the class, not an actual diff --git a/doc/api/net.md b/doc/api/net.md index 5b9d837c05..21d14fc706 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -151,7 +151,7 @@ Stops the server from accepting new connections and keeps existing connections. This function is asynchronous, the server is finally closed when all connections are ended and the server emits a [`'close'`][] event. The optional `callback` will be called once the `'close'` event occurs. Unlike -that event, it will be called with an Error as its only argument if the server +that event, it will be called with an `Error` as its only argument if the server was not open when it was closed. ### server.connections @@ -183,7 +183,7 @@ Callback should take two arguments `err` and `count`. ### server.listen() Start a server listening for connections. A `net.Server` can be a TCP or -a [IPC][] server depending on what it listens to. +an [IPC][] server depending on what it listens to. Possible signatures: @@ -295,7 +295,7 @@ added: v0.1.90 * `callback` {Function} Common parameter of [`server.listen()`][] functions. * Returns: {net.Server} -Start a [IPC][] server listening for connections on the given `path`. +Start an [IPC][] server listening for connections on the given `path`. #### server.listen([port[, host[, backlog]]][, callback]) <!-- YAML @@ -326,8 +326,7 @@ may cause the `net.Server` to also listen on the [unspecified IPv4 address][] added: v5.7.0 --> -A Boolean indicating whether or not the server is listening for -connections. +* {boolean} Indicates whether or not the server is listening for connections. ### server.maxConnections <!-- YAML @@ -370,7 +369,7 @@ added: v0.3.4 This class is an abstraction of a TCP socket or a streaming [IPC][] endpoint (uses named pipes on Windows, and UNIX domain sockets otherwise). A `net.Socket` is also a [duplex stream][], so it can be both readable and -writable, and it is also a [`EventEmitter`][]. +writable, and it is also an [`EventEmitter`][]. A `net.Socket` can be created by the user and used directly to interact with a server. For example, it is returned by [`net.createConnection()`][], @@ -558,10 +557,10 @@ Initiate a connection on a given socket. Possible signatures: -* [socket.connect(options[, connectListener])][`socket.connect(options)`] -* [socket.connect(path[, connectListener])][`socket.connect(path)`] +* [`socket.connect(options[, connectListener])`][`socket.connect(options)`] +* [`socket.connect(path[, connectListener])`][`socket.connect(path)`] for [IPC][] connections. -* [socket.connect(port[, host][, connectListener])][`socket.connect(port, host)`] +* [`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`] for TCP connections. * Returns: {net.Socket} The socket itself. @@ -670,8 +669,8 @@ listeners for that event will receive `exception` as an argument. ### socket.destroyed -A Boolean value that indicates if the connection is destroyed or not. Once a -connection is destroyed no further data can be transferred using it. +* {boolean} Indicates if the connection is destroyed or not. Once a + connection is destroyed no further data can be transferred using it. ### socket.end([data][, encoding]) <!-- YAML @@ -775,8 +774,8 @@ Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. 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 +data packet received and the first keepalive probe. Setting `0` for +`initialDelay` will leave the value unchanged from the default (or previous) setting. ### socket.setNoDelay([noDelay]) @@ -849,7 +848,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory. The optional `callback` parameter will be executed when the data is finally written out - this may not be immediately. -See Writable stream [`write()`][stream_writable_write] method for more +See `Writable` stream [`write()`][stream_writable_write] method for more information. ## net.connect() @@ -1030,7 +1029,7 @@ This allows connections to be passed between processes without any data being read by the original process. To begin reading data from a paused socket, call [`socket.resume()`][]. -The server can be a TCP server or a [IPC][] server, depending on what it +The server can be a TCP server or an [IPC][] server, depending on what it [`listen()`][`server.listen()`] to. Here is an example of an TCP echo server which listens for connections diff --git a/doc/api/os.md b/doc/api/os.md index 4e231aac54..8db4904d29 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -1114,7 +1114,7 @@ The following error codes are specific to the Windows operating system: </tr> <tr> <td><code>WSAVERNOTSUPPORTED</code></td> - <td>Indicates that the winsock.dll version is out of range.</td> + <td>Indicates that the `winsock.dll` version is out of range.</td> </tr> <tr> <td><code>WSANOTINITIALISED</code></td> @@ -1197,7 +1197,7 @@ information. </tr> <tr> <td><code>RTLD_LOCAL</code></td> - <td>The converse of RTLD_GLOBAL. This is the default behavior if neither + <td>The converse of `RTLD_GLOBAL`. This is the default behavior if neither flag is specified.</td> </tr> <tr> diff --git a/doc/api/process.md b/doc/api/process.md index 9c0c26162e..8205efbd78 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -205,10 +205,10 @@ added: v1.4.1 changes: - version: v7.0.0 pr-url: https://github.com/nodejs/node/pull/8217 - description: Not handling Promise rejections has been deprecated. + description: Not handling `Promise` rejections has been deprecated. - version: v6.6.0 pr-url: https://github.com/nodejs/node/pull/8223 - description: Unhandled Promise rejections will now emit + description: Unhandled `Promise` rejections will now emit a process warning. --> @@ -234,7 +234,7 @@ process.on('unhandledRejection', (reason, p) => { somePromise.then((res) => { return reportToUser(JSON.pasre(res)); // note the typo (`pasre`) -}); // no `.catch` or `.then` +}); // no `.catch()` or `.then()` ``` The following will also trigger the `'unhandledRejection'` event to be @@ -524,7 +524,7 @@ added: v0.7.7 * {Object} -The `process.config` property returns an Object containing the JavaScript +The `process.config` property returns an `Object` containing the JavaScript representation of the configure options used to compile the current Node.js executable. This is the same as the `config.gypi` file that was produced when running the `./configure` script. @@ -699,10 +699,10 @@ added: v8.0.0 * `warning` {string|Error} The warning to emit. * `options` {Object} - * `type` {string} When `warning` is a String, `type` is the name to use + * `type` {string} When `warning` is a `String`, `type` is the name to use for the *type* of warning being emitted. **Default:** `'Warning'`. * `code` {string} A unique identifier for the warning instance being emitted. - * `ctor` {Function} When `warning` is a String, `ctor` is an optional + * `ctor` {Function} When `warning` is a `String`, `ctor` is an optional function used to limit the generated stack trace. **Default:** `process.emitWarning`. * `detail` {string} Additional text to include with the error. @@ -744,10 +744,10 @@ added: v6.0.0 --> * `warning` {string|Error} The warning to emit. -* `type` {string} When `warning` is a String, `type` is the name to use +* `type` {string} When `warning` is a `String`, `type` is the name to use for the *type* of warning being emitted. **Default:** `'Warning'`. * `code` {string} A unique identifier for the warning instance being emitted. -* `ctor` {Function} When `warning` is a String, `ctor` is an optional +* `ctor` {Function} When `warning` is a `String`, `ctor` is an optional function used to limit the generated stack trace. **Default:** `process.emitWarning`. @@ -1151,12 +1151,12 @@ added: v0.7.6 * Returns: {integer[]} The `process.hrtime()` method returns the current high-resolution real time -in a `[seconds, nanoseconds]` tuple Array, where `nanoseconds` is the +in a `[seconds, nanoseconds]` tuple `Array`, where `nanoseconds` is the remaining part of the real time that can't be represented in second precision. `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time. If the parameter -passed in is not a tuple Array, a `TypeError` will be thrown. Passing in a +passed in is not a tuple `Array`, a `TypeError` will be thrown. Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior. @@ -1401,7 +1401,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 -nextTick callbacks will block any I/O from happening, just like a +`nextTick()` callbacks will block any I/O from happening, just like a `while(true);` loop. ## process.noDeprecation @@ -1482,8 +1482,8 @@ changes: * {Object} -The `process.release` property returns an Object containing metadata related to -the current release, including URLs for the source tarball and headers-only +The `process.release` property returns an `Object` containing metadata related +to the current release, including URLs for the source tarball and headers-only tarball. `process.release` contains the following properties: @@ -1741,7 +1741,7 @@ The `process.stdout` property returns a stream connected to stream) unless fd `1` refers to a file, in which case it is a [Writable][] stream. -For example, to copy process.stdin to process.stdout: +For example, to copy `process.stdin` to `process.stdout`: ```js process.stdin.pipe(process.stdout); @@ -1961,7 +1961,7 @@ cases: * `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 - can happen, for example, if a [`'uncaughtException'`][] or + can happen, for example, if an [`'uncaughtException'`][] or `domain.on('error')` handler throws an error. * `8` - Unused. In previous versions of Node.js, exit code 8 sometimes indicated an uncaught exception. diff --git a/doc/api/readline.md b/doc/api/readline.md index ead469e97c..a2a4adf309 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -303,7 +303,7 @@ rl.write('Delete this!'); rl.write(null, { ctrl: true, name: 'u' }); ``` -The `rl.write()` method will write the data to the `readline` Interface's +The `rl.write()` method will write the data to the `readline` `Interface`'s `input` *as if it were provided by the user*. ## readline.clearLine(stream, dir) @@ -401,9 +401,9 @@ a `'resize'` event on the `output` if or when the columns ever change ### Use of the `completer` Function The `completer` function takes the current line entered by the user -as an argument, and returns an Array with 2 entries: +as an argument, and returns an `Array` with 2 entries: -* An Array with matching entries for the completion. +* An `Array` with matching entries for the completion. * The substring that was used for the matching. For instance: `[[substr1, substr2, ...], originalsubstring]`. @@ -447,7 +447,7 @@ added: v0.7.7 * `interface` {readline.Interface} The `readline.emitKeypressEvents()` method causes the given [Readable][] -`stream` to begin emitting `'keypress'` events corresponding to received input. +stream to begin emitting `'keypress'` events corresponding to received input. Optionally, `interface` specifies a `readline.Interface` instance for which autocompletion is disabled when copy-pasted input is detected. diff --git a/doc/api/repl.md b/doc/api/repl.md index 995dabaa5d..b751472049 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -63,7 +63,7 @@ The following key combinations in the REPL have these special effects: When pressed twice on a blank line, has the same effect as the `.exit` command. * `<ctrl>-D` - Has the same effect as the `.exit` command. -* `<tab>` - When pressed on a blank line, displays global and local(scope) +* `<tab>` - When pressed on a blank line, displays global and local (scope) variables. When pressed while entering other input, displays relevant autocompletion options. @@ -251,7 +251,7 @@ function isRecoverableError(error) { ### Customizing REPL Output By default, `repl.REPLServer` instances format output using the -[`util.inspect()`][] method before writing the output to the provided Writable +[`util.inspect()`][] method before writing the output to the provided `Writable` stream (`process.stdout` by default). The `useColors` boolean option can be specified at construction to instruct the default writer to use ANSI style codes to colorize the output from the `util.inspect()` method. @@ -356,7 +356,7 @@ added: v0.3.0 The `replServer.defineCommand()` method is used to add new `.`-prefixed commands to the REPL instance. Such commands are invoked by typing a `.` followed by the -`keyword`. The `cmd` is either a Function or an object with the following +`keyword`. The `cmd` is either a `Function` or an `Object` with the following properties: * `help` {string} Help text to be displayed when `.help` is entered (Optional). @@ -443,7 +443,7 @@ added: v0.1.91 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/v10.0.0 - description: The `REPL_MAGIC_MODE` replMode was removed. + description: The `REPL_MAGIC_MODE` `replMode` was removed. - version: v5.8.0 pr-url: https://github.com/nodejs/node/pull/5388 description: The `options` parameter is optional now. @@ -452,10 +452,10 @@ changes: * `options` {Object|string} * `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. **Default:** `process.stdin`. - * `output` {stream.Writable} The Writable stream to which REPL output will be - written. **Default:** `process.stdout`. + * `input` {stream.Readable} The `Readable` stream from which REPL input will + be read. **Default:** `process.stdin`. + * `output` {stream.Writable} The `Writable` stream to which REPL output will + be 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. **Default:** checking the value of the `isTTY` property on the `output` diff --git a/doc/api/stream.md b/doc/api/stream.md index 8af12d12bf..483aec1b70 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -37,13 +37,13 @@ the elements of the API that are required to *implement* new types of streams. There are four fundamental stream types within Node.js: -* [Readable][] - streams from which data can be read (for example +* [`Readable`][] - streams from which data can be read (for example [`fs.createReadStream()`][]). -* [Writable][] - streams to which data can be written (for example +* [`Writable`][] - streams to which data can be written (for example [`fs.createWriteStream()`][]). -* [Duplex][] - streams that are both Readable and Writable (for example +* [`Duplex`][] - streams that are both `Readable` and `Writable` (for example [`net.Socket`][]). -* [Transform][] - Duplex streams that can modify or transform the data as it +* [`Transform`][] - `Duplex` streams that can modify or transform the data as it is written and read (for example [`zlib.createDeflate()`][]). Additionally this module includes the utility functions [pipeline][] and @@ -65,7 +65,7 @@ object mode is not safe. <!--type=misc--> -Both [Writable][] and [Readable][] streams will store data in an internal +Both [`Writable`][] and [`Readable`][] streams will store data in an internal buffer that can be retrieved using `writable.writableBuffer` or `readable.readableBuffer`, respectively. @@ -74,7 +74,7 @@ passed into the streams constructor. For normal streams, the `highWaterMark` option specifies a [total number of bytes][hwm-gotcha]. For streams operating in object mode, the `highWaterMark` specifies a total number of objects. -Data is buffered in Readable streams when the implementation calls +Data is buffered in `Readable` streams when the implementation calls [`stream.push(chunk)`][stream-push]. If the consumer of the Stream does not call [`stream.read()`][stream-read], the data will sit in the internal queue until it is consumed. @@ -85,7 +85,7 @@ underlying resource until the data currently buffered can be consumed (that is, the stream will stop calling the internal `readable._read()` method that is used to fill the read buffer). -Data is buffered in Writable streams when the +Data is buffered in `Writable` streams when the [`writable.write(chunk)`][stream-write] method is called repeatedly. While the total size of the internal write buffer is below the threshold set by `highWaterMark`, calls to `writable.write()` will return `true`. Once @@ -96,15 +96,15 @@ A key goal of the `stream` API, particularly the [`stream.pipe()`] method, is to limit the buffering of data to acceptable levels such that sources and destinations of differing speeds will not overwhelm the available memory. -Because [Duplex][] and [Transform][] streams are both Readable and Writable, -each maintain *two* separate internal buffers used for reading and writing, -allowing each side to operate independently of the other while maintaining an -appropriate and efficient flow of data. For example, [`net.Socket`][] instances -are [Duplex][] streams whose Readable side allows consumption of data received -*from* the socket and whose Writable side allows writing data *to* the socket. -Because data may be written to the socket at a faster or slower rate than data -is received, it is important for each side to operate (and buffer) independently -of the other. +Because [`Duplex`][] and [`Transform`][] streams are both `Readable` and +`Writable`, each maintain *two* separate internal buffers used for reading and +writing, allowing each side to operate independently of the other while +maintaining an appropriate and efficient flow of data. For example, +[`net.Socket`][] instances are [`Duplex`][] streams whose `Readable` side allows +consumption of data received *from* the socket and whose `Writable` side allows +writing data *to* the socket. Because data may be written to the socket at a +faster or slower rate than data is received, it is important for each side to +operate (and buffer) independently of the other. ## API for Stream Consumers @@ -156,17 +156,18 @@ server.listen(1337); // error: Unexpected token o in JSON at position 1 ``` -[Writable][] streams (such as `res` in the example) expose methods such as +[`Writable`][] streams (such as `res` in the example) expose methods such as `write()` and `end()` that are used to write data onto the stream. -[Readable][] streams use the [`EventEmitter`][] API for notifying application +[`Readable`][] streams use the [`EventEmitter`][] API for notifying application code when data is available to be read off the stream. That available data can be read from the stream in multiple ways. -Both [Writable][] and [Readable][] streams use the [`EventEmitter`][] API in +Both [`Writable`][] and [`Readable`][] streams use the [`EventEmitter`][] API in various ways to communicate the current state of the stream. -[Duplex][] and [Transform][] streams are both [Writable][] and [Readable][]. +[`Duplex`][] and [`Transform`][] streams are both [`Writable`][] and +[`Readable`][]. Applications that are either writing data to or consuming data from a stream are not required to implement the stream interfaces directly and will generally @@ -180,7 +181,7 @@ section [API for Stream Implementers][]. Writable streams are an abstraction for a *destination* to which data is written. -Examples of [Writable][] streams include: +Examples of [`Writable`][] streams include: * [HTTP requests, on the client][] * [HTTP responses, on the server][] @@ -191,14 +192,14 @@ Examples of [Writable][] streams include: * [child process stdin][] * [`process.stdout`][], [`process.stderr`][] -Some of these examples are actually [Duplex][] streams that implement the -[Writable][] interface. +Some of these examples are actually [`Duplex`][] streams that implement the +[`Writable`][] interface. -All [Writable][] streams implement the interface defined by the +All [`Writable`][] streams implement the interface defined by the `stream.Writable` class. -While specific instances of [Writable][] streams may differ in various ways, -all Writable streams follow the same fundamental usage pattern as illustrated +While specific instances of [`Writable`][] streams may differ in various ways, +all `Writable` streams follow the same fundamental usage pattern as illustrated in the example below: ```js @@ -224,7 +225,7 @@ The `'close'` event is emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed. The event indicates that no more events will be emitted, and no further computation will occur. -Not all Writable streams will emit the `'close'` event. +Not all `Writable` streams will emit the `'close'` event. ##### Event: 'drain' <!-- YAML @@ -323,11 +324,11 @@ added: v0.9.4 [unpiped][`stream.unpipe()`] this writable The `'unpipe'` event is emitted when the [`stream.unpipe()`][] method is called -on a [Readable][] stream, removing this [Writable][] from its set of +on a [`Readable`][] stream, removing this [`Writable`][] from its set of destinations. -This is also emitted in case this [Writable][] stream emits an error when a -[Readable][] stream pipes into it. +This is also emitted in case this [`Writable`][] stream emits an error when a +[`Readable`][] stream pipes into it. ```js const writer = getWritableStreamSomehow(); @@ -391,7 +392,7 @@ changes: * Returns: {this} Calling the `writable.end()` method signals that no more data will be written -to the [Writable][]. The optional `chunk` and `encoding` arguments allow one +to the [`Writable`][]. The optional `chunk` and `encoding` arguments allow one final additional chunk of data to be written immediately before closing the stream. If provided, the optional `callback` function is attached as a listener for the [`'finish'`][] event. @@ -421,7 +422,7 @@ changes: * Returns: {this} The `writable.setDefaultEncoding()` method sets the default `encoding` for a -[Writable][] stream. +[`Writable`][] stream. ##### writable.uncork() <!-- YAML @@ -517,7 +518,7 @@ stop until the [`'drain'`][] event is emitted. While a stream is not draining, calls to `write()` will buffer `chunk`, and return false. Once all currently buffered chunks are drained (accepted for delivery by the operating system), the `'drain'` event will be emitted. -It is recommended that once write() returns false, no more chunks be written +It is recommended that once `write()` returns false, no more chunks be written until the `'drain'` event is emitted. While calling `write()` on a stream that is not draining is allowed, Node.js will buffer all written chunks until maximum memory usage occurs, at which point it will abort unconditionally. @@ -528,12 +529,12 @@ drain if the remote peer does not read the data, writing a socket that is not draining may lead to a remotely exploitable vulnerability. Writing data while the stream is not draining is particularly -problematic for a [Transform][], because the `Transform` streams are paused +problematic for a [`Transform`][], because the `Transform` streams are paused by default until they are piped or an `'data'` or `'readable'` event handler is added. If the data to be written can be generated or fetched on demand, it is -recommended to encapsulate the logic into a [Readable][] and use +recommended to encapsulate the logic into a [`Readable`][] and use [`stream.pipe()`][]. However, if calling `write()` is preferred, it is possible to respect backpressure and avoid memory issues using the [`'drain'`][] event: @@ -553,14 +554,14 @@ write('hello', () => { }); ``` -A Writable stream in object mode will always ignore the `encoding` argument. +A `Writable` stream in object mode will always ignore the `encoding` argument. ### Readable Streams Readable streams are an abstraction for a *source* from which data is consumed. -Examples of Readable streams include: +Examples of `Readable` streams include: * [HTTP responses, on the client][http-incoming-message] * [HTTP requests, on the server][http-incoming-message] @@ -571,12 +572,12 @@ Examples of Readable streams include: * [child process stdout and stderr][] * [`process.stdin`][] -All [Readable][] streams implement the interface defined by the +All [`Readable`][] streams implement the interface defined by the `stream.Readable` class. #### Two Modes -Readable streams effectively operate in one of two modes: flowing and paused. +`Readable` streams effectively operate in one of two modes: flowing and paused. When in flowing mode, data is read from the underlying system automatically and provided to an application as quickly as possible using events via the @@ -585,14 +586,14 @@ and provided to an application as quickly as possible using events via the In paused mode, the [`stream.read()`][stream-read] method must be called explicitly to read chunks of data from the stream. -All [Readable][] streams begin in paused mode but can be switched to flowing +All [`Readable`][] streams begin in paused mode but can be switched to flowing mode in one of the following ways: * Adding a [`'data'`][] event handler. * Calling the [`stream.resume()`][stream-resume] method. -* Calling the [`stream.pipe()`][] method to send the data to a [Writable][]. +* Calling the [`stream.pipe()`][] method to send the data to a [`Writable`][]. -The Readable can switch back to paused mode using one of the following: +The `Readable` can switch back to paused mode using one of the following: * If there are no pipe destinations, by calling the [`stream.pause()`][stream-pause] method. @@ -600,9 +601,9 @@ The Readable can switch back to paused mode using one of the following: Multiple pipe destinations may be removed by calling the [`stream.unpipe()`][] method. -The important concept to remember is that a Readable will not generate data +The important concept to remember is that a `Readable` will not generate data until a mechanism for either consuming or ignoring that data is provided. If -the consuming mechanism is disabled or taken away, the Readable will *attempt* +the consuming mechanism is disabled or taken away, the `Readable` will *attempt* to stop generating the data. For backwards compatibility reasons, removing [`'data'`][] event handlers will @@ -610,7 +611,7 @@ For backwards compatibility reasons, removing [`'data'`][] event handlers will then calling [`stream.pause()`][stream-pause] will not guarantee that the stream will *remain* paused once those destinations drain and ask for more data. -If a [Readable][] is switched into flowing mode and there are no consumers +If a [`Readable`][] is switched into flowing mode and there are no consumers available to handle the data, that data will be lost. This can occur, for instance, when the `readable.resume()` method is called without a listener attached to the `'data'` event, or when a `'data'` event handler is removed @@ -618,11 +619,11 @@ from the stream. #### Three States -The "two modes" of operation for a Readable stream are a simplified abstraction -for the more complicated internal state management that is happening within the -Readable stream implementation. +The "two modes" of operation for a `Readable` stream are a simplified +abstraction for the more complicated internal state management that is happening +within the `Readable` stream implementation. -Specifically, at any given point in time, every Readable is in one of three +Specifically, at any given point in time, every `Readable` is in one of three possible states: * `readable.readableFlowing = null` @@ -633,7 +634,7 @@ When `readable.readableFlowing` is `null`, no mechanism for consuming the streams data is provided so the stream will not generate its data. While in this state, attaching a listener for the `'data'` event, calling the `readable.pipe()` method, or calling the `readable.resume()` method will switch -`readable.readableFlowing` to `true`, causing the Readable to begin +`readable.readableFlowing` to `true`, causing the `Readable` to begin actively emitting events as data is generated. Calling `readable.pause()`, `readable.unpipe()`, or receiving "back pressure" @@ -661,7 +662,7 @@ within the streams internal buffer. #### Choose One -The Readable stream API evolved across multiple Node.js versions and provides +The `Readable` stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data. In general, developers should choose *one* of the methods of consuming data and *should never* use multiple methods to consume data from a single stream. @@ -687,7 +688,7 @@ The `'close'` event is emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed. The event indicates that no more events will be emitted, and no further computation will occur. -Not all [Readable][] streams will emit the `'close'` event. +Not all [`Readable`][] streams will emit the `'close'` event. ##### Event: 'data' <!-- YAML @@ -752,7 +753,7 @@ added: v0.9.4 * {Error} -The `'error'` event may be emitted by a Readable implementation at any time. +The `'error'` event may be emitted by a `Readable` implementation at any time. Typically, this may occur if the underlying stream is unable to generate data due to an underlying internal failure, or when a stream implementation attempts to push an invalid chunk of data. @@ -847,7 +848,7 @@ added: v0.11.14 * Returns: {boolean} The `readable.isPaused()` method returns the current operating state of the -Readable. This is used primarily by the mechanism that underlies the +`Readable`. This is used primarily by the mechanism that underlies the `readable.pipe()` method. In most typical cases, there will be no reason to use this method directly. @@ -896,11 +897,11 @@ added: v0.9.4 * Returns: {stream.Writable} making it possible to set up chains of piped streams -The `readable.pipe()` method attaches a [Writable][] stream to the `readable`, +The `readable.pipe()` method attaches a [`Writable`][] stream to the `readable`, causing it to switch automatically into flowing mode and push all of its data -to the attached [Writable][]. The flow of data will be automatically managed so -that the destination Writable stream is not overwhelmed by a faster Readable -stream. +to the attached [`Writable`][]. The flow of data will be automatically managed +so that the destination `Writable` stream is not overwhelmed by a faster +`Readable` stream. The following example pipes all of the data from the `readable` into a file named `file.txt`: @@ -912,7 +913,8 @@ const writable = fs.createWriteStream('file.txt'); // All the data from readable goes into 'file.txt' readable.pipe(writable); ``` -It is possible to attach multiple Writable streams to a single Readable stream. +It is possible to attach multiple `Writable` streams to a single `Readable` +stream. The `readable.pipe()` method returns a reference to the *destination* stream making it possible to set up chains of piped streams: @@ -925,8 +927,8 @@ const w = fs.createWriteStream('file.txt.gz'); r.pipe(z).pipe(w); ``` -By default, [`stream.end()`][stream-end] is called on the destination Writable -stream when the source Readable stream emits [`'end'`][], so that the +By default, [`stream.end()`][stream-end] is called on the destination `Writable` +stream when the source `Readable` stream emits [`'end'`][], so that the destination is no longer writable. To disable this default behavior, the `end` option can be passed as `false`, causing the destination stream to remain open, as illustrated in the following example: @@ -938,12 +940,12 @@ reader.on('end', () => { }); ``` -One important caveat is that if the Readable stream emits an error during -processing, the Writable destination *is not closed* automatically. If an +One important caveat is that if the `Readable` stream emits an error during +processing, the `Writable` destination *is not closed* automatically. If an error occurs, it will be necessary to *manually* close each stream in order to prevent memory leaks. -The [`process.stderr`][] and [`process.stdout`][] Writable streams are never +The [`process.stderr`][] and [`process.stdout`][] `Writable` streams are never closed until the Node.js process exits, regardless of the specified options. ##### readable.read([size]) @@ -968,9 +970,9 @@ buffer will be returned. If the `size` argument is not specified, all of the data contained in the internal buffer will be returned. -The `readable.read()` method should only be called on Readable streams operating -in paused mode. In flowing mode, `readable.read()` is called automatically until -the internal buffer is fully drained. +The `readable.read()` method should only be called on `Readable` streams +operating in paused mode. In flowing mode, `readable.read()` is called +automatically until the internal buffer is fully drained. ```js const readable = getReadableStreamSomehow(); @@ -982,7 +984,7 @@ readable.on('readable', () => { }); ``` -A Readable stream in object mode will always return a single item from +A `Readable` stream in object mode will always return a single item from a call to [`readable.read(size)`][stream-read], regardless of the value of the `size` argument. @@ -1025,7 +1027,7 @@ changes: * Returns: {this} -The `readable.resume()` method causes an explicitly paused Readable stream to +The `readable.resume()` method causes an explicitly paused `Readable` stream to resume emitting [`'data'`][] events, switching the stream into flowing mode. The `readable.resume()` method can be used to fully consume the data from a @@ -1052,7 +1054,7 @@ added: v0.9.4 * Returns: {this} The `readable.setEncoding()` method sets the character encoding for -data read from the Readable stream. +data read from the `Readable` stream. By default, no encoding is assigned and stream data will be returned as `Buffer` objects. Setting an encoding causes the stream data @@ -1062,9 +1064,9 @@ output data to be interpreted as UTF-8 data, and passed as strings. Calling `readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal string format. -The Readable stream will properly handle multi-byte characters delivered through -the stream that would otherwise become improperly decoded if simply pulled from -the stream as `Buffer` objects. +The `Readable` stream will properly handle multi-byte characters delivered +through the stream that would otherwise become improperly decoded if simply +pulled from the stream as `Buffer` objects. ```js const readable = getReadableStreamSomehow(); @@ -1083,7 +1085,7 @@ added: v0.9.4 * `destination` {stream.Writable} Optional specific stream to unpipe * Returns: {this} -The `readable.unpipe()` method detaches a Writable stream previously attached +The `readable.unpipe()` method detaches a `Writable` stream previously attached using the [`stream.pipe()`][] method. If the `destination` is not specified, then *all* pipes are detached. @@ -1129,7 +1131,7 @@ The `stream.unshift(chunk)` method cannot be called after the [`'end'`][] event has been emitted or a runtime error will be thrown. Developers using `stream.unshift()` often should consider switching to -use of a [Transform][] stream instead. See the [API for Stream Implementers][] +use of a [`Transform`][] stream instead. See the [API for Stream Implementers][] section for more information. ```js @@ -1191,7 +1193,7 @@ for more information.) When using an older Node.js library that emits [`'data'`][] events and has a [`stream.pause()`][stream-pause] method that is advisory only, the -`readable.wrap()` method can be used to create a [Readable][] stream that uses +`readable.wrap()` method can be used to create a [`Readable`][] stream that uses the old stream as its data source. It will rarely be necessary to use `readable.wrap()` but the method has been @@ -1254,10 +1256,10 @@ changes: <!--type=class--> -Duplex streams are streams that implement both the [Readable][] and -[Writable][] interfaces. +Duplex streams are streams that implement both the [`Readable`][] and +[`Writable`][] interfaces. -Examples of Duplex streams include: +Examples of `Duplex` streams include: * [TCP sockets][] * [zlib streams][zlib] @@ -1270,11 +1272,11 @@ added: v0.9.4 <!--type=class--> -Transform streams are [Duplex][] streams where the output is in some way -related to the input. Like all [Duplex][] streams, Transform streams -implement both the [Readable][] and [Writable][] interfaces. +Transform streams are [`Duplex`][] streams where the output is in some way +related to the input. Like all [`Duplex`][] streams, `Transform` streams +implement both the [`Readable`][] and [`Writable`][] interfaces. -Examples of Transform streams include: +Examples of `Transform` streams include: * [zlib streams][zlib] * [crypto streams][crypto] @@ -1436,7 +1438,7 @@ on the type of stream being created, as detailed in the chart below: <p>Reading only</p> </td> <td> - <p>[Readable](#stream_class_stream_readable)</p> + <p>[`Readable`](#stream_class_stream_readable)</p> </td> <td> <p><code>[_read][stream-_read]</code></p> @@ -1447,7 +1449,7 @@ on the type of stream being created, as detailed in the chart below: <p>Writing only</p> </td> <td> - <p>[Writable](#stream_class_stream_writable)</p> + <p>[`Writable`](#stream_class_stream_writable)</p> </td> <td> <p> @@ -1462,7 +1464,7 @@ on the type of stream being created, as detailed in the chart below: <p>Reading and writing</p> </td> <td> - <p>[Duplex](#stream_class_stream_duplex)</p> + <p>[`Duplex`](#stream_class_stream_duplex)</p> </td> <td> <p> @@ -1477,7 +1479,7 @@ on the type of stream being created, as detailed in the chart below: <p>Operate on written data, then read the result</p> </td> <td> - <p>[Transform](#stream_class_stream_transform)</p> + <p>[`Transform`](#stream_class_stream_transform)</p> </td> <td> <p> @@ -1516,9 +1518,9 @@ const myWritable = new Writable({ ### Implementing a Writable Stream -The `stream.Writable` class is extended to implement a [Writable][] stream. +The `stream.Writable` class is extended to implement a [`Writable`][] stream. -Custom Writable streams *must* call the `new stream.Writable([options])` +Custom `Writable` streams *must* call the `new stream.Writable([options])` constructor and implement the `writable._write()` method. The `writable._writev()` method *may* also be implemented. @@ -1536,7 +1538,7 @@ changes: [`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]. + `Buffer`s before passing them to [`stream._write()`][stream-_write]. **Default:** `true`. * `objectMode` {boolean} Whether or not the [`stream.write(anyObj)`][stream-write] is a valid operation. When set, @@ -1606,16 +1608,16 @@ const myWritable = new Writable({ * `callback` {Function} Call this function (optionally with an error argument) when processing is complete for the supplied chunk. -All Writable stream implementations must provide a +All `Writable` stream implementations must provide a [`writable._write()`][stream-_write] method to send data to the underlying resource. -[Transform][] streams provide their own implementation of the +[`Transform`][] streams provide their own implementation of the [`writable._write()`][stream-_write]. This function MUST NOT be called by application code directly. It should be -implemented by child classes, and called by the internal Writable class methods -only. +implemented by child classes, and called by the internal `Writable` class +methods only. The `callback` method must be called to signal either that the write completed successfully or failed with an error. The first argument passed to the @@ -1647,8 +1649,8 @@ user programs. argument) to be invoked when processing is complete for the supplied chunks. This function MUST NOT be called by application code directly. It should be -implemented by child classes, and called by the internal Writable class methods -only. +implemented by child classes, and called by the internal `Writable` class +methods only. The `writable._writev()` method may be implemented in addition to `writable._write()` in stream implementations that are capable of processing @@ -1680,7 +1682,7 @@ added: v8.0.0 argument) when finished writing any remaining data. The `_final()` method **must not** be called directly. It may be implemented -by child classes, and if so, will be called by the internal Writable +by child classes, and if so, will be called by the internal `Writable` class methods only. This optional function will be called before the stream closes, delaying the @@ -1692,13 +1694,13 @@ or write buffered data before a stream ends. It is recommended that errors occurring during the processing of the `writable._write()` and `writable._writev()` methods are reported by invoking 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 +`'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 predictable handling of errors. -If a Readable stream pipes into a Writable stream when Writable emits an -error, the Readable stream will be unpiped. +If a `Readable` stream pipes into a `Writable` stream when `Writable` emits an +error, the `Readable` stream will be unpiped. ```js const { Writable } = require('stream'); @@ -1717,9 +1719,9 @@ const myWritable = new Writable({ #### An Example Writable Stream The following illustrates a rather simplistic (and somewhat pointless) custom -Writable stream implementation. While this specific Writable stream instance +`Writable` stream implementation. While this specific `Writable` stream instance is not of any real particular usefulness, the example illustrates each of the -required elements of a custom [Writable][] stream instance: +required elements of a custom [`Writable`][] stream instance: ```js const { Writable } = require('stream'); @@ -1745,7 +1747,7 @@ class MyWritable extends Writable { Decoding buffers is a common task, for instance, when using transformers whose input is a string. This is not a trivial process when using multi-byte characters encoding, such as UTF-8. The following example shows how to decode -multi-byte strings using `StringDecoder` and [Writable][]. +multi-byte strings using `StringDecoder` and [`Writable`][]. ```js const { Writable } = require('stream'); @@ -1782,9 +1784,9 @@ console.log(w.data); // currency: € ### Implementing a Readable Stream -The `stream.Readable` class is extended to implement a [Readable][] stream. +The `stream.Readable` class is extended to implement a [`Readable`][] stream. -Custom Readable streams *must* call the `new stream.Readable([options])` +Custom `Readable` streams *must* call the `new stream.Readable([options])` constructor and implement the `readable._read()` method. #### new stream.Readable([options]) @@ -1797,7 +1799,7 @@ constructor and implement the `readable._read()` method. 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. **Default:** `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 @@ -1847,16 +1849,16 @@ added: v0.9.4 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/17979 - description: call _read() only once per microtick + description: call `_read()` only once per microtick --> * `size` {number} Number of bytes to read asynchronously This function MUST NOT be called by application code directly. It should be -implemented by child classes, and called by the internal Readable class methods -only. +implemented by child classes, and called by the internal `Readable` class +methods only. -All Readable stream implementations must provide an implementation of the +All `Readable` stream implementations must provide an implementation of the `readable._read()` method to fetch data from the underlying resource. When `readable._read()` is called, if data is available from the resource, the @@ -1906,7 +1908,7 @@ changes: string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any JavaScript value. * `encoding` {string} Encoding of string chunks. Must be a valid - Buffer encoding, such as `'utf8'` or `'ascii'` + `Buffer` encoding, such as `'utf8'` or `'ascii'`. * Returns: {boolean} `true` if additional chunks of data may continued to be pushed; `false` otherwise. @@ -1915,18 +1917,18 @@ be added to the internal queue for users of the stream to consume. Passing `chunk` as `null` signals the end of the stream (EOF), after which no more data can be written. -When the Readable is operating in paused mode, the data added with +When the `Readable` is operating in paused mode, the data added with `readable.push()` can be read out by calling the [`readable.read()`][stream-read] method when the [`'readable'`][] event is emitted. -When the Readable is operating in flowing mode, the data added with +When the `Readable` is operating in flowing mode, the data added with `readable.push()` will be delivered by emitting a `'data'` event. The `readable.push()` method is designed to be as flexible as possible. For example, when wrapping a lower-level source that provides some form of pause/resume mechanism, and a data callback, the low-level source can be wrapped -by the custom Readable instance as illustrated in the following example: +by the custom `Readable` instance as illustrated in the following example: ```js // source is an object with readStop() and readStart() methods, @@ -1959,8 +1961,8 @@ class SourceWrapper extends Readable { } ``` -The `readable.push()` method is intended be called only by Readable -Implementers, and only from within the `readable._read()` method. +The `readable.push()` method is intended be called only by `Readable` +implementers, and only from within the `readable._read()` method. For streams not operating in object mode, if the `chunk` parameter of `readable.push()` is `undefined`, it will be treated as empty string or @@ -1970,7 +1972,7 @@ buffer. See [`readable.push('')`][] for more information. It is recommended that errors occurring during the processing of the `readable._read()` method are emitted using the `'error'` event rather than -being thrown. Throwing an Error from within `readable._read()` can result in +being thrown. Throwing an `Error` from within `readable._read()` can result in unexpected and inconsistent behavior depending on whether the stream is operating in flowing or paused mode. Using the `'error'` event ensures consistent and predictable handling of errors. @@ -1994,7 +1996,7 @@ const myReadable = new Readable({ <!--type=example--> -The following is a basic example of a Readable stream that emits the numerals +The following is a basic example of a `Readable` stream that emits the numerals from 1 to 1,000,000 in ascending order, and then ends. ```js @@ -2022,11 +2024,11 @@ class Counter extends Readable { ### Implementing a Duplex Stream -A [Duplex][] stream is one that implements both [Readable][] and [Writable][], -such as a TCP socket connection. +A [`Duplex`][] stream is one that implements both [`Readable`][] and +[`Writable`][], such as a TCP socket connection. Because JavaScript does not have support for multiple inheritance, the -`stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed +`stream.Duplex` class is extended to implement a [`Duplex`][] stream (as opposed to extending the `stream.Readable` *and* `stream.Writable` classes). The `stream.Duplex` class prototypically inherits from `stream.Readable` and @@ -2034,7 +2036,7 @@ parasitically from `stream.Writable`, but `instanceof` will work properly for both base classes due to overriding [`Symbol.hasInstance`][] on `stream.Writable`. -Custom Duplex streams *must* call the `new stream.Duplex([options])` +Custom `Duplex` streams *must* call the `new stream.Duplex([options])` constructor and implement *both* the `readable._read()` and `writable._write()` methods. @@ -2047,7 +2049,7 @@ changes: are supported now. --> -* `options` {Object} Passed to both Writable and Readable +* `options` {Object} Passed to both `Writable` and `Readable` constructors. Also has the following fields: * `allowHalfOpen` {boolean} If set to `false`, then the stream will automatically end the writable side when the readable side ends. @@ -2103,13 +2105,13 @@ const myDuplex = new Duplex({ #### An Example Duplex Stream -The following illustrates a simple example of a Duplex stream that wraps a +The following illustrates a simple example of a `Duplex` stream that wraps a hypothetical lower-level source object to which data can be written, and from which data can be read, albeit using an API that is not compatible with Node.js streams. -The following illustrates a simple example of a Duplex stream that buffers -incoming written data via the [Writable][] interface that is read back out -via the [Readable][] interface. +The following illustrates a simple example of a `Duplex` stream that buffers +incoming written data via the [`Writable`][] interface that is read back out +via the [`Readable`][] interface. ```js const { Duplex } = require('stream'); @@ -2137,20 +2139,20 @@ class MyDuplex extends Duplex { } ``` -The most important aspect of a Duplex stream is that the Readable and Writable -sides operate independently of one another despite co-existing within a single -object instance. +The most important aspect of a `Duplex` stream is that the `Readable` and +`Writable` sides operate independently of one another despite co-existing within +a single object instance. #### Object Mode Duplex Streams -For Duplex streams, `objectMode` can be set exclusively for either the Readable -or Writable side using the `readableObjectMode` and `writableObjectMode` options -respectively. +For `Duplex` streams, `objectMode` can be set exclusively for either the +`Readable` or `Writable` side using the `readableObjectMode` and +`writableObjectMode` options respectively. -In the following example, for instance, a new Transform stream (which is a -type of [Duplex][] stream) is created that has an object mode Writable side +In the following example, for instance, a new `Transform` stream (which is a +type of [`Duplex`][] stream) is created that has an object mode `Writable` side that accepts JavaScript numbers that are converted to hexadecimal strings on -the Readable side. +the `Readable` side. ```js const { Transform } = require('stream'); @@ -2184,31 +2186,31 @@ myTransform.write(100); ### Implementing a Transform Stream -A [Transform][] stream is a [Duplex][] stream where the output is computed +A [`Transform`][] stream is a [`Duplex`][] stream where the output is computed in some way from the input. Examples include [zlib][] streams or [crypto][] streams that compress, encrypt, or decrypt data. There is no requirement that the output be the same size as the input, the same -number of chunks, or arrive at the same time. For example, a Hash stream will +number of chunks, or arrive at the same time. For example, a `Hash` stream will only ever have a single chunk of output which is provided when the input is ended. A `zlib` stream will produce output that is either much smaller or much larger than its input. -The `stream.Transform` class is extended to implement a [Transform][] stream. +The `stream.Transform` class is extended to implement a [`Transform`][] stream. The `stream.Transform` class prototypically inherits from `stream.Duplex` and implements its own versions of the `writable._write()` and `readable._read()` -methods. Custom Transform implementations *must* implement the +methods. Custom `Transform` implementations *must* implement the [`transform._transform()`][stream-_transform] method and *may* also implement the [`transform._flush()`][stream-_flush] method. -Care must be taken when using Transform streams in that data written to the -stream can cause the Writable side of the stream to become paused if the output -on the Readable side is not consumed. +Care must be taken when using `Transform` streams in that data written to the +stream can cause the `Writable` side of the stream to become paused if the +output on the `Readable` side is not consumed. #### new stream.Transform([options]) -* `options` {Object} Passed to both Writable and Readable +* `options` {Object} Passed to both `Writable` and `Readable` constructors. Also has the following fields: * `transform` {Function} Implementation for the [`stream._transform()`][stream-_transform] method. @@ -2267,8 +2269,8 @@ after all data has been output, which occurs after the callback in argument and data) to be called when remaining data has been flushed. This function MUST NOT be called by application code directly. It should be -implemented by child classes, and called by the internal Readable class methods -only. +implemented by child classes, and called by the internal `Readable` class +methods only. In some cases, a transform operation may need to emit an additional bit of data at the end of the stream. For example, a `zlib` compression stream will @@ -2276,10 +2278,10 @@ store an amount of internal state used to optimally compress the output. When the stream ends, however, that additional data needs to be flushed so that the compressed data will be complete. -Custom [Transform][] implementations *may* implement the `transform._flush()` +Custom [`Transform`][] implementations *may* implement the `transform._flush()` method. This will be called when there is no more written data to be consumed, but before the [`'end'`][] event is emitted signaling the end of the -[Readable][] stream. +[`Readable`][] stream. Within the `transform._flush()` implementation, the `readable.push()` method may be called zero or more times, as appropriate. The `callback` function must @@ -2302,10 +2304,10 @@ user programs. processed. This function MUST NOT be called by application code directly. It should be -implemented by child classes, and called by the internal Readable class methods -only. +implemented by child classes, and called by the internal `Readable` class +methods only. -All Transform stream implementations must provide a `_transform()` +All `Transform` stream implementations must provide a `_transform()` method to accept input and produce output. The `transform._transform()` implementation handles the bytes being written, computes an output, then passes that output off to the readable portion using the `readable.push()` method. @@ -2343,7 +2345,7 @@ called, either synchronously or asynchronously. #### Class: stream.PassThrough -The `stream.PassThrough` class is a trivial implementation of a [Transform][] +The `stream.PassThrough` class is a trivial implementation of a [`Transform`][] stream that simply passes the input bytes across to the output. Its purpose is primarily for examples and testing, but there are some use cases where `stream.PassThrough` is useful as a building block for novel sorts of streams. @@ -2356,7 +2358,7 @@ primarily for examples and testing, but there are some use cases where <!--type=misc--> -In versions of Node.js prior to v0.10, the Readable stream interface was +In versions of Node.js prior to v0.10, the `Readable` stream interface was simpler, but also less powerful and less useful. * Rather than waiting for calls the [`stream.read()`][stream-read] method, @@ -2367,9 +2369,9 @@ simpler, but also less powerful and less useful. guaranteed. This meant that it was still necessary to be prepared to receive [`'data'`][] events *even when the stream was in a paused state*. -In Node.js v0.10, the [Readable][] class was added. For backwards compatibility -with older Node.js programs, Readable streams switch into "flowing mode" when a -[`'data'`][] event handler is added, or when the +In Node.js v0.10, the [`Readable`][] class was added. For backwards +compatibility with older Node.js programs, `Readable` streams switch into +"flowing mode" when a [`'data'`][] event handler is added, or when the [`stream.resume()`][stream-resume] method is called. The effect is that, even when not using the new [`stream.read()`][stream-read] method and [`'readable'`][] event, it is no longer necessary to worry about losing @@ -2416,8 +2418,8 @@ net.createServer((socket) => { }).listen(1337); ``` -In addition to new Readable streams switching into flowing mode, -pre-v0.10 style streams can be wrapped in a Readable class using the +In addition to new `Readable` streams switching into flowing mode, +pre-v0.10 style streams can be wrapped in a `Readable` class using the [`readable.wrap()`][`stream.wrap()`] method. ### `readable.read(0)` @@ -2433,7 +2435,7 @@ a low-level [`stream._read()`][stream-_read] call. While most applications will almost never need to do this, there are situations within Node.js where this is done, particularly in the -Readable stream class internals. +`Readable` stream class internals. ### `readable.push('')` @@ -2483,13 +2485,13 @@ contain multi-byte characters. [API for Stream Consumers]: #stream_api_for_stream_consumers [API for Stream Implementers]: #stream_api_for_stream_implementers [Compatibility]: #stream_compatibility_with_older_node_js_versions -[Duplex]: #stream_class_stream_duplex +[`Duplex`]: #stream_class_stream_duplex [HTTP requests, on the client]: http.html#http_class_http_clientrequest [HTTP responses, on the server]: http.html#http_class_http_serverresponse -[Readable]: #stream_class_stream_readable +[`Readable`]: #stream_class_stream_readable [TCP sockets]: net.html#net_class_net_socket -[Transform]: #stream_class_stream_transform -[Writable]: #stream_class_stream_writable +[`Transform`]: #stream_class_stream_transform +[`Writable`]: #stream_class_stream_writable [child process stdin]: child_process.html#child_process_subprocess_stdin [child process stdout and stderr]: child_process.html#child_process_subprocess_stdout [crypto]: crypto.html diff --git a/doc/api/tls.md b/doc/api/tls.md index bdda8bd734..e22286adb4 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -422,8 +422,7 @@ added: v3.0.0 Updates the keys for encryption/decryption of the [TLS Session Tickets][]. The key's `Buffer` should be 48 bytes long. See `ticketKeys` option in -[tls.createServer](#tls_tls_createserver_options_secureconnectionlistener) for -more information on how it is used. +[`tls.createServer()`] for more information on how it is used. Changes to the ticket keys are effective only for future server connections. Existing or currently pending server connections will use the previous keys. @@ -582,7 +581,7 @@ an ephemeral key exchange in [Perfect Forward Secrecy][] on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; `null` is returned if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The -`name` property is available only when type is 'ECDH'. +`name` property is available only when type is `'ECDH'`. For example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }`. @@ -615,7 +614,7 @@ added: v0.11.4 Returns an object representing the peer's certificate. The returned object has some properties corresponding to the fields of the certificate. -If the full certificate chain was requested, each certificate will include a +If the full certificate chain was requested, each certificate will include an `issuerCertificate` property containing an object representing its issuer's certificate. @@ -637,7 +636,7 @@ For example: OU: 'Test TLS Certificate', CN: 'localhost' }, issuerCertificate: - { ... another certificate, possibly with a .issuerCertificate ... }, + { ... another certificate, possibly with an .issuerCertificate ... }, raw: < RAW DER buffer >, pubkey: < RAW DER buffer >, valid_from: 'Nov 11 09:52:22 2009 GMT', @@ -1016,7 +1015,7 @@ changes: - version: v7.3.0 pr-url: https://github.com/nodejs/node/pull/10294 description: If the `key` option is an array, individual entries do not - need a `passphrase` property anymore. Array entries can also + need a `passphrase` property anymore. `Array` entries can also just be `string`s or `Buffer`s now. - version: v5.2.0 pr-url: https://github.com/nodejs/node/pull/4099 @@ -1056,9 +1055,9 @@ changes: * `ca` {string|string[]|Buffer|Buffer[]} Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CAs are explicitly specified - 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 + using this option. The value can be a string or `Buffer`, or an `Array` of + strings and/or `Buffer`s. 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 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 @@ -1156,12 +1155,12 @@ changes: * `SNICallback(servername, cb)` {Function} A function that will be called if the client supports SNI TLS extension. Two arguments will be passed when called: `servername` and `cb`. `SNICallback` should invoke `cb(null, ctx)`, - where `ctx` is a SecureContext instance. (`tls.createSecureContext(...)` can - be used to get a proper SecureContext.) If `SNICallback` wasn't provided the - default callback with high-level API will be used (see below). + where `ctx` is a `SecureContext` instance. (`tls.createSecureContext(...)` + can be used to get a proper `SecureContext`.) If `SNICallback` wasn't + provided the default callback with high-level API will be used (see below). * `sessionTimeout` {number} An integer specifying the number of seconds after which the TLS session identifiers and TLS session tickets created by the - server will time out. See [SSL_CTX_set_timeout] for more details. + server will time out. See [`SSL_CTX_set_timeout`] for more details. * `ticketKeys`: A 48-byte `Buffer` instance consisting of a 16-byte prefix, a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS session tickets on multiple instances of the TLS server. @@ -1169,7 +1168,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 @@ -1371,13 +1370,16 @@ where `secureSocket` has the same API as `pair.cleartext`. [`'secureConnect'`]: #tls_event_secureconnect [`'secureConnection'`]: #tls_event_secureconnection +[`SSL_CTX_set_timeout`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_timeout.html [`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves +[`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback [`net.Server.address()`]: net.html#net_server_address [`net.Server`]: net.html#net_class_net_server [`net.Socket`]: net.html#net_class_net_socket [`server.getConnections()`]: net.html#net_server_getconnections_callback [`server.listen()`]: net.html#net_server_listen [`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve +[`tls.Server`]: #tls_class_tls_server [`tls.TLSSocket.getPeerCertificate()`]: #tls_tlssocket_getpeercertificate_detailed [`tls.TLSSocket`]: #tls_class_tls_tlssocket [`tls.connect()`]: #tls_tls_connect_options_callback @@ -1392,7 +1394,7 @@ where `secureSocket` has the same API as `pair.cleartext`. [OpenSSL Options]: crypto.html#crypto_openssl_options [OpenSSL cipher list format documentation]: https://www.openssl.org/docs/man1.1.0/apps/ciphers.html#CIPHER-LIST-FORMAT [Perfect Forward Secrecy]: #tls_perfect_forward_secrecy -[SSL_CTX_set_timeout]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_timeout.html +[RFC 5929]: https://tools.ietf.org/html/rfc5929 [SSL_METHODS]: https://www.openssl.org/docs/man1.1.0/ssl/ssl.html#Dealing-with-Protocol-Methods [Stream]: stream.html#stream_stream [TLS Session Tickets]: https://www.ietf.org/rfc/rfc5077.txt @@ -1400,6 +1402,3 @@ where `secureSocket` has the same API as `pair.cleartext`. [asn1.js]: https://npmjs.org/package/asn1.js [modifying the default cipher suite]: #tls_modifying_the_default_tls_cipher_suite [specific attacks affecting larger AES key sizes]: https://www.schneier.com/blog/archives/2009/07/another_new_aes.html -[tls.Server]: #tls_class_tls_server -[`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback -[RFC 5929]: https://tools.ietf.org/html/rfc5929 diff --git a/doc/api/tracing.md b/doc/api/tracing.md index f83e808dc8..7b30672ecc 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -8,14 +8,14 @@ Trace Event provides a mechanism to centralize tracing information generated by V8, Node.js core, and userspace code. Tracing can be enabled with the `--trace-event-categories` command-line flag -or by using the trace_events module. The `--trace-event-categories` flag accepts -a list of comma-separated category names. +or by using the `trace_events` module. The `--trace-event-categories` flag +accepts a list of comma-separated category names. The available categories are: * `node` - An empty placeholder. -* `node.async_hooks` - Enables capture of detailed [async_hooks] trace data. - The [async_hooks] events have a unique `asyncId` and a special triggerId +* `node.async_hooks` - Enables capture of detailed [`async_hooks`] trace data. + The [`async_hooks`] events have a unique `asyncId` and a special `triggerId` `triggerAsyncId` property. * `node.bootstrap` - Enables capture of Node.js bootstrap milestones. * `node.perf` - Enables capture of [Performance API] measurements. @@ -196,4 +196,4 @@ console.log(trace_events.getEnabledCategories()); [Performance API]: perf_hooks.html [V8]: v8.html -[async_hooks]: async_hooks.html +[`async_hooks`]: async_hooks.html diff --git a/doc/api/tty.md b/doc/api/tty.md index f8bc4feec3..91bca8284d 100644 --- a/doc/api/tty.md +++ b/doc/api/tty.md @@ -126,15 +126,15 @@ is updated whenever the `'resize'` event is emitted. added: v9.9.0 --> -* `env` {Object} A object containing the environment variables to check. +* `env` {Object} An object containing the environment variables to check. **Default:** `process.env`. * Returns: {number} Returns: -* 1 for 2, -* 4 for 16, -* 8 for 256, -* 24 for 16,777,216 +* `1` for 2, +* `4` for 16, +* `8` for 256, +* `24` for 16,777,216 colors supported. Use this to determine what colors the terminal supports. Due to the nature of diff --git a/doc/api/url.md b/doc/api/url.md index a7add464e8..64b7b444c5 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -86,8 +86,8 @@ The `URL` class is also available on the global object. In accordance with browser conventions, all properties of `URL` objects are implemented as getters and setters on the class prototype, rather than as -data properties on the object itself. Thus, unlike [legacy urlObject][]s, using -the `delete` keyword on any properties of `URL` objects (e.g. `delete +data properties on the object itself. Thus, unlike [legacy `urlObject`][]s, +using the `delete` keyword on any properties of `URL` objects (e.g. `delete myURL.protocol`, `delete myURL.pathname`, etc) has no effect but will still return `true`. @@ -346,7 +346,7 @@ console.log(myURL.port); // Prints 1234 ``` -The port value may be set as either a number or as a String containing a number +The port value may be set as either a number or as a string containing a number in the range `0` to `65535` (inclusive). Setting the value to the default port of the `URL` objects given `protocol` will result in the `port` value becoming the empty string (`''`). @@ -581,7 +581,7 @@ added: v7.10.0 * `iterable` {Iterable} An iterable object whose elements are key-value pairs 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 +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 @@ -644,16 +644,16 @@ Remove all name-value pairs whose name is `name`. * Returns: {Iterator} -Returns an ES6 Iterator over each of the name-value pairs in the query. -Each item of the iterator is a JavaScript Array. The first item of the Array -is the `name`, the second item of the Array is the `value`. +Returns an ES6 `Iterator` over each of the name-value pairs in the query. +Each item of the iterator is a JavaScript `Array`. The first item of the `Array` +is the `name`, the second item of the `Array` is the `value`. Alias for [`urlSearchParams[@@iterator]()`][`urlSearchParams@@iterator()`]. #### urlSearchParams.forEach(fn[, thisArg]) -* `fn` {Function} Function invoked for each name-value pair in the query. -* `thisArg` {Object} Object to be used as `this` value for when `fn` is called +* `fn` {Function} Invoked for each name-value pair in the query +* `thisArg` {Object} To be used as `this` value for when `fn` is called Iterates over each name-value pair in the query and invokes the given function. @@ -695,7 +695,7 @@ Returns `true` if there is at least one name-value pair whose name is `name`. * Returns: {Iterator} -Returns an ES6 Iterator over the names of each name-value pair. +Returns an ES6 `Iterator` over the names of each name-value pair. ```js const params = new URLSearchParams('foo=bar&foo=baz'); @@ -760,15 +760,15 @@ percent-encoded where necessary. * Returns: {Iterator} -Returns an ES6 Iterator over the values of each name-value pair. +Returns an ES6 `Iterator` over the values of each name-value pair. #### urlSearchParams\[Symbol.iterator\]() * Returns: {Iterator} -Returns an ES6 Iterator over each of the name-value pairs in the query string. -Each item of the iterator is a JavaScript Array. The first item of the Array -is the `name`, the second item of the Array is the `value`. +Returns an ES6 `Iterator` over each of the name-value pairs in the query string. +Each item of the iterator is a JavaScript `Array`. The first item of the `Array` +is the `name`, the second item of the `Array` is the `value`. Alias for [`urlSearchParams.entries()`][]. @@ -846,7 +846,7 @@ added: v7.6.0 Punycode encoded. **Default:** `false`. * Returns: {string} -Returns a customizable serialization of a URL String representation of a +Returns a customizable serialization of a URL `String` representation of a [WHATWG URL][] object. The URL object has both a `toString()` method and `href` property that return @@ -871,9 +871,9 @@ console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); ## Legacy URL API -### Legacy urlObject +### Legacy `urlObject` -The legacy urlObject (`require('url').Url`) is created and returned by the +The legacy `urlObject` (`require('url').Url`) is created and returned by the `url.parse()` function. #### urlObject.auth @@ -1039,7 +1039,7 @@ The formatting process operates as follows: `urlObject.host` is coerced to a string and appended to `result`. * If the `urlObject.pathname` property is a string that is not an empty string: * If the `urlObject.pathname` *does not start* with an ASCII forward slash - (`/`), then the literal string '/' is appended to `result`. + (`/`), then the literal string `'/'` is appended to `result`. * The value of `urlObject.pathname` is appended to `result`. * Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an [`Error`][] is thrown. @@ -1205,6 +1205,6 @@ console.log(myURL.origin); [WHATWG URL Standard]: https://url.spec.whatwg.org/ [WHATWG URL]: #url_the_whatwg_url_api [examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing -[legacy urlObject]: #url_legacy_urlobject +[legacy `urlObject`]: #url_legacy_urlobject [percent-encoded]: #whatwg-percent-encoding [stable sorting algorithm]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability diff --git a/doc/api/util.md b/doc/api/util.md index 8ed8c0b2c9..529f7b6fc7 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -20,10 +20,10 @@ added: v8.2.0 * `original` {Function} An `async` function * Returns: {Function} a callback style function -Takes an `async` function (or a function that returns a Promise) and returns a +Takes an `async` function (or a function that returns a `Promise`) and returns a function following the error-first callback style, i.e. taking -a `(err, value) => ...` callback as the last argument. In the callback, the -first argument will be the rejection reason (or `null` if the Promise +an `(err, value) => ...` callback as the last argument. In the callback, the +first argument will be the rejection reason (or `null` if the `Promise` resolved), and the second argument will be the resolved value. ```js @@ -185,7 +185,7 @@ added: v0.5.3 changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/17907 - description: The `%o` specifiers `depth` option is now set to Infinity. + description: The `%o` specifiers `depth` option is now set to `Infinity`. - version: v8.4.0 pr-url: https://github.com/nodejs/node/pull/14558 description: The `%o` and `%O` specifiers are supported now. @@ -200,18 +200,18 @@ The first argument is a string containing zero or more *placeholder* tokens. Each placeholder token is replaced with the converted value from the corresponding argument. Supported placeholders are: -* `%s` - String. -* `%d` - Number (integer or floating point value). +* `%s` - `String`. +* `%d` - `Number` (integer or floating point value). * `%i` - Integer. * `%f` - Floating point value. * `%j` - JSON. Replaced with the string `'[Circular]'` if the argument contains circular references. -* `%o` - Object. A string representation of an object +* `%o` - `Object`. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` with options `{ showHidden: true, showProxy: true }`. This will show the full object including non-enumerable properties and proxies. -* `%O` - Object. A string representation of an object with generic JavaScript +* `%O` - `Object`. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` without options. This will show the full object not including non-enumerable properties and proxies. * `%%` - single percent sign (`'%'`). This does not consume an argument. @@ -365,10 +365,11 @@ added: v0.3.0 changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/19259 - description: WeakMap and WeakSet entries can now be inspected as well. + description: The `WeakMap` and `WeakSet` entries can now be inspected + as well. - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/17907 - description: The `depth` default changed to Infinity. + description: The `depth` default changed to `Infinity`. - version: v9.9.0 pr-url: https://github.com/nodejs/node/pull/17576 description: The `compact` option is supported now. @@ -387,7 +388,7 @@ changes: description: The `showProxy` option is supported now. --> -* `object` {any} Any JavaScript primitive or Object. +* `object` {any} Any JavaScript primitive or `Object`. * `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`][] @@ -418,10 +419,10 @@ changes: 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. **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`. - **Default:** `Infinity`. + * `depth` {number} Specifies the number of visible nested `Object`s in an + `object`. This is useful to minimize the inspection output for large + complicated 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 @@ -640,7 +641,7 @@ util.inspect(obj); added: v6.6.0 --> -A Symbol that can be used to declare custom inspect functions, see +* {symbol} that can be used to declare custom inspect functions, see [Custom inspection functions on Objects][]. ### util.inspect.defaultOptions @@ -687,7 +688,7 @@ added: v8.0.0 * Returns: {Function} Takes a function following the common error-first callback style, i.e. taking -a `(err, value) => ...` callback as the last argument, and returns a version +an `(err, value) => ...` callback as the last argument, and returns a version that returns promises. ```js @@ -767,9 +768,7 @@ throw an error. added: v8.0.0 --> -* {symbol} - -A Symbol that can be used to declare custom promisified variants of functions, +* {symbol} that can be used to declare custom promisified variants of functions, see [Custom promisified functions][]. ## Class: util.TextDecoder @@ -876,7 +875,7 @@ supported encodings or an alias. ### textDecoder.decode([input[, options]]) * `input` {ArrayBuffer|DataView|TypedArray} An `ArrayBuffer`, `DataView` or - Typed Array instance containing the encoded data. + `TypedArray` instance containing the encoded data. * `options` {Object} * `stream` {boolean} `true` if additional chunks of data are expected. **Default:** `false`. diff --git a/doc/api/vm.md b/doc/api/vm.md index 68b25b6aa3..9e1249dc4e 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -162,20 +162,20 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); * `url` {string} URL used in module resolution and stack traces. **Default:** `'vm:module(i)'` where `i` is a context-specific ascending index. * `context` {Object} The [contextified][] object as returned by the - `vm.createContext()` method, to compile and evaluate this Module in. + `vm.createContext()` method, to compile and evaluate this `Module` in. * `lineOffset` {integer} Specifies the line number offset that is displayed - in stack traces produced by this Module. - * `columnOffset` {integer} Spcifies the column number offset that is displayed - in stack traces produced by this Module. - * `initalizeImportMeta` {Function} Called during evaluation of this Module to - initialize the `import.meta`. This function has the signature `(meta, - module)`, where `meta` is the `import.meta` object in the Module, and + in stack traces produced by this `Module`. + * `columnOffset` {integer} Specifies the column number offset that is + displayed in stack traces produced by this `Module`. + * `initalizeImportMeta` {Function} Called during evaluation of this `Module` + to initialize the `import.meta`. This function has the signature `(meta, + module)`, where `meta` is the `import.meta` object in the `Module`, and `module` is this `vm.Module` object. Creates a new ES `Module` object. *Note*: Properties assigned to the `import.meta` object that are objects may -allow the Module to access information outside the specified `context`, if the +allow the `Module` to access information outside the specified `context`, if the object is created in the top level context. Use `vm.runInContext()` to create objects in a specific context. @@ -217,8 +217,8 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); The specifiers of all dependencies of this module. The returned array is frozen to disallow any changes to it. -Corresponds to the [[RequestedModules]] field of [Source Text Module Record][]s -in the ECMAScript specification. +Corresponds to the `[[RequestedModules]]` field of +[Source Text Module Record][]s in the ECMAScript specification. ### module.error @@ -231,7 +231,7 @@ accessing this property will result in a thrown exception. The value `undefined` cannot be used for cases where there is not a thrown exception due to possible ambiguity with `throw undefined;`. -Corresponds to the [[EvaluationError]] field of [Source Text Module Record][]s +Corresponds to the `[[EvaluationError]]` field of [Source Text Module Record][]s in the ECMAScript specification. ### module.linkingStatus @@ -246,8 +246,8 @@ The current linking status of `module`. It will be one of the following values: - `'linked'`: `module.link()` has been called, and all its dependencies have been successfully linked. - `'errored'`: `module.link()` has been called, but at least one of its - dependencies failed to link, either because the callback returned a Promise - that is rejected, or because the Module the callback returned is invalid. + dependencies failed to link, either because the callback returned a `Promise` + that is rejected, or because the `Module` the callback returned is invalid. ### module.namespace @@ -289,9 +289,9 @@ The current status of the module. Will be one of: - `'errored'`: The module has been evaluated, but an exception was thrown. Other than `'errored'`, this status string corresponds to the specification's -[Source Text Module Record][]'s [[Status]] field. `'errored'` corresponds to -`'evaluated'` in the specification, but with [[EvaluationError]] set to a value -that is not `undefined`. +[Source Text Module Record][]'s `[[Status]]` field. `'errored'` corresponds to +`'evaluated'` in the specification, but with `[[EvaluationError]]` set to a +value that is not `undefined`. ### module.url diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 33dbdbef1d..0e66abdcfb 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,7 +178,7 @@ 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 @@ -287,10 +287,10 @@ added: v0.11.1 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `dictionary` option can be an ArrayBuffer. + description: The `dictionary` option can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `dictionary` option can be an Uint8Array now. + description: The `dictionary` option can be an `Uint8Array` now. - version: v5.11.0 pr-url: https://github.com/nodejs/node/pull/6069 description: The `finishFlush` option is supported now. @@ -473,17 +473,17 @@ Provides an object enumerating Zlib-related constants. added: v0.5.8 --> -Creates and returns a new [Deflate][] object with the given [`options`][]. +Creates and returns a new [`Deflate`][] object with the given [`options`][]. ## zlib.createDeflateRaw([options]) <!-- YAML added: v0.5.8 --> -Creates and returns a new [DeflateRaw][] object with the given [`options`][]. +Creates and returns a new [`DeflateRaw`][] object with the given [`options`][]. -An upgrade of zlib from 1.2.8 to 1.2.11 changed behavior when windowBits -is set to 8 for raw deflate streams. zlib would automatically set windowBits +An upgrade of zlib from 1.2.8 to 1.2.11 changed behavior when `windowBits` +is set to 8 for raw deflate streams. zlib would automatically set `windowBits` to 9 if was initially set to 8. Newer versions of zlib will throw an exception, so Node.js restored the original behavior of upgrading a value of 8 to 9, since passing `windowBits = 9` to zlib actually results in a compressed stream @@ -494,35 +494,35 @@ that effectively uses an 8-bit window only. added: v0.5.8 --> -Creates and returns a new [Gunzip][] object with the given [`options`][]. +Creates and returns a new [`Gunzip`][] object with the given [`options`][]. ## zlib.createGzip([options]) <!-- YAML added: v0.5.8 --> -Creates and returns a new [Gzip][] object with the given [`options`][]. +Creates and returns a new [`Gzip`][] object with the given [`options`][]. ## zlib.createInflate([options]) <!-- YAML added: v0.5.8 --> -Creates and returns a new [Inflate][] object with the given [`options`][]. +Creates and returns a new [`Inflate`][] object with the given [`options`][]. ## zlib.createInflateRaw([options]) <!-- YAML added: v0.5.8 --> -Creates and returns a new [InflateRaw][] object with the given [`options`][]. +Creates and returns a new [`InflateRaw`][] object with the given [`options`][]. ## zlib.createUnzip([options]) <!-- YAML added: v0.5.8 --> -Creates and returns a new [Unzip][] object with the given [`options`][]. +Creates and returns a new [`Unzip`][] object with the given [`options`][]. ## Convenience Methods @@ -542,13 +542,13 @@ added: v0.6.0 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.deflateSync(buffer[, options]) <!-- YAML @@ -556,18 +556,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Compress a chunk of data with [Deflate][]. +Compress a chunk of data with [`Deflate`][]. ### zlib.deflateRaw(buffer[, options], callback) <!-- YAML @@ -575,10 +575,10 @@ added: v0.6.0 changes: - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.deflateRawSync(buffer[, options]) <!-- YAML @@ -586,18 +586,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Compress a chunk of data with [DeflateRaw][]. +Compress a chunk of data with [`DeflateRaw`][]. ### zlib.gunzip(buffer[, options], callback) <!-- YAML @@ -605,13 +605,13 @@ added: v0.6.0 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.gunzipSync(buffer[, options]) <!-- YAML @@ -619,18 +619,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Decompress a chunk of data with [Gunzip][]. +Decompress a chunk of data with [`Gunzip`][]. ### zlib.gzip(buffer[, options], callback) <!-- YAML @@ -638,13 +638,13 @@ added: v0.6.0 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.gzipSync(buffer[, options]) <!-- YAML @@ -652,18 +652,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Compress a chunk of data with [Gzip][]. +Compress a chunk of data with [`Gzip`][]. ### zlib.inflate(buffer[, options], callback) <!-- YAML @@ -671,13 +671,13 @@ added: v0.6.0 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.inflateSync(buffer[, options]) <!-- YAML @@ -685,18 +685,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Decompress a chunk of data with [Inflate][]. +Decompress a chunk of data with [`Inflate`][]. ### zlib.inflateRaw(buffer[, options], callback) <!-- YAML @@ -704,13 +704,13 @@ added: v0.6.0 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.inflateRawSync(buffer[, options]) <!-- YAML @@ -718,18 +718,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Decompress a chunk of data with [InflateRaw][]. +Decompress a chunk of data with [`InflateRaw`][]. ### zlib.unzip(buffer[, options], callback) <!-- YAML @@ -737,13 +737,13 @@ added: v0.6.0 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> ### zlib.unzipSync(buffer[, options]) <!-- YAML @@ -751,18 +751,18 @@ added: v0.11.12 changes: - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/16042 - description: The `buffer` parameter can be an ArrayBuffer. + description: The `buffer` parameter can be an `ArrayBuffer`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12223 - description: The `buffer` parameter can be any TypedArray or DataView now. + description: The `buffer` parameter can be any `TypedArray` or `DataView`. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/12001 - description: The `buffer` parameter can be an Uint8Array now. + description: The `buffer` parameter can be an `Uint8Array` now. --> - `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} -Decompress a chunk of data with [Unzip][]. +Decompress a chunk of data with [`Unzip`][]. [`.flush()`]: #zlib_zlib_flush_kind_callback [`Accept-Encoding`]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3 @@ -770,16 +770,16 @@ Decompress a chunk of data with [Unzip][]. [`Buffer`]: buffer.html#buffer_class_buffer [`Content-Encoding`]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11 [`DataView`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView +[`Deflate`]: #zlib_class_zlib_deflate +[`DeflateRaw`]: #zlib_class_zlib_deflateraw +[`Gunzip`]: #zlib_class_zlib_gunzip +[`Gzip`]: #zlib_class_zlib_gzip +[`Inflate`]: #zlib_class_zlib_inflate +[`InflateRaw`]: #zlib_class_zlib_inflateraw [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray -[`options`]: #zlib_class_options -[DeflateRaw]: #zlib_class_zlib_deflateraw -[Deflate]: #zlib_class_zlib_deflate -[Gunzip]: #zlib_class_zlib_gunzip -[Gzip]: #zlib_class_zlib_gzip -[InflateRaw]: #zlib_class_zlib_inflateraw -[Inflate]: #zlib_class_zlib_inflate -[Memory Usage Tuning]: #zlib_memory_usage_tuning -[Unzip]: #zlib_class_zlib_unzip [`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size +[`Unzip`]: #zlib_class_zlib_unzip +[`options`]: #zlib_class_options [`zlib.bytesWritten`]: #zlib_zlib_byteswritten +[Memory Usage Tuning]: #zlib_memory_usage_tuning [zlib documentation]: https://zlib.net/manual.html#Constants |