TypeScript Record: הסבר על Record<K, V> עם דוגמאות

Record<K, V> הוא utility type מובנה לאובייקט שהמפתחות שלו מטיפוס K וכל הערכים שלו מטיפוס V. עם מפתחות string הוא מתאר מילון; עם איחוד של מפתחות ליטרליים הוא מתאר אובייקט שחייב להכיל בדיוק את המפתחות האלה.

// Any string key, number values
const stock: Record<string, number> = { apples: 12, pears: 0 };
stock.plums = 7;

// Exactly these three keys, each with a string value
type Lang = "en" | "de" | "fr";
const greeting: Record<Lang, string> = {
  en: "Hello",
  de: "Hallo",
  fr: "Bonjour",
};

console.log(stock);          // { apples: 12, pears: 0, plums: 7 }
console.log(greeting.de);    // Hallo

Record קיים רק במערכת הטיפוסים. בזמן ריצה שני האובייקטים הם אובייקטי JavaScript רגילים, ולכן הם עובדים עם ליטרלי אובייקט, spread, JSON.stringify וכל דבר אחר שמקבל אובייקט.

תחביר והגדרה

Record<Keys, Value>

Keys חייב להיות משהו שיכול לשמש מפתח של אובייקט: string, number, symbol, איחוד של ליטרלים מסוג מחרוזת או מספר, או template literal type. Value יכול להיות כל טיפוס. ההגדרה כולה בספרייה הסטנדרטית של TypeScript היא שורה אחת, mapped type:

type Record<K extends keyof any, T> = {
  [P in K]: T;
};

keyof any הוא string | number | symbol, קבוצת כל טיפוסי המפתח האפשריים. [P in K]: T יוצר מאפיין אחד מטיפוס T לכל איבר של K. זה מסביר את שתי ההתנהגויות שבהמשך: K רחב כמו string מייצר index signature (כל מפתח), ו-K שהוא איחוד מייצר מאפיין חובה אחד לכל איבר.

מפתחות איחוד: כל מפתח הוא חובה

כשהמפתחות הם איחוד של ליטרלים, Record חייב לפרט כל אחד מהם, ולא אף מפתח אחר. זה הופך את הקומפיילר לרשימת תיוג:

type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
  error: "Something went wrong",
};

const color: Record<Status, `#${string}`> = {
  idle: "#888888",
  loading: "#3b82f6",
  success: "#16a34a",
  error: "#dc2626",
};

function render(s: Status): string {
  return `${label[s]} (${color[s]})`;
}

console.log(render("success")); // Done (#16a34a)

הוסיפו "cancelled" ל-Status, ושני האובייקטים יפסיקו לעבור קומפילציה עד שתתנו לסטטוס החדש תווית וצבע. השמטת מפתח, או הוספת מפתח שלא נמצא באיחוד, היא שגיאת קומפילציה:

// This does not compile: one key is missing and one is not allowed
type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
};

const icon: Record<Status, string> = {
  idle: "o", loading: "~", success: "v", error: "x", paused: "=",
};

index.ts(4,7): error TS2741: Property 'error' is missing in type '{ idle: string; loading: string; success: string; }' but required in type 'Record<Status, string>'.
index.ts(11,54): error TS2353: Object literal may only specify known properties, and 'paused' does not exist in type 'Record<Status, string>'.

אותו דבר עובד עם string enum כטיפוס המפתח: Record<Color, string> דורש רשומה אחת לכל איבר של ה-enum.

Record<string, T> והמפתח החסר

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

const prices: Record<string, number> = { tea: 2.5, coffee: 3.2 };

const juice = prices["juice"]; // typed number, but undefined at runtime
console.log(juice);            // undefined
console.log(juice * 2);        // NaN, and no compile error

// Check before you use it
if ("juice" in prices) {
  console.log("juice costs", prices.juice);
} else {
  console.log("no juice"); // no juice
}

// Or put undefined in the value type so the compiler makes you check
const safePrices: Record<string, number | undefined> = { tea: 2.5 };
const maybe = safePrices["juice"]; // number | undefined
console.log(maybe ?? 0);           // 0

זה הבאג הנפוץ ביותר עם Record. שלוש דרכים לטפל בו: לבדוק עם in או Object.hasOwn לפני הקריאה, להצהיר על הערך כ-V | undefined, או להפעיל את אפשרות הקומפיילר noUncheckedIndexedAccess, שמוסיפה | undefined לכל קריאה דרך index signature בפרויקט. ל-Record עם מפתחות איחוד אין את הבעיה הזו, כי מובטח שכל מפתח קיים.

Partial<Record<K, V>>: רק חלק מהמפתחות

כדי להשתמש באיחוד של מפתחות בלי לדרוש את כולם, עטפו את ה-Record ב-Partial. אז קריאות מחזירות V | undefined, וזה כן:

type Lang = "en" | "de" | "fr" | "ja";

// Translations are optional per language, but only these languages are allowed
const title: Partial<Record<Lang, string>> = {
  en: "Settings",
  de: "Einstellungen",
};

function translate(lang: Lang): string {
  return title[lang] ?? title.en ?? "(missing)";
}

console.log(translate("de")); // Einstellungen
console.log(translate("ja")); // Settings

// Required "en", optional others
type Labels = Record<"en", string> & Partial<Record<Exclude<Lang, "en">, string>>;
const save: Labels = { en: "Save", fr: "Enregistrer" };
console.log(save); // { en: 'Save', fr: 'Enregistrer' }

מפתח עם שגיאת כתיב כמו jp הוא עדיין שגיאה, וזה היתרון לעומת Record<string, string>.

איטרציה על Record

Object.keys, Object.values ו-Object.entries כולם עובדים. הבעיה היא טיפוס המפתח: Object.keys מחזיר string[] ו-Object.entries מחזיר [string, V][], ואף פעם לא את איחוד המפתחות שלכם:

type Plan = "free" | "pro" | "team";
const seats: Record<Plan, number> = { free: 1, pro: 1, team: 10 };

for (const [plan, n] of Object.entries(seats)) {
  console.log(plan, n); // plan is string, n is number
}
// free 1
// pro 1
// team 10

// When you need the union type, cast the keys
const plans = Object.keys(seats) as Plan[];
const total = plans.reduce((sum, p) => sum + seats[p], 0);
console.log(total); // 12

// for...in gives string keys too
for (const key in seats) {
  console.log(key.toUpperCase()); // FREE, PRO, TEAM on separate lines
}

TypeScript משאיר את המפתחות כ-string בכוונה: לאובייקט יכולים להיות בזמן ריצה יותר מאפיינים ממה שהטיפוס שלו מפרט, ולכן הבטחה של Plan[] הייתה לא בטוחה באופן כללי. לאובייקט שיצרתם מליטרל, כמו seats, ה-cast בטוח.

בניית Record מנתונים

Records הם התוצאה הרגילה של קיבוץ או של יצירת אינדקס ממערך. התחילו מאובייקט ריק מטיפוס Record ומלאו אותו:

interface Book {
  id: string;
  title: string;
  genre: "fiction" | "science" | "history";
}

const books: Book[] = [
  { id: "b1", title: "Dune", genre: "fiction" },
  { id: "b2", title: "Cosmos", genre: "science" },
  { id: "b3", title: "Emma", genre: "fiction" },
];

// Index by id
const byId: Record<string, Book> = {};
for (const b of books) byId[b.id] = b;

// Group by genre (every genre present, even if empty)
const byGenre: Record<Book["genre"], string[]> = { fiction: [], science: [], history: [] };
for (const b of books) byGenre[b.genre].push(b.title);

console.log(byId.b2.title); // Cosmos
console.log(byGenre);       // { fiction: [ 'Dune', 'Emma' ], science: [ 'Cosmos' ], history: [] }

// Object.fromEntries gives { [k: string]: V }, which fits Record<string, V>
const titles: Record<string, string> = Object.fromEntries(books.map((b) => [b.id, b.title]));
console.log(titles); // { b1: 'Dune', b2: 'Cosmos', b3: 'Emma' }

Book["genre"] משתמש מחדש באיחוד מה-interface כטיפוס המפתח, ולכן הוספת ז'אנר ל-Book גורמת ל-byGenre לדרוש רשומה חדשה.

Record<string, unknown> ו-interfaces

Record<string, unknown> הוא טיפוס נפוץ ל"אובייקט כלשהו עם מפתחות מחרוזת". הוא מקבל ליטרלי אובייקט וערכים שהטיפוס שלהם הוגדר עם type alias, אבל interface נדחה:

// This does not compile: interfaces have no implicit index signature
interface User {
  name: string;
}

function logFields(obj: Record<string, unknown>) {
  console.log(Object.keys(obj));
}

const user: User = { name: "Ada" };
logFields(user);

index.ts(11,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'Record<string, unknown>'.
  Index signature for type 'string' is missing in type 'User'.

אפשר להרחיב interfaces באמצעות מיזוג הצהרות, ולכן TypeScript לא מניח שהם מתאימים ל-index signature; type aliases אי אפשר לפתוח מחדש, ולכן type User = { name: string } היה עובר. הפתרונות הרגילים הם לקבל במקום זאת object (עדיין אפשר לקרוא עליו ל-Object.keys), להפוך את הפונקציה לגנרית (<T extends object>(obj: T)), או להצהיר על User עם type (דף interface מול type מכסה את שאר ההבדלים).

Record מול index signature מול Map

בחרו ב-Record עם מפתחות איחוד בכל פעם שקבוצת המפתחות ידועה: זו האפשרות היחידה שבודקת שכל מפתח קיים. למפתחות מחרוזת פתוחים, Record<string, V> ו-index signature ניתנים להחלפה, ובסיסי קוד רבים מעדיפים את Record בגלל הקריאות. פנו ל-Map כשמפתחות נוספים ומוסרים בזמן ריצה, כשהמפתחות אינם מחרוזות, או כשצריך את הגודל ואת סדר ההכנסה בלי עבודה נוספת.