Narrowing and type guards

Narrowing is the compiler following your control flow. After a check it understands, the type inside that branch is smaller than the declared one, and after an early return the rest of the function is smaller too.

function size(x: string | string[] | null): number {
  if (x === null) return 0;          // x: string | string[] below
  if (typeof x === "string") return x.length;
  return x.length;                   // x: string[]
}

The built-in checks: typeof (for primitives), instanceof (for classes, including Date and Error), in (does the object have this property), Array.isArray, and comparison with a literal or with null.

Your own guards

When the check is more than one expression, put it in a function whose return type is a type predicate, x is T. A true result then narrows at the call site exactly as typeof would:

1interface Cat { kind: "cat"; meows: boolean }2interface Robot { serial: string }3 4// A user-defined type guard: the return type says what a true result proves.5function isRobot(x: Cat | Robot): x is Robot {6  return "serial" in x;7}8 9function describe(value: Cat | Robot | Date | string[]): string {10  if (Array.isArray(value)) return `list of ${value.length}`;11  if (value instanceof Date) return `date ${value.toISOString().slice(0, 10)}`;12  if (isRobot(value)) return `robot ${value.serial}`;13  return value.meows ? "a cat that meows" : "a quiet cat";14}15 16export function run(): string[] {17  return [18    describe(["a", "b"]),19    describe(new Date(Date.UTC(2024, 0, 15))),20    describe({ serial: "R2" }),21    describe({ kind: "cat", meows: false }),22  ];23}

An assertion function is the throwing variant: asserts x is T means "if this returns at all, x is a T", so the code after the call is narrowed.

function assertIsString(x: unknown): asserts x is string {
  if (typeof x !== "string") throw new TypeError("expected a string");
}

The compiler trusts the predicate

A type guard's body is never compared with its return type. Write a guard that says x is string and returns true for numbers, and every caller narrows wrongly:

1// The compiler trusts a type guard's verdict. It never checks the body.2function isText(x: unknown): x is string {3  return x !== null;   // wrong: lets numbers through4}5 6function shout(x: unknown): string {7  if (isText(x)) return x.toUpperCase();8  return "not text";9}10 11export function run(): string[] {12  const out: string[] = [];13  for (const v of ["hi", null, 42]) {14    try {15      out.push(shout(v));16    } catch (e) {17      out.push(String(e));18    }19  }20  return out;21}

So a guard is a small piece of code that deserves its own tests: it is the one place where a mistake silently switches the checker off for everything downstream.

Truthiness is a blunt check

if (value) narrows away null and undefined, but also 0, "", false and NaN, which are often real values:

1function label(count: number | undefined): string {2  if (count) return `${count} items`;   // 0 is falsy, so it lands below3  return "count unknown";4}5 6function labelFixed(count: number | undefined): string {7  if (count !== undefined) return `${count} items`;8  return "count unknown";9}10 11export function run(): string[] {12  return [label(3), label(0), labelFixed(0), labelFixed(undefined)];13}

Compare against what you actually mean to exclude: !== undefined, !== null, or != null for both.

Common mistakes

• typeof x === "object" as an object check. typeof null is also "object", so "price" in x on a null throws a TypeError. Check x !== null first.
• A guard that checks too little. "price" in x proves the key exists, not that its value is a number; { price: "5" } passes and + concatenates.
• Truthiness where 0 or "" is valid. Shown above: label(0) says "count unknown".
• Narrowing lost in a callback. A narrowed property (order.note), or a let that is assigned again later, is not narrowed inside a callback, because by the time the callback runs the value may have changed. Copy it into a first.