diff --git a/assert/assert_fail_actual_expected_message_operator_stackstartfn.md b/assert/assert_fail_actual_expected_message_operator_stackstartfn.md index c4b36f22..90053b39 100644 --- a/assert/assert_fail_actual_expected_message_operator_stackstartfn.md +++ b/assert/assert_fail_actual_expected_message_operator_stackstartfn.md @@ -7,22 +7,22 @@ changes: deprecated and emits a warning. --> +> Stability: 0 - Deprecated: Use `assert.fail([message])` or other assert +> functions instead. + * `actual` {any} * `expected` {any} * `message` {string|Error} * `operator` {string} **Default:** `'!='` * `stackStartFn` {Function} **Default:** `assert.fail` -> Stability: 0 - Deprecated: Use `assert.fail([message])` or other assert -> functions instead. - If `message` is falsy, the error message is set as the values of `actual` and `expected` separated by the provided `operator`. If just the two `actual` and `expected` arguments are provided, `operator` will default to `'!='`. If `message` is provided as third argument it will be used as the error message and the other arguments will be stored as properties on the thrown object. If `stackStartFn` is provided, all stack frames above that function will be -removed from stacktrace (see [`Error.captureStackTrace`]). If no arguments are +removed from stacktrace (see [`Error.captureStackTrace`][]). If no arguments are given, the default message `Failed` will be used. ```js diff --git a/buffer/buf_lastindexof_value_byteoffset_encoding.md b/buffer/buf_lastindexof_value_byteoffset_encoding.md index 1c3e0a8e..f4d3fcde 100644 --- a/buffer/buf_lastindexof_value_byteoffset_encoding.md +++ b/buffer/buf_lastindexof_value_byteoffset_encoding.md @@ -7,7 +7,7 @@ changes: --> * `value` {string|Buffer|Uint8Array|integer} 要查找的值。 -* `byteOffset` {integer} `buf` 中开始查找的偏移量。**默认值:** [`buf.length`]` - 1`。 +* `byteOffset` {integer} `buf` 中开始查找的偏移量。**默认值:** `buf.length - 1`。 * `encoding` {string} 如果 `value` 是字符串，则指定 `value` 的字符编码。**默认值:** `'utf8'`。 * 返回: {integer} `buf` 中最后一次出现 `value` 的索引，如果 `buf` 没包含 `value` 则返回 `-1`。 diff --git a/cli/enable_source_maps.md b/cli/enable_source_maps.md new file mode 100644 index 00000000..3cba5eac --- /dev/null +++ b/cli/enable_source_maps.md @@ -0,0 +1,8 @@ + + +> Stability: 1 - Experimental + +Enable experimental Source Map V3 support for stack traces. + diff --git a/cli/experimental_json_modules.md b/cli/experimental_json_modules.md new file mode 100644 index 00000000..ae111c80 --- /dev/null +++ b/cli/experimental_json_modules.md @@ -0,0 +1,6 @@ + + +Enable experimental JSON support for the ES Module loader. + diff --git a/cli/force_context_aware.md b/cli/force_context_aware.md new file mode 100644 index 00000000..8a7bacfc --- /dev/null +++ b/cli/force_context_aware.md @@ -0,0 +1,6 @@ + + +Disable loading native addons that are not [context-aware][]. + diff --git a/cli/node_options_options.md b/cli/node_options_options.md index 77f0d903..5c059834 100644 --- a/cli/node_options_options.md +++ b/cli/node_options_options.md @@ -36,8 +36,10 @@ node --require "./a.js" --require "./b.js" Node.js options that are allowed are: * `--enable-fips` +* `--enable-source-maps` * `--es-module-specifier-resolution` * `--experimental-exports` +* `--experimental-json-modules` * `--experimental-loader` * `--experimental-modules` * `--experimental-policy` @@ -45,6 +47,7 @@ Node.js options that are allowed are: * `--experimental-report` * `--experimental-vm-modules` * `--experimental-wasm-modules` +* `--force-context-aware` * `--force-fips` * `--frozen-intrinsics` * `--heapsnapshot-signal` diff --git a/cli/uv_threadpool_size_size.md b/cli/uv_threadpool_size_size.md index f5d10287..ee336b2d 100644 --- a/cli/uv_threadpool_size_size.md +++ b/cli/uv_threadpool_size_size.md @@ -38,5 +38,6 @@ greater than `4` (its current default value). For more information, see the + diff --git a/crypto/crypto_creatediffiehellmangroup_name.md b/crypto/crypto_creatediffiehellmangroup_name.md index 8dc34b3b..74fedcdb 100644 --- a/crypto/crypto_creatediffiehellmangroup_name.md +++ b/crypto/crypto_creatediffiehellmangroup_name.md @@ -3,7 +3,7 @@ added: v0.9.3 --> * `name` {string} -* Returns: {DiffieHellman} +* Returns: {DiffieHellmanGroup} An alias for [`crypto.getDiffieHellman()`][] diff --git a/crypto/crypto_generatekeypair_type_options_callback.md b/crypto/crypto_generatekeypair_type_options_callback.md index 9dd7de50..d22784a1 100644 --- a/crypto/crypto_generatekeypair_type_options_callback.md +++ b/crypto/crypto_generatekeypair_type_options_callback.md @@ -32,7 +32,7 @@ and Ed448 are currently supported. If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function behaves as if [`keyObject.export()`][] had been called on its result. Otherwise, -the respective part of the key is returned as a [`KeyObject`]. +the respective part of the key is returned as a [`KeyObject`][]. It is recommended to encode public keys as `'spki'` and private keys as `'pkcs8'` with encryption for long-term storage: diff --git a/crypto/crypto_generatekeypairsync_type_options.md b/crypto/crypto_generatekeypairsync_type_options.md index 6e81d3eb..3f642540 100644 --- a/crypto/crypto_generatekeypairsync_type_options.md +++ b/crypto/crypto_generatekeypairsync_type_options.md @@ -27,7 +27,7 @@ and Ed448 are currently supported. If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function behaves as if [`keyObject.export()`][] had been called on its result. Otherwise, -the respective part of the key is returned as a [`KeyObject`]. +the respective part of the key is returned as a [`KeyObject`][]. When encoding public keys, it is recommended to use `'spki'`. When encoding private keys, it is recommended to use `'pks8'` with a strong passphrase, and to diff --git a/crypto/crypto_getdiffiehellman_groupname.md b/crypto/crypto_getdiffiehellman_groupname.md index 0885aa56..b2f8cc50 100644 --- a/crypto/crypto_getdiffiehellman_groupname.md +++ b/crypto/crypto_getdiffiehellman_groupname.md @@ -3,9 +3,9 @@ added: v0.7.5 --> * `groupName` {string} -* Returns: {DiffieHellman} +* Returns: {DiffieHellmanGroup} -Creates a predefined `DiffieHellman` key exchange object. The +Creates a predefined `DiffieHellmanGroup` key exchange object. The supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC 2412][], but see [Caveats][]) and `'modp14'`, `'modp15'`, `'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The diff --git a/deprecations/dep0005_buffer_constructor.md b/deprecations/dep0005_buffer_constructor.md index 84d6ca6c..5a72a104 100644 --- a/deprecations/dep0005_buffer_constructor.md +++ b/deprecations/dep0005_buffer_constructor.md @@ -32,8 +32,9 @@ objects: * [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` that copies `string`. -As of v10.0.0, a deprecation warning is printed at runtime when -`--pending-deprecation` is used or when the calling code is -outside `node_modules` in order to better target developers, rather than users. +Without `--pending-deprecation`, runtime warnings occur only for code not in +`node_modules`. This means there will not be deprecation warnings for +`Buffer()` usage in dependencies. With `--pending-deprecation`, a runtime +warning results no matter where the `Buffer()` usage occurs. diff --git a/deprecations/dep0132_worker_terminate_with_callback.md b/deprecations/dep0132_worker_terminate_with_callback.md index 95d6ab8c..fdb8ead7 100644 --- a/deprecations/dep0132_worker_terminate_with_callback.md +++ b/deprecations/dep0132_worker_terminate_with_callback.md @@ -10,107 +10,4 @@ Type: Runtime Passing a callback to [`worker.terminate()`][] is deprecated. Use the returned `Promise` instead, or a listener to the worker’s `'exit'` event. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + diff --git a/deprecations/dep0133_http_connection.md b/deprecations/dep0133_http_connection.md new file mode 100644 index 00000000..f057e758 --- /dev/null +++ b/deprecations/dep0133_http_connection.md @@ -0,0 +1,13 @@ + + +Type: Documentation-only + +Prefer [`response.socket`][] over [`response.connection`][] and +[`request.socket`][] over [`request.connection`][]. + + diff --git a/deprecations/dep0134_process_tickcallback.md b/deprecations/dep0134_process_tickcallback.md new file mode 100644 index 00000000..b8692d3c --- /dev/null +++ b/deprecations/dep0134_process_tickcallback.md @@ -0,0 +1,115 @@ + +Type: Documentation-only (supports [`--pending-deprecation`][]) + +The `process._tickCallback` property was never documented as +an officially supported API. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dgram/dgram_createsocket_type_callback.md b/dgram/dgram_createsocket_type_callback.md index f5a36365..0b2b002b 100644 --- a/dgram/dgram_createsocket_type_callback.md +++ b/dgram/dgram_createsocket_type_callback.md @@ -7,8 +7,6 @@ added: v0.1.99 * 返回: {dgram.Socket} 创建一个特定 `type` 的 `dgram.Socket` 对象。 -`type` 参数是 `'udp4'` 或 `'udp6'`。 -可选传一个 `callback` 函数，作为 `'message'` 事件的监听器。 一旦套接字被创建，调用 [`socket.bind()`] 会指示套接字开始监听数据报消息。 如果 `address` 和 `port` 没传给 [`socket.bind()`]，那么这个方法会把这个套接字绑定到 "全部接口" 地址的一个随机端口（这适用于 `udp4` 和 `udp6` 套接字）。 diff --git a/dgram/note_about_udp_datagram_size.md b/dgram/note_about_udp_datagram_size.md new file mode 100644 index 00000000..7502b233 --- /dev/null +++ b/dgram/note_about_udp_datagram_size.md @@ -0,0 +1,15 @@ + +`IPv4/v6` 数据包的最大尺寸取决于 `MTU`(Maximum Transmission Unit，最大传输单元)与 `Payload Length` 字段大小。 + +- `Payload Length` 字段有 `16 位` 宽，指一个超过 64K 的包含 IP 头部和数据的负载 (65,507 字节 = 65,535 − 8 字节 UDP 头 − 20 字节 IP 头)。 + 通常对于环回地址来说是这样，但这个长度的数据包对于大多数的主机和网络来说不切实际。 + +- `MTU` 指的是数据链路层为数据包提供的最大大小。 + 对于任意链路，`IPv4` 所托管的 `MTU` 最小为 `68` 个字节，推荐为 `576`（典型地，作为拨号上网应用的推荐值），无论它们是完整地还是分块地抵达。 + + 对于 `IPv6`，`MTU` 的最小值是 `1280` 个字节，然而，受托管的最小的碎片重组缓冲大小为 `1500` 个字节。 + 现今大多数的数据链路层技术（如以太网），都有 `1500` 的 `MTU` 最小值，因而 `68` 个字节显得非常小。 + +要提前知道数据包可能经过的每个链路的 MTU 是不可能的。 +发送大于接受者 `MTU` 大小的数据包将不会起作用，因为数据包会被静默地丢失，而不会通知发送者该包未抵达目的地。 + diff --git a/dgram/socket_bind_port_address_callback.md b/dgram/socket_bind_port_address_callback.md index a08b760b..1f04e2e9 100644 --- a/dgram/socket_bind_port_address_callback.md +++ b/dgram/socket_bind_port_address_callback.md @@ -1,5 +1,10 @@ * `port` {integer} diff --git a/dgram/socket_ref.md b/dgram/socket_ref.md index 1432debf..974ee601 100644 --- a/dgram/socket_ref.md +++ b/dgram/socket_ref.md @@ -2,6 +2,8 @@ added: v0.9.1 --> +* 返回: {dgram.Socket} + 默认情况下，绑定一个 socket 会在 socket 运行时阻止 Node.js 进程退出。 `socket.unref()` 方法用于将 socket 从维持 Node.js 进程的引用列表中解除。 `socket.ref()` 方法用于将 socket 重新添加到这个引用列表中，并恢复其默认行为。 diff --git a/dgram/socket_send_msg_offset_length_port_address_callback.md b/dgram/socket_send_msg_offset_length_port_address_callback.md index f7c9b3ea..1af20e08 100644 --- a/dgram/socket_send_msg_offset_length_port_address_callback.md +++ b/dgram/socket_send_msg_offset_length_port_address_callback.md @@ -94,19 +94,3 @@ client.connect(41234, 'localhost', (err) => { }); ``` -**关于 UDP 包大小的注意事项** - -`IPv4/v6` 数据包的最大尺寸取决于 `MTU`(Maximum Transmission Unit，最大传输单元)与 `Payload Length` 字段大小。 - -- `Payload Length` 字段有 `16 位` 宽，指一个超过 64K 的包含 IP 头部和数据的负载 (65,507 字节 = 65,535 − 8 字节 UDP 头 − 20 字节 IP 头)。 - 通常对于环回地址来说是这样，但这个长度的数据包对于大多数的主机和网络来说不切实际。 - -- `MTU` 指的是数据链路层为数据包提供的最大大小。 - 对于任意链路，`IPv4` 所托管的 `MTU` 最小为 `68` 个字节，推荐为 `576`（典型地，作为拨号上网应用的推荐值），无论它们是完整地还是分块地抵达。 - - 对于 `IPv6`，`MTU` 的最小值是 `1280` 个字节，然而，受托管的最小的碎片重组缓冲大小为 `1500` 个字节。 - 现今大多数的数据链路层技术（如以太网），都有 `1500` 的 `MTU` 最小值，因而 `68` 个字节显得非常小。 - -要提前知道数据包可能经过的每个链路的 MTU 是不可能的。 -发送大于接受者 `MTU` 大小的数据包将不会起作用，因为数据包会被静默地丢失，而不会通知发送者该包未抵达目的地。 - diff --git a/dgram/socket_unref.md b/dgram/socket_unref.md index b7dc59c4..0959ecd4 100644 --- a/dgram/socket_unref.md +++ b/dgram/socket_unref.md @@ -2,6 +2,8 @@ added: v0.9.1 --> +* 返回: {dgram.Socket} + 默认情况下，只要 socket 是打开的，绑定一个 socket 将导致它阻塞 Node.js 进程退出。 使用 `socket.unref()` 方法可以从保持 Node.js 进程活动的引用计数中排除 socket，从而允许进程退出，尽管这个 socket 仍然在侦听。 diff --git a/errors/err_closed_message_port.md b/errors/err_closed_message_port.md index 768660af..2bda492d 100644 --- a/errors/err_closed_message_port.md +++ b/errors/err_closed_message_port.md @@ -6,4 +6,4 @@ removed: v11.12.0 There was an attempt to use a `MessagePort` instance in a closed state, usually after `.close()` has been called. - + diff --git a/errors/err_crypto_fips_unavailable.md b/errors/err_crypto_fips_unavailable.md index a220321b..e8c9269e 100644 --- a/errors/err_crypto_fips_unavailable.md +++ b/errors/err_crypto_fips_unavailable.md @@ -2,4 +2,4 @@ An attempt was made to enable or disable FIPS mode, but FIPS mode was not available. - + diff --git a/errors/err_crypto_hash_digest_no_utf16.md b/errors/err_crypto_hash_digest_no_utf16.md index 211c8d5d..6841b371 100644 --- a/errors/err_crypto_hash_digest_no_utf16.md +++ b/errors/err_crypto_hash_digest_no_utf16.md @@ -1,7 +1,11 @@ + The UTF-16 encoding was used with [`hash.digest()`][]. While the `hash.digest()` method does allow an `encoding` argument to be passed in, causing the method to return a string rather than a `Buffer`, the UTF-16 encoding (e.g. `ucs` or `utf16le`) is not supported. - + diff --git a/errors/err_crypto_timing_safe_equal_length.md b/errors/err_crypto_timing_safe_equal_length.md index 1e39ef83..dbac2703 100644 --- a/errors/err_crypto_timing_safe_equal_length.md +++ b/errors/err_crypto_timing_safe_equal_length.md @@ -2,4 +2,4 @@ [`crypto.timingSafeEqual()`][] was called with `Buffer`, `TypedArray`, or `DataView` arguments of different lengths. - + diff --git a/errors/err_dir_closed.md b/errors/err_dir_closed.md new file mode 100644 index 00000000..1359eeb0 --- /dev/null +++ b/errors/err_dir_closed.md @@ -0,0 +1,4 @@ + +The [`fs.Dir`][] was previously closed. + + diff --git a/errors/err_invalid_handle_type.md b/errors/err_invalid_handle_type.md index 1317299c..76880d6b 100644 --- a/errors/err_invalid_handle_type.md +++ b/errors/err_invalid_handle_type.md @@ -1,6 +1,6 @@ An attempt was made to send an unsupported "handle" over an IPC communication -channel to a child process. See [`subprocess.send()`] and [`process.send()`] for -more information. +channel to a child process. See [`subprocess.send()`][] and [`process.send()`][] +for more information. diff --git a/errors/err_manifest_assert_integrity.md b/errors/err_manifest_assert_integrity.md index 419cc948..8af128f2 100644 --- a/errors/err_manifest_assert_integrity.md +++ b/errors/err_manifest_assert_integrity.md @@ -1,6 +1,6 @@ An attempt was made to load a resource, but the resource did not match the -integrity defined by the policy manifest. See the documentation for [policy] +integrity defined by the policy manifest. See the documentation for [policy][] manifests for more information. diff --git a/errors/err_manifest_dependency_missing.md b/errors/err_manifest_dependency_missing.md index 264766f0..1bc20479 100644 --- a/errors/err_manifest_dependency_missing.md +++ b/errors/err_manifest_dependency_missing.md @@ -1,6 +1,6 @@ An attempt was made to load a resource, but the resource was not listed as a dependency from the location that attempted to load it. See the documentation -for [policy] manifests for more information. +for [policy][] manifests for more information. diff --git a/errors/err_manifest_integrity_mismatch.md b/errors/err_manifest_integrity_mismatch.md index c6fb4a38..70198d13 100644 --- a/errors/err_manifest_integrity_mismatch.md +++ b/errors/err_manifest_integrity_mismatch.md @@ -2,6 +2,6 @@ An attempt was made to load a policy manifest, but the manifest had multiple entries for a resource which did not match each other. Update the manifest entries to match in order to resolve this error. See the documentation for -[policy] manifests for more information. +[policy][] manifests for more information. diff --git a/errors/err_manifest_invalid_resource_field.md b/errors/err_manifest_invalid_resource_field.md index 5b282abf..50157e2e 100644 --- a/errors/err_manifest_invalid_resource_field.md +++ b/errors/err_manifest_invalid_resource_field.md @@ -1,6 +1,6 @@ A policy manifest resource had an invalid value for one of its fields. Update the manifest entry to match in order to resolve this error. See the -documentation for [policy] manifests for more information. +documentation for [policy][] manifests for more information. diff --git a/errors/err_manifest_parse_policy.md b/errors/err_manifest_parse_policy.md index 1d067210..4b9a32db 100644 --- a/errors/err_manifest_parse_policy.md +++ b/errors/err_manifest_parse_policy.md @@ -1,5 +1,5 @@ An attempt was made to load a policy manifest, but the manifest was unable to -be parsed. See the documentation for [policy] manifests for more information. +be parsed. See the documentation for [policy][] manifests for more information. diff --git a/errors/err_manifest_unknown_onerror.md b/errors/err_manifest_unknown_onerror.md index 1764edba..250deb9d 100644 --- a/errors/err_manifest_unknown_onerror.md +++ b/errors/err_manifest_unknown_onerror.md @@ -1,5 +1,5 @@ A policy manifest was loaded, but had an unknown value for its "onerror" -behavior. See the documentation for [policy] manifests for more information. +behavior. See the documentation for [policy][] manifests for more information. diff --git a/errors/err_no_icu.md b/errors/err_no_icu.md index 7d72f561..cac4f9a5 100644 --- a/errors/err_no_icu.md +++ b/errors/err_no_icu.md @@ -2,4 +2,4 @@ An attempt was made to use features that require [ICU][], but Node.js was not compiled with ICU support. - + diff --git a/errors/err_non_context_aware_disabled.md b/errors/err_non_context_aware_disabled.md new file mode 100644 index 00000000..6999d413 --- /dev/null +++ b/errors/err_non_context_aware_disabled.md @@ -0,0 +1,4 @@ + +A non-context-aware native addon was loaded in a process that disallows them. + + diff --git a/errors/err_tty_writable_not_readable.md b/errors/err_tty_writable_not_readable.md index 7af18a67..f565a826 100644 --- a/errors/err_tty_writable_not_readable.md +++ b/errors/err_tty_writable_not_readable.md @@ -62,5 +62,6 @@ such as `process.stdout.on('data')`. + diff --git a/errors/err_value_out_of_range.md b/errors/err_value_out_of_range.md index e961eaac..d8625700 100644 --- a/errors/err_value_out_of_range.md +++ b/errors/err_value_out_of_range.md @@ -5,4 +5,4 @@ removed: v10.0.0 Used when a given value is out of the accepted range. - + diff --git a/errors/err_vm_module_linking_errored.md b/errors/err_vm_module_linking_errored.md index 36c297e3..f1e10d14 100644 --- a/errors/err_vm_module_linking_errored.md +++ b/errors/err_vm_module_linking_errored.md @@ -1,4 +1,4 @@ The linker function returned a module for which linking has failed. - + diff --git a/errors/err_vm_module_not_linked.md b/errors/err_vm_module_not_linked.md index df71db1b..6e24d702 100644 --- a/errors/err_vm_module_not_linked.md +++ b/errors/err_vm_module_not_linked.md @@ -1,4 +1,4 @@ The module must be successfully linked before instantiation. - + diff --git a/esm/builtin_modules.md b/esm/builtin_modules.md index 411bd347..88f8c135 100644 --- a/esm/builtin_modules.md +++ b/esm/builtin_modules.md @@ -1,8 +1,9 @@ -Builtin modules will provide named exports of their public API, as well as a -default export which can be used for, among other things, modifying the named -exports. Named exports of builtin modules are updated when the corresponding -exports property is accessed, redefined, or deleted. +Builtin modules will provide named exports of their public API. A +default export is also provided which is the value of the CommonJS exports. +The default export can be used for, among other things, modifying the named +exports. Named exports of builtin modules are updated only by calling +[`module.syncBuiltinESMExports()`][]. ```js import EventEmitter from 'events'; @@ -22,8 +23,10 @@ readFile('./foo.txt', (err, source) => { ```js import fs, { readFileSync } from 'fs'; +import { syncBuiltinESMExports } from 'module'; fs.readFileSync = () => Buffer.from('Hello, ESM'); +syncBuiltinESMExports(); fs.readFileSync === readFileSync; ``` diff --git a/esm/customizing_esm_specifier_resolution_algorithm.md b/esm/customizing_esm_specifier_resolution_algorithm.md index b25daa19..843bf061 100644 --- a/esm/customizing_esm_specifier_resolution_algorithm.md +++ b/esm/customizing_esm_specifier_resolution_algorithm.md @@ -35,3 +35,4 @@ success! + diff --git a/esm/experimental_json_modules.md b/esm/experimental_json_modules.md new file mode 100644 index 00000000..dd1fd884 --- /dev/null +++ b/esm/experimental_json_modules.md @@ -0,0 +1,29 @@ + +Currently importing JSON modules are only supported in the `commonjs` mode +and are loaded using the CJS loader. [WHATWG JSON modules specification][] are +still being standardized, and are experimentally supported by including the +additional flag `--experimental-json-modules` when running Node.js. + +When the `--experimental-json-modules` flag is included both the +`commonjs` and `module` mode will use the new experimental JSON +loader. The imported JSON only exposes a `default`, there is no +support for named exports. A cache entry is created in the CommonJS +cache, to avoid duplication. The same object will be returned in +CommonJS if the JSON module has already been imported from the +same path. + +Assuming an `index.mjs` with + + +```js +import packageConfig from './package.json'; +``` + +The `--experimental-json-modules` flag is needed for the module +to work. + +```bash +node --experimental-modules index.mjs # fails +node --experimental-modules --experimental-json-modules index.mjs # works +``` + diff --git a/events/eventemitter_listenercount_emitter_eventname.md b/events/eventemitter_listenercount_emitter_eventname.md index 3d926d4c..abb20e71 100644 --- a/events/eventemitter_listenercount_emitter_eventname.md +++ b/events/eventemitter_listenercount_emitter_eventname.md @@ -3,11 +3,11 @@ added: v0.9.12 deprecated: v4.0.0 --> +> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. + * `emitter` {EventEmitter} The emitter to query * `eventName` {string|symbol} The event name -> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. - A class method that returns the number of listeners for the given `eventName` registered on the given `emitter`. diff --git a/fs/class_fs_dir.md b/fs/class_fs_dir.md new file mode 100644 index 00000000..87fd18c9 --- /dev/null +++ b/fs/class_fs_dir.md @@ -0,0 +1,20 @@ + + +A class representing a directory stream. + +Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. + +```js +const fs = require('fs'); + +async function print(path) { + const dir = await fs.promises.opendir(path); + for await (const dirent of dir) { + console.log(dirent.name); + } +} +print('./').catch(console.error); +``` + diff --git a/fs/class_fs_dirent.md b/fs/class_fs_dirent.md index 14a98914..d242ca91 100644 --- a/fs/class_fs_dirent.md +++ b/fs/class_fs_dirent.md @@ -2,5 +2,7 @@ added: v10.10.0 --> -当使用 `withFileTypes` 选项设置为 `true` 调用 [`fs.readdir()`] 或 [`fs.readdirSync()`] 时，生成的数组将填充 `fs.Dirent` 对象，而不是字符串或 `Buffer`。 +目录条目的表示形式，通过从 [`fs.Dir`] 中读取而返回。 + +此外，当使用 `withFileTypes` 选项设置为 `true` 调用 [`fs.readdir()`] 或 [`fs.readdirSync()`] 时，生成的数组将会填充 `fs.Dirent` 对象，而不是字符串或 `Buffer`。 diff --git a/fs/dir_close.md b/fs/dir_close.md new file mode 100644 index 00000000..14d71f17 --- /dev/null +++ b/fs/dir_close.md @@ -0,0 +1,12 @@ + + +* Returns: {Promise} + +Asynchronously close the directory's underlying resource handle. +Subsequent reads will result in errors. + +A `Promise` is returned that will be resolved after the resource has been +closed. + diff --git a/fs/dir_close_callback.md b/fs/dir_close_callback.md new file mode 100644 index 00000000..405c1d61 --- /dev/null +++ b/fs/dir_close_callback.md @@ -0,0 +1,12 @@ + + +* `callback` {Function} + * `err` {Error} + +Asynchronously close the directory's underlying resource handle. +Subsequent reads will result in errors. + +The `callback` will be called after the resource handle has been closed. + diff --git a/fs/dir_closesync.md b/fs/dir_closesync.md new file mode 100644 index 00000000..f5cf9c1e --- /dev/null +++ b/fs/dir_closesync.md @@ -0,0 +1,7 @@ + + +Synchronously close the directory's underlying resource handle. +Subsequent reads will result in errors. + diff --git a/fs/dir_path.md b/fs/dir_path.md new file mode 100644 index 00000000..0cc1b3fe --- /dev/null +++ b/fs/dir_path.md @@ -0,0 +1,9 @@ + + +* {string} + +The read-only path of this directory as was provided to [`fs.opendir()`][], +[`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. + diff --git a/fs/dir_read.md b/fs/dir_read.md new file mode 100644 index 00000000..897f1d38 --- /dev/null +++ b/fs/dir_read.md @@ -0,0 +1,15 @@ + + +* Returns: {Promise} containing {fs.Dirent|null} + +Asynchronously read the next directory entry via readdir(3) as an +[`fs.Dirent`][]. + +After the read is completed, a `Promise` is returned that will be resolved with +an [`fs.Dirent`][], or `null` if there are no more directory entries to read. + +_Directory entries returned by this function are in no particular order as +provided by the operating system's underlying directory mechanisms._ + diff --git a/fs/dir_read_callback.md b/fs/dir_read_callback.md new file mode 100644 index 00000000..c870a756 --- /dev/null +++ b/fs/dir_read_callback.md @@ -0,0 +1,17 @@ + + +* `callback` {Function} + * `err` {Error} + * `dirent` {fs.Dirent|null} + +Asynchronously read the next directory entry via readdir(3) as an +[`fs.Dirent`][]. + +After the read is completed, the `callback` will be called with an +[`fs.Dirent`][], or `null` if there are no more directory entries to read. + +_Directory entries returned by this function are in no particular order as +provided by the operating system's underlying directory mechanisms._ + diff --git a/fs/dir_readsync.md b/fs/dir_readsync.md new file mode 100644 index 00000000..f3e3d1d0 --- /dev/null +++ b/fs/dir_readsync.md @@ -0,0 +1,14 @@ + + +* Returns: {fs.Dirent|null} + +Synchronously read the next directory entry via readdir(3) as an +[`fs.Dirent`][]. + +If there are no more directory entries to read, `null` will be returned. + +_Directory entries returned by this function are in no particular order as +provided by the operating system's underlying directory mechanisms._ + diff --git a/fs/dir_symbol_asynciterator.md b/fs/dir_symbol_asynciterator.md new file mode 100644 index 00000000..1214f705 --- /dev/null +++ b/fs/dir_symbol_asynciterator.md @@ -0,0 +1,17 @@ + + +* Returns: {AsyncIterator} of {fs.Dirent} + +Asynchronously iterates over the directory via readdir(3) until all entries have +been read. + +Entries returned by the async iterator are always an [`fs.Dirent`][]. +The `null` case from `dir.read()` is handled internally. + +See [`fs.Dir`][] for an example. + +_Directory entries returned by this iterator are in no particular order as +provided by the operating system's underlying directory mechanisms._ + diff --git a/fs/fs_opendir_path_options_callback.md b/fs/fs_opendir_path_options_callback.md new file mode 100644 index 00000000..21d6ede7 --- /dev/null +++ b/fs/fs_opendir_path_options_callback.md @@ -0,0 +1,19 @@ + + +* `path` {string|Buffer|URL} +* `options` {Object} + * `encoding` {string|null} **Default:** `'utf8'` +* `callback` {Function} + * `err` {Error} + * `dir` {fs.Dir} + +Asynchronously open a directory. See opendir(3). + +Creates an [`fs.Dir`][], which contains all further functions for reading from +and cleaning up the directory. + +The `encoding` option sets the encoding for the `path` while opening the +directory and subsequent read operations. + diff --git a/fs/fs_opendirsync_path_options.md b/fs/fs_opendirsync_path_options.md new file mode 100644 index 00000000..03c17e56 --- /dev/null +++ b/fs/fs_opendirsync_path_options.md @@ -0,0 +1,17 @@ + + +* `path` {string|Buffer|URL} +* `options` {Object} + * `encoding` {string|null} **Default:** `'utf8'` +* Returns: {fs.Dir} + +Synchronously open a directory. See opendir(3). + +Creates an [`fs.Dir`][], which contains all further functions for reading from +and cleaning up the directory. + +The `encoding` option sets the encoding for the `path` while opening the +directory and subsequent read operations. + diff --git a/fs/fspromises_opendir_path_options.md b/fs/fspromises_opendir_path_options.md new file mode 100644 index 00000000..85a64cd8 --- /dev/null +++ b/fs/fspromises_opendir_path_options.md @@ -0,0 +1,31 @@ + + +* `path` {string|Buffer|URL} +* `options` {Object} + * `encoding` {string|null} **Default:** `'utf8'` +* Returns: {Promise} containing {fs.Dir} + +Asynchronously open a directory. See opendir(3). + +Creates an [`fs.Dir`][], which contains all further functions for reading from +and cleaning up the directory. + +The `encoding` option sets the encoding for the `path` while opening the +directory and subsequent read operations. + +Example using async iteration: + +```js +const fs = require('fs'); + +async function print(path) { + const dir = await fs.promises.opendir(path); + for await (const dirent of dir) { + console.log(dirent.name); + } +} +print('./').catch(console.error); +``` + diff --git a/http2/http2session_ref.md b/http2/http2session_ref.md index 42148933..871a4e05 100644 --- a/http2/http2session_ref.md +++ b/http2/http2session_ref.md @@ -3,5 +3,5 @@ added: v9.4.0 --> Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session` -instance's underlying [`net.Socket`]. +instance's underlying [`net.Socket`][]. diff --git a/http2/http2session_unref.md b/http2/http2session_unref.md index 1b281958..218955af 100644 --- a/http2/http2session_unref.md +++ b/http2/http2session_unref.md @@ -3,5 +3,5 @@ added: v9.4.0 --> Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session` -instance's underlying [`net.Socket`]. +instance's underlying [`net.Socket`][]. diff --git a/http2/http2stream_respondwithfd_fd_headers_options.md b/http2/http2stream_respondwithfd_fd_headers_options.md index f454fed3..97087593 100644 --- a/http2/http2stream_respondwithfd_fd_headers_options.md +++ b/http2/http2stream_respondwithfd_fd_headers_options.md @@ -1,13 +1,16 @@ -* `fd` {number} A readable file descriptor. +* `fd` {number|FileHandle} A readable file descriptor. * `headers` {HTTP/2 Headers Object} * `options` {Object} * `statCheck` {Function} @@ -53,8 +56,8 @@ The `offset` and `length` options may be used to limit the response to a specific range subset. This can be used, for instance, to support HTTP Range requests. -The file descriptor is not closed when the stream is closed, so it will need -to be closed manually once it is no longer needed. +The file descriptor or `FileHandle` is not closed when the stream is closed, +so it will need to be closed manually once it is no longer needed. Using the same file descriptor concurrently for multiple streams is not supported and may result in data loss. Re-using a file descriptor after a stream has finished is supported. diff --git a/http2/response_createpushresponse_headers_callback.md b/http2/response_createpushresponse_headers_callback.md index a1e7bf15..8638b640 100644 --- a/http2/response_createpushresponse_headers_callback.md +++ b/http2/response_createpushresponse_headers_callback.md @@ -11,7 +11,7 @@ added: v8.4.0 * `stream` {ServerHttp2Stream} The newly-created `ServerHttp2Stream` object Call [`http2stream.pushStream()`][] with the given headers, and wrap the -given [`Http2Stream`] on a newly created `Http2ServerResponse` as the callback +given [`Http2Stream`][] on a newly created `Http2ServerResponse` as the callback parameter if successful. When `Http2ServerRequest` is closed, the callback is called with an error `ERR_HTTP2_INVALID_STREAM`. diff --git a/http2/server_close_callback.md b/http2/server_close_callback.md index f8240de4..a241b51d 100644 --- a/http2/server_close_callback.md +++ b/http2/server_close_callback.md @@ -6,7 +6,7 @@ added: v8.4.0 Stops the server from establishing new sessions. This does not prevent new request streams from being created due to the persistent nature of HTTP/2 -sessions. To gracefully shut down the server, call [`http2session.close()`] on +sessions. To gracefully shut down the server, call [`http2session.close()`][] on all active sessions. If `callback` is provided, it is not invoked until all active sessions have been diff --git a/http2/server_close_callback_1.md b/http2/server_close_callback_1.md index 19405b43..4a8258dc 100644 --- a/http2/server_close_callback_1.md +++ b/http2/server_close_callback_1.md @@ -6,7 +6,7 @@ added: v8.4.0 Stops the server from establishing new sessions. This does not prevent new request streams from being created due to the persistent nature of HTTP/2 -sessions. To gracefully shut down the server, call [`http2session.close()`] on +sessions. To gracefully shut down the server, call [`http2session.close()`][] on all active sessions. If `callback` is provided, it is not invoked until all active sessions have been diff --git a/http2/settings_object.md b/http2/settings_object.md index ef408e4b..4585b3d5 100644 --- a/http2/settings_object.md +++ b/http2/settings_object.md @@ -1,6 +1,9 @@ Immediately close the session. All pending message callbacks will be called -with an error. [`session.connect()`] will need to be called to be able to send +with an error. [`session.connect()`][] will need to be called to be able to send messages again. Reconnected session will lose all inspector state, such as enabled agents or configured breakpoints. diff --git a/modules/module_createrequirefrompath_filename.md b/modules/module_createrequirefrompath_filename.md index ab69dd3c..e79149dc 100644 --- a/modules/module_createrequirefrompath_filename.md +++ b/modules/module_createrequirefrompath_filename.md @@ -3,12 +3,12 @@ added: v10.12.0 deprecated: v12.2.0 --> +> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead. + * `filename` {string} Filename to be used to construct the relative require function. * Returns: {require} Require function -> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead. - ```js const { createRequireFromPath } = require('module'); const requireUtil = createRequireFromPath('../src/utils/'); @@ -17,16 +17,3 @@ const requireUtil = createRequireFromPath('../src/utils/'); requireUtil('./some-tool'); ``` - - - - - - - - - - - - - diff --git a/modules/module_syncbuiltinesmexports.md b/modules/module_syncbuiltinesmexports.md new file mode 100644 index 00000000..904f8d1e --- /dev/null +++ b/modules/module_syncbuiltinesmexports.md @@ -0,0 +1,42 @@ + + +The `module.syncBuiltinESMExports()` method updates all the live bindings for +builtin ES Modules to match the properties of the CommonJS exports. It does +not add or remove exported names from the ES Modules. + +```js +const fs = require('fs'); +const { syncBuiltinESMExports } = require('module'); + +fs.readFile = null; + +delete fs.readFileSync; + +fs.newAPI = function newAPI() { + // ... +}; + +syncBuiltinESMExports(); + +import('fs').then((esmFS) => { + assert.strictEqual(esmFS.readFile, null); + assert.strictEqual('readFileSync' in fs, true); + assert.strictEqual(esmFS.newAPI, undefined); +}); +``` + + + + + + + + + + + + + + diff --git a/n-api/n_api.md b/n-api/n_api.md index 4ba64c07..c61c9a01 100644 --- a/n-api/n_api.md +++ b/n-api/n_api.md @@ -36,8 +36,7 @@ properties: The N-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. To support using C++, the project maintains a -C++ wrapper module called -[node-addon-api](https://github.com/nodejs/node-addon-api). +C++ wrapper module called [node-addon-api][]. This wrapper provides an inlineable C++ API. Binaries built with `node-addon-api` will depend on the symbols for the N-API C-based functions exported by Node.js. `node-addon-api` is a more diff --git a/n-api/napi_add_finalizer.md b/n-api/napi_add_finalizer.md index a1cf2c65..e1e92371 100644 --- a/n-api/napi_add_finalizer.md +++ b/n-api/napi_add_finalizer.md @@ -32,7 +32,8 @@ in `js_object` is ready for garbage collection. This API is similar to * the native data cannot be retrieved later using `napi_unwrap()`, * nor can it be removed later using `napi_remove_wrap()`, and * the API can be called multiple times with different data items in order to - attach each of them to the JavaScript object. + attach each of them to the JavaScript object, and +* the object manipulated by the API can be used with `napi_wrap()`. *Caution*: The optional returned reference (if obtained) should be deleted via [`napi_delete_reference`][] ONLY in response to the finalize callback diff --git a/n-api/napi_coerce_to_bool.md b/n-api/napi_coerce_to_bool.md index 007a46af..bc9d0822 100644 --- a/n-api/napi_coerce_to_bool.md +++ b/n-api/napi_coerce_to_bool.md @@ -16,7 +16,6 @@ napi_status napi_coerce_to_bool(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToBoolean()` as defined in -[Section 7.1.2](https://tc39.github.io/ecma262/#sec-toboolean) -of the ECMAScript Language Specification. +[Section 7.1.2][] of the ECMAScript Language Specification. This API can be re-entrant if getters are defined on the passed-in `Object`. diff --git a/n-api/napi_coerce_to_number.md b/n-api/napi_coerce_to_number.md index 8ea102af..6b7cfb5e 100644 --- a/n-api/napi_coerce_to_number.md +++ b/n-api/napi_coerce_to_number.md @@ -16,7 +16,6 @@ napi_status napi_coerce_to_number(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToNumber()` as defined in -[Section 7.1.3](https://tc39.github.io/ecma262/#sec-tonumber) -of the ECMAScript Language Specification. +[Section 7.1.3][] of the ECMAScript Language Specification. This API can be re-entrant if getters are defined on the passed-in `Object`. diff --git a/n-api/napi_coerce_to_object.md b/n-api/napi_coerce_to_object.md index 4a7ce08e..e4416598 100644 --- a/n-api/napi_coerce_to_object.md +++ b/n-api/napi_coerce_to_object.md @@ -16,7 +16,6 @@ napi_status napi_coerce_to_object(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToObject()` as defined in -[Section 7.1.13](https://tc39.github.io/ecma262/#sec-toobject) -of the ECMAScript Language Specification. +[Section 7.1.13][] of the ECMAScript Language Specification. This API can be re-entrant if getters are defined on the passed-in `Object`. diff --git a/n-api/napi_coerce_to_string.md b/n-api/napi_coerce_to_string.md index 2aa01bd6..d54f745b 100644 --- a/n-api/napi_coerce_to_string.md +++ b/n-api/napi_coerce_to_string.md @@ -16,7 +16,6 @@ napi_status napi_coerce_to_string(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToString()` as defined in -[Section 7.1.13](https://tc39.github.io/ecma262/#sec-tostring) -of the ECMAScript Language Specification. +[Section 7.1.13][] of the ECMAScript Language Specification. This API can be re-entrant if getters are defined on the passed-in `Object`. diff --git a/n-api/napi_create_external.md b/n-api/napi_create_external.md index d01c6a58..0c0c5b89 100644 --- a/n-api/napi_create_external.md +++ b/n-api/napi_create_external.md @@ -23,9 +23,15 @@ Returns `napi_ok` if the API succeeded. This API allocates a JavaScript value with external data attached to it. This is used to pass external data through JavaScript code, so it can be retrieved -later by native code. The API allows the caller to pass in a finalize callback, -in case the underlying native resource needs to be cleaned up when the external -JavaScript value gets collected. +later by native code using [`napi_get_value_external`]. + +The API adds a `napi_finalize` callback which will be called when the JavaScript +object just created is ready for garbage collection. It is similar to +`napi_wrap()` except that: + +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the object created by the API can be used with `napi_wrap()`. The created value is not an object, and therefore does not support additional properties. It is considered a distinct value type: calling `napi_typeof()` with diff --git a/n-api/napi_create_external_arraybuffer.md b/n-api/napi_create_external_arraybuffer.md index 57b4fe03..58618029 100644 --- a/n-api/napi_create_external_arraybuffer.md +++ b/n-api/napi_create_external_arraybuffer.md @@ -30,6 +30,14 @@ The underlying byte buffer of the `ArrayBuffer` is externally allocated and managed. The caller must ensure that the byte buffer remains valid until the finalize callback is called. +The API adds a `napi_finalize` callback which will be called when the JavaScript +object just created is ready for garbage collection. It is similar to +`napi_wrap()` except that: + +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the object created by the API can be used with `napi_wrap()`. + JavaScript `ArrayBuffer`s are described in [Section 24.1][] of the ECMAScript Language Specification. diff --git a/n-api/napi_create_external_buffer.md b/n-api/napi_create_external_buffer.md index 33cc90cc..1a1488b4 100644 --- a/n-api/napi_create_external_buffer.md +++ b/n-api/napi_create_external_buffer.md @@ -28,5 +28,13 @@ 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. +The API adds a `napi_finalize` callback which will be called when the JavaScript +object just created is ready for garbage collection. It is similar to +`napi_wrap()` except that: + +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the object created by the API can be used with `napi_wrap()`. + For Node.js >=4 `Buffers` are `Uint8Array`s. diff --git a/n-api/napi_create_function.md b/n-api/napi_create_function.md index e5d07723..0d04ebe8 100644 --- a/n-api/napi_create_function.md +++ b/n-api/napi_create_function.md @@ -75,7 +75,6 @@ be associated with the resulting JavaScript function (which is returned in the `result` parameter) and freed whenever the function is garbage-collected by passing both the JavaScript function and the data to [`napi_add_finalizer`][]. -JavaScript `Function`s are described in -[Section 19.2](https://tc39.github.io/ecma262/#sec-function-objects) -of the ECMAScript Language Specification. +JavaScript `Function`s are described in [Section 19.2][] of the ECMAScript +Language Specification. diff --git a/n-api/napi_create_int64.md b/n-api/napi_create_int64.md index 087e30c7..f09d4e84 100644 --- a/n-api/napi_create_int64.md +++ b/n-api/napi_create_int64.md @@ -19,9 +19,6 @@ This API is used to convert from the C `int64_t` type to the JavaScript The JavaScript `Number` type is described in [Section 6.1.6][] of the ECMAScript Language Specification. Note the complete range of `int64_t` cannot be represented with full precision in JavaScript. Integer values -outside the range of -[`Number.MIN_SAFE_INTEGER`](https://tc39.github.io/ecma262/#sec-number.min_safe_integer) --(2^53 - 1) - -[`Number.MAX_SAFE_INTEGER`](https://tc39.github.io/ecma262/#sec-number.max_safe_integer) -(2^53 - 1) will lose precision. +outside the range of [`Number.MIN_SAFE_INTEGER`][] `-(2^53 - 1)` - +[`Number.MAX_SAFE_INTEGER`][] `(2^53 - 1)` will lose precision. diff --git a/n-api/napi_create_object.md b/n-api/napi_create_object.md index 14584ddb..3dc369ca 100644 --- a/n-api/napi_create_object.md +++ b/n-api/napi_create_object.md @@ -15,7 +15,6 @@ Returns `napi_ok` if the API succeeded. This API allocates a default JavaScript `Object`. It is the equivalent of doing `new Object()` in JavaScript. -The JavaScript `Object` type is described in -[Section 6.1.7](https://tc39.github.io/ecma262/#sec-object-type) of the +The JavaScript `Object` type is described in [Section 6.1.7][] of the ECMAScript Language Specification. diff --git a/n-api/napi_create_symbol.md b/n-api/napi_create_symbol.md index dd9128a3..ee91a9a5 100644 --- a/n-api/napi_create_symbol.md +++ b/n-api/napi_create_symbol.md @@ -18,7 +18,6 @@ Returns `napi_ok` if the API succeeded. This API creates a JavaScript `Symbol` object from a UTF8-encoded C string. -The JavaScript `Symbol` type is described in -[Section 19.4](https://tc39.github.io/ecma262/#sec-symbol-objects) +The JavaScript `Symbol` type is described in [Section 19.4][] of the ECMAScript Language Specification. diff --git a/n-api/napi_get_array_length.md b/n-api/napi_get_array_length.md index 263ce359..90043d4a 100644 --- a/n-api/napi_get_array_length.md +++ b/n-api/napi_get_array_length.md @@ -18,7 +18,6 @@ Returns `napi_ok` if the API succeeded. This API returns the length of an array. -`Array` length is described in -[Section 22.1.4.1](https://tc39.github.io/ecma262/#sec-properties-of-array-instances-length) -of the ECMAScript Language Specification. +`Array` length is described in [Section 22.1.4.1][] of the ECMAScript Language +Specification. diff --git a/n-api/napi_get_value_int64.md b/n-api/napi_get_value_int64.md index f1049bab..e21c7058 100644 --- a/n-api/napi_get_value_int64.md +++ b/n-api/napi_get_value_int64.md @@ -20,11 +20,8 @@ is passed in it returns `napi_number_expected`. This API returns the C `int64` primitive equivalent of the given JavaScript `Number`. -`Number` values outside the range of -[`Number.MIN_SAFE_INTEGER`](https://tc39.github.io/ecma262/#sec-number.min_safe_integer) --(2^53 - 1) - -[`Number.MAX_SAFE_INTEGER`](https://tc39.github.io/ecma262/#sec-number.max_safe_integer) -(2^53 - 1) will lose precision. +`Number` values outside the range of [`Number.MIN_SAFE_INTEGER`][] +`-(2^53 - 1)` - [`Number.MAX_SAFE_INTEGER`][] `(2^53 - 1)` will lose precision. Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the result to zero. diff --git a/n-api/napi_instanceof.md b/n-api/napi_instanceof.md index ea34b896..656a15d8 100644 --- a/n-api/napi_instanceof.md +++ b/n-api/napi_instanceof.md @@ -20,7 +20,5 @@ is true. Returns `napi_ok` if the API succeeded. This API represents invoking the `instanceof` Operator on the object as -defined in -[Section 12.10.4](https://tc39.github.io/ecma262/#sec-instanceofoperator) -of the ECMAScript Language Specification. +defined in [Section 12.10.4][] of the ECMAScript Language Specification. diff --git a/n-api/napi_is_array.md b/n-api/napi_is_array.md index de000c13..5a7d0b17 100644 --- a/n-api/napi_is_array.md +++ b/n-api/napi_is_array.md @@ -14,6 +14,5 @@ napi_status napi_is_array(napi_env env, napi_value value, bool* result) Returns `napi_ok` if the API succeeded. This API represents invoking the `IsArray` operation on the object -as defined in [Section 7.2.2](https://tc39.github.io/ecma262/#sec-isarray) -of the ECMAScript Language Specification. +as defined in [Section 7.2.2][] of the ECMAScript Language Specification. diff --git a/n-api/napi_property_descriptor.md b/n-api/napi_property_descriptor.md index 2b3213fe..c14ad7a1 100644 --- a/n-api/napi_property_descriptor.md +++ b/n-api/napi_property_descriptor.md @@ -39,7 +39,7 @@ property to be a JavaScript function represented by `method`. If this is passed in, set `value`, `getter` and `setter` to `NULL` (since these members won't be used). * `attributes`: The attributes associated with the particular property. -See [`napi_property_attributes`](#n_api_napi_property_attributes). +See [`napi_property_attributes`][]. * `data`: The callback data passed into `method`, `getter` and `setter` if this function is invoked. diff --git a/n-api/napi_strict_equals.md b/n-api/napi_strict_equals.md index df30d8c2..8edd9a73 100644 --- a/n-api/napi_strict_equals.md +++ b/n-api/napi_strict_equals.md @@ -18,7 +18,5 @@ napi_status napi_strict_equals(napi_env env, Returns `napi_ok` if the API succeeded. This API represents the invocation of the Strict Equality algorithm as -defined in -[Section 7.2.14](https://tc39.github.io/ecma262/#sec-strict-equality-comparison) -of the ECMAScript Language Specification. +defined in [Section 7.2.14][] of the ECMAScript Language Specification. diff --git a/n-api/napi_unref_threadsafe_function.md b/n-api/napi_unref_threadsafe_function.md index 6d8e67ca..fff5ab06 100644 --- a/n-api/napi_unref_threadsafe_function.md +++ b/n-api/napi_unref_threadsafe_function.md @@ -71,6 +71,24 @@ This API may only be called from the main thread. + + + + + + + + + + + + + + + + + + diff --git a/n-api/napi_valuetype.md b/n-api/napi_valuetype.md index d773fa88..e88fb1a6 100644 --- a/n-api/napi_valuetype.md +++ b/n-api/napi_valuetype.md @@ -16,9 +16,7 @@ typedef enum { ``` Describes the type of a `napi_value`. This generally corresponds to the types -described in -[Section 6.1](https://tc39.github.io/ecma262/#sec-ecmascript-language-types) of -the ECMAScript Language Specification. +described in [Section 6.1][] of the ECMAScript Language Specification. In addition to types in that section, `napi_valuetype` can also represent `Function`s and `Object`s with external data. diff --git a/n-api/working_with_javascript_properties.md b/n-api/working_with_javascript_properties.md index 02713c05..c79271ad 100644 --- a/n-api/working_with_javascript_properties.md +++ b/n-api/working_with_javascript_properties.md @@ -1,7 +1,6 @@ N-API exposes a set of APIs to get and set properties on JavaScript -objects. Some of these types are documented under -[Section 7](https://tc39.github.io/ecma262/#sec-operations-on-objects) of the +objects. Some of these types are documented under [Section 7][] of the [ECMAScript Language Specification][]. Properties in JavaScript are represented as a tuple of a key and a value. diff --git a/n-api/working_with_javascript_values.md b/n-api/working_with_javascript_values.md index 5e727a12..4fecf929 100644 --- a/n-api/working_with_javascript_values.md +++ b/n-api/working_with_javascript_values.md @@ -1,6 +1,5 @@ N-API exposes a set of APIs to create all types of JavaScript values. -Some of these types are documented under -[Section 6](https://tc39.github.io/ecma262/#sec-ecmascript-data-types-and-values) +Some of these types are documented under [Section 6][] of the [ECMAScript Language Specification][]. Fundamentally, these APIs are used to do one of the following: diff --git a/n-api/working_with_javascript_values_abstract_operations.md b/n-api/working_with_javascript_values_abstract_operations.md index 7bf81a34..fca2416a 100644 --- a/n-api/working_with_javascript_values_abstract_operations.md +++ b/n-api/working_with_javascript_values_abstract_operations.md @@ -1,7 +1,6 @@ N-API exposes a set of APIs to perform some abstract operations on JavaScript -values. Some of these operations are documented under -[Section 7](https://tc39.github.io/ecma262/#sec-abstract-operations) +values. Some of these operations are documented under [Section 7][] of the [ECMAScript Language Specification][]. These APIs support doing one of the following: diff --git a/process/process_ppid.md b/process/process_ppid.md index 5209159c..5a87f001 100644 --- a/process/process_ppid.md +++ b/process/process_ppid.md @@ -1,5 +1,8 @@ * {integer} diff --git a/repl/replserver_parsereplkeyword_keyword_rest.md b/repl/replserver_parsereplkeyword_keyword_rest.md index bc7d8adc..0febc356 100644 --- a/repl/replserver_parsereplkeyword_keyword_rest.md +++ b/repl/replserver_parsereplkeyword_keyword_rest.md @@ -3,12 +3,12 @@ added: v0.8.9 deprecated: v9.0.0 --> +> Stability: 0 - Deprecated. + * `keyword` {string} the potential keyword to parse and execute * `rest` {any} any parameters to the keyword command * Returns: {boolean} -> Stability: 0 - Deprecated. - An internal method used to parse and execute `REPLServer` keywords. Returns `true` if `keyword` is a valid keyword, otherwise `false`. diff --git a/stream/api_for_stream_implementers.md b/stream/api_for_stream_implementers.md index 834219b3..5189e4e7 100644 --- a/stream/api_for_stream_implementers.md +++ b/stream/api_for_stream_implementers.md @@ -21,10 +21,10 @@ class MyWritable extends Writable { | 用例 | 类 | 需实现的方法 | | -------- | ----- | ---------------------- | -| 只读流 | [`Readable`] | [_read][stream-_read] | -| 只写流 | [`Writable`] | [_write][stream-_write], [_writev][stream-_writev], [_final][stream-_final] | -| 可读可写流 | [`Duplex`] | [_read][stream-_read], [_write][stream-_write], [_writev][stream-_writev], [_final][stream-_final] | -| 对写入的数据进行操作，然后读取结果 | [`Transform`] | [_transform][stream-_transform], [_flush][stream-_flush], [_final][stream-_final] | +| 只读流 | [`Readable`] | [`_read()`][stream-_read] | +| 只写流 | [`Writable`] | [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | +| 可读可写流 | [`Duplex`] | [`_read()`][stream-_read], [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | +| 对写入的数据进行操作，然后读取结果 | [`Transform`][] | [`_transform()`][stream-_transform], [`_flush()`][stream-_flush], [`_final()`][stream-_final] | 实现流的代码中不应该调用流的公共方法，因为这些方法是给消费者使用的（详见[用于消费流的API][API for Stream Consumers]）。 这样做可能会导致使用流的应用程序代码产生不利的副作用。 diff --git a/stream/readable_read_size_1.md b/stream/readable_read_size_1.md index f81e6c3a..5c2d79f3 100644 --- a/stream/readable_read_size_1.md +++ b/stream/readable_read_size_1.md @@ -13,8 +13,8 @@ added: v0.9.4 `_read()` 应该持续从资源读取数据并推送数据，直到 `readable.push()` 返回 `false`。 若想再次调用 `_read()` 方法，则需要恢复推送数据到队列。 -一旦 `readable._read()` 被调用，它不会被再次调用，除非调用了 [`readable.push()`][stream-push]。 -这是为了确保 `readable._read()` 在同步执行时只会被调用一次。 +一旦 `readable._read()` 方法被调用，将不会再次调用它，直到更多数据通过 [`readable.push()`][stream-push] 方法被推送。 +空的数据（例如空的 buffer 和字符串）将不会导致 `readable._read()` 被调用。 `size` 是可选的参数。 对于读取是一个单一操作的实现，可以使用 `size` 参数来决定要读取多少数据。 diff --git a/tls/event_ocsprequest.md b/tls/event_ocsprequest.md index ae46f3d4..b8eed3a3 100644 --- a/tls/event_ocsprequest.md +++ b/tls/event_ocsprequest.md @@ -29,7 +29,7 @@ The typical flow of an OCSP Request is as follows: 2. Server receives the request and emits the `'OCSPRequest'` event, calling the listener if registered. 3. Server extracts the OCSP URL from either the `certificate` or `issuer` and - performs an [OCSP request] to the CA. + performs an [OCSP request][] to the CA. 4. Server receives `'OCSPResponse'` from the CA and sends it back to the client via the `callback` argument 5. Client validates the response and either destroys the socket or performs a @@ -42,5 +42,5 @@ via the `ca` option when establishing the TLS connection.) Listening for this event will have an effect only on connections established after the addition of the event listener. -An npm module like [asn1.js] may be used to parse the certificates. +An npm module like [asn1.js][] may be used to parse the certificates. diff --git a/tls/tls_createsecurecontext_options.md b/tls/tls_createsecurecontext_options.md index 39a08f89..a8eaf833 100644 --- a/tls/tls_createsecurecontext_options.md +++ b/tls/tls_createsecurecontext_options.md @@ -1,6 +1,10 @@ The default curve name to use for ECDH key agreement in a tls server. The -default value is `'auto'`. See [`tls.createSecureContext()`] for further +default value is `'auto'`. See [`tls.createSecureContext()`][] for further information. diff --git a/tls/tls_rootcertificates.md b/tls/tls_rootcertificates.md index 9a16ebe9..879dd5f4 100644 --- a/tls/tls_rootcertificates.md +++ b/tls/tls_rootcertificates.md @@ -6,5 +6,5 @@ added: v12.3.0 An immutable array of strings representing the root certificates (in PEM format) used for verifying peer certificates. This is the default value of the `ca` -option to [`tls.createSecureContext()`]. +option to [`tls.createSecureContext()`][]. diff --git a/tracing/trace_events.md b/tracing/trace_events.md index fa49fa67..bb696529 100644 --- a/tracing/trace_events.md +++ b/tracing/trace_events.md @@ -13,8 +13,8 @@ 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.console` - Enables capture of `console.time()` and `console.count()` @@ -22,7 +22,7 @@ The available categories are: * `node.dns.native` - Enables capture of trace data for DNS queries. * `node.environment` - Enables capture of Node.js Environment milestones. * `node.fs.sync` - Enables capture of trace data for file system sync methods. -* `node.perf` - Enables capture of [Performance API] measurements. +* `node.perf` - Enables capture of [Performance API][] measurements. * `node.perf.usertiming` - Enables capture of only Performance API User Timing measures and marks. * `node.perf.timerify` - Enables capture of only Performance API timerify @@ -31,7 +31,7 @@ The available categories are: of unhandled Promise rejections and handled-after-rejections. * `node.vm.script` - Enables capture of trace data for the `vm` module's `runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. -* `v8` - The [V8] events are GC, compiling, and execution related. +* `v8` - The [V8][] events are GC, compiling, and execution related. By default the `node`, `node.async_hooks`, and `v8` categories are enabled. diff --git a/url/url_strings_and_url_objects.md b/url/url_strings_and_url_objects.md index 7376129a..33066ac9 100644 --- a/url/url_strings_and_url_objects.md +++ b/url/url_strings_and_url_objects.md @@ -4,9 +4,6 @@ URL 字符串是结构化的字符串，包含多个含义不同的组成部分 `url` 模块提供了两套 API 来处理 URL：一个是旧版本遗留的 API，一个是实现了 [WHATWG标准][WHATWG URL Standard]的新 API。 -遗留的 API 还没有被废弃，保留是为了兼容已存在的应用程序。 -新的应用程序应使用 WHATWG 的 API。 - WHATWG 的 API 与遗留的 API 的区别如下。 在下图中，URL `'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'` 上方的是遗留的 `url.parse()` 返回的对象的属性。 下方的则是 WHATWG 的 `URL` 对象的属性。 diff --git a/util/util_extend_target_source.md b/util/util_extend_target_source.md index 637812b3..c814cf4f 100644 --- a/util/util_extend_target_source.md +++ b/util/util_extend_target_source.md @@ -3,14 +3,14 @@ added: v0.7.5 deprecated: v6.0.0 --> +> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. + * `target` {Object} * `source` {Object} -> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. - The `util._extend()` method was never intended to be used outside of internal Node.js modules. The community found and used it anyway. It is deprecated and should not be used in new code. JavaScript comes with very -similar built-in functionality through [`Object.assign()`]. +similar built-in functionality through [`Object.assign()`][]. diff --git a/vm/class_vm_sourcetextmodule.md b/vm/class_vm_sourcetextmodule.md index b0cfa6b3..fe0adbc0 100644 --- a/vm/class_vm_sourcetextmodule.md +++ b/vm/class_vm_sourcetextmodule.md @@ -18,9 +18,9 @@ intrinsically asynchronous, in contrast with the synchronous nature of `vm.Script` objects. With the help of async functions, however, manipulating `vm.SourceTextModule` objects is fairly straightforward. -Using a `vm.SourceTextModule` object requires four distinct steps: -creation/parsing, linking, instantiation, and evaluation. These four steps are -illustrated in the following example. +Using a `vm.SourceTextModule` object requires three distinct steps: +creation/parsing, linking, and evaluation. These three steps are illustrated in +the following example. This implementation lies at a lower level than the [ECMAScript Module loader][]. There is also currently no way to interact with the Loader, though @@ -87,15 +87,6 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); // Step 3 // - // Instantiate the top-level Module. - // - // Only the top-level Module needs to be explicitly instantiated; its - // dependencies will be recursively instantiated by instantiate(). - - bar.instantiate(); - - // Step 4 - // // Evaluate the Module. The evaluate() method returns a Promise with a single // property "result" that contains the result of the very last statement // executed in the Module. In the case of `bar`, it is `s;`, which refers to diff --git a/vm/constructor_new_vm_sourcetextmodule_code_options.md b/vm/constructor_new_vm_sourcetextmodule_code_options.md index d862a732..234ceda3 100644 --- a/vm/constructor_new_vm_sourcetextmodule_code_options.md +++ b/vm/constructor_new_vm_sourcetextmodule_code_options.md @@ -1,8 +1,9 @@ * `code` {string} JavaScript Module code to parse * `options` - * `url` {string} URL used in module resolution and stack traces. **Default:** - `'vm:module(i)'` where `i` is a context-specific ascending index. + * `identifier` {string} String used in 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. * `lineOffset` {integer} Specifies the line number offset that is displayed @@ -49,7 +50,6 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); }); // Since module has no dependencies, the linker function will never be called. await module.link(() => {}); - module.instantiate(); await module.evaluate(); // Now, Object.prototype.secret will be equal to 42. diff --git a/vm/module_evaluate_options.md b/vm/module_evaluate_options.md index c87cbdfe..3368e662 100644 --- a/vm/module_evaluate_options.md +++ b/vm/module_evaluate_options.md @@ -12,7 +12,7 @@ Evaluate the module. -This must be called after the module has been instantiated; otherwise it will +This must be called after the module has been linked; otherwise it will throw an error. It could be called also when the module has already been evaluated, in which case it will do one of the following two things: diff --git a/vm/module_identifier.md b/vm/module_identifier.md new file mode 100644 index 00000000..8e57122c --- /dev/null +++ b/vm/module_identifier.md @@ -0,0 +1,5 @@ + +* {string} + +The identifier of the current module, as set in the constructor. + diff --git a/vm/module_link_linker.md b/vm/module_link_linker.md index 8283aa21..01b43365 100644 --- a/vm/module_link_linker.md +++ b/vm/module_link_linker.md @@ -12,7 +12,7 @@ * Returns: {vm.SourceTextModule|Promise} * Returns: {Promise} -Link module dependencies. This method must be called before instantiation, and +Link module dependencies. This method must be called before evaluation, and can only be called once per module. The function is expected to return a `Module` object or a `Promise` that @@ -20,9 +20,9 @@ eventually resolves to a `Module` object. The returned `Module` must satisfy the following two invariants: * It must belong to the same context as the parent `Module`. -* Its `linkingStatus` must not be `'errored'`. +* Its `status` must not be `'errored'`. -If the returned `Module`'s `linkingStatus` is `'unlinked'`, this method will be +If the returned `Module`'s `status` is `'unlinked'`, this method will be recursively called on the returned `Module` with the same provided `linker` function. @@ -36,13 +36,13 @@ specification, with a few key differences: * The linker function is allowed to be asynchronous while [HostResolveImportedModule][] is synchronous. -* The linker function is executed during linking, a Node.js-specific stage - before instantiation, while [HostResolveImportedModule][] is called during - instantiation. The actual [HostResolveImportedModule][] implementation used during module -instantiation is one that returns the modules linked during linking. Since at +linking is one that returns the modules linked during linking. Since at that point all modules would have been fully linked already, the [HostResolveImportedModule][] implementation is fully synchronous per specification. +Corresponds to the [Link() concrete method][] field of [Source Text Module +Record][]s in the ECMAScript specification. + diff --git a/vm/module_namespace.md b/vm/module_namespace.md index eb8d949b..c7d83df7 100644 --- a/vm/module_namespace.md +++ b/vm/module_namespace.md @@ -1,8 +1,8 @@ * {Object} -The namespace object of the module. This is only available after instantiation -(`module.instantiate()`) has completed. +The namespace object of the module. This is only available after linking +(`module.link()`) has completed. Corresponds to the [GetModuleNamespace][] abstract operation in the ECMAScript specification. diff --git a/vm/module_status.md b/vm/module_status.md index 1f1b9c02..96b7a5f3 100644 --- a/vm/module_status.md +++ b/vm/module_status.md @@ -3,21 +3,13 @@ The current status of the module. Will be one of: -* `'uninstantiated'`: The module is not instantiated. It may because of any of - the following reasons: +* `'unlinked'`: `module.link()` has not yet been called. - * The module was just created. - * `module.instantiate()` has been called on this module, but it failed for - some reason. +* `'linking'`: `module.link()` has been called, but not all Promises returned + by the linker function have been resolved yet. - This status does not convey any information regarding if `module.link()` has - been called. See `module.linkingStatus` for that. - -* `'instantiating'`: The module is currently being instantiated through a - `module.instantiate()` call on itself or a parent module. - -* `'instantiated'`: The module has been instantiated successfully, but - `module.evaluate()` has not yet been called. +* `'linked'`: The module has been linked successfully, and all of its + dependencies are linked, but `module.evaluate()` has not yet been called. * `'evaluating'`: The module is being evaluated through a `module.evaluate()` on itself or a parent module.