Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
function show(x: string | number) {
  if (typeof x === "string") {
    return x.toUpperCase(); // x: string
  }
  return x.toFixed(1); // x: number
}

Try it

TypeScript Narrowing a union of primitives

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 The null quirk and functions

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 A misspelled typeof result is an error

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
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 null is "object", so an "object" branch includes null unless you also check for it.
  • In the type position, typeof x means 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

  • unknown is the classic use. Narrowing unknown with typeof is how you safely read values from JSON, events and catch clauses.
  • Both branches narrow. In the else branch the checked kind is removed from the union, so a chain of if statements ends with the remaining members.
  • Arrays are objects. typeof [] === "object". To detect arrays use Array.isArray.
  • Classes and interfaces. typeof cannot tell two object types apart. Use in, instanceof or 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 const condition. See aliased conditions.
  • switch (typeof x) narrows in each case, and exhaustiveness works like any other switch.
  • Version note. "bigint" and "symbol" results are recognized in all current versions of TypeScript.