📖 The Story: The Shape Detective

A payment processing company handled multiple payment types: Credit Cards, PayPal, and Bank Transfers. Each had different properties. The developer used a union type:

type Payment = CreditCard | PayPal | BankTransfer;

function processPayment(payment: Payment) {
  // How do we know if it has cardNumber or paypalemail?
  payment.cardNumber; // ❌ Error! Not all types have this!
}

TypeScript blocked access because it couldn't know which specific type payment was. The developer almost reached for as CreditCard—a dangerous assertion that would crash on PayPal payments.

Instead, they learned type narrowing. By checking for a property that only exists on one type, TypeScript automatically narrowed the type inside that condition. Safe access. Zero assertions. The code handled all three payment types without a single crash.

Narrowing is TypeScript's reasoning engine. You give it clues; it solves the puzzle.

🎯 Why Narrowing?

🧒 Explain Like I'm 10

Imagine a mystery box that could contain a toy car, a doll, or a puzzle. You can't play with it until you know what's inside.

You shake it. "It rattles!" Now you know it's not the puzzle (puzzles don't rattle). You've narrowed it down. You look through the keyhole. "I see wheels!" Now you know it's the car. You can finally play with it.

Every check you make (typeof, in, instanceof) is a clue. TypeScript uses these clues to figure out exactly what's in the box at that moment.

🎓 Professional Explanation

Type narrowing is the compiler's process of refining a variable's type from a broad union to a specific member based on control flow analysis. TypeScript analyzes your if statements, switch blocks, and ternary expressions, tracking which conditions must be true in each code path, and adjusts the type accordingly.

📊 The Narrowing Flow

🔤 typeof Guards

The simplest narrowing tool. Works with string, number, boolean, symbol, bigint, function, and undefined.

function formatValue(value: string | number) {
  if (typeof value === "string") {
    // In here, TypeScript KNOWS value is a string
    return value.toUpperCase(); // ✅ Safe!
  }
  // Here, TypeScript KNOWS value must be a number
  return value.toFixed(2; // ✅ Safe!
}

💡 Truthiness Narrowing

Checking if a value exists automatically filters out null and undefined.

function printLength(str: string | null | undefined) {
  if (str) {
    console.log(str.length); // ✅ TS knows str is a string here
  } else {
    console.log("No string provided");
  }
}

🔍 The in Operator

The in operator checks if a property exists on an object. Perfect for narrowing object unions.

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

function move(animal: Bird | Fish) {
  if ("swim" in animal) {
    animal.swim(); // ✅ TS knows it's a Fish!
  } else {
    animal.fly(); // ✅ TS knows it's a Bird!
  }
}

🏗️ instanceof Narrowing

For classes, instanceof narrows to the class type.

function logError(error: Error | string) {
  if (error instanceof Error) {
    console.log(error.message); // ✅ It's an Error object
  } else {
    console.log(error.toUpperCase()); // ✅ It's a string
  }
}

🎯 Custom Type Predicates

This is the crown jewel of narrowing. When built-in guards aren't enough, write your own with the is keyword.

interface Cat { meow(): void; }
interface Dog { bark(): void; }

// The return type 'animal is Cat' is a TYPE PREDICATE
function isCat(animal: Cat | Dog): animal is Cat {
  return (animal as Cat).meow !== undefined;
}

function makeSound(animal: Cat | Dog) {
  if (isCat(animal)) {
    animal.meow(); // ✅ TS trusts your predicate!
  } else {
    animal.bark(); // ✅ Must be a Dog!
  }
}

🏷️ Discriminated Unions (Best Practice)

The cleanest narrowing pattern. Give every variant a literal "tag" field.

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

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2; // ✅ .radius exists!
    case "square":
      return shape.sideLength ** 2; // ✅ .sideLength exists!
    case "rectangle":
      return shape.width * shape.height; // ✅ Both exist!
  }
}

✅ Exhaustive Checking with never

The most powerful trick in TypeScript. Guarantee you've handled every possible case—even future ones.

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
    case "rectangle":
      return shape.width * shape.height;
    default:
      // If we've handled all cases, shape here is 'never'
      const _exhaustiveCheck: never = shape;
      return _exhaustiveCheck;
  }
}

// Later, someone adds 'triangle' to Shape...
// TypeScript INSTANTLY errors:
// Type '"triangle"' is not assignable to type 'never'.
// You're forced to add the triangle case! Future-proof!

⚠️ Common Mistakes

Mistake 1: Narrowing Lost in Callbacks

function processValue(value: string | number) {
  if (typeof value === "string") {
    // ✅ value is string here...
    setTimeout(() => {
      value.toUpperCase(); // ❌ ERROR! Narrowing lost!
      // TS can't guarantee value wasn't reassigned by the callback time
    }, 100);
  }
}

Mistake 2: Using = instead of === in guards

// ❌ Single = is assignment, not comparison! No narrowing!
if (typeof value = "string") { // Syntax error!

// ✅ Always use ===
if (typeof value === "string") { // Perfect!

✅ Best Practices

1. Always use discriminated unions for state management (loading/success/error).
2. Always add the exhaustive never check in switch statements over unions.
3. Extract complex checks into type predicates (function isCat(x): x is Cat).
4. Use !== null instead of typeof !== "object" to check for null.
5. Assign narrowed values to const before using in closures.

🏗️ Senior Deep Dive

Control Flow Analysis Internals

TypeScript's narrowing is powered by Control Flow Analysis (CFA). The compiler builds a graph of your code's execution paths. At each node, it computes the "reachable type"—which union members could possibly reach that point. When you write if (typeof x === "string") return;, the code after the if can only be reached by non-strings, so TypeScript eliminates string from the union there.

This is why narrowing sometimes "fails" in async callbacks: TypeScript can't know when the callback runs relative to other code, so it conservatively widens the type back.

Assertion Functions

A lesser-known alternative to type predicates—assertion functions:

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new Error("Not a string!");
  }
}

function process(input: unknown) {
  assertIsString(input);
  input.toUpperCase(); // ✅ TS knows it's a string now!
}

💼 Interview Questions

🏋️ Practical Exercise

type ApiResponse =
  | { success: true; data: string[] }
  | { success: false; error: string };

// Write this function using the 'is' keyword
function isSuccessResponse(resp: ApiResponse): /* ??? */ {
  // Your implementation here
}

📝 Quiz

📦 Summary