wasm_bindgen_struct/

lib.rs

//! A crate to make working with [`wasm-bindgen`](https://crates.io/crates/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
//!
//! ```rust
//! // 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;
//!
//! # use wasm_bindgen::prelude::*;
//!
//! #[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:
//!
//! ```rust
//! # use wasm_bindgen::prelude::*;
//!
//! // 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
//!   ```rust
//!   # use wasm_bindgen_struct::wasm_bindgen_struct;
//!   # use wasm_bindgen::prelude::*;
//!   
//!   #[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`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/extends.html)
//! - [getter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/getter-and-setter.html)
//! - [setter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/getter-and-setter.html)
//! - [final_: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/final.html)
//! - [js_name: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/js_name.html)
//! - [js_namespacejsnamespace: Vec: `[Lit1, Lit2, Lit3, ...]`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/js_namespace.html)
//! - [module: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/module.html)
//! - [raw_module: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/raw_module.html)
//! - _`<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`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/getter-and-setter.html)
//! - [setter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/getter-and-setter.html)
//! - [structural: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/structural.html)
//! - [final_: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/final.html)
//! - [js_name: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/js_name.html)
//!
//! # `#[opts(...)]` on `impl`
//!
//! - dbg: bool
//!
//!   Show the formatted output of the macro as a warning
//! - [final_: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/final.html)
//! - [js_name: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/js_name.html)
//! - [js_namespace: `[Lit1, Lit2, Lit3, ...]`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/js_namespace.html)
//! - [module: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/module.html)
//! - [raw_module: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/raw_module.html)
//!
//! # `#[opts(...)]` on `impl` methods
//!
//! - [constructor: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/constructor.html)
//! - [final_: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/final.html)
//! - [structural: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/structural.html)
//! - [getter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/getter-and-setter.html)
//! - [setter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/getter-and-setter.html)
//! - [indexing_getter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/indexing-getter-setter-deleter.html)
//! - [indexing_setter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/indexing-getter-setter-deleter.html)
//! - [indexing_deleter: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/indexing-getter-setter-deleter.html)
//! - [js_name: `Lit`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/js_name.html)
//! - [variadic: `bool`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/variadic.html)
//!
//! # Treatment of Special Types
//! - `Result<T, E>`
//!
//!   Implies [`catch`](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/catch.html).
//! - `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
//!
//!   ```rust
//!   # use wasm_bindgen::prelude::*;
//!   # use wasm_bindgen_struct::wasm_bindgen_struct;
//!   
//!   #[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.

#[macro_use]
extern crate proc_macro_error;

#[macro_use]
mod utils;
mod exts;
mod model;

use crate::model::Model;
use proc_macro_error::proc_macro_error;
use quote::ToTokens;

#[proc_macro_attribute]
#[proc_macro_error]
pub fn wasm_bindgen_struct(
  _: proc_macro::TokenStream,
  input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
  let model = syn::parse_macro_input!(input as Model);

  model.to_token_stream().into()
}

#[cfg(test)]
mod macro_tests {
  use super::*;
  use crate::exts::TokenStreamExt;

  #[track_caller]
  fn parse_model(input: proc_macro2::TokenStream) -> proc_macro2::TokenStream {
    let model = syn::parse2::<Model>(input).unwrap();

    model.to_token_stream()
  }

  #[track_caller]
  fn assert_eq_token_stream(
    output: proc_macro2::TokenStream,
    expected_output: proc_macro2::TokenStream,
  ) {
    let left = output.to_pretty();
    let right = expected_output.to_pretty();

    let theme = termdiff::SignsColorTheme::default();

    let diff = termdiff::DrawDiff::new(&right, &left, &theme);

    assert_eq!(left, right, "\n\n{diff}");
  }

  fn test_macro(
    input: proc_macro2::TokenStream,
    expected_output: proc_macro2::TokenStream,
  ) {
    let output = parse_model(input);

    assert_eq_token_stream(output, expected_output);
  }

  #[test]
  fn simple_struct() {
    test_macro(
      quote! {
        struct JsType {
          my_prop_1: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          type JsType;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn my_prop_1(this: &JsType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn set_my_prop_1(this: &JsType, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_with_field_rename() {
    test_macro(
      quote! {
        struct JsType {
          #[opts(js_name = "prop")]
          my_prop_1: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          type JsType;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "prop")]
          fn my_prop_1(this: &JsType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "prop")]
          fn set_my_prop_1(this: &JsType, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_on_other_type() {
    test_macro(
      quote! {
        #[opts(on = SomeType)]
        struct JsType {
          my_prop_1: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn my_prop_1(this: &SomeType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn set_my_prop_1(this: &SomeType, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_final_and_structural() {
    test_macro(
      quote! {
        #[opts(final_)]
        struct JsType {
          my_prop_1: String,
          #[opts(structural)]
          prop: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          type JsType;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "myProp1")]
          #[wasm_bindgen(final)]
          fn my_prop_1(this: &JsType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "myProp1")]
          #[wasm_bindgen(final)]
          fn set_my_prop_1(this: &JsType, value: String);

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "prop")]
          fn prop(this: &JsType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "prop")]
          fn set_prop(this: &JsType, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_only_get_set() {
    test_macro(
      quote! {
        struct JsType {
          #[opts(getter)]
          my_prop_1: String,
          #[opts(setter)]
          prop: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          type JsType;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn my_prop_1(this: &JsType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "prop")]
          fn set_prop(this: &JsType, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_global_setter_with_local_getter() {
    test_macro(
      quote! {
        #[opts(setter)]
        struct JsType {
          #[opts(getter)]
          my_prop_1: String,
          prop: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          type JsType;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn my_prop_1(this: &JsType) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "myProp1")]
          fn set_my_prop_1(this: &JsType, value: String);

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "prop")]
          fn set_prop(this: &JsType, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_js_class() {
    test_macro(
      quote! {
        #[opts(js_name = "String")]
        struct JsString {
          prop: String,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          #[wasm_bindgen(js_name = "String")]
          type JsString;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_class = "String")]
          #[wasm_bindgen(js_name = "prop")]
          fn prop(this: &JsString) -> String;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_class = "String")]
          #[wasm_bindgen(js_name = "prop")]
          fn set_prop(this: &JsString, value: String);
        }
      },
    );
  }

  #[test]
  fn struct_extends() {
    test_macro(
      quote! {
        #[opts(js_name = "String")]
        #[opts(extends = Object)]
        struct JsString {}
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          #[wasm_bindgen(js_name = "String")]
          #[wasm_bindgen(extends = Object)]
          type JsString;
        }
      },
    );
  }

  #[test]
  fn struct_can_use_self_ty() {
    test_macro(
      quote! {
        struct JsType {
          a: Self,
        }
      },
      quote! {
        #[::wasm_bindgen::prelude::wasm_bindgen]
        extern "C" {
          type JsType;

          #[wasm_bindgen(method, getter)]
          #[wasm_bindgen(js_name = "a")]
          fn a(this: &JsType) -> JsType;

          #[wasm_bindgen(method, setter)]
          #[wasm_bindgen(js_name = "a")]
          fn set_a(this: &JsType, value: JsType);
        }
      },
    );
  }

  #[test]
  fn simpl_impl() {
    test_macro(
      quote! {
        impl JsType {
          fn example(&self);
        }
      },
      quote! {
        impl JsType {
          fn example(&self) {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(method)]
              #[wasm_bindgen(js_name = "example")]
              fn example_js(this: &JsType);
            }

            self.example_js()
          }
        }
      },
    );
  }

  #[test]
  fn impl_static() {
    test_macro(
      quote! {
        impl JsType {
          fn example();
        }
      },
      quote! {
        impl JsType {
          fn example() {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(static_method_of = JsType)]
              #[wasm_bindgen(js_name = "example")]
              fn example_js();
            }

            Self::example_js()
          }
        }
      },
    );
  }

  #[test]
  fn impl_can_map_value() {
    test_macro(
      quote! {
        impl JsType {
          fn example(&self) -> MapValue<T, U>;
        }
      },
      quote! {
        impl JsType {
          fn example(&self) -> U {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(method)]
              #[wasm_bindgen(js_name = "example")]
              fn example_js(this: &JsType) -> T;
            }

            self.example_js()
          }
        }
      },
    );
  }

  #[test]
  fn impl_can_async_with_args_can_map_value() {
    test_macro(
      quote! {
        impl JsType {
          async fn example(&self, a: String) -> MapValue<T, U>;
        }
      },
      quote! {
        impl JsType {
          async fn example(&self, a: String) -> U {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(method)]
              #[wasm_bindgen(js_name = "example")]
              async fn example_js(this: &JsType, a: String) -> T;
            }

            self.example_js(a).await
          }
        }
      },
    );
  }

  #[test]
  fn impl_can_async_with_args_can_map_value_with_block() {
    test_macro(
      quote! {
        impl JsType {
          async fn example(&self, a: String) -> MapValue<T, U> {
            self.example_js(a).await.into()
          }
        }
      },
      quote! {
        impl JsType {
          async fn example(&self, a: String) -> U {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(method)]
              #[wasm_bindgen(js_name = "example")]
              async fn example_js(this: &JsType, a: String) -> T;
            }

            self.example_js(a).await.into()
          }
        }
      },
    );
  }

  #[test]
  fn impl_with_result_catches() {
    test_macro(
      quote! {
        impl JsType {
          fn example(&self) -> Result<String, JsValue>;
        }
      },
      quote! {
        impl JsType {
          fn example(&self) -> Result<String, JsValue> {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(method)]
              #[wasm_bindgen(js_name = "example")]
              #[wasm_bindgen(catch)]
              fn example_js(this: &JsType) -> Result<String, JsValue>;
            }

            self.example_js()
          }
        }
      },
    );
  }

  #[test]
  fn impl_with_map_value_result_catches() {
    test_macro(
      quote! {
        impl JsType {
          async fn example(&self) -> MapValue<
            Result<JsValue, JsValue>,
            Result<String, JsValue>,
          >;
        }
      },
      quote! {
        impl JsType {
          async fn example(&self) -> Result<String, JsValue> {
            #[::wasm_bindgen::prelude::wasm_bindgen]
            extern "C" {
              #[wasm_bindgen(method)]
              #[wasm_bindgen(js_name = "example")]
              #[wasm_bindgen(catch)]
              async fn example_js(this: &JsType) -> Result<JsValue, JsValue>;
            }

            self.example_js().await
          }
        }
      },
    );
  }

  #[test]
  fn impl_with_module_gets_applied() {
    test_macro(
      quote! {
        #[opts(module = "my-module")]
        impl JsType {
          fn example();
        }
      },
      quote! {
        impl JsType {
          fn example() {
            #[::wasm_bindgen::prelude::wasm_bindgen(module = "my-module")]
            extern "C" {
              #[wasm_bindgen(static_method_of = JsType)]
              #[wasm_bindgen(js_name = "example")]
              fn example_js();
            }

            Self::example_js()
          }
        }
      },
    );
  }
}