ما هو type guard معرّف من قبل المستخدم؟

Question

Accepted Answer

**user-defined type guard** هي دالة يكون نوع إرجاعها **type predicate** (`x is T`). عندما تُرجع `true`، يقوم المترجم بتضييق نطاق الوسيط إلى `T` في الكود الاستدعاء — مما يتيح لك تغليف فحوصات مخصصة في وقت التشغيل.

```ts
interface Cat { meow(): void; }
interface Dog { bark(): void; }

// the magic is the return type `pet is Cat`, not just `boolean`
function isCat(pet: Cat | Dog): pet is Cat {
  return "meow" in pet;
}

function speak(pet: Cat | Dog) {
  if (isCat(pet)) {
    pet.meow(); // ✅ narrowed to Cat
  } else {
    pet.bark(); // ✅ narrowed to Dog
  }
}
```

بدون `pet is Cat` predicate، فإن `isCat` الذي يرجع `boolean` لن يضيق نطاق `pet` — سيستمر المترجم في رؤية `Cat | Dog` داخل `if`. الـ predicate هو ما يعلّمه.

## التحقق من بيانات خارجية غير معروفة

```ts
interface User { id: number; name: string; }

function isUser(x: unknown): x is User {
  return (
    typeof x === "object" && x !== null &&
    typeof (x as any).id === "number" &&
    typeof (x as any).name === "string"
  );
}

const data: unknown = await res.json();
if (isUser(data)) data.name; // ✅ safely typed as User
```

## تحذير

المترجم **يثق** في predicate الخاص بك — إذا كانت منطق الجسم خاطئًا، ستحصل على تضييق نطاق غير آمن. بالنسبة للأشكال المعقدة، يقوم schema validator (zod) بإنشاء guards صحيحة لك.

## لماذا يهم

تسمح لك type guards بتحويل فحوصات التشغيل التعسفية إلى دوال تضييق نطاق قابلة لإعادة الاستخدام — ضرورية للتحقق من `unknown` data عند API/boundaries ولتمييز أعضاء union عندما لا يكون `typeof`/`in` check بسيط كافيًا بمفرده.