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.');
})();

Trade-offs

Option	Benefit	Cost
A cursor + `IDBKeyRange` instead of `getAll()`	Processes one record at a time without loading everything into memory at once — good for a large dataset	More complex code — you handle callbacks and call `continue()` yourself every time
Calling `getAll()` directly	Short, readable code, giving you an array right away	Loads every record into memory in one shot — unsuitable for a large store
Filtering with `IDBKeyRange` before iterating	Fewer records to scan, saving time	You need to know the key structure in advance to build the correct range

Common mistakes

Forgetting to call cursor.continue() inside the onsuccess handler — iteration just stops silently, with no error to see. Call it every time records remain.
Assuming IDBKeyRange.bound() excludes both edges by default — the default is inclusive of both the lower and upper bound. Pass true explicitly as the third or fourth argument if you want it exclusive.
Opening a new cursor every time you want the next record — a single cursor can keep advancing with continue(); there’s no need to reopen it. Doing so wastes performance and confuses the code.