wasm-bindgen-futuresCrate

Overview

Rust and JavaScript both have async, and neither understands the other's version of it. A Promise is a JS object that calls you back; a Rust Future is an inert value that something must poll. wasm-bindgen-futures is the adapter in both directions, and it is small enough to describe in three names:

use wasm_bindgen_futures::{future_to_promise, spawn_local, JsFuture};
use wasm_bindgen::prelude::*;

// JS promise -> Rust future, so .await works.
pub async fn awaited(promise: js_sys::Promise) -> Result<JsValue, JsValue> {
    JsFuture::from(promise).await
}

// Rust future -> JS promise, to hand back across the boundary.
pub fn exported() -> js_sys::Promise {
    future_to_promise(async { Ok(JsValue::from(1)) })
}

// Rust future -> run it, caring only about side effects.
pub fn detached() {
    spawn_local(async {
        let _ = awaited(js_sys::Promise::resolve(&JsValue::from(1))).await;
    });
}

There is no runtime here, and that is the point. On wasm32-unknown-unknown there is one thread and the host already owns the event loop, so there is nothing for a tokio-style executor to schedule. spawn_local hands a future to the browser's loop via a microtask, which is why the crate is a few hundred lines rather than a runtime — and why tokio's timers, I/O and thread pool are not available to you. Futures here make progress when the host gives the module control, and not otherwise. A loop {} waiting on a flag blocks the page and deadlocks.

In practice you rarely name the crate, because an exported async fn is converted for you:

use wasm_bindgen::prelude::*;

// JS sees a function returning a Promise. No explicit conversion needed.
#[wasm_bindgen]
pub async fn fetch_count() -> Result<u32, JsValue> {
    Ok(7)
}

The explicit functions are for the cases the attribute does not cover: awaiting a promise you were given, and starting work from a non-async context such as an event handler.

One structural note on 0.4.79: the crate has become mostly a re-export, with JsFuture, spawn_local and future_to_promise now implemented in js-sys under js_sys::futures. Importing them from here still works and remains the documented path, so nothing needs changing — it is worth knowing only if you wonder why the source is so short. It is released in lockstep with wasm-bindgen, MSRV is 1.81, and no_std works by turning off the default std feature.

When to use it

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use wasm_bindgen_futures::JsFuture;
use web_sys::{window, Response};

pub async fn fetch_body(url: &str) -> Result<String, JsValue> {
    let window = window().ok_or("no window")?;

    // fetch returns a Promise; JsFuture makes it awaitable.
    let response: Response = JsFuture::from(window.fetch_with_str(url))
        .await?
        .dyn_into()?;

    // So does .text(), so there are two awaits in one request.
    let body = JsFuture::from(response.text()?).await?;
    Ok(body.as_string().unwrap_or_default())
}

use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::spawn_local;

async fn save(value: String) -> Result<(), JsValue> {
    let _ = value;
    Ok(())
}

#[wasm_bindgen]
pub fn on_submit(value: String) {
    // The handler returns immediately; the future runs on the event loop.
    spawn_local(async move {
        if let Err(error) = save(value).await {
            web_sys::console::error_1(&error);
        }
    });
}

use wasm_bindgen::prelude::*;

// The attribute does the conversion: JS gets a Promise.
#[wasm_bindgen]
pub async fn compute(input: u32) -> Result<u32, JsValue> {
    if input == 0 {
        return Err(JsValue::from("input must be non-zero"));
    }
    Ok(input * 2)
}

// The explicit form, for a future you already have.
#[wasm_bindgen]
pub fn compute_promise(input: u32) -> js_sys::Promise {
    wasm_bindgen_futures::future_to_promise(async move {
        Ok(JsValue::from(input * 2))
    })
}

API map

Four items, and the constraint they all operate under.

use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::JsFuture;

pub async fn resolve_and_reject() -> Result<JsValue, JsValue> {
    // A resolved promise yields its value...
    let value = JsFuture::from(js_sys::Promise::resolve(&JsValue::from(1))).await?;

    // ...and a rejected one becomes Err, carrying whatever JS threw.
    let failure = JsFuture::from(js_sys::Promise::reject(&JsValue::from("no"))).await;
    assert!(failure.is_err());

    Ok(value)
}

use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::spawn_local;

#[wasm_bindgen]
pub fn start_work() {
    spawn_local(async {
        let result = Work::run().await;
        // Nothing receives this, so log rather than return.
        web_sys::console::log_1(&JsValue::from(result));
    });
}

struct Work;

impl Work {
    async fn run() -> u32 {
        42
    }
}

use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::future_to_promise;

#[wasm_bindgen]
pub fn deferred(fail: bool) -> js_sys::Promise {
    future_to_promise(async move {
        if fail {
            // Becomes a rejected promise.
            Err(JsValue::from("rejected"))
        } else {
            Ok(JsValue::from("resolved"))
        }
    })
}

use wasm_bindgen_futures::spawn_local;

pub fn concurrency() {
    // Two futures can be in flight: both are handed to the event loop.
    spawn_local(async { let _ = 1; });
    spawn_local(async { let _ = 2; });

    // What cannot happen: parallelism, blocking, or a thread.
    // No tokio::time::sleep, no std::thread::spawn, no block_on.
}