diff --git a/cli/experimental_loader_module.md b/cli/experimental_loader_module.md new file mode 100644 index 00000000..9ff0800c --- /dev/null +++ b/cli/experimental_loader_module.md @@ -0,0 +1,7 @@ + + +Specify the `module` of a custom [experimental ECMAScript Module][] loader. +`module` may be either a path to a file, or an ECMAScript Module name. + diff --git a/cli/loader_file.md b/cli/loader_file.md deleted file mode 100644 index 8881c050..00000000 --- a/cli/loader_file.md +++ /dev/null @@ -1,6 +0,0 @@ - - -Specify the `file` of the custom [experimental ECMAScript Module][] loader. - diff --git a/cli/node_options_options.md b/cli/node_options_options.md index 6ff6d60e..77f0d903 100644 --- a/cli/node_options_options.md +++ b/cli/node_options_options.md @@ -38,6 +38,7 @@ Node.js options that are allowed are: * `--enable-fips` * `--es-module-specifier-resolution` * `--experimental-exports` +* `--experimental-loader` * `--experimental-modules` * `--experimental-policy` * `--experimental-repl-await` @@ -55,7 +56,6 @@ Node.js options that are allowed are: * `--inspect-port`, `--debug-port` * `--inspect-publish-uid` * `--inspect` -* `--loader` * `--max-http-header-size` * `--napi-modules` * `--no-deprecation` diff --git a/crypto/crypto_createcipheriv_algorithm_key_iv_options.md b/crypto/crypto_createcipheriv_algorithm_key_iv_options.md index fa593a99..87ff66cc 100644 --- a/crypto/crypto_createcipheriv_algorithm_key_iv_options.md +++ b/crypto/crypto_createcipheriv_algorithm_key_iv_options.md @@ -22,7 +22,7 @@ changes: * `algorithm` {string} * `key` {string | Buffer | TypedArray | DataView | KeyObject} -* `iv` {string | Buffer | TypedArray | DataView} +* `iv` {string | Buffer | TypedArray | DataView | null} * `options` {Object} [`stream.transform` options][] * Returns: {Cipher} diff --git a/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md b/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md index bfa4749f..aee98a98 100644 --- a/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md +++ b/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md @@ -21,8 +21,8 @@ changes: --> * `algorithm` {string} -* `key` {string | Buffer | TypedArray | DataView} -* `iv` {string | Buffer | TypedArray | DataView} +* `key` {string | Buffer | TypedArray | DataView | KeyObject} +* `iv` {string | Buffer | TypedArray | DataView | null} * `options` {Object} [`stream.transform` options][] * Returns: {Decipher} diff --git a/esm/experimental_loader_hooks.md b/esm/experimental_loader_hooks.md index 07e7001c..05209959 100644 --- a/esm/experimental_loader_hooks.md +++ b/esm/experimental_loader_hooks.md @@ -4,7 +4,7 @@ To customize the default module resolution, loader hooks can optionally be -provided via a `--loader ./loader-name.mjs` argument to Node.js. +provided via a `--experimental-loader ./loader-name.mjs` argument to Node.js. When hooks are used they only apply to ES module loading and not to any CommonJS modules loaded. diff --git a/esm/resolve_hook.md b/esm/resolve_hook.md index 61bf0a4a..aa123a6a 100644 --- a/esm/resolve_hook.md +++ b/esm/resolve_hook.md @@ -91,7 +91,7 @@ export async function resolve(specifier, With this loader, running: ```console -NODE_OPTIONS='--experimental-modules --loader ./custom-loader.mjs' node x.js +NODE_OPTIONS='--experimental-modules --experimental-loader ./custom-loader.mjs' node x.js ``` would load the module `x.js` as an ES module with relative resolution support diff --git a/fs/fs_futimessync_fd_atime_mtime.md b/fs/fs_futimessync_fd_atime_mtime.md index 05b0946d..3da01994 100644 --- a/fs/fs_futimessync_fd_atime_mtime.md +++ b/fs/fs_futimessync_fd_atime_mtime.md @@ -8,8 +8,8 @@ changes: --> * `fd` {integer} -* `atime` {integer} -* `mtime` {integer} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} [`fs.futimes()`] 的同步版本。返回 `undefined`。 diff --git a/fs/fs_symlink_target_path_type_callback.md b/fs/fs_symlink_target_path_type_callback.md index d7e2ef90..1454b07a 100644 --- a/fs/fs_symlink_target_path_type_callback.md +++ b/fs/fs_symlink_target_path_type_callback.md @@ -18,20 +18,28 @@ changes: * `callback` {Function} * `err` {Error} -异步的 symlink(2)。 +异步的 symlink(2),它会创建名为 `path` 的链接,该链接指向 `target`。 除了可能的异常,完成回调没有其他参数。 -`type` 参数仅在 Windows 上可用,在其他平台上会被忽略。 + +`type` 参数仅在 Windows 上可用,在其他平台上则会被忽略。 它可以被设置为 `'dir'`、`'file'` 或 `'junction'`。 如果未设置 `type` 参数,则 Node 将会自动检测 `target` 的类型并使用 `'file'` 或 `'dir'`。 如果 `target` 不存在,则将会使用 `'file'`。 -Windows 上使用 `'junction'` 要求目标路径是绝对路径。 -当使用 `'junction'` 时,`target` 参数将自动标准化为绝对路径。 +Windows 上的连接点要求目标路径是绝对路径。 +当使用 `'junction'` 时,`target` 参数将会自动地标准化为绝对路径。 -示例: +相对目标是相对于链接的父目录。 ```js -fs.symlink('./foo', './new-port', callback); +fs.symlink('./mew', './example/mewtwo', callback); ``` -它创建了一个名为 "new-port" 且指向 "foo" 的符号链接。 +上面的示例中,在 `example` 中创建了符号链接 `mewtwo`,它指向同一目录中的 `mew`: + +```bash +$ tree example/ +example/ +├── mew +└── mewtwo -> ./mew +``` diff --git a/fs/fs_utimessync_path_atime_mtime.md b/fs/fs_utimessync_path_atime_mtime.md index 98c7c8c5..6e7d1fa2 100644 --- a/fs/fs_utimessync_path_atime_mtime.md +++ b/fs/fs_utimessync_path_atime_mtime.md @@ -16,8 +16,8 @@ changes: --> * `path` {string|Buffer|URL} -* `atime` {integer} -* `mtime` {integer} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} 返回 `undefined`。 diff --git a/inspector/heap_profiler.md b/inspector/heap_profiler.md index cd21ff3e..b481d979 100644 --- a/inspector/heap_profiler.md +++ b/inspector/heap_profiler.md @@ -15,7 +15,7 @@ session.on('HeapProfiler.addHeapSnapshotChunk', (m) => { }); session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => { - console.log('Runtime.takeHeapSnapshot done:', err, r); + console.log('HeapProfiler.takeHeapSnapshot done:', err, r); session.disconnect(); fs.closeSync(fd); }); diff --git a/n-api/n_api_version_matrix.md b/n-api/n_api_version_matrix.md index bd275892..77047dfd 100644 --- a/n-api/n_api_version_matrix.md +++ b/n-api/n_api_version_matrix.md @@ -6,7 +6,7 @@ to recompile for new versions of Node.js which are listed as supporting a later version. | | 1 | 2 | 3 | 4 | 5 | -|:-----:|:-------:|:--------:|:--------:|:--------:|:---------:| +|-------|---------|----------|----------|----------|-----------| | v6.x | | | v6.14.2* | | | | v8.x | v8.0.0* | v8.10.0* | v8.11.2 | v8.16.0 | | | v9.x | v9.0.0* | v9.3.0* | v9.11.0* | | | diff --git a/process/process_throwdeprecation.md b/process/process_throwdeprecation.md index a51b1980..c843634b 100644 --- a/process/process_throwdeprecation.md +++ b/process/process_throwdeprecation.md @@ -21,7 +21,7 @@ undefined true > process.emitWarning('test', 'DeprecationWarning'); 抛出: -{ [DeprecationWarning: test] name: 'DeprecationWarning' } +[DeprecationWarning: test] { name: 'DeprecationWarning' } ``` diff --git a/stream/errors_while_reading.md b/stream/errors_while_reading.md index 83f83c85..206e4b54 100644 --- a/stream/errors_while_reading.md +++ b/stream/errors_while_reading.md @@ -1,19 +1,18 @@ -当 `readable._read()` 在执行期间发生的错误时,建议触发 `'error'` 事件而不是抛出错误。 -从 `readable._read()` 中抛出错误可能会导致无法预期的结果。 -使用`'error'` 事件可以确保对错误进行一致且可预测的处理。 +在 [`readable._read()`] 执行期间发生的错误必须通过 [`readable.destroy(err)`][readable-_destroy] 方法冒泡。 +从 [`readable._read()`] 中抛出 `Error` 或手动触发 `'error'` 事件会导致未定义的行为。 - ```js const { Readable } = require('stream'); const myReadable = new Readable({ read(size) { - if (checkSomeErrorCondition()) { - process.nextTick(() => this.emit('error', err)); - return; + const err = checkSomeErrorCondition(); + if (err) { + this.destroy(err); + } else { + // 做些处理。 } - // 各种处理。 } }); ``` diff --git a/stream/errors_while_writing.md b/stream/errors_while_writing.md index 68cc2ad3..c008dfab 100644 --- a/stream/errors_while_writing.md +++ b/stream/errors_while_writing.md @@ -1,10 +1,8 @@ -当 `writable._write()` 和 `writable._writev()` 在执行期间发生的错误时,建议调用回调函数并传入错误对象作为第一个参数。 -这样 `Writable` 就会触发 `'error'` 事件。 -从 `writable._write()` 中抛出错误可能会导致无法预期的结果。 -使用回调可以确保对错误进行一致且可预测的处理。 +在 [`writable._write()`]、[`writable._writev()`] 和 [`writable._final()`] 方法的处理期间发生的错误必须通过调用回调并将错误作为第一个参数传入来冒泡。 +从这些方法中抛出 `Error` 或手动触发 `'error'` 事件会导致未定义的行为。 -如果可读流 pipe 到可写流时可写流触发错误,则可读流将会被 unpipe。 +如果 `Readable` 流通过管道传送到 `Writable` 流时 `Writable` 触发了错误,则 `Readable` 流将会被取消管道。 ```js const { Writable } = require('stream'); @@ -12,7 +10,7 @@ const { Writable } = require('stream'); const myWritable = new Writable({ write(chunk, encoding, callback) { if (chunk.toString().indexOf('a') >= 0) { - callback(new Error('无效的数据块')); + callback(new Error('数据块是无效的')); } else { callback(); } diff --git a/stream/readable_push_chunk_encoding.md b/stream/readable_push_chunk_encoding.md index a58aca0b..58b71793 100644 --- a/stream/readable_push_chunk_encoding.md +++ b/stream/readable_push_chunk_encoding.md @@ -52,7 +52,8 @@ class SourceWrapper extends Readable { } ``` -`readable.push()` 只能被可读流的实现调用,且只能在 `readable._read()` 方法中调用。 +`readable.push()` 方法用于将内容推入内部的 buffer。 +它可以由 `readable._read()` 方法驱动。 对于非对象模式的流,如果 `readable.push()` 的 `chunk` 参数为 `undefined`,则它会被当成空字符串或 buffer。 详见 [`readable.push('')`]。 diff --git a/stream/stream_pipeline_streams_callback.md b/stream/stream_pipeline_streams_callback.md index bd25575e..c42a08f2 100644 --- a/stream/stream_pipeline_streams_callback.md +++ b/stream/stream_pipeline_streams_callback.md @@ -48,6 +48,10 @@ async function run() { run().catch(console.error); ``` +`stream.pipeline()` 将会在所有的流上调用 `stream.destroy(err)`,除了: +* 已触发 `'end'` 或 `'close'` 的 `Readable` 流。 +* 已触发 `'finish'` 或 `'close'` 的 `Writable` 流。 + 在调用 `callback` 之后,`stream.pipeline()` 会将悬挂的事件监听器留在流上。 在失败后重新使用流的情况下,这可能导致事件监听器泄漏和误吞的错误。 diff --git a/tls/tls_createsecurecontext_options.md b/tls/tls_createsecurecontext_options.md index b8aca6be..39a08f89 100644 --- a/tls/tls_createsecurecontext_options.md +++ b/tls/tls_createsecurecontext_options.md @@ -65,7 +65,7 @@ changes: order as their private keys in `key`. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail. - * `sigalgs` {string}` Colon-separated list of supported signature algorithms. + * `sigalgs` {string} Colon-separated list of supported signature algorithms. The list can contain digest algorithms (`SHA256`, `MD5` etc.), public key algorithms (`RSA-PSS`, `ECDSA` etc.), combination of both (e.g 'RSA+SHA384') or TLS v1.3 scheme names (e.g. `rsa_pss_pss_sha512`). diff --git a/tls/tlssocket_getcipher.md b/tls/tlssocket_getcipher.md index 60a0cd68..0b84b429 100644 --- a/tls/tlssocket_getcipher.md +++ b/tls/tlssocket_getcipher.md @@ -17,6 +17,6 @@ Returns an object containing information on the negotiated cipher suite. For example: `{ name: 'AES256-SHA', version: 'TLSv1.2' }`. See -[SSL_CIPHER_get_name](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html) + for more information. diff --git a/url/url_port.md b/url/url_port.md index 5a446071..3da28c0b 100644 --- a/url/url_port.md +++ b/url/url_port.md @@ -9,7 +9,7 @@ 端口值可以是空字符串,在这种情况下,端口取决于协议/规范: | 协议 | 端口 | -| :------- | :--- | +| -------- | ---- | | "ftp" | 21 | | "file" | | | "gopher" | 70 |