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.

Why it is mandatory: without toJSON(), serialization is accidental — it exposes whatever fields happen to be public today and breaks the moment a private field is added. Without toString(), a class interpolated into a string is [object Object], which destroys logs and error context. Both methods make the class's external contract explicit and decoupled from its internal representation (information hiding). See references/tostring-tojson.md for the full rationale, edge cases (circular refs, Date, bigint, secrets redaction), and the copy-ready pattern. Every template in templates/ demonstrates it.

Decision guide

Reference files

• references/idioms.md — every rule above with motivation, a bad example, the idiomatic refactor, TypeScript-specific notes, and when the rule is over-engineering.
• references/tostring-tojson.md — the mandatory toString/toJSON convention in depth: contract, edge cases, redaction, testing.

Templates (copy and adapt)

Non-negotiable defaults

These are silent-failure rules; apply them everywhere from day one:

1. strict: true (and noUncheckedIndexedAccess) in tsconfig.
2. No any in committed code — unknown + narrowing instead.
3. No floating promises — await or explicit void.
4. Every class implements toString() and toJSON().
5. Exported functions have explicit return types.
6. External/untrusted data is validated at the boundary, never cast.