Conditional Types ו-infer ב-TypeScript, עם דוגמאות

conditional type בוחר בין שני טיפוסים עם בדיקה שנקראת כמו האופרטור הטרנרי של 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 כאן פירושו "ניתן להשמה ל", אותו יחס שהקומפיילר משתמש בו כשמשימים ערך למשתנה. conditional types קיימים רק בזמן קומפילציה; הם נמחקים מפלט ה-JavaScript.

התחביר

type Result = CheckedType extends TestType ? TrueType : FalseType;

conditional types נהיים שימושיים עם גנריים, כשהטיפוס הנבדק הוא פרמטר טיפוס שמקבל טיפוס קונקרטי מאוחר יותר. בענף ה-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> בגוף הפונקציה הוא לא אופציונלי, כפי שהחלק הבא מראה.

טיפוסי החזרה מותנים צריכים assertion

פונקציה שטיפוס ההחזרה שלה הוא conditional type על פרמטר הטיפוס שלה עצמה לא יכולה להחזיר אף אחד מהענפים ישירות. 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, שמציינים כל זוג של קלט ופלט ובודקים את הקוראים בדיוק, או assertion במימוש.

// 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 מוסברים בעמוד על function overloading. עם assertion, הקומפיילר סומך עליכם: ענף שגוי בגוף לא ייתפס.

Distributive Conditional Types

כשהטיפוס הנבדק הוא פרמטר טיפוס חשוף והוא מקבל 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 הריק, ולכן distributive conditional type שמקבל 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 הוא promise של משהו, קראו למשהו הזה V והחזירו אותו; אחרת החזירו את T בלי שינוי". infer מותר רק בפסוקית ה-extends של conditional type.

למשתנה 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 המובנה הוא conditional type של שורה אחת עם 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 הופך את ערך הפונקציה לטיפוס שלה, ואז ה-conditional type מתאים אותו מול "כל פונקציה" ולוכד את טיפוס ההחזרה כ-R. הגרסה של הספרייה הסטנדרטית שונה בשני פרטים: הפרמטר שלה מוגבל לטיפוסי פונקציה (T extends (...args: any) => any), ולכן ReturnType<string> היא שגיאת קומפילציה ולא never, והענף השלילי שלה הוא any. העמוד על ReturnType מכסה גם את Parameters, InstanceType ו-Awaited.

Conditional Types רקורסיביים

conditional type יכול להתייחס לעצמו, וזה מאפשר לו לפרוס קינון בכל עומק:

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.

סיכום מהיר