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 Development - Define schemas before types, derive types from schemas
3. Immutability - No data mutation, always create new values
4. Explicit Types - No implicit any, strict mode enabled
5. Behavior over implementation - Focus on contracts and outcomes

Quick Reference

When to Use Each Guide

Schemas

Use schemas.md when you need:

• Schema-first development patterns
• Decision framework: when schema is required vs optional
• Trust boundary identification
• Test data factory patterns with schema validation
• Examples of schema usage (API responses, business validation)

Types and Interfaces

Use types-interfaces.md when you need:

• Type vs interface guidance
• The any vs unknown decision
• Type assertion best practices
• Strict mode configuration
• tsconfig.json settings

Immutability

Use immutability.md when you need:

• Immutability patterns (spread operators)
• Readonly modifiers
• Forbidden array methods reference
• Options objects vs positional parameters
• Boolean parameter anti-patterns
• Result types for error handling
• Early return patterns

Utilities

Use utilities.md when you need:

• Branded types for domain concepts
• Built-in utility types (Pick, Omit, Partial, etc.)
• Custom utility types
• Code smell reference tables

Patterns

Use patterns.md when you need:

• Schema-first examples at trust boundaries
• Internal type examples without schemas
• Schema with test factory patterns
• Result type for error handling
• Branded types for domain safety
• Immutable array operations
• Options object pattern

Quick Reference: Decision Trees

Should I use a schema?

Does data come from outside the application?
├── Yes → Schema required
└── No → Does it have validation rules (format, range, enum)?
    ├── Yes → Schema required
    └── No → Is it shared between systems?
        ├── Yes → Schema required
        └── No → Type is fine

Should I use type or interface?

Am I defining a behavior contract for dependency injection?
├── Yes → interface
└── No → type

Should I use any or unknown?

Never use any.
Always use unknown for truly unknown types.

Options object or positional parameters?

How many parameters?
├── 1-2 → Positional is fine
└── 3+ → Use options object

Summary Checklist

Before committing TypeScript code, verify:

• Strict mode enabled in tsconfig.json
• No any types (use unknown instead)
• Schemas at all trust boundaries (API, user input, files)
• Types derived from schemas using z.infer
• Using type for data, interface only for behavior contracts
• All data structures use readonly where appropriate
• No array mutations (push, pop, splice, etc.)
• Functions with 3+ params use options objects
• No boolean positional parameters
• Result types for operations that can fail
• Early returns instead of nested conditionals
• Test factories validate with schemas
• Branded types for domain concepts that shouldn't mix
• Explicit return types on functions