TypeScript Mapped Types: תחביר, מודיפיירים ומיפוי מפתחות מחדש

mapped type בונה טיפוס אובייקט חדש באמצעות מעבר על קבוצת מפתחות. { [K in keyof T]: boolean } פירושו "לכל מפתח K של T, מאפיין בשם K מטיפוס boolean":

type Features = {
  darkMode: string;
  search: number;
  export: string[];
};

// Same keys as T, every property turned into a boolean
type Flags<T> = { [K in keyof T]: boolean };

const enabled: Flags<Features> = {
  darkMode: true,
  search: false,
  export: true,
};

console.log(enabled); // { darkMode: true, search: false, export: true }
// Leaving out "export" would be error TS2741: Property 'export' is missing

הוסיפו מפתח ל-Features ו-Flags<Features> ידרוש גם אותו. mapped types קיימים רק בזמן קומפילציה: הם מתארים אובייקטים, הם לא יוצרים אותם.

התחביר

ל-mapped type יש שלושה חלקים: משתנה מפתח, union של מפתחות לעבור עליהם, וטיפוס המאפיין, שיכול להשתמש במשתנה המפתח.

type MappedType = {
  [K in Keys]: PropertyType; // K takes each member of Keys in turn
};

Keys יכול להיות כל union של מחרוזות, מספרים או symbols. הוא לא חייב להגיע מ-keyof:

type Size = "small" | "medium" | "large";

type PriceTable = { [S in Size]: number };
// { small: number; medium: number; large: number }

const prices: PriceTable = { small: 3, medium: 4, large: 5 };

for (const size of ["small", "large"] as const) {
  console.log(size, prices[size]);
}
// small 3
// large 5

זה בדיוק מה ש-Record<Size, number> עושה; Record הוא mapped type בשורה אחת. טיפוס המאפיין יכול להשתמש במפתח: { [K in keyof T]: T[K] } מעתיק כל טיפוס מאפיין דרך indexed access, ו-{ [K in keyof T]: T[K] | null } הופך כל מאפיין ל-nullable.

מודיפיירים: readonly ו-? עם + ו--

mapped type יכול להוסיף או להסיר את המודיפיירים readonly ואופציונלי (?) מכל המאפיינים בבת אחת. הוסיפו + כקידומת כדי להוסיף (ברירת המחדל כשלא כותבים כלום) ו-- כדי להסיר:

type Account = {
  readonly id: number;
  email?: string;
};

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type AllRequired<T> = { [K in keyof T]-?: T[K] };
type Frozen<T> = { +readonly [K in keyof T]: T[K] };

const editable: Mutable<Account> = { id: 1 };
editable.id = 2; // allowed: readonly was removed

const complete: AllRequired<Account> = { id: 1, email: "a@b.co" };
// { id: 1 } alone would be error TS2741: Property 'email' is missing

const frozen: Frozen<{ n: number }> = { n: 1 };
// @ts-expect-error: Cannot assign to 'n' because it is a read-only property
frozen.n = 2;

console.log(editable, complete, frozen);
// { id: 2 } { id: 1, email: 'a@b.co' } { n: 2 }

השורה האחרונה מראה ש-readonly הוא רק כלל של זמן קומפילציה: ההשמה דווחה (והושתקה כאן עם @ts-expect-error), אבל ה-JavaScript שנוצר עדיין הריץ אותה. -? עושה יותר מלהסיר את סימן השאלה: הוא גם מסיר את undefined מטיפוס המאפיין, כך ש-AllRequired<Account> דוחה את { id: 1, email: undefined } עם error TS2322: Type 'undefined' is not assignable to type 'string'.

איך בנויים Partial, Readonly, Pick ו-Record

טיפוסי העזר המובנים שמעצבים מחדש אובייקטים הם mapped types. אלה ההגדרות מתוך lib.es5.d.ts של TypeScript עצמו:

type Partial<T> = { [P in keyof T]?: T[P] };
type Required<T> = { [P in keyof T]-?: T[P] };
type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Pick<T, K extends keyof T> = { [P in K]: T[P] };
type Record<K extends keyof any, T> = { [P in K]: T };

קריאה שלהן היא תרגול טוב: Pick עובר רק על המפתחות שמעבירים לו, ו-Record מתעלם מכל טיפוס מקור ונותן לכל מפתח את אותו טיפוס ערך. Omit אינו mapped type בפני עצמו: הוא Pick<T, Exclude<keyof T, K>>. המדריך ל-utility types מפרט את כולם.

מיפוי מפתחות מחדש עם as

פסוקית as אחרי המפתח משנה את שם המאפיין. בשילוב עם template literal types היא יכולה לייצר שמות חדשים מהישנים:

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Person = { name: string; age: number };

// { getName: () => string; getAge: () => number }
const person: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};

console.log(person.getName(), person.getAge()); // Ada 36

string & K נמצא שם כי keyof T עשוי לכלול מפתחות מסוג number ו-symbol, ו-Capitalize מקבל רק מחרוזות. ה-intersection שומר את מפתחות המחרוזת ומשמיט את השאר.

סינון מפתחות עם never

אם פסוקית as מייצרת never עבור מפתח, המפתח הזה מוסר. עם conditional type אפשר לשמור או להשמיט מאפיינים לפי הטיפוס שלהם:

type DataOnly<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: T[K];
};

class Invoice {
  constructor(public id: number, public total: number) {}
  format(): string {
    return `#${this.id}: ${this.total.toFixed(2)}`;
  }
}

// { id: number; total: number }  (format is gone)
const data: DataOnly<Invoice> = { id: 7, total: 19.5 };

console.log(data);                        // { id: 7, total: 19.5 }
console.log(new Invoice(7, 19.5).format()); // #7: 19.50

טיפוסים כמו DataOnly שימושיים כדי לתאר מה שורד את JSON.stringify או מה טופס עורך: השדות בלי המתודות.

אילו מודיפיירים נשמרים

mapped type על keyof T עבור טיפוס T כלשהו נקרא homomorphic, והוא מעתיק את המודיפיירים readonly ו-? של כל מאפיין מ-T. mapped type על union פשוט של מפתחות מתחיל בלי מודיפיירים:

type Account = { readonly id: number; email?: string };

type Copy<T> = { [K in keyof T]: T[K] };
type A = Copy<Account>;
// { readonly id: number; email?: string }  (modifiers kept)

type B = { [K in "id" | "email"]: Account[K] };
// { id: number; email: string | undefined }  (email is required now)

ב-B עדיין יש undefined בטיפוס של email, כי Account["email"] כולל אותו, אבל המאפיין עצמו כבר לא אופציונלי: { id: 1 } נדחה. זו הסיבה ש-Partial<T> וחבריו ממפים על keyof T: הם שומרים על כל מה שהם לא משנים במפורש.

mapped type גנרי homomorphic שמופעל על מערך או tuple מייצר מערך או tuple, לא אובייקט עם מפתחות מספריים. Readonly<string[]> הוא readonly string[], ועם type Box<T> = { [K in keyof T]: { value: T[K] } }, Box<[string, number]> הוא [{ value: string }, { value: number }].

Mapped types וקוד בזמן ריצה

מאחר ש-mapped type רק מתאר אובייקט, פונקציה שבונה אובייקט כזה צריכה לולאה משלה בזמן ריצה. הטיפוס מתאר אז את התוצאה שלה:

type Validators<T> = { [K in keyof T]: (value: T[K]) => boolean };

type SignUp = { email: string; age: number };

const rules: Validators<SignUp> = {
  email: (v) => v.includes("@"), // v is string
  age: (v) => v >= 13,           // v is number
};

function validate(form: SignUp): string[] {
  const failed: string[] = [];
  for (const key of Object.keys(rules) as (keyof SignUp)[]) {
    const ok = key === "email" ? rules.email(form.email) : rules.age(form.age);
    if (!ok) failed.push(key);
  }
  return failed;
}

console.log(validate({ email: "ada@example.com", age: 36 })); // []
console.log(validate({ email: "nope", age: 9 }));             // [ 'email', 'age' ]

ה-callbacks מקבלים את טיפוסי הפרמטרים שלהם מה-mapped type (v הוא string באחד ו-number בשני) בלי שום הגדרת טיפוס. אם הגעתם לכאן בחיפוש אחר המחלקה Map ולא אחר מיפוי טיפוסים, ראו Map ב-TypeScript.