instanceof en TypeScript : affiner les classes et les erreurs

value instanceof SomeClass est une vérification JavaScript qui s'exécute : elle vaut true quand SomeClass.prototype se trouve dans la chaîne de prototypes de l'objet, c'est-à-dire quand l'objet a été créé avec new SomeClass (ou une sous-classe). TypeScript affine value en SomeClass à l'intérieur de la vérification.

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

Utilisez instanceof pour les objets créés à partir de classes, et typeof pour les primitives. Ici, les deux sont nécessaires : instanceof isole le Date, puis typeof sépare ce qui reste.

Affiner vos propres classes

instanceof affine vers la classe dans la branche true et la retire dans la branche false : une union de classes peut donc être traitée membre par membre.

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

Une instance de sous-classe passe aussi la vérification de son parent : si Square extends Rect, alors new Square(2) instanceof Rect vaut true. Testez d'abord la classe la plus précise quand les branches diffèrent.

Les sous-classes d'Error dans catch

L'usage le plus courant d'instanceof se trouve dans catch. Avec strict, la valeur capturée est unknown (on peut lever n'importe quoi), et instanceof est le moyen de retrouver une erreur typée.

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

Sortie :

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

class X extends Error fonctionne avec instanceof sur toutes les cibles que prend en charge TypeScript 7 (ES2015 et ultérieures). L'ancien conseil d'appeler Object.setPrototypeOf(this, X.prototype) dans le constructeur s'appliquait au code compilé en ES5, une cible que TypeScript 7 a supprimée.

instanceof ne fonctionne pas avec les interfaces ni les types

Les interfaces et les alias de type n'existent que pour le compilateur. Après la compilation, il n'y a aucune valeur User à laquelle comparer, TypeScript refuse donc la vérification :

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

Le compilateur signale index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Il y a deux corrections. Vérifiez vous-même la forme avec un type guard, une fonction qui renvoie 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, si votre code crée ces objets, faites de User une classe et construisez-les avec new ; instanceof fonctionne alors. La page type guards présente en détail les prédicats et les fonctions d'assertion.

Le bon type n'est pas la bonne instance

TypeScript compare les types par leur structure : un littéral objet qui a les mêmes membres qu'une classe est assignable au type de cette classe. instanceof ne regarde pas la structure. Il parcourt la chaîne de prototypes, et un objet qui n'a jamais été créé avec new échoue même si le compilateur l'accepte comme ce type.

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 dernière ligne compte. structuredClone, JSON.parse(JSON.stringify(...)) et les messages entre workers renvoient tous des objets simples sans le prototype de la classe, même si leur type statique peut encore indiquer Point. Quand des instances de classes franchissent une telle frontière, reconstruisez-les (new Point(copy.x, copy.y)) avant de compter sur instanceof ou sur les méthodes.

instanceof et les primitives

Les primitives (string, number, boolean...) ne sont pas des objets et n'ont pas de chaîne de prototypes : "hi" instanceof String vaut donc false. TypeScript signale l'erreur quand il le peut : avec une valeur typée string à gauche, instanceof provoque l'erreur TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Utilisez typeof pour les primitives.

Valeurs venues d'un autre realm

instanceof compare à un objet constructeur précis. Du code exécuté dans un autre realm (une iframe, ou un contexte vm de Node) a ses propres Array, Error et Date : un tableau créé là-bas échoue donc à instanceof Array ici. La même chose se produit quand deux copies d'un même paquet npm se retrouvent dans node_modules : chaque copie a sa propre classe, et une instance de l'une échoue à instanceof face à l'autre. Pour les tableaux, Array.isArray fonctionne d'un realm à l'autre. Pour vos propres types, vérifier une propriété (un type guard, ou un champ kind) évite complètement le problème.