Overview

Perry-WIT compiles a static subset of TypeScript ahead of time into WASI 0.3 WebAssembly components. It lowers TypeScript through typed SSA directly to WebAssembly instructions and links only referenced functions from its precompiled runtime and standard libraries, so a component exporting a string function is about 3 KB. These #![no_std] modules ship inside the compiler, so compiling needs no Rust or LLVM toolchain, whether you use the CLI, the Rust API or the compiler as a sandboxed WASI 0.2 component (see Embedding and Architecture).

Programs are ordinary TypeScript that tsc checks against types generated from the WIT world, and modules without WIT imports also run under Node.js. A module can be a CLI command with top-level await, export functions or an HTTP handler, or do both, in which case its top-level code initializes state once before the first export runs (see Authoring). WIT integer types refine number: a u8 parameter is an integer in 0..=255. Forward range and backward bitwidth analysis turn in-range arithmetic into i32 and i64 instructions and drop proven bounds checks, while other numbers keep IEEE 754 f64 semantics (see Semantics and Standard Library).

Memory stays flat across calls: the test suite runs 1,000 calls with a nested record argument within two 64 KiB pages. When no export can suspend, keep state, hold host resources or allocate without bound, each call allocates from a region freed in bulk when it returns. Otherwise the runtime uses precise mark-and-sweep collection at compiled safe points. async functions compile to stackless state machines without a guest microtask queue, so await, streams and Promise combinators suspend on WASI 0.3 waitables and resume from host callbacks. Conformance contracts run the same programs under Node.js and Wasmtime, with fuel and memory limits, and compare the results (see Conformance).

Authoring

A component is a TypeScript entry module plus a WIT world. Perry-WIT builds typed components that export WIT functions, CLI commands that run top-level code, and HTTP handlers.

Typed Components

The WIT world declares the exports. Each kebab-case WIT export binds to the matching camelCase TypeScript export; remaining module functions stay internal. The starter template contains this pair:

package example:task@0.1.0;

world task {
    export run-task: func(input: string) -> string;
}

/**
 * Example task component conforming to WIT world `task`.
 * Exported functions map directly to the world contract.
 */
export function runTask(input: string): string {
    return "[task] Processed input: " + input;
}

perry-wit src/index.ts --wit wit --world task -o dist/task.wasm
wasmtime run -C cache=n -S p3=y -W component-model-async=y --invoke 'run-task("hello")' dist/task.wasm

• An async func in WIT binds to an async function returning a Promise.
• A result<T, E> export returns T directly, and a thrown exception becomes err. Returning { ok: true, value } or { ok: false, error } also works.
• --core-only emits the standalone core WebAssembly module. --keep-names preserves function names in the custom name section for guest profiling.
• WASI 0.3 packages resolve from WASI_WIT_PATH. Packages in wit/deps take precedence over them.

Generated Types

perry-wit gen-types writes .d.ts declarations for a world’s imports and exports, plus a tsconfig.json that checks the entry module against them:

perry-wit gen-types --wit wit --world task --entry src/index.ts -o .perry/types
tsc --noEmit -p .perry/types

WIT integer types appear as number and bigint. See Semantics for how the compiler uses them.

Commands

A world that includes wasi:cli/command@0.3.0 turns the module’s top-level statements, including top-level await, into the wasi:cli/run export:

package example:cli@0.1.0;

world app {
  include wasi:cli/command@0.3.0;
}

import { readFile } from "node:fs/promises";

const text = await readFile("input.json", "utf8");
const items: number[] = JSON.parse(text);
console.log("sum:", items.reduce((a, b) => a + b, 0));
if (items.length === 0) process.exitCode = 1;

perry-wit src/main.ts --wit wit --world app -o app.wasm
wasmtime run -S p3=y -W component-model-async=y --dir . app.wasm

console writes to WASI standard output and error, process.env reads the WASI environment, and process.exitCode or process.exit(code) sets the exit status.

If the module also exports functions, its top-level statements initialize the module once instead, and wasi:cli/run and every export wait for that initialization. Top-level statements that start asynchronous work without awaiting it are then a compile error.

HTTP Handlers

A module implementing the perry:http-handler world receives a request record and returns a response record. The compiler wraps it in an adapter, so the component exports wasi:http/handler@0.3.0. The world ships in wit/http-handler:

package perry:http-handler;

interface types {
  variant method { get, head, post, put, delete, connect, options, trace, patch, other(string) }
  variant scheme { http, https, other(string) }
  record request {
    method: method,
    scheme: option<scheme>,
    authority: option<string>,
    path-with-query: option<string>,
    headers: list<tuple<string, list<u8>>>,
    body: list<u8>,
  }
  record response { status: u16, headers: list<tuple<string, list<u8>>>, body: list<u8> }
}

world handler {
  use types.{request, response};
  export handle: func(request: request) -> response;
}

import type { Request, Response } from "./handler-types/world";

const encoder = new TextEncoder();

export function handle(request: Request): Response {
  const path = request.pathWithQuery ?? "/";
  return {
    status: 200,
    headers: [["content-type", encoder.encode("text/plain")]],
    body: encoder.encode(`${request.method.tag} ${path}\n`),
  };
}

perry-wit gen-types --wit wit/http-handler --world handler -o handler-types --no-tsconfig
perry-wit handler.ts --wit wit/http-handler --world handler -o handler.wasm
wasmtime serve -S p3=y -W component-model-async=y handler.wasm

The adapter reads the whole request body before calling handle. An uncaught exception becomes a 500 response, and the instance keeps serving later requests.

New Projects

The flake template creates a standalone project. Its development shell generates .perry/types on entry, and nix build type-checks and compiles the component:

mkdir my-component && cd my-component
nix flake init -t github:ahirner/perry-wit
nix develop
nix build

After editing wit/*.wit inside the shell, run perry-wit gen-types --no-tsconfig --wit wit --entry src/index.ts again before tsc --noEmit -p .perry/types.

Embedding

The compiler ships as the perry_wit Rust crate and as a standalone WASI 0.2 component. The runtime and standard libraries are precompiled and embedded in the compiler binary, so compilation runs entirely in memory.

Rust

perry_wit::api::compile compiles an entry module, auxiliary ESM modules and WIT packages from byte buffers:

use perry_wit::api::{self, Options, Program, Wit};

let program = Program {
    source: br#"
        export function authorize(token: string): boolean {
            return token.startsWith("Bearer ") && token.length > 16;
        }
    "#
    .as_slice()
    .into(),
    modules: vec![],
};

let wit = Wit {
    application: br#"
        package example:auth@0.1.0;
        world filter {
            export authorize: func(token: string) -> bool;
        }
    "#
    .as_slice()
    .into(),
    dependencies: vec![],
};

let compiled = api::compile(&program, &wit, &Options::default())?;
assert!(!compiled.core.is_empty());
assert!(compiled.component.is_some_and(|component| !component.bytes.is_empty()));

Errors are CompileError values holding PerryDiagnostic records with a source span and a DiagnosticCode.

WebAssembly Component

perry-wit.wasm is a WASI 0.2 component that exports this interface (compiler.wit) next to a wasi:cli/run command:

package perry:compiler@0.1.2;

interface api {
  /// Optional diagnostic name; for an entrypoint, also its logical module identity.
  /// Anonymous single-source compilation needs no name. Names never access host files.
  record source {
    name: option<string>,
    contents: list<u8>,
  }
  /// Dependency modules require package-relative logical identifiers for import resolution.
  record module {
    name: string,
    contents: list<u8>,
  }
  record program {
    source: source,
    modules: list<module>,
  }
  variant wit-package {
    sources(list<source>),
    encoded(list<u8>),
  }
  record wit-input {
    application: wit-package,
    dependencies: list<wit-package>,
  }
  record compile-options {
    %world: option<string>,
    /// Omit component wrapping, retaining the selected WIT world's canonical ABI.
    core-only: bool,
  }
  record component-output {
    bytes: list<u8>,
    stripped: list<u8>,
  }
  record compiled {
    core: list<u8>,
    component: option<component-output>,
    allocation-report: string,
  }
  record artifact {
    name: string,
    contents: list<u8>,
  }
  enum diagnostic-code {
    parse-error,
    unsupported-operator,
    unsupported-spread,
    missing-type-annotation,
    unsupported-type,
    unsupported-expression,
    incompatible-record-layout,
    missing-required-field,
    absence-mismatch,
    interface-mismatch,
    export-mismatch,
    import-signature-mismatch,
    module-resolution,
    invalid-input,
    wit-resolution,
    codegen-failure,
    missing-error-channel,
    io,
    internal-compiler-error,
  }
  enum diagnostic-severity { error, warning, info }
  record source-span {
    file: string,
    start-line: u32,
    start-column: u32,
    end-line: u32,
    end-column: u32,
    start-byte: u64,
    end-byte: u64,
  }
  record diagnostic {
    code: diagnostic-code,
    severity: diagnostic-severity,
    message: string,
    span: option<source-span>,
    notes: list<string>,
    help: option<string>,
  }
  compile: func(program: program, wit: wit-input, options: compile-options) -> result<compiled, list<diagnostic>>;
  /// Raw TypeScript exports without WIT. This differs from compile with core-only,
  /// which still checks a WIT world and emits its canonical ABI.
  compile-core: func(program: program) -> result<list<u8>, list<diagnostic>>;
  generate-sdk: func(wit: wit-input, %world: option<string>) -> result<list<artifact>, list<diagnostic>>;
}

world compiler {
  export api;
}

The playground runs it in a Web Worker. Because the api export operates on in-memory buffers, a server can instantiate it with empty filesystem preopens, fuel limits and memory caps to compile untrusted TypeScript.

Semantics

Perry-WIT accepts a statically typed subset of TypeScript. Names, object layouts and host capabilities are resolved at compile time, and a construct outside the subset is a compile error with a source location.

Objects

• Interfaces, type aliases and object literals compile to records with fixed field offsets. Types with the same fields share a layout; classes and recursive types get their own.
• Records keep their declared fields, and prototype mutation is rejected. Record<string, V> dictionaries accept new keys, and delete removes dictionary keys and optional properties.
• An empty object, including const object: any = {}, becomes a dictionary when every write stores the same value type. Writes through local aliases, branches and loops count. An object that escapes, or whose writes store different types, needs a type annotation.
• Unions of literals, records and WIT variants narrow through typeof, equality and discriminant properties.

Arrays

• Arrays (T[]) are dense. Elements share one type or a finite union of numbers, strings, booleans and one plain record shape.
• Reading an index outside the array, or a fractional index, yields undefined when the element type admits it.
• Writing at length appends. Writing at any other index outside 0..length throws RangeError.
• Fresh empty arrays ([], including any[]) infer their element type from push calls and numeric-indexed writes across branches, loops, non-reassigned local aliases and helper returns, widening string literals to string and preserving nested record and array layouts. Inferred arrays support .length, index reads, Object.keys, Array.isArray and JSON.stringify without a replacer; other uses, unresolved writes or no writes require an explicit element type.

Strings

• Strings are UTF-8. Length and indexing count Unicode scalar values and agree with Node.js for text in the Basic Multilingual Plane. Only charCodeAt indexes UTF-16 code units, so past a character outside that plane its positions differ from length and indexOf: '😀x'.length is 2, yet '😀x'.charCodeAt(2) reads the x.
• String.fromCharCode and lone surrogate escapes (\uD800 to \uDFFF) are compile errors. Use String.fromCodePoint.
• Text arriving through the Canonical ABI, JSON.parse or TextDecoder is validated as UTF-8.

Regular Expressions

• Regular expressions require compile-time constant patterns and flags (regex literals or RegExp calls with string literal arguments) and compile to search bytecode.
• test, exec, match, search, split, replace and replaceAll support named capture groups (.groups on exec and non-global match), $<name> replacement templates and synchronous replacement callbacks.

JSON

• JSON.parse decodes into the expected static target type (retaining extra object properties for serialization) or into a dynamic JSON value that is validated when assigned to a typed binding. Reviver callbacks are compile errors.
• JSON.stringify supports synchronous replacer callbacks and property-allowlist arrays. The third indentation argument is a compile error.

Dates

• Date operates in the UTC time zone. Date.parse and new Date(string) accept ISO 8601 year, year-month, date and date-time strings (offset-free strings use UTC). Malformed ISO strings return NaN, whereas non-ISO legacy date formats throw RangeError.
• Temporal.Instant, Temporal.PlainDate and Temporal.PlainDateTime use the ISO 8601 calendar (calendarId is "iso8601", and non-ISO calendar annotations are rejected). PlainDate.from and PlainDateTime.from accept ISO strings, existing instances or field objects (year, month, day and optional hour through nanosecond) with { overflow: "constrain" | "reject" }. add and subtract accept { years?, months?, weeks?, days? } with optional overflow, and until and since accept largestUnit ("day", "week", "month", "year", "auto").

Exceptions

• Error, TypeError, RangeError, ReferenceError and SyntaxError keep name, message and cause through try, catch and finally.
• A failed implicit check produces a fresh error object when caught. Successful checks bypass the exception runtime; explicitly thrown values retain their identity.
• An export declared with a WIT result<T, E> turns an uncaught exception into err. Without a result, an uncaught exception traps, and a trap does not run pending finally blocks.

Async

• An async function runs eagerly until its first suspension. Awaiting an already settled promise continues inline.
• There is no microtask queue in the guest. Waiting tasks resume from WASI 0.3 callbacks, so the order of continuations for different host events follows the host, not Node.js. Observers of the same promise resume in registration order.
• Promise.race leaves the losing tasks running. They must settle before the export returns, or the call traps.
• ReadableStream supports default readers (getReader()), for await loops, BYOB readers (getReader({ mode: "byob" }) with read(view, { min }) into a caller-provided Uint8Array) and explicit cancellation. for await over a byte stream releases the reader lock and cancels the stream when the loop exits early. Releasing a reader lock rejects pending reads but keeps buffered chunks for the next reader.

Numbers

WIT provides fixed-width integers (u8..u64, s8..s64) alongside f32 and f64, while TypeScript provides number (IEEE 754 f64) and bigint.

Keeping u8..s32 as number in generated .d.ts files lets guest code use standard TypeScript arithmetic while giving the compiler range information to emit integer instructions.

Refinement Analysis

Each numeric SSA value carries an optional integer type (width, signedness) and a value interval [min, max]. ProgramFacts propagates ranges forward through arithmetic, branches and calls (including recursion), and propagates required register widths and observation requirements backward through the same worklist to a fixed point [1].

• Register selection: Refined integers whose interval fits in 32 bits lower to i32. Wider refined integers lower to i64. Unrefined values stay in f64.
• Bitwise results: &, |, ^, ~, <<, >> and Math.imul produce s32 values and >>> produces u32, so they lower to i32 instructions even when their operands are unrefined f64 values, which convert with ToInt32. When every use needs only the low bits, refined arithmetic feeding them, such as (a * b) | 0 on u32 values, computes in i32. This deliberately preserves integer wrapping before conversion: at a = b = 4294967295, the result is 1, whereas JavaScript rounds the product before converting and returns 0. A use that observes the full value, such as arithmetic or a comparison, requires a wider register when the result does not fit; a bitwise consumer then truncates at its own use.
• Register-width intermediates: Required widths stay at register size (32 or 64 bits) during computation. Narrowing to 8 or 16 bits happens only at the WIT boundary.
• Literals: An integer literal adopts a required width only when its value fits. Larger literals stay in f64 until converted at the boundary.
• Loops: At a join point, an interval may grow once before widening to the bounds of its register type, or to unbounded endpoints for unrefined numbers. A specialized loop counter wraps at 32 or 64 bits on overflow.
• Guarded ranges: Dominating comparisons of integral operands refine index ranges through the numeric solver’s shared arithmetic and integer bounds. Derived arithmetic and cast ranges must fit the result type. Addition and subtraction preserve one-sided bounds; arithmetic that may produce NaN stays unknown.
• Bounds checks: A proof of 0 <= i < length permits unchecked array reads and stores, and Uint8Array reads. Array proofs account for mutations through aliases. Byte-view proofs use length comparisons or constructor, copy and subarray extents, and require the view to stay attached on every path to the access. Calls, awaits, foreign operations and BYOB reads invalidate these byte-view proofs.

Type Join

Combining two operands takes the least upper bound of their refinements:

Generated Code

package example:numerics@0.1.0;

world numerics {
  export combine-delta: func(base: u8, delta: s8) -> s16;
  export scale-bytes: func(count: u32, stride: u32) -> u32;
}

export function combineDelta(base: number, delta: number): number {
  return base + delta;
}

export function scaleBytes(count: number, stride: number): number {
  return Math.trunc((count * stride) / 1024);
}

Compiling this pair with --core-only emits:

(module
  (type (;0;) (func (param i32 i32) (result i32)))
  (export "scale-bytes" (func $__perry_integer_3_scaleBytes))
  (export "combine-delta" (func $wit_combine_delta))
  (func $__perry_integer_1_combineDelta (;0;) (type 0) (param $v35 i32) (param $v36 i32) (result i32)
    local.get $v35
    local.get $v36
    i32.add
    i32.extend16_s
  )
  (func $__perry_integer_3_scaleBytes (;1;) (type 0) (param $v39 i32) (param $v40 i32) (result i32)
    (local $v47 f64)
    local.get $v39
    i64.extend_i32_u
    local.get $v40
    i64.extend_i32_u
    i64.mul
    f64.convert_i64_u
    f64.const 0x1p+10 (;=1024;)
    f64.div
    f64.trunc
    local.tee $v47
    local.get $v47
    f64.const 0x1p-32 (;=0.00000000023283064365386963;)
    f64.mul
    f64.trunc
    f64.const 0x1p+32 (;=4294967296;)
    f64.mul
    f64.sub
    i64.trunc_sat_f64_s
    i32.wrap_i64
  )
  (func $wit_combine_delta (;2;) (type 0) (param $v56 i32) (param $v57 i32) (result i32)
    local.get $v56
    i32.const 255
    i32.and
    local.get $v57
    i32.extend8_s
    call $__perry_integer_1_combineDelta
  )
)

• combine-delta: The export adapter $wit_combine_delta masks base (i32.and) and sign-extends delta (i32.extend8_s). The sum lies in -128..=382, so the body adds directly in i32.
• scale-bytes: The product of two u32 values is below 2⁶⁴, so i64.mul computes it exactly. Converting that exact product to f64 rounds once, matching JavaScript floating-point multiplication. / is floating-point division, so the division stays in f64.

Boundary Conversion

• Incoming u8..s16: The export adapter masks u8 and u16 arguments and sign-extends s8 and s16 arguments.
• Outgoing u8..s32: Values convert with JavaScript typed-array semantics (ToUint8 through ToInt32), truncating toward zero, mapping NaN and ±Infinity to 0, and wrapping modulo 2^N. Integer and f64 code paths produce identical results.
• u64, s64 (bigint): Out-of-range bigint returns trap at the boundary. Inside guest code, +, -, unary -, comparisons and toString() support arbitrary width. *, /, % and BigInt(number) require 64-bit operands.

package example:boundaries@0.1.0;

world boundaries {
  export scale8: func(a: u8, b: u8) -> u8;
  export to-u8: func(x: f64) -> u8;
  export to-s32: func(x: f64) -> s32;
  export dec-u64: func(x: u64) -> u64;
}

export function scale8(a: number, b: number): number { return a * b; }
export function toU8(x: number): number { return x; }
export function toS32(x: number): number { return x; }
export function decU64(x: bigint): bigint { return x - 1n; }

References

1. M. Stephenson, J. Babb, S. Amarasinghe. Bitwidth Analysis with Application to Silicon Compilation. ACM PLDI, 2000.

Standard Library

Conformance

perry-conformance tests Perry-WIT differentially against Node.js. A contract names one capability, such as ecma.string.operations, and supplies directed cases plus a property-based generator (proptest) of TypeScript programs and inputs. Executable cases and their metamorphic variants run as compiled components in a Wasmtime host with WASI 0.3, fuel metering and memory limits, and under Node.js, except aggregate cases with exact integers beyond 2^53, which use an expected-value model. The runner checks that each variant matches its oracle and that transformations preserve return values, evaluation traces and standard streams. Rejection cases and their variants must report the required diagnostic.

Expected Outcomes

Each case declares what must happen:

Expected-Pass List

passing.txt in perry-conformance lists the contracts that must pass. A listed contract that fails is a regression, and an unlisted contract that passes fails the run until it is added, so the list only grows. deferred.txt records contracts outside the supported domain with their exclusion rationale.

cargo run -p perry-conformance -- check
cargo run -p perry-conformance -- check --select node.fs
cargo run -p perry-conformance -- list
cargo run -p perry-conformance -- doc

--select filters by contract ID prefix. doc prints the catalog table below.

Catalog

The registry holds 63 capability contracts: 63 passing, 0 deferred, 0 pending.

ECMAScript

Web Platform

Node.js

WASI 0.3 Host

Perry-WIT Architecture

Perry-WIT compiles static TypeScript into WASI 0.3 components through Perry HIR and typed SSA MIR built on pliron.

Pipeline

The resolved WIT world feeds five compiler stages:

                  ┌───────────┬─── resolved WIT world ───┬────────────────────────┬────────────┐
                  ▼           ▼                          ▼                        ▼            ▼
TypeScript ──► Source ──► Frontend ──► Elaborate ──► Contract ──► Optimize ──► Codegen ──► Component ──► .wasm
                  1           2            3             4            5           6            7

Top-level statements collect into one function: the wasi:cli/run body in a command-only module, or a one-time initializer that wasi:cli/run and every export await before running. Module bindings persist across calls.

ProgramFacts infers numeric refinements (integer type and interval with two-step loop widening), purity and allocation effects, and parameter escape provenance across functions, including recursive call cycles. The numeric analysis propagates ranges forward and bitwidth demand backward [3]. Numeric refinements select i32, i64, or f64 representations, specialize synchronous callees for the integer argument types known at each call site, and elide bounds checks on proven in-bounds array reads. Closed non-escaping records decompose into scalar SSA values, read-only record parameters of internal synchronous functions promote to one scalar argument per field read, and JSON.parse / JSON.stringify on statically known shapes lower to specialized field decoders and schema-normalizing deep copies. Repeated string appends reuse spare capacity in place when ownership is unique, and single characters read by indexing stay Unicode scalars through comparisons and appends.

During code generation, optional values avoid boxing by reserving sentinel encodings inside the value’s own representation. undefined, null and an omitted property are the signaling-NaN payloads 0x7ff0000000000001 to 0x7ff0000000000003 in an f64, the addresses 0 to 2 for heap references, and 2 to 4 for booleans. WebAssembly arithmetic only produces quiet NaNs, so a computed number never matches a sentinel. Constants rematerialize at use sites, single-use expressions in the same basic block stay on the WebAssembly operand stack when effect and trap ordering permits, and remaining values share WebAssembly locals across non-overlapping live ranges.

Workspace

The compiler workspace separates these responsibilities:

The frontend returns a read-only program and metadata. Record identity and function instance specialization belong to this stage. Evaluation order, numeric refinement, effect analysis, allocation, ABI marshalling and linking belong to the compiler stages below it.

Aggregate inference

The frontend infers the contents of empty arrays and objects from the writes it can see, including writes through local aliases. Numeric indices make an array, and string keys or property names make a dictionary. An array that stores several types gets a value union, while a dictionary needs a single value type.

A dictionary is an array of key-value entries, so the MIR heap analysis treats its values like array elements. That analysis also tracks which parsed JSON records carry undeclared fields, and storing such a record in a dictionary keeps them.

A value union holds a number, string, boolean or one plain record shape, with number | string as the common case. Each value stores a tag, an eight-byte payload and a traced reference, and operators, property reads and typeof checks branch on the tag. Mixed arrays box every element, because packed numeric storage with type transitions is not implemented.

Memory

A component has one linear memory, and the compiler picks its heap strategy per module from the effect summaries of ProgramFacts. perry-wit --explain-tiers prints the choice:

• Task regions when every reachable function allocates a bounded amount, cannot suspend or re-enter, uses no host resources, and the module has no top-level state. Each export call bump-allocates in chunks that grow from 4 KiB to 64 KiB, with a dedicated chunk per larger object, and frees them in bulk when the call ends. A synchronous export frees its region in cabi_post_<export>, after the host has lifted the results, so arguments and results go with the region.
• Precise collection otherwise. Objects up to 512 bytes allocate from non-moving 1 KiB pages across 11 size classes (powers of two and three-quarter midpoints) with mark bitmaps and lazy sweep. A larger object gets a dedicated page rounded up to a 1 KiB multiple, allocated from talc and marked and swept like the rest. Each record type carries a static pointer-offset descriptor so byte buffers and scalar payloads are never scanned for pointers. Compiled safe points clear dead reference slots in suspended async frames, publish exact live roots, and collect mid-call as well as when the last active task ends.

Non-escaping scalar records that still require an address (such as arguments passed to a non-retaining callee) pack into a single per-function activation frame (up to 448 bytes), reusing the same slots across loop iterations and freeing the frame on return. For streams, backward liveness analysis detects when reader.read() or writer.write() results die before the next operation on the same stream, leasing and reusing a single promise, { done, value } record, and chunk buffer in constant memory.

Strings are stored as validated UTF-8 byte sequences with cached Unicode scalar counts (precomputed in the data section for static literals) so character indexing avoids re-scanning ASCII strings. Canonical ABI return areas are zero-initialized and rooted before the host populates them, and export adapters release canonical scratch storage only after task.return completes or all pending host operations acknowledge cancellation.

Static data starts at address 16, above the reference sentinels, followed by relocated library data and the shared scratch stack. The talc allocator claims the remaining bytes of the initial 64 KiB page before growing memory, keeping small components within a single page.

Async

Codegen splits each async function into a ramp function and a resume-state step function. Backward liveness analysis spills only values whose live ranges cross an await into the heap-allocated coroutine frame. Awaiting an already-settled promise continues inline without suspending to the host.

Each pending call has a task record holding its settlement state, outcome, and an intrusive observer list whose nodes live directly inside suspended coroutine frames or combinator records. A settled outcome is retained for repeated observation [4], §3, so later observers borrow it without copying its object graph. Observers awaiting the same native operation share a single WASI 0.3 waitable handle, whose callback resumes them in registration order. Promise.all, allSettled, and race register as observers of their inputs and count settlements, advancing arbitrarily deep dependency chains through host events with bounded guest stack depth. Non-winning branches in Promise.race continue as background tasks, and the export adapter traps if unresolved background work remains when the top-level export finishes.

Readable stream readers decouple public read promises from native transfer completion: releasing a reader lock rejects pending reads while preserving buffered chunks for subsequent readers, explicit cancellation retains the native transfer owner and its pinned buffers until the host acknowledges cancellation, and for await loops cancel and unlock the stream on early exit while giving loop exceptions precedence over cancellation errors.

Runtime

runtime/ is a separate Cargo workspace containing the freestanding #![no_std] runtime and standard libraries. perry-abi supplies layouts, pure algorithms and the Wasm panic handler. perry-rt-sys supplies imports, guest-memory access and native stand-ins. perry-runtime owns allocation and instance state.

Standard-library functions implement UTF-8 validation, Unicode normalization, regex bytecode execution, JSON parsing, number and Decimal conversion, URL and HTTP header parsing, and calendar math. Each artifact package declares its builds in Cargo metadata. The host crate perry-rt-build reads those declarations, builds wasm32-unknown-unknown modules and generates the JSON WAT codecs. The compiler build script embeds the resulting artifacts and the pinned WASI WIT packages, so compiling TypeScript requires no Rust or LLVM toolchain. PERRY_PREBUILT_RUNTIME_DIR selects a directory of prebuilt runtime modules.

Runtime release builds optimize each artifact as one unit: optimization level 2, fat LTO, one codegen unit and aborting panics. The compact profile uses size optimization for the bounded runtime. Target-specific Cargo configuration applies position-independent code to Wasm dependencies; each artifact invocation supplies the shared-library linker arguments.

During linking, a reachability pass from the runtime and standard-library calls emitted by MIR strips unused functions, globals and element tables, compacts type signatures, and relocates the survivors into direct local call instructions that share the guest module’s linear memory, scratch stack and talc allocator.

Runtime crates run their unit tests on the host in their own workspace. The compiler integration suite tests the embedded modules through the linker and Wasmtime.

References

1. N. Ramsey. Beyond Relooper: Recursive Translation of Unstructured Control Flow to Structured Control Flow (Functional Pearl). Proceedings of the ACM on Programming Languages 6(ICFP), 2022.
2. WebAssembly Community Group. Canonical ABI Explainer. WebAssembly/component-model, living design document.
3. M. Stephenson, J. Babb, S. Amarasinghe. Bitwidth Analysis with Application to Silicon Compilation. ACM PLDI, 2000.
4. B. Liskov, L. Shrira. Promises: Linguistic Support for Efficient Asynchronous Procedure Calls in Distributed Systems. ACM PLDI, pp. 260-267, 1988.