Promise

【Promises】

Node-API 提供了用于创建 Promise 对象的功能，如 ECMA 规范的 Promise 对象部分 所述。它将 Promise 实现为一对对象。当通过 napi_create_promise() 创建一个 Promise 时，会创建一个“延迟”（deferred）对象，并与 Promise 一起返回。延迟对象绑定到创建的 Promise，并且是使用 napi_resolve_deferred() 或 napi_reject_deferred() 唯一可以解决或拒绝 Promise 的方式。通过 napi_create_promise() 创建的延迟对象会被 napi_resolve_deferred() 或 napi_reject_deferred() 释放。Promise 对象可以返回给 JavaScript，在那里可以以通常的方式使用它。

【Node-API provides facilities for creating Promise objects as described in Section Promise objects of the ECMA specification. It implements promises as a pair of objects. When a promise is created by napi_create_promise(), a "deferred" object is created and returned alongside the Promise. The deferred object is bound to the created Promise and is the only means to resolve or reject the Promise using napi_resolve_deferred() or napi_reject_deferred(). The deferred object that is created by napi_create_promise() is freed by napi_resolve_deferred() or napi_reject_deferred(). The Promise object may be returned to JavaScript where it can be used in the usual fashion.】

例如，要创建一个 promise 并将其传递给异步 worker：

【For example, to create a promise and pass it to an asynchronous worker:】

napi_deferred deferred;
napi_value promise;
napi_status status;

// Create the promise.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// Pass the deferred to a function that performs an asynchronous action.
do_something_asynchronous(deferred);

// Return the promise to JS
return promise; 拷贝

上述函数 do_something_asynchronous() 会执行其异步操作，然后它会解决或拒绝延迟对象，从而结束该 Promise 并释放延迟对象：

【The above function do_something_asynchronous() would perform its asynchronous action and then it would resolve or reject the deferred, thereby concluding the promise and freeing the deferred:】

napi_deferred deferred;
napi_value undefined;
napi_status status;

// Create a value with which to conclude the deferred.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// Resolve or reject the promise associated with the deferred depending on
// whether the asynchronous action succeeded.
if (asynchronous_action_succeeded) {
  status = napi_resolve_deferred(env, deferred, undefined);
} else {
  status = napi_reject_deferred(env, deferred, undefined);
}
if (status != napi_ok) return NULL;

// At this point the deferred has been freed, so we should assign NULL to it.
deferred = NULL; 拷贝