خطأ الاسترداد من الدرس الأول كان سببه رقمين يبدوان متشابهين: الدولارات والسنتات. ولدى Cartwheel المشكلة نفسها في كل مكان. معرّف الطلب ومعرّف العميل كلاهما number. والمبلغ بالسنتات والكمية كلاهما number. والتنميط البنيوي، الذي تعرّفت عليه في الـ Structural Typing وقابلية الإسناد، يعتبر الأشياء المتشابهة في الشكل متطابقة، فيدعك بسرور تكتب cancelOrder(customer.id).
الإصلاح أن تجعل الأشكال مختلفة، دون تغيير أي شيء وقت التشغيل.
\nالـ branded type (النوع الموسوم) هو تقاطع (intersection) بين نوع أولي وخاصية لا وجود لها إلا في نظام الأنواع:
\ndeclare const brand: unique symbol;\ntype Brand<T, B extends string> = T & { readonly [brand]: B };\n\ntype OrderId = Brand<number, 'OrderId'>;\ntype CustomerId = Brand<number, 'CustomerId'>;\ntype Cents = Brand<number, 'Cents'>;declare const brand: unique symbol تعلن symbol لا يوجد أبدًا وقت التشغيل؛ واستخدامه مفتاحًا للخاصية يعني أنه لا يمكن لأي كائن حقيقي أن يملكه عن طريق الخطأ، ولا يستطيع أي شيء خارج هذا الملف تزويره بالاسم. يبقى OrderId رقمًا لكل الأغراض (يمكنك مقارنته وطباعته وإرساله كـ JSON)، لكن TypeScript لم يعد يقبل رقمًا عاديًا أو CustomerId مكانه:
function cancelOrder(id: OrderId) {}\n\ncancelOrder(customer.id);\n// Error: Argument of type 'CustomerId' is not assignable to parameter of type 'OrderId'.\ncancelOrder(1042);\n// Error: Argument of type 'number' is not assignable to parameter of type 'OrderId'.إن لم يكن الرقم العادي OrderId، فمن أين تأتي قيم OrderId؟ من دالة واحدة بالضبط لكل وسم، هي المُنشئ الذكي (smart constructor) الذي يتحقّق ثم يحوّل:
function toOrderId(n: number): OrderId {\n if (!Number.isInteger(n) || n < 1000) throw new Error(`Invalid order id: ${n}`);\n return n as OrderId;\n}\n\nfunction toCents(n: number): Cents {\n if (!Number.isSafeInteger(n)) throw new Error(`Cents must be a whole number, got ${n}`);\n return n as Cents;\n}هذا هو المكان المشروع الوحيد لـ as في الكود الموسوم. ولأن التحويل لا يحدث إلا بعد التحقّق، فإن كل OrderId في أي مكان من النظام معروف أنه معرّف صالح. الوسم إيصال: يثبت أن القيمة مرّت بالفحص.
وسم السنتات نصف المهمة. والنصف الآخر هو العملة. اجعل العملة معامل نوع، فيصبح Money<'USD'> وMoney<'EUR'> نوعين مختلفين:
type Currency = 'EGP' | 'AED' | 'SAR' | 'JOD' | 'GBP' | 'EUR' | 'USD' | 'CAD';\ntype Money<C extends Currency = Currency> = { cents: Cents; currency: C };\n\nfunction add<C extends Currency>(a: Money<C>, b: Money<NoInfer<C>>): Money<C> {\n return { cents: toCents(a.cents + b.cents), currency: a.currency };\n}\n\nadd(usdPrice, usdShipping); // Money<'USD'>\nadd(usdPrice, eurShipping);\n// Error: Argument of type 'Money<\"EUR\">' is not assignable to parameter of type 'Money<\"USD\">'.تفصيلان مهمّان. دون NoInfer، سيكون كلا الوسيطين موقع استنتاج وسيصبح C بهدوء 'USD' | 'EUR'، وهو بالضبط الفخ من التحكّم في الـ Inference. وa.cents + b.cents هي number عادية: الحساب ينزع الوسوم، لأن TypeScript لا يعرف إن كانت النتيجة ما زالت تعني “سنتات”. أعِد الوسم عن قصد، عبر المُنشئ، كي تُفحص قاعدة “السنتات أعداد صحيحة” من جديد.
لا تسِم كل شيء. كل وسم يضيف استدعاء مُنشئ أينما دخلت القيم إلى النظام، وعلى بيانات الاختبار الجاهزة أن تمرّ به أيضًا. سِم حيث تتشارك قيمتان النوع الأولي نفسه، ويسهل الخلط بينهما، ويكون الخلط مكلفًا: معرّفات الكيانات المختلفة، والمبالغ بوحدات مختلفة، والنصوص التي يجب أن تجتاز تحقّقًا قبل الاستخدام، مثل Email أو Sku. أما quantity التي لا تُضرب إلا في سعر فلا تحتاج وسمًا. في قاعدة كود كبيرة، نحو اثني عشر وسمًا مختارًا جيدًا يلتقط معظم أخطاء “النوع الصحيح، المعنى الخاطئ”؛ ومئة منها لا تولّد في الغالب إلا التحويلات.
الوسوم تجعل القيم متمايزة. والنمط اليومي الآخر يجعل المعالجة كاملة. رأيت في الـ Discriminated Unions لحالات المجال أن جملة عودة ناقصة قد تكشف حالة منسيّة. فحص never يجعل ذلك صريحًا، ويعمل حتى حين لا تُعيد الدالة شيئًا:
function assertNever(value: never): never {\n throw new Error(`Unhandled value: ${JSON.stringify(value)}`);\n}\n\nfunction notifyCustomer(order: Order): void {\n switch (order.status) {\n case 'processing': return sendEmail('We are packing your order');\n case 'shipped': return sendEmail(`Track it: ${order.trackingNumber}`);\n case 'delivered': return sendEmail('Enjoy!');\n case 'cancelled': return sendEmail(`Cancelled: ${order.cancelReason}`);\n case 'returned': return sendEmail('Refund on its way');\n default: return assertNever(order);\n }\n}في فرع default، يكون كل عضو مُعالَج قد ضُيّق وأُزيل، فيكون order من نوع never، ويمرّ تمريره إلى معامل never في الترجمة. أضف حالة 'on-hold' فيصبح order في ذلك الفرع هو شكل on-hold، وهو غير قابل للإسناد إلى never: خطأ ترجمة يشير إلى جملة الـ switch التي يجب تحديثها بالضبط. ووقت التشغيل، إن تسلّلت بيانات سيئة متجاوزةً الأنواع، ترمي الدالة خطأً برسالة واضحة بدل أن لا تفعل شيئًا.
إن كنت تفضّل ألّا تعرّف دالة مساعدة، فإن default: throw new Error(`Unhandled: ${order satisfies never}`) تُجري الفحص نفسه مباشرة. ولجداول البحث، يعطيك Record<OrderStatus, string> مع satisfies الشمول مجانًا: المفتاح الناقص خطأ ترجمة.
في التمرين ستسِم معرّفات Cartwheel وسنتاته، وتجعل add ترفض العملات المختلطة، وتضيف فحص شمول. والدرس القادم يتناول الشيء الآخر الذي يجب أن يتعامل معه كل نظام دفع: الإخفاقات المتوقَّعة.
OrderId وCustomerId عن التبادل رغم أن كليهما رقم.","أنشئ القيم الموسومة فقط في مُنشئات ذكية تتحقّق أولًا؛ ذلك هو المكان الوحيد الذي يليق فيه تحويل as.","الحساب على الأرقام الموسومة يُعيد number عاديًا، لذا يجب أن تعيد دوال المال وسم نتائجها عن قصد.","Money<NoInfer<C>> على الوسيط الثاني يمنع add(usd, eur) من استنتاج union يخلط العملات.","فرع default يمرّر القيمة إلى معامل من نوع never، أو يفحصها بـ satisfies never، يحوّل عضو الـ union المنسي إلى خطأ ترجمة."],"further":[{"title":"Unique symbol types","url":"https://www.typescriptlang.org/docs/handbook/symbols.html#unique-symbol"},{"title":"Exhaustiveness checking (Narrowing)","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#exhaustiveness-checking"}],"quiz":[{"q":"type OrderId = number & { readonly [brand]: 'OrderId' }. كيف تبدو خاصية الوسم وقت التشغيل؟
OrderId تحمل خاصية symbol مخفية.","why":"الأنواع الأولية لا تحمل خصائص، والوسم مُعلَن فقط ولا يُسند أبدًا. لا وجود له إلا في نظام الأنواع."},{"text":"تُغلَّف القيمة في كائن Number مرفق به الـ symbol.","why":"لا شيء يغلّف القيمة. تحويل مثل n as OrderId لا يولّد أي كود إطلاقًا."},{"text":"لا وجود لها؛ القيمة رقم عادي، والوسم يعيش في النوع فقط.","why":"صحيح. لهذا تكون الوسوم مجانية وقت التشغيل، ولهذا أيضًا لا تكون البيانات القادمة من JSON.parse موسومة أبدًا حتى تُنشئها أنت."}],"answer":2},{"q":"أين يجب أن تظهر as OrderId في قاعدة كود جيدة التصميم؟
OrderId.","why":"هذا يحوّل الوسم إلى زينة؛ يمكن تحويل أي رقم في أي مكان فتضيع الضمانة."},{"text":"فقط داخل المُنشئ الذكي الذي يتحقّق من الرقم أولًا.","why":"صحيح. نقطة دخول واحدة متحقَّق منها تعني أن كل OrderId في النظام قد فُحص."},{"text":"لا مكان لها؛ يجب إنشاء الوسوم بـ satisfies.","why":"satisfies تفحص مقابل نوع دون تغييره، فلا تستطيع إضافة وسم لا تملكه القيمة."}],"answer":1},{"q":"تُستدعى add<C extends Currency>(a: Money<C>, b: Money<C>) هكذا: add(usd, eur). ماذا يحدث؟
C هو 'USD' | 'EUR' ويمرّ الاستدعاء."},{"text":"يمرّ في الترجمة، لأن C يُستنتج على أنه 'USD' | 'EUR'؛ علّم المعامل الثاني بـ Money<NoInfer<C>> لرفضه.","why":"صحيح. مع NoInfer، يأتي C من الوسيط الأول وحده، ويفشل Money<'EUR'> أمام Money<'USD'>."},{"text":"يرمي خطأ وقت التشغيل لأن الوسم لا يطابق.","why":"الوسوم لا وجود لها وقت التشغيل، فلا شيء يمكن أن يرمي خطأً بسببها."}],"answer":1},{"q":"أُضيفت حالة جديدة 'on-hold'. أيّ دالة تفشل في الترجمة إلى أن تتعامل معها؟
function label(s: OrderStatus): string {\n switch (s) {\n case 'processing': return 'Packing';\n // …one case for every other existing status…\n default: return assertNever(s);\n }\n}s في فرع default تكون 'on-hold'، وهي غير قابلة للإسناد إلى never.","why":"صحيح. فرع default لا يرى إلا الأعضاء التي لم تعالجها أي حالة، وassertNever لا تقبل أيًّا منها."},{"text":"لا شيء؛ default تعالج كل قيمة، فيرضى الـ compiler.","why":"فرع default العادي سيُخفي الحالة الجديدة. تمرير القيمة إلى معامل never هو ما يجعله فحصًا."},{"text":"كل دالة تستخدم OrderStatus، بما فيها تلك التي تخزّنها فقط.","why":"لا يتأثّر إلا الكود الذي يدّعي الشمول. الدوال التي تخزّن الحالة أو تمرّرها تبقى تمرّ في الترجمة."},{"text":"فقط الدوال التي تستخدم جمل if بدل switch","why":"الفحص يتعلّق بمعامل never، لا بنوع الجملة المستخدمة؛ ويعمل مع سلاسل if أيضًا."}],"answer":0}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// Brand these three so they stop being interchangeable numbers.\ntype OrderId = number;\ntype CustomerId = number;\ntype Cents = number;\n\nfunction toOrderId(n: number): OrderId {\n if (!Number.isInteger(n) || n < 1000) throw new Error(`Invalid order id: ${n}`);\n return n;\n}\n\nfunction toCustomerId(n: number): CustomerId {\n if (!Number.isInteger(n) || n < 1) throw new Error(`Invalid customer id: ${n}`);\n return n;\n}\n\nfunction toCents(n: number): Cents {\n if (!Number.isSafeInteger(n)) throw new Error(`Cents must be a whole number, got ${n}`);\n return n;\n}\n\ntype Currency = 'USD' | 'EUR' | 'EGP';\ntype Moneyقوِّ أنواع الدفع في Cartwheel:
\nOrderId وCustomerId وCents بحيث تتمايز عن number وعن بعضها، واجعل المُنشئات الذكية الثلاثة تُعيد قيمًا موسومة.add ترفض قيم Money بعملات مختلفة.describePayment تتعامل مع cash-on-delivery (تُعيد 'Cash on delivery') وأضف فحص شمول يفشل في الترجمة إن تُرك نوع دفع دون معالجة يومًا ما، ويرمي خطأً وقت التشغيل مع نوع مجهول.declare const brand: unique symbol; type Brand<T, B extends string> = T & { readonly [brand]: B };.","المُنشئات الذكية هي المكان الوحيد للتحويل: return n as OrderId;. وفي add، تذكّر لماذا يتحوّل C إلى union: كلا الوسيطين موقع استنتاج.","اكتب function assertNever(value: never): never { throw … } واستدعها في فرع default: بالقيمة المضيَّقة."],"explanation":"التقاطع مع خاصية unique symbol يجعل كل نوع موسوم مجموعة جزئية صارمة من number لا يستطيع أي رقم عادي (أو وسم آخر) تحقيقها، دون أي كلفة وقت التشغيل. والتحويل داخل المُنشئات المتحقِّقة وحدها يعني أن كل قيمة موسومة قد فُحصت. وMoney<NoInfer<C>> تجعل الوسيط الثاني للفحص فقط، فيأتي C من الوسيط الأول ويُرفض Money<'EUR'>. وفي describePayment، يتلقّى فرع default كل ما لم تعالجه الحالات؛ وحين لا يتبقّى شيء يكون never فتمرّ assertNever في الترجمة، وإن تسلّل نوع ما وقت التشغيل فإنها ترمي خطأً بدل إعادة undefined.
toOrderId ترفض 999 وتقبل 1042","adds":"add تجمع مبلغين بالعملة نفسها","cash":"describePayment تتعامل مع الدفع عند الاستلام","throws-unknown":"describePayment ترمي خطأً مع نوع دفع مجهول"}},"words":635,"readMinutes":4}