diff --git a/async_hooks/troubleshooting.md b/async_hooks/troubleshooting.md index 8d87b5fb..4e001a01 100644 --- a/async_hooks/troubleshooting.md +++ b/async_hooks/troubleshooting.md @@ -1,14 +1,14 @@ In most cases your application or library code should have no issues with `AsyncLocalStorage`. But in rare cases you may face situations when the -current store is lost in one of asynchronous operations. Then you should +current store is lost in one of asynchronous operations. In those cases, consider the following options. If your code is callback-based, it is enough to promisify it with [`util.promisify()`][], so it starts working with native promises. If you need to keep using callback-based API, or your code assumes -a custom thenable implementation, you should use [`AsyncResource`][] class +a custom thenable implementation, use the [`AsyncResource`][] class to associate the asynchronous operation with the correct execution context. diff --git a/child_process/subprocess_spawnargs.md b/child_process/subprocess_spawnargs.md index 6cd80641..91a3dbc0 100644 --- a/child_process/subprocess_spawnargs.md +++ b/child_process/subprocess_spawnargs.md @@ -1,6 +1,6 @@ * {Array} -The `subprocess.spawnargs` property represents the full list of command line +The `subprocess.spawnargs` property represents the full list of command-line arguments the child process was launched with. diff --git a/cli/.md b/cli/.md index a2f89206..5de9c2a7 100644 --- a/cli/.md +++ b/cli/.md @@ -3,5 +3,5 @@ added: v8.0.0 --> stdin 的别名。 -类似于在其他命令行工具中使用 `-`，这意味着将会从 stdin 读取脚本，且其余的选项会传给该脚本。 +类似于在其他命令行工具中使用 `-`，这意味着从 stdin 读取脚本，且其余的选项会传给该脚本。 diff --git a/cli/1.md b/cli/1.md index b018cd50..dbbfc141 100644 --- a/cli/1.md +++ b/cli/1.md @@ -4,5 +4,5 @@ added: v6.11.0 指示 node 选项的结束。 其余的参数会被传给脚本。 -如果在此之前没有提供脚本的文件名或 eval/print 脚本，则下一个参数将会被用作脚本的文件名。 +如果在此之前没有提供脚本的文件名或 eval/print 脚本，则下一个参数会被用作脚本的文件名。 diff --git a/cli/cpu_prof.md b/cli/cpu_prof.md index 6492d221..67e3b00d 100644 --- a/cli/cpu_prof.md +++ b/cli/cpu_prof.md @@ -7,10 +7,10 @@ added: v12.0.0 Starts the V8 CPU profiler on start up, and writes the CPU profile to disk before exit. -If `--cpu-prof-dir` is not specified, the generated profile will be placed +If `--cpu-prof-dir` is not specified, the generated profile is placed in the current working directory. -If `--cpu-prof-name` is not specified, the generated profile will be +If `--cpu-prof-name` is not specified, the generated profile is named `CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile`. ```console diff --git a/cli/cpu_prof_dir.md b/cli/cpu_prof_dir.md index d80b6425..e3c695ea 100644 --- a/cli/cpu_prof_dir.md +++ b/cli/cpu_prof_dir.md @@ -8,5 +8,5 @@ Specify the directory where the CPU profiles generated by `--cpu-prof` will be placed. The default value is controlled by the -[--diagnostic-dir](#cli_diagnostic_dir_directory) command line option. +[--diagnostic-dir](#cli_diagnostic_dir_directory) command-line option. diff --git a/cli/diagnostic_dir_directory.md b/cli/diagnostic_dir_directory.md index 44d4b010..b54ddfcf 100644 --- a/cli/diagnostic_dir_directory.md +++ b/cli/diagnostic_dir_directory.md @@ -1,5 +1,5 @@ -Set the directory to which all diagnostic output files will be written to. +Set the directory to which all diagnostic output files are written. Defaults to current working directory. Affects the default output directory of: diff --git a/cli/disable_proto_mode.md b/cli/disable_proto_mode.md index 213bf433..55b1539a 100644 --- a/cli/disable_proto_mode.md +++ b/cli/disable_proto_mode.md @@ -3,6 +3,6 @@ added: v13.12.0 --> Disable the `Object.prototype.__proto__` property. If `mode` is `delete`, the -property will be removed entirely. If `mode` is `throw`, accesses to the -property will throw an exception with the code `ERR_PROTO_ACCESS`. +property is removed entirely. If `mode` is `throw`, accesses to the +property throw an exception with the code `ERR_PROTO_ACCESS`. diff --git a/cli/experimental_specifier_resolution_mode.md b/cli/experimental_specifier_resolution_mode.md index 9515568c..8f8c945c 100644 --- a/cli/experimental_specifier_resolution_mode.md +++ b/cli/experimental_specifier_resolution_mode.md @@ -8,8 +8,8 @@ Sets the resolution algorithm for resolving ES module specifiers. Valid options are `explicit` and `node`. The default is `explicit`, which requires providing the full path to a -module. The `node` mode will enable support for optional file extensions and +module. The `node` mode enables support for optional file extensions and the ability to import a directory that has an index file. -Please see [customizing ESM specifier resolution][] for example usage. +See [customizing ESM specifier resolution][] for example usage. diff --git a/cli/heap_prof.md b/cli/heap_prof.md index 6a04cdf3..bb7354ed 100644 --- a/cli/heap_prof.md +++ b/cli/heap_prof.md @@ -7,10 +7,10 @@ added: v12.4.0 Starts the V8 heap profiler on start up, and writes the heap profile to disk before exit. -If `--heap-prof-dir` is not specified, the generated profile will be placed +If `--heap-prof-dir` is not specified, the generated profile is placed in the current working directory. -If `--heap-prof-name` is not specified, the generated profile will be +If `--heap-prof-name` is not specified, the generated profile is named `Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile`. ```console diff --git a/cli/heap_prof_dir.md b/cli/heap_prof_dir.md index c47c55c6..67941de6 100644 --- a/cli/heap_prof_dir.md +++ b/cli/heap_prof_dir.md @@ -8,5 +8,5 @@ Specify the directory where the heap profiles generated by `--heap-prof` will be placed. The default value is controlled by the -[--diagnostic-dir](#cli_diagnostic_dir_directory) command line option. +[--diagnostic-dir](#cli_diagnostic_dir_directory) command-line option. diff --git a/cli/max_old_space_size_size_in_megabytes.md b/cli/max_old_space_size_size_in_megabytes.md index adb47b6f..ec5066b7 100644 --- a/cli/max_old_space_size_size_in_megabytes.md +++ b/cli/max_old_space_size_size_in_megabytes.md @@ -32,5 +32,6 @@ $ node --max-old-space-size=1536 index.js + diff --git a/cli/node_options_options.md b/cli/node_options_options.md index a557224b..c5407e2d 100644 --- a/cli/node_options_options.md +++ b/cli/node_options_options.md @@ -2,20 +2,19 @@ added: v8.0.0 --> -A space-separated list of command line options. `options...` are interpreted -before command line options, so command line options will override or +A space-separated list of command-line options. `options...` are interpreted +before command-line options, so command-line options will override or compound after anything in `options...`. Node.js will exit with an error if an option that is not allowed in the environment is used, such as `-p` or a script file. -In case an option value happens to contain a space (for example a path listed -in `--require`), it must be escaped using double quotes. For example: +If an option value contains a space, it can be escaped using double quotes: ```bash NODE_OPTIONS='--require "./my path/file.js"' ``` -A singleton flag passed as a command line option will override the same flag +A singleton flag passed as a command-line option will override the same flag passed into `NODE_OPTIONS`: ```bash @@ -24,7 +23,7 @@ NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555 ``` A flag that can be passed multiple times will be treated as if its -`NODE_OPTIONS` instances were passed first, and then its command line +`NODE_OPTIONS` instances were passed first, and then its command-line instances afterwards: ```bash diff --git a/cli/node_pending_deprecation_1.md b/cli/node_pending_deprecation_1.md index 54ae2e2c..7905c938 100644 --- a/cli/node_pending_deprecation_1.md +++ b/cli/node_pending_deprecation_1.md @@ -6,7 +6,7 @@ When set to `1`, emit pending deprecation warnings. Pending deprecations are generally identical to a runtime deprecation with the notable exception that they are turned *off* by default and will not be emitted -unless either the `--pending-deprecation` command line flag, or the +unless either the `--pending-deprecation` command-line flag, or the `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations are used to provide a kind of selective "early warning" mechanism that developers may leverage to detect deprecated API usage. diff --git a/cli/openssl_conf_file.md b/cli/openssl_conf_file.md index 7354d360..5d3e4f9f 100644 --- a/cli/openssl_conf_file.md +++ b/cli/openssl_conf_file.md @@ -6,6 +6,6 @@ Load an OpenSSL configuration file on startup. Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is built with `./configure --openssl-fips`. -If the [`--openssl-config`][] command line option is used, the environment +If the [`--openssl-config`][] command-line option is used, the environment variable is ignored. diff --git a/cli/options.md b/cli/options.md index 8b873cf7..5b896392 100644 --- a/cli/options.md +++ b/cli/options.md @@ -7,7 +7,10 @@ changes: --> 所有选项（包括 V8 选项）都允许单词用短划线（`-`）或下划线（`_`）分隔。 +例如，`--pending-deprecation` 等效于 `--pending_deprecation`。 -例如，`--pending-deprecation` 等同于 `--pending_deprecation`。 - +If an option that takes a single value (such as `--max-http-header-size`) is +passed more than once, then the last passed value is used. Options from the +command line take precedence over options passed through the [`NODE_OPTIONS`][] +environment variable. diff --git a/cli/pending_deprecation.md b/cli/pending_deprecation.md index ce7034bd..984ef984 100644 --- a/cli/pending_deprecation.md +++ b/cli/pending_deprecation.md @@ -6,7 +6,7 @@ Emit pending deprecation warnings. Pending deprecations are generally identical to a runtime deprecation with the notable exception that they are turned *off* by default and will not be emitted -unless either the `--pending-deprecation` command line flag, or the +unless either the `--pending-deprecation` command-line flag, or the `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations are used to provide a kind of selective "early warning" mechanism that developers may leverage to detect deprecated API usage. diff --git a/cli/preserve_symlinks_main.md b/cli/preserve_symlinks_main.md index cd192627..86e5f4ca 100644 --- a/cli/preserve_symlinks_main.md +++ b/cli/preserve_symlinks_main.md @@ -9,8 +9,8 @@ This flag exists so that the main module can be opted-in to the same behavior that `--preserve-symlinks` gives to all other imports; they are separate flags, however, for backward compatibility with older Node.js versions. -`--preserve-symlinks-main` does not imply `--preserve-symlinks`; it -is expected that `--preserve-symlinks-main` will be used in addition to +`--preserve-symlinks-main` does not imply `--preserve-symlinks`; use +`--preserve-symlinks-main` in addition to `--preserve-symlinks` when it is not desirable to follow symlinks before resolving relative paths. diff --git a/cli/redirect_warnings_file.md b/cli/redirect_warnings_file.md index 0878dcd7..a3c7887c 100644 --- a/cli/redirect_warnings_file.md +++ b/cli/redirect_warnings_file.md @@ -9,5 +9,5 @@ warning will be written to stderr instead. The `file` name may be an absolute path. If it is not, the default directory it will be written to is controlled by the -[--diagnostic-dir](#cli_diagnostic_dir_directory) command line option. +[--diagnostic-dir](#cli_diagnostic_dir_directory) command-line option. diff --git a/crypto/crypto_default_encoding.md b/crypto/crypto_default_encoding.md index abad7d79..2609f443 100644 --- a/crypto/crypto_default_encoding.md +++ b/crypto/crypto_default_encoding.md @@ -9,7 +9,7 @@ The default encoding to use for functions that can take either strings or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods default to [`Buffer`][] objects. -The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility +The `crypto.DEFAULT_ENCODING` mechanism is provided for backward compatibility with legacy programs that expect `'latin1'` to be the default encoding. New applications should expect the default to be `'buffer'`. diff --git a/deprecations/dep0089_require_assert.md b/deprecations/dep0089_require_assert.md index 930ea54c..c026ef61 100644 --- a/deprecations/dep0089_require_assert.md +++ b/deprecations/dep0089_require_assert.md @@ -14,5 +14,5 @@ Type: Deprecation revoked Importing assert directly was not recommended as the exposed functions use loose equality checks. The deprecation was revoked because use of the `assert` -module is not discouraged, and the deprecation caused end user confusion. +module is not discouraged, and the deprecation caused developer confusion. diff --git a/dgram/note_about_udp_datagram_size.md b/dgram/note_about_udp_datagram_size.md index 7502b233..fafeb591 100644 --- a/dgram/note_about_udp_datagram_size.md +++ b/dgram/note_about_udp_datagram_size.md @@ -1,14 +1,14 @@ -`IPv4/v6` 数据包的最大尺寸取决于 `MTU`(Maximum Transmission Unit，最大传输单元)与 `Payload Length` 字段大小。 +IPv4/v6 数据包的最大尺寸取决于 `MTU`(Maximum Transmission Unit，最大传输单元)与 `Payload Length` 字段大小。 -- `Payload Length` 字段有 `16 位` 宽，指一个超过 64K 的包含 IP 头部和数据的负载 (65,507 字节 = 65,535 − 8 字节 UDP 头 − 20 字节 IP 头)。 +- `Payload Length` 字段有 16 位宽，这意味着不能超过 64K 的包含 IP 头部和数据的负载 (65,507 字节 = 65,535 − 8 字节 UDP 头 − 20 字节 IP 头)。 通常对于环回地址来说是这样，但这个长度的数据包对于大多数的主机和网络来说不切实际。 - `MTU` 指的是数据链路层为数据包提供的最大大小。 - 对于任意链路，`IPv4` 所托管的 `MTU` 最小为 `68` 个字节，推荐为 `576`（典型地，作为拨号上网应用的推荐值），无论它们是完整地还是分块地抵达。 + 对于任意链路，IPv4 所托管的 `MTU` 最小为 68 个字节，推荐为 576（典型地，作为拨号上网应用的推荐值），无论它们是完整地还是分块地抵达。 - 对于 `IPv6`，`MTU` 的最小值是 `1280` 个字节，然而，受托管的最小的碎片重组缓冲大小为 `1500` 个字节。 - 现今大多数的数据链路层技术（如以太网），都有 `1500` 的 `MTU` 最小值，因而 `68` 个字节显得非常小。 + 对于 IPv6，`MTU` 的最小值是 1280 个字节。但是，受托管的最小的碎片重组缓冲大小为 1500 个字节。 + 现今大多数的数据链路层技术（如以太网），都有 1500 的 `MTU` 最小值，因而 68 个字节显得非常小。 要提前知道数据包可能经过的每个链路的 MTU 是不可能的。 发送大于接受者 `MTU` 大小的数据包将不会起作用，因为数据包会被静默地丢失，而不会通知发送者该包未抵达目的地。 diff --git a/documentation/stability_index.md b/documentation/stability_index.md index 3fe55c32..1e2b3723 100644 --- a/documentation/stability_index.md +++ b/documentation/stability_index.md @@ -24,7 +24,7 @@ > 与 npm 生态系统的兼容性是最高的优先级。 在使用实验的特性时必须谨慎，特别是在模块中。 -终端用户可能不知道正在使用实验的特性。 +用户可能不知道正在使用实验的特性。 当实验的 API 发生修改时，可能会出现意外的故障或行为的改变。 为了避免此类意外，使用实验的特性可能需要命令行标志。 实验的特性也可能触发[警告][warning]。 diff --git a/domain/domain.md b/domain/domain.md index 3bd21c51..fa36e341 100644 --- a/domain/domain.md +++ b/domain/domain.md @@ -1,4 +1,5 @@ **This module is pending deprecation**. Once a replacement API has been -finalized, this module will be fully deprecated. Most end users should +finalized, this module will be fully deprecated. Most developers should **not** have cause to use this module. Users who absolutely must have the functionality that domains provide may rely on it for the time being but should expect to have to migrate to a different solution diff --git a/errors/err_invalid_package_config.md b/errors/err_invalid_package_config.md index 571aebf4..84ec86eb 100644 --- a/errors/err_invalid_package_config.md +++ b/errors/err_invalid_package_config.md @@ -1,4 +1,4 @@ -An invalid `package.json` file was found which failed parsing. +An invalid `package.json` file failed parsing. diff --git a/errors/err_missing_message_port_in_transfer_list.md b/errors/err_missing_message_port_in_transfer_list.md index 7ee41664..d675c87b 100644 --- a/errors/err_missing_message_port_in_transfer_list.md +++ b/errors/err_missing_message_port_in_transfer_list.md @@ -1,6 +1,6 @@ An object that needs to be explicitly listed in the `transferList` argument -was found in the object passed to a `postMessage()` call, but not provided in -the `transferList` for that call. Usually, this is a `MessagePort`. +is in the object passed to a `postMessage()` call, but is not provided +in the `transferList` for that call. Usually, this is a `MessagePort`. diff --git a/errors/err_valid_performance_entry_type.md b/errors/err_valid_performance_entry_type.md index bdd4f063..cedfe88c 100644 --- a/errors/err_valid_performance_entry_type.md +++ b/errors/err_valid_performance_entry_type.md @@ -1,5 +1,5 @@ While using the Performance Timing API (`perf_hooks`), no valid performance -entry types were found. +entry types are found. diff --git a/errors/error_capturestacktrace_targetobject_constructoropt.md b/errors/error_capturestacktrace_targetobject_constructoropt.md index 5e3d0c4d..bff24767 100644 --- a/errors/error_capturestacktrace_targetobject_constructoropt.md +++ b/errors/error_capturestacktrace_targetobject_constructoropt.md @@ -15,7 +15,7 @@ myObject.stack; // 类似 `new Error().stack` 可选的 `constructorOpt` 参数接受一个函数。 如果提供了，则 `constructorOpt` 之上包括自身在内的全部栈帧都会被生成的堆栈跟踪省略。 -`constructorOpt` 参数用在向最终用户隐藏错误生成的具体细节时非常有用。例如： +`constructorOpt` 参数用在向用户隐藏错误生成的具体细节时非常有用。例如： ```js diff --git a/events/eventemitter_defaultmaxlisteners.md b/events/eventemitter_defaultmaxlisteners.md index afc8be7a..3245bf5b 100644 --- a/events/eventemitter_defaultmaxlisteners.md +++ b/events/eventemitter_defaultmaxlisteners.md @@ -5,7 +5,7 @@ added: v0.11.2 默认情况下，每个事件可以注册最多 `10` 个监听器。 可以使用 [`emitter.setMaxListeners(n)`] 方法改变单个 `EventEmitter` 实例的限制。 可以使用 `EventEmitter.defaultMaxListeners` 属性改变所有 `EventEmitter` 实例的默认值。 -如果此值不是一个正数，则抛出 `TypeError`。 +如果此值不是一个正数，则抛出 `RangeError`。 设置 `EventEmitter.defaultMaxListeners` 要谨慎，因为会影响所有 `EventEmitter` 实例，包括之前创建的。 因而，优先使用 [`emitter.setMaxListeners(n)`] 而不是 `EventEmitter.defaultMaxListeners`。 diff --git a/events/eventemitter_listenercount_emitter_eventname.md b/events/eventemitter_listenercount_emitter_eventname.md index abb20e71..8cd1f6da 100644 --- a/events/eventemitter_listenercount_emitter_eventname.md +++ b/events/eventemitter_listenercount_emitter_eventname.md @@ -1,6 +1,6 @@ > Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. diff --git a/fs/filehandle_write_buffer_offset_length_position.md b/fs/filehandle_write_buffer_offset_length_position.md index 08981078..cbc2fd5b 100644 --- a/fs/filehandle_write_buffer_offset_length_position.md +++ b/fs/filehandle_write_buffer_offset_length_position.md @@ -1,12 +1,17 @@ -* `buffer` {Buffer|Uint8Array} + +* `buffer` {Buffer|Uint8Array|string|Object} * `offset` {integer} * `length` {integer} * `position` {integer} diff --git a/fs/filehandle_write_string_position_encoding.md b/fs/filehandle_write_string_position_encoding.md index 5a8f1b21..d81518c3 100644 --- a/fs/filehandle_write_string_position_encoding.md +++ b/fs/filehandle_write_string_position_encoding.md @@ -1,19 +1,23 @@ -* `string` {string} +* `string` {string|Object} * `position` {integer} * `encoding` {string} **默认值:** `'utf8'`。 * 返回: {Promise} 将 `string` 写入到文件。 -如果 `string` 不是一个字符串，则会抛出异常。 +如果 `string` 不是字符串或具有自有 `toString` 函数属性的对象，则抛出异常。 `Promise` 会被解决并带上一个对象，对象包含一个 `bytesWritten` 属性（指定写入的字节数）和一个 `buffer` 属性（指向写入的 `string`）。 diff --git a/fs/filehandle_writefile_data_options.md b/fs/filehandle_writefile_data_options.md index b97692a3..658ad717 100644 --- a/fs/filehandle_writefile_data_options.md +++ b/fs/filehandle_writefile_data_options.md @@ -1,19 +1,24 @@ -* `data` {string|Buffer|Uint8Array} + +* `data` {string|Buffer|Uint8Array|Object} * `options` {Object|string} * `encoding` {string|null} **默认值:** `'utf8'`。 * 返回: {Promise} 异步地将数据写入到一个文件，如果文件已存在则覆盖该文件。 -`data` 可以是字符串或 buffer。 -`Promise` 将会在成功时解决，且不带参数。 +`data` 可以是字符串、buffer、或具有自有 `toString` 函数属性的对象。 +`Promise` 会在成功时被解决，且不带参数。 如果 `data` 是 buffer，则 `encoding` 选项会被忽略。 diff --git a/fs/fs_copyfile_src_dest_mode_callback.md b/fs/fs_copyfile_src_dest_mode_callback.md index 923a3d38..752606c3 100644 --- a/fs/fs_copyfile_src_dest_mode_callback.md +++ b/fs/fs_copyfile_src_dest_mode_callback.md @@ -1,5 +1,10 @@ * `src` {string|Buffer|URL} 要拷贝的源文件名。 diff --git a/fs/fs_copyfilesync_src_dest_mode.md b/fs/fs_copyfilesync_src_dest_mode.md index 8c58dabe..24b15b1f 100644 --- a/fs/fs_copyfilesync_src_dest_mode.md +++ b/fs/fs_copyfilesync_src_dest_mode.md @@ -1,5 +1,10 @@ * `src` {string|Buffer|URL} 要拷贝的源文件名。 diff --git a/fs/fs_lchown_path_uid_gid_callback.md b/fs/fs_lchown_path_uid_gid_callback.md index fdfd4695..1a727b4b 100644 --- a/fs/fs_lchown_path_uid_gid_callback.md +++ b/fs/fs_lchown_path_uid_gid_callback.md @@ -11,6 +11,8 @@ changes: pr-url: https://github.com/nodejs/node/pull/7897 description: 参数 `callback` 不再是可选的。 如果不传入，则会触发弃用警告（id 为 DEP0013）。 + - version: v0.4.7 + description: Documentation-only deprecation. --> * `path` {string|Buffer|URL} diff --git a/fs/fs_lchownsync_path_uid_gid.md b/fs/fs_lchownsync_path_uid_gid.md index c325e477..17af037e 100644 --- a/fs/fs_lchownsync_path_uid_gid.md +++ b/fs/fs_lchownsync_path_uid_gid.md @@ -3,6 +3,8 @@ changes: - version: v10.6.0 pr-url: https://github.com/nodejs/node/pull/21498 description: This API is no longer deprecated. + - version: v0.4.7 + description: Documentation-only deprecation. --> * `path` {string|Buffer|URL} diff --git a/fs/fs_write_fd_buffer_offset_length_position_callback.md b/fs/fs_write_fd_buffer_offset_length_position_callback.md index 50d7034f..914c5075 100644 --- a/fs/fs_write_fd_buffer_offset_length_position_callback.md +++ b/fs/fs_write_fd_buffer_offset_length_position_callback.md @@ -1,6 +1,9 @@ * `fd` {integer} -* `string` {string} +* `string` {string|Object} * `position` {integer} * `encoding` {string} **默认值:** `'utf8'`。 * `callback` {Function} @@ -28,7 +32,7 @@ changes: * `string` {string} 将 `string` 写入到 `fd` 指定的文件。 -如果 `string` 不是一个字符串，则会抛出异常。 +如果 `string` 不是字符串或具有自有 `toString` 函数属性的对象，则抛出异常。 `position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `typeof position !== 'number'`，则数据会被写入当前的位置。 diff --git a/fs/fs_writefile_file_data_options_callback.md b/fs/fs_writefile_file_data_options_callback.md index 5a394060..66cc5cce 100644 --- a/fs/fs_writefile_file_data_options_callback.md +++ b/fs/fs_writefile_file_data_options_callback.md @@ -1,6 +1,9 @@ * `fd` {integer} -* `buffer` {Buffer|TypedArray|DataView} +* `buffer` {Buffer|TypedArray|DataView|string|Object} * `offset` {integer} * `length` {integer} * `position` {integer} diff --git a/fs/fs_writesync_fd_string_position_encoding.md b/fs/fs_writesync_fd_string_position_encoding.md index 32369fd1..a7838c3e 100644 --- a/fs/fs_writesync_fd_string_position_encoding.md +++ b/fs/fs_writesync_fd_string_position_encoding.md @@ -1,6 +1,10 @@ * `fd` {integer} -* `string` {string} +* `string` {string|Object} * `position` {integer} * `encoding` {string} * 返回: {number} 写入的字节数。 diff --git a/fs/fspromises_copyfile_src_dest_mode.md b/fs/fspromises_copyfile_src_dest_mode.md index 4410f19b..9a25d41c 100644 --- a/fs/fspromises_copyfile_src_dest_mode.md +++ b/fs/fspromises_copyfile_src_dest_mode.md @@ -1,5 +1,10 @@ * `src` {string|Buffer|URL} 要拷贝的源文件名。 diff --git a/fs/fspromises_writefile_file_data_options.md b/fs/fspromises_writefile_file_data_options.md index d7f268e3..66ba16b1 100644 --- a/fs/fspromises_writefile_file_data_options.md +++ b/fs/fspromises_writefile_file_data_options.md @@ -1,13 +1,17 @@ * `file` {string|Buffer|URL|FileHandle} 文件名或 `FileHandle`。 -* `data` {string|Buffer|Uint8Array} +* `data` {string|Buffer|Uint8Array|Object} * `options` {Object|string} * `encoding` {string|null} **默认值:** `'utf8'`。 * `mode` {integer} **默认值:** `0o666`。 @@ -15,8 +19,8 @@ changes: * 返回: {Promise} 异步地将数据写入到一个文件，如果文件已存在则覆盖该文件。 -`data` 可以是字符串或 buffer。 -`Promise` 将会在成功时解决，且不带参数。 +`data` 可以是字符串、buffer、或具有自有 `toString` 函数属性的对象。 +`Promise` 会在成功时被解决，且不带参数。 如果 `data` 是 buffer，则 `encoding` 选项会被忽略。 diff --git a/module/module_findsourcemap_path_error.md b/module/module_findsourcemap_path_error.md index de845cf3..66e5454f 100644 --- a/module/module_findsourcemap_path_error.md +++ b/module/module_findsourcemap_path_error.md @@ -12,8 +12,8 @@ added: should be fetched. The `error` instance should be passed as the second parameter to `findSourceMap` -in exceptional flows, e.g., when an overridden +in exceptional flows, such as when an overridden [`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to -the module cache until they are successfully loaded, in these cases source maps -will be associated with the `error` instance along with the `path`. +the module cache until they are successfully loaded. In these cases, source maps +are associated with the `error` instance along with the `path`. diff --git a/modules/addenda_package_manager_tips.md b/modules/addenda_package_manager_tips.md index 976c3af3..de47d1f7 100644 --- a/modules/addenda_package_manager_tips.md +++ b/modules/addenda_package_manager_tips.md @@ -12,7 +12,7 @@ Node.js 的 `require()` 函数的语义被设计得足够通用化，可以支 为了安装包 `foo`，可能需要安装一个指定版本的 `bar` 包。 `bar` 包也可能有依赖，且在某些情况下，依赖可能有冲突或形成循环。 -因为 Node.js 会查找它所加载的模块的实际路径（也就是说会解析符号链接），然后在 `node_modules` 目录中寻找它们的依赖，[如下所述](#modules_loading_from_node_modules_folders)，这种情况使用以下体系结构很容易解决： +因为 Node.js 会查找它所加载的模块的实际路径（也就是说会解析符号链接），然后[在 `node_modules` 目录中寻找它们的依赖](#modules_loading_from_node_modules_folders)，这种情况可以使用以下体系结构解决： * `/usr/lib/node/foo/1.2.3/` - `foo` 包的内容，版本 1.2.3。 * `/usr/lib/node/bar/4.3.2/` - `foo` 依赖的 `bar` 包的内容。 diff --git a/modules/source_map_v3_support.md b/modules/source_map_v3_support.md index 48a37225..b3fe9d63 100644 --- a/modules/source_map_v3_support.md +++ b/modules/source_map_v3_support.md @@ -1,6 +1,6 @@ This section was moved to -[Modules: `module` core module](modules_module.html#modules_module_source_map_v3_support). +[Modules: `module` core module](module.html#module_source_map_v3_support). * `module.findSourceMap(path[, error])` diff --git a/n-api/module_registration.md b/n-api/module_registration.md index 42bac791..d70c47ce 100644 --- a/n-api/module_registration.md +++ b/n-api/module_registration.md @@ -25,8 +25,16 @@ provided by the addon: ```c napi_value Init(napi_env env, napi_value exports) { napi_status status; - napi_property_descriptor desc = - {"hello", NULL, Method, NULL, NULL, NULL, napi_default, NULL}; + napi_property_descriptor desc = { + "hello", + NULL, + Method, + NULL, + NULL, + NULL, + napi_writable | napi_enumerable | napi_configurable, + NULL + }; status = napi_define_properties(env, exports, 1, &desc); if (status != napi_ok) return NULL; return exports; @@ -53,7 +61,7 @@ To define a class so that new instances can be created (often used with napi_value Init(napi_env env, napi_value exports) { napi_status status; napi_property_descriptor properties[] = { - { "value", NULL, NULL, GetValue, SetValue, NULL, napi_default, NULL }, + { "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL }, DECLARE_NAPI_METHOD("plusOne", PlusOne), DECLARE_NAPI_METHOD("multiply", Multiply), }; diff --git a/n-api/n_api_version_matrix.md b/n-api/n_api_version_matrix.md index 55ff97c4..8e82bdc7 100644 --- a/n-api/n_api_version_matrix.md +++ b/n-api/n_api_version_matrix.md @@ -5,16 +5,92 @@ from version 3 with some additions. This means that it is not necessary to recompile for new versions of Node.js which are listed as supporting a later version. -| | 1 | 2 | 3 | 4 | 5 | 6 | -|-------|----------|----------|----------|----------|-----------|-----------| -| v6.x | | | v6.14.2* | | | | -| v8.x | v8.6.0** | v8.10.0* | v8.11.2 | v8.16.0 | | | -| v9.x | v9.0.0* | v9.3.0* | v9.11.0* | | | | -| v10.x | v10.0.0 | v10.0.0 | v10.0.0 | v10.16.0 | v10.17.0 | v10.20.0 | -| v11.x | v11.0.0 | v11.0.0 | v11.0.0 | v11.8.0 | | | -| v12.x | v12.0.0 | v12.0.0 | v12.0.0 | v12.0.0 | v12.11.0 | v12.17.0 | -| v13.x | v13.0.0 | v13.0.0 | v13.0.0 | v13.0.0 | v13.0.0 | | -| v14.x | v14.0.0 | v14.0.0 | v14.0.0 | v14.0.0 | v14.0.0 | v14.0.0 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
123456
v6.xv6.14.2*
v8.xv8.6.0**v8.10.0*v8.11.2v8.16.0
v9.xv9.0.0*v9.3.0*v9.11.0*
v10.xv10.0.0v10.0.0v10.0.0v10.16.0v10.17.0v10.20.0
v11.xv11.0.0v11.0.0v11.0.0v11.8.0
v12.xv12.0.0v12.0.0v12.0.0v12.0.0v12.11.0v12.17.0
v13.xv13.0.0v13.0.0v13.0.0v13.0.0v13.0.0
v14.xv14.0.0v14.0.0v14.0.0v14.0.0v14.0.0v14.0.0
\* N-API was experimental. @@ -22,6 +98,18 @@ listed as supporting a later version. version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend N-API version 3 or later. +Each API documented for N-API will have a header named `added in:`, and APIs +which are stable will have the additional header `N-API version:`. +APIs are directly usable when using a Node.js version which supports +the N-API version shown in `N-API version:` or higher. +When using a Node.js version that does not support the +`N-API version:` listed or if there is no `N-API version:` listed, +then the API will only be available if +`#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h` +or `js_native_api.h`. If an API appears not to be available on +a version of Node.js which is later than the one shown in `added in:` then +this is most likely the reason for the apparent absence. + The N-APIs associated strictly with accessing ECMAScript features from native code can be found separately in `js_native_api.h` and `js_native_api_types.h`. The APIs defined in these headers are included in `node_api.h` and diff --git a/n-api/napi_detach_arraybuffer.md b/n-api/napi_detach_arraybuffer.md index 4cac3db8..a4a04f09 100644 --- a/n-api/napi_detach_arraybuffer.md +++ b/n-api/napi_detach_arraybuffer.md @@ -2,10 +2,10 @@ added: - v13.0.0 - v12.16.0 + - v10.22.0 +napiVersion: 7 --> -> Stability: 1 - Experimental - ```c napi_status napi_detach_arraybuffer(napi_env env, napi_value arraybuffer) diff --git a/n-api/napi_is_detached_arraybuffer.md b/n-api/napi_is_detached_arraybuffer.md index 490475b8..75472d00 100644 --- a/n-api/napi_is_detached_arraybuffer.md +++ b/n-api/napi_is_detached_arraybuffer.md @@ -2,10 +2,10 @@ added: - v13.3.0 - v12.16.0 + - v10.22.0 +napiVersion: 7 --> -> Stability: 1 - Experimental - ```c napi_status napi_is_detached_arraybuffer(napi_env env, napi_value arraybuffer, diff --git a/n-api/napi_property_attributes.md b/n-api/napi_property_attributes.md index 57017f70..edde0931 100644 --- a/n-api/napi_property_attributes.md +++ b/n-api/napi_property_attributes.md @@ -1,3 +1,9 @@ + ```c typedef enum { @@ -9,6 +15,14 @@ typedef enum { // Used with napi_define_class to distinguish static properties // from instance properties. Ignored by napi_define_properties. napi_static = 1 << 10, + + // Default for class methods. + napi_default_method = napi_writable | napi_configurable, + + // Default for object properties, like in JS obj[prop]. + napi_default_property = napi_writable | + napi_enumerable | + napi_configurable, } napi_property_attributes; ``` @@ -27,4 +41,8 @@ They can be one or more of the following bitflags: * `napi_static`: The property will be defined as a static property on a class as opposed to an instance property, which is the default. This is used only by [`napi_define_class`][]. It is ignored by `napi_define_properties`. +* `napi_default_method`: Like a method in a JS class, the property is + configurable and writeable, but not enumerable. +* `napi_default_property`: Like a property set via assignment in JavaScript, the + property is writable, enumerable, and configurable. diff --git a/n-api/working_with_javascript_properties.md b/n-api/working_with_javascript_properties.md index b3777ec0..8ab578e2 100644 --- a/n-api/working_with_javascript_properties.md +++ b/n-api/working_with_javascript_properties.md @@ -127,8 +127,8 @@ if (status != napi_ok) return status; // Set the properties napi_property_descriptor descriptors[] = { - { "foo", NULL, NULL, NULL, NULL, fooValue, napi_default, NULL }, - { "bar", NULL, NULL, NULL, NULL, barValue, napi_default, NULL } + { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL }, + { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL } } status = napi_define_properties(env, obj, diff --git a/path/path_basename_path_ext.md b/path/path_basename_path_ext.md index 0ad63c42..8834685b 100644 --- a/path/path_basename_path_ext.md +++ b/path/path_basename_path_ext.md @@ -22,5 +22,16 @@ path.basename('/目录1/目录2/文件.html', '.html'); // 返回: '文件' ``` +尽管 Windows 通常以不区分大小写的方式处理文件名（包括文件扩展名），但是此函数不会这样。 +例如，`C:\\文件.html` 和 `C:\\文件.HTML` 指向相同的文件，但是 `basename` 会将扩展名视为区分大小写的字符串： + +```js +path.win32.basename('C:\\文件.html', '.html'); +// 返回: '文件' + +path.win32.basename('C:\\文件.HTML', '.html'); +// 返回: '文件.HTML' +``` + 如果 `path` 不是字符串、或给定了 `ext` 但不是字符串，则抛出 [`TypeError`]。 diff --git a/perf_hooks/performance_eventlooputilization_utilization1_utilization2.md b/perf_hooks/performance_eventlooputilization_utilization1_utilization2.md new file mode 100644 index 00000000..76e430f3 --- /dev/null +++ b/perf_hooks/performance_eventlooputilization_utilization1_utilization2.md @@ -0,0 +1,55 @@ + + +* `utilization1` {Object} The result of a previous call to `eventLoopUtilization()` +* `utilization2` {Object} The result of a previous call to `eventLoopUtilization()` + prior to `util1` +* Returns {Object} + * `idle` {number} + * `active` {number} + * `utilization` {number} + +The `eventLoopUtilization()` method returns an object that contains the +cumulative duration of time the event loop has been both idle and active as a +high resolution milliseconds timer. The `utilization` value is the calculated +Event Loop Utilization (ELU). If bootstrapping has not yet finished, the +properties have the value of 0. + +`utilization1` and `utilization2` are optional parameters. + +If `utilization1` is passed, then the delta between the current call's `active` +and `idle` times, as well as the corresponding `utilization` value are +calculated and returned (similar to [`process.hrtime()`][]). + +If `utilization1` and `utilization2` are both passed, then the delta is +calculated between the two arguments. This is a convenience option because, +unlike [`process.hrtime()`][], calculating the ELU is more complex than a +single subtraction. + +ELU is similar to CPU utilization, except that it only measures event loop +statistics and not CPU usage. It represents the percentage of time the event +loop has spent outside the event loop's event provider (e.g. `epoll_wait`). +No other CPU idle time is taken into consideration. The following is an example +of how a mostly idle process will have a high ELU. + +```js +'use strict'; +const { eventLoopUtilization } = require('perf_hooks').performance; +const { spawnSync } = require('child_process'); + +setImmediate(() => { + const elu = eventLoopUtilization(); + spawnSync('sleep', ['5']); + console.log(eventLoopUtilization(elu).utilization); +}); +``` + +Although the CPU is mostly idle while running this script, the value of +`utilization` is 1. This is because the call to [`child_process.spawnSync()`][] +blocks the event loop from proceeding. + +Passing in a user-defined object instead of the result of a previous call to +`eventLoopUtilization()` will lead to undefined behavior. The return values +are not guaranteed to reflect any correct state of the event loop. + diff --git a/process/process_release.md b/process/process_release.md index ffc28fa0..b89b52b1 100644 --- a/process/process_release.md +++ b/process/process_release.md @@ -19,19 +19,20 @@ changes: * `libUrl` {string} 指向一个_`node.lib`_文件的绝对 URL，匹配当前发布的结构和版本信息。此文件用于编译 Node.js 本地插件。这个属性只在 Windows 版本中存在，在其他平台中无效。 * `lts` {string} 标识当前发布的 [LTS][] 标签的字符串。  只有 LTS 版本存在这个属性，其他所有版本类型（包括当前版本）这个属性都是 `undefined`。 -  当前的有效值有： - - `'Argon'` 用于 4.2.0 开始的 4.x LTS 版本。 - - `'Boron'` 用于 6.9.0 开始的 6.x LTS 版本。 - - `'Carbon'` 用于 8.9.1 开始的 8.x LTS 版本。 +  有效值包括 LTS 发行代号（包括不再受支持的代号）。 + 这些代号的非穷举示例包括： + * `'Dubnium'` 用于 10.13.0 开始的 10.x LTS 版本。 + * `'Erbium'` 用于 12.13.0 开始的 12.x LTS 版本。 + 有关其他的 LTS 发行代号，参见 [Node.js 更新日志的存档](https://github.com/nodejs/node/blob/master/doc/changelogs/CHANGELOG_ARCHIVE.md)。 ```js { name: 'node', - lts: 'Argon', - sourceUrl: 'https://nodejs.org/download/release/v4.4.5/node-v4.4.5.tar.gz', - headersUrl: 'https://nodejs.org/download/release/v4.4.5/node-v4.4.5-headers.tar.gz', - libUrl: 'https://nodejs.org/download/release/v4.4.5/win-x64/node.lib' + lts: 'Erbium', + sourceUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1.tar.gz', + headersUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1-headers.tar.gz', + libUrl: 'https://nodejs.org/download/release/v12.18.1/win-x64/node.lib' } ``` diff --git a/punycode/punycode.md b/punycode/punycode.md index 654e6e1b..bee09b62 100644 --- a/punycode/punycode.md +++ b/punycode/punycode.md @@ -1,8 +1,5 @@ diff --git a/readline/tty_keybindings.md b/readline/tty_keybindings.md index ef2e87a8..d01a4868 100644 --- a/readline/tty_keybindings.md +++ b/readline/tty_keybindings.md @@ -85,7 +85,7 @@ ctrl + w or ctrl + backspace - Delete backwards to a word boundary + Delete backward to a word boundary ctrl + backspace Doesn't work on Linux, Mac and Windows diff --git a/repl/repl_start_options.md b/repl/repl_start_options.md index a3030173..d8c675b9 100644 --- a/repl/repl_start_options.md +++ b/repl/repl_start_options.md @@ -11,6 +11,9 @@ changes: - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/19187 description: The `REPL_MAGIC_MODE` `replMode` was removed. + - version: v6.3.0 + pr-url: https://github.com/nodejs/node/pull/6635 + description: The `breakEvalOnSigint` option is supported now. - version: v5.8.0 pr-url: https://github.com/nodejs/node/pull/5388 description: The `options` parameter is optional now. diff --git a/repl/reverse_i_search.md b/repl/reverse_i_search.md index e6ad1ae1..8c0159e9 100644 --- a/repl/reverse_i_search.md +++ b/repl/reverse_i_search.md @@ -3,8 +3,8 @@ added: v13.6.0 --> The REPL supports bi-directional reverse-i-search similar to [ZSH][]. It is -triggered with ` + R` to search backwards and ` + S` to search -forwards. +triggered with ` + R` to search backward and ` + S` to search +forward. Duplicated history entires will be skipped. diff --git a/repl/starting_multiple_repl_instances_against_a_single_running_instance.md b/repl/starting_multiple_repl_instances_against_a_single_running_instance.md index 936a4c2a..9ab4a0ce 100644 --- a/repl/starting_multiple_repl_instances_against_a_single_running_instance.md +++ b/repl/starting_multiple_repl_instances_against_a_single_running_instance.md @@ -45,5 +45,5 @@ net.createServer((socket) => { 例子，在一个 `net.Server` 实例和一个 `net.Socket` 实例上运行一个全特性的（`terminal`）REPL，详见：。 -例子，在 [curl(1)][] 上运行一个 REPL 实例，详见：。 +例子，在 [`curl(1)`][] 上运行一个 REPL 实例，详见：。 diff --git a/synopsis/usage.md b/synopsis/usage.md index c58f5b7d..bd769bda 100644 --- a/synopsis/usage.md +++ b/synopsis/usage.md @@ -4,5 +4,5 @@ `node [options] [V8 options] [script.js | -e "script" | - ] [arguments]` -详见[命令行选项][Command Line Options]文档。 +详见[命令行选项][Command-line options]文档。 diff --git a/timers/timeout_symbol_toprimitive.md b/timers/timeout_symbol_toprimitive.md index ffe52e53..70555a02 100644 --- a/timers/timeout_symbol_toprimitive.md +++ b/timers/timeout_symbol_toprimitive.md @@ -2,13 +2,12 @@ added: v14.9.0 --> -* Returns: {integer} number that can be used to reference this `timeout` +* Returns: {integer} a number that can be used to reference this `timeout` -Coerce a `Timeout` to a primitive, a primitive will be generated that -can be used to clear the `Timeout`. -The generated number can only be used in the same thread where timeout -was created. Therefore to use it cross [`worker_threads`][] it has -to first be passed to a correct thread. -This allows enhanced compatibility with browser's `setTimeout()`, and -`setInterval()` implementations. +Coerce a `Timeout` to a primitive. The primitive can be used to +clear the `Timeout`. The primitive can only be used in the +same thread where the timeout was created. Therefore, to use it +across [`worker_threads`][] it must first be passed to the correct +thread. This allows enhanced compatibility with browser +`setTimeout()` and `setInterval()` implementations. diff --git a/wasi/class_wasi.md b/wasi/class_wasi.md index 69b97f3d..bfc79c1e 100644 --- a/wasi/class_wasi.md +++ b/wasi/class_wasi.md @@ -7,6 +7,6 @@ added: The `WASI` class provides the WASI system call API and additional convenience methods for working with WASI-based applications. Each `WASI` instance represents a distinct sandbox environment. For security purposes, each `WASI` -instance must have its command line arguments, environment variables, and +instance must have its command-line arguments, environment variables, and sandbox directory structure configured explicitly. diff --git a/wasi/new_wasi_options.md b/wasi/new_wasi_options.md index 588aa3c2..795f9ee5 100644 --- a/wasi/new_wasi_options.md +++ b/wasi/new_wasi_options.md @@ -6,7 +6,7 @@ added: * `options` {Object} * `args` {Array} An array of strings that the WebAssembly application will - see as command line arguments. The first argument is the virtual path to the + see as command-line arguments. The first argument is the virtual path to the WASI command itself. **Default:** `[]`. * `env` {Object} An object similar to `process.env` that the WebAssembly application will see as its environment. **Default:** `{}`.