Iterating with Cursors and Ranges

What is a cursor?

Reading a single record by key with objectStore.get(key) is fast, but sometimes you need to walk through many records — filtering, aggregating, or transforming as you go. That is what cursors are for.

A cursor points at one record at a time. You open it on an object store (or index), process the current record, then call cursor.continue() to advance to the next one. When there are no more records the cursor resolves to null, signalling that iteration is complete.

const request = objectStore.openCursor();

request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    console.log(cursor.key, cursor.value);
    cursor.continue(); // advance to next record
  } else {
    console.log('Done — no more records');
  }
};

Opening a cursor

objectStore.openCursor(query, direction) — both arguments are optional.

query — an IDBKeyRange or a specific key. Omit (or pass null) to iterate all records.
direction — "next" (default, ascending), "prev" (descending), "nextunique", or "prevunique".

// All records, ascending order (default)
objectStore.openCursor();

// All records, descending order
objectStore.openCursor(null, 'prev');

// Only records with keys 2–3 (inclusive on both ends)
objectStore.openCursor(IDBKeyRange.bound(2, 3));

IDBKeyRange — filtering by key

IDBKeyRange lets you describe a subset of keys without scanning every record. The four factory methods are:

Method	What it matches
`IDBKeyRange.only(value)`	Exactly one key
`IDBKeyRange.lowerBound(lower, open?)`	Keys ≥ lower (pass `true` to exclude lower itself)
`IDBKeyRange.upperBound(upper, open?)`	Keys ≤ upper (pass `true` to exclude upper itself)
`IDBKeyRange.bound(lower, upper, lowerOpen?, upperOpen?)`	Keys between lower and upper, inclusive by default

IDBKeyRange.only(42)           // key === 42
IDBKeyRange.lowerBound(10)     // key >= 10
IDBKeyRange.lowerBound(10, true) // key > 10
IDBKeyRange.upperBound(50)     // key <= 50
IDBKeyRange.bound(10, 50)      // 10 <= key <= 50
IDBKeyRange.bound(10, 50, true, true) // 10 < key < 50

Wrapping cursor iteration in a Promise

Raw onsuccess callbacks are tedious. Wrapping the pattern in a helper makes it composable with async/await:

function iterateCursor(store, range = null) {
  return new Promise((resolve, reject) => {
    const results = [];
    const req = store.openCursor(range);
    req.onsuccess = (e) => {
      const cursor = e.target.result;
      if (cursor) {
        results.push(cursor.value);
        cursor.continue();
      } else {
        resolve(results);
      }
    };
    req.onerror = () => reject(req.error);
  });
}

Runnable: iterate all records, then a range

The demo below:

Opens a database and seeds four player score records.
Uses a cursor to iterate all records and logs each one.
Uses IDBKeyRange.bound(2, 3) to iterate only the records with id 2 and 3.
Deletes the database afterwards to leave no trace.

Browser Storage

(async function() {
  // Helper: wrap an IDBRequest in a Promise
  function req(r) {
    return new Promise((res, rej) => {
      r.onsuccess = () => res(r.result);
      r.onerror  = () => rej(r.error);
    });
  }

  // Helper: iterate a cursor and collect all values
  function iterateCursor(store, range) {
    return new Promise((resolve, reject) => {
      const results = [];
      const r = store.openCursor(range);
      r.onsuccess = (e) => {
        const cursor = e.target.result;
        if (cursor) {
          results.push(cursor.value);
          cursor.continue();
        } else {
          resolve(results);
        }
      };
      r.onerror = () => reject(r.error);
    });
  }

  // --- Open / seed ---
  const db = await new Promise((resolve, reject) => {
    const openReq = indexedDB.open('demo-advanced-cursors', 1);
    openReq.onupgradeneeded = (e) => {
      const database = e.target.result;
      database.createObjectStore('scores', { keyPath: 'id' });
    };
    openReq.onsuccess = () => resolve(openReq.result);
    openReq.onerror   = () => reject(openReq.error);
  });

  const seedTx = db.transaction('scores', 'readwrite');
  const seedStore = seedTx.objectStore('scores');
  await Promise.all([
    req(seedStore.put({ id: 1, player: 'Alice', score: 150 })),
    req(seedStore.put({ id: 2, player: 'Bob',   score: 80  })),
    req(seedStore.put({ id: 3, player: 'Carol', score: 200 })),
    req(seedStore.put({ id: 4, player: 'Dave',  score: 60  })),
  ]);
  await new Promise((res, rej) => {
    seedTx.oncomplete = res;
    seedTx.onerror    = () => rej(seedTx.error);
  });

  // --- Iterate ALL records ---
  console.log('=== All records (cursor, no range) ===');
  const allTx    = db.transaction('scores', 'readonly');
  const allStore = allTx.objectStore('scores');
  const allRows  = await iterateCursor(allStore, null);
  for (const row of allRows) {
    console.log(`  ${row.player}: ${row.score}`);
  }

  // --- Iterate with IDBKeyRange.bound(2, 3) ---
  console.log('=== Range: ids 2–3 only ===');
  const rangeTx    = db.transaction('scores', 'readonly');
  const rangeStore = rangeTx.objectStore('scores');
  const rangeRows  = await iterateCursor(rangeStore, IDBKeyRange.bound(2, 3));
  for (const row of rangeRows) {
    console.log(`  ${row.player}: ${row.score}`);
  }

  // --- Cleanup ---
  db.close();
  await new Promise((res, rej) => {
    const del = indexedDB.deleteDatabase('demo-advanced-cursors');
    del.onsuccess = res;
    del.onerror   = () => rej(del.error);
  });
  console.log('Database deleted — cleanup complete.');
})();