## When to Use - Use when: types are too broad (`any`, `as unknown`, `as SomeType` casts) - Use when: building a reusable library or SDK that needs precise generics - Use when: needing runtime-safe IDs (userId vs orderId confusion) - Use when: modeling complex state machines with discriminated unions - Do NOT use for: React component prop types — see frontend-patterns - Do NOT use for: Zod schema ↔ type sync — that's in api-design --- ## Branded / Nominal Types ```ts // Prevents mixing IDs from different domains at compile time type Brand = T & { readonly _brand: B }; type UserId = Brand; type OrderId = Brand; function getUser(id: UserId): Promise { ... } // Create branded values at system boundaries const userId = '123' as UserId; const orderId = '456' as OrderId; getUser(userId); // ✅ getUser(orderId); // ❌ TypeScript error — OrderId is not UserId getUser('123'); // ❌ string is not UserId ``` --- ## Discriminated Unions ```ts // Exhaustive state modeling — TypeScript checks all cases type AsyncState = | { status: 'idle' } | { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }; function render(state: AsyncState) { switch (state.status) { case 'idle': return ; case 'loading': return ; case 'success': return ; case 'error': return ; // TypeScript error if a case is missing (with noImplicitReturns) } } ``` --- ## Generic Constraints ```ts // Constrain T to objects with a known shape function pluck(items: T[], key: K): T[K][] { return items.map(item => item[key]); } const names = pluck([{ name: 'Alice', age: 30 }], 'name'); // string[] pluck([{ name: 'Alice' }], 'missing'); // ❌ TypeScript error // Constrain to objects with an id field function findById(items: T[], id: string): T | undefined { return items.find(i => i.id === id); } ``` --- ## Conditional Types + infer ```ts // Extract return type of async function type Awaited = T extends Promise ? R : T; type Result = Awaited>; // string // Extract first argument of a function type FirstArg any> = T extends (first: infer F, ...rest: any[]) => any ? F : never; type F = FirstArg<(id: string, limit: number) => void>; // string // Distributive conditional types type Nullable = T extends null | undefined ? never : T; type Clean = Nullable; // string | number ``` --- ## Mapped Types ```ts // Make all fields optional and readonly type DeepReadonly = { readonly [K in keyof T]: T[K] extends object ? DeepReadonly : T[K]; }; // Create event handler map from event union type EventHandlers = { [K in T['type']]: (event: Extract) => void; }; type AppEvent = | { type: 'USER_LOGIN'; userId: string } | { type: 'PAGE_VIEW'; path: string } | { type: 'PURCHASE'; amount: number }; const handlers: EventHandlers = { USER_LOGIN: ({ userId }) => console.log(userId), PAGE_VIEW: ({ path }) => analytics.track(path), PURCHASE: ({ amount }) => metrics.record(amount), }; ``` --- ## Template Literal Types ```ts type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; type Endpoint = `/${string}`; type Route = `${HttpMethod} ${Endpoint}`; const routes: Route[] = ['GET /users', 'POST /orders']; const invalid: Route = 'FETCH /data'; // ❌ TypeScript error // CSS property builder type CSSProperty = `${string}-${'color' | 'size' | 'weight'}`; ``` --- ## satisfies Operator (TS 4.9+) ```ts // satisfies: validate type without widening — keeps literal inference const config = { port: 3000, env: 'production', db: { host: 'localhost', port: 5432 }, } satisfies Partial; config.port; // type: number (not widened to AppConfig['port']) config.env; // type: 'production' (literal, not string) // vs `as AppConfig` — that would lose literal types // vs `: AppConfig` — that would accept missing fields ``` --- ## Type Guards ```ts // User-defined type guard function isApiError(error: unknown): error is ApiError { return typeof error === 'object' && error !== null && 'code' in error && 'message' in error; } try { await api.call(); } catch (err) { if (isApiError(err)) { console.log(err.code); // typed as ApiError } else { throw err; } } // Assertion function (throws instead of returning false) function assertDefined(val: T | undefined, name: string): asserts val is T { if (val === undefined) throw new Error(`${name} must be defined`); } ``` --- ## Anti-Fake-Pass Rules Before claiming TypeScript types are production-quality, you MUST show: - [ ] `strict: true` enabled — no partial strict mode - [ ] No `any` in public APIs — use `unknown` + type guards instead - [ ] No unchecked `as T` casts — add runtime assertion or type guard - [ ] IDs use branded types — no mixing of `string` ID domains - [ ] State machines use discriminated unions — no `boolean` flag soup - [ ] All `switch` statements over discriminated unions are exhaustive Reference: `gates/anti-fake-pass-gate.md`

typescript-patterns