ts-best-practices

# Type Safety This project's TypeScript policy. Apply when writing or reviewing TypeScript. | Rule | Summary | |------|---------| | No `as` casts | Every `as` is a potential runtime crash. Validate at boundaries, then cast only if earned. Prefer Zod/Valibot over manual validation. | | `unknown` over `any` | `any` disables type checking for everything it touches. External data is always `unknown`. | | Discriminated unions | Model variants with a shared literal discriminant. No optional-field bags. | | Narrowing hierarchy | Prefer: discriminated union switch > `in` operator > typeof/instanceof > type guard > `as` | | Type guards | Must actually verify the claim. Name them `isX` or `hasX`. Prefer discriminant narrowing when possible. | | Exhaustiveness checks | Always add `default: never` arm to switches over discriminated unions. Use an `absurd()` helper to reduce boilerplate. | | `satisfies` over `as` | When verifying a value matches a type without widening, use `satisfies` to preserve literal types. | | Impossible states | If a bug requires asking "can this combination happen?" the type is too loose. Tighten it. | Read [references/patterns.md](references/patterns.md) for code examples of each rule.