ScriptGo

A high-performance Ahead-Of-Time (AOT) compiler compiling TypeScript to native standalone executables and WebAssembly (WASI) modules with Node.js core subset parity.

---

ScriptGo is a high-performance native compiler that runs TypeScript and JavaScript with Node.js-compatible semantics while compiling eligible code directly to standalone native binaries or WebAssembly modules. It combines the official TypeScript (Go implementation) compiler frontend for parsing, type-checking, and diagnostics with an independent Typed IR system and an LLVM IR / Native Machine Code backend.

---

Highlights & Features

• High-Performance AOT Compilation: Compiles TypeScript directly to native machine code (Mach-O, ELF, PE) and WebAssembly (.wasm) via LLVM.
• Node.js Core Subset Parity: Full parity across the 392-case regression test corpus checked against Node.js v22+ core subset (392/392, 100%).
• WebAssembly / WASI Target: First-class Ahead-Of-Time compilation to standalone .wasm executables with --target wasm32-wasi, validated on Node.js WASI and Wasmtime.
• Zero-Dependency Native Builds: Automatically uses system clang or auto-detects zig cc for hassle-free out-of-the-box compilation and seamless cross-compilation (macOS, Linux, Windows, WASM).
• Fast Execution: Instantly compiles and runs scripts directly or produces optimized standalone binary builds.
• Modern TypeScript & ECMAScript (ES2022 - ES2025):
  • Explicit Resource Management: Full using and await using resource disposal with Symbol.dispose and Symbol.asyncDispose.
  • ES2024 Set Methods: union(), intersection(), difference(), symmetricDifference(), isSubsetOf(), isSupersetOf(), isDisjointFrom().
  • ES2024 Utilities: Promise.withResolvers(), Object.groupBy(), Map.groupBy(), Array.fromAsync().
  • ES2025 Iterator Helpers: Iterator.from(), map(), filter(), take(), drop(), flatMap(), reduce(), toArray(), forEach(), some(), every(), find().
  • Types & Primitives: number (IEEE-754), bigint, string (UTF-8), boolean, symbol (with Symbol Registry), null, undefined, unknown (with type narrowing), Tuples, Enums (numeric, string, reverse mappings), Union types (T | null | undefined), Monomorphized Generics.
  • Control Flow: if/else, switch/case (with fallthrough), while, do..while, for, for..of, for..in, for await..of, Labeled statements (break label, continue label), try/catch/finally, throw, Array & Object destructuring, Spread/Rest (...), Tagged template literals, Optional chaining & calls (?., fn?.()).
  • Functions & Closures: Lexical closures, arrow functions, default/optional/rest parameters, Generators (function*, yield, yield*), Async Generators.
  • OOP & Classes: Constructors, properties, static fields/methods, Class Static Blocks (static { ... }), Getters/Setters, Inheritance (extends, super), Polymorphic VTables, instanceof.
  • Async Runtime: Promise (resolve, reject, chaining), async/await, microtask queue execution conforming to JavaScript event loop ordering.
  • Web Standards & WinterCG: Streaming fetch() & WHATWG Streams (ReadableStream, WritableStream, TransformStream), URL, URLSearchParams, TextEncoder/TextDecoder, AbortController/AbortSignal.
  • Node.js Standard Library: High-performance native implementations for core Node.js modules (node:fs, node:path, node:os, node:process, node:crypto, node:buffer, node:http, node:net, node:dgram, node:dns, node:domain, node:events, node:stream, node:assert, node:child_process, node:module, node:querystring, node:util, node:timers, node:zlib, node:tls, node:sqlite). All placeholder/dummy stubs strictly removed.

---

Documentation

• docs/typescript-parity-report.md - Comprehensive TypeScript/Node.js core subset feature matrix and parity test report.
• docs/native-subset.md - Native static subset definition and compatibility constraints.
• docs/compilation-tiers.md - Static, Dynamic (QuickJS-ng island), and Unsupported compilation policy.
• docs/application-structure.md - Repository architecture, package ownership, and dependency direction.
• docs/typescript-to-native.md - Pipeline boundaries, IR verification invariants, and LLVM lowering.
• docs/stdlib.md - Standard library API scope and Node.js runtime emulation policy.
• docs/roadmap.md - Project roadmap, milestones, and acceptance criteria.

---

Installation

Install the latest GitHub release on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/pilotworks/scriptgo/main/install.sh | sh

Install a specific release or choose another destination:

curl -fsSL https://raw.githubusercontent.com/pilotworks/scriptgo/main/install.sh | \
  sh -s -- --version 0.1.0-alpha.1 --install-dir /usr/local/bin

The installer detects the host platform, downloads the matching release archive, verifies it against SHA256SUMS, and installs the scriptgo binary. The default destination is ~/.scriptgo; add that directory to PATH if needed. A Clang-compatible native toolchain is still required to compile TypeScript programs.

Run the same command again to upgrade the existing installation to the latest release. The installer verifies and atomically replaces the current binary.

---

CLI Usage

Running Code

# Compile and run immediately on host
scriptgo run examples/hello.ts

# Run with inline TypeScript code
scriptgo run -e "console.log('Hello from ScriptGo!')"

Building Standalone Executables & WebAssembly Modules

# 1. Build a native binary for the host platform
scriptgo build examples/hello.ts -o hello

# 2. Build a WebAssembly (WASI) module
scriptgo build --target wasm32-wasi examples/hello.ts -o hello.wasm

# 3. Execute the generated WASM module via Node.js WASI or Wasmtime
node -e 'const { WASI } = require("wasi"); const fs = require("fs"); const wasi = new WASI({ version: "preview1", args: ["hello.wasm"], returnOnExit: true }); const bytes = fs.readFileSync("hello.wasm"); (async () => { const mod = await WebAssembly.compile(bytes); const inst = await WebAssembly.instantiate(mod, wasi.getImportObject()); wasi.start(inst); })();'
# Or via wasmtime
wasmtime hello.wasm

# 4. Build with debug symbols
scriptgo build examples/hello.ts --debug -o hello-debug

# 5. Build with Clang sanitizers (address, undefined, leak)
scriptgo build examples/hello.ts --sanitize address,undefined -o hello-sanitized

Type Checking & Emitting IR

# Type-check and validate against the native subset
scriptgo check examples/hello.ts

# Emit LLVM IR
scriptgo emit examples/hello.ts -o hello.ll

# Emit verified Typed IR
scriptgo emit examples/hello.ts --mode typed-ir -o hello.ir

---

Showcase Examples

Explore the examples/ directory for complete TypeScript samples:

• examples/hello.ts - Basic hello world script.
• examples/fibonacci.ts - Recursive and iterative performance benchmark.
• examples/classes_oop.ts - OOP with inheritance, class static blocks, getters/setters, and instanceof.
• examples/functional_arrays.ts - Functional Array methods (map, filter, reduce, find, some, every).
• examples/advanced_primitives.ts - BigInt, Symbol registry, and RegExp literals.
• examples/async_generators.ts - Generator functions, async generators, and for await..of loops.
• examples/node_apis.ts - Built-in Node.js APIs (path, crypto, fs, os).

---

Toolchain & Cross-Compilation

ScriptGo uses a Clang-compatible C/LLVM compiler driver to compile emitted LLVM IR and link against the lightweight runtime:

• System Clang: Defaults to clang in your $PATH.
• Zig CC (zig cc): If clang is not installed or when compiling for cross targets (including --target wasm32-wasi), ScriptGo automatically utilizes zig in $PATH for zero-dependency builds and cross-compilation across platforms.

Configuring Compiler Driver & Target Triple

You can configure the C compiler driver and target triple via CLI flags or environment variables:

# 1. WebAssembly / WASI compilation
scriptgo build examples/hello.ts --target wasm32-wasi -o hello.wasm

# 2. Cross-compilation for Linux x86_64
scriptgo build examples/hello.ts --cc zigcc --target x86_64-linux-gnu -o hello-linux

# 3. Via environment variables
export SCRIPTGO_CC="zigcc"
export SCRIPTGO_TARGET="wasm32-wasi"
scriptgo build examples/hello.ts -o hello.wasm

Direct Cross-Compilation via zig cc

You can also emit LLVM IR and cross-compile with zig cc directly:

# 1. Emit LLVM IR
scriptgo emit examples/hello.ts -o module.ll

# 2. Cross-compile for Linux x86_64
zig cc -target x86_64-linux-gnu -O2 -x ir module.ll -x c internal/runtime/runtime.c -o hello-linux

# 3. Cross-compile for Windows x86_64
zig cc -target x86_64-windows-gnu -O2 -x ir module.ll -x c internal/runtime/runtime.c -o hello-windows.exe

# 4. Cross-compile for macOS ARM64
zig cc -target aarch64-macos -O2 -x ir module.ll -x c internal/runtime/runtime.c -o hello-macos

---

Development & Contributing

We welcome contributions! Please check out CONTRIBUTING.md to get started.

# Build binary
make build

# Run all unit & integration tests
make test

# Run TypeScript-Go frontend tests
make test-frontend

# Run Node.js parity comparison benchmark
make test-parity

---

Community & Security

• Contributing Guide: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security Policy: SECURITY.md

---

License

This project is licensed under the MIT License.