typescript-best-practiceslisted

# TypeScript Best Practices ## Pair with React Best Practices When working with React components (`.tsx`, `.jsx` files or `@react` imports), always load `react-best-practices` alongside this skill. This skill covers TypeScript fundamentals; React-specific patterns (effects, hooks, refs, component design) are in the dedicated React skill. ## Type-First Development Types define the contract before implementation. Follow this workflow: 1. **Define the data model** - types, interfaces, and schemas first 2. **Define function signatures** - input/output types before logic 3. **Implement to satisfy types** - let the compiler guide completeness 4. **Validate at boundaries** - runtime checks where data enters the system ### Make Illegal States Unrepresentable Use the type system to prevent invalid states at compile time. **Discriminated unions for mutually exclusive states:** ```ts // Good: only valid combinations possible type RequestState<T> = | { status: 'idle' } | { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }; // Bad: allows invalid combinations like { loading: true, error: Error } type RequestState<T> = { loading: boolean; data?: T; error?: Error; }; ``` **Branded types for domain primitives:** ```ts type UserId = string & { readonly __brand: 'UserId' }; type OrderId = string & { readonly __brand: 'OrderId' }; // Compiler prevents passing OrderId where UserId expected function getUser(id: UserId): Promise<User>