diff --git a/child_process/subprocess_signalcode.md b/child_process/subprocess_signalcode.md index 08433eff..c51da5ce 100644 --- a/child_process/subprocess_signalcode.md +++ b/child_process/subprocess_signalcode.md @@ -1,6 +1,6 @@ -* {integer} +* {string|null} -The `subprocess.signalCode` property indicates the signal number received by +The `subprocess.signalCode` property indicates the signal received by the child process if any, else `null`. diff --git a/crypto/class_hash.md b/crypto/class_hash.md index 422b5b14..71dec0c0 100644 --- a/crypto/class_hash.md +++ b/crypto/class_hash.md @@ -41,7 +41,7 @@ const fs = require('fs'); const hash = crypto.createHash('sha256'); const input = fs.createReadStream('要创建哈希摘要的数据.txt'); -input.pipe(hash).pipe(process.stdout); +input.pipe(hash).setEncoding('hex').pipe(process.stdout); ``` 示例，使用 [`hash.update()`] 和 [`hash.digest()`] 方法： diff --git a/crypto/crypto_createsecretkey_key.md b/crypto/crypto_createsecretkey_key.md index e55f576e..9d7d2fb3 100644 --- a/crypto/crypto_createsecretkey_key.md +++ b/crypto/crypto_createsecretkey_key.md @@ -2,7 +2,7 @@ added: v11.6.0 --> -* `key` {Buffer} +* `key` {Buffer | TypedArray | DataView} * Returns: {KeyObject} Creates and returns a new key object containing a secret key for symmetric diff --git a/errors/err_console_writable_stream.md b/errors/err_console_writable_stream.md index 23ddc803..fa249d69 100644 --- a/errors/err_console_writable_stream.md +++ b/errors/err_console_writable_stream.md @@ -2,4 +2,4 @@ `Console` was instantiated without `stdout` stream, or `Console` has a non-writable `stdout` or `stderr` stream. - + diff --git a/errors/err_construct_call_invalid.md b/errors/err_construct_call_invalid.md index 193e1130..508d37e7 100644 --- a/errors/err_construct_call_invalid.md +++ b/errors/err_construct_call_invalid.md @@ -4,4 +4,4 @@ added: v12.5.0 A class constructor was called that is not callable. - + diff --git a/errors/err_construct_call_required.md b/errors/err_construct_call_required.md index 7c363fbb..bf97cbea 100644 --- a/errors/err_construct_call_required.md +++ b/errors/err_construct_call_required.md @@ -1,4 +1,4 @@ A constructor for a class was called without `new`. - + diff --git a/errors/err_context_not_initialized.md b/errors/err_context_not_initialized.md index 6f152c80..5f8014b1 100644 --- a/errors/err_context_not_initialized.md +++ b/errors/err_context_not_initialized.md @@ -4,4 +4,4 @@ when an error occurs (and is caught) during the creation of the context, for example, when the allocation fails or the maximum call stack size is reached when the context is created. - + diff --git a/errors/err_fs_invalid_symlink_type.md b/errors/err_fs_invalid_symlink_type.md index 4fed2d5f..3ca6c41b 100644 --- a/errors/err_fs_invalid_symlink_type.md +++ b/errors/err_fs_invalid_symlink_type.md @@ -2,4 +2,4 @@ An invalid symlink type was passed to the [`fs.symlink()`][] or [`fs.symlinkSync()`][] methods. - + diff --git a/errors/err_http2_goaway_session.md b/errors/err_http2_goaway_session.md index 8fd891e0..0ed9afc5 100644 --- a/errors/err_http2_goaway_session.md +++ b/errors/err_http2_goaway_session.md @@ -2,4 +2,4 @@ New HTTP/2 Streams may not be opened after the `Http2Session` has received a `GOAWAY` frame from the connected peer. - + diff --git a/errors/err_http2_headers_sent.md b/errors/err_http2_headers_sent.md index e7c8f91e..34eafd34 100644 --- a/errors/err_http2_headers_sent.md +++ b/errors/err_http2_headers_sent.md @@ -1,4 +1,4 @@ An attempt was made to send multiple response headers. - + diff --git a/errors/err_http2_unsupported_protocol.md b/errors/err_http2_unsupported_protocol.md index 8843fbae..4a6a1204 100644 --- a/errors/err_http2_unsupported_protocol.md +++ b/errors/err_http2_unsupported_protocol.md @@ -2,4 +2,4 @@ `http2.connect()` was passed a URL that uses any protocol other than `http:` or `https:`. - + diff --git a/errors/err_http_invalid_char.md b/errors/err_http_invalid_char.md index f29a4eb0..8453e69b 100644 --- a/errors/err_http_invalid_char.md +++ b/errors/err_http_invalid_char.md @@ -5,4 +5,4 @@ removed: v10.0.0 HTTP 响应的状态信息中存在非法字符（原因短语）。 - + diff --git a/errors/err_http_request_timeout.md b/errors/err_http_request_timeout.md index 267e57f2..4d420a4b 100644 --- a/errors/err_http_request_timeout.md +++ b/errors/err_http_request_timeout.md @@ -1,4 +1,4 @@ The client has not sent the entire request within the allowed time. - + diff --git a/errors/err_inspector_not_worker.md b/errors/err_inspector_not_worker.md index ee368102..6f50fc8f 100644 --- a/errors/err_inspector_not_worker.md +++ b/errors/err_inspector_not_worker.md @@ -2,4 +2,4 @@ An API was called on the main thread that can only be used from the worker thread. - + diff --git a/errors/err_internal_assertion.md b/errors/err_internal_assertion.md index b539a954..f8210a3f 100644 --- a/errors/err_internal_assertion.md +++ b/errors/err_internal_assertion.md @@ -2,4 +2,4 @@ There was a bug in Node.js or incorrect usage of Node.js internals. To fix the error, open an issue at . - + diff --git a/errors/err_invalid_package_config.md b/errors/err_invalid_package_config.md index 84ec86eb..3a761fe8 100644 --- a/errors/err_invalid_package_config.md +++ b/errors/err_invalid_package_config.md @@ -1,4 +1,4 @@ -An invalid `package.json` file failed parsing. +An invalid [`package.json`][] file was found which failed parsing. diff --git a/errors/err_invalid_package_target.md b/errors/err_invalid_package_target.md index 512474c9..675f9739 100644 --- a/errors/err_invalid_package_target.md +++ b/errors/err_invalid_package_target.md @@ -1,5 +1,5 @@ -The `package.json` [exports][] field contains an invalid target mapping value -for the attempted module resolution. +The `package.json` [`"exports"`][] field contains an invalid target mapping +value for the attempted module resolution. diff --git a/errors/err_missing_args.md b/errors/err_missing_args.md index 6ca509fd..12039f29 100644 --- a/errors/err_missing_args.md +++ b/errors/err_missing_args.md @@ -5,4 +5,4 @@ strict compliance with the API specification (which in some cases may accept `func(undefined)` and `func()` are treated identically, and the [`ERR_INVALID_ARG_TYPE`][] error code may be used instead. - + diff --git a/errors/err_missing_message_port_in_transfer_list.md b/errors/err_missing_message_port_in_transfer_list.md index d675c87b..4612670a 100644 --- a/errors/err_missing_message_port_in_transfer_list.md +++ b/errors/err_missing_message_port_in_transfer_list.md @@ -3,4 +3,4 @@ An object that needs to be explicitly listed in the `transferList` argument is in the object passed to a `postMessage()` call, but is not provided in the `transferList` for that call. Usually, this is a `MessagePort`. - + diff --git a/errors/err_missing_option.md b/errors/err_missing_option.md index e63911c8..1d666d73 100644 --- a/errors/err_missing_option.md +++ b/errors/err_missing_option.md @@ -2,4 +2,4 @@ For APIs that accept options objects, some options might be mandatory. This code is thrown if a required option is missing. - + diff --git a/errors/err_package_import_not_defined.md b/errors/err_package_import_not_defined.md index 75884329..bc136b5d 100644 --- a/errors/err_package_import_not_defined.md +++ b/errors/err_package_import_not_defined.md @@ -1,5 +1,5 @@ -The `package.json` ["imports" field][] does not define the given internal +The `package.json` [`"imports"`][] field does not define the given internal package specifier mapping. diff --git a/errors/err_package_path_not_exported.md b/errors/err_package_path_not_exported.md index 587ea13b..de97f04a 100644 --- a/errors/err_package_path_not_exported.md +++ b/errors/err_package_path_not_exported.md @@ -1,5 +1,5 @@ -The `package.json` [exports][] field does not export the requested subpath. +The `package.json` [`"exports"`][] field does not export the requested subpath. Because exports are encapsulated, private internal modules that are not exported cannot be imported through the package resolution, unless using an absolute URL. diff --git a/errors/err_sri_parse.md b/errors/err_sri_parse.md index 86e0c101..73a61e16 100644 --- a/errors/err_sri_parse.md +++ b/errors/err_sri_parse.md @@ -3,4 +3,4 @@ A string was provided for a Subresource Integrity check, but was unable to be parsed. Check the format of integrity attributes by looking at the [Subresource Integrity specification][]. - + diff --git a/errors/err_stream_already_finished.md b/errors/err_stream_already_finished.md index a118e7ab..e0741716 100644 --- a/errors/err_stream_already_finished.md +++ b/errors/err_stream_already_finished.md @@ -2,4 +2,4 @@ A stream method was called that cannot complete because the stream was finished. - + diff --git a/errors/err_stream_destroyed.md b/errors/err_stream_destroyed.md index 29781c89..ea6af656 100644 --- a/errors/err_stream_destroyed.md +++ b/errors/err_stream_destroyed.md @@ -2,4 +2,4 @@ A stream method was called that cannot complete because the stream was destroyed using `stream.destroy()`. - + diff --git a/errors/err_tls_invalid_context.md b/errors/err_tls_invalid_context.md index d05a7aef..756c0467 100644 --- a/errors/err_tls_invalid_context.md +++ b/errors/err_tls_invalid_context.md @@ -4,4 +4,4 @@ added: v13.3.0 The context must be a `SecureContext`. - + diff --git a/errors/err_tls_invalid_protocol_version.md b/errors/err_tls_invalid_protocol_version.md index d5ee4154..dae08bf3 100644 --- a/errors/err_tls_invalid_protocol_version.md +++ b/errors/err_tls_invalid_protocol_version.md @@ -1,4 +1,4 @@ Valid TLS protocol versions are `'TLSv1'`, `'TLSv1.1'`, or `'TLSv1.2'`. - + diff --git a/errors/err_tls_invalid_state.md b/errors/err_tls_invalid_state.md index d0cd7291..8d35256d 100644 --- a/errors/err_tls_invalid_state.md +++ b/errors/err_tls_invalid_state.md @@ -1,8 +1,10 @@ The TLS socket must be connected and securily established. Ensure the 'secure' event is emitted before continuing. - + diff --git a/errors/err_tls_protocol_version_conflict.md b/errors/err_tls_protocol_version_conflict.md index e1ca1447..ec2f8a4d 100644 --- a/errors/err_tls_protocol_version_conflict.md +++ b/errors/err_tls_protocol_version_conflict.md @@ -2,4 +2,4 @@ Attempting to set a TLS protocol `minVersion` or `maxVersion` conflicts with an attempt to set the `secureProtocol` explicitly. Use one mechanism or the other. - + diff --git a/errors/err_tls_psk_set_identiy_hint_failed.md b/errors/err_tls_psk_set_identiy_hint_failed.md index 00e5619f..75fbd3e6 100644 --- a/errors/err_tls_psk_set_identiy_hint_failed.md +++ b/errors/err_tls_psk_set_identiy_hint_failed.md @@ -1,4 +1,4 @@ Failed to set PSK identity hint. Hint may be too long. - + diff --git a/errors/err_tls_sni_from_server.md b/errors/err_tls_sni_from_server.md index 32d58d27..fef29479 100644 --- a/errors/err_tls_sni_from_server.md +++ b/errors/err_tls_sni_from_server.md @@ -2,4 +2,4 @@ An attempt was made to issue Server Name Indication from a TLS server-side socket, which is only valid from a client. - + diff --git a/errors/err_unsupported_dir_import.md b/errors/err_unsupported_dir_import.md index 6b151b73..b8c3380e 100644 --- a/errors/err_unsupported_dir_import.md +++ b/errors/err_unsupported_dir_import.md @@ -1,7 +1,7 @@ `import` a directory URL is unsupported. Instead, [self-reference a package using its name][] and [define a custom subpath][] in -the `"exports"` field of the `package.json` file. +the [`"exports"`][] field of the [`package.json`][] file. ```js diff --git a/errors/err_zlib_binding_closed.md b/errors/err_zlib_binding_closed.md index cc7aab96..badc42be 100644 --- a/errors/err_zlib_binding_closed.md +++ b/errors/err_zlib_binding_closed.md @@ -78,5 +78,6 @@ closed. + diff --git a/esm/builtin_modules.md b/esm/builtin_modules.md index 88f8c135..cd10f5a4 100644 --- a/esm/builtin_modules.md +++ b/esm/builtin_modules.md @@ -1,5 +1,5 @@ -Builtin modules will provide named exports of their public API. A +[Core 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 diff --git a/esm/commonjs_namespaces.md b/esm/commonjs_namespaces.md new file mode 100644 index 00000000..30582380 --- /dev/null +++ b/esm/commonjs_namespaces.md @@ -0,0 +1,82 @@ + +CommonJS modules consist of a `module.exports` object which can be of any type. + +When importing a CommonJS module, it can be reliably imported using the ES +module default import or its corresponding sugar syntax: + + +```js +import { default as cjs } from 'cjs'; + +// The following import statement is "syntax sugar" (equivalent but sweeter) +// for `{ default as cjsSugar }` in the above import statement: +import cjsSugar from 'cjs'; + +console.log(cjs); +console.log(cjs === cjsSugar); +// Prints: +// +// true +``` + +The ECMAScript Module Namespace representation of a CommonJS module will always +be a namespace with a `default` export key pointing to the CommonJS +`module.exports` value. + +This Module Namespace Exotic Object can be directly observed either when using +`import * as m from 'cjs'` or a dynamic import: + + +```js +import * as m from 'cjs'; +console.log(m); +console.log(m === await import('cjs')); +// Prints: +// [Module] { default: } +// true +``` + +For better compatibility with existing usage in the JS ecosystem, Node.js will +in addition attempt to determine the CommonJS named exports of every imported +CommonJS module to provide them as separate ES module exports using a static +analysis process. + +For example, a CommonJS module written: + +```js +// cjs.cjs +exports.name = 'exported'; +``` + +will support named imports in ES modules: + + +```js +import { name } from './cjs.cjs'; +console.log(name); +// Prints: 'exported' + +import cjs from './cjs.cjs'; +console.log(cjs); +// Prints: { name: 'exported' } + +import * as m from './cjs.cjs'; +console.log(m); +// Prints: [Module] { default: { name: 'exported' }, name: 'exported' } +``` + +As can be seen from the last example of the Module Namespace Exotic Object being +logged, the `name` export is copied off of the `module.exports` object and set +directly on the ES module namespace when the module is imported. + +Live binding updates or new exports added to `module.exports` are not detected +for these named exports. + +The detection of named exports is based on common syntax patterns but will not +always correctly detect named exports, in these cases using the default +import form described above can be a better option. + +Named exports detection covers many common export patterns, reexport patterns +and build tool and transpiler outputs. See [cjs-module-lexer][] for the exact +semantics implemented. + diff --git a/esm/customizing_esm_specifier_resolution_algorithm.md b/esm/customizing_esm_specifier_resolution_algorithm.md index 59ceb93f..47b366fc 100644 --- a/esm/customizing_esm_specifier_resolution_algorithm.md +++ b/esm/customizing_esm_specifier_resolution_algorithm.md @@ -19,6 +19,7 @@ $ node --experimental-specifier-resolution=node index success! ``` + diff --git a/esm/enabling.md b/esm/enabling.md index 1ea5d02f..53d21d25 100644 --- a/esm/enabling.md +++ b/esm/enabling.md @@ -1,31 +1,26 @@ -Experimental support for ECMAScript modules is enabled by default. -Node.js will treat the following as ES modules when passed to `node` as the -initial input, or when referenced by `import` statements within ES module code: - -* Files ending in `.mjs`. - -* Files ending in `.js` when the nearest parent `package.json` file contains a - top-level field `"type"` with a value of `"module"`. - -* Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`, - with the flag `--input-type=module`. - -Node.js will treat as CommonJS all other forms of input, such as `.js` files -where the nearest parent `package.json` file contains no top-level `"type"` -field, or string input without the flag `--input-type`. This behavior is to -preserve backward compatibility. However, now that Node.js supports both -CommonJS and ES modules, it is best to be explicit whenever possible. Node.js -will treat the following as CommonJS when passed to `node` as the initial input, -or when referenced by `import` statements within ES module code: - -* Files ending in `.cjs`. - -* Files ending in `.js` when the nearest parent `package.json` file contains a - top-level field `"type"` with a value of `"commonjs"`. - -* Strings passed in as an argument to `--eval` or `--print`, or piped to `node` - via `STDIN`, with the flag `--input-type=commonjs`. +Node.js treats JavaScript code as CommonJS modules by default. +Authors can tell Node.js to treat JavaScript code as ECMAScript modules +via the `.mjs` file extension, the `package.json` [`"type"`][] field, or the +`--input-type` flag. See +[Modules: Packages](packages.html#packages_determining_module_system) for more +details. + + + + + + + + + + + + + + + + diff --git a/esm/exports_sugar.md b/esm/exports_sugar.md deleted file mode 100644 index a85d0d11..00000000 --- a/esm/exports_sugar.md +++ /dev/null @@ -1,25 +0,0 @@ - -If the `"."` export is the only export, the `"exports"` field provides sugar -for this case being the direct `"exports"` field value. - -If the `"."` export has a fallback array or string value, then the `"exports"` -field can be set to this value directly. - - -```js -{ - "exports": { - ".": "./main.js" - } -} -``` - -can be written: - - -```js -{ - "exports": "./main.js" -} -``` - diff --git a/esm/import_statements.md b/esm/import_statements.md index d9ab3fac..d4f9e181 100644 --- a/esm/import_statements.md +++ b/esm/import_statements.md @@ -1,33 +1,28 @@ -An `import` statement can reference an ES module or a CommonJS module. Other -file types such as JSON or native modules are not supported. For those, use -[`module.createRequire()`][]. - +An `import` statement can reference an ES module or a CommonJS module. `import` statements are permitted only in ES modules. For similar functionality in CommonJS, see [`import()`][]. +When importing [CommonJS modules](#esm_commonjs_namespaces), the +`module.exports` object is provided as the default export. Named exports may be +available, provided by static analysis as a convenience for better ecosystem +compatibility. + +Additional experimental flags are available for importing +[Wasm modules](#esm_experimental_wasm_modules) or +[JSON modules](#esm_experimental_json_modules). For importing native modules or +JSON modules unflagged, see [`module.createRequire()`][]. + The _specifier_ of an `import` statement (the string after the `from` keyword) can either be an URL-style relative path like `'./file.mjs'` or a package name like `'fs'`. Like in CommonJS, files within packages can be accessed by appending a path to -the package name; unless the package’s `package.json` contains an `"exports"` -field, in which case files within packages need to be accessed via the path -defined in `"exports"`. +the package name; unless the package’s [`package.json`][] contains an +[`"exports"`][] field, in which case files within packages need to be accessed +via the path defined in [`"exports"`][]. ```js import { sin, cos } from 'geometry/trigonometry-functions.mjs'; ``` -Only the “default export” is supported for CommonJS files or packages: - - -```js -import packageMain from 'commonjs-package'; // Works - -import { method } from 'commonjs-package'; // Errors -``` - -It is also possible to -[import an ES or CommonJS module for its side effects only][]. - diff --git a/esm/introduction.md b/esm/introduction.md index 1a12abe7..8f8b60a6 100644 --- a/esm/introduction.md +++ b/esm/introduction.md @@ -36,3 +36,8 @@ Node.js contains support for ES Modules based upon the Expect major changes in the implementation including interoperability support, specifier resolution, and default behavior. + + + + + diff --git a/esm/package_exports_fallbacks.md b/esm/package_exports_fallbacks.md deleted file mode 100644 index 6f7b6f46..00000000 --- a/esm/package_exports_fallbacks.md +++ /dev/null @@ -1,16 +0,0 @@ - -For possible new specifier support in future, array fallbacks are -supported for all invalid specifiers: - - -```js -{ - "exports": { - "./submodule": ["not:valid", "./submodule.js"] - } -} -``` - -Since `"not:valid"` is not a valid specifier, `"./submodule.js"` is used -instead as the fallback, as if it were the only target. - diff --git a/esm/package_scope_and_file_extensions.md b/esm/package_scope_and_file_extensions.md deleted file mode 100644 index 7402f000..00000000 --- a/esm/package_scope_and_file_extensions.md +++ /dev/null @@ -1,56 +0,0 @@ - -A folder containing a `package.json` file, and all subfolders below that folder -until the next folder containing another `package.json`, are a -_package scope_. The `"type"` field defines how to treat `.js` files -within the package scope. Every package in a -project’s `node_modules` folder contains its own `package.json` file, so each -project’s dependencies have their own package scopes. If a `package.json` file -does not have a `"type"` field, the default `"type"` is `"commonjs"`. - -The package scope applies not only to initial entry points (`node my-app.js`) -but also to files referenced by `import` statements and `import()` expressions. - -```js -// my-app.js, in an ES module package scope because there is a package.json -// file in the same folder with "type": "module". - -import './startup/init.js'; -// Loaded as ES module since ./startup contains no package.json file, -// and therefore inherits the ES module package scope from one level up. - -import 'commonjs-package'; -// Loaded as CommonJS since ./node_modules/commonjs-package/package.json -// lacks a "type" field or contains "type": "commonjs". - -import './node_modules/commonjs-package/index.js'; -// Loaded as CommonJS since ./node_modules/commonjs-package/package.json -// lacks a "type" field or contains "type": "commonjs". -``` - -Files ending with `.mjs` are always loaded as ES modules regardless of package -scope. - -Files ending with `.cjs` are always loaded as CommonJS regardless of package -scope. - -```js -import './legacy-file.cjs'; -// Loaded as CommonJS since .cjs is always loaded as CommonJS. - -import 'commonjs-package/src/index.mjs'; -// Loaded as ES module since .mjs is always loaded as ES module. -``` - -The `.mjs` and `.cjs` extensions may be used to mix types within the same -package scope: - -* Within a `"type": "module"` package scope, Node.js can be instructed to - interpret a particular file as CommonJS by naming it with a `.cjs` extension - (since both `.js` and `.mjs` files are treated as ES modules within a - `"module"` package scope). - -* Within a `"type": "commonjs"` package scope, Node.js can be instructed to - interpret a particular file as an ES module by naming it with an `.mjs` - extension (since both `.js` and `.cjs` files are treated as CommonJS within a - `"commonjs"` package scope). - diff --git a/esm/packages.md b/esm/packages.md index 8b137891..70cbaf7f 100644 --- a/esm/packages.md +++ b/esm/packages.md @@ -1 +1,3 @@ +This section was moved to [Modules: Packages](packages.html). + diff --git a/esm/resolver_algorithm.md b/esm/resolver_algorithm.md index 1fd1f9e5..9449b277 100644 --- a/esm/resolver_algorithm.md +++ b/esm/resolver_algorithm.md @@ -133,7 +133,8 @@ The resolver can throw the following errors: > 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_). +> _packageURL_, _mainExport_, _""_, **false**, **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 @@ -167,29 +168,43 @@ _isImports_, _conditions_) > 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_). +> _packageURL_, _target_, _""_, **false**, _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. Let _expansionKeys_ be the list of keys of _matchObj_ ending in _"/"_ +> or _"*"_, sorted by length descending. > 1. For each key _expansionKey_ in _expansionKeys_, do +> 1. If _expansionKey_ ends in _"*"_ and _matchKey_ starts with but is +> not equal to the substring of _expansionKey_ excluding the last _"*"_ +> character, 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_ minus one. +> 1. Let _resolved_ be the result of **PACKAGE_TARGET_RESOLVE**( +> _packageURL_, _target_, _subpath_, **true**, _isImports_, +> _conditions_). +> 1. Return the object _{ resolved, exact: **true** }_. > 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_). +> _packageURL_, _target_, _subpath_, **false**, _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_) +**PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_, _pattern_, +_internal_, _conditions_) > 1. If _target_ is a String, then -> 1. If _subpath_ has non-zero length and _target_ does not end with _"/"_, -> throw an _Invalid Module Specifier_ error. +> 1. If _pattern_ is **false**, _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 _internal_ is **true** and _target_ does not start with _"../"_ or > _"/"_ and is not a valid URL, then +> 1. If _pattern_ is **true**, then +> 1. Return **PACKAGE_RESOLVE**(_target_ with every instance of +> _"*"_ replaced by _subpath_, _packageURL_ + _"/"_)_. > 1. Return **PACKAGE_RESOLVE**(_target_ + _subpath_, > _packageURL_ + _"/"_)_. > 1. Otherwise, throw an _Invalid Package Target_ error. @@ -201,8 +216,12 @@ _conditions_) > 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. If _pattern_ is **true**, then +> 1. Return the URL resolution of _resolvedTarget_ with every instance of +> _"*"_ replaced with _subpath_. +> 1. Otherwise, +> 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. @@ -211,7 +230,8 @@ _conditions_) > 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_, _conditions_). +> _packageURL_, _targetValue_, _subpath_, _pattern_, _internal_, +> _conditions_). > 1. If _resolved_ is equal to **undefined**, continue the loop. > 1. Return _resolved_. > 1. Return **undefined**. @@ -219,8 +239,9 @@ _conditions_) > 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_, _conditions_), -> continuing the loop on any _Invalid Package Target_ error. +> _packageURL_, _targetValue_, _subpath_, _pattern_, _internal_, +> _conditions_), continuing the loop on any _Invalid Package Target_ +> error. > 1. If _resolved_ is **undefined**, continue the loop. > 1. Return _resolved_. > 1. Return or throw the last fallback resolution **null** return or error. diff --git a/esm/subpath_exports.md b/esm/subpath_exports.md deleted file mode 100644 index 28b96d4b..00000000 --- a/esm/subpath_exports.md +++ /dev/null @@ -1,56 +0,0 @@ - -When using the `"exports"` field, custom subpaths can be defined along -with the main entry point by treating the main entry point as the -`"."` subpath: - - -```js -{ - "main": "./main.js", - "exports": { - ".": "./main.js", - "./submodule": "./src/submodule.js" - } -} -``` - -Now only the defined subpath in `"exports"` can be imported by a -consumer: - -```js -import submodule from 'es-module-package/submodule'; -// Loads ./node_modules/es-module-package/src/submodule.js -``` - -While other subpaths will error: - -```js -import submodule from 'es-module-package/private-module.js'; -// Throws ERR_PACKAGE_PATH_NOT_EXPORTED -``` - -Entire folders can also be mapped with package exports: - - -```js -// ./node_modules/es-module-package/package.json -{ - "exports": { - "./features/": "./src/features/" - } -} -``` - -With the above, all modules within the `./src/features/` folder -are exposed deeply to `import` and `require`: - -```js -import feature from 'es-module-package/features/x.js'; -// Loads ./node_modules/es-module-package/src/features/x.js -``` - -When using folder mappings, ensure that you do want to expose every -module inside the subfolder. Any modules which are not public -should be moved to another folder to retain the encapsulation -benefits of exports. - diff --git a/fs/fs_lutimes_path_atime_mtime_callback.md b/fs/fs_lutimes_path_atime_mtime_callback.md index 42a4024b..e706870e 100644 --- a/fs/fs_lutimes_path_atime_mtime_callback.md +++ b/fs/fs_lutimes_path_atime_mtime_callback.md @@ -1,5 +1,5 @@ * `path` {string|Buffer|URL} diff --git a/http2/error_codes_for_rst_stream_and_goaway.md b/http2/error_codes_for_rst_stream_and_goaway.md index 8e47cbea..5afb2de9 100644 --- a/http2/error_codes_for_rst_stream_and_goaway.md +++ b/http2/error_codes_for_rst_stream_and_goaway.md @@ -1,4 +1,3 @@ - | Value | Name | Constant | |--------|---------------------|-----------------------------------------------| diff --git a/modules/folders_as_modules.md b/modules/folders_as_modules.md index 9d4cf951..ab6ca775 100644 --- a/modules/folders_as_modules.md +++ b/modules/folders_as_modules.md @@ -4,8 +4,8 @@ 可以把程序和库放到一个单独的目录，然后提供一个单一的入口来指向它。 把目录递给 `require()` 作为一个参数，有三种方式。 -第一种方式是在根目录下创建一个 `package.json` 文件，并指定一个 `main` 模块。 -例子，`package.json` 文件类似： +第一种方式是在根目录下创建一个 [`package.json`] 文件，并指定一个 `main` 模块。 +例子，[`package.json`] 文件类似： ```json { "name" : "some-library", @@ -16,8 +16,8 @@ 这就是 Node.js 处理 `package.json` 文件的方式。 -如果目录里没有 `package.json` 文件，或者 `'main'` 入口不存在或无法解析，则 Node.js 将会试图加载目录下的 `index.js` 或 `index.node` 文件。 -例如，如果上面的例子中没有 `package.json` 文件，则 `require('./some-library')` 会试图加载： +如果目录里没有 [`package.json`] 文件，或者 [`"main"`] 入口不存在或无法解析，则 Node.js 将会试图加载目录下的 `index.js` 或 `index.node` 文件。 +例如，如果前面的例子中没有 [`package.json`] 文件，则 `require('./some-library')` 会试图加载： * `./some-library/index.js` * `./some-library/index.node` diff --git a/modules/source_map_v3_support.md b/modules/source_map_v3_support.md index b3fe9d63..5fd4f0eb 100644 --- a/modules/source_map_v3_support.md +++ b/modules/source_map_v3_support.md @@ -23,3 +23,5 @@ This section was moved to + + diff --git a/n-api/n_api_version_matrix.md b/n-api/n_api_version_matrix.md index 8e82bdc7..b6d11455 100644 --- a/n-api/n_api_version_matrix.md +++ b/n-api/n_api_version_matrix.md @@ -17,6 +17,7 @@ listed as supporting a later version. 4 5 6 + 7 v6.x @@ -26,6 +27,7 @@ listed as supporting a later version. + v8.x @@ -35,6 +37,7 @@ listed as supporting a later version. v8.16.0 + v9.x @@ -44,6 +47,7 @@ listed as supporting a later version. + v10.x @@ -53,6 +57,7 @@ listed as supporting a later version. v10.16.0 v10.17.0 v10.20.0 + v11.x @@ -62,6 +67,7 @@ listed as supporting a later version. v11.8.0 + v12.x @@ -71,6 +77,7 @@ listed as supporting a later version. v12.0.0 v12.11.0 v12.17.0 + v13.x @@ -80,6 +87,7 @@ listed as supporting a later version. v13.0.0 v13.0.0 + v14.x @@ -89,6 +97,7 @@ listed as supporting a later version. v14.0.0 v14.0.0 v14.0.0 + v14.12.0 diff --git a/n-api/napi_async_init.md b/n-api/napi_async_init.md index 3ed03976..5d733192 100644 --- a/n-api/napi_async_init.md +++ b/n-api/napi_async_init.md @@ -14,8 +14,8 @@ napi_status napi_async_init(napi_env env, * `[in] async_resource`: Object associated with the async work that will be passed to possible `async_hooks` [`init` hooks][]. In order to retain ABI compatibility with previous versions, - passing `NULL` for `async_resource` will not result in an error, however, - this will result incorrect operation of async hooks for the + passing `NULL` for `async_resource` does not result in an error. However, + this results in incorrect operation of async hooks for the napi_async_context created. Potential issues include loss of async context when using the AsyncLocalStorage API. * `[in] async_resource_name`: Identifier for the kind of resource diff --git a/n-api/napi_get_cb_info.md b/n-api/napi_get_cb_info.md index 8e23460d..b2606b19 100644 --- a/n-api/napi_get_cb_info.md +++ b/n-api/napi_get_cb_info.md @@ -14,8 +14,8 @@ napi_status napi_get_cb_info(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] cbinfo`: The callback info passed into the callback function. -* `[in-out] argc`: Specifies the size of the provided `argv` array and receives - the actual count of arguments. +* `[in-out] argc`: Specifies the length of the provided `argv` array and + receives the actual count of arguments. * `[out] argv`: Buffer to which the `napi_value` representing the arguments are copied. If there are more arguments than the provided count, only the requested number of arguments are copied. If there are fewer arguments diff --git a/n-api/napi_get_value_string_latin1.md b/n-api/napi_get_value_string_latin1.md index b398cfd0..044547ba 100644 --- a/n-api/napi_get_value_string_latin1.md +++ b/n-api/napi_get_value_string_latin1.md @@ -14,9 +14,10 @@ napi_status napi_get_value_string_latin1(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript string. * `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If `NULL` is - passed in, the length of the string (in bytes) is returned. + passed in, the length of the string in bytes and excluding the null terminator + is returned in `result`. * `[in] bufsize`: Size of the destination buffer. When this value is - insufficient, the returned string will be truncated. + insufficient, the returned string is truncated and null-terminated. * `[out] result`: Number of bytes copied into the buffer, excluding the null terminator. diff --git a/n-api/napi_get_value_string_utf16.md b/n-api/napi_get_value_string_utf16.md index 676348a4..6d1e22ce 100644 --- a/n-api/napi_get_value_string_utf16.md +++ b/n-api/napi_get_value_string_utf16.md @@ -14,9 +14,10 @@ napi_status napi_get_value_string_utf16(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript string. * `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If `NULL` is - passed in, the length of the string (in 2-byte code units) is returned. + passed in, the length of the string in 2-byte code units and excluding the + null terminator is returned. * `[in] bufsize`: Size of the destination buffer. When this value is - insufficient, the returned string will be truncated. + insufficient, the returned string is truncated and null-terminated. * `[out] result`: Number of 2-byte code units copied into the buffer, excluding the null terminator. diff --git a/n-api/napi_get_value_string_utf8.md b/n-api/napi_get_value_string_utf8.md index d59527fa..99569c4a 100644 --- a/n-api/napi_get_value_string_utf8.md +++ b/n-api/napi_get_value_string_utf8.md @@ -14,9 +14,10 @@ napi_status napi_get_value_string_utf8(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript string. * `[in] buf`: Buffer to write the UTF8-encoded string into. If `NULL` is passed - in, the length of the string (in bytes) is returned. + in, the length of the string in bytes and excluding the null terminator is + returned in `result`. * `[in] bufsize`: Size of the destination buffer. When this value is - insufficient, the returned string will be truncated. + insufficient, the returned string is truncated and null-terminated. * `[out] result`: Number of bytes copied into the buffer, excluding the null terminator. diff --git a/n-api/napi_make_callback.md b/n-api/napi_make_callback.md index dbc33c10..f351d84a 100644 --- a/n-api/napi_make_callback.md +++ b/n-api/napi_make_callback.md @@ -19,9 +19,11 @@ NAPI_EXTERN napi_status napi_make_callback(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] async_context`: Context for the async operation that is invoking the callback. This should normally be a value previously - obtained from [`napi_async_init`][]. However `NULL` is also allowed, - which indicates the current async context (if any) is to be used - for the callback. + obtained from [`napi_async_init`][]. + In order to retain ABI compatibility with previous versions, passing `NULL` + for `async_context` does not result in an error. However, this results + in incorrect operation of async hooks. Potential issues include loss of + async context when using the `AsyncLocalStorage` API. * `[in] recv`: The `this` object passed to the called function. * `[in] func`: `napi_value` representing the JavaScript function to be invoked. * `[in] argc`: The count of elements in the `argv` array. diff --git a/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md b/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md index cc64dd2f..35296a5d 100644 --- a/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md +++ b/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md @@ -24,11 +24,11 @@ for a reference is 0, all subsequent calls to get the object associated with the reference [`napi_get_reference_value`][] will return `NULL` for the returned `napi_value`. An attempt to call [`napi_reference_ref`][] for a reference whose object has been collected -will result in an error. +results in an error. References must be deleted once they are no longer required by the addon. When -a reference is deleted it will no longer prevent the corresponding object from -being collected. Failure to delete a persistent reference will result in +a reference is deleted, it will no longer prevent the corresponding object from +being collected. Failure to delete a persistent reference results in a 'memory leak' with both the native memory for the persistent reference and the corresponding object on the heap being retained forever. diff --git a/net/socket_readystate.md b/net/socket_readystate.md new file mode 100644 index 00000000..ca336aa0 --- /dev/null +++ b/net/socket_readystate.md @@ -0,0 +1,13 @@ + + +* {string} + +This property represents the state of the connection as a string. + +* If the stream is connecting `socket.readyState` is `opening`. +* If the stream is readable and writable, it is `open`. +* If the stream is readable and not writable, it is `readOnly`. +* If the stream is not readable and writable, it is `writeOnly`. + diff --git a/esm/approach_1_use_an_es_module_wrapper.md b/packages/approach_1_use_an_es_module_wrapper.md similarity index 98% rename from esm/approach_1_use_an_es_module_wrapper.md rename to packages/approach_1_use_an_es_module_wrapper.md index 2ca91c32..4ab40278 100644 --- a/esm/approach_1_use_an_es_module_wrapper.md +++ b/packages/approach_1_use_an_es_module_wrapper.md @@ -4,8 +4,7 @@ create an ES module wrapper file that defines the named exports. Using [Conditional exports][], the ES module wrapper is used for `import` and the CommonJS entry point for `require`. - -```js +```json // ./node_modules/pkg/package.json { "type": "module", @@ -72,8 +71,7 @@ application, such as by dependencies; or if the CommonJS version can be loaded but doesn’t affect the ES module version (for example, because the package is stateless): - -```js +```json // ./node_modules/pkg/package.json { "type": "module", diff --git a/esm/approach_2_isolate_state.md b/packages/approach_2_isolate_state.md similarity index 96% rename from esm/approach_2_isolate_state.md rename to packages/approach_2_isolate_state.md index 9c491e27..967656c5 100644 --- a/esm/approach_2_isolate_state.md +++ b/packages/approach_2_isolate_state.md @@ -1,9 +1,8 @@ -A `package.json` file can define the separate CommonJS and ES module entry +A [`package.json`][] file can define the separate CommonJS and ES module entry points directly: - -```js +```json // ./node_modules/pkg/package.json { "type": "module", @@ -88,8 +87,7 @@ As with the previous approach, a variant of this approach not requiring conditional exports for consumers could be to add an export, e.g. `"./module"`, to point to an all-ES module-syntax version of the package: - -```js +```json // ./node_modules/pkg/package.json { "type": "module", diff --git a/esm/conditional_exports.md b/packages/conditional_exports.md similarity index 78% rename from esm/conditional_exports.md rename to packages/conditional_exports.md index 5e19ae5a..91098b72 100644 --- a/esm/conditional_exports.md +++ b/packages/conditional_exports.md @@ -1,12 +1,13 @@ +> Stability: 1 - Experimental + Conditional exports provide a way to map to different paths depending on certain conditions. They are supported for both CommonJS and ES module imports. For example, a package that wants to provide different ES module exports for `require()` and `import` can be written: - -```js +```json // package.json { "main": "./main-require.cjs", @@ -21,19 +22,22 @@ For example, a package that wants to provide different ES module exports for Node.js supports the following conditions out of the box: * `"import"` - matched when the package is loaded via `import` or - `import()`. Can reference either an ES module or CommonJS file, as both - `import` and `import()` can load either ES module or CommonJS sources. - _Always matched when the `"require"` condition is not matched._ -* `"require"` - matched when the package is loaded via `require()`. - As `require()` only supports CommonJS, the referenced file must be CommonJS. - _Always matched when the `"import"` condition is not matched._ + `import()`, or via any top-level import or resolve operation by the + ECMAScript module loader. Applies regardless of the module format of the + target file. _Always mutually exclusive with `"require"`._ +* `"require"` - matched when the package is loaded via `require()`. The + referenced file should be loadable with `require()` although the condition + will be matched regardless of the module format of the target file. Expected + formats include CommonJS, JSON, and native addons but not ES modules as + `require()` doesn't support them. _Always mutually exclusive with + `"import"`._ * `"node"` - matched for any Node.js environment. Can be a CommonJS or ES module file. _This condition should always come after `"import"` or `"require"`._ * `"default"` - the generic fallback that will always match. Can be a CommonJS or ES module file. _This condition should always come last._ -Within the `"exports"` object, key order is significant. During condition +Within the [`"exports"`][] object, key order is significant. During condition matching, earlier entries have higher priority and take precedence over later entries. _The general rule is that conditions should be from most specific to least specific in object order_. @@ -48,8 +52,7 @@ which are further explained in [the dual CommonJS/ES module packages section][]. Conditional exports can also be extended to exports subpaths, for example: - -```js +```json { "main": "./main.js", "exports": { diff --git a/packages/determining_module_system.md b/packages/determining_module_system.md new file mode 100644 index 00000000..b2bb0a4b --- /dev/null +++ b/packages/determining_module_system.md @@ -0,0 +1,34 @@ + +Node.js will treat the following as [ES modules][] when passed to `node` as the +initial input, or when referenced by `import` statements within ES module code: + +* Files ending in `.mjs`. + +* Files ending in `.js` when the nearest parent `package.json` file contains a + top-level [`"type"`][] field with a value of `"module"`. + +* Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`, + with the flag `--input-type=module`. + +Node.js will treat as [CommonJS][] all other forms of input, such as `.js` files +where the nearest parent `package.json` file contains no top-level `"type"` +field, or string input without the flag `--input-type`. This behavior is to +preserve backward compatibility. However, now that Node.js supports both +CommonJS and ES modules, it is best to be explicit whenever possible. Node.js +will treat the following as CommonJS when passed to `node` as the initial input, +or when referenced by `import` statements within ES module code: + +* Files ending in `.cjs`. + +* Files ending in `.js` when the nearest parent `package.json` file contains a + top-level field [`"type"`][] with a value of `"commonjs"`. + +* Strings passed in as an argument to `--eval` or `--print`, or piped to `node` + via `STDIN`, with the flag `--input-type=commonjs`. + +Package authors should include the [`"type"`][] field, even in packages where +all sources are CommonJS. Being explicit about the `type` of the package will +future-proof the package in case the default type of Node.js ever changes, and +it will also make things easier for build tools and loaders to determine how the +files in the package should be interpreted. + diff --git a/esm/dual_commonjs_es_module_packages.md b/packages/dual_commonjs_es_module_packages.md similarity index 83% rename from esm/dual_commonjs_es_module_packages.md rename to packages/dual_commonjs_es_module_packages.md index be934bd6..506e2d76 100644 --- a/esm/dual_commonjs_es_module_packages.md +++ b/packages/dual_commonjs_es_module_packages.md @@ -1,8 +1,9 @@ Prior to the introduction of support for ES modules in Node.js, it was a common pattern for package authors to include both CommonJS and ES module JavaScript -sources in their package, with `package.json` `"main"` specifying the CommonJS -entry point and `package.json` `"module"` specifying the ES module entry point. +sources in their package, with `package.json` [`"main"`][] specifying the +CommonJS entry point and `package.json` `"module"` specifying the ES module +entry point. This enabled Node.js to run the CommonJS entry point while build tools such as bundlers used the ES module entry point, since Node.js ignored (and still ignores) the top-level `"module"` field. diff --git a/esm/dual_package_hazard.md b/packages/dual_package_hazard.md similarity index 100% rename from esm/dual_package_hazard.md rename to packages/dual_package_hazard.md diff --git a/packages/exports.md b/packages/exports.md new file mode 100644 index 00000000..035b95b9 --- /dev/null +++ b/packages/exports.md @@ -0,0 +1,41 @@ + + +* Type: {Object} | {string} | {string[]} + +```json +{ + "exports": "./index.js" +} +``` + +The `"exports"` field allows defining the [entry points][] of a package when +imported by name loaded either via a `node_modules` lookup or a +[self-reference][] to its own name. It is supported in Node.js 12+ as an +alternative to the [`"main"`][] that can support defining [subpath exports][] +and [conditional exports][] while encapsulating internal unexported modules. + +[Conditional Exports][] can also be used within `"exports"` to define different +package entry points per environment, including whether the package is +referenced via `require` or via `import`. + +All paths defined in the `"exports"` must be relative file URLs starting with +`./`. + diff --git a/packages/exports_sugar.md b/packages/exports_sugar.md new file mode 100644 index 00000000..bd6c837a --- /dev/null +++ b/packages/exports_sugar.md @@ -0,0 +1,25 @@ + +> Stability: 1 - Experimental + +If the `"."` export is the only export, the [`"exports"`][] field provides sugar +for this case being the direct [`"exports"`][] field value. + +If the `"."` export has a fallback array or string value, then the +[`"exports"`][] field can be set to this value directly. + +```json +{ + "exports": { + ".": "./main.js" + } +} +``` + +can be written: + +```json +{ + "exports": "./main.js" +} +``` + diff --git a/esm/internal_package_imports.md b/packages/imports.md similarity index 65% rename from esm/internal_package_imports.md rename to packages/imports.md index 644bb8cf..7d79dc74 100644 --- a/esm/internal_package_imports.md +++ b/packages/imports.md @@ -1,6 +1,14 @@ + -In addition to the `"exports"` field it is possible to define internal package -import maps that only apply to import specifiers from within the package itself. +> Stability: 1 - Experimental + +* Type: {Object} + +In addition to the [`"exports"`][] field it is possible to define internal +package import maps that only apply to import specifiers from within the package +itself. Entries in the imports field must always start with `#` to ensure they are clearly disambiguated from package specifiers. @@ -27,10 +35,27 @@ where `import '#dep'` would now get the resolution of the external package `dep-node-native` (including its exports in turn), and instead get the local file `./dep-polyfill.js` relative to the package in other environments. -Unlike the exports field, import maps permit mapping to external packages -because this provides an important use case for conditional loading and also can -be done without the risk of cycles, unlike for exports. +Unlike the `"exports"` field, import maps permit mapping to external packages, +providing an important use case for conditional loading scenarios. Apart from the above, the resolution rules for the imports field are otherwise analogous to the exports field. + + + + + + + + + + + + + + + + + + diff --git a/esm/input_type_flag.md b/packages/input_type_flag.md similarity index 82% rename from esm/input_type_flag.md rename to packages/input_type_flag.md index 790bb9df..c1e0ed2f 100644 --- a/esm/input_type_flag.md +++ b/packages/input_type_flag.md @@ -1,7 +1,7 @@ Strings passed in as an argument to `--eval` (or `-e`), or piped to `node` via -`STDIN`, will be treated as ES modules when the `--input-type=module` flag is -set. +`STDIN`, will be treated as [ES modules][] when the `--input-type=module` flag +is set. ```bash node --input-type=module --eval "import { sep } from 'path'; console.log(sep);" diff --git a/packages/introduction.md b/packages/introduction.md new file mode 100644 index 00000000..f4536d8a --- /dev/null +++ b/packages/introduction.md @@ -0,0 +1,9 @@ + +A package is a folder tree described by a `package.json` file. The package +consists of the folder containing the `package.json` file and all subfolders +until the next folder containing another `package.json` file, or a folder +named `node_modules`. + +This page provides guidance for package authors writing `package.json` files +along with a reference for the [`package.json`][] fields defined by Node.js. + diff --git a/packages/main.md b/packages/main.md new file mode 100644 index 00000000..6c0d390c --- /dev/null +++ b/packages/main.md @@ -0,0 +1,23 @@ + + +* Type: {string} + +```json +{ + "main": "./main.js" +} +``` + +The `"main"` field defines the script that is used when the [package directory +is loaded via `require()`](modules.html#modules_folders_as_modules). Its value +is interpreted as a path. + +```js +require('./path/to/directory'); // This resolves to ./path/to/directory/main.js. +``` + +When a package has an [`"exports"`][] field, this will take precedence over the +`"main"` field when importing the package by name. + diff --git a/esm/main_entry_point_export.md b/packages/main_entry_point_export.md similarity index 58% rename from esm/main_entry_point_export.md rename to packages/main_entry_point_export.md index 9fce1e7d..6a5cc94f 100644 --- a/esm/main_entry_point_export.md +++ b/packages/main_entry_point_export.md @@ -1,19 +1,18 @@ To set the main entry point for a package, it is advisable to define both -`"exports"` and `"main"` in the package’s `package.json` file: +[`"exports"`][] and [`"main"`][] in the package’s [`package.json`][] file: - -```js +```json { "main": "./main.js", "exports": "./main.js" } ``` -The benefit of doing this is that when using the `"exports"` field all -subpaths of the package will no longer be available to importers under -`require('pkg/subpath.js')`, and instead they will get a new error, -`ERR_PACKAGE_PATH_NOT_EXPORTED`. +When defining the [`"exports"`][] field, all subpaths of the package will be +encapsulated and no longer available to importers. For example, +`require('pkg/subpath.js')` would throw an [`ERR_PACKAGE_PATH_NOT_EXPORTED`][] +error. This encapsulation of exports provides more reliable guarantees about package interfaces for tools and when handling semver upgrades for a diff --git a/packages/modules_packages.md b/packages/modules_packages.md new file mode 100644 index 00000000..de16202d --- /dev/null +++ b/packages/modules_packages.md @@ -0,0 +1,3 @@ + + + diff --git a/packages/name.md b/packages/name.md new file mode 100644 index 00000000..7ee8607d --- /dev/null +++ b/packages/name.md @@ -0,0 +1,27 @@ + + +* Type: {string} + +```json +{ + "name": "package-name" +} +``` + +The `"name"` field defines your package’s name. Publishing to the +_npm_ registry may require a name that satisfies +[certain requirements](https://docs.npmjs.com/files/package.json#name). + +The `"name"` field can be used in addition to the [`"exports"`][] field to +[self-reference][] a package using its name. + diff --git a/esm/nested_conditions.md b/packages/nested_conditions.md similarity index 94% rename from esm/nested_conditions.md rename to packages/nested_conditions.md index 5036edc1..1007ee9c 100644 --- a/esm/nested_conditions.md +++ b/packages/nested_conditions.md @@ -1,11 +1,12 @@ +> Stability: 1 - Experimental + In addition to direct mappings, Node.js also supports nested condition objects. For example, to define a package that only has dual mode entry points for use in Node.js but not the browser: - -```js +```json { "main": "./main.js", "exports": { diff --git a/packages/node_js_package_json_field_definitions.md b/packages/node_js_package_json_field_definitions.md new file mode 100644 index 00000000..f925c8a1 --- /dev/null +++ b/packages/node_js_package_json_field_definitions.md @@ -0,0 +1,18 @@ + +This section describes the fields used by the Node.js runtime. Other tools (such +as [npm](https://docs.npmjs.com/creating-a-package-json-file)) may use +additional fields which are ignored by Node.js and not documented here. + +The following fields in `package.json` files are used in Node.js: + +* [`"name"`][] - Relevant when using named imports within a package. Also used + by package managers as the name of the package. +* [`"type"`][] - The package type determining whether to load `.js` files as + CommonJS or ES modules. +* [`"exports"`][] - Package exports and conditional exports. When present, + limits which submodules may be loaded from within the package. +* [`"main"`][] - The default module when loading the package, if exports is not + specified, and in versions of Node.js prior to the introduction of exports. +* [`"imports"`][] - Package imports, for use by modules within the package + itself. + diff --git a/esm/package_entry_points.md b/packages/package_entry_points.md similarity index 54% rename from esm/package_entry_points.md rename to packages/package_entry_points.md index 0125e050..3866d594 100644 --- a/esm/package_entry_points.md +++ b/packages/package_entry_points.md @@ -1,34 +1,34 @@ In a package’s `package.json` file, two fields can define entry points for a -package: `"main"` and `"exports"`. The `"main"` field is supported in all -versions of Node.js, but its capabilities are limited: it only defines the main -entry point of the package. +package: [`"main"`][] and [`"exports"`][]. The [`"main"`][] field is supported +in all versions of Node.js, but its capabilities are limited: it only defines +the main entry point of the package. -The `"exports"` field provides an alternative to `"main"` where the package -main entry point can be defined while also encapsulating the package, -**preventing any other entry points besides those defined in `"exports"`**. +The [`"exports"`][] field provides an alternative to [`"main"`][] where the +package main entry point can be defined while also encapsulating the package, +**preventing any other entry points besides those defined in [`"exports"`][]**. This encapsulation allows module authors to define a public interface for their package. -If both `"exports"` and `"main"` are defined, the `"exports"` field takes -precedence over `"main"`. `"exports"` are not specific to ES modules or -CommonJS; `"main"` will be overridden by `"exports"` if it exists. As such -`"main"` cannot be used as a fallback for CommonJS but it can be used as a -fallback for legacy versions of Node.js that do not support the `"exports"` -field. +If both [`"exports"`][] and [`"main"`][] are defined, the [`"exports"`][] field +takes precedence over [`"main"`][]. [`"exports"`][] are not specific to ES +modules or CommonJS; [`"main"`][] will be overridden by [`"exports"`][] if it +exists. As such [`"main"`][] cannot be used as a fallback for CommonJS but it +can be used as a fallback for legacy versions of Node.js that do not support the +[`"exports"`][] field. -[Conditional exports][] can be used within `"exports"` to define different +[Conditional exports][] can be used within [`"exports"`][] to define different package entry points per environment, including whether the package is referenced via `require` or via `import`. For more information about supporting both CommonJS and ES Modules in a single package please consult [the dual CommonJS/ES module packages section][]. -**Warning**: Introducing the `"exports"` field prevents consumers of a package -from using any entry points that are not defined, including the `package.json` -(e.g. `require('your-package/package.json')`. **This will likely be a breaking -change.** +**Warning**: Introducing the [`"exports"`][] field prevents consumers of a +package from using any entry points that are not defined, including the +[`package.json`][] (e.g. `require('your-package/package.json')`. **This will +likely be a breaking change.** -To make the introduction of `"exports"` non-breaking, ensure that every +To make the introduction of [`"exports"`][] non-breaking, ensure that every previously supported entry point is exported. It is best to explicitly specify entry points so that the package’s public API is well-defined. For example, a project that previous exported `main`, `lib`, @@ -57,17 +57,17 @@ Alternatively a project could choose to export entire folders: "exports": { ".": "./lib/index.js", "./lib": "./lib/index.js", - "./lib/": "./lib/", + "./lib/*": "./lib/*.js", "./feature": "./feature/index.js", - "./feature/": "./feature/", + "./feature/*": "./feature/*.js", "./package.json": "./package.json" } } ``` As a last resort, package encapsulation can be disabled entirely by creating an -export for the root of the package `"./": "./"`. This will expose every file in -the package at the cost of disabling the encapsulation and potential tooling +export for the root of the package `"./*": "./*"`. This will expose every file +in the package at the cost of disabling the encapsulation and potential tooling benefits this provides. As the ES Module loader in Node.js enforces the use of [the full specifier path][], exporting the root rather than being explicit about entry is less expressive than either of the prior examples. Not only diff --git a/packages/package_json_and_file_extensions.md b/packages/package_json_and_file_extensions.md new file mode 100644 index 00000000..1065643b --- /dev/null +++ b/packages/package_json_and_file_extensions.md @@ -0,0 +1,55 @@ + +Within a package, the [`package.json`][] [`"type"`][] field defines how +Node.js should interpret `.js` files. If a `package.json` file does not have a +`"type"` field, `.js` files are treated as [CommonJS][]. + +A `package.json` `"type"` value of `"module"` tells Node.js to interpret `.js` +files within that package as using [ES module][] syntax. + +The `"type"` field applies not only to initial entry points (`node my-app.js`) +but also to files referenced by `import` statements and `import()` expressions. + +```js +// my-app.js, treated as an ES module because there is a package.json +// file in the same folder with "type": "module". + +import './startup/init.js'; +// Loaded as ES module since ./startup contains no package.json file, +// and therefore inherits the "type" value from one level up. + +import 'commonjs-package'; +// Loaded as CommonJS since ./node_modules/commonjs-package/package.json +// lacks a "type" field or contains "type": "commonjs". + +import './node_modules/commonjs-package/index.js'; +// Loaded as CommonJS since ./node_modules/commonjs-package/package.json +// lacks a "type" field or contains "type": "commonjs". +``` + +Files ending with `.mjs` are always loaded as [ES modules][] regardless of +the nearest parent `package.json`. + +Files ending with `.cjs` are always loaded as [CommonJS][] regardless of the +nearest parent `package.json`. + +```js +import './legacy-file.cjs'; +// Loaded as CommonJS since .cjs is always loaded as CommonJS. + +import 'commonjs-package/src/index.mjs'; +// Loaded as ES module since .mjs is always loaded as ES module. +``` + +The `.mjs` and `.cjs` extensions may be used to mix types within the same +package: + +* Within a `"type": "module"` package, Node.js can be instructed to + interpret a particular file as [CommonJS][] by naming it with a `.cjs` + extension (since both `.js` and `.mjs` files are treated as ES modules within + a `"module"` package). + +* Within a `"type": "commonjs"` package, Node.js can be instructed to + interpret a particular file as an [ES module][] by naming it with an `.mjs` + extension (since both `.js` and `.cjs` files are treated as CommonJS within a + `"commonjs"` package). + diff --git a/esm/resolving_user_conditions.md b/packages/resolving_user_conditions.md similarity index 92% rename from esm/resolving_user_conditions.md rename to packages/resolving_user_conditions.md index 50a76b98..22f988bd 100644 --- a/esm/resolving_user_conditions.md +++ b/packages/resolving_user_conditions.md @@ -1,6 +1,6 @@ When running Node.js, custom user conditions can be added with the -`--conditions` or `-u` flag: +`--conditions` flag: ```bash node --conditions=development main.js diff --git a/esm/self_referencing_a_package_using_its_name.md b/packages/self_referencing_a_package_using_its_name.md similarity index 73% rename from esm/self_referencing_a_package_using_its_name.md rename to packages/self_referencing_a_package_using_its_name.md index a86872a0..649c3774 100644 --- a/esm/self_referencing_a_package_using_its_name.md +++ b/packages/self_referencing_a_package_using_its_name.md @@ -1,6 +1,6 @@ Within a package, the values defined in the package’s -`package.json` `"exports"` field can be referenced via the package’s name. +`package.json` [`"exports"`][] field can be referenced via the package’s name. For example, assuming the `package.json` is: ```json @@ -21,9 +21,10 @@ Then any module _in that package_ can reference an export in the package itself: import { something } from 'a-package'; // Imports "something" from ./main.mjs. ``` -Self-referencing is available only if `package.json` has `exports`, and will -allow importing only what that `exports` (in the `package.json`) allows. -So the code below, given the previous package, will generate a runtime error: +Self-referencing is available only if `package.json` has [`"exports"`][], and +will allow importing only what that [`"exports"`][] (in the `package.json`) +allows. So the code below, given the previous package, will generate a runtime +error: ```js // ./another-module.mjs diff --git a/packages/subpath_export_patterns.md b/packages/subpath_export_patterns.md new file mode 100644 index 00000000..11d25fb2 --- /dev/null +++ b/packages/subpath_export_patterns.md @@ -0,0 +1,40 @@ + +> Stability: 1 - Experimental + +For packages with a small number of exports, we recommend explicitly listing +each exports subpath entry. But for packages that have large numbers of +subpaths, this might cause `package.json` bloat and maintenance issues. + +For these use cases, subpath export patterns can be used instead: + +```json +// ./node_modules/es-module-package/package.json +{ + "exports": { + "./features/*": "./src/features/*.js" + } +} +``` + +The left hand matching pattern must always end in `*`. All instances of `*` on +the right hand side will then be replaced with this value, including if it +contains any `/` separators. + +```js +import featureX from 'es-module-package/features/x'; +// Loads ./node_modules/es-module-package/src/features/x.js + +import featureY from 'es-module-package/features/y/y'; +// Loads ./node_modules/es-module-package/src/features/y/y.js +``` + +This is a direct static replacement without any special handling for file +extensions. In the previous example, `pkg/features/x.json` would be resolved to +`./src/features/x.json.js` in the mapping. + +The property of exports being statically enumerable is maintained with exports +patterns since the individual exports for a package can be determined by +treating the right hand side target pattern as a `**` glob against the list of +files within the package. Because `node_modules` paths are forbidden in exports +targets, this expansion is dependent on only the files of the package itself. + diff --git a/packages/subpath_exports.md b/packages/subpath_exports.md new file mode 100644 index 00000000..9768c135 --- /dev/null +++ b/packages/subpath_exports.md @@ -0,0 +1,31 @@ + +> Stability: 1 - Experimental + +When using the [`"exports"`][] field, custom subpaths can be defined along +with the main entry point by treating the main entry point as the +`"."` subpath: + +```json +{ + "main": "./main.js", + "exports": { + ".": "./main.js", + "./submodule": "./src/submodule.js" + } +} +``` + +Now only the defined subpath in [`"exports"`][] can be imported by a consumer: + +```js +import submodule from 'es-module-package/submodule'; +// Loads ./node_modules/es-module-package/src/submodule.js +``` + +While other subpaths will error: + +```js +import submodule from 'es-module-package/private-module.js'; +// Throws ERR_PACKAGE_PATH_NOT_EXPORTED +``` + diff --git a/esm/package_json_type_field.md b/packages/type.md similarity index 60% rename from esm/package_json_type_field.md rename to packages/type.md index b5704c84..9eadf35f 100644 --- a/esm/package_json_type_field.md +++ b/packages/type.md @@ -1,3 +1,17 @@ + + +* Type: {string} + +The `"type"` field defines the module format that Node.js will use for all +`.js` files that have that `package.json` file as their nearest parent. Files ending with `.js` will be loaded as ES modules when the nearest parent `package.json` file contains a top-level field `"type"` with a value of @@ -5,10 +19,9 @@ Files ending with `.js` will be loaded as ES modules when the nearest parent The nearest parent `package.json` is defined as the first `package.json` found when searching in the current folder, that folder’s parent, and so on up -until the root of the volume is reached. +until a node_modules folder or the volume root is reached. - -```js +```json // package.json { "type": "module" @@ -21,9 +34,9 @@ node my-app.js # Runs as ES module ``` If the nearest parent `package.json` lacks a `"type"` field, or contains -`"type": "commonjs"`, `.js` files are treated as CommonJS. If the volume root is -reached and no `package.json` is found, Node.js defers to the default, a -`package.json` with no `"type"` field. +`"type": "commonjs"`, `.js` files are treated as [CommonJS][]. If the volume +root is reached and no `package.json` is found, `.js` files are treated as +[CommonJS][]. `import` statements of `.js` files are treated as ES modules if the nearest parent `package.json` contains `"type": "module"`. @@ -33,12 +46,6 @@ parent `package.json` contains `"type": "module"`. import './startup.js'; // Loaded as ES module because of package.json ``` -Package authors should include the `"type"` field, even in packages where all -sources are CommonJS. Being explicit about the `type` of the package will -future-proof the package in case the default type of Node.js ever changes, and -it will also make things easier for build tools and loaders to determine how the -files in the package should be interpreted. - Regardless of the value of the `"type"` field, `.mjs` files are always treated as ES modules and `.cjs` files are always treated as CommonJS. diff --git a/esm/writing_dual_packages_while_avoiding_or_minimizing_hazards.md b/packages/writing_dual_packages_while_avoiding_or_minimizing_hazards.md similarity index 88% rename from esm/writing_dual_packages_while_avoiding_or_minimizing_hazards.md rename to packages/writing_dual_packages_while_avoiding_or_minimizing_hazards.md index a3ddf5a8..a50b2272 100644 --- a/esm/writing_dual_packages_while_avoiding_or_minimizing_hazards.md +++ b/packages/writing_dual_packages_while_avoiding_or_minimizing_hazards.md @@ -8,9 +8,10 @@ could be intended only for other environments such as browsers. Such a package would be usable by any version of Node.js, since `import` can refer to CommonJS files; but it would not provide any of the advantages of using ES module syntax. -A package could also switch from CommonJS to ES module syntax in a breaking -change version bump. This has the disadvantage that the newest version -of the package would only be usable in ES module-supporting versions of Node.js. +A package could also switch from CommonJS to ES module syntax in a [breaking +change](https://semver.org/) version bump. This has the disadvantage that the +newest version of the package would only be usable in ES module-supporting +versions of Node.js. Every pattern has tradeoffs, but there are two broad approaches that satisfy the following conditions: diff --git a/policy/dependency_redirection.md b/policy/dependency_redirection.md index e3d49f20..20a1590d 100644 --- a/policy/dependency_redirection.md +++ b/policy/dependency_redirection.md @@ -19,7 +19,7 @@ replaced. ``` 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, +of either `true`, `null`, a string pointing to a module to be resolved, or a conditions object. The specifier string does not perform any searching and must match exactly @@ -27,20 +27,20 @@ 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 -be used to find the module. +If the value of the redirection is `true` the default searching algorithms are +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. +If the value of the redirection is a string, it is resolved relative to +the manifest and then immediately used without searching. -Any specifier string that is attempted to resolve and not listed in the -dependencies will result in an error according to the policy. +Any specifier string for which resolution is attempted and that is not listed in +the dependencies results 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 +Redirection does not prevent access to APIs through means such as direct access +to `require.cache` or through `module.constructor` which allow access to loading modules. Policy redirection only affects 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. +`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 @@ -49,12 +49,12 @@ 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 preceding example, `"http"` will be allowed when the `"import"` condition is +the preceding example, `"http"` is 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 +A value of `null` for the resolved value causes the resolution to fail. This can be used to ensure some kinds of dynamic access are explicitly prevented. -Unknown values for the resolved module location will cause failure but are -not guaranteed to be forwards compatible. +Unknown values for the resolved module location cause failures but are +not guaranteed to be forward compatible. diff --git a/process/event_uncaughtexception.md b/process/event_uncaughtexception.md index be6308d1..44382bf1 100644 --- a/process/event_uncaughtexception.md +++ b/process/event_uncaughtexception.md @@ -10,7 +10,9 @@ changes: * `err` {Error} 未捕获的异常。 * `origin` {string} 表明异常是来自未处理的拒绝还是来自同步的错误。 可以是 `'uncaughtException'` 或 `'unhandledRejection'`。 - The latter is only used in conjunction with the [`--unhandled-rejections`][] flag set to `strict` and an unhandled rejection. + The latter is only used in conjunction with the + [`--unhandled-rejections`][] flag set to `strict` or `throw` and + an unhandled rejection. 当未捕获的 JavaScript 异常一直冒泡回到事件循环时，会触发 `'uncaughtException'` 事件。 默认情况下，Node.js 通过将堆栈跟踪打印到 `stderr` 并使用退出码 `1` 来处理此类异常，从而覆盖任何先前设置的 [`process.exitCode`]。 diff --git a/process/event_uncaughtexceptionmonitor.md b/process/event_uncaughtexceptionmonitor.md index 49ac543e..0f6f96f4 100644 --- a/process/event_uncaughtexceptionmonitor.md +++ b/process/event_uncaughtexceptionmonitor.md @@ -5,7 +5,9 @@ added: v13.7.0 * `err` {Error} The uncaught exception. * `origin` {string} Indicates if the exception originates from an unhandled rejection or from synchronous errors. Can either be `'uncaughtException'` or - `'unhandledRejection'`. + `'unhandledRejection'`. The latter is only used in conjunction with the + [`--unhandled-rejections`][] flag set to `strict` or `throw` and + an unhandled rejection. The `'uncaughtExceptionMonitor'` event is emitted before an `'uncaughtException'` event is emitted or a hook installed via diff --git a/repl/commands_and_special_keys.md b/repl/commands_and_special_keys.md index eabea2ca..4d9556d1 100644 --- a/repl/commands_and_special_keys.md +++ b/repl/commands_and_special_keys.md @@ -1,7 +1,7 @@ 所有 REPL 的实例都支持下列特殊命令： -* `.break` - 在输入一个多行表达式的过程中，输入 `.break` 命令（或按下 `-C` 组合键）将终止表达式的继续输入。 +* `.break` - 在输入一个多行表达式的过程中，输入 `.break` 命令（或按下 **Ctrl+C**）将终止表达式的继续输入。 * `.clear` - 重置 REPL 的 `context` 为一个空对象，并清除正在输入中的所有多行表达式。 * `.exit` - 关闭输入输出流，退出 REPL。 * `.help` - 显示特定命令的帮助列表。 @@ -9,7 +9,7 @@ `> .save ./file/to/save.js` * `.load` - 读取一个文件到当前 REPL 会话。 `> .load ./file/to/load.js` -* `.editor` 进入编辑模式（`-D` 完成，`-C` 取消） +* `.editor` 进入编辑模式（**Ctrl+D** 完成，**Ctrl+C** 取消） ```console > .editor @@ -27,9 +27,9 @@ welcome('Node.js 用户'); REPL 中下列按键组合有特殊作用： -* `-C` - 当按下一次时，与 `.break` 命令的效果一样。当在空白行按下两次时，与 `.exit` 命令的效果一样。 -* `-D` - 与 `.exit` 命令的效果一样。 -* `` - 当在空白行按下时，显示全局和本地作用域内的变量。当在输入时按下，显示相关的自动补全选项。 +* **Ctrl+C**: 当按下一次时，与 `.break` 命令的效果一样。当在空白行按下两次时，与 `.exit` 命令的效果一样。 +* **Ctrl+D**: 与 `.exit` 命令的效果一样。 +* ``: 当在空白行按下时，显示全局和本地作用域内的变量。当在输入时按下，显示相关的自动补全选项。 有关与反向i搜索相关的快捷键，请参见[反向i搜索][`reverse-i-search`]。 有关所有的其他快捷键，请参见 [TTY 快捷键][TTY keybindings]。 diff --git a/repl/event_exit.md b/repl/event_exit.md index 6495aa16..973bbbc3 100644 --- a/repl/event_exit.md +++ b/repl/event_exit.md @@ -2,7 +2,7 @@ added: v0.7.7 --> -当接收到 `.exit` 命令、或按下两次 `-C` 发出 `SIGINT` 信号、或按下 `-D` 发出 `'end'` 信号而使 REPL 被退出时，触发 `'exit'` 事件。 +当接收到 `.exit` 命令、或按下两次 **Ctrl+C** 发出 `SIGINT` 信号、或按下 **Ctrl+D** 发出 `'end'` 信号而使 REPL 被退出时，触发 `'exit'` 事件。 监听器的回调函数被调用时不带任何参数。 ```js diff --git a/repl/recoverable_errors.md b/repl/recoverable_errors.md index a2a1b950..0b1d016c 100644 --- a/repl/recoverable_errors.md +++ b/repl/recoverable_errors.md @@ -1,5 +1,5 @@ -当用户正在 REPL 中输入时，按下 `` 键会把当前行的输入发送到 `eval` 函数。 +当用户正在 REPL 中输入时，按下 **Enter** 键会把当前行的输入发送到 `eval` 函数。 为了支持多行输入，`eval` 函数可以返回一个 `repl.Recoverable` 实例给提供的回调函数： ```js diff --git a/repl/reverse_i_search.md b/repl/reverse_i_search.md index 8c0159e9..cbb486b1 100644 --- a/repl/reverse_i_search.md +++ b/repl/reverse_i_search.md @@ -3,14 +3,14 @@ added: v13.6.0 --> The REPL supports bi-directional reverse-i-search similar to [ZSH][]. It is -triggered with ` + R` to search backward and ` + S` to search -forward. +triggered with **Ctrl+R** to search backward and **Ctrl+S** to search +forwards. Duplicated history entires will be skipped. Entries are accepted as soon as any button is pressed that doesn't correspond -with the reverse search. Cancelling is possible by pressing `escape` or -` + C`. +with the reverse search. Cancelling is possible by pressing **Esc** or +**Ctrl+C**. Changing the direction immediately searches for the next entry in the expected direction from the current position on. diff --git a/stream/readable_destroy_error.md b/stream/readable_destroy_error.md index 1d83ac06..57e57f8a 100644 --- a/stream/readable_destroy_error.md +++ b/stream/readable_destroy_error.md @@ -1,5 +1,9 @@ * `error` {Error} 将会在 `'error'` 事件中作为负载传入的错误。 diff --git a/stream/transform_destroy_error.md b/stream/transform_destroy_error.md index 11c5b4d4..30dfa0c4 100644 --- a/stream/transform_destroy_error.md +++ b/stream/transform_destroy_error.md @@ -1,5 +1,9 @@ * `error` {Error} diff --git a/stream/writable_destroy_error.md b/stream/writable_destroy_error.md index adea8cd2..88d3476e 100644 --- a/stream/writable_destroy_error.md +++ b/stream/writable_destroy_error.md @@ -1,5 +1,9 @@ * `error` {Error} 可选，使用 `'error'` 事件触发的错误。 diff --git a/synopsis/example.md b/synopsis/example.md index db13eba7..4e000e84 100644 --- a/synopsis/example.md +++ b/synopsis/example.md @@ -8,7 +8,7 @@ 不以 `$` 或 `>` 字符开头的命令行展示的是上一个命令的输出。 首先，确保已经下载并安装了 Node.js。 -关于安装的更多信息，请参见[此指南][this guide]。 +关于安装的更多信息，请参见[通过包管理器安装 Node.js][Installing Node.js via package manager]。 现在，创建一个空的名为 `projects` 的项目文件夹，然后导航到它。