typescript-advanced-practices

TypeScript Practices

Workflow-level habits: design types first, make bad states impossible to construct, validate at the boundary where untyped data enters, and organize modules so the type-first discipline stays easy to keep up.

Mindset

Design the types before writing the implementation — a type is a specification the compiler checks on every subsequent change, and writing it first forces the impossible states question to be answered up front rather than discovered later as a bug. An interface with many optional fields is usually a discriminated union that hasn't been modeled yet: if data and error can theoretically both be set, that combination will eventually occur, and the fix is a type that excludes it, not a runtime check that catches it after the fact. Runtime validation belongs at the boundary — the one place untyped data (an API response, form input, an environment variable) enters the typed world — not scattered through the code that consumes it; validate once there, and let the type system carry the guarantee everywhere downstream.

When to Apply

Use this skill when:

• Starting a new feature and deciding what the types should look like before writing implementation
• Spotting an interface with many optional fields that allow an impossible combination to compile
• Validating data at a system boundary (API responses, form input, environment variables) with Zod
• Deciding how to organize a module's exports (single-function modules, barrel files, internal encapsulation)

Use When

• "Where do I even start typing this feature?"
• "This interface has five optional fields — some combinations don't make sense. How do I fix that?"
• "How do I validate this API response is actually shaped the way I expect?"
• "Should this be one big module or several small ones?"

Scope

In Scope

• Type-first development workflow.
• Making illegal states unrepresentable with discriminated unions.
• Runtime validation with Zod at system boundaries.
• Module organization patterns (single-function modules, barrel exports, encapsulation).