Basics

What is a Map in JavaScript — and why an object secretly turns your keys into text

Illustration: a key ring where the keys are a coin, a leaf and a cup — each tied to its own box

Watch this trick. Make an empty object and put two values in it — under the key 1 and under the key "1":

const box = {}
box[1] = "number"
box["1"] = "string"
box   // { "1": "string" }

Only one is left. The object quietly turned the number 1 into the text "1" — and the second value overwrote the first. No error. And if you use another object as a key, it gets silly: the key becomes the string "[object Object]". One for every object at once.

That's what Map is for in JavaScript.

What a Map is

A Map is a dictionary: a set of "key → value" pairs. You put things in by key and get them out by key. Like a coat check: hand in your coat, get a ticket, use the ticket to get it back.

const prices = new Map()
prices.set("coffee", 250)
prices.set("tea", 180)

prices.get("coffee")   // 250
prices.has("juice")    // false
prices.size            // 2

The main difference from an object: the key can be anything, and Map doesn't change it. A number stays a number, a string stays a string. Even an object can be a key — the object itself, not its text label.

const m = new Map()
m.set(1, "number")
m.set("1", "string")
m.size   // 2 — both are there

Don't confuse it with .map()

This is where beginners get lost. JavaScript has two different "map"s, and all they share is the name.

  • new Map() — a collection, a dictionary. It stores pairs.
  • array.map(...) — an array method. It turns one list into another: prices.map(p => p * 2). More on it in for loop or map.

How to tell them apart in AI-written code: if you see new Map or .set( and .get(, it's the dictionary. If .map( follows an array with an arrow inside, it's a list transformation.

Map or a plain object

An object can store pairs too, and in most AI-written code that's what you'll see. So when is a Map better?

Use a Map when:

  • the keys aren't strings: numeric ids, objects, dates;
  • the keys come from users. The word "constructor" or "__proto__" behaves oddly in an object; in a Map it's just another key;
  • pairs are added and removed often. Map is built for that — it has size and delete;
  • order matters. A Map gives pairs back in exactly the order you put them in.

Stick with an object when:

  • it describes one thing with fields known in advance: { name, email, age };
  • the data needs to be sent to a server or saved. More on that below.

The big trap: JSON

A Map doesn't survive being turned into JSON. No error — just emptiness:

JSON.stringify(new Map([["coffee", 250]]))   // "{}"

You saved a Map to localStorage, reloaded the page — the data is gone. You sent it to the server — an empty object arrived. It's one of the quietest bugs there is, because everything works until the reload.

The fix is one line each way:

// Map → object, before saving
const plain = Object.fromEntries(prices)

// object → Map, after loading
const back = new Map(Object.entries(plain))

If the keys aren't strings, save it as an array of pairs: [...prices], and back with new Map(pairs).

Where you'll run into it

In AI-written code, Map most often plays one of three roles:

  • cache: remember a server response by id so you don't fetch it again — cache.get(id);
  • counting: how many times each word appears — counts.set(word, (counts.get(word) ?? 0) + 1);
  • "object → data" link: keep something next to a DOM element or a user without touching the object itself.

You loop over a Map with a plain for...of — pair by pair:

for (const [item, price] of prices) {
  console.log(item, price)
}

How to ask the AI

Out of habit, models reach for an object even where a Map belongs. Name the structure outright — and warn about saving while you're at it:

Weak promptmake a cache for server responses
Strong promptMake a cache of API responses with a Map: the key is the product id (a number), the value is the product object. Before a request, check cache.has(id). If the cache has to be saved to localStorage, turn it into an array of pairs and back with new Map(pairs).

The weak prompt gives you an object with string keys and, most likely, quietly loses the cache on save. The strong one closes both traps from this article in advance.

Is a Map faster than an object?

For frequent adds and deletes, usually yes — it's optimized for that. On small data sets the difference is invisible, so choose by meaning, not by speed.

How is a Map different from a Set?

A Set stores plain values with no repeats — "is it there or not." A Map stores pairs: each key has a value attached.

What does Python use instead of Map?

A regular dict. Unlike a JavaScript object, it doesn't turn keys into strings: 1 and "1" are different keys there — exactly like in a Map.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →