TypeScript Map: Map<K, V>, get, set, has und Iterieren

Eine TypeScript-Map ist die eingebaute Map von JavaScript mit typisierten Schlüsseln und Werten: Map<string, number> bildet Strings auf Zahlen ab. Erzeuge eine mit new Map<K, V>() und nutze dann set, get, has und delete. get gibt V | undefined zurück, weil der Schlüssel fehlen kann.

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

Erst die Typargumente machen eine Map in TypeScript nützlich: Jedes set wird geprüft, und jedes get liefert den Werttyp. Die letzte Zeile ist ein Compilerfehler (TS2345); @ts-expect-error lässt den Block weiterlaufen.

Diese Seite behandelt die Sammlung Map. Wenn du nach array.map() gesucht hast, das steht im letzten Abschnitt.

Eine Map erzeugen

Die Typen kommen aus Typargumenten, aus Anfangseinträgen oder aus einer Annotation. Anfangseinträge sind ein Array von [key, value]-Tupeln oder alles andere, das solche liefert.

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

Zwei Fallen bei der Inferenz:

• new Map() ohne Typargumente und ohne Einträge ist Map<any, any>. Nichts, was du hineinlegst oder herausholst, wird geprüft. Schreibe immer new Map<K, V>().
• Einträge mit unterschiedlichen Werttypen ergeben keine Union. new Map([["a", 1], ["b", "x"]]) ist der Fehler TS2769 (No overload matches this call). Schreibe den Typ aus: new Map<string, number | string>([...]).

get gibt V | undefined zurück

Eine Map kann nicht versprechen, dass ein Schlüssel existiert, daher ist get als V | undefined typisiert. Unter strict musst du dich um das undefined kümmern, bevor du den Wert als V verwendest:

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

Die Lösungen, von der häufigsten zur seltensten:

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 merkt sich nicht, dass has true zurückgegeben hat, wenn du später get aufrufst. Das Ergebnis von get direkt zu prüfen ist kürzer und sicher. Eine Non-Null-Assertion, stock.get("apples")!, bringt den Fehler zum Schweigen, schützt aber nicht, wenn der Schlüssel fehlt.

Map-Methoden und ihre Typen

Über eine Map iterieren

Eine Map wird in Einfügereihenfolge durchlaufen. for...of über die Map liefert [key, value]-Tupel vom Typ [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' ]

Einen vorhandenen Schlüssel neu zu setzen aktualisiert den Wert, behält aber seine ursprüngliche Position in der Reihenfolge.

Objekte als Schlüssel und Zählen

Jeder Wert kann ein Schlüssel sein, auch Objekte und Arrays. Schlüssel werden wie mit === verglichen: Zwei Objekte mit gleichem Inhalt sind verschiedene Schlüssel. Eine Map ist außerdem der übliche Weg, Elemente zu zählen oder zu gruppieren.

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

Um nach dem Inhalt eines Objekts zu schlüsseln, leite stattdessen einen String oder Zahlenschlüssel ab, etwa user.id oder `${x},${y}`.

Map vs Objekt vs Record

Faustregel: eine Map für eine Sammlung, deren Schlüssel Daten sind (User-IDs, Wörter, Cache-Einträge) und sich zur Laufzeit ändern; ein Objekttyp oder Record für eine feste Menge bekannter Schlüssel und für alles, was von oder zu JSON geht. Die Seite zum Dictionary vergleicht Index-Signaturen, Record und Map für Lookups mit String-Schlüsseln.

Maps in Objekte und JSON umwandeln

Die Einträge einer Map sind keine Eigenschaften, deshalb sieht JSON.stringify sie nicht. Wandle über Object.fromEntries und Object.entries um:

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 gibt any zurück, daher legt das as Record<...> fest, was die Daten sein sollen. Es ist keine Prüfung zur Laufzeit; validiere nicht vertrauenswürdiges JSON, bevor du diesem Typ traust.

array.map() typisieren

Viele Suchen nach „typescript map“ meinen die Array-Methode, die jedes Element umwandelt und ein neues Array zurückgibt. Ihr Typ wird aus dem Callback abgeleitet, Annotationen sind also selten nötig:

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

Den Rückgabetyp des Callbacks zu annotieren ((u): Option => ...) ist der klarste Weg, den Ergebnistyp festzulegen: Eine fehlende oder falsch geschriebene Eigenschaft im zurückgegebenen Objekt ist dann ein Compilerfehler direkt am Callback.