v12.16.0

addons/c_addons.md

@@ -2,8 +2,9 @@
 <!--introduced_in=v0.10.0-->
 <!-- type=misc -->
 
-Node.js 插件是用 C++ 编写的动态链接共享对象，可以使用 [`require()`][require] 函数加载到 Node.js 中，且像普通的 Node.js 模块一样被使用。
-它们主要用于为运行在 Node.js 中的 JavaScript 与 C/C++ 库之间提供接口。
+插件是用 C++ 编写的动态链接共享对象。
+[`require()`][require] 函数可以将插件加载为普通的 Node.js 模块。
+插件提供了 JavaScript 和 C/C++ 库之间的接口。
 
 实现插件有三种选择：N-API、nan、或直接使用内部的 V8、libuv 和 Node.js 库。 
 除非你需要直接访问 N-API 未公开的函数，否则请使用 N-API。 

addons/context_aware_addons.md

@@ -32,8 +32,8 @@ NODE_MODULE_INITIALIZER(Local<Object> exports,
 
 可以通过执行以下步骤来构造上下文感知的插件以避免全局静态数据：
 
-* 定义一个持有每个插件实例数据的类。这样的类应该包含一个 `v8::Persistent<v8::Object>` 持有 `exports` 对象的弱引用。与该弱引用关联的回调函数将会破坏该类的实例。
-* 在插件实例化过程中构造这个类的实例，把`v8::Persistent<v8::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`。
@@ -56,14 +56,6 @@ class AddonData {
     exports_.SetWeak(this, DeleteMe, WeakCallbackType::kParameter);
   }
 
-  ~AddonData() {
-    if (!exports_.IsEmpty()) {
-      // 重新设置引用以避免数据泄露。
-      exports_.ClearWeak();
-      exports_.Reset();
-    }
-  }
-
   // 每个插件的数据。
   int call_count;
 
@@ -74,7 +66,7 @@ class AddonData {
   }
 
   // 导出对象弱句柄。该类的实例将与其若绑定的 exports 对象一起销毁。
-  v8::Persistent<v8::Object> exports_;
+  v8::Global<v8::Object> exports_;
 };
 
 static void Method(const v8::FunctionCallbackInfo<v8::Value>& info) {

addons/factory_of_wrapped_objects.md

@@ -62,7 +62,7 @@ class MyObject : public node::ObjectWrap {
 
   static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);
-  static v8::Persistent<v8::Function> constructor;
+  static v8::Global<v8::Function> constructor;
   double value_;
 };
 
@@ -80,20 +80,22 @@ class MyObject : public node::ObjectWrap {
 
 namespace demo {
 
+using node::AddEnvironmentCleanupHook;
 using v8::Context;
 using v8::Function;
 using v8::FunctionCallbackInfo;
 using v8::FunctionTemplate;
+using v8::Global;
 using v8::Isolate;
 using v8::Local;
 using v8::NewStringType;
 using v8::Number;
 using v8::Object;
-using v8::Persistent;
 using v8::String;
 using v8::Value;
 
-Persistent<Function> MyObject::constructor;
+// 注意！这不是线程安全的，此插件不能用于工作线程。
+Global<Function> MyObject::constructor;
 
 MyObject::MyObject(double value) : value_(value) {
 }
@@ -113,6 +115,10 @@ void MyObject::Init(Isolate* isolate) {
 
   Local<Context> context = isolate->GetCurrentContext();
   constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());
+
+  AddEnvironmentCleanupHook(isolate, [](void*) {
+    constructor.Reset();
+  }, nullptr);
 }
 
 void MyObject::New(const FunctionCallbackInfo<Value>& args) {

addons/passing_wrapped_objects_around.md

@@ -71,7 +71,7 @@ class MyObject : public node::ObjectWrap {
   ~MyObject();
 
   static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
-  static v8::Persistent<v8::Function> constructor;
+  static v8::Global<v8::Function> constructor;
   double value_;
 };
 
@@ -89,19 +89,21 @@ class MyObject : public node::ObjectWrap {
 
 namespace demo {
 
+using node::AddEnvironmentCleanupHook;
 using v8::Context;
 using v8::Function;
 using v8::FunctionCallbackInfo;
 using v8::FunctionTemplate;
+using v8::Global;
 using v8::Isolate;
 using v8::Local;
 using v8::NewStringType;
 using v8::Object;
-using v8::Persistent;
 using v8::String;
 using v8::Value;
 
-Persistent<Function> MyObject::constructor;
+// 注意！这不是线程安全的，此插件不能用于工作线程。
+Global<Function> MyObject::constructor;
 
 MyObject::MyObject(double value) : value_(value) {
 }
@@ -118,6 +120,10 @@ void MyObject::Init(Isolate* isolate) {
 
   Local<Context> context = isolate->GetCurrentContext();
   constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());
+
+  AddEnvironmentCleanupHook(isolate, [](void*) {
+    constructor.Reset();
+  }, nullptr);
 }
 
 void MyObject::New(const FunctionCallbackInfo<Value>& args) {

addons/worker_support.md

@@ -1,4 +1,9 @@
 
+为了从多个 Node.js 环境加载，例如主线程和工作线程，插件还需要：
+
+* 是一个 N-API 插件，或
+* 如上所述，使用 `NODE_MODULE_INIT()` 声明为上下文感知。
+
 为了支持 [`Worker`] 线程，插件需要清理可能分配的任何资源（当存在这样的线程时）。 
 这可以通过使用 `AddEnvironmentCleanupHook()` 函数来实现：
 
@@ -10,8 +15,62 @@ void AddEnvironmentCleanupHook(v8::Isolate* isolate,
 
 此函数添加了一个钩子，该钩子将在给定的 Node.js 实例关闭之前运行。 
 如有必要，可以在运行之前使用 `RemoveEnvironmentCleanupHook()` 删除此类挂钩，它们具有相同的签名。
+回调以后进先出的顺序运行。
+
+以下的 `addon.cc` 使用 `AddEnvironmentCleanupHook`：
+
+```cpp
+// addon.cc
+#include <assert.h>
+#include <stdlib.h>
+#include <node.h>
+
+using node::AddEnvironmentCleanupHook;
+using v8::HandleScope;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+
+// 注意：在实际的应用程序中，请勿依赖静态/全局的数据。
+static char cookie[] = "yum yum";
+static int cleanup_cb1_called = 0;
+static int cleanup_cb2_called = 0;
+
+static void cleanup_cb1(void* arg) {
+  Isolate* isolate = static_cast<Isolate*>(arg);
+  HandleScope scope(isolate);
+  Local<Object> obj = Object::New(isolate);
+  assert(!obj.IsEmpty());  // 断言 VM 仍然存在。
+  assert(obj->IsObject());
+  cleanup_cb1_called++;
+}
+
+static void cleanup_cb2(void* arg) {
+  assert(arg == static_cast<void*>(cookie));
+  cleanup_cb2_called++;
+}
+
+static void sanity_check(void*) {
+  assert(cleanup_cb1_called == 1);
+  assert(cleanup_cb2_called == 1);
+}
+
+// 将此插件初始化为上下文感知的。
+NODE_MODULE_INIT(/* exports, module, context */) {
+  Isolate* isolate = context->GetIsolate();
+
+  AddEnvironmentCleanupHook(isolate, sanity_check, nullptr);
+  AddEnvironmentCleanupHook(isolate, cleanup_cb2, cookie);
+  AddEnvironmentCleanupHook(isolate, cleanup_cb1, isolate);
+}
+```
+
+通过运行以下命令在 JavaScript 中进行测试：
+
+```js
+// test.js
+require('./build/Release/addon');
+```
+
 
-为了从多个 Node.js 环境加载，例如主线程和工作线程，插件还需要：
-- 是一个 N-API 插件，或
-- 如上所述，使用 `NODE_MODULE_INIT()` 声明为上下文感知。
 

addons/wrapping_c_objects.md

@@ -42,7 +42,7 @@ class MyObject : public node::ObjectWrap {
 
   static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);
-  static v8::Persistent<v8::Function> constructor;
+
   double value_;
 };
 
@@ -70,12 +70,10 @@ using v8::Local;
 using v8::NewStringType;
 using v8::Number;
 using v8::Object;
-using v8::Persistent;
+using v8::ObjectTemplate;
 using v8::String;
 using v8::Value;
 
-Persistent<Function> MyObject::constructor;
-
 MyObject::MyObject(double value) : value_(value) {
 }
 
@@ -84,21 +82,27 @@ MyObject::~MyObject() {
 
 void MyObject::Init(Local<Object> exports) {
   Isolate* isolate = exports->GetIsolate();
+  Local<Context> context = isolate->GetCurrentContext();
+
+  Local<ObjectTemplate> addon_data_tpl = ObjectTemplate::New(isolate);
+  addon_data_tpl->SetInternalFieldCount(1);  // MyObject::New() 的一个字段。
+  Local<Object> addon_data =
+      addon_data_tpl->NewInstance(context).ToLocalChecked();
 
   // 准备构造函数模版
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New, addon_data);
   tpl->SetClassName(String::NewFromUtf8(
       isolate, "MyObject", NewStringType::kNormal).ToLocalChecked());
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
 
   // 原型
   NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne);
 
-  Local<Context> context = isolate->GetCurrentContext();
-  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());
+  Local<Function> constructor = tpl->GetFunction(context).ToLocalChecked();
+  addon_data->SetInternalField(0, constructor);
   exports->Set(context, String::NewFromUtf8(
       isolate, "MyObject", NewStringType::kNormal).ToLocalChecked(),
-               tpl->GetFunction(context).ToLocalChecked()).FromJust();
+               constructor).FromJust();
 }
 
 void MyObject::New(const FunctionCallbackInfo<Value>& args) {
@@ -116,7 +120,8 @@ void MyObject::New(const FunctionCallbackInfo<Value>& args) {
     // 像普通方法 `MyObject(...)` 一样调用，转为构造调用。
     const int argc = 1;
     Local<Value> argv[argc] = { args[0] };
-    Local<Function> cons = Local<Function>::New(isolate, constructor);
+    Local<Function> cons =
+        args.Data().As<Object>()->GetInternalField(0).As<Function>();
     Local<Object> result =
         cons->NewInstance(context, argc, argv).ToLocalChecked();
     args.GetReturnValue().Set(result);

assert/assert_doesnotmatch_string_regexp_message.md

@@ -0,0 +1,35 @@
+<!-- YAML
+added: v12.16.0
+-->
+
+* `string` {string}
+* `regexp` {RegExp}
+* `message` {string|Error}
+
+> Stability: 1 - Experimental
+
+Expects the `string` input not to match the regular expression.
+
+This feature is currently experimental and the name might change or it might be
+completely removed again.
+
+```js
+const assert = require('assert').strict;
+
+assert.doesNotMatch('I will fail', /fail/);
+// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...
+
+assert.doesNotMatch(123, /pass/);
+// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
+
+assert.doesNotMatch('I will pass', /different/);
+// OK
+```
+
+If the values do match, or if the `string` argument is of another type than
+`string`, an [`AssertionError`][] is thrown with a `message` property set equal
+to the value of the `message` parameter. If the `message` parameter is
+undefined, a default error message is assigned. If the `message` parameter is an
+instance of an [`Error`][] then it will be thrown instead of the
+[`AssertionError`][].
+

assert/assert_doesnotthrow_fn_error_message.md

@@ -8,6 +8,7 @@ changes:
     pr-url: https://github.com/nodejs/node/pull/3276
     description: The `error` parameter can now be an arrow function.
 -->
+
 * `fn` {Function}
 * `error` {RegExp|Function}
 * `message` {string}
@@ -19,7 +20,7 @@ changes:
 
 当调用 `assert.doesNotThrow()` 时，它将立即调用 `fn` 函数。
 
-如果抛出错误并且它与 `error` 参数指定的类型相同，则抛出 `AssertionError`。
+如果抛出错误并且它与 `error` 参数指定的类型相同，则抛出 [`AssertionError`]。
 如果错误的类型不同，或者 `error` 参数未定义，则错误将传播回调用方。
 
 如果指定，则 `error` 可以是 [`Class`]、[`RegExp`] 或验证函数。
@@ -38,7 +39,7 @@ assert.doesNotThrow(
 );
 ```
 
-以下示例将导致 `AssertionError`，并显示消息 'Got unwanted exception...'：
+以下示例将导致 [`AssertionError`]，并显示消息 'Got unwanted exception...'：
 
 <!-- eslint-disable no-restricted-syntax -->
 ```js
@@ -50,7 +51,7 @@ assert.doesNotThrow(
 );
 ```
 
-如果抛出 `AssertionError` 并为 `message` 参数提供了值，则 `message` 的值将附加到 `AssertionError` 消息：
+如果抛出 [`AssertionError`] 并为 `message` 参数提供了值，则 `message` 的值将附加到 `AssertionError` 消息：
 
 <!-- eslint-disable no-restricted-syntax -->
 ```js

assert/assert_equal_actual_expected_message.md

@@ -31,7 +31,7 @@ assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
 // AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
 ```
 
-If the values are not equal, an `AssertionError` is thrown with a `message`
+If the values are not equal, an [`AssertionError`][] is thrown with a `message`
 property set equal to the value of the `message` parameter. If the `message`
 parameter is undefined, a default error message is assigned. If the `message`
 parameter is an instance of an [`Error`][] then it will be thrown instead of the

assert/assert_fail_message.md

@@ -3,8 +3,8 @@ added: v0.1.21
 -->
 * `message` {string|Error} **默认值:** `'Failed'`。
 
-使用提供的错误消息或默认错误消息抛出 `AssertionError`。 
-如果 `message` 参数是 [`Error`] 的实例，则它将被抛出而不是 `AssertionError`。
+使用提供的错误消息或默认错误消息抛出 [`AssertionError`]。 
+如果 `message` 参数是 [`Error`] 的实例，则它将被抛出而不是 [`AssertionError`]。
 
 
 ```js

assert/assert_iferror_value.md

@@ -4,12 +4,13 @@ changes:
   - version: v10.0.0
     pr-url: https://github.com/nodejs/node/pull/18247
     description: Instead of throwing the original error it is now wrapped into
-                 an `AssertionError` that contains the full stack trace.
+                 an [`AssertionError`][] that contains the full stack trace.
   - version: v10.0.0
     pr-url: https://github.com/nodejs/node/pull/18247
     description: Value may now only be `undefined` or `null`. Before all falsy
                  values were handled the same as `null` and did not throw.
 -->
+
 * `value` {any}
 
 如果 `value` 不为 `undefined` 或 `null`，则抛出 `value`。