Crate wasm_bindgen_struct 

A crate to make working with wasm-bindgen easier.

This crate contains the wasm_bindgen_struct macro which can be used to declare wasm_bindgen types, and implement getters/setter as if they were normal rust structs. It can also be used to implement methods for the type, including inline mapping to overcome wasm-bindgen-futures limitations.

Example

// Or you can use this instead to avoid needing to import
// the macro throughout your crate
// #[macro_use]
// extern crate wasm_bindgen_struct;
use wasm_bindgen_struct::wasm_bindgen_struct;


#[wasm_bindgen_struct]
// `module` here means this type comes from the JS "my-module" module
// with the class name `aAnotherType`
#[opts(module = "my-module", js_name = "AnotherType")]
struct MyJsType {
  // field names are automatically converted to `camelCase`
  field_a: String,
  // ...but can be manually specified if needed
  #[opts(js_name = "field_b")]
  field_b: String,
}

#[wasm_bindgen_struct]
#[opts(module = "my-module")]
impl MyJsType {
  // Automatically gets the `static_method_of = MyJsType` applied,
  // as well as `catch` due to the `Result`
  fn apple() -> Result<String, JsValue>;

  // `async` functions in `wasm-bindgen` can only currently return
  // `()`, `JsValue`, or Result<_, JsValue>`, where `_` is one of
  // the two previously mentioned types. We use `MapValue<T, U>`
  // to tell the macro that the binding method should return `T`,
  // but we'll map the value to `U`
  async fn oranges(&self) -> MapValue<JsValue, String> {
    self
      .oranges_js()
      .await
      .unchecked_into::<js_sys::JsString>()
      .into()
  }
}

The above expands to:

// For getters/setters
#[wasm_bindgen(module = "my-module")]
extern "C" {
  #[wasm_bindgen(js_name = "AnotherType")]
  type MyJsType;

  #[wasm_bindgen(
    method,
    getter,
    js_class = "AnotherType",
    js_name = "fieldA"
  )]
  fn field_a(this: &MyJsType) -> String;

  #[wasm_bindgen(
    method,
    setter,
    js_class = "AnotherType",
    js_name = "fieldA"
  )]
  fn set_field_a(this: &MyJsType, value: String);

  #[wasm_bindgen(
    method,
    getter,
    js_class = "AnotherType",
    js_name = "field_b"
  )]
  fn field_b(this: &MyJsType) -> String;
  #[wasm_bindgen(
    method,
    setter,
    js_class = "AnotherType",
    js_name = "field_b"
  )]
  fn set_field_b(this: &MyJsType, value: String);
}

// And for methods
impl MyJsType {
  fn apple() -> Result<String, JsValue> {
    #[wasm_bindgen(module = "my-module")]
    extern "C" {
      #[wasm_bindgen(static_method_of = MyJsType, js_name = "apple")]
      #[wasm_bindgen(catch)]
      fn apple_js() -> Result<String, JsValue>;
    }
    Self::apple_js()
  }
  async fn oranges(&self) -> String {
    #[wasm_bindgen(module = "my-module")]
    extern "C" {
      #[wasm_bindgen(method, js_name = "oranges")]
      async fn oranges_js(this: &MyJsType) -> JsValue;
    }
    self
      .oranges_js()
      .await
      .unchecked_into::<js_sys::JsString>()
      .into()
  }
}

#[opts(...)] on structs

• dbg: bool

  Show the formatted output of the macro as a warning

• on: Type

  Allows using an existing type with the struct syntax.

  Example

   
  #[wasm_bindgen]
  extern "C" {
    type JsType;
  }
  
  #[wasm_bindgen_struct]
  #[opts(on = JsType)]
  // Struct can be named anything, it doesn't matter
  struct JsType {
    field_1: bool,
  }

• extends: Type

• getter: bool

• setter: bool

• final_: bool

• js_name: Lit

• js_namespacejsnamespace: Vec: [Lit1, Lit2, Lit3, ...]

• module: Lit

• raw_module: Lit

• <unknown>

  Unknown attributes, such as doc comments, are forwarded to the type MyType declaration, or ignored in the case of using on.

#[opts(...)] on struct fields

• getter: bool
• setter: bool
• structural: bool
• final_: bool
• js_name: Lit

#[opts(...)] on impl

• dbg: bool

  Show the formatted output of the macro as a warning

• final_: bool

• js_name: Lit

• js_namespace: [Lit1, Lit2, Lit3, ...]

• module: Lit

• raw_module: Lit

#[opts(...)] on impl methods

• constructor: bool
• final_: bool
• structural: bool
• getter: bool
• setter: bool
• indexing_getter: bool
• indexing_setter: bool
• indexing_deleter: bool
• js_name: Lit
• variadic: bool

Treatment of Special Types

• Result<T, E>

  Implies catch.

• MapValue<T, U>

  Allows specifing the types of the generated wasm-bindgen binding, as well as the actual method type. This allows arbitrary transformations between the bound method and the output method.

  Example

   
  #[wasm_bindgen_struct]
  struct JsType;
  
  #[wasm_bindgen_struct]
  impl JsType {
    async fn get_async_string(&self) -> MapValue<JsValue, String> {
      self
        .get_async_string_js()
        .await
        .unchecked_into::<js_sys::JsString>()
        .into()
    }
  }

  Important note

  MapValue is a pseudo-type which only exists within the macro’s scope. i.e., this type does not exist outside of #[wasm_bindgen_struct] impl { /* ... */ } and therefore does not need to be imported.

Attribute Macros

wasm_bindgen_struct