هكذا كان شكل نوع Order في Cartwheel قبل أن يفكّر فيه أحد:
type Order = {\n id: number;\n status: 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\n trackingNumber?: string; // set once shipped\n deliveredAt?: string; // set once delivered\n cancelReason?: string; // set if cancelled\n refundCents?: number; // set if returned\n};يبدو معقولًا، لكنه فخ. كل واحد من الحقول الاختيارية الأربعة يمكن أن يحضر أو يغيب، فيسمح هذا النوع بـ 5 × 2⁴ = 80 شكلًا. وعمل Cartwheel فيه خمسة فقط. طلب مشحون بلا رقم تتبّع يمرّ في الترجمة. طلب ملغى فيه تاريخ تسليم يمرّ. وفي كل مرة تقرأ order.trackingNumber تحصل على string | undefined فتمدّ يدك إلى !، أي أنك تقول للـ compiler “ثق بي” ثمانين مرة في الأسبوع.
الـ discriminated union (الاتحاد المميَّز) يعطي كل حالة نوع كائن خاصًا بها ويجمعها بـ |. لكل عضو خاصية مشتركة بقيمة حرفية مختلفة، هي المميِّز (discriminant):
type ProcessingOrder = { id: number; status: 'processing' };\ntype ShippedOrder = { id: number; status: 'shipped'; trackingNumber: string };\ntype DeliveredOrder = { id: number; status: 'delivered'; trackingNumber: string; deliveredAt: string };\ntype CancelledOrder = { id: number; status: 'cancelled'; cancelReason: string };\ntype ReturnedOrder = {\n id: number;\n status: 'returned';\n trackingNumber: string;\n deliveredAt: string;\n refundCents: number;\n};\n\ntype Order = ProcessingOrder | ShippedOrder | DeliveredOrder | CancelledOrder | ReturnedOrder;الآن يسمح النوع بخمسة أشكال بالضبط. لاحظ أنه لم يعد شيء اختياريًا: الطلب المشحون له رقم تتبّع. الحالات المستحيلة لا تُفحص وقت التشغيل؛ بل لا يمكن التعبير عنها أصلًا:
\nconst o: Order = { id: 1042, status: 'shipped' };\n// Error: Type '{ id: number; status: \"shipped\"; }' is not assignable to type 'Order'.\n// Property 'trackingNumber' is missing in type '{ id: number; status: \"shipped\"; }'\n// but required in type 'ShippedOrder'.فحص المميِّز يضيّق الكائن كله. داخل كل case، يعرف TypeScript بالضبط أيّ عضو بين يديك:
function describe(order: Order): string {\n switch (order.status) {\n case 'processing':\n return `#${order.id} is being packed`;\n case 'shipped':\n return `#${order.id} is on its way (${order.trackingNumber})`;\n case 'delivered':\n return `#${order.id} arrived on ${order.deliveredAt}`;\n case 'cancelled':\n return `#${order.id} was cancelled: ${order.cancelReason}`;\n case 'returned':\n return `#${order.id} was refunded $${(order.refundCents / 100).toFixed(2)}`;\n }\n}لا ! ولا ?. ولا ?? ''. ولاحظ نوع الإرجاع الصريح : string. إذا أضاف أحدهم الحالة 'on-hold' إلى الـ union الشهر القادم، تصبح نهاية هذه الدالة قابلة للوصول، فيبلّغ TypeScript عن Function lacks ending return statement and return type does not include ‘undefined’. الـ compiler يجد كل مكان يحتاج إلى تحديث. وستجعل هذا الفحص صريحًا وأعلى صوتًا باستخدام never في الـ Branded Types والفحوص الشاملة.
يؤتي الـ union أكبر ثماره في الدوال التي تغيّر الحالة. حدّد أنواع مدخلاتها ومخرجاتها كأشكال محدّدة:
\nfunction ship(order: ProcessingOrder, trackingNumber: string): ShippedOrder {\n return { id: order.id, status: 'shipped', trackingNumber };\n}\n\nfunction cancel(order: ProcessingOrder, reason: string): CancelledOrder {\n return { id: order.id, status: 'cancelled', cancelReason: reason };\n}الآن صار “لا يمكنك شحن طلب مرتين” و"لا يمكنك إلغاء طلب مشحون" حقيقتين وقت الترجمة. المستدعي الذي بين يديه Order عليه أن يضيّق النوع أولًا:
function shipIfReady(order: Order, tracking: string): Order {\n if (order.status !== 'processing') return order;\n return ship(order, tracking); // order is ProcessingOrder here\n}أنواع الإرجاع مهمة بقدر المعاملات. لأن ship تُعيد ShippedOrder لا Order، يستطيع المستدعي تسليم النتيجة مباشرة إلى دالة تحتاج رقم تتبّع، مثل printLabel(shipped)، دون فحص status مرة أخرى. كل انتقال يحمل المعرفة إلى الأمام. أعِد الـ Order الواسع وستكون قد رميت تلك المعرفة، وأجبرت كل مستدعٍ على التضييق من جديد.
للطلبات الحقيقية أكثر من id: عميل، وطابع زمني لوقت الطلب، وبنود. تكرار هذه في خمسة أشكال يدعو إلى التباعد بينها، فاسحبها إلى نوع أساسي وقاطعه مع حقول كل حالة:
type OrderBase = { id: number; customerId: number; placedAt: string };\n\ntype Shipped = OrderBase & { status: 'shipped'; trackingNumber: string };\ntype Cancelled = OrderBase & { status: 'cancelled'; cancelReason: string };يبقى كل شكل عضوًا مستقلًا بـ status حرفي خاص به، فيعمل الـ narrowing تمامًا كما من قبل. ويعطيك النوع الأساسي أيضًا نوع معامل طبيعيًا للدوال التي لا تهتم بالحالة، مثل function customerLink(order: OrderBase)، التي تقبل كل الأشكال.
يمكنك أيضًا تفكيك المميِّز. منذ TypeScript 4.4، تضيّق const { status } = order; if (status === 'shipped') { … } النوعَ order أيضًا، ما دام order ثابتًا const أو معاملًا لم يُعَد الإسناد إليه. هذا يُبقي جمل switch الطويلة مقروءة دون التخلّي عن الـ narrowing.
الـ discriminated union هو الخيار الصحيح حين تحمل الحالات بيانات مختلفة. أما حين تختلف الأشكال في التسمية فقط (مثلًا channel بقيم 'web' | 'mobile_app' | 'marketplace' والحقول نفسها)، فيكفي union حرفي بسيط على خاصية واحدة. الجأ إلى النمط الكامل حين تضبط نفسك تكتب حقولًا اختيارية مع تعليقات مثل “تُضبط فقط حين…”.
في التمرين، ستحوّل Order المليء بالحقول الاختيارية في Cartwheel إلى union، وتجعل ship لا تقبل إلا الطلبات القابلة للشحن. الدرس القادم: الـ literal types وas const وsatisfies، الأدوات التي تمنع تلك القيم الحرفية من الاتساع مجددًا إلى string.
status.","فحص المميِّز بـ === أو switch يضيّق الكائن كله، فتصبح الحقول الخاصة بكل حالة متاحة دون !.","الدوال التي تنقل بين الحالات يجب أن تقبل وتُعيد أشكالًا محدّدة، مثل ship(order: ProcessingOrder): ShippedOrder.","نوع الإرجاع الصريح على جملة switch فوق المميِّز يحوّل الحالة المنسيّة إلى خطأ ترجمة."],"further":[{"title":"Discriminated unions (Narrowing)","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"},{"title":"Unions and intersection types (Everyday Types)","url":"https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types"}],"quiz":[{"q":"نوع Order فيه status بخمس قيم وأربعة حقول اختيارية. كم شكلًا تقريبًا يسمح به النوع، وكم منها حالات صالحة إذا كانت كل حالة تستخدم مجموعة ثابتة من الحقول؟
status يتحكّم في الحقول الموجودة.","why":"لا شيء في نوع الحقول الاختيارية يربط الحقول بـ status. يراها الـ compiler مستقلة."},{"text":"80 مسموحة (5 × 2⁴) و5 صالحة.","why":"صحيح. كل حقل اختياري يمكن أن يحضر أو يغيب باستقلال، فمعظم التركيبات حالات مستحيلة ومع ذلك تمرّ في الترجمة."},{"text":"20 مسموحة (5 × 4) و5 صالحة.","why":"الحقول الاختيارية تتضاعف ولا تُجمع. أربعة خيارات مستقلة بنعم/لا تعطي 16 تركيبة لكل حالة."}],"answer":1},{"q":"بالنظر إلى الـ union أدناه، ما نوع order داخل فرع case 'returned':؟
type Order =\n | { status: 'processing'; id: number }\n | { status: 'delivered'; id: number; deliveredAt: string }\n | { status: 'returned'; id: number; deliveredAt: string; refundCents: number };Order، لأن switch لا تضيّق الكائنات","why":"الـ switch على مميِّز حرفي يضيّق الكائن كله، وهذا هو جوهر النمط."},{"text":"{ status: 'delivered' … } | { status: 'returned' … }، لأن كليهما فيه deliveredAt","why":"الـ narrowing يتبع قيمة المميِّز، لا الحقول المشتركة. عضو واحد فقط فيه status: 'returned'."},{"text":"{ status: 'returned'; id: number; deliveredAt: string; refundCents: number }","why":"صحيح. عضو واحد فقط يمكن أن يساوي status فيه 'returned'، فيكون refundCents متاحًا كـ number عادي."}],"answer":2},{"q":"أيّ توقيع يستخدم الـ union على أفضل وجه لمنع شحن الطلب مرتين؟
","options":[{"text":"ship(order: Order, tracking: string): Order","why":"هذا يقبل أيضًا طلبًا مُسلَّمًا أو ملغى، ويفقد المستدعي معرفة أن النتيجة مشحونة."},{"text":"ship(order: Order, tracking: string): ShippedOrder","why":"نوع الإرجاع أفضل، لكن ما زال يمكن تمرير أي طلب، بما فيه طلب شُحن من قبل."},{"text":"ship(order: ShippedOrder, tracking: string): ShippedOrder","why":"هذا لا يقبل إلا الطلبات المشحونة أصلًا، وهو عكس ما يجب أن تسمح به الدالة."},{"text":"ship(order: ProcessingOrder, tracking: string): ShippedOrder","why":"صحيح. لا يدخل إلا طلب قيد المعالجة، ويحصل المستدعي على قيمة يعرف الـ compiler أنها مشحونة."}],"answer":3},{"q":"تضيف الحالة 'on-hold' إلى الـ union المسمّى Order. أيّ دالة مضمونٌ أن تحصل على خطأ ترجمة إلى أن تتعامل مع الحالة الجديدة؟
string وفيها switch يعود في كل حالة وليس فيه default.","why":"صحيح. مع وجود عضو جديد غير مُعالَج، تصبح نهاية الدالة قابلة للوصول، فيبلّغ TypeScript أنها تفتقد جملة عودة ختامية."},{"text":"دالة تستخدم if (order.status === 'shipped') … else ….","why":"فرع else يمتصّ الحالة الجديدة بصمت، وهذا بالضبط الخطأ الذي تريد تجنّبه."},{"text":"دالة فيها فرع default: يُعيد 'Unknown'.","why":"فرع default يعالج الحالة الجديدة وقت التشغيل، فلا يجد الـ compiler سببًا للشكوى."}],"answer":0}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// Every field that only some statuses have is optional,\n// so impossible states (shipped with no tracking number…) compile.\ntype Order = {\n id: number;\n status: 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\n trackingNumber?: string; // shipped, delivered, returned\n deliveredAt?: string; // delivered, returned\n cancelReason?: string; // cancelled\n refundCents?: number; // returned\n};\n\nfunction ship(order: Order, trackingNumber: string): Order {\n return { id: order.id, status: 'shipped', trackingNumber };\n}\n\nfunction describe(order: Order): string {\n switch (order.status) {\n case 'processing': return `#${order.id} is being packed`;\n case 'shipped': return `#${order.id} is on its way (${order.trackingNumber})`;\n case 'delivered': return `#${order.id} arrived on ${order.deliveredAt}`;\n case 'cancelled': return `#${order.id} was cancelled: ${order.cancelReason}`;\n case 'returned': return `#${order.id} was refunded $${(order.refundCents! / 100).toFixed(2)}`;\n }\n}\n\n// ---- Type tests (do not edit) ----\ntype T1 = Expectاستبدل Order المليء بالحقول الاختيارية بـ discriminated union من خمسة أشكال (واحد لكل status)، يكون فيه كل حقل تملكه الحالة إلزاميًا، والحقول التي لا تملكها غائبة:
processing: idshipped: id، trackingNumberdelivered: id، trackingNumber، deliveredAtcancelled: id، cancelReasonreturned: id، trackingNumber، deliveredAt، refundCentsثم غيّر ship بحيث لا تقبل إلا طلبًا قيد المعالجة وتُعيد طلبًا مشحونًا. يجب أن تصبح أسطر @ts-expect-error الثلاثة أخطاءً حقيقية، وألّا تحتاج describe إلى ! بعد الآن.
status قيمة نصية حرفية واحدة، واجمعها بـ |.","تسمية الأشكال (ProcessingOrder وShippedOrder…) تتيح لك استخدامها في توقيع ship.","function ship(order: ProcessingOrder, trackingNumber: string): ShippedOrder"],"explanation":"صار كل شكل يحمل البيانات التي تملكها حالته بالضبط، فالكائن الحرفي الذي لا يحتوي trackingNumber لا يمكن أن يكون طلبًا مشحونًا، والحقل الزائد deliveredAt في طلب ملغى يُعلَّم. داخل كل case، يضيّق فحص status النوعَ order إلى شكل واحد، فيصبح refundCents من نوع number عادي ولا حاجة إلى !. وتحديد نوع ship بـ ProcessingOrder مدخلًا وShippedOrder مخرجًا ينقل القاعدة “لا تُشحن إلا الطلبات قيد المعالجة” من تعليق في مراجعة الكود إلى الـ compiler.
ship تُعيد طلبًا مشحونًا فيه رقم التتبّع والمعرّف نفسه","describes":"describe ما زالت تصف الطلبات المرتجعة والملغاة"}},"words":633,"readMinutes":4}