Что такое instanceof в TypeScript

Короткий ответ можно начать с главного: instanceof проверяет не название типа и не набор полей. Он проверяет прототипную цепочку объекта. Справа стоит класс или функция-конструктор, слева значение. Если Constructor.prototype найден в цепочке прототипов значения, результат будет true.

Для TypeScript здесь есть два важных вывода. Оператор реально выполняется в браузере или Node.js. А еще TypeScript умеет использовать результат проверки как type guard и сужает тип внутри ветки.

class NetworkError extends Error {
  status = 500;
}

function showError(error: unknown) {
  if (error instanceof NetworkError) {
    // error сужен до NetworkError
    return `Request failed with status ${error.status}`;
  }

  if (error instanceof Error) {
    return error.message;
  }

  return "Unknown error";
}

На практике используйте instanceof, когда у вас есть реальные классы и экземпляры. Не подменяйте им проверку любых TypeScript-типов.

В JavaScript объекты связаны с прототипами. Когда вы пишете value instanceof User, движок не сравнивает поля value с полями класса User. Он ищет User.prototype в цепочке прототипов value.

class User {
  constructor(public name: string) {}
}

const realUser = new User("Ann");
const plainUser = { name: "Ann" };

console.log(realUser instanceof User); // true
console.log(plainUser instanceof User); // false

Этот пример удобно привести на интервью. Объекты выглядят похоже по полям, но результат разный. Один создан через new User, а второй является обычным объектом.

Сильный ответ не заканчивается определением. Покажите, что выбираете проверку по источнику значения. Во frontend значения часто приходят из форм, API, localStorage, iframe и сторонних виджетов. Для них один и тот же инструмент не всегда подходит.

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

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

function handle(value: unknown) {
  // Плохой пример: User это не runtime-значение
  if (value instanceof User) {
    console.log(value.name);
  }
}

Такой код не скомпилируется, потому что User существует только как тип. Дальше выбор зависит от модели. Для union-состояния удобно добавить поле-дискриминатор. Для данных с сервера лучше написать проверку формы или использовать валидатор.

type LoadState =
  | { kind: "idle" }
  | { kind: "success"; user: { id: string; name: string } }
  | { kind: "error"; message: string };

function render(state: LoadState) {
  if (state.kind === "success") {
    return state.user.name;
  }

  if (state.kind === "error") {
    return state.message;
  }

  return "Loading";
}

Такой вариант проще поддерживать в UI. Состояние явно описано, TypeScript хорошо сужает тип, а проверка не зависит от прототипов.

Для строк, чисел и boolean обычно нужен typeof. Проверка через instanceof String или instanceof Number ищет объект-обертку, а не обычный примитив. В интерфейсе это может привести к плохому UX. Пользователь ввел нормальную строку, но код решил, что тип неверный.

const name = "Ann";

console.log(name instanceof String); // false
console.log(typeof name === "string"); // true

Для массивов часто лучше использовать Array.isArray. Это особенно полезно в браузере, где значение может прийти из другого окна или iframe. value instanceof Array привязан к конкретному конструктору Array, а Array.isArray проверяет массив надежнее.

С данными из API есть отдельная ловушка. После JSON.parse вы получаете plain object, а не экземпляр вашего класса. Даже если у объекта есть все нужные поля, payload instanceof User вернет false, пока вы явно не создадите new User(...).

class User {
  constructor(public id: string, public name: string) {}
}

const payload: unknown = JSON.parse(responseText);

// Плохой вариант: валидный ответ API уйдет в состояние ошибки,
// потому что payload не является экземпляром класса User.
if (payload instanceof User) {
  setUser(payload);
} else {
  setError("Bad response");
}

Безопаснее проверить форму ответа и отдельно решить, нужен ли вам экземпляр класса. Так UI не покажет ошибку только из-за того, что у объекта нет нужного прототипа.

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

if (isUserPayload(payload)) {
  setUser(new User(payload.id, payload.name));
} else {
  setError("Bad response");
}

Во frontend-коде instanceof чаще всего уместен для ошибок, классовых моделей и объектов, которые вы точно создали через new. Например, проверка error instanceof Error помогает безопасно достать message из unknown в обработчике запроса.

Но для ответов API, данных из форм и состояния React чаще лучше проверять форму данных. Иначе можно получить ветку, которая никогда не выполнится, лишний fallback, неверный текст ошибки или состояние UI, которое не соответствует реальным данным.