[−][src]Crate napi

High level NodeJS N-API binding

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

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_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_module

Deprecated

Deprecated register nodejs module

Structs

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. This structure is passed to native functions when they're invoked, and it must be passed back when making N-API calls. Specifically, the same `Env` that was passed in when the initial native function was called must be passed to any subsequent nested N-API calls. Caching the `Env` for the purpose of general reuse, and passing the `Env` between instances of the same addon running on different Worker threads is not allowed. The `Env` becomes invalid when an instance of a native addon is unloaded. Notification of this event is delivered through the callbacks given to `Env::add_env_cleanup_hook` and `Env::set_instance_data`.
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
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

NapiValue
Task

Type Definitions

Callback
ContextlessResult
Result