تضييق الأنواع في TypeScript: كيف يعمل تحليل مسار التحكم

تضييق الأنواع (type narrowing) هو أن تحدد TypeScript نوعًا أدق لقيمة في نقطة معينة من الكود، بناءً على الفحوص التي أجراها الكود مسبقًا. يصبح معامل string | number من نوع string داخل if (typeof x === "string") ومن نوع number في else.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

استدعاء value.toFixed(2) قبل الفحص كان سيكون خطأ ترجمة، لأن toFixed غير موجودة في string. الفحص JavaScript عادية تعمل وقت التشغيل؛ والتضييق هو قراءة المترجم له وتعديل النوع. لا يُنتج أي شيء إضافي.

تحليل مسار التحكم

تتبع TypeScript كل مسار داخل الدالة: if/else، وreturn وthrow المبكرتين، وswitch، والحلقات، والعوامل المختصرة && و|| و?? و?:. في كل نقطة يكون نوع المتغير هو ما يظل ممكنًا هناك.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

أسلوب الإعادة المبكرة («guard clauses») هو أوضح طريقة للتضييق: عالج الحالات الشاذة أولًا فيعمل بقية الدالة بالنوع النظيف.

كل طرق التضييق

الثلاثة الأخيرة مشروحة في صفحتي type guards وdiscriminated unions. والباقي أدناه.

التضييق بالقيمة المنطقية

يحذف if (x) النوعين null وundefined (والأنواع الحرفية false و0 و""). إنه قصير، وفيه فخ كلاسيكي واحد: 0 و"" قيمتان خاطئتان منطقيًا، فتُعامل قيم صحيحة كأنها غائبة.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

للأرقام والنصوص، قارن مع undefined أو null صراحة (أو استخدم ??). والفحص بالقيمة المنطقية مناسب للكائنات والمصفوفات والدوال، التي لا تكون خاطئة منطقيًا أبدًا.

التضييق بالمساواة

تضيّق === و!== و== و!= الطرفين. المقارنة مع قيمة حرفية تضيّق إلى تلك القيمة؛ و== null (المساواة المرنة) يطابق null وundefined في فحص واحد، وهو الموضع الوحيد الذي تكون فيه المساواة المرنة أسلوبًا مألوفًا.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

مقارنة متغيرين تضيّق كليهما إلى ما قد يشتركان فيه: إذا اجتاز a: string | number وb: string | boolean الفحص a === b، يكون كلاهما string داخل if.

العامل in

يضيّق "key" in obj union من أنواع الكائنات إلى الأعضاء التي تملك (أو قد تملك) تلك الخاصية.

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

يعمل in أيضًا مع unknown بمجرد أن تعرف أنه كائن: بعد typeof v === "object" && v !== null && "id" in v تعرف TypeScript أن v يملك خاصية id نوعها unknown. وللـ unions التي تصممها بنفسك، تكون خاصية وسم مشتركة (kind: "fish") أوضح من البحث عن الدوال: يُسمى هذا النمط discriminated union.

التضييق بالإسناد

للمتغير نوع معلن، ونوع مضيَّق يتبع إسناداته. إسناد قيمة يضيّقه إلى نوع تلك القيمة، في حدود النوع المعلن.

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

أين يضيع التضييق

التضييق محلي ومتحفظ. بضع حالات تعيد ضبطه:

• تعبير مختلف. فحص obj.name يضيّق obj.name (وobj["name"])، لكن لا يضيّق obj[key] عندما يكون key متغيرًا من نوع string لا قيمة حرفية، ولا نسخة أُنشئت قبل الفحص.
• الـ callbacks وإعادة الإسناد. داخل callback، يحتفظ let المضيَّق بتضييقه فقط إذا لم يُسند مرة أخرى بعد إنشاء الـ callback. أما const أو المعامل الذي لا يُعاد إسناده فيبقى مضيَّقًا.
• الفحوص المخفية في الدوال المساعدة. دالة isString(x: unknown): boolean لا تخبر المترجم بشيء. أعطها نوع قيمة مُعادة هو type predicate، x is string، فتضيّق استدعاءاتها كما يفعل typeof.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

يبلّغ المترجم index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. قد يعمل الـ callback لاحقًا، بعد x = undefined. احذف ذلك الإسناد الأخير (أو انسخ القيمة إلى const داخل if) فيُترجم ويطبع 5 مرتين.

يمكن إصلاح الدالة المساعدة التي تعيد boolean بإعلان ما تثبته. هذا هو type guard:

function isString(value: unknown): value is string {
  return typeof value === "string";
}

منذ TypeScript 5.5 يستنتج المترجم مثل هذه الـ predicates للدوال السهمية البسيطة، ولهذا يعيد list.filter((x) => x !== undefined) الآن مصفوفة دون undefined.