diff --git a/async_hooks/asynchronous_context_example.md b/async_hooks/asynchronous_context_example.md index 25675206..be8fb750 100644 --- a/async_hooks/asynchronous_context_example.md +++ b/async_hooks/asynchronous_context_example.md @@ -11,7 +11,7 @@ async_hooks.createHook({ const eid = async_hooks.executionAsyncId(); const indentStr = ' '.repeat(indent); fs.writeSync( - 1, + process.stdout.fd, `${indentStr}${type}(${asyncId}):` + ` trigger: ${triggerAsyncId} execution: ${eid}\n`); }, diff --git a/async_hooks/triggerasyncid.md b/async_hooks/triggerasyncid.md index 707d648d..69ac2612 100644 --- a/async_hooks/triggerasyncid.md +++ b/async_hooks/triggerasyncid.md @@ -11,7 +11,8 @@ async_hooks.createHook({ init(asyncId, type, triggerAsyncId) { const eid = async_hooks.executionAsyncId(); fs.writeSync( - 1, `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`); + process.stdout.fd, + `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`); } }).enable(); diff --git a/buffer/buf_readuint16be_offset.md b/buffer/buf_readuint16be_offset.md index 711491ac..c4496704 100644 --- a/buffer/buf_readuint16be_offset.md +++ b/buffer/buf_readuint16be_offset.md @@ -1,6 +1,9 @@ + +> Stability: 1 - Experimental + +Enable experimental support for custom conditional exports resolution +conditions. + +Any number of custom string condition names are permitted. + +The default Node.js conditions of `"node"`, `"default"`, `"import"`, and +`"require"` will always apply as defined. + diff --git a/cli/node_options_options.md b/cli/node_options_options.md index 119cc989..a557224b 100644 --- a/cli/node_options_options.md +++ b/cli/node_options_options.md @@ -35,6 +35,7 @@ node --require "./a.js" --require "./b.js" Node.js options that are allowed are: +* `--conditions` * `--diagnostic-dir` * `--disable-proto` * `--enable-fips` diff --git a/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md b/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md index a72cecdf..3758a7ba 100644 --- a/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md +++ b/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md @@ -30,5 +30,5 @@ If `outputEncoding` is given a string will be returned; otherwise a `ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY` error when `otherPublicKey` lies outside of the elliptic curve. Since `otherPublicKey` is usually supplied from a remote user over an insecure network, -its recommended for developers to handle this exception accordingly. +be sure to handle this exception accordingly. diff --git a/crypto/legacy_api.md b/crypto/legacy_api.md index 4f381fcc..51218f09 100644 --- a/crypto/legacy_api.md +++ b/crypto/legacy_api.md @@ -1,5 +1,6 @@ -As a still supported legacy interface, it is possible (but not recommended) to -create new instances of the `crypto.Certificate` class as illustrated in the -examples below. +> Stability: 0 - Deprecated + +As a legacy interface, it is possible to create new instances of +the `crypto.Certificate` class as illustrated in the examples below. diff --git a/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md b/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md index 78e2a73f..9f74d01e 100644 --- a/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md +++ b/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md @@ -16,6 +16,6 @@ Type: End-of-Life Using a property named `inspect` on an object to specify a custom inspection function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][] instead. For backward compatibility with Node.js prior to version 6.4.0, both -may be specified. +can be specified. diff --git a/deprecations/dep0084_requiring_bundled_internal_dependencies.md b/deprecations/dep0084_requiring_bundled_internal_dependencies.md index e34461d0..05b017ce 100644 --- a/deprecations/dep0084_requiring_bundled_internal_dependencies.md +++ b/deprecations/dep0084_requiring_bundled_internal_dependencies.md @@ -32,7 +32,7 @@ The `v8/*` modules do not have any exports, and if not imported in a specific order would in fact throw errors. As such there are virtually no legitimate use cases for importing them through `require()`. -On the other hand, `node-inspect` may be installed locally through a package +On the other hand, `node-inspect` can be installed locally through a package manager, as it is published on the npm registry under the same name. No source code modification is necessary if that is done. diff --git a/deprecations/dep0104_process_env_string_coercion.md b/deprecations/dep0104_process_env_string_coercion.md index 0e245144..b519b330 100644 --- a/deprecations/dep0104_process_env_string_coercion.md +++ b/deprecations/dep0104_process_env_string_coercion.md @@ -9,7 +9,7 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) When assigning a non-string property to [`process.env`][], the assigned value is implicitly converted to a string. This behavior is deprecated if the assigned -value is not a string, boolean, or number. In the future, such assignment may +value is not a string, boolean, or number. In the future, such assignment might result in a thrown error. Please convert the property to a string before assigning it to `process.env`. diff --git a/deprecations/dep0115_crypto_prng_crypto_pseudorandombytes_crypto_rng.md b/deprecations/dep0115_crypto_prng_crypto_pseudorandombytes_crypto_rng.md index 268b1b26..fb9daa9a 100644 --- a/deprecations/dep0115_crypto_prng_crypto_pseudorandombytes_crypto_rng.md +++ b/deprecations/dep0115_crypto_prng_crypto_pseudorandombytes_crypto_rng.md @@ -13,7 +13,7 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) In recent versions of Node.js, there is no difference between [`crypto.randomBytes()`][] and `crypto.pseudoRandomBytes()`. The latter is deprecated along with the undocumented aliases `crypto.prng()` and -`crypto.rng()` in favor of [`crypto.randomBytes()`][] and may be removed in a +`crypto.rng()` in favor of [`crypto.randomBytes()`][] and might be removed in a future release. diff --git a/deprecations/dep0137_closing_fs_filehandle_on_garbage_collection.md b/deprecations/dep0137_closing_fs_filehandle_on_garbage_collection.md index 6c20b727..c0e83ef9 100644 --- a/deprecations/dep0137_closing_fs_filehandle_on_garbage_collection.md +++ b/deprecations/dep0137_closing_fs_filehandle_on_garbage_collection.md @@ -8,7 +8,7 @@ changes: Type: Runtime Allowing a [`fs.FileHandle`][] object to be closed on garbage collection is -deprecated. In the future, doing so may result in a thrown error that will +deprecated. In the future, doing so might result in a thrown error that will terminate the process. Please ensure that all `fs.FileHandle` objects are explicitly closed using diff --git a/deprecations/dep0145_socket_buffersize.md b/deprecations/dep0145_socket_buffersize.md index fba179b4..9869ee79 100644 --- a/deprecations/dep0145_socket_buffersize.md +++ b/deprecations/dep0145_socket_buffersize.md @@ -9,125 +9,4 @@ Type: Documentation-only [`socket.bufferSize`][] is just an alias for [`writable.writableLength`][]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + diff --git a/deprecations/dep0146_new_crypto_certificate.md b/deprecations/dep0146_new_crypto_certificate.md new file mode 100644 index 00000000..94c8a036 --- /dev/null +++ b/deprecations/dep0146_new_crypto_certificate.md @@ -0,0 +1,136 @@ + + +Type: Documentation-only + +The [`crypto.Certificate()` constructor][] is deprecated. Use +[static methods of `crypto.Certificate()`][] instead. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/deprecations/deprecated_apis.md b/deprecations/deprecated_apis.md index d8f45fb0..e75de46c 100644 --- a/deprecations/deprecated_apis.md +++ b/deprecations/deprecated_apis.md @@ -2,13 +2,13 @@ -Node.js may deprecate APIs for any of the following reasons: +Node.js APIs might be deprecated for any of the following reasons: * Use of the API is unsafe. * An improved alternative API is available. * Breaking changes to the API are expected in a future major release. -Node.js utilizes three kinds of Deprecations: +Node.js uses three kinds of Deprecations: * Documentation-only * Runtime diff --git a/deprecations/revoking_deprecations.md b/deprecations/revoking_deprecations.md index 79ff68eb..77c3219e 100644 --- a/deprecations/revoking_deprecations.md +++ b/deprecations/revoking_deprecations.md @@ -1,5 +1,5 @@ -Occasionally, the deprecation of an API may be reversed. In such situations, +Occasionally, the deprecation of an API might be reversed. In such situations, this document will be updated with information relevant to the decision. However, the deprecation identifier will not be modified. diff --git a/embedding/setting_up_per_process_state.md b/embedding/setting_up_per_process_state.md index 4b983d3e..7757e3ff 100644 --- a/embedding/setting_up_per_process_state.md +++ b/embedding/setting_up_per_process_state.md @@ -9,6 +9,7 @@ the `node` and `v8` C++ namespaces, respectively. ```cpp int main(int argc, char** argv) { + argv = uv_setup_args(argc, argv); std::vector args(argv, argv + argc); std::vector exec_args; std::vector errors; diff --git a/errors/err_unknown_stream_type.md b/errors/err_unknown_stream_type.md index 130ff898..4b8892e4 100644 --- a/errors/err_unknown_stream_type.md +++ b/errors/err_unknown_stream_type.md @@ -7,4 +7,4 @@ An attempt was made to launch a Node.js process with an unknown `stdout` or `stderr` file type. This error is usually an indication of a bug within Node.js itself, although it is possible for user code to trigger it. - + diff --git a/errors/err_unsupported_esm_url_scheme.md b/errors/err_unsupported_esm_url_scheme.md index 92dfcdf6..c7a842a0 100644 --- a/errors/err_unsupported_esm_url_scheme.md +++ b/errors/err_unsupported_esm_url_scheme.md @@ -1,4 +1,4 @@ `import` with URL schemes other than `file` and `data` is unsupported. - + diff --git a/errors/err_v8breakiterator.md b/errors/err_v8breakiterator.md index 4b9f2021..bb8da0a3 100644 --- a/errors/err_v8breakiterator.md +++ b/errors/err_v8breakiterator.md @@ -1,4 +1,4 @@ The V8 `BreakIterator` API was used but the full ICU data set is not installed. - + diff --git a/errors/hpe_header_overflow.md b/errors/hpe_header_overflow.md index bd510544..b2a8963a 100644 --- a/errors/hpe_header_overflow.md +++ b/errors/hpe_header_overflow.md @@ -12,4 +12,4 @@ malconfigured clients, if more than 8KB of HTTP header data is received then HTTP parsing will abort without a request or response object being created, and an `Error` with this code will be emitted. - + diff --git a/errors/hpe_unexpected_content_length.md b/errors/hpe_unexpected_content_length.md new file mode 100644 index 00000000..48cc79f1 --- /dev/null +++ b/errors/hpe_unexpected_content_length.md @@ -0,0 +1,10 @@ + +Server is sending both a `Content-Length` header and `Transfer-Encoding: chunked`. + +`Transfer-Encoding: chunked` allows the server to maintain an HTTP persistent +connection for dynamically generated content. +In this case, the `Content-Length` HTTP header cannot be used. + +Use `Content-Length` or `Transfer-Encoding: chunked`. + + diff --git a/esm/approach_1_use_an_es_module_wrapper.md b/esm/approach_1_use_an_es_module_wrapper.md index b044256e..2a7cc972 100644 --- a/esm/approach_1_use_an_es_module_wrapper.md +++ b/esm/approach_1_use_an_es_module_wrapper.md @@ -17,6 +17,12 @@ CommonJS entry point for `require`. } ``` +The above example uses explicit extensions `.mjs` and `.cjs`. +If your files use the `.js` extension, `"type": "module"` will cause such files +to be treated as ES modules, just as `"type": "commonjs"` would cause them +to be treated as CommonJS. +See [Enabling](#esm_enabling). + ```js // ./node_modules/pkg/index.cjs exports.name = 'value'; diff --git a/esm/customizing_esm_specifier_resolution_algorithm.md b/esm/customizing_esm_specifier_resolution_algorithm.md index e932a0c3..59ceb93f 100644 --- a/esm/customizing_esm_specifier_resolution_algorithm.md +++ b/esm/customizing_esm_specifier_resolution_algorithm.md @@ -10,7 +10,7 @@ requires the full path to a module be provided to the loader. To enable the automatic extension resolution and importing from directories that include an index file use the `node` mode. -```bash +```console $ node index.mjs success! $ node index # Failure! diff --git a/esm/https_loader.md b/esm/https_loader.md index 2efed03c..673615c0 100644 --- a/esm/https_loader.md +++ b/esm/https_loader.md @@ -69,8 +69,8 @@ console.log(VERSION); With this loader, running: -```console -node --experimental-loader ./https-loader.mjs ./main.js +```bash +node --experimental-loader ./https-loader.mjs ./main.mjs ``` Will print the current version of CoffeeScript per the module at the URL in diff --git a/esm/ecmascript_modules.md b/esm/modules_ecmascript_modules.md similarity index 100% rename from esm/ecmascript_modules.md rename to esm/modules_ecmascript_modules.md diff --git a/esm/resolver_algorithm.md b/esm/resolver_algorithm.md index 00a1f44f..a65074f0 100644 --- a/esm/resolver_algorithm.md +++ b/esm/resolver_algorithm.md @@ -13,7 +13,7 @@ future updates. In the following algorithms, all subroutine errors are propagated as errors of these top-level routines unless stated otherwise. -_defaultEnv_ is the conditional environment name priority array, +_defaultConditions_ is the conditional environment name array, `["node", "import"]`. The resolver can throw the following errors: @@ -33,40 +33,41 @@ The resolver can throw the following errors: **ESM_RESOLVE**(_specifier_, _parentURL_) -> 1. Let _resolvedURL_ be **undefined**. +> 1. Let _resolved_ be **undefined**. > 1. If _specifier_ is a valid URL, then -> 1. Set _resolvedURL_ to the result of parsing and reserializing +> 1. Set _resolved_ to the result of parsing and reserializing > _specifier_ as a URL. > 1. Otherwise, if _specifier_ starts with _"/"_, _"./"_ or _"../"_, then -> 1. Set _resolvedURL_ to the URL resolution of _specifier_ relative to +> 1. Set _resolved_ to the URL resolution of _specifier_ relative to > _parentURL_. > 1. Otherwise, if _specifier_ starts with _"#"_, then -> 1. Set _resolvedURL_ to the result of -> **PACKAGE_INTERNAL_RESOLVE**(_specifier_, _parentURL_). -> 1. If _resolvedURL_ is **null** or **undefined**, throw a -> _Package Import Not Defined_ error. +> 1. Set _resolved_ to the destructured value of the result of +> **PACKAGE_IMPORTS_RESOLVE**(_specifier_, _parentURL_, +> _defaultConditions_). > 1. Otherwise, > 1. Note: _specifier_ is now a bare specifier. -> 1. Set _resolvedURL_ the result of +> 1. Set _resolved_ the result of > **PACKAGE_RESOLVE**(_specifier_, _parentURL_). -> 1. If _resolvedURL_ contains any percent encodings of _"/"_ or _"\\"_ (_"%2f"_ +> 1. If _resolved_ contains any percent encodings of _"/"_ or _"\\"_ (_"%2f"_ > and _"%5C"_ respectively), then > 1. Throw an _Invalid Module Specifier_ error. -> 1. If the file at _resolvedURL_ is a directory, then +> 1. If the file at _resolved_ is a directory, then > 1. Throw an _Unsupported Directory Import_ error. -> 1. If the file at _resolvedURL_ does not exist, then +> 1. If the file at _resolved_ does not exist, then > 1. Throw a _Module Not Found_ error. -> 1. Set _resolvedURL_ to the real path of _resolvedURL_. -> 1. Let _format_ be the result of **ESM_FORMAT**(_resolvedURL_). -> 1. Load _resolvedURL_ as module format, _format_. -> 1. Return _resolvedURL_. +> 1. Set _resolved_ to the real path of _resolved_. +> 1. Let _format_ be the result of **ESM_FORMAT**(_resolved_). +> 1. Load _resolved_ as module format, _format_. +> 1. Return _resolved_. **PACKAGE_RESOLVE**(_packageSpecifier_, _parentURL_) -> 1. Let _packageName_ be *undefined*. -> 1. Let _packageSubpath_ be *undefined*. +> 1. Let _packageName_ be **undefined**. > 1. If _packageSpecifier_ is an empty string, then > 1. Throw an _Invalid Module Specifier_ error. +> 1. If _packageSpecifier_ does not start with _"@"_, then +> 1. Set _packageName_ to the substring of _packageSpecifier_ until the first +> _"/"_ separator or the end of the string. > 1. Otherwise, > 1. If _packageSpecifier_ does not contain a _"/"_ separator, then > 1. Throw an _Invalid Module Specifier_ error. @@ -74,18 +75,12 @@ The resolver can throw the following errors: > until the second _"/"_ separator or the end of the string. > 1. If _packageName_ starts with _"."_ or contains _"\\"_ or _"%"_, then > 1. Throw an _Invalid Module Specifier_ error. -> 1. Let _packageSubpath_ be _undefined_. -> 1. If the length of _packageSpecifier_ is greater than the length of -> _packageName_, then -> 1. Set _packageSubpath_ to _"."_ concatenated with the substring of +> 1. Let _packageSubpath_ be _"."_ concatenated with the substring of > _packageSpecifier_ from the position at the length of _packageName_. -> 1. If _packageSubpath_ contains any _"."_ or _".."_ segments or percent -> encoded strings for _"/"_ or _"\\"_, then -> 1. Throw an _Invalid Module Specifier_ error. > 1. Let _selfUrl_ be the result of -> **SELF_REFERENCE_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_). -> 1. If _selfUrl_ isn't empty, return _selfUrl_. -> 1. If _packageSubpath_ is _undefined_ and _packageName_ is a Node.js builtin +> **PACKAGE_SELF_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_). +> 1. If _selfUrl_ is not **undefined**, return _selfUrl_. +> 1. If _packageSubpath_ is _"."_ and _packageName_ is a Node.js builtin > module, then > 1. Return the string _"nodejs:"_ concatenated with _packageSpecifier_. > 1. While _parentURL_ is not the file system root, @@ -96,126 +91,127 @@ The resolver can throw the following errors: > 1. Set _parentURL_ to the parent URL path of _parentURL_. > 1. Continue the next loop iteration. > 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). -> 1. If _packageSubpath_ is equal to _"./"_, then -> 1. Return _packageURL_ + _"/"_. -> 1. If _packageSubpath_ is _undefined__, then -> 1. Return the result of **PACKAGE_MAIN_RESOLVE**(_packageURL_, -> _pjson_). +> 1. If _pjson_ is not **null** and _pjson_._exports_ is not **null** or +> **undefined**, then +> 1. Let _exports_ be _pjson.exports_. +> 1. Return the _resolved_ destructured value of the result of +> **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _packageSubpath_, +> _pjson.exports_, _defaultConditions_). +> 1. Otherwise, if _packageSubpath_ is equal to _"."_, then +> 1. Return the result applying the legacy **LOAD_AS_DIRECTORY** +> CommonJS resolver to _packageURL_, throwing a _Module Not Found_ +> error for no resolution. > 1. Otherwise, -> 1. If _pjson_ is not **null** and _pjson_ has an _"exports"_ key, then -> 1. Let _exports_ be _pjson.exports_. -> 1. If _exports_ is not **null** or **undefined**, then -> 1. Let _resolved_ be the result of **PACKAGE_EXPORTS_RESOLVE**( -> _packageURL_, _packageSubpath_, _pjson.exports_). -> 1. If _resolved_ is **null** or **undefined**, throw a -> _Package Path Not Exported_ error. -> 1. Return _resolved_. > 1. Return the URL resolution of _packageSubpath_ in _packageURL_. > 1. Throw a _Module Not Found_ error. -**SELF_REFERENCE_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_) +**PACKAGE_SELF_RESOLVE**(_packageName_, _packageSubpath_, _parentURL_) > 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_). > 1. If _packageURL_ is **null**, then > 1. Return **undefined**. > 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). -> 1. If _pjson_ does not include an _"exports"_ property, then +> 1. If _pjson_ is **null** or if _pjson_._exports_ is **null** or +> **undefined**, then > 1. Return **undefined**. > 1. If _pjson.name_ is equal to _packageName_, then -> 1. If _packageSubpath_ is equal to _"./"_, then -> 1. Return _packageURL_ + _"/"_. -> 1. If _packageSubpath_ is _undefined_, then -> 1. Return the result of **PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_). -> 1. Otherwise, -> 1. If _pjson_ is not **null** and _pjson_ has an _"exports"_ key, then -> 1. Let _exports_ be _pjson.exports_. -> 1. If _exports_ is not **null** or **undefined**, then -> 1. Let _resolved_ be the result of **PACKAGE_EXPORTS_RESOLVE**( -> _packageURL_, _subpath_, _pjson.exports_). -> 1. If _resolved_ is **null** or **undefined**, throw a -> _Package Path Not Exported_ error. -> 1. Return _resolved_. -> 1. Return the URL resolution of _subpath_ in _packageURL_. +> 1. Return the _resolved_ destructured value of the result of +> **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _subpath_, _pjson.exports_, +> _defaultConditions_). > 1. Otherwise, return **undefined**. -**PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_) +**PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _subpath_, _exports_, _conditions_) -> 1. If _pjson_ is **null**, then -> 1. Throw a _Module Not Found_ error. -> 1. If _pjson.exports_ is not **null** or **undefined**, then -> 1. If _exports_ is an Object with both a key starting with _"."_ and a key -> not starting with _"."_, throw an _Invalid Package Configuration_ error. -> 1. If _pjson.exports_ is a String or Array, or an Object containing no -> keys starting with _"."_, then -> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( -> _packageURL_, _pjson.exports_, _""_, **false**, _defaultEnv_). -> 1. If _resolved_ is **null** or **undefined**, throw a -> _Package Path Not Exported_ error. -> 1. Return _resolved_. -> 1. If _pjson.exports_ is an Object containing a _"."_ property, then -> 1. Let _mainExport_ be the _"."_ property in _pjson.exports_. -> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( -> _packageURL_, _mainExport_, _""_, **false**, _defaultEnv_). -> 1. If _resolved_ is **null** or **undefined**, throw a -> _Package Path Not Exported_ error. -> 1. Return _resolved_. -> 1. Throw a _Package Path Not Exported_ error. -> 1. Let _legacyMainURL_ be the result applying the legacy -> **LOAD_AS_DIRECTORY** CommonJS resolver to _packageURL_, throwing a -> _Module Not Found_ error for no resolution. -> 1. Return _legacyMainURL_. - -**PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _packagePath_, _exports_) > 1. If _exports_ is an Object with both a key starting with _"."_ and a key not > starting with _"."_, throw an _Invalid Package Configuration_ error. -> 1. If _exports_ is an Object and all keys of _exports_ start with _"."_, then -> 1. Set _packagePath_ to _"./"_ concatenated with _packagePath_. -> 1. If _packagePath_ is a key of _exports_, then -> 1. Let _target_ be the value of _exports\[packagePath\]_. -> 1. Return **PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, -> _""_, **false**, _defaultEnv_). -> 1. Let _directoryKeys_ be the list of keys of _exports_ ending in -> _"/"_, sorted by length descending. -> 1. For each key _directory_ in _directoryKeys_, do -> 1. If _packagePath_ starts with _directory_, then -> 1. Let _target_ be the value of _exports\[directory\]_. -> 1. Let _subpath_ be the substring of _target_ starting at the index -> of the length of _directory_. -> 1. Return **PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, -> _subpath_, **false**, _defaultEnv_). -> 1. Return **null**. +> 1. If _subpath_ is equal to _"."_, then +> 1. Let _mainExport_ be **undefined**. +> 1. If _exports_ is a String or Array, or an Object containing no keys +> starting with _"."_, then +> 1. Set _mainExport_ to _exports_. +> 1. Otherwise if _exports_ is an Object containing a _"."_ property, then +> 1. Set _mainExport_ to _exports_\[_"."_\]. +> 1. If _mainExport_ is not **undefined**, then +> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> _packageURL_, _mainExport_, _""_, **false**, _conditions_). +> 1. If _resolved_ is not **null** or **undefined**, then +> 1. Return _resolved_. +> 1. Otherwise, if _exports_ is an Object and all keys of _exports_ start with +> _"."_, then +> 1. Let _matchKey_ be the string _"./"_ concatenated with _subpath_. +> 1. Let _resolvedMatch_ be result of **PACKAGE_IMPORTS_EXPORTS_RESOLVE**( +> _matchKey_, _exports_, _packageURL_, **false**, _conditions_). +> 1. If _resolvedMatch_._resolve_ is not **null** or **undefined**, then +> 1. Return _resolvedMatch_. +> 1. Throw a _Package Path Not Exported_ error. + +**PACKAGE_IMPORTS_RESOLVE**(_specifier_, _parentURL_, _conditions_) + +> 1. Assert: _specifier_ begins with _"#"_. +> 1. If _specifier_ is exactly equal to _"#"_ or starts with _"#/"_, then +> 1. Throw an _Invalid Module Specifier_ error. +> 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_). +> 1. If _packageURL_ is not **null**, then +> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). +> 1. If _pjson.imports_ is a non-null Object, then +> 1. Let _resolvedMatch_ be the result of +> **PACKAGE_IMPORTS_EXPORTS_RESOLVE**(_specifier_, _pjson.imports_, +> _packageURL_, **true**, _conditions_). +> 1. If _resolvedMatch_._resolve_ is not **null** or **undefined**, then +> 1. Return _resolvedMatch_. +> 1. Throw a _Package Import Not Defined_ error. + +**PACKAGE_IMPORTS_EXPORTS_RESOLVE**(_matchKey_, _matchObj_, _packageURL_, +_isImports_, _conditions_) -**PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_, _internal_, _env_) +> 1. If _matchKey_ is a key of _matchObj_, and does not end in _"*"_, then +> 1. Let _target_ be the value of _matchObj_\[_matchKey_\]. +> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> _packageURL_, _target_, _""_, _isImports_, _conditions_). +> 1. Return the object _{ resolved, exact: **true** }_. +> 1. Let _expansionKeys_ be the list of keys of _matchObj_ ending in _"/"_, +> sorted by length descending. +> 1. For each key _expansionKey_ in _expansionKeys_, do +> 1. If _matchKey_ starts with _expansionKey_, then +> 1. Let _target_ be the value of _matchObj_\[_expansionKey_\]. +> 1. Let _subpath_ be the substring of _matchKey_ starting at the +> index of the length of _expansionKey_. +> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> _packageURL_, _target_, _subpath_, _isImports_, _conditions_). +> 1. Return the object _{ resolved, exact: **false** }_. +> 1. Return the object _{ resolved: **null**, exact: **true** }_. + +**PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_, _internal_, +_conditions_) > 1. If _target_ is a String, then -> 1. If _target_ contains any _"node_modules"_ segments including -> _"node_modules"_ percent-encoding, throw an _Invalid Package Target_ -> error. > 1. If _subpath_ has non-zero length and _target_ does not end with _"/"_, > throw an _Invalid Module Specifier_ error. > 1. If _target_ does not start with _"./"_, then -> 1. If _target_ does not start with _"../"_ or _"/"_ and is not a valid -> URL, then -> 1. If _internal_ is **true**, return **PACKAGE_RESOLVE**( -> _target_ + _subpath_, _packageURL_ + _"/"_)_. -> 1. Otherwise throw an _Invalid Package Target_ error. +> 1. If _internal_ is **true** and _target_ does not start with _"../"_ or +> _"/"_ and is not a valid URL, then +> 1. Return **PACKAGE_RESOLVE**(_target_ + _subpath_, +> _packageURL_ + _"/"_)_. +> 1. Otherwise, throw an _Invalid Package Target_ error. +> 1. If _target_ split on _"/"_ or _"\\"_ contains any _"."_, _".."_ or +> _"node_modules"_ segments after the first segment, throw an +> _Invalid Module Specifier_ error. > 1. Let _resolvedTarget_ be the URL resolution of the concatenation of > _packageURL_ and _target_. -> 1. If _resolvedTarget_ is not contained in _packageURL_, throw an -> _Invalid Package Target_ error. -> 1. Let _resolved_ be the URL resolution of the concatenation of -> _subpath_ and _resolvedTarget_. -> 1. If _resolved_ is not contained in _resolvedTarget_, throw an -> _Invalid Module Specifier_ error. -> 1. Return _resolved_. +> 1. Assert: _resolvedTarget_ is contained in _packageURL_. +> 1. If _subpath_ split on _"/"_ or _"\\"_ contains any _"."_, _".."_ or +> _"node_modules"_ segments, throw an _Invalid Module Specifier_ error. +> 1. Return the URL resolution of the concatenation of _subpath_ and +> _resolvedTarget_. > 1. Otherwise, if _target_ is a non-null Object, then > 1. If _exports_ contains any index property keys, as defined in ECMA-262 > [6.1.7 Array Index][], throw an _Invalid Package Configuration_ error. > 1. For each property _p_ of _target_, in object insertion order as, -> 1. If _p_ equals _"default"_ or _env_ contains an entry for _p_, then +> 1. If _p_ equals _"default"_ or _conditions_ contains an entry for _p_, +> then > 1. Let _targetValue_ be the value of the _p_ property in _target_. > 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( -> _packageURL_, _targetValue_, _subpath_, _internal_, _env_) +> _packageURL_, _targetValue_, _subpath_, _internal_, _conditions_). > 1. If _resolved_ is equal to **undefined**, continue the loop. > 1. Return _resolved_. > 1. Return **undefined**. @@ -223,7 +219,7 @@ The resolver can throw the following errors: > 1. If _target.length is zero, return **null**. > 1. For each item _targetValue_ in _target_, do > 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( -> _packageURL_, _targetValue_, _subpath_, _internal_, _env_), +> _packageURL_, _targetValue_, _subpath_, _internal_, _conditions_), > continuing the loop on any _Invalid Package Target_ error. > 1. If _resolved_ is **undefined**, continue the loop. > 1. Return _resolved_. @@ -231,31 +227,6 @@ The resolver can throw the following errors: > 1. Otherwise, if _target_ is _null_, return **null**. > 1. Otherwise throw an _Invalid Package Target_ error. -**PACKAGE_INTERNAL_RESOLVE**(_specifier_, _parentURL_) - -> 1. Assert: _specifier_ begins with _"#"_. -> 1. If _specifier_ is exactly equal to _"#"_ or starts with _"#/"_, then -> 1. Throw an _Invalid Module Specifier_ error. -> 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_). -> 1. If _packageURL_ is not **null**, then -> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). -> 1. If _pjson.imports is a non-null Object, then -> 1. Let _imports_ be _pjson.imports_. -> 1. If _specifier_ is a key of _imports_, then -> 1. Let _target_ be the value of _imports\[specifier\]_. -> 1. Return **PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, -> _""_, **true**, _defaultEnv_). -> 1. Let _directoryKeys_ be the list of keys of _imports_ ending in -> _"/"_, sorted by length descending. -> 1. For each key _directory_ in _directoryKeys_, do -> 1. If _specifier_ starts with _directory_, then -> 1. Let _target_ be the value of _imports\[directory\]_. -> 1. Let _subpath_ be the substring of _target_ starting at the -> index of the length of _directory_. -> 1. Return **PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, -> _subpath_, **true**, _defaultEnv_). -> 1. Return **null**. - **ESM_FORMAT**(_url_) > 1. Assert: _url_ corresponds to an existing file. @@ -275,11 +246,11 @@ The resolver can throw the following errors: > 1. Let _scopeURL_ be _url_. > 1. While _scopeURL_ is not the file system root, +> 1. Set _scopeURL_ to the parent URL of _scopeURL_. > 1. If _scopeURL_ ends in a _"node_modules"_ path segment, return **null**. > 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_scopeURL_). > 1. If _pjson_ is not **null**, then > 1. Return _pjson_. -> 1. Set _scopeURL_ to the parent URL of _scopeURL_. > 1. Return **null**. **READ_PACKAGE_JSON**(_packageURL_) diff --git a/esm/resolving_user_conditions.md b/esm/resolving_user_conditions.md new file mode 100644 index 00000000..50a76b98 --- /dev/null +++ b/esm/resolving_user_conditions.md @@ -0,0 +1,14 @@ + +When running Node.js, custom user conditions can be added with the +`--conditions` or `-u` flag: + +```bash +node --conditions=development main.js +``` + +which would then resolve the `"development"` condition in package imports and +exports, while resolving the existing `"node"`, `"default"`, `"import"`, and +`"require"` conditions as appropriate. + +Any number of custom conditions can be set with repeat flags. + diff --git a/fs/callback_example.md b/fs/callback_example.md new file mode 100644 index 00000000..a6de4626 --- /dev/null +++ b/fs/callback_example.md @@ -0,0 +1,14 @@ + +异步的形式总是把完成回调作为其最后一个参数。 +传给完成回调的参数取决于具体方法，但第一个参数总是预留给异常。 +如果操作被成功地完成，则第一个参数会为 `null` 或 `undefined`。 + +```js +const fs = require('fs'); + +fs.unlink('文件', (err) => { + if (err) throw err; + console.log('已成功地删除文件'); +}); +``` + diff --git a/fs/file_paths.md b/fs/file_paths.md index 1729fedb..6eefecc9 100644 --- a/fs/file_paths.md +++ b/fs/file_paths.md @@ -2,7 +2,7 @@ 大多数 `fs` 操作接受的文件路径可以指定为字符串、[`Buffer`]、或 [`URL`] 对象（使用 `file:` 协议）。 字符串形式的路径会被解释为 UTF-8 字符序列（标识绝对或相对的文件名）。 -相对路径会相对于当前工作目录（由 `process.cwd()` 指定）进行处理。 +相对路径会相对于当前工作目录（通过调用 `process.cwd()` 确定）进行处理。 在 POSIX 上使用绝对路径的示例： diff --git a/fs/file_system.md b/fs/file_system.md index ba1cbc05..3b0f8b1b 100644 --- a/fs/file_system.md +++ b/fs/file_system.md @@ -7,7 +7,7 @@ -`fs` 模块提供了用于与文件系统进行交互（以类似于标准 POSIX 函数的方式）的 API。 +`fs` 模块可用于与文件系统进行交互（以类似于标准 POSIX 函数的方式）。 要使用此模块： @@ -15,81 +15,6 @@ const fs = require('fs'); ``` -所有的文件系统操作都具有同步和异步的形式。 +所有的文件系统操作都具有同步的、回调的、以及基于 promise 的形式。 -异步的形式总是把完成回调作为其最后一个参数。 -传给完成回调的参数取决于具体方法，但第一个参数总是预留给异常。 -如果操作被成功地完成，则第一个参数会为 `null` 或 `undefined`。 - -```js -const fs = require('fs'); - -fs.unlink('文件', (err) => { - if (err) throw err; - console.log('已成功地删除文件'); -}); -``` - -当使用同步的操作时，发生的异常会被立即地抛出，可以使用 `try…catch` 处理，也可以冒泡。 - -```js -const fs = require('fs'); - -try { - fs.unlinkSync('文件'); - console.log('已成功地删除文件'); -} catch (err) { - // 处理错误 -} -``` - -当使用异步的方法时，无法保证顺序。 -因此，以下的操作容易出错，因为 `fs.stat()` 操作可能在 `fs.rename()` 操作之前完成： - - -```js -fs.rename('旧文件', '新文件', (err) => { - if (err) throw err; - console.log('重命名完成'); -}); -fs.stat('新文件', (err, stats) => { - if (err) throw err; - console.log(`文件属性: ${JSON.stringify(stats)}`); -}); -``` - -若要正确地排序这些操作，则移动 `fs.stat()` 调用到 `fs.rename()` 操作的回调中： - -```js -fs.rename('旧文件', '新文件', (err) => { - if (err) throw err; - fs.stat('新文件', (err, stats) => { - if (err) throw err; - console.log(`文件属性: ${JSON.stringify(stats)}`); - }); -}); -``` - -在繁忙的进程中，应使用这些调用的异步版本。 -同步的版本会阻塞整个进程（停止所有的连接），直到它们完成。 - -大多数异步的 `fs` 函数都可以省略回调参数。 -但是，不建议这么使用。 -当省略回调时，会使用默认的回调来抛出错误。 -若要获取对原始调用点的跟踪，则设置 `NODE_DEBUG` 环境变量： - -```console -$ cat script.js -function bad() { - require('fs').readFile('/'); -} -bad(); - -$ env NODE_DEBUG=fs node script.js -fs.js:88 - throw backtrace; - ^ -Error: EISDIR: illegal operation on a directory, read - -``` diff --git a/fs/filehandle_close.md b/fs/filehandle_close.md index ee93f6b9..e1b9c5d6 100644 --- a/fs/filehandle_close.md +++ b/fs/filehandle_close.md @@ -3,7 +3,8 @@ added: v10.0.0 --> * 返回: {Promise} 如果底层的文件描述符被关闭则 `Promise` 将会被解决，如果关闭时发生错误则将 `Promise` 将会被拒绝。 -关闭文件描述符。 + +等待句柄上的所有处理中的操作完成之后，关闭文件句柄。 ```js const fsPromises = require('fs').promises; diff --git a/fs/ordering_of_callback_and_promise_based_operations.md b/fs/ordering_of_callback_and_promise_based_operations.md new file mode 100644 index 00000000..7e1e2e5a --- /dev/null +++ b/fs/ordering_of_callback_and_promise_based_operations.md @@ -0,0 +1,44 @@ + +当使用异步的方法时，无法保证顺序。 +因此，以下的操作容易出错，因为 `fs.stat()` 操作可能在 `fs.rename()` 操作之前完成： + + +```js +fs.rename('旧文件', '新文件', (err) => { + if (err) throw err; + console.log('重命名完成'); +}); +fs.stat('新文件', (err, stats) => { + if (err) throw err; + console.log(`文件属性: ${JSON.stringify(stats)}`); +}); +``` + +若要正确地排序这些操作，则移动 `fs.stat()` 调用到 `fs.rename()` 操作的回调中： + +```js +fs.rename('旧文件', '新文件', (err) => { + if (err) throw err; + fs.stat('新文件', (err, stats) => { + if (err) throw err; + console.log(`文件属性: ${JSON.stringify(stats)}`); + }); +}); +``` + +或者，使用基于 promise 的 API： + +```js +const fs = require('fs/promises'); + +(async function(from, to) { + try { + await fs.rename(from, to); + const stats = await fs.stat(to); + console.log(`文件属性: ${JSON.stringify(stats)}`); + } catch (error) { + console.error('出错：', error.message); + } +})('旧文件', '新文件'); +``` + diff --git a/fs/promise_example.md b/fs/promise_example.md new file mode 100644 index 00000000..9698407c --- /dev/null +++ b/fs/promise_example.md @@ -0,0 +1,16 @@ + +基于 Promise 的操作会返回 `Promise`（当异步操作完成时会被解决）。 + +```js +const fs = require('fs/promises'); + +(async function(path) { + try { + await fs.unlink(path); + console.log(`已成功地删除文件 ${path}`); + } catch (error) { + console.error('出错：', error.message); + } +})('文件'); +``` + diff --git a/fs/synchronous_example.md b/fs/synchronous_example.md new file mode 100644 index 00000000..c8115a21 --- /dev/null +++ b/fs/synchronous_example.md @@ -0,0 +1,14 @@ + +同步的形式会阻止 Node.js 事件循环和进一步的 JavaScript 执行，直到操作完成。 +异常会被立即地抛出，可以使用 `try…catch` 处理，也可以冒泡。 + +```js +const fs = require('fs'); + +try { + fs.unlinkSync('文件'); + console.log('已成功地删除文件'); +} catch (err) { + // 处理错误 +} +``` diff --git a/http/event_close_1.md b/http/event_close_1.md index 3c43a043..37907a41 100644 --- a/http/event_close_1.md +++ b/http/event_close_1.md @@ -2,5 +2,5 @@ added: v0.6.7 --> -表明底层的连接已被终止。 +表明响应已完成，或者其底层的连接过早被终止（在响应完成之前）。 diff --git a/http2/settings_object.md b/http2/settings_object.md index 9270e1b1..397c676b 100644 --- a/http2/settings_object.md +++ b/http2/settings_object.md @@ -36,6 +36,7 @@ properties. * `maxHeaderListSize` {number} Specifies the maximum size (uncompressed octets) of header list that will be accepted. The minimum allowed value is 0. The maximum allowed value is 232-1. **Default:** `65535`. +* `maxHeaderSize` {number} Alias for `maxHeaderListSize`. * `enableConnectProtocol`{boolean} Specifies `true` if the "Extended Connect Protocol" defined by [RFC 8441][] is to be enabled. This setting is only meaningful if sent by the server. Once the `enableConnectProtocol` setting diff --git a/module/class_module_sourcemap.md b/module/class_module_sourcemap.md new file mode 100644 index 00000000..fe510d1f --- /dev/null +++ b/module/class_module_sourcemap.md @@ -0,0 +1,6 @@ + + diff --git a/modules/module_builtinmodules.md b/module/module_builtinmodules.md similarity index 100% rename from modules/module_builtinmodules.md rename to module/module_builtinmodules.md diff --git a/modules/module_createrequire_filename.md b/module/module_createrequire_filename.md similarity index 100% rename from modules/module_createrequire_filename.md rename to module/module_createrequire_filename.md diff --git a/modules/module_createrequirefrompath_filename.md b/module/module_createrequirefrompath_filename.md similarity index 100% rename from modules/module_createrequirefrompath_filename.md rename to module/module_createrequirefrompath_filename.md diff --git a/modules/module_findsourcemap_path_error.md b/module/module_findsourcemap_path_error.md similarity index 94% rename from modules/module_findsourcemap_path_error.md rename to module/module_findsourcemap_path_error.md index 3162ccda..de845cf3 100644 --- a/modules/module_findsourcemap_path_error.md +++ b/module/module_findsourcemap_path_error.md @@ -1,5 +1,7 @@ * `path` {string} diff --git a/modules/module_syncbuiltinesmexports.md b/module/module_syncbuiltinesmexports.md similarity index 100% rename from modules/module_syncbuiltinesmexports.md rename to module/module_syncbuiltinesmexports.md diff --git a/module/modules_module_api.md b/module/modules_module_api.md new file mode 100644 index 00000000..a2bf2246 --- /dev/null +++ b/module/modules_module_api.md @@ -0,0 +1,3 @@ + + + diff --git a/modules/new_sourcemap_payload.md b/module/new_sourcemap_payload.md similarity index 100% rename from modules/new_sourcemap_payload.md rename to module/new_sourcemap_payload.md diff --git a/module/source_map_v3_support.md b/module/source_map_v3_support.md new file mode 100644 index 00000000..5974ef57 --- /dev/null +++ b/module/source_map_v3_support.md @@ -0,0 +1,20 @@ + + +> Stability: 1 - Experimental + +Helpers for interacting with the source map cache. This cache is +populated when source map parsing is enabled and +[source map include directives][] are found in a modules' footer. + +To enable source map parsing, Node.js must be run with the flag +[`--enable-source-maps`][], or with code coverage enabled by setting +[`NODE_V8_COVERAGE=dir`][]. + +```js +const { findSourceMap, SourceMap } = require('module'); +``` + diff --git a/modules/sourcemap_findentry_linenumber_columnnumber.md b/module/sourcemap_findentry_linenumber_columnnumber.md similarity index 96% rename from modules/sourcemap_findentry_linenumber_columnnumber.md rename to module/sourcemap_findentry_linenumber_columnnumber.md index f762c3a4..8c34a976 100644 --- a/modules/sourcemap_findentry_linenumber_columnnumber.md +++ b/module/sourcemap_findentry_linenumber_columnnumber.md @@ -18,20 +18,6 @@ consists of the following keys: - - - - - - - - - - - - - - diff --git a/modules/sourcemap_payload.md b/module/sourcemap_payload.md similarity index 100% rename from modules/sourcemap_payload.md rename to module/sourcemap_payload.md diff --git a/module/the_module_object.md b/module/the_module_object.md new file mode 100644 index 00000000..011ae735 --- /dev/null +++ b/module/the_module_object.md @@ -0,0 +1,7 @@ + +* {Object} + +当与 `Module` 实例（`module` 变量常见于文件模块中）进行交互时，提供通用的工具方法。 +通过 `require('module')` 访问。 + + diff --git a/modules/all_together.md b/modules/all_together.md index 3c99fa37..35652ca5 100644 --- a/modules/all_together.md +++ b/modules/all_together.md @@ -17,10 +17,10 @@ require(X) from module at path Y b. LOAD_AS_DIRECTORY(Y + X) c. THROW "not found" 4. If X begins with '#' - a. LOAD_INTERAL_IMPORT(X, Y) -4. LOAD_SELF_REFERENCE(X, Y) -5. LOAD_NODE_MODULES(X, dirname(Y)) -6. THROW "not found" + a. LOAD_PACKAGE_IMPORTS(X, dirname(Y)) +5. LOAD_PACKAGE_SELF(X, dirname(Y)) +6. LOAD_NODE_MODULES(X, dirname(Y)) +7. THROW "not found" LOAD_AS_FILE(X) 1. If X is a file, load X as its file extension format. STOP @@ -47,7 +47,7 @@ LOAD_AS_DIRECTORY(X) LOAD_NODE_MODULES(X, START) 1. let DIRS = NODE_MODULES_PATHS(START) 2. for each DIR in DIRS: - a. LOAD_PACKAGE_EXPORTS(DIR, X) + a. LOAD_PACKAGE_EXPORTS(X, DIR) b. LOAD_AS_FILE(DIR/X) c. LOAD_AS_DIRECTORY(DIR/X) @@ -62,46 +62,44 @@ NODE_MODULES_PATHS(START) d. let I = I - 1 5. return DIRS -LOAD_SELF_REFERENCE(X, START) -1. Find the closest package scope to START. +LOAD_PACKAGE_IMPORTS(X, DIR) +1. Find the closest package scope SCOPE to DIR. 2. If no scope was found, return. -3. If the `package.json` has no "exports", return. -4. If the name in `package.json` is a prefix of X, then - a. Load the remainder of X relative to this package as if it was - loaded via `LOAD_NODE_MODULES` with a name in `package.json`. +3. If the SCOPE/package.json "imports" is null or undefined, return. +4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE), + ["node", "require"]) defined in the ESM resolver. +5. RESOLVE_ESM_MATCH(MATCH). -LOAD_PACKAGE_EXPORTS(DIR, X) -1. Try to interpret X as a combination of name and subpath where the name +LOAD_PACKAGE_EXPORTS(X, DIR) +1. Try to interpret X as a combination of NAME and SUBPATH where the name may have a @scope/ prefix and the subpath begins with a slash (`/`). -2. If X does not match this pattern or DIR/name/package.json is not a file, +2. If X does not match this pattern or DIR/NAME/package.json is not a file, return. -3. Parse DIR/name/package.json, and look for "exports" field. +3. Parse DIR/NAME/package.json, and look for "exports" field. 4. If "exports" is null or undefined, return. -5. If "exports" is an object with some keys starting with "." and some keys - not starting with ".", throw "invalid config". -6. If "exports" is a string, or object with no keys starting with ".", treat - it as having that value as its "." object property. -7. If subpath is "." and "exports" does not have a "." entry, return. -8. Find the longest key in "exports" that the subpath starts with. -9. If no such key can be found, throw "not found". -10. let RESOLVED = - fileURLToPath(PACKAGE_EXPORTS_TARGET_RESOLVE(pathToFileURL(DIR/name), - exports[key], subpath.slice(key.length), ["node", "require"])), as defined - in the ESM resolver. -11. If key ends with "/": - a. LOAD_AS_FILE(RESOLVED) - b. LOAD_AS_DIRECTORY(RESOLVED) -12. Otherwise - a. If RESOLVED is a file, load it as its file extension format. STOP -13. Throw "not found" +5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH, + `package.json` "exports", ["node", "require"]) defined in the ESM resolver. +6. RESOLVE_ESM_MATCH(MATCH) -LOAD_INTERNAL_IMPORT(X, START) -1. Find the closest package scope to START. -2. If no scope was found or the `package.json` has no "imports", return. -3. let RESOLVED = - fileURLToPath(PACKAGE_INTERNAL_RESOLVE(X, pathToFileURL(START)), as defined - in the ESM resolver. -4. If RESOLVED is not a valid file, throw "not found" -5. Load RESOLVED as its file extension format. STOP +LOAD_PACKAGE_SELF(X, DIR) +1. Find the closest package scope SCOPE to DIR. +2. If no scope was found, return. +3. If the SCOPE/package.json "exports" is null or undefined, return. +4. If the SCOPE/package.json "name" is not the first segment of X, return. +5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE), + "." + X.slice("name".length), `package.json` "exports", ["node", "require"]) + defined in the ESM resolver. +6. RESOLVE_ESM_MATCH(MATCH) + +RESOLVE_ESM_MATCH(MATCH) +1. let { RESOLVED, EXACT } = MATCH +2. let RESOLVED_PATH = fileURLToPath(RESOLVED) +3. If EXACT is true, + a. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension + format. STOP +4. Otherwise, if EXACT is false, + a. LOAD_AS_FILE(RESOLVED_PATH) + b. LOAD_AS_DIRECTORY(RESOLVED_PATH) +5. THROW "not found" ``` diff --git a/modules/class_module_sourcemap.md b/modules/class_module_sourcemap.md deleted file mode 100644 index 7d78ee53..00000000 --- a/modules/class_module_sourcemap.md +++ /dev/null @@ -1,4 +0,0 @@ - - diff --git a/modules/modules.md b/modules/modules_commonjs_modules.md similarity index 100% rename from modules/modules.md rename to modules/modules_commonjs_modules.md diff --git a/modules/source_map_v3_support.md b/modules/source_map_v3_support.md index 32c527ff..48a37225 100644 --- a/modules/source_map_v3_support.md +++ b/modules/source_map_v3_support.md @@ -1,18 +1,25 @@ - -> Stability: 1 - Experimental +This section was moved to +[Modules: `module` core module](modules_module.html#modules_module_source_map_v3_support). + + +* `module.findSourceMap(path[, error])` +* Class: `module.SourceMap` + * `new SourceMap(payload)` + * `sourceMap.payload` + * `sourceMap.findEntry(lineNumber, columnNumber)` + + + + + + + + + + + -Helpers for interacting with the source map cache. This cache is -populated when source map parsing is enabled and -[source map include directives][] are found in a modules' footer. -To enable source map parsing, Node.js must be run with the flag -[`--enable-source-maps`][], or with code coverage enabled by setting -[`NODE_V8_COVERAGE=dir`][]. -```js -const { findSourceMap, SourceMap } = require('module'); -``` diff --git a/modules/the_module_object_1.md b/modules/the_module_object_1.md index 18841ccd..fa72c24b 100644 --- a/modules/the_module_object_1.md +++ b/modules/the_module_object_1.md @@ -1,11 +1,9 @@ - +本章节移至 [`module` 模块][_module_object]。 -* {Object} - -为 `Module` 实例提供通用方法，`module` 变量常见于文件模块中。 -通过 `require('module')` 获取。 +* [`module.builtinModules`][_module.builtinModules] +* [`module.createRequire(filename)`][_module.createRequire] +* [`module.createRequireFromPath(filename)`][_module.createRequireFromPath] +* [`module.syncBuiltinESMExports()`][_module.syncBuiltinESMExports] diff --git a/n-api/environment_life_cycle_apis.md b/n-api/environment_life_cycle_apis.md index a854f6d9..ece7e36a 100644 --- a/n-api/environment_life_cycle_apis.md +++ b/n-api/environment_life_cycle_apis.md @@ -1,6 +1,4 @@ -> Stability: 1 - Experimental - [Section 8.7][] of the [ECMAScript Language Specification][] defines the concept of an "Agent" as a self-contained environment in which JavaScript code runs. Multiple such Agents may be started and terminated either concurrently or in diff --git a/n-api/n_api.md b/n-api/n_api.md index 87d0f262..c37efb34 100644 --- a/n-api/n_api.md +++ b/n-api/n_api.md @@ -77,3 +77,7 @@ it still gets the benefits of the ABI stability provided by the C API. When using `node-addon-api` instead of the C APIs, start with the API [docs][] for `node-addon-api`. +The [N-API Resource](https://nodejs.github.io/node-addon-examples/) offers an +excellent orientation and tips for developers just getting started with N-API +and node-addon-api. + diff --git a/policy/dependency_redirection.md b/policy/dependency_redirection.md index 97d614ef..95279c0a 100644 --- a/policy/dependency_redirection.md +++ b/policy/dependency_redirection.md @@ -6,24 +6,25 @@ replaced. ```json { - "builtins": [], "resources": { "./app/checked.js": { "dependencies": { "fs": true, - "os": "./app/node_modules/alt-os" + "os": "./app/node_modules/alt-os", + "http": { "import": true } } } } } ``` -The dependencies are keyed by the requested string specifier and have values -of either `true` or a string pointing to a module that will be resolved. +The dependencies are keyed by the requested specifier string and have values +of either `true`, `null`, a string pointing to a module that will be resolved, +or a conditions object. The specifier string does not perform any searching and must match exactly -what is provided to the `require()`. Therefore, multiple specifiers may be -needed in the policy if `require()` uses multiple different strings to point +what is provided to the `require()` or `import`. Therefore, multiple specifiers +may be needed in the policy if it uses multiple different strings to point to the same module (such as excluding the extension). If the value of the redirection is `true` the default searching algorithms will @@ -32,17 +33,28 @@ be used to find the module. If the value of the redirection is a string, it will be resolved relative to the manifest and then immediately be used without searching. -Any specifier string that is `require()`ed and not listed in the dependencies -will result in an error according to the policy. +Any specifier string that is attempted to resolved and not listed in the +dependencies will result in an error according to the policy. Redirection will not prevent access to APIs through means such as direct access to `require.cache` and/or through `module.constructor` which allow access to -loading modules. Policy redirection only affect specifiers to `require()`. -Other means such as to prevent undesired access to APIs through variables are -necessary to lock down that path of loading modules. +loading modules. Policy redirection only affect specifiers to `require()` and +`import`. Other means such as to prevent undesired access to APIs through +variables are necessary to lock down that path of loading modules. A boolean value of `true` for the dependencies map can be specified to allow a module to load any specifier without redirection. This can be useful for local development and may have some valid usage in production, but should be used only with care after auditing a module to ensure its behavior is valid. +Similar to `"exports"` in `package.json` dependencies can also be specified to +be objects containing conditions which branch how dependencies are loaded. In +the above example `"http"` will be allowed when the `"import"` condition is +part of loading it. + +A value of `null` for the resolved value will cause the resolution to fail. +This can be used to ensure some kinds dynamic access are explicitly prevented. + +Unknown values for the resolved module location will cause failure, but are +not guaranteed to be forwards compatible. + diff --git a/process/process_version.md b/process/process_version.md index dab02e68..fb713810 100644 --- a/process/process_version.md +++ b/process/process_version.md @@ -4,7 +4,7 @@ added: v0.1.3 * {string} -`process.version` 属性返回 Node.js 的版本信息。 +`process.version` 属性返回 Node.js 的版本信息（以 `v<主版本号>.<次版本号>.<补丁号>` 的形式）。 ```js console.log(`版本: ${process.version}`); diff --git a/stream/new_stream_duplex_options.md b/stream/new_stream_duplex_options.md index 57b7eabb..67cfa2ef 100644 --- a/stream/new_stream_duplex_options.md +++ b/stream/new_stream_duplex_options.md @@ -9,6 +9,10 @@ changes: * `options` {Object} 同时传给 `Writable` 和 `Readable` 的构造函数。 * `allowHalfOpen` {boolean} 如果设为 `false`，则当可读端结束时，可写端也会自动结束。 默认为 `true`。 + * `readable` {boolean} Sets whether the `Duplex` should be readable. + **Default:** `true`. + * `writable` {boolean} Sets whether the `Duplex` should be writable. + **Default:** `true`. * `readableObjectMode` {boolean} 设置流的可读端为 `objectMode`。 如果 `objectMode` 为 `true`，则不起作用。 默认为 `false`。 diff --git a/timers/timeout_symbol_toprimitive.md b/timers/timeout_symbol_toprimitive.md new file mode 100644 index 00000000..ffe52e53 --- /dev/null +++ b/timers/timeout_symbol_toprimitive.md @@ -0,0 +1,14 @@ + + +* Returns: {integer} 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. + diff --git a/tls/class_cryptostream.md b/tls/class_tls_cryptostream.md similarity index 100% rename from tls/class_cryptostream.md rename to tls/class_tls_cryptostream.md diff --git a/tls/class_securepair.md b/tls/class_tls_securepair.md similarity index 100% rename from tls/class_securepair.md rename to tls/class_tls_securepair.md diff --git a/tls/deprecated_apis.md b/tls/deprecated_apis.md deleted file mode 100644 index 8b137891..00000000 --- a/tls/deprecated_apis.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md b/tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md index 02bad438..c49c1fdc 100644 --- a/tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md +++ b/tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md @@ -60,61 +60,3 @@ secureSocket = tls.TLSSocket(socket, options); where `secureSocket` has the same API as `pair.cleartext`. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tls/tls_default_min_version.md b/tls/tls_default_min_version.md index 333584fa..ae3f053d 100644 --- a/tls/tls_default_min_version.md +++ b/tls/tls_default_min_version.md @@ -11,3 +11,61 @@ added: v11.4.0 `'TLSv1.3'`. If multiple of the options are provided, the lowest minimum is used. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/util/debuglog_enabled.md b/util/debuglog_enabled.md new file mode 100644 index 00000000..54e64d8b --- /dev/null +++ b/util/debuglog_enabled.md @@ -0,0 +1,27 @@ + + +* {boolean} + +The `util.debuglog().enabled` getter is used to create a test that can be used +in conditionals based on the existence of the `NODE_DEBUG` environment variable. +If the `section` name appears within the value of that environment variable, +then the returned value will be `true`. If not, then the returned value will be +`false`. + +```js +const util = require('util'); +const enabled = util.debuglog('foo').enabled; +if (enabled) { + console.log('hello from foo [%d]', 123); +} +``` + +If this program is run with `NODE_DEBUG=foo` in the environment, then it will +output something like: + +```console +hello from foo [123] +``` + diff --git a/util/util_debug_section.md b/util/util_debug_section.md new file mode 100644 index 00000000..a7d2381b --- /dev/null +++ b/util/util_debug_section.md @@ -0,0 +1,7 @@ + + +Alias for `util.debuglog`. Usage allows for readability of that doesn't imply +logging when only using `util.debuglog().enabled`. + diff --git a/worker_threads/new_worker_filename_options.md b/worker_threads/new_worker_filename_options.md index 1367398b..7a207f2c 100644 --- a/worker_threads/new_worker_filename_options.md +++ b/worker_threads/new_worker_filename_options.md @@ -1,6 +1,13 @@ -* `filename` {string} 工作线程主脚本的路径。必须是以 `./` 或 `../` 开头的绝对路径或相对路径（即相对于当前工作目录）、或者使用 `file:` 协议的 WHATWG `URL` 对象。 +* `filename` {string} 工作线程主脚本的路径。必须是以 `./` 或 `../` 开头的绝对路径或相对路径（即相对于当前工作目录）、或者使用 `file:` 或 `data:` 协议的 WHATWG `URL` 对象。 + When using a [`data:` URL][], the data is interpreted based on MIME type using the [ECMAScript module loader][]. 如果 `options.eval` 为 `true`，则这是一个包含 JavaScript 代码而不是路径的字符串。 * `options` {Object} * `argv` {any[]} 参数列表，其将会被字符串化并附加到工作线程中的 `process.argv`。 diff --git a/worker_threads/worker_unref.md b/worker_threads/worker_unref.md index c41c7f69..4aef81c0 100644 --- a/worker_threads/worker_unref.md +++ b/worker_threads/worker_unref.md @@ -60,6 +60,8 @@ active handle in the event system. If the worker is already `unref()`ed calling + +