TypeScript instanceof: Narrowing Classes and Errors

value instanceof SomeClass is a JavaScript check that runs at run time: it is true when SomeClass.prototype is in the object's prototype chain, which means the object was created with new SomeClass (or a subclass). TypeScript narrows value to SomeClass inside the check.

function formatWhen(when: Date | string | number): string {
  if (when instanceof Date) {
    return when.toISOString().slice(0, 10); // when: Date
  }
  // when: string | number
  return typeof when === "number" ? new Date(when).toISOString().slice(0, 10) : when;
}

console.log(formatWhen(new Date("2024-03-15T10:30:00Z"))); // 2024-03-15
console.log(formatWhen(0));                                // 1970-01-01
console.log(formatWhen("tomorrow"));                       // tomorrow

Use instanceof for objects made from classes, and typeof for primitives. Here both are needed: instanceof separates the Date, then typeof splits what is left.

Narrowing Your Own Classes

instanceof narrows to the class in the true branch and removes it in the false branch, so a union of classes can be handled one member at a time.

class Circle {
  constructor(public radius: number) {}
}

class Rect {
  constructor(public width: number, public height: number) {}
}

function area(shape: Circle | Rect): number {
  if (shape instanceof Circle) {
    return Math.PI * shape.radius ** 2; // shape: Circle
  }
  return shape.width * shape.height;    // shape: Rect
}

console.log(area(new Circle(1)).toFixed(3)); // 3.142
console.log(area(new Rect(2, 5)));           // 10

A subclass instance also passes the check for its parent: if Square extends Rect, then new Square(2) instanceof Rect is true. Test the most specific class first when the branches differ.

Error Subclasses in catch

The most common use of instanceof is in catch. Under strict, the caught value is unknown (anything can be thrown), and instanceof is how you get back to a typed error.

class NotFoundError extends Error {
  constructor(public path: string) {
    super(`not found: ${path}`);
    this.name = "NotFoundError";
  }
}

function load(path: string): string {
  if (!path.startsWith("/")) throw new TypeError("path must be absolute");
  throw new NotFoundError(path);
}

for (const path of ["/missing.txt", "relative.txt"]) {
  try {
    load(path);
  } catch (err) {
    if (err instanceof NotFoundError) {
      console.log("404:", err.path);            // err: NotFoundError
    } else if (err instanceof Error) {
      console.log(err.name + ":", err.message); // err: Error
    } else {
      console.log("unknown throw", err);
    }
  }
}

Output:

404: /missing.txt
TypeError: path must be absolute

class X extends Error works with instanceof on every target TypeScript 7 supports (ES2015 and later). Older advice to call Object.setPrototypeOf(this, X.prototype) in the constructor applied to code compiled to ES5, a target TypeScript 7 has removed.

instanceof Does Not Work With Interfaces or Types

Interfaces and type aliases exist only for the compiler. After compilation there is no User value to compare against, so TypeScript refuses the check:

// This does not compile: User is an interface, and interfaces are erased.
interface User {
  name: string;
  email: string;
}

function greet(value: unknown): string {
  if (value instanceof User) {
    return "Hello, user";
  }
  return "Hello, stranger";
}

console.log(greet({ name: "Ada", email: "ada@example.com" }));

The compiler reports index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. There are two fixes. Check the shape yourself with a type guard, a function that returns value is User:

interface User {
  name: string;
  email: string;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "email" in value && typeof value.email === "string"
  );
}

function greet(value: unknown): string {
  return isUser(value) ? `Hello, ${value.name}` : "Hello, stranger";
}

console.log(greet({ name: "Ada", email: "ada@example.com" })); // Hello, Ada
console.log(greet({ name: "Ada" }));                            // Hello, stranger

Or, if your code creates these objects, make User a class and construct them with new; then instanceof works. The type guards page covers predicates and assertion functions in detail.

The Right Type Is Not the Right Instance

TypeScript compares types by structure: an object literal with the same members as a class is assignable to the class type. instanceof does not look at structure. It walks the prototype chain, and an object that was never created with new fails it even when the compiler accepts it as that type.

class Point {
  constructor(public x: number, public y: number) {}
  length(): number {
    return Math.hypot(this.x, this.y);
  }
}

const made = new Point(3, 4);
const literal: Point = { x: 3, y: 4, length: () => 5 }; // accepted: same shape
const copy = structuredClone(made);                      // typed Point, but a plain object

console.log(made instanceof Point);    // true
console.log(literal instanceof Point); // false
console.log(copy instanceof Point);    // false
console.log(typeof copy.length);       // undefined: the method did not survive

The last line matters. structuredClone, JSON.parse(JSON.stringify(...)) and messages between workers all return plain objects without the class prototype, even though their static type can still say Point. When class instances cross such a boundary, rebuild them (new Point(copy.x, copy.y)) before relying on instanceof or on methods.

instanceof and Primitives

Primitives (string, number, boolean...) are not objects and have no prototype chain, so "hi" instanceof String is false. TypeScript flags the mistake when it can: with a value typed string on the left, instanceof is error TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Use typeof for primitives.

Cross-Realm Values

instanceof compares against one specific constructor object. Code running in another realm (an iframe, or a Node vm context) has its own Array, Error and Date, so an array created there fails instanceof Array here. The same happens when two copies of one npm package end up in node_modules: each copy has its own class, and an instance from one fails instanceof against the other. For arrays, Array.isArray works across realms. For your own types, checking a property (a type guard, or a kind field) avoids the problem entirely.