Crate napi[−][src]

Expand description

High level Node.js N-API binding

napi-rs provides minimal overhead to write N-API modules in Rust.

Because Node.js 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)
}

Re-exports

pub use napi_sys as sys;

Modules

bindgen_prelude

threadsafe_function

Structs

AsyncCleanupHook

Notice The hook will be removed if AsyncCleanupHook was dropped. If you want keep the hook until node process exited, call the AsyncCleanupHook::forget.

AsyncWorkPromise

CallContext

Function call context

CleanupEnvHook

Created by Env::add_env_cleanup_hook And used by Env::remove_env_cleanup_hook

Env

Env is used to represent a context that the underlying N-API implementation can use to persist VM-specific state.

Error

Represent JsError. Return this Error in js_function, napi-rs will throw it as JsError for you. If you want throw it as TypeError or RangeError, you can use JsTypeError/JsRangeError::from(Error).throw_into(env)

Enums

Traits

NapiRaw

NapiValue

Task

Functions

noop_finalize

This function could be used for create_buffer_with_borrowed_data and want do noting when Buffer finalized.

Type Definitions

Callback

ContextlessResult

Result

Attribute Macros

module_init

Marks a function or static variable as a library/executable constructor. This uses OS-specific linker sections to call a specific function at load time.