Using Union Types to Improve Your TypeScript Code

TypeScript's unions are a powerful feature. Let's dive into what they are and how you can use them to your advantage!

What is union type?

A union type is a set of mutually exclusive types. The name union (or sum type) comes from type theory. According to Wikipedia definition:

The sum type is a “tagged union”. That is, for types “A” and “B”, the type “A + B” holds either a term of type “A” or a term of type “B” and it knows which one it holds.

And in TypeScript, it's similar to type theory (as programming has a lot in common with the set, type, and category theory). Let's look at how official documentation defines union type:

A union type is a type formed from two or more other types, representing values that may be any one of those types. We refer to each of these types as the union’s members.

The most basic union type consists of two primitive types:

type Union = number | string;

// defined as inline type
function getUserById(id: number | string) {
  // ...
}

This allows handling value which can be either number a string. This is great to prove code is type-safe for all possible cases!

In this guide, I'm not going to discuss null and undefined and how by default they are assignable to anything. Please do yourself a favor and start using strict or at least strict null checks.

Union types are perfect to express a finite number of known options, either primitive literals or objects (as a discriminated unions which we'll discuss later), where single logic has to handle all the possible cases. A few great examples where union types shine are:

finite state machines (like React's useReducer)
event names
object fields (using keyof keyword)

You shouldn't use union types where the amount of possible options is too large, for example, a person's name as there is an infinite number of options. Also, keep in mind, they exist only at the type level. They are stripped out during compilation.

How to narrow union types?

If your function logic can work most of the time on union type, it's great. But sooner or later you'll need to narrow it down to a specific union member. There are a few common patterns when narrowing union type.

Using `typeof` keyword

typeof The keyword is the most basic TypeScript tool. Unfortunately, it will work only with string, number or function

function getDateFullYear(date: number | Date) {
  if (typeof date === "number") {
    return new Date(date).getFullYear();
  }

  return date.getFullYear();
}

Using `instanceof` keyword

While typeof works great with primitives, instanceof is great for the OOP feature of TypeScript — classes.

class Developer {
  public develop() {
    // ...
  }
}

class Manager {
  public manage() {
    // ...
  }
}

function work(person: Developer | Manager) {
  if (person instanceof Developer) {
    person.develop();
  } else if (person instanceof Manager) {
    person.manage();
  }
}

There is more OOP way of implementing work function, but the above example should do the job as well.

Using `if` or `switch` statement

Because union types can also consist of literal type members, not generic types but specific values, it's easy to use switch or if statements on them.

function getTextColor(theme: "dark" | "light") {
  switch (theme) {
    case "dark":
      return "#ffffff";
    case "light":
      return "#000000";
  }
}

const textColor = getTextColor("darkk");
// 🛑 Argument of type '"darkk"' is not assignable to parameter of type '"dark" | "light"'.(2345)

String literals are helpful for specifying a limited set of possible options, similar to an enum being a great replacement for them, as there is not that much added complexity as in the enum's case. Using union type of string literals will help not make typos or pass generic string.

When you need to narrow type down from string to string literal, you can use a type guard function, which we'll discuss later in this post!

Using “pattern match” object

When talking about string or number literals, there is a great trick allowing you to achieve "pattern matching" in TypeScript:

function getTextColor(theme: "dark" | "light") {
  return {
    dark: "#fff",
    light: "#000",
  }[theme];
}

At first, it may look noisy, but the advantage of this solution is the fact it's an expression, not a statement, which may be sometimes required in places like JSX.

Using the type guard function

One nice but advanced feature TypeScript provides us is the ability to define a custom type guard function. By default, TypeScript provides us with built-in type guards like typeof, instanceof keywords we discussed earlier. There is also Array.isArray() which is handy when we need to handle either a single value or multiple values of the same type.

But sometimes it's required to write something more specific to our business logic. Let's take a look at a simple function that narrows any string to either dark or light:

type Theme = "dark" | "light";

function isTheme(value: string): value is Theme {
  return value === "dark" || value === "light";
}

function getTheme(value: string): Theme {
  if (isTheme(value)) {
    return value;
  }

  // default case
  return "dark";
}

This is helpful when your value is coming from the outside world (API or used provided) and you cannot be sure it will be always within your expected range.

Not only primitive types

Union types are not limited to primitive types or type literals. They can as well be objects. I'm using the following pattern all the time as TypeScript's equivalent of algebraic data type (ADT). It's a great pattern to express values that may contain different payloads or the same payload interpreted differently.

type Event = Credit | Debit;
type Credit = { type: "credit"; amount: number };
type Debit = { type: "debit"; amount: number };

let account = 0;
function handleAccountEvent(event: Event) {
  switch (event.type) {
    case "credit":
      account += event.amount;
      break;
    case "debit":
      account -= event.amount;
      break;
  }
}

handleAccountEvent({ type: "credit", amount: "10" }); // account == 10
handleAccountEvent({ type: "debit", amount: "5" }); // account == 5

Conclusion

I hope you understand union types better! With all that knowledge and all the TypeScript features now under your belt, you can take advantage of them when working on the next great feature!

Resources

List of resources I used when researching this blog post:

Also Published here

Using typeof keyword

Using instanceof keyword

Using if or switch statement

Using `typeof` keyword

Using `instanceof` keyword

Using `if` or `switch` statement