JavaScript Promise Integration (JSPI)

[fgmccabe]

WebKittens

No response

Title of the proposal

JavaScript Promise Integration Proposal

URL to the spec

https://github.com/WebAssembly/js-promise-integration/blob/main/document/js-api/index.bs

URL to the spec's repository

https://github.com/WebAssembly/js-promise-integration

Issue Tracker URL

No response

Explainer URL

https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md

TAG Design Review URL

https://github.com/w3ctag/design-reviews/issues/809

Mozilla standards-positions issue URL

https://mozilla.github.io/standards-positions/#wasm-js-promise-integration

WebKit Bugzilla URL

No response

Radar URL

No response

Description

This is an integration API between WebAssembly and JavaScript. It is following the W3C WebAssembly standards process; and is currently (10/29/2024) at phase 3: we expect to be able to transition to phase 4 in the near future.

JSPI allows a WebAssembly application that issues calls to sequential APIs to access asynchronous Promise-bearing functions. For example, in the scenario where a C program that has been written using a Posix read function the actual implementation of read will be via a WebAssembly import. However, most WebAPIs are asynchronous in nature: returning a Promise when invoked and expecting the application to attach a callback to the Promise. This is not straightforward to realize when the C original source simply expects the read to complete before continuing.

JSPI allows the C program to use the read as normal; it functions by intercepting the Promise and suspending the entire C application until the Promise is fulfilled. At which point the C code is resumed with the results of the read operation.

This represents an important capability for WebAssembly code that is based on legacy APIs: it allows the code to access the asynchronous functionality in a sequential way. In particular, this allows the code to run in the main thread without causing it to block (even though the WebAssembly code is blocked: the main thread will not be).

Apart from the core application of accessing asynchronous APIs from WebAssembly, other important functionalities enabled by JSPI include dynamic loading of WebAssembly modules (again from the main thread), dynamic access to resources (via the fetch API) and so-called code-splitting (where a module is split into smaller segments that are loaded separately and patched together at run-time).

JSPI should not be confused with parallelism or threading. An application using JSPI continues to be single threaded.

JSPI does not alter the semantics of either WebAssembly or JavaScript. In particular, JSPI does not permit JS programs to be suspended via WebAssembly. In addition, because the entire WebAssembly call is suspended, it is not possible for a WebAssembly program to respond internally when being suspended. (This is the subject of a separate activity within the W3C Wasm community.)