No description
Find a file
LongYinan a8873525fc
Merge pull request #329 from napi-rs/dependabot/npm_and_yarn/typescript-eslint/eslint-plugin-4.9.0
build(deps-dev): bump @typescript-eslint/eslint-plugin from 4.8.2 to 4.9.0
2020-12-02 22:12:58 +08:00
.github ci: add cargo clippy 2020-12-01 14:58:00 +08:00
bench feat(napi): major upgrades for napi@1 2020-11-26 11:31:49 +08:00
build feat(napi): major upgrades for napi@1 2020-11-26 11:31:49 +08:00
napi refactor(napi): reduce useless type cast 2020-12-02 18:39:20 +08:00
napi-derive refactor(napi): js error 2020-12-02 14:56:19 +08:00
napi-derive-example feat(napi): major upgrades for napi@1 2020-11-26 11:31:49 +08:00
src ci: reduce aarch64 running time by cross compile in host machine 2020-10-15 16:14:11 +08:00
sys feat(napi): major upgrades for napi@1 2020-11-26 11:31:49 +08:00
test_module refactor(napi): js error 2020-12-02 14:56:19 +08:00
.cirrus.yml refactor(napi-sys): remove bindgen 2020-11-10 17:52:59 +08:00
.dockerignore feat(napi): support musl linux 2020-06-11 16:20:37 +08:00
.editorconfig init 2018-04-28 16:26:38 +08:00
.eslintignore feat(cli): start new cli 2020-07-29 23:06:37 +08:00
.eslintrc.yml feat: support linux aarch64 2020-10-15 09:12:43 +08:00
.gitignore ci: setup benchmark action 2020-10-14 01:02:00 +08:00
.npmignore feat: support linux aarch64 2020-10-15 09:12:43 +08:00
.prettierignore refactor(napi): async and lifetime span 2020-05-09 14:13:25 +08:00
.yarnrc feat: upgrade to std-future 2020-02-18 21:09:17 +08:00
alpine.Dockerfile fix: add missing rustup path 2020-11-28 00:25:44 +08:00
ava.config.js feat: support linux aarch64 2020-10-15 09:12:43 +08:00
Cargo.toml style: format toml files 2020-10-11 21:36:14 +08:00
CODE_OF_CONDUCT.md doc: add email to CODE_OF_CONDUCT 2020-05-20 18:49:36 +08:00
LICENSE chore: prepare for release 2020-03-16 14:30:54 +08:00
package.json Merge pull request #329 from napi-rs/dependabot/npm_and_yarn/typescript-eslint/eslint-plugin-4.9.0 2020-12-02 22:12:58 +08:00
README.md refactor(napi-sys): remove bindgen 2020-11-10 17:52:59 +08:00
rustfmt.toml Implement buffer 2019-05-23 19:28:51 +08:00
tsconfig.json chore(napi): simplify module register, support node@10+ 2020-11-04 15:54:57 +08:00
tsconfig.root-lint.json feat: support linux aarch64 2020-10-15 09:12:43 +08:00
yarn.lock Merge pull request #329 from napi-rs/dependabot/npm_and_yarn/typescript-eslint/eslint-plugin-4.9.0 2020-12-02 22:12:58 +08:00

napi-rs

This project was initialized from xray

A minimal library for building compiled NodeJS add-ons in Rust.

Platform Support

Lint Linux N-API@3 Linux musl macOS/Windows/Linux x64 Linux-aarch64 Windows i686 FreeBSD

Operating Systems

Linux macOS Windows MSVC FreeBSD

NodeJS

Node10 Node 12 Node14 Node15

This library depends on N-API and requires Node@8.9 or later.

We already have some packages written by napi-rs: node-rs

One nice feature is that this crate allows you to build add-ons purely with the Rust toolchain and without involving node-gyp.

Taste

You can start from package-template to play with napi-rs

Define JavaScript functions

#[js_function(1)] // ------> arguments length, omit for zero
fn fibonacci(ctx: CallContext) -> Result<JsNumber> {
  let n = ctx.get::<JsNumber>(0)?.try_into()?;
  ctx.env.create_int64(fibonacci_native(n))
}

#[inline]
fn fibonacci_native(n: i64) -> i64 {
  match n {
    1 | 2 => 1,
    _ => fibonacci_native(n - 1) + fibonacci_native(n - 2),
  }
}

Register module

/// test_module is Module name
register_module!(test_module, init);

/// Module is `module` object in NodeJS
fn init(module: &mut Module) -> Result<()> {
  module.create_named_method("fibonacci", fibonacci)?;
}

Building

This repository is a Cargo crate. Any napi-based add-on should contain Cargo.toml to make it a Cargo crate.

In your Cargo.toml you need to set the crate-type to "cdylib" so that cargo builds a C-style shared library that can be dynamically loaded by the Node executable. You'll also need to add this crate as a dependency.

[lib]
crate-type = ["cdylib"]

[dependencies]
napi = "0.5"
napi-derive = "0.5"

[build-dependencies]
napi-build = "0.2"

And create build.rs in your own project:

// build.rs
extern crate napi_build;

fn main() {
  napi_build::setup();
}

So far, the napi build script has only been tested on macOS Linux and Windows x64 MSVC.

See the included test_module for an example add-on.

Run cargo build to produce the Dynamic lib file. And install the napi-rs to help you copy Dynamic lib file to .node file in case you can require it in your program.

{
  "package": "your pkg",
  "devDependencies": {
    "napi-rs": "latest"
  },
  "scripts": {
    "build": "cargo build && napi build",
    "build-release": "cargo build --release && napi build --release"
  }
}

Then you can require your native binding:

require('./target/debug|release/[module_name].node')

The module_name would be your package name in your Cargo.toml.

xxx => ./target/debug|release/xxx.node

xxx-yyy => ./target/debug|release/xxx_yyy.node

You can also copy Dynamic lib file to an appointed location:

napi build [--release] .
napi build [--release] ./mylib

Testing

Because libraries that depend on this crate must be loaded into a Node executable in order to resolve symbols, all tests are written in JavaScript in the test_module subdirectory.

To run tests:

yarn build:test
yarn test

Features table

Create JavaScript values

NAPI NAPI Version Minimal Node version Status
napi_create_array 1 v8.0.0
napi_create_array_with_length 1 v8.0.0
napi_create_arraybuffer 1 v8.0.0
napi_create_buffer 1 v8.0.0
napi_create_buffer_copy 1 v8.0.0
napi_create_date 5 v11.11.0
napi_create_external 1 v8.0.0
napi_create_external_arraybuffer 1 v8.0.0
napi_create_external_buffer 1 v8.0.0
napi_create_object 1 v8.0.0
napi_create_symbol 1 v8.0.0
napi_create_typedarray 1 v8.0.0
napi_create_dataview 1 v8.3.0
napi_create_int32 1 v8.4.0
napi_create_uint32 1 v8.4.0
napi_create_int64 1 v8.4.0
napi_create_double 1 v8.4.0
napi_create_bigint_int64 6 v10.7.0
napi_create_bigint_uint64 6 v10.7.0
napi_create_bigint_words 6 v10.7.0
napi_create_string_latin1 1 v8.0.0
napi_create_string_utf16 1 v8.0.0
napi_create_string_utf8 1 v8.0.0

Functions to convert from N-API to C types

NAPI NAPI Version Minimal Node Version Status
napi_get_array_length 1 v8.0.0
napi_get_arraybuffer_info 1 v8.0.0
napi_get_buffer_info 1 v8.0.0
napi_get_prototype 1 v8.0.0
napi_get_typedarray_info 1 v8.0.0
napi_get_dataview_info 1 v8.3.0
napi_get_date_value 5 v11.11.0
napi_get_value_bool 1 v8.0.0
napi_get_value_double 1 v8.0.0
napi_get_value_bigint_int64 6 v10.7.0
napi_get_value_bigint_uint64 6 v10.7.0
napi_get_value_bigint_words 6 v10.7.0
napi_get_value_external 1 v8.0.0
napi_get_value_int32 1 v8.0.0
napi_get_value_int64 1 v8.0.0
napi_get_value_string_latin1 1 v8.0.0
napi_get_value_string_utf8 1 v8.0.0
napi_get_value_string_utf16 1 v8.0.0
napi_get_value_uint32 1 v8.0.0
napi_get_boolean 1 v8.0.0
napi_get_global 1 v8.0.0
napi_get_null 1 v8.0.0
napi_get_undefined 1 v8.0.0

Working with JavaScript Values and Abstract Operations

NAPI NAPI Version Minimal Node Version Status
napi_coerce_to_bool 1 v8.0.0
napi_coerce_to_number 1 v8.0.0
napi_coerce_to_object 1 v8.0.0
napi_coerce_to_string 1 v8.0.0
napi_typeof 1 v8.0.0
napi_instanceof 1 v8.0.0
napi_is_array 1 v8.0.0
napi_is_arraybuffer 1 v8.0.0
napi_is_buffer 1 v8.0.0
napi_is_date 1 v8.0.0
napi_is_error 1 v8.0.0
napi_is_typedarray 1 v8.0.0
napi_is_dataview 1 v8.3.0
napi_strict_equals 1 v8.0.0
napi_detach_arraybuffer 7 v13.3.0
napi_is_detached_arraybuffer 7 v13.3.0