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).
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.
Practice what you learned
1. Which value types can a WebAssembly function signature natively accept as parameters?
2. What is the standard convention for passing a string from JavaScript into a Wasm function?
3. Why is writing directly into a TypedArray view over memory.buffer preferred over passing array elements one function call at a time?
4. What must a caller do after passing data through memory allocated by a Wasm-exported allocator function?
5. What do tools like wasm-bindgen and Emscripten's ccall/cwrap primarily automate?
Was this page helpful?
You May Also Like
Memory Management in Wasm
How WebAssembly's linear memory model works, how it grows, and how it differs from garbage-collected host environments like JavaScript.
The WebAssembly JavaScript API
A tour of the WebAssembly global object's core classes — Module, Instance, Memory, Table, and Global — and how JavaScript orchestrates Wasm.
Wasm Tables and Functions
How WebAssembly represents functions as first-class values, why linear memory can't hold them, and how Table enables indirect calls and function pointers.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics