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.
function f(x: "a" | "b" | undefined) { if (x === "a") { x; // "a" } else { x; // "b" | undefined } }
Try it
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.
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.
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
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
NaNnever narrows, andx === NaNis alwaysfalseat run time. - Narrowing by equality works on references (variables, parameters, property paths), including
this.xandobj.prop.
Usage notes
- Prefer
===. Loose==coerces types at run time (0 == ""is true). The one widely accepted use is== nullas 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 anunknownvalue to the literal"a", butx === someStringwith astringoperand narrows it tostring.- 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.