إليك دالة مساعدة من صفحة سجل الطلبات في Cartwheel. أنواعها محدّدة، وتمرّ في الترجمة، وترمي المعلومات بهدوء:
\ntype DetailedOrder = { id: number; totalCents: number; customer: string };\n\nfunction sortByTotal(orders: { totalCents: number }[]): { totalCents: number }[] {\n return [...orders].sort((a, b) => a.totalCents - b.totalCents);\n}\n\ndeclare const orders: DetailedOrder[];\nconst sorted = sortByTotal(orders);\nsorted[0].customer;\n// Error: Property 'customer' does not exist on type '{ totalCents: number; }'.الكائنات في sorted ما زالت طلبات كاملة وقت التشغيل. لكن توقيع الدالة لا يستطيع وصف مخرجها إلا من خلال التعليق النوعي على مدخلها، وهذا التعليق لا يذكر إلا totalCents. والإصلاح ليس تعليقًا أوسع، بل علاقة: “أيًّا كان نوع الكائن الذي تعطيني إياه، ستحصل على النوع نفسه”.
هذه العلاقة هي ما يقوله الـ generic:
\nfunction sortByTotal<T extends { totalCents: number }>(orders: T[]): T[] {\n return [...orders].sort((a, b) => a.totalCents - b.totalCents);\n}\n\nconst sorted = sortByTotal(orders); // DetailedOrder[]\nsorted[0].customer; // stringاقرأ التوقيع بصوت عالٍ: “لنوعٍ ما T فيه totalCents رقمية، خذ مصفوفة من T وأعِد مصفوفة من T”. المستدعي لا يكتب <DetailedOrder>؛ يستنتج TypeScript قيمة T من الوسيط (والدرس القادم يشرح كيف بالضبط).
جزءان يقومان بالعمل. T يظهر في المعامل وفي نوع الإرجاع، فيربط بينهما. وextends { totalCents: number } هو constraint (قيد): يحدّ من الأنواع التي يمكن أن يكونها T، وهذا ما يجعل a.totalCents مشروعة داخل الدالة. دونه قد يكون T أي شيء، وسيرفض TypeScript الوصول إلى الخاصية.
أنفع اختبار للـ generic، وهو ما أطبّقه في كل مراجعة كود: يجب أن يظهر كل معامل نوع مرتين على الأقل. مرة ليلتقط نوعًا، ومرة ليستخدمه في مكان آخر.
\nfunction lastItem<T>(items: T[]): T | undefined { // input → output\n return items[items.length - 1];\n}\n\nfunction indexById<T extends { id: number }>(items: T[]): Map<number, T> {\n return new Map(items.map((item) => [item.id, item]));\n}\n\nfunction merge<A, B>(a: A, b: B): A & B { // two inputs → output\n return { ...a, ...b };\n}المعامل الذي يظهر مرة واحدة لا يربط شيئًا. function log<T>(value: T): void هي ببساطة function log(value: unknown): void مع صياغة زائدة، وfunction count<T>(items: T[]): number هي items: unknown[]. احذف معاملات النوع هذه؛ تصبح التوقيعات أسهل قراءة ولا تخسر شيئًا.
هذا الخطأ يربك الجميع تقريبًا في المرة الأولى:
\ntype Shippable = { weightGrams: number };\n\nfunction withDefaultWeight<T extends Shippable>(): T {\n return { weightGrams: 500 };\n // Error: Type '{ weightGrams: number; }' is not assignable to type 'T'.\n // '{ weightGrams: number; }' is assignable to the constraint of type 'T', but 'T'\n // could be instantiated with a different subtype of constraint 'Shippable'.\n}القيد يقول إن T على الأقل Shippable. قد يطلب المستدعي withDefaultWeight<{ weightGrams: number; sku: string }>()، وقيمتك الحرفية ليس فيها sku. داخل الدالة الـ generic، T نوعٌ لا تختاره أنت؛ لا يمكنك إنتاج T إلا من قيم هي T أصلًا، مثل الوسائط. وإن كانت دالتك تبني القيمة بنفسها، فنوع إرجاعها هو القيد (Shippable)، ولا حاجة إلى generic.
يمكن أن يشير القيد إلى معامل نوع آخر. المثال الكلاسيكي يختار خاصية باسمها:
\nfunction pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {\n return items.map((item) => item[key]);\n}\n\nconst customers = pluck(orders, 'customer'); // string[]\npluck(orders, 'email');\n// Error: Argument of type '\"email\"' is not assignable to parameter of type 'keyof DetailedOrder'.keyof T هو الـ union من أسماء خصائص T، وT[K] هو نوع الخاصية K. ستفكّك الاثنين في القسم 3؛ أما الآن فلاحظ النمط. K يظهر في المعامل وفي نوع الإرجاع، وقيده يربطه بـ T. كل معامل يظهر مرتين على الأقل، وكلٌّ منهما يستحق مكانه.
ليست كل دالة تقبل عدة أنواع بحاجة إلى معامل نوع. اسأل سؤالًا واحدًا: هل يعتمد نوع المخرج على نوع المدخل الذي مرّره المستدعي؟
\n// Output is always a number, whatever came in: a union is enough.\nfunction toCents(amount: number | string): number {\n return Math.round(Number(amount) * 100);\n}\n\n// Output depends on the input: a generic says so.\nfunction firstOrThrow<T>(items: T[]): T {\n if (items.length === 0) throw new Error('Expected at least one item');\n return items[0];\n}toCents تُعيد number مهما كان المدخل، فجعلها toCents<T extends number | string>(amount: T): number سيضيف معاملًا يظهر مرة واحدة ولا يربط شيئًا. وfirstOrThrow عكسها: قائمة طلبات يجب أن تُعيد طلبًا، وقائمة منتجات تُعيد منتجًا. أما توقيع الـ union (items: unknown[]): unknown) فسيُجبر كل مستدعٍ على التحويل.
حين لا تكون متأكّدًا، ابدأ دون الـ generic. إذا بدأ المستدعون يكتبون as على النتيجة، فتلك إشارة إلى أن المخرج يعتمد على المدخل، وأن معامل نوع سيُزيل تلك التحويلات.
في التمرين ستحوّل أربع دوال مساعدة تُضيّع المعلومات إلى دوال generic تحتفظ بأنواع المستدعي. والدرس القادم ينظر في كيف يقرّر TypeScript ما هو T حين لا يقوله المستدعي.
T extends { totalCents: number } تتيح للدالة استخدام totalCents مع إعادة النوع الكامل والأكثر تحديدًا الذي مرّره المستدعي.","الـ generic الذي لا يظهر إلا في نوع الإرجاع، مثل parse<T>(text): T، هو تحويل غير مفحوص بصياغة أجمل.","المستدعي هو من يختار T لا الدالة، ولهذا لا يمكنك إعادة كائن حرفي حيث يُنتظر T."],"further":[{"title":"Generics","url":"https://www.typescriptlang.org/docs/handbook/2/generics.html"},{"title":"More on Functions (generic functions and constraints)","url":"https://www.typescriptlang.org/docs/handbook/2/functions.html#generic-functions"}],"quiz":[{"q":"ما نوع sorted؟
type DetailedOrder = { id: number; totalCents: number; customer: string };\ndeclare const orders: DetailedOrder[];\nfunction sortByTotal(xs: { totalCents: number }[]) { return [...xs].sort((a, b) => a.totalCents - b.totalCents); }\nconst sorted = sortByTotal(orders);DetailedOrder[]، لأن المصفوفة تحتوي قيمًا من نوع DetailedOrder","why":"القيم ما زالت طلبات كاملة وقت التشغيل، لكن نوع الإرجاع يُحسب من نوع المعامل، الذي لا يعرف إلا totalCents."},{"text":"{ totalCents: number }[]، فيكون sorted[0].customer خطأً","why":"صحيح. دون معامل نوع، لا تملك الدالة طريقة لتقول “أُعيد لك النوع نفسه الذي أعطيتني إياه”."},{"text":"any[]، لأن sort تُعيد any","why":"sort تُعيد نوع عناصر المصفوفة نفسها. وفقدان المعلومات سببه التعليق النوعي على المعامل."}],"answer":1},{"q":"أيّ هذه التوقيعات يستخدم معامل النوع بطريقة تضيف أمانًا حقيقيًا في الأنواع؟
","options":[{"text":"function log<T>(value: T): void","why":"T يظهر مرة واحدة، فلا يربط شيئًا. value: unknown تقول الشيء نفسه بصدق أكبر."},{"text":"function parse<T>(json: string): T","why":"T لا يظهر إلا في نوع الإرجاع، فيختار المستدعي أي نوع ولا شيء يفحصه. إنه تحويل متنكّر."},{"text":"function lastItem<T>(items: T[]): T | undefined","why":"صحيح. T يظهر في المدخل والمخرج رابطًا بينهما، فيحصل المستدعي بالضبط على نوع العنصر الذي مرّره."},{"text":"function count<T>(items: T[]): number","why":"T لا يظهر إلا مرة واحدة في موضع ذي أهمية؛ وitems: unknown[] تعمل بالطريقة نفسها تمامًا."}],"answer":2},{"q":"لماذا يُعدّ هذا خطأً؟
\nfunction emptyCart<T extends { items: string[] }>(): T {\n return { items: [] };\n}[] تُستنتج على أنها never[].","why":"never[] قابلة للإسناد إلى string[]. المشكلة في العلاقة بين القيمة الحرفية وT."},{"text":"لأن الدوال الـ generic لا يمكنها إعادة كائنات حرفية.","why":"يمكنها ذلك، حين يكون نوع القيمة الحرفية هو ما يقوله نوع الإرجاع. هنا نوع الإرجاع هو T الخاص بالمستدعي، وأنت لا تعرفه."},{"text":"لأن المستدعي يختار T، الذي قد يكون { items: string[]; owner: string }، وقيمتك الحرفية ليس فيها owner.","why":"صحيح. يقول الخطأ إن T قد يُجسَّد بنوع فرعي مختلف من القيد. أعِد نوع القيد بدلًا من ذلك."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"function sortByTotal(orders: { totalCents: number }[]): { totalCents: number }[] {\n return [...orders].sort((a, b) => a.totalCents - b.totalCents);\n}\n\nfunction indexById(items: { id: number }[]): Mapهذه الدوال المساعدة الأربع من صفحة سجل الطلبات في Cartwheel تعمل وقت التشغيل لكنها تُضيّع معلومات الأنواع. اجعل كل واحدة منها generic حتى تنجح اختبارات الأنواع:
\nsortByTotal تُعيد نسخة مرتّبة نوعها هو نوع عنصر المستدعي، وتبقى ترفض الكائنات التي ليس فيها totalCents.indexById تُعيد Map من المعرّف إلى نوع عنصر المستدعي.pluck(items, key) لا تقبل إلا أسماء خصائص حقيقية، وتُعيد مصفوفة من نوع تلك الخاصية.lastItem تُعيد العنصر الأخير، بنوع العنصر أو undefined.أبقِ السلوك وقت التشغيل كما هو، ولا تستخدم any أو as.
extends: <T extends { totalCents: number }> تتيح لك قراءة totalCents مع إعادة T[].","في pluck، استخدم معاملَي نوع: <T, K extends keyof T>(items: T[], key: K): T[K][]."],"explanation":"صار كل معامل نوع يظهر مرتين على الأقل، رابطًا المدخل بالمخرج، فيحصل المستدعي بالضبط على نوع العنصر الذي مرّره. القيود (extends { totalCents: number } وextends { id: number }) هي ما يجعل قراءة الخصائص مشروعة داخل الدوال، وهي أيضًا ما يرفض [{ sku: 'TENT-2P' }]. وفي pluck، تربط K extends keyof T المفتاح بالعناصر، وتبحث T[K] عن نوع تلك الخاصية، فتعطي 'customer' النوع string[] وتُرفض 'email'.
sortByTotal ترتّب تصاعديًا دون تعديل مدخلها","indexes":"indexById تربط كل معرّف بعنصره","plucks":"pluck وlastItem ما زالتا تعملان وقت التشغيل"}},"words":627,"readMinutes":4}