From 95dcb8bd3b64238aa5cfc95764d6e0800822a425 Mon Sep 17 00:00:00 2001 From: h7lin Date: Wed, 8 Jan 2020 23:08:36 +0800 Subject: [PATCH] v12.14.1 --- addons/void_atexit_callback_args.md | 2 +- assert/assert_throws_fn_error_message.md | 2 + assert/strict_mode.md | 4 +- buffer/buf_buffer.md | 5 ++- child_process/subprocess_kill_signal.md | 2 + .../v8_inspector_integration_for_node_js.md | 2 + esm/commonjs_json_and_native_modules.md | 7 ++-- http/http_request_url_options_callback.md | 1 + http/message_destroy_error.md | 5 ++- modules/module_builtinmodules.md | 5 ++- n-api/napi_add_finalizer.md | 1 + n-api/napi_call_function.md | 12 +++--- n-api/napi_create_date.md | 1 + n-api/napi_create_reference.md | 2 +- n-api/napi_get_date_value.md | 1 + n-api/napi_is_date.md | 1 + n-api/napi_make_callback.md | 14 +++---- n-api/napi_reference_ref.md | 2 +- n-api/napi_reference_unref.md | 2 +- n-api/return_values.md | 4 +- net/socket_buffersize.md | 14 +++++-- net/socket_connect_options_connectlistener.md | 4 +- ...suring_the_duration_of_async_operations.md | 2 +- ...end_message_sendhandle_options_callback.md | 2 +- repl/global_uncaught_exceptions.md | 18 ++++---- stream/api_for_stream_implementers.md | 4 ++ stream/readable_read_size.md | 2 + ...ring_parsequerystring_slashesdenotehost.md | 5 +++ util/class_util_textdecoder.md | 4 +- util/class_util_textencoder.md | 8 ++-- util/custom_promisified_functions.md | 14 +++---- util/util_promisify_custom.md | 3 +- util/util_promisify_original.md | 42 +++++++++++++++---- v8/serialization_api.md | 5 --- 34 files changed, 130 insertions(+), 72 deletions(-) diff --git a/addons/void_atexit_callback_args.md b/addons/void_atexit_callback_args.md index 47b0daa7..682bd2f2 100644 --- a/addons/void_atexit_callback_args.md +++ b/addons/void_atexit_callback_args.md @@ -48,10 +48,10 @@ static void sanity_check(void*) { } void init(Local exports) { + AtExit(sanity_check); AtExit(at_exit_cb2, cookie); AtExit(at_exit_cb2, cookie); AtExit(at_exit_cb1, exports->GetIsolate()); - AtExit(sanity_check); } NODE_MODULE(NODE_GYP_MODULE_NAME, init) diff --git a/assert/assert_throws_fn_error_message.md b/assert/assert_throws_fn_error_message.md index 5e5b75a3..711ce84c 100644 --- a/assert/assert_throws_fn_error_message.md +++ b/assert/assert_throws_fn_error_message.md @@ -142,9 +142,11 @@ assert.throws( function throwingFirst() { throw new Error('错误一'); } + function throwingSecond() { throw new Error('错误二'); } + function notThrowing() {} // 第二个参数是一个字符串，输入函数抛出一个错误。 diff --git a/assert/strict_mode.md b/assert/strict_mode.md index e2496111..ab35780a 100644 --- a/assert/strict_mode.md +++ b/assert/strict_mode.md @@ -42,6 +42,8 @@ assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]); // ] ``` -要停用颜色，则使用 `NODE_DISABLE_COLORS` 环境变量。 +要停用颜色，则使用 `NO_COLOR` 或 `NODE_DISABLE_COLORS` 环境变量。 注意，这也将停用 REPL 中的颜色。 +有关终端环境中颜色支持的更多信息，参阅 [getColorDepth()][_tty_writestream_getcolordepth] 文档。 + diff --git a/buffer/buf_buffer.md b/buffer/buf_buffer.md index b2721a5f..062bb4b5 100644 --- a/buffer/buf_buffer.md +++ b/buffer/buf_buffer.md @@ -1,5 +1,8 @@ -* {ArrayBuffer} 创建 `Buffer` 对象时基于的底层 `ArrayBuffer` 对象。 +* {ArrayBuffer} 创建此 `Buffer` 对象时基于的底层 `ArrayBuffer` 对象。 + +不能保证此 `ArrayBuffer` 与原始的 `Buffer` 完全对应。 +有关详细信息，参阅 `buf.byteOffset` 上的说明。 ```js const arrayBuffer = new ArrayBuffer(16); diff --git a/child_process/subprocess_kill_signal.md b/child_process/subprocess_kill_signal.md index dd39f91c..957e3561 100644 --- a/child_process/subprocess_kill_signal.md +++ b/child_process/subprocess_kill_signal.md @@ -3,10 +3,12 @@ added: v0.1.90 --> * `signal` {number|string} +* 返回: {boolean} `subprocess.kill()` 方法会向子进程发送一个信号。 如果没有给定参数，则进程将会发送 `'SIGTERM'` 信号。 参阅 signal(7) 了解可用的信号列表。 +如果 kill(2) 成功，则此函数返回 `true`，否则返回 `false`。 ```js const { spawn } = require('child_process'); diff --git a/debugger/v8_inspector_integration_for_node_js.md b/debugger/v8_inspector_integration_for_node_js.md index d1f8ce74..6aceaf98 100644 --- a/debugger/v8_inspector_integration_for_node_js.md +++ b/debugger/v8_inspector_integration_for_node_js.md @@ -18,4 +18,6 @@ To start debugging, open the following URL in Chrome: 如果 Chrome 浏览器的版本低于 66.0.3345.0，请在上述网址中使用 `inspector.html` 而不是 `js_app.html`。 +Chrome DevTools 目前还不支持调试[工作线程][Worker Threads]。 +可以使用 [ndb] 调试它们。 diff --git a/esm/commonjs_json_and_native_modules.md b/esm/commonjs_json_and_native_modules.md index 4068b7e1..c83ac6b7 100644 --- a/esm/commonjs_json_and_native_modules.md +++ b/esm/commonjs_json_and_native_modules.md @@ -3,16 +3,15 @@ CommonJS, JSON, and Native modules can be used with [`module.createRequire()`][]. ```js -// cjs.js +// cjs.cjs module.exports = 'cjs'; // esm.mjs import { createRequire } from 'module'; -import { fileURLToPath as fromURL } from 'url'; -const require = createRequire(fromURL(import.meta.url)); +const require = createRequire(import.meta.url); -const cjs = require('./cjs'); +const cjs = require('./cjs.cjs'); cjs === 'cjs'; // true ``` diff --git a/http/http_request_url_options_callback.md b/http/http_request_url_options_callback.md index ca3a12a8..e59f4319 100644 --- a/http/http_request_url_options_callback.md +++ b/http/http_request_url_options_callback.md @@ -24,6 +24,7 @@ changes: * `host` {string} 请求发送至的服务器的域名或 IP 地址。**默认值:** `'localhost'`。 * `hostname` {string} `host` 的别名。为了支持 [`url.parse()`]，如果同时指定 `host` 和 `hostname`，则使用 `hostname`。 * `localAddress` {string} 为网络连接绑定的本地接口。 + * `lookup` {Function} 自定义的查找函数。 **默认值:** [`dns.lookup()`]。 * `method` {string} 一个字符串，指定 HTTP 请求的方法。**默认值:** `'GET'`。 * `path` {string} 请求的路径。应包括查询字符串（如果有）。例如 `'/index.html?page=12'`。当请求的路径包含非法的字符时，则抛出异常。目前只有空格被拒绝，但未来可能会有所变化。**默认值:** `'/'`。 * `port` {number} 远程服务器的端口。**默认值:** `defaultPort`（如果有设置）或 `80`。 diff --git a/http/message_destroy_error.md b/http/message_destroy_error.md index 9356ec51..7fcaf976 100644 --- a/http/message_destroy_error.md +++ b/http/message_destroy_error.md @@ -4,6 +4,7 @@ added: v0.3.0 * `error` {Error} -在接收 `IncomingMessage` 的套接字上调用 `destroy()`。 -如果提供了 `error`，则会触发 `'error'` 事件，并将 `error` 作为参数传递给事件上的任何监听器。 +在接收到 `IncomingMessage` 的套接字上调用 `destroy()`。 + +如果提供了 `error`，则会在套接字上触发 `'error'` 事件，并将 `error` 作为参数传给该事件上的所有监听器。 diff --git a/modules/module_builtinmodules.md b/modules/module_builtinmodules.md index 2519ecda..8180c8bb 100644 --- a/modules/module_builtinmodules.md +++ b/modules/module_builtinmodules.md @@ -1,5 +1,8 @@ * {string[]} diff --git a/n-api/napi_add_finalizer.md b/n-api/napi_add_finalizer.md index e1e92371..6e038235 100644 --- a/n-api/napi_add_finalizer.md +++ b/n-api/napi_add_finalizer.md @@ -1,6 +1,7 @@ ```C diff --git a/n-api/napi_call_function.md b/n-api/napi_call_function.md index f843942c..a940622f 100644 --- a/n-api/napi_call_function.md +++ b/n-api/napi_call_function.md @@ -4,12 +4,12 @@ napiVersion: 1 --> ```C -napi_status napi_call_function(napi_env env, - napi_value recv, - napi_value func, - int argc, - const napi_value* argv, - napi_value* result) +NAPI_EXTERN napi_status napi_call_function(napi_env env, + napi_value recv, + napi_value func, + size_t argc, + const napi_value* argv, + napi_value* result); ``` * `[in] env`: The environment that the API is invoked under. diff --git a/n-api/napi_create_date.md b/n-api/napi_create_date.md index 6d43efe6..387c4b61 100644 --- a/n-api/napi_create_date.md +++ b/n-api/napi_create_date.md @@ -1,5 +1,6 @@ ```C diff --git a/n-api/napi_create_reference.md b/n-api/napi_create_reference.md index dfa7881a..b422cb76 100644 --- a/n-api/napi_create_reference.md +++ b/n-api/napi_create_reference.md @@ -6,7 +6,7 @@ napiVersion: 1 ```C NAPI_EXTERN napi_status napi_create_reference(napi_env env, napi_value value, - int initial_refcount, + uint32_t initial_refcount, napi_ref* result); ``` diff --git a/n-api/napi_get_date_value.md b/n-api/napi_get_date_value.md index 0d625b86..505c3bd7 100644 --- a/n-api/napi_get_date_value.md +++ b/n-api/napi_get_date_value.md @@ -1,5 +1,6 @@ ```C diff --git a/n-api/napi_is_date.md b/n-api/napi_is_date.md index 3c1da76c..ddee3217 100644 --- a/n-api/napi_is_date.md +++ b/n-api/napi_is_date.md @@ -1,5 +1,6 @@ ```C diff --git a/n-api/napi_make_callback.md b/n-api/napi_make_callback.md index 6af792f7..e9f57ed5 100644 --- a/n-api/napi_make_callback.md +++ b/n-api/napi_make_callback.md @@ -7,13 +7,13 @@ changes: --> ```C -napi_status napi_make_callback(napi_env env, - napi_async_context async_context, - napi_value recv, - napi_value func, - int argc, - const napi_value* argv, - napi_value* result) +NAPI_EXTERN napi_status napi_make_callback(napi_env env, + napi_async_context async_context, + napi_value recv, + napi_value func, + size_t argc, + const napi_value* argv, + napi_value* result); ``` * `[in] env`: The environment that the API is invoked under. diff --git a/n-api/napi_reference_ref.md b/n-api/napi_reference_ref.md index d49a8b51..86ee4b77 100644 --- a/n-api/napi_reference_ref.md +++ b/n-api/napi_reference_ref.md @@ -6,7 +6,7 @@ napiVersion: 1 ```C NAPI_EXTERN napi_status napi_reference_ref(napi_env env, napi_ref ref, - int* result); + uint32_t* result); ``` * `[in] env`: The environment that the API is invoked under. diff --git a/n-api/napi_reference_unref.md b/n-api/napi_reference_unref.md index 8222da1a..4d75e5bc 100644 --- a/n-api/napi_reference_unref.md +++ b/n-api/napi_reference_unref.md @@ -6,7 +6,7 @@ napiVersion: 1 ```C NAPI_EXTERN napi_status napi_reference_unref(napi_env env, napi_ref ref, - int* result); + uint32_t* result);); ``` * `[in] env`: The environment that the API is invoked under. diff --git a/n-api/return_values.md b/n-api/return_values.md index 7c33a627..f5103c3b 100644 --- a/n-api/return_values.md +++ b/n-api/return_values.md @@ -25,8 +25,8 @@ is provided which returns a `napi_extended_error_info` structure. The format of the `napi_extended_error_info` structure is as follows: ```C diff --git a/net/socket_buffersize.md b/net/socket_buffersize.md index d2c35774..d2fc5a39 100644 --- a/net/socket_buffersize.md +++ b/net/socket_buffersize.md @@ -4,8 +4,16 @@ added: v0.3.8 * {integer} -`net.Socket` 具有该属性，`socket.write()` 工作时需要。它可以帮助用户快速启动和运行。计算机（处理速度）不能总是跟上 socket 的写入速度。网络连接也可能太慢。 Node.js 内部将维护一个写入 socket 的数据队列，并在可能的时候将数据发送出去。（内部实现是对 socket 的文件描述符进行轮询其是否是可写状态。） +此属性显示为写入而缓冲的字符数。 +缓冲器中可能包含字符串，其编码后的长度是未知的。 +因此，此数字仅是缓冲器中字节数的近似值。 -使用内部缓冲的结果是可能造成内存的增长。此属性显示当前即将被写入的缓冲的字符数。（字符串的数目大致等于即将被写入的字节，但缓冲可能包含字符串，而字符串是惰性编码的，所以实际的字节数是不知道的。） +`net.Socket` 具有该属性时，则 `socket.write()` 始终可用。 +这是为了帮助用户快速启动并运行。 +计算机不能总是跟上写入套接字的数据量。 +网络连接也可能太慢。 +Node.js 将会在内部将写入套接字的数据进行排队，并在可能的情况下将其发送出去。 + +这种内部缓冲的结果是内存可能会增加。 +对于遇到 `bufferSize` 太大或不断增加的用户，应尝试使用 [`socket.pause()`] 和 [`socket.resume()`] 来对其程序中的数据流进行节流。 -对处理大量或持续增长的 `bufferSize` 有经验的用户应该注意使用 [`socket.pause()`][] 和 [`socket.resume()`][] 对他们程序中的数据流进行节流。 diff --git a/net/socket_connect_options_connectlistener.md b/net/socket_connect_options_connectlistener.md index 794beea8..34e880db 100644 --- a/net/socket_connect_options_connectlistener.md +++ b/net/socket_connect_options_connectlistener.md @@ -39,7 +39,9 @@ changes: 对于这两种类型，可用 `options` 包括： * `onread` {Object} 如果指定，则传入的数据会存储在单个 `buffer` 中，并在数据到达套接字时传给提供的 `callback`。 - 这将会导致流式的功能不会提供任何数据，但 `'error'`、`'end'` 和 `'close'` 等事件仍将会被正常触发，且 `pause()` 和 `resume()` 等方法也将会按预期运行。 + 这将会导致流式的功能不会提供任何数据。 + 该套接字将会正常触发 `'error'`、`'end'` 和 `'close'` 之类的事件。 + 诸如 `pause()` 和 `resume()` 之类的方法也将会按预期运行。 * `buffer` {Buffer|Uint8Array|Function} 用于存储传入数据的可复用的内存块、或返回此类数据的函数。 * `callback` {Function} 为每个传入的数据块调用此函数。有两个参数传给它：写入 `buffer` 的字节数和对 `buffer` 的引用。从此函数返回 `false` 可以隐式地 `pause()` 套接字。该函数将会在全局的上下文中执行。 diff --git a/perf_hooks/measuring_the_duration_of_async_operations.md b/perf_hooks/measuring_the_duration_of_async_operations.md index 4c662f43..3d6bdf79 100644 --- a/perf_hooks/measuring_the_duration_of_async_operations.md +++ b/perf_hooks/measuring_the_duration_of_async_operations.md @@ -1,6 +1,6 @@ The following example uses the [Async Hooks][] and Performance APIs to measure -the actual duration of a Timeout operation (including the amount of time it +the actual duration of a Timeout operation (including the amount of time it took to execute the callback). ```js diff --git a/process/process_send_message_sendhandle_options_callback.md b/process/process_send_message_sendhandle_options_callback.md index 77ef6430..a75840eb 100644 --- a/process/process_send_message_sendhandle_options_callback.md +++ b/process/process_send_message_sendhandle_options_callback.md @@ -12,7 +12,7 @@ added: v0.5.9 如果 Node.js 是使用 IPC 通道衍生的，则可以使用 `process.send()` 方法将消息发送到父进程。 消息将会作为父进程的 [`ChildProcess`] 对象上的 [`'message'`] 事件被接收。 -如果 Node.js 不是通过 IPC 通道衍生的，则 `process.send()` 将会是 `undefined`。 +如果 Node.js 不是通过 IPC 通道衍生的，则 `process.send` 将会是 `undefined`。 消息会进行序列化和解析。 生成的消息可能与最初发送的消息不同。 diff --git a/repl/global_uncaught_exceptions.md b/repl/global_uncaught_exceptions.md index e6eed7c1..39f065c3 100644 --- a/repl/global_uncaught_exceptions.md +++ b/repl/global_uncaught_exceptions.md @@ -6,13 +6,14 @@ changes: repl is used as standalone program. --> -REPL使用 [`domain`] 模块来捕获会话期间的所有未捕获异常。 +REPL 使用 [`domain`] 模块来捕获该 REPL 会话的所有未捕获的异常。 -在REPL中使用 [`domain`] 模块有如下副作用： +在 REPL 中对 [`domain`] 模块的这种使用具有以下的副作用： -* 如果将 `repl` 用作独立程序，则未捕获的异常仅触发 [`'uncaughtException'`] 事件。 - 如果 `repl` 包含在另一个应用程序的任何位置，则为此事件添加监听器将会抛出 [`ERR_INVALID_REPL_INPUT`] 异常。 -* 如果尝试使用 [`process.setUncaughtExceptionCaptureCallback()`] 将产生一个 [`ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE`] 错误。 +* 未捕获的异常仅在独立的 REPL 中触发 [`'uncaughtException'`] 事件。 + 在另一个 Node.js 程序的 REPL 中添加此事件的监听器会抛出 [`ERR_INVALID_REPL_INPUT`]。 + +* 尝试使用 [`process.setUncaughtExceptionCaptureCallback()`] 会抛出 [`ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE`] 错误。 作为独立程序： @@ -20,14 +21,15 @@ REPL使用 [`domain`] 模块来捕获会话期间的所有未捕获异常。 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 +// TypeError [ERR_INVALID_REPL_INPUT]: Listeners for `uncaughtException` +// cannot be used in the REPL throw new Error('foobar'); // 抛出: diff --git a/stream/api_for_stream_implementers.md b/stream/api_for_stream_implementers.md index 3a3408e2..2734e1fc 100644 --- a/stream/api_for_stream_implementers.md +++ b/stream/api_for_stream_implementers.md @@ -37,3 +37,7 @@ class MyWritable extends Writable { 流的实现代码应永远不要调用旨在供消费者使用的公共方法（详见[用于消费流的API][API for Stream Consumers]）。 这样做可能会导致消费流的应用程序代码产生不利的副作用。 +避免重写诸如 `write()`、`end()`、`cork()`、`uncork()`、`read()` 和 `destroy()` 之类的公共方法，或通过 `.emit()` 触发诸如 `'error'`、`'data'`、`'end'`、`'finish'` 和 `'close'` 之类的内部事件。 +这样做会破坏当前和未来的流的不变量，从而导致与其他流、流的实用工具、以及用户期望的行为和/或兼容性问题。 + + diff --git a/stream/readable_read_size.md b/stream/readable_read_size.md index 14486b92..ee14bfef 100644 --- a/stream/readable_read_size.md +++ b/stream/readable_read_size.md @@ -14,6 +14,8 @@ added: v0.9.4 如果没有指定 `size` 参数，则返回内部缓冲中的所有数据。 +`size` 参数必须小于或等于 1 GB。 + `readable.read()` 应该只对处于暂停模式的可读流调用。 在流动模式中，`readable.read()` 会自动调用直到内部缓冲的数据完全耗尽。 diff --git a/url/url_parse_urlstring_parsequerystring_slashesdenotehost.md b/url/url_parse_urlstring_parsequerystring_slashesdenotehost.md index b82169e3..66f17da0 100644 --- a/url/url_parse_urlstring_parsequerystring_slashesdenotehost.md +++ b/url/url_parse_urlstring_parsequerystring_slashesdenotehost.md @@ -1,6 +1,11 @@ -An implementation of the [WHATWG Encoding Standard][] `TextDecoder` API. +[WHATWG 编码标准][WHATWG Encoding Standard]的 `TextDecoder` API 的实现。 ```js const decoder = new TextDecoder('shift_jis'); @@ -11,6 +11,6 @@ let buffer; while (buffer = getNextChunkSomehow()) { string += decoder.decode(buffer, { stream: true }); } -string += decoder.decode(); // end-of-stream +string += decoder.decode(); // 流的末尾。 ``` diff --git a/util/class_util_textencoder.md b/util/class_util_textencoder.md index bb1810d4..457fb5cb 100644 --- a/util/class_util_textencoder.md +++ b/util/class_util_textencoder.md @@ -6,13 +6,13 @@ changes: description: The class is now available on the global object. --> -An implementation of the [WHATWG Encoding Standard][] `TextEncoder` API. All -instances of `TextEncoder` only support UTF-8 encoding. +[WHATWG 编码标准][WHATWG Encoding Standard] 的 `TextEncoder` API 的实现。 +`TextEncoder` 的所有实例仅支持 UTF-8 编码。 ```js const encoder = new TextEncoder(); -const uint8array = encoder.encode('this is some data'); +const uint8array = encoder.encode('这是一些数据'); ``` -The `TextEncoder` class is also available on the global object. +`TextEncoder` 类在全局对象上也可用。 diff --git a/util/custom_promisified_functions.md b/util/custom_promisified_functions.md index bc20389b..b63e0680 100644 --- a/util/custom_promisified_functions.md +++ b/util/custom_promisified_functions.md @@ -1,6 +1,5 @@ -Using the `util.promisify.custom` symbol one can override the return value of - +使用 `util.promisify.custom` 符号可以重写 [`util.promisify()`] 的返回值： ```js const util = require('util'); @@ -15,14 +14,12 @@ doSomething[util.promisify.custom] = (foo) => { const promisified = util.promisify(doSomething); console.log(promisified === doSomething[util.promisify.custom]); -// prints 'true' +// 打印 'true' ``` -This can be useful for cases where the original function does not follow the -standard format of taking an error-first callback as the last argument. +对于原始函数不遵循将错误优先的回调作为最后一个参数的标准格式的情况，这很有用。 -For example, with a function that takes in -`(foo, onSuccessCallback, onErrorCallback)`: +例如，使用一个接受 `(foo, onSuccessCallback, onErrorCallback)` 的函数: ```js doSomething[util.promisify.custom] = (foo) => { @@ -32,6 +29,5 @@ doSomething[util.promisify.custom] = (foo) => { }; ``` -If `promisify.custom` is defined but is not a function, `promisify()` will -throw an error. +如果定义了 `promisify.custom` 但不是一个函数，则 `promisify()` 将会抛出错误。 diff --git a/util/util_promisify_custom.md b/util/util_promisify_custom.md index c91f0c95..ffbc3d88 100644 --- a/util/util_promisify_custom.md +++ b/util/util_promisify_custom.md @@ -2,6 +2,5 @@ added: v8.0.0 --> -* {symbol} that can be used to declare custom promisified variants of functions, -see [Custom promisified functions][]. +* {symbol} 可用于声明函数的自定义的 promise 化变量，参阅[自定义的 promise 化函数][Custom promisified functions]。 diff --git a/util/util_promisify_original.md b/util/util_promisify_original.md index 040126ee..903037a5 100644 --- a/util/util_promisify_original.md +++ b/util/util_promisify_original.md @@ -5,7 +5,7 @@ added: v8.0.0 * `original` {Function} * 返回: {Function} -让一个遵循异常优先的回调风格的函数，即 `(err, value) => ...` 回调函数是最后一个参数，返回一个返回值是一个 promise 版本的函数。 +传入一个遵循常见的错误优先的回调风格的函数（即以 `(err, value) => ...` 回调作为最后一个参数），并返回一个返回 promise 的版本。 ```js const util = require('util'); @@ -13,13 +13,13 @@ const fs = require('fs'); const stat = util.promisify(fs.stat); stat('.').then((stats) => { - // 处理 `stats`。 + // 使用 `stats`。 }).catch((error) => { // 处理错误。 }); ``` -或者，使用 `async function` 获得等效的效果: +或者，等效地使用 `async function`: ```js const util = require('util'); @@ -29,14 +29,40 @@ const stat = util.promisify(fs.stat); async function callStat() { const stats = await stat('.'); - console.log(`该目录的所有者是 ${stats.uid}`); + console.log(`该目录归 ${stats.uid} 拥有`); } ``` -如果原本就有 `original[util.promisify.custom]` 属性，`promisify` 会返回它的值，详见[自定义的 promise 化函数][Custom promisified functions]。 +如果存在 `original[util.promisify.custom]` 属性，则 `promisify` 将会返回其值，参阅[自定义的 promise 化函数][Custom promisified functions]。 -`promisify()` 会在所有情况下假定 `original` 是一个最后的参数是回调函数的函数。 -如果 `original` 不是函数，则 `promisify()` 将会抛出错误。 -如果 `original` 是一个函数但它的最后一个参数不是错误优先回调，它仍然会传递一个错误优先回调作为它的最后一个参数。 +`promisify()` 在所有情况下都会假定 `original` 是一个以回调作为其最后参数的函数。 +如果 `original` 不是一个函数，则 `promisify()` 将会抛出错误。 +如果 `original` 是一个函数但其最后一个参数不是一个错误优先的回调，则它将仍会传入一个错误优先的回调作为其最后一个参数。 +除非特殊处理，否则在类方法或使用 `this` 的其他方法上使用 `promisify()` 可能无法正常工作： + +```js +const util = require('util'); + +class Foo { + constructor() { + this.a = 42; + } + + bar(callback) { + callback(null, this.a); + } +} + +const foo = new Foo(); + +const naiveBar = util.promisify(foo.bar); +// TypeError: Cannot read property 'a' of undefined +// naiveBar().then(a => console.log(a)); + +naiveBar.call(foo).then((a) => console.log(a)); // '42' + +const bindBar = naiveBar.bind(foo); +bindBar().then((a) => console.log(a)); // '42' +``` diff --git a/v8/serialization_api.md b/v8/serialization_api.md index e2acb2d5..aeb11e17 100644 --- a/v8/serialization_api.md +++ b/v8/serialization_api.md @@ -1,10 +1,5 @@ -> Stability: 1 - Experimental - The serialization API provides means of serializing JavaScript values in a way that is compatible with the [HTML structured clone algorithm][]. The format is backward-compatible (i.e. safe to store to disk). -This API is under development, and changes (including incompatible -changes to the API or wire format) may occur until this warning is removed. -