Type Mapping (JS ↔ Rust)

Fresh 🌱

How JavaScript types correspond to Neon's Js* handle types and the Rust values you build them from or read them into.

Primitives

JavaScript	Neon handle type	Build from Rust	Read into Rust
number	JsNumber	cx.number(x) where x: f64-compatible	.value(&mut cx) → f64
string	JsString	cx.string(&s)	.value(&mut cx) → String
boolean	JsBoolean	cx.boolean(b)	.value(&mut cx) → bool
null	JsNull	cx.null()	-
undefined	JsUndefined	cx.undefined()	-

Objects & collections

JavaScript	Neon handle type	Notes
{} object	JsObject	get/set via the Object trait
[] array	JsArray	cx.empty_array(); len, to_vec, indexed get/set
Buffer	JsBuffer	cx.buffer(n)?
ArrayBuffer	JsArrayBuffer	cx.array_buffer(n)?
typed array	JsTypedArray<T>	as_slice(&cx) / as_mut_slice(&lock) for zero-copy access
Date	JsDate	requires a sufficient napi-N feature

Functions & special

JavaScript	Neon handle type	Notes
function	JsFunction	bind(), call_with(), construct_with()
Promise	JsPromise	from cx.promise() or cx.task(...).promise(...)
any value	JsValue	the supertype; use when you do not need to narrow the type
boxed Rust data	JsBox<T>	opaque to JS; T: Finalize

The umbrella types

Type	Meaning
Handle<'a, T>	a safe, lifetime-tracked reference to a JS value of type T
JsResult<'a, T>	Result<Handle<'a, T>, Throw> - a function that may throw
NeonResult<T>	Result<T, Throw> - used by #[neon::main] and non-handle returns
Root<T>	a persistent reference that survives across threads/async

Argument extraction (with #[neon::export])

When using the macro, plain Rust types convert automatically:

Rust parameter type	Accepts JavaScript
f64	number
String	string
bool	boolean
Option<T>	T or a missing/undefined trailing argument
(A, B, ...) via cx.args()	a positional argument list

Narrow only as much as you need

Read an argument as JsValue when you just need to pass it through, or as a specific Js* type when you want Neon to type-check it for you (and throw a TypeError if it does not match).