Node-API

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

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

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

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

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

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

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

C++

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

C++

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 предлагает отличную ориентацию и советы для разработчиков, которые только начинают работать с Node-API и node-addon-api. Дополнительные медиа-ресурсы можно найти на странице Медиа Node-API.

Последствия стабильности 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. Следующая команда устанавливает необходимую цепочку инструментов:

bash

xcode-select --install

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

bash

npm install --global windows-build-tools

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

Средства сборки

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

node-gyp

node-gyp — это система сборки, основанная на форке gyp-next инструмента Google GYP и поставляется в комплекте с 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. 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 поддерживает только версию Node-API 8. Стабильность ABI была достигнута, поскольку 8 была строгим надмножеством всех предыдущих версий.

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

В версиях Node.js, которые поддерживают версию Node-API 9 и более поздние, определение NAPI_VERSION=X и использование существующих макросов инициализации аддонов внедрят в аддон запрошенную версию Node-API, которая будет использоваться во время выполнения. Если NAPI_VERSION не установлен, по умолчанию будет использоваться версия 8.

Эта таблица может быть не актуальной в старых потоках, самая актуальная информация находится в последней документации API по адресу: Матрица версий Node-API

Версия Node-API	Поддерживается в
9	v18.17.0+, 20.3.0+, 21.0.0 и все более поздние версии
8	v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 и все более поздние версии
7	v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 и все более поздние версии
6	v10.20.0+, v12.17.0+, 14.0.0 и все более поздние версии
5	v10.17.0+, v12.11.0+, 13.0.0 и все более поздние версии
4	v10.16.0+, v11.8.0+, 12.0.0 и все более поздние версии
3	v6.14.2, 8.11.2+, v9.11.0+, 10.0.0 и все более поздние версии
2	v8.10.0+, v9.3.0+, 10.0.0 и все более поздние версии
1	v8.6.0+*, v9.0.0+, 10.0.0 и все более поздние версии

* Node-API был экспериментальным.

** Node.js 8.0.0 включал Node-API как экспериментальный. Он был выпущен как версия Node-API 1, но продолжал развиваться до Node.js 8.6.0. API отличается в версиях до Node.js 8.6.0. Мы рекомендуем Node-API версии 3 или выше.

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

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

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

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

`napi_value`

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

`napi_threadsafe_function`

Добавлен в: v10.6.0

Версия N-API: 4

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

`napi_threadsafe_function_release_mode`

Добавлен в: v10.6.0

Версия N-API: 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`

Добавлен в: v10.6.0

Версия N-API: 4

Значение, передаваемое в napi_call_threadsafe_function(), чтобы указать, следует ли вызову блокировать выполнение, когда очередь, связанная с потокобезопасной функцией, заполнена.

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

Типы управления памятью Node-API

`napi_handle_scope`

Это абстракция, используемая для управления и изменения времени жизни объектов, созданных в определённой области видимости. В целом, значения Node-API создаются в контексте области действия обработчика. Когда собственный метод вызывается из JavaScript, будет существовать область действия обработчика по умолчанию. Если пользователь явно не создаёт новую область действия обработчика, значения Node-API будут создаваться в области действия обработчика по умолчанию. Для любых вызовов кода за пределами выполнения собственного метода (например, во время вызова обратного вызова libuv) модуль должен создать область видимости перед вызовом любых функций, которые могут привести к созданию значений JavaScript.

Области действия обработчиков создаются с помощью napi_open_handle_scope и уничтожаются с помощью napi_close_handle_scope. Закрытие области видимости может указать сборщику мусора, что все 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, могут вызываться только API Node, которые принимают 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);

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

экспериментальный (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_status со значением napi_pending_exception. Однако это не относится ко всем функциям. Node-API позволяет вызывать подмножество функций для выполнения минимальной очистки перед возвратом в JavaScript. В этом случае napi_status будет отражать состояние функции. Он не будет отражать предыдущие ожидающие исключения. Во избежание путаницы проверяйте состояние ошибки после каждого вызова функции.

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

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

Второй подход заключается в попытке обработки исключения. Будут случаи, когда собственный код может перехватить исключение, предпринять соответствующие действия и продолжить работу. Это рекомендуется только в тех конкретных случаях, когда известно, что исключение может быть безопасно обработано. В этих случаях можно использовать napi_get_and_clear_last_exception для получения и очистки исключения. В случае успеха result будет содержать дескриптор последнего выброшенного объекта JavaScript Object. Если после получения исключения будет определено, что его нельзя обработать, его можно перебросить с помощью napi_throw, где error — это значение JavaScript, которое будет выброшено.

Также доступны следующие служебные функции, если собственному коду необходимо выбросить исключение или определить, является ли napi_value экземпляром объекта JavaScript Error: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error и napi_is_error.

Также доступны следующие служебные функции, если собственному коду необходимо создать объект Error: napi_create_error, napi_create_type_error, napi_create_range_error и node_api_create_syntax_error, где result — это napi_value, который ссылается на вновь созданный объект JavaScript Error.

В проекте Node.js добавляются коды ошибок ко всем ошибкам, генерируемым внутри. Цель состоит в том, чтобы приложения использовали эти коды ошибок для всей проверки ошибок. Соответствующие сообщения об ошибках останутся, но будут предназначены только для ведения журнала и отображения с ожиданием, что сообщение может измениться без применения SemVer. Для поддержки этой модели с Node-API, как во внутренней функциональности, так и для функциональности, специфичной для модуля (так как это хорошая практика), функции throw_ и create_ принимают необязательный параметр кода, который представляет собой строку для кода, который будет добавлен к объекту ошибки. Если необязательный параметр равен NULL, то никакой код не будет связан с ошибкой. Если предоставлен код, имя, связанное с ошибкой, также обновляется следующим образом:

text

originalName [code]

где originalName — это исходное имя, связанное с ошибкой, а code — это предоставленный код. Например, если код — 'ERR_ERROR_1' и создается TypeError, имя будет:

text

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`

Добавлен в: v17.2.0, v16.14.0

Версия N-API: 9

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

[in] env: Среда, в которой вызывается API.
[in] code: Необязательный код ошибки, который будет установлен для ошибки.
[in] msg: C-строка, представляющая текст, который будет связан с ошибкой.

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

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

`napi_is_error`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] value: Значение napi_value, которое необходимо проверить.
[out] result: Булево значение, которое устанавливается в true, если napi_value представляет ошибку, в противном случае — false.

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

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

`napi_create_error`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] code: Необязательное значение napi_value со строкой кода ошибки, который будет связан с ошибкой.
[in] msg: napi_value, который ссылается на JavaScript string, который будет использоваться в качестве сообщения для Error.
[out] result: napi_value, представляющее созданную ошибку.

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

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

`napi_create_type_error`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] code: Необязательное значение napi_value со строкой кода ошибки, который будет связан с ошибкой.
[in] msg: 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-строку, которая будет использоваться в качестве сообщения для 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-строку, которая будет использоваться в качестве сообщения для 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`

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

Версия N-API: 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`

Добавлено в: v9.10.0

Версия N-API: 3

napi_status napi_fatal_exception(napi_env env, napi_value err);

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

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

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

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

`napi_fatal_error`

Добавлено в: v8.2.0

Версия N-API: 1

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

[in] location: Необязательное местоположение, где произошла ошибка.
[in] location_len: Длина местоположения в байтах или NAPI_AUTO_LENGTH, если оно завершается нулем.
[in] message: Сообщение, связанное с ошибкой.
[in] message_len: Длина сообщения в байтах или NAPI_AUTO_LENGTH, если оно завершается нулем.

Функция не возвращает значение, процесс будет завершен.

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

Управление временем существования объектов

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

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

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

Сокращение времени жизни дескрипторов по сравнению с временем жизни собственного метода

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

for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // выполнить действие с элементом
}

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

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

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

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

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

Этот API открывает новый scope.

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

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

Этот API закрывает переданный scope. Scopes должны закрываться в обратном порядке их создания.

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

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

Этот API открывает новый scope, из которого один объект может быть перемещен во внешний scope.

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

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

Этот API закрывает переданный scope. Scopes должны закрываться в обратном порядке их создания.

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

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

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

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

Ссылки на значения со временем существования, превышающим время существования собственного метода

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

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

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

Символьные значения имеют разные характеристики. Поведение истинной слабой ссылки поддерживается только локальными символами, созданными с помощью функции napi_create_symbol или вызовов конструктора JavaScript Symbol(). Глобально зарегистрированные символы, созданные с помощью функции node_api_symbol_for или вызовов функции JavaScript Symbol.for(), всегда остаются сильными ссылками, поскольку сборщик мусора не собирает их. То же самое относится и к общеизвестным символам, таким как Symbol.iterator. Они также никогда не собираются сборщиком мусора.

Ссылки могут быть созданы с начальным счетчиком ссылок. Затем счетчик можно изменить с помощью napi_reference_ref и napi_reference_unref. Если объект собирается, пока счетчик для ссылки равен 0, все последующие вызовы для получения объекта, связанного со ссылкой napi_get_reference_value, вернут 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 также может представлять Функции и Объекты с внешними данными.

Значение 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. Свойство длины Array устанавливается в переданный параметр длины. Однако не гарантируется, что базовый буфер будет предварительно выделен виртуальной машиной при создании массива. Это поведение остается за реализацией базовой виртуальной машины. Если буфер должен быть непрерывным блоком памяти, который можно напрямую читать и/или записывать через 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: Длина в байтах создаваемого буфера массива.
[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: Необязательный намек для передачи в обратный вызов завершения во время сбора мусора.
[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`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] external_data: Указатель на основной буфер байтов ArrayBuffer.
[in] byte_length: Длина в байтах основного буфера.
[in] finalize_cb: Необязательный обратный вызов, вызываемый при сборке мусора ArrayBuffer. napi_finalize содержит дополнительные сведения.
[in] finalize_hint: Необязательное подсказка для передачи в обратный вызов завершения во время сбора мусора.
[out] result: Значение 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 выделяется и управляется внешним образом. Вызывающая сторона должна гарантировать, что буфер байтов останется действительным до вызова обратного вызова завершения.

Объекты 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.

Для 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 из кодированной в UTF8 C-строки.

Тип символа 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

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1 - Экспериментально

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

[in] env: Среда, в которой вызывается API.
[in] arraybuffer: ArrayBuffer, из которого будет создан буфер.
[in] byte_offset: Смещение в байтах внутри ArrayBuffer, с которого начинается создание буфера.
[in] byte_length: Длина в байтах буфера, который будет создан из ArrayBuffer.
[out] result: Значение 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 предоставляют представление в виде массива для базового буфера данных, но такое, которое позволяет использовать элементы разных размеров и типов в 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.

Возвращает 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.

Возвращает 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.

Возвращает 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: Массив слов uint64_t в формате little-endian.
[out] result: Значение napi_value, представляющее JavaScript BigInt.

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

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

Результирующий BigInt вычисляется как: (–1)^sign_bit (words[0] × (2⁶⁴) + words[1] × (2¹²⁸) + …)

`napi_create_string_latin1`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] str: Буфер символов, представляющий строку в кодировке ISO-8859-1.
[in] length: Длина строки в байтах или NAPI_AUTO_LENGTH, если она завершается нулевым символом.
[out] result: napi_value, представляющее строку JavaScript.

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

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

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

`node_api_create_external_string_latin1`

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

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1 - Экспериментально

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

[in] env: Среда, в которой вызывается API.
[in] str: Буфер символов, представляющий строку в кодировке ISO-8859-1.
[in] length: Длина строки в байтах или NAPI_AUTO_LENGTH, если она завершается нулевым символом.
[in] finalize_callback: Функция, вызываемая при сборке мусора строки. Функция будет вызвана со следующими параметрами:
- [in] env: Среда, в которой работает надстройка. Это значение может быть null, если строка собирается как часть завершения работы потока или основного экземпляра Node.js.
- [in] data: Это значение str как указатель void*.
- [in] finalize_hint: Это значение finalize_hint, переданное в API. napi_finalize содержит более подробную информацию. Этот параметр необязателен. Передача нулевого значения означает, что надстройка не должна получать уведомление о том, когда соответствующая строка JavaScript собрана.
[in] finalize_hint: Необязательное значение для передачи в функцию обратного вызова finalize во время сбора мусора.
[out] result: napi_value, представляющее строку JavaScript.
[out] copied: Была ли скопирована строка. Если да, то финализатор уже был вызван для уничтожения str.

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

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

Тип строки JavaScript описан в разделе 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.

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

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

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

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

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

Тип строки JavaScript описан в разделе 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.

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

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

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

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

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

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

`node_api_create_property_key_utf16`

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

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

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

[in] env: Среда, в которой вызывается API.
[in] str: Буфер символов, представляющий строку, закодированную в UTF16-LE.
[in] length: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если она завершается нулевым байтом.
[out] result: Значение napi_value, представляющее оптимизированную строку JavaScript, которая будет использоваться в качестве ключа свойства для объектов.

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

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

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

`node_api_create_property_key_utf8`

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

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

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

[in] env: Среда, в которой вызывается API.
[in] str: Буфер символов, представляющий строку, закодированную в UTF8.
[in] length: Длина строки в байтах или NAPI_AUTO_LENGTH, если она завершается нулевым байтом.
[out] result: Значение napi_value, представляющее оптимизированную строку JavaScript, которая будет использоваться в качестве ключа свойства для объектов.

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

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

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

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

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

Длина массива описана в Разделе 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, которые могут вызвать сборку мусора.

`napi_get_buffer_info`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] value: 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`

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

Версия N-API: 1

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

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

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

`napi_get_typedarray_info`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] typedarray: 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`

Добавлено в: v8.3.0

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] dataview: 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`

Добавлено в: v11.11.0, v10.17.0

Версия N-API: 5

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

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

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

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

`napi_get_value_bool`

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

Версия N-API: 1

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

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

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

Этот API возвращает эквивалент основного типа C bool для данного 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.
[out] result: Примитивный эквивалент типа C double для заданного числа JavaScript.

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

Этот API возвращает примитивный эквивалент типа C double для заданного числа JavaScript.

`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 выполнено без потерь.

Этот 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-битный массив в формате little-endian и количество элементов в массиве. 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.
[out] result: Примитивный эквивалент C int64 данного числа JavaScript.

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

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

Значения 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, не являющееся строкой, возвращается 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-байтных кодовых единиц, скопированных в буфер, без учёта завершающего нуля.

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

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

Этот API возвращает глобальный объект.

`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.

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

Этот API возвращает неопределенный объект.

Работа с 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.

Возвращает 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 истинно.

Возвращает 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`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] value: Проверяемое значение JavaScript.
[out] result: Определяет, представляет ли данное значение napi_value объект Error.

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

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

`napi_is_typedarray`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] value: Проверяемое значение JavaScript.
[out] result: Определяет, представляет ли данное значение napi_value массив TypedArray.

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

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

`napi_is_dataview`

Добавлено в: v8.3.0

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] value: Проверяемое значение JavaScript.
[out] result: Определяет, представляет ли данное значение napi_value объект DataView.

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

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

`napi_strict_equals`

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

Версия N-API: 1

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

[in] env: Среда, в которой вызывается API.
[in] lhs: Проверяемое значение JavaScript.
[in] rhs: Значение JavaScript для сравнения.
[out] result: Определяет, равны ли два объекта 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, представляющее строку, число или символ.

Значения 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 {
  // Одно из значений utf8name или name должно быть NULL.
  const char* utf8name;
  napi_value name;

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

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor;

utf8name: Необязательная строка, описывающая ключ свойства, закодированная в UTF8. Для свойства необходимо указать одно из значений utf8name или name.
name: Необязательное значение 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 должен быть строкой или символом, иначе будет выброшено исключение. 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 вызывать обратный вызов в собственный код. API Node-API, которые поддерживают обратный вызов в собственный код, принимают в качестве аргумента функции обратного вызова, представленные типом napi_callback. Когда виртуальная машина JavaScript вызывает обратный вызов в собственный код, вызывается предоставленная функция 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, чтобы функция была доступна из скрипта.

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

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, который оборачивает собственный дескриптор базы данных.
// handle.
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_ref может помочь, поскольку 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++ переданный через constructor обратный вызов конструктора C++ должен быть статическим методом класса, который вызывает фактический конструктор класса, затем оборачивает новый экземпляр 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, который будет оберткой для собственного объекта.
[in] native_object: Собственный экземпляр, который будет обернут в объект JavaScript.
[in] finalize_cb: Необязательный собственный обратный вызов, который можно использовать для освобождения собственного экземпляра, когда объект JavaScript был удален сборщиком мусора. napi_finalize содержит более подробную информацию.
[in] finalize_hint: Необязательный контекстный намек, передаваемый в обратный вызов завершения.
[out] result: Необязательная ссылка на обернутый объект.

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

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

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

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

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

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

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

Повторный вызов napi_wrap() для объекта вернет ошибку. Чтобы связать другой собственный экземпляр с объектом, сначала используйте napi_remove_wrap().

`napi_unwrap`

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

Версия N-API: 1

napi_status napi_unwrap(napi_env env,
                        napi_value js_object,
                        void** result);

[in] env: Среда, в которой вызывается API.
[in] js_object: Объект, связанный с собственным экземпляром.
[out] result: Указатель на обернутый собственный экземпляр.

Возвращает 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: Объект JavaScript, связанный с собственным экземпляром.
[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 или внешний объект, который необходимо пометить.
[in] type_tag: Тег, которым необходимо пометить объект.

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

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

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

`napi_check_object_type_tag`

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

Версия N-API: 8

napi_status napi_check_object_type_tag(napi_env env,
                                       napi_value js_object,
                                       const napi_type_tag* type_tag,
                                       bool* result);

[in] env: Среда, в которой вызывается API.
[in] js_object: Объект JavaScript или внешний объект, тег типа которого нужно проверить.
[in] type_tag: Тег, с которым нужно сравнить любой тег, найденный в объекте.
[out] result: Совпал ли заданный тег типа с тегом типа в объекте. false также возвращается, если в объекте не найден тег типа.

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

Сравнивает указатель, заданный как type_tag, с любым, который может быть найден в js_object. Если тег не найден в js_object или если тег найден, но он не совпадает с type_tag, то result устанавливается в false. Если тег найден и он совпадает с type_tag, то result устанавливается в true.

`napi_add_finalizer`

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

Версия N-API: 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

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint);

[in] env: Среда, в которой вызывается API.
[in] finalize_cb: Нативный обратный вызов, который будет использоваться для освобождения собственных данных после сборки мусора объекта JavaScript. napi_finalize содержит более подробную информацию.
[in] finalize_data: Необязательные данные, которые будут переданы в finalize_cb.
[in] finalize_hint: Необязательная контекстная подсказка, передаваемая в обратный вызов завершения.

Возвращает 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: Объект, связанный с асинхронной работой, который будет передан возможным хукам async_hooks init и может быть доступен через 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 до того, как napi_async_context будет уничтожен с помощью napi_async_destroy, вызов API, связанных с napi_async_context, таких как napi_open_callback_scope и napi_make_callback, может привести к проблемам, таким как потеря асинхронного контекста при использовании API AsyncLocalStorage.

Для сохранения совместимости ABI со старыми версиями, передача NULL для async_resource не приводит к ошибке. Однако это не рекомендуется, так как это приведёт к нежелательному поведению с хуками async_hooks init и 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 или Promise, запланированные в очереди микрозадач 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. Этот параметр устарел и игнорируется во время выполнения. Используйте параметр 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`

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

Версия N-API: 1

napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);

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

Возвращает 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`

Добавлено в: v8.5.0

Версия N-API: 1

NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
                                                    int64_t change_in_bytes,
                                                    int64_t* result);

[in] env: Среда, в которой вызывается API.
[in] change_in_bytes: Изменение в объёме внешне выделенной памяти, которая поддерживается объектами JavaScript.
[out] result: Скоректированное значение

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

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

Promise

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

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

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() для разрешения или отклонения связанного promise.
[out] promise: Promise JavaScript, связанный с отложенным объектом.

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

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

Этот API разрешает promise JavaScript с помощью отложенного объекта, с которым он связан. Таким образом, он может использоваться только для разрешения promise JavaScript, для которых доступен соответствующий отложенный объект. Это означает, что promise должен был быть создан с помощью 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: Отложенный объект, связанный с promise, который нужно отклонить.
[in] rejection: Значение, с помощью которого нужно отклонить promise.

Этот API отклоняет promise JavaScript с помощью отложенного объекта, с которым он связан. Таким образом, он может использоваться только для отклонения promise JavaScript, для которых доступен соответствующий отложенный объект. Это означает, что promise должен был быть создан с помощью 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(). Помимо потока основного цикла, ни один поток не должен использовать потокобезопасную функцию после завершения обратного вызова finalize.

Контекст, заданный во время вызова 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, вызываемая из другого потока. Она должна быть предоставлена, если в call_js_cb передается NULL.
[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` из основного потока или потока worker, и очередь заполнена.
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 может быть пустой строкой, если процесс загрузки дополнения не может установить имя файла дополнения во время загрузки.

Node-API ​

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

Сборка ​

Средства сборки ​

node-gyp ​

CMake.js ​

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

node-pre-gyp ​

prebuild ​

prebuildify ​

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

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

API жизненного цикла среды ​

napi_set_instance_data ​

napi_get_instance_data ​

Базовые типы данных Node-API ​

napi_status ​

napi_extended_error_info ​

napi_env ​

node_api_basic_env ​

napi_value ​

napi_threadsafe_function ​

napi_threadsafe_function_release_mode ​

napi_threadsafe_function_call_mode ​

Типы управления памятью Node-API ​

napi_handle_scope ​

napi_escapable_handle_scope ​

napi_ref ​

napi_type_tag ​

napi_async_cleanup_hook_handle ​

Типы обратных вызовов Node-API ​

napi_callback_info ​

napi_callback ​

node_api_basic_finalize ​

napi_finalize ​

napi_async_execute_callback ​

napi_async_complete_callback ​

napi_threadsafe_function_call_js ​

napi_cleanup_hook ​

napi_async_cleanup_hook ​

Обработка ошибок ​

Возвращаемые значения ​

napi_get_last_error_info ​

Исключения ​

napi_throw ​

napi_throw_error ​

napi_throw_type_error ​

napi_throw_range_error ​

node_api_throw_syntax_error ​

napi_is_error ​

napi_create_error ​

napi_create_type_error ​

napi_create_range_error ​

node_api_create_syntax_error ​

napi_get_and_clear_last_exception ​

napi_is_exception_pending ​

napi_fatal_exception ​

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

napi_fatal_error ​

Управление временем существования объектов ​

Сокращение времени жизни дескрипторов по сравнению с временем жизни собственного метода ​

napi_open_handle_scope ​

napi_close_handle_scope ​

napi_open_escapable_handle_scope ​

napi_close_escapable_handle_scope ​

napi_escape_handle ​

Ссылки на значения со временем существования, превышающим время существования собственного метода ​

napi_create_reference ​

napi_delete_reference ​

napi_reference_ref ​

napi_reference_unref ​

napi_get_reference_value ​

Очистка при выходе из текущей среды Node.js ​

napi_add_env_cleanup_hook ​

napi_remove_env_cleanup_hook ​

napi_add_async_cleanup_hook ​

napi_remove_async_cleanup_hook ​

Завершение работы среды Node.js ​

Регистрация модуля ​

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

Node-API

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

Сборка

Средства сборки

node-gyp

CMake.js

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

node-pre-gyp

prebuild

prebuildify

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

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

API жизненного цикла среды

`napi_set_instance_data`

`napi_get_instance_data`

Базовые типы данных Node-API

`napi_status`

`napi_extended_error_info`

`napi_env`

`node_api_basic_env`

`napi_value`

`napi_threadsafe_function`

`napi_threadsafe_function_release_mode`

`napi_threadsafe_function_call_mode`

Типы управления памятью Node-API

`napi_handle_scope`

`napi_escapable_handle_scope`

`napi_ref`

`napi_type_tag`

`napi_async_cleanup_hook_handle`

Типы обратных вызовов Node-API

`napi_callback_info`

`napi_callback`

`node_api_basic_finalize`

`napi_finalize`

`napi_async_execute_callback`

`napi_async_complete_callback`

`napi_threadsafe_function_call_js`

`napi_cleanup_hook`

`napi_async_cleanup_hook`

Обработка ошибок

Возвращаемые значения

`napi_get_last_error_info`

Исключения

`napi_throw`

`napi_throw_error`

`napi_throw_type_error`

`napi_throw_range_error`

`node_api_throw_syntax_error`

`napi_is_error`

`napi_create_error`

`napi_create_type_error`

`napi_create_range_error`

`node_api_create_syntax_error`

`napi_get_and_clear_last_exception`

`napi_is_exception_pending`

`napi_fatal_exception`

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

`napi_fatal_error`

Управление временем существования объектов

Сокращение времени жизни дескрипторов по сравнению с временем жизни собственного метода

`napi_open_handle_scope`

`napi_close_handle_scope`

`napi_open_escapable_handle_scope`

`napi_close_escapable_handle_scope`

`napi_escape_handle`

Ссылки на значения со временем существования, превышающим время существования собственного метода

`napi_create_reference`

`napi_delete_reference`

`napi_reference_ref`

`napi_reference_unref`

`napi_get_reference_value`

Очистка при выходе из текущей среды Node.js

`napi_add_env_cleanup_hook`

`napi_remove_env_cleanup_hook`

`napi_add_async_cleanup_hook`

`napi_remove_async_cleanup_hook`

Завершение работы среды Node.js

Регистрация модуля

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