WebAssembly JSPI Gets a Streamlined API: Key Updates and Migration Guide
WebAssembly's JavaScript Promise Integration (JSPI) API has received a significant overhaul in Chrome release M126. This update simplifies the developer experience by removing explicit Suspender objects, eliminating the need for WebAssembly.Function wrappers, and optimizing when suspensions occur. Below, we answer common questions about what has changed, how to adapt existing code, and what lies ahead for JSPI.
1. What exactly is WebAssembly JSPI and why was it created?
JSPI bridges the gap between synchronous WebAssembly applications—often compiled from C or C++—and asynchronous browser APIs that return Promises. Many Web APIs, like fetch() or setTimeout(), work with Promises, but code compiled to WebAssembly typically expects blocking calls. JSPI allows such applications to suspend execution when a Promise is returned and resume when that Promise resolves, without requiring developers to rewrite their code in an async style. This makes it possible to use modern browser capabilities directly from legacy or synchronous codebases compiled to WebAssembly.
2. What are the key changes in the JSPI API available in Chrome M126?
The new API introduces three major simplifications. First, Suspender objects are gone. Instead, the JavaScript/WebAssembly boundary automatically determines which computations are suspended, reducing manual management. Second, the WebAssembly.Function constructor is no longer required; dedicated wrapper functions now handle the integration. Third, the suspension behavior has been optimized: now, a call into a JavaScript function from WebAssembly only suspends if that JavaScript function actually returns a Promise, avoiding unnecessary event-loop trips. These changes make JSPI easier to use and more performant in many cases.
3. How does the removal of Suspender objects affect my code?
Previously, you had to explicitly create and manage Suspender objects to define the “cut point” where WebAssembly execution would pause. In the new API, that cut point is automatically determined by the most recent call into a wrapped WebAssembly export. This gives you slightly less control, but in practice, the automatic behavior covers the vast majority of use cases. The benefit is a much cleaner programming model: you no longer need to allocate or pass around Suspender objects, which reduces boilerplate and potential errors. Migration typically involves removing any code that creates or references Suspender instances; the existing wrapping logic can often stay the same with minor adjustments.
4. Why was WebAssembly.Function dropped? What replaces it?
The old JSPI API relied on WebAssembly.Function, a constructor from the Type Reflection Proposal. This approach required developers to explicitly specify WebAssembly function types when creating wrappers. The new API replaces this with dedicated functions like WebAssembly.promising and constructors such as WebAssembly.Suspending. These new tools no longer depend on type reflection, making tooling simpler and more portable. For example, you can now wrap an exported WebAssembly function with WebAssembly.promising(exportedFunc) to turn it into a function that returns a Promise, without having to declare its type signature beforehand.
5. What does “returning without suspending” mean, and why is it safe?
Earlier versions of JSPI would always suspend when a WebAssembly import called a JavaScript function, even if that function returned a non-Promise value. The new behavior only triggers a suspension when the JavaScript function actually returns a Promise. This might seem to go against W3C TAG recommendations, but it is a safe optimization because JSPI acts as the caller—it can detect whether a Promise is involved. In practice, most applications won't notice the difference, but some will benefit from fewer context switches to the browser's event loop, improving performance. If your code relies on suspension even for synchronous returns, you can force a Promise by wrapping the function accordingly.
6. How can I use the new JSPI API with Emscripten, and what's the roadmap?
Emscripten has updated its toolchain to support the new JSPI API automatically. When you compile with -sJSPI=1, the generated WebAssembly module uses the latest suspension boundary and omits Suspender objects. You can then wrap exported functions using WebAssembly.promising() in your JavaScript. For the roadmap, the JSPI specification is still evolving, but the Stacks subgroup of the WebAssembly Community Group plans to finalize the API in upcoming meetings. Future enhancements may include better error handling and deeper integration with JavaScript’s async/await patterns. Keep an eye on the Stack Switching repository for the latest proposals.