type-patterns

TypeScript Type Patterns

Apply advanced type-level patterns to model domains precisely and catch logic errors at compile time instead of runtime.

When to Use

• Modeling state machines or multi-variant data
• Preventing invalid values (e.g., mixing IDs of different entities)
• Building type-safe string patterns or event systems
• Ensuring all union cases are handled in switch/if chains
• Creating immutable constant objects with full type inference

Core Patterns

Pattern 1: Discriminated Unions

Use a shared literal property to let TypeScript narrow union members automatically.

interface Loading { status: "loading" }
interface Success<T> { status: "success"; data: T }
interface Failure { status: "error"; error: Error }

type AsyncState<T> = Loading | Success<T> | Failure;

function render(state: AsyncState<string>): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data; // narrowed to Success<string>
    case "error":
      return state.error.message; // narrowed to Failure
  }
}

Pattern 2: Exhaustive Checking with never

Guarantee every union variant is handled. If a new variant is added, the compiler flags every switch that misses it.

function assertNever(value: never): never {
  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rect":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
    default:
      return assertNever(shape); // compile error if a case is missing
  }
}

Pattern 3: Branded Types

Prevent mixing structurally identical types by attaching a phantom brand.

type Brand<T, B extends string> = T & { readonly __brand: B };

type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;

function createUserId(id: string): UserId {
  return id as UserId;
}

function createOrderId(id: string): OrderId {
  return id as OrderId;
}

function getUser(id: UserId): void { /* ... */ }

const userId = createUserId("u-123");
const orderId = createOrderId("o-456");

getUser(userId);   // OK
// getUser(orderId); // Compile error -- OrderId is not UserId