|
1 | | -# Converting Between JavaScript `Promise`s and Rust `Future`s |
| 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::resolved(&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 | +Next up you'll probably want to export a Rust function to JS that returns a |
| 29 | +promise. To do this you can use an `async` function and `#[wasm_bindgen]`: |
| 30 | + |
| 31 | +```rust |
| 32 | +#[wasm_bindgen] |
| 33 | +pub async fn foo() { |
| 34 | + // ... |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +When invoked from JS the `foo` function here will return a `Promise`, so you can |
| 39 | +import this as: |
| 40 | + |
| 41 | +```js |
| 42 | +import { foo } from "my-module"; |
| 43 | + |
| 44 | +async function shim() { |
| 45 | + const result = await foo(); |
| 46 | + // ... |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +## Return values of `async fn` |
| 51 | + |
| 52 | +When using an `async fn` in Rust and exporting it to JS there's some |
| 53 | +restrictions on the return type. The return value of an exported Rust function |
| 54 | +will eventually become `Result<JsValue, JsValue>` where `Ok` turns into a |
| 55 | +successfully resolved promise and `Err` is equivalent to throwing an exception. |
| 56 | + |
| 57 | +The following types are supported as return types from an `async fn`: |
| 58 | + |
| 59 | +* `()` - turns into a successful `undefined` in JS |
| 60 | +* `T: Into<JsValue>` - turns into a successful JS value |
| 61 | +* `Result<(), E: Into<JsValue>>` - if `Ok(())` turns into a successful |
| 62 | + `undefined` and otherwise turns into a failed promise with `E` converted to a |
| 63 | + JS value |
| 64 | +* `Result<T: Into<JsValue>, E: Into<JsValue>>` - like the previous case except |
| 65 | + both data payloads are converted into a `JsValue`. |
| 66 | + |
| 67 | +Note that many types implement being converted into a `JsValue`, such as all |
| 68 | +imported types via `#[wasm_bindgen]` (aka those in `js-sys` or `web-sys`), |
| 69 | +primitives like `u32`, and all exported `#[wasm_bindgen]` types. In general, |
| 70 | +you should be able to write code without having too many explicit conversions, |
| 71 | +and the macro should take care of the rest! |
| 72 | + |
| 73 | +## Using `wasm-bindgen-futures` |
2 | 74 |
|
3 | 75 | The `wasm-bindgen-futures` crate bridges the gap between JavaScript `Promise`s |
4 | 76 | and Rust `Future`s. Its `JsFuture` type provides conversion from a JavaScript |
|
0 commit comments