TypeScript Reference ยท Narrowing and Type Guards
typeof type guards in TypeScript
Reference for typeof type guards in TypeScript: which strings it returns, how it narrows unions of primitives, the null quirk, functions and objects.
The typeof operator returns a string naming the runtime kind of a value. When you compare that result to a string literal in an if, switch or ternary, TypeScript narrows the variable's type inside the matching branch. It is the simplest and most common type guard.
TypeScript understands exactly these results: "string", "number", "bigint", "boolean", "symbol", "undefined", "object" and "function". Comparing against any other string is an error, which catches typos.
function show(x: string | number) { if (typeof x === "string") { return x.toUpperCase(); // x: string } return x.toFixed(1); // x: number }
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
typeof expr === "string" typeof expr !== "number" switch (typeof expr) { case "string": ... }
| Result string | Narrows to |
|---|---|
"string" |
string (and string literal types) |
"number" |
number (and number literal types) |
"bigint" |
bigint |
"boolean" |
boolean |
"symbol" |
symbol |
"undefined" |
undefined |
"function" |
Callable members of the union |
"object" |
Object types and null |
Edge cases:
typeof nullis"object", so an"object"branch includesnullunless you also check for it.- In the type position,
typeof xmeans something different: it gives the compile-time type of a value (see the typeof type operator). - Comparing against an invalid string gives TS2367 ("This comparison appears to be unintentional because the types ... have no overlap"), as the last example shows.
Usage notes
unknownis the classic use. Narrowingunknownwithtypeofis how you safely read values from JSON, events and catch clauses.- Both branches narrow. In the
elsebranch the checked kind is removed from the union, so a chain ofifstatements ends with the remaining members. - Arrays are objects.
typeof [] === "object". To detect arrays useArray.isArray. - Classes and interfaces.
typeofcannot tell two object types apart. Usein,instanceofor a discriminant field. - Aliased reads. Narrowing applies to references (variables, properties and parameters), not to the result stored in a variable, unless it is a
constcondition. See aliased conditions. switch (typeof x)narrows in eachcase, and exhaustiveness works like any other switch.- Version note.
"bigint"and"symbol"results are recognized in all current versions of TypeScript.