diff --git a/doc/api/addons.md b/doc/api/addons.md index 34f49d9a24ac77..9a2b6d1a536359 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -1,4 +1,4 @@ -# C++ Addons +# C++ addons @@ -395,7 +395,7 @@ only the symbols exported by Node.js will be available. source image. Using this option, the Addon will have access to the full set of dependencies. -### Loading Addons using `require()` +### Loading addons using `require()` The filename extension of the compiled Addon binary is `.node` (as opposed to `.dll` or `.so`). The [`require()`][require] function is written to look for @@ -410,7 +410,7 @@ there is a file `addon.js` in the same directory as the binary `addon.node`, then [`require('addon')`][require] will give precedence to the `addon.js` file and load it instead. -## Native Abstractions for Node.js +## Native abstractions for Node.js Each of the examples illustrated in this document make direct use of the Node.js and V8 APIs for implementing Addons. The V8 API can, and has, changed diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index cdac6287f4d6e6..49aac3dc445e45 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -1,4 +1,4 @@ -# Async Hooks +# Async hooks @@ -127,7 +127,7 @@ class MyAddedCallbacks extends MyAsyncCallbacks { const asyncHook = async_hooks.createHook(new MyAddedCallbacks()); ``` -##### Error Handling +##### Error handling If any `AsyncHook` callbacks throw, the application will print the stack trace and exit. The exit path does follow that of an uncaught exception, but @@ -201,7 +201,7 @@ be called again until enabled. For API consistency `disable()` also returns the `AsyncHook` instance. -#### Hook Callbacks +#### Hook callbacks Key events in the lifetime of asynchronous events have been categorized into four areas: instantiation, before/after the callback is called, and when the @@ -626,7 +626,7 @@ only on chained promises. That means promises not created by `then()`/`catch()` will not have the `before` and `after` callbacks fired on them. For more details see the details of the V8 [PromiseHooks][] API. -## JavaScript Embedder API +## JavaScript embedder API Library developers that handle their own asynchronous resources performing tasks like I/O, connection pooling, or managing callback queues may use the diff --git a/doc/api/buffer.md b/doc/api/buffer.md index b43b7eded247d7..2df4fe795082bf 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -53,7 +53,7 @@ const buf6 = Buffer.from('tést'); const buf7 = Buffer.from('tést', 'latin1'); ``` -## Buffers and Character Encodings +## Buffers and character encodings diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 1c1f736ed1b2da..779542c00fe58b 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,4 +1,4 @@ -# Child Process +# Child process @@ -70,7 +70,7 @@ For certain use cases, such as automating shell scripts, the the synchronous methods can have significant impact on performance due to stalling the event loop while spawned processes complete. -## Asynchronous Process Creation +## Asynchronous process creation The [`child_process.spawn()`][], [`child_process.fork()`][], [`child_process.exec()`][], and [`child_process.execFile()`][] methods all follow the idiomatic asynchronous @@ -153,7 +153,7 @@ changes: * `env` {Object} Environment key-value pairs. **Default:** `process.env`. * `encoding` {string} **Default:** `'utf8'` * `shell` {string} Shell to execute the command with. See - [Shell Requirements][] and [Default Windows Shell][]. **Default:** + [Shell requirements][] and [Default Windows shell][]. **Default:** `'/bin/sh'` on Unix, `process.env.ComSpec` on Windows. * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or @@ -270,8 +270,8 @@ changes: done on Windows. Ignored on Unix. **Default:** `false`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * `callback` {Function} Called with the output when process terminates. * `error` {Error} * `stdout` {string|Buffer} @@ -355,7 +355,7 @@ changes: **Default:** `process.execArgv`. * `serialization` {string} Specify the kind of serialization used for sending messages between processes. Possible values are `'json'` and `'advanced'`. - See [Advanced Serialization][] for more details. **Default:** `'json'`. + See [Advanced serialization][] for more details. **Default:** `'json'`. * `silent` {boolean} If `true`, stdin, stdout, and stderr of the child will be piped to the parent, otherwise they will be inherited from the parent, see the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s @@ -434,11 +434,11 @@ changes: * `gid` {number} Sets the group identity of the process (see setgid(2)). * `serialization` {string} Specify the kind of serialization used for sending messages between processes. Possible values are `'json'` and `'advanced'`. - See [Advanced Serialization][] for more details. **Default:** `'json'`. + See [Advanced serialization][] for more details. **Default:** `'json'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * `windowsVerbatimArguments` {boolean} No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to `true` automatically when `shell` is specified and is CMD. **Default:** `false`. @@ -699,7 +699,7 @@ see [V8 issue 7381](https://bugs.chromium.org/p/v8/issues/detail?id=7381). See also: [`child_process.exec()`][] and [`child_process.fork()`][]. -## Synchronous Process Creation +## Synchronous process creation The [`child_process.spawnSync()`][], [`child_process.execSync()`][], and [`child_process.execFileSync()`][] methods are synchronous and will block the @@ -755,8 +755,8 @@ changes: normally be created on Windows systems. **Default:** `false`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * Returns: {Buffer|string} The stdout from the command. The `child_process.execFileSync()` method is generally identical to @@ -804,7 +804,7 @@ changes: **Default:** `'pipe'`. * `env` {Object} Environment key-value pairs. **Default:** `process.env`. * `shell` {string} Shell to execute the command with. See - [Shell Requirements][] and [Default Windows Shell][]. **Default:** + [Shell requirements][] and [Default Windows shell][]. **Default:** `'/bin/sh'` on Unix, `process.env.ComSpec` on Windows. * `uid` {number} Sets the user identity of the process. (See setuid(2)). * `gid` {number} Sets the group identity of the process. (See setgid(2)). @@ -884,8 +884,8 @@ changes: **Default:** `'buffer'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different - shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. **Default:** `false` (no shell). + shell can be specified as a string. See [Shell requirements][] and + [Default Windows shell][]. **Default:** `false` (no shell). * `windowsVerbatimArguments` {boolean} No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to `true` automatically when `shell` is specified and is CMD. **Default:** `false`. @@ -1025,7 +1025,7 @@ message might not be the same as what is originally sent. If the `serialization` option was set to `'advanced'` used when spawning the child process, the `message` argument can contain data that JSON is not able to represent. -See [Advanced Serialization][] for more details. +See [Advanced serialization][] for more details. ### `subprocess.channel` @@ -160,7 +160,7 @@ added: v12.12.0 > Stability: 1 - Experimental -Enable experimental Source Map V3 support for stack traces. +Enable experimental Source Map v3 support for stack traces. Currently, overriding `Error.prepareStackTrace` is ignored when the `--enable-source-maps` flag is set. @@ -1099,7 +1099,7 @@ added: v0.1.3 Print node's version. -## Environment Variables +## Environment variables ### `NODE_DEBUG=module[,…]` @@ -753,7 +753,7 @@ changes: `undefined` (inherits from parent process). * `serialization` {string} Specify the kind of serialization used for sending messages between processes. Possible values are `'json'` and `'advanced'`. - See [Advanced Serialization for `child_process`][] for more details. + See [Advanced serialization for `child_process`][] for more details. **Default:** `false`. * `silent` {boolean} Whether or not to send output to parent's stdio. **Default:** `false`. @@ -883,5 +883,5 @@ socket.on('data', (id) => { [`process` event: `'message'`]: process.html#process_event_message [`server.close()`]: net.html#net_event_close [`worker.exitedAfterDisconnect`]: #cluster_worker_exitedafterdisconnect -[Advanced Serialization for `child_process`]: child_process.html#child_process_advanced_serialization +[Advanced serialization for `child_process`]: child_process.html#child_process_advanced_serialization [Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e45d41586cffd4..016a60802c46b4 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1585,7 +1585,7 @@ added: v6.3.0 * Returns: {Object} An object containing commonly used constants for crypto and security related operations. The specific constants currently defined are - described in [Crypto Constants][]. + described in [Crypto constants][]. ### `crypto.DEFAULT_ENCODING` @@ -6,7 +6,7 @@ -The `dgram` module provides an implementation of UDP Datagram sockets. +The `dgram` module provides an implementation of UDP datagram sockets. ```js const dgram = require('dgram'); @@ -558,7 +558,7 @@ also use explicit scope in addresses, so only packets sent to a multicast address without specifying an explicit scope are affected by the most recent successful use of this call. -#### Examples: IPv6 Outgoing Multicast Interface +#### Example: IPv6 outgoing multicast interface On most systems, where scope format uses the interface name: @@ -580,7 +580,7 @@ socket.bind(1234, () => { }); ``` -#### Example: IPv4 Outgoing Multicast Interface +#### Example: IPv4 outgoing multicast interface All systems use an IP of the host on the desired physical interface: ```js @@ -591,7 +591,7 @@ socket.bind(1234, () => { }); ``` -#### Call Results +#### Call results A call on a socket that is not ready to send or no longer open may throw a *Not running* [`Error`][]. diff --git a/doc/api/dns.md b/doc/api/dns.md index b89be2f104694f..8a4ee45fe10de5 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -621,7 +621,7 @@ That is, if attempting to resolve with the first server provided results in a subsequent servers provided. Fallback DNS servers will only be used if the earlier ones time out or result in some other error. -## DNS Promises API +## DNS promises API The `dns.promises` API provides an alternative set of asynchronous DNS methods that return `Promise` objects rather than using callbacks. The API is accessible diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 7059c4d33e11ca..f15936b3f43279 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -1,4 +1,4 @@ -# About this Documentation +# About this documentation @@ -12,7 +12,7 @@ Node.js is a JavaScript runtime built on the [V8 JavaScript engine][]. Report errors in this documentation in [the issue tracker][]. See [the contributing guide][] for directions on how to submit pull requests. -## Stability Index +## Stability index @@ -43,7 +43,7 @@ Bugs or behavior changes may surprise end users when Experimental API modifications occur. To avoid surprises, use of an Experimental feature may need a command-line flag. Experimental features may also emit a [warning][]. -## JSON Output +## JSON output diff --git a/doc/api/domain.md b/doc/api/domain.md index fa3aef66b98241..b9219fbb4d714e 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -30,7 +30,7 @@ will be notified, rather than losing the context of the error in the `process.on('uncaughtException')` handler, or causing the program to exit immediately with an error code. -## Warning: Don't Ignore Errors! +## Warning: Don't ignore errors! @@ -199,7 +199,7 @@ are added to it. * `error.domainThrown` A boolean indicating whether the error was thrown, emitted, or passed to a bound callback function. -## Implicit Binding +## Implicit binding @@ -225,7 +225,7 @@ Implicit binding routes thrown errors and `'error'` events to the `Domain`. Implicit binding only takes care of thrown errors and `'error'` events. -## Explicit Binding +## Explicit binding @@ -432,9 +432,9 @@ d.run(() => { In this example, the `d.on('error')` handler will be triggered, rather than crashing the program. -## Domains and Promises +## Domains and promises -As of Node.js 8.0.0, the handlers of Promises are run inside the domain in +As of Node.js 8.0.0, the handlers of promises are run inside the domain in which the call to `.then()` or `.catch()` itself was made: ```js @@ -472,7 +472,7 @@ d2.run(() => { ``` Domains will not interfere with the error handling mechanisms for -Promises. In other words, no `'error'` event will be emitted for unhandled +promises. In other words, no `'error'` event will be emitted for unhandled `Promise` rejections. [`Error`]: errors.html#errors_class_error diff --git a/doc/api/embedding.md b/doc/api/embedding.md index a8fe2de72c9310..1a416f52c600de 100644 --- a/doc/api/embedding.md +++ b/doc/api/embedding.md @@ -1,4 +1,4 @@ -# C++ Embedder API +# C++ embedder API diff --git a/doc/api/errors.md b/doc/api/errors.md index bbec1313c5d827..d59c4029e60e5e 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -16,11 +16,11 @@ errors: Node.js detects an exceptional logic violation that should never occur. These are raised typically by the `assert` module. -All JavaScript and System errors raised by Node.js inherit from, or are +All JavaScript and system errors raised by Node.js inherit from, or are instances of, the standard JavaScript {Error} class and are guaranteed to provide *at least* the properties available on that class. -## Error Propagation and Interception +## Error propagation and interception @@ -186,7 +186,7 @@ circumstance of why the error occurred. `Error` objects capture a "stack trace" detailing the point in the code at which the `Error` was instantiated, and may provide a text description of the error. -All errors generated by Node.js, including all System and JavaScript errors, +All errors generated by Node.js, including all system and JavaScript errors, will either be instances of, or inherit from, the `Error` class. ### `new Error(message)` @@ -258,7 +258,7 @@ not capture any frames. The `error.code` property is a string label that identifies the kind of error. `error.code` is the most stable way to identify an error. It will only change between major versions of Node.js. In contrast, `error.message` strings may -change between any versions of Node.js. See [Node.js Error Codes][] for details +change between any versions of Node.js. See [Node.js error codes][] for details about specific codes. ### `error.message` @@ -497,7 +497,7 @@ If present, `error.port` is the network connection port that is not available. The `error.syscall` property is a string describing the [syscall][] that failed. -### Common System Errors +### Common system errors This is a list of system errors commonly-encountered when writing a Node.js program. For a comprehensive list, see the [`errno`(3) man page][]. @@ -574,7 +574,7 @@ require('url').parse(() => { }); Node.js will generate and throw `TypeError` instances *immediately* as a form of argument validation. -## Exceptions vs. Errors +## Exceptions vs. errors @@ -588,7 +588,7 @@ Some exceptions are *unrecoverable* at the JavaScript layer. Such exceptions will *always* cause the Node.js process to crash. Examples include `assert()` checks or `abort()` calls in the C++ layer. -## OpenSSL Errors +## OpenSSL errors Errors originating in `crypto` or `tls` are of class `Error`, and in addition to the standard `.code` and `.message` properties, may have some additional @@ -612,7 +612,7 @@ The OpenSSL library the error originates in. A human-readable string describing the reason for the error. -## Node.js Error Codes +## Node.js error codes ### `ERR_AMBIGUOUS_ARGUMENT` @@ -2213,7 +2213,7 @@ changes: A module file could not be resolved while attempting a [`require()`][] or `import` operation. -## Legacy Node.js Error Codes +## Legacy Node.js error codes > Stability: 0 - Deprecated. These error codes are either inconsistent, or have > been removed. @@ -2618,7 +2618,7 @@ such as `process.stdout.on('data')`. [`zlib`]: zlib.html [ES Module]: esm.html [ICU]: intl.html#intl_internationalization_support -[Node.js Error Codes]: #nodejs-error-codes +[Node.js error codes]: #nodejs-error-codes [V8's stack trace API]: https://github.com/v8/v8/wiki/Stack-Trace-API [WHATWG Supported Encodings]: util.html#util_whatwg_supported_encodings [WHATWG URL API]: url.html#url_the_whatwg_url_api diff --git a/doc/api/esm.md b/doc/api/esm.md index b92ae3138e97a4..9252eaeed2306a 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -1,4 +1,4 @@ -# ECMAScript Modules +# ECMAScript modules @@ -121,7 +121,7 @@ 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. -### Package Scope and File Extensions +### Package scope and file extensions A folder containing a `package.json` file, and all subfolders below that folder down until the next folder containing another `package.json`, is considered a @@ -196,7 +196,7 @@ unspecified. ## Packages -### Package Entry Points +### Package entry points 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 @@ -216,7 +216,7 @@ CommonJS; `"main"` will be overridden by `"exports"` if it exists. As such 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 @@ -274,7 +274,7 @@ will encapsulation be lost but module consumers will be unable to `import feature from 'my-mod/feature'` as they will need to provide the full path `import feature from 'my-mod/feature/index.js`. -#### Main Entry Point Export +#### Main entry point export 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: @@ -298,7 +298,7 @@ package. It is not a strong encapsulation since a direct require of any absolute subpath of the package such as `require('/path/to/node_modules/pkg/subpath.js')` will still load `subpath.js`. -#### Subpath Exports +#### Subpath exports When using the `"exports"` field, custom subpaths can be defined along with the main entry point by treating the main entry point as the @@ -355,7 +355,7 @@ module inside the subfolder. Any modules which are not public should be moved to another folder to retain the encapsulation benefits of exports. -#### Package Exports Fallbacks +#### Package exports fallbacks For possible new specifier support in future, array fallbacks are supported for all invalid specifiers: @@ -372,7 +372,7 @@ supported for all invalid specifiers: Since `"not:valid"` is not a valid specifier, `"./submodule.js"` is used instead as the fallback, as if it were the only target. -#### Exports Sugar +#### Exports sugar If the `"."` export is the only export, the `"exports"` field provides sugar for this case being the direct `"exports"` field value. @@ -398,7 +398,7 @@ can be written: } ``` -#### Conditional Exports +#### Conditional exports Conditional exports provide a way to map to different paths depending on certain conditions. They are supported for both CommonJS and ES module imports. @@ -536,7 +536,7 @@ and in a CommonJS one. For example, this code will also work: const { something } = require('a-package/foo'); // Loads from ./foo.js. ``` -### Dual CommonJS/ES Module Packages +### Dual CommonJS/ES module packages 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 @@ -549,12 +549,12 @@ ignores) the top-level `"module"` field. Node.js can now run ES module entry points, and a package can contain both CommonJS and ES module entry points (either via separate specifiers such as `'pkg'` and `'pkg/es-module'`, or both at the same specifier via [Conditional -Exports][]). Unlike in the scenario where `"module"` is only used by bundlers, +exports][]). Unlike in the scenario where `"module"` is only used by bundlers, or ES module files are transpiled into CommonJS on the fly before evaluation by Node.js, the files referenced by the ES module entry point are evaluated as ES modules. -#### Dual Package Hazard +#### Dual package hazard When an application is using a package that provides both CommonJS and ES module sources, there is a risk of certain bugs if both versions of the package get @@ -577,7 +577,7 @@ all-CommonJS or all-ES module environments, respectively, and therefore is surprising to users. It also differs from the behavior users are familiar with when using transpilation via tools like [Babel][] or [`esm`][]. -#### Writing Dual Packages While Avoiding or Minimizing Hazards +#### Writing dual packages while avoiding or minimizing hazards First, the hazard described in the previous section occurs when a package contains both CommonJS and ES module sources and both sources are provided for @@ -607,11 +607,11 @@ following conditions: browsers. 1. The hazards described in the previous section are avoided or minimized. -##### Approach #1: Use an ES Module Wrapper +##### Approach #1: Use an ES module wrapper Write the package in CommonJS or transpile ES module sources into CommonJS, and create an ES module wrapper file that defines the named exports. Using -[Conditional Exports][], the ES module wrapper is used for `import` and the +[Conditional exports][], the ES module wrapper is used for `import` and the CommonJS entry point for `require`. @@ -689,7 +689,7 @@ stateless): } ``` -##### Approach #2: Isolate State +##### Approach #2: Isolate state A `package.json` file can define the separate CommonJS and ES module entry points directly: @@ -859,7 +859,7 @@ property: * `url` {string} The absolute `file:` URL of the module. -## Differences Between ES Modules and CommonJS +## Differences between ES modules and CommonJS ### Mandatory file extensions @@ -955,7 +955,7 @@ To include an ES module into CommonJS, use [`import()`][]. ### `import` statements 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 +file types such as JSON or native modules are not supported. For those, use [`module.createRequire()`][]. `import` statements are permitted only in ES modules. For similar functionality @@ -991,9 +991,9 @@ It is also possible to [Dynamic `import()`][] is supported in both CommonJS and ES modules. It can be used to include ES module files from CommonJS code. -## CommonJS, JSON, and Native Modules +## CommonJS, JSON, and native modules -CommonJS, JSON, and Native modules can be used with +CommonJS, JSON, and native modules can be used with [`module.createRequire()`][]. ```js @@ -1043,7 +1043,7 @@ syncBuiltinESMExports(); fs.readFileSync === readFileSync; ``` -## Experimental JSON Modules +## Experimental JSON modules Currently importing JSON modules are only supported in the `commonjs` mode and are loaded using the CJS loader. [WHATWG JSON modules specification][] are @@ -1073,7 +1073,7 @@ node index.mjs # fails node --experimental-json-modules index.mjs # works ``` -## Experimental Wasm Modules +## Experimental Wasm modules Importing Web Assembly modules is supported under the `--experimental-wasm-modules` flag, allowing any `.wasm` files to be @@ -1097,7 +1097,7 @@ node --experimental-wasm-modules index.mjs would provide the exports interface for the instantiation of `module.wasm`. -## Experimental Top-Level `await` +## Experimental top-level `await` When the `--experimental-top-level-await` flag is provided, `await` may be used in the top level (outside of async functions) within modules. This implements @@ -1123,7 +1123,7 @@ node b.mjs # fails node --experimental-top-level-await b.mjs # works ``` -## Experimental Loaders +## Experimental loaders **Note: This API is currently being redesigned and will still change.** @@ -1148,11 +1148,11 @@ and parent URL. The module specifier is the string in an `import` statement or this one, or `undefined` if this is the main entry point for the application. The `conditions` property on the `context` is an array of conditions for -[Conditional Exports][] that apply to this resolution request. They can be used +[Conditional exports][] that apply to this resolution request. They can be used for looking up conditional mappings elsewhere or to modify the list when calling the default resolution logic. -The [current set of Node.js default conditions][Conditional Exports] will always +The [current set of Node.js default conditions][Conditional exports] will always be in the `context.conditions` list passed to the hook. If the hook wants to ensure Node.js-compatible resolution logic, all items from this default condition list **must** be passed through to the `defaultResolve` function. @@ -1512,7 +1512,7 @@ loaded from disk but before Node.js executes it; and so on for any `.coffee`, `.litcoffee` or `.coffee.md` files referenced via `import` statements of any loaded file. -## Resolution Algorithm +## Resolution algorithm ### Features @@ -1525,7 +1525,7 @@ The resolver has the following properties: * No folder mains * Bare specifier package resolution lookup through node_modules -### Resolver Algorithm +### Resolver algorithm The algorithm to load an ES module specifier is given through the **ESM_RESOLVE** method below. It returns the resolved URL for a @@ -1797,7 +1797,7 @@ success! [Babel]: https://babeljs.io/ [CommonJS]: modules.html -[Conditional Exports]: #esm_conditional_exports +[Conditional exports]: #esm_conditional_exports [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports [ECMAScript-modules implementation]: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md [ECMAScript Top-Level `await` proposal]: https://github.com/tc39/proposal-top-level-await/ diff --git a/doc/api/events.md b/doc/api/events.md index e5d8e41c049769..80e9ccf6fef27a 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -74,7 +74,7 @@ myEmitter.on('event', (a, b) => { myEmitter.emit('event', 'a', 'b'); ``` -## Asynchronous vs. Synchronous +## Asynchronous vs. synchronous The `EventEmitter` calls all listeners synchronously in the order in which they were registered. This ensures the proper sequencing of @@ -167,7 +167,7 @@ myEmitter.emit('error', new Error('whoops!')); // Still throws and crashes Node.js ``` -## Capture Rejections of Promises +## Capture rejections of promises > Stability: 1 - captureRejections is experimental. @@ -968,7 +968,7 @@ There are two key differences between the Node.js `EventTarget` and the 2. In the Node.js `EventTarget`, if an event listener is an async function or returns a `Promise`, and the returned `Promise` rejects, the rejection will be automatically captured and handled the same way as a listener that - throws synchronously (see [`EventTarget` Error Handling][] for details). + throws synchronously (see [`EventTarget` error handling][] for details). ### `NodeEventTarget` vs. `EventEmitter` @@ -990,7 +990,7 @@ and cannot be used in place of an `EventEmitter` in most cases. 3. The `NodeEventTarget` supports `EventListener` objects as well as functions as handlers for all event types. -### Event Listener +### Event listener Event listeners registered for an event `type` may either be JavaScript functions or objects with a `handleEvent` property whose value is a function. @@ -1000,7 +1000,7 @@ passed to the `eventTarget.dispatchEvent()` function. Async functions may be used as event listeners. If an async handler function rejects, the rejection will be captured and be will handled as described in -[`EventTarget` Error Handling][]. +[`EventTarget` error handling][]. An error thrown by one handler function will not prevent the other handlers from being invoked. @@ -1042,7 +1042,7 @@ target.addEventListener('foo', handler3); target.addEventListener('foo', handler4, { once: true }); ``` -### `EventTarget` Error Handling +### `EventTarget` error handling When a registered event listener throws (or returns a Promise that rejects), by default the error will be forwarded to the `process.on('error')` event @@ -1399,7 +1399,7 @@ to the `EventTarget`. [`emitter.removeListener()`]: #events_emitter_removelistener_eventname_listener [`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n [`Event` Web API]: https://dom.spec.whatwg.org/#event -[`EventTarget` Error Handling]: #events_eventtarget_error_handling +[`EventTarget` error handling]: #events_eventtarget_error_handling [`EventTarget` Web API]: https://dom.spec.whatwg.org/#eventtarget [`fs.ReadStream`]: fs.html#fs_class_fs_readstream [`net.Server`]: net.html#net_class_net_server diff --git a/doc/api/fs.md b/doc/api/fs.md index fe89d169cce0f9..317a1ca174ca0d 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1,4 +1,4 @@ -# File System +# File system @@ -242,7 +242,7 @@ fs.readFileSync(new URL('file:///C:/path/%5c')); \ or / characters */ ``` -## File Descriptors +## File descriptors On POSIX systems, for every process, the kernel maintains a table of currently open files and resources. Each open file is assigned a simple numeric @@ -277,7 +277,7 @@ at any given time so it is critical to close the descriptor when operations are completed. Failure to do so will result in a memory leak that will eventually cause an application to crash. -## Threadpool Usage +## Threadpool usage All file system APIs except `fs.FSWatcher()` and those that are explicitly synchronous use libuv's threadpool, which can have surprising and negative @@ -1030,7 +1030,7 @@ added: v0.11.13 The timestamp indicating the creation time of this file. -### Stat Time Values +### Stat time values The `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` properties are numeric values that hold the corresponding times in milliseconds. Their @@ -1155,7 +1155,7 @@ changes: Tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the accessibility -checks to be performed. Check [File Access Constants][] for possible values +checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). @@ -1297,7 +1297,7 @@ changes: Synchronously tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the -accessibility checks to be performed. Check [File Access Constants][] for +accessibility checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). @@ -1623,7 +1623,7 @@ through any other `fs` operation may lead to undefined behavior. Returns an object containing commonly used constants for file system operations. The specific constants currently defined are described in -[FS Constants][]. +[FS constants][]. ## `fs.copyFile(src, dest[, mode], callback)` @@ -4290,7 +4290,7 @@ It is unsafe to use `fs.writeFile()` multiple times on the same file without waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is recommended. -### Using `fs.writeFile()` with File Descriptors +### Using `fs.writeFile()` with file descriptors When `file` is a file descriptor, the behavior is almost identical to directly calling `fs.write()` like: @@ -4893,7 +4893,7 @@ added: v10.0.0 Tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the accessibility -checks to be performed. Check [File Access Constants][] for possible values +checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). @@ -5480,7 +5480,7 @@ Any specified `FileHandle` has to support writing. It is unsafe to use `fsPromises.writeFile()` multiple times on the same file without waiting for the `Promise` to be resolved (or rejected). -## FS Constants +## FS constants The following constants are exported by `fs.constants`. @@ -5504,7 +5504,7 @@ fs.open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => { }); ``` -### File Access Constants +### File access constants The following constants are meant for use with [`fs.access()`][]. @@ -5536,7 +5536,7 @@ The following constants are meant for use with [`fs.access()`][]. -### File Copy Constants +### File copy constants The following constants are meant for use with [`fs.copyFile()`][]. @@ -5564,7 +5564,7 @@ The following constants are meant for use with [`fs.copyFile()`][]. -### File Open Constants +### File open constants The following constants are meant for use with `fs.open()`. @@ -5658,7 +5658,7 @@ The following constants are meant for use with `fs.open()`. -### File Type Constants +### File type constants The following constants are meant for use with the [`fs.Stats`][] object's `mode` property for determining a file's type. @@ -5702,7 +5702,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's -### File Mode Constants +### File mode constants The following constants are meant for use with the [`fs.Stats`][] object's `mode` property for determining the access permissions for a file. @@ -5762,7 +5762,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's -## File System Flags +## File system flags The following flags are available wherever the `flag` option takes a string. @@ -5910,8 +5910,8 @@ the file contents. [`util.promisify()`]: util.html#util_util_promisify_original [Caveats]: #fs_caveats [Common System Errors]: errors.html#errors_common_system_errors -[FS Constants]: #fs_fs_constants_1 -[File Access Constants]: #fs_file_access_constants +[FS constants]: #fs_fs_constants_1 +[File access constants]: #fs_file_access_constants [MDN-Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date [MDN-Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type [MSDN-Rel-Path]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths diff --git a/doc/api/globals.md b/doc/api/globals.md index 7e6129e9038aa2..4e2e362bcdeb5b 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -1,4 +1,4 @@ -# Global Objects +# Global objects diff --git a/doc/api/http2.md b/doc/api/http2.md index 956196dff22d13..67bb4c27e4d0b0 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -119,7 +119,7 @@ User code will not create `Http2Session` instances directly. Server-side new HTTP/2 connection is received. Client-side `Http2Session` instances are created using the `http2.connect()` method. -#### `Http2Session` and Sockets +#### `Http2Session` and sockets Every `Http2Session` instance is associated with exactly one [`net.Socket`][] or [`tls.TLSSocket`][] when it is created. When either the `Socket` or the @@ -2366,7 +2366,7 @@ client.close(); added: v8.4.0 --> -#### Error Codes for `RST_STREAM` and `GOAWAY` +#### Error codes for `RST_STREAM` and `GOAWAY` | Value | Name | Constant | @@ -2432,7 +2432,7 @@ added: v8.4.0 Returns a [HTTP/2 Settings Object][] containing the deserialized settings from the given `Buffer` as generated by `http2.getPackedSettings()`. -### Headers Object +### Headers object Headers are represented as own-properties on JavaScript objects. The property keys will be serialized to lower-case. Property values should be strings (if @@ -2480,7 +2480,7 @@ server.on('stream', (stream, headers) => { }); ``` -### Settings Object +### Settings object -* [About these Docs](documentation.html) -* [Usage & Example](synopsis.html) +* [About these docs](documentation.html) +* [Usage and example](synopsis.html)
-* [Assertion Testing](assert.html) -* [Async Hooks](async_hooks.html) +* [Assertion testing](assert.html) +* [Async hooks](async_hooks.html) * [Buffer](buffer.html) -* [C++ Addons](addons.html) -* [C/C++ Addons with N-API](n-api.html) -* [C++ Embedder API](embedding.html) -* [Child Processes](child_process.html) +* [C++ addons](addons.html) +* [C/C++ addons with N-API](n-api.html) +* [C++ embedder API](embedding.html) +* [Child processes](child_process.html) * [Cluster](cluster.html) -* [Command Line Options](cli.html) +* [Command line options](cli.html) * [Console](console.html) * [Crypto](crypto.html) * [Debugger](debugger.html) * [Deprecated APIs](deprecations.html) * [DNS](dns.html) * [Domain](domain.html) -* [ECMAScript Modules](esm.html) +* [ECMAScript modules](esm.html) * [Errors](errors.html) * [Events](events.html) -* [File System](fs.html) +* [File system](fs.html) * [Globals](globals.html) * [HTTP](http.html) * [HTTP/2](http2.html) @@ -39,27 +39,27 @@ * [Net](net.html) * [OS](os.html) * [Path](path.html) -* [Performance Hooks](perf_hooks.html) +* [Performance hooks](perf_hooks.html) * [Policies](policy.html) * [Process](process.html) * [Punycode](punycode.html) -* [Query Strings](querystring.html) +* [Query strings](querystring.html) * [Readline](readline.html) * [REPL](repl.html) * [Report](report.html) * [Stream](stream.html) -* [String Decoder](string_decoder.html) +* [String decoder](string_decoder.html) * [Timers](timers.html) * [TLS/SSL](tls.html) -* [Trace Events](tracing.html) +* [Trace events](tracing.html) * [TTY](tty.html) -* [UDP/Datagram](dgram.html) +* [UDP/datagram](dgram.html) * [URL](url.html) * [Utilities](util.html) * [V8](v8.html) * [VM](vm.html) * [WASI](wasi.html) -* [Worker Threads](worker_threads.html) +* [Worker threads](worker_threads.html) * [Zlib](zlib.html) diff --git a/doc/api/inspector.md b/doc/api/inspector.md index ece84aa2c1f2a8..4f9501a5f861a7 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -188,7 +188,7 @@ to the run-time events. Apart from the debugger, various V8 Profilers are available through the DevTools protocol. -### CPU Profiler +### CPU profiler Here's an example showing how to use the [CPU Profiler][]: @@ -213,7 +213,7 @@ session.post('Profiler.enable', () => { }); ``` -### Heap Profiler +### Heap profiler Here's an example showing how to use the [Heap Profiler][]: diff --git a/doc/api/intl.md b/doc/api/intl.md index 25f7e61cd1808a..8b7dee489b4e9b 100644 --- a/doc/api/intl.md +++ b/doc/api/intl.md @@ -1,4 +1,4 @@ -# Internationalization Support +# Internationalization support diff --git a/doc/api/modules.md b/doc/api/modules.md index 0d23edcbe7e8fb..eccf4ed68d3e58 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -78,7 +78,7 @@ Because `module` provides a `filename` property (normally equivalent to `__filename`), the entry point of the current application can be obtained by checking `require.main.filename`. -## Addenda: Package Manager Tips +## Addenda: Package manager tips @@ -139,7 +139,7 @@ Attempting to do so will throw [an error][]. The `.mjs` extension is reserved for [ECMAScript Modules][] which cannot be loaded via `require()`. See [ECMAScript Modules][] for more details. -## All Together... +## All together... @@ -254,7 +254,7 @@ allowing transitive dependencies to be loaded even when they would cause cycles. To have a module execute code multiple times, export a function, and call that function. -### Module Caching Caveats +### Module caching caveats @@ -269,7 +269,7 @@ them as different modules and will reload the file multiple times. For example, `require('./foo')` and `require('./FOO')` return two different objects, irrespective of whether or not `./foo` and `./FOO` are the same file. -## Core Modules +## Core modules @@ -347,7 +347,7 @@ in main, a.done = true, b.done = true Careful planning is required to allow cyclic module dependencies to work correctly within an application. -## File Modules +## File modules @@ -373,7 +373,7 @@ either be a core module or is loaded from a `node_modules` folder. If the given path does not exist, `require()` will throw an [`Error`][] with its `code` property set to `'MODULE_NOT_FOUND'`. -## Folders as Modules +## Folders as modules @@ -413,7 +413,7 @@ with the default error: Error: Cannot find module 'some-library' ``` -## Loading from `node_modules` Folders +## Loading from `node_modules` folders @@ -737,7 +737,7 @@ Returns an array containing the paths searched during resolution of `request` or `null` if the `request` string references a core module, for example `http` or `fs`. -## The `module` Object +## The `module` object @@ -935,7 +935,7 @@ Since `require()` returns the `module.exports`, and the `module` is typically *only* available within a specific module's code, it must be explicitly exported in order to be used. -## The `Module` Object +## The `Module` object @@ -1083,7 +1083,7 @@ added: v13.7.0 Creates a new `sourceMap` instance. -`payload` is an object with keys matching the [Source Map V3 format][]: +`payload` is an object with keys matching the [Source map v3 format][]: * `file`: {string} * `version`: {number} @@ -1134,4 +1134,4 @@ consists of the following keys: [`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir [`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces [`SourceMap`]: modules.html#modules_class_module_sourcemap -[Source Map V3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej +[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej diff --git a/doc/api/n-api.md b/doc/api/n-api.md index e375616d23dd90..902cb883aeec92 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -31,7 +31,7 @@ properties: `napi_value`. * In case of an error status code, additional information can be obtained using `napi_get_last_error_info`. More information can be found in the error - handling section [Error Handling][]. + handling section [Error handling][]. The N-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. @@ -78,7 +78,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`. -## Implications of ABI Stability +## Implications of ABI stability Although N-API provides an ABI stability guarantee, other parts of Node.js do not, and any external libraries used from the addon may not. In particular, @@ -196,7 +196,7 @@ GitHub projects using CMake.js. #### prebuildify -[prebuildify][] is tool based on node-gyp. The advantage of prebuildify is +[prebuildify][] is a tool based on node-gyp. The advantage of prebuildify is that the built binaries are bundled with the native module when it's uploaded to npm. The binaries are downloaded from npm and are immediately available to the module user when the native module is installed. @@ -233,7 +233,7 @@ opt-in to access those APIs: In this case the entire API surface, including any experimental APIs, will be available to the module code. -## N-API Version Matrix +## N-API version matrix N-API versions are additive and versioned independently from Node.js. Version 4 is an extension to version 3 in that it has all of the APIs @@ -343,7 +343,7 @@ NAPI_MODULE_INIT() { } ``` -## Environment Life Cycle APIs +## Environment life cycle APIs > Stability: 1 - Experimental @@ -425,7 +425,7 @@ This API retrieves data that was previously associated with the currently running Agent via `napi_set_instance_data()`. If no data is set, the call will succeed and `data` will be set to `NULL`. -## Basic N-API Data Types +## Basic N-API data types N-API exposes the following fundamental datatypes as abstractions that are consumed by the various APIs. These APIs should be treated as opaque, @@ -492,7 +492,7 @@ typedef struct { not implemented for any VM. * `error_code`: The N-API status code that originated with the last error. -See the [Error Handling][] section for additional information. +See the [Error handling][] section for additional information. ### napi_env @@ -557,7 +557,7 @@ typedef enum { } napi_threadsafe_function_call_mode; ``` -### N-API Memory Management types +### N-API memory management types #### napi_handle_scope This is an abstraction used to control and modify the lifetime of objects @@ -575,7 +575,7 @@ using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC that all `napi_value`s created during the lifetime of the handle scope are no longer referenced from the current stack frame. -For more details, review the [Object Lifetime Management][]. +For more details, review the [Object lifetime management][]. #### napi_escapable_handle_scope @@ -1252,7 +1252,7 @@ The following process scheduling constants are exported by -### libuv Constants +### libuv constants