map, filter & reduce

Do one job to a whole list

An array is a list of values. Arrays often hold many similar things: products in a cart, names in a class, or messages in an inbox.

You already know how a loop visits each item, one index at a time. With a loop, you write every step yourself: start at 0, read the item, move to the next index. Arrays also have built-in methods that do the walking for you. You only say what should happen to each item. Code that says what you want, not how to walk the list, is called declarative code.

Here is which method to pick:

• map: every item becomes one new item.
• filter: some items stay and some are left out.
• reduce: all the items become one final value, like a total.
• forEach: you want to do something with each item, like print it, and you don't need a new array back.
• flat and flatMap: you have arrays inside an array and want one plain list.

The table below puts the five methods side by side. Read each row as: "use this method when…, it gives back…, and the original array…".

map calls your function once for each item. Whatever your function returns goes into a new array. So the new array always has the same number of items as the old one.

const prices = [3, 5, 8];
const doubled = prices.map(price => price * 2);

console.log(doubled);
console.log(prices);

• Line 1 makes an array of three prices.
• Line 2 calls map. For each price, the arrow function returns that price times 2. map puts those answers in a new array called doubled.
• Line 4 prints [6, 10, 16], the new array.
• Line 5 prints [3, 5, 8]. The original prices array did not change.

The next example shows three mistakes people often make with map. The last line checks that the original array is still the same.

1const numbers = [1, 2, 3];2const missingReturn = numbers.map(n => { n * 2; });3const objects = numbers.map(n => ({ value: n }));4const parsed = ["1", "2", "3"].map(parseInt);5 6console.log(missingReturn);7console.log(objects);8console.log(parsed);9console.log(numbers);

• Line 2 has curly braces around the function body. With braces, an arrow function only gives back a value if you write return. There is no return here, so each call gives back undefined. Line 6 prints [undefined, undefined, undefined].
• Line 3 wants to return an object, like { value: 1 }. The round brackets around the object tell JavaScript "this is a value to return." Without them, JavaScript would read the curly braces as a function body. Line 7 prints three objects.
• Line 4 passes parseInt straight to map. parseInt turns text into a whole number. Its second input is the number base: 10 for normal numbers, 2 for binary. The number base is also called the radix. But map gives your function three inputs: the item, its index, and the whole array. So parseInt gets the index as its base. Line 8 prints [1, NaN, NaN]. NaN means "not a number".

filter calls your function once for each item. Your function is a test. It answers "should this item stay?"

• If the answer is truthy, the item stays. Truthy means "counts as yes": true, and most other values too.
• If the answer is falsy, the item is left out. Falsy means "counts as no". The falsy values you will meet most are false, 0, "" (empty text), null, undefined, and NaN.

Your test doesn't have to return exactly true or false. Still, a clear check like age >= 18 is the easiest to read.

const cart = [
  { name: "tea", inStock: true },
  { name: "cake", inStock: false },
  { name: "juice", inStock: true },
];
const available = cart.filter(item => item.inStock);

console.log(available.map(item => item.name));
console.log(cart.map(item => item.name));

• Lines 1 to 5 make a small cart with three items.
• Line 6 keeps only the items whose inStock is true. They go into a new array called available.
• Line 8 prints the names that stayed: ["tea", "juice"].
• Line 9 prints ["tea", "cake", "juice"]. The original cart still has all three items.

1const values = [0, "hi", "", 42, null, "ok"];2const compact = values.filter(Boolean);3const adults = [{ age: 17 }, { age: 22 }, { age: 31 }].filter(person => person.age >= 18);4 5console.log(compact);6console.log(adults.map(person => person.age));

• Line 2 passes Boolean as the test. Boolean(value) turns any value into true or false. So filter(Boolean) keeps the truthy values and drops the falsy ones. Line 5 prints ["hi", 42, "ok"].
• Line 3 keeps the people aged 18 or more. Line 6 prints their ages, [22, 31].

Use filter(Boolean) when you really mean "remove the empty values". Don't use it when 0 is a real value you need to keep, because 0 is falsy and would be dropped too.

reduce turns a whole array into one value, like a total. It does this by carrying a running result from one item to the next. This running result is called the accumulator.

Your function gets two inputs on each turn:

• the accumulator, which is the result so far, and
• the current item.

Whatever your function returns becomes the accumulator for the next item. After the last item, reduce gives back the accumulator. reduce can do a lot, so it is also easy to use it where a simpler method would be clearer.

The accumulator can start as many kinds of value. A sum starts at 0 and adds each price. A word counter starts as an empty object, {}, and adds one property per word. A text builder starts as empty text, "", and adds words to it.

const prices = [2, 3, 5];
const total = prices.reduce((sum, price) => sum + price, 0);

console.log(total);

• Line 1 makes an array of three prices.
• Line 2 calls reduce. The 0 at the end is the start value for sum, the accumulator. On each turn, the arrow function returns sum + price.
• Line 4 prints 10. Three prices became one number.

Step through the code below to watch the accumulator, acc, change on each turn. Try all three ways of starting.

1const prices = [5, 12, 3];Run2const total = prices.reduce((acc, price) => {3  return acc + price;4}, 0);5console.log(total);

Always give reduce a start value if you can. Here is what happens without one:

• reduce uses the first item as the start value. Your function then begins at the second item.
• If the array is empty, there is no first item. [].reduce(callback) then stops with an error: TypeError: Reduce of empty array with no initial value.

reduceRight works just like reduce, but it visits the items from right to left: last item first. Use it when the order matters, for example when you build text starting from the end.

filter and map give back a new array. So you can call the next method straight on that new array. Writing methods one after another like this is called chaining.

For a shopping cart, a chain could do four steps:

1. Keep the items that are in stock.
2. Add tax to each price.
3. Keep the items that cost more than 5.
4. Add the prices into one total.

A good chain reads like a checklist, one short step per line. If one step gets long, move it into its own named function. Or save the result so far in a variable with a clear name, then go on.

const prices = [2, 5, 8];
const total = prices
  .filter(price => price > 3)
  .map(price => price * 2)
  .reduce((sum, price) => sum + price, 0);

console.log(total);

• Line 1 makes the prices 2, 5, and 8.
• Line 3 keeps the prices above 3. That leaves [5, 8].
• Line 4 doubles them. That gives [10, 16].
• Line 5 adds them, starting from 0. That gives 26.
• Line 7 prints 26.

In the playground below, turn each step of the cart chain on or off. You will see the array after every step and the final total.

Line 10 builds a new object for each item with { ...item, priceWithTax: ... }. The three dots copy every property of item into the new object. Then priceWithTax is added next to them.

1const cart = [2  { name: "Notebook", price: 4, inStock: true },3  { name: "Marker", price: 2, inStock: false },4  { name: "Mug", price: 8, inStock: true },5  { name: "Stickers", price: 3, inStock: true },6];7 8const total = cart9  .filter(item => item.inStock)10  .map(item => ({ ...item, priceWithTax: item.price * 1.1 }))11  .filter(item => item.priceWithTax > 5)12  .reduce((sum, item) => sum + item.priceWithTax, 0);

flat and flatMap: unpack arrays inside arrays

Sometimes an array holds other arrays. An array inside an array is called a nested array. Each array inside is one level deeper.

• flat gives back a new array with the inner arrays unpacked. With no input, it unpacks one level.
• flatMap does a map first, then unpacks one level.

const boxes = [["tea", "cake"], ["juice"]];
const items = boxes.flat();

console.log(items);

• Line 1 puts two small arrays inside boxes.
• Line 2 calls flat. It takes the items out of the two small arrays and puts them in one new list.
• Line 4 prints ["tea", "cake", "juice"]. boxes itself did not change.

1const nested = [1, [2, [3]]];2const oneLevel = nested.flat();3const allLevels = nested.flat(Infinity);4const letters = ["map", "fun"].flatMap(word => word.split(""));5 6console.log(oneLevel);7console.log(allLevels);8console.log(letters);

• Line 1 has an array three levels deep: [3] sits inside [2, [3]], which sits inside the outer array.
• Line 2 unpacks one level. Line 6 prints [1, 2, [3]]. The [3] was one level too deep, so it is still an array.
• Line 3 passes Infinity, which means "keep unpacking until no arrays are left". Line 7 prints [1, 2, 3].
• Line 4 splits each word into its letters with word.split(""). That makes one array of letters per word. flatMap then unpacks them into one list. Line 8 prints the six letters.

Beginners often use forEach when they need map. Here is the difference:

• forEach calls your function for each item. Then it gives back undefined, which means nothing.
• map calls your function for each item. Then it gives back a new array of your function's answers.

So forEach is only for side effects. A side effect is a change that your function makes outside itself, such as:

• printing to the console,
• changing the page,
• pushing into an array that already exists.

const names = ["Asha", "Bo"];
const greetings = [];
names.forEach(name => greetings.push("Hi " + name));

console.log(greetings);

• Line 1 makes two names. Line 2 makes an empty array, greetings.
• Line 3 runs once per name. Each time, it pushes a greeting into greetings. That push is the side effect.
• Line 5 prints ["Hi Asha", "Hi Bo"]. The useful result is in greetings, not in anything forEach gave back.

1const numbers = [1, 2, 3];2const mapped = numbers.map(n => n * 2);3const visited = [];4const eachResult = numbers.forEach(n => visited.push(n * 2));5 6console.log(mapped);7console.log(visited);8console.log(eachResult);

• Line 2 uses map. Line 6 prints the new array, [2, 4, 6].
• Line 4 uses forEach to push the same doubled numbers into visited. Line 7 prints [2, 4, 6].
• Line 8 prints undefined. That is what forEach gave back on line 4.

One more difference: you can't stop forEach early. break does not work inside it. If you need to stop early, use a for...of loop. Or use some or every, which stop as soon as they know the yes-or-no answer.

Where you'll use this

You will use these methods whenever you turn data into something on the page. For example, you can turn an object into a list of pairs with Object.entries, change each pair with map, and then show the result.

reduce can do more than add numbers. The code below uses it twice: once to count words, and once to put words into groups.

1const words = ["tea", "coffee", "tea", "juice"];2const counts = words.reduce((result, word) => {3  result[word] = (result[word] ?? 0) + 1;4  return result;5}, {});6 7const grouped = words.reduce((result, word) => {8  const first = word[0];9  (result[first] ??= []).push(word);10  return result;11}, {});12 13console.log(counts);14console.log(grouped);

• Lines 2 to 5 count each word. The accumulator, result, starts as an empty object, {}.
• Line 3 reads the old count for the word. If there is none yet, ?? 0 uses 0 instead. Then it adds 1 and stores the new count.
• Line 4 returns the same object, so the next turn gets it.
• Lines 7 to 11 group words by their first letter. Line 8 reads the first letter, like "t" for "tea".
• Line 9 uses ??=. It creates an empty array for that letter only if there isn't one yet. Then it pushes the word in.
• Line 13 prints { tea: 2, coffee: 1, juice: 1 }. Line 14 prints the groups.

Newer JavaScript has a built-in method for grouping, Object.groupBy. Some older browsers don't have it. So check first that it exists: typeof Object.groupBy === "function". If it doesn't exist, use reduce. reduce also works when you need a result shaped in your own way.

Common misconceptions

Read each function carefully and work out what it returns. After you answer, read the explanation for every choice, even the wrong ones.

Key takeaways

• map changes each item and gives back a new array with the same number of items.
• filter keeps the items whose test answer is truthy, which means it counts as yes.
• reduce carries a running result, the accumulator, through the list and gives back one final value. Give it a start value.
• flat unpacks arrays inside an array. flatMap does a map, then unpacks one level.
• forEach gives back undefined. Use it only to do something, like printing, not to make a new array.

Up next: Sorting & copying safely.