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

Signatur

Iterator.prototype.includes(searchElement, skippedElements)

Beschreibung

includes() ist das Gegenstück zu Array.prototype.includes() für beliebige Iteratoren, etwa Generatoren, Map.prototype.keys(), Set.prototype.values() oder Ketten aus Iterator-Helfern wie map() und filter(). Du musst die Werte nicht erst mit [...iter] oder Array.from() in ein Array kopieren, um nachzusehen, ob ein bestimmter Wert vorkommt.

Verglichen wird mit dem Algorithmus SameValueZero, also genau wie bei Array.prototype.includes(): NaN gilt als gleich NaN, +0 und -0 gelten als gleich, und Objekte werden nur über ihre Identität verglichen. Die Suche ist lazy und bricht beim ersten Treffer ab. Danach schließt die Methode den zugrunde liegenden Iterator über return(). Deshalb funktioniert sie auch bei unendlichen Iteratoren, solange der gesuchte Wert irgendwann vorkommt.

Mit dem optionalen zweiten Argument skippedElements lässt sich eine bestimmte Anzahl von Elementen am Anfang überspringen. Anders als der Parameter fromIndex von Arrays sind hier keine negativen Werte erlaubt, denn ein Iterator kennt seine Länge nicht.

Wichtig: Iteratoren lassen sich nur einmal durchlaufen. Nach dem Aufruf ist der Iterator ganz oder teilweise verbraucht. Wenn du mehrmals suchen willst, erzeuge jedes Mal einen neuen Iterator oder verwende ein Set.

Parameter

Name	Typ	Default	Beschreibung
$searchElement Pflicht	any		Der gesuchte Wert. Verglichen wird mit SameValueZero (`NaN` wird gefunden, `-0` und `+0` gelten als gleich).
$skippedElements	number	0	Anzahl der Elemente, die vor Beginn des Vergleichs übersprungen werden. Muss eine nicht-negative ganze Zahl sein (auch `Infinity` ist laut Vorschlag erlaubt). Negative Werte oder `NaN` lösen einen `RangeError` aus, Nicht-Zahlen einen `TypeError`.

Beispiele

Wert in einem Generator suchen

function* ids() {
  yield 101;
  yield 102;
  yield NaN;
  yield 104;
}

console.log(ids().includes(102));
console.log(ids().includes(999));
// SameValueZero: NaN wird gefunden
console.log(ids().includes(NaN));

true false true

Map-Schlüssel nach einer Transformation prüfen

const users = new Map([
  ['anna@example.com', { role: 'admin' }],
  ['ben@example.com', { role: 'user' }]
]);

// Lazy: kein Zwischen-Array, Abbruch beim ersten Treffer
const hasAdmin = users.values()
  .map((u) => u.role)
  .includes('admin');

console.log(hasAdmin);

true

Unendlicher Iterator und skippedElements

function* naturals() {
  let n = 0;
  while (true) yield n++;
}

// Endet, weil 42 irgendwann vorkommt und der Iterator geschlossen wird
console.log(naturals().includes(42));

// Die ersten 3 Elemente (0, 1, 2) werden übersprungen
console.log(naturals().take(5).includes(1, 3));
console.log(naturals().take(5).includes(4, 3));

true false true

Feature-Erkennung mit einfachem Fallback

const iterIncludes = (iter, value, skip = 0) => {
  if (typeof Iterator !== 'undefined' &&
      typeof Iterator.prototype.includes === 'function') {
    return Iterator.from(iter).includes(value, skip);
  }
  // Fallback über for...of (break ruft return() auf)
  for (const item of iter) {
    if (skip > 0) { skip--; continue; }
    if (item === value || (item !== item && value !== value)) return true;
  }
  return false;
};

console.log(iterIncludes(new Set(['a', 'b']).values(), 'b'));

true

// Wichtig · Fallstricke

Kompatibilität: Iterator.prototype.includes() ist ein TC39-Vorschlag und in den meisten Browsern und Node.js-Versionen noch nicht verfügbar. Prüfe vor der Nutzung mit typeof Iterator.prototype.includes === 'function' oder verwende ein Polyfill (z. B. core-js). Die übrigen Iterator-Helfer (map, filter, take, some …) sind seit ES2025 Standard.
Iterator wird verbraucht: Nach einem Aufruf ist der Iterator ganz oder bis zum Treffer abgearbeitet. Ein zweites includes() auf demselben Objekt setzt dort an, wo das erste aufgehört hat, oder liefert direkt false.
Endlosschleife: Bei unendlichen Iteratoren kehrt der Aufruf nie zurück, wenn der Wert nicht vorkommt. Begrenze den Iterator vorher, z. B. mit take(n).
Kein negativer Startwert: Anders als bei Array.prototype.includes(value, fromIndex) ist skippedElements eine Anzahl zu überspringender Elemente. Negative Werte lösen einen RangeError aus.
Objekte: Objekte werden nur über ihre Identität verglichen. includes({ id: 1 }) findet keine inhaltlich gleichen Objekte. Dafür eignet sich some(fn).
Für häufige Mitgliedschaftsprüfungen ist ein Set mit has() (O(1)) deutlich schneller als eine lineare Suche.

Siehe auch

Array.prototype.includes() Iterator.prototype.some() Iterator.prototype.find() Iterator.prototype.take() Iterator.from() Set.prototype.has() Iterator