Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

The instanceof operator

Reference for instanceof in TypeScript: how it checks the prototype chain, narrows unions of classes, handles errors, and where it can fail.

value instanceof Constructor is true when Constructor.prototype appears in the prototype chain of value. TypeScript uses that test to narrow the type of the left operand: inside the true branch it becomes the instance type of the constructor, and in the false branch the matching union members are removed.

It is the standard way to tell class instances apart, to narrow unknown caught errors to Error, and to distinguish built-ins such as Date, Map or RegExp.

TypeScript
function when(v: Date | string): string {
  return v instanceof Date ? v.toISOString() : v;
}

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 Custom errors and the structural trap

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
Left operand An expression of type any, an object type, or a type parameter. Primitives on the left are a compile error.
Right operand A value of type any or a type that has a construct signature (or a function type with a prototype).
Result boolean. In a condition it narrows the left operand.

Edge cases and errors:

  • The left side of instanceof must be of type any, an object type or a type parameter; a plain string or number is error TS2358.
  • The right side must be a constructor or function; a plain object or interface is error TS2359.
  • A primitive at run time is never an instance of its wrapper class: 5 instanceof Number is false.
  • Objects from another realm (an iframe, a vm context) have different constructors, so instanceof Array may fail; use Array.isArray.
  • Symbol.hasInstance can override the logic, and TypeScript honors a type predicate on it for narrowing.

Usage notes

  • instanceof checks nominal prototype identity at run time, while TypeScript's type system is structural. A plain object with the same shape as a class is assignable to it but is not an instance of it.
  • When narrowing in the false branch, TypeScript removes only the members that are subtypes of the class, so structurally similar classes can narrow oddly. Give classes distinct members or a discriminant.
  • Subclasses pass for their parents: new HttpError() instanceof Error is true. Check the most specific class first.
  • Caught errors are unknown under useUnknownInCatchVariables (part of strict); narrow with instanceof Error.
  • For interfaces or plain-object unions, use in, a discriminant property or a type guard function instead.