Crate napi_h

High level Node.js N-API binding

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

Feature flags

napi1 ~ napi8

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;

#[napi]
pub async fn tokio_readfile(js_filepath: String) -> Result<JsBuffer> {
    ctx.env.execute_tokio_future(
        tokio::fs::read(js_filepath)
          .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),
    )
}

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 tokio;

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

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)

EscapableHandleScope

ExtendedErrorInfo

FinalizeContext

JSON

JsArrayBuffer

JsArrayBufferValue

JsBigInt

JsBoolean

JsBuffer

JsBufferValue

JsDataView

JsDataViewValue

JsDate

JsDeferred

JsError

JsExternal

JsFunction

JsGlobal

JsNull

JsNumber

JsObject

JsRangeError

JsString

JsStringLatin1

JsStringUtf8

JsStringUtf16

JsSymbol

JsSyntaxError

JsTimeout

JsTypeError

JsTypedArray

JsTypedArrayValue

JsUndefined

JsUnknown

NodeVersion

Property

PropertyAttributes

PropertyClosures

Ref

Enums

Either

KeyCollectionMode

KeyConversion

KeyFilter

Status

TypedArrayType

ValueType

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 Aliases

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.