WebAssembly JavaScript Interface

1. 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()
);

2. Internal storage

2.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.

2.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 Global object cache, mapping global addresses to Global objects.

3. The WebAssembly Namespace

dictionary WebAssemblyInstantiatedSource {
    required Module module;
    required Instance instance;
};

[Exposed=(Window,Worker,Worklet)]
namespace WebAssembly {
    boolean validate(BufferSource bytes);
    Promise<Module> compile(BufferSource bytes);

    Promise<WebAssemblyInstantiatedSource> instantiate(
        BufferSource bytes, optional object importObject);

    Promise<Instance> instantiate(
        Module moduleObject, optional object importObject);
};

To compile a WebAssembly module from source bytes bytes, perform the following steps:

Let module be module_decode(bytes). If module is error, return error.
If module_validate(module) is error, return error.
Return module.

The validate(bytes) method, when invoked, performs the following steps:

Let stableBytes be a copy of the bytes held by the buffer bytes.
Compile stableBytes as a WebAssembly module and store the results as module.
If module is error, return false.
Return true.

A Module object represents a single WebAssembly module. Each Module object has the following internal slots:

[[Module]] : a WebAssembly module
[[Bytes]] : the source bytes of [[Module]].

To construct a WebAssembly module object from a module module and source bytes bytes, perform the following steps:

Let moduleObject be a new Module object.
Set moduleObject.[[Module]] to module.
Set moduleObject.[[Bytes]] to bytes.
Return moduleObject.

To asynchronously compile a WebAssembly module from source bytes bytes, using optional task source taskSource, perform the following steps:

Let promise be a new promise.
Run the following steps in parallel:
1. Compile the WebAssembly module bytes and store the result as module.
2. Queue a task to perform the following steps. If taskSource was provided, queue the task on that task source.
  1. If module is error, reject promise with a CompileError exception.
  2. Otherwise,
    1. Construct a WebAssembly module object from module and bytes, and let moduleObject be the result.
    2. Resolve promise with moduleObject.
Return promise.

The compile(bytes) method, when invoked, performs the following steps:

Let stableBytes be a copy of the bytes held by the buffer bytes.
Asynchronously compile a WebAssembly module from stableBytes and return the result.

To read the imports from a WebAssembly module module from imports object importObject, perform the following steps:

If module.𝗂𝗆𝗉𝗈𝗋𝗍𝗌 is not an empty list, and importObject is undefined, throw a TypeError exception.
Let imports be an empty list of external values.
For each (moduleName, componentName, externtype) in module_imports(module), do
1. Let o be ? Get(importObject, moduleName).
2. If Type(o) is not Object, throw a TypeError exception.
3. Let v be ? Get(o, componentName)
4. If externtype is of the form 𝖿𝗎𝗇𝖼 functype,
  1. If IsCallable(v) is false, throw a LinkError exception.
  2. If v has a [[FunctionAddress]] internal slot, and therefore is an Exported Function,
    1. Let funcaddr be the value of v’s [[FunctionAddress]] internal slot.
    Note: The signature is checked by module_instantiate invoked below.
  3. Otherwise,
    1. Create a host function from v and functype, and let funcaddr be the result.
    2. Let index be the number of external functions in imports. This value index is known as the index of the host function funcaddr.
  4. Let externfunc be the external value 𝖿𝗎𝗇𝖼 funcaddr.
  5. Append externfunc to imports.
5. If externtype is of the form 𝗀𝗅𝗈𝖻𝖺𝗅 mut valtype,
  1. If Type(v) is Number,
    1. If valtype is 𝗂𝟨𝟦, throw a LinkError exception.
    2. Let value be ToWebAssemblyValue(v, valtype)
    3. Let store be the surrounding agent's associated store.
    4. Let (store, globaladdr) be global_alloc(store, const valtype, value).
    5. Set the surrounding agent's associated store to store.
  2. If v is a Global instance,
    1. Let globaladdr be v.[[Global]]
  3. Otherwise,
    1. Throw a LinkError exception.
  4. Let externglobal be 𝗀𝗅𝗈𝖻𝖺𝗅 globaladdr.
  5. Append externglobal to imports.
6. If externtype is of the form 𝗆𝖾𝗆 memtype,
  1. If v is not a Memory object, throw a LinkError exception.
  2. Note: module_instantiate invoked below will check the imported Memory's size against the importing module’s requirements.
  3. Let externmem be the external value 𝗆𝖾𝗆 v.[[Memory]].
  4. Append externmem to imports.
7. Otherwise, externtype is of the form 𝗍𝖺𝖻𝗅𝖾 tabletype,
  1. If v is not a Table instance, throw a LinkError exception.
  2. Note: The table’s length, etc. is checked by module_instantiate invoked below.
  3. Let tableaddr be v.[[Table]]
  4. Let externtable be the external value 𝗍𝖺𝖻𝗅𝖾 tableaddr.
  5. Append externtable to imports.
Return imports.

To create an exports object from a WebAssembly module module and instance instance, perform the following steps:

Let exportsObject be ! ObjectCreate(null).
For each pair (name, externtype) in module_exports(module),
1. Let externval be instance_export(instance, name).
2. Assert: externval is not error.
3. If externtype is of the form 𝖿𝗎𝗇𝖼 functype,
  1. Assert: externval is of the form 𝖿𝗎𝗇𝖼 funcaddr.
  2. Let 𝖿𝗎𝗇𝖼 funcaddr be externval.
  3. Let func be the result of creating a new Exported Function from funcaddr.
  4. Let value be func.
4. If externtype is of the form 𝗀𝗅𝗈𝖻𝖺𝗅 globaltype,
  1. Assert: externval is of the form 𝗀𝗅𝗈𝖻𝖺𝗅 globaladdr.
  2. Let 𝗀𝗅𝗈𝖻𝖺𝗅 globaladdr be externval.
  3. Let global be a new Global object created from globaladdr.
  4. Let value be global.
5. If externtype is of the form 𝗆𝖾𝗆 memtype,
  1. Assert: externval is of the form 𝗆𝖾𝗆 memaddr.
  2. Let 𝗆𝖾𝗆 memaddr be externval.
  3. Let memory be a new Memory object created from memaddr.
  4. Let value be memory.
6. Otherwise, externtype is of the form 𝗍𝖺𝖻𝗅𝖾 tabletype,
  1. Assert: externval is of the form 𝗍𝖺𝖻𝗅𝖾 tableaddr.
  2. Let 𝗍𝖺𝖻𝗅𝖾 tableaddr be externval.
  3. Let table be a new Table object created from tableaddr.
  4. Let value be table.
7. Let status be ! CreateDataProperty(exportsObject, name, value).
8. Assert: status is true.
Note: the validity and uniqueness checks performed during WebAssembly module validation ensure that each property name is valid and no properties are defined twice.
Perform ! SetIntegrityLevel(exportsObject, "frozen").
Return exportsObject.

To initialize an instance object instanceObject from a WebAssembly module module and instance instance, perform the following steps:

Create an exports object from module and instance and let exportsObject be the result.
Set instanceObject.[[Instance]] to instance.
Set instanceObject.[[Exports]] to exportsObject.

To instantiate the core of a WebAssembly module from a module module and imports imports, perform the following steps:

Let store be the surrounding agent's associated store.
Let result be module_instantiate(store, module, imports).
If result is error, throw an appropriate exception type:
- A LinkError exception for most cases which occur during linking.
- If the error came when running the start function, throw a RuntimeError for most errors which occur from WebAssembly, or the error object propagated from inner ECMAScript code.
- Another error type if appropriate, for example an out-of-memory exception, as documented in the WebAssembly error mapping.
Let (store, instance) be result.
Set the surrounding agent's associated store to store.
Return instance.

To asynchronously instantiate a WebAssembly module from a Module moduleObject and imports importObject, perform the following steps:

Let promise be a new promise.
Let module be moduleObject.[[Module]].
Read the imports of module with imports importObject, and let imports be the result. If this operation throws an exception, catch it, reject promise with the exception, and return promise.
Queue a task to perform the following steps:
1. Instantiate the core of a WebAssembly module module with imports, and let instance be the result. If this throws an exception, catch it, reject promise with the exception, and terminate these substeps.
2. Let instanceObject be a new Instance.
3. Initialize instanceObject from module and instance. If this throws an exception, catch it, reject promise with the exception, and terminate these substeps.
4. Resolve promise with instanceObject.
Return promise.

To instantiate a WebAssembly module from a Module moduleObject and imports importObject, perform the following steps:

Let module be moduleObject.[[Module]].
Read the imports of module with imports importObject, and let imports be the result.
Instantiate the core of a WebAssembly module module with imports, and let instance be the result.
Let instanceObject be a new Instance.
Initialize instanceObject from module and instance.
Return instanceObject.

To instantiate a promise of a module promiseOfModule with imports importObject, perform the following steps:

Let promise be a new promise
Upon fulfillment of promiseOfModule with value module:
1. Instantiate the WebAssembly module module importing importObject, and let instance be the result. If this throws an exception, catch it, reject promise with the exception, and abort these substeps.
2. Let result be a WebAssemblyInstantiatedSource dictionary with module set to module and instance set to instance.
3. Resolve promise with result.
Upon rejection of promiseOfModule with reason reason:
1. Reject promise with reason.
Return promise.

Note: It would be valid to perform certain parts of the instantiation in parallel, but several parts need to happen in the event loop, including JavaScript operations to access the importObject and execution of the start function.

The instantiate(bytes, importObject) method, when invoked, performs the following steps:

Let stableBytes be a copy of the bytes held by the buffer bytes.
Asynchronously compile a WebAssembly module from stableBytes and let promiseOfModule be the result.
Instantiate promiseOfModule with imports importObject and return the result.

The instantiate(moduleObject, importObject) method, when invoked, performs the following steps:

Asynchronously instantiate the WebAssembly module moduleObject importing importObject, and return the result.

Note: A follow-on streaming API is documented in the WebAssembly Web API.

3.1. Modules

enum ImportExportKind {
  "function",
  "table",
  "memory",
  "global"
};

dictionary ModuleExportDescriptor {
  required USVString name;
  required ImportExportKind kind;
  // Note: Other fields such as signature may be added in the future.
};

dictionary ModuleImportDescriptor {
  required USVString module;
  required USVString name;
  required ImportExportKind kind;
};

[LegacyNamespace=WebAssembly, Constructor(BufferSource bytes), Exposed=(Window,Worker,Worklet)]
interface Module {
  static sequence<ModuleExportDescriptor> exports(Module moduleObject);
  static sequence<ModuleImportDescriptor> imports(Module moduleObject);
  static sequence<ArrayBuffer> customSections(Module moduleObject, DOMString sectionName);
};

The string value of the extern type type is

"function" if type is of the form 𝖿𝗎𝗇𝖼 functype
"table" if type is of the form 𝗍𝖺𝖻𝗅𝖾 tabletype
"memory" if type is of the form 𝗆𝖾𝗆 memtype
"global" if type is of the form 𝗀𝗅𝗈𝖻𝖺𝗅 globaltype

The exports(moduleObject) method, when invoked, performs the following steps:

Let module be moduleObject.[[Module]].
Let exports be an empty list.
For each (name, type) in module_exports(module)
1. Let kind be the string value of the extern type type.
2. Let obj be a new ModuleExportDescriptor dictionary with name name and kind kind.
3. Append obj to the end of exports.
Return exports.

The imports(moduleObject) method, when invoked, performs the following steps:

Let module be moduleObject.[[Module]].
Let imports be an empty list.
For each (moduleName, name, type) in module_imports(module),
1. Let kind be the string value of the extern type type.
2. Let obj be a new ModuleImportDescriptor dictionary with module moduleName, name name and kind kind.
3. Append obj to the end of imports.
Return imports.

The customSections(moduleObject, sectionName) method, when invoked, performs the following steps:

Let bytes be moduleObject.[[Bytes]].
Let customSections be an empty list of ArrayBuffers.
For each custom section customSection in bytes, interpreted according to the module grammar,
1. Let name be the name of customSection, decoded as UTF-8.
2. Assert: name is not failure (moduleObject.[[Module]] is valid).
3. If name equals sectionName as string values,
  1. Append a new ArrayBuffer containing a copy of the bytes in bytes for the range matched by this customsec production.
Return customSections.

The Module(bytes) constructor, when invoked, performs the follwing steps:

Let stableBytes be a copy of the bytes held by the buffer bytes.
Compile the WebAssembly module stableBytes and store the result as module.
If module is error, throw a CompileError exception.
Set this.[[Module]] to module.
Set this.[[Bytes]] to stableBytes.

3.2. Instances

[LegacyNamespace=WebAssembly, Constructor(Module module, optional object importObject), Exposed=(Window,Worker,Worklet)]
interface Instance {
  readonly attribute object exports;
};

The Instance(module, importObject) constructor, when invoked, runs the following steps:

Let module be module.[[Module]].
Read the imports of module with imports importObject, and let imports be the result.
Instantiate the core of a WebAssembly module module with imports, and let instance be the result.
Initialize this from module and instance.

The getter of the exports attribute of Instance returns this.[[Exports]].

3.3. Memories

dictionary MemoryDescriptor {
  required [EnforceRange] unsigned long initial;
  [EnforceRange] unsigned long maximum;
};

[LegacyNamespace=WebAssembly, Constructor(MemoryDescriptor descriptor), Exposed=(Window,Worker,Worklet)]
interface Memory {
  unsigned long grow([EnforceRange] unsigned long delta);
  readonly attribute ArrayBuffer buffer;
};

A Memory object represents a single memory instance which can be simultaneously referenced by multiple Instance objects. Each Memory object has the following internal slots:

[[Memory]] : a memory address
[[BufferObject]] : an ArrayBuffer whose Data Block is identified with the above memory address

To create a memory buffer from a memory address memaddr, perform the following steps:

Let block be a Data Block which is identified with the underlying memory of memaddr.
Let buffer be a new ArrayBuffer whose [[ArrayBufferData]] is block and [[ArrayBufferByteLength]] is set to the length of block.
Set buffer.[[ArrayBufferDetachKey]] to "WebAssembly.Memory".
Return buffer.

To initialize a memory object memory from a memory address memaddr, perform the following steps:

Let map be the surrounding agent's associated Memory object cache.
Assert: map[memaddr] doesn’t exist.
Let buffer be a the result of creating a memory buffer from memaddr.
Set memory.[[Memory]] to memaddr.
Set memory.[[BufferObject]] to buffer.
Set map[memaddr] to memory.

To create a memory object from a memory address memaddr, perform the following steps:

Let map be the surrounding agent's associated Memory object cache.
If map[memaddr] exists,
1. Return map[memaddr].
Let memory be a new Memory.
Initialize memory from memaddr.
Return memory.

The Memory(descriptor) constructor, when invoked, performs the following steps:

let initial be descriptor["initial"].
If descriptor["maximum"] is present, let maximum be descriptor["maximum"]; otherwise, let maximum be empty.
If maximum is not empty and maximum < initial, throw a RangeError exception.
Let memtype be { min initial, max maximum }
Let store be the surrounding agent's associated store.
Let (store, memaddr) be mem_alloc(store, memtype). If allocation fails, throw a RangeError exception.
Set the surrounding agent's associated store to store.
Initialize this from memaddr.

To reset the Memory buffer of memaddr, perform the following steps:

Let map be the surrounding agent's associated Memory object cache.
Assert: map[memaddr] exists.
Let memory be map[memaddr].
Perform ! DetachArrayBuffer(memory.[[BufferObject]], "WebAssembly.Memory").
Let buffer be a the result of creating a memory buffer from memaddr.
Set memory.[[BufferObject]] to buffer.

The grow(delta) method, when invoked, performs the following steps:

Let store be the surrounding agent's associated store.
Let memaddr be this.[[Memory]].
Let ret be the mem_size(store, memaddr).
Let store be mem_grow(store, memaddr, delta).
If store is error, throw a RangeError exception.
Set the surrounding agent's associated store to store.
Reset the memory buffer of memaddr.
Return ret.

Immediately after a WebAssembly memory.grow instruction executes, perform the following steps:

If the top of the stack is not 𝗂𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 (−1), then:
1. Let frame be the current frame.
2. Assert: due to validation, frame.𝗆𝗈𝖽𝗎𝗅𝖾.𝗆𝖾𝗆𝖺𝖽𝖽𝗋𝗌[0] exists.
3. Let memaddr be the memory address frame.𝗆𝗈𝖽𝗎𝗅𝖾.𝗆𝖾𝗆𝖺𝖽𝖽𝗋𝗌[0].
4. Reset the memory buffer of memaddr.

The getter of the buffer attribute of Memory returns this.[[BufferObject]].

3.4. Tables

enum TableKind {
  "anyfunc",
  // Note: More values may be added in future iterations,
  // e.g., typed function references, typed GC references
};

dictionary TableDescriptor {
  required TableKind element;
  required [EnforceRange] unsigned long initial;
  [EnforceRange] unsigned long maximum;
};

[LegacyNamespace=WebAssembly, Constructor(TableDescriptor descriptor), Exposed=(Window,Worker,Worklet)]
interface Table {
  unsigned long grow([EnforceRange] unsigned long delta);
  Function? get([EnforceRange] unsigned long index);
  void set([EnforceRange] unsigned long index, Function? value);
  readonly attribute unsigned long length;
};

A Table object represents a single table instance which can be simultaneously referenced by multiple Instance objects. Each Table object has the following internal slots:

[[Table]] : a table address
[[Values]] : a List whose elements are either null or Exported Functions.

To initialize a table object table from a table address tableaddr, perform the following steps:

Let map be the surrounding agent's associated Table object cache.
Assert: map[tableaddr] doesn’t exist.
Let store be the surrounding agent's associated store.
Let values be a list whose length is table_size(store, tableaddr) where each element is null.
Set table.[[Table]] to tableaddr.
Set table.[[Values]] to values.
Set map[tableaddr] to table.

To create a table object from a table address tableaddr, perform the following steps:

Let map be the surrounding agent's associated Table object cache.
If map[tableaddr] exists,
1. Return map[tableaddr].
Let table be a new Table.
Initialize table from tableaddr.
Return table.

The Table(descriptor) constructor, when invoked, performs the following steps:

let initial be descriptor["initial"].
If descriptor["maximum"] is present, let maximum be descriptor["maximum"]; otherwise, let maximum be empty.
If maximum is not empty and maximum < initial, throw a RangeError exception.
Let type be the table type {𝗆𝗂𝗇 n, 𝗆𝖺𝗑 maximum} 𝖺𝗇𝗒𝖿𝗎𝗇𝖼.
Let store be the surrounding agent's associated store.
Let (store, tableaddr) be table_alloc(store, type).
Set the surrounding agent's associated store to store.
Initialize this from tableaddr.

The grow(delta) method, when invoked, performs the following steps:

Let tableaddr be this.[[Table]].
Let initialSize be the length of this.[[Values]].
Let store be the surrounding agent's associated store.
Let result be table_grow(store, tableaddr, delta).
If result is error, throw a RangeError exception.

Note: The above exception may happen due to either insufficient memory or an invalid size parameter.
Set the surrounding agent's associated store to result.
Append null to this.[[Values]] delta times.
Return initialSize.

The getter of the length attribute of Table returns the length of this.[[Values]].

The get(index) method, when invoked, performs the following steps:

Let values be this.[[Values]].
Let size be the length of values.
If index ≥ size, throw a RangeError exception.
Return values[index].

The set(index, value) method, when invoked, performs the following steps:

Let tableaddr be this.[[Table]].
Let values be this.[[Values]].
If value is null, let funcaddr be an empty function element.
Otherwise,
1. If value does not have a [[FunctionAddress]] internal slot, throw a TypeError exception.
2. Let funcaddr be value.[[FunctionAddress]].
Let store be the surrounding agent's associated store.
Let store be table_write(store, tableaddr, index, funcaddr).
If store is error, throw a RangeError exception.
Set the surrounding agent's associated store to store.
Set values[index] to value.
Return undefined.

3.5. Globals

enum ValueType {
  "i32",
  "i64",
  "f32",
  "f64"
};

Note: this type may be extended with additional cases in future versions of WebAssembly.

dictionary GlobalDescriptor {
  required ValueType value;
  boolean mutable = false;
};

[LegacyNamespace=WebAssembly, Constructor(GlobalDescriptor descriptor, optional any v), Exposed=(Window,Worker,Worklet)]
interface Global {
  any valueOf();
  attribute any value;
};

A Global object represents a single global instance which can be simultaneously referenced by multiple Instance objects. Each Global object has one internal slot:

[[Global]] : a global address

To initialize a global object global from a global address globaladdr, perform the following steps:

Let map be the surrounding agent's associated Global object cache.
Assert: map[globaladdr] doesn’t exist.
Set global.[[Global]] to globaladdr.
Set map[globaladdr] to global.

To create a global object from a global address globaladdr, perform the following steps:

Let map be the current agent's associated Global object cache.
If map[globaladdr] exists,
1. Return map[globaladdr].
Let global be a new Global.
Initialize global from globaladdr.
Return global.

The algorithm ToValueType(s) performs the following steps:

If s equals "i32", return 𝗂𝟥𝟤.
If s equals "i64", return 𝗂𝟨𝟦.
If s equals "f32", return 𝖿𝟥𝟤.
If s equals "f64", return 𝖿𝟨𝟦.

The algorithm DefaultValue(valuetype) performs the following steps:

If valuetype equals 𝗂𝟥𝟤, return 𝗂𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 0.
If valuetype equals 𝗂𝟨𝟦, return 𝗂𝟨𝟦.𝖼𝗈𝗇𝗌𝗍 0.
If valuetype equals 𝖿𝟥𝟤, return 𝖿𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 0.
If valuetype equals 𝖿𝟨𝟦, return 𝖿𝟨𝟦.𝖼𝗈𝗇𝗌𝗍 0.
Assert: This step is not reached.

The Global(descriptor, v) constructor, when invoked, performs the following steps:

Let mutable be descriptor["mutable"].
Let valuetype be ToValueType(descriptor["value"]).
If v is undefined,
1. let value be DefaultValue(valuetype).
Otherwise,
1. If valuetype is 𝗂𝟨𝟦, throw a TypeError exception.
2. Let value be ToWebAssemblyValue(v, valuetype).
If mutable is true, let globaltype be var valuetype; otherwise, let globaltype be const valuetype.
Let store be the current agent’s associated store.
Let (store, globaladdr) be global_alloc(store, globaltype, value).
Set the current agent’s associated store to store.
Initialize this from globaladdr.

The algorithm GetGlobalValue(Global global) performs the following steps:

Let store be the current agent’s associated store.
Let globaladdr be global.[[Global]].
Let globaltype be global_type(store, globaladdr).
If globaltype is of the form mut 𝗂𝟨𝟦, throw a TypeError.
Let value be global_read(store, globaladdr).
Return ToJSValue(value).

The getter of the value attribute of Global, when invoked, performs the following steps:

Return GetGlobalValue(this).

The setter of the value attribute of Global, when invoked, performs the following steps:

Let store be the current agent’s associated store.
Let globaladdr be this.[[Global]].
Let globaltype be global_type(store, globaladdr), where globaltype is of the form mut valuetype.
If mut is const, throw a TypeError.
If valuetype is 𝗂𝟨𝟦, throw a TypeError.
Let value be ToWebAssemblyValue(the given value, valuetype).
Let store be global_write(store, globaladdr, value).
If store is error, throw a RangeError exception.
Set the current agent’s associated store to store.

The valueOf() method, when invoked, performs the following steps:

Return GetGlobalValue(this).

3.6. Exported Functions

A WebAssembly function is made available in JavaScript as an Exported Function. Exported Functions are Built-in Function Objects which are not constructors, and which have a [[FunctionAddress]] internal slot. This slot holds a function address relative to the surrounding agent's associated store.

The name of the WebAssembly function funcaddr is found by performing the following steps:

Let store be the surrounding agent's associated store.
Let funcinst be store.𝖿𝗎𝗇𝖼𝗌[funcaddr].
If funcinst is of the form {𝗍𝗒𝗉𝖾 functype, 𝗁𝗈𝗌𝗍𝖼𝗈𝖽𝖾 hostfunc},
1. Assert: hostfunc is a JavaScript object and IsCallable(hostfunc) is true.
2. Let index be the index of the host function funcaddr.
Otherwise,
1. Let moduleinst be funcinst.𝗆𝗈𝖽𝗎𝗅𝖾.
2. Assert: funcaddr is contained in moduleinst.𝖿𝗎𝗇𝖼𝖺𝖽𝖽𝗋𝗌.
3. Let index be the index of moduleinst.𝖿𝗎𝗇𝖼𝖺𝖽𝖽𝗋𝗌 where funcaddr is found.
Return ! ToString(index).

To create a new Exported Function from a WebAssembly function address funcaddr, perform the following steps:

Let map be the surrounding agent's associated Exported Function cache.
If map[funcaddr] exists,
1. Return map[funcaddr].
Let steps be "call the Exported Function funcaddr with arguments."
Let realm be the current Realm.
Let function be CreateBuiltinFunction(realm, steps, %FunctionPrototype%, « [[FunctionAddress]] »).
Set function.[[FunctionAddress]] to funcaddr.
Let store be the surrounding agent's associated store.
Let functype be func_type(store, funcaddr).
Let [paramTypes] → [resultTypes] be functype.
Let arity be the length of paramTypes.
Perform ! SetFunctionLength(function, arity).
Let name be the name of the WebAssembly function funcaddr.
Perform ! SetFunctionName(function, name).
Set map[funcaddr] to function.
Return function.

To call an Exported Function with function address funcaddr and a list of JavaScript arguments argValues, perform the following steps:

Let store be the surrounding agent's associated store.
Let functype be func_type(store, funcaddr).
Let [parameters] → [results] be functype.
If parameters or results contains an 𝗂𝟨𝟦, throw a TypeError.

Note: the above error is thrown each time the [[Call]] method is invoked.
Let args be an empty list of WebAssembly values.
Let i be 0.
For each type t of parameters,
1. If the length of argValues > i, let arg be argValues[i].
2. Otherwise, let arg be undefined.
3. Append ToWebAssemblyValue(arg, t) to args.
4. Set i to i + 1.
Let argsSeq be a WebAssembly sequence containing the elements of args.
Let (store, ret) be the result of func_invoke(store, funcaddr, argsSeq).
Set the surrounding agent's associated store to store.
If ret is error, throw an exception. This exception should be a WebAssembly RuntimeError exception, unless otherwise indicated by the WebAssembly error mapping.
If ret is empty, return undefined.
Otherwise, return ToJSValue(v), where v is the singular element of ret.

Note: Calling an Exported Function executes in the [[Realm]] of the callee Exported Function, as per the definition of built-in function objects.

Note: Exported Functions do not have a [[Construct]] method and thus it is not possible to call one with the new operator.

To run a host function from the JavaScript object func and type functype, perform the following steps:

Let [parameters] → [results] be functype.
Assert: results’s size is at most one.
If either parameters or results contains 𝗂𝟨𝟦, throw a TypeError.
Let arguments be a list of the arguments of the invocation of this function.
Let jsArguments be an empty list.
For each arg in arguments,
1. Append ! ToJSValue(arg) to jsArguments.
Let ret be ? Call(func, undefined, jsArguments).
If results is empty, return undefined.
Otherwise, return ? ToWebAssemblyValue(ret, results[0]).

To create a host function from the JavaScript object func and type functype, perform the following steps:

Let hostfunc be a host function which performs the following steps when called:
1. Let result be the result of running a host function from func and functype.
2. Assert: result.[[Type]] is throw or return.
3. If result.[[Type]] is throw, then trigger a WebAssembly trap, and propagate result.[[Value]] to the enclosing JavaScript.
4. Otherwise, return result.[[Value]].
Let store be the surrounding agent's associated store.
Let (store, funcaddr) be func_alloc(store, functype, hostfunc).
Set the surrounding agent's associated store to store.
Return funcaddr

The algorithm ToJSValue(w) coerces a WebAssembly value to a JavaScript value performs the following steps:

Assert: w is not of the form 𝗂𝟨𝟦.𝖼𝗈𝗇𝗌𝗍 i64.
If w is of the form 𝗂𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 i32, return the Number value for signed_32(i32).
If w is of the form 𝖿𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 f32, return the Number value for f32.
If w is of the form 𝖿𝟨𝟦.𝖼𝗈𝗇𝗌𝗍 f64, return the Number value for f64.

Note: Number values which are equal to NaN may have various observable NaN payloads; see NumberToRawBytes for details.

The algorithm ToWebAssemblyValue(v, type) coerce a JavaScript value to a WebAssembly value performs the following steps:

Assert: type is not 𝗂𝟨𝟦.
If type is 𝗂𝟥𝟤,
1. Let i32 be ? ToInt32(v).
2. Return 𝗂𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 i32.
If type is 𝖿𝟥𝟤,
1. Let f32 be ? ToNumber(v) rounded to the nearest representable value using IEEE 754-2019 round to nearest, ties to even mode.
2. Return 𝖿𝟥𝟤.𝖼𝗈𝗇𝗌𝗍 f32.
If type is 𝖿𝟨𝟦,
1. Let f64 be ? ToNumber(v).
2. Return 𝖿𝟨𝟦.𝖼𝗈𝗇𝗌𝗍 f64.

3.7. Error Objects

WebAssembly defines the following Error classes: CompileError, LinkError, and RuntimeError. WebAssembly errors have the following custom bindings:

Unlike normal interface types, the interface prototype object for these exception classes must have as its [[Prototype]] the intrinsic object %ErrorPrototype%.
The constructor and properties of WebAssembly errors is as specified for NativeError.
If an implementation gives native Error objects special powers or nonstandard properties (such as a stack property), it should also expose those on these exception instances.

[LegacyNamespace=WebAssembly]
interface CompileError { };

[LegacyNamespace=WebAssembly]
interface LinkError { };

[LegacyNamespace=WebAssembly]
interface RuntimeError { };

4. Error Condition Mappings to JavaScript

Running WebAssembly programs encounter certain events which halt execution of the WebAssembly code. WebAssembly code (currently) has no way to catch these conditions and thus an exception will necessarily propagate to the enclosing non-WebAssembly caller (whether it is a browser, JavaScript or another runtime system) where it is handled like a normal JavaScript exception.

If WebAssembly calls JavaScript via import and the JavaScript throws an exception, the exception is propagated through the WebAssembly activation to the enclosing caller.

Because JavaScript exceptions can be handled, and JavaScript can continue to call WebAssembly exports after a trap has been handled, traps do not, in general, prevent future execution.

4.1. Stack Overflow

Whenever a stack overflow occurs in WebAssembly code, the same class of exception is thrown as for a stack overflow in JavaScript. The particular exception here is implementation-defined in both cases.

Note: ECMAScript doesn’t specify any sort of behavior on stack overflow; implementations have been observed to throw RangeError, InternalError or Error. Any is valid here.

4.2. Out of Memory

Whenever validation, compilation or instantiation run out of memory, the same class of exception is thrown as for out of memory conditions in JavaScript. The particular exception here is implementation-defined in both cases.

Note: ECMAScript doesn’t specify any sort of behavior on out-of-memory conditions; implementations have been observed to throw OOMError and to crash. Either is valid here.

A failed allocation of a large table or memory may either result in

a RangeError, as specified in the Memory grow() and Table grow() operations
returning -1 as the memory.grow instruction
UA-specific OOM behavior as described in this section.

In a future revision, we may reconsider more reliable and recoverable errors for allocations of large amounts of memory.

See Issue 879 for further discussion.

5. Implementation-defined Limits

The WebAssembly core specification allows an implementation to define limits on the syntactic structure of the module. While each embedding of WebAssembly may choose to define its own limits, for predictability the standard WebAssembly JavaScript Interface described in this document defines the following exact limits. An implementation must reject a module that exceeds these limits with a CompileError. In practice, an implementation may run out of resources for valid modules below these limits.

The maximum size of a module is 1073741824 bytes (1 GiB).
The maximum number of types defined in the types section is 1000000.
The maximum number of functions defined in a module is 1000000.
The maximum number of imports declared in a module is 100000.
The maximum number of exports declared in a module is 100000.
The maximum number of globals defined in a module is 1000000.
The maximum number of data segments defined in a module is 100000.
The maximum number of tables, including declared or imported tables, is 1.
The maximum size of a table is 10000000.
The maximum number of table entries in any table initialization is 10000000.
The maximum number of memories, including declared or imported memories, is 1.
The initial or maximum number of pages for any memory, declared or imported, is at most 32767.
The maximum number of parameters to any function is 1000.
The maximum number of return values for any function is 1.
The maximum size of a function body, including locals declarations, is 7654321 bytes.
The maximum number of locals declared in a function, including implicitly declared as parameters, is 50000.

6. Security and Privacy Considerations

This section is non-normative.

This document defines a host environment for WebAssembly. It enables a WebAssembly instance to import JavaScript objects and functions from an import object, but otherwise provides no access to the embedding environment. Thus a WebAssembly instance is bounds to the same constraints as JavaScript.

Changes

Changes since the previous Working Draft:

Used noun_verb format from core embedding API (e.g. init_store becomes store_init).
Asynchronously compile a WebAssembly module. Clarified how operations run in parallel.
Create an exports object. Changed to share text between various module instantiation methods.
Used this where appropriate.
Separated initialization and creation of Memory, Table, and Global objects.
Defined the Memory.buffer getter.
ToValueType, DefaultValue. Removed unreachable throw steps.
§ 5 Implementation-defined Limits. Added Implementation-defined Limits section.
§ 6 Security and Privacy Considerations. Added Security and Privacy Considerations section.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

WebAssembly JavaScript Interface

W3C Recommendation, 5 December 2019

Abstract

Status of this document