يُطلق نظام الدفع في Cartwheel أحداثًا: order.shipped وpayment.failed وcheckout.opened. وتستمع إليها أدوات التحليلات وخدمة البريد وصفحة الطلب. النسخة الأولى استخدمت emitter عاديًا بأسماء من نوع string وحمولات من نوع any، فأنتجت الخطأين الكلاسيكيين: listener لـ 'order.shiped' لم يُطلَق أبدًا، وhandler يقرأ payload.trackingNo من حدث يرسل trackingNumber. كلاهما كان غير مرئي حتى لاحظ أحدهم رسائل بريد مفقودة.
كل ما في هذا القسم والذي قبله يجتمع لإصلاح ذلك.
\nصِف كل حدث مرة واحدة، في خريطة من الاسم إلى نوع الحمولة:
\ntype CheckoutEvents = {\n 'checkout.opened': undefined;\n 'order.shipped': { orderId: number; carrier: string; trackingNumber: string };\n 'payment.failed': { orderId: number; reason: string };\n};يمكنك أيضًا توليد جزء من هذه الخريطة بالـ mapped type ذي الـ template literal من الـ Template Literal Types. وفي الحالتين، الخريطة هي مصدر الحقيقة الواحد: الأسماء مفاتيحها، والحمولات قيمها.
\ntype EventArgs<P> = [P] extends [undefined] ? [] : [payload: P];\ntype Handler = (payload: never) => void;\n\nclass Emitter<Events extends Record<string, unknown>> {\n #handlers = new Map<keyof Events, Set<Handler>>();\n\n on<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void): () => void {\n let set = this.#handlers.get(event);\n if (!set) {\n set = new Set();\n this.#handlers.set(event, set);\n }\n set.add(handler);\n return () => set.delete(handler);\n }\n\n emit<K extends keyof Events>(event: K, ...args: EventArgs<Events[K]>): void {\n for (const handler of this.#handlers.get(event) ?? []) {\n // Handlers for K were registered with a matching payload type in on().\n (handler as (payload: unknown) => void)(args[0]);\n }\n }\n}النمط هو نمط عميل الـ API، مطبَّقًا على الأحداث. يُستنتج K من اسم الحدث وله مهمة واحدة: البحث عن الحمولة في Events[K]. في on، يسري ذلك النوع إلى معامل الـ handler، فيُحدَّد نوع الـ callback من السياق. وفي emit، يفحص الحمولة التي تمرّرها.
const bus = new Emitter<CheckoutEvents>();\n\nconst off = bus.on('order.shipped', (e) => sendEmail(`Tracking: ${e.trackingNumber}`));\nbus.emit('order.shipped', { orderId: 1042, carrier: 'DHL', trackingNumber: '1Z-999' });\nbus.emit('checkout.opened'); // no payload needed\nbus.on('order.shiped', () => {});\n// Error: Argument of type '\"order.shiped\"' is not assignable to parameter of type 'keyof CheckoutEvents'.\nbus.emit('payment.failed', { orderId: 1042 });\n// Error: … Property 'reason' is missing …\noff(); // unsubscribeEventArgs هي حيلة معامل البقية الشرطي من الـ Conditional Types والتوزيع و infer: الأحداث التي لا حمولة لها لا تأخذ أي وسيط إضافي، والباقية تأخذ واحدًا بالضبط. والأقواس في [P] extends [undefined] توقف التوزيع، فيبقى نوع حمولة مثل string | undefined مطلوبًا بدل أن يُقسم.
لاحظ أين تعيش الأنواع الفضفاضة. داخل الصنف، تُخزَّن الـ handlers كـ Set<Handler> وتُستدعى عبر تحويل واحد مشروح بتعليق، لأن Map لا تستطيع التعبير عن “نوع القيمة يعتمد على المفتاح”. وفي الخارج، كل method دقيقة. هذا الفصل، أي تخزين بلا أنواع خلف واجهة محدَّدة الأنواع، هو طريقة بناء معظم المكتبات جيدة الأنواع. والحقل الخاص #handlers حقل خاص حقيقي في JavaScript، فلا يستطيع شيء من الخارج الوصول إليه وكسر الثابت.
حين يكون القلب محدَّد الأنواع، ترث الـ methods الجديدة الدقة شبه مجانًا. method باسم once تحلّ promise بالحمولة التالية تأخذ أربعة أسطر، ونتيجتها محدَّدة النوع لكل حدث دون تعليقات إضافية:
once<K extends keyof Events>(event: K): Promise<Events[K]> {\n return new Promise((resolve) => {\n const off = this.on(event, (payload) => { off(); resolve(payload); });\n });\n}\n\nconst shipped = await bus.once('order.shipped'); // { orderId; carrier; trackingNumber }هذا هو عائد وضع الأنواع في خريطة واحدة وتمرير K عبرها: كل method تضيفها تُفحص مقابل مصدر الحقيقة نفسه، ولا تكرّر أيٌّ منها نوع حمولة.
الـ builder (الباني) يسلسل استدعاءات methods لتجميع شيء خطوة بخطوة. والحيلة على مستوى الأنواع هي حمل ما بُني حتى الآن في معامل نوع، وإعادة نوع جديد أوسع من كل استدعاء. إليك builder استعلامات صغيرًا لسجل الطلبات في Cartwheel:
\ntype Order = { id: number; status: OrderStatus; totalCents: number; customer: string };\n\nclass OrderQuery<Selected extends keyof Order = never> {\n readonly #fields: readonly (keyof Order)[];\n\n constructor(fields: readonly (keyof Order)[] = []) {\n this.#fields = fields;\n }\n\n select<K extends keyof Order>(...fields: K[]): OrderQuery<Selected | K> {\n return new OrderQuery<Selected | K>([...this.#fields, ...fields]);\n }\n\n run(rows: Order[]): Pick<Order, Selected>[] {\n // #fields holds exactly the keys in Selected.\n return rows.map((row) => Object.fromEntries(this.#fields.map((f) => [f, row[f]])) as Pick<Order, Selected>);\n }\n}\n\nconst rows = new OrderQuery().select('id').select('totalCents').run(allOrders);\nrows[0].totalCents; // number\nrows[0].customer; // Error: Property 'customer' does not exist on type 'Pick<Order, \"id\" | \"totalCents\">'.يبدأ Selected بـ never (لا شيء مختار) وكل select تُعيد OrderQuery<Selected | K>. لا تستطيع الـ method تغيير نوع الكائن الذي تُستدعى عليه، فتُعيد كل خطوة نسخة جديدة. وهذا أيضًا تصميم جيد وقت التشغيل: البنّاؤون الذين لا يعدّلون أبدًا يمكن مشاركتهم وإعادة استخدامهم بأمان. وهي التقنية نفسها التي يستخدمها بنّاؤو الاستعلامات مثل Kysely وDrizzle على نطاق أكبر بكثير.
في التمرين ستبني ناقل الأحداث محدَّد الأنواع في Cartwheel وbuilder اختيار صغيرًا. وبه يكتمل قسم الأنماط؛ والقسم 5 ينتقل إلى إيصال كل هذا إلى الإنتاج، بدءًا بخيارات الـ compiler التي تجعل هذه الأنواع جديرة بالثقة.
\n","toc":[{"id":"sec-1","text":"خريطة واحدة، كل الأنواع","level":2},{"id":"sec-2","text":"الـ emitter محدَّد الأنواع","level":2},{"id":"sec-3","text":"بنّاؤون يكبر نوعهم","level":2}],"takeaways":["نوع خريطة الأحداث ({ 'order.shipped': { orderId: number } }) هو مصدر الحقيقة الواحد لأسماء الأحداث وأنواع حمولاتها معًا.","on<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void) تربط معامل الـ handler باسم الحدث الذي يمرّره المستدعي.","معامل البقية الشرطي يتيح إطلاق الأحداث التي لا حمولة لها دون وسيط وهمي.","يستطيع الـ builder حمل الحالة في معامل نوع، مُعيدًا نوعًا جديدًا أوسع من كل استدعاء، فيعكس نوع النتيجة النهائي كل خطوة.","أبقِ التخزين غير محدَّد الأنواع داخل الصنف والأنواع الدقيقة على methods العامة، كي يعيش التحويل الوحيد في مكان واحد."],"further":[{"title":"Generic Classes","url":"https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-classes"},{"title":"Classes (this-based types and parameter properties)","url":"https://www.typescriptlang.org/docs/handbook/2/classes.html"},{"title":"Rest parameters with tuple types (TypeScript 3.0 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-0.html"}],"quiz":[{"q":"مع bus = new Emitter<CheckoutEvents>()، ما نوع p؟
type CheckoutEvents = {\n 'order.shipped': { orderId: number; carrier: string };\n 'payment.failed': { orderId: number; reason: string };\n};\nbus.on('payment.failed', (p) => console.log(p.reason));CheckoutEvents[keyof CheckoutEvents]، الـ union من الحمولتين","why":"هذا ما سيحدث لو كان نوع اسم الحدث keyof Events دون معامل نوع. أما K فيلتقط الاسم المحدّد."},{"text":"unknown، لأن الـ handlers مخزّنة في Map بلا أنواع","why":"طريقة تخزين الـ handlers تفصيل في التنفيذ؛ التوقيع العام هو ما يحدّد ما يراه المستدعون."},{"text":"any، لأن الـ callbacks تُحدَّد أنواعها من السياق","why":"تحديد النوع من السياق يعطي p نوع المعامل من التوقيع، وهو دقيق هنا."},{"text":"{ orderId: number; reason: string }","why":"صحيح. يُستنتج K على أنه 'payment.failed'، ومعامل الـ handler هو CheckoutEvents[K]."}],"answer":3},{"q":"لماذا نحدّد نوع emit بـ ...args: EventArgs<Events[K]> بدل payload: Events[K]؟
undefined هكذا emit('checkout.opened') دون وسيط ثانٍ.","why":"صحيح. ينتج الشرط tuple فارغًا للأحداث التي لا حمولة لها، وtuple من عنصر واحد في غير ذلك."},{"text":"لأن معاملات البقية أسرع وقت التشغيل.","why":"الاختيار يتعلّق بتوقيع النوع؛ والفرق وقت التشغيل لا يُذكر."},{"text":"لأن Events[K] لا يمكن استخدامها نوعًا لمعامل.","why":"يمكن ذلك؛ on تستخدمها لمعامل الـ handler. صيغة البقية تحلّ فقط حالة الحمولة الغائبة."}],"answer":0},{"q":"ما نوع rows؟
const rows = new OrderQuery().select('id').select('totalCents').run(allOrders);Order[]، لأن run تُعيد دائمًا طلبات كاملة","why":"في هذا الـ builder تُعيد run النوع Pick<Order, Selected>[]، وSelected كبر مع كل استدعاء."},{"text":"Pick<Order, 'id' | 'totalCents'>[]","why":"صحيح. كل select تُعيد OrderQuery<Selected | K>، فيراكم معامل النوع الحقلين كليهما."},{"text":"Pick<Order, 'totalCents'>[]، لأن الاستدعاء الثاني يستبدل الأول","why":"الاستدعاء الثاني يوسّع Selected بـ union؛ لا يستبدله."}],"answer":1},{"q":"لماذا يُعيد كل استدعاء لـ select كائن OrderQuery جديدًا بدل تعديل this وإعادته؟
this من الـ methods.","why":"يمكنها ذلك؛ والـ APIs المتسلسلة تفعله كثيرًا. المشكلة فيما يستطيع نوع this التعبير عنه."},{"text":"لأن الـ method لا تستطيع تغيير نوع الكائن الذي تُستدعى عليه، فيحتاج النوع الأوسع إلى قيمة جديدة.","why":"صحيح. this يحتفظ بنوعه طوال حياته؛ وإعادة نسخة جديدة بمعامل نوع جديد هي الطريقة التي يكبر بها النوع."},{"text":"لأن التعديل غير مسموح في أصناف TypeScript.","why":"يسمح TypeScript بالتعديل بحرية؛ هذا قيد في تحديد الأنواع، لا قاعدة في اللغة."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus; totalCents: number; customer: string };\n\nconst ORDERS: Order[] = [\n { id: 1042, status: 'shipped', totalCents: 18900, customer: 'Mona' },\n { id: 1043, status: 'processing', totalCents: 4500, customer: 'Karim' },\n];\n\nclass Emitter = [P] extends [undefined] ? [] : [payload: P];\ntype Handler = (payload: never) => void;\n\nclass Emitter اجعل الأداتين في Cartwheel محدَّدتي الأنواع بالكامل دون تغيير سلوكهما وقت التشغيل: أبقِ أي تحويل داخل الصنفين، في مكان واحد مشروح بتعليق لكلٍّ منهما. خريطة الأحداث هي المكان الوحيد الذي تُكتب فيه أنواع الحمولات؛ يُستنتج \n
\nEmitter<Events>: يجب ألّا تقبل on(event, handler) إلا أسماء أحداث من Events وأن تعطي الـ handler نوع حمولة ذلك الحدث؛ ويجب أن تفحص emit(event, payload) الحمولة، وأن تُطلَق الأحداث التي حمولتها undefined دون وسيط حمولة.OrderQuery: كل استدعاء لـ select(...fields) يضيف إلى الحقول المختارة، وrun(rows) تُعيد Pick<Order, …>[] من الحقول المختارة بالضبط.on وemit معامل نوع K extends keyof Events وابحث عن الحمولة بـ Events[K]. وقيّد الصنف: Emitter<Events extends Record<string, unknown>>.","للأحداث التي لا حمولة لها، استخدم معامل بقية شرطيًا: type EventArgs<P> = [P] extends [undefined] ? [] : [payload: P]; وemit<K …>(event: K, ...args: EventArgs<Events[K]>).","أعطِ OrderQuery معامل نوع Selected extends keyof Order = never؛ تُعيد select<K extends keyof Order>(...fields: K[]) القيمة new OrderQuery<Selected | K>(…)، وتُعيد run النوع Pick<Order, Selected>[] بتحويل واحد."],"explanation":"K من اسم الحدث ويربطه بـ Events[K] للـ handler وللحمولة معًا. معامل البقية الشرطي ينتج صفرًا من الوسائط للحمولات undefined، والأقواس تمنعه من التوزيع على الـ unions. وفي الداخل، لا تستطيع Map ربط المفاتيح بأنواع القيم، فتُخزَّن الـ handlers بشكل فضفاض وتُستدعى عبر تحويل واحد. أما الـ builder فيحمل المفاتيح المختارة في معامل نوعه: كل select تُعيد نسخة جديدة بـ union أوسع، وتحوّل run ذلك الـ union إلى Pick.emit تستدعي فقط الـ handlers الخاصة بذلك الحدث، مع الحمولة","unsubscribes":"الدالة التي تُعيدها on تُزيل الـ handler","selects":"run تُعيد الحقول المختارة فقط، عبر عدة استدعاءات لـ select"}},"words":594,"readMinutes":3}