Chapter 49: IndexedDB Client-Side Database

Storage Limits and Persistent Storage

Monitoring disk quotas with `navigator.storage.estimate()`, requesting persistent storage guarantees with `navigator.storage.persist()`, and handling eviction policies.

LEARNING OBJECTIVES ⌵

Inspect total available quota and origin storage usage using navigator.storage.estimate().
Understand the browser eviction lifecycle: "Best-Effort" (Temporary) vs "Persistent" storage.
Request permanent storage guarantees using navigator.storage.persist().
Handle QuotaExceededError exceptions gracefully in production web applications.

🎬 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 moving your personal belongings into a self-storage facility.

By default, the facility rents you a "Standby Storage Locker" (Best-Effort Storage). You can store hundreds of boxes for free. However, if the entire facility runs out of space, the building superintendent has the legal authority to discard your oldest boxes without asking your permission (LRU eviction—Least Recently Used).

If you run a mission-critical business with irreplaceable client files, you cannot afford to have the superintendent discard your boxes during a building space crunch.

You walk to the front desk and apply for a "Permanent Lease" (navigator.storage.persist()):

The facility reviews your application. If you are a trusted tenant (an installed PWA, high site engagement, or granted permissions), they grant you Persistent Storage.
Once marked Persistent, the browser will never silently evict or wipe your IndexedDB data, even if the device's hard drive is 99% full. Only the user themselves, by explicitly opening browser settings and clearing site data, can delete your database.

Technical Deep Dive & Specifications

Storage Quota Calculations

Modern browsers (Chromium, Firefox, WebKit) dynamically allocate storage quota based on the device's physical disk capacity:

+----------------------------------------------------------------------------------------------------+
|                                    BROWSER STORAGE QUOTA MODELS                                    |
+-------------------+------------------------------------+-------------------------------------------+
| Browser Engine    | Origin Storage Quota               | Storage Eviction Behavior                 |
+-------------------+------------------------------------+-------------------------------------------+
| **Chromium**      | Up to ~60% of total free disk      | Evicts origins by LRU (Least Recently     |
| (Chrome, Edge)    | space (shared across all origins)  | Used) when disk space drops below safety  |
+-------------------+------------------------------------+-------------------------------------------+
| **Firefox**       | Up to 10% of total disk size per   | Prompts user when approaching thresholds; |
| (Gecko)           | origin; max group quota up to 50%  | evicts temporary origins on disk pressure |
+-------------------+------------------------------------+-------------------------------------------+
| **Safari**        | Starts at 1GB; prompts for more in | Wipes unvisited origins after 7 days of   |
| (WebKit)          | increments (iOS / macOS policies)  | inactivity unless saved to Home Screen    |
+-------------------+------------------------------------+-------------------------------------------+

The Storage API: Key Methods

// 1. Check current disk usage and total quota
const { usage, quota, usageDetails } = await navigator.storage.estimate();

// 2. Check if the current origin has persistent storage status
const isPersisted = await navigator.storage.persisted();

// 3. Request persistent storage permission
const granted = await navigator.storage.persist();

+-----------------------------------------------------------------------------+
|                     BEST-EFFORT vs PERSISTENT STORAGE                       |
+-------------------------------------+---------------------------------------+
| Best-Effort (Default)               | Persistent Storage                    |
+-------------------------------------+---------------------------------------+
| • Subject to automatic LRU eviction | • Immune to automatic eviction        |
| • Evicted under device disk pressure| • Data preserved until explicit user  |
| • Ideal for caches, offline media   |   deletion in browser settings        |
| • No user permission required       | • Ideal for user drafts, offline CRM  |
+-------------------------------------+---------------------------------------+

Browser Heuristics for Granting Persistence

When calling navigator.storage.persist(), Chromium-based browsers evaluate heuristic criteria before granting permission without prompting the user:

Is the website bookmarked by the user?
Has the web app been added to the Home Screen / installed as a PWA?
Has the user granted Notifications or Geolocation permissions?
Does the origin have high Site Engagement (frequent visits)?

💻 Interactive Code Playground

Starter Code

Save this file as storage-limits.html and open it in your browser.

Line-by-Line Code Breakdown

Lines 82–97 (await navigator.storage.estimate()): Queries the browser's storage manager for current byte usage and maximum available quota across all origin storage APIs.
Lines 93–97 (usageDetails): In Chromium browsers, usageDetails provides a granular byte breakdown specifically attributing storage across IndexedDB, Cache Storage, and Service Worker registrations.
Line 100 (await navigator.storage.persisted()): Returns a boolean indicating whether the origin is currently protected from automated LRU eviction.
Line 118 (await navigator.storage.persist()): Requests persistent storage status. Depending on the browser, this resolves silently based on site engagement heuristics or triggers a browser permission dialog.
Lines 143–145 (const buffer = new Uint8Array(10 * 1024 * 1024)): Generates a 10-megabyte binary payload to demonstrate real-time quota updates.

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>Storage Quota & Persistence Monitor</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 850px;
      margin: 2rem auto;
      padding: 0 1rem;
      background: #0f172a;
      color: #f8fafc;
    }
    .card {
      background: #1e293b;
      padding: 1.5rem;
      border-radius: 8px;
      border: 1px solid #334155;
      margin-bottom: 1.5rem;
    }
    .meter-container {
      background: #334155;
      border-radius: 9999px;
      height: 20px;
      overflow: hidden;
      margin: 1rem 0;
    }
    .meter-bar {
      background: #38bdf8;
      height: 100%;
      width: 0%;
      transition: width 0.4s ease;
    }
    button {
      padding: 0.6rem 1.2rem;
      border: none;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
      color: white;
      background: #0284c7;
      margin-right: 0.5rem;
      margin-top: 0.5rem;
    }
    button:hover { background: #0369a1; }
    .btn-persist { background: #10b981; }
    .btn-persist:hover { background: #059669; }
    #logOutput {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 180px;
      white-space: pre-wrap;
    }
    .status-badge {
      display: inline-block;
      padding: 0.2rem 0.6rem;
      border-radius: 4px;
      font-weight: bold;
    }
    .persisted { background: #15803d; }
    .not-persisted { background: #b45309; }
  </style>
</head>
<body>

<h1>Storage Quota & Persistence Manager</h1>

<div class="card">
    <h3>Origin Storage Quota Gauge</h3>
    <div class="meter-container">
      <div id="meterBar" class="meter-bar"></div>
    </div>
    <p id="quotaLabel">Calculating quota...</p>
    <p>Storage Mode: <span id="persistBadge" class="status-badge not-persisted">Checking...</span></p>

<button id="refreshBtn">Refresh Storage Stats</button>
    <button id="requestPersistBtn" class="btn-persist">Request Persistent Storage</button>
    <button id="fillStorageBtn" style="background:#8b5cf6;">Simulate Large Write (10MB)</button>
  </div>

<div class="card">
    <h3>Diagnostic Console:</h3>
    <div id="logOutput">Ready...</div>
  </div>

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

function formatBytes(bytes) {
      if (bytes === 0) return '0 Bytes';
      const k = 1024;
      const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
      const i = Math.floor(Math.log(bytes) / Math.log(k));
      return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
    }

// 1. Inspect Storage Quota
    async function updateStorageStats() {
      if (!('storage' in navigator && 'estimate' in navigator.storage)) {
        log('❌ navigator.storage.estimate() is not supported in this browser.');
        return;
      }

const { usage, quota, usageDetails } = await navigator.storage.estimate();
      const pct = ((usage / quota) * 100).toFixed(2);

meterBar.style.width = `${Math.max(pct, 1)}%`;
      quotaLabel.textContent = `Using ${formatBytes(usage)} of ${formatBytes(quota)} (${pct}% allocated)`;

log(`📊 Quota Report: Used ${formatBytes(usage)} / ${formatBytes(quota)}`);
      if (usageDetails) {
        log(`   - IndexedDB: ${formatBytes(usageDetails.indexedDB || 0)}`);
        log(`   - CacheStorage: ${formatBytes(usageDetails.caches || 0)}`);
        log(`   - ServiceWorkers: ${formatBytes(usageDetails.serviceWorkerRegistrations || 0)}`);
      }

// Check persistence status
      const isPersisted = await navigator.storage.persisted();
      if (isPersisted) {
        persistBadge.textContent = 'PERSISTENT (Immune to Eviction)';
        persistBadge.className = 'status-badge persisted';
      } else {
        persistBadge.textContent = 'BEST-EFFORT (May be evicted on disk pressure)';
        persistBadge.className = 'status-badge not-persisted';
      }
    }

// 2. Request Persistent Storage
    document.getElementById('requestPersistBtn').addEventListener('click', async () => {
      if (!('storage' in navigator && 'persist' in navigator.storage)) {
        log('❌ navigator.storage.persist() is not supported.');
        return;
      }

log('🛡️ Requesting persistent storage permission...');
      const isGranted = await navigator.storage.persist();

if (isGranted) {
        log('🎉 SUCCESS: Persistent storage granted by browser!');
      } else {
        log('⚠️ NOTICE: Browser declined persistence. Storage remains Best-Effort.');
      }
      updateStorageStats();
    });

// 3. Simulate Large Write
    document.getElementById('fillStorageBtn').addEventListener('click', async () => {
      log('💾 Writing 10MB binary block to IndexedDB...');
      const req = indexedDB.open('QuotaBenchmarkDB', 1);

req.onupgradeneeded = (e) => {
        e.target.result.createObjectStore('benchmarks', { keyPath: 'id' });
      };

req.onsuccess = (e) => {
        const db = e.target.result;
        const tx = db.transaction('benchmarks', 'readwrite');
        const store = tx.objectStore('benchmarks');

// Create 10MB chunk
        const buffer = new Uint8Array(10 * 1024 * 1024);
        const record = { id: `block_${Date.now()}`, data: buffer };

try {
          store.put(record);
        } catch (err) {
          log(`❌ Quota Write Error: ${err.name} - ${err.message}`);
        }

tx.oncomplete = () => {
          log('✅ 10MB block successfully committed.');
          db.close();
          updateStorageStats();
        };

tx.onerror = () => {
          log(`❌ Transaction Failed: ${tx.error.message}`);
        };
      };
    });

document.getElementById('refreshBtn').addEventListener('click', updateStorageStats);

// Initial check on load
    updateStorageStats();
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[03:15:00] 📊 Quota Report: Used 12.45 MB / 128.50 GB
[03:15:00]    - IndexedDB: 12.10 MB
[03:15:00]    - CacheStorage: 350.00 KB
[03:15:00]    - ServiceWorkers: 0 Bytes
[03:15:05] 🛡️ Requesting persistent storage permission...
[03:15:05] 🎉 SUCCESS: Persistent storage granted by browser!
[03:15:10] 💾 Writing 10MB binary block to IndexedDB...
[03:15:11] ✅ 10MB block successfully committed.
[03:15:11] 📊 Quota Report: Used 22.45 MB / 128.50 GB

🏋️ Hands-On Exercise

🎯 The Challenge: Graceful Quota Exhaustion Guard

Instructions:

Create a function safeSave(storeName, record) that wraps IndexedDB writes with a proactive quota check.
Before writing, query navigator.storage.estimate():
- If (usage / quota) > 0.90 (over 90% full), log a critical warning and reject the write with a custom warning: "Storage critical: Above 90% capacity. Purging recommended."
- Otherwise, proceed with the write.
Catch any QuotaExceededError thrown during insertion and log an emergency fallback message.

🏁 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>Quota Guard 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>Safe Quota Writer</h1>
  <button id="testSafeSave">Execute Guarded Write</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('GuardDB', 1);
    req.onupgradeneeded = (e) => e.target.result.createObjectStore('data', { keyPath: 'id' });
    req.onsuccess = (e) => {
      db = e.target.result;
      log('✅ GuardDB initialized.');
    };

    async function safeSave(record) {
      // 1. Proactive Quota Check
      if ('storage' in navigator && 'estimate' in navigator.storage) {
        const { usage, quota } = await navigator.storage.estimate();
        const ratio = usage / quota;
        log(`🔍 Quota Pre-flight: ${(ratio * 100).toFixed(4)}% utilized.`);

        if (ratio > 0.90) {
          throw new Error(`Storage critical: ${(ratio * 100).toFixed(2)}% full. Write blocked.`);
        }
      }

      // 2. Execute write with reactive QuotaExceededError protection
      return new Promise((resolve, reject) => {
        const tx = db.transaction('data', 'readwrite');
        const store = tx.objectStore('data');

        try {
          const writeReq = store.put(record);
          writeReq.onsuccess = () => resolve(writeReq.result);
        } catch (err) {
          reject(err);
        }

        tx.onerror = (e) => {
          if (tx.error && tx.error.name === 'QuotaExceededError') {
            log('🚨 CRITICAL: Device disk quota completely exhausted!');
          }
          reject(tx.error);
        };
      });
    }

    document.getElementById('testSafeSave').addEventListener('click', async () => {
      try {
        const sampleRecord = { id: `rec_${Date.now()}`, text: 'Safe guarded record payload' };
        await safeSave(sampleRecord);
        log('🎉 Safe write completed successfully!');
      } catch (err) {
        log(`❌ Safe write rejected: ${err.message}`);
      }
    });
  </script>
</body>
</html>

Why this works: By coupling proactive capacity checks with navigator.storage.estimate() and reactive QuotaExceededError event handling on the transaction, mission-critical web applications ensure that write spikes never cause unhandled promise rejections or silent data dropouts.

⚠️ Common Pitfalls

Assuming Quotas are Fixed at 50MB: Unlike old documentation that referenced legacy Web SQL quotas, modern IndexedDB quotas scale dynamically with available OS hard drive capacity.
Ignoring WebKit's 7-Day Inactivity Rule: In Safari on iOS and macOS, temporary origin storage may be pruned if the user does not interact with the website for 7 consecutive days. Request persistent storage or prompt users to install your PWA to retain long-term offline data.
Treating navigator.storage.persist() as a Guarantee: Browsers may reject persistence requests if the user has never engaged with your domain. Always structure your application to function reliably even if persistence is denied.

💡 Pro Tips

Implement LRU Cache Eviction in Userland: Build an index on lastAccessedAt timestamp in your media cache. When storage reaches 80% capacity, run a cursor to delete the oldest 20% of media blobs before the browser triggers an origin eviction.
Prompt for Persistence During Key User Milestones: Instead of requesting persist() on page load, trigger it when the user performs a high-intent action—such as creating an offline document, enabling offline sync, or installing your PWA.

📌 Key Takeaways

navigator.storage.estimate() provides real-time visibility into byte usage and allocated quota.
By default, client storage is "Best-Effort", meaning the browser can purge it under low-disk conditions using an LRU eviction strategy.
navigator.storage.persist() requests persistent storage, protecting data from automated browser eviction.
navigator.storage.persisted() checks the current persistence status of the origin.
Chromium grants persistence based on site engagement and installation heuristics, while WebKit enforces strict user-origin retention policies.
--

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

? Question 1 / 3

What is the difference between "Best-Effort" (Temporary) storage and "Persistent" storage in the browser?

Topic: HTML Fundamentals

? Question 2 / 3

Which JavaScript API method allows a web application to inspect its current disk usage and quota in bytes?

Topic: HTML Fundamentals

? Question 3 / 3

Which error is thrown by IndexedDB if an application attempts to write data that exceeds the allocated disk quota?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Storage Quota Calculations

The Storage API: Key Methods

Browser Heuristics for Granting Persistence

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Graceful Quota Exhaustion Guard

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the difference between "Best-Effort" (Temporary) storage and "Persistent" storage in the browser?

Which JavaScript API method allows a web application to inspect its current disk usage and quota in bytes?

Which error is thrown by IndexedDB if an application attempts to write data that exceeds the allocated disk quota?