instanceof w TypeScript: zawężanie klas i błędów

value instanceof SomeClass to sprawdzenie JavaScriptu wykonywane w czasie działania: daje true, gdy SomeClass.prototype jest w łańcuchu prototypów obiektu, czyli gdy obiekt został utworzony przez new SomeClass (albo przez podklasę). Wewnątrz sprawdzenia TypeScript zawęża value do SomeClass.

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

Używaj instanceof dla obiektów utworzonych z klas, a typeof dla prymitywów. Tutaj potrzebne są oba: instanceof wydziela Date, a potem typeof dzieli to, co zostało.

Zawężanie własnych klas

instanceof zawęża do klasy w gałęzi true i usuwa ją w gałęzi false, więc unię klas można obsłużyć po jednym członie naraz.

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

Instancja podklasy przechodzi też sprawdzenie dla klasy rodzica: jeśli Square extends Rect, to new Square(2) instanceof Rect daje true. Gdy gałęzie się różnią, najpierw sprawdzaj najbardziej konkretną klasę.

Podklasy Error w catch

Najczęściej instanceof pojawia się w catch. W trybie strict złapana wartość ma typ unknown (rzucić można cokolwiek), a instanceof pozwala wrócić do otypowanego błędu.

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

Wynik:

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

class X extends Error działa z instanceof na każdym targecie obsługiwanym przez TypeScript 7 (ES2015 i nowsze). Dawna rada, żeby w konstruktorze wywoływać Object.setPrototypeOf(this, X.prototype), dotyczyła kodu kompilowanego do ES5, a ten target TypeScript 7 usunął.

instanceof nie działa z interfejsami ani typami

Interfejsy i aliasy typów istnieją tylko dla kompilatora. Po kompilacji nie ma żadnej wartości User, z którą można porównać, więc TypeScript odrzuca takie sprawdzenie:

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

Kompilator zgłasza index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Są dwa rozwiązania. Możesz sam sprawdzić kształt za pomocą type guard, czyli funkcji, która zwraca 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

Albo, jeśli to twój kod tworzy te obiekty, zrób z User klasę i twórz je przez new; wtedy instanceof działa. Predykaty i funkcje asercji szczegółowo opisuje strona o type guards.

Właściwy typ to nie właściwa instancja

TypeScript porównuje typy według struktury: literał obiektowy z tymi samymi składowymi co klasa da się przypisać do typu tej klasy. instanceof nie patrzy na strukturę. Przechodzi po łańcuchu prototypów, a obiekt, który nigdy nie powstał przez new, nie przechodzi sprawdzenia, nawet gdy kompilator akceptuje go jako ten typ.

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

Ostatnia linia jest ważna. structuredClone, JSON.parse(JSON.stringify(...)) i komunikaty między workerami zwracają zwykłe obiekty bez prototypu klasy, choć ich typ statyczny nadal może mówić Point. Gdy instancje klas przekraczają taką granicę, odtwórz je (new Point(copy.x, copy.y)), zanim zaczniesz polegać na instanceof albo na metodach.

instanceof i prymitywy

Prymitywy (string, number, boolean...) nie są obiektami i nie mają łańcucha prototypów, więc "hi" instanceof String daje false. TypeScript wychwytuje ten błąd, gdy tylko może: gdy po lewej stronie stoi wartość typu string, instanceof to błąd TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Dla prymitywów używaj typeof.

Wartości z innego realmu

instanceof porównuje z jednym konkretnym obiektem konstruktora. Kod działający w innym realmie (iframe albo kontekst vm w Node) ma własne Array, Error i Date, więc tablica utworzona tam nie przechodzi tutaj instanceof Array. To samo dzieje się, gdy w node_modules trafią dwie kopie tego samego pakietu npm: każda kopia ma własną klasę, a instancja z jednej nie przechodzi instanceof względem drugiej. Dla tablic Array.isArray działa między realmami. Dla twoich własnych typów sprawdzanie właściwości (type guard albo pole kind) całkowicie omija ten problem.