TypeScript Discriminated Unions: Safe API Response Handling

TypeScript Discriminated Unions: Safely Handling Dynamic API Responses

In the real world, API responses aren't always uniform. Sometimes, a single endpoint might return data in wildly different shapes depending on a status field, or an error might contain different details than a successful payload. This heterogeneity can quickly lead to runtime errors if not handled carefully. TypeScript's discriminated unions, combined with type guards, provide an elegant and robust solution to this common challenge, ensuring type safety even when dealing with dynamic data.

This article dives into how to define and use discriminated unions to confidently process API responses that vary in structure. We'll move beyond high-level concepts and explore practical code examples, demonstrating how to leverage TypeScript's type narrowing capabilities for more reliable applications.

Understanding Discriminated Unions

At its core, a discriminated union is a type that consists of several other types (a union), where each member of the union shares a common, literal property (the 'discriminant'). This property acts as a tag, allowing TypeScript to narrow down the specific type within the union at runtime based on its value.

Consider an API that returns either a success payload with user data or an error payload with a message. Both responses might share a status field, but its value ('success' or 'error') dictates the presence of other fields.

Defining Our API Response Types

Let's start by defining the possible shapes of our API responses using interfaces and then combining them into a discriminated union type. We'll use a status property as our discriminant.

interface UserData {
  id: string;
  name: string;
  email: string;
}

interface SuccessApiResponse {
  status: 'success';
  data: UserData;
}

interface ErrorApiResponse {
  status: 'error';
  message: string;
  errorCode?: number; // Optional error code
}

// Our discriminated union type
type ApiResponse = SuccessApiResponse | ErrorApiResponse;

Here, UserData defines the structure of a successful payload. SuccessApiResponse and ErrorApiResponse each declare a status property with a literal string type ('success' or 'error'). This literal type is crucial for the discriminant. Finally, ApiResponse is a union of these two interfaces. Notice how SuccessApiResponse has a data property, while ErrorApiResponse has message and an optional errorCode.

Implementing Type Guards for Narrowing

Once we have our discriminated union, the next step is to write code that can intelligently determine which specific type it's currently dealing with. This is where type guards come in. A type guard is a runtime check that guarantees a type within a certain scope. For discriminated unions, checking the discriminant property acts as a powerful type guard.

Let's create a function that processes an ApiResponse:

function processApiResponse(response: ApiResponse): void {
  if (response.status === 'success') {
    // TypeScript now knows 'response' is a SuccessApiResponse
    console.log(`User ID: ${response.data.id}, Name: ${response.data.name}`);
    // console.log(response.message); // This would cause a compile-time error
  } else {
    // TypeScript now knows 'response' is an ErrorApiResponse
    console.error(`Error (${response.errorCode || 'unknown'}): ${response.message}`);
    // console.log(response.data); // This would also cause a compile-time error
  }
}

// Example usage:
const successRes: ApiResponse = {
  status: 'success',
  data: { id: '123', name: 'Alice', email: '[e-mail]' }
};

const errorRes: ApiResponse = {
  status: 'error',
  message: 'User not found', 
  errorCode: 404
};

processApiResponse(successRes);
processApiResponse(errorRes);

In processApiResponse, the if (response.status === 'success') statement acts as a type guard. Inside the if block, TypeScript automatically narrows the type of response to SuccessApiResponse. This means you can safely access response.data without any type assertions. Conversely, in the else block, TypeScript narrows response to ErrorApiResponse, allowing access to response.message and response.errorCode.

Processing Collections of Mixed Responses

Discriminated unions truly shine when you need to process an array or collection of items that could be any of the union members. Imagine a scenario where you've made multiple API calls, and you want to log both successful results and errors.

const apiResponses: ApiResponse[] = [
  { status: 'success', data: { id: 'u1', name: 'Bob', email: '[e-mail]' } },
  { status: 'error', message: 'Unauthorized', errorCode: 401 },
  { status: 'success', data: { id: 'u2', name: 'Charlie', email: '[e-mail]' } }
];

apiResponses.forEach(response => {
  switch (response.status) {
    case 'success':
      console.log(`Fetched user: ${response.data.name} (ID: ${response.data.id})`);
      break;
    case 'error':
      console.error(`API Error: ${response.message} (Code: ${response.errorCode || 'N/A'})`);
      break;
    default:
      // This branch should theoretically be unreachable if all cases are handled.
      // 'never' type helps ensure exhaustiveness.
      const _exhaustiveCheck: never = response;
      return _exhaustiveCheck;
  }
});

Here, we iterate through an array of ApiResponse objects. The switch (response.status) statement provides clear branching logic. For each case, TypeScript intelligently narrows the response type, allowing direct and safe access to the specific properties of SuccessApiResponse or ErrorApiResponse. The default case with const _exhaustiveCheck: never = response; is a powerful TypeScript pattern. If you were to add a new variant to ApiResponse (e.g., LoadingApiResponse) but forgot to add a corresponding case in the switch, TypeScript would issue a compile-time error, reminding you to handle all possibilities. This ensures exhaustiveness and prevents unexpected runtime behavior.

Common Mistakes and Gotchas

While powerful, discriminated unions have a few pitfalls to be aware of:

• Missing or Optional Discriminant Property: The common property must be present in all members of the union and have a literal type (e.g., 'success', not string). If it's optional (status?: 'success') or a broad string type, TypeScript cannot reliably use it for narrowing.
• Incorrect Type Guards: Relying on typeof for object differentiation often doesn't work as expected, as typeof someObject will always return 'object'. Always use the literal discriminant property for narrowing discriminated unions.
• Non-Exhaustive Checks: Forgetting to handle all possible cases in if/else if/else chains or switch statements can lead to runtime errors if new union members are introduced. The never type check in a default case is a strong guard against this.
• Accidental Overlap: Ensure your discriminant values are truly unique across the union members. If SuccessApiResponse and ErrorApiResponse could both have status: 'pending', TypeScript wouldn't be able to narrow them effectively based on that property.

Key Takeaways

Discriminated unions are a cornerstone of advanced TypeScript usage, providing a robust mechanism to handle data with varying structures. By explicitly defining the possible shapes and using a common literal property as a discriminant, you enable TypeScript's static analysis to perform precise type narrowing. This leads to code that is:

• Safer: Runtime errors due to incorrect property access are drastically reduced.
• Clearer: The code explicitly documents the possible data shapes and how they are handled.
• More Maintainable: Refactoring is easier, as TypeScript will flag unhandled cases when union members change.

Conclusion

Mastering discriminated unions and type guards is an essential skill for any intermediate TypeScript developer. They empower you to write more resilient and maintainable applications, especially when interacting with external systems like APIs that may return dynamic data. Experiment with these patterns in your own projects to experience the full benefits of TypeScript's type system in action. Your future self (and your teammates) will thank you for the clarity and safety they provide.