Overview

Relevant source files

• .gitignore
• README.md
• bench/README.md
• bench/bench.js
• bench/hyperfine.sh
• bench/objects.js
• docs/bucketlist.md
• pkg/checker/checker.go
• pkg/checker/expressions.go
• pkg/compiler/compile_assignment.go
• pkg/compiler/compile_expression.go
• pkg/compiler/compile_literal.go
• pkg/compiler/compile_statement.go
• pkg/compiler/compiler.go
• pkg/compiler/emit.go
• pkg/lexer/lexer.go
• pkg/parser/ast.go
• pkg/parser/parser.go
• pkg/vm/bytecode.go
• pkg/vm/ic_site_cache.go
• pkg/vm/vm.go

Purpose and Scope

This page provides a high-level architectural overview of Paserati, a TypeScript/JavaScript runtime that compiles TypeScript directly to bytecode and executes it on a register-based virtual machine. It covers the major subsystems, their interactions, and the data flow from source code to execution.

For detailed information on specific subsystems, see:

• Compilation pipeline details: Compilation Pipeline
• Type checking details: Type Checker
• VM execution details: Virtual Machine
• Built-in objects: Built-in Objects
• Module system: Module System

---

System Architecture

Paserati is organized into distinct subsystems that transform TypeScript source code into executable bytecode and manage its execution:

Sources: pkg/driver/driver.go1-100 cmd/paserati/main.go1-50 README.md1-150

The Driver struct maintains a persistent session with reusable VM, Checker, and Compiler instances, enabling REPL-style interactive execution while preserving state across multiple compilations.

---

Compilation Data Flow

Source code passes through a series of transformations, with each stage adding semantic information:

Sources: pkg/lexer/lexer.go326-450 pkg/parser/parser.go420-467 pkg/checker/checker.go425-580 pkg/compiler/compiler.go484-530 pkg/vm/vm.go595-726

Token Stream

The Lexer struct tokenizes source code into Token values, each containing:

• Type (e.g., IDENT, NUMBER, STRING, FUNCTION)
• Literal (the actual text)
• Position information (Line, Column, StartPos, EndPos)
• Template literal state for handling backtick strings with interpolations

Sources: pkg/lexer/lexer.go49-63 pkg/lexer/lexer.go326-450

Abstract Syntax Tree

The Parser struct uses a Pratt parser to build an AST with nodes implementing either Statement or Expression interfaces. Key node types:

• Program - root node containing statements and hoisted declarations
• FunctionLiteral, ArrowFunctionLiteral - function definitions
• ClassDeclaration - class definitions
• InfixExpression, CallExpression - operations and calls
• Identifier, MemberExpression, IndexExpression - property access

Sources: pkg/parser/parser.go24-44 pkg/parser/ast.go14-50

Type Checking

The Checker struct performs multi-pass semantic analysis:

Each Expression node receives a ComputedType field populated during checking, enabling downstream type-aware compilation.

Sources: pkg/checker/checker.go425-698 pkg/parser/ast.go29-49

Bytecode Generation

The Compiler struct translates the typed AST into a Chunk of bytecode:

• Code []byte - sequence of OpCode instructions
• Constants []vm.Value - constant pool for literals and functions
• ExceptionTable []*ExceptionHandler - try/catch/finally metadata
• MaxRegs int - register allocation requirement
• NumSpillSlots int - spill slot allocation for register overflow

Sources: pkg/compiler/compiler.go217-300 pkg/vm/bytecode.go1-200

---

Runtime Architecture

The VM struct executes bytecode using a register-based architecture:

Sources: pkg/vm/vm.go146-309 pkg/vm/vm.go102-136 pkg/vm/value.go1-150 pkg/vm/object.go1-200

Register-Based Execution

The VM uses a fixed-size register file (RegFileSize = 256 registers per frame, MaxFrames = 1024 call depth). Each CallFrame holds a slice window into the flat registerStack, avoiding per-call allocations:

Sources: pkg/vm/vm.go19-22 pkg/vm/vm.go146-155

Value System

The Value struct uses a tagged union design:

• Primitives stored inline in payload (8 bytes)
• Objects referenced via obj pointer
• typ field discriminates between value types

Sources: pkg/vm/value.go14-80

Object Model and Shapes

Objects use a shape-based system (hidden classes) for memory efficiency:

• Shape defines property layout and order
• Objects with identical property sets share the same Shape
• Property access compiles to inline-cached lookups using shape+offset

Sources: pkg/vm/object.go178-280 pkg/vm/shapes.go1-200

---

Type System Architecture

The type system provides static analysis through the Type interface hierarchy:

Sources: pkg/types/types.go1-150 pkg/types/types.go300-500

Environment and Scope Management

The Environment struct manages nested scopes with separate namespaces:

• variables map[string]Type - value bindings
• types map[string]Type - type alias bindings
• typeParameters map[string]*TypeParameter - generic type parameter bindings
• narrowings map[string]Type - control-flow refined types
• Outer *Environment - lexical parent scope

Sources: pkg/checker/environment.go1-100

Type Operations

Key type operations implemented by the checker:

• IsAssignable(source, target Type) bool - structural compatibility checking
• inferGenericFunctionCall() - two-phase generic inference
• detectTypeGuard() - control-flow narrowing via type guards
• instantiateGenericType() - generic type instantiation with substitution

Sources: pkg/types/assignable.go1-500 pkg/checker/checker.go2000-2500

---

Module System

The module system coordinates separate compilation units while preventing global index collisions:

Sources: pkg/compiler/heapalloc.go1-200 pkg/modules/loader.go1-150 pkg/vm/vm.go73-82

HeapAlloc Coordination

The HeapAlloc struct ensures global variable indices don't collide across modules:

• Maintains a registry of allocated indices
• Thread-safe allocation via sync.RWMutex
• Shared across all module compilers in a session

Sources: pkg/compiler/heapalloc.go15-100

Module Execution

The OpEvalModule instruction triggers module evaluation:

1. Checks ModuleContexts cache for prior execution
2. If not cached, executes module chunk and stores exports
3. Returns cached exports on subsequent imports

Sources: pkg/vm/vm.go73-82 pkg/vm/op_eval_module.go1-150

---

Built-in Environment

The standard library initializes through a two-phase process:

Sources: pkg/builtins/registry.go1-100 pkg/builtins/object.go1-150

Initialization Priorities

Built-ins are initialized in dependency order:

• Object: priority 0 (base of inheritance)
• Function: priority 1 (functions inherit from Object)
• Array: priority 2 (arrays inherit from Object)
• TypedArray: priority 419 (base for typed array types)
• Uint8Array: priority 420 (inherits from TypedArray)

Sources: pkg/builtins/registry.go50-150

Built-in Categories

Key built-in groups:

• Core objects: Object, Array, String, Number, Boolean, BigInt
• Functions: Function.prototype.call/apply/bind
• Error handling: Error, TypeError, ReferenceError, RangeError
• Collections: Map, Set, typed arrays
• Async: Promise, async generator protocol
• Reflection: Proxy, Reflect, Symbol

Sources: pkg/builtins/registry.go1-200 pkg/builtins/array.go1-100 pkg/builtins/function.go1-100

---

Key Design Decisions

Register-Based VM

Paserati uses registers instead of a stack-based architecture:

• Advantage: Fewer bytecode instructions per operation (no push/pop)
• Advantage: Better modeling of local variables (direct register assignment)
• Trade-off: Larger instruction encoding (register operands), fixed register limit (256 per frame)

Sources: pkg/vm/vm.go19-22 docs/bucketlist.md202-225

Inline Caching

Property access uses per-site inline caches transitioning through states:

• Uninitialized → Monomorphic → Polymorphic → Megamorphic
• Caches shape+offset pairs for fast repeated access
• Stored directly in Chunk for cache-local access

Sources: pkg/vm/ic_site_cache.go1-31 pkg/vm/inline_cache.go1-200

Shape-Based Objects

Objects use hidden classes for memory efficiency:

• Property layout defined by Shape
• Shape transitions on property addition
• Inline cache validation uses shape identity

Sources: pkg/vm/shapes.go1-200 pkg/vm/object.go178-280

Multi-Pass Type Checking

The checker uses four passes to handle forward references:

• Pass 0: Pre-register interface/type alias names
• Pass 1: Define all type aliases, interfaces, classes
• Pass 2: Register hoisted function signatures and variables
• Pass 3: Check function bodies and expressions

This allows mutually recursive types and functions.

Sources: pkg/checker/checker.go425-698

Tail Call Optimization

Enabled by default (enableTCO = true), TCO reuses the current frame for tail-positioned calls:

• Identifies tail calls during compilation
• Emits OpTailCall instead of OpCall+OpReturn
• Critical for functional programming patterns

Sources: pkg/compiler/compiler.go204 pkg/compiler/compile_expression.go800-950

Direct Eval Support

Direct eval (calling eval by name) receives special treatment:

• OpDirectEval instruction with caller scope access
• evalCallerRegs provides read/write access to caller's registers
• ScopeDescriptor maps caller's variable names to register indices

Sources: pkg/vm/vm.go264-278 pkg/vm/scope_descriptor.go1-100