The WebAssembly JavaScript API

Analogy categoryAnalogies

The WebAssembly Global Object

JavaScript engines expose WebAssembly functionality through a single global namespace object, WebAssembly, containing the constructors Module, Instance, Memory, Table, and Global, plus the free functions compile, instantiate, validate, and their streaming variants. This API is deliberately low-level: it gives JavaScript precise control over compiling bytecode, wiring up imports, and reading exports, without imposing any framework or build tool — everything higher-level (like Emscripten's glue code or wasm-bindgen) is built on top of these primitives.

🏏

Cricket analogy: It's like the ICC's official rulebook: a small set of primitives (LBW, no-ball, follow-on) that every domestic board — BCCI, ECB — builds their own tournament formats on top of, without the rulebook itself dictating format.

Module, Instance, and validate()

A WebAssembly.Module is stateless, immutable compiled bytecode — it can be safely shared across Web Workers via postMessage (unlike an Instance) because it holds no live memory or mutable state. WebAssembly.Instance is the stateful counterpart: constructing one via new WebAssembly.Instance(module, importObject) (the synchronous constructor form) or via instantiate() allocates the module's memory and tables and wires up imports, producing something with genuinely mutable state that must not be shared across threads without careful use of SharedArrayBuffer.

🏏

Cricket analogy: A Module is like a printed match strategy playbook — copyable and shareable to every player without side effects — while an Instance is the live match itself with a scoreboard that only one official scorer should be updating at a time.

javascript

// Sharing a compiled Module across Web Workers
const bytes = await (await fetch('image-filter.wasm')).arrayBuffer();
const sharedModule = await WebAssembly.compile(bytes);

const worker = new Worker('worker.js');
worker.postMessage({ module: sharedModule }); // Module is transferable/shareable

// Inside worker.js:
self.onmessage = async ({ data }) => {
  const instance = await WebAssembly.instantiate(data.module, {
    env: { memory: new WebAssembly.Memory({ initial: 1 }) },
  });
  const output = instance.exports.applyFilter(0, 1024);
  self.postMessage(output);
};

WebAssembly.validate(bufferSource) synchronously checks whether a byte sequence is well-formed WebAssembly without fully compiling it, returning a plain boolean rather than throwing — useful for a quick sanity check (e.g. a plugin-loading system rejecting corrupt uploads) before committing to the more expensive compile() call. It is intentionally cheap and does not report why validation failed, only whether it passed.

🏏

Cricket analogy: It's like a boundary umpire doing a quick visual check that the ball hasn't gone out of shape before the over continues, a fast yes/no check rather than sending it to the full ball-testing lab.

Memory, Table, and Global as First-Class Objects

Beyond compiling and instantiating code, the API exposes three constructible resource types that can be created in JavaScript and passed in as imports, or read out as exports: WebAssembly.Memory (a growable linear memory backed by an ArrayBuffer), WebAssembly.Table (a resizable, typed array of references — typically funcref or externref — used for indirect calls), and WebAssembly.Global (a single mutable or immutable typed value shared between host and module). Constructing these on the JavaScript side, rather than letting the module define them internally, is what enables patterns like sharing one Memory across multiple module instances.

🏏

Cricket analogy: Memory is like the shared team dressing room both batting partners use; Table is like the substitutes' bench holding numbered players ready to be called on by index; Global is like a single shared stump microphone both teams' broadcasters can read from.

Sharing a single WebAssembly.Memory across multiple Instances (by passing the same Memory object into each import object) is the standard pattern for letting two modules — say, an image decoder and a filter kernel — operate directly on the same linear memory buffer without copying data between them.

A WebAssembly.Global constructed as mutable ({ value: 'i32', mutable: true }) can only have its .value reassigned from JavaScript if it was explicitly declared mutable; attempting to write to an immutable Global throws a TypeError, and most modules export globals as immutable by default for safety.

The WebAssembly global namespace exposes Module, Instance, Memory, Table, Global, plus compile/instantiate/validate functions.
A Module is immutable, stateless compiled bytecode and can be safely shared across Web Workers via postMessage.
An Instance holds live, mutable state (memory, table contents, global values) and should not be casually shared across threads.
WebAssembly.validate() gives a cheap boolean well-formedness check before committing to a full compile().
WebAssembly.Memory wraps a growable ArrayBuffer-backed linear memory that can be shared across multiple instances.
WebAssembly.Table holds typed references (funcref/externref) for indirect function calls, indexed like an array.
WebAssembly.Global exposes a single typed value as mutable or immutable, shared between host JS and the module.