Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

instanceof type guards in TypeScript

Reference for instanceof narrowing in TypeScript: classes, built-ins like Date and Error, the prototype chain, structural typing surprises and custom Symbol.hasInstance.

value instanceof Constructor is true when Constructor.prototype appears in the prototype chain of value. TypeScript uses it as a type guard: in the true branch the value is narrowed to the instance type of the constructor, and in the false branch that type is removed from a union.

It works with your own classes and with built-ins such as Date, Error, Map, RegExp and Promise. It does not work with interfaces or type aliases, which do not exist at run time.

TypeScript
function format(x: Date | string): string {
  return x instanceof Date ? x.toISOString() : x.trim();
}

Try it

TypeScript Narrowing a union of classes

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 Errors in a catch clause

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 Structural typing can surprise you

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
value instanceof Constructor
Part Description
value An expression of type any, an object type or a type parameter. Primitives on the left are an error (TS2358).
Constructor An expression whose type is any or has a construct signature or a prototype property.
Result boolean; a type guard for the instance type.

Edge cases:

  • If the constructor's prototype property is any, narrowing falls back to the declared constructor type.
  • With generic classes the narrowed type uses any for type arguments unless the original value already carried them.
  • An object created across realms (iframes, workers) fails instanceof for built-ins because each realm has its own constructors.

Usage notes

  • Structural typing. Narrowing considers shapes: two classes with identical members are interchangeable to the compiler, but instanceof differs at run time. The third example shows the effect: a plain object with the right shape type-checks as a class instance but fails the run-time test. Give classes a distinguishing member (a private field or a tag) when it matters.
  • Interfaces are invisible at run time. You cannot write x instanceof SomeInterface. Use in, a tag field or a custom guard.
  • Subclasses. err instanceof Error is true for every subclass too, so check the most specific class first.
  • Symbol.hasInstance. A class can customize the test with a static [Symbol.hasInstance] method. The compiler still narrows to the instance type.
  • Cross-realm built-ins. For arrays use Array.isArray, which also works across realms.
  • Primitives. "x" instanceof String is false, since a primitive string is not a String object. Use typeof.