Type Narrowing

typeof Guards

The typeof operator checks the type of a value at runtime, allowing TypeScript to narrow the type.

Basic typeof

function process(value: string | number | boolean) {
  if (typeof value === "string") {
    // TypeScript knows value is string
    return value.toUpperCase();
  } else if (typeof value === "number") {
    // TypeScript knows value is number
    return value.toFixed(2);
  } else {
    // TypeScript knows value is boolean
    return value ? "yes" : "no";
  }
}

typeof with undefined

function greet(name: string | undefined) {
  if (typeof name === "string") {
    return `Hello, ${name}`;
  }
  return "Hello, stranger";
}

typeof in Callbacks

function handleEvent(event: KeyboardEvent | MouseEvent) {
  if (typeof event.key === "string") {
    // KeyboardEvent
    console.log(event.key);
  } else {
    // MouseEvent
    console.log(event.clientX);
  }
}

Limitations

typeof only works with primitives:

function process(value: string | object) {
  if (typeof value === "object") {
    // Can't distinguish between different object types
    // value is still string | object
  }
}

instanceof Guards

The instanceof operator checks if an object is an instance of a specific class.

Basic instanceof

class HttpError {
  constructor(public statusCode: number, public message: string) {}
}

class NetworkError {
  constructor(public message: string) {}
}

function handleError(error: HttpError | NetworkError) {
  if (error instanceof HttpError) {
    console.log(`HTTP ${error.statusCode}: ${error.message}`);
  } else {
    console.log(`Network: ${error.message}`);
  }
}

instanceof with Built-in Classes

function processDate(value: Date | string) {
  if (value instanceof Date) {
    return value.getFullYear();
  }
  return new Date(value).getFullYear();
}

instanceof with Error Types

function catchBlock(error: unknown) {
  if (error instanceof TypeError) {
    console.log("Type error:", error.message);
  } else if (error instanceof RangeError) {
    console.log("Range error:", error.message);
  } else if (error instanceof Error) {
    console.log("Generic error:", error.message);
  }
}

instanceof vs typeof

// Use typeof for primitives
function isString(value: unknown): value is string {
  return typeof value === "string";
}

// Use instanceof for classes
function isError(value: unknown): value is Error {
  return value instanceof Error;
}

Discriminated Unions

Discriminated unions use a common property to narrow types in switch statements.

Pattern

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rectangle"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      // TypeScript knows shape is circle
      return Math.PI * shape.radius ** 2;
    case "rectangle":
      // TypeScript knows shape is rectangle
      return shape.width * shape.height;
    case "triangle":
      // TypeScript knows shape is triangle
      return (shape.base * shape.height) / 2;
  }
}

Exhaustive Switch

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rectangle":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
    default:
      const _exhaustive: never = shape;
      return _exhaustive;
  }
}

Real-World Example

type Action =
  | { type: "INCREMENT"; amount: number }
  | { type: "DECREMENT"; amount: number }
  | { type: "RESET" };

function reducer(state: number, action: Action): number {
  switch (action.type) {
    case "INCREMENT":
      return state + action.amount;
    case "DECREMENT":
      return state - action.amount;
    case "RESET":
      return 0;
  }
}