Discriminated Unions in TypeScript

Discriminated unions (also known as tagged unions) are a powerful feature in TypeScript that allow you to model data structures where a type can be one of several options, and each option has a unique "tag" that helps distinguish it. These unions are especially useful for dealing with multiple types that share some common properties but differ in others.

 

What are Discriminated Unions?

A discriminated union is a union type that uses a common property (often called a "discriminator" or "tag") to determine the type of the object. The discriminator is a literal type property that acts as the "key" for TypeScript's type narrowing. When TypeScript encounters a value in the union, it uses the discriminator to figure out the correct type, allowing it to access type-specific properties safely.

 

Key Concepts

• Discriminator Property: A literal property in the object that distinguishes between different types in the union.
• Union Type: A type that can be one of several types.
• Type Narrowing: TypeScript narrows down the union type based on the discriminator property.

 

Example of Discriminated Unions

Here is an example of a discriminated union in TypeScript, where we define different shapes using a common type property:

interface Circle {
  type: "circle";
  radius: number;
}

interface Square {
  type: "square";
  sideLength: number;
}

type Shape = Circle | Square;

function calculateArea(shape: Shape): number {
  if (shape.type === "circle") {
    return Math.PI * shape.radius * shape.radius;
  } else {
    return shape.sideLength * shape.sideLength;
  }
}

const myCircle: Circle = { type: "circle", radius: 10 };
const mySquare: Square = { type: "square", sideLength: 5 };

console.log(calculateArea(myCircle));  // Output: 314.159
console.log(calculateArea(mySquare));  // Output: 25

Explanation:

• The Shape type is a union of Circle and Square.
• Each type has a type property with a distinct literal value ("circle" and "square"), which acts as the discriminator.
• In the calculateArea function, TypeScript uses the type property to narrow the union and access type-specific properties (radius for Circle and sideLength for Square).

 

Advantages of Discriminated Unions

1. Type Safety: Discriminated unions help ensure that TypeScript can narrow types properly, preventing errors when accessing properties.
2. Readability: The type property makes the union types more explicit, improving the readability and maintainability of the code.
3. Flexibility: You can easily add new variants to the union type without modifying the existing logic, just by adding a new interface with the corresponding type property.

Example with Complex Types

You can use discriminated unions to represent more complex scenarios, such as different types of responses from an API:

interface SuccessResponse {
  status: "success";
  data: string;
}

interface ErrorResponse {
  status: "error";
  message: string;
}

type ApiResponse = SuccessResponse | ErrorResponse;

function handleResponse(response: ApiResponse): void {
  if (response.status === "success") {
    console.log("Data received:", response.data);
  } else {
    console.log("Error:", response.message);
  }
}

const successResponse: SuccessResponse = { status: "success", data: "All good!" };
const errorResponse: ErrorResponse = { status: "error", message: "Something went wrong" };

handleResponse(successResponse);  // Output: Data received: All good!
handleResponse(errorResponse);    // Output: Error: Something went wrong

Explanation:

• The ApiResponse type is a union of SuccessResponse and ErrorResponse.
• The status property is the discriminator that TypeScript uses to distinguish between the two response types.
• Inside the handleResponse function, the status property is used to safely narrow down the type and access the correct properties (data for success and message for errors).

 

Using Discriminated Unions with Functions

Discriminated unions are also helpful in situations where you need to define different behaviors for different types:

interface Admin {
  type: "admin";
  permissions: string[];
}

interface User {
  type: "user";
  username: string;
}

type Person = Admin | User;

function greetPerson(person: Person): string {
  if (person.type === "admin") {
    return `Hello Admin, you have the following permissions: ${person.permissions.join(", ")}`;
  } else {
    return `Hello ${person.username}, welcome back!`;
  }
}

const admin: Admin = { type: "admin", permissions: ["manage", "edit", "delete"] };
const user: User = { type: "user", username: "john_doe" };

console.log(greetPerson(admin));  // Output: Hello Admin, you have the following permissions: manage, edit, delete
console.log(greetPerson(user));   // Output: Hello john_doe, welcome back!

Explanation:

• The Person type is a union of Admin and User, where the type property acts as the discriminator.
• In the greetPerson function, TypeScript narrows the union based on the type property, ensuring that the appropriate properties (permissions or username) are accessed.

 

Summary

Discriminated unions in TypeScript allow you to model data that can have multiple types, each distinguished by a common property (the discriminator). By leveraging the discriminator, TypeScript narrows the type, enabling you to safely access type-specific properties. This approach ensures better type safety, flexibility, and clarity in your code.

• Discriminated Union: A union of types distinguished by a common literal property.
• Type Narrowing: TypeScript uses the discriminator to narrow the union and access properties specific to the type.
• Flexibility and Safety: Discriminated unions provide a flexible way to handle multiple types while maintaining type safety.

Discriminated unions are a powerful tool for modeling complex data structures in TypeScript, especially in scenarios like handling API responses, form inputs, or event types.