Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Calling Between JS and Wasm

Exporting Functions to JavaScript

Learn how JavaScript calls WebAssembly exports: argument and result conversion for i32, i64, f32 and f64, multi-value, exported memories, tables and globals, and call overhead.

Everything a module offers to the outside world is listed in its Export section, and JavaScript sees it as the frozen instance.exports object. This lesson is about the contract at that boundary: what a call from JavaScript into Wasm really does to your arguments and results, and how to design exports that are fast and easy to use.

What you get on the exports object

Each export has a kind, and JavaScript receives a matching object:

Kind JavaScript value
Function A callable function (an "exported function" exotic object)
Memory WebAssembly.Memory
Table WebAssembly.Table
Global WebAssembly.Global
Tag WebAssembly.Tag (exceptions)

Exported functions look like ordinary JavaScript functions: you call them, pass them around, and they have length. But they are not quite normal. They ignore this, cannot be used with new, and their name is the function's numeric index as a string. Asking for the same export twice returns the very same object, so a.exports.f === a.exports.f is true.

Argument conversion

Wasm functions have fixed parameter types, so on every call JavaScript values are converted to the declared type. Missing arguments become undefined before conversion, and extra arguments are ignored.

Parameter type JavaScript conversion
i32 ToInt32: like x | 0; strings and booleans become numbers, fractions are cut, large values wrap modulo 2^32, NaN becomes 0
i64 ToBigInt64: needs a BigInt (a plain number throws TypeError); wraps modulo 2^64
f32 ToNumber, then rounded to 32-bit float
f64 ToNumber
externref Any JavaScript value, passed untouched
funcref A Wasm function or null

Results go the other way. An i32 result becomes a signed JavaScript number, i64 a BigInt, f32 and f64 a number. A function with several results gives an array; with none it gives undefined.

Node.js What the boundary does to your values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice i32({}): the object becomes NaN through ToNumber, which becomes 0. And passing a Symbol throws, because a symbol cannot be converted to a number. Because the module cannot tell good input from garbage once it is converted, validate arguments on the JavaScript side before calling.

Memories, tables and globals as exports

An export is not always a function. A typical compiled module exports its memory and a handful of functions:

Node.js Listing the exports of a module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Designing a good export surface

  • Export a small, stable set. Everything exported is part of your public interface. Internal helpers should stay private.
  • Make calls coarse-grained. Crossing the boundary is cheap in modern engines (the engines inline the call path) but not free: it converts arguments, and it prevents optimizing across the border. One call such as processImage(ptr, width, height) beats a million calls to setPixel.
  • Prefer numbers. Numbers pass at near zero cost. Strings, arrays and objects must go through memory, covered in the lessons that follow.
  • Wrap raw exports in a friendly JavaScript API. Export _add and _alloc from Wasm and expose add() and createBuffer() from a small JavaScript module. Users never see the pointers.
  • Name exports predictably. Compilers prefix with an underscore (_main, _malloc) or use plain names. Follow the convention of your toolchain.
flowchart LR
    U["Your app code"] --> W["JS wrapper: validates, encodes, decodes"]
    W --> E["Wasm exports: numbers and pointers"]
    E --> M["Linear memory: buffers and strings"]

When a Wasm function needs to return something larger than a number, return a pointer and let JavaScript read the bytes, or write into a buffer that JavaScript passed in. Multi-value results are best for two or three small numbers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an i32 parameter do with the JavaScript value 3.99?

    ToInt32 truncates toward zero, so 3.99 becomes 3 and -3.99 becomes -3.
  2. 2. How do you pass a value to an i64 parameter?

    i64 parameters require BigInt; a plain number throws a TypeError.
  3. 3. What does a call return for a function with no results?

    Functions without results return undefined, like normal JavaScript functions.
  4. 4. Why should you validate arguments in JavaScript?

    The conversion rules are lenient, so the module cannot tell whether a zero was intended.

Summary

  • Exports of every kind appear on a frozen instance.exports object: functions, memories, tables, globals.
  • Arguments are converted (ToInt32, BigInt, ToNumber); results come back as numbers, BigInts, or an array for multi-value.
  • Exported functions ignore this, have length equal to their parameter count, and return the same object on every access.
  • Keep the exported surface small, coarse-grained and numeric; wrap it in friendly JavaScript.
  • Validate input in JavaScript before it is silently converted.

Next: Importing JavaScript Functions