Options are passed as jz(source, opts) or compile(source, opts). Common ones:

jz compiles a distilled JS subset to static WASM — it is not a JavaScript engine and does not chase full TC39 semantics. Valid jz = valid JS means jz source always parses and runs as JS; it does not promise byte-identical results for the cases below. --wat shows exactly what was emitted.

Out of scope — by design, not unfinished. Each needs a runtime jz deliberately does not ship; the compiler errors instead of emitting something slow:

• Dynamic execution & reflection — eval, Function, with, import(), Proxy, Reflect, WeakMap/WeakSet, property descriptors, accessors.
• Concurrency — async/await, Promise, generators, iterators.
• General-runtime surface a numeric / DSP / parser kernel never touches — Intl, realms, resizable ArrayBuffer, DataView, dynamic RegExp patterns, the Symbol registry and most well-known symbols, the full BigInt surface. A few of these have partial static support; the rest will not be added — that is what keeps the output close to hand-written WAT.

Behavioral divergences — valid jz whose result differs from V8. Tracked, narrowing over time:

• Booleans are numbers. true/false compile to 1/0. typeof is recovered statically where a boolean can be proven, but a boolean carried through an untyped binding reports "number", String(true) is "1", and parseInt(true) is 1. A real-boolean carrier is planned.
• Objects are fixed-layout schemas — key set and order fixed at the literal, delete rejected, memory.Object({...}) must match the source key order.
• Errors are untagged — throw carries a value, not a typed Error; e instanceof TypeError does not discriminate.
• Set/Map iterate slot order, not insertion order.
• Memory is not reclaimed automatically — see How does memory work?.

For full TC39 conformance use porffor; jz trades completeness for low-level numeric performance by design.

Numbers pass directly as f64, arrays of ≤ 8 elements return as plain JS arrays (multi-value). Strings, arrays, objects, and typed arrays are heap values — inst.memory provides read/write across the boundary:

[!WARNING] jz objects are fixed-layout schemas (like C structs), not dynamic key bags. memory.Object({ x: 3, y: 4 }) expects the same key order as the jz source { x, y }. { y: 4, x: 3 } with reversed keys will produce wrong values.

const { exports, memory } = jz`
  export let greet = (s) => s.length
  export let sum = (a) => a.reduce((s, x) => s + x, 0)
  export let dist = (p) => (p.x * p.x + p.y * p.y) ** 0.5
  export let rgb = (c) => [c, c * 0.5, c * 0.2]
  export let process = (buf) => buf.map(x => x * 2)
`

// JS → WASM (write)
memory.String('hello')               // → string pointer
memory.Array([1, 2, 3])              // → array pointer
memory.Float64Array([1.0, 2.0])      // → typed array pointer
memory.Int32Array([10, 20, 30])      // all typed array constructors available

// ⚠ Objects: keys and order must match the jz source declaration.
// jz objects are fixed-layout schemas (like C structs), not dynamic key bags.
// If the jz source declares `{ x, y }`, you must pass `{ x, y }` in that order.
memory.Object({ x: 3, y: 4 })       // → object pointer

// Strings/arrays inside objects are auto-wrapped to pointers:
memory.Object({ name: 'jz', count: 3 })  // name auto-wrapped via memory.String

// Call with pointers
exports.greet(memory.String('hello'))          // 5
exports.sum(memory.Array([1, 2, 3]))           // 6
exports.dist(memory.Object({ x: 3, y: 4 }))   // 5

// direct JS array return
exports.rgb(100)      // [100, 50, 20]

// read pointer value
memory.read(exports.process(memory.Float64Array([1, 2, 3])))  // Float64Array [2, 4, 6]

Template interpolation handles most of this automatically — strings, arrays, numbers, and numeric objects are marshaled for you:

jz`export let f = () => ${'hello'}.length + ${[1,2,3]}[0] + ${{x: 5, y: 10}}.x`

Numbers and booleans inline directly into source. Strings, arrays, and objects are serialized as jz source literals and compiled at compile time — no post-instantiation allocation, no getter overhead:

jz`export let f = () => ${'hello'}.length`              // 5 — string compiled as literal
jz`export let f = () => ${[10, 20, 30]}[1]`             // 20 — array compiled as literal
jz`export let f = () => ${{name: 'jz', count: 3}}.count` // 3 — object compiled as literal

// Nested values work too
jz`export let f = () => ${{label: 'origin', x: 0, y: 0}}.label.length`  // 6

Functions are imported as host calls. Non-serializable values (host objects, class instances) fall back to post-instantiation getters automatically.

Yes — standard ES import syntax is bundled at compile-time into a single WASM.

const { exports } = jz(
  'import { add } from "./math.jz"; export let f = (a, b) => add(a, b)',
  { modules: { './math.jz': 'export let add = (a, b) => a + b' } }
)

Transitive imports work (main → math → utils → …). Circular imports error at compile time. Output is always one WASM binary — no runtime resolution.

CLI resolves filesystem imports automatically.

jz main.jz -o main.wasm    # reads ./math.jz, ./utils.jz automatically

Browser: fetch sources yourself, pass via { modules }. The compiler stays synchronous and pure — no I/O.

// Transitive bundling — all merged into one WASM
const { exports } = jz(mainSrc, { modules: {
  './math.jz': 'import { sq } from "./utils.jz"; export let dist = (x, y) => (sq(x) + sq(y)) ** 0.5',
  // Fetch sources yourself, pass them in
  './utils.jz': await fetch('./util.jz').then(r => r.text())
} })

Ship the .wasm and the small host-side bridge that knows the value encoding. jz publishes the bridge under the jz/interop subpath — it has no dependency on the compiler, parser, or watr (only wasi.js), so bundlers tree-shake the compiler out entirely.

jz program.js -o program.wasm    # compile once, anywhere

// In production: no compiler shipped, just the wasm + the interop bridge.
import { instantiate } from 'jz/interop'
import wasmBytes from './program.wasm'   // bundler-specific; or fetch(...)

const { exports, memory } = instantiate(wasmBytes)
exports.greet(memory.String('hello'))    // marshal works the same as compile-time

instantiate(wasm, opts?) accepts Uint8Array, ArrayBuffer, or a pre-built WebAssembly.Module. The returned { exports, memory, instance, module } is identical to what the jz(src) template tag returns — same memory.String/Array/Object/... constructors, same memory.read(ptr) decoder, same handling of imports / shared memory / WASI.

The bridge encodes values as NaN-boxed f64 with bump-allocated heap blobs. One boundary codec per binary — a jz wasm picks its host shape at compile time, the JS host that loads it knows which variant it asked for. Internal representation (whether a number lives as a flat i32, an SSO string stays inline, an object packs its fields) is analysis-driven and per-site, never a user-pickable preset.

Any host namespace — functions, constants, custom objects — wires in via the imports option. jz extracts what's needed via Object.getOwnPropertyNames, so non-enumerable built-ins (Math.sin, Date.now) work automatically:

// Custom function
const { exports } = jz(
  'import { log } from "host"; export let f = (x) => { log(x); return x }',
  { imports: { host: { log: console.log } } }
)

// Whole namespace — sin, cos, sqrt, PI, etc. all auto-wired
const { exports } = jz(
  'import { sin, PI } from "math"; export let f = () => sin(PI / 2)',
  { imports: { math: Math } }
)

// Date static methods
const { exports } = jz(
  'import { now } from "date"; export let f = () => now()',
  { imports: { date: Date } }
)

// window / globalThis
const { exports } = jz(
  'import { parseInt } from "window"; export let f = () => parseInt("42")',
  { imports: { window: globalThis } }
)

For per-call data (numbers, strings, arrays, objects, typed arrays), see How to pass data between JS and WASM? above — pointers via memory.String/memory.Array/memory.Object or template interpolation.

Yes — jz.memory() creates a shared memory that modules compile into. Schemas accumulate automatically, so objects created in one module are readable by another:

const memory = jz.memory()

const a = jz('export let make = () => { let o = {x: 10, y: 20}; return o }', { memory })
const b = jz('export let read = (o) => o.x + o.y', { memory })

// Object from module a, processed by module b — same memory, merged schemas
b.exports.read(a.exports.make())  // 30

// Read from JS too — memory knows all schemas
memory.read(a.exports.make())  // {x: 10, y: 20}

// Write from JS before any compilation
memory.String('hello')      // → NaN-boxed pointer
memory.Array([1, 2, 3])     // → NaN-boxed pointer

jz.memory() returns an actual WebAssembly.Memory (monkey-patched with .read(), .String(), .Array(), .Object(), .write(), etc). You can also pass an existing memory: jz.memory(new WebAssembly.Memory({ initial: 4 })) patches and returns the same object. Passing raw WebAssembly.Memory to { memory } auto-wraps it.

Modules sharing a memory share a single bump allocator — see How does memory work? below. Use .instance.exports for raw pointers, .exports for the JS-wrapped surface.

jz uses a bump allocator: every heap value (string, array, object, typed array) bumps a single pointer forward. No free list, no GC, no per-object header overhead beyond [len][cap]. Bytes 0–1023 are reserved (data segment + heap-pointer slot at byte 1020); the heap starts at byte 1024 and grows the WASM memory automatically when full.

This means memory is never reclaimed implicitly — long-running programs that allocate per call will grow without bound. The fix is to reset the heap pointer between independent batches:

const { exports, memory } = jz`
  export let process = (n) => {
    let xs = []
    for (let i = 0; i < n; i++) xs.push(i * 2)
    return xs.reduce((s, x) => s + x, 0)
  }
`

for (let i = 0; i < 1000; i++) {
  const sum = exports.process(100)   // allocates an array each call
  memory.reset()                     // drop everything; heap ptr → 1024
}

After memory.reset() all previously returned pointers are invalid — read what you need first, then reset.

For finer control, allocate manually: memory.alloc(bytes) returns a raw offset using the same bump pointer. Pure scalar modules (no strings/arrays/objects) are compiled without the allocator at all — no _alloc, no _clear, no memory section.

Non-JS hosts (wasmtime, wasmer, deno, EdgeJS, embedded WASM) get the same allocator via two exports:

(func $_alloc (param $bytes i32) (result i32))   ;; returns heap offset
(func $_clear)                                    ;; rewinds heap pointer to 1024

memory.reset() and memory.alloc() are JS-side aliases for these. Headers vary by type: strings store [len:i32] + utf8 bytes (offset = _alloc(4+n) + 4); arrays / typed arrays / objects store [len:i32, cap:i32] + payload (offset = _alloc(8+bytes) + 8). The pointer crossing the WASM boundary is the f64 NaN-box 0x7FF8 << 48 | type << 47 | aux << 32 | offset — see src/host.js for type codes and the canonical encoders. Call _clear() between batches to reclaim. Strip both with compile(code, { alloc: false }) if you only call functions and never marshal heap values across the boundary.

jz program.js -o program.wasm

# Run with any WASM runtime
wasmtime program.wasm     # WASI support built in
wasmer run program.wasm
deno run program.wasm

Pure numeric modules have no imports and instantiate with standard WebAssembly.Module / WebAssembly.Instance, which is the right shape for JS hosts such as EdgeJS. Compile once at startup or build time, then reuse the module; do not compile JZ source per request.

Two host modes select how runtime services lower:

jz.compile(code)                      // host: 'js' (default) — env.* imports
jz.compile(code, { host: 'wasi' })    // wasi_snapshot_preview1.* imports

host: 'js' (default) — console.log/Date.now/performance.now import from env.* and the JS host (jz() runtime) wires them automatically. Host-side stringification means jz drops __ftoa/__write_*/__to_str from the binary.

host: 'wasi' — console.log compiles to WASI fd_write, clocks to clock_time_get. Output runs natively on wasmtime/wasmer/deno. In JS hosts, the small jz/wasi polyfill is auto-applied; pass { write(fd, text) {…} } to capture stdout/stderr. host: 'wasi' errors at compile time if a program would emit env.__ext_* (dynamic dispatch into the JS host) — annotate the receiver or stay on host: 'js'.

The compiled .wasm uses at most one import namespace:

• none — pure scalar/compute modules. Instantiate directly with standard WebAssembly APIs.
• env — JS-host services (default). Auto-wired by the jz() runtime.
• wasi_snapshot_preview1 — standard WASI Preview 1. Run natively on wasmtime/wasmer/deno.

jz's emitter table (ctx.core.emit) maps AST operators → WASM IR generators. Module files in module/ register handlers on it. To add your own:

import { emitter } from './src/emit.js'
import { typed } from './src/ir.js'

// Register a custom operator: my.double(x) → x * 2
emitter['my.double'] = (x) => {
  return ['f64.mul', ['f64.const', 2], typed(x, 'f64')]
}

The naming convention follows the AST path: Math.sin → math.sin, arr.push → .push, typed variants like .f64:push. See any file in module/ for the full pattern — each exports a function that receives ctx and registers emitters, stdlib, globals, or helpers.

Inside a runtime module, import directly from the layer you need:

import { emit } from '../src/emit.js'
import { asF64, temp } from '../src/ir.js'
import { valTypeOf, VAL } from '../src/analyze.js'

The "explicit > implicit" reflex assumes inference is hidden, fragile, or coercive. jz inference is none of those — the rules are mechanical (name, literals, operators, member access, typeof, assignment flow, JSDoc), the chosen types are visible in --wat output, and ambiguous cases fall back to NaN-boxed f64: a safe default, never a wrong type.

Type annotations (eg. TypeScript) do two different jobs in one syntax:

1. Hints to the compiler about storage (let x: number = 5). That's compiler internals leakage into syntax — inference reads operators (x | 0 → i32), member access (s.length → string), typeof guards, and assignments the way a human reader does. The annotation duplicates what's already in the code.
2. Contracts at module boundaries (function f(id: UserId): User | null). Legitimate — but a documentation concern, not a language concern.

jz keeps the split clean: inference handles storage, JSDoc handles contracts. Valid jz = valid JS — no parallel type system to learn. Annotations don't make code faster; they sharpen what the compiler can already infer.

Yes, via wasm2c or w2c2:

jz program.js -o program.wasm
wasm2c program.wasm -o program.c
cc program.c -o program

npm run test:bench pins every claimed V8 win, AssemblyScript win/tie, and wasm size budget. Mandelbrot is pinned as a V8 win and AssemblyScript tie, not an AS win. Unclaimed rows stay visible as todo gaps without weakening the asserted wins.