typego

[!NOTE] Project Status: TypeGo is under active development. However, please note that maintenance is limited as I am balancing this project with my university commitments. Issues and PRs are welcome but may see delayed responses.

Unlike typical runtimes that communicate over IPC or JSON-RPC, typego runs a JS engine (Sobek) directly inside your Go process. You can import Go packages as if they were native TS modules using the go: prefix, allowing for zero-copy data sharing and direct access to Go’s standard library.

Features

• Direct Go Integration: Import any Go package as a native TS module (go:fmt, go:github.com/gin-gonic/gin).
• Standard Library Intrinsics: Direct access to Go-native keywords and types like go routines, makeChan, select, defer, ref/deref, and make/cap.
• Smarter Type Linker: Automatic, recursive type generation for Go structs, interfaces, and methods. Supports struct embedding (extends) and nested type resolution.
• True Parallelism: Goroutine-based workers with zero-copy shared memory (typego:memory).
• Modern Package Ecosystem: Built-in CLI for managing Go dependencies with typego.modules.json and typego.lock.
• Fast Developer Loop: Hot-reloading dev server and ~0.2s interpreter startup. Compiles to single-binary with --compile.

Tech Stack

• Language: Go 1.21+, TypeScript
• JS Engine: Sobek (fork of Goja, pure Go)
• Bundler: esbuild
• CLI: Cobra

Getting Started

Installation

go install github.com/repyh/typego/cmd/typego@latest

Quick Start

typego init myapp
cd myapp
typego run src/index.ts

Standard Library Intrinsics

TypeGo provides first-class support for Go-native keywords and low-level primitives as global functions.

Project Structure

A standard TypeGo project consists of the following structure:

• src/: Directory for your TypeScript source files.
• typego.modules.json: Dependency manifest for Go packages.
• typego.lock: [New] Auto-generated lockfile for reproducible Go module versions.
• .typego/: [Internal] Managed workspace for build artifacts and cached TypeScript types (go.d.ts).
• package.json: Standard Node.js manifest for NPM dependencies (handled via esbuild).

Commands

Package Management

TypeGo uses a typego.modules.json file to manage Go dependencies. This allows you to use any Go package in your TypeScript code.

# Add a Go package. Ecosystem will automatically resolve versions and sync types.
typego add github.com/gin-gonic/gin

// src/index.ts
import { Default } from "go:github.com/gin-gonic/gin";

const app = Default();
app.GET("/ping", (c) => c.JSON(200, { message: "pong" }));
app.Run();

TypeGo automatically manages a .typego/ workspace, handling go mod tidy, JIT compilation, and TypeScript definition syncing behind the scenes.

Examples

Go Imports

import { Println, Printf } from "go:fmt";
import { Sleep } from "go:sync";

Println("Hello from Go!");
await Sleep(1000);
Printf("Done after %dms\n", 1000);

Workers & Shared Memory

import { makeShared } from "typego:memory";
import { Worker } from "typego:worker";

const shared = makeShared("buffer", 1024);
const worker = new Worker("worker.ts");
worker.postMessage({ buffer: shared });

Concurrency

import { Spawn, Sleep } from "go:sync";

Spawn(async () => {
  for (let i = 0; i < 5; i++) {
    await Sleep(500);
    console.log(`Heartbeat ${i}`);
  }
});

Intrinsics

A short example demonstrating channels, select, and pointer handles (ref/deref).

import { Println } from "go:fmt";

// Channels + select
const ch = makeChan<number>(1);

go(() => {
  ch.send(42);
});

select([
  { chan: ch, recv: (v) => Println("received:", v) },
  { default: () => Println("no message") }
]);

// Pointer handles
const r = ref(100);
Println("before:", deref(r)); // 100
r.value = 200;
Println("after:", deref(r)); // 200

// TypedArray helpers
const buf = make(Uint8Array, 4);
Println("capacity:", cap(buf));

Applications

Limitations

When to Use

Performance

TypeGo is optimized for high-throughput I/O and true parallelism. For a detailed breakdown of the execution model, interop overhead, and optimization strategies, see OPTIMIZATION.md.

Runtime Comparison

Development

Prerequisites

• Go 1.21+
• Node.js 18+ (for NPM packages)

Building from Source

git clone https://github.com/repyh/typego.git
cd typego
go build -o typego.exe ./cmd/typego

Running Examples

./typego run examples/01-hello-world.ts
./typego run examples/02-go-concurrency.ts
./typego run examples/10-typego-stdlib.ts

License

MIT