Map em TypeScript: Map<K, V>, get, set, has e iteração

Um Map em TypeScript é o Map nativo do JavaScript com chaves e valores tipados: Map<string, number> mapeia strings para números. Crie um com new Map<K, V>() e depois use set, get, has e delete. get retorna V | undefined, porque a chave pode não existir.

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

São os argumentos de tipo que tornam um Map útil no TypeScript: todo set é verificado e todo get retorna o tipo do valor. A última linha é um erro de compilação (TS2345); @ts-expect-error mantém o bloco rodando.

Esta página trata da coleção Map. Se você procurava array.map(), ele está na última seção.

Criando um Map

Os tipos vêm de argumentos de tipo, das entradas iniciais ou de uma anotação. As entradas iniciais são um array de tuplas [key, value] ou qualquer outra coisa que as gere.

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

Duas armadilhas de inferência:

• new Map() sem argumentos de tipo e sem entradas é Map<any, any>. Nada do que você coloca ou tira é verificado. Sempre escreva new Map<K, V>().
• Entradas com tipos de valor diferentes não inferem uma union. new Map([["a", 1], ["b", "x"]]) é o erro TS2769 (No overload matches this call). Escreva o tipo: new Map<string, number | string>([...]).

get retorna V | undefined

Um Map não pode garantir que uma chave existe, então get tem o tipo V | undefined. Com strict, você precisa lidar com o undefined antes de usar o valor como 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'.

As correções, da mais comum para a menos comum:

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

O TypeScript não lembra que has retornou true quando você chama get depois. Verificar direto o resultado de get é mais curto e seguro. Uma non-null assertion, stock.get("apples")!, silencia o erro, mas não protege nada se a chave não existir.

Métodos do Map e seus tipos

Iterando um Map

Um Map é iterado na ordem de inserção. for...of sobre o map gera tuplas [key, value], com o tipo [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' ]

Definir uma chave que já existe atualiza o valor, mas mantém a posição original dela na ordem.

Chaves que são objetos e contagem

Qualquer valor pode ser chave, inclusive objetos e arrays. As chaves são comparadas como ===: dois objetos com o mesmo conteúdo são chaves diferentes. Um Map também é a forma padrão de contar ou agrupar itens.

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

Para usar o conteúdo de um objeto como chave, derive uma chave string ou numérica, como user.id ou `${x},${y}`.

Map vs objeto vs Record

Regra prática: um Map para uma coleção cujas chaves são dados (ids de usuário, palavras, entradas de cache) e mudam em tempo de execução; um tipo de objeto ou Record para um conjunto fixo de chaves conhecidas e para tudo o que vai para JSON ou vem dele. A página de dicionário compara index signatures, Record e Map para buscas com chave string.

Convertendo Maps em objetos e JSON

As entradas de um Map não são propriedades, então JSON.stringify não as enxerga. Converta com Object.fromEntries e 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 retorna any, então o as Record<...> declara o que se espera que os dados sejam. Isso não é uma verificação em tempo de execução; valide JSON não confiável antes de confiar nesse tipo.

Tipando array.map()

Muitas buscas por "typescript map" se referem ao método de array, que transforma cada elemento e retorna um novo array. O tipo dele é inferido a partir do callback, então anotações raramente são necessárias:

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

Anotar o tipo de retorno do callback ((u): Option => ...) é a forma mais clara de declarar o tipo do resultado: uma propriedade ausente ou com nome errado no objeto retornado passa a ser erro de compilação no próprio callback.