diff --git a/examples/guide-supported-types-examples/enums.js b/examples/guide-supported-types-examples/enums.js new file mode 100644 index 00000000000..ca283869631 --- /dev/null +++ b/examples/guide-supported-types-examples/enums.js @@ -0,0 +1,27 @@ +import { + take_number, + take_string, + take_number_option, + take_string_option, + return_number, + return_string, + return_number_option, + return_string_option, + NumberEnum, + // nothing generated for StringEnum :( +} from "./guide_supported_types_examples"; + +take_number(NumberEnum.Foo); +take_string("spam"); + +take_number_option(NumberEnum.Bar); +take_number_option(undefined); + +take_string_option("eggs"); +take_string_option(undefined); + +return_number(); // typed as `NumberEnum` +return_string(); // typed as `any` + +return_number_option(); // typed as `NumberEnum | undefined` +return_string_option(); // typed as `any | undefined` diff --git a/examples/guide-supported-types-examples/src/enums.rs b/examples/guide-supported-types-examples/src/enums.rs new file mode 100644 index 00000000000..5b632fe043a --- /dev/null +++ b/examples/guide-supported-types-examples/src/enums.rs @@ -0,0 +1,47 @@ +use wasm_bindgen::prelude::*; + +#[wasm_bindgen] +pub enum NumberEnum { + // numbers are optional; default ones will be generated if not provided + Foo = 0, + Bar = 1, + Baz = 2, +} + +#[wasm_bindgen] +pub enum StringEnum { + Spam = "spam", + Eggs = "eggs", +} + +#[wasm_bindgen] +pub fn take_number(x: NumberEnum) {} + +#[wasm_bindgen] +pub fn take_string(x: StringEnum) {} + +#[wasm_bindgen] +pub fn take_number_option(x: Option) {} + +#[wasm_bindgen] +pub fn take_string_option(x: Option) {} + +#[wasm_bindgen] +pub fn return_number() -> NumberEnum { + todo!() +} + +#[wasm_bindgen] +pub fn return_string() -> StringEnum { + todo!() +} + +#[wasm_bindgen] +pub fn return_number_option() -> Option { + todo!() +} + +#[wasm_bindgen] +pub fn return_string_option() -> Option { + todo!() +} diff --git a/examples/guide-supported-types-examples/src/lib.rs b/examples/guide-supported-types-examples/src/lib.rs index 97f6bb3ede5..6d537d54d5c 100644 --- a/examples/guide-supported-types-examples/src/lib.rs +++ b/examples/guide-supported-types-examples/src/lib.rs @@ -4,6 +4,7 @@ pub mod bool; pub mod boxed_js_value_slice; pub mod boxed_number_slices; pub mod char; +pub mod enums; pub mod exported_types; pub mod imported_types; pub mod js_value; diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 5d9c362902c..ab92b5c8260 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -2,7 +2,7 @@ [Introduction](./introduction.md) --------------------------------------------------------------------------------- +--- - [Examples](./examples/index.md) - [Hello, World!](./examples/hello-world.md) @@ -32,6 +32,7 @@ - [Wasm Audio Worklet](./examples/wasm-audio-worklet.md) - [web-sys: A TODO MVC App](./examples/todomvc.md) - [Reference](./reference/index.md) + - [Deployment](./reference/deployment.md) - [JS snippets](./reference/js-snippets.md) - [Static JS Objects](./reference/static-js-objects.md) @@ -59,6 +60,7 @@ - [`char`](./reference/types/char.md) - [`str`](./reference/types/str.md) - [`String`](./reference/types/string.md) + - [`enum`](./reference/types/enum.md) - [Number Slices](./reference/types/number-slices.md) - [Boxed Number Slices](./reference/types/boxed-number-slices.md) - [`Result`](./reference/types/result.md) @@ -98,6 +100,7 @@ - [`getter_with_clone`](./reference/attributes/on-rust-exports/getter_with_clone.md) - [`web-sys`](./web-sys/index.md) + - [Using `web-sys`](./web-sys/using-web-sys.md) - [Cargo Features](./web-sys/cargo-features.md) - [Function Overloads](./web-sys/function-overloads.md) @@ -106,6 +109,7 @@ - [Unstable APIs](./web-sys/unstable-apis.md) - [Testing with `wasm-bindgen-test`](./wasm-bindgen-test/index.md) + - [Usage](./wasm-bindgen-test/usage.md) - [Writing Asynchronous Tests](./wasm-bindgen-test/asynchronous-tests.md) - [Testing in Headless Browsers](./wasm-bindgen-test/browsers.md) diff --git a/guide/src/reference/types/enum.md b/guide/src/reference/types/enum.md new file mode 100644 index 00000000000..cff3755dcdc --- /dev/null +++ b/guide/src/reference/types/enum.md @@ -0,0 +1,72 @@ +# enum + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +| :-----------: | :------------: | :----------------: | :--------------: | :-------------------: | :----------------------: | :-----------------------: | +| Yes | No | No | Yes | Yes | Yes | `string` or `number` | + +## Example Rust Usage + +```rust +{{#include ../../../../examples/guide-supported-types-examples/src/enums.rs}} +``` + +## Example JavaScript Usage + +```js +{{#include ../../../../examples/guide-supported-types-examples/enums.js}} +``` + +## TypeScript + +Unfortunately, string enums don't fully work yet; no TypeScript is generated for the enum itself and functions using them accept or return `any`. +They work correctly, it's just there's no type hints. +See [Issue #3057](https://github.com/rustwasm/wasm-bindgen/issues/3057) + +The generated TypeScript declarations for the above: + + + +```ts +/** + * @param {NumberEnum} x + */ +export function take_number(x: NumberEnum): void; +/** + * @param {any} x + */ +export function take_string(x: any): void; +/** + * @param {NumberEnum | undefined} [x] + */ +export function take_number_option(x?: NumberEnum): void; +/** + * @param {any | undefined} [x] + */ +export function take_string_option(x?: any): void; +/** + * @returns {NumberEnum} + */ +export function return_number(): NumberEnum; +/** + * @returns {any} + */ +export function return_string(): any; +/** + * @returns {NumberEnum | undefined} + */ +export function return_number_option(): NumberEnum | undefined; +/** + * @returns {any | undefined} + */ +export function return_string_option(): any | undefined; +/** + */ +export enum NumberEnum { + Foo = 0, + Bar = 1, + Baz = 2, +} + +// no types generated for StringEnum (yet) :( +// see the note above +```