Crate napi[−][src]

High level NodeJS N-API binding

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

Feature flags

napi1 ~ napi8

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

Re-exports

pub use napi_sys as sys;

Modules

threadsafe_function

Macros

register_moduleDeprecated

Deprecated register nodejs module

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
JsArrayBuffer
JsArrayBufferValue
JsBigint
JsBoolean
JsBuffer
JsBufferValue
JsDataView
JsDataViewValue
JsDate
JsError
JsExternal
JsFunction
JsGlobal
JsNull
JsNumber
JsObject
JsRangeError
JsString
JsStringLatin1
JsStringUtf8
JsStringUtf16
JsSymbol
JsTimeout
JsTypeError
JsTypedArray
JsTypedArrayValue
JsUndefined
JsUnknown
Module
NodeVersion
Property
Ref

Enums

Either
KeyCollectionMode
KeyConversion
KeyFilter
PropertyAttributes
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 Definitions

Callback
ContextlessResult
Result