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

Signatur

Iterator.prototype.chunks(chunkSize)

Beschreibung

chunks() teilt die Werte eines Iterators in nicht überlappende Blöcke fester Größe auf. Jeder erzeugte Wert ist ein normales Array mit genau chunkSize Elementen. Nur der letzte Block kann kleiner sein, wenn die Anzahl der Elemente nicht glatt aufgeht. Ein leerer Quell-Iterator liefert gar keinen Block.

Wie alle Iterator-Helfer (map(), filter(), take() …) arbeitet chunks() lazy: Aus der Quelle wird erst gelesen, wenn der nächste Block angefordert wird, und dann nur so viele Werte, wie für diesen Block nötig sind. Deshalb funktioniert die Methode auch mit unendlichen Generatoren und großen Datenströmen, ohne alles vorher in den Speicher zu laden.

Typische Einsatzfälle sind Batch-Verarbeitung (z. B. je 100 Datensätze pro API-Aufruf oder Datenbank-Insert), das Aufteilen von Listen für Seiten oder Tabellenzeilen und das Gruppieren von Byte- oder Zeichenfolgen. Für überlappende Fenster („Sliding Window“) ist im selben Vorschlag die Schwester-Methode windows() vorgesehen.

Parameter

Name	Typ	Default	Beschreibung
$chunkSize Pflicht	number		Maximale Anzahl Elemente pro Block. Muss eine ganze Zahl zwischen `1` und `2**32 - 1` sein, sonst wird ein `RangeError` ausgelöst.

Rückgabewert

Typ

Iterator<Array>

Beschreibung

Ein neues Iterator-Hilfsobjekt, das nacheinander Arrays mit je chunkSize Elementen liefert. Der letzte Block kann kürzer sein.

Beispiele

Array in Zweiergruppen aufteilen

const zahlen = [1, 2, 3, 4, 5];

const bloecke = zahlen.values().chunks(2).toArray();
console.log(bloecke);

[[1, 2], [3, 4], [5]]

Batch-Upload: je 3 Datensätze pro Anfrage

const datensaetze = Array.from({ length: 7 }, (_, i) => ({ id: i + 1 }));

const sendeBatch = async (batch) => {
  // Hier stünde z. B. fetch('/api/import', { method: 'POST', body: JSON.stringify(batch) })
  console.log('Sende IDs:', batch.map((d) => d.id).join(', '));
};

const importiere = async () => {
  for (const batch of datensaetze.values().chunks(3)) {
    await sendeBatch(batch);
  }
};

importiere();

Sende IDs: 1, 2, 3 Sende IDs: 4, 5, 6 Sende IDs: 7

Unendlichen Generator lazy verarbeiten

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

// Nur so viel wird gelesen, wie für 3 Blöcke nötig ist
const ersteBloecke = natuerlicheZahlen()
  .chunks(4)
  .map((block) => block.reduce((a, b) => a + b, 0))
  .take(3)
  .toArray();

console.log(ersteBloecke);

[10, 26, 42]

Feature-Erkennung mit einfachem Fallback

const chunked = (iterable, size) => {
  const it = Iterator.from(iterable);
  if (typeof it.chunks === 'function') return it.chunks(size);
  // Fallback als Generator
  return (function* () {
    let buf = [];
    for (const x of it) {
      buf.push(x);
      if (buf.length === size) { yield buf; buf = []; }
    }
    if (buf.length) yield buf;
  })();
};

console.log([...chunked('abcdefg', 3)]);

[['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]

// Wichtig · Fallstricke

Kompatibilität: chunks() gehört zum TC39-Vorschlag „Iterator Chunking“ und ist noch nicht in allen Browsern bzw. in Node.js verfügbar. Für den Produktiveinsatz vorher per Feature-Erkennung prüfen (typeof Iterator.prototype.chunks === 'function') oder ein Polyfill bzw. einen eigenen Generator verwenden (siehe Beispiel).
Nur auf Iteratoren: Arrays, Strings, Map und Set haben selbst keine chunks()-Methode. Zuerst einen Iterator erzeugen, z. B. mit arr.values() oder Iterator.from(iterable).
Ungültige Größe: chunks(0), negative Zahlen, Bruchzahlen wie 2.5 oder NaN lösen sofort einen RangeError aus. Ohne Argument (undefined) gibt es ebenfalls einen Fehler, einen Standardwert gibt es nicht.
Letzter Block kürzer: Der letzte Block wird nicht aufgefüllt. Wer gleich große Blöcke braucht, muss den letzten selbst prüfen oder auffüllen.
Einmalig verwendbar: Der zurückgegebene Helfer verbraucht den Quell-Iterator. Ein zweiter Durchlauf liefert nichts mehr.
Kein Überlappen: Für gleitende Fenster wie [1,2], [2,3] usw. ist windows() gedacht, nicht chunks().

Siehe auch

Iterator Iterator.prototype.windows() Iterator.prototype.take() Iterator.prototype.map() Iterator.prototype.toArray() Iterator.from() Array.prototype.values()