TypeScript instanceof: צמצום מחלקות ושגיאות

value instanceof SomeClass היא בדיקה של JavaScript שרצה בזמן ריצה: היא true כש-SomeClass.prototype נמצא בשרשרת ה-prototype של האובייקט, כלומר האובייקט נוצר עם 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, כך שאפשר לטפל ב-union של מחלקות איבר אחרי איבר.

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. כשהענפים שונים, בדקו קודם את המחלקה הספציפית ביותר.

תתי-מחלקות של Error ב-catch

השימוש הנפוץ ביותר ב-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

class X extends Error עובד עם instanceof בכל target ש-TypeScript 7 תומך בו (ES2015 ומעלה). העצה הישנה לקרוא ל-Object.setPrototypeOf(this, X.prototype) בבנאי התאימה לקוד שקומפל ל-ES5, target ש-TypeScript 7 הסיר.

instanceof לא עובד עם interfaces או טיפוסים

interfaces ו-type aliases קיימים רק בשביל הקומפיילר. אחרי הקומפילציה אין ערך 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. יש שני פתרונות. בדקו את המבנה בעצמכם עם type guard, פונקציה שמחזירה 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 עובד. העמוד על type guards מסביר לעומק predicates ו-assertion functions.

הטיפוס הנכון אינו המופע הנכון

TypeScript משווה טיפוסים לפי מבנה: ליטרל אובייקט עם אותם איברים כמו מחלקה ניתן להשמה לטיפוס של המחלקה. instanceof לא מסתכל על המבנה. הוא עובר על שרשרת ה-prototype, ואובייקט שאף פעם לא נוצר עם 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(...)) והודעות בין workers מחזירים כולם אובייקטים רגילים בלי ה-prototype של המחלקה, למרות שהטיפוס הסטטי שלהם עדיין יכול לומר Point. כשמופעים של מחלקות עוברים גבול כזה, בנו אותם מחדש (new Point(copy.x, copy.y)) לפני שסומכים על instanceof או על מתודות.

instanceof וערכים פרימיטיביים

ערכים פרימיטיביים (string, number, boolean...) אינם אובייקטים ואין להם שרשרת prototype, ולכן "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, או הקשר vm של Node) יש Array, Error ו-Date משלו, ולכן מערך שנוצר שם נכשל ב-instanceof Array כאן. אותו דבר קורה כששני עותקים של אותה חבילת npm מגיעים ל-node_modules: לכל עותק יש מחלקה משלו, ומופע מעותק אחד נכשל ב-instanceof מול השני. למערכים, Array.isArray עובד בין realms. לטיפוסים משלכם, בדיקה של מאפיין (type guard, או שדה kind) מונעת את הבעיה לגמרי.