🛡 ️ Exhaustiveness Checking: Complete Pattern Coverage

🎯 Introduction

Welcome to the world of exhaustive pattern matching! 🎉 In this guide, we’ll explore how TypeScript’s type system can guarantee that your code handles every possible case, eliminating an entire class of runtime errors.

You’ll discover how exhaustiveness checking transforms fragile switch statements into bulletproof pattern matching systems. Whether you’re building state machines 🤖, processing API responses 🌐, or handling complex business logic 💼, exhaustive checking ensures you never miss a case.

By the end of this tutorial, you’ll be writing code that’s impossible to break when new variants are added! Let’s dive in! 🏊‍♂️

📚 Understanding Exhaustiveness Checking

🤔 What is Exhaustiveness Checking?

Exhaustiveness checking is like having a super-powered safety inspector 🕵️‍♂️ that ensures your code handles every possible scenario. It’s TypeScript’s way of saying “Hey, you forgot to handle this case!” before your code ever runs.

In TypeScript terms, exhaustiveness checking uses the never type to create compile-time errors when you haven’t handled all possible values in a union type. This means you can:

• ✨ Catch missing cases at compile time - no more runtime surprises
• 🚀 Refactor with confidence - add new cases and get immediate feedback
• 🛡️ Eliminate impossible states - if it compiles, it handles everything

💡 Why Use Exhaustiveness Checking?

Here’s why developers love exhaustive pattern matching:

1. Compile-Time Safety 🔒: Catch missing cases before deployment
2. Refactoring Protection 💻: Add new variants and get guided updates
3. Self-Documenting Code 📖: The type system enforces complete coverage
4. Zero Runtime Overhead 🚀: All checking happens at compile time

Real-world example: Imagine adding a new order status to your e-commerce system 🛒. With exhaustive checking, TypeScript will tell you exactly which functions need updating!

🔧 Basic Syntax and Usage

📝 The Never Type Helper

Let’s start with the foundation of exhaustiveness checking:

// 🛡️ Exhaustiveness helper function
function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
}

// 🚦 Traffic light states
type TrafficLight = 'red' | 'yellow' | 'green';

function getAction(light: TrafficLight): string {
  switch (light) {
    case 'red':
      return 'Stop! 🛑';
    case 'yellow':
      return 'Caution! ⚠️';
    case 'green':
      return 'Go! ✅';
    default:
      // 🎯 This line ensures exhaustiveness!
      return assertNever(light);
  }
}

💡 Explanation: The assertNever function expects a value of type never. If all cases are handled, TypeScript infers never for the default case. If we miss a case, TypeScript throws a compile error!

🎯 Exhaustive Switch Patterns

Here are the essential patterns for exhaustive checking:

// 🎨 Pattern 1: Simple union exhaustiveness
type Theme = 'light' | 'dark' | 'auto';

function applyTheme(theme: Theme): void {
  switch (theme) {
    case 'light':
      document.body.className = 'theme-light 🌞';
      break;
    case 'dark':
      document.body.className = 'theme-dark 🌙';
      break;
    case 'auto':
      document.body.className = 'theme-auto 🔄';
      break;
    default:
      assertNever(theme); // 🛡️ Exhaustiveness guaranteed!
  }
}

// 🏗️ Pattern 2: Discriminated union exhaustiveness
type Shape = 
  | { type: 'circle'; radius: number }
  | { type: 'rectangle'; width: number; height: number }
  | { type: 'triangle'; base: number; height: number };

function calculateArea(shape: Shape): number {
  switch (shape.type) {
    case 'circle':
      return Math.PI * shape.radius ** 2; // 🔵
    case 'rectangle':
      return shape.width * shape.height; // 🟦
    case 'triangle':
      return 0.5 * shape.base * shape.height; // 🔺
    default:
      return assertNever(shape); // 🎯 All shapes covered!
  }
}

// 🔄 Pattern 3: Functional exhaustiveness
const processStatus = (status: 'pending' | 'approved' | 'rejected'): string => {
  switch (status) {
    case 'pending': return '⏳ Processing...';
    case 'approved': return '✅ Approved!';
    case 'rejected': return '❌ Rejected';
    default: return assertNever(status);
  }
};

💡 Practical Examples

🎮 Example 1: Game State Machine

Let’s build a robust game state system:

// 🎮 Comprehensive game states
type GameState = 
  | { state: 'menu'; selectedOption: string }
  | { state: 'loading'; progress: number; asset: string }
  | { state: 'playing'; level: number; score: number; lives: number }
  | { state: 'paused'; level: number; score: number; lives: number; pausedAt: Date }
  | { state: 'game_over'; finalScore: number; reason: 'died' | 'completed' | 'quit' }
  | { state: 'leaderboard'; scores: Array<{ name: string; score: number }> };

class GameEngine {
  private currentState: GameState = { state: 'menu', selectedOption: 'start' };
  
  // 🎯 Exhaustive state processing
  processCurrentState(): string {
    switch (this.currentState.state) {
      case 'menu':
        return `🏠 Main Menu - Selected: ${this.currentState.selectedOption}`;
      
      case 'loading':
        return `⏳ Loading ${this.currentState.asset}... ${this.currentState.progress}%`;
      
      case 'playing':
        return `🎮 Playing Level ${this.currentState.level} | Score: ${this.currentState.score} | Lives: ${this.currentState.lives}`;
      
      case 'paused':
        const pauseDuration = Date.now() - this.currentState.pausedAt.getTime();
        return `⏸️ Paused for ${Math.round(pauseDuration / 1000)}s | Level: ${this.currentState.level}`;
      
      case 'game_over':
        const emoji = this.currentState.reason === 'completed' ? '🎉' : '💀';
        return `${emoji} Game Over! Final Score: ${this.currentState.finalScore} (${this.currentState.reason})`;
      
      case 'leaderboard':
        const topScore = this.currentState.scores[0]?.score || 0;
        return `🏆 Leaderboard - Top Score: ${topScore}`;
      
      default:
        // 🛡️ TypeScript ensures we handle all states!
        return assertNever(this.currentState);
    }
  }
  
  // 🔄 Valid state transitions with exhaustive checking
  canTransitionTo(newState: GameState['state']): boolean {
    const currentStateType = this.currentState.state;
    
    switch (currentStateType) {
      case 'menu':
        return ['loading', 'leaderboard'].includes(newState);
      case 'loading':
        return ['playing', 'menu'].includes(newState);
      case 'playing':
        return ['paused', 'game_over', 'menu'].includes(newState);
      case 'paused':
        return ['playing', 'game_over', 'menu'].includes(newState);
      case 'game_over':
        return ['menu', 'leaderboard'].includes(newState);
      case 'leaderboard':
        return ['menu'].includes(newState);
      default:
        // 🎯 Exhaustive checking prevents forgotten states!
        assertNever(currentStateType);
        return false;
    }
  }
}

🎯 Try it yourself: Add a ‘settings’ state and watch TypeScript guide you through all the places you need to update!

🌐 Example 2: HTTP Response Handler

Let’s create a bulletproof API response processor:

// 📡 HTTP response states with rich metadata
type HttpResponse<T> = 
  | { 
      status: 'loading'; 
      startTime: Date; 
      retryCount: number;
      endpoint: string;
    }
  | { 
      status: 'success'; 
      data: T; 
      responseTime: number;
      statusCode: 200 | 201 | 204;
      headers: Record<string, string>;
    }
  | { 
      status: 'client_error'; 
      statusCode: 400 | 401 | 403 | 404 | 422;
      error: string;
      details?: unknown;
    }
  | { 
      status: 'server_error'; 
      statusCode: 500 | 502 | 503 | 504;
      error: string;
      retryAfter?: number;
    }
  | { 
      status: 'network_error'; 
      error: string;
      offline: boolean;
      lastAttempt: Date;
    }
  | { 
      status: 'timeout'; 
      duration: number;
      endpoint: string;
    };

class ApiClient {
  // 🎯 Exhaustive response processing
  processResponse<T>(response: HttpResponse<T>): {
    message: string;
    shouldRetry: boolean;
    data?: T;
  } {
    switch (response.status) {
      case 'loading':
        const loadingTime = Date.now() - response.startTime.getTime();
        return {
          message: `⏳ Loading ${response.endpoint}... ${loadingTime}ms (attempt ${response.retryCount + 1})`,
          shouldRetry: false
        };
      
      case 'success':
        return {
          message: `✅ Success! ${response.statusCode} in ${response.responseTime}ms`,
          shouldRetry: false,
          data: response.data
        };
      
      case 'client_error':
        // 🚫 Client errors usually shouldn't retry
        const clientRetry = response.statusCode === 429; // Rate limited
        return {
          message: `❌ Client Error ${response.statusCode}: ${response.error}`,
          shouldRetry: clientRetry
        };
      
      case 'server_error':
        // 🔄 Server errors might be temporary
        return {
          message: `🔥 Server Error ${response.statusCode}: ${response.error}`,
          shouldRetry: true
        };
      
      case 'network_error':
        // 🌐 Network errors depend on connectivity
        const networkMsg = response.offline ? 'offline' : 'network issue';
        return {
          message: `🌐 Network Error: ${response.error} (${networkMsg})`,
          shouldRetry: !response.offline
        };
      
      case 'timeout':
        // ⏰ Timeouts can often be retried
        return {
          message: `⏰ Timeout after ${response.duration}ms for ${response.endpoint}`,
          shouldRetry: true
        };
      
      default:
        // 🛡️ Impossible to miss a case!
        return assertNever(response);
    }
  }
  
  // 📊 Response analytics with exhaustive metrics
  getAnalytics(responses: HttpResponse<unknown>[]): Record<string, number> {
    const stats: Record<string, number> = {};
    
    for (const response of responses) {
      switch (response.status) {
        case 'loading':
          stats.loading = (stats.loading || 0) + 1;
          break;
        case 'success':
          stats.success = (stats.success || 0) + 1;
          stats[`status_${response.statusCode}`] = (stats[`status_${response.statusCode}`] || 0) + 1;
          break;
        case 'client_error':
          stats.client_error = (stats.client_error || 0) + 1;
          stats[`error_${response.statusCode}`] = (stats[`error_${response.statusCode}`] || 0) + 1;
          break;
        case 'server_error':
          stats.server_error = (stats.server_error || 0) + 1;
          stats[`error_${response.statusCode}`] = (stats[`error_${response.statusCode}`] || 0) + 1;
          break;
        case 'network_error':
          stats.network_error = (stats.network_error || 0) + 1;
          if (response.offline) stats.offline = (stats.offline || 0) + 1;
          break;
        case 'timeout':
          stats.timeout = (stats.timeout || 0) + 1;
          break;
        default:
          // 📈 All response types accounted for!
          assertNever(response);
      }
    }
    
    return stats;
  }
}

🚀 Advanced Concepts

🧙‍♂️ Conditional Exhaustiveness

For complex scenarios where exhaustiveness depends on conditions:

// 🎯 Permission system with conditional logic
type UserRole = 'guest' | 'user' | 'moderator' | 'admin';
type Permission = 'read' | 'write' | 'delete' | 'moderate' | 'admin_panel';

function hasPermission(role: UserRole, permission: Permission): boolean {
  // 🔐 Guest permissions
  if (role === 'guest') {
    switch (permission) {
      case 'read': return true;
      case 'write':
      case 'delete':
      case 'moderate':
      case 'admin_panel':
        return false;
      default:
        return assertNever(permission);
    }
  }
  
  // 👤 User permissions
  if (role === 'user') {
    switch (permission) {
      case 'read':
      case 'write':
        return true;
      case 'delete':
      case 'moderate':
      case 'admin_panel':
        return false;
      default:
        return assertNever(permission);
    }
  }
  
  // 🛡️ Moderator permissions
  if (role === 'moderator') {
    switch (permission) {
      case 'read':
      case 'write':
      case 'delete':
      case 'moderate':
        return true;
      case 'admin_panel':
        return false;
      default:
        return assertNever(permission);
    }
  }
  
  // 👑 Admin permissions
  if (role === 'admin') {
    switch (permission) {
      case 'read':
      case 'write':
      case 'delete':
      case 'moderate':
      case 'admin_panel':
        return true;
      default:
        return assertNever(permission);
    }
  }
  
  // 🎯 Ensures all roles are handled!
  return assertNever(role);
}

🏗️ Mapped Type Exhaustiveness

Using mapped types for systematic exhaustiveness:

// 🗺️ Mapped type for exhaustive handling
type NotificationSettings = {
  email: boolean;
  push: boolean;
  sms: boolean;
  browser: boolean;
};

type NotificationChannel = keyof NotificationSettings;

// 🎯 Exhaustive channel processor using mapped types
type ChannelHandlers = {
  [K in NotificationChannel]: (enabled: boolean) => string;
};

const notificationHandlers: ChannelHandlers = {
  email: (enabled) => enabled ? '📧 Email notifications ON' : '📧 Email notifications OFF',
  push: (enabled) => enabled ? '📱 Push notifications ON' : '📱 Push notifications OFF',
  sms: (enabled) => enabled ? '💬 SMS notifications ON' : '💬 SMS notifications OFF',
  browser: (enabled) => enabled ? '🌐 Browser notifications ON' : '🌐 Browser notifications OFF',
};

// 🛡️ Process all notification settings exhaustively
function processNotificationSettings(settings: NotificationSettings): string[] {
  const results: string[] = [];
  
  // 🔄 This loop is guaranteed to handle all channels
  for (const channel of Object.keys(settings) as NotificationChannel[]) {
    const handler = notificationHandlers[channel];
    results.push(handler(settings[channel]));
  }
  
  return results;
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Forgetting the Default Case

// ❌ Wrong way - no exhaustiveness checking!
type Size = 'small' | 'medium' | 'large';

function getPrice(size: Size): number {
  switch (size) {
    case 'small': return 10;
    case 'medium': return 15;
    // 💥 Forgot 'large'! No compile error, but runtime crash!
  }
  // 😰 TypeScript thinks this might return undefined
}

// ✅ Correct way - always include exhaustiveness check!
function getSafePrice(size: Size): number {
  switch (size) {
    case 'small': return 10;
    case 'medium': return 15;
    case 'large': return 20;
    default:
      return assertNever(size); // 🛡️ Compile error if cases missing!
  }
}

🤯 Pitfall 2: Partial Exhaustiveness with If-Else

// ❌ Dangerous - if-else chains can miss cases!
function processStatusUnsafe(status: 'pending' | 'success' | 'error'): string {
  if (status === 'pending') {
    return '⏳ Processing...';
  }
  if (status === 'success') {
    return '✅ Done!';
  }
  // 💥 Forgot 'error' case! No compile error!
  return '❓ Unknown'; // This will run for 'error'
}

// ✅ Safe - use switch with exhaustiveness checking!
function processStatusSafe(status: 'pending' | 'success' | 'error'): string {
  switch (status) {
    case 'pending': return '⏳ Processing...';
    case 'success': return '✅ Done!';
    case 'error': return '❌ Failed!';
    default: return assertNever(status); // 🎯 All cases required!
  }
}

🔥 Pitfall 3: Mutating Union Types

// ❌ Problems with mutable union handling
type MutableResponse = {
  status: 'loading' | 'success' | 'error';
  data?: unknown;
  error?: string;
};

function processMutableBad(response: MutableResponse): string {
  // 😰 Can't use exhaustive checking on object properties
  // because they could change at runtime!
  if (response.status === 'success') {
    return `Data: ${response.data}`;
  }
  // 💥 Status could have changed between checks!
  return `Status: ${response.status}`;
}

// ✅ Better - use discriminated unions with exhaustiveness
type ImmutableResponse = 
  | { status: 'loading' }
  | { status: 'success'; data: unknown }
  | { status: 'error'; error: string };

function processImmutableGood(response: ImmutableResponse): string {
  switch (response.status) {
    case 'loading': return '⏳ Loading...';
    case 'success': return `✅ Data: ${response.data}`;
    case 'error': return `❌ Error: ${response.error}`;
    default: return assertNever(response); // 🛡️ Safe and exhaustive!
  }
}

🛠️ Best Practices

1. 🎯 Always Use assertNever: Include it in every default case for exhaustiveness
2. 📝 Prefer Switch Over If-Else: Switch statements work better with exhaustiveness checking
3. 🛡️ Use Discriminated Unions: They provide the best exhaustiveness guarantees
4. 🎨 Create Helper Functions: Build reusable exhaustiveness utilities
5. ✨ Test Exhaustiveness: Add unit tests that verify all cases are handled
6. 🔒 Make Types Immutable: Use readonly types to prevent runtime mutations
7. 🚫 Avoid Optional Properties: Use discriminated unions instead of optional fields

🧪 Hands-On Exercise

🎯 Challenge: Build a File Processing System

Create a file processor with exhaustive error handling:

📋 Requirements:

• 📁 File types: text, image, video, audio, document
• 🔄 Processing states: queued, processing, completed, failed
• ❌ Error types: invalid_format, too_large, corrupted, network_error
• 📊 Progress tracking and detailed status messages
• 🎨 Comprehensive error recovery strategies!

🚀 Bonus Points:

• Add file validation states
• Implement retry logic with exponential backoff
• Create a file conversion pipeline

💡 Solution

// 📁 File processing system with exhaustive checking!
type FileType = 'text' | 'image' | 'video' | 'audio' | 'document';
type ErrorType = 'invalid_format' | 'too_large' | 'corrupted' | 'network_error';

type FileJob = 
  | { 
      state: 'queued'; 
      fileId: string; 
      fileName: string; 
      fileType: FileType; 
      queuedAt: Date;
    }
  | { 
      state: 'processing'; 
      fileId: string; 
      fileName: string; 
      fileType: FileType; 
      progress: number;
      startedAt: Date;
    }
  | { 
      state: 'completed'; 
      fileId: string; 
      fileName: string; 
      fileType: FileType; 
      outputPath: string;
      completedAt: Date;
      processingTime: number;
    }
  | { 
      state: 'failed'; 
      fileId: string; 
      fileName: string; 
      fileType: FileType; 
      error: ErrorType;
      errorMessage: string;
      retryCount: number;
      failedAt: Date;
    };

class FileProcessor {
  private jobs: Map<string, FileJob> = new Map();
  
  // 🎯 Exhaustive job status processing
  getJobStatus(job: FileJob): string {
    switch (job.state) {
      case 'queued':
        const waitTime = Date.now() - job.queuedAt.getTime();
        return `📋 Queued: ${job.fileName} (${this.getFileEmoji(job.fileType)} ${job.fileType}) - waiting ${Math.round(waitTime / 1000)}s`;
      
      case 'processing':
        const processingTime = Date.now() - job.startedAt.getTime();
        return `⚙️ Processing: ${job.fileName} (${job.progress}%) - ${Math.round(processingTime / 1000)}s elapsed`;
      
      case 'completed':
        return `✅ Completed: ${job.fileName} in ${job.processingTime}ms -> ${job.outputPath}`;
      
      case 'failed':
        const retryText = job.retryCount > 0 ? ` (retry ${job.retryCount})` : '';
        return `❌ Failed: ${job.fileName} - ${this.getErrorDescription(job.error)}${retryText}`;
      
      default:
        // 🛡️ Exhaustive checking ensures all states handled!
        return assertNever(job);
    }
  }
  
  // 🎨 Exhaustive file type emoji mapping
  private getFileEmoji(fileType: FileType): string {
    switch (fileType) {
      case 'text': return '📝';
      case 'image': return '🖼️';
      case 'video': return '🎬';
      case 'audio': return '🎵';
      case 'document': return '📄';
      default:
        return assertNever(fileType); // 🎯 All file types covered!
    }
  }
  
  // ⚠️ Exhaustive error description mapping
  private getErrorDescription(error: ErrorType): string {
    switch (error) {
      case 'invalid_format':
        return 'Invalid file format - format not supported';
      case 'too_large':
        return 'File too large - exceeds size limit';
      case 'corrupted':
        return 'File corrupted - unable to read data';
      case 'network_error':
        return 'Network error - connection failed';
      default:
        return assertNever(error); // 🛡️ All errors described!
    }
  }
  
  // 🔄 Exhaustive retry strategy
  shouldRetry(job: FileJob): boolean {
    if (job.state !== 'failed') return false;
    
    switch (job.error) {
      case 'network_error':
        return job.retryCount < 3; // 🌐 Network issues can be retried
      case 'too_large':
        return false; // 📏 Size issues can't be fixed by retrying
      case 'invalid_format':
        return false; // 🚫 Format issues are permanent
      case 'corrupted':
        return job.retryCount < 1; // 🔧 Maybe a one-time read error
      default:
        assertNever(job.error); // 🎯 All error types considered!
        return false;
    }
  }
  
  // 📊 Exhaustive analytics
  getAnalytics(jobs: FileJob[]): Record<string, number> {
    const stats: Record<string, number> = {};
    
    for (const job of jobs) {
      // State statistics
      switch (job.state) {
        case 'queued':
          stats.queued = (stats.queued || 0) + 1;
          break;
        case 'processing':
          stats.processing = (stats.processing || 0) + 1;
          break;
        case 'completed':
          stats.completed = (stats.completed || 0) + 1;
          break;
        case 'failed':
          stats.failed = (stats.failed || 0) + 1;
          // Error type breakdown
          switch (job.error) {
            case 'invalid_format':
              stats.invalid_format = (stats.invalid_format || 0) + 1;
              break;
            case 'too_large':
              stats.too_large = (stats.too_large || 0) + 1;
              break;
            case 'corrupted':
              stats.corrupted = (stats.corrupted || 0) + 1;
              break;
            case 'network_error':
              stats.network_error = (stats.network_error || 0) + 1;
              break;
            default:
              assertNever(job.error); // 🛡️ All error types counted!
          }
          break;
        default:
          assertNever(job); // 🎯 All job states analyzed!
      }
      
      // File type statistics
      switch (job.fileType) {
        case 'text':
          stats.text_files = (stats.text_files || 0) + 1;
          break;
        case 'image':
          stats.image_files = (stats.image_files || 0) + 1;
          break;
        case 'video':
          stats.video_files = (stats.video_files || 0) + 1;
          break;
        case 'audio':
          stats.audio_files = (stats.audio_files || 0) + 1;
          break;
        case 'document':
          stats.document_files = (stats.document_files || 0) + 1;
          break;
        default:
          assertNever(job.fileType); // 📊 All file types tracked!
      }
    }
    
    return stats;
  }
}

// 🧪 Test the exhaustive file processor!
const processor = new FileProcessor();
const job: FileJob = {
  state: 'processing',
  fileId: '123',
  fileName: 'vacation-video.mp4',
  fileType: 'video',
  progress: 75,
  startedAt: new Date(Date.now() - 30000)
};

console.log(processor.getJobStatus(job));
// ⚙️ Processing: vacation-video.mp4 (75%) - 30s elapsed

🎓 Key Takeaways

You’ve mastered TypeScript’s most powerful safety feature! Here’s what you can now do:

• ✅ Create bulletproof pattern matching with compile-time guarantees 💪
• ✅ Never miss a case again - TypeScript will tell you immediately 🛡️
• ✅ Refactor with complete confidence - add cases and get guided updates 🎯
• ✅ Build maintainable switch statements that scale with your types 🔧
• ✅ Eliminate entire categories of runtime errors before they happen 🚀

Remember: Exhaustiveness checking turns TypeScript into your personal code reviewer that never gets tired! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered exhaustive pattern matching!

Here’s what to do next:

1. 💻 Practice with the file processor exercise above
2. 🏗️ Refactor existing switch statements to use exhaustiveness checking
3. 📚 Move on to our next tutorial: ES Modules in TypeScript: Import and Export
4. 🌟 Share your bulletproof code patterns with the community!

Remember: Every missing case you catch at compile time is a bug prevented in production. Keep building unbreakable software! 🚀

Happy exhaustive coding! 🎉🛡️✨