Course contentsShow
← TypeScript
Lesson 1509 of 1,79634. The Limits of TypeScriptFree lesson

Embrace Runtime Checks Over Type Gymnastics

Learn when to use simple runtime validation instead of complex type-level code for better maintainability.

Embrace Runtime Checks Over Type Gymnastics

You'll learn when elaborate type-level code creates more problems than it solves, and how simple runtime validation often delivers better maintainability.

The Core Idea

TypeScript's advanced type features—recursive conditionals, complex mapped types, intricate generic constraints—are powerful tools. But they exist only at compile time. When types become so complex that error messages span hundreds of lines, when IDE performance crawls, when teammates can't understand what a type does, you've crossed into territory where runtime validation would be simpler, clearer, and more maintainable.

Think of it like building elaborate scaffolding around a house: at some point, the scaffolding becomes more complex than the house itself. Sometimes it's better to build the house and inspect it afterward than to create ever-more-intricate supports that slow down every change.

When Type Gymnastics Become Counterproductive

You've reached diminishing returns when:

  • Error messages reference 15 intermediate types and take 30 seconds to appear
  • New team members need a guide to understand a single type definition
  • IDE autocomplete freezes while resolving deeply nested conditionals
  • A simple data change requires updating five interconnected type utilities
  • You're simulating higher-kinded types or building type-level parsers

The compile-time guarantee isn't worth it if the code becomes unmaintainable.

The Runtime Alternative

Instead of encoding every constraint in types:

// Complex type gymnastics approach
type ValidUser<T> = T extends { name: string; age: number }
  ? T['age'] extends infer A
    ? A extends number
      ? A extends 0 | 1 | 2 | 3 | 4 | 5 // (continues for every valid age...)
        ? never
        : A extends 120 | 121 | 122 // (continues checking upper bound...)
          ? never
          : T
      : never
    : never
  : never;

// Simple runtime approach
function validateUser(data: unknown): data is { name: string; age: number } {
  if (typeof data !== 'object' || data === null) return false;
  const user = data as Record<string, unknown>;
  return (
    typeof user.name === 'string' &&
    typeof user.age === 'number' &&
    user.age >= 6 &&
    user.age < 120
  );
}

The runtime version is readable, debuggable, and testable. The type version might catch errors at compile time, but at what cost?

The Balanced Approach

Use TypeScript's type system for:

  • Structure and shape (objects, arrays, basic unions)
  • Autocompletion and documentation
  • Preventing basic mistakes (wrong property names, mismatched function arguments)

Use runtime validation for:

  • Business rules (age ranges, string formats, relational constraints)
  • External data (API responses, user input, configuration files)
  • Complex conditional logic that would require elaborate type-level code

Analogy: Building Inspectors

TypeScript types are like building codes that prevent certain constructions at blueprint stage. But you wouldn't encode every safety rule (electrical load calculations, soil composition requirements, weather resistance) into the blueprint language itself—that's what building inspectors are for. Some checks are simply better performed on the actual building (at runtime) than prevented by increasingly complex drawing rules (at compile time).

Key Takeaway: Prioritize code maintainability over compile-time exhaustiveness. When types become harder to understand than the runtime logic they protect, choose runtime validation with simpler types.