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.
function when(v: Date | string): string { return v instanceof Date ? v.toISOString() : v; }
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.
Syntax
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
instanceofmust be of typeany, an object type or a type parameter; a plainstringornumberis 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 Numberisfalse. - Objects from another realm (an iframe, a
vmcontext) have different constructors, soinstanceof Arraymay fail; useArray.isArray. Symbol.hasInstancecan override the logic, and TypeScript honors a type predicate on it for narrowing.
Usage notes
instanceofchecks 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 Erroris true. Check the most specific class first. - Caught errors are
unknownunderuseUnknownInCatchVariables(part ofstrict); narrow withinstanceof Error. - For interfaces or plain-object unions, use
in, a discriminant property or a type guard function instead.