TypeScript Generic Constraints: extends ו-keyof T

אילוץ גנרי מגביל את מה שפרמטר טיפוס יכול להיות. <T extends { length: number }> מקבל רק טיפוסים שיש להם length מספרי (מחרוזות, מערכים, אובייקטים משלכם), ובזכות ההבטחה הזו מותר לפונקציה לקרוא את .length.

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));        // apple
console.log(longest([1, 2, 3], [4]));        // [ 1, 2, 3 ]
console.log(longest({ length: 2, tag: "x" }, { length: 5, tag: "y" })); // { length: 5, tag: 'y' }

// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
longest(10, 20);

טיפוס ההחזרה הוא עדיין T, לא { length: number }: העברה של שני מערכי מספרים מחזירה number[], והאובייקטים שומרים על ה-tag שלהם. האילוץ מתאר את המינימום; הטיפוס של מי שקורא לפונקציה נשמר.

למה צריך אילוצים

בתוך פונקציה גנרית, T בלי אילוץ יכול להיות כל דבר: מחרוזת, מספר, null, פונקציה. לכן TypeScript מאפשר רק מה שעובד על כל טיפוס, וזה כמעט כלום.

// This does not compile: T could be number or undefined, which have no length.
function longest<T>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));

הקומפיילר מדפיס:

index.ts(3,12): error TS2339: Property 'length' does not exist on type 'T'.
index.ts(3,24): error TS2339: Property 'length' does not exist on type 'T'.

הפתרון הוא לומר מה אתם צריכים: <T extends { length: number }>. אילוצים הופכים "כל טיפוס" ל"כל טיפוס שיש לו את זה", ובדרך כלל זו הכוונה של פונקציה גנרית.

אילוץ ל-interface

האילוץ יכול להיות כל טיפוס, כולל interface או type alias שכבר יש לכם. הפונקציה עובדת אז עם כל דבר שיש לו לפחות את האיברים האלה, ועדיין מחזירה את הטיפוס המלא של מי שקורא לה.

interface HasId {
  id: number;
}

function byId<T extends HasId>(items: T[], id: number): T | undefined {
  return items.find((item) => item.id === id);
}

function indexById<T extends HasId>(items: T[]): Map<number, T> {
  return new Map(items.map((item) => [item.id, item]));
}

const users = [
  { id: 1, name: "Ada", role: "admin" },
  { id: 2, name: "Grace", role: "editor" },
];

const found = byId(users, 2);
console.log(found?.name);              // Grace (found keeps name and role)
console.log(indexById(users).get(1));  // { id: 1, name: 'Ada', role: 'admin' }

השוו לטיפוס פרמטר רגיל: function byId(items: HasId[], id: number): HasId | undefined מקבלת את אותם מערכים, אבל התוצאה היא רק HasId, ולכן found.name היה שגיאה. הגרסה הגנרית מעבירה הלאה את הטיפוס המלא.

K extends keyof T: גישה בטוחה למאפיינים

האילוץ הנפוץ ביותר מקשר בין שני פרמטרי טיפוס. K extends keyof T אומר ש-K חייב להיות אחד משמות המאפיינים של T, ו-T[K] הוא הטיפוס של המאפיין הזה.

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const book = { title: "Dune", year: 1965, tags: ["sci-fi"] };

const year = getProperty(book, "year");   // number
const title = getProperty(book, "title"); // string
console.log(year + 1, title.toUpperCase()); // 1966 DUNE

const books = [book, { title: "Emma", year: 1815, tags: [] }];
console.log(pluck(books, "year"));        // [ 1965, 1815 ]

// @ts-expect-error: Argument of type '"author"' is not assignable to parameter of type '"tags" | "title" | "year"'.
getProperty(book, "author");

מפתח עם שגיאת כתיב או מפתח שלא קיים הוא שגיאת קומפילציה, וטיפוס ההחזרה נקבע לפי המפתח: "year" נותן number, ו-"title" נותן string. העמוד על keyof מסביר את keyof עצמו, כולל איך הוא מתנהג עם index signatures.

אילוץ לטיפוסים פרימיטיביים

אילוץ יכול להיות טיפוס פרימיטיבי או union שלהם. תופעת לוואי שימושית: כש-T extends string (או number), TypeScript מסיק את טיפוס הליטרל של הארגומנט במקום להרחיב אותו.

function maxOf<T extends number | bigint>(values: T[]): T {
  return values.reduce((a, b) => (b > a ? b : a)); // < and > work on the constraint
}

function createEvent<T extends string>(name: T): { type: T } {
  return { type: name };
}

console.log(maxOf([3, 9, 4]));           // 9
console.log(maxOf([10n, 2n]));           // 10n

const evt = createEvent("user.saved");   // evt: { type: "user.saved" }
const same: "user.saved" = evt.type;     // the literal survived
console.log(same);                       // user.saved

בלי האילוץ, createEvent("user.saved") מחזיר { type: string }: כאן TypeScript מרחיב ל-string את הליטרל שהוא הסיק עבור T. עם T extends string הליטרל נשמר, וכך פונקציות עזר עם טיפוסים לאירועים ולניתוב מקבלות שמות מדויקים מארגומנטים רגילים של מחרוזות.

שגיאות נפוצות

החזרה של משהו שרק מתאים לאילוץ. פונקציה שמחזירה T חייבת להחזיר T, ולא סתם ערך שמתאים לאילוץ:

interface HasId {
  id: number;
}

function reset<T extends HasId>(item: T): T {
  return { id: item.id };
}
// error TS2322: Type '{ id: number; }' is not assignable to type 'T'.
//   '{ id: number; }' is assignable to the constraint of type 'T', but 'T' could be
//   instantiated with a different subtype of constraint 'HasId'.

אם T הוא { id: number; name: string }, לאובייקט החדש אין name, ולכן הוא אינו T. החזירו spread של הקלט, return { ...item, id: 0 };, ששומר על כל מאפיין, או הצהירו על טיפוס ההחזרה כ-HasId אם זה כל מה שאתם מייצרים.

העברה של ארגומנט טיפוס ששובר את האילוץ. גם ארגומנטי טיפוס מפורשים נבדקים: עם function scale<T extends number>(x: T), הקריאה scale<string>("2") נכשלת עם Type 'string' does not satisfy the constraint 'number'. (TS2344).

אילוץ כשלא צריך גנרי. אם T מופיע רק בפרמטר, function print<T extends HasId>(item: T): void היא פשוט function print(item: HasId): void עם תחביר מיותר. אילוצים חשובים כש-T מופיע גם בטיפוס ההחזרה או בפרמטר נוסף.

אילוצים עם ערכי ברירת מחדל

לפרמטר טיפוס יכולים להיות גם אילוץ וגם ערך ברירת מחדל. ברירת המחדל חייבת לעמוד באילוץ.

interface Store<TState extends object = Record<string, unknown>> {
  get(): TState;
  set(next: Partial<TState>): void;
}

type AnyStore = Store;                              // Store<Record<string, unknown>>
type CounterStore = Store<{ count: number }>;       // fine
type BadStore = Store<number>;
// error TS2344: Type 'number' does not satisfy the constraint 'object'.

אותה מילת מפתח extends מופיעה גם ב-conditional types, T extends string ? A : B, ושם היא בדיקה ולא הגבלה; העמוד על conditional types מסביר את הצורה הזו.