Narrowing

The point of unions is narrowing

A union is only useful because you can narrow it. TypeScript reads your control flow — if, switch, typeof, return — and shrinks the type within each branch to the case that must be true there. This is control-flow analysis, and it’s one of the smartest parts of the compiler.

function printId(id: string | number) {
  if (typeof id === "string") {
    id.toUpperCase(); // ✅ here id is string
  } else {
    id.toFixed(2);    // ✅ here id is number
  }
}

Inside the if, the type is string; the else branch removes string from the union, leaving number. You didn’t cast anything — the compiler narrowed based on a real runtime check it understands.

The built-in narrowing operators

TypeScript understands several ordinary JavaScript checks and narrows from them:

• typeof x — narrows primitives: "string", "number", "boolean", "object", "function", "undefined", "symbol", "bigint".
• instanceof — narrows to a class from its prototype chain.
• "key" in obj — narrows object unions by presence of a property.
• Truthiness — if (x) removes null, undefined, 0, "", false from the possibilities.
• Equality — if (x === "a") narrows to that literal; comparing two variables narrows both.

interface Circle { kind: "circle"; radius: number }
interface Square { kind: "square"; side: number }

function area(shape: Circle | Square) {
  if ("radius" in shape) {
    return Math.PI * shape.radius ** 2; // shape is Circle
  }
  return shape.side ** 2;               // shape is Square
}

in with optional properties

in narrows by which members of the union declare the property at all — not by whether the property is currently present at runtime. That means it works even when the property is optional, as long as only one side of the union declares it:

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

function speak(pet: Cat | Dog) {
  if ("leash" in pet) {
    pet.bark(); // pet narrowed to Dog -- because only Dog even declares leash
  }
}

This narrows to Dog even for a Dog whose leash is currently undefined — in checks the type’s declared shape, and only Dog has a leash key at all, optional or not. If both members declared the same optional property, in alone couldn’t distinguish them and you’d need a real discriminant.

Equality narrowing between two variables

Comparing two variables with === narrows both of them to whatever they have in common — not just one side to a literal:

function compare(a: string | number, b: string | boolean) {
  if (a === b) {
    // only string is common to both unions -- narrows both to string
    a.toUpperCase();
    b.toUpperCase();
  }
}

Neither a nor b is a literal here, so this isn’t the if (x === "a") case — the compiler reasons that a === b can only be true if both hold a value from the intersection of their possible types, string. Both variables narrow together inside the if, even though neither was compared against a fixed value.

Discriminated unions: the pattern to reach for

The cleanest way to model “one of several object shapes” is a discriminated union: every member shares a common literal field (the discriminant or tag), and switching on that field narrows to the right member.

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

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2; // s is the circle member
    case "square": return s.side ** 2;
    case "rect":   return s.width * s.height;
  }
}

flowchart TB
  u["Shape (union)
circle | square | rect"] -->|switch on kind| c["kind === circle
→ radius available"]
  u --> sq["kind === square
→ side available"]
  u --> r["kind === rect
→ width, height available"]

A discriminant field narrows a union to one member

This pattern is everywhere: Redux actions, API responses, state machines, result types. When you find yourself reaching for a class hierarchy to model variants, a discriminated union is usually simpler and safer.

Exhaustiveness with never

Here’s the payoff. Add a default branch that assigns the value to never, and the compiler will error the day someone adds a new union member and forgets to handle it:

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

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2;
    case "square": return s.side ** 2;
    case "rect":   return s.width * s.height;
    default:
      const _exhaustive: never = s; // compiles now — every member is handled
      return _exhaustive;
      // add a new Shape member and this line starts erroring, pointing at the gap
  }
}

In the default, every known case has been narrowed away, so s is never. Add a "triangle" member and s is no longer never there — the assignment fails to compile, pointing you straight at the missing case. This turns “did I handle every variant?” from a code-review question into a compile error.

Custom type guards: x is T

When narrowing needs custom logic, write a type-guard function whose return type is a type predicate x is T:

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

function handle(v: unknown) {
  if (isString(v)) {
    v.toUpperCase(); // ✅ v narrowed to string by the guard
  }
}

The predicate is a promise to the compiler: “if this returns true, treat the argument as T.” It’s how you narrow unknown from external data, and how libraries expose validation that the type system trusts.

Type predicates can lie

That promise is never checked against the function’s body — the compiler trusts the signature, not the implementation. A type-guard function that lies compiles with zero errors:

function isString(x: unknown): x is string {
  return true; // lies -- always claims true, no real check
}

function shout(x: unknown) {
  if (isString(x)) {
    console.log(x.toUpperCase()); // trusted -- x is "string" here
  }
}

// @run
function isString(x: unknown): x is string {
  return true; // lies -- always claims true, no real check
}

function shout(x: unknown) {
  if (isString(x)) {
    console.log(x.toUpperCase()); // trusted -- x is "string" here
  }
}

shout(42); // not a string at all

Running it crashes exactly where the compiler said it was safe:

TypeError: x.toUpperCase is not a function

This is the sharpest version of the course’s core warning: any type annotation — including a predicate — is a claim, not a proof. A hand-written or AI-generated type guard is only as trustworthy as its actual logic; always read the body of a custom x is T function before trusting what it narrows to.

Assertion functions: asserts x is T

A cousin of the type guard is the assertion function, which throws instead of returning a boolean and narrows for the rest of the scope:

function assert(cond: unknown, msg: string): asserts cond {
  if (!cond) throw new Error(msg);
}

function use(v: string | null) {
  assert(v !== null, "v must be set");
  v.toUpperCase(); // ✅ v is string from here on — the assert removed null
}

After the call, the compiler knows the asserted condition held (or execution would have thrown), so it narrows accordingly. This is how assert-style helpers and Node’s assert give you type narrowing for free.

unknown in catch: narrowing an error before you can use it

Under strict (specifically useUnknownInCatchVariables, on by default since TypeScript 4.4 whenever strict is on), a caught exception is typed unknown, not any — because JavaScript lets you throw literally anything, so the compiler refuses to assume it has an Error’s shape:

// @expect-error TS18046
try {
  JSON.parse("{");
} catch (e) {
  console.log(e.message); // ❌ 'e' is of type 'unknown'.
}

Narrow it the same way you’d narrow any other unknown, most commonly with instanceof:

try {
  JSON.parse("{");
} catch (e) {
  if (e instanceof Error) {
    console.log(e.message); // ✅ narrowed from unknown
  }
}

This is a direct, everyday application of the module’s whole theme: catch hands you the widest possible type on purpose, and narrowing is what turns it back into something you can safely call .message on.

Inferred type predicates (TypeScript 5.5)

You no longer have to write x is T for the simplest guards. When a function returns a boolean that is about its parameter, TypeScript infers the predicate for you:

interface Bird { name: string }
declare const countries: string[];
declare const nationalBirds: Map<string, Bird>;

function isBirdReal(bird: Bird | undefined) {
  return bird !== undefined;
}
// inferred: (bird: Bird | undefined) => bird is Bird

const birds = countries
  .map((c) => nationalBirds.get(c))
  .filter((b) => b !== undefined);
//    ^? Bird[]   — was (Bird | undefined)[] before 5.5

The compiler infers a predicate only when all four hold: the function has no explicit return-type annotation, it has a single return (and no implicit undefined return), the returned boolean is tied to a narrowing check on the parameter, and the parameter is never reassigned. Anything fancier — multiple returns, checks on a property of a mutable variable — still needs the explicit x is T.

Narrowing that got smarter

Three newer refinements remove common “why won’t it narrow?” moments:

• switch (true) (5.3). Each case expression narrows as if it were an if:

  declare const x: unknown;
  
  switch (true) {
    case typeof x === "string": x.toUpperCase(); break;
    case x instanceof Date:     x.getTime();     break;
  }

• Closures after the last assignment (5.4). A const, or a let/parameter that is never reassigned afterwards, keeps its narrowed type inside callbacks created after the check:

  function getUrls(url: string | URL, names: string[]) {
    if (typeof url === "string") url = new URL(url);
    return names.map((n) => new URL(n, url)); // url: URL — no cast needed
  }

• Constant indexed access (5.5). obj[key] narrows when both obj and key are effectively const:

  function f(obj: Record<string, unknown>, key: string) {
    if (typeof obj[key] === "string") obj[key].toUpperCase(); // ✅
  }

Checks the compiler now refuses (TypeScript 5.6)

The flip side of narrowing: a condition that can never narrow is almost always a bug, and 5.6 makes several of them errors. A bare regex or arrow function in an if is always truthy; a ?? whose left side can never be nullish is unreachable:

// @expect-error TS2872 TS2869
if (/0x[0-9a-f]/) { }             // ❌ this kind of expression is always truthy
if ((x: number) => 0) { }         // ❌ (you meant x >= 0) — an arrow function is always truthy too

function f(value: number, max: number) {
  return value < max ?? 100;      // ❌ right operand of ?? is unreachable
}

Literal true, false, 0 and 1 stay allowed (while (true) is idiomatic). Regex literals are also syntax-checked since 5.5, so an unbalanced group or a backreference to a missing capture is a compile error, not a runtime surprise.

Narrowing limits: lost across a closure, optimistic across await

Narrowing is a property of the linear control-flow graph the compiler builds for one function body — and that graph has real edges it can’t see across.

Lost across a closure. Narrowing an object’s property doesn’t survive being read inside a nested function, because that function might run at any later time, after something else has mutated the property:

// @expect-error TS2339
interface State { id: string | number }
function handleState(state: State) {
  if (typeof state.id === "string") {
    setTimeout(() => {
      state.id.toUpperCase(); // property narrowing does not survive a closure
    }, 0);
  }
}

The fix is to capture the narrowed value into a local const before creating the closure — a const can never be reassigned, so its narrowed type is safe to carry into a nested function:

interface State { id: string | number }
function handleState(state: State) {
  if (typeof state.id === "string") {
    const id = state.id; // capture the narrowed value in a local const
    setTimeout(() => {
      id.toUpperCase(); // ✅ id is a const, never reassigned — narrowing survives
    }, 0);
  }
}

Optimistic across await. await doesn’t create a new function scope, so narrowing does survive it syntactically — but that’s actually unsound, because an awaited call can run arbitrary code that mutates the narrowed value while your function is suspended, and the compiler has no way to know:

// @run
interface State { id: string | number }

async function corrupt(state: State) {
  state.id = 42; // runs while the caller is suspended at its own await
}

async function run(state: State) {
  if (typeof state.id === "string") {
    await corrupt(state); // TS has no idea this mutates state.id
    console.log(state.id.toUpperCase()); // still typed string here -- but is it?
  }
}

run({ id: "abc" });

This compiles with zero errors — TypeScript has no interprocedural analysis, so it doesn’t know corrupt touches state.id at all, and keeps trusting the narrowing from before the await. Running it crashes:

TypeError: state.id.toUpperCase is not a function

The lesson generalizes: narrowing is only as reliable as the compiler’s certainty that nothing else ran in between. A closure might run later — narrowing loses on purpose, conservatively. An await runs now, in the same function, so narrowing optimistically survives — even though real code, including code you don’t control, gets a chance to invalidate it in between. Re-check (or re-narrow) any shared, mutable value immediately after an await, rather than trusting a check that happened before it.

Narrowing survives await, but it's optimistic

interface State { id: string | number }

async function corrupt(state: State) {
  state.id = 42; // runs while the caller is suspended at its own await
}

async function run(state: State) {
  if (typeof state.id === "string") {
    await corrupt(state); // TS has no idea this mutates state.id
    console.log(state.id.toUpperCase()); // still typed string here -- but is it?
  }
}

run({ id: "abc" });

Check types Run ▸ Open in TS Playground

Mental Model

flowchart TD
  check["A runtime check the compiler understands
(typeof, instanceof, in, equality, discriminant)"] --> cfa["Tracked in the linear control-flow graph
of THIS function body"]
  cfa --> same["Used later in the SAME graph
(if/else, switch, after an await)"] --> trusted["Narrowing holds"]
  cfa --> escapes["Read inside a NESTED function
(closure, setTimeout, event handler)"] --> lost["Narrowing lost -- could run any time"]
  guard["A custom function returning x is T"] --> sig["Compiler trusts the SIGNATURE"]
  sig -.->|"never checks"| body["...not the function body"]

Narrowing is a claim the compiler trusts, checked only where it can see

Every narrowing rule in this lesson is the compiler tracking one thing: a claim, and how far that claim can travel before something might invalidate it. A typeof check is a claim tracked precisely through the linear flow of one function. A type predicate is a claim the compiler takes on faith from a signature, never verified against the body. await doesn’t end the flow, so a claim survives it — optimistically, since real code ran in between. A closure begins a new flow that might execute at any time, so the compiler conservatively refuses to carry old claims into it. None of this is arbitrary: it’s exactly as much certainty as static analysis of one function body, read top to bottom, can actually offer.

Trade-offs

Technique	Benefit	Cost
Built-in operators (typeof, instanceof, in, equality)	Zero-cost, no custom code, compiler-verified against real checks	Only covers patterns the compiler recognizes natively
Discriminated union + exhaustive switch	New variant is a compile error until handled everywhere	Requires every variant to carry a shared literal tag up front
Custom type guard (x is T)	Encapsulates arbitrary validation logic behind a reusable check	The compiler trusts the signature, not the body — a wrong or incomplete guard compiles clean
Assertion function (asserts x is T)	Narrows for the rest of the scope, not just one branch	Same trust problem as a type guard, plus it throws instead of branching
Capturing into a const before a closure	Restores narrowing that a closure would otherwise lose	One extra local variable per narrowed value used in a callback

Common Misconceptions

• A function returning x is T is verified by the compiler to actually check what it claims. It isn’t — the predicate is trusted from the signature alone. A guard that returns true unconditionally, or checks the wrong thing, compiles with zero errors.
• Narrowing a variable before an await is still safe after it. It’s syntactically preserved, but not actually safe — the awaited operation can run code that mutates the value while your function is suspended, and the compiler can’t see that.
• Narrowing a variable before creating a closure survives inside that closure. It doesn’t, for property access — a closure might run at any later time, so the compiler drops the narrowing rather than risk it being stale. A const local captured beforehand is the fix.
• in only works when the property is actually present at runtime. It narrows based on which union member declares the property in its type, so it works even for a currently-undefined optional property, as long as only one member declares that key at all.

Reading AI-generated code

Before trusting generated narrowing logic, check for:

• A type-guard function (x is T) whose body checks something much weaker than what it claims — typeof x === "object" && x !== null returning x is { id: string; name: string } is a common shape, and it compiles with zero errors while claiming far more than it verified.
• A value narrowed before an await, then used immediately after without re-checking — especially if anything awaited could plausibly touch the same shared object or module-level state.
• A narrowed value read inside a setTimeout, event handler, or any other callback defined inside the narrowing branch — if it’s a property access (not a captured local), the type is likely wider there than the surrounding code implies.
• An assertion function or type guard used to validate data crossing a real boundary (parsed JSON, a fetch response) with a check that only confirms “is an object,” not the actual required shape.

🐛 Spot the bug

function isValidUser(x: unknown): x is { id: string; name: string } {
return typeof x === "object" && x !== null;
}

function greet(input: unknown) {
if (isValidUser(input)) {
  console.log(`Hello, ${input.name}`);
}
}

greet({ id: "1" });

Show the answer

This compiles with zero errors and does not crash — it just silently prints Hello, undefined. isValidUser claims the much stronger predicate x is { id: string; name: string }, but its body only checks “is a non-null object,” which { id: "1" } satisfies without ever having a name property. Because the compiler never checks a type guard’s body against its claimed predicate, greet trusts input.name is a string — it’s actually undefined, and template-literal interpolation happily stringifies that without throwing. The fix is to make the guard’s runtime check match its claim: typeof x === "object" && x !== null && "id" in x && "name" in x && typeof (x as any).name === "string", or use a real validation library that keeps the check and the type in sync.

🔷 The one-line takeaway

Narrowing is how a wide union becomes a usable specific type: the compiler reads control flow (typeof, instanceof, in, truthiness, equality) and shrinks the type per branch. Model variants as discriminated unions with a shared literal tag, switch on it, and add a never default for compile-time exhaustiveness. For custom logic, write type guards (x is T) or assertion functions (asserts x is T) that the compiler trusts.

What is control-flow narrowing?

A runtime performance optimization The compiler shrinking a union type within each branch based on checks like typeof and in A way to cast any to a specific type Deleting unused branches

What defines a discriminated union?

All members share a common literal tag field you can switch on All members are classes The members have no shared properties It uses intersection instead of union

How does assigning to never in a default branch help?

It speeds up the switch It forces a compile error if a new union member is added but not handled — exhaustiveness It logs an error at runtime It has no effect

What does a function returning x is string (a type predicate) do?

Returns the string value of x Tells the compiler that when it returns true, the argument can be treated as string Throws if x is not a string Converts x to a string

What does an assertion function asserts cond do after it is called?

Returns a boolean the caller checks Narrows the type for the rest of the scope, since execution would have thrown otherwise Nothing at compile time Runs only in tests

When does TypeScript 5.5+ infer a type predicate for a function that has no explicit x is T?

Whenever the function returns a boolean When it has no return annotation, a single return, the boolean is tied to a check on the parameter, and the parameter is never reassigned Only for arrow functions passed to filter Never — predicates must always be written out

Does this compile, and what happens when it runs?

function isString(x: unknown): x is string {
  return true;
}

function shout(x: unknown) {
  if (isString(x)) {
    console.log(x.toUpperCase());
  }
}

shout(42);

Compile error — the predicate must actually check typeof x === "string" Compiles fine, but throws at runtime -- the predicate is trusted from the signature, never checked against the body Compiles and runs fine -- isString always returns true so it is always safe Compile error -- unknown cannot be narrowed by a custom function

Does run compile, and is the narrowing after await corrupt(state) actually safe?

interface State { id: string | number }
async function corrupt(state: State) {
  state.id = 42;
}
async function run(state: State) {
  if (typeof state.id === "string") {
    await corrupt(state);
    state.id.toUpperCase();
  }
}

Does not compile -- await always clears narrowing Compiles, but the narrowing is unsound -- corrupt can mutate state.id while run is suspended, and the compiler has no way to know Compiles and is completely safe -- await preserves narrowing correctly Does not compile -- state.id cannot be reassigned inside corrupt

Submit

Mark as complete