| 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. |