Chapter 49: IndexedDB Client-Side Database

Building an Offline Cache with IndexedDB

Persisting media Blobs and binary files, constructing resilient offline mutation outbox queues, and syncing with Service Workers.

LEARNING OBJECTIVES ⌵

Persist large binary media assets (Blob, File, ArrayBuffer) natively inside IndexedDB.
Render cached binary assets in the DOM using URL.createObjectURL() and memory-safe URL.revokeObjectURL().
Construct an offline Mutation Outbox Queue to capture user actions while disconnected from the network.
Implement an automatic synchronization pipeline triggered by window.addEventListener('online') and Service Worker Background Sync.

🎬 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 an explorer trekking through the Sahara Desert with a field tablet.

If the application relies solely on live network APIs, the moment the explorer loses cell reception, the screen freezes with a "Network Error" alert. Any research notes entered into the app vanish into the void.

An Offline-First IndexedDB Architecture acts like a physical field notebook and courier pouch:

The Field Album (Blob Storage): High-resolution satellite maps and camera photos are downloaded ahead of time and stored as binary Blob objects directly inside IndexedDB. The explorer can zoom into terrain maps offline with zero network latency.
The Outbox Pouch (Mutation Queue): When the explorer records a new rock sample, the app immediately writes the record to an outbox ObjectStore and optimistically renders it on screen.
The Courier Handshake (Sync Pipeline): The app listens for connectivity (navigator.onLine). The instant the explorer reaches an oasis with Wi-Fi, the sync worker awakens, processes each pending outbox envelope in order, posts them to the server, and purges the queue upon server confirmation.

Technical Deep Dive & Specifications

Storing Binary Blobs vs Base64 Strings

A common anti-pattern in early web development was converting images to Base64 strings to store in localStorage.

+-----------------------------------------------------------------------------+
|                     BASE64 vs NATIVE BLOB STORAGE COMPARISON                |
+---------------------+-------------------------+-----------------------------+
| Metric / Property   | Base64 in localStorage  | Native Blob in IndexedDB    |
+---------------------+-------------------------+-----------------------------+
| Storage Overhead    | ~33% bloat (text enc)   | 0% bloat (raw binary bytes) |
| Memory Allocation   | Multi-MB string alloc   | Direct pointer / buffer ref |
| Thread Blocking     | Blocks main UI thread   | Asynchronous background I/O |
| Quota Limit         | 5 MB total quota        | Gigabytes / Multi-hundred MB|
| DOM Rendering       | Memory-heavy data URI   | `URL.createObjectURL(blob)` |
+---------------------+-------------------------+-----------------------------+

The Offline Mutation Queue Architecture

                                  USER ACTION
                         (e.g., "Post New Comment")
                                      │
                                      ▼
                        ┌───────────────────────────┐
                        │   Write to IndexedDB:     │
                        │   ObjectStore: `outbox`   │
                        └───────────────────────────┘
                                      │
                         Optimistic UI Update (Instant)
                                      │
                                      ▼
                            [Is navigator.onLine?]
                                 /          \
                          ONLINE/            \ OFFLINE
                               v              v
               ┌───────────────────────┐   [Wait for 'online' event]
               │ Process Outbox Queue  │              │
               │ POST /api/v1/comments │ <────────────┘
               └───────────────────────┘
                               │
                       [Server Returns 200 OK?]
                               │
                               ▼
               ┌───────────────────────┐
               │ Delete from `outbox`  │
               └───────────────────────┘

💻 Interactive Code Playground

Starter Code

Save this file as offline-sync.html and open it in your browser.

Line-by-Line Code Breakdown

Lines 104–112 (const blob = new Blob([...]); tx.objectStore('media_cache').put({ id, blob })): Demonstrates native binary Blob storage. IndexedDB writes the raw binary stream directly into browser storage without base64 text expansion.
Lines 123–128 (URL.createObjectURL(blob)): Creates a lightweight in-memory DOM reference string (e.g. blob:http://...) pointing directly to the cached image.
Line 128 (img.onload = () => URL.revokeObjectURL(objectUrl)): Essential memory management practice. Once the browser decodes the image into the GPU canvas, revoking the object URL frees the blob pointer.
Lines 135–148 (tx.objectStore('outbox').add(mutation)): Captures user edits into an outbox queue immediately, guaranteeing zero data loss even if the device powers off or loses connectivity.
Lines 153–170 (processOutbox()): Iterates through pending queue items, dispatches them sequentially to the backend API, and deletes each item from the outbox only after receiving a successful HTTP response.

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>Offline Media & Sync Outbox</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 1rem;
      border: none;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
      color: white;
      background: #0284c7;
      margin-top: 0.5rem;
    }
    button:hover { background: #0369a1; }
    .network-badge {
      display: inline-block;
      padding: 0.2rem 0.6rem;
      border-radius: 4px;
      font-weight: bold;
      margin-bottom: 1rem;
    }
    .online { background: #15803d; }
    .offline { background: #b91c1c; }
    #logOutput {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 180px;
      white-space: pre-wrap;
    }
    #imagePreview {
      max-width: 100%;
      height: 140px;
      object-fit: cover;
      border-radius: 6px;
      margin-top: 0.5rem;
      display: none;
    }
  </style>
</head>
<body>

<h1>Offline Media Cache & Sync Outbox</h1>

<div>
    Status: <span id="netStatus" class="network-badge online">ONLINE</span>
    <button id="toggleMockOffline" style="background:#64748b;">Simulate Network Drop</button>
  </div>

<div class="grid">
    <div class="card">
      <h3>1. Cache Binary Image Blob</h3>
      <p>Generates an SVG canvas Blob and stores it in IndexedDB.</p>
      <button id="saveBlobBtn">Download & Store Blob</button>
      <button id="loadBlobBtn" style="background:#059669;">Load Cached Blob</button>
      <br>
      <img id="imagePreview" alt="Cached Preview">
    </div>

<div class="card">
      <h3>2. Offline Mutation Outbox</h3>
      <p>Queue user posts offline and sync automatically.</p>
      <input type="text" id="postInput" placeholder="Write a note..." style="width:90%; padding:0.4rem; margin-bottom:0.5rem;">
      <button id="queuePostBtn" style="background:#8b5cf6;">Submit Note</button>
      <button id="forceSyncBtn" style="background:#d97706;">Trigger Sync</button>
    </div>
  </div>

<div id="logOutput">Initializing offline database...</div>

function log(msg) {
      logBox.textContent += `[${new Date().toLocaleTimeString()}] ${msg}\n`;
      logBox.scrollTop = logBox.scrollHeight;
    }

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

req.onupgradeneeded = (e) => {
      const d = e.target.result;
      // 1. Store for media Blobs
      d.createObjectStore('media_cache', { keyPath: 'id' });
      // 2. Store for pending offline mutations
      d.createObjectStore('outbox', { keyPath: 'id', autoIncrement: true });
      log('🛠️ Created "media_cache" and "outbox" ObjectStores.');
    };

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

// Network status management
    function updateNetworkStatus() {
      const online = !isMockOffline && navigator.onLine;
      netStatus.textContent = online ? 'ONLINE' : 'OFFLINE';
      netStatus.className = `network-badge ${online ? 'online' : 'offline'}`;
      if (online) {
        log('🌐 Connection restored! Initiating outbox sync...');
        processOutbox();
      } else {
        log('📡 Disconnected from network. Mutations will queue locally.');
      }
    }

window.addEventListener('online', updateNetworkStatus);
    window.addEventListener('offline', updateNetworkStatus);

document.getElementById('toggleMockOffline').addEventListener('click', () => {
      isMockOffline = !isMockOffline;
      updateNetworkStatus();
    });

// 1. Storing and Loading Blobs
    document.getElementById('saveBlobBtn').addEventListener('click', () => {
      // Create a sample SVG graphic Blob
      const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="300" height="150" viewBox="0 0 300 150">
        <rect width="300" height="150" fill="#0284c7"/>
        <circle cx="150" cy="75" r="40" fill="#38bdf8"/>
        <text x="150" y="82" font-family="sans-serif" font-size="16" fill="white" text-anchor="middle">OFFLINE CACHED BLOB</text>
      </svg>`;
      const blob = new Blob([svgString], { type: 'image/svg+xml' });

const tx = db.transaction('media_cache', 'readwrite');
      tx.objectStore('media_cache').put({ id: 'hero_image', blob, updatedAt: Date.now() });

tx.oncomplete = () => log('💾 High-resolution binary Blob saved to IndexedDB!');
    });

document.getElementById('loadBlobBtn').addEventListener('click', () => {
      const tx = db.transaction('media_cache', 'readonly');
      const getReq = tx.objectStore('media_cache').get('hero_image');

getReq.onsuccess = () => {
        if (!getReq.result) return log('⚠️ No cached Blob found. Save it first.');

const blob = getReq.result.blob;
        const objectUrl = URL.createObjectURL(blob);
        const img = document.getElementById('imagePreview');
        img.src = objectUrl;
        img.style.display = 'block';

// Revoke ObjectURL when image finishes loading to prevent memory leaks
        img.onload = () => URL.revokeObjectURL(objectUrl);
        log(`🖼️ Loaded Blob from IndexedDB (${blob.size} bytes) via URL.createObjectURL()!`);
      };
    });

// 2. Outbox Mutation Queue
    document.getElementById('queuePostBtn').addEventListener('click', () => {
      const text = document.getElementById('postInput').value.trim();
      if (!text) return alert('Enter note text');

const mutation = {
        action: 'CREATE_NOTE',
        payload: { text, timestamp: Date.now() },
        status: 'pending'
      };

const tx = db.transaction('outbox', 'readwrite');
      tx.objectStore('outbox').add(mutation);

tx.oncomplete = () => {
        log(`📝 Note saved locally in "outbox": "${text}"`);
        document.getElementById('postInput').value = '';
        if (!isMockOffline && navigator.onLine) {
          processOutbox();
        }
      };
    });

// Process Outbox
    function processOutbox() {
      const tx = db.transaction('outbox', 'readonly');
      const getAllReq = tx.objectStore('outbox').getAll();

getAllReq.onsuccess = async () => {
        const queue = getAllReq.result;
        if (!queue || queue.length === 0) return log('ℹ️ Outbox is empty. No pending syncs.');

log(`🚀 Syncing ${queue.length} pending mutation(s) with remote server...`);

for (const item of queue) {
          // Simulate network HTTP POST to backend server
          await new Promise(r => setTimeout(r, 400));
          log(`  ✅ Synced [ID: ${item.id}] "${item.payload.text}" ➔ Server 200 OK`);

// Remove from outbox upon successful sync
          const delTx = db.transaction('outbox', 'readwrite');
          delTx.objectStore('outbox').delete(item.id);
        }
      };
    }

document.getElementById('forceSyncBtn').addEventListener('click', processOutbox);
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[03:10:00] 🛠️ Created "media_cache" and "outbox" ObjectStores.
[03:10:00] ✅ OfflineAppDB ready.
[03:10:05] 💾 High-resolution binary Blob saved to IndexedDB!
[03:10:08] 🖼️ Loaded Blob from IndexedDB (273 bytes) via URL.createObjectURL()!
[03:10:12] 📡 Disconnected from network. Mutations will queue locally.
[03:10:15] 📝 Note saved locally in "outbox": "Desert sample #402 collected"
[03:10:20] 🌐 Connection restored! Initiating outbox sync...
[03:10:20] 🚀 Syncing 1 pending mutation(s) with remote server...
[03:10:21]   ✅ Synced [ID: 1] "Desert sample #402 collected" ➔ Server 200 OK

🏋️ Hands-On Exercise

🎯 The Challenge: Persistent Offline Audio Player Cache

Instructions:

Open database AudioCacheDB with store audio_tracks (keyPath: "trackId").
Create an async function cacheAudioTrack(trackId, title, audioBlob) that stores the audio blob.
Create a function playCachedTrack(trackId):
- Retrieves the track from IndexedDB.
- Creates an object URL via URL.createObjectURL(track.blob).
- Injects the URL into an HTML5 <audio controls> element.
Test by creating a sample audio tone Blob and verifying playback.

🏁 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>Audio Cache 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; margin-right: 0.5rem; }
  </style>
</head>
<body>
  <h1>Offline Audio Player</h1>
  <button id="saveAudio">Cache Audio Tone</button>
  <button id="playAudio">Play from IndexedDB</button>
  <br><br>
  <audio id="player" controls></audio>
  <pre id="output"></pre>

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

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

    req.onupgradeneeded = (e) => {
      e.target.result.createObjectStore('audio_tracks', { keyPath: 'trackId' });
      log('🛠️ Created "audio_tracks" store.');
    };

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

    document.getElementById('saveAudio').addEventListener('click', () => {
      // Create a minimal 1-second synthesized audio pulse (WAV container)
      const buffer = new ArrayBuffer(44 + 44100 * 2);
      const view = new DataView(buffer);
      // Write basic RIFF WAV header
      const writeStr = (offset, str) => {
        for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i));
      };
      writeStr(0, 'RIFF');
      view.setUint32(4, 36 + 44100 * 2, true);
      writeStr(8, 'WAVE');
      writeStr(12, 'fmt ');
      view.setUint32(16, 16, true);
      view.setUint16(20, 1, true); // PCM
      view.setUint16(22, 1, true); // Mono
      view.setUint32(24, 44100, true); // Sample Rate
      view.setUint32(28, 44100 * 2, true); // Byte rate
      view.setUint16(32, 2, true); // Block align
      view.setUint16(34, 16, true); // Bits per sample
      writeStr(36, 'data');
      view.setUint32(40, 44100 * 2, true);

      // Fill with 440Hz sine wave tone
      for (let i = 0; i < 44100; i++) {
        const sample = Math.sin((i / 44100) * 2 * Math.PI * 440) * 16000;
        view.setInt16(44 + i * 2, sample, true);
      }

      const audioBlob = new Blob([buffer], { type: 'audio/wav' });

      const tx = db.transaction('audio_tracks', 'readwrite');
      tx.objectStore('audio_tracks').put({
        trackId: 'tone_440hz',
        title: 'A440 Concert Pitch',
        blob: audioBlob,
        size: audioBlob.size
      });

      tx.oncomplete = () => log(`🎵 Cached audio track "A440" (${audioBlob.size} bytes) in IndexedDB!`);
    });

    document.getElementById('playAudio').addEventListener('click', () => {
      const tx = db.transaction('audio_tracks', 'readonly');
      const getReq = tx.objectStore('audio_tracks').get('tone_440hz');

      getReq.onsuccess = () => {
        if (!getReq.result) return log('⚠️ No track found. Click "Cache Audio Tone" first.');
        const track = getReq.result;
        const objectUrl = URL.createObjectURL(track.blob);
        player.src = objectUrl;
        player.play();
        log(`▶️ Playing offline track: "${track.title}" from IndexedDB Blob.`);
      };
    });
  </script>
</body>
</html>

Why this works: The application stores the raw PCM audio byte buffer as a first-class Blob. When offline, URL.createObjectURL(track.blob) generates a direct stream handle for the HTML5 <audio> player, enabling full offline media playback without any network roundtrips.

⚠️ Common Pitfalls

Leaking Memory with URL.createObjectURL: Forgetting to call URL.revokeObjectURL() after rendering images or audio causes the browser process to retain the underlying binary blobs in memory for the lifetime of the document.
Deleting Outbox Items Before Server Confirmation: Deleting an outbox record before the HTTP POST returns 200 OK will result in silent permanent data loss if the network fails midway.
Not Handling Idempotency on Sync: If the device loses connection right after the server receives a request but before the response reaches the client, the client will retry. Ensure mutations include unique clientMutationId UUIDs so the backend can deduplicate requests.

💡 Pro Tips

Coordinate with Service Worker Background Sync: In Progressive Web Apps, register a sync event (navigator.serviceWorker.ready.then(reg => reg.sync.register('sync-outbox'))). The browser will wake up your Service Worker and flush the IndexedDB outbox even if the user has closed the tab!
Use IndexedDB for Media, Cache Storage for Requests: Store structured documents, state queues, and dynamically generated Blobs in IndexedDB; store static network assets (CSS, JS bundles, HTML pages) in the Cache Storage API.

📌 Key Takeaways

IndexedDB stores binary Blob, File, and ArrayBuffer objects natively with 0% Base64 encoding overhead.
Cached media Blobs are rendered in the DOM using URL.createObjectURL(blob) and cleaned up with URL.revokeObjectURL(url).
An Outbox Mutation Queue enables offline-first interactions, capturing user intent locally and replaying operations once connected.
The window.addEventListener('online') hook provides automatic queue flushing when connectivity returns.
Client-generated UUIDs ensure backend idempotency during offline retry synchronizations.
--

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

? Question 1 / 3

Why is storing raw `Blob` objects in IndexedDB superior to storing Base64 strings in `localStorage`?

Topic: HTML Fundamentals

? Question 2 / 3

What is the critical reason to call `URL.revokeObjectURL(url)` after setting an image source from an IndexedDB Blob?

Topic: HTML Fundamentals

? Question 3 / 3

In an offline-first architecture, when should an item in the `outbox` ObjectStore be deleted?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Storing Binary Blobs vs Base64 Strings

The Offline Mutation Queue Architecture

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Persistent Offline Audio Player Cache

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why is storing raw Blob objects in IndexedDB superior to storing Base64 strings in localStorage?

What is the critical reason to call URL.revokeObjectURL(url) after setting an image source from an IndexedDB Blob?

In an offline-first architecture, when should an item in the outbox ObjectStore be deleted?

Why is storing raw `Blob` objects in IndexedDB superior to storing Base64 strings in `localStorage`?

What is the critical reason to call `URL.revokeObjectURL(url)` after setting an image source from an IndexedDB Blob?

In an offline-first architecture, when should an item in the `outbox` ObjectStore be deleted?