Dictionnaire en TypeScript : index signature, Record et Map

TypeScript n'a pas de classe dictionnaire ou hashmap à part. Un dictionnaire est soit un objet simple typé avec une index signature, { [key: string]: number }, soit le même type écrit Record<string, number>, soit un Map<string, number>. Les trois stockent des valeurs par clé ; ils diffèrent par les types de clés acceptés, par la façon dont les clés absentes sont typées et par leur sérialisation.

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

Pour des clés de type chaîne et des données au format JSON, un objet avec Record<string, T> est le choix habituel. Pour des clés qui ne sont pas des chaînes, ou des entrées ajoutées et retirées en permanence, utilisez un Map.

Index signatures

Une index signature, [key: KeyType]: ValueType, signifie « toute clé de ce type correspond à une valeur de ce type ». Le nom de la clé (key, name, userId) ne sert que de documentation. Le type de clé peut être string, number, symbol, un motif template literal, ou une union de ces types.

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 convertit les clés numériques en chaînes, donc un objet { [id: number]: string } a quand même des clés de type chaîne à l'exécution : Object.keys({ 1: "one" }) donne [ '1' ]. L'index signature numérique ne fait que restreindre la façon dont vous pouvez l'indexer en TypeScript.

Record<K, V>

Record<string, V> est un raccourci pour { [key: string]: V }. Avec une union de clés littérales à la place de string, il devient un dictionnaire fermé qui doit contenir chaque clé :

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

Oublier staging dans urls provoque l'erreur de compilation TS2741 (Property 'staging' is missing...), ce qui fait de Record avec des clés en union une table de correspondance vérifiée. Partial rend chaque valeur number | undefined.

Map comme table de hachage

Un Map accepte des clés de n'importe quel type, conserve l'ordre d'insertion, possède une propriété size et type honnêtement les clés absentes : get renvoie 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

Vérifier qu'une clé existe

Il existe plusieurs tests, et ils ne veulent pas tous dire la même chose :

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

Ce problème de clés héritées explique pourquoi des clés fournies par les utilisateurs, comme "constructor" ou "__proto__", rendent les objets simples risqués comme dictionnaires. Un Map n'a pas de telles clés.

Le problème du type des clés absentes

Sur une index signature ou un Record<string, T>, lire n'importe quelle clé donne le type T, même pour une clé qui n'existe pas. Le compilateur vous laisse appeler des méthodes sur une valeur qui vaut undefined à l'exécution :

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

L'option de compilation noUncheckedIndexedAccess corrige cela : avec elle, colors["grass"] a le type string | undefined et l'appel à toUpperCase est une erreur de compilation tant que vous ne l'avez pas vérifié. Elle ne fait pas partie de strict et doit donc être activée à part dans tsconfig.json ; voir le mode strict pour les autres options qui l'accompagnent. Un Map n'a pas ce trou, puisque get inclut toujours undefined.

Ajouter, supprimer et parcourir

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 fonctionne sur les propriétés d'une index signature. Sur une propriété nommée obligatoire d'un type objet, c'est l'erreur de compilation TS2790, The operand of a 'delete' operator must be optional.

Laquelle choisir