يُطلق نظام الدفع في Cartwheel أحداثًا مثل order.shipped وpayment.failed، ويبني عميل الـ API فيه الروابط من أنماط مثل /orders/:orderId/lines/:lineId. كلاهما نصوص لها بنية. وتحديد نوعها بـ string يعني أن الخطأ الإملائي في اسم حدث أو معامل المسار الناقص لا يظهر إلا حين لا يُطلَق listener أبدًا أو يُعيد طلبٌ 404. الـ template literal types تتيح للـ compiler أن يرى البنية.
الـ template literal type يستخدم صياغة علامات الاقتباس المائلة نفسها في نصوص JavaScript القالبية، لكن مع أنواع في العناصر النائبة:
\ntype OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\n\ntype OrderEvent = `order.${OrderStatus}`;\n// 'order.processing' | 'order.shipped' | 'order.delivered' | 'order.cancelled' | 'order.returned'\n\ntype CheckoutEvent = OrderEvent | `payment.${'captured' | 'failed'}`;حين يحمل عنصر نائب union، يكون للنتيجة عضو واحد لكل عضو في الـ union. ومع عنصرين نائبين تحصل على كل التركيبات: `${'s' | 'm' | 'l'}-${'red' | 'blue'}` هي ستة نصوص. هذه قوة الميزة وخطرها في آنٍ، كما سترى في نهاية الدرس.
الآن يستطيع ناقل الأحداث تحديد أنواع أسماء أحداثه من أنواع المجال التي تملكها أصلًا:
\ndeclare function on(event: CheckoutEvent, handler: () => void): void;\n\non('order.shipped', () => {});\non('order.shiped', () => {});\n// Error: Argument of type '\"order.shiped\"' is not assignable to parameter of type 'CheckoutEvent'.أضف حالة إلى OrderStatus فيصبح order.on-hold اسم حدث صالحًا تلقائيًا.
يأتي TypeScript بأربعة أنواع نصية مدمجة (intrinsic) تحوّل الأنواع الحرفية: Uppercase وLowercase وCapitalize وUncapitalize. استخدمت Capitalize لأسماء الـ setters في الـ Mapped Types وإعادة تسمية المفاتيح. واستخدام شائع آخر هو متغيّرات البيئة وأعلام الميزات:
type Feature = 'express-shipping' | 'gift-wrap';\ntype FlagEnvVar = `CHECKOUT_${Uppercase<Feature>}`;\n// 'CHECKOUT_EXPRESS-SHIPPING' | 'CHECKOUT_GIFT-WRAP'إنها مبنية داخل الـ compiler لا معرَّفة بلغة TypeScript، فلا يمكنك رؤية مصدرها، لكنها تتصرّف مثل أي نوع generic آخر.
\nتعمل الـ template literal types أيضًا كـ أنماط في conditional type. ومع infer، تستخرج أجزاءً من literal type نصي:
type Method<R> = R extends `${infer M} ${string}` ? M : never;\n\ntype M1 = Method<'POST /orders/:id/cancel'>; // 'POST'النمط `${infer M} ${string}` يعني “نصٌّ ما، ثم مسافة، ثم أي شيء”. يطابقه TypeScript مع القيمة الحرفية ويربط M بالجزء الذي قبل أول مسافة.
إليك النوع الذي يجعل باني الروابط آمنًا. إنه يجمع كل :param في نمط المسار:
type PathParams<P extends string> =\n P extends `${string}:${infer Param}/${infer Rest}`\n ? Param | PathParams<Rest>\n : P extends `${string}:${infer Param}`\n ? Param\n : never;\n\ntype P1 = PathParams<'/orders/:orderId/lines/:lineId'>; // 'orderId' | 'lineId'\ntype P2 = PathParams<'/orders'>; // neverاقرأه كحالتين. إن كان هناك معامل يليه مزيد من المسار، التقط المعامل وعاوِد على الباقي. وإن كان هناك معامل في النهاية، التقطه. وإلا فلا معاملات. حين يطابق TypeScript نمطًا، يأخذ كل عنصر نائب infer أقصر نص يسمح لبقية النمط بالمطابقة، فيتوقّف Param عند أول /.
التعاود (PathParams<Rest>) هو موضوع الدرس القادم. أما الآن فانظر إلى ما يعطيك إياه:
function buildPath<P extends string>(pattern: P, params: Record<PathParams<P>, string | number>): string {\n // Every :param in the pattern has a key in params, by construction.\n const values = params as Record<string, string | number>;\n return pattern.replace(/:(\\w+)/g, (_, name: string) => encodeURIComponent(String(values[name])));\n}\n\nbuildPath('/orders/:orderId/lines/:lineId', { orderId: 1042, lineId: 3 }); // '/orders/1042/lines/3'\nbuildPath('/orders/:orderId/lines/:lineId', { orderId: 1042 });\n// Error: … Property 'lineId' is missing in type '{ orderId: number; }' …يُستنتج P على أنه النمط الحرفي، ويحوّله PathParams<P> إلى المفاتيح المطلوبة، ويحوّل Record تلك المفاتيح إلى شكل params. والمسار الذي لا معاملات فيه يأخذ {}.
أسماء الأحداث نصف القصة فقط؛ كل حدث يحمل أيضًا حمولة. يستطيع mapped type مع جملة as بناء جدول الاسم إلى الحمولة كاملًا من union الحالات دفعة واحدة:
type OrderEventPayloads = {\n [S in OrderStatus as `order.${S}`]: { orderId: number; status: S };\n};\n\ntype ShippedPayload = OrderEventPayloads['order.shipped'];\n// { orderId: number; status: 'shipped' }تمرّ الحلقة على الحالات، وتحوّل جملة as كل واحدة منها إلى اسم حدث، ويظل نوع الحمولة قادرًا على الإشارة إلى S الأصلي. هذا الجدول هو بالضبط ما يحتاجه event emitter محدَّد الأنواع، وستبني واحدًا فوقه في باعثات أحداث وبنّاؤون آمنون من حيث النوع. لاحظ أنه لا شيء جديد هنا: mapped type وtemplate literal ووصول بالفهرس، مجتمعة. معظم كود مستوى الأنواع الحقيقي قطع صغيرة كهذه، مركّبة بعناية.
في التمرين ستحدّد أنواع أسماء الأحداث وباني الروابط في Cartwheel. والدرس القادم ينظر في التعاود داخل الأنواع: ما فائدته، وإلى أي عمق يمكن أن يصل، ومتى يكون النوع الأبسط هو الخيار الهندسي الأفضل.
\n","toc":[{"id":"sec-1","text":"بناء النصوص من الأنواع","level":2},{"id":"sec-2","text":"تحويل النصوص","level":2},{"id":"sec-3","text":"تحليل النصوص بـ infer","level":2},{"id":"sec-4","text":"الـ template literals كمفاتيح","level":2}],"takeaways":["الـ template literal type مثل`order.${OrderStatus}` يبني literal types نصية، والـ union داخله ينتج كل التركيبات.","Uppercase وLowercase وCapitalize وUncapitalize أنواع مدمجة تحوّل الـ literal types النصية.","infer داخل نمط template literal تلتقط أجزاءً من النص، ما يتيح لك تحليل أنماط مسارات مثل /orders/:orderId على مستوى الأنواع.","العناصر النائبة ${number} و${string} تقبل أنماطًا فضفاضة؛ توثّق صيغة لكنها لا تتحقّق منها بصرامة.","الـ unions داخل الـ template literals تتضاعف، ويرفض TypeScript الـ unions التي تتجاوز 100,000 عضو، فأبقِ المدخلات صغيرة."],"further":[{"title":"Template Literal Types","url":"https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html"},{"title":"Intrinsic String Manipulation Types","url":"https://www.typescriptlang.org/docs/handbook/utility-types.html#intrinsic-string-manipulation-types"}],"quiz":[{"q":"كم عضوًا في `${'s' | 'm' | 'l'}-${'red' | 'blue'}`؟
's-red' | 's-blue' | 'm-red' | …، فتتضاعف المقاسات."},{"text":"1، نص النمط نفسه","why":"الـ template literal types التي فيها unions حرفية تُوسَّع إلى نصوص محدّدة، ولا تبقى نمطًا واحدًا."}],"answer":1},{"q":"ماذا يعطي PathParams<'/orders/:orderId/lines/:lineId'> بالتعريف التعاودي من الدرس؟
'orderId' | 'lineId'","why":"صحيح. المطابقة الأولى تلتقط orderId وتعاود على lines/:lineId، التي تلتقط مطابقتها الأخيرة lineId."},{"text":"':orderId' | ':lineId'","why":"النقطتان جزء من النمط، خارج العنصر النائب infer، فلا تُلتقطان."},{"text":"'orderId' فقط","why":"هذا ما تحصل عليه دون الاستدعاء التعاودي على Rest؛ التعاود هو ما يصل إلى المعامل الثاني."},{"text":"string","why":"infer تلتقط الأجزاء النصية الحرفية بالضبط، فتكون النتيجة union من القيم الحرفية."}],"answer":0},{"q":"أيّ قيمة يقبلها type Price = ${number}``؟
'12.50' التي تبدو كمبالغ مالية","why":"${number} لا تعرف شيئًا عن صيغ المبالغ؛ تقبل أي شيء تقرؤه JavaScript كرقم."},{"text":"'1e5' وكذلك '12.50'","why":"صحيح. أي نص تقرؤه JavaScript كرقم يناسب، بما في ذلك الصيغة الأُسّية (بل حتى '0x1F')، فهو فحص فضفاض."},{"text":"الأعداد الصحيحة فقط، لأن number غير مسموح في الـ template literals","why":"العناصر النائبة number مسموحة وتقبل الكسور العشرية أيضًا."}],"answer":1},{"q":"يبني زميل `${Locale}/${Currency}/${Category}/${Sku}` من أربعة unions فيها 40 و30 و15 و500 عضو. ماذا يحدث؟
string للجزء كثير القيم، أو تحقّق وقت التشغيل."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype PaymentOutcome = 'captured' | 'failed';\ntype Feature = 'express-shipping' | 'gift-wrap';\n\ntype CheckoutEvent = string;\ntype FlagEnvVar = string;\ntype PathParams= string;\n\nfunction buildPath
(pattern: P, params: Record =\n P extends `${string}:${infer Param}/${infer Rest}`\n ? Param | PathParams (pattern: P, params: Record استخدم الـ template literal types لتحديد أنواع نصوص Cartwheel: ثم نفّذ الـ union داخل الـ template literal يتوسّع إلى نص واحد لكل عضو، فتُشتقّ عائلتا الأحداث كلتاهما من الـ unions الموجودة. وتحوّل \n
\nCheckoutEvent: order.<status> لكل OrderStatus، إضافة إلى payment.<outcome> لكل PaymentOutcome.FlagEnvVar: CHECKOUT_ متبوعة بكل Feature بأحرف كبيرة.PathParams<P>: أسماء كل :param في نمط المسار (never حين لا يوجد أيٌّ منها).buildPath(pattern, params) وقت التشغيل: استبدل كل :param بقيمته من params، مرمّزة للروابط بـ encodeURIComponent.`order.${OrderStatus}` يتوسّع إلى نص واحد لكل حالة. وUppercase<Feature> تعمل داخل العنصر النائب.","لـ PathParams حالتان: معامل يليه / ومزيد من المسار (التقطه وعاوِد على الباقي)، أو معامل في النهاية تمامًا.","وقت التشغيل، تزور pattern.replace(/:(\\w+)/g, (_, name) => …) كل اسم معامل. عامل params في الداخل كـ Record<string, string | number> بتحويل واحد مشروح بتعليق."],"explanation":"Uppercase كل اسم ميزة. أما PathParams فتطابق المسار بالأنماط: تلتقط infer Param النص الذي بعد النقطتين حتى أول /، ويعالج الاستدعاء التعاودي بقية المسار؛ ويلتقط الفرع الأخير المعامل الذي في النهاية. ثم يجعل Record<PathParams<P>, …> كل معامل مفتاحًا إلزاميًا في params، فيكون lineId الناقص خطأ ترجمة لا طلبًا إلى /orders/1042/lines/undefined.buildPath تملأ كل معامل وتترك المسارات الخالية من المعاملات كما هي","encodes":"قيم المعاملات مرمّزة للروابط"}},"words":618,"readMinutes":4}