Lines Matching +full:node +full:- +full:api

1 # N-API
3 <!--introduced_in=v8.0.0-->
4 <!-- type=misc -->
6 > Stability: 2 - Stable
8 N-API (pronounced N as in the letter, followed by API)
9 is an API for building native Addons. It is independent from
11 Node.js itself. This API will be Application Binary Interface (ABI) stable
12 across versions of Node.js. It is intended to insulate Addons from
14 compiled for one major version to run on later major versions of Node.js without
15 recompilation. The [ABI Stability][] guide provides a more in-depth explanation.
19 the native code. Instead of using the V8 or [Native Abstractions for Node.js][]
20 APIs, the functions available in the N-API are used.
22 APIs exposed by N-API are generally used to create and manipulate
24 in the ECMA-262 Language Specification. The APIs have the following
27 * All N-API calls return a status code of type `napi_status`. This
28   status indicates whether the API call succeeded or failed.
29 * The API's return value is passed via an out parameter.
36 The N-API is a C API that ensures ABI stability across Node.js versions
37 and different compiler levels. A C++ API can be easier to use.
39 C++ wrapper module called [`node-addon-api`][].
40 This wrapper provides an inlineable C++ API. Binaries built
41 with `node-addon-api` will depend on the symbols for the N-API C-based
42 functions exported by Node.js. `node-addon-api` is a more
43 efficient way to write code that calls N-API. Take, for example, the
44 following `node-addon-api` code. The first section shows the
45 `node-addon-api` code and the second section shows what actually gets
76 it still gets the benefits of the ABI stability provided by the C API.
78 When using `node-addon-api` instead of the C APIs, start with the API [docs][]
79 for `node-addon-api`.
81 The [N-API Resource](https://nodejs.github.io/node-addon-examples/) offers an
82 excellent orientation and tips for developers just getting started with N-API
83 and `node-addon-api`.
87 Although N-API provides an ABI stability guarantee, other parts of Node.js do
92 * the Node.js C++ APIs available via any of
95     #include <node.h>
101 * the libuv APIs which are also included with Node.js and available via
107 * the V8 API available via
113 Thus, for an addon to remain ABI-compatible across Node.js major versions, it
114 must use N-API exclusively by restricting itself to using
121 library makes ABI stability guarantees similar to N-API.
125 Unlike modules written in JavaScript, developing and deploying Node.js
126 native addons using N-API requires an additional set of tools. Besides the
127 basic tools required to develop for Node.js, the native addon developer
133 available. [GCC][] is widely used in the Node.js community to build and
142 xcode-select --install
150 npm install --global windows-build-tools
154 and deploying Node.js native addons.
162 #### node-gyp
164 [node-gyp][] is a build system based on Google's [GYP][] tool and comes
165 bundled with npm. GYP, and therefore node-gyp, requires that Python be
168 Historically, node-gyp has been the tool of choice for building native
170 developers have run into limitations in node-gyp.
177 developers affected by limitations in node-gyp.
188 #### node-pre-gyp
190 [node-pre-gyp][] is a tool based on node-gyp that adds the ability to
191 upload binaries to a server of the developer's choice. node-pre-gyp has
196 [prebuild][] is a tool that supports builds using either node-gyp or
197 CMake.js. Unlike node-pre-gyp which supports a variety of servers, prebuild
203 [prebuildify][] is a tool based on node-gyp. The advantage of prebuildify is
210 In order to use the N-API functions, include the file [`node_api.h`][] which is
211 located in the src directory in the node development tree:
217 This will opt into the default `NAPI_VERSION` for the given release of Node.js.
218 In order to ensure compatibility with specific versions of N-API, the version
226 This restricts the N-API surface to just the functionality that was available in
229 Some of the N-API surface is experimental and requires explicit opt-in:
236 In this case the entire API surface, including any experimental APIs, will be
239 ## N-API version matrix
241 N-API versions are additive and versioned independently from Node.js.
244 to recompile for new versions of Node.js which are
248 |-------|---------|----------|----------|----------|-----------|-----------|
258 \* Indicates that the N-API version was released as experimental
260 Each API documented for N-API will have a header named `added in:`, and APIs
261 which are stable will have the additional header `N-API version:`.
262 APIs are directly usable when using a Node.js version which supports
263 the N-API version shown in `N-API version:` or higher.
264 When using a Node.js version that does not support the
265 `N-API version:` listed or if there is no `N-API version:` listed,
266 then the API will only be available if
268 or `js_native_api.h`. If an API appears not to be available on
269 a version of Node.js which is later than the one shown in `added in:` then
272 The N-APIs associated strictly with accessing ECMAScript features from native
276 implementations of N-API outside of Node.js. For those implementations the
277 Node.js specific APIs may not be applicable.
279 The Node.js-specific parts of an addon can be separated from the code that
281 latter may be used with multiple implementations of N-API. In the example below,
283 `addon.c` can be reused to compile against either the Node.js implementation of
284 N-API or any implementation of N-API outside of Node.js.
286 `addon_node.c` is a separate file that contains the Node.js specific entry point
288 addon is loaded into a Node.js environment.
312         const char* message = (error_info->error_message == NULL) \
314             : error_info->error_message;                          \
364 of an "Agent" as a self-contained environment in which JavaScript code runs.
368 A Node.js environment corresponds to an ECMAScript Agent. In the main process,
370 on separate threads to serve as [worker threads][]. When Node.js is embedded in
372 destroy a Node.js environment multiple times during the life cycle of the
373 application process such that each Node.js environment created by the
385 To this end, N-API provides a way to allocate data such that its life cycle is
389 <!-- YAML
392 -->
401 * `[in] env`: The environment that the N-API call is invoked under.
409 Returns `napi_ok` if the API succeeded.
411 This API associates `data` with the currently running Agent. `data` can later
418 <!-- YAML
421 -->
428 * `[in] env`: The environment that the N-API call is invoked under.
432 Returns `napi_ok` if the API succeeded.
434 This API retrieves data that was previously associated with the currently
438 ## Basic N-API data types
440 N-API exposes the following fundamental datatypes as abstractions that are
442 introspectable only with other N-API calls.
445 <!-- YAML
448 -->
449 Integral status code indicating the success or failure of a N-API call.
478 If additional information is required upon an API returning a failed status,
482 <!-- YAML
485 -->
496 * `error_message`: UTF8-encoded string containing a VM-neutral description of
498 * `engine_reserved`: Reserved for VM-specific error details. This is currently
500 * `engine_error_code`: VM-specific error code. This is currently
502 * `error_code`: The N-API status code that originated with the last error.
508 `napi_env` is used to represent a context that the underlying N-API
509 implementation can use to persist VM-specific state. This structure is passed
511 making N-API calls. Specifically, the same `napi_env` that was passed in when
513 nested N-API calls. Caching the `napi_env` for the purpose of general reuse,
525 <!-- YAML
528 -->
535 <!-- YAML
538 -->
541 the thread-safe function is to be closed immediately (`napi_tsfn_abort`) or
553 <!-- YAML
556 -->
559 the call should block whenever the queue associated with the thread-safe
569 ### N-API memory management types
573 created within a particular scope. In general, N-API values are created within
576 create a new handle scope, N-API values will be created in the default handle
590 <!-- YAML
593 -->
598 <!-- YAML
601 -->
609 <!-- YAML
611 -->
613 A 128-bit value stored as two unsigned 64-bit integers. It serves as a UUID
617 manipulated. Type-tagging is most useful in conjunction with [`napi_wrap`][]
630 <!-- YAML
632 -->
638 ### N-API callback types
641 <!-- YAML
644 -->
650 <!-- YAML
653 -->
654 Function pointer type for user-provided native functions which are to be
655 exposed to JavaScript via N-API. Callback functions should satisfy the
666 <!-- YAML
669 -->
670 Function pointer type for add-on provided functions that allow the user to be
671 notified when externally-owned data is ready to be cleaned up because the
672 object with which it was associated with, has been garbage-collected. The user
687 <!-- YAML
690 -->
698 Implementations of this function must avoid making N-API calls that execute
699 JavaScript or interact with JavaScript objects. N-API calls should be in the
704 <!-- YAML
707 -->
721 <!-- YAML
724 -->
726 Function pointer used with asynchronous thread-safe function calls. The callback
736 N-API sets up the environment prior to calling this callback, so it is
749 * `[in] env`: The environment to use for API calls, or `NULL` if the thread-safe
752   thread-safe function is being torn down and `data` may need to be freed. It
753   may also be `NULL` if the thread-safe function was created without
755 * `[in] context`: The optional data with which the thread-safe function was
758   the callback to convert this native data to JavaScript values (with N-API
767 <!-- YAML
769 -->
792 N-API uses both return values and JavaScript exceptions for error handling.
797 All of the N-API functions share the same error handling pattern. The
798 return type of all API functions is `napi_status`.
814 The `napi_status` return value provides a VM-independent representation of
817 VM (engine)-specific information.
823 <!-- YAML
826 -->
840 * `error_code`: n-api status code for the last error.
843 N-API call that was made.
850 <!-- YAML
853 -->
861 * `[in] env`: The environment that the API is invoked under.
865 Returns `napi_ok` if the API succeeded.
867 This API retrieves a `napi_extended_error_info` structure with information
871 an n-api function is called on the same `env`.
877 This API can be called even if there is a pending JavaScript exception.
881 Any N-API function call may result in a pending JavaScript exception. This is
882 the case for any of the API functions, even those that may not cause the
892 In many cases when an N-API function is called and an exception is
895 for all functions. N-API allows a subset of the functions to be
906 code where the native method was invoked. The behavior of most N-API calls
919 it can be re-thrown it with [`napi_throw`][] where error is the
934 The Node.js project is adding error codes to all of the errors
939 SemVer applying. In order to support this model with N-API, both
960 <!-- YAML
963 -->
969 * `[in] env`: The environment that the API is invoked under.
972 Returns `napi_ok` if the API succeeded.
974 This API throws the JavaScript value provided.
977 <!-- YAML
980 -->
988 * `[in] env`: The environment that the API is invoked under.
992 Returns `napi_ok` if the API succeeded.
994 This API throws a JavaScript `Error` with the text provided.
997 <!-- YAML
1000 -->
1008 * `[in] env`: The environment that the API is invoked under.
1012 Returns `napi_ok` if the API succeeded.
1014 This API throws a JavaScript `TypeError` with the text provided.
1017 <!-- YAML
1020 -->
1028 * `[in] env`: The environment that the API is invoked under.
1032 Returns `napi_ok` if the API succeeded.
1034 This API throws a JavaScript `RangeError` with the text provided.
1037 <!-- YAML
1040 -->
1048 * `[in] env`: The environment that the API is invoked under.
1053 Returns `napi_ok` if the API succeeded.
1055 This API queries a `napi_value` to check if it represents an error object.
1058 <!-- YAML
1061 -->
1070 * `[in] env`: The environment that the API is invoked under.
1077 Returns `napi_ok` if the API succeeded.
1079 This API returns a JavaScript `Error` with the text provided.
1082 <!-- YAML
1085 -->
1094 * `[in] env`: The environment that the API is invoked under.
1101 Returns `napi_ok` if the API succeeded.
1103 This API returns a JavaScript `TypeError` with the text provided.
1106 <!-- YAML
1109 -->
1118 * `[in] env`: The environment that the API is invoked under.
1125 Returns `napi_ok` if the API succeeded.
1127 This API returns a JavaScript `RangeError` with the text provided.
1130 <!-- YAML
1133 -->
1140 * `[in] env`: The environment that the API is invoked under.
1143 Returns `napi_ok` if the API succeeded.
1145 This API can be called even if there is a pending JavaScript exception.
1148 <!-- YAML
1151 -->
1157 * `[in] env`: The environment that the API is invoked under.
1160 Returns `napi_ok` if the API succeeded.
1162 This API can be called even if there is a pending JavaScript exception.
1165 <!-- YAML
1168 -->
1174 * `[in] env`: The environment that the API is invoked under.
1186 <!-- YAML
1189 -->
1200   `NAPI_AUTO_LENGTH` if it is null-terminated.
1203   if it is null-terminated.
1207 This API can be called even if there is a pending JavaScript exception.
1211 As N-API calls are made, handles to objects in the heap for the underlying
1225 The sections which follow describe the N-API functions that can be used
1249 To handle this case, N-API provides the ability to establish a new 'scope' to
1255 N-API only supports a single nested hierarchy of scopes. There is only one
1286 inner scope needs to live beyond the lifespan of that scope. N-API supports an
1300 <!-- YAML
1303 -->
1310 * `[in] env`: The environment that the API is invoked under.
1313 Returns `napi_ok` if the API succeeded.
1315 This API opens a new scope.
1318 <!-- YAML
1321 -->
1328 * `[in] env`: The environment that the API is invoked under.
1331 Returns `napi_ok` if the API succeeded.
1333 This API closes the scope passed in. Scopes must be closed in the
1336 This API can be called even if there is a pending JavaScript exception.
1339 <!-- YAML
1342 -->
1350 * `[in] env`: The environment that the API is invoked under.
1353 Returns `napi_ok` if the API succeeded.
1355 This API opens a new scope from which one object can be promoted
1359 <!-- YAML
1362 -->
1370 * `[in] env`: The environment that the API is invoked under.
1373 Returns `napi_ok` if the API succeeded.
1375 This API closes the scope passed in. Scopes must be closed in the
1378 This API can be called even if there is a pending JavaScript exception.
1381 <!-- YAML
1384 -->
1393 * `[in] env`: The environment that the API is invoked under.
1400 Returns `napi_ok` if the API succeeded.
1402 This API promotes the handle to the JavaScript object so that it is valid
1406 This API can be called even if there is a pending JavaScript exception.
1420 N-API provides methods to create persistent references to an object.
1448 <!-- YAML
1451 -->
1460 * `[in] env`: The environment that the API is invoked under.
1466 Returns `napi_ok` if the API succeeded.
1468 This API create a new reference with the specified reference count
1472 <!-- YAML
1475 -->
1481 * `[in] env`: The environment that the API is invoked under.
1484 Returns `napi_ok` if the API succeeded.
1486 This API deletes the reference passed in.
1488 This API can be called even if there is a pending JavaScript exception.
1491 <!-- YAML
1494 -->
1502 * `[in] env`: The environment that the API is invoked under.
1506 Returns `napi_ok` if the API succeeded.
1508 This API increments the reference count for the reference
1512 <!-- YAML
1515 -->
1523 * `[in] env`: The environment that the API is invoked under.
1527 Returns `napi_ok` if the API succeeded.
1529 This API decrements the reference count for the reference
1533 <!-- YAML
1536 -->
1547 * `[in] env`: The environment that the API is invoked under.
1552 Returns `napi_ok` if the API succeeded.
1554 If still valid, this API returns the `napi_value` representing the
1558 ### Cleanup on exit of the current Node.js instance
1560 While a Node.js process typically releases all its resources when exiting,
1561 embedders of Node.js, or future Worker support, may require addons to register
1562 clean-up hooks that will be run once the current Node.js instance exits.
1564 N-API provides functions for registering and un-registering such callbacks.
1569 <!-- YAML
1572 -->
1581 current Node.js environment exits.
1598 <!-- YAML
1601 -->
1610 current Node.js environment exits. Both the argument and the function value
1617 <!-- YAML
1620   - version: v12.19.0
1621     pr-url: https://github.com/nodejs/node/pull/34819
1623 -->
1625 > Stability: 1 - Experimental
1635 * `[in] env`: The environment that the API is invoked under.
1643 current Node.js environment exits.
1656 <!-- YAML
1659   - version: v12.19.0
1660     pr-url: https://github.com/nodejs/node/pull/34819
1662 -->
1664 > Stability: 1 - Experimental
1680 N-API modules are registered in a manner similar to other modules
1688 The next difference is the signature for the `Init` method. For a N-API
1698 exported by the module. N-API modules cannot modify the `module` object but can
1763 If the module will be loaded multiple times during the lifetime of the Node.js
1782 special name and with visibility beyond the addon. This will allow Node.js to
1786 multiple times. The documentation of [context-aware addons][] provides more
1796 API.
1799 N-API exposes a set of APIs to create all types of JavaScript values.
1806 2. Convert from a primitive C type to an N-API value
1807 3. Convert from N-API value to a primitive C type
1810 N-API values are represented by the type `napi_value`.
1811 Any N-API call that requires a JavaScript value takes in a `napi_value`.
1812 In some cases, the API does check the type of the `napi_value` up-front.
1814 the `napi_value` in question is of the JavaScript type expected by the API.
1818 <!-- YAML
1821 -->
1839 <!-- YAML
1842 -->
1858 <!-- YAML
1861 -->
1924 <!-- YAML
1927 -->
1933 * `[in] env`: The environment that the N-API call is invoked under.
1936 Returns `napi_ok` if the API succeeded.
1938 This API returns an N-API value corresponding to a JavaScript `Array` type.
1943 <!-- YAML
1946 -->
1954 * `[in] env`: The environment that the API is invoked under.
1958 Returns `napi_ok` if the API succeeded.
1960 This API returns an N-API value corresponding to a JavaScript `Array` type.
1961 The `Array`'s length property is set to the passed-in length parameter.
1962 However, the underlying buffer is not guaranteed to be pre-allocated by the VM
1972 <!-- YAML
1975 -->
1984 * `[in] env`: The environment that the API is invoked under.
1989 Returns `napi_ok` if the API succeeded.
1991 This API returns an N-API value corresponding to a JavaScript `ArrayBuffer`.
1992 `ArrayBuffer`s are used to represent fixed-length binary data buffers. They are
1993 normally used as a backing-buffer for `TypedArray` objects.
2005 <!-- YAML
2008 -->
2017 * `[in] env`: The environment that the API is invoked under.
2020 * `[out] result`: A `napi_value` representing a `node::Buffer`.
2022 Returns `napi_ok` if the API succeeded.
2024 This API allocates a `node::Buffer` object. While this is still a
2025 fully-supported data structure, in most cases using a `TypedArray` will suffice.
2028 <!-- YAML
2031 -->
2041 * `[in] env`: The environment that the API is invoked under.
2046 * `[out] result`: A `napi_value` representing a `node::Buffer`.
2048 Returns `napi_ok` if the API succeeded.
2050 This API allocates a `node::Buffer` object and initializes it with data copied
2051 from the passed-in buffer. While this is still a fully-supported data
2055 <!-- YAML
2058 -->
2066 * `[in] env`: The environment that the API is invoked under.
2070 Returns `napi_ok` if the API succeeded.
2072 This API does not observe leap seconds; they are ignored, as
2075 This API allocates a JavaScript `Date` object.
2081 <!-- YAML
2084 -->
2094 * `[in] env`: The environment that the API is invoked under.
2102 Returns `napi_ok` if the API succeeded.
2104 This API allocates a JavaScript value with external data attached to it. This
2108 The API adds a `napi_finalize` callback which will be called when the JavaScript
2114 * the object created by the API can be used with `napi_wrap()`.
2121 <!-- YAML
2124 -->
2136 * `[in] env`: The environment that the API is invoked under.
2146 Returns `napi_ok` if the API succeeded.
2148 This API returns an N-API value corresponding to a JavaScript `ArrayBuffer`.
2153 The API adds a `napi_finalize` callback which will be called when the JavaScript
2159 * the object created by the API can be used with `napi_wrap()`.
2165 <!-- YAML
2168 -->
2179 * `[in] env`: The environment that the API is invoked under.
2187 * `[out] result`: A `napi_value` representing a `node::Buffer`.
2189 Returns `napi_ok` if the API succeeded.
2191 This API allocates a `node::Buffer` object and initializes it with data
2192 backed by the passed in buffer. While this is still a fully-supported data
2195 The API adds a `napi_finalize` callback which will be called when the JavaScript
2201 * the object created by the API can be used with `napi_wrap()`.
2203 For Node.js >=4 `Buffers` are `Uint8Array`s.
2206 <!-- YAML
2209 -->
2215 * `[in] env`: The environment that the API is invoked under.
2218 Returns `napi_ok` if the API succeeded.
2220 This API allocates a default JavaScript `Object`.
2227 <!-- YAML
2230 -->
2238 * `[in] env`: The environment that the API is invoked under.
2243 Returns `napi_ok` if the API succeeded.
2245 This API creates a JavaScript `Symbol` object from a UTF8-encoded C string.
2251 <!-- YAML
2254 -->
2265 * `[in] env`: The environment that the API is invoked under.
2273 Returns `napi_ok` if the API succeeded.
2275 This API creates a JavaScript `TypedArray` object over an existing
2276 `ArrayBuffer`. `TypedArray` objects provide an array-like view over an
2288 <!-- YAML
2291 -->
2301 * `[in] env`: The environment that the API is invoked under.
2308 Returns `napi_ok` if the API succeeded.
2310 This API creates a JavaScript `DataView` object over an existing `ArrayBuffer`.
2311 `DataView` objects provide an array-like view over an underlying data buffer,
2321 ### Functions to convert from C types to N-API
2323 <!-- YAML
2326 -->
2332 * `[in] env`: The environment that the API is invoked under.
2336 Returns `napi_ok` if the API succeeded.
2338 This API is used to convert from the C `int32_t` type to the JavaScript
2345 <!-- YAML
2348 -->
2354 * `[in] env`: The environment that the API is invoked under.
2358 Returns `napi_ok` if the API succeeded.
2360 This API is used to convert from the C `uint32_t` type to the JavaScript
2367 <!-- YAML
2370 -->
2376 * `[in] env`: The environment that the API is invoked under.
2380 Returns `napi_ok` if the API succeeded.
2382 This API is used to convert from the C `int64_t` type to the JavaScript
2388 outside the range of [`Number.MIN_SAFE_INTEGER`][] `-(2**53 - 1)` -
2389 [`Number.MAX_SAFE_INTEGER`][] `(2**53 - 1)` will lose precision.
2392 <!-- YAML
2395 -->
2401 * `[in] env`: The environment that the API is invoked under.
2402 * `[in] value`: Double-precision value to be represented in JavaScript.
2405 Returns `napi_ok` if the API succeeded.
2407 This API is used to convert from the C `double` type to the JavaScript
2414 <!-- YAML
2417 -->
2425 * `[in] env`: The environment that the API is invoked under.
2429 Returns `napi_ok` if the API succeeded.
2431 This API converts the C `int64_t` type to the JavaScript `BigInt` type.
2434 <!-- YAML
2437 -->
2445 * `[in] env`: The environment that the API is invoked under.
2449 Returns `napi_ok` if the API succeeded.
2451 This API converts the C `uint64_t` type to the JavaScript `BigInt` type.
2454 <!-- YAML
2457 -->
2467 * `[in] env`: The environment that the API is invoked under.
2471 * `[in] words`: An array of `uint64_t` little-endian 64-bit words.
2474 Returns `napi_ok` if the API succeeded.
2476 This API converts an array of unsigned 64-bit words into a single `BigInt`
2483 <!-- YAML
2486 -->
2495 * `[in] env`: The environment that the API is invoked under.
2496 * `[in] str`: Character buffer representing an ISO-8859-1-encoded string.
2498   is null-terminated.
2501 Returns `napi_ok` if the API succeeded.
2503 This API creates a JavaScript `String` object from an ISO-8859-1-encoded C
2510 <!-- YAML
2513 -->
2522 * `[in] env`: The environment that the API is invoked under.
2523 * `[in] str`: Character buffer representing a UTF16-LE-encoded string.
2524 * `[in] length`: The length of the string in two-byte code units, or
2525   `NAPI_AUTO_LENGTH` if it is null-terminated.
2528 Returns `napi_ok` if the API succeeded.
2530 This API creates a JavaScript `String` object from a UTF16-LE-encoded C string.
2537 <!-- YAML
2540 -->
2549 * `[in] env`: The environment that the API is invoked under.
2550 * `[in] str`: Character buffer representing a UTF8-encoded string.
2552   is null-terminated.
2555 Returns `napi_ok` if the API succeeded.
2557 This API creates a JavaScript `String` object from a UTF8-encoded C string.
2563 ### Functions to convert from N-API to C types
2565 <!-- YAML
2568 -->
2576 * `[in] env`: The environment that the API is invoked under.
2581 Returns `napi_ok` if the API succeeded.
2583 This API returns the length of an array.
2589 <!-- YAML
2592 -->
2601 * `[in] env`: The environment that the API is invoked under.
2607 Returns `napi_ok` if the API succeeded.
2609 This API is used to retrieve the underlying data buffer of an `ArrayBuffer` and
2612 *WARNING*: Use caution while using this API. The lifetime of the underlying data
2614 possible safe way to use this API is in conjunction with
2621 <!-- YAML
2624 -->
2633 * `[in] env`: The environment that the API is invoked under.
2634 * `[in] value`: `napi_value` representing the `node::Buffer` being queried.
2635 * `[out] data`: The underlying data buffer of the `node::Buffer`.
2639 Returns `napi_ok` if the API succeeded.
2641 This API is used to retrieve the underlying data buffer of a `node::Buffer`
2644 *Warning*: Use caution while using this API since the underlying data buffer's
2648 <!-- YAML
2651 -->
2659 * `[in] env`: The environment that the API is invoked under.
2665 Returns `napi_ok` if the API succeeded.
2668 <!-- YAML
2671 -->
2683 * `[in] env`: The environment that the API is invoked under.
2697   `data - byte_offset`.
2699 Returns `napi_ok` if the API succeeded.
2701 This API returns various properties of a typed array.
2703 *Warning*: Use caution while using this API since the underlying data buffer
2707 <!-- YAML
2710 -->
2721 * `[in] env`: The environment that the API is invoked under.
2731 Returns `napi_ok` if the API succeeded.
2733 This API returns various properties of a `DataView`.
2736 <!-- YAML
2739 -->
2747 * `[in] env`: The environment that the API is invoked under.
2752 This API does not observe leap seconds; they are ignored, as
2755 Returns `napi_ok` if the API succeeded. If a non-date `napi_value` is passed
2758 This API returns the C double primitive of time value for the given JavaScript
2762 <!-- YAML
2765 -->
2771 * `[in] env`: The environment that the API is invoked under.
2776 Returns `napi_ok` if the API succeeded. If a non-boolean `napi_value` is
2779 This API returns the C boolean primitive equivalent of the given JavaScript
2783 <!-- YAML
2786 -->
2794 * `[in] env`: The environment that the API is invoked under.
2799 Returns `napi_ok` if the API succeeded. If a non-number `napi_value` is passed
2802 This API returns the C double primitive equivalent of the given JavaScript
2806 <!-- YAML
2809 -->
2818 * `[in] env`: The environment that the API is invoked under
2825 Returns `napi_ok` if the API succeeded. If a non-`BigInt` is passed in it
2828 This API returns the C `int64_t` primitive equivalent of the given JavaScript
2832 <!-- YAML
2835 -->
2844 * `[in] env`: The environment that the API is invoked under.
2851 Returns `napi_ok` if the API succeeded. If a non-`BigInt` is passed in it
2854 This API returns the C `uint64_t` primitive equivalent of the given JavaScript
2858 <!-- YAML
2861 -->
2871 * `[in] env`: The environment that the API is invoked under.
2878 * `[out] words`: Pointer to a pre-allocated 64-bit word array.
2880 Returns `napi_ok` if the API succeeded.
2882 This API converts a single `BigInt` value into a sign bit, 64-bit little-endian
2887 <!-- YAML
2890 -->
2898 * `[in] env`: The environment that the API is invoked under.
2902 Returns `napi_ok` if the API succeeded. If a non-external `napi_value` is
2905 This API retrieves the external data pointer that was previously passed to
2909 <!-- YAML
2912 -->
2920 * `[in] env`: The environment that the API is invoked under.
2925 Returns `napi_ok` if the API succeeded. If a non-number `napi_value`
2928 This API returns the C `int32` primitive equivalent
2933 positive number becoming a negative number if the value is > 2<sup>31</sup> - 1.
2935 Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the
2939 <!-- YAML
2942 -->
2950 * `[in] env`: The environment that the API is invoked under.
2955 Returns `napi_ok` if the API succeeded. If a non-number `napi_value`
2958 This API returns the C `int64` primitive equivalent of the given JavaScript
2962 `-(2**53 - 1)` - [`Number.MAX_SAFE_INTEGER`][] `(2**53 - 1)` will lose
2965 Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the
2969 <!-- YAML
2972 -->
2982 * `[in] env`: The environment that the API is invoked under.
2984 * `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If `NULL` is
2991 Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value`
2994 This API returns the ISO-8859-1-encoded string corresponding the value passed
2998 <!-- YAML
3001 -->
3011 * `[in] env`: The environment that the API is invoked under.
3013 * `[in] buf`: Buffer to write the UTF8-encoded string into. If `NULL` is passed
3020 Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value`
3023 This API returns the UTF8-encoded string corresponding the value passed in.
3026 <!-- YAML
3029 -->
3039 * `[in] env`: The environment that the API is invoked under.
3041 * `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If `NULL` is
3042   passed in, the length of the string (in 2-byte code units) is returned.
3045 * `[out] result`: Number of 2-byte code units copied into the buffer, excluding
3048 Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value`
3051 This API returns the UTF16-encoded string corresponding the value passed in.
3054 <!-- YAML
3057 -->
3065 * `[in] env`: The environment that the API is invoked under.
3070 Returns `napi_ok` if the API succeeded. If a non-number `napi_value`
3073 This API returns the C primitive equivalent of the given `napi_value` as a
3078 <!-- YAML
3081 -->
3087 * `[in] env`: The environment that the API is invoked under.
3092 Returns `napi_ok` if the API succeeded.
3094 This API is used to return the JavaScript singleton object that is used to
3098 <!-- YAML
3101 -->
3107 * `[in] env`: The environment that the API is invoked under.
3110 Returns `napi_ok` if the API succeeded.
3112 This API returns the `global` object.
3115 <!-- YAML
3118 -->
3124 * `[in] env`: The environment that the API is invoked under.
3127 Returns `napi_ok` if the API succeeded.
3129 This API returns the `null` object.
3132 <!-- YAML
3135 -->
3141 * `[in] env`: The environment that the API is invoked under.
3144 Returns `napi_ok` if the API succeeded.
3146 This API returns the Undefined object.
3150 N-API exposes a set of APIs to perform some abstract operations on JavaScript
3162 <!-- YAML
3165 -->
3173 * `[in] env`: The environment that the API is invoked under.
3177 Returns `napi_ok` if the API succeeded.
3179 This API implements the abstract operation `ToBoolean()` as defined in
3181 This API can be re-entrant if getters are defined on the passed-in `Object`.
3184 <!-- YAML
3187 -->
3195 * `[in] env`: The environment that the API is invoked under.
3199 Returns `napi_ok` if the API succeeded.
3201 This API implements the abstract operation `ToNumber()` as defined in
3203 This API can be re-entrant if getters are defined on the passed-in `Object`.
3206 <!-- YAML
3209 -->
3217 * `[in] env`: The environment that the API is invoked under.
3221 Returns `napi_ok` if the API succeeded.
3223 This API implements the abstract operation `ToObject()` as defined in
3225 This API can be re-entrant if getters are defined on the passed-in `Object`.
3228 <!-- YAML
3231 -->
3239 * `[in] env`: The environment that the API is invoked under.
3243 Returns `napi_ok` if the API succeeded.
3245 This API implements the abstract operation `ToString()` as defined in
3247 This API can be re-entrant if getters are defined on the passed-in `Object`.
3250 <!-- YAML
3253 -->
3259 * `[in] env`: The environment that the API is invoked under.
3263 Returns `napi_ok` if the API succeeded.
3268 This API represents behavior similar to invoking the `typeof` Operator on
3279 <!-- YAML
3282 -->
3291 * `[in] env`: The environment that the API is invoked under.
3298 Returns `napi_ok` if the API succeeded.
3300 This API represents invoking the `instanceof` Operator on the object as
3304 <!-- YAML
3307 -->
3313 * `[in] env`: The environment that the API is invoked under.
3317 Returns `napi_ok` if the API succeeded.
3319 This API represents invoking the `IsArray` operation on the object
3323 <!-- YAML
3326 -->
3332 * `[in] env`: The environment that the API is invoked under.
3336 Returns `napi_ok` if the API succeeded.
3338 This API checks if the `Object` passed in is an array buffer.
3341 <!-- YAML
3344 -->
3350 * `[in] env`: The environment that the API is invoked under.
3352 * `[out] result`: Whether the given `napi_value` represents a `node::Buffer`
3355 Returns `napi_ok` if the API succeeded.
3357 This API checks if the `Object` passed in is a buffer.
3360 <!-- YAML
3363 -->
3369 * `[in] env`: The environment that the API is invoked under.
3374 Returns `napi_ok` if the API succeeded.
3376 This API checks if the `Object` passed in is a date.
3379 <!-- YAML
3382 -->
3388 * `[in] env`: The environment that the API is invoked under.
3392 Returns `napi_ok` if the API succeeded.
3394 This API checks if the `Object` passed in is an `Error`.
3397 <!-- YAML
3400 -->
3406 * `[in] env`: The environment that the API is invoked under.
3410 Returns `napi_ok` if the API succeeded.
3412 This API checks if the `Object` passed in is a typed array.
3415 <!-- YAML
3418 -->
3424 * `[in] env`: The environment that the API is invoked under.
3428 Returns `napi_ok` if the API succeeded.
3430 This API checks if the `Object` passed in is a `DataView`.
3433 <!-- YAML
3436 -->
3445 * `[in] env`: The environment that the API is invoked under.
3450 Returns `napi_ok` if the API succeeded.
3452 This API represents the invocation of the Strict Equality algorithm as
3456 <!-- YAML
3459 -->
3466 * `[in] env`: The environment that the API is invoked under.
3469 Returns `napi_ok` if the API succeeded. If a non-detachable `ArrayBuffer` is
3472 Generally, an `ArrayBuffer` is non-detachable if it has been detached before.
3477 This API represents the invocation of the `ArrayBuffer` detach operation as
3481 <!-- YAML
3484 -->
3492 * `[in] env`: The environment that the API is invoked under.
3496 Returns `napi_ok` if the API succeeded.
3500 This API represents the invocation of the `ArrayBuffer` `IsDetachedBuffer`
3506 N-API exposes a set of APIs to get and set properties on JavaScript
3511 Fundamentally, all property keys in N-API can be represented in one of the
3514 * Named: a simple UTF8-encoded string
3515 * Integer-Indexed: an index value represented by `uint32_t`
3516 * JavaScript value: these are represented in N-API by `napi_value`. This can
3519 N-API values are represented by the type `napi_value`.
3520 Any N-API call that requires a JavaScript value takes in a `napi_value`.
3522 `napi_value` in question is of the JavaScript type expected by the API.
3535 The equivalent can be done using N-API values with the following snippet:
3562 The equivalent can be done using N-API values with the following snippet:
3589 The following is the approximate equivalent of the N-API counterpart:
3615 The following is the approximate equivalent of the N-API counterpart:
3646 <!-- YAML
3648  - version: v12.20.0
3649    pr-url: https://github.com/nodejs/node/pull/35214
3651 -->
3725   performed using a N-API call). [`napi_callback`][] provides more details.
3730   performed using a N-API call). [`napi_callback`][] provides more details.
3742 <!-- YAML
3745 -->
3753 * `[in] env`: The environment that the N-API call is invoked under.
3756   that represent the property names of the object. The API can be used to
3760 Returns `napi_ok` if the API succeeded.
3762 This API returns the names of the enumerable properties of `object` as an array
3767 <!-- YAML
3770 -->
3781 * `[in] env`: The environment that the N-API call is invoked under.
3791 Returns `napi_ok` if the API succeeded.
3793 This API returns an array containing the names of the available properties
3797 <!-- YAML
3800 -->
3809 * `[in] env`: The environment that the N-API call is invoked under.
3814 Returns `napi_ok` if the API succeeded.
3816 This API set a property on the `Object` passed in.
3819 <!-- YAML
3822 -->
3831 * `[in] env`: The environment that the N-API call is invoked under.
3836 Returns `napi_ok` if the API succeeded.
3838 This API gets the requested property from the `Object` passed in.
3841 <!-- YAML
3844 -->
3853 * `[in] env`: The environment that the N-API call is invoked under.
3858 Returns `napi_ok` if the API succeeded.
3860 This API checks if the `Object` passed in has the named property.
3863 <!-- YAML
3866 -->
3875 * `[in] env`: The environment that the N-API call is invoked under.
3881 Returns `napi_ok` if the API succeeded.
3883 This API attempts to delete the `key` own property from `object`.
3886 <!-- YAML
3889 -->
3898 * `[in] env`: The environment that the N-API call is invoked under.
3903 Returns `napi_ok` if the API succeeded.
3905 This API checks if the `Object` passed in has the named own property. `key` must
3906 be a string or a `Symbol`, or an error will be thrown. N-API will not perform
3910 <!-- YAML
3913 -->
3922 * `[in] env`: The environment that the N-API call is invoked under.
3927 Returns `napi_ok` if the API succeeded.
3933 <!-- YAML
3936 -->
3945 * `[in] env`: The environment that the N-API call is invoked under.
3950 Returns `napi_ok` if the API succeeded.
3956 <!-- YAML
3959 -->
3968 * `[in] env`: The environment that the N-API call is invoked under.
3973 Returns `napi_ok` if the API succeeded.
3979 <!-- YAML
3982 -->
3991 * `[in] env`: The environment that the N-API call is invoked under.
3996 Returns `napi_ok` if the API succeeded.
3998 This API sets and element on the `Object` passed in.
4001 <!-- YAML
4004 -->
4013 * `[in] env`: The environment that the N-API call is invoked under.
4018 Returns `napi_ok` if the API succeeded.
4020 This API gets the element at the requested index.
4023 <!-- YAML
4026 -->
4035 * `[in] env`: The environment that the N-API call is invoked under.
4040 Returns `napi_ok` if the API succeeded.
4042 This API returns if the `Object` passed in has an element at the
4046 <!-- YAML
4049 -->
4058 * `[in] env`: The environment that the N-API call is invoked under.
4064 Returns `napi_ok` if the API succeeded.
4066 This API attempts to delete the specified `index` from `object`.
4069 <!-- YAML
4072 -->
4081 * `[in] env`: The environment that the N-API call is invoked under.
4086 Returns `napi_ok` if the API succeeded.
4091 this API will set the properties on the object one at a time, as defined by
4092 `DefineOwnProperty()` (described in [Section 9.1.6][] of the ECMA-262
4096 <!-- YAML
4098 -->
4100 > Stability: 1 - Experimental
4107 * `[in] env`: The environment that the N-API call is invoked under.
4110 Returns `napi_ok` if the API succeeded.
4117 in [Section 19.1.2.6](https://tc39.es/ecma262/#sec-object.freeze) of the
4118 ECMA-262 specification.
4121 <!-- YAML
4123 -->
4125 > Stability: 1 - Experimental
4132 * `[in] env`: The environment that the N-API call is invoked under.
4135 Returns `napi_ok` if the API succeeded.
4138 added to it, as well as marking all existing properties as non-configurable.
4139 This is described in [Section 19.1.2.20](https://tc39.es/ecma262/#sec-object.seal)
4140 of the ECMA-262 specification.
4144 N-API provides a set of APIs that allow JavaScript code to
4145 call back into native code. N-API APIs that support calling back
4156 Additionally, N-API provides a set of functions which allow calling
4161 Any non-`NULL` data which is passed to this API via the `data` field of the
4163 whenever `object` is garbage-collected by passing both `object` and the data to
4167 <!-- YAML
4170 -->
4181 * `[in] env`: The environment that the API is invoked under.
4189 Returns `napi_ok` if the API succeeded.
4192 add-on. This is the primary mechanism of calling back *from* the add-on's
4205 Then, the above function can be invoked from a native add-on using the
4236 <!-- YAML
4239 -->
4250 * `[in] env`: The environment that the API is invoked under.
4254   it is null-terminated.
4257 * `[in] data`: User-provided data context. This will be passed back into the
4262 Returns `napi_ok` if the API succeeded.
4264 This API allows an add-on author to create a function object in native code.
4265 This is the primary mechanism to allow calling *into* the add-on's native code
4273 add-on's module exports, set the newly created function on the exports
4298 Given the above code, the add-on can be used from JavaScript as follows:
4306 responsible for creating the `.node` file.
4308 Any non-`NULL` data which is passed to this API via the `data` parameter can
4310 `result` parameter) and freed whenever the function is garbage-collected by
4317 <!-- YAML
4320 -->
4331 * `[in] env`: The environment that the API is invoked under.
4333 * `[in-out] argc`: Specifies the size of the provided `argv` array and receives
4343 Returns `napi_ok` if the API succeeded.
4349 <!-- YAML
4352 -->
4360 * `[in] env`: The environment that the API is invoked under.
4364 Returns `napi_ok` if the API succeeded.
4366 This API returns the `new.target` of the constructor call. If the current
4370 <!-- YAML
4373 -->
4383 * `[in] env`: The environment that the API is invoked under.
4405 The following can be approximated in N-API using the following snippet:
4427 Returns `napi_ok` if the API succeeded.
4431 N-API offers a way to "wrap" C++ classes and instances so that the class
4434 1. The [`napi_define_class`][] API defines a JavaScript class with constructor,
4473 const myAddon = require('./build/Release/my_addon.node');
4484 // the query handle (`query`), so the correct condition for the while-loop
4518 To this end, N-API provides type-tagging capabilities.
4520 A type tag is a 128-bit integer unique to the addon. N-API provides the
4527 previously "marked" with the type tag. This creates a type-checking capability
4528 of a higher fidelity than `napi_instanceof()` can provide, because such type-
4538 //   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
4604 <!-- YAML
4607 -->
4620 * `[in] env`: The environment that the API is invoked under.
4625   if it is null-terminated.
4638 Returns `napi_ok` if the API succeeded.
4648   _non-static_ data properties, accessors, and methods of the C++ class
4658 case, to prevent the function value from being garbage-collected, create a
4662 Any non-`NULL` data which is passed to this API via the `data` parameter or via
4665 parameter) and freed whenever the class is garbage-collected by passing both
4669 <!-- YAML
4672 -->
4683 * `[in] env`: The environment that the API is invoked under.
4689   native instance when the JavaScript object is ready for garbage-collection.
4695 Returns `napi_ok` if the API succeeded.
4703 `napi_wrap()` to wrap the newly constructed instance in the already-created
4727 <!-- YAML
4730 -->
4738 * `[in] env`: The environment that the API is invoked under.
4742 Returns `napi_ok` if the API succeeded.
4754 <!-- YAML
4757 -->
4765 * `[in] env`: The environment that the API is invoked under.
4769 Returns `napi_ok` if the API succeeded.
4774 JavaScript object becomes garbage-collected.
4777 <!-- YAML
4779 -->
4781 > Stability: 1 - Experimental
4789 * `[in] env`: The environment that the API is invoked under.
4793 Returns `napi_ok` if the API succeeded.
4800 If the object already has an associated type tag, this API will return
4804 <!-- YAML
4806 -->
4808 > Stability: 1 - Experimental
4817 * `[in] env`: The environment that the API is invoked under.
4823 Returns `napi_ok` if the API succeeded.
4832 <!-- YAML
4835 -->
4846 * `[in] env`: The environment that the API is invoked under.
4852   native data when the JavaScript object is ready for garbage-collection.
4858 Returns `napi_ok` if the API succeeded.
4861 in `js_object` is ready for garbage collection. This API is similar to
4866 * the API can be called multiple times with different data items in order to
4868 * the object manipulated by the API can be used with `napi_wrap()`.
4881 allows them to avoid blocking overall execution of the Node.js application.
4883 N-API provides an ABI-stable interface for these
4886 N-API defines the `napi_async_work` structure which is used to manage
4894 The `execute` function should avoid making any N-API calls
4896 JavaScript objects. Most often, any code that needs to make N-API
4912 addon-provided `void*` data that was passed into the
4932 <!-- YAML
4936   - version: v8.6.0
4937     pr-url: https://github.com/nodejs/node/pull/14697
4939 -->
4951 * `[in] env`: The environment that the API is invoked under.
4955   provided for diagnostic information exposed by the `async_hooks` API.
4963 * `[in] data`: User-provided data context. This will be passed back into the
4968 Returns `napi_ok` if the API succeeded.
4970 This API allocates a work object that is used to execute logic asynchronously.
4974 `async_resource_name` should be a null-terminated, UTF-8-encoded string.
4982 <!-- YAML
4985 -->
4992 * `[in] env`: The environment that the API is invoked under.
4995 Returns `napi_ok` if the API succeeded.
4997 This API frees a previously allocated work object.
4999 This API can be called even if there is a pending JavaScript exception.
5002 <!-- YAML
5005 -->
5012 * `[in] env`: The environment that the API is invoked under.
5015 Returns `napi_ok` if the API succeeded.
5017 This API requests that the previously allocated work be scheduled
5018 for execution. Once it returns successfully, this API must not be called again
5022 <!-- YAML
5025 -->
5032 * `[in] env`: The environment that the API is invoked under.
5035 Returns `napi_ok` if the API succeeded.
5037 This API cancels queued work if it has not yet
5044 This API can be called even if there is a pending JavaScript exception.
5054 <!-- YAML
5057 -->
5066 * `[in] env`: The environment that the API is invoked under.
5073   loss of async context when using the AsyncLocalStorage API.
5076   `async_hooks` API.
5079 Returns `napi_ok` if the API succeeded.
5082 <!-- YAML
5085 -->
5092 * `[in] env`: The environment that the API is invoked under.
5095 Returns `napi_ok` if the API succeeded.
5097 This API can be called even if there is a pending JavaScript exception.
5100 <!-- YAML
5104   - version: v8.6.0
5106 -->
5118 * `[in] env`: The environment that the API is invoked under.
5131 Returns `napi_ok` if the API succeeded.
5134 add-on. This API is similar to `napi_call_function`. However, it is used to call
5137 wrapper around `node::MakeCallback`.
5150 <!-- YAML
5153 -->
5162 * `[in] env`: The environment that the API is invoked under.
5171 in place when making certain N-API calls. If there is no other script on
5177 <!-- YAML
5180 -->
5187 * `[in] env`: The environment that the API is invoked under.
5190 This API can be called even if there is a pending JavaScript exception.
5195 <!-- YAML
5198 -->
5212 * `[in] env`: The environment that the API is invoked under.
5213 * `[out] version`: A pointer to version information for Node.js itself.
5215 Returns `napi_ok` if the API succeeded.
5218 version of Node.js that is currently running, and the `release` field with the
5224 <!-- YAML
5227 -->
5234 * `[in] env`: The environment that the API is invoked under.
5235 * `[out] result`: The highest version of N-API supported.
5237 Returns `napi_ok` if the API succeeded.
5239 This API returns the highest N-API version supported by the
5240 Node.js runtime. N-API is planned to be additive such that
5241 newer releases of Node.js may support additional API functions.
5243 versions of Node.js that support it, while providing
5244 fallback behavior when running with Node.js versions that don't
5247 * Call `napi_get_version()` to determine if the API is available.
5256 <!-- YAML
5259 -->
5267 * `[in] env`: The environment that the API is invoked under.
5272 Returns `napi_ok` if the API succeeded.
5282 N-API provides facilities for creating `Promise` objects as described in
5337 <!-- YAML
5340 -->
5348 * `[in] env`: The environment that the API is invoked under.
5354 Returns `napi_ok` if the API succeeded.
5356 This API creates a deferred object and a JavaScript promise.
5359 <!-- YAML
5362 -->
5370 * `[in] env`: The environment that the API is invoked under.
5374 This API resolves a JavaScript promise by way of the deferred object
5379 have been retained in order to be passed to this API.
5384 <!-- YAML
5387 -->
5395 * `[in] env`: The environment that the API is invoked under.
5399 This API rejects a JavaScript promise by way of the deferred object
5404 have been retained in order to be passed to this API.
5409 <!-- YAML
5412 -->
5420 * `[in] env`: The environment that the API is invoked under.
5427 N-API provides an API for executing a string containing JavaScript using the
5431 <!-- YAML
5434 -->
5442 * `[in] env`: The environment that the API is invoked under.
5451   [module scope][], meaning that pseudo-globals such as `require` will not be
5461 N-API provides a function for getting the current event loop associated with
5465 <!-- YAML
5467   - v8.10.0
5468   - v9.3.0
5470 -->
5477 * `[in] env`: The environment that the API is invoked under.
5480 ## Asynchronous thread-safe function calls
5483 thread. If an addon creates additional threads, then N-API functions that
5490 JavaScript function on their behalf. The thread-safe function APIs provide an
5502 provided. This callback will be invoked on the main thread when the thread-safe
5506 no threads should be using the thread-safe function after the finalize callback
5513 ### Calling a thread-safe function
5517 whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API
5518 behaves non-blockingly, returning `napi_queue_full` if the queue was full,
5520 `napi_tsfn_blocking`, the API blocks until space becomes available in the queue.
5521 `napi_call_threadsafe_function()` never blocks if the thread-safe function was
5532 created by one of the secondary threads. The callback can then use an API such
5538 Node.js process exits while there is a thread-safe function still active.
5541 N-API runs `call_js_cb` in a context appropriate for callbacks.
5543 ### Reference counting of thread-safe functions
5548 indicate that a new thread will start making use of the thread-safe function.
5550 existing thread will stop making use of the thread-safe function.
5557 should be the last API call made in conjunction with a given
5560 reason, do not use a thread-safe function
5566 number of aquisitions of the thread-safe functions, instead of calling
5571 `napi_acquire_threadsafe_function()`. In fact, all subsequent API calls
5575 The thread-safe function can be "aborted" by giving a value of `napi_tsfn_abort`
5577 associated with the thread-safe function except
5581 possible to make asynchronous calls to the thread-safe function. This can be
5584 the thread-safe function anymore because it is no longer guaranteed to
5589 Similarly to libuv handles, thread-safe functions can be "referenced" and
5590 "unreferenced". A "referenced" thread-safe function will cause the event loop on
5591 the thread on which it is created to remain alive until the thread-safe function
5592 is destroyed. In contrast, an "unreferenced" thread-safe function will not
5596 Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as
5602 <!-- YAML
5606   - version: v12.6.0
5607     pr-url: https://github.com/nodejs/node/pull/27791
5609 -->
5626 * `[in] env`: The environment that the API is invoked under.
5633   by the `async_hooks` API.
5648 * `[out] result`: The asynchronous thread-safe JavaScript function.
5652 <!-- YAML
5655 -->
5663 * `[in] func`: The thread-safe function for which to retrieve the context.
5666 This API may be called from any thread which makes use of `func`.
5670 <!-- YAML
5673 -->
5682 * `[in] func`: The asynchronous thread-safe JavaScript function to invoke.
5684   provided during the creation of the thread-safe JavaScript function.
5690 This API will return `napi_closing` if `napi_release_threadsafe_function()` was
5692 added to the queue if the API returns `napi_ok`.
5694 This API may be called from any thread which makes use of `func`.
5698 <!-- YAML
5701 -->
5708 * `[in] func`: The asynchronous thread-safe JavaScript function to start making
5711 A thread should call this API before passing `func` to any other thread-safe
5716 This API may be called from any thread which will start making use of `func`.
5720 <!-- YAML
5723 -->
5731 * `[in] func`: The asynchronous thread-safe JavaScript function whose reference
5734   that the current thread will make no further calls to the thread-safe
5736   thread, no other thread should make any further calls to the thread-safe
5741 A thread should call this API when it stops making use of `func`. Passing `func`
5742 to any thread-safe APIs after having called this API has undefined results, as
5745 This API may be called from any thread which will stop making use of `func`.
5749 <!-- YAML
5752 -->
5759 * `[in] env`: The environment that the API is invoked under.
5760 * `[in] func`: The thread-safe function to reference.
5762 This API is used to indicate that the event loop running on the main thread
5766 Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as
5771 This API may only be called from the main thread.
5775 <!-- YAML
5778 -->
5785 * `[in] env`: The environment that the API is invoked under.
5786 * `[in] func`: The thread-safe function to unreference.
5788 This API is used to indicate that the event loop running on the main thread
5792 This API may only be called from the main thread.
5794 [ABI Stability]: https://nodejs.org/en/docs/guides/abi-stability/
5797 [CMake.js]: https://github.com/cmake-js/cmake-js
5803 [GitHub releases]: https://help.github.com/en/github/administering-a-repository/about-releases
5805 [Native Abstractions for Node.js]: https://github.com/nodejs/nan
5808 [Section 12.10.4]: https://tc39.github.io/ecma262/#sec-instanceofoperator
5809 [Section 12.5.5]: https://tc39.github.io/ecma262/#sec-typeof-operator
5810 [Section 19.2]: https://tc39.github.io/ecma262/#sec-function-objects
5811 [Section 19.4]: https://tc39.github.io/ecma262/#sec-symbol-objects
5812 [Section 20.3]: https://tc39.github.io/ecma262/#sec-date-objects
5813 [Section 22.1.4.1]: https://tc39.github.io/ecma262/#sec-properties-of-array-instances-length
5814 [Section 22.1]: https://tc39.github.io/ecma262/#sec-array-objects
5815 [Section 22.2]: https://tc39.github.io/ecma262/#sec-typedarray-objects
5816 [Section 24.1]: https://tc39.github.io/ecma262/#sec-arraybuffer-objects
5817 [Section 24.1.1.3]: https://tc39.es/ecma262/#sec-detacharraybuffer
5818 [Section 24.3]: https://tc39.github.io/ecma262/#sec-dataview-objects
5819 [Section 25.4]: https://tc39.github.io/ecma262/#sec-promise-objects
5820 [Section 6.1.4]: https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type
5821 [Section 6.1.6]: https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type
5822 [Section 6.1.7.1]: https://tc39.github.io/ecma262/#table-2
5823 [Section 6.1.7]: https://tc39.github.io/ecma262/#sec-object-type
5824 [Section 6.1]: https://tc39.github.io/ecma262/#sec-ecmascript-language-types
5825 [Section 6]: https://tc39.github.io/ecma262/#sec-ecmascript-data-types-and-values
5826 [Section 7.1.13]: https://tc39.github.io/ecma262/#sec-toobject
5827 [Section 7.1.2]: https://tc39.github.io/ecma262/#sec-toboolean
5828 [Section 7.1.3]: https://tc39.github.io/ecma262/#sec-tonumber
5829 [Section 7.2.14]: https://tc39.github.io/ecma262/#sec-strict-equality-comparison
5830 [Section 7.2.2]: https://tc39.github.io/ecma262/#sec-isarray
5831 [Section 7]: https://tc39.github.io/ecma262/#sec-abstract-operations
5832 [Section 8.7]: https://tc39.es/ecma262/#sec-agents
5833 ….6]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots-defin…
5834 [Section 24.1.1.2]: https://tc39.es/ecma262/#sec-isdetachedbuffer
5835 [Travis CI]: https://travis-ci.org
5839 [`Number.MAX_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.max_safe_integer
5840 [`Number.MIN_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.min_safe_integer
5897 [`node-addon-api`]: https://github.com/nodejs/node-addon-api
5898 [`node_api.h`]: https://github.com/nodejs/node/blob/master/src/node_api.h
5903 [context-aware addons]: addons.html#addons_context_aware_addons
5904 [docs]: https://github.com/nodejs/node-addon-api#api-documentation
5907 [node-gyp]: https://github.com/nodejs/node-gyp
5908 [node-pre-gyp]: https://github.com/mapbox/node-pre-gyp
5911 [worker threads]: https://nodejs.org/api/worker_threads.html