Type Guard في TypeScript: كيف تفحص نوع كائن

الـ type guard فحص وقت التشغيل تفهمه TypeScript، فيضيّق النوع داخل الفرع الذي اجتاز الفحص. typeof وinstanceof وin فحوص مدمجة؛ ولأي شيء آخر تكتب دالة نوع قيمتها المُعادة type predicate، أي value is Type.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

تعيد isUser قيمة منطقية عادية وقت التشغيل. يخبر نوع القيمة المُعادة value is User المترجم بما تثبته النتيجة true، فيضيّق كل if (isUser(x)) بعد ذلك x إلى User.

الـ Type Guards المدمجة

هذه الفحوص تضيّق دون أي دالة مساعدة:

كلها تعمل JavaScript عادية. ما تضيفه TypeScript هو التضييق: تقرأ الفحص وتعدّل النوع في كل فرع. القائمة الكاملة للصيغ في صفحة تضييق الأنواع. الـ guard المخصص للفحوص التي لا تتسع لتعبير واحد، أو التي تريد إعادة استخدامها.

كتابة Type Predicate

صيغة الـ type predicate هي parameterName is Type، وتحل محل boolean في نوع القيمة المُعادة. يعمل التضييق في الاتجاهين: true تضيّق إلى Type، وfalse تحذف Type من الـ union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

تمرير guard إلى filter يعطي مصفوفة بنوع صحيح. ومنذ TypeScript 5.5 يستنتج المترجم أيضًا predicate من دوال الأسهم البسيطة، فيعيد pets.filter((p) => p.kind === "cat") النوع Cat[] دون guard مسمّى.

يجب أن يتوافق نوع الـ predicate مع نوع المعامل: function f(x: string): x is number هو الخطأ TS2677، A type predicate's type must be assignable to its parameter's type.

المترجم يثق بالـ Guard الذي تكتبه

تتحقق TypeScript من أن الـ guard يعيد قيمة منطقية، ولا تتحقق من صحة هذه القيمة. الـ guard الذي يعيد true لقيم خاطئة يجعل الأنواع كاذبة، فيفشل البرنامج وقت التشغيل دون أي خطأ ترجمة.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

يرمي data.price.toFixed(2) الخطأ TypeError: Cannot read properties of undefined (reading 'toFixed') وقت التشغيل. قبل المترجم data.price على أنه number لأن الـ guard قال ذلك. افحص كل خاصية يعتمد عليها بقية الكود، واجعل الـ guards صغيرة ومختبرة وقريبة من النوع الذي تصفه.

التحقق من أن كائنًا من نوع معين

هذا هو السؤال وراء معظم الـ guards المخصصة: تصل البيانات بالنوع unknown (من JSON.parse أو fetch أو localStorage أو رسالة) وتحتاج أن تعرف هل تطابق الـ interface لديك. الطريقة:

1. typeof value === "object" && value !== null (كائن، وليس null).
2. "prop" in value لكل خاصية مطلوبة. على unknown يضيف in الخاصية إلى النوع بالنوع unknown.
3. typeof value.prop === "..." (أو guard متداخل) لنوع كل خاصية.
4. Array.isArray(value.items) && value.items.every(isItem) للمصفوفات.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

مع الأشكال الكبيرة أو المتداخلة بعمق تصبح كتابة هذه الفحوص يدويًا مرهقة. مكتبات المخططات مثل Zod وValibot تتيح وصف الشكل مرة واحدة وتعطيك فحص وقت التشغيل ونوع TypeScript معًا.

دوال التأكيد: asserts value is Type

دالة التأكيد ترمي خطأ إذا فشل الفحص وتعود بشكل عادي في غير ذلك. نوع قيمتها المُعادة asserts value is Type (أو asserts condition)، ويُضيَّق كل ما بعد الاستدعاء دون حاجة إلى if.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

قاعدة واحدة توقع الناس: يجب استدعاء دالة التأكيد عبر اسم له نوع صريح. دالة سهم const دون توصيف نوع، const check = (v: unknown): asserts v is string => {...}، تعطي الخطأ TS2775 في موضع الاستدعاء، Assertions require every name in the call target to be declared with an explicit type annotation. استخدم تعريف function، أو صِف الثابت بنوع دالة.

الـ Guards مقابل التأكيدات مقابل التحويل

تأكيد النوع (as) يغيّر النوع دون أن يفحص شيئًا. عند حدود البرنامج حيث تأتي البيانات من الخارج، الـ guard أو دالة التأكيد هما النسخة الآمنة من الفكرة نفسها.

Guards مبنية على this في الأصناف

يستطيع التابع تضييق الكائن الذي يُستدعى عليه باستخدام this is Type. هذا مفيد في هرميات الأصناف:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}