🎯 Discriminated Unions: Pattern Matching Magic

🎯 Introduction

Welcome to the fascinating world of discriminated unions! 🎉 In this guide, we’ll explore one of TypeScript’s most powerful features for creating type-safe, expressive code that eliminates entire classes of runtime errors.

You’ll discover how discriminated unions can transform complex conditional logic into elegant, bulletproof patterns. Whether you’re building state machines 🤖, API responses 🌐, or complex data structures 📚, discriminated unions provide unmatched type safety and developer experience.

By the end of this tutorial, you’ll be crafting sophisticated pattern matching systems that make your code both safer and more readable! Let’s dive in! 🏊‍♂️

📚 Understanding Discriminated Unions

🤔 What is a Discriminated Union?

A discriminated union is like a sophisticated traffic light system 🚦. Each “state” has a unique identifier (the discriminant) that tells you exactly which type you’re dealing with, plus additional data specific to that state.

In TypeScript terms, a discriminated union combines multiple types where each type has a common property (the discriminant) with a literal value that uniquely identifies it. This means you can:

• ✨ Eliminate “impossible states” - no more invalid combinations
• 🚀 Get exhaustive checking - TypeScript ensures you handle all cases
• 🛡️ Achieve perfect type narrowing - access properties with complete safety

💡 Why Use Discriminated Unions?

Here’s why developers love discriminated unions:

1. Exhaustive Pattern Matching 🔒: TypeScript ensures you handle every case
2. Impossible States Made Impossible 💻: Prevent invalid state combinations
3. Self-Documenting Code 📖: The structure tells the story
4. Bulletproof Refactoring 🔧: Add new cases and get compile errors where you need to update

Real-world example: Imagine building an API response system 🛒. With discriminated unions, you can represent success, loading, and error states in a way that makes it impossible to accidentally access error messages when you’re in a success state!

🔧 Basic Syntax and Usage

📝 Simple Example

Let’s start with a classic discriminated union:

// 🚦 Traffic Light States
type TrafficLight = 
  | { type: 'red'; timeLeft: number; emoji: '🔴' }
  | { type: 'yellow'; timeLeft: number; emoji: '🟡' }
  | { type: 'green'; timeLeft: number; emoji: '🟢' };

// 🎯 Pattern matching function
function getAction(light: TrafficLight): string {
  switch (light.type) { // 👈 TypeScript knows the discriminant!
    case 'red':
      return `Stop! ${light.emoji} Wait ${light.timeLeft}s`;
    case 'yellow':
      return `Caution! ${light.emoji} ${light.timeLeft}s left`;
    case 'green':
      return `Go! ${light.emoji} ${light.timeLeft}s remaining`;
    // 🎉 No default case needed - all cases handled!
  }
}

💡 Explanation: Notice how type is our discriminant property! TypeScript automatically narrows the type in each case, giving us perfect autocomplete and type safety.

🎯 Common Patterns

Here are the essential discriminated union patterns:

// 🏗️ Pattern 1: API Response States
type ApiResponse<T> = 
  | { status: 'loading'; progress?: number }
  | { status: 'success'; data: T; timestamp: Date }
  | { status: 'error'; error: string; code: number };

// 🎨 Pattern 2: Form Validation
type ValidationResult = 
  | { valid: true; value: string }
  | { valid: false; errors: string[]; originalValue: string };

// 🔄 Pattern 3: State Machine Events
type PlayerAction = 
  | { type: 'PLAY'; song: string }
  | { type: 'PAUSE' }
  | { type: 'STOP' }
  | { type: 'SKIP'; direction: 'forward' | 'backward' };

💡 Practical Examples

🛒 Example 1: E-commerce Order States

Let’s build a real-world order management system:

// 📦 Order states with different data for each state
type Order = 
  | { 
      status: 'pending'; 
      items: string[]; 
      estimatedTotal: number;
      customerEmail: string;
    }
  | { 
      status: 'confirmed'; 
      orderId: string;
      items: string[];
      total: number;
      paymentMethod: string;
      customerEmail: string;
    }
  | { 
      status: 'shipped'; 
      orderId: string;
      trackingNumber: string;
      estimatedDelivery: Date;
      carrier: string;
    }
  | { 
      status: 'delivered'; 
      orderId: string;
      deliveredAt: Date;
      signedBy?: string;
    }
  | { 
      status: 'cancelled'; 
      orderId?: string;
      reason: string;
      refundAmount?: number;
    };

// 🎯 Order processor with exhaustive matching
class OrderProcessor {
  processOrder(order: Order): string {
    switch (order.status) {
      case 'pending':
        // 🔍 TypeScript knows we have customerEmail and estimatedTotal
        return `⏳ Order pending for ${order.customerEmail}. Estimated: $${order.estimatedTotal}`;
      
      case 'confirmed':
        // 💳 TypeScript knows we have orderId and paymentMethod
        return `✅ Order ${order.orderId} confirmed! Paid via ${order.paymentMethod}`;
      
      case 'shipped':
        // 🚚 TypeScript knows we have trackingNumber and carrier
        return `🚛 Order ${order.orderId} shipped via ${order.carrier}. Tracking: ${order.trackingNumber}`;
      
      case 'delivered':
        // 📫 TypeScript knows we have deliveredAt
        const signInfo = order.signedBy ? ` Signed by: ${order.signedBy}` : '';
        return `📦 Order ${order.orderId} delivered on ${order.deliveredAt.toDateString()}.${signInfo}`;
      
      case 'cancelled':
        // ❌ TypeScript knows we have reason and optional refundAmount
        const refund = order.refundAmount ? ` Refund: $${order.refundAmount}` : '';
        return `❌ Order cancelled. Reason: ${order.reason}.${refund}`;
        
      // 🎉 No default needed - TypeScript ensures all cases handled!
    }
  }
  
  // 🔄 State transitions with validation
  canTransitionTo(order: Order, newStatus: Order['status']): boolean {
    switch (order.status) {
      case 'pending':
        return ['confirmed', 'cancelled'].includes(newStatus);
      case 'confirmed':
        return ['shipped', 'cancelled'].includes(newStatus);
      case 'shipped':
        return ['delivered'].includes(newStatus);
      case 'delivered':
      case 'cancelled':
        return false; // 🔒 Final states
    }
  }
}

🎯 Try it yourself: Add an ‘on-hold’ status and update the transition logic!

🎮 Example 2: Game Combat System

Let’s create a type-safe combat system:

// ⚔️ Combat actions with different requirements
type CombatAction = 
  | { type: 'attack'; weaponId: string; targetId: string; damage: number }
  | { type: 'defend'; shieldValue: number; duration: number }
  | { type: 'heal'; amount: number; targetId?: string }
  | { type: 'cast_spell'; spellId: string; manaCost: number; targets: string[] }
  | { type: 'flee'; escapeChance: number; destination?: string };

// 🏆 Combat result states
type CombatResult = 
  | { outcome: 'success'; damage?: number; healing?: number; effect?: string }
  | { outcome: 'failure'; reason: string; penaltyApplied?: boolean }
  | { outcome: 'critical'; multiplier: number; damage: number; specialEffect: string }
  | { outcome: 'blocked'; blockedDamage: number; counterAttack?: boolean };

class CombatEngine {
  executeAction(action: CombatAction): CombatResult {
    switch (action.type) {
      case 'attack':
        // 🗡️ TypeScript knows we have weaponId, targetId, and damage
        const isCritical = Math.random() < 0.15;
        if (isCritical) {
          return {
            outcome: 'critical',
            multiplier: 2.5,
            damage: action.damage * 2.5,
            specialEffect: '💥 Critical Strike!'
          };
        }
        return { outcome: 'success', damage: action.damage };
      
      case 'defend':
        // 🛡️ TypeScript knows we have shieldValue and duration
        return {
          outcome: 'success',
          effect: `🛡️ Defense increased by ${action.shieldValue} for ${action.duration}s`
        };
      
      case 'heal':
        // 💚 TypeScript knows we have amount and optional targetId
        const target = action.targetId ? 'ally' : 'self';
        return {
          outcome: 'success',
          healing: action.amount,
          effect: `💚 Healed ${target} for ${action.amount} HP`
        };
      
      case 'cast_spell':
        // 🪄 TypeScript knows we have spellId, manaCost, and targets array
        if (action.targets.length === 0) {
          return { outcome: 'failure', reason: 'No targets selected' };
        }
        return {
          outcome: 'success',
          effect: `🪄 Cast spell ${action.spellId} on ${action.targets.length} targets`
        };
      
      case 'flee':
        // 🏃 TypeScript knows we have escapeChance and optional destination
        const escaped = Math.random() < action.escapeChance;
        return escaped 
          ? { outcome: 'success', effect: '🏃 Escaped successfully!' }
          : { outcome: 'failure', reason: 'Failed to escape', penaltyApplied: true };
    }
  }
}

🚀 Advanced Concepts

🧙‍♂️ Generic Discriminated Unions

When you’re ready to level up, try generic discriminated unions:

// 🎯 Generic Result type for any operation
type Result<T, E = string> = 
  | { success: true; data: T; timestamp: Date }
  | { success: false; error: E; retryable: boolean };

// 🪄 Using with different data types
type UserResult = Result<{ id: string; name: string; email: string }, 'USER_NOT_FOUND' | 'INVALID_CREDENTIALS'>;
type ApiResult<T> = Result<T, { code: number; message: string; details?: unknown }>;

// 🔧 Generic handler function
function handleResult<T, E>(result: Result<T, E>): string {
  if (result.success) {
    return `✅ Success! Data received at ${result.timestamp.toISOString()}`;
  } else {
    const retry = result.retryable ? ' (Retryable)' : ' (Fatal)';
    return `❌ Error: ${JSON.stringify(result.error)}${retry}`;
  }
}

🏗️ Nested Discriminated Unions

For the brave developers who need complex state management:

// 🚀 Nested discriminated unions for complex workflows
type PaymentMethod = 
  | { type: 'credit_card'; cardNumber: string; cvv: string; expiryDate: string }
  | { type: 'paypal'; email: string; accountId: string }
  | { type: 'bank_transfer'; routingNumber: string; accountNumber: string };

type PaymentState = 
  | { 
      status: 'selecting_method'; 
      availableMethods: PaymentMethod['type'][]; 
    }
  | { 
      status: 'processing'; 
      method: PaymentMethod; 
      transactionId: string;
      startedAt: Date;
    }
  | { 
      status: 'completed'; 
      method: PaymentMethod; 
      transactionId: string;
      completedAt: Date;
      receiptUrl: string;
    }
  | { 
      status: 'failed'; 
      method: PaymentMethod; 
      transactionId: string;
      error: string;
      retryCount: number;
    };

// 🎯 Exhaustive processing with nested pattern matching
function processPayment(state: PaymentState): string {
  switch (state.status) {
    case 'selecting_method':
      return `🛒 Choose from: ${state.availableMethods.join(', ')}`;
    
    case 'processing':
      // 🔍 We can pattern match on the nested union too!
      const methodDesc = (() => {
        switch (state.method.type) {
          case 'credit_card':
            return `💳 Card ending in ${state.method.cardNumber.slice(-4)}`;
          case 'paypal':
            return `💰 PayPal (${state.method.email})`;
          case 'bank_transfer':
            return `🏦 Bank transfer (${state.method.routingNumber})`;
        }
      })();
      return `⏳ Processing payment via ${methodDesc} (${state.transactionId})`;
    
    case 'completed':
      return `✅ Payment successful! Receipt: ${state.receiptUrl}`;
    
    case 'failed':
      const retryMsg = state.retryCount > 0 ? ` (Attempt ${state.retryCount + 1})` : '';
      return `❌ Payment failed: ${state.error}${retryMsg}`;
  }
}

🎭 Exhaustiveness Checking with never

Ensure compile-time completeness with the never type:

// 🛡️ Helper function to ensure exhaustive matching
function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
}

// 🎯 Function that MUST handle all cases
function processOrderStatus(order: Order): string {
  switch (order.status) {
    case 'pending':
      return 'Processing...';
    case 'confirmed':
      return 'Confirmed!';
    case 'shipped':
      return 'On the way!';
    case 'delivered':
      return 'Delivered!';
    case 'cancelled':
      return 'Cancelled';
    default:
      // 🚨 TypeScript error if we miss any cases!
      return assertNever(order); 
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Forgetting the Discriminant

// ❌ Wrong way - no common discriminant property!
type BadUnion = 
  | { name: string; age: number }
  | { title: string; duration: number };

// TypeScript can't tell these apart! 😰
function processBadUnion(item: BadUnion) {
  // 💥 How do we know which properties are available?
  // TypeScript only gives us properties common to ALL types
}

// ✅ Correct way - always include a discriminant!
type GoodUnion = 
  | { type: 'person'; name: string; age: number }
  | { type: 'media'; title: string; duration: number };

function processGoodUnion(item: GoodUnion) {
  switch (item.type) {
    case 'person':
      console.log(`${item.name} is ${item.age} years old`); // ✅ Perfect!
      break;
    case 'media':
      console.log(`${item.title} lasts ${item.duration} minutes`); // ✅ Perfect!
      break;
  }
}

🤯 Pitfall 2: Using Enums as Discriminants

// ❌ Dangerous - enums can be tricky with discriminated unions
enum Status {
  LOADING = 'loading',
  SUCCESS = 'success',
  ERROR = 'error'
}

type ProblematicResponse = 
  | { status: Status.LOADING; progress: number }
  | { status: Status.SUCCESS; data: string }
  | { status: Status.ERROR; error: string };

// ⚠️ Works, but string literals are cleaner and more explicit

// ✅ Better - use string literal types!
type CleanResponse = 
  | { status: 'loading'; progress: number }
  | { status: 'success'; data: string }
  | { status: 'error'; error: string };

// 🎯 Much cleaner to work with!
function handleResponse(response: CleanResponse) {
  switch (response.status) {
    case 'loading':
      return `Loading... ${response.progress}%`;
    case 'success':
      return `Data: ${response.data}`;
    case 'error':
      return `Error: ${response.error}`;
  }
}

🔥 Pitfall 3: Missing Exhaustiveness Checking

// ❌ Dangerous - might miss cases when adding new variants!
type Animal = 
  | { species: 'dog'; breed: string; good: true }
  | { species: 'cat'; indoor: boolean; sass: number }
  | { species: 'bird'; canFly: boolean; volume: number };

function describeAnimal(animal: Animal): string {
  switch (animal.species) {
    case 'dog':
      return `🐕 Good doggo! Breed: ${animal.breed}`;
    case 'cat':
      return `🐱 Cat with sass level: ${animal.sass}`;
    // 😱 Forgot birds! No compile error!
  }
  // 💥 Runtime error if we get a bird!
}

// ✅ Safe - use exhaustiveness checking!
function describeSafeAnimal(animal: Animal): string {
  switch (animal.species) {
    case 'dog':
      return `🐕 Good doggo! Breed: ${animal.breed}`;
    case 'cat':
      return `🐱 Cat with sass level: ${animal.sass}`;
    case 'bird':
      return `🐦 Bird volume: ${animal.volume}/10`;
    default:
      // 🛡️ This ensures we handle all cases!
      const exhaustiveCheck: never = animal;
      return exhaustiveCheck;
  }
}

🛠️ Best Practices

1. 🎯 Always Use a Discriminant: Include a common property with literal types
2. 📝 Make Discriminants Meaningful: Use descriptive names like status, type, or kind
3. 🛡️ Enable Exhaustiveness Checking: Use never type to catch missing cases
4. 🎨 Prefer String Literals: Use 'loading' instead of enums when possible
5. ✨ Keep States Separate: Don’t share properties between different states unless they’re truly common
6. 🔒 Make Impossible States Impossible: Design your unions so invalid combinations can’t exist
7. 🧪 Add Helpers: Create utility functions for common operations like state transitions

🧪 Hands-On Exercise

🎯 Challenge: Build a Media Player State Machine

Create a type-safe media player using discriminated unions:

📋 Requirements:

• 🎵 Player states: idle, loading, playing, paused, error
• 📊 Each state should have appropriate data (current song, progress, error message, etc.)
• 🎮 State transition validation
• 🔄 Playlist management
• 🎨 Progress tracking and metadata!

🚀 Bonus Points:

• Add volume control states
• Implement shuffle/repeat modes
• Create a queue system with different priorities

💡 Solution

// 🎯 Media player state machine with discriminated unions!
type Song = {
  id: string;
  title: string;
  artist: string;
  duration: number;
  url: string;
};

type PlayerState = 
  | { status: 'idle'; lastPlayed?: Song }
  | { status: 'loading'; song: Song; progress: number }
  | { 
      status: 'playing'; 
      song: Song; 
      currentTime: number; 
      volume: number;
      playlistPosition: number;
    }
  | { 
      status: 'paused'; 
      song: Song; 
      pausedAt: number; 
      volume: number;
      playlistPosition: number;
    }
  | { 
      status: 'error'; 
      song?: Song; 
      error: string; 
      retryCount: number;
    };

class MediaPlayer {
  private state: PlayerState = { status: 'idle' };
  private playlist: Song[] = [];
  
  // 🎵 Get current state description
  getStateDescription(): string {
    switch (this.state.status) {
      case 'idle':
        const last = this.state.lastPlayed;
        return last ? `💤 Idle (last: ${last.title})` : '💤 Ready to play';
      
      case 'loading':
        return `⏳ Loading ${this.state.song.title} (${this.state.progress}%)`;
      
      case 'playing':
        const progress = Math.round((this.state.currentTime / this.state.song.duration) * 100);
        return `🎵 Playing: ${this.state.song.title} by ${this.state.song.artist} (${progress}%)`;
      
      case 'paused':
        const pauseProgress = Math.round((this.state.pausedAt / this.state.song.duration) * 100);
        return `⏸️ Paused: ${this.state.song.title} at ${pauseProgress}%`;
      
      case 'error':
        const songInfo = this.state.song ? ` (${this.state.song.title})` : '';
        return `❌ Error${songInfo}: ${this.state.error}`;
    }
  }
  
  // 🔄 State transitions with validation
  canTransition(from: PlayerState['status'], to: PlayerState['status']): boolean {
    const transitions: Record<PlayerState['status'], PlayerState['status'][]> = {
      idle: ['loading'],
      loading: ['playing', 'error', 'idle'],
      playing: ['paused', 'loading', 'error', 'idle'],
      paused: ['playing', 'loading', 'error', 'idle'],
      error: ['loading', 'idle']
    };
    
    return transitions[from].includes(to);
  }
  
  // ▶️ Play a song
  play(song: Song): void {
    if (!this.canTransition(this.state.status, 'loading')) {
      console.log(`❌ Cannot start loading from ${this.state.status} state`);
      return;
    }
    
    // Start loading
    this.state = { status: 'loading', song, progress: 0 };
    
    // Simulate loading
    setTimeout(() => {
      this.state = {
        status: 'playing',
        song,
        currentTime: 0,
        volume: 0.8,
        playlistPosition: this.playlist.findIndex(s => s.id === song.id)
      };
      console.log(`🎵 Now playing: ${song.title}`);
    }, 1000);
  }
  
  // ⏸️ Pause playback
  pause(): void {
    if (this.state.status === 'playing') {
      this.state = {
        status: 'paused',
        song: this.state.song,
        pausedAt: this.state.currentTime,
        volume: this.state.volume,
        playlistPosition: this.state.playlistPosition
      };
      console.log(`⏸️ Paused at ${Math.round(this.state.pausedAt)}s`);
    }
  }
  
  // ▶️ Resume playback
  resume(): void {
    if (this.state.status === 'paused') {
      this.state = {
        status: 'playing',
        song: this.state.song,
        currentTime: this.state.pausedAt,
        volume: this.state.volume,
        playlistPosition: this.state.playlistPosition
      };
      console.log(`▶️ Resumed ${this.state.song.title}`);
    }
  }
}

// 🎮 Test the media player!
const player = new MediaPlayer();
const song: Song = {
  id: '1',
  title: 'TypeScript Symphony',
  artist: 'The Compiler Band',
  duration: 240,
  url: 'music/typescript-symphony.mp3'
};

console.log(player.getStateDescription()); // 💤 Ready to play
player.play(song);
console.log(player.getStateDescription()); // ⏳ Loading...

🎓 Key Takeaways

You’ve mastered one of TypeScript’s most powerful features! Here’s what you can now do:

• ✅ Create bulletproof discriminated unions with perfect type safety 💪
• ✅ Implement exhaustive pattern matching that catches all edge cases 🛡️
• ✅ Build type-safe state machines for complex workflows 🎯
• ✅ Eliminate impossible states from your applications 🐛
• ✅ Design APIs that are impossible to misuse 🚀

Remember: Discriminated unions turn runtime errors into compile-time guarantees. They’re your secret weapon for building rock-solid applications! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered discriminated unions and pattern matching!

Here’s what to do next:

1. 💻 Practice with the media player exercise above
2. 🏗️ Refactor existing code to use discriminated unions instead of optional properties
3. 📚 Move on to our next tutorial: Exhaustiveness Checking: Complete Pattern Coverage
4. 🌟 Share your type-safe creations with the community!

Remember: Every impossible state you eliminate makes your application more reliable. Keep building bulletproof software! 🚀

Happy pattern matching! 🎉🎯✨