WebAssembly JavaScript Interface

1. Introduction

By design, the scope of the WebAssembly core specification [WEBASSEMBLY] does not include a description of how WebAssembly programs interact with their surrounding execution environment. Instead it defines an abstract embedding interface between WebAssembly and its environment, (called the embedder). It is only through this interface that an embedder interacts with the semantics of WebAssembly, and the embedder implements the connection between its host environment and the embedding API. This document describes the embedding of WebAssembly into JavaScript [ECMASCRIPT] environments, including how WebAssembly modules can be constructed and instantiated, how imported and exported functions are called, how data is exchanged, and how errors are handled. When the JavaScript environment is itself embedded in a Web browser, the Web API spec [WASMWEB] describes additional behavior relevant to the Web environment.

2. Sample API Usage

This section is non-normative.

Given demo.wat (encoded to demo.wasm):

(module
    (import "js" "import1" (func $i1))
    (import "js" "import2" (func $i2))
    (func $main (call $i1))
    (start $main)
    (func (export "f") (call $i2))
)

and the following JavaScript, run in a browser:

var importObj = {js: {
    import1: () => console.log("hello,"),
    import2: () => console.log("world!")
}};
fetch('demo.wasm').then(response =>
    response.arrayBuffer()
).then(buffer =>
    WebAssembly.instantiate(buffer, importObj)
).then(({module, instance}) =>
    instance.exports.f()
);

3. Notation

This specification depends on the Infra Standard. [INFRA]

The WebAssembly sequence type is equivalent to the list type defined there; values of one are treated as values of the other transparently.

4. Internal storage

4.1. Interaction of the WebAssembly Store with JavaScript

Note: WebAssembly semantics are defined in terms of an abstract store, representing the state of the WebAssembly abstract machine. WebAssembly operations take a store and return an updated store.

Each agent has an associated store. When a new agent is created, its associated store is set to the result of store_init().

Note: In this specification, no WebAssembly-related objects, memory or addresses can be shared among agents in an agent cluster. In a future version of WebAssembly, this may change.

Elements of the WebAssembly store may be identified with JavaScript values. In particular, each WebAssembly memory instance with a corresponding Memory object is identified with a JavaScript Data Block; modifications to this Data Block are identified to updating the agent’s store to a store which reflects those changes, and vice versa.

4.2. WebAssembly JS Object Caches

Note: There are several WebAssembly objects that may have a corresponding JavaScript object. The correspondence is stored in a per-agent mapping from WebAssembly addresses to JavaScript objects. This mapping is used to ensure that, for a given agent, there exists at most one JavaScript object for a particular WebAssembly address. However, this property does not hold for shared objects.

Each agent is associated with the following ordered maps:

• The Memory object cache, mapping memory addresses to Memory objects.

• The Table object cache, mapping table addresses to Table objects.

• The Exported Function cache, mapping function addresses to Exported Function objects.

• The Exported GC Object cache, mapping struct addresses and array addresses to Exported GC Object objects.

• The Global object cache, mapping global addresses to Global objects.

• The Tag object cache, mapping tag addresses to Tag objects.

• The Exception object cache, mapping exception addresses to Exception objects.

• The Host value cache, mapping host addresses to values.

5. The WebAssembly Namespace

dictionary WebAssemblyInstantiatedSource {
    required