💾 Chapter 48: Web Storage API

Quota Management & QuotaExceededError

Browser quota limits, UTF-16 byte memory calculations, `QuotaExceededError` exception handling, and automated LRU cache eviction.

LEARNING OBJECTIVES ⌵

Calculate the exact byte memory footprint of Web Storage data based on UTF-16 code units (2 bytes per character).
Understand quota allocations across major browser engines (Chromium, Gecko, WebKit).
Intercept and handle DOMException: QuotaExceededError without breaking application runtime state.
Design and implement an automated Least Recently Used (LRU) cache eviction algorithm for client-side storage.

🎬 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 a carry-on suitcase for an airplane flight that has a strict 5 kg weight limit. You can pack lightweight t-shirts, socks, and headphones with plenty of room to spare. But if you try to pack a 10 kg solid iron barbell, the airport luggage scale triggers a red alarm (QuotaExceededError) and the flight attendant refuses to let you board.

+---------------------------------------------------------------------------------------------------+
|  THE STORAGE QUOTA BOUNDARY                                                                       |
|                                                                                                   |
|  [ Current Storage Bucket: 4.8 MB consumed ]                                                      |
|  localStorage.setItem('huge_image_base64', '800KB payload')                                      |
|             |                                                                                     |
|             v  (Attempting write: Total would be 5.6 MB > 5.0 MB Limit!)                          |
|  💥 DOMException: Failed to execute 'setItem' on 'Storage': Setting the value... exceeded quota! |
|                                                                                                   |
|  * The write is REJECTED atomically. No partial data is written.                                  |
|  * Solution: Implement LRU Eviction to discard oldest items before writing!                       |
+---------------------------------------------------------------------------------------------------+

Without proactive quota management, your application will crash the moment an active user exceeds their local storage limit. By building an LRU (Least Recently Used) eviction engine, your application becomes self-cleaning—automatically shedding old, unused cached data to make room for fresh items.

Technical Deep Dive & Specifications

Browser Quota Comparison & Storage Allocations

The WHATWG specification recommends a default quota of 5 MB per origin, but does not enforce a rigid ceiling. Different browser vendors implement slightly different limits:

Browser Engine	Typical `localStorage` Quota	Typical `sessionStorage` Quota	Quota Scope
Google Chrome / Chromium	~5 MB – 10 MB	~5 MB – 10 MB	Per Origin (`<scheme, host, port>`)
Mozilla Firefox (Gecko)	~5 MB – 10 MB	~5 MB – 10 MB	Per Origin
Apple Safari (WebKit)	~5 MB	~5 MB	Per Origin (Subject to 7-day ITP caps)
Mobile Safari (iOS)	~5 MB	~5 MB	Per Origin (Restricted on low memory)

The UTF-16 Memory Model (2 Bytes Per Character)

In JavaScript and the DOM WebIDL specification, DOMString values are encoded in UTF-16 code units. Each character in a storage key or value consumes 2 bytes (16 bits) of allocated memory.

$$\text{Total Memory (Bytes)} = \sum (\text{length of Key} + \text{length of Value}) \times 2$$

Therefore:

A 5 MB quota allows roughly 2,621,440 characters (approx. 2.5 million characters of text).
Storing high-density binary data as Base64 strings inflates raw payload size by 33%, which is then doubled by UTF-16 encoding, rapidly consuming available storage.

`QuotaExceededError` Across Browser Engines

When storage.setItem() attempts to write a payload that exceeds the remaining origin quota, the browser throws a DOMException.

try {
  localStorage.setItem('my_key', largePayload);
} catch (error) {
  if (
    error instanceof DOMException &&
    (
      // Standard W3C/WHATWG name
      error.name === 'QuotaExceededError' ||
      // Legacy code check (W3C standard code 22)
      error.code === 22 ||
      // Firefox legacy name
      error.name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
      error.code === 1014
    )
  ) {
    console.error('Storage quota exceeded! Executing cache eviction...');
  }
}

The LRU (Least Recently Used) Eviction Architecture

An LRU cache tracks when items are accessed or written. When storage space runs out, the eviction engine deletes the item with the oldest access timestamp until sufficient space is freed.

       Write New Item -> [ Storage Full? ]
                                |
                   +------------+------------+
                   |                         |
               NO (Space OK)             YES (Full)
                   |                         |
               Write to Disk                 v
                                  Find Oldest 'lastAccessed'
                                             |
                                     Evict Oldest Key
                                             |
                                  Retry Write Operation

+------------------------------------------------------------------------------------+
|  LRU CACHE METADATA STRUCTURE                                                      |
|  Key: "cache:user:101"                                                             |
|  Value: {                                                                          |
|    "lastAccessed": 1724200000000,  // Unix timestamp (ms)                          |
|    "data": { "name": "Alice", "role": "engineer" }                                 |
|  }                                                                                 |
+------------------------------------------------------------------------------------+

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Lines 73–81 (calculateUsageBytes): Iterates through all stored keys and values, computing character count multiplied by 2 to measure total memory utilization in UTF-16 code units.
Lines 83–91 (updateMeter): Calculates percentage consumed against an estimated 5MB boundary and drives the CSS gradient meter width dynamically.
Lines 94–96 (create500KBString): Creates a 250,000-character string ('X'.repeat(250000)), which occupies exactly 500,000 bytes (approx. 500 KB) in memory.
Lines 100–108: Traps err.name === 'QuotaExceededError' cleanly when localStorage.setItem() exceeds capacity, preventing runtime crashes.
Lines 111–127 (btn-stress-test): Synchronously loops until setItem() throws, identifying the exact maximum storage boundary allocated by the host browser.

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 Stress Tester & Capacity Meter</title>
  <style>
    :root {
      --bg: #0f172a;
      --card: #1e293b;
      --accent: #38bdf8;
      --text: #f8fafc;
      --danger: #ef4444;
      --success: #22c55e;
    }
    body {
      font-family: system-ui, sans-serif;
      background: var(--bg);
      color: var(--text);
      padding: 2rem;
      line-height: 1.5;
    }
    .card {
      background: var(--card);
      max-width: 700px;
      margin: 0 auto;
      padding: 2rem;
      border-radius: 12px;
      border: 1px solid #334155;
    }
    .meter-container {
      background: #020617;
      border-radius: 8px;
      height: 24px;
      width: 100%;
      overflow: hidden;
      margin: 1rem 0;
      border: 1px solid #475569;
    }
    .meter-fill {
      height: 100%;
      background: linear-gradient(90deg, var(--success), #eab308, var(--danger));
      width: 0%;
      transition: width 0.3s ease;
    }
    .btn-group { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-top: 1rem; }
    button {
      padding: 0.6rem 1.2rem;
      border: none;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
      background: var(--accent);
      color: #0f172a;
    }
    button.danger { background: var(--danger); color: white; }
    pre { background: #020617; padding: 1rem; border-radius: 6px; color: #7dd3fc; max-height: 200px; overflow-y: auto; }
  </style>
</head>
<body>
  <div class="card">
    <h2>Storage Quota Stress Tester</h2>
    <p>Simulate memory consumption, calculate byte usage, and observe <code>QuotaExceededError</code> handling.</p>

<div>
      <strong>Current Usage:</strong> <span id="usage-text">0 KB</span> / ~5,120 KB (Est. 5MB)
    </div>

<div class="btn-group">
      <button id="btn-fill-500k">Inject 500 KB Chunk</button>
      <button id="btn-stress-test">Stress Test to Max Quota</button>
      <button id="btn-clear" class="danger">Clear Test Data</button>
    </div>

<h3>Diagnostic Log:</h3>
    <pre id="log">// Awaiting stress action...</pre>
  </div>

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

// 1. Calculate approximate usage in bytes (UTF-16)
    function calculateUsageBytes() {
      let chars = 0;
      for (let i = 0; i < localStorage.length; i++) {
        const k = localStorage.key(i);
        const v = localStorage.getItem(k);
        if (k && v) chars += (k.length + v.length);
      }
      return chars * 2; // 2 bytes per char
    }

function updateMeter() {
      const bytes = calculateUsageBytes();
      const kb = (bytes / 1024).toFixed(1);
      const estMaxBytes = 5 * 1024 * 1024; // 5MB estimate
      const percentage = Math.min(100, (bytes / estMaxBytes) * 100);

usageText.textContent = `${kb} KB (${(bytes / (1024 * 1024)).toFixed(2)} MB)`;
      meterBar.style.width = `${percentage}%`;
    }

// Generate 250,000 chars (approx 500 KB in UTF-16)
    function create500KBString() {
      return 'X'.repeat(250000);
    }

document.getElementById('btn-stress-test').addEventListener('click', () => {
      log('Starting automated stress fill until exhaustion...');
      let count = 0;
      const chunk = 'A'.repeat(50000); // 100KB in UTF-16

while (true) {
        try {
          const key = `${PREFIX}stress_${count}`;
          localStorage.setItem(key, chunk);
          count++;
        } catch (e) {
          log(`🚨 QUOTA EXCEEDED! Browser stopped writes at ${count} chunks.`);
          log(`Total estimated stored capacity before error: ${(calculateUsageBytes() / (1024 * 1024)).toFixed(2)} MB`);
          break;
        }
      }
      updateMeter();
    });

updateMeter();
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

+-------------------------------------------------------------+
| Storage Quota Stress Tester                                 |
| Current Usage: 4,500.0 KB (4.39 MB) / ~5,120 KB (Est. 5MB)   |
| [======================================------] 88%          |
|                                                             |
| [Inject 500 KB Chunk] [Stress Test to Max] [Clear Test Data]|
|                                                             |
| Diagnostic Log:                                             |
| [02:26:15] Successfully wrote 500KB chunk: quota_test_chunk |
| [02:26:18] 🚨 QUOTA EXCEEDED! Browser stopped writes at 51.  |
| [02:26:18] Total estimated stored capacity: 5.12 MB         |
+-------------------------------------------------------------+

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Automated Self-Evicting LRU Storage Manager

Build a production-ready cache wrapper class LRUStorageCache that stores items with a timestamp. When a QuotaExceededError occurs during a write, it automatically finds the oldest accessed key, deletes it, and retries the write operation until it succeeds.

Your Goal:

Prefix cached keys with a configurable namespace (e.g. lru_cache:).
Store every item wrapped in an envelope: { lastAccessed: Date.now(), data: payload }.
When get(key) is called, update the item's lastAccessed timestamp.
When set(key, data) throws QuotaExceededError, find the key in the namespace with the smallest lastAccessed timestamp, remove it, and retry writing.

🏁 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>LRU Storage Manager Challenge</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 650px; margin: 0 auto; line-height: 1.5; }
    .card { background: #f8fafc; border: 1px solid #e2e8f0; border-radius: 8px; padding: 1.5rem; }
    .log-box { background: #0f172a; color: #38bdf8; padding: 1rem; border-radius: 6px; font-family: monospace; font-size: 0.85rem; max-height: 250px; overflow-y: auto; }
    button { padding: 0.6rem 1.2rem; background: #2563eb; color: white; border: none; border-radius: 6px; font-weight: bold; cursor: pointer; }
  </style>
</head>
<body>
  <div class="card">
    <h2>Automated LRU Cache Eviction Engine</h2>
    <p>Click below to fill storage and watch the LRU engine evict oldest entries automatically upon reaching quota.</p>
    
    <button id="btn-run">Run LRU Stress Benchmark</button>
    <button id="btn-clean" style="background: #dc2626;">Purge LRU Keys</button>

    <h3>Engine Action Log:</h3>
    <div id="log" class="log-box">// Ready...</div>
  </div>

  <script>
    const logBox = document.getElementById('log');
    function log(msg) {
      logBox.innerHTML += `<div>[${new Date().toLocaleTimeString()}] ${msg}</div>`;
      logBox.scrollTop = logBox.scrollHeight;
    }

    class LRUStorageCache {
      constructor(prefix = 'app_lru_') {
        this.prefix = prefix;
      }

      #formatKey(key) {
        return this.prefix + key;
      }

      set(key, data) {
        const fullKey = this.#formatKey(key);
        const envelope = {
          lastAccessed: Date.now(),
          data: data
        };

        let attempts = 0;
        const MAX_ATTEMPTS = 50;

        while (attempts < MAX_ATTEMPTS) {
          try {
            localStorage.setItem(fullKey, JSON.stringify(envelope));
            return true;
          } catch (err) {
            if (err.name === 'QuotaExceededError' || err.code === 22 || err.name === 'NS_ERROR_DOM_QUOTA_REACHED') {
              log(`⚠️ Storage full! Evicting oldest LRU entry to make room...`);
              const evictedKey = this.evictOldest();
              if (!evictedKey) {
                throw new Error('LRU Eviction Failed: No evictable LRU keys remaining in storage.');
              }
              attempts++;
            } else {
              throw err;
            }
          }
        }
        throw new Error('LRU Eviction limit exceeded.');
      }

      get(key) {
        const fullKey = this.#formatKey(key);
        const raw = localStorage.getItem(fullKey);
        if (!raw) return null;

        try {
          const envelope = JSON.parse(raw);
          // Refresh last accessed timestamp
          envelope.lastAccessed = Date.now();
          localStorage.setItem(fullKey, JSON.stringify(envelope));
          return envelope.data;
        } catch (e) {
          return null;
        }
      }

      evictOldest() {
        let oldestKey = null;
        let oldestTime = Infinity;

        for (let i = 0; i < localStorage.length; i++) {
          const k = localStorage.key(i);
          if (k && k.startsWith(this.prefix)) {
            try {
              const item = JSON.parse(localStorage.getItem(k));
              if (item && item.lastAccessed < oldestTime) {
                oldestTime = item.lastAccessed;
                oldestKey = k;
              }
            } catch (e) {
              // If corrupt, evict immediately
              oldestKey = k;
              break;
            }
          }
        }

        if (oldestKey) {
          localStorage.removeItem(oldestKey);
          log(`🗑️ Evicted oldest cached key: <b>${oldestKey}</b> (Last used: ${new Date(oldestTime).toLocaleTimeString()})`);
          return oldestKey;
        }
        return null;
      }

      clearAll() {
        const keys = [];
        for (let i = 0; i < localStorage.length; i++) {
          const k = localStorage.key(i);
          if (k && k.startsWith(this.prefix)) keys.push(k);
        }
        keys.forEach(k => localStorage.removeItem(k));
        log(`Cleared ${keys.length} LRU items.`);
      }
    }

    // Benchmark runner
    const cache = new LRUStorageCache('benchmark_lru_');

    document.getElementById('btn-run').addEventListener('click', () => {
      log('Running LRU stress test (inserting 100 x 200KB entries)...');
      const largePayload = 'Z'.repeat(100000); // ~200KB UTF-16

      for (let i = 1; i <= 35; i++) {
        try {
          cache.set(`resource_${i}`, { index: i, payload: largePayload });
          log(`Saved resource_${i}`);
        } catch (e) {
          log(`❌ Fatal: ${e.message}`);
          break;
        }
      }
      log('✅ LRU stress benchmark completed successfully without unhandled exceptions!');
    });

    document.getElementById('btn-clean').addEventListener('click', () => {
      cache.clearAll();
    });
  </script>
</body>
</html>

Why this works:

When localStorage.setItem throws QuotaExceededError, execution enters the catch block where this.evictOldest() is invoked.
evictOldest() inspects only keys starting with the configured namespace prefix and deletes the record with the oldest lastAccessed timestamp.
The while loop re-attempts the write immediately with the newly cleared disk space, providing a 100% resilient self-healing storage engine.

⚠️ Common Pitfalls

Base64 Bloat in Web Storage: Storing base64 images or PDFs in localStorage quickly triggers QuotaExceededError. Base64 is ~33% larger than raw binary, and JavaScript doubles this in memory via UTF-16. Use IndexedDB with Blob or ArrayBuffer instead.
Assuming 10MB Everywhere: Never assume 10MB is guaranteed. On low-memory mobile devices or privacy browsers (Brave/Tor), storage limits can be restricted to 5MB or less.
Unbounded Writes in Event Handlers: Storing continuous user coordinates (mousemove or scroll positions) without throttling will rapidly exhaust disk space.

💡 Pro Tips

The Storage API (navigator.storage.estimate): Use the modern navigator.storage.estimate() API to query overall origin storage quota and usage asynchronously before attempting large operations.
Soft Quota Warning Thresholds: Set an in-app soft ceiling (e.g. 80% of capacity). When usage exceeds 4MB, trigger proactive background cleanup before a hard QuotaExceededError interrupts user workflows.

📌 Key Takeaways

Web Storage limits typically range from 5 MB to 10 MB per origin.
JavaScript strings in Web Storage use UTF-16 code units (2 bytes per character).
Writing beyond the available quota throws a DOMException named QuotaExceededError.
Writes that fail due to quota exhaustion are rejected atomically; no partial data is written.
Implementing an LRU (Least Recently Used) cache eviction algorithm ensures automatic cleanup and prevents application crashes.
--

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

? Question 1 / 3

How much disk/memory space does a 1,000,000-character ASCII string consume in Web Storage?

Topic: HTML Fundamentals

? Question 2 / 3

What happens to existing `localStorage` data when a `QuotaExceededError` is thrown during a `setItem()` call?

Topic: HTML Fundamentals

? Question 3 / 3

How does an LRU (Least Recently Used) cache decide which item to evict first when storage is full?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Browser Quota Comparison & Storage Allocations

The UTF-16 Memory Model (2 Bytes Per Character)

QuotaExceededError Across Browser Engines

The LRU (Least Recently Used) Eviction Architecture

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Automated Self-Evicting LRU Storage Manager

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

How much disk/memory space does a 1,000,000-character ASCII string consume in Web Storage?

What happens to existing localStorage data when a QuotaExceededError is thrown during a setItem() call?

How does an LRU (Least Recently Used) cache decide which item to evict first when storage is full?

`QuotaExceededError` Across Browser Engines

What happens to existing `localStorage` data when a `QuotaExceededError` is thrown during a `setItem()` call?