WebAssembly and JavaScript
Tern compiles to WebAssembly (WASI) with one flag, --target wasm. This guide covers installing the toolchain, building and running whole programs under wasmtime or Node, building a library that JavaScript can call (with a generated loader and TypeScript types), how values cross between Tern and JavaScript, how runtime errors surface, using a module in the browser, and what doesn't work on wasm.
Installing the toolchain
Tern compiles to C, so wasm needs a C compiler that targets wasm32-wasip1. Either install Homebrew's LLVM with the WASI libraries:
brew install llvm lld wasi-libc wasi-runtimesor install a wasi-sdk and point WASI_SDK_PATH at it (tern also looks in /opt/wasi-sdk). If neither is found, tern stops with a message saying which packages to install.
To run programs you need wasmtime or Node.js 18 or newer. JavaScript libraries need only Node or a browser.
Building and running a program
Any program that doesn't use sqlite or http builds for wasm unchanged:
import os
fn count_primes(lo: int, hi: int) int:
n = 0
for k in lo..hi:
if k < 2:
continue
prime = true
d = 2
while d * d <= k:
if k % d == 0:
prime = false
break
d += 1
if prime:
n += 1
return n
fn main():
parallel: # two tasks on native; one after the other on wasm
low = count_primes(0, 50_000)
high = count_primes(50_000, 100_000)
print(f"{low} + {high} = {low + high} primes below 100,000")
print("arguments:", len(os.args()) - 1)5133 + 4459 = 9592 primes below 100,000
arguments: 0tern run --target wasm app.tn -- one two # build, then run under wasmtime (or Node)
tern build --target wasm app.tn # writes app.wasm (about 40 KB)
wasmtime run app.wasm one two
wasmtime run --dir=/tmp -S inherit-env=y app.wasm # let it see /tmp and the environmenttern run uses wasmtime if it's installed and Node's node:wasi otherwise. Either way it gives the program the current directory, /tmp, and the environment. When you run wasmtime yourself, the module sees only what you grant: without --dir, fs.read returns "" and fs.write returns false, as they do for any unreadable path, and without -S inherit-env=y, os.env returns its default.
A runtime error in a wasm program prints runtime error in f (prog.tn:N): ... to stderr and exits with status 2, the same as natively.
Building a library for JavaScript
Mark the functions JavaScript should see with export fn. A library file can still have a main; --lib ignores it, and it lets you test the functions natively with tern run:
export fn word_count(text: str) int:
n = 0
for w in text.split(" "):
if w.trim() != "":
n += 1
return n
export fn title_case(text: str) str:
words: [str] = []
for w in text.split(" "):
if w != "":
words.push(w[0].upper() + w[1..].lower())
return " ".join(words)
export fn average(total: float, count: int) float:
return total / float(count)
export fn nth_word(text: str, i: int) str:
return text.split(" ")[i] # out of range: a runtime error
fn main(): # ignored by --lib; lets you test with `tern run`
print(word_count("the quick brown fox"), title_case("hello WASM world"))
print(average(7.0, 2), nth_word("a b c", 1))4 Hello Wasm World
3.5 btern build --lib --target wasm textstats.tn -o textstats.wasmThis writes three files next to each other:
textstats.wasm: the module (about 50 KB here).textstats.mjs: an ES module that loads it and wraps each exported function. It works in browsers, Node, and other JavaScript runtimes, and needs no npm packages.textstats.d.ts: TypeScript types for the loader.
Call it from Node:
import { load, TernError } from './textstats.mjs';
const lib = await load(); // finds textstats.wasm next to this file
console.log(lib.word_count('the quick brown fox')); // a bigint
console.log(lib.title_case('héllo wasm'));
console.log(lib.average(7.5, 2)); // numbers work where an int is expected
console.log(Number(lib.word_count('a b')) * 10);
try {
lib.nth_word('a b c', 5);
} catch (e) {
if (e instanceof TernError) console.log('TernError:', e.message);
}
console.log(lib.nth_word('a b c', 2)); // the module still works4n
Héllo Wasm
3.75
20
TernError: runtime error (line 19): index 5 out of bounds (length 3)
cWith no argument, load() loads the .wasm file with the same name next to the .mjs. You can also pass the module: its bytes (an ArrayBuffer or typed array, such as the result of readFile in Node), a Response (load(await fetch('/static/textstats.wasm'))), or a URL to fetch (in Node, use a file: URL such as new URL('./textstats.wasm', import.meta.url)). Each call to load() makes a new, independent instance with its own memory.
How values cross
| Tern | JavaScript argument | JavaScript result |
|---|---|---|
int | bigint or number | bigint |
float | number | number |
bool | any value (truthy or falsy) | boolean |
str | string (sent as UTF-8) | string |
ptr | number | number |
| no return type | undefined |
- Ints are 64-bit, so they come back as
bigint. Convert withNumber(x)when you know the value fits in a double. Anintargument accepts anumber, but it must be a whole number:BigInt(1.5)throws aRangeErrorin JavaScript before Tern is called. - Strings are copied into the module's memory for the call and freed afterwards. Returned strings are copied out and freed by the loader, so you never manage wasm memory yourself.
- Only
int,float,bool,str, andptrcross the boundary. Arrays, maps, structs, and enums are compile errors in an exported signature. To pass structured data, encode it as JSON text (json.encode/json.decode) or a delimited string:
struct Point:
x, y: int
export fn total(xs: [int]) int:
t = 0
for x in xs:
t += x
return t
export fn origin() Point:
return Point(0, 0)
fn main():
print(total([1, 2]))4: error: `[int]` can't cross the C boundary (exported functions take int, float, bool, str, or ptr)
10: error: exported `origin` returns Point, which can't cross the C boundary (return int, float, bool, str, or ptr)- Calling a function with the wrong number of arguments throws a
TypeErrorfrom the loader (average takes 2 argument(s), got 1). - The library object also has
memory, the module'sWebAssembly.Memory.
Runtime errors become TernError
A runtime error inside an exported function (an index out of bounds, a missing map key, division by zero) doesn't end anything. The call unwinds, and the loader throws a TernError whose message is the same text a program would print. The module keeps working, so later calls behave normally, as the nth_word example above shows.
This costs nothing for functions that can't fail. The compiler works out which exported functions might hit a runtime error, and the loader checks for an error only after those.
Printing from a library
print inside a library goes to process.stdout under Node and to console.log in a browser (a line at a time; stderr goes to console.error). To send it somewhere else, pass a write function:
const lines = [];
const lib = await load(undefined, { write: (fd, text) => lines.push(text) }); // fd is 1 or 2A library has no files, arguments, or environment: the loader provides only printing, clocks (time), and random numbers (random, from crypto.getRandomValues). fs.read returns "" and os.args() is empty.
In the browser
examples/wasm/ has a complete page. Build the library, serve the directory over HTTP (the loader uses fetch, which doesn't work on file:// URLs), and open the page:
cd examples/wasm
tern build --lib --target wasm lib.tn -o lib.wasm
node demo.mjs # the same library from Node
python3 -m http.server 8000 # then open http://localhost:8000/index.htmlThe page imports the loader as a module and calls Tern on every keystroke:
import { load, TernError } from './lib.mjs';
const lib = await load();
const c = lib.count_primes(Number(document.getElementById('n').value) || 2);
try { lib.char_at('abc', 10); }
catch (e) { console.log(e instanceof TernError, e.message); } // true "runtime error (line 52): index 10 out of bounds (length 3)"Counting the primes below 1,000,000 takes about 77 ms in the page (Chromium, Apple M4 Pro), and lib.wasm is about 51 KB.
Threads: --target wasm-threads
--target wasm has one thread. --target wasm-threads builds for WebAssembly's shared memory, and then parallel: blocks and parallel for really run in parallel, on a pool of Web Workers (worker_threads under Node) that the generated loader starts. The same source works for both targets; only the build changes:
tern build --lib --target wasm-threads primes.tn -o primes.wasm
tern run --target wasm-threads prog.tn # programs run under Nodeload(source, { threads: 8 })picks the number of threads (default: the number of cores);lib.close()stops the workers. Programs readTERN_THREADS.- In a browser, shared memory needs a cross-origin-isolated page (served with
Cross-Origin-Opener-Policy: same-originandCross-Origin-Embedder-Policy: require-corp), and the library must be loaded from a Worker, since the page's own thread isn't allowed to wait.examples/wasm/threads/has the whole setup, including a small server: counting primes below 3,000,000 takes 326 ms on 1 thread and 22 ms on 14 (Chromium). - Runtime errors inside parallel tasks still come back as
TernError. - The loader runs any WASI-threads module, not only Tern's (the benchmarks below run Rust's
wasm32-wasip1-threadsbuilds with it).
Limits
- One thread on
wasm. With--target wasm, the tasks of aparallel:block and the iterations of aparallel forrun one after another (usewasm-threadsfor real threads). The race checks still apply, so the same code is correct everywhere. - No database or web server.
import sqliteandhttp.serveare compile errors on wasm:
app.tn:1: error: `import sqlite` is not available on wasm- Runtime errors in programs end the program (exit status 2). Only libraries recover and report them as
TernError. - Memory grows in chunks of at least 1 MB as the program allocates, and is never given back to the host; freed memory is reused by later allocations. Tern code runs on an 8 MB wasm stack, which bounds recursion depth.
- The C boundary is the same as for native libraries (see Calling C, and Tern as a library): no structs or arrays in exported signatures (
externstructs work for calling C).externblocks work if the C code builds for WASI (libc functions such asmath.h'scbrtdo).
Performance
bench/platforms.tn runs the compute benchmarks under wasmtime against Rust built for wasm32-wasip1 (full table in bench/platforms_results.md; median of 5 runs):
| benchmark | Tern | Rust | |
|---|---|---|---|
| binary-trees | 3.65 s | 5.98 s | Tern 1.64x faster |
| sieve | 731 ms, 33 MB | 747 ms, 199 MB | tie, 6x less memory |
| fib | 1.76 s | 1.76 s | tie |
| tasks | 354 ms | 357 ms | tie |
| n-body | 1.18 s | 1.42 s | Tern 1.2x faster (wasm SIMD) |
.wasm size | 32–44 KB | 49–113 KB |
Tern builds use wasm SIMD, which browsers, Node, and wasmtime all support; set TERN_WASM_SIMD=0 when compiling for a host that rejects it. Programs shaped like what wasm is used for are compared with Rust and Go in bench/wasm_apps/README.md:
| workload | Tern | Rust | Go |
|---|---|---|---|
| JSON: encode + decode 100k records, 5 times | 137 ms, 64 MB | 190 ms, 64 MB | 2238 ms, 259 MB |
| request handler (cold start) | 6 ms, 76 KB module | 7 ms, 154 KB | 20 ms, 3129 KB |
| virtual DOM: build, render, diff | 20 ms, 10 MB | 32 ms, 11 MB | 162 ms, 35 MB |
| text: split 2M words, count them | 56 ms, 30 MB | 55 ms, 38 MB | 286 ms, 104 MB |
image: grayscale + blur, 1024x1024 [byte] | 16 ms, 15 MB | 29 ms, 15 MB | 83 ms, 35 MB |
| regex: find emails in 2MB of text | 28 ms, 114 KB module | 33 ms, 1171 KB | 944 ms |
| base64: encode + decode 3MB | 57 ms | 60 ms | 125 ms |
| sort: 1M records by int, 200k strings | 53 ms | 171 ms | 9854 ms |
| expressions: parse into trees, evaluate | 43 ms | 72 ms | 171 ms |
With threads (wasm32-wasip1-threads for both, 14 threads under Node, Rust using rayon):
| benchmark | Tern | Rust | |
|---|---|---|---|
| binary-trees | 0.51 s | 150 s | Tern ~300x faster: Rust's wasm allocator is one global lock |
| fib | 210 ms | 217 ms | tie |
| tasks | 120 ms | 121 ms | tie |
To check that your own programs behave the same on wasm, the test suite runs on it too: tern run tests/runner/main.tn -- run --target=wasm or --target=wasm-threads (tests that use sqlite or http are skipped).