State Persistence in Wasm

In this lesson, you will learn how to synchronize your Wasm application state with browser storage backends using asynchronous Rust drivers.

The Challenge of Volatile Memory

In a Wasm runtime, memory is ephemeral; once the instance is destroyed or the page refreshes, your heap-allocated state vanishes. To persist data, we must bridge the gap between Rust’s linear memory and the browser’s non-volatile APIs, such as localStorage or IndexedDB. Because these browser APIs are inherently asynchronous and reside outside the Wasm memory boundary, we must handle these interactions through asynchronous drivers.

Architecting the Persistence Layer

To keep your Wasm logic clean, avoid mixing storage I/O with business logic. Instead, utilize an asynchronous trait-based approach. By defining an AsyncStore trait, you can implement drivers that utilize wasm-bindgen and js-sys to bridge the Rust Future lifecycle with JavaScript Promises.

When state changes, you trigger an async operation that serializes your Rust struct (e.g., via serde) into a format the browser understands, pushes it across the FFI boundary, and awaits the confirmation of the write operation.

async fn persist_state<T: Serialize>(data: &T) -> Result<(), JsValue> {
    let serialized = serde_json::to_string(data)
        .map_err(|_| "Serialization failed")?;
    
    let storage = window().local_storage()?;
    // We await the promise returned by the browser's storage API
    JsFuture::from(storage.set_item("app_state", &serialized)?).await?;
    
    Ok(())
}

Bridging Asynchrony

Because browser storage methods return Promises, we use wasm-bindgen-futures to wrap these into Rust Futures. The crucial insight here is that while the browser writes to disk, your Wasm instance remains responsive. By using a synchronization pattern—often implemented as a background task that listens for changes in a state container—you ensure the browser's storage backend is eventually consistent with your internal memory.

Remember to handle errors gracefully; disk writes can fail (e.g., quota exceeded), and in Wasm, you must bubble these exceptions back through your async runtime to ensure your application state doesn't drift from the persisted reality.

Key Takeaway: State persistence in Wasm requires bridging the gap between volatile linear memory and persistent JS storage via async drivers that utilize wasm-bindgen-futures to reconcile Rust data structures with the browser's asynchronous I/O.