Tern

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-runtimes

or 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)
Output
5133 + 4459 = 9592 primes below 100,000
arguments: 0
tern 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 environment

tern 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))
Output
4 Hello Wasm World
3.5 b
tern build --lib --target wasm textstats.tn -o textstats.wasm

This 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 works
4n
Héllo Wasm
3.75
20
TernError: runtime error (line 19): index 5 out of bounds (length 3)
c

With 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

TernJavaScript argumentJavaScript result
intbigint or numberbigint
floatnumbernumber
boolany value (truthy or falsy)boolean
strstring (sent as UTF-8)string
ptrnumbernumber
no return typeundefined
  • Ints are 64-bit, so they come back as bigint. Convert with Number(x) when you know the value fits in a double. An int argument accepts a number, but it must be a whole number: BigInt(1.5) throws a RangeError in 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, and ptr cross 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:
Does not compile
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]))
Compiler output
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 TypeError from the loader (average takes 2 argument(s), got 1).
  • The library object also has memory, the module's WebAssembly.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 2

A 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.html

The 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 Node
  • load(source, { threads: 8 }) picks the number of threads (default: the number of cores); lib.close() stops the workers. Programs read TERN_THREADS.
  • In a browser, shared memory needs a cross-origin-isolated page (served with Cross-Origin-Opener-Policy: same-origin and Cross-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-threads builds with it).

Limits

  • One thread on wasm. With --target wasm, the tasks of a parallel: block and the iterations of a parallel for run one after another (use wasm-threads for real threads). The race checks still apply, so the same code is correct everywhere.
  • No database or web server. import sqlite and http.serve are 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 (extern structs work for calling C). extern blocks work if the C code builds for WASI (libc functions such as math.h's cbrt do).

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):

benchmarkTernRust
binary-trees3.65 s5.98 sTern 1.64x faster
sieve731 ms, 33 MB747 ms, 199 MBtie, 6x less memory
fib1.76 s1.76 stie
tasks354 ms357 mstie
n-body1.18 s1.42 sTern 1.2x faster (wasm SIMD)
.wasm size32–44 KB49–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:

workloadTernRustGo
JSON: encode + decode 100k records, 5 times137 ms, 64 MB190 ms, 64 MB2238 ms, 259 MB
request handler (cold start)6 ms, 76 KB module7 ms, 154 KB20 ms, 3129 KB
virtual DOM: build, render, diff20 ms, 10 MB32 ms, 11 MB162 ms, 35 MB
text: split 2M words, count them56 ms, 30 MB55 ms, 38 MB286 ms, 104 MB
image: grayscale + blur, 1024x1024 [byte]16 ms, 15 MB29 ms, 15 MB83 ms, 35 MB
regex: find emails in 2MB of text28 ms, 114 KB module33 ms, 1171 KB944 ms
base64: encode + decode 3MB57 ms60 ms125 ms
sort: 1M records by int, 200k strings53 ms171 ms9854 ms
expressions: parse into trees, evaluate43 ms72 ms171 ms

With threads (wasm32-wasip1-threads for both, 14 threads under Node, Rust using rayon):

benchmarkTernRust
binary-trees0.51 s150 sTern ~300x faster: Rust's wasm allocator is one global lock
fib210 ms217 mstie
tasks120 ms121 mstie

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).

Source: docs/guides/wasm.md. Every example on this page is compiled and run by tern x test docs.