التحكّم في الـ Inference: NoInfer والقيم الافتراضية والـ Overloads

إليك دالة مساعدة من نظام الدفع في Cartwheel. تبدو آمنة، وفيها ثغرة:

function applyCoupon<C extends string>(available: C[], code: C) {
  // …
}

applyCoupon(['WELCOME10', 'LOYAL5'], 'WELCOM10'); // compiles

النية واضحة: يجب أن يكون code واحدًا من الكوبونات المتاحة. لكن C يظهر في المعاملين كليهما، وكما رأيت في الدرس السابق، كل ظهور موقعُ استنتاج. يجمع TypeScript القيم 'WELCOME10' و'LOYAL5' و'WELCOM10' كمرشّحين، ويجعل C هو الـ union من الثلاثة، فيجتاز كل شيء فحص الأنواع. لم يُفحص الخطأ الإملائي مقابل القائمة؛ بل أُضيف إليها.

NoInfer: افحص هنا، لكن لا تستنتج من هنا

أضاف TypeScript 5.4 النوع المدمج NoInfer<T>. يُحَلّ إلى T العادي، لكنه يجعل ذلك الموضع محظورًا على الـ inference:

function applyCoupon<C extends string>(available: C[], code: NoInfer<C>) {
  // …
}

applyCoupon(['WELCOME10', 'LOYAL5'], 'WELCOM10');
// 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> }) {
  return config;
}

createMachine({ states: ['cart', 'shipping', 'payment'], initial: 'cart' });    // ok
createMachine({ states: ['cart', 'shipping', 'payment'], initial: 'checkout' }); // error

قبل 5.4، كان الحل البديل معامل نوع ثانيًا مقيَّدًا بالأول، <C extends string, D extends C>(available: C[], code: D). هذا يعمل، وستراه في المكتبات القديمة، لكنه يضيف معاملًا لا وجود له إلا للتهرّب من الاستنتاج. استخدم NoInfer في الكود الجديد. فهي توثّق النية أيضًا: القارئ الذي يرى initial: NoInfer<S> يعرف من النظرة الأولى أيّ وسيط هو مصدر الحقيقة وأيّها يُفحص فقط، وهذا ما لم توضّحه حيلة المعاملين أبدًا.

قيم افتراضية لمعاملات النوع

يمكن أن تكون لمعامل النوع قيمة افتراضية، تُستخدم حين لا يوجد ما يُستنتج منه:

type ApiResponse<T = unknown> = { data: T; requestId: string };

async function request<TRes = unknown, TBody = undefined>(path: string, body?: TBody): Promise<TRes> {
  const res = await fetch(path, { method: body === undefined ? 'GET' : 'POST', body: JSON.stringify(body) });
  return res.json();
}

أمران يجعلان القيم الافتراضية مفيدة. أولًا، ApiResponse وحدها تعني الآن ApiResponse<unknown>، وهي قيمة افتراضية آمنة: على المستدعين تضييق data قبل استخدامها. ثانيًا، القيم الافتراضية تجعل وسائط النوع الصريحة الجزئية مشروعة. دونها كانت request<Order>('/orders/1042') ستفشل مع “Expected 2 type arguments”؛ ومعها يرجع TBody إلى undefined.

اختر قيمًا افتراضية آمنة لا مريحة. unknown قيمة افتراضية جيدة للبيانات القادمة من الخارج؛ أما any فلا، لأنها تُطفئ الفحص بصمت لكل من ينسى وسيط النوع. (ولاحظ أن request<Order> ما زالت تحويلًا متنكّرًا: جسم الاستجابة لا يُفحص. ستُصلح ذلك كما ينبغي في الدرس القادم وفي تحليل البيانات غير الموثوقة عند الحدود.)

حين يعتمد نوع الإرجاع على الوسيط

أحيانًا يحدّد نوعُ الوسيط نوعَ النتيجة. الـ overloads (التحميل الزائد) تصف ذلك مباشرة:

function formatPrice(cents: number): string;
function formatPrice(cents: number[]): string[];
function formatPrice(cents: number | number[]): string | string[] {
  return Array.isArray(cents) ? cents.map(toDollars) : toDollars(cents);
}

function toDollars(cents: number): string {
  return `${(cents / 100).toFixed(2)}`;
}

const one = formatPrice(4500);          // string
const many = formatPrice([4500, 1299]); // string[]

السطران الأولان هما توقيعا الـ overload اللذان يراهما المستدعون. والثالث هو توقيع التنفيذ، الذي يجب أن يتوافق معها جميعًا وهو غير مرئي من الخارج. يجرّب TypeScript الـ overloads من الأعلى إلى الأسفل ويستخدم أول واحد يطابق، فضع الأكثر تحديدًا أولًا.

للـ overloads حافة حادة واحدة: المستدعي الذي بين يديه number | number[] لا يطابق أيًّا من الـ overloads، فيحصل على “No overload matches this call”. ستحتاج إلى overload ثالث يقبل الـ union. وهذه الحافة تلميح بشأن التصميم. إذا كان لدى المستدعين الـ union غالبًا، فالدالة تريد على الأرجح توقيعًا واحدًا؛ وإن كان نادرًا، فدالتان منفصلتان باسمين واضحين (formatPrice وformatPrices) تتفوّقان عادةً على دالة واحدة محمّلة بالـ overloads.

في التمرين ستُصلح ثلاثًا من مشكلات الـ inference هذه في نظام الدفع في Cartwheel. والدرس القادم يجمع كل ما في هذا القسم في عميل API واحد محدَّد الأنواع.