webdev-typescript-patterns

TypeScript Patterns

Production-ready TypeScript 5.x patterns emphasizing type safety, inference, and maintainability.

Core Principles

1. Type safety over convenience - Avoid any; use unknown when the type is genuinely uncertain
2. Enable strict mode from day one - All strict flags on; never selectively disable
3. Prefer inference over annotation - Let TypeScript infer when the result is unambiguous
4. Model domain states explicitly - Use discriminated unions to make illegal states unrepresentable
5. Types are documentation - Well-named types replace comments and reduce cognitive load

Type System Fundamentals

Use unions, intersections, and literal types to model data precisely

// Literal types constrain to exact values
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";

// Intersection types compose capabilities
type Timestamped = { createdAt: Date; updatedAt: Date };
type SoftDeletable = { deletedAt: Date | null };
type BaseEntity = Timestamped & SoftDeletable & { id: string };

// Union types model alternatives
type Result<T> = { ok: true; value: T } | { ok: false; error: Error };

// Template literal types build string patterns
type EventName = `on${Capitalize<"click" | "focus" | "blur">}`;
// => "onClick" | "onFocus" | "onBlur"

Key rules:

• Use string literal unions instead of enum for simple value sets
• Prefer interface for object shapes that may be extended; type for unions and computed types
• Use readonly arrays and tuples to prevent mutation

See type-system-patterns.md for:

• Conditional types and infer keyword
• Mapped types and key remapping
• Template literal type utilities
• Index signatures and record patterns

Generics

Use generics to write reusable, type-safe abstractions

// Constrained generic with default
interface Repository<T extends { id: string }, K extends keyof T = "id"> {
  findById(id: T[K]): Promise<T | null>;
  findAll(filter?: Partial<T>): Promise<T[]>;
  save(entity: Omit<T, "id">): Promise<T>;
}

// Generic function with inference
function groupBy<T, K extends string | number>(
  items: T[],
  keyFn: (item: T) => K
): Record<K, T[]> {
  return items.reduce((acc, item) => {
    const key = keyFn(item);
    (acc[key] ??= []).push(item);
    return acc;
  }, {} as Record<K, T[]>);
}

// Usage - types inferred from arguments
const grouped = groupBy(users, (u) => u.role);
// => Record<string, User[]>