⚠️ Project Status

Why Home?

⚡ Speed

🔒 Safety

😊 Joy

Quick Example

import basics/http { Server }import basics/database { Connection }fn main() {  let server = Server.bind(":3000")  let db = Connection.open("app.db")  server.get("/", fn(req) {    return "Hello from Home!"  })  server.get("/users", fn(req) -> async Response {    let users = await db.query("SELECT * FROM users")    return Response.json(users)  })  server.get("/user/:id", fn(req) -> async Response {    let user = await fetch_user(db, req.param("id"))    return Response.json(user)  })  print("Server running on http://localhost:3000")  server.listen()}fn fetch_user(db: &Connection, id: string) -> async Result<User> {  let stmt = db.prepare("SELECT * FROM users WHERE id = ?")  stmt.bind(1, id)  return stmt.execute().first()}struct User {  id: i64  name: string  email: string}

Getting Started

Installation

# Clone repositorygit clone https://github.com/stacksjs/home.gitcd home# Build compilerzig build# Run tests (200+ tests)zig buildtest# Run exampleszig build examples

Your First Home Program

# Run the HTTP server examplezig build example-router# Run the database examplezig build example-database# Run the queue system examplezig build example-queue

Prerequisites

# Install Zigcurl -L https://ziglang.org/download/0.15.0/zig-macos-aarch64-0.15.0.tar.xz| tar xJ# On macOS with Homebrewbrew install zig sqlite3# On Ubuntu/Debiansudo apt install zig libsqlite3-dev# On Arch Linuxsudo pacman -S zig sqlite

Core Architecture

Compiler Packages

packages/├── lexer/          # Tokenization and scanning├── parser/         # AST generation from tokens├── ast/            # Abstract Syntax Tree structures├── types/          # Type system and inference├── diagnostics/    # Error reporting with color output├── interpreter/    # Direct code execution├── codegen/        # Native x64 code generation├── formatter/      # Code formatting├── lsp/            # Language Server Protocol├── pkg/            # Package manager└── testing/        # Modern test framework (snapshots, mocks, benchmarks)

Standard Library Packages

packages/├── basics/         # Core standard library│   ├── http_router # HTTP server with routing│   └── zyte        # Desktop app integration├── database/       # SQL database access (SQLite)├── queue/          # Background job processing├── async/          # Async runtime├── build/          # Build system├── cache/          # Caching utilities└── tools/          # Development tools

Advanced Features

packages/├── comptime/       # Compile-time execution├── generics/       # Generic type system├── macros/         # Macro system├── modules/        # Module system├── patterns/       # Pattern matching├── safety/         # Memory safety checks├── traits/         # Trait system└── acthome/         # GitHub Actions integration

Developer Tooling

packages/└── vscode-home/     # VSCode extension with:    ├── Language Server Protocol (LSP)    ├── Debug Adapter Protocol (DAP)    ├── Time-travel debugging    ├── Memory profiling with leak detection    ├── CPU profiling with flame graphs    ├── Multi-threaded debugging (deadlock detection)    ├── GC profiling with pressure analysis    └── Chrome DevTools format export

Current Capabilities

✅ Working Now

HTTP Server (Laravel-style)

import http_router { Router }let router = Router.init()// Route parametersrouter.get("/user/:id", handler)// Middlewarerouter.use(logger_middleware)router.use(auth_middleware)// Route groupslet api = router.group("/api")api.get("/users", get_users)api.post("/users", create_user)// JSON responsesfn handler(req: Request) Response {  return Response.json(.{ message = "Hello!" })}

Database Access (Native SQLite)

import database { Connection }let conn = Connection.open(":memory:")// Execute SQLconn.exec("CREATE TABLE users (id INTEGER, name TEXT)")// Prepared statementslet stmt = conn.prepare("INSERT INTO users VALUES (?, ?)")stmt.bind_int(1, 42)stmt.bind_text(2, "Alice")stmt.step()// Query with iterationlet result = conn.query("SELECT * FROM users")while (result.next()) |row| {  print("User: {s}", row.get_text(1))}// Query builderlet builder = QueryBuilder.init()  .from("users")  .where("age > 18")  .order_by("name DESC")  .limit(10)let sql = builder.build()  // Generates SQL string

Background Jobs (Queue System)

import queue { Queue, QueueConfig }let config = QueueConfig.default()let queue = Queue.init(config)// Dispatch jobsqueue.dispatch("emails", "send_welcome_email")queue.dispatch_sync("logs", "write_log")  // Execute immediatelyqueue.dispatch_after(60, "cleanup", "purge_cache")  // Delayed// Process jobslet worker = Worker.init(&queue)worker.work(job_handler)// Batch processinglet batch = Batch.init("batch_001")batch.add(job1)batch.add(job2)batch.dispatch(&queue)// Monitor queueprint("Pending: {}", queue.pending_count())print("Failed: {}", queue.failed_count())queue.retry_failed()  // Retry all failed jobs

🏗️ In Progress

Package System

File Extensions

Package Configuration (home.toml orcouch.jsonc)

[package]name ="home-database"version ="0.1.0"authors = ["Home Contributors"]description ="SQL database access with SQLite driver"license ="MIT"[dependencies]home-diagnostics = {path ="../diagnostics" }[scripts]test ="zig test src/database.zig"bench ="zig build bench"

Workspace Root (home.toml orcouch.jsonc)

[package]name ="home"version ="0.1.0"[workspaces]packages = ["packages/*"][scripts]build ="zig build"test ="zig build test"format ="find src packages -name '*.zig' -exec zig fmt {} +"

Installing Home Packages

# Install from registry (planned)home add http database queue# Install from GitHubhome add github:user/repo# Install from Git URLhome add https://github.com/user/repo.git# Install specific versionhome add database@0.1.0

Package Storage

Testing

# Run all tests (200+ tests)zig buildtest# Test specific packagezigtest packages/database/tests/database_test.zig# Run with verbose outputzig buildtest --summary all# Run benchmarkszig build bench

Test Infrastructure

import { test, expect, describe, mock, snapshot } from '@home/testing'describe('User API', () => {  test('creates user successfully', async () => {    const user = await createUser({ name: 'Alice' })    expect(user.name).toBe('Alice')    expect(user).toMatchSnapshot()  })  test('handles validation errors', () => {    const mockDb = mock(database)    mockDb.save.mockReject(new Error('Invalid email'))    expect(() => createUser({})).toThrow('Invalid email')  })})

VSCode Extension & Developer Tools

Installation

# From the Home repositorycd packages/vscode-homenpm installnpm run compile# Install in VSCode# Open Command Palette (Cmd+Shift+P)# Run: Extensions: Install from VSIX

Features

🔍Time-Travel Debugging

// Automatically records snapshots during debugging// Use debugger controls to step back/forward// View variable changes between any two points

💾Memory Profiling

⚡CPU Profiling

🧵Multi-threaded Debugging

🗑️Garbage Collection Profiling

Commands

Home: Start DebuggingHome: Start CPU ProfilerHome: Stop CPU ProfilerHome: Generate Flame GraphHome: Export Chrome DevTools ProfileHome: Start Memory ProfilerHome: Stop Memory ProfilerHome: Take Memory SnapshotHome: Generate Memory ReportHome: Start GC ProfilerHome: Stop GC ProfilerHome: Analyze GC PressureHome: Time-Travel: Step BackHome: Time-Travel: Step ForwardHome: Multi-thread: Show DeadlocksHome: Multi-thread: Show Race Conditions

Keybindings

Examples

HTTP Server Example

zig build example-router

Database Example

zig build example-database

Queue System Example

zig build example-queue

Full-Stack Example

zig build example-fullstack

Language Features (Planned)

Memory Management

// Ownership (implicit, no ceremony)let data = read_file("config.home")  // data owns the string// Automatic borrowingfn process(data: string) {  // compiler infers &string  print(data.len())}process(data)  // auto-borrowprint(data)    // still valid!// Explicit ownership transferfn consume(data: string) {  // takes ownership  // data is moved here}consume(data)// print(data)  // Error: value moved

Error Handling

fn read_config() -> Result<Config> {  let file = fs.read_file("config.home")?  // ? propagates errors  let config = json.parse(file)?  return Ok(config)}match read_config() {  Ok(config) => app.start(config),  Err(e) => log.error("Failed: {e}")}// Or unwrap with defaultlet config = read_config().unwrap_or(Config.default())

Async/Await

fn fetch_users() -> async []User {  let tasks = [    http.get("/users/1"),    http.get("/users/2"),    http.get("/users/3"),  ]  return await Promise.all(tasks)}// Concurrent database queriesfn get_dashboard_data() -> async Dashboard {  let [users, posts, stats] = await Promise.all([    db.query("SELECT * FROM users"),    db.query("SELECT * FROM posts"),    db.query("SELECT COUNT(*) FROM analytics"),  ])  return Dashboard { users, posts, stats }}

Comptime Magic

// Run at compile timecomptime fn generate_routes() -> []Route {  return fs.glob("routes/**/*.home")    .map(|path| Route.from_path(path))}const ROUTES = generate_routes()  // executed during compilation// Compile-time SQL validationcomptime fn validate_query(sql: string) {  let parsed = sql_parser.parse(sql)  if (!parsed.is_valid()) {    @compile_error("Invalid SQL: " ++ sql)  }}// Use at compile timecomptime validate_query("SELECT * FROM users WHERE id = ?")

Pattern Matching

match value {  Ok(x) if x > 0 => print("Positive: {x}"),  Ok(0) => print("Zero"),  Ok(x) => print("Negative: {x}"),  Err(e) => print("Error: {e}")}// Destructuringmatch point {  Point { x: 0, y: 0 } => print("Origin"),  Point { x, y: 0 } => print("On x-axis at {x}"),  Point { x: 0, y } => print("On y-axis at {y}"),  Point { x, y } => print("Point ({x}, {y})")}// Enum matchingmatch response {  HttpResponse.Ok(body) => send(body),  HttpResponse.NotFound => send_404(),  HttpResponse.Error(code, msg) => log_error(code, msg),}

Generics

fn map<T, U>(items: []T, f: fn(T) -> U) -> []U {  let result = []U.init(items.len)  for (item, i in items) {    result[i] = f(item)  }  return result}struct Result<T, E> {  value: union {    Ok(T),    Err(E)  }  fn unwrap(self) -> T {    match self.value {      Ok(v) => return v,      Err(e) => panic("Called unwrap on Err: {e}")    }  }  fn unwrap_or(self, default: T) -> T {    match self.value {      Ok(v) => return v,      Err(_) => return default    }  }}

Performance Goals

Compile Time (vs Zig)

Runtime Performance (vs Zig/C)

Community

Get Involved

Contributors Welcome

FAQ

Comparison

Project Structure

home/├── src/│   ├── main.zig          # CLI entry point│   └── ion.zig           # Compiler library├── packages/             # Core packages (27 total)│   ├── lexer/           # Tokenization│   ├── parser/          # AST generation│   ├── ast/             # Syntax tree│   ├── types/           # Type system│   ├── interpreter/     # Code execution│   ├── codegen/         # x64 generation│   ├── diagnostics/     # Error reporting│   ├── formatter/       # Code formatting│   ├── testing/         # Modern test framework│   ├── basics/          # Standard library│   ├── database/        # SQLite access│   ├── queue/           # Job processing│   └── vscode-home/      # VSCode extension with advanced tooling├── examples/            # Usage examples│   ├── http_router_example.zig│   ├── database_example.zig│   ├── queue_example.zig│   └── full_stack_zyte.zig├── bench/               # Benchmarks├── docs/                # Documentation├── build.zig            # Build configuration└── ion.toml             # Workspace configuration

License

Acknowledgments

Citation

@software{home2025,title ={Home: A Systems Language for Speed, Safety, and Joy},author ={Stacks.js Team and Contributors},year ={2025},url ={https://github.com/stacksjs/home},}