TypeScript instanceof：类与 Error 的类型收窄

value instanceof SomeClass 是一个在运行时执行的 JavaScript 检查：当 SomeClass.prototype 位于对象的原型链上时，它返回 true，也就是说这个对象是用 new SomeClass（或其子类）创建的。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（什么都可能被抛出），而 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

在 TypeScript 7 支持的所有编译目标（ES2015 及以后）上，class X extends Error 都能配合 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. 有两种修复方法。一是用类型守卫自己检查结构，也就是一个返回 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

二是如果这些对象由你的代码创建，就把 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(...)) 以及 worker 之间传递的消息，返回的都是不带类原型的普通对象，尽管它们的静态类型仍然可以写作 Point。类实例跨越这样的边界后，要先重新构建（new Point(copy.x, copy.y)），再依赖 instanceof 或调用方法。

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。

跨 realm 的值

instanceof 比较的是某一个特定的构造函数对象。在另一个 realm（iframe 或 Node 的 vm 上下文）中运行的代码有自己的 Array、Error 和 Date，所以在那里创建的数组，在这里通不过 instanceof Array。同一个 npm 包的两份副本同时出现在 node_modules 中时也会这样：每份副本都有自己的类，一份的实例对另一份做 instanceof 检查会失败。对数组来说，Array.isArray 可以跨 realm 使用。对你自己的类型，检查某个属性（类型守卫，或一个 kind 字段）可以彻底避开这个问题。