Chapter 49: IndexedDB Client-Side Database

Iterating with Cursors

Stream-processing massive datasets, bidirectional cursor iteration, in-place updates, deletions, and memory-efficient pagination with `IDBCursor`.

LEARNING OBJECTIVES ⌵

Understand why IDBCursor prevents browser memory exhaustion compared to getAll().
Control cursor navigation using openCursor(), continue(), advance(), and traversal directions.
Perform in-place batch mutations and deletions using cursor.update() and cursor.delete().
Implement robust cursor-based offset and keyset pagination for high-volume datasets.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine you are auditing 50,000 physical tax forms stored in a filing warehouse.

If you use getAll(), you instruct a forklift to dump all 50,000 heavy file boxes directly onto your small desktop at the exact same moment. Your desk collapses under the weight, paper flies everywhere, and your office runs out of oxygen (a browser tab crash / JavaScript Out-Of-Memory error).

If you use a Cursor (openCursor), you hire a diligent courier who brings you one single folder at a time:

You inspect Folder #1.
You stamp it, update it (cursor.update()), or shred it (cursor.delete()).
You tap the courier on the shoulder and say "Next please" (cursor.continue()).
The courier swaps out the folder. Your desk only ever holds one single folder in memory at any given millisecond.
When the cabinet is empty, the courier signals that the job is finished (cursor === null).

Technical Deep Dive & Specifications

`openCursor()` Signature & Directions

You can open a cursor on an IDBObjectStore or an IDBIndex:

const request = source.openCursor([queryRange], [direction]);

+----------------------------------------------------------------------------------------------------+
|                                    IDBCURSOR TRAVERSAL DIRECTIONS                                   |
+-------------------+--------------------------------+-----------------------------------------------+
| Direction String  | Traversal Order                | Duplicate Key Handling                        |
+-------------------+--------------------------------+-----------------------------------------------+
| `'next'` (default)| Ascending (Lowest ➔ Highest)  | Yields all records matching index keys        |
+-------------------+--------------------------------+-----------------------------------------------+
| `'nextunique'`    | Ascending (Lowest ➔ Highest)  | Yields ONLY the first record for duplicate keys|
+-------------------+--------------------------------+-----------------------------------------------+
| `'prev'`          | Descending (Highest ➔ Lowest) | Yields all records in reverse order           |
+-------------------+--------------------------------+-----------------------------------------------+
| `'prevunique'`    | Descending (Highest ➔ Lowest) | Yields ONLY the first record per unique key   |
+-------------------+--------------------------------+-----------------------------------------------+

Cursor Anatomy & Methods

When request.onsuccess fires, request.result is an instance of IDBCursorWithValue (or null when finished):

+-----------------------------------------------------------------------------+
|                            IDBCursor Properties                             |
+-------------------+---------------------------------------------------------+
| `cursor.key`        | The index key or primary key currently under the cursor |
| `cursor.primaryKey` | The primary key of the current record                   |
| `cursor.value`      | The deserialized JavaScript object payload              |
+-------------------+---------------------------------------------------------+
|                             IDBCursor Methods                               |
+-------------------+---------------------------------------------------------+
| `cursor.continue([key])`  | Advances cursor to the next record (or to `key`)  |
| `cursor.advance(count)`   | Skips forward by `count` records (Offset paging)  |
| `cursor.update(newValue)` | Modifies the current record in-place              |
| `cursor.delete()`         | Deletes the current record from the ObjectStore   |
+-----------------------------------------------------------------------------+

The Cursor Recursive Event Loop Pattern

A cursor does not use a synchronous while loop. Instead, each call to cursor.continue() or cursor.advance() triggers another onsuccess event on the same IDBRequest:

                       request = store.openCursor()
                                     |
                                     v
                       +---------------------------+
                       |     request.onsuccess     | <----------------+
                       +---------------------------+                  |
                                     |                                |
                        const cursor = req.result;                    |
                                     |                                |
                               [cursor === null?]                     |
                                /          \                          |
                         YES   /            \   NO                    |
                              v              v                        |
                        [DONE / EXIT]   Process cursor.value          |
                                             |                        |
                                        cursor.continue() ------------+

💻 Interactive Code Playground

Starter Code

Save this file as cursors.html and open it in your browser.

Line-by-Line Code Breakdown

Line 77 (store.openCursor(null, 'next')): Opens a cursor across all records in ascending order. Passing null as the first argument indicates no range filter.
Lines 80–87 (if (cursor) ... cursor.continue()): The standard cursor loop pattern. When records exist, cursor is populated and cursor.continue() is invoked to trigger the next step. When iteration reaches the end, cursor is null.
Line 97 (store.openCursor(null, 'prev')): Reverses traversal, streaming from highest primary key (105) down to lowest (101).
Line 124 (const updateReq = cursor.update(user)): Mutates the record currently under the cursor in-place without needing a separate store.put() call.
Line 146 (cursor.delete()): Deletes the exact record currently referenced by the cursor.

Expected Browser Render Output

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>IndexedDB Cursor Streaming Lab</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 850px;
      margin: 2rem auto;
      padding: 0 1rem;
      background: #0f172a;
      color: #f8fafc;
    }
    .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin-bottom: 1rem; }
    .card { background: #1e293b; padding: 1rem; border-radius: 8px; border: 1px solid #334155; }
    button {
      padding: 0.6rem 1.2rem;
      border: none;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
      color: white;
      width: 100%;
      margin-top: 0.5rem;
    }
    .btn-blue { background: #0284c7; }
    .btn-purple { background: #8b5cf6; }
    .btn-red { background: #ef4444; }
    .btn-green { background: #10b981; }
    #logOutput {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 220px;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>

<h1>Streaming Cursors & Batch Operations</h1>

<div class="grid">
    <div class="card">
      <h3>1. Forward Stream</h3>
      <p>Stream records in ascending primary key order.</p>
      <button id="streamAscBtn" class="btn-blue">Stream Ascending ('next')</button>
    </div>

<div class="card">
      <h3>2. Reverse Stream</h3>
      <p>Stream records in descending order.</p>
      <button id="streamDescBtn" class="btn-purple">Stream Descending ('prev')</button>
    </div>

<div class="card">
      <h3>3. In-Place Batch Update</h3>
      <p>Add 10% bonus points to all active user records.</p>
      <button id="batchUpdateBtn" class="btn-green">Run cursor.update()</button>
    </div>

<div class="card">
      <h3>4. Batch Purge</h3>
      <p>Delete all inactive users with <code>cursor.delete()</code>.</p>
      <button id="batchDeleteBtn" class="btn-red">Run cursor.delete()</button>
    </div>
  </div>

<div id="logOutput">Seeding Log DB...</div>

let db;
    const req = indexedDB.open('CursorDemoDB', 1);

req.onupgradeneeded = (e) => {
      const d = e.target.result;
      const store = d.createObjectStore('members', { keyPath: 'id' });

// Seed 5 test members
      const seedData = [
        { id: 101, name: 'Alice', points: 150, active: true },
        { id: 102, name: 'Bob', points: 40, active: false },
        { id: 103, name: 'Charlie', points: 320, active: true },
        { id: 104, name: 'Diana', points: 10, active: false },
        { id: 105, name: 'Evan', points: 500, active: true }
      ];
      seedData.forEach(item => store.add(item));
      log('🛠️ Seeded 5 member records.');
    };

req.onsuccess = (e) => {
      db = e.target.result;
      log('✅ CursorDemoDB ready.');
    };

// 1. Ascending Stream
    document.getElementById('streamAscBtn').addEventListener('click', () => {
      log('\n▶️ Starting Forward Cursor Stream:');
      const tx = db.transaction('members', 'readonly');
      const store = tx.objectStore('members');
      const cursorReq = store.openCursor(null, 'next');

cursorReq.onsuccess = (e) => {
        const cursor = e.target.result;
        if (cursor) {
          log(`  [ID: ${cursor.key}] ${cursor.value.name} - Points: ${cursor.value.points}`);
          cursor.continue(); // Move to next record!
        } else {
          log('🏁 Reached end of forward stream.');
        }
      };
    });

// 2. Descending Stream
    document.getElementById('streamDescBtn').addEventListener('click', () => {
      log('\n◀️ Starting Reverse Cursor Stream:');
      const tx = db.transaction('members', 'readonly');
      const store = tx.objectStore('members');
      const cursorReq = store.openCursor(null, 'prev');

cursorReq.onsuccess = (e) => {
        const cursor = e.target.result;
        if (cursor) {
          log(`  [ID: ${cursor.key}] ${cursor.value.name} - Points: ${cursor.value.points}`);
          cursor.continue();
        } else {
          log('🏁 Reached start of reverse stream.');
        }
      };
    });

// 3. In-Place Batch Update with cursor.update()
    document.getElementById('batchUpdateBtn').addEventListener('click', () => {
      log('\n✨ Running In-Place Batch Bonus Points Update...');
      const tx = db.transaction('members', 'readwrite');
      const store = tx.objectStore('members');
      const cursorReq = store.openCursor();
      let updatedCount = 0;

cursorReq.onsuccess = (e) => {
        const cursor = e.target.result;
        if (cursor) {
          const user = cursor.value;
          if (user.active) {
            user.points = Math.round(user.points * 1.10); // +10%
            const updateReq = cursor.update(user);
            updatedCount++;
          }
          cursor.continue();
        } else {
          log(`🎉 Batch Update Completed! ${updatedCount} active users received +10% bonus.`);
        }
      };
    });

// 4. Batch Delete Inactive Users with cursor.delete()
    document.getElementById('batchDeleteBtn').addEventListener('click', () => {
      log('\n🗑️ Purging inactive users with cursor.delete()...');
      const tx = db.transaction('members', 'readwrite');
      const store = tx.objectStore('members');
      const cursorReq = store.openCursor();
      let deletedCount = 0;

cursorReq.onsuccess = (e) => {
        const cursor = e.target.result;
        if (cursor) {
          if (!cursor.value.active) {
            log(`  Removing inactive user: ${cursor.value.name}`);
            cursor.delete();
            deletedCount++;
          }
          cursor.continue();
        } else {
          log(`✅ Purge Complete! Removed ${deletedCount} inactive users.`);
        }
      };
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[03:00:00] 🛠️ Seeded 5 member records.
[03:00:00] ✅ CursorDemoDB ready.
[03:00:05] ▶️ Starting Forward Cursor Stream:
  [ID: 101] Alice - Points: 150
  [ID: 102] Bob - Points: 40
  [ID: 103] Charlie - Points: 320
  [ID: 104] Diana - Points: 10
  [ID: 105] Evan - Points: 500
🏁 Reached end of forward stream.

🏋️ Hands-On Exercise

🎯 The Challenge: Paginated Data Feed with `cursor.advance()`

Instructions:

Open database NewsApp with store articles (keyPath: "id", autoIncrement: true).
Seed 15 news articles with titles "Article 1" through "Article 15".
Implement a function getPage(pageNumber, pageSize):
- Calculate how many items to skip: skip = (pageNumber - 1) * pageSize.
- Open a cursor.
- If skip > 0, use cursor.advance(skip) on the first step to jump directly to the target offset.
- Collect exactly pageSize items and log them.
Test by fetching Page 2 with a pageSize of 4 (should return Articles 5, 6, 7, and 8).

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Cursor Pagination Challenge</title>
  <style>
    body { font-family: sans-serif; margin: 2rem; background: #0f172a; color: #f8fafc; }
    pre { background: #000; color: #38bdf8; padding: 1rem; border-radius: 6px; }
    button { padding: 0.6rem 1.2rem; cursor: pointer; background: #38bdf8; border: none; border-radius: 4px; font-weight: bold; }
  </style>
</head>
<body>
  <h1>Cursor Paging</h1>
  <button id="fetchPage2">Fetch Page 2 (Items 5–8)</button>
  <pre id="output"></pre>

  <script>
    const output = document.getElementById('output');
    const log = (msg) => output.textContent += `[${new Date().toLocaleTimeString()}] ${msg}\n`;

    let db;
    const req = indexedDB.open('NewsApp', 1);

    req.onupgradeneeded = (e) => {
      const d = e.target.result;
      const store = d.createObjectStore('articles', { keyPath: 'id', autoIncrement: true });
      for (let i = 1; i <= 15; i++) {
        store.add({ title: `Article ${i}: Breaking News Report #${i}`, date: Date.now() });
      }
      log('🛠️ Seeded 15 articles.');
    };

    req.onsuccess = (e) => {
      db = e.target.result;
      log('✅ NewsApp ready.');
    };

    function fetchPage(pageNumber, pageSize) {
      log(`\n📄 Fetching Page ${pageNumber} (Page Size: ${pageSize})...`);
      const tx = db.transaction('articles', 'readonly');
      const store = tx.objectStore('articles');
      const cursorReq = store.openCursor();

      const skip = (pageNumber - 1) * pageSize;
      let hasAdvanced = false;
      const pageResults = [];

      cursorReq.onsuccess = (e) => {
        const cursor = e.target.result;
        if (!cursor) {
          log(`🏁 Page complete. Retrieved ${pageResults.length} records:`);
          pageResults.forEach(item => log(`   - [ID: ${item.id}] ${item.title}`));
          return;
        }

        // Jump to offset if needed
        if (skip > 0 && !hasAdvanced) {
          hasAdvanced = true;
          cursor.advance(skip);
          return;
        }

        // Collect page items
        pageResults.push(cursor.value);

        if (pageResults.length < pageSize) {
          cursor.continue();
        } else {
          // Reached limit for this page
          log(`🏁 Page complete. Retrieved ${pageResults.length} records:`);
          pageResults.forEach(item => log(`   - [ID: ${item.id}] ${item.title}`));
        }
      };
    }

    document.getElementById('fetchPage2').addEventListener('click', () => {
      output.textContent = '';
      fetchPage(2, 4); // Page 2, 4 items per page
    });
  </script>
</body>
</html>

Why this works: cursor.advance(skip) instructs the underlying storage engine to skip the first 4 records without allocating JavaScript memory for their object payloads. Once the cursor arrives at record 5, cursor.continue() reads only the requested 4 records before terminating.

⚠️ Common Pitfalls

Calling Both cursor.continue() and cursor.advance(): Attempting to call both within the same onsuccess invocation throws InvalidStateError: The cursor is being continued.
Forgetting to Call cursor.continue(): If you process a record in onsuccess and forget to call cursor.continue(), iteration halts permanently after the first record.
Using Offset Pagination for Millions of Rows: cursor.advance(1000000) must still traverse 1,000,000 B-Tree leaf nodes. For massive tables, use keyset pagination (IDBKeyRange.lowerBound(lastSeenKey, true)) instead.

💡 Pro Tips

Use openKeyCursor() When Payloads Are Not Needed: If you are aggregating keys, checking unique constraints, or counting custom ranges, store.openKeyCursor() returns only key and primaryKey, skipping all Structured Clone value deserialization.
Combine Cursors with Web Workers: Streaming and filtering 500,000 records using a cursor inside a dedicated Web Worker ensures the main UI thread never drops a single frame.

📌 Key Takeaways

IDBCursor iterates through records one at a time, keeping memory consumption constant regardless of dataset size.
Traversal directions include 'next', 'prev', 'nextunique', and 'prevunique'.
In-place mutations and removals are executed directly via cursor.update() and cursor.delete().
cursor.advance(count) skips forward by a given count, enabling offset pagination.
openKeyCursor() streams only key metadata, bypassing object payload deserialization for maximum performance.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What is the principal architectural advantage of using `store.openCursor()` instead of `store.getAll()` for large datasets?

Topic: HTML Fundamentals

? Question 2 / 3

What happens if you invoke `cursor.advance(5)`?

Topic: HTML Fundamentals

? Question 3 / 3

Which cursor direction should you pass to `openCursor()` to iterate from the highest key value down to the lowest?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

openCursor() Signature & Directions

Cursor Anatomy & Methods

The Cursor Recursive Event Loop Pattern

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Paginated Data Feed with cursor.advance()

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the principal architectural advantage of using store.openCursor() instead of store.getAll() for large datasets?

What happens if you invoke cursor.advance(5)?

Which cursor direction should you pass to openCursor() to iterate from the highest key value down to the lowest?

`openCursor()` Signature & Directions

🎯 The Challenge: Paginated Data Feed with `cursor.advance()`

What is the principal architectural advantage of using `store.openCursor()` instead of `store.getAll()` for large datasets?

What happens if you invoke `cursor.advance(5)`?

Which cursor direction should you pass to `openCursor()` to iterate from the highest key value down to the lowest?