Type Guards

Type narrowing is one of the most important concepts in TypeScript. Often, however, standard type guards like typeof or instanceof are not sufficient for complex custom objects. This is where Custom Type Guards come in.

Standard Type Guards

Let's begin by summarizing how TypeScript narrows types using standard JavaScript operators:

function processInput(val: string | number) {
  if (typeof val === 'string') {
    // Here 'val' is of type string
    console.log(val.toUpperCase());
  } else {
    // Here 'val' is of type number
    console.log(val.toFixed(2));
  }
}

Custom Type Guards (is operator)

To define a custom type guard, we create a function that returns a type predicate in the format parameterName is Type instead of a standard boolean return type.

The function must return a boolean (true or false). If it returns true, TypeScript will know that the passed parameter is of the specified type.

interface Cat {
  name: string;
  meow(): void;
}

interface Dog {
  name: string;
  bark(): void;
}

// This is a custom type guard
function isCat(animal: Cat | Dog): animal is Cat {
  return (animal as Cat).meow !== undefined;
}

function makeNoise(pet: Cat | Dog) {
  if (isCat(pet)) {
    // Here TypeScript knows 'pet' is a Cat
    pet.meow();
  } else {
    // Here TypeScript knows 'pet' is a Dog
    pet.bark();
  }
}

Safety and Casting (as vs Type Guards)

Type casting (e.g., val as Cat) forces the compiler to trust the developer without any real runtime verification. If the runtime object does not meet expectations, the code will fail silently or throw exceptions.

Custom type guards, on the other hand, perform a robust and dynamic runtime check, safely and accurately informing the TypeScript compiler of the actual variable type:

function processInput(input: unknown) {
  // unsafe casting: could crash if input does not have the split method
  // const str = input as string;
  // console.log(str.split(' '));

  // safe guard
  if (isString(input)) {
    console.log(input.split(' ')); // 100% Safe!
  }
}

Try it yourself

Exercise 1: String Type Guard

Exercise 2: Premium User Type Guard

Exercise 3: Custom Error Object Validation

Exercise 4: Admin Type Guard