TypeScript is a superb software for writing JavaScript that scales. It’s roughly the de facto commonplace for the net on the subject of giant JavaScript tasks. As excellent as it’s, there are some difficult items for the unaccustomed. One such space is TypeScript discriminated unions.

Particularly, given this code:

interface Cat {
  weight: quantity;
  whiskers: quantity;
}
interface Canine {
  weight: quantity;
  pleasant: boolean;
}
let animal: Canine | Cat;

…many builders are stunned (and perhaps even offended) to find that after they do animal., solely the weight property is legitimate, and never whiskers or pleasant. By the top of this put up, this may make excellent sense.

Earlier than we dive in, let’s do a fast (and needed) overview of structural typing, and the way it differs from nominal typing. It will arrange our dialogue of TypeScript’s discriminated unions properly.

Structural typing

One of the simplest ways to introduce structural typing is to match it to what it’s not. Most typed languages you’ve most likely used are nominally typed. Think about this C# code (Java or C++ would look comparable):

class Foo {
  public int x;
}
class Blah {
  public int x;
}

Despite the fact that Foo and Blah are structured precisely the identical, they can’t be assigned to 1 one other. The next code:

Blah b = new Foo();

…generates this error:

Can't implicitly convert sort 'Foo' to 'Blah'

The construction of those courses is irrelevant. A variable of sort Foo can solely be assigned to cases of the Foo class (or subclasses thereof).

TypeScript operates the other method. TypeScript considers sorts to be appropriate if they’ve the identical construction—therefore the identify, structural typing. Get it?

So, the next runs with out error:

class Foo {
  x: quantity = 0;
}
class Blah {
  x: quantity = 0;
}
let f: Foo = new Blah();
let b: Blah = new Foo();

Sorts as units of matching values

Let’s hammer this house. Given this code:

class Foo {
  x: quantity = 0;
}

let f: Foo;

f is a variable holding any object that matches the construction of cases created by the Foo class which, on this case, means an x property that represents a quantity. Meaning even a plain JavaScript object will likely be accepted.

let f: Foo;
f = {
  x: 0
}

Unions

Thanks for sticking with me up to now. Let’s get again to the code from the start:

interface Cat {
  weight: quantity;
  whiskers: quantity;
}
interface Canine {
  weight: quantity;
  pleasant: boolean;
}

We all know that this:

let animal: Canine;

…makes animal any object that has the identical construction because the Canine interface. So what does the next imply?

let animal: Canine | Cat;

This sorts animal as any object that matches the Canine interface, or any object that matches the Cat interface.

So why does animal—because it exists now—solely enable us to entry the weight property? To place it merely, it’s as a result of TypeScript doesn’t know which sort it’s. TypeScript is aware of that animal needs to be both a Canine or Cat, nevertheless it might be both (or each on the similar time, however let’s maintain it easy). We’d possible get runtime errors if we have been allowed to entry the pleasant property, however the occasion wound up being a Cat as a substitute of a Canine. Likewise for the whiskers property if the item wound up being a Canine.

Sort unions are unions of legitimate values relatively than unions of properties. Builders typically write one thing like this:

let animal: Canine | Cat;

…and anticipate animal to have the union of Canine and Cat properties. However once more, that’s a mistake. This specifies animal as having a worth that matches the union of legitimate Canine values and legitimate Cat values. However TypeScript will solely permit you to entry properties it is aware of are there. For now, meaning properties on all the kinds within the union.

Narrowing

Proper now, now we have this:

let animal: Canine | Cat;

How can we correctly deal with animal as a Canine when it’s a Canine, and entry properties on the Canine interface, and likewise when it’s a Cat? For now, we will use the in operator. That is an old-school JavaScript operator you most likely don’t see fairly often, nevertheless it basically permits us to check if a property is in an object. Like this:

let o = { a: 12 };

"a" in o; // true
"x" in o; // false

It seems TypeScript is deeply built-in with the in operator. Let’s see how:

let animal: Canine | Cat = {} as any;

if ("pleasant" in animal) {
  console.log(animal.pleasant);
} else {
  console.log(animal.whiskers);
}

This code produces no errors. When contained in the if block, TypeScript is aware of there’s a pleasant property, and due to this fact casts animal as a Canine. And when contained in the else block, TypeScript equally treats animal as a Cat. You possibly can even see this in the event you hover over the animal object inside these blocks in your code editor:

Discriminated unions

You would possibly anticipate the weblog put up to finish right here however, sadly, narrowing sort unions by checking for the existence of properties is extremely restricted. It labored effectively for our trivial Canine and Cat sorts, however issues can simply get extra difficult, and extra fragile, when now we have extra sorts, in addition to extra overlap between these sorts.

That is the place discriminated unions come in useful. We’ll maintain every thing the identical from earlier than, besides add a property to every sort whose solely job is to differentiate (or “discriminate”) between the kinds:

interface Cat {
  weight: quantity;
  whiskers: quantity;
  ANIMAL_TYPE: "CAT";
}
interface Canine {
  weight: quantity;
  pleasant: boolean;
  ANIMAL_TYPE: "DOG";
}

Be aware the ANIMAL_TYPE property on each sorts. Don’t mistake this as a string with two completely different values; this can be a literal sort. ANIMAL_TYPE: "CAT"; means a sort that holds precisely the string "CAT", and nothing else.

And now our test turns into a bit extra dependable:

let animal: Canine | Cat = {} as any;

if (animal.ANIMAL_TYPE === "DOG") {
  console.log(animal.pleasant);
} else {
  console.log(animal.whiskers);
}

Assuming every sort taking part within the union has a definite worth for the ANIMAL_TYPE property, this test turns into foolproof.

The one draw back is that you just now have a brand new property to cope with. Any time you create an occasion of a Canine or a Cat, it’s a must to provide the single right worth for the ANIMAL_TYPE. However don’t fear about forgetting as a result of TypeScript will remind you. 🙂

Conclusion

At the start of this text, I stated it might make sense why weight is the one accessible property within the following instance:

interface Cat {
  weight: quantity;
  whiskers: quantity;
}
interface Canine {
  weight: quantity;
  pleasant: boolean;
}
let animal: Canine | Cat;

What we discovered is that TypeScript solely is aware of that animal may very well be both a Canine or a Cat, however not each. As such, all we get is weight, which is the one frequent property between the 2.

The idea of discriminated unions is how TypeScript differentiates between these objects and does so in a method that scales extraordinarily effectively, even with bigger units of objects. As such, we needed to create a brand new ANIMAL_TYPE property on each sorts that holds a single literal worth we will use to test towards. Positive, it’s one other factor to trace, nevertheless it additionally produces extra dependable outcomes—which is what we wish from TypeScript within the first place.