TypeScript Discriminated Union Builder

A discriminated union (also called a tagged union or algebraic data type) is a union type where each member has a common literal property called the discriminant. TypeScript uses this discriminant field to narrow the type in switch/if statements, giving you exhaustive type checking. They model finite sets of states cleanly — like UI states (loading/success/error) or action types in reducers.

Use discriminated unions when your data has mutually exclusive states — never allow a combination that makes no sense in your domain. For example, don't use { data?: T, error?: Error, loading?: boolean } — use a union with discriminant 'status': 'loading' | 'success' | 'error'. This prevents impossible states at the type level and forces exhaustive handling.

By adding a default case that assigns the discriminant to 'never', TypeScript will emit a compile error if you forget to handle a union member. Pattern: default: const _exhaustive: never = state; throw new Error('Unhandled state'). When you add a new state to the union, TypeScript will tell you exactly which switch statements need updating.

TypeScript narrows the type inside each case block based on the discriminant value. If the discriminant is 'status' and the case is 'success', TypeScript knows the full shape including success-only fields. This means you get autocomplete, null-checking, and type errors when accessing fields that don't exist in that state — without any runtime overhead.

Discriminated unions are pure data structures — plain objects with a type discriminant. They're serializable, immutable-friendly, and work great with JSON. Class inheritance requires instantiation and is harder to serialize. In functional TypeScript (Redux, Zustand, React reducers), discriminated unions are preferred. For OOP patterns with methods and polymorphism, classes are more appropriate.