Mastering Discriminated Unions in TypeScript
Tags: webdev, typescript, programming
Published: 2024-05-20 19:28:05

---
canonical_url: https://antondevtips.com/blog/mastering-discriminated-unions-in-typescript
---

_Originally published at_ [_https://antondevtips.com_](https://antondevtips.com/blog/mastering-discriminated-unions-in-typescript)_._

## What Are Discriminated Unions

Often, applications require variables and functions that have multiple types of input or output.
TypeScript has a special Union Type for such use cases, called **Discriminated Unions**.

**Discriminated Unions** in TypeScript are formed from two or more other types.
A variable of **discriminated union** can be one of the types from the union.

Here's a simple example where a variable can hold either a number or a string:

```typescript
let id: number | string;
id = 100; // This code is correct
id = "200"; // This code is correct

// TypeScript Error: Type 'boolean' is not assignable to type 'string | number'.
id = false;
```

**Unions** are also useful when combining string literals. A literal in TypeScript is a special type for constant string, for example:

```typescript
let text: "TypeScript" = "TypeScript";
text = "TypeScript"; // This code compiles

// TypeScript Error: Type '"JavaScript"' is not assignable to type '"TypeScript"'.
text = "JavaScript";
```

By combining literals into unions you can express that a variable can only accept a certain set of values:
```typescript
function print(value: string, align: "left" | "right" | "center") {
    // ...
}

print("TypeScript types", "left");

// TypeScript Error: "align" parameter should be one of: "left" | "right" | "center"
print("TypeScript types", "middle");
```

When using **discriminated unions**, TypeScript will only allow to access properties or methods that are common to all types in the union.
To use type-specific properties or methods, you need to use type guards for built-in types:
```typescript
function getLength(obj: string | string[]) {
    if (typeof obj === "string") {
        return obj.length; // Return length of a string
    }

    return obj.length; // Return legnth of string array
}
```


## Discriminated Unions With Object Types

Discriminated Unions can combine object types too.
Let's explore an example of geometrics shapes, that have common and different properties:

```typescript
type Circle = {
    type: "circle";
    radius: number;
};

type Square = {
    type: "square";
    size: number;
};
```

Let's create a function that calculates a square for each shape:

```typescript
function getSquare(shape: Circle | Square) {
    if (shape.type === "circle") {
        return Math.PI * shape.radius * shape.radius;
    }

    if (shape.type === "square") {
        return shape.size * shape.size;
    }
}

const circle: Circle = {
    type: "circle",
    radius: 10
};

const square: Square = {
    type: "square",
    size: 5
};

console.log("Circle square: ", getSquare(circle));
console.log("Circle square: ", getSquare(square));
```

Here a `getSquare` function accepts a shape parameter that can be one of 2 types: `Circle` or `Square`.
When working with custom types you can use a property that will allow to distinguish types from each other.
In our example it's a `type` property.
Type guards here are straightforward:

```typescript
function getSquare(shape: Circle | Square) {
    if (shape.type === "circle") {
        return Math.PI * shape.radius * shape.radius;
    }

    if (shape.type === "square") {
        return shape.square;
    }
    
    return 0;
}
```

TypeScript is smart enough to know that we are working with `Circle` or `Square` type. 


## Using Discriminated Unions as Function Return Type

Another example where **discriminated unions** are useful - is a function return type.
Let's explore an example of placing an order for a product by its ID and desired quantity.
The return type of this function will be a discriminated union representing three possible states:
* order successfully created
* product not found
* not enough product quantity in the warehouse

The naive approach is to declare a big object with properties that cover all three cases.
But such implementation is cumbersome.

Discriminated unions offer a more elegant approach:

```typescript
type OrderResponse = OrderCreated | ProductNotFound | NoProductQuantity;

type OrderCreated = {
    type: "order-created";
    orderId: string;
    message: string;
};

type ProductNotFound = {
    type: "product-not-found";
    message: string;
};

type NoProductQuantity = {
    type: "no-product-quantity";
    message: string;
};
```

Now we can use this union type as a function's return type.
We are getting products from a database or an external API, but for simplicity we will mock the data:

```typescript
function orderProduct(productId: string, quantity: number): OrderResponse {
    const productsDatabase = {
        "Mobile Phone": { stock: 10 },
        "Smart TV": { stock: 0 },
    };

    const product = productsDatabase[productId];
    
    if (!product) {
        return {
            type: "product-not-found",
            message: "Product not found"
        };
    }
    
    if (quantity > product.stock) {
        return {
            type: "no-product-quantity",
            message: "Insufficient product quantity"
        };
    }
    
    return {
        type: "order-created",
        orderId: `order-${new Date().getTime()}`,
        message: "Order has been successfully created"
    };
}
```

In this function we are returning 3 types of responses: "order-created", "product-not-found", "no-product-quantity".
To order a product let's call the method:

```typescript
const orderResult = orderProduct("Mobile Phone", 1);

switch (orderResult.type) {
    case "order-created":
        console.log(`Success: ${orderResult.message} (Order ID: ${orderResult.orderId})`);
        break;
    case "product-not-found":
        console.log(`Error: ${orderResult.message}`);
        break;
    case "no-product-quantity":
        console.log(`Error: ${orderResult.message}`);
        break;
}
```

As you can see discriminated unions make code more readable and maintainable in such use cases.


## Summary

**Discriminated unions** in TypeScript offer a robust way to manage different data types under a united type.
They enhance type safety, improve code clarity, and ensure that all possible cases are handled, reducing runtime errors.
Using discriminated unions as function input and output types will significantly improve the quality and maintainability of your TypeScript applications.

Hope you find this blog post useful. Happy coding!

_Originally published at_ [_https://antondevtips.com_](https://antondevtips.com/blog/mastering-discriminated-unions-in-typescript)_._

### After reading the post consider the following:

- [Subscribe](https://antondevtips.com/blog/mastering-discriminated-unions-in-typescript#subscribe) **to receive newsletters with the latest blog posts**
- [Download](https://github.com/AntonMartyniuk-DevTips/dev-tips-code/tree/main/frontend/typescript/discriminated-unions) **the source code for this post from my** [github](https://github.com/AntonMartyniuk-DevTips/dev-tips-code/tree/main/frontend/typescript/discriminated-unions) (available for my sponsors on BuyMeACoffee and Patreon)

If you like my content —  **consider supporting me**

Unlock exclusive access to the source code from the blog posts by joining my **Patreon** and **Buy Me A Coffee** communities!

[![](https://cdn-images-1.medium.com/max/233/1*GSZFx05RDUWr5pn_E9bK8w.png)](https://www.buymeacoffee.com/antonmartyniuk)

[![](https://cdn-images-1.medium.com/max/229/1*8tJk9eYCJrkzoAJw2cILSA.png)](https://www.patreon.com/bePatron?u=73769486)