إليك خطأً وصل إلى الإنتاج في نظام دفع عملت عليه. كانت هناك دالة استرداد تأخذ amount، ومزوّد الدفع يتوقّع المبلغ بالسنتات. أحد المستدعين مرّر المبلغ بالدولارات. فاسترد العملاء 1% فقط مما يستحقّونه، ولم ينتبه أحد لأسبوعين، لأن كل سطر في ذلك الكود كان “محدَّد النوع”: amount: number.
الأنواع كانت موجودة، لكنها لم تستحق مكانها. number وصف الكود ولم يمنع شيئًا. هذه الدورة عن النوع الآخر من الـ types (الأنواع): النوع الذي يجعل كتابة الخطأ مستحيلة.
في Cartwheel، المتجر الذي ستعمل عليه طوال الدورة، خمس حالات للطلب: processing وshipped وdelivered وcancelled وreturned. هذه هي النسخة التزيينية:
type Order = { id: number; status: string };\n\nfunction canCancel(order: Order): boolean {\n return order.status === 'procesing'; // typo: always false\n}هذا يمرّ في الترجمة. status من نوع string، فمقارنته بأي نص أمر مشروع. والآن النسخة التي تستحق مكانها:
type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus };\n\nfunction canCancel(order: Order): boolean {\n return order.status === 'procesing';\n // Error: This comparison appears to be unintentional because the types\n // 'OrderStatus' and '\"procesing\"' have no overlap.\n}كود التشغيل نفسه، وسطر واحد تغيّر في الأنواع، فاختفت فئة كاملة من الأخطاء. سترى هذه الحركة مرارًا: استبدل نوعًا واسعًا (string أو number أو object) بنوع ضيّق يقول ما هو مسموح فعلًا.
درسًا بعد درس ستبني طبقة الأنواع لعميل الـ API الخاص بالدفع في Cartwheel: الطلبات وحالاتها، ومبالغ مالية ترفض خلط العملات، والكوبونات، وعميل fetch تُحدَّد أنواع استجاباته من خريطة المسارات، والأحداث التي يطلقها الدفع، ومحلّلات تحوّل JSON غير موثوق إلى types موثوقة. يبقى كود التشغيل صغيرًا عن قصد؛ الجزء المثير هو ما يرفض الـ compiler (المترجم) قبوله.
\nتسير الدورة في خمس خطوات. أولًا تستخدم الأنواع أداةً للتصميم: الـ structural typing، والـ narrowing، والـ discriminated unions، وsatisfies. ثم الـ generics مع تركيز على الـ inference. ثم البرمجة على مستوى الأنواع، مع نصيحة صادقة عن متى تتوقّف. ثم أنماط تحتاجها قواعد الكود الحقيقية: الـ branded types، وأنواع Result، والتحليل عند الحدود، والأحداث المحدَّدة الأنواع. وأخيرًا الوصول إلى الإنتاج: خيارات الـ compiler، وملفات التصريحات، والـ decorators، وترحيل JavaScript.
معظم التمارين على مستوى الأنواع. تشغّل بيئة التجربة TypeScript 5.9 في الوضع الصارم وتعطيك أداتين مساعدتين:
\ntype T1 = Expect<Equal<OrderStatus, 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned'>>;Equal<A, B> يساوي true فقط حين يتطابق النوعان، وExpect لا يقبل إلا true. إذن هذا السطر اختبار وحدة: يمرّ في الترجمة حين يكون الـ type صحيحًا ويفشل حين لا يكون.
الأداة الثانية مدمجة في TypeScript. تعليق // @ts-expect-error يقول “السطر التالي يجب أن يكون خطأً”:
// @ts-expect-error: 'canceled' is not a status\ncanCancel({ id: 1001, status: 'canceled' });إذا مرّ السطر الذي تحته بلا خطأ، يبلّغ TypeScript عن توجيه غير مستخدَم. هكذا يتحوّل “هذا الاستدعاء الخاطئ مرفوض” إلى اختبار، وهذا مهم بقدر “هذا الاستدعاء الصحيح مقبول”. فالـ type الذي يقبل كل شيء ينجح في كل اختبار إيجابي.
\n\nفي التمرين أدناه، حالات الطلب من نوع string. ضيّق الـ type وشاهد الـ compiler يجد التسمية الناقصة بدلًا منك. الدرس التالي ينظر في معنى “قابل للإسناد” (assignable) فعلًا في TypeScript، لأنه ليس ما يتوقّعه معظم القادمين من Java أو C#.
string حيث لا تصحّ إلا خمس قيم فرصةٌ ضائعة؛ أما الـ union من القيم الحرفية فيسمح للـ compiler بفحص كل استخدام.","Expect<Equal<A, B>> يفشل في الترجمة ما لم يكن النوعان متطابقين تمامًا، لذا يعمل كاختبار وحدة للأنواع.","سطر // @ts-expect-error يؤكّد أن السطر التالي مرفوض، ويصبح هو نفسه خطأً إذا مرّ ذلك السطر بلا خطأ."],"further":[{"title":"TypeScript for JavaScript Programmers","url":"https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html"},{"title":"Everyday Types","url":"https://www.typescriptlang.org/docs/handbook/2/everyday-types.html"}],"quiz":[{"q":"أيّ هذه الأنواع يلتقط أكبر عدد من الأخطاء الحقيقية لحقل status في طلب لا يمكن أن يكون إلا processing أو shipped أو delivered أو cancelled أو returned؟
string، مع تعليق يسرد القيم الخمس","why":"لا أحد يفحص التعليقات. القيمة 'canceled' بحرف L واحد تمرّ بلا مشكلة وتفشل بصمت وقت التشغيل."},{"text":"'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned'","why":"صحيح. كل إسناد ومقارنة يُفحص مقابل القيم الخمس، ويستطيع الـ compiler أن يعرف متى تُغفل جملة switch إحداها."},{"text":"any، لأن القيمة تأتي من قاعدة البيانات على أي حال","why":"any يُطفئ الفحص في كل استخدام للقيمة، فيمرّ أي خطأ إملائي في أي مكان لاحق دون أن يلاحظه أحد."},{"text":"String، نوع الكائن المغلِّف، لأنه أكثر صرامة من string","why":"String هو نوع الكائن المغلِّف وليس أكثر صرامة؛ يقبل أي نص، ونادرًا جدًا ما يكون ما تريده."}],"answer":1},{"q":"ماذا يفعل اختبار النوع هذا حين يكون Total هو number | undefined؟
type T1 = Expect<Equal<Total, number>>;number جزء من الـ union.","why":"Equal يتحقّق من أن النوعين متطابقان، لا من أن أحدهما يتداخل مع الآخر. الـ union الذي يضم undefined نوعٌ مختلف."},{"text":"يمرّ في الترجمة، لكنه يطبع تحذيرًا وقت التشغيل.","why":"تُمحى الأنواع قبل تشغيل الكود، لذا لا يفشل اختبار النوع إلا وقت الترجمة؛ لا يبقى شيء ليُطبع."},{"text":"يفشل في الترجمة، لأن Equal يُحَلّ إلى false وExpect لا يقبل إلا true.","why":"صحيح. Expect<T extends true> يرفض false، فيظهر عدم التطابق كخطأ نوع على ذلك السطر."}],"answer":2},{"q":"تضيف // @ts-expect-error فوق pay(order, 'EUR')، لكن pay تقبل أي نص كعملة. ماذا يحدث؟
// @ts-ignore. أما @ts-expect-error فأكثر صرامة ويشتكي حين لا يجد ما يُخفيه."},{"text":"يبلّغ TypeScript عن “Unused ‘@ts-expect-error’ directive”، فيفشل الاختبار.","why":"صحيح. التوجيه @ts-expect-error غير المستخدَم هو خطأ بحد ذاته، ولهذا بالضبط يصلح اختبارًا على أن الاستدعاء الخاطئ مرفوض."},{"text":"يُحذف الاستدعاء من JavaScript الناتجة.","why":"التعليقات لا تغيّر الكود الناتج أبدًا. يبقى الاستدعاء ويُنفَّذ؛ لا يتأثّر إلا فحص الأنواع."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// Cartwheel's five order statuses come from the orders table.\n// Right now the type accepts any string at all.\ntype OrderStatus = string;\n\nconst statusLabels: Recordلطلبات Cartwheel خمس حالات بالضبط: processing وshipped وdelivered وcancelled وreturned. استبدل string في OrderStatus بـ union من هذه القيم الحرفية الخمس حتى تنجح اختبارات الأنواع. وحين يضيق النوع، يشير الـ compiler إلى فجوة في statusLabels: املأها حتى تُعيد statusLabel('returned') القيمة 'Returned'.
'a' | 'b' | 'c'.","بعد تغيير OrderStatus، اقرأ الخطأ الجديد على statusLabels: صار Record<OrderStatus, string> يتطلّب مفتاحًا لكل حالة.","أضف returned: 'Returned' إلى الكائن."],"explanation":"حين يكون OrderStatus من نوع string، يعني Record<OrderStatus, string> “أي مفاتيح نصية”، فتكون الحالة الناقصة غير مرئية، والخطأ الإملائي 'canceled' وسيطًا صالحًا. أما حين يصير union من خمس قيم حرفية، فيجب أن يحتوي الـ record هذه المفاتيح الخمسة بالضبط، وتُرفض canCancel('canceled')، وهذا ما يؤكّده سطر @ts-expect-error. لم يتغيّر شيء وقت التشغيل سوى التسمية المضافة: الأنواع وحدها وجدت المشكلتين.
statusLabel('returned') تُعيد 'Returned'","can-cancel":"canCancel ما زالت لا تسمح بإلغاء إلا الطلبات في حالة processing"}},"words":522,"readMinutes":3}