IDBCursor.continue() — Methode · JavaScript-Referenz

Signatur

IDBCursor.prototype.continue(key)

Beschreibung

continue() ist die zentrale Methode, um mit einem IDBCursor bzw. IDBCursorWithValue über die Datensätze eines Object Stores oder Index zu iterieren. Jeder Aufruf löst erneut das success-Event auf dem ursprünglichen IDBRequest aus, das von openCursor() oder openKeyCursor() zurückgegeben wurde. In diesem Handler steht der Cursor dann über request.result an der neuen Position bereit. Gibt es keinen weiteren Datensatz, ist request.result gleich null.

Ohne Argument springt der Cursor einfach zum nächsten Eintrag in seiner Richtung ("next", "nextunique", "prev", "prevunique"). Wird ein key übergeben, springt der Cursor direkt zum ersten Datensatz, dessen Schlüssel größer oder gleich (bei Vorwärtsrichtung) bzw. kleiner oder gleich (bei Rückwärtsrichtung) diesem Schlüssel ist. So lassen sich Bereiche gezielt überspringen, ohne jeden Datensatz einzeln zu laden.

Die Methode gibt nichts zurück (undefined). Das Ergebnis kommt ausschließlich asynchron über das Event. Pro success-Event darf continue() (bzw. advance() oder continuePrimaryKey()) nur einmal aufgerufen werden.

Parameter

Name	Typ	Default	Beschreibung
$key	number\|string\|Date\|ArrayBuffer\|ArrayBufferView\|Array		Optionaler gültiger IndexedDB-Schlüssel, zu dem der Cursor springen soll. Muss in Cursor-Richtung hinter der aktuellen Position liegen, sonst wird ein `DataError` geworfen.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die neue Cursor-Position wird über das success-Event des zugehörigen IDBRequest (request.result) geliefert, bzw. null, wenn das Ende erreicht ist.

Beispiele

Alle Datensätze eines Object Stores durchlaufen

const openReq = indexedDB.open('shop', 1);

openReq.onupgradeneeded = () => {
  const db = openReq.result;
  const store = db.createObjectStore('produkte', { keyPath: 'id' });
  store.add({ id: 1, name: 'Tastatur' });
  store.add({ id: 2, name: 'Maus' });
  store.add({ id: 3, name: 'Monitor' });
};

openReq.onsuccess = () => {
  const db = openReq.result;
  const store = db.transaction('produkte', 'readonly').objectStore('produkte');
  const cursorReq = store.openCursor();

  cursorReq.onsuccess = () => {
    const cursor = cursorReq.result;
    if (cursor) {
      console.log(cursor.key, cursor.value.name);
      cursor.continue(); // nächster Datensatz -> erneutes success-Event
    } else {
      console.log('Fertig');
    }
  };
};

1 Tastatur 2 Maus 3 Monitor Fertig

Mit Schlüssel zu einer Position springen

// Überspringt alle Nachnamen vor 'M' in einem Index 'nachname'
const listeAbM = (db) => {
  const index = db.transaction('kunden').objectStore('kunden').index('nachname');
  let gesprungen = false;

  index.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (!cursor) return;

    if (!gesprungen && cursor.key < 'M') {
      gesprungen = true;
      cursor.continue('M'); // direkt zum ersten Schlüssel >= 'M'
      return;
    }
    console.log(cursor.key);
    cursor.continue();
  };
};

Cursor als Promise-basierter Async-Iterator

const iterateCursor = async function* (source, query, direction = 'next') {
  const request = source.openCursor(query, direction);
  while (true) {
    const cursor = await new Promise((resolve, reject) => {
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
    if (!cursor) return;
    yield cursor.value;
    cursor.continue();
  }
};

// Nutzung (innerhalb einer aktiven Transaktion, ohne fremde awaits):
// for await (const produkt of iterateCursor(store)) console.log(produkt.name);

// Wichtig · Fallstricke

InvalidStateError: tritt auf, wenn continue() zweimal im selben success-Handler aufgerufen wird oder der Cursor bereits am Ende steht bzw. seine Quelle gelöscht wurde.
TransactionInactiveError: Die Transaktion wird automatisch beendet, sobald keine Anfragen mehr ausstehen. Wer zwischen zwei continue()-Aufrufen etwa auf fetch() oder setTimeout wartet, verliert die Transaktion. Asynchrone Fremdarbeit also vorher oder nachher erledigen.
DataError: wird geworfen, wenn key kein gültiger Schlüssel ist oder in Cursor-Richtung nicht hinter der aktuellen Position liegt (bei "next" also kleiner oder gleich dem aktuellen Schlüssel).
Um mehrere Datensätze zu überspringen, ohne einen Schlüssel zu kennen, ist advance(count) gedacht. Bei Index-Cursorn mit doppelten Schlüsseln hilft continuePrimaryKey().
Wenn du nur alle Werte brauchst, sind getAll() bzw. getAllKeys() meist deutlich schneller als eine Cursor-Schleife.
Wird in allen modernen Browsern und in Web Workern unterstützt. In privaten Fenstern mancher Browser kann IndexedDB eingeschränkt sein.

Siehe auch

IDBCursor IDBCursor.advance() IDBCursor.continuePrimaryKey() IDBObjectStore.openCursor() IDBIndex.openCursor() IDBCursorWithValue IDBObjectStore.getAll()