typescript-best-practices

A style guide for writing type-safe TypeScript that prevents invalid states at compile time. Apply this when reading or editing .ts or .tsx files to enforce discipline around the type system, boundary validation, and runtime safety.

• Use discriminated unions with literal discriminants to model variants and prevent impossible states
• Brand primitives to prevent type confusion and enforce validation at boundaries
• Construct types so illegal values cannot be represented (e.g., non-empty arrays, even-length tuples)
• Prefer `unknown` over `any` for external data and validate at system boundaries
• Use schema-derived types and runtime validation libraries instead of hand-written type guards
• Avoid `as` casts; cast only after validation and use `satisfies` to preserve literal types

1. 1.Apply the type-system-discipline principle skill first
2. 2.Review the rules table for the specific pattern you're implementing
3. 3.Check `references/patterns.md` for concrete examples
4. 4.When modeling variants, use a `kind` literal discriminant instead of optional fields
5. 5.When accepting external data, parse it into a named domain type at the boundary
6. 6.Use schema libraries (e.g., Zod) and infer types rather than hand-writing guards