Słownik w TypeScript: sygnatury indeksu, Record i Map

TypeScript nie ma osobnej klasy słownika ani hashmapy. Słownik to albo zwykły obiekt otypowany sygnaturą indeksu, { [key: string]: number }, albo ten sam typ zapisany jako Record<string, number>, albo Map<string, number>. Wszystkie trzy przechowują wartości po kluczu; różnią się typami kluczy, sposobem typowania brakujących kluczy i serializacją.

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

Dla kluczy napisowych i danych w kształcie JSON zwykłym wyborem jest obiekt z Record<string, T>. Dla kluczy innych niż napisy albo wpisów ciągle dodawanych i usuwanych użyj Map.

Sygnatury indeksu

Sygnatura indeksu, [key: KeyType]: ValueType, mówi „każdy klucz tego typu wskazuje wartość tego typu”. Nazwa klucza (key, name, userId) to tylko dokumentacja. Typy kluczy mogą być string, number, symbol, wzorcami szablonów literałów albo uniami tych typów.

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 zamienia klucze liczbowe na napisy, więc obiekt { [id: number]: string } nadal ma w czasie działania klucze napisowe: Object.keys({ 1: "one" }) to [ '1' ]. Liczbowa sygnatura indeksu ogranicza tylko to, jak możesz go indeksować w TypeScript.

Record<K, V>

Record<string, V> to skrót od { [key: string]: V }. Z unią kluczy literałowych zamiast string staje się stałym słownikiem, który musi zawierać każdy klucz:

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

Pominięcie staging w urls to błąd kompilacji TS2741 (Property 'staging' is missing...), dzięki czemu Record z kluczami w postaci unii to sprawdzana tablica wyszukiwania. Partial sprawia, że każda wartość ma typ number | undefined.

Map jako hashmapa

Map przyjmuje klucze dowolnego typu, zachowuje kolejność wstawiania, ma size i uczciwie typuje brakujące klucze: get zwraca 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

Sprawdzanie, czy klucz istnieje

Istnieje kilka sprawdzeń i nie wszystkie znaczą to samo:

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'");
}

Problem z odziedziczonymi kluczami sprawia, że klucze podawane przez użytkowników, takie jak "constructor" albo "__proto__", czynią zwykłe obiekty ryzykownymi jako słowniki. Map nie ma takich kluczy.

Problem z typem brakującego klucza

Na sygnaturze indeksu albo Record<string, T> odczyt dowolnego klucza ma typ T, nawet klucza, który nie istnieje. Kompilator pozwala wywoływać metody na wartości, która w czasie działania jest 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);
}

Opcja kompilatora noUncheckedIndexedAccess to naprawia: z nią colors["grass"] ma typ string | undefined, a wywołanie toUpperCase to błąd kompilacji, dopóki go nie sprawdzisz. Nie jest częścią strict, więc trzeba ją włączyć osobno w tsconfig.json; inne flagi obok niej opisuje strona o trybie strict. Map nie ma tej luki, bo get zawsze uwzględnia undefined.

Dodawanie, usuwanie i iteracja

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 działa na właściwościach z sygnatury indeksu. Na wymaganej nazwanej właściwości typu obiektowego to błąd kompilacji TS2790, The operand of a 'delete' operator must be optional.

Czego użyć