Record trong TypeScript: giải thích Record<K, V> qua ví dụ

Record<K, V> là một utility type có sẵn cho object có khóa kiểu K và mọi giá trị đều kiểu V. Với khóa string, nó mô tả một từ điển (dictionary); với union các khóa literal, nó mô tả một object phải có đúng những khóa đó.

// 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 chỉ tồn tại trong hệ thống kiểu. Lúc chạy, cả hai object đều là object JavaScript thông thường, nên chúng hoạt động với object literal, spread, JSON.stringify và mọi thứ khác nhận object.

Cú pháp và định nghĩa

Record<Keys, Value>

Keys phải là thứ có thể làm khóa của object: string, number, symbol, một union các literal chuỗi hoặc số, hay một template literal type. Value có thể là kiểu bất kỳ. Toàn bộ định nghĩa trong thư viện chuẩn của TypeScript chỉ là một dòng, một mapped type:

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

keyof any là string | number | symbol, tập hợp mọi kiểu khóa có thể có. [P in K]: T tạo một thuộc tính kiểu T cho mỗi thành phần của K. Điều đó giải thích cả hai hành vi bên dưới: một K rộng như string tạo ra index signature (khóa bất kỳ), còn một K là union tạo ra một thuộc tính bắt buộc cho mỗi thành phần.

Khóa union: mọi khóa đều bắt buộc

Khi các khóa là union các literal, một Record phải liệt kê đủ từng khóa, và không có khóa nào khác. Điều này biến trình biên dịch thành một danh sách kiểm tra:

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)

Thêm "cancelled" vào Status thì cả hai object sẽ không biên dịch được cho đến khi bạn đặt nhãn và màu cho trạng thái mới. Bỏ sót một khóa, hoặc thêm một khóa không có trong union, đều là lỗi biên dịch:

// 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>'.

Cách này cũng hoạt động với string enum làm kiểu khóa: Record<Color, string> bắt buộc có một mục cho mỗi thành phần của enum.

Record<string, T> và khóa không tồn tại

Với khóa string, khóa nào cũng được chấp nhận, và TypeScript gán kiểu T cho mọi lần tra cứu, kể cả với khóa không có. Lúc chạy, khóa không tồn tại sẽ cho 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

Đây là bug phổ biến nhất với Record. Có ba cách xử lý: kiểm tra bằng in hoặc Object.hasOwn trước khi đọc, khai báo giá trị là V | undefined, hoặc bật tùy chọn trình biên dịch noUncheckedIndexedAccess, tùy chọn này thêm | undefined vào mọi lần đọc qua index signature trong dự án. Record với khóa union không gặp vấn đề này, vì mọi khóa đều chắc chắn tồn tại.

Partial<Record<K, V>>: chỉ một số khóa

Để dùng union các khóa mà không bắt buộc có tất cả, hãy bọc Record trong Partial. Khi đó phép đọc trả về V | undefined, phản ánh đúng thực tế:

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' }

Một khóa viết sai chính tả như jp vẫn là lỗi, đó là ưu điểm so với Record<string, string>.

Duyệt qua một Record

Object.keys, Object.values và Object.entries đều dùng được. Điểm cần lưu ý là kiểu của khóa: Object.keys trả về string[] và Object.entries trả về [string, V][], không bao giờ là union các khóa của bạn:

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 cố ý giữ khóa ở kiểu string: lúc chạy một object có thể có nhiều thuộc tính hơn những gì kiểu của nó liệt kê, nên nói chung cam kết Plan[] là không an toàn. Với object bạn tạo từ một literal, như seats, phép ép kiểu là an toàn.

Tạo Record từ dữ liệu

Record thường là kết quả của việc nhóm hoặc đánh chỉ mục một mảng. Bắt đầu từ một object rỗng có kiểu Record rồi điền dữ liệu vào:

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"] dùng lại union từ interface làm kiểu khóa, nên thêm một thể loại vào Book sẽ khiến byGenre đòi thêm một mục mới.

Record<string, unknown> và interface

Record<string, unknown> là kiểu thường dùng cho "một object nào đó có khóa là chuỗi". Nó chấp nhận object literal và giá trị có kiểu là type alias, nhưng một interface thì bị từ chối:

// 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'.

Interface có thể được mở rộng qua cơ chế gộp khai báo, nên TypeScript không mặc định rằng chúng khớp với một index signature; type alias thì không thể mở lại, nên type User = { name: string } sẽ hợp lệ. Các cách sửa thường dùng là nhận object thay thế (bạn vẫn gọi được Object.keys trên nó), biến hàm thành generic (<T extends object>(obj: T)), hoặc khai báo User bằng type (trang interface và type trình bày các khác biệt còn lại).

So sánh Record, index signature và Map

Chọn Record với khóa union mỗi khi tập khóa đã biết trước: đây là lựa chọn duy nhất kiểm tra được mọi khóa đều có mặt. Với khóa chuỗi không giới hạn, Record<string, V> và index signature có thể thay thế cho nhau, và nhiều dự án chọn Record vì dễ đọc hơn. Hãy dùng Map khi khóa được thêm và xóa lúc chạy, khi khóa không phải chuỗi, hoặc khi bạn cần kích thước và thứ tự thêm vào mà không phải làm thêm gì.