v14.0.0

addons/c_addons.md

@@ -7,7 +7,7 @@
 插件提供了 JavaScript 和 C/C++ 库之间的接口。
 
 实现插件有三种选择：N-API、nan、或直接使用内部的 V8、libuv 和 Node.js 库。 
-除非你需要直接访问 N-API 未公开的函数，否则请使用 N-API。 
+除非需要直接访问 N-API 未公开的函数，否则请使用 N-API。 
 有关 N-API 的更多信息，参阅[具有 N-API 的 C/C++ 插件][_n-api]。
 
 当不使用 N-API 时，实现插件很复杂，涉及多个组件和 API 的知识：

addons/context_aware_addons.md

@@ -32,11 +32,19 @@ NODE_MODULE_INITIALIZER(Local<Object> exports,
 
 可以通过执行以下步骤来构造上下文感知的插件以避免全局静态数据：
 
-* 定义一个持有每个插件实例数据的类。这样的类应该包含一个 `v8::Global<v8::Object>` 持有 `exports` 对象的弱引用。与该弱引用关联的回调函数将会破坏该类的实例。
-* 在插件实例化过程中构造这个类的实例，把`v8::Global<v8::Object>` 挂到 `exports` 对象上去。
-* 在 `v8::External` 中保存这个类的实例。
-* 通过将 `v8::External` 传给 `v8::FunctionTemplate` 构造函数，该函数会创建本地支持的 JavaScript 函数，把 `v8::External` 传递给所有暴露给 JavaScript 的方法。
-  `v8::FunctionTemplate` 构造函数的第三个参数接受 `v8::External`。
+* 定义一个类，该类会保存每个插件实例的数据，并且具有以下形式的静态成员：
+    ```C++
+    static void DeleteInstance(void* data) {
+      // 将 `data` 转换为该类的实例并删除它。
+    }
+    ```
+* 在插件的初始化过程中堆分配此类的实例。
+  这可以使用 `new` 关键字来完成。
+* 调用 `node::AddEnvironmentCleanupHook()`，将上面创建的实例和指向 `DeleteInstance()` 的指针传给它。 
+  这可以确保实例会在销毁环境之后被删除。
+* 将类的实例保存在 `v8::External`中。
+* 通过将 `v8::External` 传给 `v8::FunctionTemplate::New()` 或 `v8::Function::New()`（用以创建原生支持的 JavaScript 函数）来将其传给暴露给 JavaScript 的所有方法。 
+  `v8::FunctionTemplate::New()` 或 `v8::Function::New()` 的第三个参数接受 `v8::External`，并使用 `v8::FunctionCallbackInfo::Data()` 方法使其在原生回调中可用。
 
 这确保了每个扩展实例数据到达每个能被 JavaScript 访问的绑定。每个扩展实例数据也必须通过其创建的任何异步回调函数。
 
@@ -49,24 +57,18 @@ using namespace v8;
 
 class AddonData {
  public:
-  AddonData(Isolate* isolate, Local<Object> exports):
+  explicit AddonData(Isolate* isolate):
       call_count(0) {
-    // 将次对象的实例挂到 exports 上。
-    exports_.Reset(isolate, exports);
-    exports_.SetWeak(this, DeleteMe, WeakCallbackType::kParameter);
+    // 确保在清理环境时删除每个插件实例的数据。
+    node::AddEnvironmentCleanupHook(isolate, DeleteInstance, this);
   }
 
   // 每个插件的数据。
   int call_count;
 
- private:
-  // 导出即将被回收时调用的方法。
-  static void DeleteMe(const WeakCallbackInfo<AddonData>& info) {
-    delete info.GetParameter();
+  static void DeleteInstance(void* data) {
+    delete static_cast<AddonData*>(data);
   }
-
-  // 导出对象弱句柄。该类的实例将与其若绑定的 exports 对象一起销毁。
-  v8::Global<v8::Object> exports_;
 };
 
 static void Method(const v8::FunctionCallbackInfo<v8::Value>& info) {
@@ -81,12 +83,13 @@ static void Method(const v8::FunctionCallbackInfo<v8::Value>& info) {
 NODE_MODULE_INIT(/* exports, module, context */) {
   Isolate* isolate = context->GetIsolate();
 
-  // 为该扩展实例的AddonData创建一个新的实例
+  // 为此插件实例创建一个新的 `AddonData` 实例，并将其生命周期与 Node.js 环境的生命周期联系起来。
   AddonData* data = new AddonData(isolate, exports);
-  // 在 v8::External 中包裹数据，这样我们就可以将它传递给我们暴露的方法。
+  // 在 `v8::External` 中包裹数据，这样我们就可以将它传递给我们暴露的方法。
   Local<External> external = External::New(isolate, data);
 
-  // 把 "Method" 方法暴露给 JavaScript，并确保其接收我们通过把 `external` 作为 FunctionTemplate 构造函数第三个参数时创建的每个插件实例的数据。
+  // 把 `Method` 方法暴露给 JavaScript，
+  // 并确保其接收我们通过把 `external` 作为 `FunctionTemplate` 构造函数第三个参数时创建的每个插件实例的数据。
   exports->Set(context,
                String::NewFromUtf8(isolate, "method", NewStringType::kNormal)
                   .ToLocalChecked(),

assert/assert_deepequal_actual_expected_message.md

@@ -1,6 +1,10 @@
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: v14.0.0
+    pr-url: https://github.com/nodejs/node/pull/30766
+    description: NaN is now treated as being identical in case both sides are
+                 NaN.
   - version: v12.0.0
     pr-url: https://github.com/nodejs/node/pull/25008
     description: The type tags are now properly compared and there are a couple

assert/assert_doesnotmatch_string_regexp_message.md

@@ -1,5 +1,5 @@
 <!-- YAML
-added: v12.16.0
+added: v13.6.0
 -->
 
 * `string` {string}

assert/assert_equal_actual_expected_message.md

@@ -1,5 +1,10 @@
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v14.0.0
+    pr-url: https://github.com/nodejs/node/pull/30766
+    description: NaN is now treated as being identical in case both sides are
+                 NaN.
 -->
 
 * `actual` {any}
@@ -15,7 +20,8 @@ An alias of [`assert.strictEqual()`][].
 > Stability: 0 - Deprecated: Use [`assert.strictEqual()`][] instead.
 
 Tests shallow, coercive equality between the `actual` and `expected` parameters
-using the [Abstract Equality Comparison][] ( `==` ).
+using the [Abstract Equality Comparison][] ( `==` ). `NaN` is special handled
+and treated as being identical in case both sides are `NaN`.
 
 ```js
 const assert = require('assert');
@@ -24,6 +30,8 @@ assert.equal(1, 1);
 // OK, 1 == 1
 assert.equal(1, '1');
 // OK, 1 == '1'
+assert.equal(NaN, NaN);
+// OK
 
 assert.equal(1, 2);
 // AssertionError: 1 == 2

assert/assert_match_string_regexp_message.md

@@ -1,5 +1,5 @@
 <!-- YAML
-added: v12.16.0
+added: v13.6.0
 -->
 
 * `string` {string}

assert/assert_notdeepequal_actual_expected_message.md

@@ -1,6 +1,10 @@
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: v14.0.0
+    pr-url: https://github.com/nodejs/node/pull/30766
+    description: NaN is now treated as being identical in case both sides are
+                 NaN.
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15001
     description: The `Error` names and messages are now properly compared

assert/assert_notequal_actual_expected_message.md

@@ -1,5 +1,10 @@
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v14.0.0
+    pr-url: https://github.com/nodejs/node/pull/30766
+    description: NaN is now treated as being identical in case both sides are
+                 NaN.
 -->
 
 * `actual` {any}
@@ -15,7 +20,8 @@ An alias of [`assert.notStrictEqual()`][].
 > Stability: 0 - Deprecated: Use [`assert.notStrictEqual()`][] instead.
 
 Tests shallow, coercive inequality with the [Abstract Equality Comparison][]
-( `!=` ).
+(`!=` ). `NaN` is special handled and treated as being identical in case both
+sides are `NaN`.
 
 ```js
 const assert = require('assert');

assert/comparison_details.md

@@ -1,5 +1,5 @@
 
-* 使用[抽象的相等性比较][Abstract Equality Comparison]来比较原始值。
+* 除 `NaN` 之外，使用[抽象的相等性比较][Abstract Equality Comparison]（`==`）来比较原始值。如果双方均为 `NaN`，则视为相同。
 * 对象的[类型标签][Object.prototype.toString()]应该相同。
 * 只考虑[可枚举的自身属性][enumerable "own" properties]。
 * 始终比较 [`Error`] 的名称和消息，即使这些不是可枚举的属性。

assert/strict_assertion_mode.md

@@ -1,7 +1,7 @@
 <!-- YAML
 added: v9.9.0
 changes:
-  - version: v12.16.2
+  - version: v13.9.0
     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".

async_hooks/async_hooks_executionasyncresource.md

@@ -0,0 +1,55 @@
+
+<!-- YAML
+added: v13.9.0
+-->
+
+* Returns: {Object} The resource representing the current execution.
+  Useful to store data within the resource.
+
+Resource objects returned by `executionAsyncResource()` are most often internal
+Node.js handle objects with undocumented APIs. Using any functions or properties
+on the object is likely to crash your application and should be avoided.
+
+Using `executionAsyncResource()` in the top-level execution context will
+return an empty object as there is no handle or request object to use,
+but having an object representing the top-level can be helpful.
+
+```js
+const { open } = require('fs');
+const { executionAsyncId, executionAsyncResource } = require('async_hooks');
+
+console.log(executionAsyncId(), executionAsyncResource());  // 1 {}
+open(__filename, 'r', (err, fd) => {
+  console.log(executionAsyncId(), executionAsyncResource());  // 7 FSReqWrap
+});
+```
+
+This can be used to implement continuation local storage without the
+use of a tracking `Map` to store the metadata:
+
+```js
+const { createServer } = require('http');
+const {
+  executionAsyncId,
+  executionAsyncResource,
+  createHook
+} = require('async_hooks');
+const sym = Symbol('state'); // Private symbol to avoid pollution
+
+createHook({
+  init(asyncId, type, triggerAsyncId, resource) {
+    const cr = executionAsyncResource();
+    if (cr) {
+      resource[sym] = cr[sym];
+    }
+  }
+}).enable();
+
+const server = createServer(function(req, res) {
+  executionAsyncResource()[sym] = { state: req.url };
+  setTimeout(function() {
+    res.end(JSON.stringify(executionAsyncResource()[sym]));
+  }, 100);
+}).listen(3000);
+```
+

async_hooks/asynclocalstorage_disable.md

@@ -0,0 +1,19 @@
+<!-- YAML
+added: v13.10.0
+-->
+
+This method disables the instance of `AsyncLocalStorage`. All subsequent calls
+to `asyncLocalStorage.getStore()` will return `undefined` until
+`asyncLocalStorage.run()` is called again.
+
+When calling `asyncLocalStorage.disable()`, all current contexts linked to the
+instance will be exited.
+
+Calling `asyncLocalStorage.disable()` is required before the
+`asyncLocalStorage` can be garbage collected. This does not apply to stores
+provided by the `asyncLocalStorage`, as those objects are garbage collected
+along with the corresponding async resources.
+
+This method is to be used when the `asyncLocalStorage` is not in use anymore
+in the current process.
+

async_hooks/asynclocalstorage_enterwith_store.md

@@ -0,0 +1,41 @@
+<!-- YAML
+added: v13.11.0
+-->
+
+* `store` {any}
+
+Calling `asyncLocalStorage.enterWith(store)` will transition into the context
+for the remainder of the current synchronous execution and will persist
+through any following asynchronous calls.
+
+Example:
+
+```js
+const store = { id: 1 };
+asyncLocalStorage.enterWith(store);
+asyncLocalStorage.getStore(); // Returns the store object
+someAsyncOperation(() => {
+  asyncLocalStorage.getStore(); // Returns the same object
+});
+```
+
+This transition will continue for the _entire_ synchronous execution.
+This means that if, for example, the context is entered within an event
+handler subsequent event handlers will also run within that context unless
+specifically bound to another context with an `AsyncResource`.
+
+```js
+const store = { id: 1 };
+
+emitter.on('my-event', () => {
+  asyncLocalStorage.enterWith(store);
+});
+emitter.on('my-event', () => {
+  asyncLocalStorage.getStore(); // Returns the same object
+});
+
+asyncLocalStorage.getStore(); // Returns undefined
+emitter.emit('my-event');
+asyncLocalStorage.getStore(); // Returns the same object
+```
+

async_hooks/asynclocalstorage_exit_callback_args.md

@@ -0,0 +1,34 @@
+<!-- YAML
+added: v13.10.0
+-->
+
+* `callback` {Function}
+* `...args` {any}
+
+This methods runs a function synchronously outside of a context and return its
+return value. The store is not accessible within the callback function or
+the asynchronous operations created within the callback.
+
+Optionally, arguments can be passed to the function. They will be passed to
+the callback function.
+
+If the callback function throws an error, it will be thrown by `exit` too.
+The stacktrace will not be impacted by this call and
+the context will be re-entered.
+
+Example:
+
+```js
+// Within a call to run
+try {
+  asyncLocalStorage.getStore(); // Returns the store object or value
+  asyncLocalStorage.exit(() => {
+    asyncLocalStorage.getStore(); // Returns undefined
+    throw new Error();
+  });
+} catch (e) {
+  asyncLocalStorage.getStore(); // Returns the same object or value
+  // The error will be caught here
+}
+```
+

async_hooks/asynclocalstorage_getstore.md

@@ -0,0 +1,10 @@
+<!-- YAML
+added: v13.10.0
+-->
+
+* Returns: {any}
+
+This method returns the current store.
+If this method is called outside of an asynchronous context initialized by
+calling `asyncLocalStorage.run`, it will return `undefined`.
+

async_hooks/asynclocalstorage_run_store_callback_args.md

@@ -0,0 +1,34 @@
+<!-- YAML
+added: v13.10.0
+-->
+
+* `store` {any}
+* `callback` {Function}
+* `...args` {any}
+
+This methods runs a function synchronously within a context and return its
+return value. The store is not accessible outside of the callback function or
+the asynchronous operations created within the callback.
+
+Optionally, arguments can be passed to the function. They will be passed to
+the callback function.
+
+If the callback function throws an error, it will be thrown by `run` too.
+The stacktrace will not be impacted by this call and the context will
+be exited.
+
+Example:
+
+```js
+const store = { id: 2 };
+try {
+  asyncLocalStorage.run(store, () => {
+    asyncLocalStorage.getStore(); // Returns the store object
+    throw new Error();
+  });
+} catch (e) {
+  asyncLocalStorage.getStore(); // Returns undefined
+  // The error will be caught here
+}
+```
+

async_hooks/class_asynchook.md

@@ -0,0 +1,4 @@
+
+The class `AsyncHook` exposes an interface for tracking lifetime events
+of asynchronous operations.
+