Module extract

Traits and utilities for extract Rust data from JavaScript values.

The full list of included extractors can be found on TryFromJs.

Extracting Handles

JavaScript arguments may be extracted into a Rust tuple.

fn greet(mut cx: FunctionContext) -> JsResult<JsString> {
    let (greeting, name): (Handle<JsString>, Handle<JsString>) = cx.args()?;
    let message = format!("{}, {}!", greeting.value(&mut cx), name.value(&mut cx));

    Ok(cx.string(message))
}

Extracting Native Types

It’s also possible to extract directly into native Rust types instead of a Handle.

fn add(mut cx: FunctionContext) -> JsResult<JsNumber> {
    let (a, b): (f64, f64) = cx.args()?;

    Ok(cx.number(a + b))
}

Extracting Option

It’s also possible to mix Handle, Rust types, and even Option for handling null and undefined.

fn get_or_default(mut cx: FunctionContext) -> JsResult<JsValue> {
    let (n, default_value): (Option<f64>, Handle<JsValue>) = cx.args()?;

    if let Some(n) = n {
        return Ok(cx.number(n).upcast());
    }

    Ok(default_value)
}

Additional Extractors

In some cases, the expected JavaScript type is ambiguous. For example, when trying to extract an f64, the argument may be a Date instead of a number. Newtype extractors are provided to help.

fn add_hours(mut cx: FunctionContext) -> JsResult<JsDate> {
    const MS_PER_HOUR: f64 = 60.0 * 60.0 * 1000.0;

    let (Date(date), hours): (Date, f64) = cx.args()?;
    let date = date + hours * MS_PER_HOUR;

    cx.date(date).or_throw(&mut cx)
}

Overloaded Functions

It’s common in JavaScript to overload function signatures. This can be implemented with FunctionContext::args_opt or Context::try_catch.

fn add(mut cx: FunctionContext, a: f64, b: f64) -> Handle<JsNumber> {
    cx.number(a + b)
}

fn concat(mut cx: FunctionContext, a: String, b: String) -> Handle<JsString> {
    cx.string(a + &b)
}

fn combine(mut cx: FunctionContext) -> JsResult<JsValue> {
    if let Some((a, b)) = cx.args_opt()? {
        return Ok(add(cx, a, b).upcast());
    }

    let (a, b) = cx.args()?;

    Ok(concat(cx, a, b).upcast())
}

Note well, in this example, type annotations are not required on the tuple because Rust is able to infer it from the type arguments on add and concat.

Modules

jsonserde

Extract JavaScript values with JSON serialization

Structs

ArrayBuffer

Wrapper for converting between bytes and JsArrayBuffer

BigInt64Array

Wrapper for converting between a Rust [i64] array type and a JsBigInt64Array

BigUint64Array

Wrapper for converting between a Rust [u64] array type and a JsBigUint64Array

Boxed

Wrapper to extract T from a JsBox<T> or create a JsBox from a T.

Buffer

Wrapper for converting between bytes and JsBuffer

Datenapi-5

Wrapper for converting between f64 and JsDate

Error

Error that implements TryIntoJs and can produce specific error types.

Float32Array

Wrapper for converting between a Rust [f32] array type and a JsFloat32Array

Float64Array

Wrapper for converting between a Rust [f64] array type and a JsFloat64Array

Int8Array

Wrapper for converting between a Rust [i8] array type and a JsInt8Array

Int16Array

Wrapper for converting between a Rust [i16] array type and a JsInt16Array

Int32Array

Wrapper for converting between a Rust [i32] array type and a JsInt32Array

Jsonserde

Wrapper for converting between T and JsValue by serializing with JSON.

TypeExpected

Error returned when a JavaScript value is not the type expected

Uint8Array

Wrapper for converting between a Rust [u8] array type and a JsUint8Array

Uint16Array

Wrapper for converting between a Rust [u16] array type and a JsUint16Array

Uint32Array

Wrapper for converting between a Rust [u32] array type and a JsUint32Array

Traits

FromArgs

Trait specifying values that may be extracted from function arguments.

TryFromJs

Extract Rust data from a JavaScript value

TryIntoJs

Convert Rust data into a JavaScript value

Functions

with

Wraps a closure that will be lazily evaluated when TryIntoJs::try_into_js is called.