إليك دالة مساعدة من نظام الدفع في Cartwheel. تبدو آمنة، وفيها ثغرة:
\nfunction applyCoupon<C extends string>(available: C[], code: C) {\n // …\n}\n\napplyCoupon(['WELCOME10', 'LOYAL5'], 'WELCOM10'); // compilesالنية واضحة: يجب أن يكون code واحدًا من الكوبونات المتاحة. لكن C يظهر في المعاملين كليهما، وكما رأيت في الدرس السابق، كل ظهور موقعُ استنتاج. يجمع TypeScript القيم 'WELCOME10' و'LOYAL5' و'WELCOM10' كمرشّحين، ويجعل C هو الـ union من الثلاثة، فيجتاز كل شيء فحص الأنواع. لم يُفحص الخطأ الإملائي مقابل القائمة؛ بل أُضيف إليها.
أضاف TypeScript 5.4 النوع المدمج NoInfer<T>. يُحَلّ إلى T العادي، لكنه يجعل ذلك الموضع محظورًا على الـ inference:
function applyCoupon<C extends string>(available: C[], code: NoInfer<C>) {\n // …\n}\n\napplyCoupon(['WELCOME10', 'LOYAL5'], 'WELCOM10');\n// Error: Argument of type '\"WELCOM10\"' is not assignable to parameter of type '\"WELCOME10\" | \"LOYAL5\"'.الآن يُستنتج C من available وحدها، ويُفحص code مقابل النتيجة. يظهر هذا النمط كلما كان أحد الوسائط يعرّف مجموعة وعلى وسيط آخر أن يختار منها: حالة ابتدائية يجب أن تكون إحدى الحالات المعرَّفة، أو قيمة افتراضية يجب أن تطابق الخيارات، أو مفتاح ترتيب يجب أن يكون أحد الأعمدة المدرَجة.
function createMachine<S extends string>(config: { states: S[]; initial: NoInfer<S> }) {\n return config;\n}\n\ncreateMachine({ states: ['cart', 'shipping', 'payment'], initial: 'cart' }); // ok\ncreateMachine({ states: ['cart', 'shipping', 'payment'], initial: 'checkout' }); // errorقبل 5.4، كان الحل البديل معامل نوع ثانيًا مقيَّدًا بالأول، <C extends string, D extends C>(available: C[], code: D). هذا يعمل، وستراه في المكتبات القديمة، لكنه يضيف معاملًا لا وجود له إلا للتهرّب من الاستنتاج. استخدم NoInfer في الكود الجديد. فهي توثّق النية أيضًا: القارئ الذي يرى initial: NoInfer<S> يعرف من النظرة الأولى أيّ وسيط هو مصدر الحقيقة وأيّها يُفحص فقط، وهذا ما لم توضّحه حيلة المعاملين أبدًا.
يمكن أن تكون لمعامل النوع قيمة افتراضية، تُستخدم حين لا يوجد ما يُستنتج منه:
\ntype ApiResponse<T = unknown> = { data: T; requestId: string };\n\nasync function request<TRes = unknown, TBody = undefined>(path: string, body?: TBody): Promise<TRes> {\n const res = await fetch(path, { method: body === undefined ? 'GET' : 'POST', body: JSON.stringify(body) });\n return res.json();\n}أمران يجعلان القيم الافتراضية مفيدة. أولًا، ApiResponse وحدها تعني الآن ApiResponse<unknown>، وهي قيمة افتراضية آمنة: على المستدعين تضييق data قبل استخدامها. ثانيًا، القيم الافتراضية تجعل وسائط النوع الصريحة الجزئية مشروعة. دونها كانت request<Order>('/orders/1042') ستفشل مع “Expected 2 type arguments”؛ ومعها يرجع TBody إلى undefined.
اختر قيمًا افتراضية آمنة لا مريحة. unknown قيمة افتراضية جيدة للبيانات القادمة من الخارج؛ أما any فلا، لأنها تُطفئ الفحص بصمت لكل من ينسى وسيط النوع. (ولاحظ أن request<Order> ما زالت تحويلًا متنكّرًا: جسم الاستجابة لا يُفحص. ستُصلح ذلك كما ينبغي في الدرس القادم وفي تحليل البيانات غير الموثوقة عند الحدود.)
أحيانًا يحدّد نوعُ الوسيط نوعَ النتيجة. الـ overloads (التحميل الزائد) تصف ذلك مباشرة:
\nfunction formatPrice(cents: number): string;\nfunction formatPrice(cents: number[]): string[];\nfunction formatPrice(cents: number | number[]): string | string[] {\n return Array.isArray(cents) ? cents.map(toDollars) : toDollars(cents);\n}\n\nfunction toDollars(cents: number): string {\n return `$${(cents / 100).toFixed(2)}`;\n}\n\nconst one = formatPrice(4500); // string\nconst many = formatPrice([4500, 1299]); // string[]السطران الأولان هما توقيعا الـ overload اللذان يراهما المستدعون. والثالث هو توقيع التنفيذ، الذي يجب أن يتوافق معها جميعًا وهو غير مرئي من الخارج. يجرّب TypeScript الـ overloads من الأعلى إلى الأسفل ويستخدم أول واحد يطابق، فضع الأكثر تحديدًا أولًا.
\nللـ overloads حافة حادة واحدة: المستدعي الذي بين يديه number | number[] لا يطابق أيًّا من الـ overloads، فيحصل على “No overload matches this call”. ستحتاج إلى overload ثالث يقبل الـ union. وهذه الحافة تلميح بشأن التصميم. إذا كان لدى المستدعين الـ union غالبًا، فالدالة تريد على الأرجح توقيعًا واحدًا؛ وإن كان نادرًا، فدالتان منفصلتان باسمين واضحين (formatPrice وformatPrices) تتفوّقان عادةً على دالة واحدة محمّلة بالـ overloads.
في التمرين ستُصلح ثلاثًا من مشكلات الـ inference هذه في نظام الدفع في Cartwheel. والدرس القادم يجمع كل ما في هذا القسم في عميل API واحد محدَّد الأنواع.
\n","toc":[{"id":"sec-1","text":"NoInfer: افحص هنا، لكن لا تستنتج من هنا","level":2},{"id":"sec-2","text":"قيم افتراضية لمعاملات النوع","level":2},{"id":"sec-3","text":"حين يعتمد نوع الإرجاع على الوسيط","level":2}],"takeaways":["كل ظهور لمعامل النوع موقعُ استنتاج، فقد يؤدّي خطأ إملائي في وسيط واحد إلى توسيع النوع بدل رفضه.","NoInfer<T> (منذ TypeScript 5.4) تجعل الموضع للفحص فقط: يُتحقَّق منه مقابل T لكنه لا يساهم بأي مرشّح.","القيم الافتراضية لمعاملات النوع تُطبَّق حين لا يوجد ما يُستنتج منه، وتجعل وسائط النوع الصريحة الجزئية ممكنة.","الـ overloads تتيح لنوع الإرجاع أن يعتمد على نوع الوسيط، لكن الوسيط من نوع union لا يطابق أيًّا منها؛ ودالتان بأسماء جيدة كثيرًا ما تكونان أوضح."],"further":[{"title":"NoInfer (TypeScript 5.4 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-4.html"},{"title":"Function overloads","url":"https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads"},{"title":"NoInfer utility type","url":"https://www.typescriptlang.org/docs/handbook/utility-types.html#noinfertype"}],"quiz":[{"q":"لماذا يمرّ هذا الاستدعاء في الترجمة رغم أن 'WELCOM10' خطأ إملائي؟
function applyCoupon<C extends string>(available: C[], code: C) {}\napplyCoupon(['WELCOME10', 'LOYAL5'], 'WELCOM10');string في الاستدعاءات الـ generic.","why":"القيد extends string يحتفظ بالقيم الحرفية. المشكلة في مصدر تلك القيم."},{"text":"لأن code هو أيضًا موقع استنتاج، فيصبح C هو 'WELCOME10' | 'LOYAL5' | 'WELCOM10'.","why":"صحيح. يُجمع الخطأ الإملائي كمرشّح بدل أن يُفحص. والحل code: NoInfer<C>."},{"text":"لأن المصفوفات تُستنتج بعد الوسائط العادية.","why":"المصفوفات ليست حسّاسة للسياق؛ كلا الوسيطين يساهم بمرشّحين في الجولة نفسها."}],"answer":1},{"q":"function request<TRes = unknown, TBody = undefined>(path: string, body?: TBody): Promise<TRes>. ماذا تفعل request<Order>('/orders/1')؟
TBody قيمة افتراضية، فيمكن حذفه."},{"text":"TRes هو Order وTBody يُستنتج من body الغائب.","why":"ما إن تمرّر وسائط نوع صريحة حتى يتوقّف الاستنتاج كليًا؛ والمحذوفة تأخذ قيمها الافتراضية."},{"text":"TRes هو Order وTBody يرجع إلى قيمته الافتراضية undefined.","why":"صحيح. القيم الافتراضية هي ما يجعل وسائط النوع الصريحة الجزئية مشروعة."}],"answer":2},{"q":"مع هذه الـ overloads، ماذا يحدث في السطر الأخير؟
\nfunction getOrder(id: number): Promise<Order>;\nfunction getOrder(ids: number[]): Promise<Order[]>;\nfunction getOrder(idOrIds: number | number[]): Promise<Order | Order[]> { /* … */ }\ndeclare const input: number | number[];\ngetOrder(input);Promise<Order | Order[]> من توقيع التنفيذ.","why":"توقيع التنفيذ غير مرئي للمستدعين. لا يمكن مطابقة إلا توقيعات الـ overloads التي فوقه."},{"text":"خطأ، “No overload matches this call”، لأنه لا يوجد overload واحد يقبل الـ union.","why":"صحيح. تُجرَّب الـ overloads واحدًا تلو الآخر، ولا يقبل أيٌّ منها number | number[]. ستحتاج إلى overload ثالث للـ union."},{"text":"يختار الـ overload الأول، لأن الـ overloads تُجرَّب بالترتيب.","why":"الترتيب يحدّد أيّ overload يفوز حين يتطابق أكثر من واحد. هنا لا يتطابق أيٌّ منها، لأن number[] تفشل في الأول."}],"answer":1},{"q":"تصمّم دالة بحث تُعيد طلبًا واحدًا لمعرّف، وقائمة لعميل. أيّ API هو الأسهل للمستدعين وللمسؤولين عن صيانة الكود؟
","options":[{"text":"دالتان،getOrder(id) وgetOrdersForCustomer(customerId)، لكلٍّ منهما توقيع بسيط.","why":"صحيح. كل دالة تقول ما تفعله، ولا تحتاج إلى overloads أو conditional types، والـ inference فيها بديهي."},{"text":"دالة واحدة get(idOrCustomer) بتوقيعَي overload.","why":"هذا يعمل لكنه يحشر نيّتين في اسم واحد، والمستدعون الذين لديهم مدخلات من نوع union سيصطدمون بـ “No overload matches”."},{"text":"دالة generic واحدة get<T>(key) بنوع إرجاع شرطي مبني على T.","why":"أنواع الإرجاع الشرطية تحتاج عادةً إلى تحويلات داخل التنفيذ، وموضع الاستدعاء أقل وضوحًا من دالة مسمّاة."}],"answer":0}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"function applyCouponأصلح ثلاث مشكلات في الـ inference في نظام الدفع في Cartwheel. لا تغيّر الاستدعاءات تحت اختبارات الأنواع.
\napplyCoupon(available, code) أي code ليس في available، بدل أن تضيفه إلى الـ union.createMachine({ states, initial }) أي حالة initial ليست في states.formatPrice النوع string مع رقم، وstring[] مع مصفوفة أرقام.NoInfer<…>: code: NoInfer<C>.","في 3، أضف توقيعَي overload فوق التنفيذ الموجود: function formatPrice(cents: number): string; وfunction formatPrice(cents: number[]): string[];."],"explanation":"كان code وinitial موقعَي استنتاج، فصار الخطأ الإملائي مرشّحًا إضافيًا واتّسع الـ union ليشمله. NoInfer<C> تُبقي النوع كما هو لكنها تُخرج ذلك الموضع من الاستنتاج، فيأتي C من القائمة وحدها وتُفحص القيمة المفردة مقابله. أما في formatPrice، فتوقيع الـ union لا يستطيع أن يقول أيّ مدخل ينتج أيّ مخرج؛ وتوقيعات الـ overload تستطيع، ويبقى توقيع الـ union الأصلي كتوقيع تنفيذ مخفي.
formatPrice تنسّق سعرًا مفردًا وقائمة أسعار","coupon":"applyCoupon ما زالت تطبّق الكوبون الصالح"}},"words":603,"readMinutes":4}