Node-API¶

v18.x.x

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

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

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

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

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

1
2

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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

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

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

В итоге аддон использует только экспортированные C API. В результате он все еще получает преимущества стабильности ABI, обеспечиваемой C API.

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

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

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

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

• API Node.js C++, доступные через любой из следующих интерфейсов

  1 2 3 4

  #include <node.h> #include <node_buffer.h> #include <node_version.h> #include <node_object_wrap.h>

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

  1	#include <uv.h>

• API V8, доступный через

  1	#include <v8.h>

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

1

#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. Следующая команда устанавливает необходимый набор инструментов:

1

xcode-select --install

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

1

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.

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

Три перечисленных здесь инструмента позволяют разработчикам и сопровождающим нативных аддонов создавать и загружать двоичные файлы на публичные или частные серверы. Эти инструменты обычно интегрируются с системами сборки CI/CD, такими как Travis CI и AppVeyor для создания и загрузки двоичных файлов для различных платформ и архитектур. Эти двоичные файлы затем доступны для загрузки пользователям, которым не нужно иметь установленный инструментарий C/C++.

node-pre-gyp¶

node-pre-gyp - это инструмент, основанный на node-gyp, который добавляет возможность загрузки двоичных файлов на сервер по выбору разработчика. node-pre-gyp особенно хорошо поддерживает загрузку двоичных файлов на Amazon S3.

prebuild¶

prebuild - это инструмент, поддерживающий сборку с использованием node-gyp или CMake.js. В отличие от node-pre-gyp, который поддерживает множество серверов, prebuild загружает двоичные файлы только на GitHub releases. prebuild - хороший выбор для проектов GitHub, использующих CMake.js.

prebuildify¶

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

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

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

1

#include <node_api.h>

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

1
2

#define NAPI_VERSION 3
#include <node_api.h>

Это ограничивает поверхность Node-API только той функциональностью, которая была доступна в указанных (и более ранних) версиях.

Некоторые возможности Node-API являются экспериментальными и требуют явного согласия:

1
2

#define NAPI_EXPERIMENTAL
#include <node_api.h>

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

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

Версии Node-API аддитивны и версионируются независимо от Node.js. Версия 4 является расширением версии 3 в том смысле, что она имеет все API из версии 3 с некоторыми дополнениями. Это означает, что нет необходимости в перекомпиляции для новых версий Node.js, которые указаны как поддерживающие более позднюю версию.

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

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

1
2
3
4
5
6

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

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

#define NAPI_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 (!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;
  NAPI_CALL(env, napi_create_object(env, &result));

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

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

  return result;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

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

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

Раздел 8.7 Спецификации языка ECMAScript определяет понятие "Агент" как самодостаточную среду, в которой выполняется код JavaScript. Несколько таких Агентов могут быть запущены и завершены одновременно или последовательно процессом.

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

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

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

Для этого Node-API предоставляет способ связать данные таким образом, чтобы их жизненный цикл был связан с жизненным циклом среды Node.js.

napi_set_instance_data.¶

1
2
3
4

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

• [in] env: Среда, в которой вызывается вызов Node-API.
• [in] data: Элемент данных, который должен быть доступен для привязок этого экземпляра.
• [in] finalize_cb: Функция, вызываемая при завершении работы среды. Функция получает данные, чтобы освободить их. napi_finalize предоставляет более подробную информацию.
• [in] finalize_hint: Необязательная подсказка для передачи обратному вызову finalize во время сбора.

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

Этот API связывает data с текущим окружением Node.js. Позже данные могут быть получены с помощью napi_get_instance_data(). Любые существующие данные, связанные с текущим окружением Node.js, которые были установлены с помощью предыдущего вызова napi_set_instance_data(), будут перезаписаны. Если предыдущим вызовом был предоставлен finalize_cb, он не будет вызван.

napi_get_instance_data¶

1
2

napi_status napi_get_instance_data(napi_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¶

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

Если требуется дополнительная информация о том, что API вернул статус отказа, ее можно получить, вызвав napi_get_last_error_info.

napi_extended_error_info¶

1
2
3
4
5
6

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: Зарезервировано для деталей ошибки, специфичных для ВМ. В настоящее время это не реализовано ни для одной ВМ.
• engine_error_code: Код ошибки, специфичный для ВМ. В настоящее время это не реализовано ни для одной ВМ.
• error_code: Код состояния Node-API, который возник при последней ошибке.

Дополнительную информацию смотрите в разделе Обработка ошибок.

napi_env.¶

napi_env используется для представления контекста, который базовая реализация Node-API может использовать для сохранения специфического состояния VM. Эта структура передается родным функциям, когда они вызываются, и должна быть передана обратно при выполнении вызовов Node-API. В частности, тот же napi_env, который был передан при вызове начальной нативной функции, должен быть передан всем последующим вложенным вызовам Node-API. Кэширование napi_env с целью общего повторного использования, а также передача napi_env между экземплярами одного и того же аддона, запущенными на разных потоках Worker, не допускается. Значение napi_env становится недействительным, когда экземпляр нативного аддона выгружается. Уведомление об этом событии передается через обратные вызовы, заданные в napi_add_env_cleanup_hook и napi_set_instance_data.

napi_value.¶

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

napi_threadsafe_function¶

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

napi_threadsafe_function_release_mode¶

Значение, передаваемое napi_release_threadsafe_function() для указания того, должна ли потокобезопасная функция быть немедленно закрыта (napi_tsfn_abort) или просто освобождена (napi_tsfn_release) и таким образом доступна для последующего использования через napi_acquire_threadsafe_function() и napi_call_threadsafe_function().

1
2
3
4

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

napi_threadsafe_function_call_mode¶

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

1
2
3
4

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

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

napi_handle_scope.¶

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

Области действия создаются с помощью napi_open_handle_scope и уничтожаются с помощью napi_close_handle_scope. Закрытие области видимости может указать GC, что все napi_value, созданные во время жизни области видимости хэндла, больше не являются ссылками из текущего кадра стека.

Более подробную информацию можно найти в разделе Управление временем жизни объектов.

napi_escapable_handle_scope.¶

Escapable handle scopes - это специальный тип handle scope для возврата значений, созданных в конкретной handle scope, в родительскую область.

napi_ref¶

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

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

napi_type_tag.¶

128-битное значение, хранящееся в виде двух беззнаковых 64-битных целых чисел. Служит в качестве UUID, которым можно "пометить" объекты JavaScript, чтобы убедиться, что они относятся к определенному типу. Это более надежная проверка, чем napi_instanceof, поскольку последняя может выдать ложное срабатывание, если прототип объекта был изменен. Тегирование типов наиболее полезно в сочетании с napi_wrap, поскольку оно гарантирует, что указатель, полученный из обернутого объекта, может быть безопасно приведен к собственному типу, соответствующему тегу типа, который был ранее применен к объекту JavaScript.

1
2
3
4

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

napi_async_cleanup_hook_handle.¶

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

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

napi_callback_info.¶

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

napi_callback.¶

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

1

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

Если только по причинам, обсуждаемым в Object Lifetime Management, создание хэндла и/или области обратного вызова внутри napi_callback не является необходимым.

napi_finalize.¶

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

1
2
3

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

Если только по причинам, обсуждаемым в Object Lifetime Management, создание хэндла и/или области обратного вызова внутри тела функции не является необходимым.

napi_async_execute_callback.¶

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

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

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

1
2
3

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

Если только по причинам, обсуждаемым в Object Lifetime Management, создание хэндла и/или области обратного вызова внутри тела функции не является необходимым.

napi_threadsafe_function_call_js.¶

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

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

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

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

1
2
3
4

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

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

Если только по причинам, обсуждаемым в Object Lifetime Management, создание хэндла и/или области видимости обратного вызова внутри тела функции не является необходимым.

napi_cleanup_hook.¶

Указатель функции, используемый с napi_add_env_cleanup_hook. Он будет вызван, когда среда будет снесена.

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

1

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

• [in] data: Данные, которые были переданы в napi_add_env_cleanup_hook.

napi_async_cleanup_hook.¶

Указатель функции, используемый с napi_add_async_cleanup_hook. Она будет вызвана, когда среда будет снесена.

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

1
2

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 (движка).

Для получения такой информации предусмотрена функция napi_get_last_error_info, которая возвращает структуру napi_extended_error_info. Формат структуры napi_extended_error_info следующий:

1
2
3
4
5
6

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: Код ошибки, специфичный для ВМ.
• error_code: Код состояния Node-API для последней ошибки.

napi_get_last_error_info возвращает информацию о последнем совершенном вызове Node-API.

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

napi_get_last_error_info.¶

1
2
3

napi_status
napi_get_last_error_info(napi_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_value экземпляром объекта JavaScript Error: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error и napi_is_error.

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

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

1

originalName [code]

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

1

TypeError [ERR_ERROR_1]

napi_throw.¶

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

1
2
3

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

1
2
3

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

1
2
3

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

1
2
3

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

1
2
3

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

1
2
3
4

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

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

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

napi_create_type_error.¶

1
2
3
4

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

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

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

napi_create_range_error.¶

1
2
3
4

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

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

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

node_api_create_syntax_error.¶

1
2
3
4

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

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

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

napi_get_and_clear_last_exception.¶

1
2

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

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

1

napi_status napi_fatal_exception(napi_env env, napi_value err);

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

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

Фатальные ошибки¶

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

napi_fatal_error.¶

1
2
3
4

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

Сделать срок жизни хэндла короче, чем у родного метода¶

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

1
2
3
4
5
6
7
8

for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // do something with element
}

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

for (int i = 0; i < 1000000; i++) {
  napi_handle_scope scope;
  napi_status status = napi_open_handle_scope(env, &scope);
  if (status != napi_ok) {
    break;
  }
  napi_value result;
  status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // do something with element
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

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

Для открытия/закрытия экранируемых диапазонов доступны методы napi_open_escapable_handle_scope и napi_close_escapable_handle_scope.

Запрос на продвижение хэндла осуществляется через napi_escape_handle, который может быть вызван только один раз.

napi_open_handle_scope.¶

1
2

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

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

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

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

napi_close_handle_scope.¶

1
2

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope);

• [in] env: Среда, в которой вызывается API.
• [in] scope: napi_value, представляющее область видимости, которая должна быть закрыта.

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

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

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

napi_open_escapable_handle_scope.¶

1
2
3

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

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

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

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

napi_close_escapable_handle_scope.¶

1
2
3

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);

• [in] env: Среда, в которой вызывается API.
• [in] scope: napi_value, представляющее область видимости, которая должна быть закрыта.

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

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

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

napi_escape_handle.¶

1
2
3
4

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

• [in] env: Среда, в которой вызывается API.
• [in] scope: napi_value, представляющее текущую область видимости.
• [in] escapee: napi_value, представляющее JavaScript Object, который должен быть экранирован.
• [out] result: napi_value, представляющее handle к экранированному объекту во внешней области видимости.

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

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

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

Ссылки на объекты со сроком жизни, превышающим срок жизни родного метода.¶

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

Node-API предоставляет методы для создания постоянных ссылок на объект. Каждая постоянная ссылка имеет связанный с ней счетчик со значением 0 или выше. Счетчик определяет, будет ли ссылка поддерживать соответствующий объект в живом состоянии. Ссылки со значением count, равным 0, не препятствуют сбору объекта и часто называются "слабыми" ссылками. Любой счетчик больше 0 будет препятствовать сбору объекта.

Ссылки могут быть созданы с начальным количеством ссылок. Затем счетчик может быть изменен с помощью функций napi_reference_ref и napi_reference_unref. Если объект собран, когда счетчик ссылок равен 0, все последующие вызовы для получения объекта, связанного со ссылкой napi_get_reference_value вернут NULL для возвращаемого napi_value. Попытка вызвать napi_reference_ref для ссылки, объект которой был собран, приводит к ошибке.

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

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

napi_create_reference.¶

1
2
3
4

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

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

1
2
3

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

1
2
3

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

1
2
3

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

napi_value, передаваемое в или из этих методов, является дескриптором объекта, с которым связана ссылка.

• [in] env: Среда, в которой вызывается API.
• [in] ref: napi_ref, для которого мы запрашиваем соответствующий Object.
• [out] result: napi_значение для объекта, на который ссылается napi_ref.

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

В случае успеха API возвращает napi_value, представляющее JavaScript Object, связанный с napi_ref. В противном случае результатом будет NULL.

Очистка при выходе из текущего окружения Node.js¶

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

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

napi_add_env_cleanup_hook.¶

1
2
3

NODE_EXTERN napi_status napi_add_env_cleanup_hook(napi_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.¶

1
2
3

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

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

Функция должна быть первоначально зарегистрирована с помощью napi_add_env_cleanup_hook, иначе процесс прервется.

napi_add_async_cleanup_hook.¶

1
2
3
4
5

NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
    napi_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.¶

1
2

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, Thread-safe функций и данных экземпляра среды вызываются немедленно и независимо.

Вызов обратных вызовов napi_finalize запланирован после зарегистрированных вручную хуков очистки. Чтобы обеспечить правильный порядок завершения работы аддона во время выключения окружения и избежать использования after-free в обратном вызове napi_finalize, аддоны должны зарегистрировать крючок очистки с napi_add_env_cleanup_hook и napi_add_async_cleanup_hook, чтобы вручную освободить выделенный ресурс в правильном порядке.

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

Модули Node-API регистрируются аналогично другим модулям, за исключением того, что вместо макроса NODE_MODULE используется следующий:

1

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

Следующее отличие - сигнатура для метода Init. Для модуля Node-API она выглядит следующим образом:

1

napi_value Init(napi_env env, napi_value exports);

Возвращаемое значение из Init рассматривается как объект exports для модуля. Для удобства методу Init передается пустой объект через параметр exports. Если Init возвращает NULL, то параметр, переданный в качестве exports, экспортируется модулем. Модули Node-API не могут изменять объект module, но могут указать что угодно в качестве свойства exports модуля.

Добавить метод hello в качестве функции, чтобы его можно было вызывать как метод, предоставляемый аддоном:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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() для аддона:

1
2
3
4
5
6
7

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// NOTE: partial example, not all referenced code is included
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

NAPI_MODULE_INIT() {
  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;
}

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

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

Подробнее о задании свойств объектам смотрите в разделе Работа со свойствами JavaScript.

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

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

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

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

1. Создать новый объект JavaScript
2. Преобразование из примитивного типа C в значение Node-API.
3. Преобразование значения Node-API в примитивный тип C
4. Получение глобальных экземпляров, включая undefined и null.

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

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

napi_key_collection_mode¶

1
2
3
4

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode;

Описывает перечисления фильтра Keys/Properties:

napi_key_collection_mode ограничивает диапазон собираемых свойств.

napi_key_own_only ограничивает собранные свойства только данным объектом. napi_key_include_prototypes будет включать все ключи цепочки прототипов объектов.

napi_key_filter.¶

1
2
3
4
5
6
7
8

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

1
2
3
4

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

Описывает тип napi_value. Как правило, он соответствует типам, описанным в разделе 6.1 спецификации языка ECMAScript. Помимо типов из этого раздела, napi_valuetype может также представлять функции и объекты с внешними данными.

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

napi_typedarray_type.¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

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

1
2
3

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

• [in] env: Среда, в которой вызывается API.
• [in] length: Начальная длина массива.
• [out] result: napi_value, представляющий JavaScript массив.

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

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

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

napi_create_arraybuffer.¶

1
2
3
4

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

1
2
3
4

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

1
2
3
4
5

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

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

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

napi_create_date.¶

1
2
3

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

1
2
3
4
5

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

• [in] env: Среда, в которой вызывается API.
• [in] data: Необработанный указатель на внешние данные.
• [in] finalize_cb: Необязательный обратный вызов для вызова, когда внешнее значение собирается. napi_finalize предоставляет более подробную информацию.
• [in] finalize_hint: Необязательная подсказка для передачи обратному вызову finalize во время сбора.
• [out] result: napi_value, представляющее внешнее значение.

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

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

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

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

napi_create_external_arraybuffer.¶

1
2
3
4
5
6
7

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

• [in] env: Среда, в которой вызывается API.
• [in] external_data: Указатель на базовый байтовый буфер ArrayBuffer.
• [in] byte_length: Длина в байтах базового буфера.
• [in] finalize_cb: Необязательный обратный вызов для вызова, когда ArrayBuffer собирается. napi_finalize предоставляет более подробную информацию.
• [in] finalize_hint: Необязательная подсказка для передачи обратному вызову finalize во время сбора.
• [out] result: napi_value, представляющее JavaScript ArrayBuffer.

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

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

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

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

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

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

napi_create_external_buffer.¶

1
2
3
4
5
6

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

• [in] env: Среда, в которой вызывается API.
• [in] length: Размер в байтах входного буфера (должен быть равен размеру нового буфера).
• [in] data: Необработанный указатель на базовый буфер для передачи JavaScript.
• [in] finalize_cb: Необязательный обратный вызов для вызова, когда ArrayBuffer собирается. napi_finalize предоставляет более подробную информацию.
• [in] finalize_hint: Необязательная подсказка для передачи обратному вызову finalize во время сбора.
• [out] result: napi_value, представляющее node::Buffer.

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

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

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

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

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

Для Node.js >=4 Буферы являются Uint8Array.

napi_create_object.¶

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

1
2
3

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

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

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

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

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

node_api_symbol_for.¶

1
2
3
4

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

• [in] env: Среда, в которой вызывается API.
• [in] utf8description: Строка UTF-8 C, представляющая текст, который будет использоваться в качестве описания символа.
• [in] length: Длина строки описания в байтах, или NAPI_AUTO_LENGTH, если она является нуль-терминированной.
• [out] result: Значение napi_value, представляющее JavaScript symbol.

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

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

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

napi_create_typedarray.¶

1
2
3
4
5
6

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.

napi_create_dataview.¶

1
2
3
4
5

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¶

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 число.

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

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

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

napi_create_uint32.¶

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¶

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¶

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¶

1
2
3

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

1
2
3

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

1
2
3
4
5

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 64-битных слов.
• [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¶

1
2
3
4

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

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

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

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

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

napi_create_string_utf16.¶

1
2
3
4

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

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

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

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

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

napi_create_string_utf8.¶

1
2
3
4

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 string из строки C в кодировке UTF8. Родная строка копируется.

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

Функции для преобразования типов Node-API в типы C¶

napi_get_array_length¶

1
2
3

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

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

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

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

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

napi_get_arraybuffer_info.¶

1
2
3
4

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

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

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

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

napi_get_buffer_info.¶

1
2
3
4

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

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

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

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

napi_get_prototype.¶

1
2
3

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

1
2
3
4
5
6
7

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

napi_get_dataview_info.¶

1
2
3
4
5
6

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

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

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

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

napi_get_date_value.¶

1
2
3

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

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

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

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

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

napi_get_value_bool.¶

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: Булевский примитив, эквивалентный данному JavaScript Boolean.

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

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

napi_get_value_double.¶

1
2
3

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

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

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

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

napi_get_value_bigint_int64.¶

1
2
3
4

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

1
2
3
4

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

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющее JavaScript BigInt.
• [out] result: Примитив C uint64_t, эквивалентный данному JavaScript BigInt.
• [out] lossless: Указывает, было ли значение BigInt преобразовано без потерь.

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

Этот API возвращает примитивный эквивалент C uint64_t заданного JavaScript BigInt. При необходимости он усекает значение, устанавливая lossless в false.

napi_get_value_bigint_words.¶

1
2
3
4
5

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 массив, и количество элементов в массиве. Знак_бита" и words могут быть оба установлены в NULL, чтобы получить только word_count.

napi_get_value_external.¶

1
2
3

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

1
2
3

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

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

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

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

Если число выходит за пределы диапазона 32-битного целого числа, то результат усекается до эквивалента нижних 32 бит. Это может привести к тому, что большое положительное число превратится в отрицательное, если значение > 2³¹ - 1.

Значения не бесконечных чисел (NaN, +Infinity или -Infinity) устанавливают результат равным нулю.

napi_get_value_int64¶

1
2
3

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¶

1
2
3
4
5

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

1
2
3
4
5

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

1
2
3
4
5

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

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий строку JavaScript.
• [in] buf: Буфер для записи строки в кодировке UTF16-LE. Если передан NULL, то возвращается длина строки в 2-байтовых кодовых единицах и без учета нулевого терминатора.
• [in] bufsize: Размер буфера назначения. Если это значение недостаточно, возвращаемая строка усекается и нуль-терминируется.
• [out] result: Количество 2-байтовых единиц кода, скопированных в буфер, без учета нулевого терминатора.

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

Этот API возвращает строку в кодировке UTF16, соответствующую переданному значению.

napi_get_value_uint32.¶

1
2
3

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: Примитивный эквивалент данного napi_value в виде uint32_t.

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

Этот API возвращает примитивный эквивалент заданного napi_value в виде uint32_t.

Функции для получения глобальных экземпляров¶

napi_get_boolean.¶

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

napi_get_global.¶

1

napi_status napi_get_global(napi_env env, napi_value* result)

• [in] env: Среда, в которой вызывается API.
• [out] result: napi_value, представляющий объект JavaScript global.

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

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

napi_get_null.¶

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

1

napi_status napi_get_undefined(napi_env env, napi_value* result)

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

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

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

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

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

Эти API поддерживают выполнение одного из следующих действий:

1. Приводить значения JavaScript к определенным типам JavaScript (таким как число или строка).
2. Проверять тип значения JavaScript.
3. Проверка равенства между двумя значениями JavaScript.

napi_coerce_to_bool.¶

1
2
3

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¶

1
2
3

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 число.

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

Этот API реализует абстрактную операцию ToNumber(), определенную в Раздел 7.1.3 спецификации языка ECMAScript. Эта функция потенциально запускает JS-код, если передаваемое значение является объектом.

napi_coerce_to_object¶

1
2
3

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(), определенную в Section 7.1.13 спецификации языка ECMAScript.

napi_coerce_to_string.¶

1
2
3

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

napi_typeof¶

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. Однако есть некоторые различия:

1. В нем есть поддержка обнаружения внешнего значения.
2. Он определяет null как отдельный тип, в то время как ECMAScript typeof будет определять object.

Если value имеет недопустимый тип, возвращается ошибка.

napi_instanceof.¶