TypeScript Programming Guide

Toolchain

• Use Bun as the only package manager and runtime.
• Use the following defaults when scripts are missing:

- Install deps: bun install - Type check: bun run tsc --noEmit - Lint + fix: bunx biome check --write <FILEPATH> - Format only: bunx biome format --write <FILEPATH> - Tests: bun test

• Run both Biome and type checks before finishing.
• Avoid introducing ESLint + Prettier in repositories that already use Biome.
• NEVER use npm, pnpm, yarn, npx, or pnpx.

References

Read these files before deep modifications:

• references/biome.md - before editing Biome config, lint rules, or formatting behavior
• references/typescript-conventions.md - before changing API types, async flows, or error handling

Missing vs Empty Policy

• undefined means missing; null means empty.
• Do not manually create undefined (= undefined, return undefined, { key: undefined }).
• Represent missing by omitting keys.

Code Standards

You MUST follow all rules and anti-patterns in the example below before writing code.

import type { IncomingHttpHeaders } from "node:http";
import { randomUUID } from "node:crypto";

// RULE: Prefer `type` for unions/intersections and function signatures.
type UserId = string & { readonly __brand: "UserId" };

interface UserRecord {
  id: UserId;
  email: string;
  headers: IncomingHttpHeaders;
  createdAt: Date;
}

// RULE: Model fallible operations with discriminated unions.
type LoadUserResult = { ok: true; user: UserRecord } | { ok: false; reason: "not_found" | "timeout" };

async function loadUser(id: UserId): Promise<LoadUserResult> {
  if (id.length === 0) {
    return { ok: false, reason: "not_found" };
  }

  return {
    ok: true,
    user: {
      id,
      email: "[email protected]",
      headers: {},
      createdAt: new Date(),
    },
  };
}

// RULE: Accept external input as `unknown`, then narrow.
function parsePort(value: unknown): number {
  if (typeof value !== "string") {
    return 3000;
  }

  const port = Number(value);
  if (!Number.isInteger(port) || port <= 0) {
    return 3000;
  }

  return port;
}

// RULE: Use `satisfies` to validate object shape without widening.
const DEFAULT_CONFIG = {
  timeoutMs: 5_000,
  retry: 2,
} satisfies {
  timeoutMs: number;
  retry: number;
};

function formatResult(result: LoadUserResult): string {
  // RULE: Use exhaustive checks for discriminated unions.
  switch (result.ok) {
    case true:
      return `ok:${result.user.email}`;
    case false:
      return `error:${result.reason}`;
    default: {
      const unreachable: never = result;
      return unreachable;
    }
  }
}

// RULE: Keep indentation shallow with guard clauses.
async function handle(rawId: unknown): Promise<string> {
  if (typeof rawId !== "string" || rawId.length === 0) {
    return "invalid_user_id";
  }

  const result = await loadUser(rawId as UserId);
  return formatResult(result);
}

// RULE: Throw typed errors with actionable context.
class ServiceError extends Error {
  constructor(
    message: string,
    public readonly code: "timeout" | "internal",
  ) {
    super(message);
    this.name = "ServiceError";
  }
}

// ANTI-PATTERN: Use `any` as a default escape hatch.
// function parseBad(x: any): any { ... }

// ANTI-PATTERN: Return tuples for complex multi-field results.
// function loadBad(): Promise<[UserRecord | null, string | null]> { ... }

// ANTI-PATTERN: Throw plain strings.
// throw "something failed";

// ANTI-PATTERN: Mix unrelated behavior with boolean control flags.
// function buildReport(data: Item[], debug: boolean, skipCache: boolean) { ... }

// ANTI-PATTERN: Manually manufacture undefined.
// const badPatch = { nickname: undefined };

Delivery Checklist

Before finishing:

• Ensure Biome checks pass on touched files.
• Ensure tsc --noEmit passes.
• Ensure commands were executed with bun / bunx only.
• Ensure missing/empty semantics are correct (undefined=missing, null=empty).
• Ensure exported APIs have explicit, stable types.
• Ensure async code handles failure paths (timeout, cancellation, transport errors).
• Ensure tests are added or updated for behavior changes.