WASI

wasi_snapshot_preview1 for WebAssembly modules, shaped like Node’s node:wasi. WebAssembly itself is the standard global (MDN).

import { WASI } from "@native/wasi";

Nothing is patched globally. Create a WASI, pass its imports to WebAssembly.instantiate, then start() a command or initialize() a reactor.

constructor

new WASI(options?: WASIOptions)

Creates one WASI environment.

Option	Default
`args`	`[]`	argv, including `argv[0]`
`env`	`{}`	environment variables
`preopens`	`{ "/": data/ }`	guest directory → host directory; relative host paths start at `data/`
`returnOnExit`	`true`	`proc_exit(code)` ends `start()`, which returns `code`; `false` makes it throw instead
`version`	`"preview1"`	the only one

A host directory outside data/ needs the filesystem permission and must exist.

const wasi = new WASI({
    args: ["app", "--fast"],
    env: { MODE: "demo" },
    preopens: { "/": ".", "/assets": "assets" },
});

getImportObject

wasi.getImportObject(): { wasi_snapshot_preview1: Readonly<Record<string, WasiSyscall>> }

The imports to pass to WebAssembly.instantiate. wasi.wasiImport is the same syscall table on its own, for merging with your own imports.

const { instance } = await WebAssembly.instantiate(bytes, wasi.getImportObject());

const imports = { wasi_snapshot_preview1: wasi.wasiImport, env: { log: (n: number) => console.log(n) } };

start

wasi.start(instance: WebAssembly.Instance): number

Runs a command: calls _start() and returns the exit code (0 when _start returns). Call start() or initialize() once per WASI.

const code = wasi.start(instance);

With returnOnExit: false, proc_exit throws an Error with exitCode.

initialize

wasi.initialize(instance: WebAssembly.Instance): void

Sets up a reactor (a module without _start): calls _initialize() if it’s exported. Then call its exports yourself.

wasi.initialize(instance);
const add = instance.exports.add as (a: number, b: number) => number;
add(2, 3);

dispose

wasi.dispose(): void

Closes every file the guest opened. Happens on unload anyway. alive is false afterwards, and using disposes at the end of the block.

Guest environment


argv / environ	exactly `args` / `env`
Filesystem	only the preopens, no `..` out of them
stdin	empty
stdout / stderr	the script log, stderr as errors
`sleep()`	returns immediately
Sockets	none

Symlinks and junctions inside a preopen work as long as they stay inside it; one that leads out is ENOTCAPABLE, like ... File access is direct: opening, reading and stat-ing thousands of files costs about what it costs natively, and the disk time doesn’t count against the script’s limits.

Long-running modules

A wasm module that runs for seconds at a time (an emulator, an engine, a big parse) would hold up every script on the shared thread, and the host stops calls that run too long. Three ways out:

Run it in a Worker. @native/wasi and @native/fs work there, there’s no time limit, and a WebAssembly.Module you post is shared already compiled.
Compile asynchronously. await WebAssembly.compile(bytes) / WebAssembly.instantiate(bytes) compile on background threads and don’t block anybody. Big modules start on the fast baseline compiler and get optimized in the background while they run.
Yield with JSPI. Wrap an async import in WebAssembly.Suspending and the export in WebAssembly.promising. The module can then pause on a promise in the middle of a call and resume in a later tick. It’s an experimental V8 feature (TypeScript doesn’t declare it yet, cast through any).

const W = WebAssembly as any;
const yieldNow = new W.Suspending(() => new Promise((r) => setTimeout(r, 0)));
const { instance } = await WebAssembly.instantiate(bytes, { env: { yield_now: yieldNow } });
const runFrame = W.promising(instance.exports.run_frame);
await runFrame(); // the module calls yield_now() between steps; every script keeps running meanwhile

Example

Run a WASI command from data/app.wasm.

import { WASI } from "@native/wasi";
import fs from "@native/fs";

async function runApp(args: string[]): Promise<number> {
    using wasi = new WASI({ args: ["app", ...args], env: { MODE: "demo" } });
    const bytes = await fs.readFile("app.wasm");
    const { instance } = await WebAssembly.instantiate(bytes, wasi.getImportObject());
    return wasi.start(instance);
}

const code = await runApp(["--fast"]);
console.log("exit", code);

Overview

Modules

Types

WASI

WASI

constructor

getImportObject

start

initialize

dispose

Guest environment

Long-running modules

Example