Map en TypeScript : Map<K, V>, get, set, has et itération

Une Map TypeScript est la Map intégrée de JavaScript avec des clés et des valeurs typées : Map<string, number> associe des chaînes à des nombres. Créez-en une avec new Map<K, V>(), puis utilisez set, get, has et delete. get renvoie V | undefined, car la clé peut être absente.

const ages = new Map<string, number>();

ages.set("ada", 36);
ages.set("grace", 85).set("alan", 41); // set returns the map, so calls chain

console.log(ages.get("ada"));    // 36
console.log(ages.get("linus"));  // undefined
console.log(ages.has("grace"));  // true
console.log(ages.size);          // 3

ages.delete("alan");
console.log(ages); // Map(2) { 'ada' => 36, 'grace' => 85 }

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
ages.set("bob", "forty");

Ce sont les arguments de type qui rendent une Map utile en TypeScript : chaque set est vérifié et chaque get renvoie le type des valeurs. La dernière ligne est une erreur de compilation (TS2345) ; @ts-expect-error permet au bloc de s'exécuter.

Cette page traite de la collection Map. Si vous cherchiez array.map(), elle est couverte dans la dernière section.

Créer une Map

Les types viennent des arguments de type, des entrées initiales ou d'une annotation. Les entrées initiales sont un tableau de tuples [key, value], ou tout autre objet qui en produit.

// 1. Type arguments, empty map
const scores = new Map<string, number[]>();

// 2. Inferred from entries: Map<string, number>
const prices = new Map([
    ["tea", 2.5],
    ["coffee", 3.2],
]);

// 3. From an object: Map<string, boolean>
const flags = new Map(Object.entries({ darkMode: true, beta: false }));

// 4. Keys and values of any type
type User = { id: number; name: string };
const lastSeen = new Map<User, Date>();
lastSeen.set({ id: 1, name: "Ada" }, new Date("2024-03-15T10:30:00Z"));

console.log(scores.size, prices.get("tea"), flags.get("beta"), lastSeen.size);

Deux pièges d'inférence :

• new Map() sans arguments de type ni entrées est une Map<any, any>. Rien de ce que vous y mettez ou en retirez n'est vérifié. Écrivez toujours new Map<K, V>().
• Des entrées avec des types de valeurs différents n'infèrent pas une union. new Map([["a", 1], ["b", "x"]]) provoque l'erreur TS2769 (No overload matches this call). Écrivez le type : new Map<string, number | string>([...]).

get renvoie V | undefined

Une Map ne peut pas promettre qu'une clé existe, donc get est typé V | undefined. En mode strict, vous devez traiter le undefined avant d'utiliser la valeur comme un V :

// This does not compile: get may return undefined.
const stock = new Map<string, number>([["apples", 3]]);

const apples: number = stock.get("apples");
console.log(apples);

index.ts(4,7): error TS2322: Type 'number | undefined' is not assignable to type 'number'.
  Type 'undefined' is not assignable to type 'number'.

Les solutions, de la plus courante à la moins courante :

const stock = new Map<string, number>([["apples", 3]]);

// 1. A default value with ??
const pears = stock.get("pears") ?? 0;
console.log(pears); // 0

// 2. Store the result and check it
const apples = stock.get("apples");
if (apples !== undefined) {
    console.log(apples * 2); // 6: apples is number here
}

// 3. Update a counter in one line
stock.set("apples", (stock.get("apples") ?? 0) + 1);
console.log(stock.get("apples")); // 4

// has() does not narrow a later get():
if (stock.has("apples")) {
    const n = stock.get("apples"); // still number | undefined
    console.log(n);
}

TypeScript ne se souvient pas que has a renvoyé true quand vous appelez get ensuite. Vérifier directement le résultat de get est à la fois plus court et sûr. Une assertion non nulle, stock.get("apples")!, fait taire l'erreur mais ne protège de rien si la clé est absente.

Les méthodes de Map et leurs types

Parcourir une Map

Une Map se parcourt dans l'ordre d'insertion. for...of sur la map produit des tuples [key, value], typés [K, V].

const prices = new Map<string, number>([
    ["tea", 2.5],
    ["coffee", 3.2],
    ["juice", 4],
]);

for (const [item, price] of prices) {   // item: string, price: number
    console.log(`${item}: ${price.toFixed(2)}`);
}

prices.forEach((price, item) => {       // value first, then key
    console.log(item.toUpperCase(), price);
});

const items = [...prices.keys()];       // string[]
const total = [...prices.values()].reduce((a, b) => a + b, 0);
console.log(items, total);              // [ 'tea', 'coffee', 'juice' ] 9.7

// Sorted by value: sort the entries, build a new Map
const byPrice = new Map([...prices].sort((a, b) => b[1] - a[1]));
console.log([...byPrice.keys()]);       // [ 'juice', 'coffee', 'tea' ]

Affecter une clé existante met à jour la valeur mais conserve sa position d'origine dans l'ordre.

Clés objets et comptage

N'importe quelle valeur peut servir de clé, y compris des objets et des tableaux. Les clés sont comparées comme avec === : deux objets au contenu identique sont des clés différentes. Une Map est aussi la façon standard de compter ou de regrouper des éléments.

const a = { id: 1 };
const b = { id: 1 };
const visits = new Map<object, number>([[a, 5]]);
console.log(visits.get(a), visits.get(b)); // 5 undefined: b is another object

// Counting words
const words = "the cat and the hat and the bat".split(" ");
const counts = new Map<string, number>();
for (const w of words) {
    counts.set(w, (counts.get(w) ?? 0) + 1);
}
console.log(counts); // Map(5) { 'the' => 3, 'cat' => 1, 'and' => 2, 'hat' => 1, 'bat' => 1 }

// Grouping into arrays
const byLength = new Map<number, string[]>();
for (const w of new Set(words)) {
    const group = byLength.get(w.length) ?? [];
    group.push(w);
    byLength.set(w.length, group);
}
console.log(byLength); // Map(1) { 3 => [ 'the', 'cat', 'and', 'hat', 'bat' ] }

Pour indexer selon le contenu d'un objet, dérivez plutôt une clé string ou number, comme user.id ou `${x},${y}`.

Map vs objet vs Record

Règle générale : une Map pour une collection dont les clés sont des données (identifiants d'utilisateurs, mots, entrées de cache) qui changent à l'exécution ; un type objet ou un Record pour un ensemble fixe de clés connues et pour tout ce qui va vers ou vient du JSON. La page dictionnaire compare les signatures d'index, Record et Map pour les recherches par clé string.

Convertir une Map en objet et en JSON

Les entrées d'une Map ne sont pas des propriétés, donc JSON.stringify ne les voit pas. Passez par Object.fromEntries et Object.entries :

const settings = new Map<string, string | number>([
    ["theme", "dark"],
    ["fontSize", 14],
]);

console.log(JSON.stringify(settings)); // {}

const obj = Object.fromEntries(settings); // { [k: string]: string | number }
const json = JSON.stringify(obj);
console.log(json); // {"theme":"dark","fontSize":14}

// And back again
const restored = new Map(Object.entries(JSON.parse(json) as Record<string, string | number>));
console.log(restored.get("theme")); // dark

JSON.parse renvoie any, donc le as Record<...> indique ce que les données sont censées être. Ce n'est pas une vérification à l'exécution ; validez un JSON non fiable avant de faire confiance à ce type.

Typer array.map()

Beaucoup de recherches « typescript map » visent la méthode de tableau, qui transforme chaque élément et renvoie un nouveau tableau. Son type est inféré à partir du callback, les annotations sont donc rarement nécessaires :

type User = { id: number; first: string; last: string };
const users: User[] = [
    { id: 1, first: "Ada", last: "Lovelace" },
    { id: 2, first: "Alan", last: "Turing" },
];

const names = users.map((u) => `${u.first} ${u.last}`); // string[]
const ids = users.map((u) => u.id);                     // number[]

// An explicit result type, checked against what the callback returns
type Option = { value: number; label: string };
const options = users.map((u): Option => ({ value: u.id, label: u.first }));

// With the index
const numbered = users.map((u, i) => `${i + 1}. ${u.first}`);

console.log(names, ids);
console.log(options);
console.log(numbered);

Annoter le type de retour du callback ((u): Option => ...) est la façon la plus claire d'indiquer le type du résultat : une propriété manquante ou mal orthographiée dans l'objet renvoyé devient alors une erreur de compilation au niveau du callback.