TypeScript Best Practices

Schema-first design, strict type safety, and immutable patterns.

Core Principles

1. Type safety at all boundaries: runtime validation (schemas) plus compile-time safety (TypeScript) (principle-parse-at-the-boundary).
2. Schema-first at trust boundaries: where data enters the system, define the schema first and derive the type from it (principle-type-system-discipline).
3. Immutability at the boundary: never mutate a value a caller owns or a value you have already returned. Local mutation is allowed inside the function that created the value, if the value cannot escape before the function returns.
4. Explicit types: no implicit any; strict mode enabled.
5. Behaviour over implementation: focus on contracts and outcomes.

Rules for Hard Cases

No schema library is available

A trust boundary still needs a runtime check. When the dependency set is frozen, add no dependency and do not skip the check. Write a decoder that accepts unknown. Narrow each field with typeof, Array.isArray, or a type predicate. Report an invalid value through the failure path the function already contracts, such as a Result variant or a null return (principle-parse-at-the-boundary).

Building a collection in a hot path