0.3.1 |
|
---|---|
0.3.0 |
|
0.2.3 |
|
0.2.1 |
|
0.1.1 |
|
#8 in #node-js
55KB
1.5K
SLoC
napi-rs
This project was initialized from xray
Platform Support
Operating Systems
Linux | macOS | Windows x64 MSVC |
---|---|---|
✓ | ✓ | ✓ |
NodeJS
Node10 | Node 12 | Node13 | Node14 |
---|---|---|---|
✓ | ✓ | ✓ | ✓ |
A minimal library for building compiled Node add-ons in Rust.
This library depends on N-API and requires Node 8.9 or later. It is still pretty raw and has not been tested in a production setting.
One nice feature is that this crate allows you to build add-ons purely with the Rust toolchain and without involving node-gyp
.
Taste
#[js_function(1)] // ------> arguments length, omit for zero
fn fibonacci(ctx: CallContext) -> Result<Value<Number>> {
let n = ctx.get::<Number>(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),
}
}
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-rs = "0.1"
[build-dependencies]
napi-build = "0.1"
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",
"dependencies": {
"napi-rs": "^0.1"
},
"scripts": {
"build": "cargo build && napi",
"build-release": "cargo build --release && napi --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 [--release] .
napi [--release] ./mylib
napi [--release] ./mylib.node
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:
cd test_module
npm run build
npm test
Features table
Create JavaScript values
NAPI | NAPI Version | Minimal Node version | Status |
---|---|---|---|
Enum types | 6 | v13.7.0 | ⛔️ |
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 | Experimental | v13.3.0 | ⛔️ |
napi_is_detached_arraybuffer | Experimental | v13.3.0 | ⛔️ |
Dependencies
~0.7–4MB
~67K SLoC