JavaScript flatMap(): Transforming and Flattening Data Efficiently

Abstract

Handling structured data efficiently is a critical task in JavaScript, especially when working with nested arrays or transforming API responses. The flatMap() function provides an elegant solution by combining mapping and flattening into a single step. This article explores how flatMap() simplifies data conversion, particularly when working with nested data structures such as API responses.

Introduction

Modern JavaScript applications often deal with nested data, whether from APIs, user inputs, or database queries. The traditional approach to processing such data involves using .map() to transform the elements, followed by .flat() to flatten the result. However, this method can lead to unnecessary complexity and performance overhead.

To address this, JavaScript introduced the flatMap() method, which combines mapping and flattening in one step. It is particularly useful in data transformation tasks, such as extracting information from API responses, filtering out empty values, and restructuring datasets for better usability.

Main Content

1. Understanding `flatMap()`

1.1 Syntax and Explanation

The flatMap() method is used on arrays to map each element to a new value (like map()) and flatten the result by one level (like flat(1)).

Syntax

array.flatMap(callback(element, index, array), thisArg);

callback – A function applied to each element.
element – The current array element.
index – The index of the current element.
array – The original array.
thisArg (optional) – A value to use as this inside the callback.

2. Practical Use Case: Flattening API Responses

When working with APIs, responses often contain nested data. Let’s take an example where we fetch user data, including multiple phone numbers for each user.

2.1 API Response Example

Consider an API returning a list of users with their phone numbers:

const users = [
  { name: "Alice", phones: ["123-456", "789-101"] },
  { name: "Bob", phones: ["112-233"] },
  { name: "Charlie", phones: [] },
];

Each user has one or more phone numbers stored in an array. Our goal is to extract all phone numbers into a single flat list.

2.2 Using `.map()` (Without Flattening)

Using .map(), we get a nested array because each user’s phones are in a sub-array:

const mappedPhones = users.map((user) => user.phones);

console.log(mappedPhones);
// Output: [["123-456", "789-101"], ["112-233"], []]   (Nested array)

This is not ideal, as we have unnecessary nesting.

2.3 Using `.flatMap()` (Flattened Result)

With .flatMap(), we extract and flatten the phone numbers in one step:

const allPhones = users.flatMap((user) => user.phones);

console.log(allPhones);
// Output: ["123-456", "789-101", "112-233"]   (Flat array)

✔ Why is this better?

We avoid an extra .flat() operation.
The code is cleaner and more efficient.
The result is ready for further processing (e.g., filtering duplicates).

3. Comparing `flatMap()` with Other Methods

3.1 Using `.map().flat()` (Alternative Approach)

Before flatMap(), we had to chain .map() and .flat():

const allPhones = users.map((user) => user.phones).flat();

console.log(allPhones);
// Output: ["123-456", "789-101", "112-233"]

This works, but .flatMap() is preferred because:

It avoids creating an intermediate nested array.
It improves performance, as only one iteration is needed.

3.2 Using `reduce()` (More Complex Approach)

Another way to flatten data is with .reduce(), but this is less readable:

const allPhones = users.reduce((acc, user) => acc.concat(user.phones), []);

console.log(allPhones);
// Output: ["123-456", "789-101", "112-233"]

✔ Why avoid this?

.reduce() is less intuitive for simple flattening tasks.
It’s harder to read than .flatMap().

4. Additional Use Cases for `flatMap()`

4.1 Removing Empty or `null` Values

If an API response contains empty or null values, flatMap() helps filter them out while flattening:

const data = ["apple", "", "banana", null, "cherry"];

const filteredData = data.flatMap((item) => (item ? [item] : []));

console.log(filteredData);
// Output: ["apple", "banana", "cherry"]

4.2 Splitting Sentences into Words

const sentences = ["Hello world", "JavaScript is fun"];

const words = sentences.flatMap((sentence) => sentence.split(" "));

console.log(words);
// Output: ["Hello", "world", "JavaScript", "is", "fun"]

✔ Why use flatMap()?

Avoids the extra step of flattening manually.
Results in a single, clean array of words.

Conclusion

JavaScript's flatMap() is a powerful tool for transforming and flattening arrays efficiently. It is particularly useful for:

✅ Flattening nested API responses
✅ Filtering out unwanted values while transforming data
✅ Breaking down text into structured elements

Compared to .map().flat(), flatMap() is more efficient and easier to read. It removes unnecessary intermediate arrays, making code cleaner and more performant.

References

Mozilla Developer Network (MDN). (n.d.). Array.prototype.flatMap()