JavaScript Map para armazenar e buscar chave-valor

Um objeto Map do JavaScript armazena pares chave-valor e permite que qualquer valor, como objetos, funções ou primitivos, seja usado como chave. Use-o quando precisar iterar na ordem de inserção, trabalhar com chaves que não são strings ou fazer muitas inserções e remoções. Diferente de objetos literais, as chaves de Map não sofrem interferência de propriedades herdadas do protótipo, o que evita surpresas com chaves dinâmicas em string.

Exemplo de JavaScript Map para armazenamento chave-valor

Saída:

95
false
2

Como este exemplo funciona

1. new Map() cria um mapa vazio. Chamar Map() sem new lança um TypeError.
2. set adiciona um par chave-valor e retorna a instância de Map, permitindo encadear chamadas como map.set("a", 1).set("b", 2). Chamar set com uma chave existente sobrescreve o valor sem mudar a posição de iteração dessa chave.
3. get retorna o valor armazenado, ou undefined se a chave não existir. Use has para diferenciar uma chave ausente de uma chave definida explicitamente como undefined.
4. size reflete a contagem atual de entradas. Em objetos, isso exige Object.keys(obj).length.

Erros comuns com JavaScript Map

Usar sintaxe de colchetes em vez de set/get:

Errado:

const mapa = new Map();
mapa["chave"] = "valor";
console.log(mapa.get("chave")); // undefined

Certo:

const mapa = new Map();
mapa.set("chave", "valor");
console.log(mapa.get("chave")); // "valor"

A sintaxe de colchetes define uma propriedade de objeto na instância de Map, não uma entrada do Map. get, has e size ignoram isso.

Esperar igualdade estrutural para chaves de objeto:

Errado:

const mapa = new Map();
mapa.set({id: 1}, "ana");
console.log(mapa.get({id: 1})); // undefined

Certo:

const chave = {id: 1};
mapa.set(chave, "ana");
console.log(mapa.get(chave)); // "ana"

Map usa SameValueZero para igualdade de chaves. Para objetos, isso significa identidade por referência: dois literais de objeto iguais visualmente são chaves diferentes.

JavaScript Map vs Object

Use Map quando as chaves não forem strings, quando entradas forem adicionadas e removidas com frequência, ou quando você armazenar chaves não confiáveis. Use objeto literal para registros de estrutura fixa ou dados que precisem de serialização JSON. Se precisar de um objeto, mas quiser evitar colisões com chaves de protótipo, use Object.create(null) como objeto base.

FAQ

JavaScript Map preserva a ordem de inserção?

Sim. Map itera as entradas na ordem em que foram inseridas pela primeira vez. set() em uma chave existente atualiza o valor, mas mantém a posição original. Remover uma chave e adicioná-la novamente move essa chave para o final.

JavaScript Map pode usar objetos como chaves?

Sim, mas Map compara chaves de objeto por referência, não por estrutura. Dois objetos diferentes com as mesmas propriedades são tratados como chaves separadas. Guarde a referência em uma variável e use essa mesma referência tanto no set quanto no get.

Como converter um JavaScript Map para objeto ou JSON?

Chame Object.fromEntries(map) para criar um objeto literal. Isso funciona quando todas as chaves são strings ou symbols. Para chaves que não são string, serializa o array de entradas com JSON.stringify([...map]).

Qual é a diferença entre JavaScript Map e a função JavaScript map()?

Map é uma coleção chave-valor para armazenar e consultar dados. A função JavaScript map() (Array.prototype.map) é um método de array que retorna um novo array aplicando um callback a cada elemento. Eles compartilham o nome, mas têm propósitos diferentes.