What is type guards internals?

Type guards are a fundamental feature in TypeScript that allow you to narrow down the type of a variable within a certain scope. Internally, they bridge the gap between runtime checks (which JavaScript understands) and compile-time type inference (which TypeScript provides), enabling more robust and type-safe code.

How Type Guards Work at a High Level

At its core, a type guard is a conditional check that, when evaluated at runtime, provides enough information for the TypeScript compiler to intelligently infer a more specific type for a variable within a particular code block. This compile-time type narrowing is driven by TypeScript's Control Flow Analysis (CFA).

Mechanism: Runtime Checks Informing Compile-Time Types

TypeScript's type system is erased during compilation to JavaScript. This means that type information doesn't exist at runtime. Type guards work by performing standard JavaScript runtime checks (like typeof or instanceof). The TypeScript compiler observes these checks and, based on their outcome, updates its internal understanding of the variable's type within the subsequent code path. If a check guarantees a certain type, the compiler narrows the type accordingly.

Key Components

• Runtime Expression: The actual JavaScript condition being evaluated (e.g., typeof value === 'string', obj instanceof MyClass).
• Control Flow Analysis (CFA): TypeScript's static analysis engine that tracks possible execution paths and updates type information based on conditional statements, loops, function calls, and assignments.
• Type Narrowing: The process by which the compiler refines the type of a variable to a more specific subtype based on the CFA's understanding of runtime checks.

Types of Type Guards and Their Internals

`typeof` Type Guards

These leverage JavaScript's built-in typeof operator. When TypeScript sees a comparison like typeof x === 'string', it knows that within the if block, x can safely be treated as a string (or number, boolean, symbol, bigint, undefined, function, object). The compiler performs this narrowing based on a hardcoded understanding of typeof's behavior.

function printLength(input: string | number) {
  if (typeof input === 'string') {
    // Here, input is narrowed to 'string'
    console.log(input.length);
  } else {
    // Here, input is narrowed to 'number'
    console.log(input.toFixed(2));
  }
}

`instanceof` Type Guards

Utilizes JavaScript's instanceof operator to check if an object is an instance of a particular class. TypeScript's CFA recognizes this operator and narrows the type of the variable to that specific class type within the conditional block.

class Dog { bark() {} }
class Cat { meow() {} }

function makeSound(animal: Dog | Cat) {
  if (animal instanceof Dog) {
    // animal is narrowed to Dog
    animal.bark();
  } else {
    // animal is narrowed to Cat
    animal.meow();
  }
}

`in` Operator Type Guards

Checks if a property exists on an object. TypeScript interprets property in object as a way to narrow the object's type to one that definitely contains property (if the original type was a union of types, some of which had the property and some didn't).

interface Car { drive(): void; }
interface Boat { sail(): void; }

function operateVehicle(vehicle: Car | Boat) {
  if ('drive' in vehicle) {
    // vehicle is narrowed to Car
    vehicle.drive();
  } else {
    // vehicle is narrowed to Boat
    vehicle.sail();
  }
}

User-Defined Type Guards (Type Predicates)

These are special functions that you write, which have a return type in the form parameterName is Type. The is Type part is the type predicate. Internally, when TypeScript encounters a call to such a function, and that function returns true, its CFA engine knows to narrow the type of parameterName to Type for the scope following that true result. This is crucial for custom type checks that typeof or instanceof cannot handle.

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

function isFish(pet: Fish | Bird): pet is Fish {
  // This check happens at runtime
  return (pet as Fish).swim !== undefined;
}

function move(pet: Fish | Bird) {
  if (isFish(pet)) {
    // pet is narrowed to Fish based on the predicate
    pet.swim();
  } else {
    // pet is narrowed to Bird
    pet.fly();
  }
}

Assertion Functions

Introduced in TypeScript 3.7, assertion functions are another form of user-defined type guard that assert conditions. They have a return type signature like asserts condition or asserts parameterName is Type. If an assertion function returns without throwing an error, TypeScript's CFA understands that the asserted condition must be true for the remainder of the current scope, narrowing types accordingly. This is particularly useful for preconditions or validation.

function assertIsString(val: any): asserts val is string {
  if (typeof val !== 'string') {
    throw new Error('Not a string!');
  }
}

function processInput(input: unknown) {
  assertIsString(input);
  // Here, input is guaranteed to be a string
  console.log(input.toUpperCase());
}

Conclusion

In essence, type guards are not a runtime feature of TypeScript itself. They are a compile-time mechanism where the TypeScript compiler intelligently uses information gleaned from standard JavaScript runtime checks (like typeof, instanceof, in, or the boolean return of a type predicate function) to refine its static understanding of types in different branches of your code, thereby enhancing type safety without adding any runtime overhead.