Node-API

[安定版: 2 - 安定版]

安定版: 2 安定性: 2 - 安定版

Node-API（旧称 N-API）は、ネイティブアドオンを構築するための API です。基盤となる JavaScript ランタイム（例：V8）とは独立しており、Node.js 自体の一部として保守されています。この API は、Node.js のバージョン間でアプリケーションバイナリインタフェース（ABI）の安定性を維持します。これは、基盤となる JavaScript エンジンの変更からアドオンを保護し、あるメジャーバージョン用にコンパイルされたモジュールを、再コンパイルせずに Node.js の後のメジャーバージョンで実行できるようにすることを目的としています。ABI の安定性ガイドでは、より詳細な説明を提供しています。

アドオンは、C++アドオンというセクションで概説されているのと同じ方法/ツールで構築/パッケージ化されます。唯一の違いは、ネイティブコードで使用される API のセットです。V8 またはNode.js ネイティブ抽象化 API を使用する代わりに、Node-API で使用可能な関数が使用されます。

Node-API によって公開される API は、一般的に JavaScript 値の作成と操作に使用されます。概念と操作は、一般的に ECMA-262 言語仕様で指定されたアイデアにマップされます。API には次の特性があります。

• すべての Node-API 呼び出しは、napi_status型のステータスコードを返します。このステータスは、API 呼び出しが成功したか失敗したかを示します。
• API の戻り値は、出力パラメーターを介して渡されます。
• すべての JavaScript 値は、napi_valueという不透明な型で抽象化されます。
• エラーステータスコードの場合、napi_get_last_error_infoを使用して追加情報を得ることができます。詳細については、エラー処理セクションエラー処理を参照してください。

Node-API は、Node.js のバージョンと異なるコンパイラーレベル間で ABI の安定性を確保する C API です。C++ API の方が使いやすいかもしれません。C++の使用をサポートするために、プロジェクトはnode-addon-apiという C++ラッパーモジュールを維持していますhttps://github.com/nodejs/node-addon-api。このラッパーは、インライン可能な C++ API を提供します。node-addon-apiで構築されたバイナリは、Node.js によってエクスポートされる Node-API C ベースの関数のシンボルに依存します。node-addon-apiは、Node-API を呼び出すコードを記述するためのより効率的な方法です。例えば、以下のnode-addon-apiコードを考えてみましょう。最初のセクションはnode-addon-apiコードを示し、2 番目のセクションはアドオンで実際に使用されるものを示しています。

Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");

napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

最終的な結果は、アドオンがエクスポートされた C API のみを使用することです。その結果、C API によって提供される ABI 安定性のメリットを依然として得ることができます。

C API ではなくnode-addon-apiを使用する場合は、node-addon-apiの API ドキュメントから始めましょう。

Node-API リソースは、Node-API とnode-addon-apiを初めて使用する開発者にとって優れたオリエンテーションとヒントを提供します。追加のメディアリソースは、Node-API メディアページにあります。

ABI 安定性の影響

Node-API は ABI 安定性の保証を提供しますが、Node.js の他の部分は提供しません。また、アドオンから使用される外部ライブラリも提供しない場合があります。特に、以下の API のいずれも、メジャーバージョン間で ABI 安定性の保証を提供しません。

• 以下のいずれかから利用可能な Node.js C++ API
• Node.js にも含まれており、以下から利用可能な libuv API
• 以下から利用可能な V8 API

したがって、アドオンが Node.js のメジャーバージョン間で ABI 互換性を維持するには、

#include <node_api.h>

を制限することで、Node-API を排他的に使用し、使用するすべての外部ライブラリについて、その外部ライブラリが Node-API と同様の ABI 安定性の保証を提供していることを確認する必要があります。

ビルド

JavaScript で記述されたモジュールとは異なり、Node-API を使用した Node.js ネイティブアドオンの開発と展開には、追加のツールセットが必要です。Node.js の開発に必要な基本的なツールに加えて、ネイティブアドオン開発者には、C および C++コードをバイナリにコンパイルできるツールチェーンが必要です。さらに、ネイティブアドオンの展開方法によっては、ネイティブアドオンのユーザーも C/C++ツールチェーンをインストールする必要があります。

Linux 開発者にとって、必要な C/C++ツールチェーンパッケージは容易に入手できます。GCCは、さまざまなプラットフォームでビルドとテストを行う Node.js コミュニティで広く使用されています。多くの開発者にとって、LLVMコンパイラインフラストラクチャも優れた選択肢です。

Mac 開発者にとって、Xcodeは必要なすべてのコンパイラツールを提供します。ただし、Xcode IDE 全体をインストールする必要はありません。以下のコマンドで必要なツールチェーンをインストールします。

xcode-select --install

Windows 開発者にとって、Visual Studioは必要なすべてのコンパイラツールを提供します。ただし、Visual Studio IDE 全体をインストールする必要はありません。以下のコマンドで必要なツールチェーンをインストールします。

npm install --global windows-build-tools

以下のセクションでは、Node.js ネイティブアドオンの開発と展開に使用できる追加ツールについて説明します。

ビルドツール

ここに記載されている両方のツールを使用するには、ネイティブアドオンのユーザーが C/C++ツールチェーンをインストールしている必要があります。ネイティブアドオンを正常にインストールするには、これが必須です。

node-gyp

node-gypは、Google のGYPツールのgyp-nextフォークに基づいたビルドシステムであり、npm にバンドルされています。GYP、したがって node-gyp は、Python がインストールされていることを要求します。

従来、node-gyp はネイティブアドオンをビルドするためのツールとして選ばれてきました。広く採用され、ドキュメントも充実しています。しかし、一部の開発者は node-gyp の限界に遭遇しています。

CMake.js

CMake.jsは、CMakeに基づいた代替ビルドシステムです。

CMake.js は、既に CMake を使用しているプロジェクトまたは node-gyp の制限の影響を受ける開発者にとって良い選択肢です。build_with_cmakeは、CMake ベースのネイティブアドオンプロジェクトの例です。

事前コンパイル済みバイナリのアップロード

ここに記載されている 3 つのツールにより、ネイティブアドオンの開発者とメンテナーは、パブリックまたはプライベートサーバーにバイナリを作成してアップロードできます。これらのツールは、通常、Travis CIやAppVeyorなどの CI/CD ビルドシステムと統合され、さまざまなプラットフォームとアーキテクチャのバイナリをビルドしてアップロードします。これらのバイナリは、C/C++ツールチェーンをインストールする必要のないユーザーがダウンロードできます。

node-pre-gyp

node-pre-gypは、node-gyp に基づいたツールであり、開発者が選択したサーバーにバイナリをアップロードする機能を追加します。node-pre-gyp は、Amazon S3 へのバイナリのアップロードを特に良くサポートしています。

prebuild

prebuildは、node-gyp または CMake.js を使用したビルドをサポートするツールです。さまざまなサーバーをサポートする node-pre-gyp とは異なり、prebuild はバイナリをGitHub リリースのみにアップロードします。prebuild は、CMake.js を使用する GitHub プロジェクトにとって良い選択肢です。

prebuildify

prebuildifyは、node-gyp をベースとしたツールです。prebuildify の利点は、ビルドされたバイナリが npm にアップロードされた際にネイティブアドオンにバンドルされることです。バイナリは npm からダウンロードされ、ネイティブアドオンがインストールされると、モジュールユーザーはすぐに利用できます。

使い方

Node-API 関数を使用するには、Node 開発ツリーの src ディレクトリにあるファイルnode_api.hを含めます。

#include <node_api.h>

これにより、指定された Node.js のリリースに対してデフォルトのNAPI_VERSIONが選択されます。特定のバージョンの Node-API との互換性を確保するために、ヘッダーを含める際にバージョンを明示的に指定できます。

#define NAPI_VERSION 3
#include <node_api.h>

これにより、Node-API のサーフェスは、指定された（およびそれ以前の）バージョンで使用可能な機能のみに制限されます。

Node-API サーフェスのいくつかは実験的なものであり、明示的なオプトインが必要です。

#define NAPI_EXPERIMENTAL
#include <node_api.h>

この場合、実験的な API を含むすべての API サーフェスがモジュールコードで使用可能になります。

時々、既にリリースされ安定した API に影響を与える実験的な機能が導入されます。これらの機能はオプトアウトで無効にできます。

#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>

ここで\<FEATURE_NAME\>は、実験的な API と安定した API の両方に影響を与える実験的機能の名前です。

Node-API バージョンマトリックス

バージョン 9 までは、Node-API バージョンは加算的であり、Node.js とは独立してバージョン管理されていました。これは、任意のバージョンが前のバージョンの拡張であり、前のバージョンからのすべての API に追加が加えられていたことを意味します。各 Node.js バージョンは、単一の Node-API バージョンのみをサポートしていました。たとえば、v18.15.0 は Node-API バージョン 8 のみをサポートしています。ABI の安定性は、8 が以前のすべてのバージョンの厳密な上位集合であったため達成されました。

バージョン 9 以降、Node-API バージョンは引き続き独立してバージョン管理されていますが、Node-API バージョン 9 で動作したアドオンは、Node-API バージョン 10 で動作させるためにコードの更新が必要になる場合があります。ただし、Node-API バージョン 8 より高いバージョンをサポートする Node.js バージョンは、8 とサポートする最高バージョンの間のすべてのバージョンをサポートし、アドオンがより高い Node-API バージョンを選択しない限り、バージョン 8 の API を提供することをデフォルトとするため、ABI の安定性は維持されます。このアプローチにより、既存の Node-API 関数を最適化しながら、ABI の安定性を維持する柔軟性が提供されます。既存のアドオンは、以前のバージョンの Node-API を使用して再コンパイルせずに実行し続けることができます。アドオンが新しい Node-API バージョンの機能を必要とする場合、既存のコードの変更と再コンパイルが必要になります。

Node-API バージョン 9 以降をサポートする Node.js バージョンでは、NAPI_VERSION=Xを定義し、既存のアドオン初期化マクロを使用すると、実行時に使用される要求された Node-API バージョンがアドオンに組み込まれます。NAPI_VERSIONが設定されていない場合、デフォルトで 8 になります。

この表は古いストリームでは最新ではない可能性があります。最新の情報は、最新の API ドキュメントにあります：Node-API バージョンマトリックス

Node-API バージョン	サポート対象
9	v18.17.0+、20.3.0+、21.0.0 およびそれ以降のバージョン
8	v12.22.0+、v14.17.0+、v15.12.0+、16.0.0 およびそれ以降のバージョン
7	v10.23.0+、v12.19.0+、v14.12.0+、15.0.0 およびそれ以降のバージョン
6	v10.20.0+、v12.17.0+、14.0.0 およびそれ以降のバージョン
5	v10.17.0+、v12.11.0+、13.0.0 およびそれ以降のバージョン
4	v10.16.0+、v11.8.0+、12.0.0 およびそれ以降のバージョン
3	v6.14.2*、8.11.2+、v9.11.0+*、10.0.0 およびそれ以降のバージョン
2	v8.10.0+、v9.3.0+、10.0.0 およびそれ以降のバージョン
1	v8.6.0+*、v9.0.0+、10.0.0 およびそれ以降のバージョン

• Node-API は実験的でした。

** Node.js 8.0.0 は Node-API を実験的なものとして含んでいました。Node-API バージョン 1 としてリリースされましたが、Node.js 8.6.0 まで進化し続けました。Node.js 8.6.0 より前のバージョンでは API が異なります。Node-API バージョン 3 以降を推奨します。

Node-API について記述されている各 API には、added in:という名前のヘッダーがあり、安定した API にはNode-API version:という追加のヘッダーがあります。API は、Node-API version:に示されている Node-API バージョン以上をサポートする Node.js バージョンを使用する場合に直接使用できます。Node-API version:にリストされている Node-API バージョンをサポートしていない Node.js バージョンを使用する場合、またはNode-API version:がない場合は、#define NAPI_EXPERIMENTALがnode_api.hまたはjs_native_api.hのインクルードの前にある場合にのみ API が使用できます。added in:に示されているものより後の Node.js バージョンで API が使用できないように見える場合、それがその理由である可能性が高いです。

ネイティブコードから ECMAScript 機能にアクセスすることに厳密に関連する Node-API は、js_native_api.hとjs_native_api_types.hで個別に確認できます。これらのヘッダーで定義されている API は、node_api.hとnode_api_types.hに含まれています。ヘッダーはこのように構成されているのは、Node.js 以外で Node-API を実装できるようにするためです。それらの実装では、Node.js 固有の API は適用されない場合があります。

アドオンの Node.js 固有の部分は、JavaScript 環境に実際の機能を公開するコードから分離できます。これにより、後者は Node-API の複数の実装で使用できます。以下の例では、addon.cとaddon.hはjs_native_api.hのみを参照しています。これにより、addon.cを再利用して、Node.js の実装の Node-API または Node.js 以外の Node-API の実装のいずれに対してもコンパイルできます。

addon_node.cは、アドオンへの Node.js 固有のエントリポイントを含み、アドオンが Node.js 環境にロードされるとaddon.cを呼び出してアドオンをインスタンス化する個別のファイルです。

// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif  // _ADDON_H_

// addon.c
#include "addon.h"

#define NODE_API_CALL(env, call)                                  \
  do {                                                            \
    napi_status status = (call);                                  \
    if (status != napi_ok) {                                      \
      const napi_extended_error_info* error_info = NULL;          \
      napi_get_last_error_info((env), &error_info);               \
      const char* err_message = error_info->error_message;        \
      bool is_pending;                                            \
      napi_is_exception_pending((env), &is_pending);              \
      /* If an exception is already pending, don't rethrow it */  \
      if (!is_pending) {                                          \
        const char* message = (err_message == NULL)               \
            ? "empty error message"                               \
            : err_message;                                        \
        napi_throw_error((env), NULL, message);                   \
      }                                                           \
      return NULL;                                                \
    }                                                             \
  } while(0)

static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
  // Do something useful.
  return NULL;
}

napi_value create_addon(napi_env env) {
  napi_value result;
  NODE_API_CALL(env, napi_create_object(env, &result));

  napi_value exported_function;
  NODE_API_CALL(env, napi_create_function(env,
                                          "doSomethingUseful",
                                          NAPI_AUTO_LENGTH,
                                          DoSomethingUseful,
                                          NULL,
                                          &exported_function));

  NODE_API_CALL(env, napi_set_named_property(env,
                                             result,
                                             "doSomethingUseful",
                                             exported_function));

  return result;
}

// addon_node.c
#include <node_api.h>
#include "addon.h"

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  // This function body is expected to return a `napi_value`.
  // The variables `napi_env env` and `napi_value exports` may be used within
  // the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
  return create_addon(env);
}

環境ライフサイクル API

セクション 8.7 の ECMAScript 言語仕様 は、「Agent」という概念を定義しています。これは、JavaScript コードが実行される自己完結型の環境です。複数のそのような Agent は、プロセスによって同時または順次に開始および終了される可能性があります。

Node.js 環境は ECMAScript Agent に対応します。メインプロセスでは、起動時に環境が作成され、追加の環境は別々のスレッドで作成され、ワーカースレッドとして機能します。Node.js が別のアプリケーションに埋め込まれている場合、アプリケーションのメインスレッドはアプリケーションプロセスのライフサイクル中に Node.js 環境を複数回構築および破棄することもできます。アプリケーションによって作成された各 Node.js 環境は、そのライフサイクル中にワーカースレッドとして追加の環境を作成および破棄する可能性があります。

ネイティブアドオンの観点からは、これは、それが提供するバインディングが、複数回、複数のコンテキストから、そして複数のスレッドから同時に呼び出される可能性があることを意味します。

ネイティブアドオンは、Node.js 環境のライフサイクル中に使用するグローバル状態を割り当てる必要がある場合があります。これにより、状態をアドオンの各インスタンスに固有にすることができます。

この目的のために、Node-API は、そのライフサイクルが Node.js 環境のライフサイクルに結び付けられたデータを関連付ける方法を提供します。

napi_set_instance_data

追加されたバージョン: v12.8.0, v10.20.0

N-API バージョン: 6

napi_status napi_set_instance_data(node_api_basic_env env,
                                   void* data,
                                   napi_finalize finalize_cb,
                                   void* finalize_hint);

• [in] env: Node-API 呼び出しが実行されている環境。
• [in] data: このインスタンスのバインディングで使用できるようにするデータ項目。
• [in] finalize_cb: 環境が破棄されるときに呼び出す関数。関数はdataを受け取るため、解放することができます。napi_finalize は詳細を提供します。
• [in] finalize_hint: 収集中にファイナライズコールバックに渡すオプションのヒント。

API が成功した場合はnapi_okを返します。

この API は、dataを現在実行中の Node.js 環境に関連付けます。dataは後でnapi_get_instance_data()を使用して取得できます。napi_set_instance_data()への以前の呼び出しによって設定された、現在実行中の Node.js 環境に関連付けられている既存のデータは上書きされます。以前の呼び出しでfinalize_cbが提供されていた場合、それは呼び出されません。

napi_get_instance_data

追加: v12.8.0, v10.20.0

N-API バージョン: 6

napi_status napi_get_instance_data(node_api_basic_env env,
                                   void** data);

• [in] env: Node-API 呼び出しが行われる環境。
• [out] data: napi_set_instance_data() の呼び出しによって、現在実行中の Node.js 環境に以前関連付けられていたデータ項目。

API が成功した場合は napi_ok を返します。

この API は、napi_set_instance_data() を介して、現在実行中の Node.js 環境に以前関連付けられていたデータを取得します。データが設定されていない場合、呼び出しは成功し、data は NULL に設定されます。

基本的な Node-API データ型

Node-API は、さまざまな API で使用される抽象化として、以下の基本的なデータ型を公開します。これらの API は、他の Node-API 呼び出しでのみイントロスペクト可能な、不透明なデータとして扱う必要があります。

napi_status

追加: v8.0.0

N-API バージョン: 1

Node-API 呼び出しの成功または失敗を示す整数ステータスコード。現在、以下のステータスコードがサポートされています。

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;

API が失敗したステータスを返した場合に追加情報が必要な場合は、napi_get_last_error_info を呼び出すことで取得できます。

napi_extended_error_info

追加: v8.0.0

N-API バージョン: 1

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

• error_message: エラーの VM に依存しない説明を含む、UTF8 エンコードされた文字列。
• engine_reserved: VM 固有のエラー詳細用に予約されています。現在、どの VM でも実装されていません。
• engine_error_code: VM 固有のエラーコード。現在、どの VM でも実装されていません。
• error_code: 最後のエラーの原因となった Node-API ステータスコード。

詳細は、エラー処理 セクションを参照してください。

napi_env

napi_envは、基盤となる Node-API 実装が VM 固有の状態を保持するために使用できるコンテキストを表すために使用されます。この構造体は、ネイティブ関数が呼び出されるときに渡され、Node-API 呼び出しを行う際には返される必要があります。具体的には、最初のネイティブ関数が呼び出されたときに渡されたのと同じnapi_envを、後続のネストされた Node-API 呼び出しすべてに渡す必要があります。一般的な再利用のためにnapi_envをキャッシュしたり、異なるWorkerスレッドで実行されている同じアドオンのインスタンス間でnapi_envを渡したりすることは許可されていません。napi_envは、ネイティブアドオンのインスタンスがアンロードされると無効になります。このイベントの通知は、napi_add_env_cleanup_hookとnapi_set_instance_dataに渡されたコールバックを通じて配信されます。

node_api_basic_env

[安定版: 1 - 実験的]

安定版: 1 安定性: 1 - 実験的

napi_envのこの変種は、同期ファイナライザ（node_api_basic_finalize）に渡されます。node_api_basic_env型のパラメータを最初の引数として受け入れる Node-API のサブセットがあります。これらの API は JavaScript エンジンの状態にアクセスしないため、同期ファイナライザから安全に呼び出すことができます。これらの API にnapi_env型のパラメータを渡すことは許可されていますが、JavaScript エンジンの状態にアクセスする API にnode_api_basic_env型のパラメータを渡すことは許可されていません。キャストなしでこれを行うと、アドオンが警告と/またはエラーを生成するようにフラグを立ててコンパイルされた場合、コンパイラ警告またはエラーが発生します。同期ファイナライザからそのような API を呼び出すと、最終的にアプリケーションの終了につながります。

napi_value

これは、JavaScript の値を表すために使用される不透明なポインタです。

napi_threadsafe_function

追加日時: v10.6.0

N-API バージョン: 4

これは、napi_call_threadsafe_function() を介して複数のスレッドから非同期的に呼び出すことができる JavaScript 関数を表す不透明ポインタです。

napi_threadsafe_function_release_mode

追加日時: v10.6.0

N-API バージョン: 4

スレッドセーフ関数をただちに閉じる (napi_tsfn_abort) か、単に解放する (napi_tsfn_release) かを napi_release_threadsafe_function() に指示するために渡される値です。解放された関数は、napi_acquire_threadsafe_function() および napi_call_threadsafe_function() を介して後続で使用できます。

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

napi_threadsafe_function_call_mode

追加日時: v10.6.0

N-API バージョン: 4

スレッドセーフ関数に関連付けられたキューがいっぱいの場合に、呼び出しをブロックするかどうかを napi_call_threadsafe_function() に指示するために渡される値です。

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

Node-API メモリ管理タイプ

napi_handle_scope

これは、特定のスコープ内で作成されたオブジェクトのライフタイムを制御および変更するために使用される抽象化です。一般に、Node-API の値はハンドルスコープのコンテキスト内で作成されます。ネイティブメソッドが JavaScript から呼び出されると、デフォルトのハンドルスコープが存在します。ユーザーが明示的に新しいハンドルスコープを作成しない場合、Node-API の値はデフォルトのハンドルスコープに作成されます。ネイティブメソッドの実行以外のコードの呼び出し（たとえば、libuv のコールバック呼び出し中）では、JavaScript 値の作成につながる可能性のある関数を呼び出す前に、モジュールはスコープを作成する必要があります。

ハンドルスコープは napi_open_handle_scope を使用して作成され、napi_close_handle_scope を使用して破棄されます。スコープを閉じることで、GC に対して、ハンドルスコープのライフタイム中に作成されたすべての napi_value が現在のスタックフレームから参照されなくなったことを示すことができます。

詳細については、オブジェクトのライフタイム管理 を参照してください。

napi_escapable_handle_scope

追加時期: v8.0.0

N-API バージョン: 1

escapable handle scopeは、特定のハンドルスコープ内で作成された値を親スコープに返すための特殊なタイプのハンドルスコープです。

napi_ref

追加時期: v8.0.0

N-API バージョン: 1

これはnapi_valueを参照するために使用する抽象化です。これにより、ユーザーは JavaScript 値のライフタイムを管理し、その最小ライフタイムを明示的に定義できます。

詳細については、オブジェクトのライフタイム管理を参照してください。

napi_type_tag

追加時期: v14.8.0, v12.19.0

N-API バージョン: 8

2 つの符号なし 64 ビット整数として格納される 128 ビット値です。JavaScript オブジェクトまたはexternalsに「タグ付け」するために使用される UUID として機能し、それらが特定の型であることを保証します。後者はオブジェクトのプロトタイプが操作された場合、誤検知を報告する可能性があるため、これはnapi_instanceofよりも強力なチェックです。型タグ付けは、napi_wrapと組み合わせて使用すると最も役立ちます。これは、ラップされたオブジェクトから取得されたポインタを、以前に JavaScript オブジェクトに適用されていた型タグに対応するネイティブ型に安全にキャストできることを保証するためです。

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

napi_async_cleanup_hook_handle

追加時期: v14.10.0, v12.19.0

napi_add_async_cleanup_hookによって返される不透明な値です。非同期クリーンアップイベントのチェーンが完了したときに、napi_remove_async_cleanup_hookに渡す必要があります。

Node-API コールバック型

napi_callback_info

追加時期: v8.0.0

N-API バージョン: 1

コールバック関数に渡される不透明なデータ型です。コールバックが呼び出されたコンテキストに関する追加情報を取得するために使用できます。

napi_callback

追加時期: v8.0.0

N-API バージョン: 1

Node-API を介して JavaScript に公開されるユーザー提供のネイティブ関数のための関数ポインタ型です。コールバック関数は、次のシグネチャを満たしている必要があります。

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

オブジェクトのライフタイム管理で説明されている理由がない限り、napi_callback内でハンドルやコールバックスコープを作成する必要はありません。

node_api_basic_finalize

追加日: v21.6.0, v20.12.0, v18.20.0

[安定版: 1 - 試験的]

安定版: 1 安定性: 1 - 試験的

外部所有データが関連付けられたオブジェクトのガベージコレクションによりクリーンアップの準備が整ったことをユーザーに通知するための、アドオンが提供する関数の関数ポインタ型です。ユーザーは、オブジェクトのコレクション時に呼び出される以下のシグネチャを満たす関数を提供する必要があります。現在、node_api_basic_finalizeは、外部データを持つオブジェクトがいつコレクションされるかを知るために使用できます。

typedef void (*node_api_basic_finalize)(node_api_basic_env env,
                                      void* finalize_data,
                                      void* finalize_hint);

オブジェクトのライフタイム管理で説明されている理由がない限り、関数本体内でハンドルやコールバックスコープを作成する必要はありません。

これらの関数は、JavaScript エンジンが JavaScript コードを実行できない状態で呼び出される可能性があるため、最初の引数としてnode_api_basic_envを受け入れる Node-API のみを呼び出すことができます。node_api_post_finalizerを使用して、現在のガベージコレクションサイクルの完了後に実行する必要がある、JavaScript エンジンの状態へのアクセスを必要とする Node-API 呼び出しをスケジュールできます。

node_api_create_external_string_latin1とnode_api_create_external_string_utf16の場合、外部文字列は環境シャットダウンの後期に収集される可能性があるため、envパラメーターは NULL になる可能性があります。

変更履歴:

• 試験的 (NAPI_EXPERIMENTAL): 最初の引数としてnode_api_basic_envを受け入れる Node-API 呼び出しのみが呼び出せます。そうでない場合、アプリケーションは適切なエラーメッセージと共に終了します。この機能はNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUTを定義することで無効にできます。

napi_finalize

追加日時: v8.0.0

N-API バージョン: 1

ガベージコレクションイベントへの応答として、ガベージコレクションサイクルが完了した後に、Node-API への一連の呼び出しをユーザーがスケジュールできるようにする、アドオンが提供する関数のための関数ポインタ型です。これらの関数ポインタは、node_api_post_finalizerと共に使用できます。

typedef void (*napi_finalize)(napi_env env,
                              void* finalize_data,
                              void* finalize_hint);

変更履歴:

• 実験的 (NAPI_EXPERIMENTAL が定義されている): この型の関数は、node_api_post_finalizer を除いて、ファイナライザとして使用できなくなりました。代わりに node_api_basic_finalize を使用する必要があります。この機能は NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT を定義することで無効にできます。

napi_async_execute_callback

追加日時: v8.0.0

N-API バージョン: 1

非同期操作をサポートする関数で使用される関数ポインタです。コールバック関数は、以下のシグネチャを満たす必要があります。

typedef void (*napi_async_execute_callback)(napi_env env, void* data);

この関数の実装では、JavaScript を実行したり、JavaScript オブジェクトとやり取りしたりする Node-API 呼び出しを避ける必要があります。Node-API 呼び出しは、代わりにnapi_async_complete_callbackで行う必要があります。napi_envパラメータを使用しないでください。JavaScript の実行につながる可能性があります。

napi_async_complete_callback

追加日時: v8.0.0

N-API バージョン: 1

非同期操作をサポートする関数で使用される関数ポインタです。コールバック関数は、以下のシグネチャを満たす必要があります。

typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data);

オブジェクトのライフタイム管理で説明されている理由がない限り、関数本体内でハンドルやコールバックスコープを作成する必要はありません。

napi_threadsafe_function_call_js

追加バージョン: v10.6.0

N-API バージョン: 4

非同期スレッドセーフ関数呼び出しで使用される関数ポインタ。コールバックはメインスレッドで呼び出されます。その目的は、セカンダリスレッドのいずれかからのキューを介して到着したデータ項目を使用して、通常はnapi_call_functionを介して JavaScript への呼び出しに必要なパラメータを構築し、その後 JavaScript への呼び出しを行うことです。

キューを介してセカンダリスレッドから到着するデータはdataパラメータで渡され、呼び出す JavaScript 関数はjs_callbackパラメータで渡されます。

Node-API はこのコールバックを呼び出す前に環境をセットアップするため、napi_make_callbackではなくnapi_call_functionを介して JavaScript 関数を呼び出すだけで十分です。

コールバック関数は次のシグネチャを満たす必要があります。

typedef void (*napi_threadsafe_function_call_js)(napi_env env,
                                                 napi_value js_callback,
                                                 void* context,
                                                 void* data);

• [in] env: API 呼び出しに使用する環境、またはスレッドセーフ関数が破棄され、dataを解放する必要がある場合NULL。
• [in] js_callback: 呼び出す JavaScript 関数、またはスレッドセーフ関数が破棄され、dataを解放する必要がある場合NULL。スレッドセーフ関数がjs_callbackなしで作成された場合もNULLになる場合があります。
• [in] context: スレッドセーフ関数が作成された際に渡されたオプションのデータ。
• [in] data: セカンダリスレッドによって作成されたデータ。このネイティブデータを、js_callbackが呼び出されたときにパラメータとして渡すことができる JavaScript 値（Node-API 関数を使用）に変換するのは、コールバックの責任です。このポインタは、スレッドとこのコールバックによって完全に管理されます。したがって、このコールバックはデータを解放する必要があります。

オブジェクトライフタイム管理で説明されている理由がない限り、関数本体内でハンドルやコールバックスコープを作成する必要はありません。

napi_cleanup_hook

追加バージョン: v19.2.0, v18.13.0

N-API バージョン: 3

napi_add_env_cleanup_hook と共に使用される関数ポインタ。環境の破棄時に呼び出されます。

コールバック関数は以下のシグネチャを満たす必要があります。

typedef void (*napi_cleanup_hook)(void* data);

• [in] data: napi_add_env_cleanup_hook に渡されたデータ。

napi_async_cleanup_hook

追加バージョン: v14.10.0, v12.19.0

napi_add_async_cleanup_hook と共に使用される関数ポインタ。環境の破棄時に呼び出されます。

コールバック関数は以下のシグネチャを満たす必要があります。

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data);

• [in] handle: 非同期クリーンアップの完了後に napi_remove_async_cleanup_hook に渡す必要があるハンドル。
• [in] data: napi_add_async_cleanup_hook に渡されたデータ。

関数の本体では、非同期クリーンアップアクションを開始する必要があります。その終了時に、handle を napi_remove_async_cleanup_hook の呼び出しに渡す必要があります。

エラー処理

Node-API は、エラー処理に返り値と JavaScript 例外の両方を用いています。以下のセクションでは、それぞれのケースについて説明します。

返り値

すべての Node-API 関数は、同じエラー処理パターンを共有しています。すべての API 関数の戻り値の型は napi_status です。

要求が成功し、キャッチされない JavaScript 例外がスローされなかった場合、返り値は napi_ok になります。エラーが発生し、例外がスローされた場合、エラーの napi_status 値が返されます。例外がスローされ、エラーが発生しなかった場合、napi_pending_exception が返されます。

napi_ok または napi_pending_exception 以外の返り値が返された場合、例外が保留中かどうかを確認するために napi_is_exception_pending を呼び出す必要があります。詳細については、例外に関するセクションを参照してください。

可能な napi_status 値の完全なセットは、napi_api_types.h で定義されています。

napi_status 返り値は、発生したエラーの VM に依存しない表現を提供します。場合によっては、エラーを表す文字列と VM（エンジン）固有の情報を含む、より詳細な情報を得ることが役立つ場合があります。

この情報を取得するために、napi_extended_error_info 構造体を返す napi_get_last_error_info が提供されています。napi_extended_error_info 構造体の形式は以下のとおりです。

追加バージョン: v8.0.0

N-API バージョン: 1

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

• error_message: 発生したエラーのテキスト表現。
• engine_reserved: エンジン専用に予約された不透明なハンドル。
• engine_error_code: VM 固有のエラーコード。
• error_code: 最後のエラーの Node-API ステータスコード。

napi_get_last_error_info は、最後に実行された Node-API 呼び出しの情報に戻します。

拡張情報のコンテンツまたは形式には依存しないでください。これは SemVer の対象外であり、いつでも変更される可能性があります。ログ記録の目的でのみ使用することを目的としています。

napi_get_last_error_info

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status
napi_get_last_error_info(node_api_basic_env env,
                         const napi_extended_error_info** result);

• [in] env: API が呼び出される環境。
• [out] result: エラーに関する詳細情報を含むnapi_extended_error_info構造体。

API が成功した場合はnapi_okを返します。

この API は、最後に発生したエラーに関する情報を含むnapi_extended_error_info構造体を取り出します。

返されるnapi_extended_error_infoの内容は、同じenvで Node-API 関数が呼び出されるまで有効です。これにはnapi_is_exception_pendingへの呼び出しも含まれるため、後で使えるように情報をコピーする必要があることがよくあります。error_messageで返されるポインタは静的に定義された文字列を指しているため、別の Node-API 関数が呼び出される前にerror_messageフィールドからコピーした場合（上書きされます）、そのポインタを使用しても安全です。

拡張情報のコンテンツや形式には依存しないでください。これは SemVer の対象ではなく、いつでも変更される可能性があります。ログ記録の目的のみを意図しています。

この API は、JavaScript 例外が保留されている場合でも呼び出すことができます。

例外

任意の Node-API 関数呼び出しは、保留中の JavaScript 例外を発生させる可能性があります。これは、JavaScript の実行を引き起こさない可能性のある API 関数にも当てはまります。

関数が返すnapi_statusがnapi_okの場合、例外は保留されておらず、追加のアクションは必要ありません。返されるnapi_statusがnapi_okまたはnapi_pending_exception以外の場合は、ただちに返すのではなくリカバリして続行するために、例外が保留中かどうかを判断するためにnapi_is_exception_pendingを呼び出す必要があります。

多くの場合、Node-API 関数が呼び出され、例外が既に保留されている場合、関数はnapi_pending_exceptionのnapi_statusをすぐに返します。しかし、これはすべての関数に当てはまるわけではありません。Node-API では、JavaScript に戻る前に最小限のクリーンアップを可能にするために、関数のサブセットを呼び出すことができます。その場合、napi_statusは関数の状態を反映します。以前の保留中の例外は反映されません。混乱を避けるために、各関数呼び出し後にエラー状態を確認してください。

例外が保留されている場合、2 つのアプローチのいずれかを使用できます。

最初の方法は、適切なクリーンアップを行い、JavaScript に戻って実行を返すことです。JavaScript への移行の一部として、ネイティブメソッドが呼び出された JavaScript コードの時点で例外がスローされます。例外が保留されている間のほとんどの Node-API 呼び出しの動作は未定義であり、多くの呼び出しは単純にnapi_pending_exceptionを返すため、できるだけ少なく処理して、例外を処理できる JavaScript に戻ってください。

2 番目のアプローチは、例外を処理しようとすることです。ネイティブコードが例外をキャッチし、適切なアクションを実行してから続行できる場合があります。これは、例外を安全に処理できることがわかっている特定の場合にのみ推奨されます。これらの場合、napi_get_and_clear_last_exceptionを使用して例外を取得してクリアできます。成功すると、result には、スローされた最後の JavaScript Objectへのハンドルが含まれます。例外を取得した後、例外を処理できないと判断された場合は、napi_throwを使用して再スローできます。ここで、error はスローされる JavaScript 値です。

ネイティブコードが例外をスローする必要がある場合、またはnapi_valueが JavaScript Errorオブジェクトのインスタンスであるかどうかを判断する必要がある場合、次のユーティリティ関数も使用できます。napi_throw_error、napi_throw_type_error、napi_throw_range_error、node_api_throw_syntax_error、およびnapi_is_error。

ネイティブコードがErrorオブジェクトを作成する必要がある場合、次のユーティリティ関数も使用できます。napi_create_error、napi_create_type_error、napi_create_range_error、およびnode_api_create_syntax_error。ここで、result は新しく作成された JavaScript Errorオブジェクトを参照するnapi_valueです。

Node.js プロジェクトでは、内部で生成されるすべてのエラーにエラーコードを追加しています。アプリケーションでは、すべてのエラーチェックにこれらのエラーコードを使用することを目指しています。関連するエラーメッセージは残りますが、SemVer が適用されないことを前提として、ログ記録と表示のみに使用されるようになります。Node-API でこのモデルをサポートするために、内部機能とモジュール固有の機能の両方で（これは良い習慣です）、throw_関数とcreate_関数は、エラーオブジェクトに追加されるコードの文字列であるオプションのコードパラメータを取ります。オプションのパラメータがNULLの場合、エラーにはコードは関連付けられません。コードが提供された場合、エラーに関連付けられた名前も次のように更新されます。

originalName [code]

ここで、originalNameはエラーに関連付けられた元の名前であり、codeは提供されたコードです。たとえば、コードが'ERR_ERROR_1'でTypeErrorが作成されている場合、名前は次のようになります。

TypeError [ERR_ERROR_1]

napi_throw

追加されたバージョン: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);

• [in] env: API が呼び出される環境。
• [in] error: スローされる JavaScript の値。

API が成功した場合、napi_okを返します。

この API は、指定された JavaScript の値をスローします。

napi_throw_error

追加されたバージョン: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_throw_error(napi_env env,
                                         const char* code,
                                         const char* msg);

• [in] env: API が呼び出される環境。
• [in] code: エラーに設定されるオプションのエラーコード。
• [in] msg: エラーに関連付けられるテキストを表す C 文字列。

API が成功した場合、napi_okを返します。

この API は、指定されたテキストを含む JavaScript のErrorをスローします。

napi_throw_type_error

追加されたバージョン: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
                                              const char* code,
                                              const char* msg);

• [in] env: API が呼び出される環境。
• [in] code: エラーに設定されるオプションのエラーコード。
• [in] msg: エラーに関連付けられるテキストを表す C 文字列。

API が成功した場合、napi_okを返します。

この API は、指定されたテキストを含む JavaScript のTypeErrorをスローします。

napi_throw_range_error

追加されたバージョン: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
                                               const char* code,
                                               const char* msg);

• [in] env: API が呼び出される環境。
• [in] code: エラーに設定されるオプションのエラーコード。
• [in] msg: エラーに関連付けられるテキストを表す C 文字列。

API が成功した場合、napi_okを返します。

この API は、指定されたテキストを含む JavaScript のRangeErrorをスローします。

node_api_throw_syntax_error

追加: v17.2.0, v16.14.0

N-API バージョン: 9

NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
                                                    const char* code,
                                                    const char* msg);

• [in] env: API が呼び出される環境。
• [in] code: エラーに設定されるオプションのエラーコード。
• [in] msg: エラーに関連付けられるテキストを表す C 文字列。

API が成功した場合、napi_okを返します。

この API は、指定されたテキストを持つ JavaScript SyntaxErrorをスローします。

napi_is_error

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_is_error(napi_env env,
                                      napi_value value,
                                      bool* result);

• [in] env: API が呼び出される環境。
• [in] value: チェックされるnapi_value。
• [out] result: napi_valueがエラーを表す場合は true、それ以外の場合は false に設定されるブール値。

API が成功した場合、napi_okを返します。

この API は、napi_valueがエラーオブジェクトを表しているかどうかをチェックします。

napi_create_error

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_create_error(napi_env env,
                                          napi_value code,
                                          napi_value msg,
                                          napi_value* result);

• [in] env: API が呼び出される環境。
• [in] code: エラーに関連付けられるエラーコードの文字列を含むオプションのnapi_value。
• [in] msg: Errorのメッセージとして使用される JavaScript stringを参照するnapi_value。
• [out] result: 作成されたエラーを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、指定されたテキストを持つ JavaScript Errorを返します。

napi_create_type_error

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
                                               napi_value code,
                                               napi_value msg,
                                               napi_value* result);

• [in] env: API が呼び出される環境。
• [in] code: エラーに関連付けられるエラーコードの文字列を含むオプションのnapi_value。
• [in] msg: Errorのメッセージとして使用される JavaScript stringを参照するnapi_value。
• [out] result: 作成されたエラーを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、指定されたテキストを持つ JavaScript TypeErrorを返します。

napi_create_range_error

追加：v8.0.0

N-API バージョン：1

NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
                                                napi_value code,
                                                napi_value msg,
                                                napi_value* result);

• [in] env: API が呼び出される環境。
• [in] code: エラーに関連付けるエラーコードの文字列を含む、オプションの napi_value。
• [in] msg: Error のメッセージとして使用する JavaScript の string を参照する napi_value。
• [out] result: 作成されたエラーを表す napi_value。

API が成功した場合は napi_ok を返します。

この API は、指定されたテキストを持つ JavaScript のRangeErrorを返します。

node_api_create_syntax_error

追加：v17.2.0、v16.14.0

N-API バージョン：9

NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
                                                     napi_value code,
                                                     napi_value msg,
                                                     napi_value* result);

• [in] env: API が呼び出される環境。
• [in] code: エラーに関連付けるエラーコードの文字列を含む、オプションの napi_value。
• [in] msg: Error のメッセージとして使用する JavaScript の string を参照する napi_value。
• [out] result: 作成されたエラーを表す napi_value。

API が成功した場合は napi_ok を返します。

この API は、指定されたテキストを持つ JavaScript のSyntaxErrorを返します。

napi_get_and_clear_last_exception

追加：v8.0.0

N-API バージョン：1

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result);

• [in] env: API が呼び出される環境。
• [out] result: 例外が存在する場合はその例外、存在しない場合は NULL。

API が成功した場合は napi_ok を返します。

この API は、JavaScript の例外が保留されている場合でも呼び出すことができます。

napi_is_exception_pending

追加日時: v8.0.0

N-API バージョン: 1

napi_status napi_is_exception_pending(napi_env env, bool* result);

• [in] env: API が呼び出される環境。
• [out] result: 例外が保留中の場合は true に設定されるブール値。

API が成功した場合はnapi_okを返します。

この API は、保留中の JavaScript 例外が存在する場合でも呼び出すことができます。

napi_fatal_exception

追加日時: v9.10.0

N-API バージョン: 3

napi_status napi_fatal_exception(napi_env env, napi_value err);

• [in] env: API が呼び出される環境。
• [in] err: 'uncaughtException'に渡されるエラー。

JavaScript で'uncaughtException'をトリガーします。非同期コールバックが例外をスローし、回復手段がない場合に便利です。

致命的エラー

ネイティブアドオンで回復不可能なエラーが発生した場合、プロセスを即座に終了するために致命的なエラーをスローできます。

napi_fatal_error

追加日時: v8.2.0

N-API バージョン: 1

NAPI_NO_RETURN void napi_fatal_error(const char* location,
                                     size_t location_len,
                                     const char* message,
                                     size_t message_len);

• [in] location: エラーが発生した場所（オプション）。
• [in] location_len: 場所の長さ（バイト単位）、ヌル終端の場合はNAPI_AUTO_LENGTH。
• [in] message: エラーに関連付けられたメッセージ。
• [in] message_len: メッセージの長さ（バイト単位）、ヌル終端の場合はNAPI_AUTO_LENGTH。

関数の呼び出しは返らず、プロセスは終了します。

この API は、保留中の JavaScript 例外が存在する場合でも呼び出すことができます。

オブジェクトライフタイム管理

Node-API の呼び出しが行われると、基になる VM のヒープ内のオブジェクトへのハンドルがnapi_valuesとして返される場合があります。これらのハンドルは、ネイティブコードで不要になるまでオブジェクトを「存続」させる必要があります。そうでなければ、ネイティブコードが使用を終了する前にオブジェクトが収集される可能性があります。

オブジェクトハンドルが返されると、それは「スコープ」に関連付けられます。デフォルトスコープのライフスパンは、ネイティブメソッド呼び出しのライフスパンに関連付けられています。その結果、デフォルトでは、ハンドルは有効なままであり、これらのハンドルに関連付けられたオブジェクトは、ネイティブメソッド呼び出しのライフスパンの間、存続します。

しかし、多くの場合、ハンドルをネイティブメソッドよりも短いか長いかのライフスパンの間有効にする必要があります。以下のセクションでは、ハンドルのライフスパンをデフォルトから変更するために使用できる Node-API 関数を説明します。

ネイティブメソッドより短いハンドル寿命の作成

ネイティブメソッドの寿命よりも短いハンドルの寿命を作成する必要があることがよくあります。たとえば、大きな配列の要素を反復処理するループを持つネイティブメソッドを考えてみましょう。

for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // 要素に対して何かを行う
}

これにより、多数のハンドルが作成され、大量のリソースが消費されます。さらに、ネイティブコードは最新のハンドルしか使用できない場合でも、すべてが同じスコープを共有しているため、関連付けられたすべてのオブジェクトも存続します。

この問題に対処するために、Node-API は、新しく作成されたハンドルが関連付けられる新しい「スコープ」を確立する機能を提供します。これらのハンドルが不要になったら、スコープを「閉じ」、スコープに関連付けられたハンドルを無効にすることができます。スコープを開閉するために使用できるメソッドは、napi_open_handle_scopeとnapi_close_handle_scopeです。

Node-API は、スコープの単一ネストされた階層のみをサポートします。一度にアクティブなスコープは 1 つだけであり、新しいハンドルは、アクティブな間はそのスコープに関連付けられます。スコープは、開かれた逆の順序で閉じなければなりません。さらに、ネイティブメソッド内で作成されたすべてのスコープは、そのメソッドから戻る前に閉じなければなりません。

前の例では、napi_open_handle_scopeとnapi_close_handle_scopeへの呼び出しを追加することで、ループの実行中、最大 1 つのハンドルのみが有効になることを保証します。

for (int i = 0; i < 1000000; i++) {
  napi_handle_scope scope;
  napi_status status = napi_open_handle_scope(env, &scope);
  if (status != napi_ok) {
    break;
  }
  napi_value result;
  status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // 要素に対して何かを行う
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

スコープをネストする場合、内部スコープのハンドルをそのスコープの寿命を超えて存続させる必要がある場合があります。Node-API は、このケースをサポートするために「エスケープ可能なスコープ」をサポートしています。エスケープ可能なスコープでは、1 つのハンドルを「昇格」して、現在のスコープを「エスケープ」し、ハンドルの寿命を現在のスコープから外部スコープに変更できます。

エスケープ可能なスコープを開閉するために使用できるメソッドは、napi_open_escapable_handle_scopeとnapi_close_escapable_handle_scopeです。

ハンドルの昇格要求は、napi_escape_handleを介して行われます。これは一度だけ呼び出すことができます。

napi_open_handle_scope

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result);

• [in] env: API が呼び出される環境。
• [out] result: 新しいスコープを表すnapi_value。

API が成功した場合、napi_okを返す。

この API は新しいスコープを開く。

napi_close_handle_scope

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope);

• [in] env: API が呼び出される環境。
• [in] scope: 閉じられるスコープを表すnapi_value。

API が成功した場合、napi_okを返す。

この API は渡されたスコープを閉じる。スコープは作成された逆の順序で閉じなければならない。

この API は、保留中の JavaScript 例外があっても呼び出すことができる。

napi_open_escapable_handle_scope

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result);

• [in] env: API が呼び出される環境。
• [out] result: 新しいスコープを表すnapi_value。

API が成功した場合、napi_okを返す。

この API は、1 つのオブジェクトを外側のスコープに昇格させることができる新しいスコープを開く。

napi_close_escapable_handle_scope

追加: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);

• [in] env: API が呼び出される環境。
• [in] scope: 閉じられるスコープを表すnapi_value。

API が成功した場合、napi_okを返す。

この API は渡されたスコープを閉じる。スコープは作成された逆の順序で閉じなければならない。

この API は、保留中の JavaScript 例外があっても呼び出すことができる。

napi_escape_handle

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_escape_handle(napi_env env,
                               napi_escapable_handle_scope scope,
                               napi_value escapee,
                               napi_value* result);

• [in] env: API が呼び出される環境。
• [in] scope: 現在のスコープを表すnapi_value。
• [in] escapee: エスケープする JavaScript Objectを表すnapi_value。
• [out] result: 外側のスコープでエスケープされたObjectへのハンドルを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、JavaScript オブジェクトのハンドルを昇格させ、外側のスコープの存続期間中に有効にします。スコープごとに一度しか呼び出すことができません。複数回呼び出すとエラーが返されます。

この API は、保留中の JavaScript 例外がある場合でも呼び出すことができます。

ネイティブメソッドよりも長い寿命を持つ値への参照

場合によっては、アドオンは、単一のネイティブメソッド呼び出しよりも長い寿命を持つ値を作成および参照する必要があります。たとえば、コンストラクタを作成し、後でインスタンスを作成するための要求でそのコンストラクタを使用するには、多くの異なるインスタンス作成要求にわたってコンストラクタオブジェクトを参照できる必要があります。これは、前のセクションで説明されているようにnapi_valueとして返される通常のハンドルでは不可能です。通常のハンドルの寿命はスコープによって管理され、すべてのスコープはネイティブメソッドの終了前に閉じられる必要があります。

Node-API は、値への永続的な参照を作成するためのメソッドを提供します。現在、Node-API では、オブジェクト、外部、関数、およびシンボルの限定された値の種類に対してのみ参照を作成できます。

各参照には、0 以上の値を持つ関連付けられたカウントがあり、参照が対応する値を存続させるかどうかを決定します。カウントが 0 の参照は、値が収集されるのを防ぎません。オブジェクト（オブジェクト、関数、外部）とシンボルの型の値は「弱い」参照になり、収集されていない間は引き続きアクセスできます。0 より大きいカウントは、値が収集されるのを防ぎます。

シンボル値には異なる種類があります。真の弱い参照の動作は、napi_create_symbol関数または JavaScript Symbol()コンストラクタ呼び出しで作成されたローカルシンボルのみでサポートされています。node_api_symbol_for関数または JavaScript Symbol.for()関数呼び出しで作成されたグローバルに登録されたシンボルは、ガベージコレクタがそれらを収集しないため、常に強い参照のままです。Symbol.iteratorなどのよく知られたシンボルについても同様です。これらもガベージコレクタによって収集されることはありません。

参照は、初期参照カウントで作成できます。その後、カウントはnapi_reference_refとnapi_reference_unrefを使用して変更できます。参照のカウントが 0 の場合にオブジェクトが収集されると、参照に関連付けられたオブジェクトを取得するための後続のすべての呼び出しnapi_get_reference_valueは、返されたnapi_valueに対してNULLを返します。オブジェクトが収集された参照に対してnapi_reference_refを呼び出そうとすると、エラーが発生します。

参照は、アドオンで不要になった時点で削除する必要があります。参照が削除されると、対応するオブジェクトが収集されるのを防ぐことはなくなります。永続的な参照を削除しないと、「メモリリーク」が発生し、永続的な参照のネイティブメモリとヒープ上の対応するオブジェクトの両方が永遠に保持されます。

同じオブジェクトを参照する複数の永続的な参照を作成でき、それぞれが個々のカウントに基づいてオブジェクトを存続させるかどうかが決まります。同じオブジェクトへの複数の永続的な参照により、ネイティブメモリが予期せず存続することがあります。永続的な参照のネイティブ構造は、参照されるオブジェクトのファイナライザが実行されるまで存続させる必要があります。同じオブジェクトに対して新しい永続的な参照が作成されると、そのオブジェクトのファイナライザは実行されず、以前の永続的な参照が指しているネイティブメモリは解放されません。これは、可能な場合はnapi_reference_unrefに加えてnapi_delete_referenceを呼び出すことで回避できます。

変更履歴:

• 実験的（NAPI_EXPERIMENTALが定義されている）：すべての値の種類に対して参照を作成できます。新しくサポートされる値の種類は弱い参照セマンティクスをサポートしておらず、これらの型の値は参照カウントが 0 になると解放され、参照からアクセスできなくなります。

napi_create_reference

追加日時: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result);

• [in] env: API が呼び出される環境。
• [in] value: 参照が作成されるnapi_value。
• [in] initial_refcount: 新しい参照の初期参照カウント。
• [out] result: 新しい参照を指すnapi_ref。

API が成功した場合はnapi_okを返します。

この API は、渡された値に対して、指定された参照カウントを持つ新しい参照を作成します。

napi_delete_reference

追加日時: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);

• [in] env: API が呼び出される環境。
• [in] ref: 削除されるnapi_ref。

API が成功した場合はnapi_okを返します。

この API は、渡された参照を削除します。

この API は、保留中の JavaScript 例外があっても呼び出すことができます。

napi_reference_ref

追加日時: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           uint32_t* result);

• [in] env: API が呼び出される環境。
• [in] ref: 参照カウントが増加されるnapi_ref。
• [out] result: 新しい参照カウント。

API が成功した場合はnapi_okを返します。

この API は、渡された参照の参照カウントを増やし、結果の参照カウントを返します。

napi_reference_unref

追加日時: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             uint32_t* result);

• [in] env: API が呼び出される環境。
• [in] ref: 参照カウントが減少されるnapi_ref。
• [out] result: 新しい参照カウント。

API が成功した場合はnapi_okを返します。

この API は、渡された参照の参照カウントを減らし、結果の参照カウントを返します。

napi_get_reference_value

追加日時: v8.0.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result);

• [in] env: API が呼び出される環境。
• [in] ref: 対応する値が要求されているnapi_ref。
• [out] result: napi_refによって参照されているnapi_value。

API が成功した場合、napi_okを返します。

有効な場合、この API はnapi_refに関連付けられた JavaScript 値を表すnapi_valueを返します。それ以外の場合は、resultはNULLになります。

現在の Node.js 環境の終了時のクリーンアップ

Node.js プロセスは通常、終了時にすべてのリソースを解放しますが、Node.js を埋め込む場合、または将来の Worker サポートでは、現在の Node.js 環境が終了したときに実行されるクリーンアップフックをアドオンが登録する必要がある場合があります。

Node-API は、そのようなコールバックの登録と登録解除のための関数を提供します。これらのコールバックが実行されると、アドオンによって保持されているすべてのリソースが解放される必要があります。

napi_add_env_cleanup_hook

追加日時: v10.2.0

N-API バージョン: 3

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
                                                  napi_cleanup_hook fun,
                                                  void* arg);

現在の Node.js 環境が終了したときに、argパラメーターと共に実行される関数としてfunを登録します。

異なるarg値を使用して、関数を複数回安全に指定できます。その場合、複数回呼び出されます。同じfunとargの値を複数回提供することは許可されておらず、プロセスが異常終了します。

フックは逆順に呼び出されます。つまり、最後に追加されたフックが最初に呼び出されます。

このフックの削除は、napi_remove_env_cleanup_hookを使用して行うことができます。通常、これは、このフックが追加されたリソースが既に破棄されている場合に行われます。

非同期クリーンアップには、napi_add_async_cleanup_hookを使用できます。

napi_remove_env_cleanup_hook

追加日時: v10.2.0

N-API バージョン: 3

NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
                                                     void (*fun)(void* arg),
                                                     void* arg);

現在の Node.js 環境が終了した際に、argパラメータと共に実行される関数としてfunの登録を解除します。引数と関数値は正確に一致する必要があります。

この関数は、元々napi_add_env_cleanup_hookで登録されている必要があります。そうでない場合、プロセスは異常終了します。

napi_add_async_cleanup_hook

[履歴]

バージョン	変更点
v14.10.0, v12.19.0	hookコールバックのシグネチャを変更
v14.8.0, v12.19.0	追加日時: v14.8.0, v12.19.0

N-API バージョン: 8

NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
    node_api_basic_env env,
    napi_async_cleanup_hook hook,
    void* arg,
    napi_async_cleanup_hook_handle* remove_handle);

• [in] env: API が呼び出される環境。
• [in] hook: 環境の終了時に呼び出す関数ポインタ。
• [in] arg: 呼び出された際にhookに渡すポインタ。
• [out] remove_handle: 非同期クリーンアップフックを参照するオプションのハンドル。

hookを、napi_async_cleanup_hook型の関数として登録します。現在の Node.js 環境が終了した際に、remove_handleとargパラメータと共に実行されます。

napi_add_env_cleanup_hookとは異なり、フックは非同期でも構いません。

それ以外は、napi_add_env_cleanup_hookとほぼ同じ動作をします。

remove_handleがNULLでない場合、不透明な値がそこに格納されます。この値は後でnapi_remove_async_cleanup_hookに渡す必要があります。これは、フックが既に呼び出されているかどうかに関係なく行われます。通常、これはこのフックが追加されたリソースが既に破棄されている場合に発生します。

napi_remove_async_cleanup_hook

[履歴]

バージョン	変更
v14.10.0, v12.19.0	env パラメータを削除
v14.8.0, v12.19.0	追加: v14.8.0, v12.19.0

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle);

• [in] remove_handle: napi_add_async_cleanup_hook で作成された非同期クリーンアップフックのハンドル。

remove_handle に対応するクリーンアップフックの登録を解除します。これにより、フックが既に実行を開始していない限り、フックが実行されなくなります。これは、napi_add_async_cleanup_hook から取得した任意の napi_async_cleanup_hook_handle 値に対して呼び出す必要があります。

Node.js 環境の終了時のファイナライズ

Node.js 環境は、worker.terminate() の要求など、JavaScript の実行が許可されない状態で、できるだけ早く任意の時点で破棄される可能性があります。環境が破棄されている場合、JavaScript オブジェクト、スレッドセーフな関数、および環境インスタンスデータの登録された napi_finalize コールバックは、直ちに、かつ独立して呼び出されます。

napi_finalize コールバックの呼び出しは、手動で登録されたクリーンアップフックの後に行われます。napi_finalize コールバックでの use-after-free を回避するために、環境シャットダウン時のアドオンファイナライズの適切な順序を確保するには、アドオンは napi_add_env_cleanup_hook と napi_add_async_cleanup_hook を使用してクリーンアップフックを登録し、適切な順序で割り当てられたリソースを手動で解放する必要があります。

モジュールの登録

Node-API モジュールは、NODE_MODULE マクロの代わりに次のものを使用する点を除いて、他のモジュールと同様の方法で登録されます。

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

次の違いは、Init メソッドのシグネチャです。Node-API モジュールの場合、次のようになります。

napi_value Init(napi_env env, napi_value exports);

Init からの戻り値は、モジュールの exports オブジェクトとして扱われます。Init メソッドには、便宜上、exports パラメータを介して空のオブジェクトが渡されます。Init が NULL を返す場合、exports として渡されたパラメータがモジュールによってエクスポートされます。Node-API モジュールは module オブジェクトを変更できませんが、モジュールの exports プロパティとして任意のものを指定できます。

hello メソッドを関数として追加して、アドオンによって提供されるメソッドとして呼び出せるようにするには、次のようにします。

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor desc = {
    "hello",
    NULL,
    Method,
    NULL,
    NULL,
    NULL,
    napi_writable | napi_enumerable | napi_configurable,
    NULL
  };
  status = napi_define_properties(env, exports, 1, &desc);
  if (status != napi_ok) return NULL;
  return exports;
}

アドオンの require() から返される関数に設定するには、次のようにします。

napi_value Init(napi_env env, napi_value exports) {
  napi_value method;
  napi_status status;
  status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
  if (status != napi_ok) return NULL;
  return method;
}

新しいインスタンスを作成できるようにクラスを定義するには（多くの場合、オブジェクトラップ と共に使用されます）。

// NOTE: 部分的な例であり、参照されているコードのすべてが含まれているわけではありません
napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor properties[] = {
    { "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },
    DECLARE_NAPI_METHOD("plusOne", PlusOne),
    DECLARE_NAPI_METHOD("multiply", Multiply),
  };

  napi_value cons;
  status =
      napi_define_class(env, "MyObject", New, NULL, 3, properties, &cons);
  if (status != napi_ok) return NULL;

  status = napi_create_reference(env, cons, 1, &constructor);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "MyObject", cons);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE と Init 関数の定義の省略形として機能する NAPI_MODULE_INIT マクロを使用することもできます。

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  napi_value answer;
  napi_status result;

  status = napi_create_int64(env, 42, &answer);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "answer", answer);
  if (status != napi_ok) return NULL;

  return exports;
}

env と exports のパラメータは、マクロ呼び出しに続く関数本体に提供されます。

すべての Node-API アドオンはコンテキスト認識型であり、複数回ロードされる可能性があります。このようなモジュールの宣言には、いくつかの設計上の考慮事項があります。コンテキスト認識型アドオンに関するドキュメントで詳細を確認できます。

env と exports の変数は、マクロ呼び出しに続く関数本体内で使用できます。

オブジェクトのプロパティの設定の詳細については、JavaScript プロパティの操作に関するセクションを参照してください。

アドオンモジュールの構築全般の詳細については、既存の API を参照してください。

JavaScript 値の操作

Node-API は、あらゆる種類の JavaScript 値を作成するための API セットを提供します。これらの型の一部は、ECMAScript 言語仕様のセクション 6で説明されています。

基本的に、これらの API は次のいずれかの操作に使用されます。

Node-API 値は、napi_value型で表されます。JavaScript 値を必要とする Node-API 呼び出しでは、napi_valueが渡されます。場合によっては、API が事前にnapi_valueの型をチェックします。しかし、パフォーマンスを向上させるために、呼び出し元が対象のnapi_valueが API で期待される JavaScript 型であることを確認する方が良いです。

列挙型

napi_key_collection_mode

追加バージョン: v13.7.0, v12.17.0, v10.20.0

N-API バージョン: 6

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode;

Keys/Propertiesフィルター列挙子を記述します。

napi_key_collection_modeは、収集されるプロパティの範囲を制限します。

napi_key_own_onlyは、収集されるプロパティを指定されたオブジェクトのみに制限します。napi_key_include_prototypesは、オブジェクトのプロトタイプチェーンのすべてのキーも含まれます。

napi_key_filter

追加バージョン: v13.7.0, v12.17.0, v10.20.0

N-API バージョン: 6

typedef enum {
  napi_key_all_properties = 0,
  napi_key_writable = 1,
  napi_key_enumerable = 1 << 1,
  napi_key_configurable = 1 << 2,
  napi_key_skip_strings = 1 << 3,
  napi_key_skip_symbols = 1 << 4
} napi_key_filter;

プロパティフィルタービット。これらを OR 演算して複合フィルターを作成できます。

napi_key_conversion

追加バージョン: v13.7.0, v12.17.0, v10.20.0

N-API バージョン: 6

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion;

napi_key_numbers_to_stringsは、整数インデックスを文字列に変換します。napi_key_keep_numbersは、整数インデックスに対して数値を返します。

napi_valuetype

typedef enum {
  // ES6 types (corresponds to typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype;

napi_valueの型を記述します。これは一般的に、ECMAScript 言語仕様のセクション 6.1で説明されている型に対応します。そのセクションの型に加えて、napi_valuetypeは外部データを持つFunctionとObjectも表すことができます。

napi_external型の JavaScript 値は、JavaScript ではプレーンオブジェクトとして表示され、プロパティを設定したり、プロトタイプを設定したりすることはできません。

napi_typedarray_type

typedef enum {
  napi_int8_array,
  napi_uint8_array,
  napi_uint8_clamped_array,
  napi_int16_array,
  napi_uint16_array,
  napi_int32_array,
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
  napi_bigint64_array,
  napi_biguint64_array,
} napi_typedarray_type;

これはTypedArrayの基礎となるバイナリのスカラーデータ型を表します。この列挙体の要素は、ECMAScript 言語仕様のセクション 22.2に対応しています。

オブジェクト作成関数

napi_create_array

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_create_array(napi_env env, napi_value* result)

• [in] env: Node-API 呼び出しが行われる環境。
• [out] result: JavaScript のArrayを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、JavaScript のArray型に対応する Node-API 値を返します。JavaScript 配列については、ECMAScript 言語仕様のセクション 22.1に記載されています。

napi_create_array_with_length

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_create_array_with_length(napi_env env,
                                          size_t length,
                                          napi_value* result)

• [in] env: API が呼び出される環境。
• [in] length: Arrayの初期の長さ。
• [out] result: JavaScript のArrayを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、JavaScript のArray型に対応する Node-API 値を返します。Arrayの長さプロパティは、渡された length パラメーターに設定されます。ただし、配列の作成時に、基となるバッファーが VM によって事前に割り当てられるとは限りません。その動作は、基となる VM の実装に委ねられます。バッファーが、C を介して直接読み書きできる連続したメモリのブロックでなければならない場合は、napi_create_external_arraybufferの使用を検討してください。

JavaScript 配列については、ECMAScript 言語仕様のセクション 22.1に記載されています。

napi_create_arraybuffer

追加日時: v8.0.0

N-API バージョン: 1

napi_status napi_create_arraybuffer(napi_env env,
                                    size_t byte_length,
                                    void** data,
                                    napi_value* result)

• [in] env: API が呼び出される環境。
• [in] length: 作成する ArrayBuffer のバイト数。
• [out] data: ArrayBufferの基になるバイトバッファへのポインタ。NULLを渡してオプションで無視できます。
• [out] result: JavaScript のArrayBufferを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、JavaScript のArrayBufferに対応する Node-API 値を返します。ArrayBufferは、固定長のバイナリデータバッファを表すために使用されます。通常は、TypedArrayオブジェクトのバックアップバッファとして使用されます。割り当てられたArrayBufferは、渡されたlengthパラメータによってサイズが決まる基になるバイトバッファを持ちます。呼び出し側がバッファを直接操作したい場合に備え、基になるバッファはオプションで呼び出し側に返されます。このバッファは、ネイティブコードからのみ直接書き込むことができます。JavaScript からこのバッファに書き込むには、型付き配列またはDataViewオブジェクトを作成する必要があります。

JavaScript のArrayBufferオブジェクトについては、ECMAScript 言語仕様のセクション 24.1を参照してください。

napi_create_buffer

追加日時: v8.0.0

N-API バージョン: 1

napi_status napi_create_buffer(napi_env env,
                               size_t size,
                               void** data,
                               napi_value* result)

• [in] env: API が呼び出される環境。
• [in] size: 基になるバッファのバイトサイズ。
• [out] data: 基になるバッファへの生のポインタ。NULLを渡してオプションで無視できます。
• [out] result: node::Bufferを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API はnode::Bufferオブジェクトを割り当てます。これは完全にサポートされているデータ構造ですが、ほとんどの場合、TypedArrayを使用するだけで十分です。

napi_create_buffer_copy

追加日: v8.0.0

N-API バージョン: 1

napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result)

• [in] env: API が呼び出される環境。
• [in] size: 入力バッファのサイズ（バイト単位）（新しいバッファのサイズと同じである必要があります）。
• [in] data: コピー元の基礎となるバッファへの生ポインタ。
• [out] result_data: 新しいBufferの基礎となるデータバッファへのポインタ。result_dataは、NULLを渡すことで省略可能です。
• [out] result: node::Bufferを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API はnode::Bufferオブジェクトを割り当て、渡されたバッファからコピーされたデータで初期化します。これは完全にサポートされているデータ構造ですが、ほとんどの場合、TypedArrayを使用するだけで十分です。

napi_create_date

追加日: v11.11.0, v10.17.0

N-API バージョン: 5

napi_status napi_create_date(napi_env env,
                             double time,
                             napi_value* result);

• [in] env: API が呼び出される環境。
• [in] time: 1970 年 1 月 1 日 UTC からのミリ秒単位の ECMAScript 時間値。
• [out] result: JavaScript のDateを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API はうるう秒を考慮しません。ECMAScript は POSIX 時間仕様に準拠しているので、無視されます。

この API は JavaScript のDateオブジェクトを割り当てます。

JavaScript のDateオブジェクトについては、ECMAScript 言語仕様のセクション 20.3を参照してください。

napi_create_external

追加日: v8.0.0

N-API バージョン: 1

napi_status napi_create_external(napi_env env,
                                 void* data,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)

• [in] env: API が呼び出される環境。
• [in] data: 外部データへの生ポインタ。
• [in] finalize_cb: 外部値が収集されるときに呼び出すオプションのコールバック。napi_finalizeで詳細を確認できます。
• [in] finalize_hint: 収集中にファイナライズコールバックに渡すオプションのヒント。
• [out] result: 外部値を表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、外部データが添付された JavaScript 値を割り当てます。これは、外部データを JavaScript コードに渡すために使用されるため、後でnapi_get_value_externalを使用してネイティブコードで取得できます。

この API は、作成された JavaScript オブジェクトがガベージコレクションされたときに呼び出されるnapi_finalizeコールバックを追加します。

作成された値はオブジェクトではないため、追加のプロパティはサポートされません。これは異なる値型と見なされます。外部値でnapi_typeof()を呼び出すとnapi_externalが返されます。

napi_create_external_arraybuffer

追加日時: v8.0.0

N-API バージョン: 1

napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)

• [in] env: API が呼び出される環境。
• [in] external_data: ArrayBufferの基となるバイトバッファへのポインタ。
• [in] byte_length: 基となるバッファの長さ（バイト単位）。
• [in] finalize_cb: ArrayBufferがガベージコレクションされる際に呼び出されるオプションのコールバック。napi_finalizeを参照ください。
• [in] finalize_hint: コレクション中にファイナライズコールバックに渡されるオプションのヒント。
• [out] result: JavaScript のArrayBufferを表すnapi_value。

API が成功した場合はnapi_okを返します。

Node.js 以外のいくつかのランタイムでは、外部バッファのサポートが廃止されています。 Node.js 以外のランタイムでは、このメソッドは外部バッファがサポートされていないことを示すnapi_no_external_buffers_allowedを返す場合があります。この例として、この issue electron/issues/35801で説明されているように、Electron があります。

すべてのランタイムとの幅広い互換性を維持するために、ノード API ヘッダーを含める前に、アドオンでNODE_API_NO_EXTERNAL_BUFFERS_ALLOWEDを定義できます。これにより、外部バッファを作成する 2 つの関数が非表示になり、誤ってこれらのメソッドのいずれかを使用した場合にコンパイルエラーが発生します。

この API は、JavaScript のArrayBufferに対応する Node-API 値を返します。ArrayBufferの基となるバイトバッファは外部で割り当てられ、管理されます。呼び出し元は、ファイナライズコールバックが呼び出されるまで、バイトバッファが有効な状態を維持する必要があります。

この API は、作成されたばかりの JavaScript オブジェクトがガベージコレクションされたときに呼び出されるnapi_finalizeコールバックを追加します。

JavaScript のArrayBufferについては、ECMAScript 言語仕様のセクション 24.1を参照してください。

napi_create_external_buffer

追加日: v8.0.0

N-API バージョン: 1

napi_status napi_create_external_buffer(napi_env env,
                                        size_t length,
                                        void* data,
                                        napi_finalize finalize_cb,
                                        void* finalize_hint,
                                        napi_value* result)

• [in] env: API が呼び出される環境。
• [in] length: 入力バッファのサイズ（バイト単位）（新規バッファのサイズと同じである必要があります）。
• [in] data: JavaScript に公開する基盤となるバッファへの生のポインタ。
• [in] finalize_cb: ArrayBufferが収集される際に呼び出すオプションのコールバック。napi_finalizeで詳細を確認できます。
• [in] finalize_hint: 収集中にファイナライズコールバックに渡すオプションのヒント。
• [out] result: node::Bufferを表すnapi_value。

API が成功した場合、napi_okを返します。

Node.js 以外のいくつかのランタイムは、外部バッファのサポートを削除しています。 Node.js 以外のランタイムでは、このメソッドは外部バッファがサポートされていないことを示すnapi_no_external_buffers_allowedを返す場合があります。この問題で説明されているように、Electron はそのようなランタイムの 1 つです。electron/issues/35801

すべてのランタイムとの最大限の互換性を維持するために、node-api ヘッダーのインクルードの前に、アドオンでNODE_API_NO_EXTERNAL_BUFFERS_ALLOWEDを定義できます。これにより、外部バッファを作成する 2 つの関数が非表示になります。これにより、これらのメソッドのいずれかを誤って使用した場合に、コンパイルエラーが発生します。

この API はnode::Bufferオブジェクトを割り当て、渡されたバッファによってサポートされるデータで初期化します。これは完全にサポートされているデータ構造ですが、ほとんどの場合、TypedArrayを使用するだけで十分です。

この API は、作成されたばかりの JavaScript オブジェクトがガベージコレクションされたときに呼び出されるnapi_finalizeコールバックを追加します。

Node.js >=4 では、BuffersはUint8Arrayです。

napi_create_object

追加版: v8.0.0

N-API バージョン: 1

napi_status napi_create_object(napi_env env, napi_value* result)

• [in] env: API が呼び出される環境。
• [out] result: JavaScript のObjectを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、デフォルトの JavaScript Objectを割り当てます。JavaScript のnew Object()と同等です。

JavaScript のObject型については、ECMAScript 言語仕様のセクション 6.1.7を参照してください。

napi_create_symbol

追加版: v8.0.0

N-API バージョン: 1

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result)

• [in] env: API が呼び出される環境。
• [in] description: シンボルの説明として設定される JavaScript stringを参照するオプションのnapi_value。
• [out] result: JavaScript のsymbolを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、UTF8 エンコードされた C 文字列から JavaScript のsymbol値を作成します。

JavaScript のsymbol型については、ECMAScript 言語仕様のセクション 19.4を参照してください。

node_api_symbol_for

追加版: v17.5.0, v16.15.0

N-API バージョン: 9

napi_status node_api_symbol_for(napi_env env,
                                const char* utf8description,
                                size_t length,
                                napi_value* result)

• [in] env: API が呼び出される環境。
• [in] utf8description: シンボルの説明として使用されるテキストを表す UTF-8 C 文字列。
• [in] length: 説明文字列の長さ（バイト単位）。ヌル終端の場合はNAPI_AUTO_LENGTH。
• [out] result: JavaScript のsymbolを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、グローバルレジストリ内で指定された説明を持つ既存のシンボルを検索します。シンボルが既に存在する場合はそれが返され、存在しない場合はレジストリに新しいシンボルが作成されます。

JavaScript のsymbol型については、ECMAScript 言語仕様のセクション 19.4を参照してください。

napi_create_typedarray

追加: v8.0.0

N-API バージョン: 1

napi_status napi_create_typedarray(napi_env env,
                                   napi_typedarray_type type,
                                   size_t length,
                                   napi_value arraybuffer,
                                   size_t byte_offset,
                                   napi_value* result)

• [in] env: API が呼び出される環境。
• [in] type: TypedArray内の要素のスカラーデータ型。
• [in] length: TypedArray内の要素数。
• [in] arraybuffer: 型付き配列を基にするArrayBuffer。
• [in] byte_offset: TypedArrayのプロジェクションを開始するArrayBuffer内のバイトオフセット。
• [out] result: JavaScript のTypedArrayを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、既存のArrayBuffer上に JavaScript のTypedArrayオブジェクトを作成します。TypedArrayオブジェクトは、各要素が同じ基になるバイナリのスカラーデータ型を持つ、基になるデータバッファに対する配列のようなビューを提供します。

(length * size_of_element) + byte_offsetは、渡された配列のバイトサイズ以下である必要があります。そうでない場合、RangeError例外が発生します。

JavaScript のTypedArrayオブジェクトについては、ECMAScript 言語仕様のセクション 22.2で説明されています。

node_api_create_buffer_from_arraybuffer

追加: v23.0.0

[安定版: 1 - 実験的]

安定版: 1 安定性: 1 - 実験的

napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
                                                              napi_value arraybuffer,
                                                              size_t byte_offset,
                                                              size_t byte_length,
                                                              napi_value* result)

• [in] env: API が呼び出される環境。
• [in] arraybuffer: バッファが作成されるArrayBuffer。
• [in] byte_offset: バッファの作成を開始するArrayBuffer内のバイトオフセット。
• [in] byte_length: ArrayBufferから作成されるバッファのバイト長。
• [out] result: 作成された JavaScript のBufferオブジェクトを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、既存のArrayBufferから JavaScript のBufferオブジェクトを作成します。Bufferオブジェクトは、Node.js 固有のクラスであり、JavaScript でバイナリデータを直接操作する方法を提供します。

バイト範囲[byte_offset, byte_offset + byte_length)は、ArrayBufferの範囲内にある必要があります。byte_offset + byte_lengthがArrayBufferのサイズを超える場合、RangeError例外が発生します。

napi_create_dataview

追加日: v8.3.0

N-API バージョン: 1

napi_status napi_create_dataview(napi_env env,
                                 size_t byte_length,
                                 napi_value arraybuffer,
                                 size_t byte_offset,
                                 napi_value* result)

• [in] env: API が呼び出される環境。
• [in] length: DataView内の要素数。
• [in] arraybuffer: DataViewの基となるArrayBuffer。
• [in] byte_offset: ArrayBuffer内でDataViewのプロジェクションを開始するバイトオフセット。
• [out] result: JavaScript のDataViewを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、既存のArrayBuffer上に JavaScript のDataViewオブジェクトを作成します。DataViewオブジェクトは、基となるデータバッファに対する配列のようなビューを提供しますが、ArrayBuffer内の異なるサイズと型のアイテムを許可するものです。

byte_length + byte_offsetは、渡された配列のバイトサイズ以下である必要があります。そうでない場合、RangeError例外が発生します。

JavaScript のDataViewオブジェクトについては、ECMAScript 言語仕様のセクション 24.3に記載されています。

C 型から Node-API への変換関数

napi_create_int32

追加日: v8.4.0

N-API バージョン: 1

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript で表現される整数値。
• [out] result: JavaScript のnumberを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、C のint32_t型から JavaScript のnumber型への変換に使用されます。

JavaScript のnumber型については、ECMAScript 言語仕様のセクション 6.1.6に記載されています。

napi_create_uint32

追加：v8.4.0

N-API バージョン：1

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript で表現される符号なし整数値。
• [out] result: JavaScript のnumberを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、C のuint32_t型から JavaScript のnumber型への変換に使用されます。

JavaScript のnumber型については、ECMAScript 言語仕様のセクション 6.1.6を参照してください。

napi_create_int64

追加：v8.4.0

N-API バージョン：1

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript で表現される整数値。
• [out] result: JavaScript のnumberを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、C のint64_t型から JavaScript のnumber型への変換に使用されます。

JavaScript のnumber型については、ECMAScript 言語仕様のセクション 6.1.6を参照してください。int64_tの完全な範囲は、JavaScript では完全な精度で表現できないことに注意してください。Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1)の範囲外の整数は精度が失われます。

napi_create_double

追加：v8.4.0

N-API バージョン：1

napi_status napi_create_double(napi_env env, double value, napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript で表現される倍精度値。
• [out] result: JavaScript のnumberを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、C のdouble型から JavaScript のnumber型への変換に使用されます。

JavaScript のnumber型については、ECMAScript 言語仕様のセクション 6.1.6を参照してください。

napi_create_bigint_int64

追加日時: v10.7.0

N-API バージョン: 6

napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result);

• [in] env: API が呼び出される環境。
• [in] value: JavaScript で表現される整数値。
• [out] result: JavaScript のBigIntを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、C のint64_t型を JavaScript のBigInt型に変換します。

napi_create_bigint_uint64

追加日時: v10.7.0

N-API バージョン: 6

napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result);

• [in] env: API が呼び出される環境。
• [in] value: JavaScript で表現される符号なし整数値。
• [out] result: JavaScript のBigIntを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、C のuint64_t型を JavaScript のBigInt型に変換します。

napi_create_bigint_words

追加日時: v10.7.0

N-API バージョン: 6

napi_status napi_create_bigint_words(napi_env env,
                                     int sign_bit,
                                     size_t word_count,
                                     const uint64_t* words,
                                     napi_value* result);

• [in] env: API が呼び出される環境。
• [in] sign_bit: 結果のBigIntが正か負かを決定します。
• [in] word_count: words配列の長さ。
• [in] words: uint64_tのリトルエンディアン 64 ビットワードの配列。
• [out] result: JavaScript のBigIntを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、符号なし 64 ビットワードの配列を単一のBigInt値に変換します。

結果のBigIntは、(–1)^sign_bit(words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)として計算されます。

napi_create_string_latin1

追加日時: v8.0.0

N-API バージョン: 1

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result);

• [in] env: API が呼び出される環境。
• [in] str: ISO-8859-1 エンコードされた文字列を表す文字バッファ。
• [in] length: バイト単位の文字列の長さ、またはヌル終端の場合 NAPI_AUTO_LENGTH。
• [out] result: JavaScript の string を表す napi_value。

API が成功した場合は napi_ok を返します。

この API は、ISO-8859-1 エンコードされた C 文字列から JavaScript の string 値を作成します。ネイティブ文字列はコピーされます。

JavaScript の string 型については、ECMAScript 言語仕様の セクション 6.1.4 を参照してください。

node_api_create_external_string_latin1

追加日時: v20.4.0, v18.18.0

[安定版: 1 - 実験的]

安定版: 1 安定性: 1 - 実験的

napi_status
node_api_create_external_string_latin1(napi_env env,
                                       char* str,
                                       size_t length,
                                       napi_finalize finalize_callback,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied);

• [in] env: API が呼び出される環境。

• [in] str: ISO-8859-1 エンコードされた文字列を表す文字バッファ。

• [in] length: バイト単位の文字列の長さ、またはヌル終端の場合 NAPI_AUTO_LENGTH。

• [in] finalize_callback: 文字列が収集されるときに呼び出される関数。この関数は以下のパラメータで呼び出されます。

  • [in] env: アドオンが実行されている環境。ワーカーまたはメインの Node.js インスタンスの終了の一環として文字列が収集されている場合、この値は null になる可能性があります。
  • [in] data: void* ポインタとしての str の値。
  • [in] finalize_hint: API に渡された finalize_hint の値。napi_finalize は詳細を提供します。このパラメータはオプションです。null 値を渡すと、対応する JavaScript 文字列が収集されたときにアドオンに通知する必要がなくなります。

• [in] finalize_hint: 収集中にファイナライズコールバックに渡すオプションのヒント。

• [out] result: JavaScript の string を表す napi_value。

• [out] copied: 文字列がコピーされたかどうか。コピーされた場合、ファイナライザは既に str の破棄を呼び出しています。

API が成功した場合は napi_ok を返します。

この API は、ISO-8859-1 エンコードされた C 文字列から JavaScript の string 値を作成します。ネイティブ文字列はコピーされない場合があり、そのため JavaScript 値のライフサイクル全体にわたって存在する必要があります。

JavaScript の string 型については、ECMAScript 言語仕様の セクション 6.1.4 を参照してください。

napi_create_string_utf16

追加: v8.0.0

N-API バージョン: 1

napi_status napi_create_string_utf16(napi_env env,
                                     const char16_t* str,
                                     size_t length,
                                     napi_value* result)

• [in] env: API が呼び出される環境。
• [in] str: UTF16-LE エンコードされた文字列を表す文字バッファ。
• [in] length: 2 バイトコード単位での文字列の長さ、またはヌル終端の場合は NAPI_AUTO_LENGTH。
• [out] result: JavaScript の string を表す napi_value。

API が成功した場合は napi_ok を返します。

この API は、UTF16-LE エンコードされた C 文字列から JavaScript の string 値を作成します。ネイティブ文字列はコピーされます。

JavaScript の string 型については、ECMAScript 言語仕様の セクション 6.1.4 を参照してください。

node_api_create_external_string_utf16

追加: v20.4.0, v18.18.0

[安定版: 1 - 実験的]

安定版: 1 安定性: 1 - 実験的

napi_status
node_api_create_external_string_utf16(napi_env env,
                                      char16_t* str,
                                      size_t length,
                                      napi_finalize finalize_callback,
                                      void* finalize_hint,
                                      napi_value* result,
                                      bool* copied);

• [in] env: API が呼び出される環境。

• [in] str: UTF16-LE エンコードされた文字列を表す文字バッファ。

• [in] length: 2 バイトコード単位での文字列の長さ、またはヌル終端の場合は NAPI_AUTO_LENGTH。

• [in] finalize_callback: 文字列が収集されるときに呼び出される関数。関数は以下のパラメータで呼び出されます。

  • [in] env: アドオンが実行されている環境。ワーカーまたはメインの Node.js インスタンスの終了の一環として文字列が収集されている場合は、null になる可能性があります。
  • [in] data: void* ポインタとしての str の値。
  • [in] finalize_hint: API に渡された finalize_hint の値。napi_finalize に詳細があります。このパラメータはオプションです。null 値を渡すと、対応する JavaScript 文字列が収集されたときにアドオンに通知する必要がなくなります。

• [in] finalize_hint: 収集中にファイナライズコールバックに渡すオプションのヒント。

• [out] result: JavaScript の string を表す napi_value。

• [out] copied: 文字列がコピーされたかどうか。コピーされた場合、ファイナライザはすでに str を破棄するために呼び出されています。

API が成功した場合は napi_ok を返します。

この API は、UTF16-LE エンコードされた C 文字列から JavaScript の string 値を作成します。ネイティブ文字列はコピーされない場合があり、そのため JavaScript 値のライフサイクル全体にわたって存在する必要があります。

JavaScript の string 型については、ECMAScript 言語仕様の セクション 6.1.4 を参照してください。

napi_create_string_utf8

追加日時: v8.0.0

N-API バージョン: 1

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result)

• [in] env: API が呼び出される環境。
• [in] str: UTF8 エンコードされた文字列を表す文字バッファ。
• [in] length: バイト単位の文字列の長さ。ヌル終端の場合は NAPI_AUTO_LENGTH。
• [out] result: JavaScript の string を表す napi_value。

API が成功した場合は napi_ok を返します。

この API は、UTF8 エンコードされた C 文字列から JavaScript の string 値を作成します。ネイティブ文字列はコピーされます。

JavaScript の string 型については、ECMAScript 言語仕様の セクション 6.1.4 を参照してください。

最適化されたプロパティキーを作成する関数

V8 を含む多くの JavaScript エンジンは、プロパティ値の設定と取得に内部化された文字列をキーとして使用します。通常、ハッシュテーブルを使用してこのような文字列を作成および検索します。キーの作成ごとに多少のコストは追加されますが、文字列全体ではなく文字列ポインタの比較を可能にすることで、その後パフォーマンスが向上します。

新しい JavaScript 文字列をプロパティキーとして使用することを意図している場合、一部の JavaScript エンジンでは、このセクションの関数を使用する方が効率的です。それ以外の場合は、プロパティキー作成メソッドで文字列の作成/保存に追加のオーバーヘッドが発生する可能性があるため、napi_create_string_utf8 または node_api_create_external_string_utf8 シリーズの関数を使用してください。

node_api_create_property_key_latin1

追加日時: v22.9.0, v20.18.0

[安定版: 1 - 試験的]

安定版: 1 安定性: 1 - 試験的

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result);

• [in] env: API が呼び出される環境。
• [in] str: ISO-8859-1 エンコードされた文字列を表す文字バッファ。
• [in] length: バイト単位の文字列の長さ。ヌル終端の場合は NAPI_AUTO_LENGTH。
• [out] result: オブジェクトのプロパティキーとして使用する最適化された JavaScript string を表す napi_value。

API が成功した場合は napi_ok を返します。

この API は、オブジェクトのプロパティキーとして使用する、ISO-8859-1 エンコードされた C 文字列から最適化された JavaScript の string 値を作成します。ネイティブ文字列はコピーされます。napi_create_string_latin1 とは対照的に、同じ str ポインタでこの関数を繰り返し呼び出すと、エンジンによっては要求された napi_value の作成速度が向上する可能性があります。

JavaScript の string 型については、ECMAScript 言語仕様の セクション 6.1.4 を参照してください。

node_api_create_property_key_utf16

追加日時: v21.7.0, v20.12.0

[安定版: 1 - 試験段階]

安定版: 1 安定性: 1 - 試験段階

napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
                                                          const char16_t* str,
                                                          size_t length,
                                                          napi_value* result);

• [in] env: API が呼び出される環境。
• [in] str: UTF16-LE エンコードされた文字列を表す文字バッファ。
• [in] length: 2 バイトコード単位での文字列の長さ、またはヌル終端の場合NAPI_AUTO_LENGTH。
• [out] result: オブジェクトのプロパティキーとして使用される最適化された JavaScript stringを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、オブジェクトのプロパティキーとして使用される UTF16-LE エンコードされた C 文字列から、最適化された JavaScript string値を作成します。ネイティブ文字列はコピーされます。

JavaScript string型については、ECMAScript 言語仕様のセクション 6.1.4を参照してください。

node_api_create_property_key_utf8

追加日時: v22.9.0, v20.18.0

[安定版: 1 - 試験段階]

安定版: 1 安定性: 1 - 試験段階

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result);

• [in] env: API が呼び出される環境。
• [in] str: UTF8 エンコードされた文字列を表す文字バッファ。
• [in] length: 2 バイトコード単位での文字列の長さ、またはヌル終端の場合NAPI_AUTO_LENGTH。
• [out] result: オブジェクトのプロパティキーとして使用される最適化された JavaScript stringを表すnapi_value。

API が成功した場合、napi_okを返します。

この API は、オブジェクトのプロパティキーとして使用される UTF8 エンコードされた C 文字列から、最適化された JavaScript string値を作成します。ネイティブ文字列はコピーされます。

JavaScript string型については、ECMAScript 言語仕様のセクション 6.1.4を参照してください。

Node-API から C 型への変換関数

napi_get_array_length

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result)

• [in] env: API が呼び出される環境。
• [in] value: 長さを問い合わせる JavaScript のArrayを表すnapi_value。
• [out] result: 配列の長さを表すuint32。

API が成功した場合、napi_okを返します。

この API は配列の長さを返します。

Arrayの長さは、ECMAScript 言語仕様のセクション 22.1.4.1で説明されています。

napi_get_arraybuffer_info

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length)

• [in] env: API が呼び出される環境。
• [in] arraybuffer: 問い合わせるArrayBufferを表すnapi_value。
• [out] data: ArrayBufferの基となるデータバッファ。byte_lengthが0の場合、NULLまたはその他のポインタ値になる可能性があります。
• [out] byte_length: 基となるデータバッファの長さ（バイト単位）。

API が成功した場合、napi_okを返します。

この API は、ArrayBufferの基となるデータバッファとその長さを取得するために使用されます。

警告：この API を使用する際には注意が必要です。基となるデータバッファのライフタイムは、返された後でもArrayBufferによって管理されます。この API を安全に使用する方法の 1 つは、napi_create_referenceと組み合わせて使用することです。これにより、ArrayBufferのライフタイムを制御できます。他の API への呼び出しによって GC がトリガーされる可能性がない限り、同じコールバック内で返されたデータバッファを使用することも安全です。

napi_get_buffer_info

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length)

• [in] env: API が呼び出される環境。
• [in] value: クエリ対象の node::Buffer または Uint8Array を表す napi_value。
• [out] data: node::Buffer または Uint8Array の基になるデータバッファ。length が 0 の場合、NULL またはその他のポインタ値になる可能性があります。
• [out] length: 基になるデータバッファの長さ（バイト単位）。

API が成功した場合は napi_ok を返します。

このメソッドは、napi_get_typedarray_info と同じ data と byte_length を返します。また、napi_get_typedarray_info は node::Buffer（Uint8Array）も値として受け付けます。

この API は、node::Bufferの基になるデータバッファとその長さを取得するために使用されます。

警告：この API を使用する際には注意してください。VM によって管理されている場合、基になるデータバッファのライフタイムは保証されません。

napi_get_prototype

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result)

• [in] env: API が呼び出される環境。
• [in] object: プロトタイプを返す JavaScript Object を表す napi_value。これは Object.getPrototypeOf と同等です（関数の prototype プロパティとは異なります）。
• [out] result: 指定されたオブジェクトのプロトタイプを表す napi_value。

API が成功した場合は napi_ok を返します。

napi_get_typedarray_info

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_typedarray_info(napi_env env,
                                     napi_value typedarray,
                                     napi_typedarray_type* type,
                                     size_t* length,
                                     void** data,
                                     napi_value* arraybuffer,
                                     size_t* byte_offset)

• [in] env: API が呼び出される環境。
• [in] typedarray: プロパティをクエリする TypedArray を表す napi_value。
• [out] type: TypedArray 内の要素のスカラーデータ型。
• [out] length: TypedArray 内の要素数。
• [out] data: TypedArray の基になるデータバッファ。byte_offset の値によって調整され、TypedArray の最初の要素を指します。配列の長さが 0 の場合、NULL またはその他のポインタ値になる可能性があります。
• [out] arraybuffer: TypedArray の基になる ArrayBuffer。
• [out] byte_offset: 基になるネイティブ配列内で配列の最初の要素が位置するバイトオフセット。data パラメータの値は既に調整されており、data は配列の最初の要素を指しています。したがって、ネイティブ配列の最初のバイトは data - byte_offset にあります。

API が成功した場合は napi_ok を返します。

この API は、型付き配列の様々なプロパティを返します。

不要なプロパティについては、出力パラメータを NULL にすることができます。

警告：この API を使用する際には注意してください。基になるデータバッファは VM によって管理されています。

napi_get_dataview_info

追加バージョン: v8.3.0

N-API バージョン: 1

napi_status napi_get_dataview_info(napi_env env,
                                   napi_value dataview,
                                   size_t* byte_length,
                                   void** data,
                                   napi_value* arraybuffer,
                                   size_t* byte_offset)

• [in] env: API が呼び出される環境。
• [in] dataview: プロパティを問い合わせるDataViewを表すnapi_value。
• [out] byte_length: DataViewのバイト数。
• [out] data: DataViewを基礎とするデータバッファ。byte_lengthが0の場合、NULLまたはその他のポインタ値になる可能性があります。
• [out] arraybuffer: DataViewを基礎とするArrayBuffer。
• [out] byte_offset: DataViewのプロジェクションを開始するデータバッファ内のバイトオフセット。

API が成功した場合はnapi_okを返します。

出力パラメータのいずれかを、そのプロパティが不要な場合はNULLにすることができます。

この API はDataViewの様々なプロパティを返します。

napi_get_date_value

追加バージョン: v11.11.0, v10.17.0

N-API バージョン: 5

napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のDateを表すnapi_value。
• [out] result: 1970 年 1 月 1 日 0 時 0 分 0 秒 UTC からのミリ秒単位で表されたdouble型の時間値。

この API はうるう秒を考慮しません。ECMAScript は POSIX 時刻仕様に準拠しているため、無視されます。

API が成功した場合はnapi_okを返します。日付以外のnapi_valueが渡された場合はnapi_date_expectedを返します。

この API は、指定された JavaScriptDateの時間値の C のdouble型プリミティブを返します。

napi_get_value_bool

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のBooleanを表すnapi_value。
• [out] result: 指定された JavaScriptBooleanに相当する C のbool型プリミティブ。

API が成功した場合はnapi_okを返します。bool型以外のnapi_valueが渡された場合はnapi_boolean_expectedを返します。

この API は、指定された JavaScriptBooleanに相当する C のbool型プリミティブを返します。

napi_get_value_double

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のnumberを表すnapi_value。
• [out] result: 指定された JavaScriptnumberに相当する C の double 型プリミティブ。

API が成功した場合、napi_okを返します。数値以外のnapi_valueが渡された場合、napi_number_expectedを返します。

この API は、指定された JavaScript のnumberに相当する C の double 型プリミティブを返します。

napi_get_value_bigint_int64

追加バージョン: v10.7.0

N-API バージョン: 6

napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless);

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のBigIntを表すnapi_value。
• [out] result: 指定された JavaScriptBigIntに相当する C のint64_t型プリミティブ。
• [out] lossless: BigInt値がロスレスに変換されたかどうかを示します。

API が成功した場合、napi_okを返します。BigInt以外が渡された場合、napi_bigint_expectedを返します。

この API は、指定された JavaScript のBigIntに相当する C のint64_t型プリミティブを返します。必要に応じて値を切り捨て、losslessをfalseに設定します。

napi_get_value_bigint_uint64

追加バージョン: v10.7.0

N-API バージョン: 6

napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless);

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のBigIntを表すnapi_value。
• [out] result: 指定された JavaScriptBigIntに相当する C のuint64_t型プリミティブ。
• [out] lossless: BigInt値がロスレスに変換されたかどうかを示します。

API が成功した場合、napi_okを返します。BigInt以外が渡された場合、napi_bigint_expectedを返します。

この API は、指定された JavaScript のBigIntに相当する C のuint64_t型プリミティブを返します。必要に応じて値を切り捨て、losslessをfalseに設定します。

napi_get_value_bigint_words

追加日: v10.7.0

N-API バージョン: 6

napi_status napi_get_value_bigint_words(napi_env env,
                                        napi_value value,
                                        int* sign_bit,
                                        size_t* word_count,
                                        uint64_t* words);

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のBigIntを表すnapi_value。
• [out] sign_bit: JavaScript のBigIntが正か負かを表す整数。
• [in/out] word_count: words配列の長さに初期化される必要があります。戻り値では、このBigIntを格納するために必要な単語の実際の数が設定されます。
• [out] words: 事前に割り当てられた 64 ビット単語配列へのポインタ。

API が成功した場合はnapi_okを返します。

この API は、単一のBigInt値を符号ビット、64 ビットリトルエンディアン配列、および配列の要素数に変換します。word_countのみを取得するために、sign_bitとwordsの両方をNULLに設定できます。

napi_get_value_external

追加日: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript の外部値を表すnapi_value。
• [out] result: JavaScript の外部値によってラップされたデータへのポインタ。

API が成功した場合はnapi_okを返します。外部ではないnapi_valueが渡された場合はnapi_invalid_argを返します。

この API は、以前にnapi_create_external()に渡された外部データポインタを取得します。

napi_get_value_int32

追加日: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のnumberを表すnapi_value。
• [out] result: 指定された JavaScriptnumberに相当する C のint32プリミティブ。

API が成功した場合はnapi_okを返します。数値以外のnapi_valueが渡された場合はnapi_number_expectedを返します。

この API は、指定された JavaScriptnumberに相当する C のint32プリミティブを返します。

数値が 32 ビット整数の範囲を超える場合、結果は下位 32 ビットに相当する値に切り捨てられます。これにより、値が 2³² - 1 より大きい場合、大きな正の数が負の数になる可能性があります。

非有限数値(NaN, +Infinity, または-Infinity)は、結果をゼロに設定します。

napi_get_value_int64

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript の number を表す napi_value。
• [out] result: 指定された JavaScript number に相当する C の int64 プリミティブ。

API が成功した場合は napi_ok を返します。数値以外の napi_value が渡された場合は napi_number_expected を返します。

この API は、指定された JavaScript のnumberに相当する C のint64プリミティブを返します。

Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) の範囲外の number 値は精度を失います。

非有限数値（NaN、+Infinity、または -Infinity）は、結果をゼロに設定します。

napi_get_value_string_latin1

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_string_latin1(napi_env env,
                                         napi_value value,
                                         char* buf,
                                         size_t bufsize,
                                         size_t* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript の文字列を表す napi_value。
• [in] buf: ISO-8859-1 エンコードされた文字列を書き込むバッファ。NULL が渡された場合、ヌル終端子を除く文字列の長さ（バイト数）が result に返されます。
• [in] bufsize: 宛先バッファのサイズ。この値が不十分な場合、返される文字列は切り捨てられ、ヌル終端されます。
• [out] result: バッファにコピーされたバイト数（ヌル終端子を除く）。

API が成功した場合は napi_ok を返します。文字列以外の napi_value が渡された場合は napi_string_expected を返します。

この API は、渡された値に対応する ISO-8859-1 エンコードされた文字列を返します。

napi_get_value_string_utf8

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript 文字列を表すnapi_value。
• [in] buf: UTF8 エンコードされた文字列を書き込むバッファ。NULLが渡された場合、ヌル終端文字を除く文字列の長さ（バイト数）がresultに返される。
• [in] bufsize: 宛先バッファのサイズ。この値が不十分な場合、返された文字列は切り詰められ、ヌル終端される。
• [out] result: バッファにコピーされたバイト数（ヌル終端文字を除く）。

API が成功した場合、napi_okを返す。非stringのnapi_valueが渡された場合、napi_string_expectedを返す。

この API は、渡された値に対応する UTF8 エンコードされた文字列を返す。

napi_get_value_string_utf16

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_string_utf16(napi_env env,
                                        napi_value value,
                                        char16_t* buf,
                                        size_t bufsize,
                                        size_t* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript 文字列を表すnapi_value。
• [in] buf: UTF16-LE エンコードされた文字列を書き込むバッファ。NULLが渡された場合、ヌル終端文字を除く文字列の長さ（2 バイトコードユニット数）が返される。
• [in] bufsize: 宛先バッファのサイズ。この値が不十分な場合、返された文字列は切り詰められ、ヌル終端される。
• [out] result: バッファにコピーされた 2 バイトコードユニット数（ヌル終端文字を除く）。

API が成功した場合、napi_okを返す。非stringのnapi_valueが渡された場合、napi_string_expectedを返す。

この API は、渡された値に対応する UTF16 エンコードされた文字列を返す。

napi_get_value_uint32

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result)

• [in] env: API が呼び出される環境。
• [in] value: JavaScript のnumberを表すnapi_value。
• [out] result: 与えられたnapi_valueの C プリミティブ型相当のuint32_t。

API が成功した場合はnapi_okを返します。数値以外のnapi_valueが渡された場合はnapi_number_expectedを返します。

この API は、与えられたnapi_valueの C プリミティブ型相当のuint32_tを返します。

グローバルインスタンスを取得する関数

napi_get_boolean

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: 取得するブール値。
• [out] result: 取得する JavaScript のBooleanシングルトンを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、与えられたブール値を表す JavaScript シングルトンオブジェクトを返します。

napi_get_global

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_global(napi_env env, napi_value* result)

• [in] env: API が呼び出される環境。
• [out] result: JavaScript のglobalオブジェクトを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API はglobalオブジェクトを返します。

napi_get_null

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_null(napi_env env, napi_value* result)

• [in] env: API が呼び出される環境。
• [out] result: JavaScript のnullオブジェクトを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API はnullオブジェクトを返します。

napi_get_undefined

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_undefined(napi_env env, napi_value* result)

• [in] env: API が呼び出される環境。
• [out] result: JavaScript の Undefined 値を表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は Undefined オブジェクトを返します。

JavaScript 値と抽象操作の操作

Node-API は、JavaScript 値に対していくつかの抽象操作を実行するための API セットを提供します。これらの操作の一部は、セクション 7のECMAScript 言語仕様で説明されています。

これらの API は、以下のいずれかの操作をサポートします。

napi_coerce_to_bool

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: 強制変換する JavaScript 値。
• [out] result: 強制変換された JavaScript Booleanを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、ECMAScript 言語仕様のセクション 7.1.2で定義されている抽象操作ToBoolean()を実装します。

napi_coerce_to_number

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_coerce_to_number(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: 強制変換する JavaScript 値。
• [out] result: 強制変換された JavaScript numberを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、ECMAScript 言語仕様のセクション 7.1.3で定義されている抽象操作ToNumber()を実装します。渡された値がオブジェクトの場合、この関数は JS コードを実行する可能性があります。

napi_coerce_to_object

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_coerce_to_object(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: 強制変換する JavaScript 値。
• [out] result: 強制変換された JavaScript Objectを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、ECMAScript 言語仕様のセクション 7.1.13で定義されている抽象操作ToObject()を実装します。

napi_coerce_to_string

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_coerce_to_string(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: API が呼び出される環境。
• [in] value: 強制変換する JavaScript 値。
• [out] result: 強制変換された JavaScript stringを表すnapi_value。

API が成功した場合はnapi_okを返します。

この API は、ECMAScript 言語仕様のセクション 7.1.13で定義されている抽象操作ToString()を実装します。渡された値がオブジェクトの場合、この関数は JS コードを実行する可能性があります。

napi_typeof

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)

• [in] env: API が呼び出される環境。
• [in] value: 型を照会する JavaScript 値。
• [out] result: JavaScript 値の型。

API が成功した場合はnapi_okを返します。

• valueの型が既知の ECMAScript 型ではなく、valueが外部値でない場合はnapi_invalid_arg。

この API は、ECMAScript 言語仕様のセクション 12.5.5で定義されているオブジェクトに対するtypeof演算子の呼び出しと同様の動作を表します。ただし、いくつかの違いがあります。

valueの型が無効な場合、エラーが返されます。

napi_instanceof

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_instanceof(napi_env env,
                            napi_value object,
                            napi_value constructor,
                            bool* result)

• [in] env: API が呼び出される環境。
• [in] object: チェックする JavaScript 値。
• [in] constructor: チェックするコンストラクタ関数の JavaScript 関数オブジェクト。
• [out] result: object instanceof constructorが true の場合、true に設定されるブール値。

API が成功した場合はnapi_okを返します。

この API は、ECMAScript 言語仕様のセクション 12.10.4で定義されているオブジェクトに対するinstanceof演算子の呼び出しを表します。

napi_is_array

追加: v8.0.0

N-API バージョン: 1

napi_status napi_is_array(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定されたオブジェクトが配列かどうか。

API が成功した場合、napi_ok を返します。

この API は、ECMAScript 言語仕様の セクション 7.2.2 で定義されているオブジェクトに対する IsArray 操作の呼び出しを表します。

napi_is_arraybuffer

追加: v8.0.0

N-API バージョン: 1

napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定されたオブジェクトが ArrayBuffer かどうか。

API が成功した場合、napi_ok を返します。

この API は、渡された Object が ArrayBuffer かどうかをチェックします。

napi_is_buffer

追加: v8.0.0

N-API バージョン: 1

napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定された napi_value が node::Buffer または Uint8Array オブジェクトを表しているかどうか。

API が成功した場合、napi_ok を返します。

この API は、渡された Object がバッファまたは Uint8Array かどうかをチェックします。値が Uint8Array かどうかをチェックする必要がある場合は、napi_is_typedarray を優先する必要があります。

napi_is_date

追加: v11.11.0, v10.17.0

N-API バージョン: 5

napi_status napi_is_date(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定された napi_value が JavaScript の Date オブジェクトを表しているかどうか。

API が成功した場合、napi_ok を返します。

この API は、渡された Object が日付かどうかをチェックします。

napi_is_error

追加: v8.0.0

N-API バージョン: 1

napi_status napi_is_error(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定された napi_value が Error オブジェクトを表すかどうか。

API が成功した場合、napi_ok を返します。

この API は、渡されたObjectがErrorであるかどうかをチェックします。

napi_is_typedarray

追加: v8.0.0

N-API バージョン: 1

napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定された napi_value が TypedArray を表すかどうか。

API が成功した場合、napi_ok を返します。

この API は、渡されたObjectが TypedArray であるかどうかをチェックします。

napi_is_dataview

追加: v8.3.0

N-API バージョン: 1

napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)

• [in] env: API が呼び出される環境。
• [in] value: チェックする JavaScript の値。
• [out] result: 指定された napi_value が DataView を表すかどうか。

API が成功した場合、napi_ok を返します。

この API は、渡されたObjectがDataViewであるかどうかをチェックします。

napi_strict_equals

追加: v8.0.0

N-API バージョン: 1

napi_status napi_strict_equals(napi_env env,
                               napi_value lhs,
                               napi_value rhs,
                               bool* result)

• [in] env: API が呼び出される環境。
• [in] lhs: チェックする JavaScript の値。
• [in] rhs: 比較する JavaScript の値。
• [out] result: 2 つの napi_value オブジェクトが等しいかどうか。

API が成功した場合、napi_ok を返します。

この API は、ECMAScript 言語仕様のセクション 7.2.14で定義されている厳密等価比較アルゴリズムの呼び出しを表します。

napi_detach_arraybuffer

追加されたバージョン: v13.0.0, v12.16.0, v10.22.0

N-API バージョン: 7

napi_status napi_detach_arraybuffer(napi_env env,
                                    napi_value arraybuffer)

• [in] env: API が呼び出される環境。
• [in] arraybuffer: 分離される JavaScript の ArrayBuffer。

API が成功した場合は napi_ok を返します。分離不可能な ArrayBuffer が渡された場合は napi_detachable_arraybuffer_expected を返します。

一般的に、ArrayBuffer は以前に分離されている場合、分離不可能です。エンジンは、ArrayBuffer が分離可能かどうかについて、追加の条件を課す場合があります。たとえば、V8 では、ArrayBuffer が外部であること、つまり napi_create_external_arraybuffer で作成されている必要があります。

この API は、ECMAScript 言語仕様のセクション 24.1.1.3で定義されているArrayBufferの分離操作の呼び出しを表しています。

napi_is_detached_arraybuffer

追加されたバージョン: v13.3.0, v12.16.0, v10.22.0

N-API バージョン: 7

napi_status napi_is_detached_arraybuffer(napi_env env,
                                         napi_value arraybuffer,
                                         bool* result)

• [in] env: API が呼び出される環境。
• [in] arraybuffer: チェックされる JavaScript の ArrayBuffer。
• [out] result: arraybuffer が分離されているかどうか。

API が成功した場合は napi_ok を返します。

内部データが null の場合、ArrayBuffer は分離されていると見なされます。

この API は、ECMAScript 言語仕様のセクション 24.1.1.2で定義されているArrayBufferのIsDetachedBuffer操作の呼び出しを表しています。

JavaScript プロパティの操作

Node-API は、JavaScript オブジェクトのプロパティを取得および設定するための API のセットを提供します。これらの型のいくつかは、ECMAScript 言語仕様のセクション 7で説明されています。

JavaScript のプロパティは、キーと値のタプルとして表されます。基本的に、Node-API のすべてのプロパティキーは、次のいずれかの形式で表すことができます。

• 名前付き: 単純な UTF8 エンコードされた文字列
• 整数インデックス付き: uint32_t で表されるインデックス値
• JavaScript 値: これらは Node-API では napi_value で表されます。これは、string、number、または symbol を表す napi_value である可能性があります。

Node-API の値は、型 napi_value で表されます。JavaScript の値を必要とする Node-API の呼び出しでは、napi_value が使用されます。ただし、問題の napi_value が API で期待される JavaScript の型であることを確認するのは、呼び出し元の責任です。

このセクションで説明されている API は、napi_value で表される任意の JavaScript オブジェクトのプロパティを取得および設定するための単純なインターフェースを提供します。

たとえば、次の JavaScript コードスニペットを考えてみましょう。

const obj = {}
obj.myProp = 123

同等の操作は、次のスニペットを使用して Node-API の値で行うことができます。

napi_status status = napi_generic_failure;

// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;

// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;

インデックス付きのプロパティは、同様の方法で設定できます。次の JavaScript スニペットを考えてみましょう。

const arr = []
arr[123] = 'hello'

同等の操作は、次のスニペットを使用して Node-API の値で行うことができます。

napi_status status = napi_generic_failure;

// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;

// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;

プロパティは、このセクションで説明されている API を使用して取得できます。次の JavaScript スニペットを考えてみましょう。

const arr = []
const value = arr[123]

Node-API の対応する部分のおおよその同等物は次のとおりです。

napi_status status = napi_generic_failure;

// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;

最後に、パフォーマンス上の理由から、複数のプロパティをオブジェクトに定義することもできます。次の JavaScript を考えてみましょう。

const obj = {}
Object.defineProperties(obj, {
  foo: { value: 123, writable: true, configurable: true, enumerable: true },
  bar: { value: 456, writable: true, configurable: true, enumerable: true },
})

Node-API の対応する部分のおおよその同等物は次のとおりです。

napi_status status = napi_status_generic_failure;

// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;

// Set the properties
napi_property_descriptor descriptors[] = {
  { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
  { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
                                obj,
                                sizeof(descriptors) / sizeof(descriptors[0]),
                                descriptors);
if (status != napi_ok) return status;

構造体

napi_property_attributes

[履歴]

バージョン	変更内容
v14.12.0	napi_default_method と napi_default_property を追加

typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // 静的プロパティとインスタンスプロパティを区別するために napi_define_class で使用されます。
  // napi_define_properties では無視されます。
  napi_static = 1 << 10,

  // クラスメソッドのデフォルト。
  napi_default_method = napi_writable | napi_configurable,

  // JS の obj[prop] のようなオブジェクトプロパティのデフォルト。
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes;

napi_property_attributes は、JavaScript オブジェクトに設定されたプロパティの動作を制御するために使用されるフラグです。napi_static を除き、ECMAScript 言語仕様のセクション 6.1.7.1にリストされている属性に対応しています。以下のビットフラグのいずれか、または複数を組み合わせることができます。

• napi_default: プロパティに明示的な属性が設定されていません。デフォルトでは、プロパティは読み取り専用で、列挙可能ではなく、構成可能ではありません。
• napi_writable: プロパティは書き込み可能です。
• napi_enumerable: プロパティは列挙可能です。
• napi_configurable: プロパティは、ECMAScript 言語仕様のセクション 6.1.7.1で定義されているように構成可能です。
• napi_static: プロパティは、デフォルトのインスタンスプロパティではなく、クラスの静的プロパティとして定義されます。これはnapi_define_classによってのみ使用され、napi_define_propertiesでは無視されます。
• napi_default_method: JS クラスのメソッドと同様に、プロパティは構成可能で書き込み可能ですが、列挙可能ではありません。
• napi_default_jsproperty: JavaScript での代入によって設定されたプロパティと同様に、プロパティは書き込み可能、列挙可能、および構成可能です。

napi_property_descriptor

typedef struct {
  // utf8nameまたはnameのいずれかはNULLにする必要があります。
  const char* utf8name;
  napi_value name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor;

• utf8name: プロパティのキーを表すオプションの文字列で、UTF8 でエンコードされています。プロパティにはutf8nameまたはnameのいずれか一方を指定する必要があります。
• name: プロパティのキーとして使用される JavaScript 文字列またはシンボルを指すオプションのnapi_valueです。プロパティにはutf8nameまたはnameのいずれか一方を指定する必要があります。
• value: プロパティがデータプロパティの場合、プロパティの取得アクセスによって取得される値です。これが渡された場合、getter、setter、method、dataをNULLに設定します（これらのメンバは使用されません）。
• getter: プロパティの取得アクセスが実行されたときに呼び出される関数です。これが渡された場合、valueとmethodをNULLに設定します（これらのメンバは使用されません）。この関数は、プロパティが JavaScript コードからアクセスされた場合（または Node-API 呼び出しを使用してプロパティの取得が実行された場合）、ランタイムによって暗黙的に呼び出されます。詳細はnapi_callbackを参照してください。
• setter: プロパティの設定アクセスが実行されたときに呼び出される関数です。これが渡された場合、valueとmethodをNULLに設定します（これらのメンバは使用されません）。この関数は、プロパティが JavaScript コードから設定された場合（または Node-API 呼び出しを使用してプロパティの設定が実行された場合）、ランタイムによって暗黙的に呼び出されます。詳細はnapi_callbackを参照してください。
• method: これにより、プロパティ記述子オブジェクトのvalueプロパティがmethodで表される JavaScript 関数になります。これが渡された場合、value、getter、setterをNULLに設定します（これらのメンバは使用されません）。詳細はnapi_callbackを参照してください。
• attributes: 特定のプロパティに関連付けられた属性です。napi_property_attributesを参照してください。
• data: この関数が呼び出された場合、method、getter、setterに渡されるコールバックデータです。

関数

napi_get_property_names

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result);

• [in] env: Node-API コールが呼び出される環境。
• [in] object: プロパティを取得するオブジェクト。
• [out] result: オブジェクトのプロパティ名を表す JavaScript 値の配列を表す napi_value。napi_get_array_length と napi_get_element を使用して result を反復処理できます。

API が成功した場合は napi_ok を返します。

この API は、object の列挙可能なプロパティの名前を文字列の配列として返します。キーがシンボルである object のプロパティは含まれません。

napi_get_all_property_names

追加されたバージョン: v13.7.0, v12.17.0, v10.20.0

N-API バージョン: 6

napi_get_all_property_names(napi_env env,
                            napi_value object,
                            napi_key_collection_mode key_mode,
                            napi_key_filter key_filter,
                            napi_key_conversion key_conversion,
                            napi_value* result);

• [in] env: Node-API コールが呼び出される環境。
• [in] object: プロパティを取得するオブジェクト。
• [in] key_mode: プロトタイププロパティも取得するかどうか。
• [in] key_filter: 取得するプロパティ（列挙可能/読み取り可能/書き込み可能）。
• [in] key_conversion: 番号付きプロパティキーを文字列に変換するかどうか。
• [out] result: オブジェクトのプロパティ名を表す JavaScript 値の配列を表す napi_value。napi_get_array_length と napi_get_element を使用して result を反復処理できます。

API が成功した場合は napi_ok を返します。

この API は、このオブジェクトで使用可能なプロパティの名前を含む配列を返します。

napi_set_property

追加: v8.0.0

N-API バージョン: 1

napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value);

• [in] env: Node-API コールが呼び出される環境。
• [in] object: プロパティを設定するオブジェクト。
• [in] key: 設定するプロパティの名前。
• [in] value: プロパティの値。

API が成功した場合は napi_ok を返します。

この API は、渡されたObjectにプロパティを設定します。

napi_get_property

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result);

• [in] env: Node-API コールが呼び出される環境。
• [in] object: プロパティを取得するオブジェクト。
• [in] key: 取得するプロパティの名前。
• [out] result: プロパティの値。

API が成功した場合は napi_ok を返します。

この API は、渡されたObjectから要求されたプロパティを取得します。

napi_has_property

追加: v8.0.0

N-API バージョン: 1

napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result);

• [in] env: Node-API コールが呼び出される環境。
• [in] object: クエリ対象のオブジェクト。
• [in] key: 存在を確認するプロパティの名前。
• [out] result: オブジェクトにプロパティが存在するかどうか。

API が成功した場合は napi_ok を返します。

この API は、渡されたObjectに指定された名前のプロパティが存在するかどうかをチェックします。

napi_delete_property

追加: v8.2.0

N-API バージョン: 1

napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result);

• [in] env: Node-API コールが呼び出される環境。
• [in] object: クエリ対象のオブジェクト。
• [in] key: 削除するプロパティの名前。
• [out] result: プロパティの削除が成功したかどうか。result は NULL を渡すことで省略可能です。

API が成功した場合は napi_ok を返します。

この API は、objectからkey自身のプロパティを削除しようとします。

napi_has_own_property

追加バージョン: v8.2.0

N-API バージョン: 1

napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result);

• [in] env: Node-API 呼び出しが実行される環境。
• [in] object: クエリ対象のオブジェクト。
• [in] key: 存在を確認する固有プロパティの名前。
• [out] result: オブジェクトに固有プロパティが存在するかどうか。

API が成功した場合はnapi_okを返します。

この API は、渡されたObjectに指定された名前の固有プロパティがあるかどうかを確認します。keyはstringまたはsymbolでなければなりません。そうでない場合はエラーがスローされます。Node-API はデータ型間の変換を実行しません。

napi_set_named_property

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value);

• [in] env: Node-API 呼び出しが実行される環境。
• [in] object: プロパティを設定するオブジェクト。
• [in] utf8Name: 設定するプロパティの名前。
• [in] value: プロパティの値。

API が成功した場合はnapi_okを返します。

このメソッドは、utf8Nameとして渡された文字列から作成されたnapi_valueを使用してnapi_set_propertyを呼び出すことと同等です。

napi_get_named_property

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result);

• [in] env: Node-API 呼び出しが実行される環境。
• [in] object: プロパティを取得するオブジェクト。
• [in] utf8Name: 取得するプロパティの名前。
• [out] result: プロパティの値。

API が成功した場合はnapi_okを返します。

このメソッドは、utf8Nameとして渡された文字列から作成されたnapi_valueを使用してnapi_get_propertyを呼び出すことと同等です。

napi_has_named_property

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: クエリ対象のオブジェクト。
• [in] utf8Name: 存在を確認するプロパティの名前。
• [out] result: オブジェクトにプロパティが存在するかどうか。

API が成功した場合はnapi_okを返します。

このメソッドは、utf8Nameとして渡された文字列から作成されたnapi_valueを使用してnapi_has_propertyを呼び出すことと同等です。

napi_set_element

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: プロパティを設定するオブジェクト。
• [in] index: 設定するプロパティのインデックス。
• [in] value: プロパティの値。

API が成功した場合はnapi_okを返します。

この API は、渡されたObjectに要素を設定します。

napi_get_element

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: プロパティを取得するオブジェクト。
• [in] index: 取得するプロパティのインデックス。
• [out] result: プロパティの値。

API が成功した場合はnapi_okを返します。

この API は、要求されたインデックスにある要素を取得します。

napi_has_element

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: クエリ対象のオブジェクト。
• [in] index: 存在を確認するプロパティのインデックス。
• [out] result: オブジェクトにプロパティが存在するかどうか。

API が成功した場合はnapi_okを返します。

この API は、渡されたObjectが要求されたインデックスに要素を持っているかどうかを返します。

napi_delete_element

追加: v8.2.0

N-API バージョン: 1

napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: クエリ対象のオブジェクト。
• [in] index: 削除するプロパティのインデックス。
• [out] result: 要素の削除が成功したかどうか。result は NULL を渡すことで省略可能です。

API が成功した場合はnapi_okを返します。

この API は、objectから指定されたindexを削除しようとします。

napi_define_properties

追加: v8.0.0

N-API バージョン: 1

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: プロパティを取得するオブジェクト。
• [in] property_count: properties配列の要素数。
• [in] properties: プロパティ記述子の配列。

API が成功した場合はnapi_okを返します。

このメソッドは、指定されたオブジェクトに複数のプロパティを効率的に定義できます。プロパティはプロパティ記述子を使用して定義されます（napi_property_descriptorを参照）。このようなプロパティ記述子の配列が与えられると、この API はDefineOwnProperty()（ECMA-262 仕様のセクション 9.1.6で説明）で定義されているように、オブジェクトのプロパティを 1 つずつ設定します。

napi_object_freeze

追加: v14.14.0, v12.20.0

N-API バージョン: 8

napi_status napi_object_freeze(napi_env env,
                               napi_value object);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: 凍結するオブジェクト。

API が成功した場合はnapi_okを返します。

このメソッドは、指定されたオブジェクトを凍結します。これにより、新しいプロパティの追加、既存プロパティの削除、既存プロパティの列挙可能性、構成可能性、または書き込み可能性の変更、および既存プロパティの値の変更を防ぎます。また、オブジェクトのプロトタイプの変更も防ぎます。これは、ECMA-262 仕様のセクション 19.1.2.6で説明されています。

napi_object_seal

追加日: v14.14.0, v12.20.0

N-API バージョン: 8

napi_status napi_object_seal(napi_env env,
                             napi_value object);

• [in] env: Node-API 呼び出しが行われる環境。
• [in] object: シールするオブジェクト。

API が成功した場合はnapi_okを返します。

このメソッドは、指定されたオブジェクトをシールします。これにより、新しいプロパティの追加を防ぎ、既存のプロパティをすべて非構成可能としてマークします。これは、ECMA-262 仕様の19.1.2.20 項で説明されています。

JavaScript 関数との連携

Node-API は、JavaScript コードがネイティブコードを呼び戻すことを可能にする API のセットを提供します。ネイティブコードへの呼び戻しをサポートする Node-API は、napi_callback型で表されるコールバック関数を受け取ります。JavaScript VM がネイティブコードを呼び戻すと、提供されたnapi_callback関数が呼び出されます。このセクションで説明する API では、コールバック関数が次の操作を実行できます。

• コールバックが呼び出されたコンテキストに関する情報の取得。
• コールバックに渡された引数の取得。
• コールバックからnapi_valueを返す。

さらに、Node-API は、ネイティブコードから JavaScript 関数を呼び出すことができる関数のセットを提供します。通常の JavaScript 関数呼び出しのように、またはコンストラクタ関数として関数を呼び出すことができます。

napi_property_descriptorアイテムのdataフィールドを介してこの API に渡されるNULL以外のデータは、objectに関連付けることができ、objectがnapi_add_finalizerにobjectとデータの両方を渡すことでガベージコレクションされるときに解放されます。

napi_call_function

追加日: v8.0.0

N-API バージョン: 1

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: API が呼び出される環境。
• [in] recv: 呼び出された関数に渡されるthis値。
• [in] func: 呼び出される JavaScript 関数を表すnapi_value。
• [in] argc: argv配列の要素数。
• [in] argv: 関数に引数として渡される JavaScript 値を表すnapi_valueの配列。
• [out] result: 返された JavaScript オブジェクトを表すnapi_value。

API が成功した場合はnapi_okを返します。

このメソッドでは、JavaScript 関数オブジェクトをネイティブアドオンから呼び出すことができます。これは、アドオンのネイティブコードから JavaScript への呼び戻しの主要なメカニズムです。非同期操作後の JavaScript への呼び出しの特別なケースについては、napi_make_callbackを参照してください。

サンプルのユースケースは次のようになります。次の JavaScript スニペットを考えてみましょう。

function AddTwo(num) {
  return num + 2
}
global.AddTwo = AddTwo

次に、上記の関数は、次のコードを使用してネイティブアドオンから呼び出すことができます。

// グローバルオブジェクト上の "AddTwo" という名前の関数を取得します
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;

// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;

// 結果をネイティブ型に変換します
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;

napi_create_function

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result);

• [in] env: API が呼び出される環境。
• [in] utf8Name: UTF8 でエンコードされた関数のオプション名。これは、JavaScript 内では新しい関数オブジェクトの name プロパティとして表示されます。
• [in] length: utf8name のバイト数、または null 終端の場合 NAPI_AUTO_LENGTH。
• [in] cb: この関数オブジェクトが呼び出されたときに呼び出されるネイティブ関数。napi_callback に詳細があります。
• [in] data: ユーザーが提供するデータコンテキスト。これは、後で呼び出されたときに関数に渡されます。
• [out] result: 新しく作成された関数の JavaScript 関数オブジェクトを表す napi_value。

API が成功した場合は napi_ok を返します。

この API を使用すると、アドオン作成者はネイティブコードで関数オブジェクトを作成できます。これは、JavaScript からアドオンのネイティブコードを呼び出すための主要なメカニズムです。

新しく作成された関数は、この呼び出し後、スクリプトから自動的に表示されません。代わりに、スクリプトから関数をアクセスできるようにするには、JavaScript に見えるオブジェクトにプロパティを明示的に設定する必要があります。

アドオンのモジュールエクスポートの一部として関数を公開するには、新しく作成された関数をエクスポートオブジェクトに設定します。サンプルモジュールは次のようになります。

napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\n");
  return NULL;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;

  napi_value fn;
  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "sayHello", fn);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

上記のコードを考えると、アドオンは次のように JavaScript から使用できます。

const myaddon = require('./addon')
myaddon.sayHello()

require() に渡される文字列は、.node ファイルを作成する binding.gyp のターゲットの名前です。

data パラメータを介してこの API に渡される NULL 以外のデータは、結果の JavaScript 関数（result パラメータで返される）に関連付けることができ、JavaScript 関数とデータの両方を napi_add_finalizer に渡すことで、関数がガベージコレクションされたときに解放できます。

JavaScript の Function については、ECMAScript 言語仕様の セクション 19.2 を参照してください。

napi_get_cb_info

追加日時: v8.0.0

N-API バージョン: 1

napi_status napi_get_cb_info(napi_env env,
                             napi_callback_info cbinfo,
                             size_t* argc,
                             napi_value* argv,
                             napi_value* thisArg,
                             void** data)

• [in] env: API が呼び出される環境。
• [in] cbinfo: コールバック関数に渡されるコールバック情報。
• [in-out] argc: 提供されたargv配列の長さを指定し、実際の引数の数を取得します。argcはNULLを渡して省略可能です。
• [out] argv: 引数がコピーされるnapi_valueの C 配列。提供された数よりも多くの引数がある場合、要求された数の引数のみがコピーされます。主張された数よりも少ない引数が提供された場合、残りのargvはundefinedを表すnapi_value値で埋められます。argvはNULLを渡して省略可能です。
• [out] thisArg: 呼び出しの JavaScript this引数を受け取ります。thisArgはNULLを渡して省略可能です。
• [out] data: コールバックのデータポインタを受け取ります。dataはNULLを渡して省略可能です。

API が成功した場合はnapi_okを返します。

このメソッドは、コールバック関数内で、指定されたコールバック情報から引数やthisポインタなどの呼び出しに関する詳細情報を取得するために使用されます。

napi_get_new_target

追加日時: v8.6.0

N-API バージョン: 1

napi_status napi_get_new_target(napi_env env,
                                napi_callback_info cbinfo,
                                napi_value* result)

• [in] env: API が呼び出される環境。
• [in] cbinfo: コールバック関数に渡されるコールバック情報。
• [out] result: コンストラクタ呼び出しのnew.target。

API が成功した場合はnapi_okを返します。

この API は、コンストラクタ呼び出しのnew.targetを返します。現在のコールバックがコンストラクタ呼び出しでない場合、結果はNULLです。

napi_new_instance

追加: v8.0.0

N-API バージョン: 1

napi_status napi_new_instance(napi_env env,
                              napi_value cons,
                              size_t argc,
                              napi_value* argv,
                              napi_value* result)

• [in] env: API が呼び出される環境。
• [in] cons: コンストラクタとして呼び出される JavaScript 関数を表すnapi_value。
• [in] argc: argv配列の要素数。
• [in] argv: コンストラクタへの引数を表すnapi_valueとしての JavaScript 値の配列。argcがゼロの場合、NULLを渡すことでこのパラメータを省略できます。
• [out] result: 作成されたオブジェクトを表すnapi_value。

このメソッドは、オブジェクトのコンストラクタを表すnapi_valueを使用して、新しい JavaScript 値をインスタンス化するために使用されます。例えば、次のスニペットを考えてみましょう。

function MyObject(param) {
  this.param = param
}

const arg = 'hello'
const value = new MyObject(arg)

Node-API では、次のスニペットを使用して近似できます。

// コンストラクタ関数MyObjectを取得
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;

// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value);

API が成功した場合はnapi_okを返します。

オブジェクトラッパー

Node-API は、C++クラスとインスタンスを「ラップ」して、クラスコンストラクタとメソッドを JavaScript から呼び出せるようにする方法を提供します。

ラップされたオブジェクトの場合、クラスプロトタイプで呼び出された関数とクラスのインスタンスで呼び出された関数を区別することが困難な場合があります。この問題に対処するために使用される一般的なパターンは、後のinstanceofチェックのためにクラスコンストラクタへの永続的な参照を保存することです。

napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
  // napi_unwrap() ...
} else {
  // otherwise...
}

参照は、不要になったら解放する必要があります。

napi_instanceof()が、JavaScript オブジェクトが特定のネイティブ型に対するラッパーであることを確認するのに不十分な場合があります。これは、ラップされた JavaScript オブジェクトが、プロトタイプメソッドのthis値ではなく、静的メソッドを介してアドオンに返される場合に特に当てはまります。このような場合、誤ってアンラップされる可能性があります。

const myAddon = require('./build/Release/my_addon.node')

// `openDatabase()`は、ネイティブデータベースハンドルをラップするJavaScriptオブジェクトを返します。
const dbHandle = myAddon.openDatabase()

// `query()`は、ネイティブクエリハンドルをラップするJavaScriptオブジェクトを返します。
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')

// 以下の行に意図しないエラーがあります。`myAddon.queryHasRecords()`の最初の引数はデータベースハンドル(`dbHandle`)であるべきで、クエリハンドル(`query`)ではありません。したがって、whileループの正しい条件は次のようになります。
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
  // レコードを取得
}

上記の例では、myAddon.queryHasRecords()は 2 つの引数を受け取るメソッドです。最初の引数はデータベースハンドル、2 番目の引数はクエリハンドルです。内部的には、最初の引数をアンラップし、結果のポインタをネイティブデータベースハンドルにキャストします。次に、2 番目の引数をアンラップし、結果のポインタをクエリハンドルにキャストします。引数が間違った順序で渡された場合でも、キャストは機能しますが、基礎となるデータベース操作が失敗したり、無効なメモリアクセスが発生する可能性が高くなります。

最初の引数から取得されたポインタが実際にデータベースハンドルのポインタであり、同様に、2 番目の引数から取得されたポインタが実際にクエリハンドルのポインタであることを確認するために、queryHasRecords()の実装は型検証を実行する必要があります。データベースハンドルがインスタンス化された JavaScript クラスコンストラクタと、クエリハンドルがインスタンス化されたコンストラクタをnapi_refに保持しておくと役立ちます。なぜなら、napi_instanceof()を使用して、queryHashRecords()に渡されたインスタンスが実際に正しい型であることを確認できるからです。

残念ながら、napi_instanceof()はプロトタイプ操作から保護しません。たとえば、データベースハンドルのインスタンスのプロトタイプは、クエリハンドルのインスタンスのコンストラクタのプロトタイプに設定できます。この場合、データベースハンドルのインスタンスはクエリハンドルのインスタンスとして表示され、クエリハンドルのインスタンスのnapi_instanceof()テストに合格しますが、データベースハンドルのポインタを含んだままになります。

そのため、Node-API は型タグ付け機能を提供します。

型タグは、アドオンに固有の 128 ビット整数です。Node-API は、型タグの格納にnapi_type_tag構造体を提供します。このような値が、napi_valueに格納されている JavaScript オブジェクトまたは外部と共にnapi_type_tag_object()に渡されると、JavaScript オブジェクトは型タグで「マーク」されます。この「マーク」は JavaScript 側からは見えません。JavaScript オブジェクトがネイティブバインディングに到着すると、元の型タグと共にnapi_check_object_type_tag()を使用して、JavaScript オブジェクトが以前に型タグで「マーク」されていたかどうかを判断できます。これにより、napi_instanceof()よりも高忠実度の型チェック機能が作成されます。これは、このような型タグ付けがプロトタイプ操作やアドオンのアンロード/リロードを生き残るためです。

上記の例を続けると、次のスケルトンアドオン実装は、napi_type_tag_object()とnapi_check_object_type_tag()の使用を示しています。

// この値は、データベースハンドルの型タグです。コマンド
//
//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// を使用して、構造体を初期化する2つの値を取得できます。
static const napi_type_tag DatabaseHandleTypeTag = {
  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};

// この値は、クエリハンドルの型タグです。
static const napi_type_tag QueryHandleTypeTag = {
  0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};

static napi_value
openDatabase(napi_env env, napi_callback_info info) {
  napi_status status;
  napi_value result;

  // データベースハンドルが生成される基礎となるアクションを実行します。
  DatabaseHandle* dbHandle = open_database();

  // 新しい空のJSオブジェクトを作成します。
  status = napi_create_object(env, &result);
  if (status != napi_ok) return NULL;

  // `DatabaseHandle`へのポインタを含むことを示すためにオブジェクトにタグを付けます。
  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
  if (status != napi_ok) return NULL;

  // `DatabaseHandle`構造体へのポインタをJSオブジェクト内に格納します。
  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
  if (status != napi_ok) return NULL;

  return result;
}

// 後で、データベースハンドルであると主張するJavaScriptオブジェクトを受け取ると、`napi_check_object_type_tag()`を使用して、それが実際にそのようなハンドルであることを確認できます。

static napi_value
query(napi_env env, napi_callback_info info) {
  napi_status status;
  size_t argc = 2;
  napi_value argv[2];
  bool is_db_handle;

  status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
  if (status != napi_ok) return NULL;

  // 渡された最初のオブジェクトが以前に適用されたタグを持っていることを確認します。
  status = napi_check_object_type_tag(env,
                                      argv[0],
                                      &DatabaseHandleTypeTag,
                                      &is_db_handle);
  if (status != napi_ok) return NULL;

  // そうでない場合は`TypeError`をスローします。
  if (!is_db_handle) {
    // TypeErrorをスローします。
    return NULL;
  }
}

napi_define_class

追加: v8.0.0

N-API バージョン: 1

napi_status napi_define_class(napi_env env,
                              const char* utf8name,
                              size_t length,
                              napi_callback constructor,
                              void* data,
                              size_t property_count,
                              const napi_property_descriptor* properties,
                              napi_value* result);

• [in] env: API が呼び出される環境。
• [in] utf8name: JavaScript コンストラクタ関数の名前。明確にするために、C++ クラスをラップする場合は C++ クラス名を使用することを推奨します。
• [in] length: utf8name のバイト数、または null 終端の場合は NAPI_AUTO_LENGTH。
• [in] constructor: クラスのインスタンスの構築を処理するコールバック関数。C++ クラスをラップする場合は、このメソッドは napi_callback シグネチャを持つ静的メンバでなければなりません。C++ クラスのコンストラクタは使用できません。napi_callback に詳細があります。
• [in] data: コールバック情報の data プロパティとしてコンストラクタコールバックに渡されるオプションデータ。
• [in] property_count: properties 配列引数のアイテム数。
• [in] properties: クラスの静的およびインスタンスデータプロパティ、アクセサ、メソッドを記述するプロパティ記述子の配列。napi_property_descriptor を参照してください。
• [out] result: クラスのコンストラクタ関数を表す napi_value。

API が成功した場合は napi_ok を返します。

以下のものを含む JavaScript クラスを定義します。

• クラス名を持つ JavaScript コンストラクタ関数。対応する C++ クラスをラップする際、constructor を介して渡されるコールバックを使用して新しい C++ クラスインスタンスをインスタンス化し、napi_wrap を使用して構築されている JavaScript オブジェクトインスタンス内に配置できます。
• 実装が C++ クラスの対応する 静的 データプロパティ、アクセサ、メソッドを呼び出すことができるコンストラクタ関数上のプロパティ（napi_static 属性を持つプロパティ記述子によって定義されます）。
• コンストラクタ関数の prototype オブジェクト上のプロパティ。C++ クラスをラップする際、napi_static 属性を持たないプロパティ記述子で指定された静的関数から、napi_unwrap を使用して JavaScript オブジェクトインスタンス内に配置された C++ クラスインスタンスを取得した後、C++ クラスの 非静的 データプロパティ、アクセサ、メソッドを呼び出すことができます。

C++ クラスをラップする際、constructor を介して渡される C++ コンストラクタコールバックは、クラス上の静的メソッドでなければなりません。これは、実際のクラスコンストラクタを呼び出し、新しい C++ インスタンスを JavaScript オブジェクトにラップし、ラッパーオブジェクトを返します。詳細は napi_wrap を参照してください。

napi_define_class から返される JavaScript コンストラクタ関数は、多くの場合、後でネイティブコードからクラスの新しいインスタンスを構築したり、提供された値がクラスのインスタンスかどうかを確認するために保存して使用されます。その場合、関数値がガベージコレクションされるのを防ぐために、napi_create_reference を使用して強い永続参照を作成し、参照カウントが 1 以上になるようにすることができます。

data パラメータまたは napi_property_descriptor 配列アイテムの data フィールドを介してこの API に渡される NULL 以外のデータは、結果の JavaScript コンストラクタ（result パラメータで返されます）に関連付けられ、クラスがガベージコレクションされるときに、JavaScript 関数とデータを napi_add_finalizer に渡すことで解放できます。

napi_wrap

追加バージョン: v8.0.0

N-API バージョン: 1

napi_status napi_wrap(napi_env env,
                      napi_value js_object,
                      void* native_object,
                      napi_finalize finalize_cb,
                      void* finalize_hint,
                      napi_ref* result);

• [in] env: API が呼び出される環境。
• [in] js_object: ネイティブオブジェクトのラッパーとなる JavaScript オブジェクト。
• [in] native_object: JavaScript オブジェクトにラップされるネイティブインスタンス。
• [in] finalize_cb: JavaScript オブジェクトがガベージコレクションされたときにネイティブインスタンスを解放するために使用できるオプションのネイティブコールバック。napi_finalize に詳細があります。
• [in] finalize_hint: ファイナライズコールバックに渡されるオプションのコンテキストヒント。
• [out] result: ラップされたオブジェクトへのオプションの参照。

API が成功した場合、napi_ok を返します。

ネイティブインスタンスを JavaScript オブジェクトにラップします。ネイティブインスタンスは後で napi_unwrap() を使用して取得できます。

JavaScript コードが napi_define_class() を使用して定義されたクラスのコンストラクタを呼び出すと、コンストラクタの napi_callback が呼び出されます。ネイティブクラスのインスタンスを構築した後、コールバックは napi_wrap() を呼び出して、新しく構築されたインスタンスを、コンストラクタコールバックの this 引数である既に作成されている JavaScript オブジェクトにラップする必要があります。（その this オブジェクトはコンストラクタ関数の prototype から作成されたため、既にすべてのインスタンスプロパティとメソッドの定義を持っています。）

通常、クラスインスタンスをラップする場合、ファイナライズコールバックを提供する必要があります。これは、ファイナライズコールバックの data 引数として受信したネイティブインスタンスを単に削除します。

オプションで返される参照は、最初は弱参照であり、参照カウントは 0 です。通常、この参照カウントは、インスタンスを有効な状態に維持する必要がある非同期操作中に一時的にインクリメントされます。

注意: オプションで返された参照（取得した場合）は、napi_delete_reference を使用して、ファイナライズコールバックの呼び出しに応答してのみ削除する必要があります。それより前に削除すると、ファイナライズコールバックが呼び出されない可能性があります。したがって、参照を取得する際には、参照の正しい破棄を可能にするためにファイナライズコールバックも必要です。

ファイナライザコールバックは延期される可能性があり、オブジェクトがガベージコレクションされ（弱参照が無効になる）、ファイナライザがまだ呼び出されていないウィンドウが残ります。napi_wrap() によって返された弱参照で napi_get_reference_value() を使用する場合、空の結果も処理する必要があります。

オブジェクトに対して 2 回目以降に napi_wrap() を呼び出すと、エラーが返されます。オブジェクトに別のネイティブインスタンスを関連付けるには、最初に napi_remove_wrap() を使用します。

napi_unwrap

追加されたバージョン: v8.0.0

N-API バージョン: 1

napi_status napi_unwrap(napi_env env,
                        napi_value js_object,
                        void** result);

• [in] env: API が呼び出される環境。
• [in] js_object: ネイティブインスタンスに関連付けられたオブジェクト。
• [out] result: ラップされたネイティブインスタンスへのポインタ。

API が成功した場合はnapi_okを返します。

napi_wrap()を使用して JavaScript オブジェクトに以前ラップされたネイティブインスタンスを取得します。

JavaScript コードがクラスのメソッドまたはプロパティアクセサを呼び出すと、対応するnapi_callbackが呼び出されます。コールバックがインスタンスメソッドまたはアクセサの場合、コールバックへのthis引数はラッパーオブジェクトです。呼び出しの対象となるラップされた C++インスタンスは、ラッパーオブジェクトでnapi_unwrap()を呼び出すことで取得できます。

napi_remove_wrap

追加されたバージョン: v8.5.0

N-API バージョン: 1

napi_status napi_remove_wrap(napi_env env,
                             napi_value js_object,
                             void** result);

• [in] env: API が呼び出される環境。
• [in] js_object: ネイティブインスタンスに関連付けられたオブジェクト。
• [out] result: ラップされたネイティブインスタンスへのポインタ。

API が成功した場合はnapi_okを返します。

napi_wrap()を使用して JavaScript オブジェクトjs_objectに以前ラップされたネイティブインスタンスを取得し、ラッピングを削除します。ファイナライズコールバックがラッピングに関連付けられていた場合、JavaScript オブジェクトがガベージコレクションされると、それ以上呼び出されなくなります。

napi_type_tag_object

追加されたバージョン: v14.8.0, v12.19.0

N-API バージョン: 8

napi_status napi_type_tag_object(napi_env env,
                                 napi_value js_object,
                                 const napi_type_tag* type_tag);

• [in] env: API が呼び出される環境。
• [in] js_object: マーキングされる JavaScript オブジェクトまたは外部。
• [in] type_tag: オブジェクトにマーキングされるタグ。

API が成功した場合はnapi_okを返します。

type_tagポインタの値を JavaScript オブジェクトまたは外部に関連付けます。その後、napi_check_object_type_tag()を使用して、オブジェクトに添付されたタグとアドオンが所有するタグを比較し、オブジェクトが正しい型であることを確認できます。

オブジェクトに既に関連付けられた型タグがある場合、この API はnapi_invalid_argを返します。

napi_check_object_type_tag

追加日: v14.8.0, v12.19.0

N-API version: 8

napi_status napi_check_object_type_tag(napi_env env,
                                       napi_value js_object,
                                       const napi_type_tag* type_tag,
                                       bool* result);

• [in] env: API が呼び出される環境。
• [in] js_object: 型タグを検査する JavaScript オブジェクトまたは外部オブジェクト。
• [in] type_tag: オブジェクト上で見つかったタグと比較するタグ。
• [out] result: 指定された型タグがオブジェクト上の型タグと一致したかどうか。オブジェクト上に型タグが見つからない場合もfalseが返される。

napi_okを返して API が成功したことを示す。

type_tagとして与えられたポインタと、js_object上に見つかった任意のポインタを比較する。js_object上にタグが見つからない場合、またはタグが見つかったがtype_tagと一致しない場合、resultはfalseに設定される。タグが見つかり、type_tagと一致する場合は、resultはtrueに設定される。

napi_add_finalizer

追加日: v8.0.0

N-API version: 5

napi_status napi_add_finalizer(napi_env env,
                               napi_value js_object,
                               void* finalize_data,
                               node_api_basic_finalize finalize_cb,
                               void* finalize_hint,
                               napi_ref* result);

• [in] env: API が呼び出される環境。
• [in] js_object: ネイティブデータがアタッチされる JavaScript オブジェクト。
• [in] finalize_data: finalize_cbに渡されるオプションデータ。
• [in] finalize_cb: JavaScript オブジェクトがガベージコレクションされたときにネイティブデータを解放するために使用されるネイティブコールバック。napi_finalizeで詳細を確認。
• [in] finalize_hint: ファイナライズコールバックに渡されるオプションのコンテキストヒント。
• [out] result: JavaScript オブジェクトへのオプションの参照。

napi_okを返して API が成功したことを示す。

js_object内の JavaScript オブジェクトがガベージコレクションされたときに呼び出されるnapi_finalizeコールバックを追加する。

この API は、単一の JavaScript オブジェクトに対して複数回呼び出すことができる。

注意: オプションで返される参照（取得した場合）は、napi_delete_referenceを使用して、ファイナライズコールバックの呼び出しに応答してのみ削除する必要がある。それより前に削除すると、ファイナライズコールバックが呼び出されなくなる可能性がある。したがって、参照を取得する際には、参照の正しい破棄を可能にするために、ファイナライズコールバックも必要となる。

node_api_post_finalizer

追加日時: v21.0.0, v20.10.0, v18.19.0

[安定版: 1 - 試験版]

安定版: 1 安定性: 1 - 試験版

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint);

• [in] env: API が呼び出される環境。
• [in] finalize_cb: JavaScript オブジェクトがガベージコレクションされた際にネイティブデータを解放するために使用されるネイティブコールバック。napi_finalizeで詳細を確認できます。
• [in] finalize_data: finalize_cbに渡されるオプションデータ。
• [in] finalize_hint: ファイナライズコールバックに渡されるオプションのコンテキストヒント。

API が成功した場合、napi_okを返します。

イベントループで非同期的に呼び出されるnapi_finalizeコールバックをスケジュールします。

通常、ファイナライザは GC（ガベージコレクタ）がオブジェクトを収集している間に呼び出されます。その時点で、GC の状態に変化をもたらす可能性のある Node-API を呼び出すと、Node.js がクラッシュします。

node_api_post_finalizerは、この制限を回避するために、アドオンがそのような Node-API への呼び出しを GC ファイナライズ以外の時点に延期することを可能にします。

簡単な非同期操作

アドオンモジュールは、実装の一部として libuv の非同期ヘルパーを活用する必要があることがよくあります。これにより、作業が完了する前にメソッドを返すことができるように、非同期的に実行される作業をスケジュールできます。これにより、Node.js アプリケーション全体の処理をブロックするのを避けることができます。

Node-API は、これらのサポート関数の ABI 安定インターフェースを提供し、最も一般的な非同期ユースケースをカバーしています。

Node-API は、非同期ワーカーの管理に使用されるnapi_async_work構造体を定義します。インスタンスはnapi_create_async_workとnapi_delete_async_workで作成/削除されます。

executeとcompleteコールバックは、実行の準備が整ったときと、タスクが完了したときにそれぞれ呼び出される関数です。

execute関数は、JavaScript の実行または JavaScript オブジェクトとのやり取りにつながる可能性のある Node-API 呼び出しを避ける必要があります。ほとんどの場合、Node-API 呼び出しを行う必要があるコードは、代わりにcompleteコールバックで行う必要があります。JavaScript を実行する可能性があるため、executeコールバックでnapi_envパラメータの使用は避けてください。

これらの関数は、以下のインターフェースを実装します。

typedef void (*napi_async_execute_callback)(napi_env env,
                                            void* data);
typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data);

これらのメソッドが呼び出されると、渡されたdataパラメータは、napi_create_async_work呼び出しに渡されたアドオン提供のvoid*データになります。

作成されると、非同期ワーカーはnapi_queue_async_work関数を使用して実行のためにキューイングできます。

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

作業の実行が開始される前に作業をキャンセルする必要がある場合は、napi_cancel_async_workを使用できます。

napi_cancel_async_workを呼び出した後、completeコールバックはnapi_cancelledのステータス値で呼び出されます。キャンセルされた場合でも、completeコールバックの呼び出し前には作業を削除しないでください。

napi_create_async_work

[履歴]

バージョン	変更
v8.6.0	async_resource および async_resource_name パラメータを追加
v8.0.0	追加: v8.0.0

N-API バージョン: 1

napi_status napi_create_async_work(napi_env env,
                                   napi_value async_resource,
                                   napi_value async_resource_name,
                                   napi_async_execute_callback execute,
                                   napi_async_complete_callback complete,
                                   void* data,
                                   napi_async_work* result);

• [in] env: API が呼び出される環境。
• [in] async_resource: 非同期作業に関連付けられたオプションのオブジェクト。これは、可能性のある async_hooks init フック に渡されます。
• [in] async_resource_name: async_hooks API によって公開される診断情報のために提供されるリソースの種類の識別子。
• [in] execute: 非同期でロジックを実行するために呼び出されるネイティブ関数。指定された関数はワーカープールスレッドから呼び出され、メインイベントループスレッドと並列に実行できます。
• [in] complete: 非同期ロジックが完了またはキャンセルされたときに呼び出されるネイティブ関数。指定された関数はメインイベントループスレッドから呼び出されます。napi_async_complete_callback は詳細を提供します。
• [in] data: ユーザーが提供するデータコンテキスト。これは、execute 関数と complete 関数に渡されます。
• [out] result: 新しく作成された非同期作業へのハンドルである napi_async_work*。

API が成功した場合は napi_ok を返します。

この API は、非同期でロジックを実行するために使用される作業オブジェクトを割り当てます。作業が不要になったら、napi_delete_async_work を使用して解放する必要があります。

async_resource_name は、ヌル終端の UTF-8 エンコード文字列である必要があります。

async_resource_name 識別子はユーザーによって提供され、実行される非同期作業の種類を表す必要があります。また、モジュール名を含めるなどして、識別子に名前空間を適用することをお勧めします。詳細については、async_hooks ドキュメント を参照してください。

napi_delete_async_work

追加: v8.0.0

N-API バージョン: 1

napi_status napi_delete_async_work(napi_env env,
                                   napi_async_work work);

• [in] env: API が呼び出される環境。
• [in] work: napi_create_async_workの呼び出しによって返されるハンドル。

API が成功した場合はnapi_okを返します。

この API は、以前に割り当てられた作業オブジェクトを解放します。

この API は、保留中の JavaScript 例外がある場合でも呼び出すことができます。

napi_queue_async_work

追加: v8.0.0

N-API バージョン: 1

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

• [in] env: API が呼び出される環境。
• [in] work: napi_create_async_workの呼び出しによって返されるハンドル。

API が成功した場合はnapi_okを返します。

この API は、以前に割り当てられた作業の実行をスケジュールすることを要求します。正常に返された後、同じnapi_async_workアイテムでこの API を再度呼び出すことはできません。そうすると結果は未定義になります。

napi_cancel_async_work

追加: v8.0.0

N-API バージョン: 1

napi_status napi_cancel_async_work(node_api_basic_env env,
                                   napi_async_work work);

• [in] env: API が呼び出される環境。
• [in] work: napi_create_async_workの呼び出しによって返されるハンドル。

API が成功した場合はnapi_okを返します。

この API は、キューに入れられた作業がまだ開始されていない場合にそれをキャンセルします。すでに実行が開始されている場合はキャンセルできず、napi_generic_failureが返されます。成功すると、completeコールバックはnapi_cancelledのステータス値で呼び出されます。completeコールバックの呼び出し前には、たとえ正常にキャンセルされたとしても、作業を削除しないでください。

この API は、保留中の JavaScript 例外がある場合でも呼び出すことができます。

カスタム非同期操作

上記の単純な非同期作業 API は、すべてのシナリオに適しているとは限りません。他の非同期メカニズムを使用する場合は、以下の API を使用して、非同期操作がランタイムによって適切に追跡されるようにする必要があります。

napi_async_init

追加: v8.6.0

N-API バージョン: 1

napi_status napi_async_init(napi_env env,
                            napi_value async_resource,
                            napi_value async_resource_name,
                            napi_async_context* result)

• [in] env: API が呼び出される環境。
• [in] async_resource: 非同期作業に関連付けられたオブジェクト。これは、可能性のあるasync_hooks initフックに渡され、async_hooks.executionAsyncResource()によってアクセスできます。
• [in] async_resource_name: async_hooks API によって公開される診断情報のために提供されるリソースの種類の識別子。
• [out] result: 初期化された非同期コンテキスト。

API が成功した場合はnapi_okを返します。

async_hooks関連の API が正しく動作するためには、async_resourceオブジェクトはnapi_async_destroyまで有効な状態を維持する必要があります。以前のバージョンとの ABI 互換性を維持するために、napi_async_contextはメモリリークを引き起こすのを避けるため、async_resourceオブジェクトへの強い参照を保持していません。しかし、napi_async_contextがnapi_async_destroyによって破棄される前に、async_resourceが JavaScript エンジンによってガベージコレクションされると、napi_open_callback_scopeやnapi_make_callbackなどのnapi_async_context関連の API を呼び出すと、AsyncLocalStorage API を使用している場合に非同期コンテキストの消失などの問題が発生する可能性があります。

以前のバージョンとの ABI 互換性を維持するために、async_resourceにNULLを渡してもエラーになりません。ただし、これは、async_resourceは非同期コールバック間のリンクを提供するために基盤となるasync_hooks実装で必要となるため、async_hooks initフックおよびasync_hooks.executionAsyncResource()で望ましくない動作につながるため、推奨されません。

napi_async_destroy

追加バージョン: v8.6.0

N-API バージョン: 1

napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context);

• [in] env: API が呼び出される環境。
• [in] async_context: 破棄する非同期コンテキスト。

API が成功した場合は napi_ok を返します。

この API は、保留中の JavaScript 例外がある場合でも呼び出すことができます。

napi_make_callback

[履歴]

バージョン	変更
v8.6.0	async_context パラメータを追加
v8.0.0	追加: v8.0.0

N-API バージョン: 1

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: API が呼び出される環境。
• [in] async_context: コールバックを呼び出している非同期操作のコンテキスト。これは通常、napi_async_initから以前に取得した値である必要があります。以前のバージョンとの ABI 互換性を維持するために、async_contextにNULLを渡してもエラーになりません。ただし、これにより非同期フックの動作が正しくなくなります。AsyncLocalStorage API を使用する場合、非同期コンテキストの損失など、潜在的な問題が発生します。
• [in] recv: 呼び出された関数に渡されるthis値。
• [in] func: 呼び出す JavaScript 関数を表すnapi_value。
• [in] argc: argv配列の要素数。
• [in] argv: 関数の引数を表すnapi_valueとしての JavaScript 値の配列。argcがゼロの場合、NULLを渡すことでこのパラメータを省略できます。
• [out] result: 返された JavaScript オブジェクトを表すnapi_value。

API が成功した場合は napi_ok を返します。

このメソッドを使用すると、ネイティブアドオンから JavaScript 関数オブジェクトを呼び出すことができます。この API はnapi_call_functionと似ていますが、非同期操作からの戻り後（スタック上に他のスクリプトがない場合）に、ネイティブコードから JavaScript に戻って呼び出すために使用されます。これはnode::MakeCallbackの非常に単純なラッパーです。

napi_async_complete_callback内からnapi_make_callbackを使用する必要はありません。その状況では、コールバックの非同期コンテキストは既に設定されているため、napi_call_functionを直接呼び出すだけで十分であり、適切です。napi_create_async_workを使用しないカスタム非同期動作を実装する場合、napi_make_callback関数の使用が必要になる場合があります。

コールバック中に JavaScript によってマイクロタスクキューにスケジュールされたprocess.nextTickまたは Promise は、C/C++に戻る前に実行されます。

napi_open_callback_scope

追加バージョン: v9.6.0

N-API バージョン: 3

NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
                                                 napi_value resource_object,
                                                 napi_async_context context,
                                                 napi_callback_scope* result)

• [in] env: API が呼び出される環境。
• [in] resource_object: 非同期作業に関連付けられたオブジェクトで、可能性のあるasync_hooks initフックに渡されます。このパラメータは非推奨となり、ランタイムでは無視されます。代わりにnapi_async_initのasync_resourceパラメータを使用してください。
• [in] context: コールバックを呼び出している非同期操作のコンテキスト。これは、napi_async_initから以前に取得した値である必要があります。
• [out] result: 新しく作成されたスコープ。

(例えば、Promise の解決など)特定の Node-API 呼び出しを行う際に、コールバックに関連付けられたスコープと同等のものが必要になる場合があります。スタック上に他のスクリプトがない場合、napi_open_callback_scopeとnapi_close_callback_scope関数を用いて必要なスコープを開いたり閉じたりできます。

napi_close_callback_scope

追加バージョン: v9.6.0

N-API バージョン: 3

NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
                                                  napi_callback_scope scope)

• [in] env: API が呼び出される環境。
• [in] scope: 閉じられるスコープ。

この API は、保留中の JavaScript 例外が存在する場合でも呼び出すことができます。

バージョン管理

napi_get_node_version

追加バージョン: v8.4.0

N-API バージョン: 1

typedef struct {
  uint32_t major;
  uint32_t minor;
  uint32_t patch;
  const char* release;
} napi_node_version;

napi_status napi_get_node_version(node_api_basic_env env,
                                  const napi_node_version** version);

• [in] env: API が呼び出される環境。
• [out] version: Node.js 自体のバージョン情報へのポインタ。

API が成功した場合はnapi_okを返します。

この関数は、現在実行されている Node.js のメジャー、マイナー、パッチバージョンをversion構造体に設定し、releaseフィールドをprocess.release.nameの値で設定します。

返されるバッファは静的に割り当てられており、解放する必要はありません。

napi_get_version

追加: v8.0.0

N-API バージョン: 1

napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);

• [in] env: API が呼び出される環境。
• [out] result: サポートされている Node-API の最高バージョン。

API が成功した場合は napi_ok を返します。

この API は、Node.js ランタイムによってサポートされている Node-API の最高バージョンを返します。Node-API は、Node.js の新しいリリースで追加の API 関数がサポートされるように、アドオンとして追加される予定です。Node.js のサポートするバージョンで新しい関数を使用できるようにし、サポートしない Node.js のバージョンで実行する場合はフォールバック動作を提供するために：

• napi_get_version() を呼び出して、API が使用可能かどうかを確認します。
• 使用可能な場合、uv_dlsym() を使用して関数のポインタを動的にロードします。
• 動的にロードされたポインタを使用して関数を呼び出します。
• 関数が使用できない場合は、その関数を使用しない代替実装を提供します。

メモリ管理

napi_adjust_external_memory

追加: v8.5.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
                                                    int64_t change_in_bytes,
                                                    int64_t* result);

• [in] env: API が呼び出される環境。
• [in] change_in_bytes: JavaScript オブジェクトによって存続させられる、外部で割り当てられたメモリの変更量。
• [out] result: 調整後の値

API が成功した場合は napi_ok を返します。

この関数は、JavaScript オブジェクトによって存続させられる（つまり、ネイティブアドオンによって割り当てられた独自のメモリを指す JavaScript オブジェクト）、外部で割り当てられたメモリの量を示します。外部で割り当てられたメモリを登録すると、通常よりも頻繁にグローバルガベージコレクションがトリガーされます。

Promise

Node-API は、ECMA 仕様の セクション 25.4 に記載されているように、Promise オブジェクトを作成するための機能を提供します。これは、Promise をオブジェクトのペアとして実装しています。napi_create_promise() で Promise が作成されると、「deferred」オブジェクトが作成され、Promise と共に返されます。deferred オブジェクトは作成された Promise にバインドされ、napi_resolve_deferred() または napi_reject_deferred() を使用して Promise を解決または拒否する唯一の方法です。napi_create_promise() によって作成された deferred オブジェクトは、napi_resolve_deferred() または napi_reject_deferred() によって解放されます。Promise オブジェクトは JavaScript に返され、通常どおり使用できます。

たとえば、Promise を作成して非同期ワーカーに渡すには、次のようになります。

napi_deferred deferred;
napi_value promise;
napi_status status;

// Promise を作成します。
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// 非同期アクションを実行する関数に deferred を渡します。
do_something_asynchronous(deferred);

// Promise を JS に返します
return promise;

上記の関数 do_something_asynchronous() は非同期アクションを実行し、その後 deferred を解決または拒否して、Promise を完了し、deferred を解放します。

napi_deferred deferred;
napi_value undefined;
napi_status status;

// deferred を完了するための値を作成します。
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// 非同期アクションが成功したかどうかに応じて、deferred に関連付けられた Promise を解決または拒否します。
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;

// この時点で deferred は解放されているため、NULL を割り当てる必要があります。
deferred = NULL;

napi_create_promise

追加: v8.5.0

N-API バージョン: 1

napi_status napi_create_promise(napi_env env,
                                napi_deferred* deferred,
                                napi_value* promise);

• [in] env: API が呼び出される環境。
• [out] deferred: 新しく作成された Deferred オブジェクト。後でnapi_resolve_deferred()またはnapi_reject_deferred()に渡して、関連付けられた Promise を解決または拒否するために使用できます。
• [out] promise: Deferred オブジェクトに関連付けられた JavaScript Promise。

API が成功した場合、napi_okを返します。

この API は、Deferred オブジェクトと JavaScript Promise を作成します。

napi_resolve_deferred

追加: v8.5.0

N-API バージョン: 1

napi_status napi_resolve_deferred(napi_env env,
                                  napi_deferred deferred,
                                  napi_value resolution);

• [in] env: API が呼び出される環境。
• [in] deferred: 解決する Promise に関連付けられた Deferred オブジェクト。
• [in] resolution: Promise を解決するための値。

この API は、関連付けられた Deferred オブジェクトを使用して JavaScript Promise を解決します。そのため、対応する Deferred オブジェクトが利用可能な JavaScript Promise に対してのみ使用できます。これは、Promise がnapi_create_promise()を使用して作成され、その呼び出しから返された Deferred オブジェクトが保持されている必要があることを意味します。

Deferred オブジェクトは、正常に完了すると解放されます。

napi_reject_deferred

追加: v8.5.0

N-API バージョン: 1

napi_status napi_reject_deferred(napi_env env,
                                 napi_deferred deferred,
                                 napi_value rejection);

• [in] env: API が呼び出される環境。
• [in] deferred: 拒否する Promise に関連付けられた Deferred オブジェクト。
• [in] rejection: Promise を拒否するための値。

この API は、関連付けられた Deferred オブジェクトを使用して JavaScript Promise を拒否します。そのため、対応する Deferred オブジェクトが利用可能な JavaScript Promise に対してのみ使用できます。これは、Promise がnapi_create_promise()を使用して作成され、その呼び出しから返された Deferred オブジェクトが保持されている必要があることを意味します。

Deferred オブジェクトは、正常に完了すると解放されます。

napi_is_promise

追加日時: v8.5.0

N-API バージョン: 1

napi_status napi_is_promise(napi_env env,
                            napi_value value,
                            bool* is_promise);

• [in] env: API が呼び出される環境。
• [in] value: 検査対象の値。
• [out] is_promise: promiseがネイティブプロミスオブジェクト（基盤となるエンジンによって作成されたプロミスオブジェクト）であるかどうかを示すフラグ。

スクリプト実行

Node-API は、基盤となる JavaScript エンジンを使用して JavaScript を含む文字列を実行するための API を提供します。

napi_run_script

追加日時: v8.5.0

N-API バージョン: 1

NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                        napi_value script,
                                        napi_value* result);

• [in] env: API が呼び出される環境。
• [in] script: 実行するスクリプトを含む JavaScript 文字列。
• [out] result: スクリプトの実行結果の値。

この関数は JavaScript コードの文字列を実行し、その結果を返しますが、以下の注意点があります。

• evalとは異なり、この関数はスクリプトが現在の字句スコープにアクセスすることを許可せず、そのためモジュールスコープへのアクセスも許可しません。つまり、requireなどの擬似グローバル変数は使用できません。
• スクリプトはグローバルスコープにアクセスできます。スクリプト内の関数とvar宣言はglobalオブジェクトに追加されます。letとconstを使用して作成された変数宣言はグローバルに表示されますが、globalオブジェクトには追加されません。
• thisの値はスクリプト内ではglobalです。

libuv イベントループ

Node-API は、特定のnapi_envに関連付けられた現在のイベントループを取得するための関数を提供します。

napi_get_uv_event_loop

追加日時: v9.3.0, v8.10.0

N-API バージョン: 2

NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
                                               struct uv_loop_s** loop);

• [in] env: API が呼び出される環境。
• [out] loop: 現在の libuv ループインスタンス。

注: libuv は比較的安定していますが、ABI の安定性を保証するものではありません。この関数の使用は避けるべきです。この関数を使用すると、Node.js のバージョン間で動作しないアドオンになる可能性があります。非同期スレッドセーフな関数呼び出しは、多くのユースケースにおいて代替手段となります。

非同期スレッドセーフな関数呼び出し

JavaScript 関数は、通常、ネイティブアドオンのメインスレッドからのみ呼び出すことができます。アドオンが追加のスレッドを作成する場合、napi_env、napi_value、またはnapi_refを必要とする Node-API 関数は、それらのスレッドから呼び出すことはできません。

アドオンに追加のスレッドがあり、それらのスレッドによって完了した処理に基づいて JavaScript 関数を呼び出す必要がある場合、それらのスレッドはアドオンのメインスレッドと通信して、メインスレッドがそれらの代わりに JavaScript 関数を呼び出すようにする必要があります。スレッドセーフな関数 API は、これを行う簡単な方法を提供します。

これらの API は、napi_threadsafe_function型と、この型のオブジェクトを作成、破棄、および呼び出すための API を提供します。napi_create_threadsafe_function()は、複数のスレッドから呼び出すことができる JavaScript 関数を保持するnapi_valueへの永続的な参照を作成します。呼び出しは非同期的に行われます。これは、JavaScript コールバックを呼び出す値がキューに入れられ、キュー内の各値に対して、最終的に JavaScript 関数が呼び出されることを意味します。

napi_threadsafe_functionの作成時に、napi_finalizeコールバックを提供できます。このコールバックは、スレッドセーフな関数が破棄される直前にメインスレッドで呼び出されます。構築時に提供されたコンテキストとファイナライズデータを受け取り、uv_thread_join()を呼び出すなどして、スレッドの後処理を行う機会を提供します。メインループスレッド以外では、ファイナライズコールバックが完了した後は、スレッドセーフな関数を使用しないでください。

napi_create_threadsafe_function()への呼び出し時に提供されたcontextは、napi_get_threadsafe_function_context()を呼び出すことで、任意のスレッドから取得できます。

スレッドセーフな関数の呼び出し

napi_call_threadsafe_function()を使用して、JavaScript への呼び出しを開始できます。napi_call_threadsafe_function()は、API がブロッキング動作をするかどうかを制御するパラメーターを受け入れます。napi_tsfn_nonblockingに設定されている場合、API は非ブロッキング動作を行い、キューがいっぱいの場合はnapi_queue_fullを返し、データがキューに正常に追加されるのを防ぎます。napi_tsfn_blockingに設定されている場合、API はキューに空きができるまでブロックします。スレッドセーフな関数が 0 の最大キューサイズで作成された場合、napi_call_threadsafe_function()は決してブロックしません。

JavaScript スレッドからnapi_tsfn_blockingを使用してnapi_call_threadsafe_function()を呼び出すべきではありません。キューがいっぱいの場合、JavaScript スレッドのデッドロックを引き起こす可能性があるためです。

JavaScript への実際の呼び出しは、call_js_cbパラメーターを介して提供されたコールバックによって制御されます。call_js_cbは、napi_call_threadsafe_function()の正常な呼び出しによってキューに入れられた各値に対して、メインスレッドで一度呼び出されます。このようなコールバックが提供されない場合、デフォルトのコールバックが使用され、結果として得られる JavaScript 呼び出しには引数がありません。call_js_cbコールバックは、呼び出す JavaScript 関数をnapi_valueとして、napi_threadsafe_functionの作成時に使用されたvoid*コンテキストポインター、およびセカンダリスレッドのいずれかによって作成された次のデータポインターとして、パラメーターで受け取ります。その後、コールバックはnapi_call_function()などの API を使用して JavaScript を呼び出すことができます。

コールバックは、envとcall_js_cbの両方がNULLに設定されて呼び出される場合もあります。これは、JavaScript への呼び出しが不可能になったことを示し、解放する必要がある可能性のあるアイテムがキューに残っていることを意味します。これは通常、スレッドセーフな関数がまだアクティブな状態で Node.js プロセスが終了した場合に発生します。

Node-API はコールバックに適したコンテキストでcall_js_cbを実行するため、napi_make_callback()を介して JavaScript を呼び出す必要はありません。

イベントループの各ティックで、0 個以上のキューに入れられたアイテムが呼び出される可能性があります。アプリケーションは、コールバックの呼び出しの進捗が行われ、時間が経過するにつれてイベントが呼び出される以外の特定の動作に依存するべきではありません。

スレッドセーフ関数の参照カウント

napi_threadsafe_functionオブジェクトは、その存続期間中にスレッドを追加および削除できます。そのため、作成時に初期のスレッド数を指定することに加えて、napi_acquire_threadsafe_functionを呼び出して、新しいスレッドがスレッドセーフ関数を使用し始めることを示すことができます。同様に、napi_release_threadsafe_functionを呼び出して、既存のスレッドがスレッドセーフ関数の使用を停止することを示すことができます。

napi_threadsafe_functionオブジェクトは、オブジェクトを使用するすべてのスレッドがnapi_release_threadsafe_function()を呼び出したか、napi_call_threadsafe_functionへの呼び出しに対してnapi_closingの戻り値を受け取ったときに破棄されます。napi_threadsafe_functionが破棄される前に、キューは空になります。napi_release_threadsafe_function()は、特定のnapi_threadsafe_functionと連携して行われる最後の API 呼び出しである必要があります。なぜなら、呼び出しが完了した後、napi_threadsafe_functionがまだ割り当てられているという保証がないためです。同じ理由で、napi_call_threadsafe_functionへの呼び出しに対してnapi_closingの戻り値を受け取った後、スレッドセーフ関数を使用しないでください。napi_threadsafe_functionに関連付けられたデータは、napi_create_threadsafe_function()に渡されたnapi_finalizeコールバックで解放できます。napi_create_threadsafe_functionのinitial_thread_countパラメータは、作成時にnapi_acquire_threadsafe_functionを複数回呼び出す代わりに、スレッドセーフ関数の初期取得数を示します。

napi_threadsafe_functionを使用するスレッド数がゼロになると、napi_acquire_threadsafe_function()を呼び出すことによって、それ以上スレッドが使用を開始することはできません。実際、napi_release_threadsafe_function()を除く、それに関連付けられた後続のすべての API 呼び出しは、napi_closingというエラー値を返します。

napi_release_threadsafe_function()にnapi_tsfn_abortの値を渡すことで、スレッドセーフ関数を「中断」できます。これにより、参照カウントがゼロになる前でも、napi_release_threadsafe_function()を除く、スレッドセーフ関数に関連付けられた後続のすべての API はnapi_closingを返すようになります。特に、napi_call_threadsafe_function()はnapi_closingを返し、スレッドセーフ関数への非同期呼び出しがもはや不可能であることをスレッドに知らせます。これは、スレッドを終了するための基準として使用できます。napi_call_threadsafe_function()からnapi_closingの戻り値を受け取ったら、スレッドはスレッドセーフ関数をそれ以上使用してはなりません。なぜなら、それがまだ割り当てられているという保証がなくなってしまうためです。

プロセスを実行状態に維持するかどうかの決定

libuv ハンドルと同様に、スレッドセーフ関数は「参照」および「参照解除」できます。「参照」されたスレッドセーフ関数は、それが作成されたスレッド上のイベントループが、スレッドセーフ関数が破棄されるまで存続するようにします。対照的に、「参照解除」されたスレッドセーフ関数は、イベントループの終了を妨げません。この目的のために、napi_ref_threadsafe_function と napi_unref_threadsafe_function の API が存在します。

napi_unref_threadsafe_function はスレッドセーフ関数を破棄可能とマークするものでもなく、napi_ref_threadsafe_function はその破棄を防ぐものでもありません。

napi_create_threadsafe_function

[履歴]

バージョン	変更
v12.6.0, v10.17.0	func パラメータをカスタム call_js_cb でオプション化
v10.6.0	追加: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
                                napi_value func,
                                napi_value async_resource,
                                napi_value async_resource_name,
                                size_t max_queue_size,
                                size_t initial_thread_count,
                                void* thread_finalize_data,
                                napi_finalize thread_finalize_cb,
                                void* context,
                                napi_threadsafe_function_call_js call_js_cb,
                                napi_threadsafe_function* result);

• [in] env: API が呼び出される環境。
• [in] func: 別のスレッドから呼び出すオプションの JavaScript 関数。call_js_cb に NULL が渡された場合に提供する必要があります。
• [in] async_resource: 可能性のある async_hooks init フック に渡される非同期作業に関連付けられたオプションのオブジェクト。
• [in] async_resource_name: async_hooks API によって公開される診断情報のために提供されるリソースの種類の識別子を指定する JavaScript 文字列。
• [in] max_queue_size: キューの最大サイズ。制限なしの場合は 0。
• [in] initial_thread_count: 初期の取得数、つまり、この関数を使用するメインスレッドを含む初期のスレッド数。
• [in] thread_finalize_data: thread_finalize_cb に渡されるオプションのデータ。
• [in] thread_finalize_cb: napi_threadsafe_function が破棄されるときに呼び出されるオプションの関数。
• [in] context: 生成された napi_threadsafe_function に添付するオプションのデータ。
• [in] call_js_cb: 別のスレッドでの呼び出しに応じて JavaScript 関数を呼び出すオプションのコールバック。このコールバックはメインスレッドで呼び出されます。指定されていない場合、JavaScript 関数はパラメータなしで、undefined を this 値として呼び出されます。napi_threadsafe_function_call_js に詳細があります。
• [out] result: 非同期の、スレッドセーフな JavaScript 関数。

変更履歴:

• 実験的 (NAPI_EXPERIMENTAL が定義されている): call_js_cb で発生したキャッチされない例外は、無視される代わりに 'uncaughtException' イベントで処理されます。

napi_get_threadsafe_function_context

追加日時: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
                                     void** result);

• [in] func: コンテキストを取得するスレッドセーフ関数。
• [out] result: コンテキストを格納する場所。

この API は、funcを使用する任意のスレッドから呼び出すことができます。

napi_call_threadsafe_function

[履歴]

バージョン	変更
v14.5.0	napi_would_deadlock のサポートが元に戻されました。
v14.1.0	メインスレッドまたはワーカースレッドから napi_tsfn_blocking を使用して呼び出され、キューがいっぱいの場合、napi_would_deadlock を返します。
v10.6.0	追加日時: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
                              void* data,
                              napi_threadsafe_function_call_mode is_blocking);

• [in] func: 呼び出す非同期スレッドセーフ JavaScript 関数。
• [in] data: スレッドセーフ JavaScript 関数の作成時に提供されたコールバックcall_js_cbを介して JavaScript に送信するデータ。
• [in] is_blocking: キューがいっぱいの場合に呼び出しをブロックする必要があることを示すnapi_tsfn_blocking、またはキューがいっぱいの場合にnapi_queue_fullのステータスで直ちに返すことを示すnapi_tsfn_nonblockingのいずれかの値をとることができるフラグ。

この API は、JavaScript スレッドからnapi_tsfn_blockingを使用して呼び出すことはできません。なぜなら、キューがいっぱいの場合、JavaScript スレッドのデッドロックを引き起こす可能性があるからです。

この API は、任意のスレッドからabortをnapi_tsfn_abortに設定してnapi_release_threadsafe_function()が呼び出された場合、napi_closingを返します。この値は、API がnapi_okを返す場合にのみキューに追加されます。

この API は、funcを使用する任意のスレッドから呼び出すことができます。

napi_acquire_threadsafe_function

追加日時: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);

• [in] func: 使用を開始する非同期スレッドセーフ JavaScript 関数。

スレッドは、他のスレッドセーフ関数 API にfuncを渡す前に、この API を呼び出して、funcを使用することを示す必要があります。これにより、他のすべてのスレッドが使用を停止したときにfuncが破棄されるのを防ぎます。

この API は、funcの使用を開始する任意のスレッドから呼び出すことができます。

napi_release_threadsafe_function

追加バージョン: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• [in] func: 参照カウントをデクリメントする非同期のスレッドセーフな JavaScript 関数。
• [in] mode: 現在のスレッドがスレッドセーフ関数へのさらなる呼び出しを行わないことを示すnapi_tsfn_release、または現在のスレッドに加えて、他のスレッドもスレッドセーフ関数へのさらなる呼び出しを行わないことを示すnapi_tsfn_abortのいずれかの値を取ることができるフラグ。napi_tsfn_abortに設定されている場合、napi_call_threadsafe_function()へのさらなる呼び出しはnapi_closingを返し、キューにはそれ以上の値は配置されません。

スレッドは、funcの使用を停止する際にこの API を呼び出す必要があります。この API を呼び出した後にfuncをスレッドセーフな API に渡すと、funcが破棄されている可能性があるため、結果は未定義になります。

この API は、funcの使用を停止するスレッドであれば、どのスレッドからも呼び出すことができます。

napi_ref_threadsafe_function

追加バージョン: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

• [in] env: API が呼び出される環境。
• [in] func: 参照するスレッドセーフ関数。

この API は、メインスレッドで実行されているイベントループがfuncが破棄されるまで終了しないことを示すために使用されます。uv_refと同様に、冪等性があります。

napi_unref_threadsafe_functionはスレッドセーフ関数を破棄可能としてマークするわけでもなく、napi_ref_threadsafe_functionはスレッドセーフ関数の破棄を防ぐわけでもありません。その目的にはnapi_acquire_threadsafe_functionとnapi_release_threadsafe_functionを使用できます。

この API は、メインスレッドからのみ呼び出すことができます。

napi_unref_threadsafe_function

追加バージョン: v10.6.0

N-API バージョン: 4

NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

• [in] env: API が呼び出される環境。
• [in] func: 参照解除するスレッドセーフ関数。

この API は、funcが破棄される前にメインスレッドで実行されているイベントループが終了しても良いことを示すために使用されます。uv_unrefと同様に、冪等性があります。

この API は、メインスレッドからのみ呼び出すことができます。

その他のユーティリティ

node_api_get_module_file_name

追加バージョン: v15.9.0, v14.18.0, v12.22.0

N-API バージョン: 9

NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);

• [in] env: API が呼び出される環境。
• [out] result: アドオンがロードされた場所の絶対パスを含む URL。ローカルファイルシステム上のファイルの場合、file:// で始まります。文字列はヌル終端され、env によって所有されているため、変更または解放してはなりません。

result は、アドオンのロード中にアドオンのファイル名を確立できない場合、空文字列になる可能性があります。