Bun Runtime Complete Guide

# Bun Runtime Complete Guide for Google Antigravity

Master the Bun JavaScript runtime for blazing-fast applications with Google Antigravity IDE. This comprehensive guide covers the Bun APIs, native TypeScript support, built-in test runner, package management, and performance optimization patterns that make Bun ideal for modern development.

## Configuration

Configure your Antigravity environment for Bun:

```typescript
// .antigravity/bun.ts
export const bunConfig = {
  runtime: "bun",
  features: {
    nativeTypescript: true,
    builtInAPIs: true,
    testRunner: true
  },
  optimization: {
    preload: true,
    smolStr: true
  }
};
```

## Bun HTTP Server

Create high-performance HTTP servers:

```typescript
// server.ts
const server = Bun.serve({
  port: 3000,
  
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    
    if (url.pathname === "/") {
      return new Response("Hello from Bun!", {
        headers: { "Content-Type": "text/plain" }
      });
    }
    
    if (url.pathname === "/api/users" && request.method === "GET") {
      const users = await getUsers();
      return Response.json(users);
    }
    
    if (url.pathname === "/api/users" && request.method === "POST") {
      const body = await request.json();
      const user = await createUser(body);
      return Response.json(user, { status: 201 });
    }
    
    return new Response("Not Found", { status: 404 });
  },
  
  error(error: Error): Response {
    console.error(error);
    return new Response("Internal Server Error", { status: 500 });
  }
});

console.log(`Server running at http://localhost:${server.port}`);
```

## File System Operations

Use Bun native file APIs:

```typescript
const file = Bun.file("./data.json");
const content = await file.text();
const json = await file.json();
const buffer = await file.arrayBuffer();

await Bun.write("./output.txt", "Hello, World!");
await Bun.write("./data.json", JSON.stringify({ key: "value" }));

const largeFile = Bun.file("./large-video.mp4");
const stream = largeFile.stream();

const watcher = Bun.watch("./src", {
  recursive: true,
  filter: (path) => path.endsWith(".ts")
});

for await (const event of watcher) {
  console.log("File changed:", event.path);
}
```

## SQLite Database

Use the built-in SQLite driver:

```typescript
import { Database } from "bun:sqlite";

const db = new Database("app.db", { create: true });

db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
  )
`);

const insertUser = db.prepare(
  "INSERT INTO users (name, email) VALUES ($name, $email)"
);

const getUser = db.prepare(
  "SELECT * FROM users WHERE id = $id"
);

function createUser(name: string, email: string) {
  return insertUser.run({ $name: name, $email: email });
}

function findUser(id: number) {
  return getUser.get({ $id: id });
}

const result = db.transaction(() => {
  createUser("Alice", "alice@example.com");
  createUser("Bob", "bob@example.com");
  return db.prepare("SELECT * FROM users").all();
})();
```

## Testing with Bun

Write tests using the built-in test runner:

```typescript
import { test, expect, describe, beforeEach, mock } from "bun:test";
import { createUser, getUser, deleteUser } from "./user";

describe("User Service", () => {
  beforeEach(() => {
    // Reset database
  });

  test("creates a new user", async () => {
    const user = await createUser({
      name: "John Doe",
      email: "john@example.com"
    });

    expect(user.id).toBeDefined();
    expect(user.name).toBe("John Doe");
    expect(user.email).toBe("john@example.com");
  });

  test("retrieves user by id", async () => {
    const created = await createUser({
      name: "Jane Doe",
      email: "jane@example.com"
    });

    const found = await getUser(created.id);
    expect(found).toEqual(created);
  });

  test("throws on duplicate email", async () => {
    await createUser({ name: "First", email: "test@example.com" });

    expect(async () => {
      await createUser({ name: "Second", email: "test@example.com" });
    }).toThrow("UNIQUE constraint failed");
  });
});
```

## Password Hashing

Use the built-in password hashing:

```typescript
const password = "secretPassword123";

const hash = await Bun.password.hash(password, {
  algorithm: "argon2id",
  memoryCost: 65536,
  timeCost: 3
});

const isValid = await Bun.password.verify(password, hash);
console.log("Password valid:", isValid);
```

## Best Practices

Follow these guidelines for Bun development:

1. **Use native APIs** - Prefer Bun.file over fs
2. **Leverage TypeScript** - No compilation needed
3. **Use SQLite** - Built-in and fast
4. **Write tests** - Built-in test runner
5. **Stream large data** - Avoid loading into memory
6. **Profile performance** - Use bun --inspect

Google Antigravity IDE provides intelligent Bun API suggestions and performance optimization tips for maximum speed.