Posted on May 16, 2020

JavaScript .flatMap()

In my previous post, I wrote about Celebrating JavaScript .flat() and how to flatten arrays, giving a lot of love to flat(). I naturally wanted to follow it up with a post about flatMap() and look at how it works and what it does.

flatMap()

The flatMap() method is a super merger of flat() and map().

Although based on the order of operations maybe it should be called mapFlat() 🤔.

flatMap() goes through each element using a mapping function first before the returned result is flattened into a new array of depth one. It's just like using map() followed by flat() with a depth of 1, but is slightly more efficient (an excellent 2-for-1 method).

As flatMap() only flattens 1 level, if you need to flatten beyond 1 level, you can separately call map() then flat() on your array.

Syntax

arr.flatMap(function callback(currentValue[, index[, array]]) { // do work and return element for newArray }

The callback function for flatMap() takes three arguments:

currentValue: the current element being processed
index (optional): the index of the currentValue
array (optional): the array map() was called upon

const arr = ['take me out', '', 'to the ball', 'game']; arr.flatMap(a => a.split(' ')); // ["take", "me", "out", "", "to", "the", "ball", "game"]

Using flatMap() is useful when you want to add and remove items during a map(), as it can map many to many items by handling each input item separately, versus map() itself that is always one-to-one. This means the resulting array can grow during the mapping, and it will be flattened afterward.

MDN web docs has a great example below that highlights how flatMap() works to add and remove elements.

// Let's say we want to remove all the negative numbers and // split the odd numbers into an even number and a 1 let a = [5, 4, -3, 20, 17, -33, -4, 18] // |\ \ x | | \ x x | // *[4,1, 4, [], 20, 16, 1, [], [], 18]  // *this line helps to visualize what the array will look  // like during mapping, with negative numbers represented as empty []  a.flatMap( (n) => (n < 0) ? [] : (n % 2 == 0) ? [n] : [n-1, 1] ) // [4, 1, 4, 20, 16, 1, 18]