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 Vec<u8> and JsArrayBuffer
• Boxed
  Wrapper to extract T from a JsBox<T> or create a JsBox from a T.
• Buffer
  Wrapper for converting between Vec<u8> and JsBuffer
• Datenapi-5
  Wrapper for converting between f64 and JsDate
• Error
  Error that implements TryIntoJs and can produce specific error types.
• Jsonserde
  Wrapper for converting between T and JsValue by serializing with JSON.
• TypeExpected
  Error returned when a JavaScript value is not the type expected
• With
  Wraps a closure that will be lazily evaluated when TryIntoJs::try_into_js is called.

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