instanceof trong TypeScript: thu hẹp kiểu lớp và lỗi

value instanceof SomeClass là một phép kiểm tra của JavaScript chạy lúc runtime: nó là true khi SomeClass.prototype nằm trong prototype chain của object, nghĩa là object được tạo bằng new SomeClass (hoặc một lớp con). TypeScript thu hẹp value về SomeClass bên trong phép kiểm tra.

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

Dùng instanceof cho object được tạo từ lớp, và typeof cho giá trị nguyên thủy. Ở đây cần cả hai: instanceof tách riêng Date, rồi typeof chia phần còn lại.

Thu hẹp kiểu với lớp của bạn

instanceof thu hẹp về lớp đó ở nhánh true và loại nó ra ở nhánh false, nên một union gồm nhiều lớp có thể được xử lý lần lượt từng thành phần.

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

Instance của lớp con cũng vượt qua phép kiểm tra với lớp cha: nếu Square extends Rect thì new Square(2) instanceof Rect là true. Khi các nhánh xử lý khác nhau, hãy kiểm tra lớp cụ thể nhất trước.

Lớp con của Error trong catch

Cách dùng instanceof phổ biến nhất là trong catch. Với strict, giá trị bắt được là unknown (thứ gì cũng có thể bị ném ra), và instanceof là cách để quay về một lỗi có kiểu.

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

Đầu ra:

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

class X extends Error hoạt động với instanceof trên mọi target mà TypeScript 7 hỗ trợ (ES2015 trở lên). Lời khuyên cũ về việc gọi Object.setPrototypeOf(this, X.prototype) trong hàm khởi tạo chỉ áp dụng cho code biên dịch sang ES5, một target mà TypeScript 7 đã bỏ.

instanceof không dùng được với interface hay type

Interface và type alias chỉ tồn tại cho trình biên dịch. Sau khi biên dịch, không còn giá trị User nào để so sánh, nên TypeScript từ chối phép kiểm tra:

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

Trình biên dịch báo index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Có hai cách sửa. Tự kiểm tra hình dạng bằng một type guard, tức một hàm trả về 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

Hoặc, nếu code của bạn tự tạo các object này, hãy biến User thành lớp và tạo chúng bằng new; khi đó instanceof hoạt động. Trang type guard nói chi tiết về predicate và assertion function.

Đúng kiểu chưa chắc đúng instance

TypeScript so sánh kiểu theo cấu trúc: một object literal có cùng các thành viên với một lớp sẽ gán được cho kiểu lớp đó. instanceof không nhìn vào cấu trúc. Nó đi dọc prototype chain, và một object chưa từng được tạo bằng new sẽ không qua được phép kiểm tra, kể cả khi trình biên dịch chấp nhận nó là kiểu đó.

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

Dòng cuối là điểm quan trọng. structuredClone, JSON.parse(JSON.stringify(...)) và message giữa các worker đều trả về object thuần không có prototype của lớp, dù kiểu tĩnh của chúng vẫn có thể ghi là Point. Khi instance của lớp đi qua những ranh giới như vậy, hãy dựng lại chúng (new Point(copy.x, copy.y)) trước khi dựa vào instanceof hay các phương thức.

instanceof và giá trị nguyên thủy

Giá trị nguyên thủy (string, number, boolean...) không phải object và không có prototype chain, nên "hi" instanceof String là false. TypeScript báo lỗi này khi có thể: với một giá trị kiểu string ở vế trái, instanceof là lỗi TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Với giá trị nguyên thủy, hãy dùng typeof.

Giá trị từ realm khác

instanceof so sánh với một đối tượng hàm khởi tạo cụ thể. Code chạy trong một realm khác (một iframe, hoặc một context vm của Node) có Array, Error và Date riêng, nên một mảng được tạo ở đó sẽ không qua được instanceof Array ở đây. Điều tương tự xảy ra khi hai bản sao của cùng một package npm cùng nằm trong node_modules: mỗi bản có lớp riêng, và instance từ bản này không qua được instanceof với bản kia. Với mảng, Array.isArray hoạt động xuyên realm. Với kiểu của riêng bạn, kiểm tra một thuộc tính (một type guard, hoặc một field kind) sẽ tránh được hoàn toàn vấn đề này.