# Type conversions

Every exported argument must implement FromNapiValue (or one of the reference conversion traits), and every returned value must implement ToNapiValue. The generated TypeScript type is useful documentation, but the Rust trait implementation is what determines whether a conversion is actually available.

This reference describes napi-rs v3's bindgen runtime. For the lower-level handles such as JsString and JsObject, see Env and low-level values.

# Direction legend

# Primitive values

i64 deliberately maps to number, while i64n maps to bigint. Prefer the wrapper only when the JavaScript API is intended to expose a BigInt.

#[napi]
pub fn inspect_bigint(value: BigInt) -> Result<u64> {
  let (negative, narrowed, lossless) = value.get_u64();
  if negative || !lossless {
    return Err(Error::from_reason("value does not fit in u64"));
  }
  Ok(narrowed)
}

The return type above is bigint because u64 is a BigInt output type.

# Option, null, and undefined

Option<T> has an intentionally asymmetric mapping:

Use Null or Undefined when the distinction itself is part of the API. Use Either<T, Null> or Either<T, Undefined> when exactly one nullish value is accepted.

#[napi]
pub fn optional_name(value: Option<String>) -> Option<String> {
  value.filter(|name| !name.is_empty())
}

#[napi]
pub fn null_but_not_undefined(value: Either<String, Null>) -> bool {
  matches!(value, Either::B(Null))
}

# Unions with Either

Either<A, B> through Either26<A, ..., Z> map to TypeScript unions. On input, napi-rs tests variants from left to right with each type's ValidateNapiValue implementation, then converts the first match.

#[napi]
pub fn normalize_id(value: Either<u32, String>) -> String {
  match value {
    Either::A(number) => number.to_string(),
    Either::B(text) => text,
  }
}

export function normalizeId(value: number | string): string

Order overlapping alternatives from most specific to least specific. Validation for a plain Object, for example, cannot prove a complete object schema. Either is a runtime union, not a serde-style untagged enum with backtracking after arbitrary user code.

# Arrays, tuples, maps, and sets

Conversion of Vec<T> and collections is O(n). Use scoped Array, Object, typed-array views, or a stream when you need incremental access rather than an owned copy.

# Objects, classes, and custom shapes

Do not treat a class as an object shape. A normal read-write public class field needs both output conversion for its getter and input conversion for its setter; a readonly field needs only output conversion, while a skipped class field has no accessor. For nested class values, accept &T, ClassInstance<T>, or use Array::get_ref; Vec<T> requires an owned FromNapiValue implementation and is therefore not the way to accept a list of class instances.

See Classes, Objects, Enums, and #[napi] attributes for shape-specific examples.

# Buffers, ArrayBuffers, and typed arrays

External buffers and ArrayBuffers can be zero-copy when the runtime accepts external backing stores. A runtime may reject external buffers; constructors such as BufferSlice::from_data then fall back to a copy. Do not promise zero-copy behavior across every Node-compatible runtime. See Typed arrays and Understanding lifetime.

# Dates and serde JSON

serde_json::Value is not a lossless representation of arbitrary JavaScript. In particular, a large input BigInt may become a JSON number when it fits or a decimal string when it does not. Use BigInt when BigInt identity and exact narrowing rules matter.

serde-json-ordered additionally enables serde_json's preserve_order behavior.

# Functions, promises, and streams

ReadableStream::new checks that the runtime provides a global ReadableStream. Node-API 4 alone does not guarantee the Web Streams global; with_readable_stream_class accepts a compatible constructor explicitly.

# External native data

External<T> exposes an opaque, type-tagged native allocation to JavaScript. It is not serialized and its generated type is ExternalObject<T>.

• Return an owned External<T> to transfer it into a JavaScript external value.
• Accept &External<T> or &mut External<T> to borrow and type-check the wrapped value.
• Use ExternalRef<T> when Rust must keep a JavaScript reference to the external.
• External::new_with_size_hint reports native allocation size to the JavaScript garbage collector; the number is a GC accounting hint, not a memory limit.

See External for lifecycle details.

# Validation is not coercion

Most generated functions convert according to their FromNapiValue implementation. Adding #[napi(strict)] first invokes ValidateNapiValue and rejects a mismatched top-level JavaScript type. It does not coerce strings to numbers, and it does not recursively validate every property before conversion.

#[napi(return_if_invalid)] performs the same validation but returns undefined on invalid input instead of throwing. See #[napi] attributes for its constraints.

# Choosing an ownership model

Use this order of preference:

1. Use owned Rust values (String, Vec<T>, #[napi(object)]) when a copy is acceptable and the value must cross threads or await points.
2. Use scoped handles and slices (Object<'env>, Array<'env>, BufferSlice<'env>, typed-array slices) for synchronous, zero- or low-copy access.
3. Use reference-retaining wrappers (Buffer, ObjectRef, FunctionRef, Reference<T>) when JavaScript-owned data must outlive the callback.
4. Use ThreadsafeFunction to invoke JavaScript from another thread; never move a scoped JavaScript handle there.
5. Use a stream when data should be produced incrementally instead of copied into one collection.

The compiler enforces many of these boundaries through lifetimes and Send, but an unsafe method or raw Node-API handle can bypass them. Read Understanding lifetime before doing so.