Dictionary trong TypeScript: index signature, Record và Map

TypeScript không có class dictionary hay hashmap riêng. Một từ điển (dictionary) hoặc là đối tượng thường được gán kiểu bằng index signature, { [key: string]: number }, cùng kiểu đó viết dưới dạng Record<string, number>, hoặc là một Map<string, number>. Cả ba đều lưu giá trị theo khóa; chúng khác nhau ở kiểu của khóa, cách gán kiểu cho khóa bị thiếu, và cách tuần tự hóa.

// 1. Index signature on an object
const ages: { [name: string]: number } = { ada: 36 };
ages["grace"] = 85;
ages.alan = 41;

// 2. Record: the same type, shorter to write
const prices: Record<string, number> = { tea: 2.5 };
prices["coffee"] = 3.2;

// 3. Map: a real hash map class
const stock = new Map<string, number>();
stock.set("apples", 3);

console.log(ages);            // { ada: 36, grace: 85, alan: 41 }
console.log(prices.coffee);   // 3.2
console.log(stock.get("apples")); // 3

Với khóa dạng chuỗi và dữ liệu có dạng JSON, một đối tượng với Record<string, T> là lựa chọn thông thường. Với khóa không phải chuỗi, hoặc các phần tử liên tục được thêm và xóa, hãy dùng Map.

Index signature

Index signature, [key: KeyType]: ValueType, nói rằng "mọi khóa thuộc kiểu này đều ánh xạ đến một giá trị thuộc kiểu kia". Tên khóa (key, name, userId) chỉ để mô tả. Kiểu của khóa có thể là string, number, symbol, mẫu template literal, hoặc union của các kiểu này.

type User = { name: string; admin: boolean };

// The key name documents what the key is
const usersById: { [userId: string]: User } = {
    u1: { name: "Ada", admin: true },
};
usersById["u2"] = { name: "Grace", admin: false };

// Index signature plus named properties: named ones must fit the signature
type Scores = {
    total: number;
    [player: string]: number;
};
const scores: Scores = { total: 12, ada: 7, alan: 5 };

// Every value is checked against the value type
// @ts-expect-error: Type 'string' is not assignable to type 'number'.
scores.grace = "nine";

console.log(Object.keys(usersById), scores.total);

JavaScript chuyển khóa số thành chuỗi, nên một đối tượng { [id: number]: string } lúc chạy vẫn có khóa là chuỗi: Object.keys({ 1: "one" }) là [ '1' ]. Index signature dạng số chỉ giới hạn cách bạn truy cập nó trong TypeScript.

Record<K, V>

Record<string, V> là cách viết tắt của { [key: string]: V }. Khi dùng union các khóa literal thay cho string, nó trở thành một từ điển cố định phải chứa đủ mọi khóa:

// Open dictionary: any string key
const counts: Record<string, number> = {};
for (const word of ["a", "b", "a"]) {
    counts[word] = (counts[word] ?? 0) + 1;
}
console.log(counts); // { a: 2, b: 1 }

// Closed dictionary: exactly these keys, all required
type Env = "dev" | "staging" | "prod";
const urls: Record<Env, string> = {
    dev: "http://localhost:3000",
    staging: "https://staging.example.com",
    prod: "https://example.com",
};
console.log(urls.prod);

// Some of the keys: wrap in Partial
const overrides: Partial<Record<Env, number>> = { prod: 5 };
console.log(overrides.dev ?? "default"); // default

Bỏ sót staging trong urls là lỗi biên dịch TS2741 (Property 'staging' is missing...), nhờ vậy Record với khóa là union trở thành một bảng tra cứu được kiểm tra. Partial biến mỗi giá trị thành number | undefined.

Map làm hash map

Map nhận khóa thuộc bất kỳ kiểu nào, giữ thứ tự thêm vào, có size, và gán kiểu trung thực cho khóa bị thiếu: get trả về V | undefined.

type Point = { x: number; y: number };

// Object keys work: compared by identity
const home: Point = { x: 0, y: 0 };
const labels = new Map<Point, string>([[home, "home"]]);
console.log(labels.get(home)); // home

// A string key built from the contents, for lookup by value
const grid = new Map<string, string>();
const key = (p: Point) => `${p.x},${p.y}`;
grid.set(key({ x: 2, y: 3 }), "tree");
console.log(grid.get(key({ x: 2, y: 3 }))); // tree
console.log(grid.get(key({ x: 9, y: 9 })) ?? "empty"); // empty
console.log(grid.size); // 1

Kiểm tra khóa có tồn tại không

Có nhiều cách kiểm tra, và chúng không hoàn toàn mang cùng một ý nghĩa:

const dict: Record<string, number> = { zero: 0, one: 1 };

console.log(Object.hasOwn(dict, "zero"));   // true: own property
console.log("zero" in dict);                // true
console.log("toString" in dict);            // true: inherited from Object.prototype!
console.log(Object.hasOwn(dict, "toString")); // false

console.log(dict["zero"] !== undefined);    // true
console.log(dict["zero"] ? "truthy" : "falsy"); // falsy: 0 is falsy, the key exists

const value = dict["two"];
if (value !== undefined) {
    console.log(value.toFixed(1)); // not reached
} else {
    console.log("no key 'two'");
}

Vấn đề khóa kế thừa là lý do các khóa do người dùng nhập như "constructor" hay "__proto__" khiến đối tượng thường trở nên rủi ro khi dùng làm từ điển. Map không có những khóa như vậy.

Vấn đề kiểu của khóa bị thiếu

Trên index signature hoặc Record<string, T>, đọc bất kỳ khóa nào cũng có kiểu T, kể cả khóa không tồn tại. Trình biên dịch cho phép bạn gọi phương thức trên một giá trị mà lúc chạy là undefined:

const colors: Record<string, string> = { sky: "blue" };

const grass = colors["grass"]; // type: string, value: undefined
console.log(typeof grass);     // undefined

try {
    console.log(grass.toUpperCase()); // compiles, then throws
} catch (e) {
    if (e instanceof Error) console.log(e.message);
}

Tùy chọn biên dịch noUncheckedIndexedAccess khắc phục điều này: khi bật, colors["grass"] có kiểu string | undefined và lời gọi toUpperCase là lỗi biên dịch cho đến khi bạn kiểm tra. Tùy chọn này không thuộc strict, nên phải bật riêng trong tsconfig.json; xem strict mode để biết các cờ đi kèm khác. Map không có lỗ hổng này, vì get luôn bao gồm undefined.

Thêm, xóa và duyệt

const inventory: Record<string, number> = { apples: 3, pears: 0 };

inventory["kiwis"] = 12;   // add or update
delete inventory["pears"]; // remove: allowed on index signatures

for (const [item, qty] of Object.entries(inventory)) { // [string, number]
    console.log(item, qty);
}

console.log(Object.keys(inventory).length); // 2 (the size)

// Map equivalents
const m = new Map(Object.entries(inventory)); // Map<string, number>
m.delete("apples");
console.log(m.size, [...m.keys()]); // 1 [ 'kiwis' ]

delete dùng được với thuộc tính của index signature. Với một thuộc tính có tên bắt buộc của kiểu đối tượng, nó là lỗi biên dịch TS2790, The operand of a 'delete' operator must be optional.

Nên dùng cách nào