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

w3ctag/design-reviews#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.)

[othermaciej]

@fgmccabe could you proved a link to a human-readable formatted copy of the spec, if there is one? The link provided seems to be the raw source.

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

[fgmccabe]

Apologies. This is a more readable link:

https://webassembly.github.io/js-promise-integration/js-api/#jspi

It's a permalink: it will always reflect the current state of the JSPI spec.