Node-API

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Node-API (ранее N-API) - это API для создания нативных Addons. Он не зависит от базовой среды выполнения JavaScript (например, V8) и поддерживается как часть самого Node.js. Этот API будет Application Binary Interface (ABI) стабильным для разных версий Node.js. Он предназначен для защиты аддонов от изменений в базовом движке JavaScript и позволяет модулям, скомпилированным для одной основной версии, запускаться на более поздних основных версиях Node.js без перекомпиляции. Руководство по ABI Stability содержит более подробное объяснение.

Addons строятся/пакуются с использованием того же подхода/инструментов, которые описаны в разделе C++ Addons. Единственное различие заключается в наборе API, используемых собственным кодом. Вместо использования V8 или Native Abstractions for Node.js API, используются функции, доступные в Node-API.

API, предоставляемые Node-API, обычно используются для создания и управления значениями JavaScript. Концепции и операции обычно соответствуют идеям, указанным в спецификации языка ECMA-262. API имеют следующие свойства:

• Все вызовы Node-API возвращают код состояния типа napi_status. Этот статус указывает, успешно ли выполнен вызов API или нет.
• Возвращаемое значение API передается через выходной параметр.
• Все значения JavaScript абстрагированы за непрозрачным типом с именем napi_value.
• В случае кода ошибки, дополнительную информацию можно получить с помощью napi_get_last_error_info. Более подробную информацию можно найти в разделе обработки ошибок Error handling.

Node-API - это C API, который обеспечивает стабильность ABI для разных версий Node.js и различных уровней компилятора. C++ API может быть проще в использовании. Для поддержки использования C++ проект поддерживает модуль-обертку C++ под названием node-addon-api. Эта обертка предоставляет встраиваемый C++ API. Двоичные файлы, построенные с помощью node-addon-api, будут зависеть от символов для функций на основе Node-API C, экспортируемых Node.js. node-addon-api - это более эффективный способ написания кода, который вызывает Node-API. Возьмем, к примеру, следующий код node-addon-api. В первом разделе показан код node-addon-api, а во втором - то, что на самом деле используется в аддоне.

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. В результате он по-прежнему получает преимущества стабильности ABI, обеспечиваемой C API.

При использовании node-addon-api вместо C API, начните с API docs для node-addon-api.

Node-API Resource предлагает отличную ориентацию и советы для разработчиков, только начинающих работать с Node-API и node-addon-api. Дополнительные медиа-ресурсы можно найти на странице Node-API Media.

Последствия стабильности ABI

Хотя Node-API предоставляет гарантию стабильности ABI, другие части Node.js этого не делают, и любые внешние библиотеки, используемые из дополнения, могут этого не делать. В частности, ни один из следующих API не предоставляет гарантию стабильности ABI между основными версиями:

• C++ API Node.js, доступные через любой из
• API libuv, которые также включены в Node.js и доступны через
• API V8, доступный через

Таким образом, чтобы дополнение оставалось ABI-совместимым между основными версиями Node.js, оно должно использовать исключительно Node-API, ограничиваясь использованием

#include <node_api.h>

и проверяя для всех используемых внешних библиотек, что внешняя библиотека дает гарантии стабильности ABI, аналогичные Node-API.

Сборка

В отличие от модулей, написанных на JavaScript, разработка и развертывание собственных дополнений Node.js с использованием Node-API требует дополнительного набора инструментов. Помимо базовых инструментов, необходимых для разработки для Node.js, разработчику собственных дополнений требуется цепочка инструментов, которая может компилировать код C и C++ в двоичный файл. Кроме того, в зависимости от того, как развертывается собственное дополнение, пользователю собственного дополнения также необходимо будет установить цепочку инструментов C/C++.

Для разработчиков Linux необходимые пакеты цепочки инструментов C/C++ легко доступны. GCC широко используется в сообществе Node.js для сборки и тестирования на различных платформах. Для многих разработчиков инфраструктура компилятора LLVM также является хорошим выбором.

Для разработчиков Mac Xcode предлагает все необходимые инструменты компилятора. Однако нет необходимости устанавливать всю IDE Xcode. Следующая команда устанавливает необходимую цепочку инструментов:

xcode-select --install

Для разработчиков Windows Visual Studio предлагает все необходимые инструменты компилятора. Однако нет необходимости устанавливать всю IDE Visual Studio. Следующая команда устанавливает необходимую цепочку инструментов:

npm install --global windows-build-tools

В разделах ниже описаны дополнительные инструменты, доступные для разработки и развертывания собственных дополнений Node.js.

Инструменты сборки

Оба перечисленных здесь инструмента требуют, чтобы у пользователей нативного дополнения была установлена цепочка инструментов C/C++, чтобы успешно установить нативное дополнение.

node-gyp

node-gyp — это система сборки, основанная на форке gyp-next инструмента GYP от Google, и она поставляется в комплекте с npm. GYP, а следовательно и node-gyp, требует установки Python.

Исторически сложилось так, что node-gyp был инструментом выбора для сборки нативных дополнений. Он широко распространен и имеет обширную документацию. Однако некоторые разработчики столкнулись с ограничениями в node-gyp.

CMake.js

CMake.js — это альтернативная система сборки, основанная на CMake.

CMake.js — хороший выбор для проектов, которые уже используют CMake, или для разработчиков, столкнувшихся с ограничениями в node-gyp. build_with_cmake — это пример проекта нативного дополнения на основе CMake.

Загрузка предварительно скомпилированных бинарных файлов

Три перечисленных здесь инструмента позволяют разработчикам и сопровождающим нативных дополнений создавать и загружать бинарные файлы на общедоступные или частные серверы. Эти инструменты обычно интегрируются с системами сборки CI/CD, такими как Travis CI и AppVeyor, для сборки и загрузки бинарных файлов для различных платформ и архитектур. Эти бинарные файлы затем доступны для загрузки пользователями, которым не требуется устанавливать цепочку инструментов 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 releases. prebuild — хороший выбор для проектов GitHub, использующих CMake.js.

prebuildify

prebuildify - это инструмент, основанный на node-gyp. Преимущество prebuildify заключается в том, что собранные бинарные файлы объединяются с нативным аддоном при его загрузке в npm. Бинарные файлы загружаются из npm и сразу же доступны пользователю модуля при установке нативного аддона.

Использование

Чтобы использовать функции Node-API, включите файл node_api.h, который находится в каталоге src в дереве разработки node:

#include <node_api.h>

Это приведет к выбору NAPI_VERSION по умолчанию для данного выпуска Node.js. Чтобы обеспечить совместимость с определенными версиями 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.

Матрица версий Node-API

До версии 9 версии Node-API были аддитивными и версионировались независимо от Node.js. Это означало, что каждая версия была расширением предыдущей версии в том смысле, что она имела все API из предыдущей версии с некоторыми дополнениями. Каждая версия Node.js поддерживала только одну версию Node-API. Например, v18.15.0 поддерживает только версию 8 Node-API. Стабильность ABI была достигнута потому, что 8 была строгим супермножеством всех предыдущих версий.

Начиная с версии 9, хотя версии Node-API продолжают версионироваться независимо, аддону, работающему с версией 9 Node-API, может потребоваться обновление кода для работы с версией 10 Node-API. Однако стабильность ABI поддерживается, потому что версии Node.js, которые поддерживают версии Node-API выше 8, будут поддерживать все версии между 8 и самой высокой версией, которую они поддерживают, и по умолчанию будут предоставлять API версии 8, если только аддон не выберет более высокую версию Node-API. Этот подход обеспечивает гибкость для лучшей оптимизации существующих функций Node-API при сохранении стабильности ABI. Существующие аддоны могут продолжать работать без перекомпиляции, используя более раннюю версию Node-API. Если аддону требуется функциональность из более новой версии Node-API, для использования этих новых функций все равно потребуются изменения в существующем коде и перекомпиляция.

В версиях Node.js, которые поддерживают версию 9 Node-API и более поздние, определение 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 как экспериментальную. Он был выпущен как версия 1 Node-API, но продолжал развиваться до Node.js 8.6.0. API отличается в версиях до Node.js 8.6.0. Мы рекомендуем версию 3 Node-API или более позднюю.

Каждый API, документированный для Node-API, будет иметь заголовок с именем added in:, а стабильные API будут иметь дополнительный заголовок Node-API version:. API непосредственно доступны при использовании версии Node.js, которая поддерживает версию Node-API, показанную в Node-API version:, или выше. При использовании версии Node.js, которая не поддерживает указанную Node-API version: или если нет указанной Node-API version:, то API будет доступен только в том случае, если #define NAPI_EXPERIMENTAL предшествует включению node_api.h или js_native_api.h. Если API, похоже, недоступен в версии Node.js, которая позже, чем указанная в added in:, то это, скорее всего, причина кажущегося отсутствия.

Node-API, строго связанные с доступом к функциям ECMAScript из машинного кода, можно найти отдельно в js_native_api.h и js_native_api_types.h. API, определенные в этих заголовках, включены в node_api.h и node_api_types.h. Заголовки структурированы таким образом, чтобы разрешить реализации Node-API вне Node.js. Для этих реализаций API, специфичные для Node.js, могут быть неприменимы.

Части аддона, специфичные для Node.js, могут быть отделены от кода, который предоставляет фактическую функциональность среде JavaScript, чтобы последний можно было использовать с несколькими реализациями Node-API. В приведенном ниже примере addon.c и addon.h ссылаются только на js_native_api.h. Это гарантирует, что addon.c можно будет повторно использовать для компиляции как с реализацией Node-API в Node.js, так и с любой реализацией Node-API за пределами Node.js.

addon_node.c - это отдельный файл, который содержит специфичную для Node.js точку входа в аддон и который создает аддон, вызывая addon.c, когда аддон загружается в среду Node.js.

// 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 определяет понятие "Агент" как самодостаточное окружение, в котором выполняется код JavaScript. Процесс может запускать и завершать несколько таких агентов либо одновременно, либо последовательно.

Окружение Node.js соответствует агенту ECMAScript. В основном процессе окружение создается при запуске, и дополнительные окружения могут быть созданы в отдельных потоках для использования в качестве рабочих потоков. Когда 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: Необязательная подсказка для передачи в обратный вызов finalize во время сборки.

Возвращает napi_ok, если API успешно выполнено.

Этот API связывает data с текущим запущенным окружением Node.js. data может быть получена позже с помощью napi_get_instance_data(). Любые существующие данные, связанные с текущим запущенным окружением Node.js, которые были установлены посредством предыдущего вызова napi_set_instance_data(), будут перезаписаны. Если 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: Элемент данных, который ранее был связан с текущей запущенной средой Node.js посредством вызова napi_set_instance_data().

Возвращает napi_ok, если API выполнен успешно.

Этот API извлекает данные, которые ранее были связаны с текущей запущенной средой Node.js через napi_set_instance_data(). Если данные не установлены, вызов будет успешным, и 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: строка в кодировке UTF8, содержащая VM-нейтральное описание ошибки.
• engine_reserved: Зарезервировано для специфичных для VM деталей ошибки. В настоящее время не реализовано ни для одной VM.
• engine_error_code: Специфичный для VM код ошибки. В настоящее время не реализовано ни для одной VM.
• error_code: Код состояния Node-API, возникший при последней ошибке.

См. раздел Обработка ошибок для получения дополнительной информации.

napi_env

napi_env используется для представления контекста, который основная реализация Node-API может использовать для сохранения состояния, специфичного для виртуальной машины. Эта структура передается в нативные функции при их вызове и должна быть возвращена при выполнении вызовов Node-API. В частности, один и тот же napi_env, который был передан при вызове исходной нативной функции, должен быть передан во все последующие вложенные вызовы Node-API. Кэширование napi_env для целей общего повторного использования и передача napi_env между экземплярами одного и того же аддона, работающего в разных потоках Worker, не допускается. 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-APIs, которые принимают параметр типа node_api_basic_env в качестве своего первого аргумента. Эти APIs не обращаются к состоянию движка JavaScript и, следовательно, безопасны для вызова из синхронных финализаторов. Передача параметра типа napi_env в эти APIs допускается, однако передача параметра типа node_api_basic_env в APIs, которые обращаются к состоянию движка JavaScript, не допускается. Попытка сделать это без приведения типов приведет к предупреждению компилятора или ошибке, когда аддоны компилируются с флагами, которые заставляют их выдавать предупреждения и/или ошибки, когда в функцию передаются неправильные типы указателей. Вызов таких APIs из синхронного финализатора в конечном итоге приведет к завершению работы приложения.

napi_value

Это непрозрачный указатель, который используется для представления значения JavaScript.

napi_threadsafe_function

Added in: v10.6.0

N-API version: 4

Это непрозрачный указатель, представляющий функцию JavaScript, которую можно асинхронно вызывать из нескольких потоков через napi_call_threadsafe_function().

napi_threadsafe_function_release_mode

Added in: v10.6.0

N-API version: 4

Значение, которое передается в napi_release_threadsafe_function(), чтобы указать, следует ли немедленно закрыть потокобезопасную функцию (napi_tsfn_abort) или просто освободить (napi_tsfn_release) и, таким образом, сделать ее доступной для последующего использования через 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

Added in: v10.6.0

N-API version: 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

Экранируемые области видимости обработчиков – это особый тип области видимости обработчиков для возврата значений, созданных в пределах определенной области видимости обработчиков, в родительскую область.

napi_ref

Добавлено в версии: v8.0.0

Версия N-API: 1

Это абстракция, используемая для ссылки на napi_value. Это позволяет пользователям управлять временем жизни значений JavaScript, включая явное определение их минимального времени жизни.

Для получения более подробной информации ознакомьтесь с разделом Управление временем жизни объектов.

napi_type_tag

Добавлено в версии: v14.8.0, v12.19.0

Версия N-API: 8

128-битное значение, хранящееся в виде двух 64-битных целых чисел без знака. Оно служит UUID, с помощью которого объекты JavaScript или внешние объекты могут быть "помечены", чтобы убедиться, что они определенного типа. Это более строгая проверка, чем 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

Тип указателя функции для предоставляемых пользователем собственных функций, которые должны быть доступны для JavaScript через Node-API. Функции обратного вызова должны соответствовать следующей сигнатуре:

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, которые принимают node_api_basic_env в качестве своего первого параметра. node_api_post_finalizer можно использовать для планирования вызовов Node-API, которым требуется доступ к состоянию движка JavaScript, для запуска после завершения текущего цикла сборки мусора.

В случае node_api_create_external_string_latin1 и node_api_create_external_string_utf16 параметр env может быть null, поскольку внешние строки могут быть собраны на последней стадии завершения работы среды.

История изменений:

• экспериментальная (NAPI_EXPERIMENTAL): Можно вызывать только Node-API, которые принимают node_api_basic_env в качестве своего первого параметра, в противном случае приложение будет завершено с соответствующим сообщением об ошибке. Эту функцию можно отключить, определив 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);

История изменений:

• experimental (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);

Реализации этой функции должны избегать вызовов Node-API, которые выполняют JavaScript или взаимодействуют с объектами JavaScript. Вызовы 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

Указатель на функцию, используемый с асинхронными потокобезопасными вызовами функций. Обратный вызов будет вызываться в основном потоке. Его цель - использовать элемент данных, поступающий через очередь из одного из вторичных потоков, для создания параметров, необходимых для вызова в JavaScript, обычно через napi_call_function, а затем выполнить вызов в JavaScript.

Данные, поступающие из вторичного потока через очередь, передаются в параметре data, а функция JavaScript для вызова - в параметре js_callback.

Node-API настраивает окружение перед вызовом этого обратного вызова, поэтому достаточно вызвать функцию JavaScript через napi_call_function, а не через napi_make_callback.

Функции обратного вызова должны соответствовать следующей сигнатуре:

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

• [in] env: Окружение для использования для вызовов API, или NULL, если потокобезопасная функция разрушается и data может потребоваться освободить.
• [in] js_callback: Функция JavaScript для вызова, или NULL, если потокобезопасная функция разрушается и data может потребоваться освободить. Она также может быть NULL, если потокобезопасная функция была создана без js_callback.
• [in] context: Необязательные данные, с которыми была создана потокобезопасная функция.
• [in] data: Данные, созданные вторичным потоком. Ответственность обратного вызова заключается в преобразовании этих нативных данных в значения JavaScript (с помощью функций Node-API), которые можно передать в качестве параметров при вызове js_callback. Этот указатель полностью управляется потоками и этим обратным вызовом. Таким образом, этот обратный вызов должен освободить данные.

Если нет причин, рассмотренных в разделе Управление временем жизни объектов, создание дескриптора и/или области действия обратного вызова внутри тела функции не требуется.

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.

Возвращаемое значение будет napi_ok, если запрос был успешно выполнен и не было выброшено необработанное исключение JavaScript. Если произошла ошибка И было выброшено исключение, будет возвращено значение 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_get_last_error_info, которая возвращает структуру napi_extended_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 с более подробной информацией об ошибке.

Возвращает napi_ok, если API успешно выполнен.

Этот API извлекает структуру napi_extended_error_info с информацией о последней произошедшей ошибке.

Содержимое возвращаемого napi_extended_error_info действительно только до тех пор, пока функция Node-API не будет вызвана в той же среде env. Это включает в себя вызов napi_is_exception_pending, поэтому часто может потребоваться сделать копию информации, чтобы ее можно было использовать позже. Указатель, возвращаемый в error_message, указывает на статически определенную строку, поэтому безопасно использовать этот указатель, если вы скопировали его из поля error_message (которое будет перезаписано) до вызова другой функции Node-API.

Не полагайтесь на содержимое или формат какой-либо расширенной информации, поскольку она не подлежит SemVer и может измениться в любое время. Она предназначена только для целей ведения журнала.

Этот API можно вызывать, даже если есть ожидающее исключение JavaScript.

Исключения

Любой вызов функции Node-API может привести к ожидающему исключению JavaScript. Это относится ко всем функциям API, даже к тем, которые могут не вызывать выполнение JavaScript.

Если napi_status, возвращенный функцией, равен napi_ok, то исключение не ожидается и никаких дополнительных действий не требуется. Если возвращенный napi_status отличается от napi_ok или napi_pending_exception, чтобы попытаться восстановиться и продолжить, а не просто немедленно вернуться, необходимо вызвать napi_is_exception_pending, чтобы определить, ожидается ли исключение или нет.

Во многих случаях, когда вызывается функция Node-API и исключение уже ожидается, функция немедленно вернется со статусом napi_pending_exception. Однако это не относится ко всем функциям. Node-API позволяет вызывать подмножество функций, чтобы обеспечить минимальную очистку перед возвратом в JavaScript. В этом случае napi_status будет отражать статус функции. Он не будет отражать предыдущие ожидающие исключения. Чтобы избежать путаницы, проверяйте статус ошибки после каждого вызова функции.

Когда исключение ожидает обработки, можно использовать один из двух подходов.

Первый подход состоит в том, чтобы выполнить любую соответствующую очистку, а затем вернуться, чтобы выполнение вернулось в JavaScript. В рамках перехода обратно в JavaScript исключение будет сгенерировано в той точке кода JavaScript, где был вызван собственный метод. Поведение большинства вызовов Node-API не определено, пока исключение ожидает обработки, и многие просто вернут napi_pending_exception, поэтому сделайте как можно меньше и вернитесь в JavaScript, где исключение можно обработать.

Второй подход состоит в том, чтобы попытаться обработать исключение. Бывают случаи, когда собственный код может перехватить исключение, предпринять соответствующие действия, а затем продолжить. Это рекомендуется только в тех конкретных случаях, когда известно, что исключение можно безопасно обработать. В этих случаях napi_get_and_clear_last_exception можно использовать для получения и очистки исключения. В случае успеха результат будет содержать дескриптор последнего сгенерированного 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 - это napi_value, который ссылается на вновь созданный объект JavaScript Error.

Проект Node.js добавляет коды ошибок ко всем ошибкам, создаваемым внутри. Цель состоит в том, чтобы приложения использовали эти коды ошибок для всей проверки ошибок. Связанные сообщения об ошибках останутся, но будут предназначены только для ведения журнала и отображения с ожиданием, что сообщение может измениться без применения SemVer. Чтобы поддержать эту модель с помощью Node-API, как во внутренней функциональности, так и для функциональности, специфичной для модуля (поскольку это хорошая практика), функции throw_ и create_ принимают необязательный параметр code, который является строкой для кода, который будет добавлен к объекту ошибки. Если необязательный параметр равен 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, которое будет выброшено.

Возвращает napi_ok, если API выполнился успешно.

Этот 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-строка, представляющая текст, связанный с ошибкой.

Возвращает napi_ok, если API выполнился успешно.

Этот 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-строка, представляющая текст, связанный с ошибкой.

Возвращает napi_ok, если API выполнился успешно.

Этот 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-строка, представляющая текст, связанный с ошибкой.

Возвращает napi_ok, если API выполнился успешно.

Этот API выбрасывает JavaScript RangeError с предоставленным текстом.

node_api_throw_syntax_error

Added in: v17.2.0, v16.14.0

N-API version: 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, представляющая текст, который будет связан с ошибкой.

Возвращает napi_ok, если API выполнен успешно.

Этот API выбрасывает JavaScript SyntaxError с предоставленным текстом.

napi_is_error

Added in: v8.0.0

N-API version: 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: Логическое значение, которое устанавливается в true, если napi_value представляет ошибку, в противном случае - false.

Возвращает napi_ok, если API выполнен успешно.

Этот API запрашивает napi_value, чтобы проверить, представляет ли он объект ошибки.

napi_create_error

Added in: v8.0.0

N-API version: 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: napi_value, который ссылается на JavaScript string, который будет использоваться в качестве сообщения для Error.
• [out] result: napi_value, представляющий созданную ошибку.

Возвращает napi_ok, если API выполнен успешно.

Этот API возвращает JavaScript Error с предоставленным текстом.

napi_create_type_error

Added in: v8.0.0

N-API version: 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: napi_value, который ссылается на JavaScript string, который будет использоваться в качестве сообщения для Error.
• [out] result: napi_value, представляющий созданную ошибку.

Возвращает napi_ok, если API выполнен успешно.

Этот 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: napi_value, ссылающееся на JavaScript string, который будет использоваться в качестве сообщения для Error.
• [out] result: napi_value, представляющее созданную ошибку.

Возвращает napi_ok, если API успешно завершил работу.

Этот 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: napi_value, ссылающееся на JavaScript string, который будет использоваться в качестве сообщения для Error.
• [out] result: napi_value, представляющее созданную ошибку.

Возвращает napi_ok, если API успешно завершил работу.

Этот 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.

Возвращает napi_ok, если API успешно завершил работу.

Этот API можно вызывать, даже если есть ожидающее обработки исключение JavaScript.

napi_is_exception_pending

Added in: v8.0.0

N-API version: 1

napi_status napi_is_exception_pending(napi_env env, bool* result);

• [in] env: Среда, в которой вызывается API.
• [out] result: Логическое значение, устанавливаемое в true, если ожидается исключение.

Возвращает napi_ok, если API успешно выполнен.

Этот API можно вызывать, даже если есть ожидающее исключение JavaScript.

napi_fatal_exception

Added in: v9.10.0

N-API version: 3

napi_status napi_fatal_exception(napi_env env, napi_value err);

• [in] env: Среда, в которой вызывается API.
• [in] err: Ошибка, которая передается в 'uncaughtException'.

Вызывает 'uncaughtException' в JavaScript. Полезно, если асинхронный обратный вызов выдает исключение, которое невозможно восстановить.

Критические ошибки

В случае неисправимой ошибки в нативном аддоне можно вызвать фатальную ошибку для немедленного завершения процесса.

napi_fatal_error

Added in: v8.2.0

N-API version: 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 дескрипторы объектов в куче для базовой виртуальной машины могут возвращаться как 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;
  }
  // do something with element
}

Это приведет к созданию большого количества дескрипторов, потребляющих значительные ресурсы. Кроме того, даже если собственный код может использовать только самый последний дескриптор, все связанные с ним объекты также будут оставаться активными, поскольку все они разделяют одну и ту же область видимости.

Для обработки этого случая Node-API предоставляет возможность установить новую 'область видимости', с которой будут связаны вновь созданные дескрипторы. Как только эти дескрипторы больше не требуются, область видимости может быть 'закрыта', и все дескрипторы, связанные с областью видимости, становятся недействительными. Методы, доступные для открытия/закрытия областей видимости: napi_open_handle_scope и napi_close_handle_scope.

Node-API поддерживает только одну вложенную иерархию областей видимости. В любой момент времени существует только одна активная область видимости, и все новые дескрипторы будут связаны с этой областью видимости, пока она активна. Области видимости должны быть закрыты в обратном порядке их открытия. Кроме того, все области видимости, созданные внутри собственного метода, должны быть закрыты до возврата из этого метода.

Взяв предыдущий пример, добавление вызовов napi_open_handle_scope и napi_close_handle_scope гарантирует, что в течение всего выполнения цикла действителен не более одного дескриптора:

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;
  }
  // do something with element
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

При вложении областей видимости возникают случаи, когда дескриптор из внутренней области видимости должен существовать дольше, чем время жизни этой области видимости. Node-API поддерживает 'экранируемую область видимости', чтобы поддержать этот случай. Экранируемая область видимости позволяет 'повысить' один дескриптор, чтобы он 'избежал' текущей области видимости, и время жизни дескриптора изменяется с текущей области видимости на внешнюю область видимости.

Методы, доступные для открытия/закрытия экранируемых областей видимости: 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, представляющий новую область видимости.

Возвращает napi_ok, если API успешно выполнен.

Этот 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, представляющий закрываемую область видимости.

Возвращает napi_ok, если API успешно выполнен.

Этот 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, представляющий новую область видимости.

Возвращает napi_ok, если API успешно выполнен.

Этот API открывает новую область видимости, из которой один объект может быть продвинут во внешнюю область видимости.

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, представляющий закрываемую область видимости.

Возвращает napi_ok, если API успешно выполнен.

Этот 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: napi_value, представляющий JavaScript Object, который необходимо "вынести" из области видимости.
• [out] result: napi_value, представляющий дескриптор "вынесенного" Object во внешней области видимости.

Возвращает napi_ok, если API выполнился успешно.

Этот API повышает уровень дескриптора для JavaScript-объекта, чтобы он был действителен в течение всего времени существования внешней области видимости. Его можно вызвать только один раз для каждой области видимости. Если он вызывается более одного раза, будет возвращена ошибка.

Этот API можно вызывать, даже если есть ожидающее JavaScript-исключение.

Ссылки на значения, время жизни которых больше, чем у собственного метода

В некоторых случаях надстройке потребуется создавать значения и ссылаться на них с временем жизни, превышающим время жизни одного вызова собственного метода. Например, чтобы создать конструктор и позже использовать этот конструктор в запросе на создание экземпляров, необходимо иметь возможность ссылаться на объект-конструктор в нескольких разных запросах на создание экземпляров. Это было бы невозможно с обычным дескриптором, возвращенным в виде napi_value, как описано в предыдущем разделе. Время жизни обычного дескриптора управляется областями видимости, и все области видимости должны быть закрыты до завершения собственного метода.

Node-API предоставляет методы для создания постоянных ссылок на значения. В настоящее время Node-API позволяет создавать ссылки только для ограниченного набора типов значений, включая object, external, function и symbol.

Каждая ссылка имеет связанный счетчик со значением 0 или выше, который определяет, будет ли ссылка поддерживать соответствующее значение в активном состоянии. Ссылки со счетчиком 0 не препятствуют сборке значений. Значения типов object (object, function, external) и symbol становятся "слабыми" ссылками, и к ним все еще можно получить доступ, пока они не собраны. Любой счетчик больше 0 будет препятствовать сборке значений.

Значения Symbol бывают разных видов. Истинное поведение слабой ссылки поддерживается только локальными символами, созданными с помощью функции 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, вернут NULL для возвращаемого napi_value. Попытка вызвать napi_reference_ref для ссылки, объект которой был собран, приводит к ошибке.

Ссылки необходимо удалять, когда они больше не требуются надстройке. Когда ссылка удаляется, она больше не препятствует сборке соответствующего объекта. Неудаление постоянной ссылки приводит к "утечке памяти", при этом и собственная память для постоянной ссылки, и соответствующий объект в куче сохраняются навсегда.

Можно создать несколько постоянных ссылок, которые ссылаются на один и тот же объект, каждая из которых либо поддерживает объект в активном состоянии, либо нет, в зависимости от ее индивидуального счетчика. Несколько постоянных ссылок на один и тот же объект могут привести к неожиданному поддержанию в активном состоянии собственной памяти. Собственные структуры для постоянной ссылки должны поддерживаться в активном состоянии до тех пор, пока не будут выполнены финализаторы для объекта, на который указывает ссылка. Если для одного и того же объекта создается новая постоянная ссылка, финализаторы для этого объекта не будут запущены, а собственная память, на которую указывает более ранняя постоянная ссылка, не будет освобождена. Этого можно избежать, вызвав napi_delete_reference в дополнение к napi_reference_unref, когда это возможно.

История изменений:

• Экспериментальный (определен 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, указывающий на новую ссылку.

Возвращает napi_ok, если API успешно выполнен.

Этот 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, который необходимо удалить.

Возвращает napi_ok, если API успешно выполнен.

Этот 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: Новое количество ссылок.

Возвращает napi_ok, если API успешно выполнен.

Этот 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: Новое количество ссылок.

Возвращает napi_ok, если API успешно выполнен.

Этот 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_value, на которое ссылается napi_ref.

Возвращает napi_ok, если API выполнился успешно.

Если все еще валидно, этот API возвращает napi_value, представляющее значение JavaScript, связанное с napi_ref. В противном случае 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);

Регистрирует fun как функцию, которая будет выполняться с параметром arg после выхода из текущего окружения Node.js.

Функция может быть безопасно указана несколько раз с разными значениями 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);

Отменяет регистрацию fun как функции, которая должна быть запущена с параметром arg после выхода из текущей среды Node.js. Как аргумент, так и значение функции должны точно совпадать.

Функция должна быть первоначально зарегистрирована с помощью 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, как функцию, которая должна быть запущена с параметрами remove_handle и arg после выхода из текущей среды Node.js.

В отличие от 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_async_cleanup_hook_handle, полученного от napi_add_async_cleanup_hook.

Финализация при выходе из окружения Node.js

Окружение Node.js может быть завершено в произвольный момент, как можно скорее, с запретом выполнения JavaScript, например, по запросу worker.terminate(). Когда окружение завершается, зарегистрированные обратные вызовы napi_finalize объектов JavaScript, потокобезопасных функций и данных экземпляра окружения вызываются немедленно и независимо.

Вызов обратных вызовов napi_finalize планируется после вручную зарегистрированных хуков очистки. Чтобы обеспечить правильный порядок финализации дополнений во время завершения работы окружения, чтобы избежать использования памяти после освобождения в обратном вызове napi_finalize, дополнения должны зарегистрировать хук очистки с помощью 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;
}

Чтобы определить класс, чтобы можно было создавать новые экземпляры (часто используется с Оберткой объекта):

// ПРИМЕЧАНИЕ: частичный пример, не весь указанный код включен
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 предоставляются телу макроса NAPI_MODULE_INIT.

Все Node-API дополнения поддерживают контекст, то есть могут загружаться несколько раз. При объявлении такого модуля необходимо учитывать несколько моментов. Более подробная информация представлена в документации по дополнениям, поддерживающим контекст.

Переменные env и exports будут доступны внутри тела функции после вызова макроса.

Для получения более подробной информации об установке свойств объектов смотрите раздел Работа со свойствами JavaScript.

Для получения более подробной информации о создании модулей дополнений в целом обратитесь к существующему API.

Работа со значениями JavaScript

Node-API предоставляет набор API для создания всех типов значений JavaScript. Некоторые из этих типов описаны в Разделе 6 Спецификации языка ECMAScript.

По сути, эти API используются для выполнения одного из следующих действий:

Значения Node-API представлены типом napi_value. Любой вызов Node-API, требующий значение JavaScript, принимает napi_value. В некоторых случаях API проверяет тип napi_value заранее. Однако для повышения производительности вызывающей стороне лучше убедиться, что рассматриваемый napi_value имеет тип JavaScript, ожидаемый API.

Типы перечислений

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;

Описывает перечисления фильтров Ключей/Свойств:

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;

Биты фильтра свойств. Их можно объединить операцией ИЛИ для создания составного фильтра.

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 типы (соответствует 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. Это обычно соответствует типам, описанным в Разделе 6.1 Спецификации языка ECMAScript. В дополнение к типам в этом разделе, napi_valuetype может также представлять Function и Object с внешними данными.

Значение JavaScript типа napi_external появляется в 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. Элементы этого перечисления соответствуют разделу 22.2 спецификации языка ECMAScript.

Функции создания объектов

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: napi_value, представляющий JavaScript Array.

Возвращает napi_ok, если API выполнился успешно.

Этот API возвращает значение Node-API, соответствующее типу JavaScript Array. Массивы JavaScript описаны в разделе 22.1 спецификации языка ECMAScript.

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: napi_value, представляющий JavaScript Array.

Возвращает napi_ok, если API выполнился успешно.

Этот API возвращает значение Node-API, соответствующее типу JavaScript Array. Свойство length объекта Array устанавливается равным переданному параметру length. Однако нет гарантии, что базовый буфер будет предварительно выделен виртуальной машиной при создании массива. Это поведение остается на усмотрение базовой реализации виртуальной машины. Если буфер должен быть непрерывным блоком памяти, который можно напрямую читать и/или записывать через C, рассмотрите возможность использования napi_create_external_arraybuffer.

Массивы JavaScript описаны в разделе 22.1 спецификации языка ECMAScript.

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: Длина в байтах создаваемого array buffer.
• [out] data: Указатель на базовый байтовый буфер ArrayBuffer. data можно при желании игнорировать, передав NULL.
• [out] result: napi_value, представляющий JavaScript ArrayBuffer.

Возвращает napi_ok, если API выполнено успешно.

Этот API возвращает значение Node-API, соответствующее JavaScript ArrayBuffer. ArrayBuffer используются для представления буферов двоичных данных фиксированной длины. Обычно они используются в качестве резервного буфера для объектов TypedArray. Выделенный ArrayBuffer будет иметь базовый байтовый буфер, размер которого определяется переданным параметром length. Базовый буфер при необходимости возвращается вызывающей стороне, если вызывающая сторона хочет напрямую манипулировать буфером. В этот буфер можно записывать только непосредственно из машинного кода. Для записи в этот буфер из JavaScript необходимо создать типизированный массив или объект DataView.

Объекты JavaScript ArrayBuffer описаны в Разделе 24.1 Языковой спецификации ECMAScript.

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: Необработанный указатель на базовый буфер. data можно при желании игнорировать, передав NULL.
• [out] result: napi_value, представляющий node::Buffer.

Возвращает napi_ok, если API выполнено успешно.

Этот 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: napi_value, представляющий node::Buffer.

Возвращает napi_ok, если API успешно выполнен.

Этот 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: Значение времени ECMAScript в миллисекундах с 01 января 1970 г. UTC.
• [out] result: napi_value, представляющий JavaScript Date.

Возвращает napi_ok, если API успешно выполнен.

Этот API не учитывает високосные секунды; они игнорируются, поскольку ECMAScript соответствует спецификации времени POSIX.

Этот API выделяет объект JavaScript Date.

Объекты JavaScript Date описаны в разделе 20.3 спецификации языка ECMAScript.

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: Необязательная подсказка для передачи в обратный вызов finalize во время сборки.
• [out] result: napi_value, представляющий внешнее значение.

Возвращает napi_ok, если API успешно выполнен.

Этот API выделяет значение JavaScript с прикрепленными к нему внешними данными. Это используется для передачи внешних данных через код JavaScript, чтобы их можно было позже получить с помощью собственного кода, используя napi_get_value_external.

API добавляет обратный вызов napi_finalize, который будет вызываться, когда созданный объект JavaScript будет собран сборщиком мусора.

Созданное значение не является объектом и, следовательно, не поддерживает дополнительные свойства. Он считается отдельным типом значения: вызов napi_typeof() с внешним значением дает napi_external.

napi_create_external_arraybuffer

Added in: v8.0.0

N-API version: 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: Необязательная подсказка для передачи в обратный вызов finalize во время сборки.
• [out] result: napi_value, представляющий JavaScript ArrayBuffer.

Возвращает napi_ok, если API успешно выполнен.

Некоторые среды выполнения, отличные от Node.js, отказались от поддержки внешних буферов. В средах выполнения, отличных от Node.js, этот метод может возвращать napi_no_external_buffers_allowed, чтобы указать, что внешние буферы не поддерживаются. Одной из таких сред выполнения является Electron, как описано в этой проблеме electron/issues/35801.

Чтобы обеспечить широчайшую совместимость со всеми средами выполнения, вы можете определить NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED в вашем аддоне перед включением заголовков node-api. Это скроет 2 функции, которые создают внешние буферы. Это гарантирует, что при случайном использовании одного из этих методов возникнет ошибка компиляции.

Этот API возвращает значение Node-API, соответствующее JavaScript ArrayBuffer. Базовый байтовый буфер ArrayBuffer выделяется и управляется внешне. Вызывающий должен обеспечить, чтобы байтовый буфер оставался действительным до вызова обратного вызова finalize.

API добавляет обратный вызов napi_finalize, который будет вызван, когда созданный JavaScript-объект будет собран сборщиком мусора.

JavaScript ArrayBuffer описаны в Разделе 24.1 спецификации языка ECMAScript.

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: Необязательная подсказка для передачи в обратный вызов finalize во время сборки.
• [out] result: napi_value, представляющий node::Buffer.

Возвращает napi_ok, если API успешно выполнен.

Некоторые среды выполнения, отличные от Node.js, отказались от поддержки внешних буферов. В средах выполнения, отличных от Node.js, этот метод может возвращать napi_no_external_buffers_allowed, чтобы указать, что внешние буферы не поддерживаются. Одной из таких сред выполнения является Electron, как описано в этой проблеме electron/issues/35801.

Чтобы поддерживать широчайшую совместимость со всеми средами выполнения, вы можете определить NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED в своем аддоне перед включением заголовков node-api. Это скроет 2 функции, которые создают внешние буферы. Это гарантирует возникновение ошибки компиляции, если вы случайно используете один из этих методов.

Этот API выделяет объект node::Buffer и инициализирует его данными, поддерживаемыми переданным буфером. Хотя это по-прежнему полностью поддерживаемая структура данных, в большинстве случаев достаточно использовать TypedArray.

API добавляет обратный вызов napi_finalize, который будет вызываться, когда только что созданный объект JavaScript будет собран сборщиком мусора.

Для 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: napi_value, представляющий JavaScript Object.

Возвращает napi_ok, если API успешно выполнен.

Этот API выделяет JavaScript Object по умолчанию. Это эквивалентно выполнению new Object() в JavaScript.

Тип JavaScript Object описан в Разделе 6.1.7 Спецификации языка ECMAScript.

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: Необязательный napi_value, который ссылается на JavaScript string, который будет установлен в качестве описания для символа.
• [out] result: napi_value, представляющий JavaScript symbol.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает значение JavaScript symbol из C-строки в кодировке UTF8.

Тип JavaScript symbol описан в Разделе 19.4 Спецификации языка ECMAScript.

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: C-строка в кодировке UTF-8, представляющая текст, который будет использоваться в качестве описания для символа.
• [in] length: Длина строки описания в байтах или NAPI_AUTO_LENGTH, если строка завершается нулем.
• [out] result: napi_value, представляющий JavaScript symbol.

Возвращает napi_ok, если API успешно выполнен.

Этот API ищет в глобальном реестре существующий символ с заданным описанием. Если символ уже существует, он будет возвращен, в противном случае в реестре будет создан новый символ.

Тип JavaScript symbol описан в Разделе 19.4 Спецификации языка ECMAScript.

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: Смещение в байтах внутри ArrayBuffer, с которого начинается проекция TypedArray.
• [out] result: napi_value, представляющий JavaScript TypedArray.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает объект JavaScript TypedArray поверх существующего ArrayBuffer. Объекты TypedArray предоставляют массивоподобное представление основного буфера данных, где каждый элемент имеет одинаковый основной двоичный скалярный тип данных.

Требуется, чтобы (length * size_of_element) + byte_offset было <= размеру в байтах переданного массива. В противном случае будет вызвано исключение RangeError.

Объекты JavaScript TypedArray описаны в Разделе 22.2 Спецификации языка ECMAScript.

node_api_create_buffer_from_arraybuffer

Добавлено в: v23.0.0

[Stable: 1 - Experimental]

Stable: 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: napi_value, представляющий созданный объект JavaScript Buffer.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает объект JavaScript Buffer из существующего ArrayBuffer. Объект 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: ArrayBuffer, лежащий в основе DataView.
• [in] byte_offset: Смещение в байтах внутри ArrayBuffer, с которого начинается проецирование DataView.
• [out] result: napi_value, представляющий JavaScript DataView.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает объект JavaScript DataView поверх существующего ArrayBuffer. Объекты DataView предоставляют array-like представление поверх базового буфера данных, но которое позволяет элементы разного размера и типа в ArrayBuffer.

Требуется, чтобы byte_length + byte_offset было меньше или равно размеру в байтах переданного массива. В противном случае возникает исключение RangeError.

Объекты JavaScript DataView описаны в Разделе 24.3 Спецификации языка ECMAScript.

Функции для преобразования из типов 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: napi_value, представляющий JavaScript number.

Возвращает napi_ok, если API успешно выполнен.

Этот API используется для преобразования из типа C int32_t в тип JavaScript number.

Тип JavaScript number описан в Разделе 6.1.6 Спецификации языка ECMAScript.

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: napi_value, представляющий JavaScript number.

Возвращает napi_ok, если API успешно выполнен.

Этот API используется для преобразования типа C uint32_t в тип JavaScript number.

Тип JavaScript number описан в Разделе 6.1.6 Спецификации языка ECMAScript.

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: napi_value, представляющий JavaScript number.

Возвращает napi_ok, если API успешно выполнен.

Этот API используется для преобразования типа C int64_t в тип JavaScript number.

Тип JavaScript number описан в Разделе 6.1.6 Спецификации языка ECMAScript. Обратите внимание, что полный диапазон 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: napi_value, представляющий JavaScript number.

Возвращает napi_ok, если API успешно выполнен.

Этот API используется для преобразования типа C double в тип JavaScript number.

Тип JavaScript number описан в Разделе 6.1.6 Спецификации языка ECMAScript.

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: napi_value, представляющий JavaScript BigInt.

Возвращает napi_ok, если API выполнен успешно.

Этот 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: napi_value, представляющий JavaScript BigInt.

Возвращает napi_ok, если API выполнен успешно.

Этот 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: Массив 64-битных слов uint64_t в порядке little-endian.
• [out] result: napi_value, представляющий JavaScript BigInt.

Возвращает napi_ok, если API выполнен успешно.

Этот API преобразует массив беззнаковых 64-битных слов в одно значение BigInt.

Результирующий BigInt вычисляется как: (–1) (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: napi_value, представляющий JavaScript string.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает значение JavaScript string из C-строки в кодировке ISO-8859-1. Нативная строка копируется.

Тип JavaScript string описан в разделе 6.1.4 спецификации языка ECMAScript.

node_api_create_external_string_latin1

Добавлено в: v20.4.0, v18.18.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

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: Среда, в которой выполняется надстройка. Это значение может быть null, если строка собирается в рамках завершения рабочего процесса или основного экземпляра Node.js.
  • [in] data: Это значение str в виде указателя void*.
  • [in] finalize_hint: Это значение finalize_hint, которое было передано в API. napi_finalize предоставляет более подробную информацию. Этот параметр является необязательным. Передача значения null означает, что надстройке не нужно уведомлять о сборе соответствующей строки JavaScript.

• [in] finalize_hint: Необязательная подсказка для передачи в обратный вызов финализации во время сборки.

• [out] result: napi_value, представляющий JavaScript string.

• [out] copied: Указывает, была ли скопирована строка. Если это так, то финализатор уже будет вызван для уничтожения str.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает значение JavaScript string из C-строки в кодировке ISO-8859-1. Нативная строка может быть не скопирована и, следовательно, должна существовать в течение всего жизненного цикла значения JavaScript.

Тип JavaScript string описан в разделе 6.1.4 спецификации языка ECMAScript.

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: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если строка завершается нулем.
• [out] result: napi_value, представляющий JavaScript string.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает значение JavaScript string из C-строки в кодировке UTF16-LE. Нативная строка копируется.

Тип JavaScript string описан в Разделе 6.1.4 спецификации языка ECMAScript.

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: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если строка завершается нулем.

• [in] finalize_callback: Функция, вызываемая при сборке строки. Функция будет вызываться со следующими параметрами:

  • [in] env: Среда, в которой работает аддон. Это значение может быть null, если строка собирается как часть завершения рабочего процесса или основного экземпляра Node.js.
  • [in] data: Это значение str в виде указателя void*.
  • [in] finalize_hint: Это значение finalize_hint, которое было передано в API. napi_finalize предоставляет более подробную информацию. Этот параметр является необязательным. Передача значения null означает, что аддону не нужно получать уведомления при сборке соответствующей строки JavaScript.

• [in] finalize_hint: Необязательная подсказка для передачи в обратный вызов финализации во время сборки.

• [out] result: napi_value, представляющий JavaScript string.

• [out] copied: Указывает, была ли скопирована строка. Если это так, финализатор уже был вызван для уничтожения str.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает значение JavaScript string из C-строки в кодировке UTF16-LE. Нативная строка может быть не скопирована и, следовательно, должна существовать в течение всего жизненного цикла значения JavaScript.

Тип JavaScript string описан в Разделе 6.1.4 спецификации языка ECMAScript.

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: napi_value, представляющий JavaScript string.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает значение JavaScript string из C-строки в кодировке UTF8. Нативная строка копируется.

Тип JavaScript string описан в Разделе 6.1.4 спецификации языка ECMAScript.

Функции для создания оптимизированных ключей свойств

Многие JavaScript движки, включая V8, используют интернированные строки в качестве ключей для установки и получения значений свойств. Они обычно используют хеш-таблицу для создания и поиска таких строк. Хотя это добавляет некоторую стоимость за создание каждого ключа, это улучшает производительность после этого, позволяя сравнивать указатели строк вместо целых строк.

Если новая строка 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: napi_value, представляющий оптимизированный JavaScript string, который будет использоваться в качестве ключа свойства для объектов.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает оптимизированное значение JavaScript string из C-строки в кодировке ISO-8859-1, которое будет использоваться в качестве ключа свойства для объектов. Нативная строка копируется. В отличие от napi_create_string_latin1, последующие вызовы этой функции с тем же указателем str могут выиграть от ускорения создания запрошенного napi_value, в зависимости от движка.

Тип JavaScript string описан в Разделе 6.1.4 спецификации языка ECMAScript.

node_api_create_property_key_utf16

Добавлено в: v21.7.0, v20.12.0

[Stable: 1 - Experimental]

Stable: 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: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если строка завершается нулем.
• [out] result: napi_value, представляющий оптимизированную JavaScript string, которая будет использоваться в качестве ключа свойства для объектов.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает оптимизированное значение JavaScript string из C-строки в кодировке UTF16-LE, которое будет использоваться в качестве ключа свойства для объектов. Нативная строка копируется.

Тип JavaScript string описан в разделе 6.1.4 спецификации языка ECMAScript.

node_api_create_property_key_utf8

Добавлено в: v22.9.0, v20.18.0

[Stable: 1 - Experimental]

Stable: 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: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если строка завершается нулем.
• [out] result: napi_value, представляющий оптимизированную JavaScript string, которая будет использоваться в качестве ключа свойства для объектов.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает оптимизированное значение JavaScript string из C-строки в кодировке UTF8, которое будет использоваться в качестве ключа свойства для объектов. Нативная строка копируется.

Тип JavaScript string описан в разделе 6.1.4 спецификации языка ECMAScript.

Функции для преобразования из 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: napi_value, представляющий JavaScript Array, длина которого запрашивается.
• [out] result: uint32, представляющий длину массива.

Возвращает napi_ok, если API выполнен успешно.

Этот API возвращает длину массива.

Длина Array описана в Разделе 22.1.4.1 спецификации языка ECMAScript.

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: napi_value, представляющий ArrayBuffer, для которого выполняется запрос.
• [out] data: Базовый буфер данных ArrayBuffer. Если byte_length равен 0, это может быть NULL или любое другое значение указателя.
• [out] byte_length: Длина базового буфера данных в байтах.

Возвращает napi_ok, если API выполнен успешно.

Этот API используется для получения базового буфера данных ArrayBuffer и его длины.

ВНИМАНИЕ: Будьте осторожны при использовании этого API. Время жизни базового буфера данных управляется ArrayBuffer даже после его возврата. Возможным безопасным способом использования этого API является его использование в сочетании с napi_create_reference, который можно использовать для гарантированного контроля над временем жизни ArrayBuffer. Также безопасно использовать возвращенный буфер данных в том же обратном вызове, если нет вызовов других API, которые могут вызвать GC.

napi_get_buffer_info

Added in: v8.0.0

N-API version: 1

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

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий собой запрашиваемый node::Buffer или Uint8Array.
• [out] data: Базовый буфер данных node::Buffer или Uint8Array. Если длина равна 0, это может быть NULL или любое другое значение указателя.
• [out] length: Длина в байтах базового буфера данных.

Возвращает napi_ok, если API выполнен успешно.

Этот метод возвращает те же data и byte_length, что и napi_get_typedarray_info. И napi_get_typedarray_info также принимает node::Buffer (Uint8Array) в качестве значения.

Этот API используется для получения базового буфера данных node::Buffer и его длины.

Предупреждение: Будьте осторожны при использовании этого API, поскольку время жизни базового буфера данных не гарантируется, если он управляется VM.

napi_get_prototype

Added in: v8.0.0

N-API version: 1

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

• [in] env: Среда, в которой вызывается API.
• [in] object: napi_value, представляющий JavaScript Object, чей прототип нужно вернуть. Возвращает эквивалент Object.getPrototypeOf (который не совпадает со свойством prototype функции).
• [out] result: napi_value, представляющий прототип данного объекта.

Возвращает napi_ok, если API выполнен успешно.

napi_get_typedarray_info

Added in: v8.0.0

N-API version: 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: napi_value, представляющий TypedArray, чьи свойства нужно запросить.
• [out] type: Скалярный тип данных элементов внутри TypedArray.
• [out] length: Количество элементов в TypedArray.
• [out] data: Буфер данных, лежащий в основе TypedArray, скорректированный значением byte_offset, так что он указывает на первый элемент в TypedArray. Если длина массива равна 0, это может быть NULL или любое другое значение указателя.
• [out] arraybuffer: ArrayBuffer, лежащий в основе TypedArray.
• [out] byte_offset: Смещение в байтах внутри базового собственного массива, в котором расположен первый элемент массива. Значение для параметра data уже скорректировано так, что data указывает на первый элемент в массиве. Следовательно, первый байт собственного массива будет находиться по адресу data - byte_offset.

Возвращает napi_ok, если API выполнен успешно.

Этот API возвращает различные свойства типизированного массива.

Любой из выходных параметров может быть NULL, если это свойство не требуется.

Предупреждение: Будьте осторожны при использовании этого API, поскольку базовый буфер данных управляется VM.

napi_get_dataview_info

Added in: v8.3.0

N-API version: 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: napi_value, представляющий DataView, чьи свойства нужно запросить.
• [out] byte_length: Количество байтов в DataView.
• [out] data: Буфер данных, лежащий в основе DataView. Если byte_length равен 0, это может быть NULL или любое другое значение указателя.
• [out] arraybuffer: ArrayBuffer, лежащий в основе DataView.
• [out] byte_offset: Смещение байтов внутри буфера данных, с которого начинается проецирование DataView.

Возвращает napi_ok, если API успешно выполнен.

Любой из выходных параметров может быть NULL, если это свойство не нужно.

Этот API возвращает различные свойства DataView.

napi_get_date_value

Added in: v11.11.0, v10.17.0

N-API version: 5

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

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript Date.
• [out] result: Значение времени в виде double, представленное в миллисекундах с полуночи начала 01 января 1970 года UTC.

Этот API не учитывает високосные секунды; они игнорируются, так как ECMAScript соответствует спецификации времени POSIX.

Возвращает napi_ok, если API успешно выполнен. Если передано значение napi_value, не являющееся датой, возвращает napi_date_expected.

Этот API возвращает примитив C double значения времени для данного JavaScript Date.

napi_get_value_bool

Added in: v8.0.0

N-API version: 1

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

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript Boolean.
• [out] result: C примитив boolean, эквивалентный данному JavaScript Boolean.

Возвращает napi_ok, если API успешно выполнен. Если передано значение napi_value, не являющееся логическим, возвращает napi_boolean_expected.

Этот API возвращает C примитив boolean, эквивалентный данному JavaScript Boolean.

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: napi_value, представляющее JavaScript number.
• [out] result: C примитив типа double, эквивалентный заданному JavaScript number.

Возвращает napi_ok, если API успешно выполнен. Если передано нечисловое значение napi_value, возвращается napi_number_expected.

Этот API возвращает C примитив типа double, эквивалентный заданному JavaScript number.

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: napi_value, представляющее JavaScript BigInt.
• [out] result: C примитив int64_t, эквивалентный заданному JavaScript BigInt.
• [out] lossless: Указывает, было ли преобразование значения BigInt выполнено без потерь.

Возвращает napi_ok, если API успешно выполнен. Если передано не-BigInt значение, возвращается napi_bigint_expected.

Этот API возвращает C примитив int64_t, эквивалентный заданному JavaScript BigInt. При необходимости он будет усекать значение, устанавливая 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: napi_value, представляющее JavaScript BigInt.
• [out] result: C примитив uint64_t, эквивалентный заданному JavaScript BigInt.
• [out] lossless: Указывает, было ли преобразование значения BigInt выполнено без потерь.

Возвращает napi_ok, если API успешно выполнен. Если передано не-BigInt значение, возвращается napi_bigint_expected.

Этот API возвращает C примитив uint64_t, эквивалентный заданному JavaScript BigInt. При необходимости он будет усекать значение, устанавливая 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: napi_value, представляющий JavaScript BigInt.
• [out] sign_bit: Целое число, представляющее, является ли JavaScript BigInt положительным или отрицательным.
• [in/out] word_count: Должен быть инициализирован длиной массива words. При возврате будет установлено фактическое количество слов, необходимое для хранения этого BigInt.
• [out] words: Указатель на предварительно выделенный 64-битный массив слов.

Возвращает napi_ok, если API выполнен успешно.

Этот API преобразует одно значение BigInt в знаковый бит, 64-битный массив с обратным порядком байтов и количество элементов в массиве. sign_bit и words могут быть установлены в NULL, чтобы получить только word_count.

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: napi_value, представляющий внешнее JavaScript значение.
• [out] result: Указатель на данные, обернутые JavaScript внешним значением.

Возвращает napi_ok, если API выполнен успешно. Если передан не внешний 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: napi_value, представляющий JavaScript number.
• [out] result: C int32 примитив, эквивалентный заданному JavaScript number.

Возвращает napi_ok, если API выполнен успешно. Если передан не числовой napi_value, возвращает napi_number_expected.

Этот API возвращает C int32 примитив, эквивалентный заданному JavaScript number.

Если число превышает диапазон 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: napi_value, представляющее JavaScript number.
• [out] result: C int64 примитив, эквивалентный данному JavaScript number.

Возвращает napi_ok, если API успешно выполнено. Если передано нечисловое значение napi_value, возвращает napi_number_expected.

Этот API возвращает C int64 примитив, эквивалентный данному JavaScript number.

Значения number, выходящие за пределы диапазона Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1), потеряют точность.

Неконечные числовые значения (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: napi_value, представляющее строку JavaScript.
• [in] buf: Буфер для записи строки в кодировке ISO-8859-1. Если передано значение NULL, длина строки в байтах, исключая нулевой терминатор, возвращается в result.
• [in] bufsize: Размер целевого буфера. Если этого значения недостаточно, возвращаемая строка усекается и завершается нулем.
• [out] result: Количество байтов, скопированных в буфер, исключая нулевой терминатор.

Возвращает napi_ok, если API успешно выполнено. Если передано значение 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: napi_value, представляющий строку JavaScript.
• [in] buf: Буфер для записи строки в кодировке UTF8. Если передано значение NULL, в result возвращается длина строки в байтах, исключая завершающий нуль-терминатор.
• [in] bufsize: Размер целевого буфера. Если это значение недостаточно, возвращаемая строка усекается и завершается нулем.
• [out] result: Количество байтов, скопированных в буфер, исключая завершающий нуль-терминатор.

Возвращает napi_ok, если API выполнен успешно. Если передано значение napi_value, не являющееся string, возвращается 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: napi_value, представляющий строку JavaScript.
• [in] buf: Буфер для записи строки в кодировке UTF16-LE. Если передано значение NULL, возвращается длина строки в 2-байтовых единицах кода, исключая завершающий нуль-терминатор.
• [in] bufsize: Размер целевого буфера. Если это значение недостаточно, возвращаемая строка усекается и завершается нулем.
• [out] result: Количество 2-байтовых единиц кода, скопированных в буфер, исключая завершающий нуль-терминатор.

Возвращает napi_ok, если API выполнен успешно. Если передано значение napi_value, не являющееся string, возвращается 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: napi_value, представляющий JavaScript number.
• [out] result: Примитив C, эквивалентный данному napi_value, как uint32_t.

Возвращает napi_ok, если API успешно выполнено. Если передается нечисловое napi_value, возвращает napi_number_expected.

Этот API возвращает примитив C, эквивалентный данному napi_value, как 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: napi_value, представляющий JavaScript синглтон Boolean, который нужно получить.

Возвращает napi_ok, если API успешно выполнено.

Этот 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: napi_value, представляющий JavaScript объект global.

Возвращает napi_ok, если API успешно выполнено.

Этот 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: napi_value, представляющий JavaScript объект null.

Возвращает napi_ok, если API успешно выполнено.

Этот 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: napi_value, представляющий значение JavaScript Undefined.

Возвращает napi_ok, если API успешно выполнено.

Этот API возвращает объект Undefined.

Работа со значениями JavaScript и абстрактными операциями

Node-API предоставляет набор API для выполнения некоторых абстрактных операций над значениями JavaScript. Некоторые из этих операций задокументированы в Разделе 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: napi_value, представляющее приведенное JavaScript Boolean.

Возвращает napi_ok, если API выполнен успешно.

Этот API реализует абстрактную операцию ToBoolean(), как определено в Разделе 7.1.2 Спецификации языка ECMAScript.

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: napi_value, представляющее приведенное JavaScript number.

Возвращает napi_ok, если API выполнен успешно.

Этот API реализует абстрактную операцию ToNumber(), как определено в Разделе 7.1.3 Спецификации языка ECMAScript. Эта функция потенциально запускает 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: napi_value, представляющее приведенный JavaScript Object.

Возвращает napi_ok, если API выполнен успешно.

Этот API реализует абстрактную операцию ToObject(), как определено в Разделе 7.1.13 Спецификации языка ECMAScript.

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: napi_value, представляющее преобразованную JavaScript string.

Возвращает napi_ok, если API успешно завершен.

Этот API реализует абстрактную операцию ToString(), как определено в Разделе 7.1.13 Спецификации языка ECMAScript. Эта функция потенциально запускает 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.

Возвращает napi_ok, если API успешно завершен.

• napi_invalid_arg, если тип value не является известным типом ECMAScript и value не является внешним значением.

Этот API представляет поведение, аналогичное вызову оператора typeof для объекта, как определено в Разделе 12.5.5 Спецификации языка ECMAScript. Однако есть некоторые различия:

Если 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: Логическое значение, которое устанавливается в true, если object instanceof constructor имеет значение true.

Возвращает napi_ok, если API успешно завершен.

Этот API представляет вызов оператора instanceof для объекта, как определено в Разделе 12.10.4 Спецификации языка ECMAScript.

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: Указывает, является ли данный объект массивом.

Возвращает napi_ok, если API успешно выполнен.

Этот API представляет собой вызов операции IsArray для объекта, как определено в Разделе 7.2.2 Спецификации языка ECMAScript.

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.

Возвращает napi_ok, если API успешно выполнен.

Этот API проверяет, является ли переданный Object буфером массива.

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.

Возвращает napi_ok, если API успешно выполнен.

Этот API проверяет, является ли переданный Object буфером или Uint8Array. napi_is_typedarray следует предпочесть, если вызывающему необходимо проверить, является ли значение Uint8Array.

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.

Возвращает napi_ok, если API успешно выполнен.

Этот API проверяет, является ли переданный Object датой.

napi_is_error

Added in: v8.0.0

N-API version: 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.

Возвращает napi_ok, если API выполнен успешно.

Этот API проверяет, является ли переданный Object объектом Error.

napi_is_typedarray

Added in: v8.0.0

N-API version: 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.

Возвращает napi_ok, если API выполнен успешно.

Этот API проверяет, является ли переданный Object типизированным массивом.

napi_is_dataview

Added in: v8.3.0

N-API version: 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.

Возвращает napi_ok, если API выполнен успешно.

Этот API проверяет, является ли переданный Object DataView.

napi_strict_equals

Added in: v8.0.0

N-API version: 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: Указывает, равны ли два объекта napi_value.

Возвращает napi_ok, если API выполнен успешно.

Этот API представляет собой вызов алгоритма строгого равенства, как определено в Разделе 7.2.14 спецификации языка ECMAScript.

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, который необходимо отсоединить.

Возвращает napi_ok, если API успешно выполнено. Если передается неотсоединяемый ArrayBuffer, возвращает napi_detachable_arraybuffer_expected.

Как правило, ArrayBuffer не является отсоединяемым, если он был отсоединен ранее. Движок может налагать дополнительные условия на то, является ли ArrayBuffer отсоединяемым. Например, V8 требует, чтобы ArrayBuffer был внешним, то есть созданным с помощью napi_create_external_arraybuffer.

Этот API представляет собой вызов операции отсоединения ArrayBuffer, как определено в Разделе 24.1.1.3 спецификации языка ECMAScript.

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 отсоединенным.

Возвращает napi_ok, если API успешно выполнено.

Считается, что ArrayBuffer отсоединен, если его внутренние данные равны null.

Этот API представляет собой вызов операции IsDetachedBuffer для ArrayBuffer, как определено в Разделе 24.1.1.2 спецификации языка ECMAScript.

Работа со свойствами JavaScript

Node-API предоставляет набор API для получения и установки свойств в объектах JavaScript. Некоторые из этих типов документированы в Разделе 7 Спецификации языка ECMAScript.

Свойства в JavaScript представлены как кортеж ключа и значения. В основном, все ключи свойств в Node-API могут быть представлены в одной из следующих форм:

• Именованные: простая строка в кодировке UTF8
• Целочисленно-индексированные: значение индекса, представленное uint32_t
• Значение JavaScript: они представлены в Node-API как napi_value. Это может быть napi_value, представляющий string, number или symbol.

Значения Node-API представлены типом napi_value. Любой вызов Node-API, требующий значения JavaScript, принимает napi_value. Однако ответственность за то, чтобы napi_value был типа JavaScript, ожидаемого API, лежит на вызывающей стороне.

API, документированные в этом разделе, предоставляют простой интерфейс для получения и установки свойств в произвольных объектах JavaScript, представленных napi_value.

Например, рассмотрим следующий фрагмент кода 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, они соответствуют атрибутам, перечисленным в Разделе 6.1.7.1 Спецификации языка ECMAScript. Они могут быть одним или несколькими из следующих битовых флагов:

• napi_default: Никакие явные атрибуты не установлены для свойства. По умолчанию свойство доступно только для чтения, не перечисляемо и не конфигурируемо.
• napi_writable: Свойство доступно для записи.
• napi_enumerable: Свойство перечисляемо.
• napi_configurable: Свойство конфигурируемо, как определено в Разделе 6.1.7.1 Спецификации языка ECMAScript.
• napi_static: Свойство будет определено как статическое свойство класса, в отличие от свойства экземпляра, которое является значением по умолчанию. Используется только napi_define_class. Игнорируется napi_define_properties.
• napi_default_method: Как метод в классе JS, свойство конфигурируемое и доступное для записи, но не перечисляемое.
• napi_default_jsproperty: Как свойство, установленное через присваивание в JavaScript, свойство доступно для записи, перечисляемо и конфигурируемо.

napi_property_descriptor

typedef struct {
  // One of utf8name or name should be 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: Необязательное napi_value, которое указывает на JavaScript строку или символ, используемый в качестве ключа для свойства. Для свойства должно быть указано либо 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 объекта дескриптора свойства было JavaScript функцией, представленной method. Если это передано, установите для 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: napi_value, представляющий массив значений JavaScript, которые представляют имена свойств объекта. API можно использовать для итерации по result с помощью napi_get_array_length и napi_get_element.

Возвращает napi_ok, если API выполнился успешно.

Этот 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: napi_value, представляющий массив значений JavaScript, которые представляют имена свойств объекта. napi_get_array_length и napi_get_element можно использовать для итерации по result.

Возвращает napi_ok, если API выполнился успешно.

Этот 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: Значение свойства.

Возвращает napi_ok, если API успешно выполнено.

Этот 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: Значение свойства.

Возвращает napi_ok, если API успешно выполнено.

Этот 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: Указывает, существует ли свойство в объекте.

Возвращает napi_ok, если API успешно выполнено.

Этот 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.

Возвращает napi_ok, если API успешно выполнено.

Этот API пытается удалить собственное свойство key из object.

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: Указывает, существует ли собственное свойство в объекте.

Возвращает napi_ok, если API выполнился успешно.

Этот 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: Значение свойства.

Возвращает napi_ok, если API выполнился успешно.

Этот метод эквивалентен вызову napi_set_property с napi_value, созданным из строки, переданной как utf8Name.

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: Значение свойства.

Возвращает napi_ok, если API выполнился успешно.

Этот метод эквивалентен вызову napi_get_property с napi_value, созданным из строки, переданной как utf8Name.

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: Существует ли свойство в объекте или нет.

Возвращает napi_ok, если API успешно выполнен.

Этот метод эквивалентен вызову napi_has_property с napi_value, созданным из строки, переданной как utf8Name.

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: Значение свойства.

Возвращает napi_ok, если API успешно выполнен.

Этот 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: Значение свойства.

Возвращает napi_ok, если API успешно выполнен.

Этот 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: Существует ли свойство в объекте или нет.

Возвращает napi_ok, если API успешно выполнен.

Этот 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.

Возвращает napi_ok, если API успешно выполнено.

Этот API пытается удалить указанный index из object.

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: Массив дескрипторов свойств.

Возвращает napi_ok, если API успешно выполнено.

Этот метод позволяет эффективно определить несколько свойств для заданного объекта. Свойства определяются с использованием дескрипторов свойств (см. napi_property_descriptor). Имея массив таких дескрипторов свойств, этот API будет устанавливать свойства для объекта по одному, как определено в DefineOwnProperty() (описано в Разделе 9.1.6 спецификации ECMA-262).

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: Объект для заморозки.

Возвращает napi_ok, если API успешно выполнено.

Этот метод замораживает заданный объект. Это предотвращает добавление новых свойств, удаление существующих свойств, изменение перечисляемости, конфигурируемости или возможности записи существующих свойств, а также изменение значений существующих свойств. Это также предотвращает изменение прототипа объекта. Это описано в Разделе 19.1.2.6 спецификации ECMA-262.

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: Объект для запечатывания.

Возвращает napi_ok, если API выполнена успешно.

Этот метод запечатывает заданный объект. Это предотвращает добавление новых свойств, а также отмечает все существующие свойства как неконфигурируемые. Это описано в Разделе 19.1.2.20 спецификации ECMA-262.

Работа с функциями JavaScript

Node-API предоставляет набор API, которые позволяют коду JavaScript вызывать нативный код. Node-API, поддерживающие обратный вызов в нативный код, принимают функции обратного вызова, представленные типом napi_callback. Когда JavaScript VM выполняет обратный вызов в нативный код, вызывается предоставленная функция napi_callback. API, задокументированные в этом разделе, позволяют функции обратного вызова выполнять следующие действия:

• Получать информацию о контексте, в котором был вызван обратный вызов.
• Получать аргументы, переданные в обратный вызов.
• Возвращать napi_value из обратного вызова.

Кроме того, Node-API предоставляет набор функций, которые позволяют вызывать функции JavaScript из нативного кода. Можно либо вызвать функцию как обычный вызов функции JavaScript, либо как функцию-конструктор.

Любые данные, отличные от NULL, которые передаются в этот API через поле data элементов napi_property_descriptor, могут быть связаны с object и освобождены, когда object будет собран сборщиком мусора, передав и object, и данные в napi_add_finalizer.

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: napi_value, представляющее функцию JavaScript, которую нужно вызвать.
• [in] argc: Количество элементов в массиве argv.
• [in] argv: Массив napi_values, представляющий значения JavaScript, переданные в качестве аргументов функции.
• [out] result: napi_value, представляющее возвращенный объект JavaScript.

Возвращает napi_ok, если API выполнена успешно.

Этот метод позволяет вызывать объект функции 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 в байтах или NAPI_AUTO_LENGTH, если строка завершается нулем.
• [in] cb: Нативная функция, которая должна быть вызвана при вызове этого объекта-функции. napi_callback предоставляет больше деталей.
• [in] data: Предоставленный пользователем контекст данных. Он будет передан обратно в функцию при последующем вызове.
• [out] result: napi_value, представляющий JavaScript объект-функцию для вновь созданной функции.

Возвращает napi_ok, если API выполнен успешно.

Этот API позволяет автору аддона создавать объект-функцию в нативном коде. Это основной механизм, позволяющий вызывать нативный код аддона из JavaScript.

Вновь созданная функция автоматически не видна из скрипта после этого вызова. Вместо этого свойство должно быть явно установлено на любом объекте, видимом для JavaScript, чтобы функция была доступна из скрипта.

Чтобы предоставить функцию как часть экспорта модуля аддона, установите вновь созданную функцию в объект exports. Пример модуля может выглядеть следующим образом:

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(), является именем цели в binding.gyp, отвечающей за создание файла .node.

Любые не NULL данные, которые передаются в этот API через параметр data, могут быть связаны с результирующей JavaScript функцией (которая возвращается в параметре result) и освобождены всякий раз, когда функция собирается сборщиком мусора, путем передачи JavaScript функции и данных в napi_add_finalizer.

JavaScript Function описаны в Разделе 19.2 Спецификации языка ECMAScript.

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: C массив napi_value, в который будут скопированы аргументы. Если аргументов больше, чем предоставленное количество, копируется только запрошенное количество аргументов. Если предоставлено меньше аргументов, чем заявлено, остаток argv заполняется значениями napi_value, представляющими undefined. argv можно необязательно игнорировать, передав NULL.
• [out] thisArg: Получает аргумент JavaScript this для вызова. thisArg можно необязательно игнорировать, передав NULL.
• [out] data: Получает указатель на данные для обратного вызова. data можно необязательно игнорировать, передав NULL.

Возвращает napi_ok, если API успешно выполнился.

Этот метод используется внутри функции обратного вызова для получения подробной информации о вызове, такой как аргументы и указатель 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 вызова конструктора.

Возвращает napi_ok, если API успешно выполнился.

Этот 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: napi_value, представляющий функцию JavaScript, вызываемую как конструктор.
• [in] argc: Количество элементов в массиве argv.
• [in] argv: Массив значений JavaScript как napi_value, представляющий аргументы конструктора. Если argc равно нулю, этот параметр можно опустить, передав NULL.
• [out] result: napi_value, представляющий возвращаемый объект JavaScript, который в данном случае является созданным объектом.

Этот метод используется для создания нового значения JavaScript с использованием заданного napi_value, представляющего конструктор объекта. Например, рассмотрим следующий фрагмент:

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);

Возвращает napi_ok, если API успешно завершился.

Обертка объекта

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 {
  // иначе...
}

Ссылка должна быть освобождена, когда она больше не нужна.

Бывают случаи, когда 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() - это метод, который принимает два аргумента. Первый - это дескриптор базы данных, а второй - дескриптор запроса. Внутри он разворачивает первый аргумент и приводит полученный указатель к нативному дескриптору базы данных. Затем он разворачивает второй аргумент и приводит полученный указатель к дескриптору запроса. Если аргументы переданы в неправильном порядке, приведение типов сработает, однако существует большая вероятность того, что основная операция базы данных завершится с ошибкой или даже вызовет недопустимый доступ к памяти.

Чтобы гарантировать, что указатель, полученный из первого аргумента, действительно является указателем на дескриптор базы данных, и, аналогично, чтобы указатель, полученный из второго аргумента, действительно является указателем на дескриптор запроса, реализация queryHasRecords() должна выполнить проверку типа. Сохранение конструктора класса JavaScript, из которого был создан дескриптор базы данных, и конструктора, из которого был создан дескриптор запроса, в napi_refs может помочь, поскольку napi_instanceof() можно использовать для проверки того, что экземпляры, переданные в queryHashRecords(), действительно имеют правильный тип.

К сожалению, napi_instanceof() не защищает от манипулирования прототипом. Например, прототип экземпляра дескриптора базы данных можно установить в прототип конструктора для экземпляров дескриптора запроса. В этом случае экземпляр дескриптора базы данных может отображаться как экземпляр дескриптора запроса и пройдет тест napi_instanceof() для экземпляра дескриптора запроса, все еще содержа указатель на дескриптор базы данных.

С этой целью Node-API предоставляет возможности пометки типа.

Тег типа - это 128-битное целое число, уникальное для аддона. Node-API предоставляет структуру napi_type_tag для хранения тега типа. Когда такое значение передается вместе с объектом JavaScript или внешним объектом, хранящимся в napi_value, в 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/'
//
// можно использовать для получения двух значений, с помощью которых можно инициализировать структуру.
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 в байтах или 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, представляющий функцию конструктора для класса.

Возвращает napi_ok, если API выполнился успешно.

Определяет класс JavaScript, включая:

• Функция конструктора JavaScript, имеющая имя класса. При обертке соответствующего класса C++ обратный вызов, переданный через constructor, может быть использован для создания нового экземпляра класса C++, который затем можно поместить внутрь создаваемого экземпляра объекта JavaScript с помощью napi_wrap.
• Свойства функции конструктора, реализация которых может вызывать соответствующие статические свойства данных, аксессоры и методы класса C++ (определенные дескрипторами свойств с атрибутом napi_static).
• Свойства объекта prototype функции конструктора. При обертке класса C++ нестатические свойства данных, аксессоры и методы класса C++ могут быть вызваны из статических функций, заданных в дескрипторах свойств без атрибута napi_static, после извлечения экземпляра класса C++, помещенного внутрь экземпляра объекта JavaScript с помощью napi_unwrap.

При обертке класса C++ обратный вызов конструктора C++, переданный через constructor, должен быть статическим методом класса, который вызывает фактический конструктор класса, затем оборачивает новый экземпляр C++ в объект JavaScript и возвращает объект-обертку. См. napi_wrap для получения подробной информации.

Функция конструктора JavaScript, возвращаемая из napi_define_class, часто сохраняется и используется позже для создания новых экземпляров класса из машинного кода и/или для проверки, являются ли предоставленные значения экземплярами класса. В этом случае, чтобы предотвратить сборку значения функции мусором, можно создать строгую постоянную ссылку на нее с помощью napi_create_reference, гарантируя, что счетчик ссылок будет поддерживаться >= 1.

Любые данные, отличные от NULL, которые передаются в этот API через параметр data или через поле data элементов массива napi_property_descriptor, могут быть связаны с результирующим конструктором 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 объект, который будет оберткой для native объекта.
• [in] native_object: Native экземпляр, который будет обернут в JavaScript объект.
• [in] finalize_cb: Необязательный native callback, который может быть использован для освобождения native экземпляра, когда JavaScript объект был собран сборщиком мусора. napi_finalize предоставляет больше деталей.
• [in] finalize_hint: Необязательная контекстная подсказка, которая передается в finalize callback.
• [out] result: Необязательная ссылка на обернутый объект.

Возвращает napi_ok, если API успешно выполнен.

Оборачивает native экземпляр в JavaScript объект. Native экземпляр может быть извлечен позже с помощью napi_unwrap().

Когда JavaScript код вызывает конструктор для класса, который был определен с помощью napi_define_class(), вызывается napi_callback для конструктора. После создания экземпляра native класса, callback должен затем вызвать napi_wrap(), чтобы обернуть вновь созданный экземпляр в уже созданный JavaScript объект, который является аргументом this для callback конструктора. (Этот объект this был создан из prototype функции конструктора, поэтому он уже имеет определения всех свойств и методов экземпляра.)

Обычно при оборачивании экземпляра класса следует предоставить finalize callback, который просто удаляет native экземпляр, который получен в качестве аргумента data в finalize callback.

Необязательная возвращаемая ссылка изначально является слабой ссылкой, что означает, что она имеет счетчик ссылок равный 0. Обычно этот счетчик ссылок временно увеличивается во время асинхронных операций, которые требуют, чтобы экземпляр оставался валидным.

Внимание: Необязательная возвращаемая ссылка (если она получена) должна быть удалена с помощью napi_delete_reference ТОЛЬКО в ответ на вызов finalize callback. Если она будет удалена до этого, то finalize callback может никогда не быть вызван. Поэтому, при получении ссылки также требуется finalize callback, чтобы обеспечить правильное удаление ссылки.

Finalizer callback могут быть отложены, оставляя окно, где объект был собран сборщиком мусора (и слабая ссылка недействительна), но finalizer еще не был вызван. При использовании napi_get_reference_value() на слабых ссылках, возвращенных napi_wrap(), вы все равно должны обрабатывать пустой результат.

Повторный вызов napi_wrap() для объекта вернет ошибку. Чтобы связать другой native экземпляр с объектом, сначала используйте 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: Указатель на обернутый нативный экземпляр.

Возвращает napi_ok, если API успешно выполнен.

Извлекает нативный экземпляр, который был ранее обернут в JavaScript-объект с помощью napi_wrap().

Когда код 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: Указатель на обернутый нативный экземпляр.

Возвращает napi_ok, если API успешно выполнен.

Извлекает нативный экземпляр, который был ранее обернут в JavaScript-объект js_object с помощью napi_wrap(), и удаляет обертку. Если с оберткой был связан обратный вызов финализации, он больше не будет вызываться, когда 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-объект или external, который нужно пометить.
• [in] type_tag: Тег, которым нужно пометить объект.

Возвращает napi_ok, если API успешно выполнен.

Связывает значение указателя type_tag с JavaScript-объектом или external. Затем можно использовать napi_check_object_type_tag() для сравнения тега, прикрепленного к объекту, с тегом, принадлежащим аддону, чтобы убедиться, что объект имеет правильный тип.

Если объект уже имеет связанный тег типа, этот API вернет napi_invalid_arg.

napi_check_object_type_tag

Добавлено в: v14.8.0, v12.19.0

Версия N-API: 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 объект или внешний (external), чей тег типа необходимо проверить.
• [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: 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 выполнено успешно.

Добавляет функцию обратного вызова napi_finalize, которая будет вызвана, когда JavaScript объект в js_object будет собран сборщиком мусора.

Этот API можно вызывать несколько раз для одного JavaScript объекта.

Внимание: Необязательная возвращаемая ссылка (если получена) должна быть удалена с помощью napi_delete_reference ТОЛЬКО в ответ на вызов функции обратного вызова финализатора. Если она будет удалена раньше, функция обратного вызова финализатора может никогда не быть вызвана. Поэтому, при получении ссылки также требуется функция обратного вызова финализатора, чтобы обеспечить правильное удаление ссылки.

node_api_post_finalizer

Добавлено в: v21.0.0, v20.10.0, v18.19.0

[Stable: 1 - Experimental]

Stable: 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: Необязательная контекстная подсказка, которая передается в функцию обратного вызова финализатора.

Возвращает napi_ok, если API успешно выполнено.

Планирует асинхронный вызов napi_finalize в цикле событий.

Обычно финализаторы вызываются во время сборки объектов GC (сборщиком мусора). В этот момент вызов любого Node-API, который может вызвать изменения в состоянии GC, будет отключен и приведет к сбою 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 должна избегать выполнения каких-либо вызовов Node-API, которые могут привести к выполнению JavaScript или взаимодействию с объектами JavaScript. Чаще всего любой код, которому необходимо выполнять вызовы Node-API, следует помещать в функцию обратного вызова complete. Избегайте использования параметра napi_env в функции обратного вызова execute, так как это, скорее всего, приведет к выполнению JavaScript.

Эти функции реализуют следующие интерфейсы:

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 будет предоставленными надстройкой данными void*, которые были переданы в вызов napi_create_async_work.

После создания асинхронный работник может быть поставлен в очередь на выполнение с помощью функции 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: Идентификатор типа ресурса, предоставляемый для диагностической информации, предоставляемой API async_hooks.
• [in] execute: Нативная функция, которая должна быть вызвана для асинхронного выполнения логики. Данная функция вызывается из потока пула рабочих потоков и может выполняться параллельно с потоком основного цикла событий.
• [in] complete: Нативная функция, которая будет вызвана при завершении или отмене асинхронной логики. Данная функция вызывается из потока основного цикла событий. napi_async_complete_callback предоставляет более подробную информацию.
• [in] data: Предоставляемый пользователем контекст данных. Он будет передан обратно в функции execute и complete.
• [out] result: napi_async_work*, который является дескриптором для вновь созданной асинхронной работы.

Возвращает napi_ok, если API выполнен успешно.

Этот 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.

Возвращает napi_ok, если API выполнен успешно.

Этот 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.

Возвращает napi_ok, если API выполнен успешно.

Этот API запрашивает, чтобы ранее выделенная работа была запланирована для выполнения. После успешного возврата этого API, его нельзя вызывать снова с тем же элементом napi_async_work, иначе результат будет неопределенным.

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.

Возвращает napi_ok, если API выполнен успешно.

Этот 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: Объект, связанный с асинхронной работой, который будет передан в возможные хуки init async_hooks init hooks и может быть доступен через async_hooks.executionAsyncResource().
• [in] async_resource_name: Идентификатор для типа ресурса, который предоставляется для диагностической информации, предоставляемой API async_hooks.
• [out] result: Инициализированный асинхронный контекст.

Возвращает napi_ok, если API успешно выполнен.

Объект async_resource необходимо поддерживать в активном состоянии до napi_async_destroy, чтобы API, связанные с async_hooks, работали правильно. Чтобы сохранить совместимость ABI с предыдущими версиями, napi_async_context не поддерживают строгую ссылку на объекты async_resource, чтобы избежать утечек памяти. Однако, если async_resource собирается сборщиком мусора JavaScript engine до того, как napi_async_context будет уничтожен napi_async_destroy, вызов API, связанных с napi_async_context, таких как napi_open_callback_scope и napi_make_callback, может вызвать проблемы, такие как потеря асинхронного контекста при использовании API AsyncLocalStorage.

Чтобы сохранить совместимость ABI с предыдущими версиями, передача NULL для async_resource не приводит к ошибке. Однако это не рекомендуется, так как это приведет к нежелательному поведению с хуками init async_hooks init hooks и async_hooks.executionAsyncResource(), поскольку ресурс теперь требуется базовой реализацией async_hooks, чтобы обеспечить связь между асинхронными обратными вызовами.

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: Асинхронный контекст, который необходимо уничтожить.

Возвращает napi_ok, если API выполнился успешно.

Этот 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-совместимость с предыдущими версиями, передача NULL для async_context не приводит к ошибке. Однако это приводит к неправильной работе асинхронных хуков. Потенциальные проблемы включают потерю асинхронного контекста при использовании API AsyncLocalStorage.
• [in] recv: Значение this, передаваемое вызываемой функции.
• [in] func: napi_value, представляющий вызываемую JavaScript-функцию.
• [in] argc: Количество элементов в массиве argv.
• [in] argv: Массив значений JavaScript в виде napi_value, представляющий аргументы функции. Если argc равно нулю, этот параметр может быть опущен путем передачи NULL.
• [out] result: napi_value, представляющий возвращаемый объект JavaScript.

Возвращает napi_ok, если API выполнился успешно.

Этот метод позволяет вызывать объект JavaScript-функции из нативного аддона. Этот API похож на napi_call_function. Однако он используется для вызова из нативного кода обратно в JavaScript после возврата из асинхронной операции (когда в стеке нет другого скрипта). Это довольно простая обертка вокруг node::MakeCallback.

Обратите внимание, что не обязательно использовать napi_make_callback из napi_async_complete_callback; в этой ситуации асинхронный контекст обратного вызова уже настроен, поэтому прямого вызова napi_call_function достаточно и уместно. Использование функции napi_make_callback может потребоваться при реализации пользовательского асинхронного поведения, которое не использует napi_create_async_work.

Любые process.nextTick или Promises, запланированные в очереди микрозадач JavaScript во время обратного вызова, выполняются до возврата в 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 hooks. Этот параметр устарел и игнорируется во время выполнения. Вместо этого используйте параметр async_resource в napi_async_init.
• [in] context: Контекст для асинхронной операции, которая вызывает обратный вызов. Это должно быть значение, ранее полученное из napi_async_init.
• [out] result: Вновь созданная область видимости.

Бывают случаи (например, разрешение промисов), когда необходимо иметь эквивалент области видимости, связанной с обратным вызовом, при выполнении определенных вызовов 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.

Возвращает napi_ok, если API успешно выполнен.

Эта функция заполняет структуру version основной, дополнительной и корректирующей версией Node.js, которая в данный момент запущена, а поле release значением process.release.name.

Возвращенный буфер выделен статически и не требует освобождения.

napi_get_version

Added in: v8.0.0

N-API version: 1

napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);

• [in] env: Среда, в которой вызывается API.
• [out] result: Самая высокая поддерживаемая версия Node-API.

Возвращает napi_ok, если API выполнена успешно.

Этот API возвращает самую высокую версию Node-API, поддерживаемую средой выполнения Node.js. Планируется, что Node-API будет аддитивным, чтобы более новые версии Node.js могли поддерживать дополнительные функции API. Чтобы позволить надстройке использовать более новую функцию при работе с версиями Node.js, которые ее поддерживают, при этом обеспечивая резервное поведение при работе с версиями Node.js, которые ее не поддерживают:

• Вызовите napi_get_version(), чтобы определить, доступен ли API.
• Если доступно, динамически загрузите указатель на функцию с помощью uv_dlsym().
• Используйте динамически загруженный указатель для вызова функции.
• Если функция недоступна, предоставьте альтернативную реализацию, которая не использует функцию.

Управление памятью

napi_adjust_external_memory

Added in: v8.5.0

N-API version: 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: Скорректированное значение

Возвращает napi_ok, если API выполнена успешно.

Эта функция предоставляет V8 информацию об объеме внешней выделенной памяти, которая поддерживается объектами JavaScript (т. е. объект JavaScript, который указывает на свою собственную память, выделенную собственной надстройкой). Регистрация внешней выделенной памяти будет запускать глобальные сборки мусора чаще, чем это было бы в противном случае.

Промисы

Node-API предоставляет средства для создания объектов Promise, как описано в разделе 25.4 спецификации ECMA. Он реализует промисы как пару объектов. Когда промис создается с помощью napi_create_promise(), создается и возвращается объект "отложенный" вместе с Promise. Отложенный объект привязан к созданному Promise и является единственным средством разрешения или отклонения Promise с помощью napi_resolve_deferred() или napi_reject_deferred(). Отложенный объект, созданный napi_create_promise(), освобождается napi_resolve_deferred() или napi_reject_deferred(). Объект Promise может быть возвращен в JavaScript, где его можно использовать обычным образом.

Например, чтобы создать промис и передать его асинхронному работнику:

napi_deferred deferred;
napi_value promise;
napi_status status;

// Создаем промис.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// Передаем отложенное значение функции, выполняющей асинхронное действие.
do_something_asynchronous(deferred);

// Возвращаем промис в JS
return promise;

Приведенная выше функция do_something_asynchronous() выполнит свое асинхронное действие, а затем разрешит или отклонит отложенное значение, тем самым завершив промис и освободив отложенное значение:

napi_deferred deferred;
napi_value undefined;
napi_status status;

// Создаем значение, которым завершим отложенное значение.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// Разрешаем или отклоняем промис, связанный с отложенным значением, в зависимости от
// того, успешно ли выполнено асинхронное действие.
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;

// На этом этапе отложенное значение было освобождено, поэтому мы должны присвоить ему значение 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: Недавно созданный отложенный объект, который позже можно передать в napi_resolve_deferred() или napi_reject_deferred() для разрешения или отклонения связанного промиса соответственно.
• [out] promise: JavaScript промис, связанный с отложенным объектом.

Возвращает napi_ok, если API успешно выполнен.

Этот API создает отложенный объект и JavaScript промис.

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: Отложенный объект, связанный промис которого нужно разрешить.
• [in] resolution: Значение, с которым нужно разрешить промис.

Этот API разрешает JavaScript промис посредством отложенного объекта, с которым он связан. Таким образом, его можно использовать только для разрешения JavaScript промисов, для которых доступен соответствующий отложенный объект. Это фактически означает, что промис должен быть создан с использованием napi_create_promise(), а отложенный объект, возвращенный из этого вызова, должен быть сохранен, чтобы его можно было передать в этот API.

Отложенный объект освобождается после успешного завершения.

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: Отложенный объект, связанный промис которого нужно отклонить.
• [in] rejection: Значение, с которым нужно отклонить промис.

Этот API отклоняет JavaScript промис посредством отложенного объекта, с которым он связан. Таким образом, его можно использовать только для отклонения JavaScript промисов, для которых доступен соответствующий отложенный объект. Это фактически означает, что промис должен быть создан с использованием napi_create_promise(), а отложенный объект, возвращенный из этого вызова, должен быть сохранен, чтобы его можно было передать в этот API.

Отложенный объект освобождается после успешного завершения.

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 встроенным объектом promise (то есть, объектом promise, созданным базовым движком).

Выполнение скрипта

Node-API предоставляет API для выполнения строки, содержащей JavaScript, с использованием базового движка JavaScript.

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 обычно могут быть вызваны только из основного потока нативного дополнения. Если дополнение создает дополнительные потоки, то функции Node-API, требующие napi_env, napi_value или napi_ref, не должны вызываться из этих потоков.

Когда дополнение имеет дополнительные потоки и функции JavaScript должны быть вызваны на основе обработки, завершенной этими потоками, эти потоки должны взаимодействовать с основным потоком дополнения, чтобы основной поток мог вызывать функции JavaScript от их имени. API потокобезопасных функций предоставляет простой способ сделать это.

Эти API предоставляют тип napi_threadsafe_function, а также API для создания, уничтожения и вызова объектов этого типа. napi_create_threadsafe_function() создает постоянную ссылку на napi_value, который содержит функцию JavaScript, которую можно вызывать из нескольких потоков. Вызовы происходят асинхронно. Это означает, что значения, с которыми должен быть вызван обратный вызов JavaScript, будут помещены в очередь, и для каждого значения в очереди в конечном итоге будет сделан вызов функции JavaScript.

При создании napi_threadsafe_function можно предоставить обратный вызов napi_finalize. Этот обратный вызов будет вызван в основном потоке, когда потокобезопасная функция будет уничтожена. Он получает контекст и данные завершения, предоставленные во время конструирования, и предоставляет возможность очистки после потоков, например, путем вызова uv_thread_join(). Помимо потока основного цикла, никакие потоки не должны использовать потокобезопасную функцию после завершения обратного вызова завершения.

context, предоставленный во время вызова napi_create_threadsafe_function(), можно получить из любого потока с помощью вызова 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 блокируется, пока не появится свободное место в очереди. napi_call_threadsafe_function() никогда не блокируется, если потокобезопасная функция была создана с максимальным размером очереди, равным 0.

napi_call_threadsafe_function() не следует вызывать с napi_tsfn_blocking из потока JavaScript, потому что, если очередь заполнена, это может привести к взаимоблокировке потока JavaScript.

Фактический вызов в JavaScript контролируется обратным вызовом, заданным через параметр call_js_cb. call_js_cb вызывается в основном потоке один раз для каждого значения, которое было помещено в очередь успешным вызовом napi_call_threadsafe_function(). Если такой обратный вызов не задан, будет использован обратный вызов по умолчанию, и результирующий вызов JavaScript не будет иметь аргументов. Обратный вызов call_js_cb получает функцию JavaScript для вызова в качестве napi_value в своих параметрах, а также указатель контекста void*, использованный при создании napi_threadsafe_function, и следующий указатель данных, созданный одним из вторичных потоков. Затем обратный вызов может использовать API, такой как napi_call_function(), для вызова в JavaScript.

Обратный вызов также может быть вызван с env и call_js_cb, установленными в NULL, чтобы указать, что вызовы в JavaScript больше невозможны, в то время как элементы остаются в очереди и могут нуждаться в освобождении. Обычно это происходит, когда процесс Node.js завершается при активной потокобезопасной функции.

Нет необходимости вызывать JavaScript через napi_make_callback(), потому что Node-API запускает call_js_cb в контексте, подходящем для обратных вызовов.

Ноль или более элементов в очереди могут быть вызваны в каждом тике цикла событий. Приложения не должны зависеть от конкретного поведения, кроме того, что будет достигнут прогресс в вызове обратных вызовов, и события будут вызываться по мере продвижения времени.

Подсчет ссылок на потокобезопасные функции

Потоки могут добавляться и удаляться из объекта napi_threadsafe_function во время его существования. Таким образом, в дополнение к указанию начального количества потоков при создании, можно вызвать napi_acquire_threadsafe_function, чтобы указать, что новый поток начнет использовать потокобезопасную функцию. Аналогично, можно вызвать napi_release_threadsafe_function, чтобы указать, что существующий поток прекратит использовать потокобезопасную функцию.

Объекты napi_threadsafe_function уничтожаются, когда каждый поток, использующий объект, вызвал napi_release_threadsafe_function() или получил статус возврата napi_closing в ответ на вызов napi_call_threadsafe_function. Очередь опустошается перед уничтожением napi_threadsafe_function. napi_release_threadsafe_function() должен быть последним вызовом API, сделанным в сочетании с данной napi_threadsafe_function, потому что после завершения вызова нет гарантии, что napi_threadsafe_function все еще выделена. По той же причине не используйте потокобезопасную функцию после получения возвращаемого значения napi_closing в ответ на вызов napi_call_threadsafe_function. Данные, связанные с napi_threadsafe_function, могут быть освобождены в ее обратном вызове napi_finalize, который был передан в napi_create_threadsafe_function(). Параметр initial_thread_count функции napi_create_threadsafe_function обозначает начальное количество приобретений потокобезопасных функций, вместо многократного вызова napi_acquire_threadsafe_function при создании.

Как только количество потоков, использующих napi_threadsafe_function, достигает нуля, никакие другие потоки не могут начать использовать ее, вызвав napi_acquire_threadsafe_function(). Фактически, все последующие вызовы API, связанные с ней, за исключением napi_release_threadsafe_function(), вернут значение ошибки napi_closing.

Потокобезопасная функция может быть "прервана" путем присвоения значения napi_tsfn_abort функции napi_release_threadsafe_function(). Это приведет к тому, что все последующие API, связанные с потокобезопасной функцией, за исключением napi_release_threadsafe_function(), вернут napi_closing даже до того, как ее счетчик ссылок достигнет нуля. В частности, napi_call_threadsafe_function() вернет napi_closing, тем самым информируя потоки о том, что больше невозможно делать асинхронные вызовы потокобезопасной функции. Это можно использовать в качестве критерия для завершения потока. После получения возвращаемого значения napi_closing от napi_call_threadsafe_function() поток больше не должен использовать потокобезопасную функцию, потому что больше нет гарантии, что она выделена.

Решение о поддержании работы процесса

Подобно дескрипторам libuv, функции, безопасные для потоков, могут быть "связаны" и "несвязаны". "Связанная" функция, безопасная для потоков, будет поддерживать цикл событий в потоке, в котором она создана, до тех пор, пока функция, безопасная для потоков, не будет уничтожена. В отличие от этого, "несвязанная" функция, безопасная для потоков, не будет препятствовать выходу из цикла событий. Для этой цели существуют API napi_ref_threadsafe_function и napi_unref_threadsafe_function.

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, вызываемая из другого потока. Она должна быть предоставлена, если NULL передается в call_js_cb.
• [in] async_resource: Необязательный объект, связанный с асинхронной работой, который будет передан возможным хукам init async_hooks.
• [in] async_resource_name: Строка JavaScript, предоставляющая идентификатор для вида ресурса, предоставляемого для диагностической информации, предоставляемой API async_hooks.
• [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_would_deadlock при вызове с napi_tsfn_blocking из основного потока или рабочего потока, и очередь заполнена.
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_tsfn_nonblocking, чтобы указать, что вызов должен немедленно возвращать статус napi_queue_full всякий раз, когда очередь заполнена.

Этот API не следует вызывать с napi_tsfn_blocking из потока JavaScript, потому что, если очередь заполнена, это может привести к взаимоблокировке потока JavaScript.

Этот API вернет napi_closing, если napi_release_threadsafe_function() был вызван с параметром abort, установленным в napi_tsfn_abort из любого потока. Значение добавляется в очередь только в том случае, если 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, и никакие другие значения не будут помещены в очередь.

Поток должен вызывать этот API, когда он перестает использовать func. Передача func в какие-либо потокобезопасные API после вызова этого 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 может быть пустой строкой, если процесс загрузки надстройки не может установить имя файла надстройки во время загрузки.