flatMap() - метод для преобразования и разворачивания массива в JavaScript

flatMap() сначала преобразует элементы массива, а потом разворачивает результат на один уровень.

Это удобный метод, когда map() и flat(1) нужны вместе.

Синтаксис

array.flatMap(callback)
array.flatMap(callback, thisArg)

callback - функция, которая будет вызвана для каждого элемента массива.

Что делает flatMap()

Метод проходит по массиву, получает результат callback для каждого элемента и затем “расплющивает” итог на один уровень.

const result = [1, 2, 3].flatMap((value) => [value, value * 10]);

console.log(result); // [1, 10, 2, 20, 3, 30]

flatMap() = map() + flat(1)

По смыслу flatMap() похож на такую запись:

const result = [1, 2, 3]
  .map((value) => [value, value * 10])
  .flat();

Результат будет тем же:

console.log(result); // [1, 10, 2, 20, 3, 30]

Но flatMap() короче и лучше показывает намерение.

Что возвращает flatMap()

flatMap() возвращает новый массив.

const numbers = [1, 2, 3];
const result = numbers.flatMap((value) => [value * 2]);

console.log(result);  // [2, 4, 6]
console.log(numbers); // [1, 2, 3]

Исходный массив при этом не меняется.

Разворачивание только на один уровень

Это один из самых важных моментов.

flatMap() разворачивает результат только на глубину 1.

const result = [1, 2].flatMap((value) => [[value]]);

console.log(result); // [[1], [2]]

Внутренние массивы глубже одного уровня уже не раскрываются.

Аргументы callback

Callback в flatMap() может получать до трёх аргументов:

array.flatMap((element, index, array) => {
  // ...
});

element - текущий элемент
index - индекс текущего элемента
array - сам исходный массив

Пример:

const words = ["a", "bb", "ccc"];

const result = words.flatMap((word, index) => [`${index}:${word}`]);

console.log(result); // ["0:a", "1:bb", "2:ccc"]

Один элемент, несколько элементов или ни одного

flatMap() особенно полезен тем, что callback может вернуть:

один элемент
массив из нескольких элементов
пустой массив

Пример:

const numbers = [1, 2, 3];

const result = numbers.flatMap((value) => {
  if (value === 2) return [];
  return [value, value * 10];
});

console.log(result); // [1, 10, 3, 30]

Из-за этого flatMap() иногда удобно использовать как комбинацию преобразования и простого “фильтра”.

flatMap() и map()

map() возвращает новый массив из результатов callback:

const result = [1, 2, 3].map((value) => [value, value * 10]);

console.log(result); // [[1, 10], [2, 20], [3, 30]]

flatMap() делает ещё один шаг и раскрывает этот результат на один уровень:

const result = [1, 2, 3].flatMap((value) => [value, value * 10]);

console.log(result); // [1, 10, 2, 20, 3, 30]

flatMap() не меняет исходный массив

Метод создаёт новый массив и не работает “на месте”.

const items = [1, 2, 3];
const result = items.flatMap((value) => [value, value + 1]);

console.log(items);  // [1, 2, 3]
console.log(result); // [1, 2, 2, 3, 3, 4]

Пустые слоты

flatMap() пропускает пустые слоты так же, как map().

const arr = Array(3);
const result = arr.flatMap((value) => [1]);

console.log(result); // []

Callback здесь вообще не вызовется.

Когда это полезно

flatMap() удобно использовать, когда:

нужно преобразовать каждый элемент массива
результатом каждого шага может быть массив
хочется сразу получить плоский результат
важно не менять исходные данные

Пример:

const sentences = ["hello world", "js"];
const words = sentences.flatMap((text) => text.split(" "));

console.log(words); // ["hello", "world", "js"]

Частые ошибки

Думать, что flatMap() разворачивает массив на любую глубину

const result = [1, 2].flatMap((value) => [[value]]);

console.log(result); // [[1], [2]]

Метод раскрывает результат только на один уровень.

Путать flatMap() и map()

const result = [1, 2].map((value) => [value]);

console.log(result); // [[1], [2]]

Если нужен плоский результат, одного map() недостаточно.

Забывать, что метод возвращает новый массив

const numbers = [1, 2, 3];

numbers.flatMap((value) => [value * 2]);

console.log(numbers); // [1, 2, 3]

Если результат не сохранить, исходный массив останется прежним.

Быстрая памятка

flatMap() сначала выполняет map(), потом делает flat(1)
метод возвращает новый массив
исходный массив не меняется
разворачивание идёт только на один уровень
flatMap() удобен, когда callback возвращает массивы

Коротко

flatMap() - это удобный способ одновременно преобразовать элементы массива и получить плоский результат. Главное, что стоит запомнить: метод раскрывает результат только на один уровень и возвращает новый массив, не меняя исходный.