Instanceof в TypeScript: сужение классов и ошибок

value instanceof SomeClass это проверка JavaScript, которая выполняется во время работы программы: она истинна, когда SomeClass.prototype есть в цепочке прототипов объекта, то есть когда объект создан через new SomeClass (или подкласс). TypeScript сужает value до 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

Используйте instanceof для объектов, созданных из классов, и typeof для примитивов. Здесь нужны оба: instanceof отделяет Date, а затем typeof делит то, что осталось.

Сужение ваших собственных классов

instanceof сужает до класса в ветке true и убирает его в ветке false, поэтому объединение классов можно обрабатывать по одному члену за раз.

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

Экземпляр подкласса тоже проходит проверку на родительский класс: если Square extends Rect, то new Square(2) instanceof Rect равно true. Если ветки различаются, проверяйте самый конкретный класс первым.

Подклассы Error в catch

Чаще всего instanceof используют в catch. В режиме strict пойманное значение имеет тип unknown (бросить можно что угодно), и instanceof позволяет вернуться к типизированной ошибке.

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

Вывод:

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

class X extends Error работает с instanceof на любом target, который поддерживает TypeScript 7 (ES2015 и новее). Старый совет вызывать Object.setPrototypeOf(this, X.prototype) в конструкторе относился к коду, скомпилированному в ES5, а этот target в TypeScript 7 удалён.

instanceof не работает с интерфейсами и типами

Интерфейсы и псевдонимы типов существуют только для компилятора. После компиляции значения User, с которым можно сравнить, нет, поэтому TypeScript отказывается выполнять проверку:

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

Компилятор сообщает index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Исправить можно двумя способами. Проверить форму самостоятельно защитником типа, функцией, которая возвращает 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

Или, если эти объекты создаёт ваш код, сделать User классом и создавать объекты через new; тогда instanceof работает. Предикаты и функции утверждения подробно описаны на странице защитники типов.

Правильный тип ещё не правильный экземпляр

TypeScript сравнивает типы по структуре: объектный литерал с теми же членами, что и у класса, можно присвоить типу класса. instanceof на структуру не смотрит. Он проходит по цепочке прототипов, и объект, который никогда не создавался через new, не проходит проверку, даже если компилятор принимает его как этот тип.

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

Важна последняя строка. structuredClone, JSON.parse(JSON.stringify(...)) и сообщения между воркерами возвращают обычные объекты без прототипа класса, хотя их статический тип всё ещё может говорить Point. Когда экземпляры классов пересекают такую границу, пересоздайте их (new Point(copy.x, copy.y)), прежде чем полагаться на instanceof или методы.

instanceof и примитивы

Примитивы (string, number, boolean...) не являются объектами и не имеют цепочки прототипов, поэтому "hi" instanceof String равно false. TypeScript отмечает ошибку, когда может: если слева значение типа string, instanceof даёт ошибку TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Для примитивов используйте typeof.

Значения из другого realm

instanceof сравнивает с одним конкретным объектом-конструктором. У кода, который выполняется в другом realm (iframe или контексте vm в Node), свои Array, Error и Date, поэтому массив, созданный там, не проходит здесь instanceof Array. То же случается, когда в node_modules оказываются две копии одного npm-пакета: у каждой копии свой класс, и экземпляр из одной не проходит instanceof против другой. Для массивов Array.isArray работает между realm. Для ваших собственных типов проверка свойства (защитник типа или поле kind) полностью снимает проблему.