في الدرس السابق كتبت sortByTotal(orders) فاستنتج TypeScript أن T هو DetailedOrder. في معظم الأحيان يفعل الـ inference (استنتاج النوع) ما تريده، ولهذا تبدو المرات التي لا يفعل فيها عشوائية. لكنها ليست كذلك. يتبع TypeScript مجموعة صغيرة من القواعد، وحين تعرفها تستطيع تصميم توقيعات تستنتج بالضبط النوع الذي تقصده، دون أي <…> في موضع الاستدعاء.
كل موضع يظهر فيه معامل النوع داخل نوع معامل هو موقع استنتاج (inference site). عند الاستدعاء، يطابق TypeScript كل وسيط مع نوع معامله، ويجمع مرشّحًا (candidate) لمعامل النوع من كل موقع. ثم يختار نوعًا واحدًا من بين المرشّحين.
\nfunction same<T>(a: T, b: T): T[] {\n return [a, b];\n}\n\nsame('processing', 'shipped'); // T = string, so string[]\nsame(1, 'a');\n// Error: Argument of type 'string' is not assignable to parameter of type 'number'.مع قيمتين نصيتين حرفيتين، يُدمج المرشّحان 'processing' و'shipped' ثم يتّسعان إلى string، لأن T لا يُعاد إلا داخل مصفوفة (يشرح القسم التالي متى تنجو القيم الحرفية). أما مع 1 و'a'، فلا يخترع TypeScript النوع number | string؛ بل يختار المرشّح الأول، number، فيفشل الوسيط الثاني أمامه. وهذا مقصود. فالاتساع الصامت إلى union سيُخفي الأخطاء التي وُجدت الـ generics لالتقاطها. إن أردت قيمًا مختلطة فعلًا، فقلها صراحة: same<number | string>(1, 'a').
القاعدة الثانية تفسّر معظم لحظات “لماذا حصلت على string؟”. المرشّح الحرفي مثل 'processing' يُحتفظ به أو يُوسَّع حسب التوقيع:
function identity<T>(value: T): T { return value; }\nfunction box<T>(value: T): { value: T } { return { value }; }\nfunction boxStatus<T extends string>(value: T): { value: T } { return { value }; }\n\nconst a = identity('processing'); // 'processing'\nconst b = box('processing'); // { value: string }\nconst c = boxStatus('processing'); // { value: 'processing' }تنجو القيمة الحرفية حين يُعاد T مباشرة في المستوى الأعلى (identity)، أو حين يتضمّن قيد T نوعًا أوليًا مثل string (boxStatus). وإلا فإنها تتّسع، بناءً على افتراض أن القيمة المخبّأة داخل كائن سيُعاد الإسناد إليها غالبًا لاحقًا.
الكائنات تتبع المنطق نفسه، وهنا للقيد فائدة ثانية: يعطي الوسيطَ نوعًا سياقيًا (contextual type).
\ntype OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\n\nfunction draft<T>(order: T): T { return order; }\nfunction draftOrder<T extends { status: OrderStatus }>(order: T): T { return order; }\n\ndraft({ status: 'processing' }); // { status: string }\ndraftOrder({ status: 'processing' }); // { status: 'processing' }لأن القيد يقول إن status من نوع OrderStatus، يفحص TypeScript القيمة الحرفية مقابل ذلك الـ union أثناء الاستنتاج، فيثبت النوع الحرفي. القيد الجيد يوثّق الدالة ويحسّن ما تستنتجه في آنٍ واحد.
أحيانًا تريد وسيط المستدعي كما كُتب بالضبط: ترتيب الـ tuple، والقيم الحرفية، والكائنات المتداخلة. قبل TypeScript 5.0 كان ذلك يعني أن تطلب من كل مستدعٍ أن يكتب as const. أما الآن فيمكن للدالة أن تطلب ذلك بنفسها:
function defineFlow<const T extends readonly OrderStatus[]>(steps: T): T {\n return steps;\n}\n\nconst happyPath = defineFlow(['processing', 'shipped', 'delivered']);\n// readonly ['processing', 'shipped', 'delivered']المعدِّل const يطلب من TypeScript أن يستنتج الوسيط كأنه مكتوب مع as const: القيم الحرفية تبقى حرفية، والمصفوفات تصبح tuples للقراءة فقط، وخصائص الكائنات تصبح للقراءة فقط. اقرنه بقيد مصفوفة readonly، لأن as const تنتج مصفوفات للقراءة فقط. ولا يؤثّر إلا في القيم الحرفية المكتوبة مباشرة في الاستدعاء؛ أما المتغيّر الذي تمرّره فيحتفظ بأي نوع كان له أصلًا.
الوسائط التي هي دوال بمعاملات غير معلَّقة، مثل (d) => d.totalCents، حسّاسة للسياق (context-sensitive): أنواع معاملاتها تأتي من التوقيع، الذي قد يعتمد بدوره على T. يستنتج TypeScript من كل ما عداها أولًا، ثم يحدّد أنواع هذه الـ callbacks. وداخل الكائن الحرفي الواحد، يمرّ على الخصائص الحسّاسة للسياق من اليسار إلى اليمين:
function createStep<T>(config: { load: (orderId: number) => T; render: (data: T) => string }) {}\n\ncreateStep({\n load: (orderId) => ({ orderId, totalCents: 4500 }),\n render: (d) => d.totalCents.toFixed(), // d: { orderId: number; totalCents: number }\n});\n\ncreateStep({\n render: (d) => d.totalCents.toFixed(), // Error: 'd' is of type 'unknown'.\n load: (orderId) => ({ orderId, totalCents: 4500 }),\n});حين تأتي render أولًا، لا يكون لـ T أي مرشّح بعد. يمكنك الإصلاح في موضع الاستدعاء بتبديل الخاصيتين أو بتعليق orderId: number، فلا تعود load حسّاسة للسياق. والأفضل أن تُصلحه في الـ API نفسه: ضع المنتِج قبل المستهلِك في قوائم المعاملات وفي الأمثلة الموثّقة، كي تكون الطريقة الطبيعية لاستدعائها هي الطريقة التي تستنتج.
في التمرين ستجعل ثلاث دوال مساعدة في Cartwheel تحتفظ بالقيم الحرفية التي يمرّرها مستدعوها. وبعده ستتعلّم كيف تمنع الـ inference من الحدوث حيث لا ينبغي.
\n","toc":[{"id":"sec-1","text":"مواقع الاستنتاج والمرشّحون","level":2},{"id":"sec-2","text":"متى تتّسع القيم الحرفية","level":2},{"id":"sec-3","text":"معاملات النوع const","level":2},{"id":"sec-4","text":"الـ callbacks تُستنتج أخيرًا","level":2}],"takeaways":["كل موضع يظهر فيه معامل النوع داخل نوع معامل هو موقع استنتاج؛ يجمع TypeScript مرشّحًا من كل وسيط ثم يختار نوعًا واحدًا.","تتّسع القيم الحرفية المستنتَجة ما لم يتضمّن قيد معامل النوع نوعًا أوليًا أو يُعرَّف المعامل بـconst.","معامل النوع const يستنتج الوسائط كأنها مكتوبة مع as const، فيحتفظ بالقيم الحرفية والـ tuples للقراءة فقط دون أن يطلب ذلك من المستدعي.","الـ callbacks ذات المعاملات غير المعلَّقة تُستنتج بعد الوسائط الأخرى، وداخل الكائن الحرفي الواحد يعمل TypeScript من اليسار إلى اليمين.","وسائط النوع الصريحة إمّا كلها أو لا شيء؛ حدّد واحدًا فيتوقّف TypeScript عن استنتاج البقية."],"further":[{"title":"Type Inference","url":"https://www.typescriptlang.org/docs/handbook/type-inference.html"},{"title":"const type parameters (TypeScript 5.0 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html"}],"quiz":[{"q":"ما نوع b؟
function box<T>(value: T): { value: T } { return { value }; }\nconst b = box('processing');{ value: 'processing' }","why":"هذا ما ستحصل عليه مع T extends string أو مع معامل نوع const. أما T غير المقيَّد والمتداخل في نوع الإرجاع فيتّسع."},{"text":"{ value: string }","why":"صحيح. يتّسع المرشّح الحرفي لأن T ليس له قيد أولي ولا يُعاد في المستوى الأعلى."},{"text":"{ value: unknown }","why":"unknown هو ما يلجأ إليه TypeScript حين لا يجد أي مرشّح إطلاقًا. وهنا وجد واحدًا: الوسيط النصي."}],"answer":1},{"q":"أيّ تعريف يجعل defineFlow(['processing', 'shipped']) تُعيد النوع readonly ['processing', 'shipped'] دون أن يكتب المستدعي as const؟
function defineFlow<T>(steps: T[]): T[]","why":"هذا يستنتج T على أنه string ويُعيد string[]؛ فيضيع الترتيب والقيم الحرفية معًا."},{"text":"function defineFlow<T extends string>(steps: T[]): T[]","why":"القيد يحتفظ بالقيم الحرفية، لكنك تحصل على نوع المصفوفة ('processing' | 'shipped')[]، لا على tuple للقراءة فقط."},{"text":"function defineFlow<const T extends readonly string[]>(steps: T): T","why":"صحيح. المعدِّل const يستنتج الوسيط كأنه مكتوب مع as const، فتحصل على tuple للقراءة فقط من القيم الحرفية."},{"text":"function defineFlow(steps: readonly string[]): readonly string[]","why":"دون معامل نوع لا يوجد ما يلتقط النوع الدقيق للوسيط."}],"answer":2},{"q":"لماذا نوع d هنا هو unknown؟
createStep({\n render: (d) => d.totalCents.toFixed(),\n load: (orderId) => ({ orderId, totalCents: 4500 }),\n});render تأتي قبل load، ويستنتج TypeScript الدوال الحسّاسة للسياق في الكائن الحرفي من اليسار إلى اليمين.","why":"صحيح. حين تُفحص render، لا يكون لـ T أي مرشّح بعد. ضع load أولًا، أو علّق orderId بنوعه كي لا تكون load حسّاسة للسياق."},{"text":"لأن T لا يمكن استنتاجه من نوع إرجاع.","why":"يمكن ذلك؛ نوع إرجاع load هو موقع الاستنتاج لـ T. المشكلة في توقيت زيارة ذلك الموقع."},{"text":"لأن الدوال السهمية في الكائنات الحرفية تعطّل الـ inference.","why":"الـ inference يعمل جيدًا في الكائنات الحرفية؛ تبديل الخاصيتين يجعل هذا يمرّ في الترجمة."}],"answer":0},{"q":"تُستدعى function convert<From, To>(value: From, to: (v: From) => To): To هكذا: convert<string>('12', Number). ماذا يحدث؟
To على أنه number من Number.","why":"لا يقوم TypeScript بالاستنتاج الجزئي. ما إن تمرّر أي وسيط نوع صريح حتى يتوقّع كل الوسائط المطلوبة."},{"text":"خطأ، “Expected 2 type arguments, but got 1”.","why":"صحيح. وسائط النوع الصريحة إمّا كلها أو لا شيء، ما لم تكن للمعاملات المتبقّية قيم افتراضية."},{"text":"يصبح To هو unknown، ويمرّ الاستدعاء في الترجمة.","why":"وسائط النوع الناقصة لا تلجأ إلى قيمة بديلة بصمت إلا إذا كانت لها قيم افتراضية. ودون ذلك يُرفض الاستدعاء."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Flag = { rollout: number; countries: readonly string[] };\n\nfunction defineFlow(steps: OrderStatus[]) {\n return steps;\n}\n\nfunction oneOf(values: readonly string[]) {\n return (input: string): boolean => values.includes(input);\n}\n\nfunction defineFlags(flags: Recordثلاث دوال تعريف مساعدة في نظام الدفع في Cartwheel تُضيّع الأنواع الدقيقة التي يكتبها مستدعوها. اجعل اختبارات الأنواع تنجح دون تغيير الاستدعاءات (بلا as const في مواضع الاستدعاء):
defineFlow(steps) تُعيد الخطوات كـ tuple للقراءة فقط من الحالات الحرفية، وتبقى ترفض الحالات المجهولة.oneOf(values) تُعيد type guard: بعد if (isChannel(raw)) يضيق raw إلى القيم الحرفية الممرَّرة.defineFlags(flags) تحتفظ بالشكل الدقيق لكل علم (بما فيه الـ tuple المسمّى countries) مع فحص كل علم مقابل Flag.الدوال الثلاث تُعيد وسيطها دون تغيير وقت التشغيل (وoneOf تُعيد دالة فحص).
const يستنتج الوسيط كأن المستدعي كتب as const.","أعطِ كل دالة معامل نوع قيده هو نوع المعامل القديم، مثلًا <const T extends readonly OrderStatus[]>(steps: T): T.","في oneOf، نوع إرجاع الدالة المُعادة هو type predicate: (input: string): input is T[number] => …. وفي داخلها، وسّع الـ tuple من أجل includes: (values as readonly string[]).includes(input)."],"explanation":"دون معامل نوع، يكون نوع إرجاع كل دالة مجرّد التعليق النوعي على معاملها، فتضيع القيم الحرفية التي كتبها المستدعي. معامل النوع const يلتقط الوسيط بدلالة as const: الـ tuples تبقى مرتّبة وللقراءة فقط، والنصوص تبقى حرفية. والقيد (extends readonly OrderStatus[] وextends Record<string, Flag>) ما زال يتحقّق من الوسيط، فتُرفض 'refunded' والعلم الذي ليس فيه rollout. وفي oneOf، T[number] هو الـ union من عناصر الـ tuple، والـ type predicate يسلّم ذلك الـ union إلى جملة if لدى المستدعي.
oneOf تُعيد دالة لا تقبل إلا القيم المدرَجة","identity":"defineFlow وdefineFlags تُعيدان وسيطهما دون تغيير"}},"words":650,"readMinutes":4}