Crate napi

High level Node.js N-API binding

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

Feature flags

napi1 ~ napi10

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: Node-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::bindgen_prelude::*;
use tokio;

#[napi]
pub fn tokio_readfile(js_filepath: String) -> Result<Buffer> {
    ctx.env.spawn_future_with_callback(
        tokio::fs::read(js_filepath)
          .map(|v| v.map_err(|e| Error::new(Status::Unknown, format!("failed to read file, {}", e)))),
        |_, data| data.into(),
    )
}

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,
}

#[napi]
fn deserialize_from_js(arg0: JsUnknown) -> Result<JsUndefined> {
    let de_serialized: AnObject = ctx.env.from_js_value(arg0)?;
    ...
}

#[napi]
fn serialize(env: Env) -> Result<JsUnknown> {
    let value = AnyObject { a: 1, b: vec![0.1, 2.22], c: "hello" };
    env.to_js_value(&value)
}

Re-exports

pub extern crate anyhow;

pub extern crate ctor;

pub extern crate futures_core;

pub extern crate tokio;

pub extern crate tokio_stream;

pub use crate::bindgen_prelude::KeyCollectionMode;

pub use crate::bindgen_prelude::KeyConversion;

pub use crate::bindgen_prelude::KeyFilter;

pub use napi_sys as sys;

Modules

bindgen_prelude

iterator

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

De

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)

ExtendedErrorInfo

JSON

JsArrayBufferDeprecated

JsArrayBufferValueDeprecated

JsBigIntDeprecated

JsBooleanDeprecated

JsBufferDeprecated

JsBufferValueDeprecated

JsDataView

JsDataViewValue

JsDate

JsDeferred

JsError

JsExternal

Represent the Node-API External value

JsFunctionDeprecated

JsGlobal

JsNullDeprecated

JsNumber

JsObjectDeprecated

JsRangeError

JsString

JsStringLatin1

JsStringUtf8

JsStringUtf16

JsSymbol

represent Symbol value in JavaScript

JsSyntaxError

JsTimeout

JsTypeError

JsTypedArrayDeprecated

JsTypedArrayValueDeprecated

JsUndefinedDeprecated

NodeVersion

Property

PropertyAttributes

PropertyClosures

Ref

Ser

SymbolRef

A reference to a JavaScript Symbol.

Unknown

Represents a raw JavaScript value

UnknownRef

A reference to a unknown JavaScript value.

Enums

Either

Status

ValueType

Traits

JsValue

NapiRaw

NapiValue

ScopedTask

Basically it’s the same as the Task trait

Task

Functions

noop_finalize

This function could be used for BufferSlice::from_external and want do noting when Buffer finalized.

Type Aliases

Callback

ContextlessResult

Result