Module handle

References to garbage-collected JavaScript values.

A handle is a safe reference to a JavaScript value that is owned and managed by the JavaScript engine’s memory management system (the garbage collector).

Neon APIs that accept and return JavaScript values never use raw pointer types (*T) or reference types (&T). Instead they use the special Neon type Handle, which encapsulates a JavaScript Value and ensures that Rust only maintains access to the value while it is guaranteed to be valid.

Working with Handles

The Handle<T> type automatically dereferences to T (via the standard Deref trait), so you can call T’s methods on a value of type Handle<T>. For example, we can call JsNumber::value() on a Handle<JsNumber>:

let n: Handle<JsNumber> = cx.argument(0)?;
let v = n.value(&mut cx); // JsNumber::value()

Example

This Neon function takes an object as its argument, extracts an object property, homeAddress, and then extracts a string property, zipCode from that second object. Each JavaScript value in the calculation is stored locally in a Handle.

#[export]
fn customer_zip_code<'cx>(cx: &mut FunctionContext<'cx>, customer: Handle<'cx, JsObject>) -> JsResult<'cx, JsString> {
    let home_address: Handle<JsObject> = customer.prop(cx, "homeAddress").get()?;
    let zip_code: Handle<JsString> = home_address.prop(cx, "zipCode").get()?;
    Ok(zip_code)
}

Structs

DowncastError

An error representing a failed downcast.

Handle

A handle to a JavaScript value that is owned by the JavaScript engine.

Root

A thread-safe handle that holds a reference to a JavaScript object and prevents it from being garbage collected.

Type Aliases

DowncastResult

The result of a call to Handle::downcast().