map: one array in, a new array out

A very large share of real programming is one job: I have a list of things, and I need a list of slightly different things. Prices in pounds, and I need prices with tax. User records, and I need just their names. Raw measurements, and I need them rounded. The list is the same length, in the same order — only each item has been changed.

You already know how to do that with a loop: make an empty array, walk the original, push a transformed value onto the new one. You wrote that function in the last lesson. It is four lines of bookkeeping around one line of actual work, and it is so common that JavaScript gives it a name.

That name is map. It is the single most used array method in the language, and once it clicks you will see the pattern everywhere.

Picture a conveyor belt carrying items past a machine. Each item goes in, a changed item comes out, and it lands on a second belt in the same position it had on the first. Nothing is added, nothing is dropped, nothing is reordered. When the first belt is empty, the second belt holds exactly as many items as the first one did.

You supply the machine — that is your callback. map supplies the belts. And crucially, the original belt still has its items on it: map does not consume or alter the array it was called on. What you get back is new.

You write const changed = original.map(callback). map calls your callback once per element, in order, and collects each returned value into a new array, which it hands back. The original is untouched.

Two consequences follow, and both are load-bearing. First, the output always has exactly the same length as the input. map cannot drop items — that is filter's job, two lessons from now — and it cannot add them. If you find yourself wanting a shorter array out, you have reached for the wrong method. Second, because the result is a genuinely new array, you must assign it to something or pass it somewhere. Calling map and ignoring what it returns does nothing useful at all.

The callback receives the same three arguments as forEach: the element, its index, and the array. And as before, take only what you need.

The commonest map of all is not arithmetic, it is extraction: an array of objects goes in, an array of one field goes out. Given a list of user objects, users.map((user) => user.name) gives you a list of names.

This reads as a sentence, which is the point. A counting loop that builds the same list forces the reader to hold a counter, a length and an index expression in their head just to work out that the answer is 'the names'. The map version says it directly.

One piece of syntax to have ready: when the thing you want to return is an object literal, wrap it in parentheses. An arrow function written as (user) => { name: user.name } is not returning an object — the braces are read as a function body, and it returns undefined. Writing (user) => ({ name: user.name }) makes the intent unambiguous.

Forgetting to return. An arrow function with a concise body — (n) => n * 10 — returns its expression automatically. Add braces and it becomes a full body, and a full body returns nothing unless you say return. So (n) => { n * 10 } produces an array of undefined, one per element. If a map result comes back the right length but full of nothing, this is why.

Using map for its side effects. If your callback prints, or pushes onto another array, and you do not use what map hands back, you have written a forEach with extra steps and an array nobody wanted. Say what you mean: forEach for effects, map for results.

Passing a built-in straight in. ['10', '10', '10'].map(parseInt) does not give [10, 10, 10]. map passes three arguments to whatever function it is given, and parseInt reads its second argument as a number base — so it is asked to parse in base 0, then base 1, then base 2. The result is [10, NaN, 2]. The fix is to wrap it yourself: .map((text) => parseInt(text, 10)), or use Number, which takes only one argument.

One thing to know before you run the examples, so you do not misread them. The run pad in this product prints a value by converting it to JSON. That is why an array prints as [20,40,60] with no spaces, and why an object prints with quoted keys.

JSON has no way to write undefined, so anything undefined sitting inside an array prints as null. Something similar happens to NaN. That is the pad's display, not something JavaScript did to your data — print the element on its own and you will see undefined or NaN as expected. Being told this once is cheaper than spending an evening hunting for a null your code never created.

Hold on to one sentence: map is one in, one out, in order, into a new array. Every question you will have about map is answered by it. Can it filter? No — one in, one out. Can it reorder? No — in order. Does it change the original? No — into a new array.

When what you want does not fit that sentence, a different method fits instead, and the next two lessons supply them. Keeping the methods honest about what they each do is what makes a chain of them readable later.

map builds a new array by calling your function on every element and collecting what it returns. The result has the same length and order as the input, and the input is unchanged. A concise arrow body returns automatically; a braced body needs an explicit return, or every element comes back undefined. Use forEach when you want effects and map when you want results, and never hand map a built-in function that takes more than one argument.