Promise

Class Napi::Promise inherits from class Napi::Object.

The Napi::Promise class, along with its Napi::Promise::Deferred class, implement the ability to create, resolve, and reject Promise objects.

The basic approach is to create a Napi::Promise::Deferred object and return to your caller the value returned by the Napi::Promise::Deferred::Promise method. For example:

Napi::Value YourFunction(const Napi::CallbackInfo& info) {
  // your code goes here...
  Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(info.Env());
  // deferred needs to survive this call...
  return deferred.Promise();
}

Later, when the asynchronous process completes, call either the Resolve or Reject method on the Napi::Promise::Deferred object created earlier:

  deferred.Resolve(String::New(info.Env(), "OK"));

Promise::Deferred Methods

Factory Method

static Napi::Promise::Deferred Napi::Promise::Deferred::New(napi_env env);

• [in] env: The napi_env environment in which to create the Napi::Promise::Deferred object.

Constructor

Napi::Promise::Deferred(napi_env env);

• [in] env: The napi_env environment in which to construct the Napi::Promise::Deferred object.

Env

Napi::Env Napi::Promise::Deferred::Env() const;

Returns the Env environment this Napi::Promise::Deferred object is associated with.

Promise

Napi::Promise Napi::Promise::Deferred::Promise() const;

Returns the Napi::Promise object held by the Napi::Promise::Deferred object.

Resolve

void Napi::Promise::Deferred::Resolve(napi_value value) const;

Resolves the Napi::Promise object held by the Napi::Promise::Deferred object.

• [in] value: The Node-API primitive value with which to resolve the Napi::Promise.

Reject

void Napi::Promise::Deferred::Reject(napi_value value) const;

Rejects the Promise object held by the Napi::Promise::Deferred object.

• [in] value: The Node-API primitive value with which to reject the Napi::Promise.

Promise Methods

Then

Napi::Promise Napi::Promise::Then(napi_value onFulfilled) const;
Napi::Promise Napi::Promise::Then(const Function& onFulfilled) const;

Attaches a fulfillment handler to the promise and returns a new promise.

Parameters:

• [in] onFulfilled: The fulfillment handler for the promise. May be any of:
  • napi_value – a JavaScript function to be called when the promise is fulfilled.
  • const Function& – the Napi::Function to be called when the promise is fulfilled.

Returns: A new Napi::Promise that resolves or rejects based on the handler's result.

Then

Napi::Promise Napi::Promise::Then(napi_value onFulfilled, napi_value onRejected) const;
Napi::Promise Napi::Promise::Then(const Function& onFulfilled,
                                  const Function& onRejected) const;

Attaches a fulfillment and rejection handlers to the promise and returns a new promise.

Parameters:

• [in] onFulfilled: The fulfillment handler for the promise. May be any of:
  • napi_value – a JavaScript function to be called when the promise is fulfilled.
  • const Function& – the Napi::Function to be called when the promise is fulfilled.
• [in] onRejected (optional): The rejection handler for the promise. May be any of:
  • napi_value – a JavaScript function to be called when the promise is rejected.
  • const Function& – the Napi::Function to be called when the promise is rejected.

Catch

Napi::Promise Napi::Promise::Catch(napi_value onRejected) const;
Napi::Promise Napi::Promise::Catch(const Function& onRejected) const;

Attaches a rejection handler to the promise and returns a new promise.

Parameters:

• [in] onRejected: The rejection handler for the promise. May be any of:
  • napi_value – a JavaScript function to be called when the promise is rejected.
  • const Function& – the Napi::Function to be called when the promise is rejected.

Returns: A new Napi::Promise that handles rejection cases.