How zackradisic/tyvm works
What this project is (type + purpose)
tyvm is a “compiler + bytecode VM” system for type-level TypeScript:
• Compiler (Rust): takes *TypeScript type-level source* → parses to AST (via oxc) → lowers to a custom IR → emits tyvm bytecode.
• VM (Zig): a stack-based interpreter that executes the bytecode.
• Web demo/site (Next.js): a separate site/ app that loads a WASM build of the VM (and/or related artifacts) to run in the browser.
Read the repo structure as architecture boundaries
Top-level folders clearly map to major components:
Compiler (Rust)
• Cargo.toml, src/
• Key files:
• src/main.rs (likely CLI entry)
• src/lib.rs (library API)
• src/compile.rs (compilation pipeline)
• src/ir.rs (IR definitions)
• src/ir_transform.rs, src/ir_transform_oxc.rs (AST→IR + IR passes)
• src/op.rs (bytecode ops / instruction set)
• src/common.rs (shared types/util)
VM (Zig)
• vm/ with many runtime pieces:
• vm/main.zig (native entry)
• vm/main_wasm.zig (WASM entry)
• vm/vm.zig, vm/tyvm.zig (core VM)
• vm/compiler.zig (potentially bytecode loader/assembler or compilation-related utilities on Zig side)
• vm/json.zig (I/O / decoding support)
• vm/raf/* (requestAnimationFrame integration for WASM/browser scheduling)
• Build tooling:
• build.zig (Zig build, including wasm output)
Web site / demo
• site/ is a Next.js app:
• site/src/pages/* (pages like index.tsx, mnist2.tsx)
• site/src/lib/load_wasm.ts, site/src/lib/wasm_types.ts (WASM bridge)
• site/public/tyvm.wasm (prebuilt wasm artifact checked in)
• site/public/*.ts (examples / demos: mnist.ts, flap.ts, std.ts)
Cross-language integration points
• include/tyvm_compiler.h: indicates a C header for exposing the compiler as a C ABI (used by Zig or other hosts).
• Build/devenv:
• Makefile, flake.nix, shell.nix etc.
Type-level TS Source
• Inputs: test/*.ts, site/public/*.ts (examples)
IR Layer (tyvm IR)
• Nodes: “AST→IR lowering” (ir_transform_oxc.rs)
• “IR transforms / passes” (ir_transform.rs)
Bytecode Emitter
• “IR → bytecode” (compile.rs, op.rs)
• Output artifact: “tyvm bytecode”
VM Runtime (Zig)
• “Bytecode loader/decoder”
• “Stack machine executor”
Outputs
• “Evaluated type-level result / value model”
• Or “converted schema” (future use-case from README: GraphQL/Prisma/JSON Schema)
• “TS types” → “AST” → “IR” → “Bytecode” → “Execution result”
Native CLI path
• User runs: tyvm (Rust src/main.rs)
• Compiler produces bytecode (in-memory or file)
• VM runs:
• either as separate executable (vm/main.zig) consuming bytecode
• or embedded via FFI (Rust exports C ABI via include/tyvm_compiler.h, Zig calls it), depending on actual integration
Browser path
• Next.js site/ serves UI
• UI loads public/tyvm.wasm
• JS/TS glue (load_wasm.ts, wasm_types.ts) calls into WASM exports (from vm/main_wasm.zig)
• WASM executes bytecode; results returned to UI
This view should make it obvious there are two runtime environments:
• Native (Zig executable)
• Browser (WASM module)
An “interfaces/contracts” callout (third mini-view)
Because this project is “compiler + VM”, the most important architecture contract is the bytecode format + instruction set:
• Both compiler and VM depend on this contract.
• “Instruction enum / opcode table” (Rust)
• “Opcode dispatch / interpreter loop” (Zig)
FFI boundary:
• “C ABI: tyvm_compiler.h”
• Who consumes it (likely Zig or other host)
When you label components, add small “implemented in” notes:
• Parser: “oxc” (external)
• Lowering: src/ir_transform_oxc.rs
• IR: src/ir.rs
• IR passes: src/ir_transform.rs
• Bytecode emit / compile driver: src/compile.rs
• Opcodes: src/op.rs
• CLI/library: src/main.rs, src/lib.rs
• VM core: vm/vm.zig, vm/tyvm.zig
• Entrypoints:
• native: vm/main.zig
• wasm: vm/main_wasm.zig
• Browser scheduling: vm/raf/raf_wasm.zig
• Utilities: vm/json.zig
Web UI
• Next pages: site/src/pages/*
• WASM loader/types: site/src/lib/load_wasm.ts, site/src/lib/wasm_types.ts
• Artifact: site/public/tyvm.wasm
Next.js UI → WASM VM
• “instantiate wasm” + “call exports”
Compiler → Bytecode
• output type: “bytecode buffer / file”
VM ← Bytecode
• “decode + execute”
(Optional) Compiler ↔ VM contract
• both share “bytecode spec” (even if not in a single file)
Zig WASM build → site/public/tyvm.wasm
• artifact flow (build pipeline)
Architectural patterns to highlight (specific to tyvm)
• Multi-stage compilation pipeline: AST → IR → bytecode
• “AST Adapter Layer” feeding the same IR
• Stable VM contract: stack machine interpreter over a defined opcode set
• Multi-target runtime: native + wasm
• Functional-language runtime optimizations (called out in README):
• structural sharing (HAMT/RRB)
• static RC optimization / reuse (Perceus-inspired)
• TS type-level source (tests/examples)
→ oxc parser (AST)
→ IR builder (tyvm IR)
→ IR transforms
→ bytecode emitter (opcodes)
→ bytecode
→ Zig VM (native/wasm)
→ result
• Native:
• tyvm compiler CLI → bytecode → tyvm VM native exe
• Web:
• Next.js pages → load wasm → execute bytecode in wasm VM → render result
• Bytecode format / opcode set shared between Rust compiler and Zig VM
• C ABI boundary via include/tyvm_compiler.h (if used)
• “oxc parser” called out as external dependency
• “IR (custom)” called out as the decoupling layer
• “Bytecode ISA / opcodes” as the key shared contract
• “Stack-based VM” explicitly stated
• “Native vs WASM entrypoints” (main.zig vs main_wasm.zig)
• “Next.js demo” and “WASM loader glue”
• Distinguish “build-time artifact” (wasm) from “runtime data” (bytecode)