Type Narrowing

TypeScript narrows types based on control flow analysis.

Control Flow Analysis

TypeScript analyzes your code to narrow types.

function example(x: string | number) {
  if (typeof x === "string") {
    // x is string here
    return x.toUpperCase();
  }
  // x is number here
  return x.toFixed(2);
}

Truthiness Narrowing

TypeScript narrows based on truthy/falsy checks.

function process(value: string | null | undefined) {
  if (value) {
    // value is string here (not null or undefined)
    console.log(value.length);
  }
  // value might be null or undefined here
}

Equality Narrowing

TypeScript narrows based on equality checks.

function example(x: string | number, y: string | boolean) {
  if (x === y) {
    // Both are string here
    return x.toUpperCase() + y.toUpperCase();
  }
}

Discriminated Union Narrowing

TypeScript narrows based on discriminant properties.

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

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

in Operator Narrowing

TypeScript narrows based on property existence.

interface Dog {
  bark(): void;
}

interface Cat {
  meow(): void;
}

function makeSound(pet: Dog | Cat) {
  if ("bark" in pet) {
    pet.bark(); // pet is Dog
  } else {
    pet.meow(); // pet is Cat
  }
}

instanceof Narrowing

TypeScript narrows based on instanceof checks.

class Animal {
  move(): void {}
}

class Dog extends Animal {
  bark(): void {}
}

function process(animal: Animal) {
  if (animal instanceof Dog) {
    animal.bark(); // animal is Dog
  }
}

Type Predicates

User-defined functions that narrow types.

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

function process(value: unknown) {
  if (isString(value)) {
    value.toUpperCase(); // value is string
  }
}

Assertion Functions

Functions that assert and narrow types.

function assertIsNumber(value: unknown): asserts value is number {
  if (typeof value !== "number") {
    throw new Error("Expected number");
  }
}

function process(value: unknown) {
  assertIsNumber(value);
  value.toFixed(2); // value is number
}

Exercises

Exercise 1: Control Flow

// Create a function that:
// - Takes string | number | boolean
// - Uses if/else to narrow the type
// - Handles each case appropriately

Exercise 2: Discriminated Unions

// Create a discriminated union for events
// Use switch to narrow and handle each event type

Exercise 3: Truthiness

// Create a function that:
// - Takes string | null | undefined
// - Uses truthiness to narrow
// - Returns a non-null string

Exercise 4: Type Predicates

// Create type predicates for:
// - isArray
// - isObject
// - isNumber
// Use them to narrow types

Exercise 5: Complex Narrowing

// Create a function with multiple narrowing steps
// Combine typeof, instanceof, and type predicates

Best Practices

1. Let TypeScript infer narrowing - It's very good at it
2. Use discriminated unions - Makes narrowing explicit
3. Create reusable type guards - For common patterns
4. Handle all cases - Use exhaustive checks
5. Trust the compiler - TypeScript's narrowing is sound

Common Mistakes

1. Not trusting narrowing

   // ❌ Unnecessary assertion
   function process(value: string | number) {
     if (typeof value === "string") {
       const str = value as string; // Unnecessary!
     }
   }
   
   // ✅ Trust narrowing
   function process(value: string | number) {
     if (typeof value === "string") {
       // value is already string here
     }
   }

2. Breaking narrowing with reassignment

   // ❌ Reassignment breaks narrowing
   let value: string | number = getValue();
   if (typeof value === "string") {
     value = 42; // Breaks narrowing
     value.toUpperCase(); // Error!
   }

3. Not handling all union members

   // ❌ Missing case
   function process(value: "a" | "b" | "c") {
     if (value === "a") {
       // Handle a
     }
     // Missing b and c
   }
   
   // ✅ Handle all cases
   function process(value: "a" | "b" | "c") {
     switch (value) {
       case "a":
         // Handle a
         break;
       case "b":
         // Handle b
         break;
       case "c":
         // Handle c
         break;
     }
   }

Next Steps

Learn about Mapped Types.