WASM & Playground

Build a browser package and call a Topaz function from JavaScript with inputs 45 and 20. The example below returns the remaining time, 25, and shows how to read the typed result.

For local builds, install the Topaz CLI and Rust with Cargo and wasm32-unknown-unknown. The JavaScript example runs with Node.js. The finished browser package runs without Topaz or Rust.

Try source in the Playground

Use the Playground to edit, check, and run Topaz in your browser without installing the CLI. It loads the compiler and interpreter WASM in a Worker. To add Topaz functions to your own JavaScript application, build the Web package below.

Build a Web package

In a new folder, save this complete program as main.tpz.

TOPAZ

export function remaining(total: int, used: int) -> int {
    total - used
}

Run the build from that folder.

BASH

topaz build --target web main.tpz --release --out-dir web-product

When the build finishes, it prints the paths of topaz-web.wasm and its loader topaz-web.js. The web-product folder contains topaz-web.js, topaz-web.d.ts, and topaz-web.wasm, together with the common artifact files. Your JavaScript application supplies the UI and calls exported functions through the generated module.

Call the function from JavaScript

Save this package.json beside main.tpz so Node.js reads the generated .js file as an ES module.

JSON

{ "type": "module" }

Save the following file as call.mjs in the same folder.

JAVASCRIPT

import { readFile } from 'node:fs/promises';
import { instantiateTopaz } from './web-product/topaz-web.js';

const wasm = await readFile(
  new URL('./web-product/topaz-web.wasm', import.meta.url)
);
const app = await instantiateTopaz(wasm);
const result = app.exports.remaining(
  { $: 'int', value: '45' },
  { $: 'int', value: '20' }
);
console.log(JSON.stringify(result));

Run the JavaScript file from the folder containing main.tpz.

BASH

node call.mjs

The call produces this result.

Output

{"status":"ok","value":{"$":"int","value":"25"}}

status: "ok" means the call succeeded. The result is a Topaz integer whose decimal text is "25". Each input also includes the int tag and decimal text. This preserves the integer value when passing through JavaScript.

The generated topaz-web.d.ts describes this argument and result format, called the ABI. Check status before reading value. A fault result includes an error code, message, and source span. An error result includes a message. Correct the named export, arguments, or reported Topaz source before calling again.

In a browser, serve the complete product over HTTP. Import instantiateTopaz in a module script and pass it the URL of topaz-web.wasm. The exported function takes the same tagged arguments. Browsers do not support loading this package directly through file://.

Use a Worker for calls off the main thread

Build the same main.tpz for a Worker when its calls should run outside the browser main thread.

BASH

topaz build main.tpz --target web-worker --release --out-dir worker-product

The result includes the Web files plus topaz-web-worker.js and topaz-web-worker-client.js. The client sends requests and receives responses using the same argument and result format. Its calls are asynchronous. Your JavaScript application still supplies the UI and permissions. A Worker does not grant extra capabilities.

Recover from loading and build errors

Problem	Action
The Rust WASM target is missing	Install `wasm32-unknown-unknown` in the Rust toolchain used by the build
The browser reports a host/runtime identity mismatch	Deploy the entire folder from one build. Keep its JavaScript and WASM files together
The output folder contains changed managed files	Preserve it for inspection and choose a new empty `--out-dir`

Try source in the Playground

Build a Web package

Call the function from JavaScript

Use a Worker for calls off the main thread

Recover from loading and build errors

Related documentation