Passing Data Between JS and Wasm

Analogy categoryAnalogies

The Boundary Problem: Only Numbers Cross for Free

WebAssembly function signatures only support four value types natively: i32, i64, i32/f64 floats, and (with the reference-types proposal) funcref/externref. There is no native string, array, or object parameter type — a JavaScript string or a complex struct cannot simply be passed as an argument to an exported Wasm function. Instead, the calling convention is: the caller writes the data's bytes into the module's linear memory at some offset, then passes that offset (and often a length) as a plain i32 pointer argument, and the callee reads the bytes back out from memory at that offset.

🏏

Cricket analogy: It's like a coach who can only pass a single jersey number across the boundary rope to a substitute, not the whole player — the actual player details (name, stats) have to already be written on a noticeboard in the dugout that the number just points to.

Passing Strings: Encode, Write, Point, Decode

To pass a JavaScript string into Wasm, you typically encode it to UTF-8 bytes with TextEncoder, allocate space for those bytes inside the module's memory (often via an exported malloc-like function such as Rust's alloc or Emscripten's _malloc), copy the bytes into a Uint8Array view over memory.buffer at the returned offset, and call the Wasm function with (pointer, length). Reading a string back out of Wasm works in reverse: read length bytes starting at pointer from a Uint8Array view, then decode with TextDecoder('utf-8').decode(bytes). Frameworks like wasm-bindgen (Rust) or Emscripten's ccall/cwrap with UTF8ToString automate this exact dance.

🏏

Cricket analogy: It's like translating a foreign commentator's live call into English for the broadcast: encode the words (UTF-8 bytes), place the translated script at a specific page number in the studio binder (memory offset), tell the anchor which page and how many lines to read (pointer, length), and the anchor reads it back out loud (decode).

javascript

function passStringToWasm(instance, str) {
  const { memory, alloc, greet } = instance.exports;
  const bytes = new TextEncoder().encode(str);

  const ptr = alloc(bytes.length); // module-exported allocator
  new Uint8Array(memory.buffer, ptr, bytes.length).set(bytes);

  const resultPtr = greet(ptr, bytes.length); // wasm returns a pointer to a new string
  const resultLen = new Uint32Array(memory.buffer, resultPtr, 1)[0];
  const resultBytes = new Uint8Array(memory.buffer, resultPtr + 4, resultLen);

  return new TextDecoder('utf-8').decode(resultBytes);
}

passStringToWasm(instance, 'Namaste'); // e.g. "Hello, Namaste!"

Passing Structured Data and Arrays

For numeric arrays, the fastest path is to write directly into a TypedArray view over memory.buffer — for example, a Float32Array for a batch of vertex coordinates — avoiding per-element function calls entirely; the Wasm side receives a single (pointer, length) pair and iterates the array using load instructions at computed offsets. For structs or richer objects, the convention is typically a fixed byte layout (matching the compiled language's struct representation, including padding) with the caller writing each field at its known offset — tools like wasm-bindgen generate this marshalling code automatically instead of requiring it by hand.

🏏

Cricket analogy: It's like handing over an entire innings' ball-by-ball data as one spreadsheet rather than phoning in each ball individually — the analyst reads the whole sheet at known column offsets instead of getting 300 separate phone calls.

Emscripten's ccall/cwrap helpers and Rust's wasm-bindgen both generate the pointer-and-length marshalling boilerplate automatically for common types (strings, typed arrays, and #[wasm_bindgen]-annotated structs), which is why most real-world Wasm projects rarely hand-write raw TextEncoder/Uint8Array plumbing directly.

Every pointer returned from Wasm-side allocation must eventually be freed by calling the module's exported deallocator (e.g. dealloc(ptr, len)); forgetting to do so leaks memory inside the linear memory buffer just as surely as forgetting free() in C, and unlike JavaScript's own heap, nothing garbage-collects it automatically.

Wasm function signatures only carry numeric types (i32, i64, f32, f64) plus reference types — no native string or object parameters.
Strings cross the boundary by writing UTF-8 encoded bytes into linear memory and passing a (pointer, length) pair.
TextEncoder/TextDecoder handle the JS-side encoding and decoding of those byte buffers.
Numeric arrays should be written directly into a TypedArray view over memory.buffer for batch transfer, not passed element-by-element.
Structs cross the boundary via a fixed, agreed-upon byte layout matching the compiled language's memory representation.
wasm-bindgen and Emscripten's ccall/cwrap automate most of this pointer-and-length marshalling for common types.
Memory allocated on the Wasm side for passed data must be explicitly freed via an exported deallocator — nothing does it automatically.