High level NodeJS N-API binding
napi-rs provides minimal overhead to write N-API modules in Rust.
Feature flags
napi1 ~ napi7
Because NodeJS N-API has versions. So there are feature flags to choose what version of N-API you want to build for.
For example, if you want build a library which can be used by node@10.17.0, you should choose the napi5 or lower.
The details of N-API versions and support matrix: n_api_version_matrix
tokio_rt
With tokio_rt feature, napi-rs provides a tokio runtime in an additional thread.
And you can easily run tokio future in it and return promise.
use futures::prelude::*;
use napi::{CallContext, Error, JsObject, JsString, Result, Status};
use tokio;
#[js_function(1)]
pub fn tokio_readfile(ctx: CallContext) -> Result<JsObject> {
let js_filepath = ctx.get::<JsString>(0)?;
let path_str = js_filepath.as_str()?;
ctx.env.execute_tokio_future(
tokio::fs::read(path_str.to_owned())
.map(|v| v.map_err(|e| Error::new(Status::Unknown, format!("failed to read file, {}", e)))),
|&mut env, data| env.create_buffer_with_data(data),
)
}
Tokio channel in napi-rs buffer size is default 100.
You can adjust it via NAPI_RS_TOKIO_CHANNEL_BUFFER_SIZE environment variable
NAPI_RS_TOKIO_CHANNEL_BUFFER_SIZE=1000 node ./app.js
latin1
Decode latin1 string from JavaScript using encoding_rs.
With this feature, you can use JsString.as_latin1_string function
serde-json
Enable Serialize/Deserialize data cross JavaScript Object and Rust struct.
#[derive(Serialize, Debug, Deserialize)]
struct AnObject {
a: u32,
b: Vec<f64>,
c: String,
}
#[js_function(1)]
fn deserialize_from_js(ctx: CallContext) -> Result<JsUndefined> {
let arg0 = ctx.get::<JsUnknown>(0)?;
let de_serialized: AnObject = ctx.env.from_js_value(arg0)?;
...
}
#[js_function]
fn serialize(ctx: CallContext) -> Result<JsUnknown> {
let value = AnyObject { a: 1, b: vec![0.1, 2.22], c: "hello" };
ctx.env.to_js_value(&value)
}