Typescript Type Guards And Discriminated Unions Complete Guide

Understanding TypeScript Type Guards

Type guards are a special kind of type check used in TypeScript to determine the type of objects at compile time. This way TypeScript can narrow down a variable’s type and provide more specific information to the compiler.

Example 1: Using typeof as a Type Guard

Let's start with a simple example that uses typeof to guard against potential runtime type errors:

function printVariable(x: number | string) {
    if (typeof x === 'string') {
        // Here TypeScript recognizes that `x` is a string.
        return console.log('The string is: ', x.toUpperCase());
    } else if (typeof x === 'number') {
        // And here TypeScript knows that `x` must be a number.
        return console.log('The number is: ', x.toFixed(2));
    }
}

printVariable("hello"); // Output: The string is:  HELLO
printVariable(42);      // Output: The number is:  42.00

In this example:

• We have a function printVariable that accepts a parameter x which could either be a number or a string.
• Inside the function, we use typeof to check the type of x.
• Depending on the result, TypeScript narrows the type and allows us to call toUpperCase() for strings and toFixed() for numbers.

Example 2: Using in as a Type Guard

The in keyword can be used as a type guard to check for the existence of a property in an object:

interface Bird {
    fly: () => void;
    layEggs: () => void;
}
  
interface Fish {
    swim: () => void;
    layEggs: () => void;
}

function getAnimalAction(animal: Bird | Fish) {
    if ('fly' in animal) {
        animal.fly();
        console.log("This animal can fly!");
    } else {
        animal.swim();
        console.log("This animal can swim!");
    }
}

let myBird: Bird = {
    fly: () => console.log("Bird flying..."),
    layEggs: () => console.log("Bird laying eggs...")
};

let myFish: Fish = {
    swim: () => console.log("Fish swimming..."),
    layEggs: () => console.log("Fish laying eggs...")
};

getAnimalAction(myBird); // Output: Bird flying...
                         //         This animal can fly!
getAnimalAction(myFish); // Output: Fish swimming...
                         //         This animal can swim!

In this example:

• We define two interfaces: Bird and Fish.
• Both interfaces share a common method layEggs, but Bird has fly and Fish has swim.
• In the function getAnimalAction, we use the in operator to check which properties exist in the animal object.
• Depending on the property, TypeScript understands the specific type and allows us to call the appropriate method.

Example 3: User-defined Type Guard

We can also create our own type guard functions that return a boolean value asserting the type of the variable within a certain scope:

class Dog {
    bark() {
        console.log("Woof woof!");
    }
}

class Cat {
    meow() {
        console.log("Meow meow!");
    }
}

function isDog(pet: Dog | Cat): pet is Dog {
    return (pet as Dog).bark !== undefined;
}

function getPetSound(pet: Dog | Cat) {
    if (isDog(pet)) {
        pet.bark(); 
    } else {
        // TypeScript knows that if pet is not a Dog, then it must be a Cat.
        pet.meow();
    }
}

let myDog: Dog = new Dog();
let myCat: Cat = new Cat();

getPetSound(myDog); // Output: Woof woof!
getPetSound(myCat); // Output: Meow meow!

In this example:

• We create two classes Dog and Cat with distinct methods.
• We then write a user-defined type guard isDog that returns true if the passed pet argument has a bark method.
• Finally, in getPetSound function, when we check using isDog, TypeScript treats pet as a Dog inside the if block, and as a Cat in its else clause.

Understanding Discriminated Unions

A discriminated union is a form of a tagged union, wherein each member of the union has a property, typically called a discriminator, that has a unique literal type.

Example 1: Basic Discriminated Unions

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

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

type Shape = Circle | Square;

function getArea(shape: Shape) {
    switch(shape.kind) {
        case "circle":
            // Inside this block, TypeScript knows shape is a Circle.
            return Math.PI * shape.radius ** 2;
        case "square":
            // Inside this block, TypeScript knows shape is a Square.
            return shape.sideLength ** 2;
    }
}

console.log(getArea({kind: 'circle', radius: 5})); // Output: 78.53981633974483
console.log(getArea({kind: 'square', sideLength: 5})); // Output: 25

In this example:

• We define two types: Circle and Square.
• Both have a kind property which uniquely discriminates them from each other.
• When handling getArea function, TypeScript uses the discriminant (shape.kind) to understand the type and narrow down the shape's type within each case.

Example 2: Enhancing Discriminated Union with Additional Properties

interface Bird {
    type: "bird";
    beakLength: number;
}

interface Fish {
    type: "fish";
    scaleTexture: string;
}

type Animal = Bird | Fish;

function describeAnimal(animal: Animal) {
    switch(animal.type) {
        case "bird":
            return "I am a bird with a beak length of " + animal.beakLength + " cm";
        case "fish":
            return "I am a fish with a scale texture like " + animal.scaleTexture;
    }
}

// Create an instance of Bird and Fish to test
let sparrow: Bird = { type: 'bird', beakLength: 4 };
let goldFish: Fish = { type: 'fish', scaleTexture: "shiny" };

console.log(describeAnimal(sparrow));  // Output: I am a bird with a beak length of 4 cm
console.log(describeAnimal(goldFish)); // Output: I am a fish with a scale texture like shiny

In this example:

• The interfaces Bird and Fish both possess a type property which serves the purpose of discrimination.
• Each interface adds more relevant details specific to their type (beakLength for birds and scaleTexture for fish).
• The describeAnimal function switches based on these discriminants and accesses type-specific properties.

Example 3: Including a Default Case

It is good practice to include a default case when working with discriminated unions to catch any future possible variants that might be added.

type Animal = Bird | Fish | Reptile;

interface Reptile {
    type: "reptile";
    scaleColor: string;
    hasTail: boolean;
}

function describeAnimal(animal: Animal) {
    switch(animal.type) {
        case "bird":
            return "I am a bird with a beak length of " + animal.beakLength + " cm";
        case "fish":
            return "I am a fish with a scale texture like " + animal.scaleTexture;
        case "reptile":
            return `I am a reptile with ${animal.hasTail ? 'a' : 'no'} tail and scales are ${animal.scaleColor}.`;
        default:
            const exhaustiveCheck: never = animal;
            throw new Error(`Unknown animal type: ${exhaustiveCheck}`);
    }
}

// Test cases
let turtle: Reptile = { type: 'reptile', scaleColor: 'green', hasTail: true };

console.log(describeAnimal(turtle)); // Output: I am a reptile with a tail and scales are green.

In this example:

• We introduce a third variant Reptile.
• Inside describeAnimal, the default case ensures that every possible variant is handled.
• If a new variant were added without a corresponding switch-case, the compiler would complain because animal would now have a different structure than the never type, thus catching an error during compilation.