لطلب Cartwheel الحقل shippingFeeCents: number | null. القيمة null تعني أن الرسوم غير معروفة بعد (العنوان غير مكتمل). و0 تعني شحنًا مجانيًا. هذه هي التسمية المعروضة عند الدفع، كما كُتبت أول مرة:
function shippingLabel(feeCents: number | null): string {\n if (!feeCents) return 'Calculated at checkout';\n if (feeCents === 0) return 'Free';\n return `$${(feeCents / 100).toFixed(2)}`;\n}كل عميل شحنه مجاني رأى “Calculated at checkout”. لم يشتكِ TypeScript، لأن feeCents بعد السطر الأول من نوع number، ومقارنة رقم بـ 0 أمر مشروع تمامًا. الأنواع كانت صحيحة؛ الـ narrowing (تضييق النوع) هو الخاطئ. هذا الدرس عن كيفية تضييق TypeScript للأنواع، كي تجعله يعمل لصالحك بدل أن تثق به ثقة عمياء.
يتتبّع TypeScript نوع كل متغيّر عبر كل فرع وكل جملة عودة. يمكن أن يكون للاسم نفسه نوع مختلف في كل سطر:
\nfunction shippingLabel(feeCents: number | null): string {\n // feeCents: number | null\n if (feeCents === null) return 'Calculated at checkout';\n // feeCents: number\n if (feeCents === 0) return 'Free';\n // feeCents: number\n return `$${(feeCents / 100).toFixed(2)}`;\n}هذا هو تحليل تدفّق التحكّم (control-flow analysis). كل فحص يقسم التدفّق إلى فروع، وفي كل فرع يكون نوع المتغيّر هو مجموعة القيم التي يمكن أن تبقى هناك. وحين يعود فرعٌ، لا يرى الكود بعده إلا ما تبقّى.
\nتضيّق الأنواع بفحوص JavaScript عادية؛ ويفهم TypeScript كل واحد منها:
\n| الفحص | \nما يضيّقه | \nمثال | \n
|---|---|---|
typeof x === 'string' | \nالأنواع الأولية | \ntypeof amount === 'number' | \n
x === null، x !== undefined | \nالقيم الحرفية | \ncoupon !== null | \n
'prop' in x | \nunions الكائنات حسب الخاصية | \n'trackingNumber' in shipment | \n
x instanceof C | \nنُسخ الأصناف | \nerr instanceof TypeError | \n
Array.isArray(x) | \nالمصفوفات | \nArray.isArray(input) | \n
فحص الصدقية (truthiness)، أي if (x)، يضيّق النوع أيضًا، وهو الفحص الذي يجب أن تحذر منه. فهو يُزيل null وundefined، لكنه يُزيل أيضًا 0 و'' وNaN وfalse. مع كائن أو مصفوفة، فحص الصدقية مقبول. أما مع رقم أو نص يعني فيه الصفر أو الفراغ شيئًا، فقارن مع null صراحةً.
in وinstanceof عمليًافحصان يستحقان نظرة أقرب لأن عميل الدفع يستخدمهما باستمرار. يجيب مزوّد الدفع بأحد شكلين، وواحد منهما فقط فيه receiptId:
type PaymentReply = { receiptId: string; capturedCents: number } | { declineCode: string };\n\nfunction summarize(reply: PaymentReply): string {\n if ('receiptId' in reply) return `Paid, receipt ${reply.receiptId}`;\n return `Declined (${reply.declineCode})`;\n}'receiptId' in reply تُبقي فقط أعضاء الـ union التي تعرّف receiptId. هذا يعمل، لكنه يضيّق النوع بناءً على غياب حقل في الأعضاء الأخرى، فإضافة receiptId? إلى شكل الرفض لاحقًا ستكسره بصمت. حين تتحكّم في الأنواع، يكون المميِّز الحرفي (الدرس القادم) أمتن.
وinstanceof هي أداة الأخطاء. تحت strict، يكون المتغيّر في جملة catch من نوع unknown، لأن JavaScript تسمح لك برمي (throw) أي شيء. فتضيّق النوع قبل أن تلمسه:
function describeFailure(err: unknown): string {\n if (err instanceof Error) return err.message;\n if (typeof err === 'string') return err;\n return 'Unknown error';\n}الـ narrowing حقيقةٌ عن نقطة واحدة في التدفّق. والـ callback يُنفَّذ في وقت آخر، لذا يحذر TypeScript مما يحمله إلى داخله:
\ntype Order = { id: number; couponCode: string | null };\n\nfunction couponBanner(order: Order, names: string[]): string[] {\n if (order.couponCode === null) return [];\n return names.map((n) => `${n}, ${order.couponCode.toUpperCase()} is applied`);\n // Error: 'order.couponCode' is possibly 'null'.\n}خارج الدالة السهمية، order.couponCode من نوع string. وداخلها يختفي الـ narrowing، لأن couponCode خاصية قابلة للتغيير وقد يعيدها شيءٌ إلى null قبل أن تستدعي map الـ callback. والإصلاح هو التقاط القيمة المضيَّقة في const، وهو لا يمكن أن يتغيّر أبدًا:
function couponBanner(order: Order, names: string[]): string[] {\n const code = order.couponCode;\n if (code === null) return [];\n return names.map((n) => `${n}, ${code.toUpperCase()} is applied`);\n}منذ TypeScript 5.4، تحتفظ المعاملات ومتغيّرات let أيضًا بتضييقها داخل الـ callbacks، ما دام لا يُعاد الإسناد إليها بعد إنشاء الـ callback. أما الخصائص فلا تحتفظ به أبدًا. النسخ إلى const يعمل في كل الإصدارات ويجعل النية واضحة.
كانت filter مصدر إحباط كلاسيكيًا: coupons.filter((c) => c !== null) كان نوعها يبقى (string | null)[]. منذ TypeScript 5.5، يستنتج TypeScript الـ type predicate من الدوال السهمية البسيطة مثل هذه، فتكون النتيجة string[]:
const coupons: (string | null)[] = ['WELCOME10', null, 'LOYAL5'];\nconst codes = coupons.filter((c) => c !== null); // string[]لا يحدث الاستنتاج إلا حين يثبت الفحصُ النوعَ في الاتجاهين. (c) => !!c لا تُستنتج على أنها predicate: فالنتيجة الكاذبة قد تعني '' لا null، فلا يستطيع TypeScript أن يستنتج أن القيمة المرفوضة هي null. والأمر نفسه مع filter(Boolean). اكتب المقارنة الصريحة وستحصل على الـ narrowing وعلى التعامل الصحيح مع النصوص الفارغة معًا.
التمرين أدناه يجمع الأخطاء الثلاثة من هذا الدرس في ملف واحد. وفي الدرس التالي ستصمّم أنواعًا تجعل الـ narrowing شبه تلقائي: الـ discriminated unions.
\n","toc":[{"id":"sec-1","text":"تحليل تدفّق التحكّم","level":2},{"id":"sec-2","text":"صندوق أدوات الـ narrowing","level":2},{"id":"sec-3","text":"in وinstanceof عمليًا","level":3},{"id":"sec-4","text":"أين يضيع الـ narrowing","level":2},{"id":"sec-5","text":"تضييق المصفوفات بـ filter","level":2}],"takeaways":["يمنح تحليل تدفّق التحكّم المتغيّرَ نوعًا مختلفًا عند كل نقطة في الكود، بناءً على الفحوص وجمل العودة التي سبقتها.","فحوص الصدقية (truthiness) تُزيل أيضًا0 و''، لذا قارن مع null أو undefined صراحةً حين تكون لهاتين القيمتين دلالة.","يسقط الـ narrowing لخاصية قابلة للتغيير داخل الـ callbacks؛ انسخ القيمة إلى const قبل الـ callback لتحافظ عليه.","منذ TypeScript 5.5، تُستنتج الدالة السهمية البسيطة مثل (c) => c !== null الممرَّرة إلى filter على أنها type predicate، فتضيق النتيجة."],"further":[{"title":"Narrowing","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html"},{"title":"TypeScript 5.5 release notes (inferred type predicates)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html"}],"quiz":[{"q":"قيمة shippingFeeCents هي null حين لا تكون الرسوم معروفة بعد، و0 للشحن المجاني. ماذا تُعيد هذه الدالة لطلب شحنه مجاني؟
function label(fee: number | null) {\n if (!fee) return 'Calculated at checkout';\n return fee === 0 ? 'Free' : `${fee / 100}`;\n}'Free' لا يمكن الوصول إليه مع 0، لأن !0 تساوي true فتُنفَّذ جملة العودة الأولى قبله."},{"text":"‘Calculated at checkout’","why":"صحيح. فحص الصدقية يعامل 0 كما يعامل null. اكتب if (fee === null) بدلًا منه."},{"text":"‘0’","why":"لا تصل الدالة أبدًا إلى النص القالبي مع 0؛ فحص الصدقية يعود قبل ذلك."},{"text":"لا يمرّ في الترجمة، لأن fee === 0 لا تداخل فيه بعد الفحص.","why":"بعد أن يعود !fee، يبقى fee من نوع number، ومقارنة number بـ 0 مسموحة. الخطأ صامت."}],"answer":1},{"q":"لماذا يكون order.coupon خطأً داخل الـ callback؟
if (order.coupon !== null) {\n names.map((n) => `${n}: ${order.coupon.toUpperCase()}`);\n}map لا تُفحص أنواعها تحت strict.","why":"الـ callbacks تُفحص بالكامل. والخطأ موجود تحديدًا لأنها تُفحص."},{"text":"لأن TypeScript لا يمكنه معرفة متى يُنفَّذ الـ callback، وorder.coupon خاصية قابلة للتغيير قد تصبح null حينها.","why":"صحيح. تضييق خاصية قابلة للتغيير لا ينتقل إلى دالة أُنشئت داخل الكتلة. انسخها إلى const أولًا."},{"text":"لأن !== null لا تضيّق النوع؛ تحتاج إلى typeof order.coupon === 'string'.","why":"المقارنة مع null تضيّق النوع جيدًا خارج الـ callback. المشكلة في حدود الـ callback، لا في الفحص."}],"answer":1},{"q":"في TypeScript 5.9، ما نوع codes؟
string[] حين تُكتب coupons.filter((c) => c !== null) مع coupons: (string | null)[]","why":"صحيح. يستنتج TypeScript 5.5 وما بعده أن (c) => c !== null هي الـ predicate c is string، فتضيّق filter المصفوفة."},{"text":"string[] حين تُكتب coupons.filter(Boolean)","why":"Boolean ليست type predicate، وفحص الصدقية لا يمكن أن يكون واحدًا أصلًا لأنه يُزيل '' أيضًا. تبقى النتيجة (string | null)[]."},{"text":"string[] حين تُكتب coupons.filter((c) => !!c)","why":"لا تُستنتج الصدقية على أنها predicate، لأن النتيجة الكاذبة لا تثبت أن القيمة null؛ فقد تكون ''."}],"answer":0},{"q":"أيّ فحص يضيّق input: Order | Order[] إلى Order[]؟
typeof input === 'array'","why":"typeof لا تُعيد أبدًا 'array'؛ مع المصفوفات تُعيد 'object'، ويعلّم TypeScript هذه المقارنة."},{"text":"input instanceof Object","why":"كلٌّ من Order والمصفوفة كائنات، فلا يستطيع هذا الفحص التمييز بينهما."},{"text":"'length' in input","why":"هذا يضيّق النوع فقط إن لم يكن لـ Order خاصية length، وهذا هشّ؛ الفحص المخصَّص أوضح وأأمن."},{"text":"Array.isArray(input)","why":"صحيح. Array.isArray معرَّفة كـ type predicate، فيرى الفرع الصادق Order[] ويرى الفرع الكاذب Order."}],"answer":3}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Order = {\n id: number;\n couponCode: string | null;\n // null = not known yet (address incomplete); 0 = free shipping\n shippingFeeCents: number | null;\n};\n\nfunction shippingLabel(order: Order): string {\n if (!order.shippingFeeCents) return 'Calculated at checkout';\n if (order.shippingFeeCents === 0) return 'Free';\n return `$${(order.shippingFeeCents / 100).toFixed(2)}`;\n}\n\nfunction usedCoupons(orders: Order[]): string[] {\n return orders.map((o) => o.couponCode).filter((c) => c);\n}\n\nfunction couponBanner(order: Order, names: string[]): string[] {\n if (order.couponCode === null) return [];\n return names.map((n) => `${n}, ${order.couponCode.toUpperCase()} is applied`);\n}\n\nconst orders: Order[] = [\n { id: 1001, couponCode: 'welcome10', shippingFeeCents: 0 },\n { id: 1002, couponCode: null, shippingFeeCents: null },\n { id: 1003, couponCode: 'loyal5', shippingFeeCents: 499 },\n];\nconsole.log(orders.map(shippingLabel), usedCoupons(orders));\n"},"solution":{"ts":"type Order = {\n id: number;\n couponCode: string | null;\n // null = not known yet (address incomplete); 0 = free shipping\n shippingFeeCents: number | null;\n};\n\nfunction shippingLabel(order: Order): string {\n const fee = order.shippingFeeCents;\n if (fee === null) return 'Calculated at checkout';\n if (fee === 0) return 'Free';\n return `$${(fee / 100).toFixed(2)}`;\n}\n\nfunction usedCoupons(orders: Order[]): string[] {\n return orders.map((o) => o.couponCode).filter((c) => c !== null);\n}\n\nfunction couponBanner(order: Order, names: string[]): string[] {\n const code = order.couponCode;\n if (code === null) return [];\n return names.map((n) => `${n}, ${code.toUpperCase()} is applied`);\n}\n\nconst orders: Order[] = [\n { id: 1001, couponCode: 'welcome10', shippingFeeCents: 0 },\n { id: 1002, couponCode: null, shippingFeeCents: null },\n { id: 1003, couponCode: 'loyal5', shippingFeeCents: 499 },\n];\nconsole.log(orders.map(shippingLabel), usedCoupons(orders));\n"},"checks":[{"id":"types","typecheck":true},{"id":"free-shipping","test":"const o = (fee) => ({ id: 1, couponCode: null, shippingFeeCents: fee }); return shippingLabel(o(0)) === 'Free' && shippingLabel(o(null)) === 'Calculated at checkout' && shippingLabel(o(499)) === '$4.99';"},{"id":"used-coupons","test":"const r = usedCoupons([{ id: 1, couponCode: 'A', shippingFeeCents: 0 }, { id: 2, couponCode: null, shippingFeeCents: 0 }, { id: 3, couponCode: 'B', shippingFeeCents: 0 }]); return JSON.stringify(r) === '[\"A\",\"B\"]';"},{"id":"banner","test":"const r = couponBanner({ id: 1, couponCode: 'loyal5', shippingFeeCents: 0 }, ['Mona']); return r.length === 1 && r[0].includes('LOYAL5') && couponBanner({ id: 2, couponCode: null, shippingFeeCents: 0 }, ['Mona']).length === 0;"}],"title":"أصلح ثلاثة أخطاء في الـ narrowing","prompt":"في هذا الملف مشكلات الـ narrowing الثلاث من الدرس. أصلحها دون استخدام تأكيد عدم الفراغ ! (non-null assertion) أو as أو any:
shippingLabel القيمة 'Free' حين تكون shippingFeeCents تساوي 0، و'Calculated at checkout' حين تكون null، ومبلغًا بالدولار مثل '$4.99' في غير ذلك.usedCoupons مصفوفة string[] حقيقية من رموز الكوبونات غير الفارغة.couponBanner في الترجمة وأن تبقى تحوّل الرمز إلى أحرف كبيرة داخل الـ callback.null بدل الاعتماد على الصدقية.","في 2، يستنتج TypeScript 5.5 وما بعده type predicate من (c) => c !== null، لكن ليس من (c) => c.","في 3، انسخ order.couponCode إلى const قبل فحصه، واستخدم ذلك الـ const داخل الدالة السهمية."],"explanation":"!fee صادقة مع 0، فسقط الشحن المجاني في فرع null؛ والفحص بـ === null يفصل بين المعنيين. تُستنتج filter((c) => c !== null) على أنها الـ predicate c is string، فتضيق المصفوفة إلى string[]، أما الـ callback القائم على الصدقية فليس predicate. وفي couponBanner، لا ينجو تضييق الخاصية القابلة للتغيير order.couponCode إلى داخل الـ callback، لكن الـ const لا يتغيّر أبدًا، فينجو نوعه المضيَّق.
shippingLabel تُعيد ‘Free’ مع 0، و’Calculated at checkout’ مع null، و’$4.99’ مع 499","used-coupons":"usedCoupons تُبقي الرموز غير الفارغة فقط، بالترتيب نفسه","banner":"couponBanner تحوّل الرمز إلى أحرف كبيرة وتُعيد [] حين لا يوجد كوبون"}},"words":680,"readMinutes":4}