الأنواع الشرطية وinfer في TypeScript مع أمثلة

النوع الشرطي يختار بين نوعين باختبار يشبه العامل الثلاثي في JavaScript: T extends U ? X : Y. إذا كان T قابلًا للإسناد إلى U فالنتيجة X، وإلا فهي Y.

type IsString<T> = T extends string ? "yes" : "no";

type A = IsString<"hello">; // "yes"
type B = IsString<42>;      // "no"

// A practical one: the type of a "message" property, if there is one
type MessageOf<T> = T extends { message: unknown } ? T["message"] : never;

type ErrText = MessageOf<{ message: string; code: number }>; // string
type Nothing = MessageOf<{ code: number }>;                  // never

const a: A = "yes";
const text: ErrText = "disk full";
console.log(a, text); // yes disk full

تعني extends هنا «قابل للإسناد إلى»، وهي العلاقة نفسها التي يستخدمها المترجم عندما تسند قيمة إلى متغير. الأنواع الشرطية موجودة وقت الترجمة فقط، وتُحذف من مخرجات JavaScript.

الصياغة

type Result = CheckedType extends TestType ? TrueType : FalseType;

تصبح الأنواع الشرطية مفيدة مع generics، حيث يكون النوع المفحوص معامل نوع يأخذ نوعًا محددًا لاحقًا. في فرع true تعرف TypeScript أن النوع المفحوص يطابق الاختبار، لذا يُسمح بـ T["message"] في المثال السابق مع أن T المجرد لا يملك الخاصية message.

ويمكن تداخلها أيضًا، مثل العوامل الثلاثية المتسلسلة:

type TypeName<T> =
  T extends string ? "string" :
  T extends number ? "number" :
  T extends boolean ? "boolean" :
  T extends undefined ? "undefined" :
  "object";

function typeName<T>(value: T): TypeName<T> {
  return typeof value as TypeName<T>;
}

console.log(typeName("hi"), typeName(3), typeName(true)); // string number boolean
const n: TypeName<number[]> = "object";
console.log(n); // object

الجزء as TypeName<T> في جسم الدالة ليس اختياريًا، كما يبيّن القسم التالي.

أنواع القيمة المُعادة الشرطية تحتاج إلى تأكيد نوع

الدالة التي نوع قيمتها المُعادة نوع شرطي على معامل نوعها لا تستطيع أن تعيد أيًّا من الفرعين مباشرة. لا تضيّق TypeScript النوع T داخل الجسم، فلا تستطيع معرفة أي فرع ينطبق:

// This does not compile: TypeScript cannot pick a branch of Flip<T> inside the body
type Flip<T> = T extends string ? number : string;

function flip<T extends string | number>(x: T): Flip<T> {
  return typeof x === "string" ? x.length : String(x);
}

console.log(flip("abc"), flip(7));

index.ts(5,34): error TS2322: Type 'number' is not assignable to type 'Flip<T>'.
index.ts(5,45): error TS2322: Type 'string' is not assignable to type 'Flip<T>'.

هناك حلان شائعان: التحميل الزائد (overloads)، الذي يصرّح بكل زوج من المدخلات والمخرجات ويفحص المستدعين بدقة، أو تأكيد نوع داخل التنفيذ.

// Fix 1: overloads
function flip(x: string): number;
function flip(x: number): string;
function flip(x: string | number): string | number {
  return typeof x === "string" ? x.length : String(x);
}

const len = flip("abc"); // number
const str = flip(7);     // string
console.log(len + 1, str.padStart(3, "0")); // 4 007

// Fix 2: keep the conditional type and assert inside the body
type Flip<T> = T extends string ? number : string;
function flip2<T extends string | number>(x: T): Flip<T> {
  return (typeof x === "string" ? x.length : String(x)) as Flip<T>;
}
console.log(flip2("hello")); // 5

يشرح درس التحميل الزائد للدوال الـ overloads بالتفصيل. أما مع تأكيد النوع فالمترجم يثق بك: لن يُكتشف فرع خاطئ في الجسم.

الأنواع الشرطية التوزيعية

عندما يكون النوع المفحوص معامل نوع مجردًا ويتلقى union، يعمل الشرط مرة لكل عضو وتُجمع النتائج في union جديد:

type ToArray<T> = T extends unknown ? T[] : never;

type A = ToArray<string | number>; // string[] | number[]

// Wrapping both sides in [ ] turns distribution off
type ToArrayWhole<T> = [T] extends [unknown] ? T[] : never;
type B = ToArrayWhole<string | number>; // (string | number)[]

const a: A = ["x", "y"];  // an array of strings, or an array of numbers
const b: B = ["x", 1];    // a mixed array
// const bad: A = ["x", 1] would be error TS2322:
// Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
console.log(a, b); // [ 'x', 'y' ] [ 'x', 1 ]

التوزيع هو ما يجعل Exclude وExtract تعملان. تُعرَّف Exclude<T, U> بأنها T extends U ? never : T: كل عضو يطابق U يصبح never، وnever يختفي من أي union. لذلك فإن Exclude<"a" | "b" | "c", "a"> هو "b" | "c".

وتنتج مفاجأتان عن القاعدة نفسها. النوع boolean هو union من true | false، لذا فإن ToArray<boolean> هو false[] | true[] وليس boolean[]. وnever هو union فارغ، فالنوع الشرطي التوزيعي الذي يتلقى never يعيد never دون أن يختبر شيئًا:

type IsNever<T> = T extends never ? true : false;
type X = IsNever<never>; // never, not true

type IsNeverFixed<T> = [T] extends [never] ? true : false;
type Y = IsNeverFixed<never>; // true

استخراج الأنواع بـ infer

تعلن infer متغير نوع جديدًا داخل جملة extends. إذا نجحت المطابقة تملأ TypeScript هذا المتغير من النوع المفحوص، ويمكنك استخدامه في فرع true:

type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
type Unpromise<T> = T extends Promise<infer V> ? V : T;
type FirstArg<F> = F extends (first: infer A, ...rest: any[]) => unknown ? A : never;
type Head<T> = T extends [infer H, ...unknown[]] ? H : never;

type E1 = ElementOf<string[]>;              // string
type V1 = Unpromise<Promise<{ id: number }>>; // { id: number }
type A1 = FirstArg<(name: string, age: number) => void>; // string
type H1 = Head<[Date, number]>;              // Date

const id: V1 = { id: 7 };
const first: A1 = "Ada";
const when: H1 = new Date("2024-03-15T10:30:00Z");
console.log(id, first, when.toISOString());
// { id: 7 } Ada 2024-03-15T10:30:00.000Z

اقرأ T extends Promise<infer V> ? V : T هكذا: «إذا كان T وعدًا بشيء ما، فسمِّ هذا الشيء V وأعده؛ وإلا فأعد T كما هو». لا يُسمح بـ infer إلا في جملة extends من نوع شرطي.

يمكن أن يحمل متغير infer قيدًا خاصًا به عبر extends. عندها لا تنجح المطابقة إلا إذا كان النوع المستنتج مناسبًا:

type FirstString<T> = T extends [infer S extends string, ...unknown[]] ? S : never;

type A = FirstString<["a", 1]>; // "a"
type B = FirstString<[1, "a"]>; // never: the first element is not a string

بناء ReturnType بنفسك

ReturnType المدمج نوع شرطي من سطر واحد مع infer. كتابته بنفسك هي التمرين الكلاسيكي الذي يوضّح الفكرتين معًا:

type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

function makeUser(name: string) {
  return { name, joined: new Date("2024-03-15T10:30:00Z") };
}

type User = MyReturnType<typeof makeUser>; // { name: string; joined: Date }
type Same = ReturnType<typeof makeUser>;   // the built-in gives the same type

const u: User = makeUser("Ada");
const copy: Same = { ...u, name: "Grace" };
console.log(copy.name, copy.joined.getUTCFullYear()); // Grace 2024

يحوّل typeof makeUser قيمة الدالة إلى نوعها، ثم يطابقه النوع الشرطي مع «أي دالة» ويلتقط نوع القيمة المُعادة باسم R. تختلف نسخة المكتبة القياسية في أمرين: معاملها مقيّد بأنواع الدوال (T extends (...args: any) => any)، فيكون ReturnType<string> خطأ ترجمة بدلًا من never، وفرعها الخاطئ هو any. تشرح صفحة ReturnType أيضًا Parameters وInstanceType وAwaited.

الأنواع الشرطية العودية

يمكن للنوع الشرطي أن يشير إلى نفسه، وهذا يسمح له بفك أي عمق من التداخل:

type Flatten<T> = T extends readonly (infer U)[] ? Flatten<U> : T;

type A = Flatten<number[][][]>; // number
type B = Flatten<string>;       // string

يعمل Awaited<T> المدمج بهذه الطريقة، فيفك Promise<Promise<T>> حتى يصل إلى T. أبقِ العودية ضحلة في الممارسة: العودية العميقة جدًا أو غير المحدودة تجعل المترجم يتوقف بالخطأ error TS2589: Type instantiation is excessively deep and possibly infinite.

مرجع سريع