typescript-best-practices

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.

Rules

• Discipline applies at the boundary and the domain model; inside a single function, pragmatism wins.
• Never introduce a type abstraction with one caller and no second one coming (minimal-code-discipline).