Iterator.prototype.flatMap() — Methode · JavaScript-Referenz

Signatur

Iterator.prototype.flatMap(callbackFn)

Beschreibung

Iterator.prototype.flatMap() ist das Gegenstück zu Array.prototype.flatMap() für Iteratoren. Die Methode ruft für jedes Element des ursprünglichen Iterators eine Mapping-Funktion auf. Diese muss ein Iterable (z. B. ein Array, ein Set oder eine Map) oder einen Iterator zurückgeben. Die Elemente dieses Ergebnisses werden einzeln an den neuen Iterator weitergegeben. Das Ergebnis wird also um genau eine Ebene abgeflacht.

Im Gegensatz zur Array-Variante arbeitet flatMap() verzögert (lazy): Beim Aufruf passiert noch nichts. Erst wenn der zurückgegebene Iterator-Helfer mit next(), for...of, toArray() o. Ä. abgefragt wird, holt er Elemente aus der Quelle und ruft die Mapping-Funktion auf. Deshalb eignet sich die Methode auch für sehr große oder unendliche Datenquellen wie Generatoren, solange du sie mit take() oder einer Abbruchbedingung begrenzt.

Typische Einsatzfälle sind das Auflösen verschachtelter Strukturen, z. B. Gruppen mit Mitgliedern, Sätze mit Wörtern oder Verzeichnisse mit Dateien. Außerdem kannst du Elemente mit flatMap() in einem Schritt filtern und umwandeln: Gibst du ein leeres Array zurück, wird das Element verworfen. Gibst du [wert] zurück, wird es übernommen.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(element: any, index: number) => Iterable \| Iterator		Funktion, die für jedes Element aufgerufen wird. Sie erhält das aktuelle `element` und dessen fortlaufenden `index` (ab 0). Sie muss ein Iterable oder einen Iterator zurückgeben, dessen Elemente in den Ergebnis-Iterator übernommen werden. Primitive Werte wie Strings sind nicht erlaubt.

Rückgabewert

Typ

Iterator (Iterator-Helfer)

Beschreibung

Ein neues Iterator-Helfer-Objekt, das die Elemente der von callbackFn gelieferten Iterables bzw. Iteratoren nacheinander ausgibt. Es erbt von Iterator.prototype und bietet daher weitere Helfer wie map(), filter(), take() und toArray().

Beispiele

Sätze in einzelne Wörter zerlegen

const saetze = ["Hallo Welt", "Iterator Helfer"].values();

// split() liefert ein Array, das abgeflacht wird
const woerter = saetze.flatMap((satz) => satz.split(" "));

console.log([...woerter]);

[ 'Hallo', 'Welt', 'Iterator', 'Helfer' ]

Verschachtelte Map-Daten auflösen

const teams = new Map([
  ["Frontend", ["Anna", "Ben"]],
  ["Backend", ["Clara"]],
  ["Design", []] // leeres Team: liefert keine Elemente
]);

const mitglieder = teams
  .entries()
  .flatMap(([team, namen]) => namen.map((name) => `${name} (${team})`))
  .toArray();

console.log(mitglieder);

[ 'Anna (Frontend)', 'Ben (Frontend)', 'Clara (Backend)' ]

Verzögerte Auswertung mit unendlichem Generator

function* natuerlicheZahlen() {
  let n = 1;
  while (true) yield n++;
}

// Jede Zahl n wird n-mal ausgegeben; take() begrenzt die unendliche Folge
const ergebnis = natuerlicheZahlen()
  .flatMap((n) => Array(n).fill(n))
  .take(6)
  .toArray();

console.log(ergebnis);

[ 1, 2, 2, 3, 3, 3 ]

Fallstrick: Strings als Rückgabewert

const kuerzel = ["ab", "cd"].values().flatMap((s) => s);

try {
  kuerzel.toArray(); // Fehler tritt erst beim Abfragen auf
} catch (err) {
  console.log(err instanceof TypeError);
}

// Lösung: String explizit in ein Array aufspalten
const zeichen = ["ab", "cd"].values().flatMap((s) => [...s]).toArray();
console.log(zeichen);

true [ 'a', 'b', 'c', 'd' ]

// Wichtig · Fallstricke

Keine primitiven Rückgabewerte: Anders als Array.prototype.flatMap() akzeptiert die Methode keine Einzelwerte. Gibt callbackFn eine Zahl, undefined oder einen String zurück, wird ein TypeError ausgelöst, obwohl Strings eigentlich iterierbar sind. Einzelwerte packst du deshalb in ein Array: [wert].
Fehler treten verzögert auf: Weil flatMap() erst beim Abfragen ausgewertet wird, erscheinen Fehler in callbackFn nicht beim Aufruf von flatMap(), sondern erst bei next(), toArray() oder in for...of.
Nur eine Ebene: Tiefer verschachtelte Arrays im Ergebnis werden nicht weiter aufgelöst. Einen Tiefe-Parameter wie bei Array.prototype.flat(depth) gibt es nicht.
Einmal verwendbar: Der Iterator-Helfer ist nach einmaligem Durchlaufen erschöpft. Für einen zweiten Durchlauf musst du einen neuen Iterator erzeugen.
Aufräumen: Brichst du früher ab, etwa mit break, take() oder return(), werden der gerade aktive innere Iterator und der äußere Quell-Iterator ordnungsgemäß geschlossen.
Kompatibilität: Iterator-Helfer gehören seit ES2025 zum Standard (Chrome/Edge 122+, Firefox 131+, Safari 18.4+, Node.js 22+). Für ältere Umgebungen gibt es Polyfills, z. B. in core-js. Arrays selbst haben keine Methode flatMap() aus dem Iterator-Prototyp; du rufst sie über array.values() auf.

Siehe auch

Iterator Iterator.prototype.map() Iterator.prototype.filter() Iterator.prototype.take() Iterator.prototype.toArray() Array.prototype.flatMap()