TypeScript Best Practices

Production-grade TypeScript development with schema-first design, strict type safety, and immutable patterns.

Core Principles

1. Type Safety at All Boundaries - Runtime validation (schemas) + compile-time safety (TypeScript)
2. Schema-First at Trust Boundaries - Where data enters the system, define the schema before the type, and derive the type from the schema
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. Behavior over implementation - Focus on contracts and outcomes

Rules for Hard Cases

No schema library is available

A trust boundary still needs a runtime check. Do not add a dependency when the dependency set is frozen. 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.

Building a collection in a hot path