Node-API Data Types and APIs

Data Types

napi_status

Enum indicating the success or failure of a Node-API call.

typedef enum {
    napi_ok,
    napi_invalid_arg,
    napi_object_expected,
    napi_string_expected,
    napi_name_expected,
    napi_function_expected,
    napi_number_expected,
    napi_boolean_expected,
    napi_array_expected,
    napi_generic_failure,
    napi_pending_exception,
    napi_cancelled,
    napi_escape_called_twice,
    napi_handle_scope_mismatch,
    napi_callback_scope_mismatch,
    napi_queue_full,
    napi_closing,
    napi_bigint_expected,
    napi_date_expected,
    napi_arraybuffer_expected,
    napi_detachable_arraybuffer_expected,
    napi_would_deadlock, /* unused */
    napi_no_external_buffers_allowed,
    napi_cannot_run_js
} napi_status;

napi_extended_error_info

Struct that holds detailed error information when a Node-API call fails.

typedef struct {
    const char *error_message;
    void *engine_reserved;
    uint32_t engine_error_code;
    napi_status error_code;
} napi_extended_error_info;

napi_value

Pointer used to represent a JavaScript (JS) value.

napi_env

• Context used by the underlying Node-API implementation. It is passed to the native functions when they are invoked, and must be passed back when Node-API calls are made.

• The napi_env becomes invalid when an instance of the native addon is unloaded. A notification of this event is sent through the callbacks given to napi_add_env_cleanup_hook and napi_set_instance_data.

• Avoid caching napi_env or passing napi_env between instances of the same addon running on different worker threads.

napi_threadsafe_function

Pointer that represents a JS function that can be called asynchronously from multiple threads. It can be used to pass the asynchronous operation result to the JS environment, such as reading data from another thread or performing compute-intensive operations. In addition, it can be used to call functions in C++ code from a JS environment for execution in another thread. By using napi_threadsafe_function, you can implement efficient interaction between JS and C++ code while maintaining thread safety.

napi_threadsafe_function_release_mode

Enum that indicates when to release the thread-safe function.

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

Its value is passed to napi_release_threadsafe_function.

napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• If the value is napi_tsfn_release, the current thread will not call this thread-safe function.

• If the value is napi_tsfn_abort, only the current thread can call this thread-safe function. In this case, using napi_call_threadsafe_function to call this function will return napi_closing, and this function will not be placed in the queue.

napi_threadsafe_function_call_mode

Enum that indicates whether the call should be blocked when the queue associated with the thread-safe function is full.

The data struct is as follows:

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

• napi_tsfn_nonblocking: Leave napi_call_threadsafe_function unblocked. If the queue is full, napi_queue_full is returned to prevent data from being added to the queue.

• napi_tsfn_blocking: Block napi_call_threadsafe_function until there is available space in the queue.

Memory Management Types

Node-API provides the following memory management types:

napi_handle_scope

Data used to manage the lifecycle of JS objects. It allows JS objects to remain active within a certain range for use in JS code. When napi_handle_scope is created, all JS objects created in this range remain active until the end. This can prevent released objects from being used in JS code, which improves code reliability and performance.

napi_escapable_handle_scope

• It is created by napi_open_escapable_handle_scope and closed by napi_close_escapable_handle_scope.

• It is a special type of handle range used to return values created within the scope of escapable_handle_scope to a parent scope.

• You can use napi_escape_handle to promote escape_handle_scope to a JS object so that it is valid for the lifetime of the outer scope.

napi_ref

Reference to napi_value, which allows you to manage the lifecycle of JS values.

napi_type_tag

Struct containing two unsigned 64-bit integers to identify the type of a Node-API value.

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag;

• It is a 128-bit value stored as two unsigned 64-bit integers. It is used to tag JS objects to ensure that they are of a certain type.

• This is a stronger check than napi_instanceof because napi_instanceof may report a false positive if the object's prototype is manipulated.

• The combination of type_tag and napi_wrap is useful because it ensures that the pointer retrieved from a wrapped object can be safely converted to the native type corresponding to the type tag that had been previously applied to the JS object.

napi_async_cleanup_hook_handle

Value used to register a callback for an asynchronous operation. It is mainly used to perform a cleanup operation when an asynchronous operation is complete or canceled, for example, releasing a resource or canceling an operation. Using napi_async_cleanup_hook_handle ensures that related resources are correctly released and cleaned up when an asynchronous operation is complete or canceled, thereby avoiding problems such as memory leakage.

Callback Types

Node-API provides the following callback types:

napi_callback_info

Data type passed to napi_get_cb_info to obtain JS input parameters.

napi_callback

User-defined native function, which is exposed to JS via Node-API. Generally, no handle or callback scope is created inside this callback.

The basic usage is as follows:

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);

napi_finalize

Function pointer passed to napi_create_threadsafe_function and napi_set_instance_data. napi_finalize is called when an object is reclaimed.

napi_async_execute_callback

Function pointer used in napi_create_async_work.

• An asynchronous native function is called from a worker pool thread and can be executed in parallel with the main event loop thread.

• Avoid making Node-API calls that execute JS code or interact with JS objects when implementing this callback.

• Node-API calls should be executed in napi_async_complete_callback.

napi_async_complete_callback

Function pointer used when an asynchronous operation is complete. It is usually used in C++ addon development of Node.js. When an asynchronous operation is required, you can use napi_create_async_work to create an asynchronous operation work object and specify a napi_async_complete_callback callback. When the asynchronous operation is complete, the callback is automatically called for subsequent processing. Parameters of the callback include the status of the asynchronous operation and a return value, based on which corresponding processing can be performed.

napi_threadsafe_function_call_js

Function pointer used in the main thread to interact with the JS code in an independent thread to implement more complex scenarios. It is used in napi_create_threadsafe_function(napi_env env, ..., napi_threadsafe_function_call_js call_js_cb, ...).

napi_cleanup_hook

Function pointer used with napi_add_env_cleanup_hook. It will be called when the environment is destroyed.

napi_async_cleanup_hook

Function pointer used with napi_add_async_cleanup_hook. It will be called when the environment is destroyed.

QoS

Enum indicating the thread scheduling priority.

typedef enum {
  napi_qos_background = 0,
  napi_qos_utility = 1,
  napi_qos_default = 2,
  napi_qos_user_initiated = 3,
} napi_qos_t;

APIs

Node-API is extended based on the native modules provided by Node.js. The following lists the APIs supported currently.

Asynchronous Thread-Safe APIs

Buffer

String

Date

ArrayBuffer

Module

Lifecycle Management

Promise

Array

Primitives

Class

Object

BigInt

Exceptions and Errors

Property

Asynchronous Works

Custom Asynchronous Operations

Comparing JS Values

UV

Function Invocation

Extension

napi_queue_async_work_with_qos

napi_status napi_queue_async_work_with_qos(napi_env env,
                                           napi_async_work work,
                                           napi_qos_t qos);

This API has the same usage as napi_queue_async_work. The difference is you can specify the QoS for the work to run.

napi_run_script_path

napi_status napi_run_script_path(napi_env env,
                                 const char* abcPath,
                                 napi_value* result);

napi_load_module

napi_status napi_load_module(napi_env env,
                             const char* path,
                             napi_value* result);

napi_create_object_with_properties

napi_status napi_create_object_with_properties(napi_env env,
                                               napi_value* result,
                                               size_t property_count,
                                               const napi_property_descriptor* properties);

napi_create_object_with_named_properties

napi_status napi_create_object_with_named_properties(napi_env env,
                                                     napi_value* result,
                                                     size_t property_count,
                                                     const char** keys,
                                                     const napi_value* values);

napi_coerce_to_native_binding_object

napi_status napi_coerce_to_native_binding_object(napi_env env,
                                                 napi_value js_object,
                                                 napi_native_binding_detach_callback detach_cb,
                                                 napi_native_binding_attach_callback attach_cb,
                                                 void* native_object,
                                                 void* hint);  

Environment Lifecycle

Object Lifetime Management

Other Utilities