instanceof en TypeScript: estrechar clases y errores

value instanceof SomeClass es una comprobación de JavaScript que se ejecuta en tiempo de ejecución: es true cuando SomeClass.prototype está en la cadena de prototipos del objeto, lo que significa que el objeto se creó con new SomeClass (o con una subclase). TypeScript estrecha value a SomeClass dentro de la comprobación.

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

Usa instanceof para objetos creados a partir de clases, y typeof para primitivos. Aquí hacen falta los dos: instanceof separa el Date y luego typeof divide lo que queda.

Estrechar tus propias clases

instanceof estrecha a la clase en la rama true y la quita en la rama false, así que una unión de clases se puede manejar miembro a miembro.

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

Una instancia de una subclase también pasa la comprobación de su clase padre: si Square extends Rect, entonces new Square(2) instanceof Rect es true. Comprueba primero la clase más específica cuando las ramas son distintas.

Subclases de Error en catch

El uso más habitual de instanceof está en catch. Con strict, el valor capturado es unknown (se puede lanzar cualquier cosa), e instanceof es la forma de volver a un error 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);
    }
  }
}

Salida:

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

class X extends Error funciona con instanceof en todos los targets que admite TypeScript 7 (ES2015 y posteriores). El antiguo consejo de llamar a Object.setPrototypeOf(this, X.prototype) en el constructor se aplicaba al código compilado a ES5, un target que TypeScript 7 ha eliminado.

instanceof no funciona con interfaces ni con tipos

Las interfaces y los alias de tipo solo existen para el compilador. Después de compilar no hay ningún valor User con el que comparar, así que TypeScript rechaza la comprobación:

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

El compilador informa index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Hay dos soluciones. Comprueba tú la forma con un type guard, una función que devuelve 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

O, si es tu código el que crea estos objetos, convierte User en una clase y constrúyelos con new; así instanceof funciona. La página de type guards explica en detalle los predicados y las funciones de aserción.

El tipo correcto no es la instancia correcta

TypeScript compara los tipos por estructura: un objeto literal con los mismos miembros que una clase se puede asignar al tipo de esa clase. instanceof no mira la estructura. Recorre la cadena de prototipos, y un objeto que nunca se creó con new no la pasa aunque el compilador lo acepte como de ese 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

La última línea es importante. structuredClone, JSON.parse(JSON.stringify(...)) y los mensajes entre workers devuelven objetos normales sin el prototipo de la clase, aunque su tipo estático pueda seguir diciendo Point. Cuando instancias de clases cruzan una frontera así, reconstrúyelas (new Point(copy.x, copy.y)) antes de confiar en instanceof o en sus métodos.

instanceof y los primitivos

Los primitivos (string, number, boolean...) no son objetos y no tienen cadena de prototipos, así que "hi" instanceof String es false. TypeScript señala el error cuando puede: con un valor de tipo string a la izquierda, instanceof es el error TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Usa typeof para los primitivos.

Valores de otro realm

instanceof compara con un objeto constructor concreto. El código que se ejecuta en otro realm (un iframe, o un contexto vm de Node) tiene sus propios Array, Error y Date, así que un array creado allí no pasa instanceof Array aquí. Lo mismo pasa cuando acaban dos copias de un mismo paquete npm en node_modules: cada copia tiene su propia clase, y una instancia de una no pasa instanceof contra la otra. Para arrays, Array.isArray funciona entre realms. Para tus propios tipos, comprobar una propiedad (un type guard o un campo kind) evita el problema por completo.