typescript

TypeScript Patterns

Iron Law

UNKNOWN OVER ANY

Never use any. Use unknown with type guards instead. any disables TypeScript's entire value proposition — if you need flexibility, use generics; if you need to handle arbitrary data, use unknown and validate. any is giving up. [1, Item 43]

When This Skill Activates

• Working with TypeScript codebases or designing type-safe APIs
• Using generics, type guards, branded types, or conditional types

---

Type Safety Fundamentals

Prefer Unknown Over Any [1, Item 43]

Types are sets of values [1, Item 7]. any opts out entirely; unknown forces narrowing.

// BAD: disables all type checking [4][17]
function parse(json: string): any { return JSON.parse(json); }
// GOOD: unknown forces narrowing before use [1, Item 43]
function parse(json: string): unknown { return JSON.parse(json); }
if (isUser(data)) console.log(data.name); // type-safe after guard

Exhaustive Checks [1, Item 33][13]

type Status = 'pending' | 'running' | 'completed' | 'failed';
function handleStatus(status: Status): string {
  switch (status) {
    case 'pending': return 'Waiting...';
    case 'running': return 'In progress...';
    case 'completed': return 'Done!';
    case 'failed': return 'Error occurred';
    default: const _: never = status; throw new Error(`Unhandled: ${_}`);
  }
}

---

Generic Patterns [2][6]

function first<T>(items: T[]): T | undefined { return items[0]; }
// Constrained key access [1, Item 54]
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
interface Repository<T, ID = string> { findById(id: ID): Promise<T | null>; save(entity: T): Promise<T>; }

---

Discriminated Unions [1, Item 28][24]

Make illegal states unrepresentable — encode variants in the type [24].

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
type RequestState<T> =
  | { status: 'idle' } | { status: 'loading' }
  | { status: 'success'; data: T } | { status: 'error'; error: Error };