instanceof في TypeScript: تضييق الأصناف والأخطاء

value instanceof SomeClass فحص JavaScript يعمل وقت التشغيل: يكون true عندما يوجد SomeClass.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 على كل هدف تدعمه TypeScript 7 (ES2015 وما بعده). والنصيحة القديمة باستدعاء Object.setPrototypeOf(this, X.prototype) في المُنشئ كانت تخص الكود المترجم إلى ES5، وهو هدف أزالته TypeScript 7.

instanceof لا يعمل مع الواجهات أو الأنواع

الواجهات و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 ودوال التأكيد بالتفصيل.

النوع الصحيح ليس النسخة الصحيحة

تقارن 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(...)) والرسائل بين workers كلها تعيد كائنات عادية بلا النموذج الأولي للصنف، رغم أن نوعها الثابت قد يظل يقول 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 للأنواع البدائية.

القيم من نطاقات تنفيذ أخرى

يقارن instanceof مع كائن مُنشئ واحد محدد. الكود الذي يعمل في نطاق تنفيذ آخر (realm)، مثل iframe أو سياق vm في Node، له Array وError وDate خاصة به، لذلك تفشل مصفوفة أُنشئت هناك في instanceof Array هنا. ويحدث الشيء نفسه عندما تنتهي نسختان من حزمة npm واحدة في node_modules: لكل نسخة صنفها الخاص، والنسخة من إحداهما تفشل في instanceof مقابل الأخرى. للمصفوفات يعمل Array.isArray عبر النطاقات. ولأنواعك الخاصة، يتجنب فحص خاصية (type guard، أو حقل kind) المشكلة كليًا.