typescript-best-practices

Installation
SKILL.md

TypeScript Best Practices

The type system is the cheapest place to make illegal states unrepresentable (principles skill, Type system discipline). Concrete forms:

  • Discriminated unions over boolean flags. type Ev = {kind:'click'; x:number} | {kind:'focus'} — not {isClick:boolean; x?:number}. Exhaustive switch on kind turns missing cases into compile errors.
  • satisfies for configuration literals. {...} satisfies Config keeps literal inference while checking the shape.
  • Parse, don't validate, at boundaries. External data (JSON, env, CLI args, API responses) passes through one parsing function returning a typed result; downstream code takes the parsed type, never any re-cast. unknown in, typed out.
  • Brand primitives that carry meaning. type SessionId = string & {__brand:'SessionId'} when mixing two strings is a realistic bug.
  • No non-null assertions on external data. ! is allowed only where a check on a previous line proves the value; at boundaries it is a runtime crash with compile-time approval.
  • Return types that prevent misuse. A function that can fail returns a result union, not T plus a thrown maybe; callers must handle both arms to compile.
  • readonly by default on shared shapes, mutation as an explicit opt-in.

Reviewing

When reviewing TS, the question per diff hunk is not "does it compile" but "which illegal state did this type just permit" — flag flags-over-unions, boundary anys, and unbranded overlapping primitives.

Installs
28
GitHub Stars
40.8K
First Seen
8 days ago