instanceof em TypeScript: narrowing de classes e erros

value instanceof SomeClass é uma verificação do JavaScript que roda em tempo de execução: é true quando SomeClass.prototype está na cadeia de protótipos do objeto, o que significa que o objeto foi criado com new SomeClass (ou com uma subclasse). O TypeScript estreita value para SomeClass dentro da verificação.

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 para objetos criados a partir de classes, e typeof para primitivos. Aqui os dois são necessários: o instanceof separa o Date, e depois o typeof divide o que sobra.

Narrowing das suas próprias classes

O instanceof estreita para a classe no ramo true e a remove no ramo false, então uma union de classes pode ser tratada um membro por vez.

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

Uma instância de subclasse também passa na verificação da classe pai: se Square extends Rect, então new Square(2) instanceof Rect é true. Teste primeiro a classe mais específica quando os ramos são diferentes.

Subclasses de Error no catch

O uso mais comum do instanceof é no catch. Com strict, o valor capturado é unknown (qualquer coisa pode ser lançada), e o instanceof é como você volta a ter um erro tipado.

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

Saída:

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

class X extends Error funciona com instanceof em todo target que o TypeScript 7 suporta (ES2015 e posteriores). O conselho antigo de chamar Object.setPrototypeOf(this, X.prototype) no construtor valia para código compilado para ES5, um target que o TypeScript 7 removeu.

instanceof não funciona com interfaces nem types

Interfaces e type aliases existem só para o compilador. Depois da compilação não há nenhum valor User para comparar, então o TypeScript recusa a verificação:

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

O compilador mostra index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Há duas soluções. Verifique você mesmo o formato com um type guard, uma função que retorna 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

Ou, se é o seu código que cria esses objetos, transforme User em uma classe e crie-os com new; aí o instanceof funciona. A página sobre type guards trata de predicates e assertion functions em detalhe.

O tipo certo não é a instância certa

O TypeScript compara tipos pela estrutura: um objeto literal com os mesmos membros de uma classe pode ser atribuído ao tipo da classe. O instanceof não olha a estrutura. Ele percorre a cadeia de protótipos, e um objeto que nunca foi criado com new falha na verificação mesmo quando o compilador o aceita como aquele tipo.

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

A última linha importa. structuredClone, JSON.parse(JSON.stringify(...)) e mensagens entre workers retornam objetos simples sem o protótipo da classe, mesmo que o tipo estático deles ainda diga Point. Quando instâncias de classes atravessam uma fronteira dessas, reconstrua-as (new Point(copy.x, copy.y)) antes de depender do instanceof ou dos métodos.

instanceof e primitivos

Primitivos (string, number, boolean...) não são objetos e não têm cadeia de protótipos, então "hi" instanceof String é false. O TypeScript aponta o erro quando consegue: com um valor tipado como string do lado esquerdo, o instanceof gera o erro TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Use typeof para primitivos.

Valores de outro realm

O instanceof compara com um objeto construtor específico. Código rodando em outro realm (um iframe, ou um contexto vm do Node) tem o próprio Array, Error e Date, então um array criado lá falha em instanceof Array aqui. O mesmo acontece quando duas cópias de um mesmo pacote npm acabam no node_modules: cada cópia tem a própria classe, e uma instância de uma falha no instanceof contra a outra. Para arrays, Array.isArray funciona entre realms. Para os seus próprios tipos, verificar uma propriedade (um type guard, ou um campo kind) evita o problema por completo.