في تصميم عميل API بأنواع دقيقة، أجبرت المسارات التي لا مدخل لها المستدعين على كتابة call('GET /me', {}). الإصلاح يحتاج إلى نوع يتّخذ قرارًا: “إن لم يكن في مدخل هذا المسار حقول إلزامية، فاجعل الوسيط اختياريًا؛ وإلا فاطلبه”. الـ mapped types تمرّ على المفاتيح. والـ conditional types (الأنواع الشرطية) تقرّر.
type IsArray<T> = T extends readonly unknown[] ? true : false;\n\ntype A = IsArray<string[]>; // true\ntype B = IsArray<Order>; // falseT extends U ? X : Y تُقرأ مثل العامل الثلاثي: إن كان T قابلًا للإسناد إلى U فالنتيجة X، وإلا Y. وextends هنا هي فحص قابلية الإسناد نفسه الموجود في كل مكان آخر في TypeScript: “هل T مجموعة جزئية من U؟”. وحين يكون T معاملًا generic غير معروف بعد، يؤجّل TypeScript الشرط ويُبقيه كما هو حتى يصل نوع محدّد.
إليك إصلاح عميل الـ API. {} extends Input صادقة تمامًا حين تكون كل خصائص Input اختيارية (فالكائن الفارغ سيحقّقها):
type CallArgs<R extends keyof Routes> = {} extends Routes[R]['input']\n ? [input?: Routes[R]['input']]\n : [input: Routes[R]['input']];\n\ndeclare function call<R extends keyof Routes>(route: R, ...args: CallArgs<R>): Promise<Routes[R]['output']>;\n\ncall('GET /me'); // ok: input is {}\ncall('GET /orders'); // ok: every filter is optional\ncall('GET /orders/:id'); // Error: Expected 2 arguments, but got 1.\ncall('GET /orders/:id', { id: 1 }); // okينتج الشرط نوع tuple، وينشره معامل البقية (rest parameter) ...args في قائمة المعاملات. وعناصر الـ tuple الموسومة (input?:) تُبقي اسم المعامل في التلميحات. ولم يتغيّر موضع استدعاء واحد.
للـ conditional types سلوك واحد يفاجئ الجميع. حين يكون النوع المفحوص معامل نوع مجرّدًا (naked type parameter) وتمرّر إليه union، يُنفَّذ الشرط مرة لكل عضو وتُجمع النتائج:
\ntype ToArray<T> = T extends unknown ? T[] : never;\n\ntype X = ToArray<string | number>; // string[] | number[], not (string | number)[]يُسمّى هذا التوزيع (distribution)، وهو المحرّك وراء عدد من الـ utility types. إليك Exclude وExtract، كما تعرّفهما الـ lib بالضبط:
type MyExclude<T, U> = T extends U ? never : T;\ntype MyExtract<T, U> = T extends U ? T : never;\n\ntype Active = MyExclude<OrderStatus, 'cancelled' | 'returned'>; // 'processing' | 'shipped' | 'delivered'\ntype Shipped = MyExtract<Order, { status: 'shipped' }>; // the ShippedOrder variantكل عضو يمرّ عبر الشرط وحده. والأعضاء المحوَّلة إلى never تختفي، لأن never هو الـ union الفارغ. وMyExtract<Order, { status: 'shipped' }> هي أنظف طريقة لتسمية شكل واحد من discriminated union.
لإيقاف التوزيع، غلّف الطرفين في tuple من عنصر واحد. [T] ليس معامل نوع مجرّدًا، فيُفحص الـ union ككل:
type ToArrayWhole<T> = [T] extends [unknown] ? T[] : never;\ntype Y = ToArrayWhole<string | number>; // (string | number)[]داخل جملة extends، تعلن infer X متغيّر نوع يلتقط ما يقع في ذلك الموضع، إن طابق النمط. وهكذا تعرّف الـ lib النوع ReturnType في جوهره (نسخة الـ lib تقيّد F أيضًا بنوع دالة وترجع إلى any):
type MyReturnType<F> = F extends (...args: any[]) => infer R ? R : never;\n\ntype Loaded = MyReturnType<typeof loadOrder>; // Promise<Order>الحيلة نفسها تستخرج أنواعًا من أي شيء له بنية:
\ntype ElementOf<T> = T extends readonly (infer E)[] ? E : never;\ntype UnwrapPromise<T> = T extends Promise<infer V> ? V : T;\ntype FirstArg<F> = F extends (first: infer A, ...rest: any[]) => any ? A : never;ويمكن أن تحمل infer قيدًا أيضًا، كما في infer S extends string، فلا تطابق إلا حين يكون النوع الملتقَط نصًا، وتعطيك S مضيَّقًا مسبقًا. ستحتاج إلى ذلك في الدرس القادم، حين تلتقط أجزاءً من الـ literal types النصية.
اجمع mapped type وشرطًا ووصولًا بالفهرس، وتستطيع اختيار المفاتيح حسب ماهية قيمها:
\ntype KeysOfType<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T];\n\ntype Line = { sku: string; quantity: number; unitPriceCents: number };\ntype NumericField = KeysOfType<Line, number>; // 'quantity' | 'unitPriceCents'يحوّل الـ mapped type كل خاصية إلى اسم مفتاحها أو إلى never، ثم تجمع [keyof T] القيم في union، تختفي فيه قيم never. يُقرأ بالمقلوب في المرة الأولى؛ اكتبه مرة، وسمِّه جيدًا، وأعِد استخدامه. والآن دالة ترتيب نوعها sortBy(lines, key: KeysOfType<Line, number>) ترفض الترتيب حسب sku.
من المغري إعطاء دالة نوع إرجاع شرطيًا، مثل function format<T extends number | number[]>(x: T): T extends number ? string : string[]. يحصل المستدعون على أنواع دقيقة، لكن التنفيذ لا يحصل عليها: داخل الدالة، يبقى T مجهولًا، ويبقى الشرط مؤجّلًا، ولا يستطيع TypeScript أن يتحقّق من أن return x.toFixed(2) تطابقه. فينتهي بك الأمر إلى كتابة as any أو as T extends number ? string : string[] على كل جملة عودة، أي أن أدقّ كود في الدالة هو الكود الذي لا يفحصه أحد.
لهذا فضّل القسم السابق الـ overloads أو الدوال المنفصلة لهذه المهمة. تتألّق الـ conditional types في الأنواع المشتقّة (CallArgs وExtract وKeysOfType) حيث لا يلزم تنفيذ شيء مقابلها، وتكون في أضعف حالاتها كنوع إرجاع معلَن لمنطق مكتوب يدويًا.
في التمرين ستعيد بناء Exclude وExtract وReturnType وتستخدمها على أنواع الطلبات في Cartwheel. والدرس القادم يطبّق الشروط وinfer على النصوص.
T extends U ? X : Y تختار X حين يكون T قابلًا للإسناد إلى U، وY في غير ذلك؛ ومع T من نوع generic، ينتظر الاختيار حتى يُعرف T.","الشرط على معامل نوع مجرّد يتوزّع على الـ unions، فيُنفَّذ مرة لكل عضو ثم تُجمع النتائج.","غلّف الطرفين بأقواس مربّعة، [T] extends [U]، لتختبر الـ union ككل بدل التوزيع.","infer تعلن متغيّر نوع داخل جملة extends وتلتقط ما يطابقه، وهكذا يعمل ReturnType وAwaited.","تحويل كل مفتاح إلى نفسه أو إلى never ثم الفهرسة بـ [keyof T] يصفّي المفاتيح حسب نوع قيمتها."],"further":[{"title":"Conditional Types","url":"https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"},{"title":"Utility Types (Exclude, Extract, ReturnType)","url":"https://www.typescriptlang.org/docs/handbook/utility-types.html"}],"quiz":[{"q":"type ToArray<T> = T extends unknown ? T[] : never. ما هو ToArray<string | number>؟
(string | number)[]","why":"هذه هي النتيجة غير التوزيعية، وتحصل عليها بـ [T] extends [unknown]."},{"text":"never","why":"كلا العضوين قابل للإسناد إلى unknown، فلا يأخذ أيٌّ منهما فرع never."},{"text":"unknown[]","why":"الفرع الصادق يستخدم T، وهو كل عضو بدوره، لا القيد unknown."},{"text":"string[] | number[]","why":"صحيح. T معامل نوع مجرّد، فيُنفَّذ الشرط مرة لـ string ومرة لـ number، وتُجمع النتائج."}],"answer":3},{"q":"أيّ نوع يعطيك الشكل المشحون من الـ union المسمّى Order؟
Extract<Order, { status: 'shipped' }>","why":"صحيح. Extract تُبقي أعضاء الـ union القابلة للإسناد إلى { status: 'shipped' }، وهذا بالضبط الشكل المشحون."},{"text":"Exclude<Order, { status: 'shipped' }>","why":"Exclude تفعل العكس: تُزيل الشكل المشحون وتُبقي الباقي."},{"text":"Order['shipped']","why":"الوصول بالفهرس يبحث عن خاصية اسمها shipped، وOrder ليس فيه مثلها."},{"text":"Order extends { status: 'shipped' } ? Order : never","why":"Order هنا نوع محدّد، لا معامل نوع، فلا يتوزّع شيء. والـ union كله غير قابل للإسناد إلى الشكل المشحون، فتحصل على never."}],"answer":0},{"q":"ما هو R؟
type MyReturnType<F> = F extends (...args: any[]) => infer R ? R : never;\ntype R = MyReturnType<(id: number) => Promise<Order>>;Order","why":"infer R تلتقط نوع الإرجاع كما هو مكتوب. فكّ الـ promise يحتاج خطوة ثانية، مثل Awaited."},{"text":"Promise<Order>","why":"صحيح. نوع الدالة يطابق النمط، وتلتقط R نوع إرجاعها بالضبط."},{"text":"never","why":"لا تحصل على never إلا حين لا يكون F نوع دالة. وهنا هو يطابق."}],"answer":1},{"q":"type IsString<T> = T extends string ? true : false. ما هو IsString<never>؟
true، لأن never قابل للإسناد إلى كل شيء","why":"هذا صحيح في فحص غير توزيعي مثل [never] extends [string]. أما الشرط التوزيعي فلا يصل إلى هذا الحد أصلًا."},{"text":"false، لأن never ليس نصًا","why":"لا يُقيَّم الشرط إطلاقًا؛ لا توجد أعضاء union لينفَّذ عليها."},{"text":"never، لأن التوزيع على union فارغ ينتج union فارغًا","why":"صحيح. never هو الـ union الفارغ، فيمرّ الشرط التوزيعي على صفر من الأعضاء ويُعيد never."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order =\n | { id: number; status: 'processing' }\n | { id: number; status: 'shipped'; trackingNumber: string }\n | { id: number; status: 'delivered'; trackingNumber: string; deliveredAt: string }\n | { id: number; status: 'cancelled'; cancelReason: string }\n | { id: number; status: 'returned'; trackingNumber: string; deliveredAt: string; refundCents: number };\ntype Line = { sku: string; quantity: number; unitPriceCents: number; giftWrapped: boolean };\ndeclare function loadOrder(id: number): Promiseنفّذ هذه الأنواع بالـ conditional types (لا تستخدم Exclude أو Extract أو ReturnType أو Awaited المدمجة):
MyExclude<T, U>: أعضاء T غير القابلة للإسناد إلى U.MyExtract<T, U>: أعضاء T القابلة للإسناد إلى U.MyReturnType<F>: نوع إرجاع نوع دالة.UnwrapPromise<T>: القيمة داخل Promise، أو T نفسه إن لم يكن promise.OrderWithStatus<S>: شكل (أو أشكال) Order الذي يكون status فيه هو S.KeysOfType<T, V>: مفاتيح T التي تكون قيمها قابلة للإسناد إلى V.MyExclude وMyExtract شرطان توزيعيان من سطر واحد: أحدهما يُعيد never في الفرع الصادق، والآخر في الفرع الكاذب.","استخدم infer لالتقاط جزء من نوع: F extends (...args: any[]) => infer R ? R : never.","OrderWithStatus هو MyExtract<Order, { status: S }>. وفي KeysOfType، حوّل كل مفتاح إلى نفسه أو إلى never، ثم افهرس النتيجة بـ [keyof T]."],"explanation":"تعتمد MyExclude وMyExtract على التوزيع: T معامل نوع مجرّد، فيُختبر كل عضو في الـ union منفردًا وتختفي نتائج never. والتوزيع نفسه يجعل OrderWithStatus<'delivered' | 'returned'> يعطي الشكلين كليهما، ولهذا تعمل ['deliveredAt'] عليه. وتلتقط infer نوع الإرجاع وقيمة الـ promise. أما KeysOfType فتبني كائنًا قيمه أسماء مفاتيح أو never، ثم تقرأ كل قيمه دفعة واحدة بـ [keyof T].