Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

Equality narrowing in TypeScript

Reference for equality narrowing in TypeScript: how ===, !==, == and switch narrow unions, literals, null and undefined, and what loose equality adds.

When you compare a value with === or !==, TypeScript narrows both sides to the types they could have in common. Comparing a union to a literal narrows it to that literal. Comparing two unions narrows each to the overlap. The !== form removes the compared type from the other branch.

Loose equality works too, with one useful special case: x == null is true for both null and undefined, so a single check removes both from the type. The same narrowing is applied by switch cases.

TypeScript
function f(x: "a" | "b" | undefined) {
  if (x === "a") {
    x; // "a"
  } else {
    x; // "b" | undefined
  }
}

Try it

TypeScript Narrowing to a literal and its complement

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Comparing two variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript x == null removes null and undefined

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
x === value     x !== value
x == value      x != value
x == null       x != null
switch (x) { case "a": ... }
Check Narrowing in the true branch
x === "a" x becomes "a" (if it was a possible member).
x !== "a" "a" is removed from x.
x === y Both become the intersection of their possible types.
x == null null | undefined only.
x != null null and undefined removed.
x === undefined undefined only.

Edge cases:

  • Comparing a value to a type it can never equal is error TS2367 (see TS2367).
  • Comparing with NaN never narrows, and x === NaN is always false at run time.
  • Narrowing by equality works on references (variables, parameters, property paths), including this.x and obj.prop.

Usage notes

  • Prefer ===. Loose == coerces types at run time (0 == "" is true). The one widely accepted use is == null as a shorthand for the two-value check.
  • Literal unions pair well with equality. Narrowing "a" | "b" by === is the basis of switch exhaustiveness.
  • Object identity. === between objects tests identity. It narrows by type only, so two different objects of one type narrow nothing new.
  • unknown. x === "a" narrows an unknown value to the literal "a", but x === someString with a string operand narrows it to string.
  • Enums. Comparing to an enum member narrows the same way; union enums (all members literal) behave like literal unions.
  • Mutation resets narrowing. Assigning to the variable or calling code that might change a property clears property-path narrowing.