TypeScript instanceof: Klassen und Errors einengen

value instanceof SomeClass ist eine JavaScript-Prüfung, die zur Laufzeit läuft: Sie ist true, wenn SomeClass.prototype in der Prototypkette des Objekts liegt, das Objekt also mit new SomeClass (oder einer Unterklasse) erzeugt wurde. TypeScript engt value innerhalb der Prüfung auf SomeClass ein.

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

Nimm instanceof für Objekte aus Klassen und typeof für primitive Werte. Hier braucht es beides: instanceof trennt das Date ab, dann teilt typeof den Rest auf.

Eigene Klassen einengen

instanceof engt im Zweig true auf die Klasse ein und entfernt sie im Zweig false, eine Union aus Klassen lässt sich also Member für Member behandeln.

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

Eine Instanz einer Unterklasse besteht auch die Prüfung auf ihre Elternklasse: Wenn Square extends Rect gilt, ist new Square(2) instanceof Rect gleich true. Prüfe die spezifischste Klasse zuerst, wenn sich die Zweige unterscheiden.

Error-Unterklassen in catch

Am häufigsten wird instanceof in catch verwendet. Unter strict ist der gefangene Wert unknown (alles kann geworfen werden), und mit instanceof kommst du zu einem typisierten Fehler zurück.

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);
    }
  }
}

Ausgabe:

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

class X extends Error funktioniert mit instanceof auf jedem Target, das TypeScript 7 unterstützt (ES2015 und neuer). Der ältere Rat, im Konstruktor Object.setPrototypeOf(this, X.prototype) aufzurufen, galt für Code, der nach ES5 kompiliert wurde, ein Target, das TypeScript 7 entfernt hat.

instanceof funktioniert nicht mit Interfaces oder Typen

Interfaces und Typaliasse existieren nur für den Compiler. Nach dem Kompilieren gibt es keinen Wert User, mit dem verglichen werden könnte, also verweigert TypeScript die Prüfung:

// 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" }));

Der Compiler meldet index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Es gibt zwei Lösungen. Prüfe die Form selbst mit einem Type Guard, einer Funktion, die value is User zurückgibt:

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

Oder, wenn dein Code diese Objekte erzeugt, mach User zu einer Klasse und erzeuge die Objekte mit new; dann funktioniert instanceof. Die Seite zu Type Guards behandelt Predicates und Assertion-Funktionen im Detail.

Der richtige Typ ist nicht die richtige Instanz

TypeScript vergleicht Typen nach ihrer Struktur: Ein Objektliteral mit denselben Membern wie eine Klasse ist dem Klassentyp zuweisbar. instanceof schaut nicht auf die Struktur. Es durchläuft die Prototypkette, und ein Objekt, das nie mit new erzeugt wurde, besteht die Prüfung nicht, auch wenn der Compiler es als diesen Typ akzeptiert.

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

Die letzte Zeile ist wichtig. structuredClone, JSON.parse(JSON.stringify(...)) und Nachrichten zwischen Workern liefern alle einfache Objekte ohne den Prototyp der Klasse, auch wenn ihr statischer Typ weiterhin Point sagen kann. Wenn Klasseninstanzen eine solche Grenze überqueren, baue sie neu (new Point(copy.x, copy.y)), bevor du dich auf instanceof oder auf Methoden verlässt.

instanceof und primitive Werte

Primitive Werte (string, number, boolean...) sind keine Objekte und haben keine Prototypkette, daher ist "hi" instanceof String gleich false. TypeScript markiert den Fehler, wenn es kann: Mit einem als string typisierten Wert auf der linken Seite ist instanceof der Fehler TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Nimm für primitive Werte typeof.

Werte aus anderen Realms

instanceof vergleicht mit einem bestimmten Konstruktorobjekt. Code in einem anderen Realm (einem iframe oder einem vm-Kontext in Node) hat eigene Array, Error und Date, ein dort erzeugtes Array besteht hier also instanceof Array nicht. Dasselbe passiert, wenn zwei Kopien eines npm-Pakets in node_modules landen: Jede Kopie hat ihre eigene Klasse, und eine Instanz der einen besteht instanceof gegen die andere nicht. Für Arrays funktioniert Array.isArray über Realms hinweg. Für deine eigenen Typen vermeidet eine Prüfung auf eine Eigenschaft (ein Type Guard oder ein Feld kind) das Problem ganz.