The JavaScript Promise Integration (JSPI) API for WebAssembly has received a significant update, now shipping in Chrome release M126. This overhaul simplifies the developer experience, removes outdated constructs, and introduces more intuitive behavior. In this article, we break down what has changed, how to use the new API with Emscripten, and what lies ahead on the JSPI roadmap.
Understanding JSPI and Its Purpose
What Is JSPI?
JSPI bridges the gap between synchronous WebAssembly applications, often compiled from C or C++, and the asynchronous nature of many modern Web APIs. These APIs return JavaScript Promises rather than blocking until completion. JSPI allows a WebAssembly module to pause execution when a Promise is encountered and resume once that Promise resolves—all without requiring changes to the original synchronous code.
What's New in the JSPI API?
Eliminating the Suspender Object
In January 2024, the Stacks subgroup of the WebAssembly Community Group voted to revise the JSPI API. The most notable change is the removal of the explicit Suspender object. Previously, developers had to manually create and manage Suspender instances to define which parts of a computation could be suspended. Now, the JavaScript/WebAssembly boundary itself serves as the delimiter. The most recent call into a wrapped WebAssembly export determines the cut point for suspension.
This adjustment gives developers slightly less granular control over suspension boundaries, but the trade-off is a significantly simpler API. No longer do you need to track Suspender objects or worry about their lifecycle.
No More WebAssembly.Function
Another key change is the departure from using the WebAssembly.Function constructor to create JSPI wrappers. Instead, the API now provides dedicated functions and constructors tailored specifically for JSPI. This shift offers several benefits:
- It eliminates the dependency on the Type Reflection Proposal, which was required for the old approach.
- It simplifies tooling—the new API functions no longer need to explicitly reference WebAssembly type information.
This simplification was made possible by the removal of the Suspender object, which previously required type-level annotations.
Smarter Suspension Behavior
The third major change relates to when suspension actually occurs. In the previous API, calling any JavaScript function from a suspending import would always trigger a suspension. Now, suspension only happens when the called JavaScript function returns a Promise. If the function completes synchronously, no suspension occurs.
While this behavior might seem to contradict the recommendations of the W3C TAG, it represents a safe and beneficial optimization. Since JSPI acts as the caller of the function that returns a Promise, it can intelligently decide whether to suspend. Most applications will see minimal impact, but those that frequently call synchronous JavaScript functions will notice improved performance by avoiding unnecessary trips to the browser's event loop.
The Updated API in Practice
The revamped API is straightforward. You create a JSPI wrapper by calling a function that takes an exported WebAssembly function and returns a new function that returns a JavaScript Promise. Here’s a conceptual example:
// Old way (deprecated)
const wrappedFunc = new WebAssembly.Function({parameters: [], results: []}, suspendingFunc);
// New way
const wrappedFunc = jsPromiseIntegration.wrap(wasmInstance.exports.someFunction);
When using Emscripten, the compiler now automatically handles these wrappers for many common patterns. You can rely on Emscripten’s -sASYNCIFY flag to manage the integration seamlessly. However, if you need manual control, the new API is accessible through the global WebAssembly.JSPI object (or similar, depending on the implementation).
Looking Ahead: Roadmap and Migration
The JSPI specification continues to evolve. The Chrome team at Google has indicated that future releases will further stabilize the API, with a focus on performance and broader browser support. Developers currently using the old API should plan to migrate to the new design as soon as possible. The changes are backward-incompatible, but the migration path is clear:
- Remove any manual
Suspenderobject creation and usage. - Replace
WebAssembly.Functionwrappers with the new JSPI-specific functions. - Test your application to ensure suspension behavior matches expectations—especially if you relied on the old eager-suspension model.
For more detailed information, refer to the JSPI specification and the original Chrome announcement.
By embracing these changes, developers can build more efficient and maintainable WebAssembly applications that seamlessly interact with the asynchronous web platform.