TypeScriptのinstanceof: クラスとErrorの型の絞り込み

value instanceof SomeClass は実行時に動くJavaScriptのチェックです。オブジェクトのプロトタイプチェーンに SomeClass.prototype があるとき、つまりオブジェクトが new SomeClass（またはサブクラス）で作られたときに true になります。チェックの中では、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 です。ブランチの処理が違う場合は、いちばん具体的なクラスを先にチェックしましょう。

catch の中の Error サブクラス

instanceof がいちばんよく使われるのは catch の中です。strict のもとでは捕捉した値は unknown（何でも throw できるため）で、型付きのエラーに戻すには 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 は、TypeScript 7 がサポートするすべてのターゲット（ES2015 以降）で instanceof と一緒に使えます。コンストラクターで Object.setPrototypeOf(this, X.prototype) を呼ぶという古いアドバイスは、ES5 向けにコンパイルしたコードのためのもので、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. を報告します。直し方は2つあります。1つは、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

もう1つは、自分のコードでこれらのオブジェクトを作るなら、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 のままでも、クラスのプロトタイプを持たない普通のオブジェクトを返します。クラスのインスタンスがこうした境界を越えるときは、instanceof やメソッドに頼る前に作り直しましょう（new Point(copy.x, copy.y)）。

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 を使いましょう。

別のレルムの値

instanceof は特定の1つのコンストラクターオブジェクトと比較します。別のレルム（iframe や Node の vm コンテキスト）で動くコードは独自の Array、Error、Date を持っているので、そこで作った配列はこちらの instanceof Array に失敗します。同じ npm パッケージのコピーが node_modules に2つ入った場合も同じです。コピーごとにクラスが別なので、一方のインスタンスはもう一方に対する instanceof に失敗します。配列なら Array.isArray はレルムをまたいでも動きます。自作の型なら、プロパティをチェックする方法（型ガードや kind フィールド）でこの問題を完全に避けられます。