Napi node

Napi node DEFAULT

node-addon-api module

NOTE: The default branch has been renamed! master is now named main

If you have a local clone, you can update it by running:

git branch -m master main git fetch origin git branch -u origin/main main

This module contains header-only C++ wrapper classes which simplify the use of the C based Node-API provided by Node.js when using C++. It provides a C++ object model and exception handling semantics with low overhead.

There are three options for implementing addons: Node-API, nan, or direct use of internal V8, libuv and Node.js libraries. Unless there is a need for direct access to functionality which is not exposed by Node-API as outlined in C/C++ addons in Node.js core, use Node-API. Refer to C/C++ addons with Node-API for more information on Node-API.

Node-API is an ABI stable C interface provided by Node.js for building native addons. It is independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore) and is maintained as part of Node.js itself. It is intended to insulate native addons from changes in the underlying JavaScript engine and allow modules compiled for one version to run on later versions of Node.js without recompilation.

The module, which is not part of Node.js, preserves the benefits of the Node-API as it consists only of inline code that depends only on the stable API provided by Node-API. As such, modules built against one version of Node.js using node-addon-api should run without having to be rebuilt with newer versions of Node.js.

It is important to remember that other Node.js interfaces such as (included in a project via ) are not ABI-stable across Node.js major versions. Thus, an addon must use Node-API and/or exclusively and build against a version of Node.js that includes an implementation of Node-API (meaning an active LTS version of Node.js) in order to benefit from ABI stability across Node.js major versions. Node.js provides an ABI stability guide containing a detailed explanation of ABI stability in general, and the Node-API ABI stability guarantee in particular.

As new APIs are added to Node-API, node-addon-api must be updated to provide wrappers for those new APIs. For this reason node-addon-api provides methods that allow callers to obtain the underlying Node-API handles so direct calls to Node-API and the use of the objects/methods provided by node-addon-api can be used together. For example, in order to be able to use an API for which the node-addon-api does not yet provide a wrapper.

APIs exposed by node-addon-api are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA262 Language Specification.

The Node-API Resource offers an excellent orientation and tips for developers just getting started with Node-API and node-addon-api.

Current version: 4.2.0

(See CHANGELOG.md for complete Changelog)

NPMNPM

node-addon-api is based on Node-API and supports using different Node-API versions. This allows addons built with it to run with Node.js versions which support the targeted Node-API version. However the node-addon-api support model is to support only the active LTS Node.js versions. This means that every year there will be a new major which drops support for the Node.js LTS version which has gone out of service.

The oldest Node.js version supported by the current version of node-addon-api is Node.js 12.x.

Setup

API Documentation

The following is the documentation for node-addon-api.

Examples

Are you new to node-addon-api? Take a look at our examples

Tests

To run the node-addon-api tests do:

To avoid testing the deprecated portions of the API run

To run the tests targeting a specific version of Node-API run

where X is the version of Node-API you want to target.

Debug

To run the node-addon-api tests with option:

If you want faster build, you might use the following option:

Take a look and get inspired by our test suite

Benchmarks

You can run the available benchmarks using the following command:

See benchmark/README.md for more details about running and adding benchmarks.

More resource and info about native Addons

As node-addon-api's core mission is to expose the plain C Node-API as C++ wrappers, tools that facilitate n-api/node-addon-api providing more convenient patterns on developing a Node.js add-ons with n-api/node-addon-api can be published to NPM as standalone packages. It is also recommended to tag such packages with to provide more visibility to the community.

Quick links to NPM searches: keywords:node-addon-api.

Other bindings

Badges

The use of badges is recommended to indicate the minimum version of Node-API required for the module. This helps to determine which Node.js major versions are supported. Addon maintainers can consult the Node-API support matrix to determine which Node.js versions provide a given Node-API version. The following badges are available:

Node-API v1 BadgeNode-API v2 BadgeNode-API v3 BadgeNode-API v4 BadgeNode-API v5 BadgeNode-API v6 BadgeNode-API v7 BadgeNode-API v8 BadgeNode-API Experimental Version Badge

Contributing

We love contributions from the community to node-addon-api! See CONTRIBUTING.md for more details on our philosophy around extending this module.

Team members

Active

Emeritus

Licensed under MIT

Sours: https://github.com/nodejs/node-addon-api

node-ffi-napi

Node.js Foreign Function Interface for N-API

Greenkeeper badge

NPM VersionNPM DownloadsBuild StatusCoverage StatusDependency Status

is a Node.js addon for loading and calling dynamic libraries using pure JavaScript. It can be used to create bindings to native libraries without writing any C++ code.

It also simplifies the augmentation of node.js with C code as it takes care of handling the translation of types across JavaScript and C, which can add reams of boilerplate code to your otherwise simple C. See the for an example of this use case.

WARNING: assumes you know what you're doing. You can pretty easily create situations where you will segfault the interpreter and unless you've got C debugger skills, you probably won't know what's going on.

WARNING: The original API of is left mostly untouched in the N-API wrapper. However, the API did not have very well-defined properties in the context of garbage collection and multi-threaded execution. It is recommended to avoid any multi-threading usage of this library if possible.

Example

varffi=require('ffi-napi');varlibm=ffi.Library('libm',{'ceil': ['double',['double']]});libm.ceil(1.5);// 2// You can also access just functions in the current process by passing a nullvarcurrent=ffi.Library(null,{'atoi': ['int',['string']]});current.atoi('1234');// 1234

For a more detailed introduction, see the node-ffi tutorial page.

Requirements

  • Linux, OS X, Windows, or Solaris.
  • comes bundled with node-ffi-napi; it does not need to be installed on your system.
  • The current version is tested to run on Node 6 and above.

Installation

Make sure you've installed all the necessary build tools for your platform, then invoke:

Source Install / Manual Compilation

To compile from source it's easiest to use :

$ npm install -g node-gyp

Now you can compile :

$ git clone git://github.com/node-ffi-napi/node-ffi-napi.git $ cd node-ffi $ node-gyp rebuild

Types

The types that you specify in function declarations correspond to ref's types system. So see its docs for a reference if you are unfamiliar.

V8 and 64-bit Types

Internally, V8 stores integers that will fit into a 32-bit space in a 32-bit integer, and those that fall outside of this get put into double-precision floating point numbers. This is problematic because FP numbers are imprecise. To get around this, the methods in node-ffi that deal with 64-bit integers return strings and can accept strings as parameters.

Call Overhead

There is non-trivial overhead associated with FFI calls. Comparing a hard-coded binding version of to an FFI version of shows that the native hard-coded binding is orders of magnitude faster. So don't just use the C version of a function just because it's faster. There's a significant cost in FFI calls, so make them worth it.

License

MIT License. See the file.

Sours: https://github.com/node-ffi-napi/node-ffi-napi
  1. Walmart electric skillet in store
  2. Uscg uniforms
  3. The red skull
  4. Printable fruit stickers
  5. Botox highland park

NAN to Node-API Migration: A Short Story

Throughout the years I’ve created my fair share of native addons. The first ones were created by using the native C++ Node.js and v8 API’s. When NAN was created which made life much easier, especially in terms of maintenance, there was no question that I should move all my addons to use it.

The years passed and Node-API was created and though it was on my radar and saw the benefits of using it, I never had the time to try it on my own modules. So when thinking on a topic for a blog, it struck me that writing about the migration of a couple of my addons from using NAN to Node-API could be interesting.

Background

Back in the old Node.js days the only way to implement a Node.js native addon was by using v8, Node.js and libuv libraries. For example, looking at part of the code from on of my oldest native addons which worked for the Node.js versions:

In this code snippet, a bind() method is exposed to JS as well as a couple of constants and . As it can be seen, only v8 and Node.js libraries are used.

The main issue that this approach had was that the v8 and Node.js exposed API’s might (and most of the time they did) change across versions. This caused that, in order for the native addon to be usable in different Node.js versions we had to do things like this:

This way the code would work on any version from 0.8.x to 0.12.x but it’s kind of ugly and what’s more important, it can quickly become a huge burden to maintain the more versions you want your addon to support.

In order to solve this specific issue, Native Abstractions for Node.js (NAN) was created. From their documentation:

Thanks to the crazy changes in V8 (and some in Node core), keeping native addons compiling happily across versions, particularly 0.10 to 0.12 to 4.0, is a minor nightmare. The goal of this project is to store all logic necessary to develop native Node.js addons without having to inspect NODE_MODULE_VERSION and get yourself into a macro-tangle.

In other words, NAN provides a common interface to access the v8 and Node.js functionality that their API’s provide across the different Node.js versions.

Next I’m showing the exact same function implemented using [email protected]

Which is so much nicer and makes it compatible with every nodejs version starting from 0.10.x.

So far so good. NAN helps A LOT to the burden of native addons creation and maintenance but it also comes with its own set of drawbacks:

  • The add-on needs to be rebuilt for every NODE_MODULE_VERSION, so the binary distribution becomes cumbersome.
  • It’s dependent on the V8 engine, so in the event a different JS engine were to be used it wouldn’t work.

Hello Node-API

Node-API was added to Node.js 8.0.0 as experimental with its main objective being to provide an API that allowed to develop native addons that are independent of the underlying JS engine used by Node.js (At the time it made a lot of sense as there was active development efforts to add support for the Chakracore JS engine). Also, this API is ABI across Node.js versions, meaning that a native addon built on a specific major version would run correctly in subsequent major versions without recompilation.

It is a C API that’s maintained in the nodejs source tree though in order to make it easier to use, node-addon-api, a C++ API built on top of it, is also provided.

So as stated before, we’re going to proceed with the migration of two of my native addons from using NAN and to use node-addon-api.

I’m going to describe the process highlighting what seemed more interesting. Also, I’d like to point out that there’s a very handy conversion.js script that will help a lot by automating the conversion for you, though I haven’t used it for the addons I’m presenting here.

node-ioctl

This is a simple wrapper over the syscall so it looked like a great candidate for a first NAN to Node-Addon-API migration.

The first step would be setting up the node-addon-api to be used by our addon:

  1. Install node-addon-api as a dependency, replacing NAN.

NAN → node-addon-apiScreen Shot 2021-08-19 at 8.43.18 AM

  1. Then modify the binding.gyp file to be able to actually use node-addon-api. The needed changes being:

    • Configure the location of the -
    • As our c++ addon code doesn’t throw exceptions, disable it by defining
    • Finally, as this addon is supported on OS X, define the corresponding conditions.

NAN

node-addon-api

And now for the actual code of the addon. The addon is actually quite simple as it just exports one ioctl() method.

We will focus first on the headers to be included. As already said before, Node-API is independent of the underlying v8 so we can’t directly use any of the v8 functions. The same goes for the Node.js public api’s which shouldn’t be used directly in order to keep the binary compatibility. All of this means not to include either v8.h nor node.h but just napi.h.

NAN → node-addon-apiScreen Shot 2021-08-23 at 9.08.41 AM

Looking now at the addon initialization, the modifications are quite straightforward and hopefully self-explanatory: it just exports an ioctl method implemented in the Ioctl function.

NAN

node-addon-api

This code, though, serves us well to introduce some of the basic node-addon-api classes.

  • which is an opaque structure that contains the environment in which the current code is run (the actual Node.js runtime). This structure is passed to native functions when they're invoked, and it must be passed back when making Node-API calls.
  • are the C++ representation of the underlying JS primitives ( inherits from ) and they all inherit from base class.

And finally the actual method implementation. The summary of what it actual does is

  1. Validating and extracting the arguments (2 or 3 arguments are supported)
  2. Perform the syscall with those arguments.
  3. Return the integer returned by the syscall.

NAN

node-addon-api

Some important things to highlight here:

  • defines the callback method that is called when calling the ioctl() method from JS. It returns a JS number while the contains the arguments passed to the method which can be accessed via the operator.
  • When accessing the arguments, which are , we can use specific methods to check their JS type and convert them into that specific JS type. Once that conversion is done we can extract the value it represents. As an example for an that represents an , we would do:

Notice also the use of the for every call that creates a new Javascript value such when creating a or a

node-pcsclite

It's a wrapper over the libpcsclite library which allows operating on SmartCards.

This one is a bit of a more complex add-on, and for this very same reason I won’t go into as much detail as I did with the previous pme and just focus on a specific case that doesn't appear in node-ioctl.

Just establish that the addon defines two main C++ classes PCSCLite and CardReader. They are initialized in the following way for the NAN version and the new node-addon-api version

NAN

node-addon-api

These classes are bound to the lifetime of a JS object by wrapping them into an ObjectWrap. For the NAN version, this means that these classes need to inherit from whereas for node-addon-api they’ll need to inherit from

NAN

node-addon-api

And here’s the actual implementation of how the ObjectWrap are setup for both the NAN and the new node-addon-api versions

NAN

node-addon-api

Comparing both we can see that the NAN version is very similar as you’d do it using the v8 and Node.js libraries directly whereas on the node-addon-api case the code is much more concise and simpler thanks to the base class and the static method, which allow to define a Javascript class with its methods and properties in only one call. Also it’s important to call attention to the fact that there’s no need to define a specific method to be called when the JS code is executed, but the base class handles all this for you.

The whole set of code changes that were necessary to perform the migration of both addons can be found here and here.

Conclusions

Some final thoughts after spending a couple of days on the migration of the code.

  • It was much easier than I had expected thanks to the API documentation, the extensive list of examples available and the Node-API Resource webpage whose content is top-notch.
  • The API is generally quite easy to use and understand and usually leads to cleaner and more concise code.
  • Having binary compatibility across Node.js version is amazing.
  • If I were to create new addons, Node-API would be my choice over NAN, unless I were to use some specific v8 methods not covered by it.

Need a helping hand?

If you have any questions, please feel free to contact us at [email protected] or in this form.

To get the best out of Node.js, start a free trial of N|Solid, an augmented version of the Node.js runtime, enhanced to deliver low-impact performance insights and greater security for mission-critical Node.js applications. #KnowyourNode

Sours: https://nodesource.com/blog/NAN-to-Node-API-migration-a-short-story
N-API - Next Generation Node API for Native Modules

A first project

Before you start, make sure you’ve got all the necessary prerequisites and tools installed.

As you select where to begin, you should be aware that Node-API operates at two levels which we can think of as the “C level” and the “C++ level”.

The “C level” code is built entirely into Node itself and is very well documented on the Node documentation pages. If you need low-level access to the intricacies of Node, this is the tool for you.

Alternatively, there is the node-addon-api package which adds a C++ wrapper to the Node-API code built into Node. This package makes working with Node-API much easier as it implements a very nice object model and abstracts away much of the detailed coding that would otherwise be required, while retaining the Node-API promise of ABI stability and forward compatibility.

This tutorial uses .

Node-API has been in public release and active development starting with Node 8.0.0. Since then, it’s undergone a number of refinements. This tutorial has been tested with Node 10.10.0 and is known to fail with older versions of Node. You will need a copy of Node that supports Node-API in order to develop and run Node-API code. To see which versions of Node support Node-API, refer to the Node-API Version Matrix. You can determine the version of Node you’re running with the command .

Creating a project

The easiest way to create a new Node-API project is to use the package. As the package documentation describes, relies on Yeoman which must also be installed:

On some systems, you may receive the error . In that case, on Mac and Linux systems you need to run the commands with elevated privileges:

Using is an excellent way to banish permission issues.

Then enter these commands to generate a new project:

Here are the prompts you’ll see and some suggested responses:

Yeoman will display the generated file here.

Yeoman will now build your “Hello World” add-on module.

At this point, you might try running to make sure everything is correctly installed:

Project structure

At this point you have a completely functional Node-API module project. The project files are structured according to Node-API best practices. It should look like this:

Let’s take a look at the essential files.

package.json

package.json

This is a typical file as generated by Yeoman from the responses we entered earlier to the command. There are a couple of entries of interest here.

Notice the dependency. This package, which is not strictly a part of Node, adds a C++ wrapper to the C API implemented in Node. The package makes it very straightforward to create and manipulate JavaScript objects inside C++. The package is useful even if the underlying library you’re accessing is in C.

There is also a entry which informs npm that your package requires a build using the capabilities of the package which is covered next.

binding.gyp

binding.gyp

One of the challenges of making C/C++ code available to Node is getting the code compiled, linked, and packaged for a variety of operating systems and architectures. Historically, this would require learning the intricacies of a variety of build tools across a number of operating systems. This is the specific issue GYP seeks to address.

Using GYP permits having a single configuration file that works across all platforms and architectures GYP supports. (It’s GYP, by the way, that requires Python).

node-gyp is a command line tool built in Node that orchestrates GYP to compile your C/C++ files to the correct destination. When npm sees the entry in your file, it automatically invokes its own internal copy of which looks for this file which must be called in order for node-gyp to locate it.

The file is a GYP file which is thoroughly documented here. There is also specific information about building libraries here.

src/hello_world.cc

hello_world.cc

This is perhaps the simplest useful(?) Node-API file you can have.

The file defines a C++ function that takes a single argument. This argument is used to access the JavaScript environment, including any JavaScript arguments that might be passed in.

is an array of JavaScript arguments.

In this case, the C++ function uses the argument to create a local that is then used to create a object which is returned with the value “world”.

The C++ function shows how to set a single export value for the native add-on module. In this case the name of the export is “HelloWorld” and the value is the function.

The macro at the bottom of the C++ file insures that the function is called when the module is loaded.

lib/binding.js

binding.js

This JavaScript file defines a JavaScript class that acts as an intermediary to the C++ binary.

In this case, the sole export of the binding is the function.

test/test_binding.js

test_binding.js

This code demonstrates how to load and call the function using JavaScript. Recall that the sole export from the binding is the function. The function is loaded into the variable using the command.

The function then calls the function and verifies the result.

Conclusion

This project demonstrates a very simple Node-API module that exports a single function. In addition, here are some things you might want to try:

  • Run in your debugger. See if you can step through the code to get a better understanding of how it works. What sort of visibility are you getting into the JavaScript object created by the C++ code?
  • Modify to use the C++ binary module directly instead of through . Step through the code in your debugger to see how things are different.
  • Modify to access arguments passed from the JavaScript. Hint: The module comes with examples.

Resources

Sours: https://nodejs.github.io/node-addon-examples/getting-started/first/

Node napi

Node-API#

Stability: 2 - Stable

Node-API (formerly N-API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (for example, V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without recompilation. The ABI Stability guide provides a more in-depth explanation.

Addons are built/packaged with the same approach/tools outlined in the section titled C++ Addons. The only difference is the set of APIs that are used by the native code. Instead of using the V8 or Native Abstractions for Node.js APIs, the functions available in Node-API are used.

APIs exposed by Node-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA-262 Language Specification. The APIs have the following properties:

  • All Node-API calls return a status code of type . This status indicates whether the API call succeeded or failed.
  • The API's return value is passed via an out parameter.
  • All JavaScript values are abstracted behind an opaque type named .
  • In case of an error status code, additional information can be obtained using . More information can be found in the error handling section Error handling.

Node-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. To support using C++, the project maintains a C++ wrapper module called . This wrapper provides an inlineable C++ API. Binaries built with will depend on the symbols for the Node-API C-based functions exported by Node.js. is a more efficient way to write code that calls Node-API. Take, for example, the following code. The first section shows the code and the second section shows what actually gets used in the addon.

The end result is that the addon only uses the exported C APIs. As a result, it still gets the benefits of the ABI stability provided by the C API.

When using instead of the C APIs, start with the API docs for .

The Node-API Resource offers an excellent orientation and tips for developers just getting started with Node-API and .

Implications of ABI stability#

Although Node-API provides an ABI stability guarantee, other parts of Node.js do not, and any external libraries used from the addon may not. In particular, none of the following APIs provide an ABI stability guarantee across major versions:

  • the Node.js C++ APIs available via any of

  • the libuv APIs which are also included with Node.js and available via

  • the V8 API available via

Thus, for an addon to remain ABI-compatible across Node.js major versions, it must use Node-API exclusively by restricting itself to using

and by checking, for all external libraries that it uses, that the external library makes ABI stability guarantees similar to Node-API.

Building#

Unlike modules written in JavaScript, developing and deploying Node.js native addons using Node-API requires an additional set of tools. Besides the basic tools required to develop for Node.js, the native addon developer requires a toolchain that can compile C and C++ code into a binary. In addition, depending upon how the native addon is deployed, the user of the native addon will also need to have a C/C++ toolchain installed.

For Linux developers, the necessary C/C++ toolchain packages are readily available. GCC is widely used in the Node.js community to build and test across a variety of platforms. For many developers, the LLVM compiler infrastructure is also a good choice.

For Mac developers, Xcode offers all the required compiler tools. However, it is not necessary to install the entire Xcode IDE. The following command installs the necessary toolchain:

For Windows developers, Visual Studio offers all the required compiler tools. However, it is not necessary to install the entire Visual Studio IDE. The following command installs the necessary toolchain:

The sections below describe the additional tools available for developing and deploying Node.js native addons.

Build tools#

Both the tools listed here require that users of the native addon have a C/C++ toolchain installed in order to successfully install the native addon.

node-gyp#

node-gyp is a build system based on the gyp-next fork of Google's GYP tool and comes bundled with npm. GYP, and therefore node-gyp, requires that Python be installed.

Historically, node-gyp has been the tool of choice for building native addons. It has widespread adoption and documentation. However, some developers have run into limitations in node-gyp.

CMake.js#

CMake.js is an alternative build system based on CMake.

CMake.js is a good choice for projects that already use CMake or for developers affected by limitations in node-gyp.

Uploading precompiled binaries#

The three tools listed here permit native addon developers and maintainers to create and upload binaries to public or private servers. These tools are typically integrated with CI/CD build systems like Travis CI and AppVeyor to build and upload binaries for a variety of platforms and architectures. These binaries are then available for download by users who do not need to have a C/C++ toolchain installed.

node-pre-gyp#

node-pre-gyp is a tool based on node-gyp that adds the ability to upload binaries to a server of the developer's choice. node-pre-gyp has particularly good support for uploading binaries to Amazon S3.

prebuild#

prebuild is a tool that supports builds using either node-gyp or CMake.js. Unlike node-pre-gyp which supports a variety of servers, prebuild uploads binaries only to GitHub releases. prebuild is a good choice for GitHub projects using CMake.js.

prebuildify#

prebuildify is a tool based on node-gyp. The advantage of prebuildify is that the built binaries are bundled with the native module when it's uploaded to npm. The binaries are downloaded from npm and are immediately available to the module user when the native module is installed.

Usage#

In order to use the Node-API functions, include the file which is located in the src directory in the node development tree:

This will opt into the default for the given release of Node.js. In order to ensure compatibility with specific versions of Node-API, the version can be specified explicitly when including the header:

This restricts the Node-API surface to just the functionality that was available in the specified (and earlier) versions.

Some of the Node-API surface is experimental and requires explicit opt-in:

In this case the entire API surface, including any experimental APIs, will be available to the module code.

Node-API version matrix#

Node-API versions are additive and versioned independently from Node.js. Version 4 is an extension to version 3 in that it has all of the APIs from version 3 with some additions. This means that it is not necessary to recompile for new versions of Node.js which are listed as supporting a later version.

123
v6.xv6.14.2*
v8.xv8.6.0**v8.10.0*v8.11.2
v9.xv9.0.0*v9.3.0*v9.11.0*
≥ v10.xall releasesall releasesall releases
45678
v10.xv10.16.0v10.17.0v10.20.0v10.23.0
v11.xv11.8.0
v12.xv12.0.0v12.11.0v12.17.0v12.19.0v12.22.0
v13.xv13.0.0v13.0.0
v14.xv14.0.0v14.0.0v14.0.0v14.12.0v14.17.0
v15.xv15.0.0v15.0.0v15.0.0v15.0.0v15.12.0
v16.xv16.0.0v16.0.0v16.0.0v16.0.0v16.0.0

* Node-API was experimental.

** Node.js 8.0.0 included Node-API as experimental. It was released as Node-API version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend Node-API version 3 or later.

Each API documented for Node-API will have a header named , and APIs which are stable will have the additional header . APIs are directly usable when using a Node.js version which supports the Node-API version shown in or higher. When using a Node.js version that does not support the listed or if there is no listed, then the API will only be available if precedes the inclusion of or . If an API appears not to be available on a version of Node.js which is later than the one shown in then this is most likely the reason for the apparent absence.

The Node-APIs associated strictly with accessing ECMAScript features from native code can be found separately in and . The APIs defined in these headers are included in and . The headers are structured in this way in order to allow implementations of Node-API outside of Node.js. For those implementations the Node.js specific APIs may not be applicable.

The Node.js-specific parts of an addon can be separated from the code that exposes the actual functionality to the JavaScript environment so that the latter may be used with multiple implementations of Node-API. In the example below, and refer only to . This ensures that can be reused to compile against either the Node.js implementation of Node-API or any implementation of Node-API outside of Node.js.

is a separate file that contains the Node.js specific entry point to the addon and which instantiates the addon by calling into when the addon is loaded into a Node.js environment.

Environment life cycle APIs#

Section 8.7 of the ECMAScript Language Specification defines the concept of an "Agent" as a self-contained environment in which JavaScript code runs. Multiple such Agents may be started and terminated either concurrently or in sequence by the process.

A Node.js environment corresponds to an ECMAScript Agent. In the main process, an environment is created at startup, and additional environments can be created on separate threads to serve as worker threads. When Node.js is embedded in another application, the main thread of the application may also construct and destroy a Node.js environment multiple times during the life cycle of the application process such that each Node.js environment created by the application may, in turn, during its life cycle create and destroy additional environments as worker threads.

From the perspective of a native addon this means that the bindings it provides may be called multiple times, from multiple contexts, and even concurrently from multiple threads.

Native addons may need to allocate global state which they use during their entire life cycle such that the state must be unique to each instance of the addon.

To this end, Node-API provides a way to allocate data such that its life cycle is tied to the life cycle of the Agent.

napi_set_instance_data#

Added in: v12.8.0, v10.20.0N-API version: 6

  • : The environment that the Node-API call is invoked under.
  • : The data item to make available to bindings of this instance.
  • : The function to call when the environment is being torn down. The function receives so that it might free it. provides more details.
  • : Optional hint to pass to the finalize callback during collection.

Returns if the API succeeded.

This API associates with the currently running Agent. can later be retrieved using . Any existing data associated with the currently running Agent which was set by means of a previous call to will be overwritten. If a was provided by the previous call, it will not be called.

napi_get_instance_data#

Added in: v12.8.0, v10.20.0N-API version: 6

  • : The environment that the Node-API call is invoked under.
  • : The data item that was previously associated with the currently running Agent by a call to .

Returns if the API succeeded.

This API retrieves data that was previously associated with the currently running Agent via . If no data is set, the call will succeed and will be set to .

Basic Node-API data types#

Node-API exposes the following fundamental datatypes as abstractions that are consumed by the various APIs. These APIs should be treated as opaque, introspectable only with other Node-API calls.

napi_status#

Added in: v8.0.0N-API version: 1

Integral status code indicating the success or failure of a Node-API call. Currently, the following status codes are supported.

If additional information is required upon an API returning a failed status, it can be obtained by calling .

napi_extended_error_info#

Added in: v8.0.0N-API version: 1

  • : UTF8-encoded string containing a VM-neutral description of the error.
  • : Reserved for VM-specific error details. This is currently not implemented for any VM.
  • : VM-specific error code. This is currently not implemented for any VM.
  • : The Node-API status code that originated with the last error.

See the Error handling section for additional information.

napi_env#

is used to represent a context that the underlying Node-API implementation can use to persist VM-specific state. This structure is passed to native functions when they're invoked, and it must be passed back when making Node-API calls. Specifically, the same that was passed in when the initial native function was called must be passed to any subsequent nested Node-API calls. Caching the for the purpose of general reuse, and passing the between instances of the same addon running on different threads is not allowed. The becomes invalid when an instance of a native addon is unloaded. Notification of this event is delivered through the callbacks given to and .

napi_value#

This is an opaque pointer that is used to represent a JavaScript value.

napi_threadsafe_function#

Added in: v10.6.0N-API version: 4

This is an opaque pointer that represents a JavaScript function which can be called asynchronously from multiple threads via .

napi_threadsafe_function_release_mode#

Added in: v10.6.0N-API version: 4

A value to be given to to indicate whether the thread-safe function is to be closed immediately () or merely released () and thus available for subsequent use via and .

napi_threadsafe_function_call_mode#

Added in: v10.6.0N-API version: 4

A value to be given to to indicate whether the call should block whenever the queue associated with the thread-safe function is full.

Node-API memory management types#

napi_handle_scope#

This is an abstraction used to control and modify the lifetime of objects created within a particular scope. In general, Node-API values are created within the context of a handle scope. When a native method is called from JavaScript, a default handle scope will exist. If the user does not explicitly create a new handle scope, Node-API values will be created in the default handle scope. For any invocations of code outside the execution of a native method (for instance, during a libuv callback invocation), the module is required to create a scope before invoking any functions that can result in the creation of JavaScript values.

Handle scopes are created using and are destroyed using . Closing the scope can indicate to the GC that all s created during the lifetime of the handle scope are no longer referenced from the current stack frame.

For more details, review the Object lifetime management.

napi_escapable_handle_scope#

Added in: v8.0.0N-API version: 1

Escapable handle scopes are a special type of handle scope to return values created within a particular handle scope to a parent scope.

napi_ref#

Added in: v8.0.0N-API version: 1

This is the abstraction to use to reference a . This allows for users to manage the lifetimes of JavaScript values, including defining their minimum lifetimes explicitly.

For more details, review the Object lifetime management.

napi_type_tag#

Added in: v14.8.0, v12.19.0N-API version: 8

A 128-bit value stored as two unsigned 64-bit integers. It serves as a UUID with which JavaScript objects can be "tagged" in order to ensure that they are of a certain type. This is a stronger check than , because the latter can report a false positive if the object's prototype has been manipulated. Type-tagging is most useful in conjunction with because it ensures that the pointer retrieved from a wrapped object can be safely cast to the native type corresponding to the type tag that had been previously applied to the JavaScript object.

napi_async_cleanup_hook_handle#

Added in: v14.10.0, v12.19.0

An opaque value returned by . It must be passed to when the chain of asynchronous cleanup events completes.

Node-API callback types#

napi_callback_info#

Added in: v8.0.0N-API version: 1

Opaque datatype that is passed to a callback function. It can be used for getting additional information about the context in which the callback was invoked.

napi_callback#

Added in: v8.0.0N-API version: 1

Function pointer type for user-provided native functions which are to be exposed to JavaScript via Node-API. Callback functions should satisfy the following signature:

Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside a is not necessary.

napi_finalize#

Added in: v8.0.0N-API version: 1

Function pointer type for add-on provided functions that allow the user to be notified when externally-owned data is ready to be cleaned up because the object with which it was associated with, has been garbage-collected. The user must provide a function satisfying the following signature which would get called upon the object's collection. Currently, can be used for finding out when objects that have external data are collected.

Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.

napi_async_execute_callback#

Added in: v8.0.0N-API version: 1

Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature:

Implementations of this function must avoid making Node-API calls that execute JavaScript or interact with JavaScript objects. Node-API calls should be in the instead. Do not use the parameter as it will likely result in execution of JavaScript.

napi_async_complete_callback#

Added in: v8.0.0N-API version: 1

Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature:

Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.

napi_threadsafe_function_call_js#

Added in: v10.6.0N-API version: 4

Function pointer used with asynchronous thread-safe function calls. The callback will be called on the main thread. Its purpose is to use a data item arriving via the queue from one of the secondary threads to construct the parameters necessary for a call into JavaScript, usually via , and then make the call into JavaScript.

The data arriving from the secondary thread via the queue is given in the parameter and the JavaScript function to call is given in the parameter.

Node-API sets up the environment prior to calling this callback, so it is sufficient to call the JavaScript function via rather than via .

Callback functions must satisfy the following signature:

  • : The environment to use for API calls, or if the thread-safe function is being torn down and may need to be freed.
  • : The JavaScript function to call, or if the thread-safe function is being torn down and may need to be freed. It may also be if the thread-safe function was created without .
  • : The optional data with which the thread-safe function was created.
  • : Data created by the secondary thread. It is the responsibility of the callback to convert this native data to JavaScript values (with Node-API functions) that can be passed as parameters when is invoked. This pointer is managed entirely by the threads and this callback. Thus this callback should free the data.

Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.

napi_async_cleanup_hook#

Added in: v14.10.0, v12.19.0

Function pointer used with . It will be called when the environment is being torn down.

Callback functions must satisfy the following signature:

The body of the function should initiate the asynchronous cleanup actions at the end of which must be passed in a call to .

Error handling#

Node-API uses both return values and JavaScript exceptions for error handling. The following sections explain the approach for each case.

Return values#

All of the Node-API functions share the same error handling pattern. The return type of all API functions is .

The return value will be if the request was successful and no uncaught JavaScript exception was thrown. If an error occurred AND an exception was thrown, the value for the error will be returned. If an exception was thrown, and no error occurred, will be returned.

In cases where a return value other than or is returned, must be called to check if an exception is pending. See the section on exceptions for more details.

The full set of possible values is defined in .

The return value provides a VM-independent representation of the error which occurred. In some cases it is useful to be able to get more detailed information, including a string representing the error as well as VM (engine)-specific information.

In order to retrieve this information is provided which returns a structure. The format of the structure is as follows:

Added in: v8.0.0N-API version: 1

  • : Textual representation of the error that occurred.
  • : Opaque handle reserved for engine use only.
  • : VM specific error code.
  • : Node-API status code for the last error.

returns the information for the last Node-API call that was made.

Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.

napi_get_last_error_info#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The structure with more information about the error.

Returns if the API succeeded.

This API retrieves a structure with information about the last error that occurred.

The content of the returned is only valid up until a Node-API function is called on the same .

Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.

This API can be called even if there is a pending JavaScript exception.

Exceptions#

Any Node-API function call may result in a pending JavaScript exception. This is the case for any of the API functions, even those that may not cause the execution of JavaScript.

If the returned by a function is then no exception is pending and no additional action is required. If the returned is anything other than or , in order to try to recover and continue instead of simply returning immediately, must be called in order to determine if an exception is pending or not.

In many cases when a Node-API function is called and an exception is already pending, the function will return immediately with a of . However, this is not the case for all functions. Node-API allows a subset of the functions to be called to allow for some minimal cleanup before returning to JavaScript. In that case, will reflect the status for the function. It will not reflect previous pending exceptions. To avoid confusion, check the error status after every function call.

When an exception is pending one of two approaches can be employed.

The first approach is to do any appropriate cleanup and then return so that execution will return to JavaScript. As part of the transition back to JavaScript, the exception will be thrown at the point in the JavaScript code where the native method was invoked. The behavior of most Node-API calls is unspecified while an exception is pending, and many will simply return , so do as little as possible and then return to JavaScript where the exception can be handled.

The second approach is to try to handle the exception. There will be cases where the native code can catch the exception, take the appropriate action, and then continue. This is only recommended in specific cases where it is known that the exception can be safely handled. In these cases can be used to get and clear the exception. On success, result will contain the handle to the last JavaScript thrown. If it is determined, after retrieving the exception, the exception cannot be handled after all it can be re-thrown it with where error is the JavaScript value to be thrown.

The following utility functions are also available in case native code needs to throw an exception or determine if a is an instance of a JavaScript object: , , and .

The following utility functions are also available in case native code needs to create an object: , , and , where result is the that refers to the newly created JavaScript object.

The Node.js project is adding error codes to all of the errors generated internally. The goal is for applications to use these error codes for all error checking. The associated error messages will remain, but will only be meant to be used for logging and display with the expectation that the message can change without SemVer applying. In order to support this model with Node-API, both in internal functionality and for module specific functionality (as its good practice), the and functions take an optional code parameter which is the string for the code to be added to the error object. If the optional parameter is then no code will be associated with the error. If a code is provided, the name associated with the error is also updated to be:

where is the original name associated with the error and is the code that was provided. For example, if the code is and a is being created the name will be:

napi_throw#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to be thrown.

Returns if the API succeeded.

This API throws the JavaScript value provided.

napi_throw_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional error code to be set on the error.
  • : C string representing the text to be associated with the error.

Returns if the API succeeded.

This API throws a JavaScript with the text provided.

napi_throw_type_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional error code to be set on the error.
  • : C string representing the text to be associated with the error.

Returns if the API succeeded.

This API throws a JavaScript with the text provided.

napi_throw_range_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional error code to be set on the error.
  • : C string representing the text to be associated with the error.

Returns if the API succeeded.

This API throws a JavaScript with the text provided.

napi_is_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The to be checked.
  • : Boolean value that is set to true if represents an error, false otherwise.

Returns if the API succeeded.

This API queries a to check if it represents an error object.

napi_create_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional with the string for the error code to be associated with the error.
  • : that references a JavaScript to be used as the message for the .
  • : representing the error created.

Returns if the API succeeded.

This API returns a JavaScript with the text provided.

napi_create_type_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional with the string for the error code to be associated with the error.
  • : that references a JavaScript to be used as the message for the .
  • : representing the error created.

Returns if the API succeeded.

This API returns a JavaScript with the text provided.

napi_create_range_error#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional with the string for the error code to be associated with the error.
  • : that references a JavaScript to be used as the message for the .
  • : representing the error created.

Returns if the API succeeded.

This API returns a JavaScript with the text provided.

napi_get_and_clear_last_exception#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The exception if one is pending, otherwise.

Returns if the API succeeded.

This API can be called even if there is a pending JavaScript exception.

napi_is_exception_pending#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Boolean value that is set to true if an exception is pending.

Returns if the API succeeded.

This API can be called even if there is a pending JavaScript exception.

napi_fatal_exception#

Added in: v9.10.0N-API version: 3

  • : The environment that the API is invoked under.
  • : The error that is passed to .

Trigger an in JavaScript. Useful if an async callback throws an exception with no way to recover.

Fatal errors#

In the event of an unrecoverable error in a native module, a fatal error can be thrown to immediately terminate the process.

napi_fatal_error#

Added in: v8.2.0N-API version: 1

  • : Optional location at which the error occurred.
  • : The length of the location in bytes, or if it is null-terminated.
  • : The message associated with the error.
  • : The length of the message in bytes, or if it is null-terminated.

The function call does not return, the process will be terminated.

This API can be called even if there is a pending JavaScript exception.

Object lifetime management#

As Node-API calls are made, handles to objects in the heap for the underlying VM may be returned as . These handles must hold the objects 'live' until they are no longer required by the native code, otherwise the objects could be collected before the native code was finished using them.

As object handles are returned they are associated with a 'scope'. The lifespan for the default scope is tied to the lifespan of the native method call. The result is that, by default, handles remain valid and the objects associated with these handles will be held live for the lifespan of the native method call.

In many cases, however, it is necessary that the handles remain valid for either a shorter or longer lifespan than that of the native method. The sections which follow describe the Node-API functions that can be used to change the handle lifespan from the default.

Making handle lifespan shorter than that of the native method#

It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. For example, consider a native method that has a loop which iterates through the elements in a large array:

This would result in a large number of handles being created, consuming substantial resources. In addition, even though the native code could only use the most recent handle, all of the associated objects would also be kept alive since they all share the same scope.

To handle this case, Node-API provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those handles are no longer required, the scope can be 'closed' and any handles associated with the scope are invalidated. The methods available to open/close scopes are and .

Node-API only supports a single nested hierarchy of scopes. There is only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be closed in the reverse order from which they are opened. In addition, all scopes created within a native method must be closed before returning from that method.

Taking the earlier example, adding calls to and would ensure that at most a single handle is valid throughout the execution of the loop:

When nesting scopes, there are cases where a handle from an inner scope needs to live beyond the lifespan of that scope. Node-API supports an 'escapable scope' in order to support this case. An escapable scope allows one handle to be 'promoted' so that it 'escapes' the current scope and the lifespan of the handle changes from the current scope to that of the outer scope.

The methods available to open/close escapable scopes are and .

The request to promote a handle is made through which can only be called once.

napi_open_handle_scope#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the new scope.

Returns if the API succeeded.

This API opens a new scope.

napi_close_handle_scope#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the scope to be closed.

Returns if the API succeeded.

This API closes the scope passed in. Scopes must be closed in the reverse order from which they were created.

This API can be called even if there is a pending JavaScript exception.

napi_open_escapable_handle_scope#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the new scope.

Returns if the API succeeded.

This API opens a new scope from which one object can be promoted to the outer scope.

napi_close_escapable_handle_scope#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the scope to be closed.

Returns if the API succeeded.

This API closes the scope passed in. Scopes must be closed in the reverse order from which they were created.

This API can be called even if there is a pending JavaScript exception.

napi_escape_handle#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the current scope.
  • : representing the JavaScript to be escaped.
  • : representing the handle to the escaped in the outer scope.

Returns if the API succeeded.

This API promotes the handle to the JavaScript object so that it is valid for the lifetime of the outer scope. It can only be called once per scope. If it is called more than once an error will be returned.

This API can be called even if there is a pending JavaScript exception.

References to objects with a lifespan longer than that of the native method#

In some cases an addon will need to be able to create and reference objects with a lifespan longer than that of a single native method invocation. For example, to create a constructor and later use that constructor in a request to creates instances, it must be possible to reference the constructor object across many different instance creation requests. This would not be possible with a normal handle returned as a as described in the earlier section. The lifespan of a normal handle is managed by scopes and all scopes must be closed before the end of a native method.

Node-API provides methods to create persistent references to an object. Each persistent reference has an associated count with a value of 0 or higher. The count determines if the reference will keep the corresponding object live. References with a count of 0 do not prevent the object from being collected and are often called 'weak' references. Any count greater than 0 will prevent the object from being collected.

References can be created with an initial reference count. The count can then be modified through and . If an object is collected while the count for a reference is 0, all subsequent calls to get the object associated with the reference will return for the returned . An attempt to call for a reference whose object has been collected results in an error.

References must be deleted once they are no longer required by the addon. When a reference is deleted, it will no longer prevent the corresponding object from being collected. Failure to delete a persistent reference results in a 'memory leak' with both the native memory for the persistent reference and the corresponding object on the heap being retained forever.

There can be multiple persistent references created which refer to the same object, each of which will either keep the object live or not based on its individual count.

napi_create_reference#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the to which we want a reference.
  • : Initial reference count for the new reference.
  • : pointing to the new reference.

Returns if the API succeeded.

This API create a new reference with the specified reference count to the passed in.

napi_delete_reference#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : to be deleted.

Returns if the API succeeded.

This API deletes the reference passed in.

This API can be called even if there is a pending JavaScript exception.

napi_reference_ref#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : for which the reference count will be incremented.
  • : The new reference count.

Returns if the API succeeded.

This API increments the reference count for the reference passed in and returns the resulting reference count.

napi_reference_unref#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : for which the reference count will be decremented.
  • : The new reference count.

Returns if the API succeeded.

This API decrements the reference count for the reference passed in and returns the resulting reference count.

napi_get_reference_value#

Added in: v8.0.0N-API version: 1

the in or out of these methods is a handle to the object to which the reference is related.

  • : The environment that the API is invoked under.
  • : for which we requesting the corresponding .
  • : The for the referenced by the .

Returns if the API succeeded.

If still valid, this API returns the representing the JavaScript associated with the . Otherwise, result will be .

Cleanup on exit of the current Node.js instance#

While a Node.js process typically releases all its resources when exiting, embedders of Node.js, or future Worker support, may require addons to register clean-up hooks that will be run once the current Node.js instance exits.

Node-API provides functions for registering and un-registering such callbacks. When those callbacks are run, all resources that are being held by the addon should be freed up.

napi_add_env_cleanup_hook#

Added in: v10.2.0N-API version: 3

Registers as a function to be run with the parameter once the current Node.js environment exits.

A function can safely be specified multiple times with different values. In that case, it will be called multiple times as well. Providing the same and values multiple times is not allowed and will lead the process to abort.

The hooks will be called in reverse order, i.e. the most recently added one will be called first.

Removing this hook can be done by using . Typically, that happens when the resource for which this hook was added is being torn down anyway.

For asynchronous cleanup, is available.

napi_remove_env_cleanup_hook#

Added in: v10.2.0N-API version: 3

Unregisters as a function to be run with the parameter once the current Node.js environment exits. Both the argument and the function value need to be exact matches.

The function must have originally been registered with , otherwise the process will abort.

napi_add_async_cleanup_hook#
  • : The environment that the API is invoked under.
  • : The function pointer to call at environment teardown.
  • : The pointer to pass to when it gets called.
  • : Optional handle that refers to the asynchronous cleanup hook.

Registers , which is a function of type , as a function to be run with the and parameters once the current Node.js environment exits.

Unlike , the hook is allowed to be asynchronous.

Otherwise, behavior generally matches that of .

If is not , an opaque value will be stored in it that must later be passed to , regardless of whether the hook has already been invoked. Typically, that happens when the resource for which this hook was added is being torn down anyway.

napi_remove_async_cleanup_hook#

Unregisters the cleanup hook corresponding to . This will prevent the hook from being executed, unless it has already started executing. This must be called on any value obtained from .

Module registration#

Node-API modules are registered in a manner similar to other modules except that instead of using the macro the following is used:

The next difference is the signature for the method. For a Node-API module it is as follows:

The return value from is treated as the object for the module. The method is passed an empty object via the parameter as a convenience. If returns , the parameter passed as is exported by the module. Node-API modules cannot modify the object but can specify anything as the property of the module.

To add the method as a function so that it can be called as a method provided by the addon:

To set a function to be returned by the for the addon:

To define a class so that new instances can be created (often used with Object wrap):

You can also use the macro, which acts as a shorthand for and defining an function:

All Node-API addons are context-aware, meaning they may be loaded multiple times. There are a few design considerations when declaring such a module. The documentation on context-aware addons provides more details.

The variables and will be available inside the function body following the macro invocation.

For more details on setting properties on objects, see the section on Working with JavaScript properties.

For more details on building addon modules in general, refer to the existing API.

Working with JavaScript values#

Node-API exposes a set of APIs to create all types of JavaScript values. Some of these types are documented under Section 6 of the ECMAScript Language Specification.

Fundamentally, these APIs are used to do one of the following:

  1. Create a new JavaScript object
  2. Convert from a primitive C type to a Node-API value
  3. Convert from Node-API value to a primitive C type
  4. Get global instances including and

Node-API values are represented by the type . Any Node-API call that requires a JavaScript value takes in a . In some cases, the API does check the type of the up-front. However, for better performance, it's better for the caller to make sure that the in question is of the JavaScript type expected by the API.

Enum types#

napi_key_collection_mode#

Added in: v13.7.0, v12.17.0, v10.20.0N-API version: 6

Describes the filter enums:

limits the range of collected properties.

limits the collected properties to the given object only. will include all keys of the objects's prototype chain as well.

napi_key_filter#

Added in: v13.7.0, v12.17.0, v10.20.0N-API version: 6

Property filter bits. They can be or'ed to build a composite filter.

napi_key_conversion#

Added in: v13.7.0, v12.17.0, v10.20.0N-API version: 6

will convert integer indices to strings. will return numbers for integer indices.

napi_valuetype#

Describes the type of a . This generally corresponds to the types described in Section 6.1 of the ECMAScript Language Specification. In addition to types in that section, can also represent s and s with external data.

A JavaScript value of type appears in JavaScript as a plain object such that no properties can be set on it, and no prototype.

napi_typedarray_type#

This represents the underlying binary scalar datatype of the . Elements of this enum correspond to Section 22.2 of the ECMAScript Language Specification.

Object creation functions#

napi_create_array#

Added in: v8.0.0N-API version: 1

  • : The environment that the Node-API call is invoked under.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript type. JavaScript arrays are described in Section 22.1 of the ECMAScript Language Specification.

napi_create_array_with_length#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The initial length of the .
  • : A representing a JavaScript .

Returns if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript type. The 's length property is set to the passed-in length parameter. However, the underlying buffer is not guaranteed to be pre-allocated by the VM when the array is created. That behavior is left to the underlying VM implementation. If the buffer must be a contiguous block of memory that can be directly read and/or written via C, consider using .

JavaScript arrays are described in Section 22.1 of the ECMAScript Language Specification.

napi_create_arraybuffer#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The length in bytes of the array buffer to create.
  • : Pointer to the underlying byte buffer of the .
  • : A representing a JavaScript .

Returns if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript . s are used to represent fixed-length binary data buffers. They are normally used as a backing-buffer for objects. The allocated will have an underlying byte buffer whose size is determined by the parameter that's passed in. The underlying buffer is optionally returned back to the caller in case the caller wants to directly manipulate the buffer. This buffer can only be written to directly from native code. To write to this buffer from JavaScript, a typed array or object would need to be created.

JavaScript objects are described in Section 24.1 of the ECMAScript Language Specification.

napi_create_buffer#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Size in bytes of the underlying buffer.
  • : Raw pointer to the underlying buffer.
  • : A representing a .

Returns if the API succeeded.

This API allocates a object. While this is still a fully-supported data structure, in most cases using a will suffice.

napi_create_buffer_copy#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Size in bytes of the input buffer (should be the same as the size of the new buffer).
  • : Raw pointer to the underlying buffer to copy from.
  • : Pointer to the new 's underlying data buffer.
  • : A representing a .

Returns if the API succeeded.

This API allocates a object and initializes it with data copied from the passed-in buffer. While this is still a fully-supported data structure, in most cases using a will suffice.

napi_create_date#

Added in: v11.11.0, v10.17.0N-API version: 5

  • : The environment that the API is invoked under.
  • : ECMAScript time value in milliseconds since 01 January, 1970 UTC.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.

This API allocates a JavaScript object.

JavaScript objects are described in Section 20.3 of the ECMAScript Language Specification.

napi_create_external#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Raw pointer to the external data.
  • : Optional callback to call when the external value is being collected. provides more details.
  • : Optional hint to pass to the finalize callback during collection.
  • : A representing an external value.

Returns if the API succeeded.

This API allocates a JavaScript value with external data attached to it. This is used to pass external data through JavaScript code, so it can be retrieved later by native code using .

The API adds a callback which will be called when the JavaScript object just created is ready for garbage collection. It is similar to except that:

  • the native data cannot be retrieved later using ,
  • nor can it be removed later using , and
  • the object created by the API can be used with .

The created value is not an object, and therefore does not support additional properties. It is considered a distinct value type: calling with an external value yields .

napi_create_external_arraybuffer#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Pointer to the underlying byte buffer of the .
  • : The length in bytes of the underlying buffer.
  • : Optional callback to call when the is being collected. provides more details.
  • : Optional hint to pass to the finalize callback during collection.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript . The underlying byte buffer of the is externally allocated and managed. The caller must ensure that the byte buffer remains valid until the finalize callback is called.

The API adds a callback which will be called when the JavaScript object just created is ready for garbage collection. It is similar to except that:

  • the native data cannot be retrieved later using ,
  • nor can it be removed later using , and
  • the object created by the API can be used with .

JavaScript s are described in Section 24.1 of the ECMAScript Language Specification.

napi_create_external_buffer#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Size in bytes of the input buffer (should be the same as the size of the new buffer).
  • : Raw pointer to the underlying buffer to expose to JavaScript.
  • : Optional callback to call when the is being collected. provides more details.
  • : Optional hint to pass to the finalize callback during collection.
  • : A representing a .

Returns if the API succeeded.

This API allocates a object and initializes it with data backed by the passed in buffer. While this is still a fully-supported data structure, in most cases using a will suffice.

The API adds a callback which will be called when the JavaScript object just created is ready for garbage collection. It is similar to except that:

  • the native data cannot be retrieved later using ,
  • nor can it be removed later using , and
  • the object created by the API can be used with .

For Node.js >=4 are s.

napi_create_object#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API allocates a default JavaScript . It is the equivalent of doing in JavaScript.

The JavaScript type is described in Section 6.1.7 of the ECMAScript Language Specification.

napi_create_symbol#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Optional which refers to a JavaScript to be set as the description for the symbol.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API creates a JavaScript value from a UTF8-encoded C string.

The JavaScript type is described in Section 19.4 of the ECMAScript Language Specification.

napi_create_typedarray#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Scalar datatype of the elements within the .
  • : Number of elements in the .
  • : underlying the typed array.
  • : The byte offset within the from which to start projecting the .
  • : A representing a JavaScript .

Returns if the API succeeded.

This API creates a JavaScript object over an existing . objects provide an array-like view over an underlying data buffer where each element has the same underlying binary scalar datatype.

It's required that should be <= the size in bytes of the array passed in. If not, a exception is raised.

JavaScript objects are described in Section 22.2 of the ECMAScript Language Specification.

napi_create_dataview#

Added in: v8.3.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Number of elements in the .
  • : underlying the .
  • : The byte offset within the from which to start projecting the .
  • : A representing a JavaScript .

Returns if the API succeeded.

This API creates a JavaScript object over an existing . objects provide an array-like view over an underlying data buffer, but one which allows items of different size and type in the .

It is required that is less than or equal to the size in bytes of the array passed in. If not, a exception is raised.

JavaScript objects are described in Section 24.3 of the ECMAScript Language Specification.

Functions to convert from C types to Node-API#

napi_create_int32#

Added in: v8.4.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Integer value to be represented in JavaScript.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API is used to convert from the C type to the JavaScript type.

The JavaScript type is described in Section 6.1.6 of the ECMAScript Language Specification.

napi_create_uint32#

Added in: v8.4.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Unsigned integer value to be represented in JavaScript.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API is used to convert from the C type to the JavaScript type.

The JavaScript type is described in Section 6.1.6 of the ECMAScript Language Specification.

napi_create_int64#

Added in: v8.4.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Integer value to be represented in JavaScript.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API is used to convert from the C type to the JavaScript type.

The JavaScript type is described in Section 6.1.6 of the ECMAScript Language Specification. Note the complete range of cannot be represented with full precision in JavaScript. Integer values outside the range of - will lose precision.

napi_create_double#

Added in: v8.4.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Double-precision value to be represented in JavaScript.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API is used to convert from the C type to the JavaScript type.

The JavaScript type is described in Section 6.1.6 of the ECMAScript Language Specification.

napi_create_bigint_int64#

Added in: v10.7.0N-API version: 6

  • : The environment that the API is invoked under.
  • : Integer value to be represented in JavaScript.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API converts the C type to the JavaScript type.

napi_create_bigint_uint64#

Added in: v10.7.0N-API version: 6

  • : The environment that the API is invoked under.
  • : Unsigned integer value to be represented in JavaScript.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API converts the C type to the JavaScript type.

napi_create_bigint_words#

Added in: v10.7.0N-API version: 6

  • : The environment that the API is invoked under.
  • : Determines if the resulting will be positive or negative.
  • : The length of the array.
  • : An array of little-endian 64-bit words.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API converts an array of unsigned 64-bit words into a single value.

The resulting is calculated as: (–1) ( × (264)0 + × (264)1 + …)

napi_create_string_latin1#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Character buffer representing an ISO-8859-1-encoded string.
  • : The length of the string in bytes, or if it is null-terminated.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API creates a JavaScript value from an ISO-8859-1-encoded C string. The native string is copied.

The JavaScript type is described in Section 6.1.4 of the ECMAScript Language Specification.

napi_create_string_utf16#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Character buffer representing a UTF16-LE-encoded string.
  • : The length of the string in two-byte code units, or if it is null-terminated.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API creates a JavaScript value from a UTF16-LE-encoded C string. The native string is copied.

The JavaScript type is described in Section 6.1.4 of the ECMAScript Language Specification.

napi_create_string_utf8#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : Character buffer representing a UTF8-encoded string.
  • : The length of the string in bytes, or if it is null-terminated.
  • : A representing a JavaScript .

Returns if the API succeeded.

This API creates a JavaScript value from a UTF8-encoded C string. The native string is copied.

The JavaScript type is described in Section 6.1.4 of the ECMAScript Language Specification.

Functions to convert from Node-API to C types#

napi_get_array_length#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the JavaScript whose length is being queried.
  • : representing length of the array.

Returns if the API succeeded.

This API returns the length of an array.

length is described in Section 22.1.4.1 of the ECMAScript Language Specification.

napi_get_arraybuffer_info#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the being queried.
  • : The underlying data buffer of the . If byte_length is , this may be or any other pointer value.
  • : Length in bytes of the underlying data buffer.

Returns if the API succeeded.

This API is used to retrieve the underlying data buffer of an and its length.

WARNING: Use caution while using this API. The lifetime of the underlying data buffer is managed by the even after it's returned. A possible safe way to use this API is in conjunction with , which can be used to guarantee control over the lifetime of the . It's also safe to use the returned data buffer within the same callback as long as there are no calls to other APIs that might trigger a GC.

napi_get_buffer_info#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the being queried.
  • : The underlying data buffer of the . If length is , this may be or any other pointer value.
  • : Length in bytes of the underlying data buffer.

Returns if the API succeeded.

This API is used to retrieve the underlying data buffer of a and its length.

Warning: Use caution while using this API since the underlying data buffer's lifetime is not guaranteed if it's managed by the VM.

napi_get_prototype#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript whose prototype to return. This returns the equivalent of (which is not the same as the function's property).
  • : representing prototype of the given object.

Returns if the API succeeded.

napi_get_typedarray_info#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the whose properties to query.
  • : Scalar datatype of the elements within the .
  • : The number of elements in the .
  • : The data buffer underlying the adjusted by the value so that it points to the first element in the . If the length of the array is , this may be or any other pointer value.
  • : The underlying the .
  • : The byte offset within the underlying native array at which the first element of the arrays is located. The value for the data parameter has already been adjusted so that data points to the first element in the array. Therefore, the first byte of the native array would be at .

Returns if the API succeeded.

This API returns various properties of a typed array.

Warning: Use caution while using this API since the underlying data buffer is managed by the VM.

napi_get_dataview_info#

Added in: v8.3.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing the whose properties to query.
  • : Number of bytes in the .
  • : The data buffer underlying the . If byte_length is , this may be or any other pointer value.
  • : underlying the .
  • : The byte offset within the data buffer from which to start projecting the .

Returns if the API succeeded.

This API returns various properties of a .

napi_get_date_value#

Added in: v11.11.0, v10.17.0N-API version: 5

  • : The environment that the API is invoked under.
  • : representing a JavaScript .
  • : Time value as a represented as milliseconds since midnight at the beginning of 01 January, 1970 UTC.

This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.

Returns if the API succeeded. If a non-date is passed in it returns .

This API returns the C double primitive of time value for the given JavaScript .

napi_get_value_bool#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : C boolean primitive equivalent of the given JavaScript .

Returns if the API succeeded. If a non-boolean is passed in it returns .

This API returns the C boolean primitive equivalent of the given JavaScript .

napi_get_value_double#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : C double primitive equivalent of the given JavaScript .

Returns if the API succeeded. If a non-number is passed in it returns .

This API returns the C double primitive equivalent of the given JavaScript .

napi_get_value_bigint_int64#

Added in: v10.7.0N-API version: 6

  • : The environment that the API is invoked under
  • : representing JavaScript .
  • : C primitive equivalent of the given JavaScript .
  • : Indicates whether the value was converted losslessly.

Returns if the API succeeded. If a non- is passed in it returns .

This API returns the C primitive equivalent of the given JavaScript . If needed it will truncate the value, setting to .

napi_get_value_bigint_uint64#

Added in: v10.7.0N-API version: 6

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : C primitive equivalent of the given JavaScript .
  • : Indicates whether the value was converted losslessly.

Returns if the API succeeded. If a non- is passed in it returns .

This API returns the C primitive equivalent of the given JavaScript . If needed it will truncate the value, setting to .

napi_get_value_bigint_words#

Added in: v10.7.0N-API version: 6

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : Integer representing if the JavaScript is positive or negative.
  • : Must be initialized to the length of the array. Upon return, it will be set to the actual number of words that would be needed to store this .
  • : Pointer to a pre-allocated 64-bit word array.

Returns if the API succeeded.

This API converts a single value into a sign bit, 64-bit little-endian array, and the number of elements in the array. and may be both set to , in order to get only .

napi_get_value_external#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript external value.
  • : Pointer to the data wrapped by the JavaScript external value.

Returns if the API succeeded. If a non-external is passed in it returns .

This API retrieves the external data pointer that was previously passed to .

napi_get_value_int32#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : C primitive equivalent of the given JavaScript .

Returns if the API succeeded. If a non-number is passed in .

This API returns the C primitive equivalent of the given JavaScript .

If the number exceeds the range of the 32 bit integer, then the result is truncated to the equivalent of the bottom 32 bits. This can result in a large positive number becoming a negative number if the value is > 231 - 1.

Non-finite number values (, , or ) set the result to zero.

napi_get_value_int64#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : C primitive equivalent of the given JavaScript .

Returns if the API succeeded. If a non-number is passed in it returns .

This API returns the C primitive equivalent of the given JavaScript .

values outside the range of - will lose precision.

Non-finite number values (, , or ) set the result to zero.

napi_get_value_string_latin1#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript string.
  • : Buffer to write the ISO-8859-1-encoded string into. If is passed in, the length of the string in bytes and excluding the null terminator is returned in .
  • : Size of the destination buffer. When this value is insufficient, the returned string is truncated and null-terminated.
  • : Number of bytes copied into the buffer, excluding the null terminator.

Returns if the API succeeded. If a non- is passed in it returns .

This API returns the ISO-8859-1-encoded string corresponding the value passed in.

napi_get_value_string_utf8#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript string.
  • : Buffer to write the UTF8-encoded string into. If is passed in, the length of the string in bytes and excluding the null terminator is returned in .
  • : Size of the destination buffer. When this value is insufficient, the returned string is truncated and null-terminated.
  • : Number of bytes copied into the buffer, excluding the null terminator.

Returns if the API succeeded. If a non- is passed in it returns .

This API returns the UTF8-encoded string corresponding the value passed in.

napi_get_value_string_utf16#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript string.
  • : Buffer to write the UTF16-LE-encoded string into. If is passed in, the length of the string in 2-byte code units and excluding the null terminator is returned.
  • : Size of the destination buffer. When this value is insufficient, the returned string is truncated and null-terminated.
  • : Number of 2-byte code units copied into the buffer, excluding the null terminator.

Returns if the API succeeded. If a non- is passed in it returns .

This API returns the UTF16-encoded string corresponding the value passed in.

napi_get_value_uint32#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript .
  • : C primitive equivalent of the given as a .

Returns if the API succeeded. If a non-number is passed in it returns .

This API returns the C primitive equivalent of the given as a .

Functions to get global instances#

napi_get_boolean#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The value of the boolean to retrieve.
  • : representing JavaScript singleton to retrieve.

Returns if the API succeeded.

This API is used to return the JavaScript singleton object that is used to represent the given boolean value.

napi_get_global#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript object.

Returns if the API succeeded.

This API returns the object.

napi_get_null#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript object.

Returns if the API succeeded.

This API returns the object.

napi_get_undefined#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : representing JavaScript Undefined value.

Returns if the API succeeded.

This API returns the Undefined object.

Working with JavaScript values and abstract operations#

Node-API exposes a set of APIs to perform some abstract operations on JavaScript values. Some of these operations are documented under Section 7 of the ECMAScript Language Specification.

These APIs support doing one of the following:

  1. Coerce JavaScript values to specific JavaScript types (such as or ).
  2. Check the type of a JavaScript value.
  3. Check for equality between two JavaScript values.

napi_coerce_to_bool#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to coerce.
  • : representing the coerced JavaScript .

Returns if the API succeeded.

This API implements the abstract operation as defined in Section 7.1.2 of the ECMAScript Language Specification.

napi_coerce_to_number#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to coerce.
  • : representing the coerced JavaScript .

Returns if the API succeeded.

This API implements the abstract operation as defined in Section 7.1.3 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

napi_coerce_to_object#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to coerce.
  • : representing the coerced JavaScript .

Returns if the API succeeded.

This API implements the abstract operation as defined in Section 7.1.13 of the ECMAScript Language Specification.

napi_coerce_to_string#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to coerce.
  • : representing the coerced JavaScript .

Returns if the API succeeded.

This API implements the abstract operation as defined in Section 7.1.13 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

napi_typeof#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value whose type to query.
  • : The type of the JavaScript value.

Returns if the API succeeded.

  • if the type of is not a known ECMAScript type and is not an External value.

This API represents behavior similar to invoking the Operator on the object as defined in Section 12.5.5 of the ECMAScript Language Specification. However, there are some differences:

  1. It has support for detecting an External value.
  2. It detects as a separate type, while ECMAScript would detect .

If has a type that is invalid, an error is returned.

napi_instanceof#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to check.
  • : The JavaScript function object of the constructor function to check against.
  • : Boolean that is set to true if is true.

Returns if the API succeeded.

This API represents invoking the Operator on the object as defined in Section 12.10.4 of the ECMAScript Language Specification.

napi_is_array#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to check.
  • : Whether the given object is an array.

Returns if the API succeeded.

This API represents invoking the operation on the object as defined in Section 7.2.2 of the ECMAScript Language Specification.

napi_is_arraybuffer#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to check.
  • : Whether the given object is an .

Returns if the API succeeded.

This API checks if the passed in is an array buffer.

napi_is_buffer#

Added in: v8.0.0N-API version: 1

  • : The environment that the API is invoked under.
  • : The JavaScript value to check.
  • : Whether the given represents a object.

Returns if the API succeeded.

This API checks if the passed in is a buffer.

napi_is_date#

Added in: v11.11.0, v10.17.0N-API version: 5

  • : The environment that the API is invoked under.
  • : The JavaScript value to check.
  • : Whether the given represents a JavaScript object.

Returns if the API succeeded.

This API checks if the passed in is a date.

napi_is_error#

Added in: v8.0.0N-API version: 1

Sours: https://nodejs.org/api/n-api.html
Next Generation N-API: A Hands-on Workshop - Nicola Del Gobbo, Packly \u0026 Jim Schlight, Inspiredware

NAPI-RS is a minimal library for building pre-compiled Node.js addons in Rust.

lib.rs

index.js

Features

🚀 Bring native performance for

👷‍♂️ Memory safe, guaranteed by compiler

⚡️ Zero copy data interactive between &

⚙️ Parallelism in few lines

Well tested

LintLinux N-API@3Linux muslmacOS/Windows/Linux x64Linux-aarch64Linux-armv7macOS-AndroidWindows i686Windows arm64FreeBSD

Ecosystem

swcParcelnext.js

Support matrix

Node.js

Node10Node12Node14Node16

Platform support

✅ Means official tested in napi-rs repo.
Means no official Node.js release.

i686x64aarch64arm
Windows-
macOS--
Linux-
Linux musl--
FreeBSD---
Android---

Related projects

Sours: https://napi.rs/

Now discussing:

.



472 473 474 475 476