From 773184cd22957529f758aa2277d8ebc1d5f6c266 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 14 Jun 2020 14:49:34 -0700 Subject: [PATCH] doc: use sentence-case for headings in docs PR-URL: https://github.com/nodejs/node/pull/33889 Refs: https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings Refs: https://docs.microsoft.com/en-us/style-guide/capitalization Reviewed-By: Luigi Pinca Reviewed-By: James M Snell --- doc/api/addons.md | 6 +-- doc/api/async_hooks.md | 8 ++-- doc/api/buffer.md | 4 +- doc/api/child_process.md | 44 ++++++++++---------- doc/api/cli.md | 16 +++---- doc/api/cluster.md | 6 +-- doc/api/crypto.md | 18 ++++---- doc/api/debugger.md | 8 ++-- doc/api/deprecations.md | 14 +++---- doc/api/dgram.md | 10 ++--- doc/api/dns.md | 2 +- doc/api/documentation.md | 6 +-- doc/api/domain.md | 12 +++--- doc/api/embedding.md | 2 +- doc/api/errors.md | 20 ++++----- doc/api/esm.md | 58 +++++++++++++------------- doc/api/events.md | 14 +++---- doc/api/fs.md | 40 +++++++++--------- doc/api/globals.md | 2 +- doc/api/http2.md | 14 +++---- doc/api/index.md | 34 +++++++-------- doc/api/inspector.md | 4 +- doc/api/intl.md | 2 +- doc/api/modules.md | 24 +++++------ doc/api/n-api.md | 62 +++++++++++++-------------- doc/api/net.md | 2 +- doc/api/os.md | 18 ++++---- doc/api/perf_hooks.md | 2 +- doc/api/policy.md | 8 ++-- doc/api/process.md | 10 ++--- doc/api/querystring.md | 2 +- doc/api/readline.md | 4 +- doc/api/repl.md | 24 +++++------ doc/api/report.md | 4 +- doc/api/stream.md | 88 +++++++++++++++++++-------------------- doc/api/string_decoder.md | 2 +- doc/api/synopsis.md | 2 +- doc/api/timers.md | 4 +- doc/api/tls.md | 42 ++++++++++--------- doc/api/tracing.md | 6 +-- doc/api/url.md | 6 +-- doc/api/util.md | 12 +++--- doc/api/v8.md | 4 +- doc/api/vm.md | 6 +-- doc/api/worker_threads.md | 2 +- doc/api/zlib.md | 10 ++--- 46 files changed, 346 insertions(+), 342 deletions(-) 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 diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 20f0cc0c4bb89b..8d540491604846 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -1,4 +1,4 @@ -# Performance Measurement APIs +# Performance measurement APIs diff --git a/doc/api/policy.md b/doc/api/policy.md index e7ccbaa9db08e6..05918500fcac21 100644 --- a/doc/api/policy.md +++ b/doc/api/policy.md @@ -49,7 +49,7 @@ node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+D ## Features -### Error Behavior +### Error behavior When a policy check fails, Node.js by default will throw an error. It is possible to change the error behavior to one of a few possibilities @@ -73,7 +73,7 @@ available to change the behavior: } ``` -### Integrity Checks +### Integrity checks Policy files must use integrity checks with Subresource Integrity strings compatible with the browser @@ -115,7 +115,7 @@ body for the resource which can be useful for local development. It is not recommended in production since it would allow unexpected alteration of resources to be considered valid. -### Dependency Redirection +### Dependency redirection An application may need to ship patched versions of modules or to prevent modules from allowing all modules access to all other modules. Redirection @@ -164,7 +164,7 @@ module to load any specifier without redirection. This can be useful for local development and may have some valid usage in production, but should be used only with care after auditing a module to ensure its behavior is valid. -#### Example: Patched Dependency +#### Example: Patched dependency Redirected dependencies can provide attenuated or modified functionality as fits the application. For example, log data about timing of function durations by diff --git a/doc/api/process.md b/doc/api/process.md index 820b95f4d66bf5..eda3ac16f7a984 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -12,7 +12,7 @@ accessed using `require()`: const process = require('process'); ``` -## Process Events +## Process events The `process` object is an instance of [`EventEmitter`][]. @@ -122,7 +122,7 @@ not be the same as what is originally sent. If the `serialization` option was set to `advanced` used when spawning the process, the `message` argument can contain data that JSON is not able to represent. -See [Advanced Serialization for `child_process`][] for more details. +See [Advanced serialization for `child_process`][] for more details. ### Event: `'multipleResolves'` @@ -2533,7 +2533,7 @@ Will generate an object similar to: unicode: '11.0' } ``` -## Exit Codes +## Exit codes Node.js will normally exit with a `0` status code when no more async operations are pending. The following status codes are used in other @@ -2614,7 +2614,7 @@ cases: [`require.resolve()`]: modules.html#modules_require_resolve_request_options [`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal [`v8.setFlagsFromString()`]: v8.html#v8_v8_setflagsfromstring_flags -[Advanced Serialization for `child_process`]: child_process.html#child_process_advanced_serialization +[Advanced serialization for `child_process`]: child_process.html#child_process_advanced_serialization [Android building]: https://github.com/nodejs/node/blob/master/BUILDING.md#androidandroid-based-devices-eg-firefox-os [Child Process]: child_process.html [Cluster]: cluster.html diff --git a/doc/api/querystring.md b/doc/api/querystring.md index c7fafd23d955b8..0797e3ee220d53 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -1,4 +1,4 @@ -# Query String +# Query string diff --git a/doc/api/readline.md b/doc/api/readline.md index d70a49304ce64d..a737e4bd24d34c 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -536,7 +536,7 @@ the best compatibility if it defines an `output.columns` property and emits a `'resize'` event on the `output` if or when the columns ever change ([`process.stdout`][] does this automatically when it is a TTY). -### Use of the `completer` Function +### Use of the `completer` function The `completer` function takes the current line entered by the user as an argument, and returns an `Array` with 2 entries: @@ -661,7 +661,7 @@ rl.on('line', (line) => { }); ``` -## Example: Read File Stream Line-by-Line +## Example: Read file stream line-by-Line A common use case for `readline` is to consume an input file one line at a time. The easiest way to do so is leveraging the [`fs.ReadStream`][] API as diff --git a/doc/api/repl.md b/doc/api/repl.md index 42926ca0f1cf2d..4940001a4ebfd2 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -12,7 +12,7 @@ It can be accessed using: const repl = require('repl'); ``` -## Design and Features +## Design and features The `repl` module exports the [`repl.REPLServer`][] class. While running, instances of [`repl.REPLServer`][] will accept individual lines of user input, @@ -28,7 +28,7 @@ recovery, and customizable evaluation functions. Terminals that do not support ANSI styles and Emacs-style line editing automatically fall back to a limited feature set. -### Commands and Special Keys +### Commands and special keys The following special commands are supported by all REPL instances: @@ -72,14 +72,14 @@ The following key combinations in the REPL have these special effects: For key bindings related to the reverse-i-search, see [`reverse-i-search`][]. For all other key bindings, see [TTY keybindings][]. -### Default Evaluation +### Default evaluation By default, all instances of [`repl.REPLServer`][] use an evaluation function that evaluates JavaScript expressions and provides access to Node.js built-in modules. This default behavior can be overridden by passing in an alternative evaluation function when the [`repl.REPLServer`][] instance is created. -#### JavaScript Expressions +#### JavaScript expressions The default evaluator supports direct evaluation of JavaScript expressions: @@ -96,7 +96,7 @@ Unless otherwise scoped within blocks or functions, variables declared either implicitly or using the `const`, `let`, or `var` keywords are declared at the global scope. -#### Global and Local Scope +#### Global and local scope The default evaluator provides access to any variables that exist in the global scope. It is possible to expose a variable to the REPL explicitly by assigning @@ -132,7 +132,7 @@ Object.defineProperty(r.context, 'm', { }); ``` -#### Accessing Core Node.js Modules +#### Accessing core Node.js modules The default evaluator will automatically load Node.js core modules into the REPL environment when used. For instance, unless otherwise declared as a @@ -143,7 +143,7 @@ global or scoped variable, the input `fs` will be evaluated on-demand as > fs.createReadStream('./some/file'); ``` -#### Global Uncaught Exceptions +#### Global uncaught exceptions @@ -577,7 +577,7 @@ NODE_OPTIONS="--report-uncaught-exception \ Specific API documentation can be found under [`process API documentation`][] section. -## Interaction with Workers +## Interaction with workers @@ -120,8 +120,8 @@ that implements an HTTP server: const http = require('http'); const server = http.createServer((req, res) => { - // `req` is an http.IncomingMessage, which is a Readable Stream. - // `res` is an http.ServerResponse, which is a Writable Stream. + // `req` is an http.IncomingMessage, which is a readable stream. + // `res` is an http.ServerResponse, which is a writable stream. let body = ''; // Get the data as utf8 strings. @@ -176,9 +176,9 @@ are not required to implement the stream interfaces directly and will generally have no reason to call `require('stream')`. Developers wishing to implement new types of streams should refer to the -section [API for Stream Implementers][]. +section [API for stream implementers][]. -### Writable Streams +### Writable streams Writable streams are an abstraction for a *destination* to which data is written. @@ -649,7 +649,7 @@ write('hello', () => { A `Writable` stream in object mode will always ignore the `encoding` argument. -### Readable Streams +### Readable streams Readable streams are an abstraction for a *source* from which data is consumed. @@ -668,7 +668,7 @@ Examples of `Readable` streams include: All [`Readable`][] streams implement the interface defined by the `stream.Readable` class. -#### Two Reading Modes +#### Two reading modes `Readable` streams effectively operate in one of two modes: flowing and paused. These modes are separate from [object mode][object-mode]. @@ -719,7 +719,7 @@ stop flowing, and the data to be consumed via removed, then the stream will start flowing again if there is a [`'data'`][] event handler. -#### Three States +#### Three states The "two modes" of operation for a `Readable` stream are a simplified abstraction for the more complicated internal state management that is happening @@ -762,7 +762,7 @@ pass.resume(); // Must be called to make stream emit 'data'. While `readable.readableFlowing` is `false`, data may be accumulating within the stream's internal buffer. -#### Choose One API Style +#### Choose one API style The `Readable` stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data. In general, developers should choose @@ -1184,7 +1184,7 @@ added: v9.4.0 * {boolean} This property reflects the current state of a `Readable` stream as described -in the [Stream Three States][] section. +in the [Three states][] section. ##### `readable.readableHighWaterMark` @@ -1777,7 +1777,7 @@ on the type of stream being created, as detailed in the chart below: The implementation code for a stream should *never* call the "public" methods of a stream that are intended for use by consumers (as described in the -[API for Stream Consumers][] section). Doing so may lead to adverse side effects +[API for stream consumers][] section). Doing so may lead to adverse side effects in application code consuming the stream. Avoid overriding public methods such as `write()`, `end()`, `cork()`, @@ -1787,7 +1787,7 @@ Doing so can break current and future stream invariants leading to behavior and/or compatibility issues with other streams, stream utilities, and user expectations. -### Simplified Construction +### Simplified construction @@ -1807,7 +1807,7 @@ const myWritable = new Writable({ }); ``` -### Implementing a Writable Stream +### Implementing a writable stream The `stream.Writable` class is extended to implement a [`Writable`][] stream. @@ -1891,7 +1891,7 @@ function MyWritable(options) { util.inherits(MyWritable, Writable); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Writable } = require('stream'); @@ -2008,7 +2008,7 @@ This optional function will be called before the stream closes, delaying the `'finish'` event until `callback` is called. This is useful to close resources or write buffered data before a stream ends. -#### Errors While Writing +#### Errors while writing Errors occurring during the processing of the [`writable._write()`][], [`writable._writev()`][] and [`writable._final()`][] methods must be propagated @@ -2033,7 +2033,7 @@ const myWritable = new Writable({ }); ``` -#### An Example Writable Stream +#### An example writable stream The following illustrates a rather simplistic (and somewhat pointless) custom `Writable` stream implementation. While this specific `Writable` stream instance @@ -2054,7 +2054,7 @@ class MyWritable extends Writable { } ``` -#### Decoding buffers in a Writable Stream +#### Decoding buffers in a writable stream Decoding buffers is a common task, for instance, when using transformers whose input is a string. This is not a trivial process when using multi-byte @@ -2094,7 +2094,7 @@ w.end(euro[1]); console.log(w.data); // currency: € ``` -### Implementing a Readable Stream +### Implementing a readable stream The `stream.Readable` class is extended to implement a [`Readable`][] stream. @@ -2160,7 +2160,7 @@ function MyReadable(options) { util.inherits(MyReadable, Readable); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Readable } = require('stream'); @@ -2293,7 +2293,7 @@ For streams not operating in object mode, if the `chunk` parameter of `readable.push()` is `undefined`, it will be treated as empty string or buffer. See [`readable.push('')`][] for more information. -#### Errors While Reading +#### Errors while reading Errors occurring during processing of the [`readable._read()`][] must be propagated through the [`readable.destroy(err)`][readable-_destroy] method. @@ -2315,7 +2315,7 @@ const myReadable = new Readable({ }); ``` -#### An Example Counting Stream +#### An example counting stream @@ -2345,7 +2345,7 @@ class Counter extends Readable { } ``` -### Implementing a Duplex Stream +### Implementing a duplex stream A [`Duplex`][] stream is one that implements both [`Readable`][] and [`Writable`][], such as a TCP socket connection. @@ -2412,7 +2412,7 @@ function MyDuplex(options) { util.inherits(MyDuplex, Duplex); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Duplex } = require('stream'); @@ -2427,7 +2427,7 @@ const myDuplex = new Duplex({ }); ``` -#### An Example Duplex Stream +#### An example duplex stream The following illustrates a simple example of a `Duplex` stream that wraps a hypothetical lower-level source object to which data can be written, and @@ -2467,7 +2467,7 @@ The most important aspect of a `Duplex` stream is that the `Readable` and `Writable` sides operate independently of one another despite co-existing within a single object instance. -#### Object Mode Duplex Streams +#### Object mode duplex streams For `Duplex` streams, `objectMode` can be set exclusively for either the `Readable` or `Writable` side using the `readableObjectMode` and @@ -2508,7 +2508,7 @@ myTransform.write(100); // Prints: 64 ``` -### Implementing a Transform Stream +### Implementing a transform stream A [`Transform`][] stream is a [`Duplex`][] stream where the output is computed in some way from the input. Examples include [zlib][] streams or [crypto][] @@ -2567,7 +2567,7 @@ function MyTransform(options) { util.inherits(MyTransform, Transform); ``` -Or, using the Simplified Constructor approach: +Or, using the simplified constructor approach: ```js const { Transform } = require('stream'); @@ -2682,11 +2682,11 @@ stream that simply passes the input bytes across to the output. Its purpose is primarily for examples and testing, but there are some use cases where `stream.PassThrough` is useful as a building block for novel sorts of streams. -## Additional Notes +## Additional notes -### Streams Compatibility with Async Generators and Async Iterators +### Streams compatibility with async generators and async iterators With the support of async generators and iterators in JavaScript, async generators are effectively a first-class language-level stream construct at @@ -2695,7 +2695,7 @@ this point. Some common interop cases of using Node.js streams with async generators and async iterators are provided below. -#### Consuming Readable Streams with Async Iterators +#### Consuming readable streams with async iterators ```js (async function() { @@ -2708,9 +2708,9 @@ and async iterators are provided below. Async iterators register a permanent error handler on the stream to prevent any unhandled post-destroy errors. -#### Creating Readable Streams with Async Generators +#### Creating readable streams with async generators -We can construct a Node.js Readable Stream from an asynchronous generator +We can construct a Node.js readable stream from an asynchronous generator using the `Readable.from()` utility method: ```js @@ -2729,7 +2729,7 @@ readable.on('data', (chunk) => { }); ``` -#### Piping to Writable Streams from Async Iterators +#### Piping to writable streams from async iterators When writing to a writable stream from an async iterator, ensure correct handling of backpressure and errors. [`stream.pipeline()`][] abstracts away @@ -2762,7 +2762,7 @@ pipelinePromise(iterator, writable) -### Compatibility with Older Node.js Versions +### Compatibility with older Node.js versions @@ -2903,8 +2903,8 @@ contain multi-byte characters. [`writable.uncork()`]: #stream_writable_uncork [`writable.writableFinished`]: #stream_writable_writablefinished [`zlib.createDeflate()`]: zlib.html#zlib_zlib_createdeflate_options -[API for Stream Consumers]: #stream_api_for_stream_consumers -[API for Stream Implementers]: #stream_api_for_stream_implementers +[API for stream consumers]: #stream_api_for_stream_consumers +[API for stream implementers]: #stream_api_for_stream_implementers [Compatibility]: #stream_compatibility_with_older_node_js_versions [HTTP requests, on the client]: http.html#http_class_http_clientrequest [HTTP responses, on the server]: http.html#http_class_http_serverresponse @@ -2932,7 +2932,7 @@ contain multi-byte characters. [stream-resume]: #stream_readable_resume [stream-uncork]: #stream_writable_uncork [stream-write]: #stream_writable_write_chunk_encoding_callback -[Stream Three States]: #stream_three_states +[Three states]: #stream_three_states [writable-_destroy]: #stream_writable_destroy_err_callback [writable-destroy]: #stream_writable_destroy_error [writable-new]: #stream_new_stream_writable_options diff --git a/doc/api/string_decoder.md b/doc/api/string_decoder.md index 54fcc876c9a9e9..5cd6121d50ddb9 100644 --- a/doc/api/string_decoder.md +++ b/doc/api/string_decoder.md @@ -1,4 +1,4 @@ -# String Decoder +# String decoder diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md index c296ffb0fa43c7..8ae933a499a16c 100644 --- a/doc/api/synopsis.md +++ b/doc/api/synopsis.md @@ -1,4 +1,4 @@ -# Usage & Example +# Usage and example ## Usage diff --git a/doc/api/timers.md b/doc/api/timers.md index a312022791f54b..8b080b16ffb70e 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -123,7 +123,7 @@ Calling `timeout.unref()` creates an internal timer that will wake the Node.js event loop. Creating too many of these can adversely impact performance of the Node.js application. -## Scheduling Timers +## Scheduling timers A timer in Node.js is an internal construct that calls a given function after a certain period of time. When a timer's function is called varies depending on @@ -226,7 +226,7 @@ setTimeoutPromise(40, 'foobar').then((value) => { }); ``` -## Cancelling Timers +## Cancelling timers The [`setImmediate()`][], [`setInterval()`][], and [`setTimeout()`][] methods each return objects that represent the scheduled timers. These can be used to diff --git a/doc/api/tls.md b/doc/api/tls.md index 4b49260e2663df..71c127ca6cc346 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -12,7 +12,7 @@ The module can be accessed using: const tls = require('tls'); ``` -## TLS/SSL Concepts +## TLS/SSL concepts The TLS/SSL is a public/private key infrastructure (PKI). For most common cases, each client and server must have a *private key*. @@ -64,11 +64,11 @@ Where: * `certfile`: is a concatenation of all Certificate Authority (CA) certs into a single file, e.g. `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` -### Perfect Forward Secrecy +### Perfect forward secrecy -The term "[Forward Secrecy][]" or "Perfect Forward Secrecy" describes a feature +The term _[forward secrecy][]_ or _perfect forward secrecy_ describes a feature of key-agreement (i.e., key-exchange) methods. That is, the server and client keys are used to negotiate new temporary keys that are used specifically and only for the current communication session. Practically, this means that even @@ -76,11 +76,11 @@ if the server's private key is compromised, communication can only be decrypted by eavesdroppers if the attacker manages to obtain the key-pair specifically generated for the session. -Perfect Forward Secrecy is achieved by randomly generating a key pair for +Perfect forward secrecy is achieved by randomly generating a key pair for key-agreement on every TLS/SSL handshake (in contrast to using the same key for all sessions). Methods implementing this technique are called "ephemeral". -Currently two methods are commonly used to achieve Perfect Forward Secrecy (note +Currently two methods are commonly used to achieve perfect forward secrecy (note the character "E" appended to the traditional abbreviations): * [DHE][]: An ephemeral version of the Diffie Hellman key-agreement protocol. @@ -90,7 +90,7 @@ the character "E" appended to the traditional abbreviations): Ephemeral methods may have some performance drawbacks, because key generation is expensive. -To use Perfect Forward Secrecy using `DHE` with the `tls` module, it is required +To use perfect forward secrecy using `DHE` with the `tls` module, it is required to generate Diffie-Hellman parameters and specify them with the `dhparam` option to [`tls.createSecureContext()`][]. The following illustrates the use of the OpenSSL command-line interface to generate such parameters: @@ -99,12 +99,12 @@ the OpenSSL command-line interface to generate such parameters: openssl dhparam -outform PEM -out dhparam.pem 2048 ``` -If using Perfect Forward Secrecy using `ECDHE`, Diffie-Hellman parameters are +If using perfect forward secrecy using `ECDHE`, Diffie-Hellman parameters are not required and a default ECDHE curve will be used. The `ecdhCurve` property can be used when creating a TLS Server to specify the list of names of supported curves to use, see [`tls.createServer()`][] for more info. -Perfect Forward Secrecy was optional up to TLSv1.2, but it is not optional for +Perfect forward secrecy was optional up to TLSv1.2, but it is not optional for TLSv1.3, because all TLSv1.3 cipher suites use ECDHE. ### ALPN and SNI @@ -175,13 +175,15 @@ understanding of the implications and risks. TLSv1.3 does not support renegotiation. -### Session Resumption +### Session resumption Establishing a TLS session can be relatively slow. The process can be sped up by saving and later reusing the session state. There are several mechanisms to do so, discussed here from oldest to newest (and preferred). -***Session Identifiers*** Servers generate a unique ID for new connections and +#### Session identifiers + +Servers generate a unique ID for new connections and send it to the client. Clients and servers save the session state. When reconnecting, clients send the ID of their saved session state and if the server also has the state for that ID, it can agree to use it. Otherwise, the server @@ -200,7 +202,9 @@ reuse sessions. To reuse sessions across load balancers or cluster workers, servers must use a shared session cache (such as Redis) in their session handlers. -***Session Tickets*** The servers encrypt the entire session state and send it +#### Session tickets + +The servers encrypt the entire session state and send it to the client as a "ticket". When reconnecting, the state is sent to the server in the initial connection. This mechanism avoids the need for server-side session cache. If the server doesn't use the ticket, for any reason (failure @@ -267,7 +271,7 @@ Subsequent connections should say "Reused", for example: Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256 ``` -## Modifying the Default TLS Cipher suite +## Modifying the default TLS cipher suite Node.js is built with a default suite of enabled and disabled TLS ciphers. This default cipher list can be configured when building Node.js to allow @@ -340,8 +344,8 @@ of an application. The `--tls-cipher-list` switch and `ciphers` option should by used only if absolutely necessary. The default cipher suite prefers GCM ciphers for [Chrome's 'modern -cryptography' setting][] and also prefers ECDHE and DHE ciphers for Perfect -Forward Secrecy, while offering *some* backward compatibility. +cryptography' setting][] and also prefers ECDHE and DHE ciphers for perfect +forward secrecy, while offering *some* backward compatibility. 128 bit AES is preferred over 192 and 256 bit AES in light of [specific attacks affecting larger AES key sizes][]. @@ -904,7 +908,7 @@ added: v5.0.0 * Returns: {Object} Returns an object representing the type, name, and size of parameter of -an ephemeral key exchange in [Perfect Forward Secrecy][] on a client +an ephemeral key exchange in [perfect forward secrecy][] on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; `null` is returned if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The @@ -946,7 +950,7 @@ If the full certificate chain was requested, each certificate will include an `issuerCertificate` property containing an object representing its issuer's certificate. -#### Certificate Object +#### Certificate object > Stability: 1 - Experimental -Trace Event provides a mechanism to centralize tracing information generated by -V8, Node.js core, and userspace code. +The `trace_events` module provides a mechanism to centralize tracing information +generated by V8, Node.js core, and userspace code. Tracing can be enabled with the `--trace-event-categories` command-line flag or by using the `trace_events` module. The `--trace-event-categories` flag diff --git a/doc/api/url.md b/doc/api/url.md index dfe312bef805c8..fbe8aa397918ba 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -11,7 +11,7 @@ accessed using: const url = require('url'); ``` -## URL Strings and URL Objects +## URL strings and URL objects A URL string is a structured string containing multiple meaningful components. When parsed, a URL object is returned containing properties for each of these @@ -406,7 +406,7 @@ console.log(myURL.href); Invalid URL protocol values assigned to the `protocol` property are ignored. -##### Special Schemes +##### Special schemes The [WHATWG URL Standard][] considers a handful of URL protocol schemes to be _special_ in terms of how they are parsed and serialized. When a URL is @@ -1276,7 +1276,7 @@ url.resolve('http://example.com/one', '/two'); // 'http://example.com/two' ``` -## Percent-Encoding in URLs +## Percent-encoding in URLs URLs are permitted to only contain a certain range of characters. Any character falling outside of that range must be encoded. How such characters are encoded, diff --git a/doc/api/util.md b/doc/api/util.md index bc57d8ee06130f..269210c1a38f07 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -756,7 +756,7 @@ ignored, if not supported. * `bgCyanBright` * `bgWhiteBright` -### Custom inspection functions on Objects +### Custom inspection functions on objects @@ -1047,7 +1047,7 @@ while (buffer = getNextChunkSomehow()) { string += decoder.decode(); // end-of-stream ``` -### WHATWG Supported Encodings +### WHATWG supported encodings Per the [WHATWG Encoding Standard][], the encodings supported by the `TextDecoder` API are outlined in the tables below. For each encoding, @@ -1056,7 +1056,7 @@ one or more aliases may be used. Different Node.js build configurations support different sets of encodings. (see [Internationalization][]) -#### Encodings Supported by Default (With Full ICU Data) +#### Encodings supported by default (with full ICU data) | Encoding | Aliases | | ----------------- | -------------------------------- | @@ -1095,7 +1095,7 @@ Different Node.js build configurations support different sets of encodings. | `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` | | `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` | -#### Encodings Supported when Node.js is built with the `small-icu` option +#### Encodings supported when Node.js is built with the `small-icu` option | Encoding | Aliases | | ----------- | --------------------------------- | @@ -1103,7 +1103,7 @@ Different Node.js build configurations support different sets of encodings. | `'utf-16le'` | `'utf-16'` | | `'utf-16be'` | | -#### Encodings Supported when ICU is disabled +#### Encodings supported when ICU is disabled | Encoding | Aliases | | ----------- | --------------------------------- | @@ -2427,7 +2427,7 @@ util.log('Timestamped message.'); [`util.types.isNativeError()`]: #util_util_types_isnativeerror_value [`util.types.isSharedArrayBuffer()`]: #util_util_types_issharedarraybuffer_value [Common System Errors]: errors.html#errors_common_system_errors -[Custom inspection functions on Objects]: #util_custom_inspection_functions_on_objects +[Custom inspection functions on objects]: #util_custom_inspection_functions_on_objects [Custom promisified functions]: #util_custom_promisified_functions [Customizing `util.inspect` colors]: #util_customizing_util_inspect_colors [Internationalization]: intl.html diff --git a/doc/api/v8.md b/doc/api/v8.md index ec6a6ea9a0508f..531612330f061b 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -231,7 +231,7 @@ DevTools. The JSON schema is undocumented and specific to the V8 engine, and may change from one version of V8 to the next. A heap snapshot is specific to a single V8 isolate. When using -[Worker Threads][], a heap snapshot generated from the main thread will +[worker threads][], a heap snapshot generated from the main thread will not contain any information about the workers, and vice versa. ```js @@ -519,4 +519,4 @@ A subclass of [`Deserializer`][] corresponding to the format written by [`vm.Script`]: vm.html#vm_new_vm_script_code_options [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [V8]: https://developers.google.com/v8/ -[Worker Threads]: worker_threads.html +[worker threads]: worker_threads.html diff --git a/doc/api/vm.md b/doc/api/vm.md index 7d16b48b04afc2..7ef5ff622795ca 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -1,4 +1,4 @@ -# VM (Executing JavaScript) +# VM (executing JavaScript) @@ -1168,7 +1168,7 @@ local scope, so the value `localVar` is changed. In this way `vm.runInThisContext()` is much like an [indirect `eval()` call][], e.g. `(0,eval)('code')`. -## Example: Running an HTTP Server within a VM +## Example: Running an HTTP server within a VM When using either [`script.runInThisContext()`][] or [`vm.runInThisContext()`][], the code is executed within the current V8 global @@ -1218,7 +1218,7 @@ within which it can operate. The process of creating the V8 Context and associating it with the `contextObject` is what this document refers to as "contextifying" the object. -## Timeout limitations when using `process.nextTick()`, Promises, and `queueMicrotask()` +## Timeout limitations when using `process.nextTick()`, promises, and `queueMicrotask()` Because of the internal mechanics of how the `process.nextTick()` queue and the microtask queue that underlies Promises are implemented within V8 and diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 33d9aa0eb413ed..45b9a5f0fd2323 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -1,4 +1,4 @@ -# Worker Threads +# Worker threads diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 439b9d85e05c57..d50792664840c4 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -93,7 +93,7 @@ do_unzip(buffer) }); ``` -## Threadpool Usage and Performance Considerations +## Threadpool usage and performance considerations All `zlib` APIs, except those that are explicitly synchronous, use the Node.js internal threadpool. This can lead to surprising effects and performance @@ -133,7 +133,7 @@ message. The examples given below are drastically simplified to show the basic concept. Using `zlib` encoding can be expensive, and the results ought to be cached. -See [Memory Usage Tuning][] for more information on the speed/memory/compression +See [Memory usage tuning][] for more information on the speed/memory/compression tradeoffs involved in `zlib` usage. ```js @@ -252,7 +252,7 @@ possible to determine whether the input ended prematurely or lacks the integrity checks, making it necessary to manually check that the decompressed result is valid. -## Memory Usage Tuning +## Memory usage tuning @@ -837,7 +837,7 @@ added: v0.5.8 Creates and returns a new [`Unzip`][] object. -## Convenience Methods +## Convenience methods @@ -1186,7 +1186,7 @@ Decompress a chunk of data with [`Unzip`][]. [`stream.Transform`]: stream.html#stream_class_stream_transform [`zlib.bytesWritten`]: #zlib_zlib_byteswritten [Brotli parameters]: #zlib_brotli_constants -[Memory Usage Tuning]: #zlib_memory_usage_tuning +[Memory usage tuning]: #zlib_memory_usage_tuning [RFC 7932]: https://www.rfc-editor.org/rfc/rfc7932.txt [Streams API]: stream.md [convenience methods]: #zlib_convenience_methods