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

Signatur

Iterator.prototype.map(callbackFn)

Beschreibung

Iterator.prototype.map() ist das Iterator-Gegenstück zu Array.prototype.map(). Die Methode erzeugt ein neues Iterator-Hilfsobjekt, das bei jedem Aufruf von next() das nächste Element des Quell-Iterators holt, es an callbackFn übergibt und deren Rückgabewert liefert.

Der entscheidende Unterschied zu Arrays: Die Verarbeitung ist lazy. Es wird kein Zwischen-Array angelegt, und die Abbildungsfunktion läuft erst, wenn tatsächlich ein Wert angefordert wird. Dadurch eignet sich map() für große oder sogar unendliche Datenquellen (z. B. Generatoren) sowie für Ketten wie .filter().map().take(), bei denen nur so viel berechnet wird wie nötig.

Verfügbar ist die Methode auf allen Iteratoren, die von Iterator.prototype erben – also auf Generatoren sowie den Iteratoren von Array.prototype.values(), Map.prototype.entries(), Set.prototype.values(), String.prototype[Symbol.iterator]() usw. Für eigene Iterator-Objekte, die nicht von Iterator.prototype erben, hilft Iterator.from().

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(value: any, index: number) => any		Abbildungsfunktion, die für jedes Element aufgerufen wird. Erhält den aktuellen Wert `value` und den nullbasierten Zähler `index`. Ihr Rückgabewert wird vom neuen Iterator geliefert. Anders als bei `Array.prototype.map()` gibt es kein drittes Argument und kein `thisArg`.

Rückgabewert

Typ

Iterator

Beschreibung

Ein neues Iterator-Hilfsobjekt (erbt von Iterator.prototype), dessen next()-Methode die transformierten Werte liefert. Es ist selbst iterierbar und unterstützt alle weiteren Iterator-Helfer.

Beispiele

Werte eines Map-Objekts transformieren

const preise = new Map([
  ['Apfel', 0.5],
  ['Birne', 0.8],
  ['Kiwi', 0.3]
]);

// Nettopreise in Bruttopreise umrechnen, ohne Zwischen-Array
const brutto = preise
  .values()
  .map((netto) => +(netto * 1.19).toFixed(2));

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

[0.6, 0.95, 0.36]

Lazy-Verarbeitung eines unendlichen Generators

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

const quadrate = natuerlicheZahlen()
  .map((n) => n * n)
  .filter((q) => q % 2 === 1)
  .take(4);

console.log(quadrate.toArray());

[1, 9, 25, 49]

Index-Parameter nutzen und schrittweise mit next() lesen

const namen = ['Anna', 'Ben', 'Clara'].values();

const nummeriert = namen.map((name, i) => `${i + 1}. ${name}`);

console.log(nummeriert.next());
console.log(nummeriert.next().value);
for (const zeile of nummeriert) console.log(zeile);

{ value: '1. Anna', done: false } 2. Ben 3. Clara

Eigenes Iterator-Objekt mit Iterator.from() erweitern

// Einfaches Objekt, das nicht von Iterator.prototype erbt
let zaehler = 0;
const roh = {
  next: () => (zaehler < 3
    ? { value: zaehler++, done: false }
    : { value: undefined, done: true })
};

const verdoppelt = Iterator.from(roh).map((x) => x * 2);
console.log([...verdoppelt]);

[0, 2, 4]

// Wichtig · Fallstricke

Lazy statt sofort: callbackFn wird erst beim Konsumieren (next(), for...of, Spread, toArray()) aufgerufen. Seiteneffekte in der Funktion passieren also zeitversetzt – oder gar nicht, wenn der Iterator nie gelesen wird.
Einmalig verwendbar: Wie jeder Iterator ist das Ergebnis nach vollständigem Durchlauf erschöpft. Ein zweites [...it] liefert [].
Arrays haben kein .map() dieser Art: [1, 2].map() ruft Array.prototype.map() auf (eager, liefert Array). Für lazy Verhalten zuerst .values() aufrufen.
Kein thisArg, kein drittes Argument (das Quell-Objekt) – anders als bei Arrays.
Ist callbackFn keine Funktion, wird sofort ein TypeError geworfen. Wirft callbackFn einen Fehler, wird der Quell-Iterator über return() geschlossen.
Ein vorzeitiges Beenden (z. B. break in for...of) ruft return() des Quell-Iterators auf – Generatoren führen dann ihre finally-Blöcke aus.
Kompatibilität: Teil von ES2025. Unterstützt ab Chrome/Edge 122, Firefox 131, Safari 18.4, Node.js 22. Für ältere Umgebungen gibt es Polyfills (z. B. core-js). Für asynchrone Iteratoren existiert (noch) kein Gegenstück.

Siehe auch

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