typescript-conventions

TypeScript Conventions

Project-wide TypeScript standards that complement agent-specific instructions.

Type Safety

• No any: Use unknown if the type is truly dynamic, then narrow.
• Strict config: strict: true, noUncheckedIndexedAccess, verbatimModuleSyntax.
• Use Readonly<T>, Pick, Omit, and Record for precise types.
• Use branded types for entity IDs (e.g., UserId, OrderId) to prevent mixing.
• Prefer z.infer<typeof schema> over hand-written types when a Zod schema exists.

Interface vs Type

• Interfaces for object shapes that may grow — they support extends and declaration merging.
• Type aliases for unions, intersections, mapped types, and complex compositions.
• Simple rule: interface for plain objects, type for everything else.

// Interface: object shape, extensible
interface User {
  id: string;
  name: string;
}

interface Employee extends User {
  company: string;
}

// Type: union, intersection, computed
type Result = Success | Failure;
type UserProfile = User & { bio: string };
type Nullable<T> = { [K in keyof T]: T[K] | null };

Unions and Literal Types

• Prefer literal unions over enums — zero runtime cost, better tree-shaking, full autocomplete.
• Use enums only when you need a runtime object (iteration, reverse lookup).

// Prefer this
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
type Direction = "north" | "south" | "east" | "west";

// Over this (emits runtime JS)
enum HttpMethod { GET, POST, PUT, DELETE }

Discriminated Unions

Add a type (or kind) literal field to each variant. Always handle exhaustiveness with assertNever.

interface Circle { type: "circle"; radius: number }
interface Square { type: "square"; side: number }
interface Triangle { type: "triangle"; base: number; height: number }

type Shape = Circle | Square | Triangle;

function assertNever(x: never): never {
  throw new Error(`Unexpected value: ${x}`);
}

function area(shape: Shape): number {
  switch (shape.type) {
    case "circle": return Math.PI * shape.radius ** 2;
    case "square": return shape.side ** 2;
    case "triangle": return (shape.base * shape.height) / 2;
    default: return assertNever(shape);
  }
}