v12.16.2

addons/c_addons.md

@@ -26,7 +26,7 @@
  - Node.js 包含了其他的静态链接库，如 OpenSSL。
    这些库位于 Node.js 源代码树中的 `deps/` 目录。
    只有 libuv、OpenSSL、V8 和 zlib 符号是被 Node.js 有目的地重新公开，并且可以被插件在不同程度上使用。
-   更多信息可查看[链接到 Node.js 自有的依赖项][Linking to Node.js' own dependencies]。
+   更多信息可查看[链接到 Node.js 自带的库][Linking to libraries included with Node.js]。
 
 以下所有示例均可供[下载][download]，并可用作学习插件的起点。
 

assert/assert.md

@@ -4,5 +4,4 @@
 > 稳定性: 2 - 稳定
 
 `assert` 模块提供了一组简单的断言测试，可用于测试不变量。
-该模块提供了建议的[严格模式][`strict` mode]和更宽松的遗留模式。
 

assert/assert_deepequal_actual_expected_message.md

@@ -26,18 +26,18 @@ changes:
 * `expected` {any}
 * `message` {string|Error}
 
-**Strict mode**
+**Strict assertion mode**
 
 An alias of [`assert.deepStrictEqual()`][].
 
-**Legacy mode**
+**Legacy assertion mode**
 
 > Stability: 0 - Deprecated: Use [`assert.deepStrictEqual()`][] instead.
 
 Tests for deep equality between the `actual` and `expected` parameters. Consider
 using [`assert.deepStrictEqual()`][] instead. [`assert.deepEqual()`][] can have
-potentially surprising results.
+surprising results.
 
-"Deep" equality means that the enumerable "own" properties of child objects
+_Deep equality_ means that the enumerable "own" properties of child objects
 are also recursively evaluated by the following rules.
 

assert/assert_equal_actual_expected_message.md

@@ -6,11 +6,11 @@ added: v0.1.21
 * `expected` {any}
 * `message` {string|Error}
 
-**Strict mode**
+**Strict assertion mode**
 
 An alias of [`assert.strictEqual()`][].
 
-**Legacy mode**
+**Legacy assertion mode**
 
 > Stability: 0 - Deprecated: Use [`assert.strictEqual()`][] instead.
 

assert/assert_notdeepequal_actual_expected_message.md

@@ -22,11 +22,11 @@ changes:
 * `expected` {any}
 * `message` {string|Error}
 
-**Strict mode**
+**Strict assertion mode**
 
 An alias of [`assert.notDeepStrictEqual()`][].
 
-**Legacy mode**
+**Legacy assertion mode**
 
 > Stability: 0 - Deprecated: Use [`assert.notDeepStrictEqual()`][] instead.
 

assert/assert_notequal_actual_expected_message.md

@@ -6,11 +6,11 @@ added: v0.1.21
 * `expected` {any}
 * `message` {string|Error}
 
-**Strict mode**
+**Strict assertion mode**
 
 An alias of [`assert.notStrictEqual()`][].
 
-**Legacy mode**
+**Legacy assertion mode**
 
 > Stability: 0 - Deprecated: Use [`assert.notStrictEqual()`][] instead.
 

assert/assert_rejects_asyncfn_error_message.md

@@ -32,6 +32,21 @@ added: v10.0.0
 })();
 ```
 
+```js
+(async () => {
+  await assert.rejects(
+    async () => {
+      throw new TypeError('错误值');
+    },
+    (err) => {
+      assert.strictEqual(err.name, 'TypeError');
+      assert.strictEqual(err.message, '错误值');
+      return true;
+    }
+  );
+})();
+```
+
 ```js
 assert.rejects(
   Promise.reject(new Error('错误值')),

assert/legacy_mode.md → assert/legacy_assertion_mode.md

@@ -1,19 +1,19 @@
 
 
-遗留模式在以下方法中使用[抽象的相等性比较][Abstract Equality Comparison]：
+遗留的断言模式在以下方法中使用[抽象的相等性比较][Abstract Equality Comparison]：
 
 * [`assert.deepEqual()`][]
 * [`assert.equal()`][]
 * [`assert.notDeepEqual()`][]
 * [`assert.notEqual()`][]
 
-使用遗留模式：
+使用遗留的断言模式：
 
 ```js
 const assert = require('assert');
 ```
 
-只要有可能，请使用[严格模式][`strict` mode]。 
+只要有可能，请使用[严格的断言模式][strict assertion mode]。 
 否则，[抽象的相等性比较][Abstract Equality Comparison]可能会导致意外的结果。
 特别是对于 [`assert.deepEqual()`]，其中的比较规则是松散的：
 

assert/strict_mode.md → assert/strict_assertion_mode.md

@@ -1,21 +1,25 @@
 <!-- YAML
 added: v9.9.0
 changes:
+  - version: v12.16.2
+    description: Changed "strict mode" to "strict assertion mode" and "legacy
+                 mode" to "legacy assertion mode" to avoid confusion with the
+                 more usual meaining of "strict mode".
   - version: v9.9.0
     pr-url: https://github.com/nodejs/node/pull/17615
-    description: Added error diffs to the strict mode
+    description: Added error diffs to the strict assertion mode.
   - version: v9.9.0
     pr-url: https://github.com/nodejs/node/pull/17002
-    description: Added strict mode to the assert module.
+    description: Added strict assertion mode to the assert module.
 -->
 
-在严格模式中（不要与 `"use strict"` 混淆），任何 `assert` 函数都将使用严格函数模式中使用的相等性。 
+在严格的断言模式中，非严格的方法与它们对应的严格方法的行为是一样的。
 例如，[`assert.deepEqual()`] 将与 [`assert.deepStrictEqual()`] 一样效果。
 
-在严格模式中，对象的错误消息会显示差异。
-在遗留模式下，对象的错误消息会显示对象，通常是截断的。
+在严格的断言模式中，对象的错误消息会显示差异。
+在遗留的断言模式下，对象的错误消息会显示对象，通常是截断的。
 
-使用严格模式：
+使用严格的断言模式：
 
 ```js
 const assert = require('assert').strict;
@@ -43,7 +47,6 @@ assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
 ```
 
 要停用颜色，则使用 `NO_COLOR` 或 `NODE_DISABLE_COLORS` 环境变量。 
-注意，这也将停用 REPL 中的颜色。
-
+这也将停用 REPL 中的颜色。
 有关终端环境中颜色支持的更多信息，参阅 [getColorDepth()][_tty_writestream_getcolordepth] 文档。
 

async_hooks/async_hooks.md

@@ -3,9 +3,8 @@
 
 > Stability: 1 - Experimental
 
-The `async_hooks` module provides an API to register callbacks tracking the
-lifetime of asynchronous resources created inside a Node.js application.
-It can be accessed using:
+The `async_hooks` module provides an API to track asynchronous resources. It
+can be accessed using:
 
 ```js
 const async_hooks = require('async_hooks');

async_hooks/asynchronous_context_example.md

@@ -70,8 +70,8 @@ Timeout(7) -> TickObject(6) -> root(1)
 ```
 
 The `TCPSERVERWRAP` is not part of this graph, even though it was the reason for
-`console.log()` being called. This is because binding to a port without a
-hostname is a *synchronous* operation, but to maintain a completely asynchronous
+`console.log()` being called. This is because binding to a port without a host
+name is a *synchronous* operation, but to maintain a completely asynchronous
 API the user's callback is placed in a `process.nextTick()`.
 
 The graph only shows *when* a resource was created, not *why*, so to track

async_hooks/asyncresource_triggerasyncid.md

@@ -2,12 +2,4 @@
 * Returns: {number} The same `triggerAsyncId` that is passed to the
 `AsyncResource` constructor.
 
-
-
-
-
-
-
-
-
-
+<a id="async-resource-worker-pool"></a>

async_hooks/resource.md

@@ -2,7 +2,7 @@
 `resource` is an object that represents the actual async resource that has
 been initialized. This can contain useful information that can vary based on
 the value of `type`. For instance, for the `GETADDRINFOREQWRAP` resource type,
-`resource` provides the hostname used when looking up the IP address for the
+`resource` provides the host name used when looking up the IP address for the
 host in `net.Server.listen()`. The API for accessing this information is
 currently not considered public, but using the Embedder API, users can provide
 and document their own resource objects. For example, such a resource object

async_hooks/using_asyncresource_for_a_worker_thread_pool.md

@@ -0,0 +1,129 @@
+
+The following example shows how to use the `AsyncResource` class to properly
+provide async tracking for a [`Worker`][] pool. Other resource pools, such as
+database connection pools, can follow a similar model.
+
+Assuming that the task is adding two numbers, using a file named
+`task_processor.js` with the following content:
+
+```js
+const { parentPort } = require('worker_threads');
+parentPort.on('message', (task) => {
+  parentPort.postMessage(task.a + task.b);
+});
+```
+
+a Worker pool around it could use the following structure:
+
+```js
+const { AsyncResource } = require('async_hooks');
+const { EventEmitter } = require('events');
+const path = require('path');
+const { Worker } = require('worker_threads');
+
+const kTaskInfo = Symbol('kTaskInfo');
+const kWorkerFreedEvent = Symbol('kWorkerFreedEvent');
+
+class WorkerPoolTaskInfo extends AsyncResource {
+  constructor(callback) {
+    super('WorkerPoolTaskInfo');
+    this.callback = callback;
+  }
+
+  done(err, result) {
+    this.runInAsyncScope(this.callback, null, err, result);
+    this.emitDestroy();  // `TaskInfo`s are used only once.
+  }
+}
+
+class WorkerPool extends EventEmitter {
+  constructor(numThreads) {
+    super();
+    this.numThreads = numThreads;
+    this.workers = [];
+    this.freeWorkers = [];
+
+    for (let i = 0; i < numThreads; i++)
+      this.addNewWorker();
+  }
+
+  addNewWorker() {
+    const worker = new Worker(path.resolve(__dirname, 'task_processor.js'));
+    worker.on('message', (result) => {
+      // In case of success: Call the callback that was passed to `runTask`,
+      // remove the `TaskInfo` associated with the Worker, and mark it as free
+      // again.
+      worker[kTaskInfo].done(null, result);
+      worker[kTaskInfo] = null;
+      this.freeWorkers.push(worker);
+      this.emit(kWorkerFreedEvent);
+    });
+    worker.on('error', (err) => {
+      // In case of an uncaught exception: Call the callback that was passed to
+      // `runTask` with the error.
+      if (worker[kTaskInfo])
+        worker[kTaskInfo].done(err, null);
+      else
+        this.emit('error', err);
+      // Remove the worker from the list and start a new Worker to replace the
+      // current one.
+      this.workers.splice(this.workers.indexOf(worker), 1);
+      this.addNewWorker();
+    });
+    this.workers.push(worker);
+    this.freeWorkers.push(worker);
+  }
+
+  runTask(task, callback) {
+    if (this.freeWorkers.length === 0) {
+      // No free threads, wait until a worker thread becomes free.
+      this.once(kWorkerFreedEvent, () => this.runTask(task, callback));
+      return;
+    }
+
+    const worker = this.freeWorkers.pop();
+    worker[kTaskInfo] = new WorkerPoolTaskInfo(callback);
+    worker.postMessage(task);
+  }
+
+  close() {
+    for (const worker of this.workers) worker.terminate();
+  }
+}
+
+module.exports = WorkerPool;
+```
+
+Without the explicit tracking added by the `WorkerPoolTaskInfo` objects,
+it would appear that the callbacks are associated with the individual `Worker`
+objects. However, the creation of the `Worker`s is not associated with the
+creation of the tasks and does not provide information about when tasks
+were scheduled.
+
+This pool could be used as follows:
+
+```js
+const WorkerPool = require('./worker_pool.js');
+const os = require('os');
+
+const pool = new WorkerPool(os.cpus().length);
+
+let finished = 0;
+for (let i = 0; i < 10; i++) {
+  pool.runTask({ a: 42, b: 100 }, (err, result) => {
+    console.log(i, err, result);
+    if (++finished === 10)
+      pool.close();
+  });
+}
+```
+
+
+
+
+
+
+
+
+
+

buffer/buffers_and_character_encodings.md

@@ -42,6 +42,17 @@ Node.js 当前支持的字符编码有：
 
 * `'hex'`: 将每个字节编码成两个十六进制的字符。
 
+```js
+Buffer.from('1ag', 'hex');
+// 打印 <Buffer 1a>，当遇到第一个非十六进制的值（'g'）时，则数据会被截断。
+
+Buffer.from('1a7g', 'hex');
+// 打印 <Buffer 1a>，当数据以一个数字（'7'）结尾时，则数据会被截断。
+
+Buffer.from('1634', 'hex');
+// 打印 <Buffer 16 34>，所有数据均可用。
+```
+
 现代的 Web 浏览器遵循 [WHATWG 编码标准][WHATWG Encoding Standard]，将 `'latin1'` 和 `'ISO-8859-1'` 别名为 `'win-1252'`。
 这意味着当执行 `http.get()` 之类的操作时，如果返回的字符集是 WHATWG 规范中列出的字符集之一，则服务器可能实际返回 `'win-1252'` 编码的数据，而使用 `'latin1'` 编码可能错误地解码字符。
 

buffer/class_method_buffer_from_arraybuffer_byteoffset_length.md

@@ -4,7 +4,7 @@ added: v5.10.0
 
 * `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} 一个 [`ArrayBuffer`]、[`SharedArrayBuffer`]、或 [`TypedArray`] 的 `.buffer` 属性。
 * `byteOffset` {integer} 开始拷贝的索引。**默认值:** `0`。
-* `length` {integer} 拷贝的字节数。**默认值:** `arrayBuffer.length - byteOffset`。
+* `length` {integer} 拷贝的字节数。**默认值:** `arrayBuffer.byteLength - byteOffset`。
 
 创建 [`ArrayBuffer`] 的视图，但不会拷贝底层内存。
 例如，当传入 [`TypedArray`] 的 `.buffer` 属性的引用时，新建的 `Buffer` 会与 [`TypedArray`] 共享同一内存。

buffer/new_buffer_arraybuffer_byteoffset_length.md

@@ -25,7 +25,7 @@ changes:
   [`SharedArrayBuffer`][] or the `.buffer` property of a [`TypedArray`][].
 * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
 * `length` {integer} Number of bytes to expose.
-  **Default:** `arrayBuffer.length - byteOffset`.
+  **Default:** `arrayBuffer.byteLength - byteOffset`.
 
 This creates a view of the [`ArrayBuffer`][] or [`SharedArrayBuffer`][] without
 copying the underlying memory. For example, when passed a reference to the

buffer/the_zero_fill_buffers_command_line_option.md

@@ -3,10 +3,9 @@ added: v5.10.0
 -->
 
 可以使用 `--zero-fill-buffers` 命令行选项启动 Node.js，以使所有新分配的 `Buffer` 实例在创建时默认使用零来填充。
-在 Node.js 8.0.0 之前，这包括 `new Buffer(size)`、[`Buffer.allocUnsafe()`]、[`Buffer.allocUnsafeSlow()`] 和 `new SlowBuffer(size)` 分配的 buffer。
-从 Node.js 8.0.0 开始，无论是否使用此选项，使用 `new` 分配的 buffer 始终用零填充。
+如果没有该选项，则使用 [`Buffer.allocUnsafe()`]、[`Buffer.allocUnsafeSlow()`] 和 `new SlowBuffer(size)` 创建的 buffer 不会填充零。
 使用这个选项可能会对性能产生重大的负面影响。
-建议仅在需要强制新分配的 `Buffer` 实例不能包含可能敏感的旧数据时，才使用 `--zero-fill-buffers` 选项。
+仅在需要强制新分配的 `Buffer` 实例不能包含可能敏感的旧数据时，才使用 `--zero-fill-buffers` 选项。
 
 ```console
 $ node --zero-fill-buffers

child_process/event_exit.md

@@ -8,7 +8,7 @@ added: v0.1.90
 当子进程结束后时会触发 `'exit'` 事件。
 如果进程退出，则 `code` 是进程的最终退出码，否则为 `null`。
 如果进程是因为收到的信号而终止，则 `signal` 是信号的字符串名称，否则为 `null`。
-这两个值至少有一个是非空的。
+这两个值至少有一个是非 `null` 的。
 
 当 `'exit'` 事件被触发时，子进程的 stdio 流可能依然是打开的。