v10.16.0

Author: h7lin

api-docs/0df8a572b7dbefa21c101d8d8822dcd47b53aac4ce7abdde0ef9b9eadabfd086.md

@@ -0,0 +1,8 @@
+<!-- YAML
+added: v11.0.0
+-->
+
+* 返回: {boolean}
+
+如果为 true，则 `Immediate` 对象将会使 Node.js 事件循环保持活动状态。
+

api-docs/2774854b6d9e401c9184046b475a5a4b51028ad6b0abad22ab17b02b52700f06.md

@@ -0,0 +1,33 @@
+<!-- YAML
+added: v11.4.0
+changes:
+  - version: v11.14.0
+    pr-url: https://github.com/nodejs/node/pull/26989
+    description: Symbol.asyncIterator support is no longer experimental.
+-->
+
+* 返回: {AsyncIterator}
+
+创建一个 `AsyncIterator` 对象，该对象以字符串形式迭代输入流中的每一行。 
+这个方法允许 `readline.Interface` 对象使用 `for await...of` 循环的异步迭代。
+
+输入流中的错误不会被转发。
+
+如果循环以 `break`，`throw` 或 `return` 终止，则 [`rl.close()`] 将会被调用。 
+换句话说，对 `readline.Interface` 的迭代将会始终完全消费输入流。
+
+性能比不上传统的 `'line'` 事件的 API。 
+对于性能敏感的应用程序，请使用 `'line'`。
+
+```js
+async function processLineByLine() {
+  const rl = readline.createInterface({
+    // ...
+  });
+
+  for await (const line of rl) {
+    // readline 输入中的每一行将会在此处作为 `line`。
+  }
+}
+```
+

api-docs/2dc8208af99f28f9e98eecb5030a3949d8e4a1200271b7b72270d33237cd1b8e.md

@@ -0,0 +1,15 @@
+<!-- YAML
+added: v11.10.0
+-->
+
+* `historyPath` {string} 历史文件的路径。
+* `callback` {Function} 当历史记录写入已准备好或出错时调用。
+  * `err` {Error}
+  * `repl` {repl.REPLServer}
+
+Initializes a history log file for the REPL instance. When executing the
+Node.js binary and using the command line REPL, a history file is initialized
+by default. However, this is not the case when creating a REPL
+programmatically. Use this method to initialize a history log file when working
+with REPL instances programmatically.
+

api-docs/396f688c9c4681bf3c7d192213023be0e4bd0f7b99763c1a5e0b208e0e437ec4.md

@@ -14,6 +14,7 @@ Node.js 不保证回调被触发的确切时间，也不保证它们的顺序。
 回调会在尽可能接近指定的时间调用。
 
 当 `delay` 大于 `2147483647` 或小于 `1` 时，`delay` 将设置为 `1`。
+非整数的延迟会被截断为整数。
 
 如果 `callback` 不是函数，则抛出 [`TypeError`]。
 

api-docs/47553fafd6680b7a6ec34486ef34780126785a9032df717951231922086107e8.md

@@ -0,0 +1,45 @@
+<!-- YAML
+added: v11.13.0
+-->
+
+* `filename` {string} 要保存 V8 堆快照的文件路径。 
+  如果未指定，则将会生成具有 `'Heap-${yyyymmdd}-${hhmmss}-${pid}-${thread_id}.heapsnapshot'` 模式的文件名，
+  其中 `{pid}` 将会是 Node.js 进程的 PID，`{thread_id}` 将会为 `0`（当从主 Node.js 线程调用 `writeHeapSnapshot()` 时）或工作线程的 id。
+* 返回: {string} 保存快照的文件名。
+
+生成当前 V8 堆的快照并将其写入 JSON 文件。 
+此文件旨在与 Chrome DevTools 等工具一起使用。 
+JSON 模式未记录且特定于V8引擎，并且可能从 V8 的一个版本更改为下一个版本。
+
+堆快照特定于单个 V8 隔离。 
+使用[工作线程][Worker Threads]时，从主线程生成的堆快照将不包含有关工作线程的任何信息，反之亦然。
+
+```js
+const { writeHeapSnapshot } = require('v8');
+const {
+  Worker,
+  isMainThread,
+  parentPort
+} = require('worker_threads');
+
+if (isMainThread) {
+  const worker = new Worker(__filename);
+
+  worker.once('message', (filename) => {
+    console.log(`工作线程的堆转储: ${filename}`);
+    // 获取主线程的堆转储。
+    console.log(`主线程的堆转储: ${writeHeapSnapshot()}`);
+  });
+
+  // 通知工作线程创建一个堆转储。
+  worker.postMessage('heapdump');
+} else {
+  parentPort.once('message', (message) => {
+    if (message === 'heapdump') {
+      // 为工作线程生成一个堆转储，并返回文件名到父线程。
+      parentPort.postMessage(writeHeapSnapshot());
+    }
+  });
+}
+```
+

api-docs/57e50967944bd6b6c66ba10363adb75ab0aaa93ae223c0fd90866cb05929188c.md

@@ -1,6 +1,20 @@
 
 默认情况下，在把输出写入到提供的可写流（默认为 `process.stdout`）之前，[`repl.REPLServer`] 实例会使用 [`util.inspect()`] 方法对输出进行格式化。
-使用 `util.inspect()` 方法时，`useColors` 选项可被指定是否在建立默认输出器时使用 ANSI 风格的代码给输出上色。
+`showProxy` 检查选项会默认设置为 true，`colors` 选项会设置为 true，具体取决于 REPL 的 `useColors` 选项。
+
+可以在构造时指定 `useColors` 布尔值选项，以指示默认的编写器使用 ANSI 样式代码来着色来自 `util.inspect()` 方法的输出。
+
+如果 REPL 作为独立程序运行，则还可以使用 `inspect.replDefaults` 属性从 REPL 内部更改 REPL 的检查默认值[`util.inspect()`]，该属性是 [`util.inspect()`] 中的 `defaultOptions` 的镜像。
+
+```console
+> util.inspect.replDefaults.compact = false;
+false
+> [1]
+[
+  1
+]
+>
+```
 
 在构造时，通过在 `writer` 选项传入一个新的函数，可以完全地自定义一个 [`repl.REPLServer`] 实例的输出。
 例子，把输入的任何文本转换为大写：

api-docs/65ee1bfdc50c4e7ff3c3b60c6b02fc0887ebccedd5862de7d300b8ba39b9aaff.md

@@ -1,17 +1,70 @@
 
-`readline` 的一个常见用例是每次一行地从文件系统[可读流][Readable]消费输入：
+`readline` 的一个常见用例是每次一行地输入文件。 
+最简单的方法是利用 [`fs.ReadStream`] API 以及 `for await...of` 循环：
 
 ```js
+const fs = require('fs');
 const readline = require('readline');
+
+async function processLineByLine() {
+  const fileStream = fs.createReadStream('input.txt');
+
+  const rl = readline.createInterface({
+    input: fileStream,
+    crlfDelay: Infinity
+  });
+  // 注意：我们使用 crlfDelay 选项将 input.txt 中的所有 CR LF 实例（'\r\n'）识别为单个换行符。
+
+  for await (const line of rl) {
+    // input.txt 中的每一行在这里将会被连续地用作 `line`。
+    console.log(`Line from file: ${line}`);
+  }
+}
+
+processLineByLine();
+```
+
+或者，可以使用 [`'line'`] 事件：
+
+```js
 const fs = require('fs');
+const readline = require('readline');
 
 const rl = readline.createInterface({
   input: fs.createReadStream('sample.txt'),
   crlfDelay: Infinity
 });
 
 rl.on('line', (line) => {
-  console.log(`文件的每行内容：${line}`);
+  console.log(`文件中的每一行: ${line}`);
 });
 ```
 
+目前，`for await...of` 循环可能会慢一点。 
+如果 `async` / `await` 流和速度都是必不可少的，可以应用混合方法：
+
+```js
+const { once } = require('events');
+const { createReadStream } = require('fs');
+const { createInterface } = require('readline');
+
+(async function processLineByLine() {
+  try {
+    const rl = createInterface({
+      input: createReadStream('big-file.txt'),
+      crlfDelay: Infinity
+    });
+
+    rl.on('line', (line) => {
+      // 处理行。
+    });
+
+    await once(rl, 'close');
+
+    console.log('文件已处理');
+  } catch (err) {
+    console.error(err);
+  }
+})();
+```
+

api-docs/67f65398e8ea16305f43cee7f26bf7e1d1bdfc82174490bee78828b874858819.md

@@ -2,7 +2,7 @@
 added: v0.9.1
 -->
 
-* `callback` {Function} 在当前回合的 [Node.js 事件循环][the Node.js Event Loop]结束时调用的函数。
+* `callback` {Function} 在当前回合的 [Node.js 事件循环][Event Loop]结束时调用的函数。
 * `...args` {any} 当调用 `callback` 时传入的可选参数。
 * 返回: {Immediate} 用于 [`clearImmediate()`]。
 

api-docs/7b97aa3880f3a720e2113cc95634975b8b0e936a79e75b9ab7b7d239f5c0d847.md

@@ -32,6 +32,8 @@ changes:
     **默认值:** `100`。
   * `removeHistoryDuplicates` {boolean} 如果为 `true`, 则当添加到历史列表的新输入行与旧的输入行重复时，将从列表中删除旧行。
     **默认值:** `false`。
+  * `escapeCodeTimeout` {number} `readline` 将会等待一个字符的持续时间（当以毫秒为单位读取模糊键序列时，可以使用输入读取到目前为止形成完整的键序列，并且可以采取额外的输入来完成更长的键序列）。
+     **默认值:** `500`。
 
 `readline.createInterface()` 方法创建一个新的 `readline.Interface` 实例。
 

api-docs/9726adbd6932c36947e96c84aaec2a185488cdf2928139f67f38233051d18c74.md

@@ -25,7 +25,7 @@ changes:
 `ca`、`cert`、`ciphers`、`clientCertEngine`、`crl`、`dhparam`、`ecdhCurve`、`honorCipherOrder`、`key`、`passphrase`、`pfx`、`rejectUnauthorized`、`secureOptions`、`secureProtocol`、`servername`、`sessionIdContext`。
 
 `options` 可以是对象、字符串、或 [`URL`] 对象。
-如果 `options` 是一个字符串, 则自动使用 [`url.parse()`] 解析它。
+如果 `options` 是一个字符串, 则自动使用 [`new URL()`] 解析它。
 如果它是一个 [`URL`] 对象，则将自动转换为普通的 `options` 对象。
 
 ```js

api-docs/9b96cb5adb765942f292953779b86bec06d2946fb3be72d357bbe50a18a6a37c.md

@@ -0,0 +1,15 @@
+<!-- YAML
+added: v11.13.0
+-->
+
+* 返回: {stream.Readable} 包含 V8 堆快照的可读流。
+
+生成当前 V8 堆的快照，并返回可读流，该可读流可用于读取 JSON 序列化表示。 
+此 JSON 流格式旨在与 Chrome DevTools 等工具一起使用。 
+JSON 模式未记录且特定于V8引擎，并且可能从 V8 的一个版本更改为下一个版本。
+
+```js
+const stream = v8.getHeapSnapshot();
+stream.pipe(process.stdout);
+```
+

api-docs/a5abb5e3a18ceed4cb896c64178e5ab325218e47b7802b09e1578af46b34919d.md

@@ -0,0 +1,8 @@
+<!-- YAML
+added: v11.0.0
+-->
+
+* 返回: {boolean}
+
+如果为 true，则 `Timeout` 对象将会使 Node.js 事件循环保持活动状态。
+

api-docs/a905f5e97552b5740be72caebb9e8110451f980680e71d55e143bfca72d2f777.md

@@ -23,11 +23,19 @@ changes:
 * `malloced_memory` {number}
 * `peak_malloced_memory` {number}
 * `does_zap_garbage` {number}
+* `number_of_native_contexts` {number}
+* `number_of_detached_contexts` {number}
 
 `does_zap_garbage` 是一个 0/1 布尔值，表示是否启用了 `--zap_code_space` 选项。 
 这使得 V8 用位模式覆盖堆垃圾。 
 RSS 占用空间（常驻内存集）会变得越来越大，因为它不断触及所有堆页面，这使得它们不太可能被操作系统交换出。
 
+`number_of_native_contexts` native_context 的值是当前活动的顶层上下文的数量。 
+随着时间的推移，此数字的增加表示内存泄漏。
+
+`number_of_detached_contexts` detached_context 的值是已分离但尚未回收垃圾的上下文数。
+该数字不为零表示潜在的内存泄漏。
+
 <!-- eslint-skip -->
 ```js
 {
@@ -39,7 +47,9 @@ RSS 占用空间（常驻内存集）会变得越来越大，因为它不断触
   heap_size_limit: 1535115264,
   malloced_memory: 16384,
   peak_malloced_memory: 1127496,
-  does_zap_garbage: 0
+  does_zap_garbage: 0,
+  number_of_native_contexts: 1,
+  number_of_detached_contexts: 0
 }
 ```
 

api-docs/aaa7e5ca9d0bb0b0a8aeb9d4a03259bafc3643f880d17d33e8d2f45629e90056.md

@@ -1,5 +1,13 @@
 <!-- YAML
 added: v0.4.5
+changes:
+  - version: v2.5.0
+    pr-url: https://github.com/nodejs/node/pull/2228
+    description: parameter `maxCachedSessions` added to `options` for TLS
+                 sessions reuse.
+  - version: v5.3.0
+    pr-url: https://github.com/nodejs/node/pull/4252
+    description: support `0` `maxCachedSessions` to disable TLS session caching.
 -->
 
 HTTPS 的 [`Agent`] 对象，类似于 [`http.Agent`]。 

api-docs/ab404272c190fec3a6488ad03e947320397137d65c41b7e2714e9a818c271cea.md

@@ -6,6 +6,6 @@
 `timer` 模块暴露了一个全局的 API，用于预定在将来某个时间段调用的函数。 
 因为定时器函数是全局变量，所以不需要调用 `require('timers')` 来使用 API。
 
-Node.js 中的定时器函数实现了与 Web 浏览器提供的定时器 API 类似的 API，但是使用了不同的内部实现（基于 [Node.js 事件循环][the Node.js Event Loop]构建）。
+Node.js 中的定时器函数实现了与 Web 浏览器提供的定时器 API 类似的 API，但是使用了不同的内部实现（基于 Node.js [事件循环][Event Loop]构建）。
 
 

api-docs/b76f1af153dd1239bad0510a9f637718b878bee73122027ea8b65297b79ebfa0.md

@@ -0,0 +1,13 @@
+<!-- YAML
+changes:
+  - version: v12.5.0
+    pr-url: https://github.com/nodejs/node/pull/28209
+    description: do not automatically set servername if the target host was
+                 specified using an IP address.
+-->
+* `options` {Object} 在代理上设置的一组可配置的选项。可以具有与 [`http.Agent(options)`] 相同的字段，以及：
+  * `maxCachedSessions` {number} TLS 缓存会话的最大数量。使用 `0` 可禁用 TLS 会话缓存。**默认值:** `100`。
+  * `servername` {string} 要发送到服务器的[服务器名称指示的扩展名][sni wiki]的值。使用空字符串 `''` 可以禁用发送扩展名。**默认值：** 目标服务器的主机名，除非目标服务器被指定为使用 IP 地址，在这种情况下默认为 `''`（无扩展名）。
+
+    有关 TLS 会话复用的信息，请参阅[会话恢复][`Session Resumption`]。
+

api-docs/c046594d15762a90d81acfa7db68302f4709d068ba4319f6d08362412a3d3a28.md

@@ -10,6 +10,7 @@ added: v0.0.1
 预定每隔 `delay` 毫秒重复执行 `callback`。
 
 当 `delay` 大于 `2147483647` 或小于 `1` 时，`delay` 将设置为 `1`。
+非整数的延迟会被截断为整数。
 
 如果 `callback` 不是函数，则抛出 [`TypeError`]。
 

api-docs/d92fdb582d9f54f8d9cc49cb54d02a9242d683e49df3c57863bc5ef173bd7e70.md

@@ -1,8 +1,8 @@
 
-当创建一个新的 `repl.REPLServer` 时，可以提供一个自定义的解释函数。
+当创建一个新的 [`repl.REPLServer`] 时，可以提供一个自定义的解释函数。
 这可以用于实现完全定制化的 REPL 应用。
 
-例子，一个执行文本翻译的 REPL：
+以下是 REPL 的一个假设的示例，执行从一种语言到另一种语言的文本转换：
 
 ```js
 const repl = require('repl');

api-docs/dd5312afb24e99bef283b7385e484422cc73a22eb386be4d4fde152774a3dfe3.md

@@ -1,8 +1,36 @@
+<!-- YAML
+changes:
+  - version: v12.3.0
+    pr-url: https://github.com/nodejs/node/pull/27151
+    description: The `'uncaughtException'` event is from now on triggered if the
+                 repl is used as standalone program.
+-->
 
 REPL使用 [`domain`] 模块来捕获会话期间的所有未捕获异常。
 
 在REPL中使用 [`domain`] 模块有如下副作用：
 
-* 未捕获的异常不会产生 [`'uncaughtException'`] 事件。
+* 如果将 `repl` 用作独立程序，则未捕获的异常仅触发 [`'uncaughtException'`] 事件。 
+  如果 `repl` 包含在另一个应用程序的任何位置，则为此事件添加监听器将会抛出 [`ERR_INVALID_REPL_INPUT`] 异常。
 * 如果尝试使用 [`process.setUncaughtExceptionCaptureCallback()`] 将产生一个 [`ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE`] 错误。
 
+作为独立程序：
+
+```js
+process.on('uncaughtException', () => console.log('未捕获的异常'));
+
+throw new Error('foobar');
+// 打印：未捕获的异常
+```
+
+当在其他应用程序中使用时：
+
+```js
+process.on('uncaughtException', () => console.log('未捕获的异常'));
+// 抛出 TypeError [ERR_INVALID_REPL_INPUT]: Listeners for `uncaughtException` cannot be used in the REPL
+
+throw new Error('foobar');
+// 抛出:
+// Error: foobar
+```
+

api-docs/e545317c41c8a0b49c71fd696aa67c653c4cc4d95babc85dd2fd09020556ef94.md

@@ -8,7 +8,6 @@ added: v1.0.0
 虚拟机启动后更改设置可能会导致不可预测的行为，包括崩溃和数据丢失，或者它可能根本就什么都不做。
 
 可以通过运行 `node --v8-options` 来检测可用于 Node.js 版本的 V8 选项。 
-[这里][here]提供了一个非官方的、社区维护的选项及其效果列表。
 
 用法:
 

api-docs/e7058f3a5547a20227857a47536a317563dcd9f509345b8906c5e328630cf4a9.md

@@ -1,4 +1,6 @@
-
+<!-- YAML
+added: v11.3.0
+-->
 - {number} **默认值:** `40000`。
 
 请参阅 [`http.Server#headersTimeout`]。