Narrowing and control-flow analysis

The checker tracks a type per program point

A union variable does not have a single type throughout its scope. The checker walks the control-flow graph and, at each point, holds the narrowest type still consistent with the guards taken to reach that point. A guard splits the flow: the true branch carries one narrowing, the false branch carries the complement.

function format(x: string | number) {
  // x: string | number
  if (typeof x === "string") {
    x;
    // ^? (parameter) x: string
    return x.toUpperCase();
  }
  x;
  // ^? (parameter) x: number   — the complement of the string branch
  return x.toFixed(2);
}

The else (here the fall-through after return) gets number for free: the checker subtracts string from the union because that branch was already handled. This is why an early return inside a guard narrows the rest of the function.

The five everyday narrowing operators

type Val = string | number | boolean | null | string[];

function inspect(v: Val) {
  if (typeof v === "number") v;        // ^? number  (typeof guard)
  if (v === null) return;              // equality guard → below, v excludes null
  if (Array.isArray(v)) v;             // ^? string[]  (built-in guard)
  if (v) v;                            // ^? string | number | boolean | string[] (truthiness drops null)
}

The everyday tools, each narrowing in a slightly different way:

• typeof — splits on JS runtime type tags ("string", "number", "boolean", "object", "function", "undefined", "symbol", "bigint"). Note typeof null === "object", a JS quirk the checker respects.
• Truthiness — if (v) removes null, undefined, 0, "", false, NaN from the type. Great for string | null, dangerous for number | undefined (it also drops 0).
• Equality — ===/!== against a literal or null/undefined narrows both branches.
• in — if ("radius" in shape) narrows to the union members that declare that property. Structural, not nominal.
• instanceof — narrows to the class (and subclasses), using the prototype chain at runtime.

Assignment narrowing and the let/const difference

Assigning a value narrows the variable to the assigned value’s type from that point forward — but only as far as the declared type allows.

let s: string | number;
s = "hello";
s;
// ^? string   — assignment narrowed it
s.toUpperCase();   // OK here

declare function rand(): string | number;
s = rand();
s;
// ^? string | number   — re-widened to the declared type

const differs from let for literal inference, which feeds narrowing. A const binding to a literal gets the literal type; a let binding widens to the base type:

const dir = "up";
//    ^? "up"      — literal type, usable as a discriminant
let dir2 = "up";
//    ^? string    — widened, no longer a discriminant

This matters enormously for discriminated unions (next-but-one lesson): a discriminant read from a const keeps its literal type; copied into a let it widens and narrowing silently stops working.

Exhaustiveness with never

When you have narrowed away every member of a union, the remaining type is never. Assigning that to a never-typed variable turns “I forgot a case” into a compile error:

function area(s: { kind: "circle"; r: number } | { kind: "square"; side: number }): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.side ** 2;
    default: {
      const _exhaustive: never = s;
      // If a new variant is added, s is no longer never here →
      // Error: Type '{ kind: "triangle"; ... }' is not assignable to type 'never'.
      return _exhaustive;
    }
  }
}

This is the senior pattern for safe refactors: add a variant, and every unhandled switch lights up red. You will formalize it next.

Narrowing is lost across function boundaries

This is the pitfall that catches everyone. The checker assumes any function call between a guard and a use could have mutated a captured variable, so it discards the narrowing for variables it cannot prove are unaffected:

function handle(id: string | number) {
  if (typeof id === "string") {
    id;
    // ^? string
    setTimeout(() => {
      id;
      // ^? string | number   — re-widened inside the closure!
      // id.toUpperCase();  // Error: Property 'toUpperCase' does not exist on type 'number'.
    });
  }
}

The closure may run later, after id could (in principle) have been reassigned, so the checker conservatively re-widens it to the declared type. The same happens after an await, because control left and re-entered the function. The fixes: copy the narrowed value into a const before the boundary (const sid = id; while id is string), or make the captured binding a const so the checker knows it cannot be reassigned.

function handle(id: string | number) {
  if (typeof id === "string") {
    const sid = id;        // const captures the narrowed string
    setTimeout(() => sid.toUpperCase());  // OK — sid is string
  }
}