Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/reference/js-promises-and-rust-futures.md

raw
1 # Working with a JS `Promise` and a Rust `Future`
2
3 Many APIs on the web work with a `Promise`, such as an `async` function in JS.
4 Naturally you'll probably want to interoperate with them from Rust! To do that
5 you can use the `wasm-bindgen-futures` crate as well as Rust `async`
6 functions.
7
8 The first thing you might encounter is the need for working with a `Promise`.
9 For this you'll want to use [`js_sys::Promise`]. Once you've got one of those
10 values you can convert that value to `wasm_bindgen_futures::JsFuture`. This type
11 implements the `std::future::Future` trait which allows naturally using it in an
12 `async` function. For example:
13
14 [`js_sys::Promise`]: https://docs.rs/js-sys/*/js_sys/struct.Promise.html
15
16 ```rust
17 async fn get_from_js() -> Result<JsValue, JsValue> {
18 let promise = js_sys::Promise::resolve(&42.into());
19 let result = wasm_bindgen_futures::JsFuture::from(promise).await?;
20 Ok(result)
21 }
22 ```
23
24 Here we can see how converting a `Promise` to Rust creates a `impl Future<Output
25 = Result<JsValue, JsValue>>`. This corresponds to `then` and `catch` in JS where
26 a successful promise becomes `Ok` and an erroneous promise becomes `Err`.
27
28 You can also import a JS async function directly with a `extern "C"` block, and
29 the promise will be converted to a future automatically. For now the return type
30 must be `JsValue` or no return at all:
31
32 ```rust
33 #[wasm_bindgen]
34 extern "C" {
35 async fn async_func_1() -> JsValue;
36 async fn async_func_2();
37 }
38 ```
39
40 The `async` can be combined with the `catch` attribute to manage errors from the
41 JS promise:
42
43 ```rust
44 #[wasm_bindgen]
45 extern "C" {
46 #[wasm_bindgen(catch)]
47 async fn async_func_3() -> Result<JsValue, JsValue>;
48 #[wasm_bindgen(catch)]
49 async fn async_func_4() -> Result<(), JsValue>;
50 }
51 ```
52
53 Next up you'll probably want to export a Rust function to JS that returns a
54 promise. To do this you can use an `async` function and `#[wasm_bindgen]`:
55
56 ```rust
57 #[wasm_bindgen]
58 pub async fn foo() {
59 // ...
60 }
61 ```
62
63 When invoked from JS the `foo` function here will return a `Promise`, so you can
64 import this as:
65
66 ```js
67 import { foo } from "my-module";
68
69 async function shim() {
70 const result = await foo();
71 // ...
72 }
73 ```
74
75 ## Return values of `async fn`
76
77 When using an `async fn` in Rust and exporting it to JS there's some
78 restrictions on the return type. The return value of an exported Rust function
79 will eventually become `Result<JsValue, JsValue>` where `Ok` turns into a
80 successfully resolved promise and `Err` is equivalent to throwing an exception.
81
82 The following types are supported as return types from an `async fn`:
83
84 * `()` - turns into a successful `undefined` in JS
85 * `T: Into<JsValue>` - turns into a successful JS value
86 * `Result<(), E: Into<JsValue>>` - if `Ok(())` turns into a successful
87 `undefined` and otherwise turns into a failed promise with `E` converted to a
88 JS value
89 * `Result<T: Into<JsValue>, E: Into<JsValue>>` - like the previous case except
90 both data payloads are converted into a `JsValue`.
91
92 Note that many types implement being converted into a `JsValue`, such as all
93 imported types via `#[wasm_bindgen]` (aka those in `js-sys` or `web-sys`),
94 primitives like `u32`, and all exported `#[wasm_bindgen]` types. In general,
95 you should be able to write code without having too many explicit conversions,
96 and the macro should take care of the rest!
97
98 ## Using `wasm-bindgen-futures`
99
100 The `wasm-bindgen-futures` crate bridges the gap between JavaScript `Promise`s
101 and Rust `Future`s. Its `JsFuture` type provides conversion from a JavaScript
102 `Promise` into a Rust `Future`, and its `future_to_promise` function converts a
103 Rust `Future` into a JavaScript `Promise` and schedules it to be driven to
104 completion.
105
106 Learn more:
107
108 * [`wasm_bindgen_futures` on crates.io][crate]
109 * [`wasm-bindgen-futures` API documentation and example usage][docs]
110
111 [crate]: https://crates.io/crates/wasm-bindgen-futures
112 [docs]: https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen_futures/
113
114 ## Compatibility with versions of `Future`
115
116 The current crate on crates.io, `wasm-bindgen-futures 0.4.*`, supports
117 `std::future::Future` and `async`/`await` in Rust. This typically requires Rust
118 1.39.0+ (as of this writing on 2019-09-05 it's the nightly channel of Rust).
119
120 If you're using the `Future` trait from the `futures` `0.1.*` crate then you'll
121 want to use the `0.3.*` track of `wasm-bindgen-futures` on crates.io.