node-addon-api

Napi::ObjectReference is a subclass of Napi::Reference that specifically holds a Napi::Object. It maintains a reference count for the held object; as long as this count is greater than 0, the object is protected from garbage collection.

Unlike a standard Napi::Reference, an ObjectReference allows you to directly Set and Get properties on the underlying object through the reference itself.

#include <napi.h>

using namespace Napi;

void Init(Env env) {
    // Create an empty ObjectReference that has an initial reference count of 2.
    ObjectReference obj_ref = Reference<Object>::New(Object::New(env), 2);

    // Set a couple of different properties on the reference.
    obj_ref.Set("hello", String::New(env, "world"));
    obj_ref.Set(42, "The Answer to Life, the Universe, and Everything");

    // Get the properties using the keys.
    Value val1 = obj_ref.Get("hello");
    Value val2 = obj_ref.Get(42);
}

Overview

Napi::AsyncWorker is an abstract class used to move data and perform tasks between the Node.js event loop and worker threads. It handles the complexities of thread management and asynchronous execution.

Lifecycle

1. Creation: Subclass Napi::AsyncWorker and provide a callback function (which runs on the main thread).
2. Queueing: Call Napi::AsyncWorker::Queue() to request execution.
3. Execution: When a thread is available, Napi::AsyncWorker::Execute() is invoked on a libuv worker thread.
   • CRITICAL: You must NOT call any node-addon-api methods or any code that invokes JavaScript inside Execute(), as it is not running on the main event loop.
4. Completion: Once Execute() finishes, either Napi::AsyncWorker::OnOK() or Napi::AsyncWorker::OnError() is invoked on the main thread.
5. Destruction: After the completion methods finish, the Napi::AsyncWorker instance is automatically destructed (unless SuppressDestruct() was called).

When C++ exceptions are enabled, Napi::Error extends std::exception. This allows you to use standard try/catch blocks to manage both C++ and JavaScript exceptions.

• Automatic Conversion: If a Node-API call fails (e.g., invalid arguments) or a JavaScript function called from C++ throws, node-addon-api automatically converts these into Napi::Error C++ exceptions.
• Propagation: If an Napi::Error escapes a native callback, it is automatically converted into a JavaScript exception when returning to the JS environment.
• Dependency Behavior:
  • Using node_addon_api_except: Only Napi::Error objects are handled.
  • Using node_addon_api_except_all: All exceptions are handled. std::exception derivatives use their what() message; others use a generic message.

// Throwing a C++ exception
Env env = ...
throw Napi::Error::New(env, "Example exception");

// Propagating a Node-API C++ exception (JS function call)
Napi::Function jsFunctionThatThrows = someValue.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });

// Handling a Node-API C++ exception
try {
    result = jsFunctionThatThrows({ arg1, arg2 });
} catch (const Error& e) {
    cerr << "Caught JavaScript exception: " + e.what();
}

Concept

Napi::AsyncProgressWorker is an abstract class used to perform heavy tasks on a libuv worker thread while providing a mechanism to report progress back to the JavaScript event loop. It extends Napi::AsyncWorker by internally using Napi::ThreadSafeFunction to bridge the worker thread and the main event loop.

Lifecycle

1. Creation: Instantiate a subclass of Napi::AsyncProgressWorker.
2. Queueing: Call Napi::AsyncProgressWorker::Queue to request execution.
3. Execution: The Execute method runs on a background thread. During this phase, you can call ExecutionProgress::Send to report progress.
4. Progress Reporting: ExecutionProgress::Send triggers OnProgress on the main JavaScript thread. Note that multiple Send calls might be coalesced into a single OnProgress invocation.
5. Completion: Once Execute finishes, either OnOK or OnError is invoked on the main thread.
6. Destruction: The instance is destructed after OnOK or OnError completes.

Implementation Requirements

For a basic implementation, you must override:

• Execute(const ExecutionProgress& progress): The background task logic.
• OnProgress(const T* data, size_t count): The logic to handle progress updates on the main thread.

Warning: Inside Execute, you must not call any node-addon-api methods or any code that invokes JavaScript, as it runs on a thread other than the main event loop. Use OnOK or OnError for JavaScript interactions after the task completes.

If C++ exceptions are enabled (NAPI_CPP_EXCEPTIONS), you can iterate over an object's enumerable properties using iterators. Iterators yield an std::pair where .first is the Napi::Value key and .second is a Napi::Object::PropertyLValue value.

Constant Iterator (const_iterator)

• Iterated values are immutable.
• Use for read-only traversal.

Non-Constant Iterator (iterator)

• Iterated values are mutable.
• Allows you to modify the values of properties during iteration.

Example: Summing numeric values in an object

Value Sum(const CallbackInfo& info) {
  Object object = info[0].As<Object>();
  int64_t sum = 0;

  for (const auto& e : object) {
    sum += static_cast<Value>(e.second).As<Number>().Int64Value();
  }

  return Number::New(info.Env(), sum);
}

Example: Incrementing values in an object

void Increment(const CallbackInfo& info) {
  Env env = info.Env();
  Object object = info[0].As<Object>();

  for (auto e : object) {
    int64_t value = static_cast<Value>(e.second).As<Number>().Int64Value();
    ++value;
    e.second = Napi::Number::New(env, value);
  }
}