Chapter 49: IndexedDB Client-Side Database

Promisifying IndexedDB & Modern Async/Await

Transforming legacy event-based request callbacks into ergonomic, robust `async`/`await` pipelines with zero-dependency wrappers and Jake Archibald's `idb` library.

LEARNING OBJECTIVES ⌵

Understand why IndexedDB was designed with IDBRequest event listeners instead of ES6 Promises.
Implement a lightweight, zero-dependency Promise wrapper for raw IDBRequest and IDBTransaction objects.
Integrate Jake Archibald's industry-standard idb library via modern ES modules.
Write expressive, linear database logic using async/await while managing transactional scopes.

🎬 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 communicating with an embassy in the 1990s.

In the Raw Event API era, you filled out a paper application form (open()), walked over to the lobby, and sat down. Every single time something happened, a clerk would walk into the lobby and shout a status update into a megaphone (onsuccess, onerror, onblocked). If you needed to complete a four-step document workflow (open ➔ get record ➔ modify record ➔ verify update), you ended up writing deeply nested callback pyramids—the dreaded "Callback Hell."

Promisification is like giving that entire embassy process a modern smartphone app with push notifications and seamless sequential execution:

Instead of nesting callbacks four levels deep, you simply write const db = await openDB(...).
Instead of wiring request.onsuccess and request.onerror manually for every single read and write, you write await db.put('users', newUser).
Your code reads top-to-bottom like clean synchronous logic, while the browser runs non-blocking asynchronous disk I/O under the hood.

Technical Deep Dive & Specifications

Why Didn't IndexedDB Use Promises Originally?

IndexedDB was drafted in 2010–2011 and standardized in W3C IndexedDB 1.0 (2015). At that time, ECMAScript Promises were not yet part of the JavaScript language standard (standardized in ES6/ES2015). Consequently, the API was designed around the DOM Event Model (addEventListener, onsuccess, onerror).

Architecture of a Zero-Dependency Promise Wrapper

To bridge raw IndexedDB to async/await, we wrap IDBRequest and IDBTransaction in native Promises:

// Generic request promisifier
function promisifyRequest(request) {
  return new Promise((resolve, reject) => {
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

// Transaction completion promisifier
function promisifyTransaction(transaction) {
  return new Promise((resolve, reject) => {
    transaction.oncomplete = () => resolve();
    transaction.onabort = () => reject(transaction.error || new Error('Transaction aborted'));
    transaction.onerror = () => reject(transaction.error);
  });
}

The `idb` Library (Jake Archibald / Google Chrome Team)

The industry gold standard for modern IndexedDB development is the tiny (~1.2KB gzipped) idb library:

+-----------------------------------------------------------------------------+
|                                idb ARCHITECTURE                             |
+-----------------------------------------------------------------------------+
|                                                                             |
|   Modern ES6 App:  await db.get('users', 'u101')                            |
|                            │                                                |
|                            ▼                                                |
|   ┌──────────────────────────────────────────────────────────────────────┐  |
|   │                       `idb` Proxy & Promise Layer                    │  |
|   │  - Transparently manages transactions                                │  |
|   │  - Intercepts IDBRequest and wraps in Promise.resolve() / reject()   │  |
|   │  - Exposes modern db.openDB(), db.get(), db.put(), db.getAll()       │  |
|   └──────────────────────────────────────────────────────────────────────┘  |
|                            │                                                |
|                            ▼                                                |
|   Native Browser Engine: IDBDatabase / IDBTransaction / IDBRequest          |
|                                                                             |
+-----------------------------------------------------------------------------+

💻 Interactive Code Playground

Starter Code

Save this file as promisify.html and open it in your browser. This example imports idb directly via CDN as an ES Module.

Line-by-Line Code Breakdown

Line 60 (import { openDB } from 'https://cdn.jsdelivr.net/npm/idb@8/+esm'): Loads the modern ES module version of Jake Archibald's idb library.
Lines 72–80 (await openDB('ModernAppDB', 1, { upgrade(...) })): Modernized database initialization where schema migrations are declared cleanly inside the upgrade hook.
Line 90 (await db.put('users', user)): Convenience helper on the IDBDatabase wrapper that automatically opens a single-use readwrite transaction, executes store.put(), and returns a Promise.
Lines 111–125 (const tx = db.transaction(...); await tx.done;): Notice the await tx.done idiom. In idb, tx.done is a Promise that resolves when the underlying transaction commits successfully or rejects if it aborts.
Line 132 (await db.getAllFromIndex('users', 'by_tier', 'pro')): High-level helper that queries an index and returns an array of matching records in a single line of code.

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>Modern Promisified IndexedDB</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-green { background: #10b981; }
    .btn-purple { background: #8b5cf6; }
    .btn-red { background: #ef4444; }
    #logOutput {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 220px;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>

<h1>Promisified IndexedDB with <code>idb</code></h1>

<div class="grid">
    <div class="card">
      <h3>1. Async Upsert</h3>
      <p>Save user record using <code>await db.put()</code>.</p>
      <button id="putUserBtn" class="btn-green">Async Put User</button>
    </div>

<div class="card">
      <h3>2. Async Get & Update</h3>
      <p>Fetch, mutate, and save with linear async code.</p>
      <button id="updateUserBtn" class="btn-blue">Async Update Points</button>
    </div>

<div class="card">
      <h3>3. Multi-Store Async Tx</h3>
      <p>Atomic transaction with <code>tx.done</code> promise.</p>
      <button id="asyncTxBtn" class="btn-purple">Run Async Transaction</button>
    </div>

<div class="card">
      <h3>4. Fetch All via Index</h3>
      <p>Query index with <code>await db.getAllFromIndex()</code>.</p>
      <button id="getAllBtn" class="btn-red">Query Pro Users</button>
    </div>
  </div>

<div id="logOutput">Loading idb module...</div>

<script type="module">
    import { openDB } from 'https://cdn.jsdelivr.net/npm/idb@8/+esm';

let db;

// Initialize Database with openDB helper
    async function init() {
      try {
        db = await openDB('ModernAppDB', 1, {
          upgrade(db, oldVersion, newVersion, transaction) {
            log(`🛠️ idb upgrade hook: Migrating ${oldVersion} ➔ ${newVersion}`);
            const userStore = db.createObjectStore('users', { keyPath: 'id' });
            userStore.createIndex('by_tier', 'tier');
            db.createObjectStore('audit_logs', { autoIncrement: true });
          }
        });
        log('✅ idb database initialized successfully!');
      } catch (err) {
        log(`❌ Init failed: ${err.message}`);
      }
    }
    init();

// 1. Async Put
    document.getElementById('putUserBtn').addEventListener('click', async () => {
      try {
        const user = { id: 'u_101', name: 'Marcus Vance', tier: 'pro', score: 450 };
        const key = await db.put('users', user);
        log(`💾 Saved user via await db.put()! Key: ${key}`);
      } catch (err) {
        log(`❌ Put error: ${err.message}`);
      }
    });

// 2. Async Get & Update
    document.getElementById('updateUserBtn').addEventListener('click', async () => {
      try {
        const user = await db.get('users', 'u_101');
        if (!user) return log('⚠️ User u_101 not found. Click "Async Put User" first.');

user.score += 50;
        await db.put('users', user);
        log(`✨ User u_101 score updated to ${user.score} seamlessly with async/await!`);
      } catch (err) {
        log(`❌ Update error: ${err.message}`);
      }
    });

// 3. Multi-Store Async Transaction with tx.done
    document.getElementById('asyncTxBtn').addEventListener('click', async () => {
      try {
        log('💸 Executing multi-store async transaction...');
        const tx = db.transaction(['users', 'audit_logs'], 'readwrite');

const userStore = tx.objectStore('users');
        const logStore = tx.objectStore('audit_logs');

const user = await userStore.get('u_101');
        if (user) {
          user.score += 100;
          await userStore.put(user);
          await logStore.add({ action: 'BONUS_AWARDED', userId: 'u_101', timestamp: Date.now() });
        }

// Await the transaction completion promise
        await tx.done;
        log('🎉 Transaction committed! tx.done resolved.');
      } catch (err) {
        log(`❌ Tx failed: ${err.message}`);
      }
    });

// 4. Query via Index
    document.getElementById('getAllBtn').addEventListener('click', async () => {
      try {
        const proUsers = await db.getAllFromIndex('users', 'by_tier', 'pro');
        log(`🎯 Found ${proUsers.length} 'pro' users:\n` + JSON.stringify(proUsers, null, 2));
      } catch (err) {
        log(`❌ Index query error: ${err.message}`);
      }
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[03:05:00] 🛠️ idb upgrade hook: Migrating 0 ➔ 1
[03:05:00] ✅ idb database initialized successfully!
[03:05:03] 💾 Saved user via await db.put()! Key: u_101
[03:05:05] ✨ User u_101 score updated to 500 seamlessly with async/await!
[03:05:08] 💸 Executing multi-store async transaction...
[03:05:08] 🎉 Transaction committed! tx.done resolved.

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Zero-Dependency IDB Promise Utility

Instructions:

Without importing any external libraries, create your own minimal async wrapper function: async function getIDB(dbName, version, upgradeCallback).
Implement two helper methods on the returned database wrapper:
- get(storeName, key): Returns a Promise resolving to the record.
- set(storeName, value): Returns a Promise resolving when the record is saved.
Test your custom utility by saving and reading { id: 'config_1', theme: 'dark', fontSize: 16 }.

🏁 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>Custom Promise Wrapper 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>Custom Async IDB Wrapper</h1>
  <button id="runTest">Run Custom Wrapper Test</button>
  <pre id="output"></pre>

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

    // 1. Zero-dependency IDB Promise Wrapper
    function getIDB(dbName, version, upgradeCallback) {
      return new Promise((resolve, reject) => {
        const req = indexedDB.open(dbName, version);
        req.onupgradeneeded = (e) => upgradeCallback(e.target.result);
        req.onerror = () => reject(req.error);
        req.onsuccess = () => {
          const rawDb = req.result;
          // Return an ergonomic wrapper object
          resolve({
            get(storeName, key) {
              return new Promise((res, rej) => {
                const tx = rawDb.transaction(storeName, 'readonly');
                const store = tx.objectStore(storeName);
                const query = store.get(key);
                query.onsuccess = () => res(query.result);
                query.onerror = () => rej(query.error);
              });
            },
            set(storeName, value) {
              return new Promise((res, rej) => {
                const tx = rawDb.transaction(storeName, 'readwrite');
                const store = tx.objectStore(storeName);
                const query = store.put(value);
                tx.oncomplete = () => res(query.result);
                tx.onerror = () => rej(tx.error);
              });
            }
          });
        };
      });
    }

    document.getElementById('runTest').addEventListener('click', async () => {
      output.textContent = '';
      log('1. Initializing DB with custom Promise wrapper...');
      
      const db = await getIDB('CustomWrapperDB', 1, (dbInstance) => {
        dbInstance.createObjectStore('settings', { keyPath: 'id' });
        log('🛠️ Created "settings" store in upgradeCallback');
      });

      log('2. Writing configuration using await db.set()...');
      const payload = { id: 'config_1', theme: 'dark', fontSize: 16 };
      await db.set('settings', payload);
      log('✅ Saved configuration successfully!');

      log('3. Reading configuration using await db.get()...');
      const retrieved = await db.get('settings', 'config_1');
      log(`🎯 Retrieved: ${JSON.stringify(retrieved)}`);
    });
  </script>
</body>
</html>

Why this works: By encapsulating the IDBRequest and IDBTransaction lifecycle inside native Promise constructors, any asynchronous function can await database reads and writes sequentially without callback nesting.

⚠️ Common Pitfalls

Awaiting Non-IDB Promises Inside Transactions: Even when using idb, awaiting a non-IDB Promise (e.g. await fetch() or await new Promise(...)) inside a transaction will cause the transaction to auto-commit and fail with TransactionInactiveError.
Forgetting to Await tx.done: In idb, initiating a write operation on a transaction returns immediately. Always await tx.done before concluding the workflow to ensure data has been flushed to disk.
Uncaught Rejections on Quota Exceeded: When disk quota is exceeded, await db.put() rejects with a QuotaExceededError. Always enclose write calls in try / catch blocks.

💡 Pro Tips

Leverage idb's Key-Value Helper Shortcut: For simple storage needs that require IndexedDB's quota and binary support without full relational queries, idb/keyval offers get(key), set(key, val), and del(key) in a tiny 600-byte footprint.
Type Safety with TypeScript: Jake Archibald's idb has first-class TypeScript support (openDB<MyDB>('name', 1)), providing strict compile-time autocomplete for store names, indexes, and record types.

📌 Key Takeaways

IndexedDB originally used IDBRequest events because it predated native ES6 Promises.
Wrapping IDBRequest and IDBTransaction in native Promises enables clean async/await workflows.
Jake Archibald's idb library is the industry standard wrapper, providing high-level helpers like db.get(), db.put(), and db.getAllFromIndex().
The await tx.done promise guarantees that all operations in a transaction have successfully committed to disk.
Even in promisified IndexedDB, introducing non-IDB async delays inside an open transaction will trigger TransactionInactiveError.
--

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

? Question 1 / 3

Why must you `await tx.done` when executing a multi-step transaction using the `idb` library?

Topic: HTML Fundamentals

? Question 2 / 3

What happens if you execute `await fetch('/data.json')` between two `await store.put()` calls inside an active `idb` transaction?

Topic: HTML Fundamentals

? Question 3 / 3

In the `idb` library's `openDB(name, version, options)` method, what is the name of the lifecycle hook where ObjectStores and Indexes must be created?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Why Didn't IndexedDB Use Promises Originally?

Architecture of a Zero-Dependency Promise Wrapper

The idb Library (Jake Archibald / Google Chrome Team)

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Zero-Dependency IDB Promise Utility

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why must you await tx.done when executing a multi-step transaction using the idb library?

What happens if you execute await fetch('/data.json') between two await store.put() calls inside an active idb transaction?

In the idb library's openDB(name, version, options) method, what is the name of the lifecycle hook where ObjectStores and Indexes must be created?

The `idb` Library (Jake Archibald / Google Chrome Team)

Why must you `await tx.done` when executing a multi-step transaction using the `idb` library?

What happens if you execute `await fetch('/data.json')` between two `await store.put()` calls inside an active `idb` transaction?

In the `idb` library's `openDB(name, version, options)` method, what is the name of the lifecycle hook where ObjectStores and Indexes must be created?