Iterator.prototype.flatMap()

Метод flatMap() экземпляров Iterator возвращает новый объект-помощник итератора, который берет каждый элемент исходного итератора, пропускает его через функцию отображения, и выдает элементы, возвращаемые функцией отображения (которые содержатся в другом итераторе или итерируемом объекте).

Синтаксис

flatMap(callbackFn)

Параметры

callbackFn

Функция, которая будет выполняться для каждого элемента, сгенерированного итератором. Она должна возвращать итератор или итерируемый объект, который выдает элементы, которые будут выданы flatMap(). Обратите внимание, что в отличие от Array.prototype.flatMap(), вы не можете возвращать одиночные не-итераторы/не-итерируемые значения. Функция вызывается со следующими аргументами:

element

Текущий обрабатываемый элемент в массиве.

index

Индекс текущего обрабатываемого элемента в массиве.

Возвращаемое значение

Новый объект-помощник итератора. При первом вызове метода next() объекта-помощника итератора, он вызывает callbackFn для первого элемента, произведенного нижележащим итератором, и возвращаемое значение, которое должно быть итератором или итерируемым объектом, выдается по одному объектом-помощником итератора (подобно yield*). Следующий элемент извлекается из нижележащего итератора, когда завершается предыдущий, возвращенный callbackFn. Когда нижележащий итератор завершен, объект-помощник итератора также завершается (метод next() производит { value: undefined, done: true }).

Исключения

TypeError

Выдается, если callbackFn возвращает не-итератор/не-итерируемое значение или строковый примитив.

Описание

flatMap принимает два типа возвращаемых значений от callbackFn: итератор или итерируемый объект. Они обрабатываются так же, как Iterator.from(): если возвращаемое значение является итерируемым объектом, вызывается метод [Symbol.iterator]() и используется возвращаемое значение; в противном случае возвращаемое значение рассматривается как итератор, и вызывается его метод next().

[1, 2, 3]
  .values()
  .flatMap((x) => {
    let itDone = false;
    const it = {
      next() {
        if (itDone) {
          return { value: undefined, done: true };
        }
        itDone = true;
        return { value: x, done: false };
      },
    };
    switch (x) {
      case 1:
        // An iterable that's not an iterator
        return { [Symbol.iterator]: () => it };
      case 2:
        // An iterator that's not an iterable
        return it;
      case 3:
        // An iterable iterator is treated as an iterable
        return {
          ...it,
          [Symbol.iterator]() {
            console.log("Symbol.iterator called");
            return it;
          },
        };
      default:
        return undefined;
    }
  })
  .toArray();
// Logs "Symbol.iterator called"
// Returns [1, 2, 3]

Примеры

Объединение Map-объектов

Следующий пример объединяет два объекта Map в один:

const map1 = new Map([
  ["a", 1],
  ["b", 2],
  ["c", 3],
]);
const map2 = new Map([
  ["d", 4],
  ["e", 5],
  ["f", 6],
]);

const merged = new Map([map1, map2].values().flatMap((x) => x));
console.log(merged.get("a")); // 1
console.log(merged.get("e")); // 5

Это позволяет избежать создания временных копий содержимого Map-объекта. Обратите внимание, что массив [map1, map2] должен быть сначала преобразован в итератор (используя Array.prototype.values()), потому что Array.prototype.flatMap() "сглаживает" только массивы, а не итерируемые объекты.

new Map([map1, map2].flatMap((x) => x)); // Map(1) {undefined => undefined}

Возвращение строк

Строки являются итерируемыми, но flatMap() специально отклоняет строковые примитивы, возвращаемые из callbackFn, поскольку поведение итерации по кодовым точкам часто не является тем, что вам нужно.

[1, 2, 3]
  .values()
  .flatMap((x) => String(x))
  .toArray(); // TypeError: Iterator.prototype.flatMap called on non-object

Вместо этого вы можете обернуть его в массив, чтобы вся строка была выдана как единый элемент:

[1, 2, 3]
  .values()
  .flatMap((x) => [String(x)])
  .toArray(); // ['1', '2', '3']

Или, если поведение итерации по кодовым точкам задумано, вы можете использовать Iterator.from() для преобразования его в надлежащий итератор:

[1, 2, 3]
  .values()
  .flatMap((x) => Iterator.from(String(x * 10)))
  .toArray();
// ['1', '0', '2', '0', '3', '0']

Спецификации

Совместимость с браузерами

См. также

• Полифилл Iterator.prototype.flatMap в core-js
• Полифилл es-shims для Iterator.prototype.flatMap