typescript-best-practices

TypeScript Best Practices & Idioms

How to write TypeScript that the compiler can actually protect: model illegal states out of existence, prefer narrow types over any, make invariants explicit, and keep runtime behavior (serialization, equality, errors) predictable.

🎯 Why: Design for Change

The goal of writing software is to be able to change it safely. Strict types, discriminated unions, branded types, and Result errors turn the compiler into a change-detector: when a shape moves, every caller lights up. any and loose types are change-hiders — they make the next edit look safe while it isn't. Idiomatic TS exists to keep the next refactor mechanical instead of archaeological.

This skill is about idioms and conventions. For OO design pressure use solid-principles and design-principles; for named patterns use gof-patterns. This skill does not re-explain those.

How to use this skill

1. Match the symptom in the decision guide to a rule.
2. Open references/idioms.md for that rule's full rationale, a bad example, the idiomatic refactor, and when not to apply it.
3. Copy the closest file from templates/ and adapt it. The templates already encode the conventions below (strict types, toString/toJSON, exhaustiveness) so you start compliant instead of retrofitting.
4. Apply the smallest change that removes real pain. Strictness is earned by demonstrated bugs, not applied as ceremony — but the defaults here (strict tsconfig, no any, no floating promises) are non-negotiable because their failure mode is silent.

Project rule: every class has toString() and toJSON()

This is a hard convention in this codebase, not a suggestion.

• toJSON() — returns a plain, serializable object. JSON.stringify calls it automatically, so logs, API responses, and persistence get a stable, intentional shape instead of leaking private fields, class internals, or undefined. Never return the instance itself.
• toString() — returns a short human-readable identifier for logs, error messages, and template literals (`order ${order}`). It is for humans; toJSON() is for machines. They are not interchangeable.