💾 Chapter 48: Web Storage API

Storing Complex Data & Serialization

Custom JSON replacers and revivers: Preserving `Date`, `Map`, `Set`, `BigInt`, and defending against circular references.

LEARNING OBJECTIVES ⌵

Understand why naive JSON.stringify() fails on advanced JavaScript data types (Date, Map, Set, BigInt, RegExp).
Implement custom JSON.stringify replacer functions to encode rich data types.
Implement custom JSON.parse reviver functions to restore typed object prototypes.
Defend against fatal TypeError: Converting circular structure to JSON crashes using weak reference tracking.

🎬 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 sending a complex Lego sculpture of a pirate ship across the country in a flat envelope. You cannot put the 3D ship into the slot as-is. You must carefully disassemble the ship into flat bricks, record an assembly instruction manual with colored tags, and slide the flat pieces into the envelope.

When your friend receives the envelope, if they just dump the bricks on the floor without reading the instructions, they just have a pile of plastic rectangles—not a ship. To get the ship back, they must read the tagged instruction manual and reassemble every mast, cannon, and deck back into its original 3D form.

+---------------------------------------------------------------------------------------------------+
|  THE SERIALIZATION LIFECYCLE (Disassembly & Reassembly)                                           |
|                                                                                                   |
|  [ Rich JS Object Graph ]                                                                         |
|  - Date: new Date()                                                                               |
|  - Map: new Map([['key', 42]])                                                                    |
|  - Set: new Set(['admin', 'user'])                                                                |
|             |                                                                                     |
|             v  JSON.stringify(payload, customReplacer)                                            |
|  [ Flat UTF-16 DOMString in localStorage ]                                                        |
|  '{"date":{"__type":"Date","val":"2026-08-21T00:00:00Z"},"roles":{"__type":"Set","val":["admin"]}}'|
|             |                                                                                     |
|             v  JSON.parse(rawString, customReviver)                                               |
|  [ Restored JS Instances with Active Methods (.getTime(), .has(), .get()) ]                       |
+---------------------------------------------------------------------------------------------------+

In Web Storage, the storage engine only accepts flat UTF-16 strings. Serializing is disassembling the ship; deserializing with a reviver is rebuilding it with all its original methods intact.

Technical Deep Dive & Specifications

The Limitations of Standard `JSON.stringify()`

Default JSON.stringify() only supports primitive numbers, strings, booleans, arrays, null, and plain object literals. All other native JavaScript constructs suffer silent data corruption or throw runtime errors:

// 1. Dates lose their class prototype and become ISO strings:
const d = new Date();
JSON.stringify(d); // ""2026-08-21T02:00:00.000Z"" -> Becomes a plain string!
// d.getFullYear() works; JSON.parse(JSON.stringify(d)).getFullYear() throws TypeError!

// 2. Maps serialize to empty objects:
const m = new Map([['status', 'active']]);
JSON.stringify(m); // "{}" -> All Map entries lost!

// 3. Sets serialize to empty objects:
const s = new Set([1, 2, 3]);
JSON.stringify(s); // "{}" -> All Set items lost!

// 4. BigInt throws a fatal TypeError:
const b = 900719925474099100n;
JSON.stringify(b); // Uncaught TypeError: Do not know how to serialize a BigInt

// 5. Undefined & Functions are completely omitted:
const obj = { fn: () => {}, val: undefined, visible: 1 };
JSON.stringify(obj); // '{"visible":1}'

// 6. Circular references throw an uncaught exception:
const node = {};
node.self = node;
JSON.stringify(node); // Uncaught TypeError: Converting circular structure to JSON

JSON Data Type Handling Matrix

Data Structure	Default `JSON.stringify`	Result of Default `JSON.parse`	Data Loss / Error	Custom Replacer/Reviver Solution
`Date`	`"2026-08-21T..."`	String (not `Date`)	⚠️ Methods lost (`.getTime()`)	Wrap with `__type: 'Date'`
`Map`	`{}`	`{}`	❌ Total loss of keys & values	Wrap with `__type: 'Map'`, entries array
`Set`	`{}`	`{}`	❌ Total loss of values	Wrap with `__type: 'Set'`, elements array
`BigInt`	💥 `TypeError`	N/A (Crashes)	❌ Application Crash	Wrap with `__type: 'BigInt'`, stringified digits
`RegExp`	`{}`	`{}`	❌ Total loss of pattern & flags	Wrap with `__type: 'RegExp'`, source & flags
`Circular Ref`	💥 `TypeError`	N/A (Crashes)	❌ Application Crash	Track visited nodes with `WeakSet`

Architecting Custom Replacers and Revivers

The second argument of JSON.stringify(value, replacer) and JSON.parse(text, reviver) allows intercepting every key-value pair during the traversal of the object graph.

       JSON.stringify(val, replacer)                     JSON.parse(str, reviver)
                     |                                               |
                     v                                               v
+------------------------------------------+    +------------------------------------------+
| Check Type:                              |    | Check if value is tagged object:         |
| If Date   -> { __t: 'Date', v: ISO }     |    | If __t === 'Date'   -> return new Date(v)|
| If Map    -> { __t: 'Map', v: [...m] }   |    | If __t === 'Map'    -> return new Map(v) |
| If Set    -> { __t: 'Set', v: [...s] }   |    | If __t === 'Set'    -> return new Set(v) |
| If BigInt -> { __t: 'BigInt', v: str }   |    | If __t === 'BigInt' -> return BigInt(v)  |
| Else      -> return default value        |    | Else                -> return value      |
+------------------------------------------+    +------------------------------------------+

Defending Against Circular References

When an object references itself directly or indirectly, JSON.stringify recurses infinitely until it throws a TypeError. We can protect storage writes using a WeakSet to track visited object references.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Lines 50–69 (superReplacer): Detects rich non-standard instances (BigInt, Map, Set, RegExp) and transforms them into standard object dictionaries containing explicit __dataType metadata tags and array representations.
Lines 72–92 (superReviver): Intercepts parsed objects containing the __dataType tag and instantiates actual ES6 class objects (new Map(), new Set(), BigInt(), new Date()).
Lines 95–105 (safeStringify): Uses an in-flight WeakSet to detect previously visited object references, converting circular cycles into safe sentinel strings ("[Circular Reference]") instead of throwing fatal runtime errors.
Lines 135–144: Validates that all class methods (.getFullYear(), .get(), .has(), .test()) work natively on the restored object without manual conversions.

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>Complex Data Serialization & Revitalization</title>
  <style>
    :root {
      --bg: #0f172a;
      --card: #1e293b;
      --text: #f8fafc;
      --accent: #38bdf8;
      --success: #4ade80;
    }
    body {
      font-family: system-ui, -apple-system, sans-serif;
      background: var(--bg);
      color: var(--text);
      padding: 2rem;
      line-height: 1.5;
    }
    .container { max-width: 800px; margin: 0 auto; background: var(--card); padding: 2rem; border-radius: 12px; }
    pre { background: #020617; padding: 1rem; border-radius: 6px; overflow-x: auto; color: #a5f3fc; }
    button {
      background: var(--accent);
      color: #0f172a;
      border: none;
      padding: 0.6rem 1.2rem;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
      margin-right: 0.5rem;
    }
    .badge { display: inline-block; padding: 0.25rem 0.5rem; border-radius: 4px; font-weight: bold; background: #0369a1; }
    .test-result { margin-top: 1rem; padding: 1rem; border-radius: 6px; background: rgba(255,255,255,0.05); }
  </style>
</head>
<body>
  <div class="container">
    <h2>Complex Data Serialization Engine</h2>
    <p>Test the preservation of rich JavaScript instances across `localStorage` storage cycles.</p>

<button id="btn-save">Serialize & Store Rich Object</button>
    <button id="btn-load">Deserialize & Revive Types</button>

<h3>1. Stored Raw JSON in `localStorage`:</h3>
    <pre id="raw-json">// Awaiting write...</pre>

<h3>2. Revitalized Object Inspection & Method Verification:</h3>
    <div id="test-output" class="test-result">Click "Serialize & Store" then "Deserialize & Revive"</div>
  </div>

// 1. Custom Serializer Replacer with Circular Reference Defense
    function superReplacer(key, value) {
      // Handle BigInt
      if (typeof value === 'bigint') {
        return { __dataType: 'BigInt', value: value.toString() };
      }
      // Handle Map
      if (value instanceof Map) {
        return { __dataType: 'Map', value: Array.from(value.entries()) };
      }
      // Handle Set
      if (value instanceof Set) {
        return { __dataType: 'Set', value: Array.from(value.values()) };
      }
      // Handle RegExp
      if (value instanceof RegExp) {
        return { __dataType: 'RegExp', source: value.source, flags: value.flags };
      }
      return value;
    }

// 2. Custom Deserializer Reviver
    function superReviver(key, value) {
      if (value && typeof value === 'object' && value.__dataType) {
        switch (value.__dataType) {
          case 'BigInt':
            return BigInt(value.value);
          case 'Map':
            return new Map(value.value);
          case 'Set':
            return new Set(value.value);
          case 'RegExp':
            return new RegExp(value.source, value.flags);
          case 'Date':
            return new Date(value.value);
        }
      }
      // ISO Date String auto-detection
      if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)) {
        return new Date(value);
      }
      return value;
    }

// Safe Serializer with Circular Reference Guard
    function safeStringify(obj) {
      const seen = new WeakSet();
      return JSON.stringify(obj, (key, value) => {
        if (typeof value === 'object' && value !== null) {
          if (seen.has(value)) {
            return '[Circular Reference]';
          }
          seen.add(value);
        }
        return superReplacer(key, value);
      }, 2);
    }

// Interactive Demo
    document.getElementById('btn-save').addEventListener('click', () => {
      const complexData = {
        title: 'Enterprise Task State',
        createdAt: new Date(),
        metadata: new Map([
          ['assignedTo', 'Devin'],
          ['priority', 'P0-Critical']
        ]),
        tags: new Set(['frontend', 'security', 'storage']),
        bigIdentifier: 9007199254740992451n,
        patternValidator: /^[a-z0-9_-]{3,16}$/i
      };

// Add circular reference intentionally
      complexData.selfReference = complexData;

const serialized = safeStringify(complexData);
      localStorage.setItem(KEY, serialized);
      document.getElementById('raw-json').textContent = serialized;
      alert('Complex data successfully serialized and saved to localStorage!');
    });

document.getElementById('btn-load').addEventListener('click', () => {
      const raw = localStorage.getItem(KEY);
      if (!raw) {
        alert('No data found in localStorage. Click save first!');
        return;
      }

const revived = JSON.parse(raw, superReviver);
      const out = document.getElementById('test-output');

// Verify prototypes and methods
      const isDate = revived.createdAt instanceof Date;
      const isMap = revived.metadata instanceof Map;
      const isSet = revived.tags instanceof Set;
      const isBigInt = typeof revived.bigIdentifier === 'bigint';
      const isRegExp = revived.patternValidator instanceof RegExp;

out.innerHTML = `
        <p>✅ <strong>Date check:</strong> <code>instanceof Date</code> = <b>${isDate}</b> | .getFullYear(): <b>${revived.createdAt.getFullYear()}</b></p>
        <p>✅ <strong>Map check:</strong> <code>instanceof Map</code> = <b>${isMap}</b> | .get('priority'): <b>${revived.metadata.get('priority')}</b></p>
        <p>✅ <strong>Set check:</strong> <code>instanceof Set</code> = <b>${isSet}</b> | .has('security'): <b>${revived.tags.has('security')}</b></p>
        <p>✅ <strong>BigInt check:</strong> <code>typeof === 'bigint'</code> = <b>${isBigInt}</b> | Value: <b>${revived.bigIdentifier.toString()}n</b></p>
        <p>✅ <strong>RegExp check:</strong> <code>.test('alice_01')</code> = <b>${revived.patternValidator.test('alice_01')}</b></p>
        <p>🛡️ <strong>Circular Reference Guard:</strong> <b>${revived.selfReference}</b></p>
      `;
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

+--------------------------------------------------------------------------+
| Complex Data Serialization Engine                                        |
| [ Serialize & Store Rich Object ]  [ Deserialize & Revive Types ]        |
|                                                                          |
| 1. Stored Raw JSON in localStorage:                                      |
| {                                                                        |
|   "title": "Enterprise Task State",                                      |
|   "createdAt": "2026-08-21T02:25:00.000Z",                               |
|   "metadata": {                                                          |
|     "__dataType": "Map",                                                 |
|     "value": [["assignedTo", "Devin"], ["priority", "P0-Critical"]]     |
|   },                                                                     |
|   "tags": {                                                              |
|     "__dataType": "Set",                                                 |
|     "value": ["frontend", "security", "storage"]                         |
|   },                                                                     |
|   "bigIdentifier": { "__dataType": "BigInt", "value": "900719925..." },  |
|   "selfReference": "[Circular Reference]"                                |
| }                                                                        |
|                                                                          |
| 2. Revitalized Object Inspection & Method Verification:                  |
| [ok] Date check: instanceof Date = true | .getFullYear(): 2026           |
| [ok] Map check: instanceof Map = true | .get('priority'): P0-Critical     |
| [ok] Set check: instanceof Set = true | .has('security'): true           |
| [ok] BigInt check: typeof === 'bigint' = true                            |
+--------------------------------------------------------------------------+

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Complete Typed Storage Engine

Construct a reusable TypedStorage class with set(key, value) and get(key) methods that transparently supports storing and revitalizing arrays, objects, Date objects, Map, and Set without requiring the caller to manually parse or transform anything.

Your Goal:

Implement TypedStorage.set(key, value): Automatically serialize complex types with type metadata.
Implement TypedStorage.get(key): Automatically revitalize objects with exact class prototypes.
Defend against corrupted or non-JSON string values previously stored in the storage slot by falling back cleanly to returning the raw string.

🏁 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>TypedStorage Challenge</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 700px; margin: 0 auto; }
    .card { background: #f8fafc; border: 1px solid #e2e8f0; border-radius: 8px; padding: 1.5rem; }
    .pass { color: #16a34a; font-weight: bold; }
    .fail { color: #dc2626; font-weight: bold; }
  </style>
</head>
<body>
  <div class="card">
    <h2>Typed Storage Engine Test Bench</h2>
    <div id="test-results">Running verification suite...</div>
  </div>

  <script>
    class TypedStorage {
      static #replacer(key, value) {
        if (value instanceof Map) {
          return { __type: 'Map', entries: Array.from(value.entries()) };
        }
        if (value instanceof Set) {
          return { __type: 'Set', values: Array.from(value.values()) };
        }
        if (typeof value === 'bigint') {
          return { __type: 'BigInt', value: value.toString() };
        }
        return value;
      }

      static #reviver(key, value) {
        if (value && typeof value === 'object') {
          if (value.__type === 'Map') return new Map(value.entries);
          if (value.__type === 'Set') return new Set(value.values);
          if (value.__type === 'BigInt') return BigInt(value.value);
        }
        if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/.test(value)) {
          const date = new Date(value);
          if (!isNaN(date.getTime())) return date;
        }
        return value;
      }

      static set(key, value) {
        const serialized = JSON.stringify(value, TypedStorage.#replacer);
        localStorage.setItem(key, serialized);
      }

      static get(key) {
        const raw = localStorage.getItem(key);
        if (raw === null) return null;
        try {
          return JSON.parse(raw, TypedStorage.#reviver);
        } catch (e) {
          // If raw is not valid JSON (e.g. plain legacy string), return as-is
          return raw;
        }
      }
    }

    // Verification Suite
    const resultsContainer = document.getElementById('test-results');

    // Test 1: Map
    const sampleMap = new Map([['admin', true], ['tier', 'gold']]);
    TypedStorage.set('test_map', sampleMap);
    const retrievedMap = TypedStorage.get('test_map');
    const testMapOk = retrievedMap instanceof Map && retrievedMap.get('tier') === 'gold';

    // Test 2: Set
    const sampleSet = new Set(['read', 'write', 'execute']);
    TypedStorage.set('test_set', sampleSet);
    const retrievedSet = TypedStorage.get('test_set');
    const testSetOk = retrievedSet instanceof Set && retrievedSet.has('execute');

    // Test 3: Date
    const sampleDate = new Date('2026-08-21T12:00:00.000Z');
    TypedStorage.set('test_date', sampleDate);
    const retrievedDate = TypedStorage.get('test_date');
    const testDateOk = retrievedDate instanceof Date && retrievedDate.toISOString() === '2026-08-21T12:00:00.000Z';

    resultsContainer.innerHTML = `
      <p>Test 1 (Map Revitalization): <span class="${testMapOk ? 'pass' : 'fail'}">${testMapOk ? 'PASSED ✅' : 'FAILED ❌'}</span></p>
      <p>Test 2 (Set Revitalization): <span class="${testSetOk ? 'pass' : 'fail'}">${testSetOk ? 'PASSED ✅' : 'FAILED ❌'}</span></p>
      <p>Test 3 (Date Revitalization): <span class="${testDateOk ? 'pass' : 'fail'}">${testDateOk ? 'PASSED ✅' : 'FAILED ❌'}</span></p>
    `;
  </script>
</body>
</html>

Why this works:

Private static replacer and reviver functions encapsulate encoding and decoding mechanics cleanly within the class.
The ISO regex check detects date strings automatically, eliminating the need to wrap Date instances in custom metadata wrappers.
Catching SyntaxError prevents crashes if legacy un-serialized strings exist in storage.

⚠️ Common Pitfalls

Invoking JSON.stringify(bigint) Directly: BigInt does not have a .toJSON() method. Attempting to stringify a BigInt throws an immediate uncaught TypeError that will crash your application.
Assuming Date Prototypes Persist: JSON.parse(JSON.stringify(new Date())) returns a string primitive, not a Date instance. Calling .getTime() on it will throw a TypeError.
Unsanitized Object Keys (Prototype Pollution): When reviving untrusted JSON payloads containing keys like __proto__ or constructor, ensure your parser does not assign them directly to Object prototypes.

💡 Pro Tips

Use .toJSON() on Custom Classes: You can define a .toJSON() method on any custom class or domain model. JSON.stringify() will automatically call your .toJSON() method before serialization.
Compression for Large Payloads: For payloads approaching 100KB–500KB, evaluate compression libraries like lz-string (LZString.compressToUTF16(str)) before writing to localStorage to save up to 70% of quota space.

📌 Key Takeaways

JSON.stringify() natively fails to preserve Date, Map, Set, BigInt, and RegExp.
JSON.stringify(val, replacer) enables custom encoding for complex types.
JSON.parse(str, reviver) enables dynamic revitalization of typed instances.
Circular references can be defended against using WeakSet reference tracking during serialization.
Always protect JSON.parse() calls with try...catch to prevent unhandled syntax errors from corrupt strings.
--

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

? Question 1 / 3

What happens when you run `JSON.stringify({ balance: 100000000000000000n })` without a custom replacer?

Topic: HTML Fundamentals

? Question 2 / 3

How does `JSON.stringify` handle an ES6 `Map` by default?

Topic: HTML Fundamentals

? Question 3 / 3

What does the second argument of `JSON.parse(text, reviver)` do?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Limitations of Standard JSON.stringify()

JSON Data Type Handling Matrix

Architecting Custom Replacers and Revivers

Defending Against Circular References

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Complete Typed Storage Engine

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What happens when you run JSON.stringify({ balance: 100000000000000000n }) without a custom replacer?

How does JSON.stringify handle an ES6 Map by default?

What does the second argument of JSON.parse(text, reviver) do?

The Limitations of Standard `JSON.stringify()`

What happens when you run `JSON.stringify({ balance: 100000000000000000n })` without a custom replacer?

How does `JSON.stringify` handle an ES6 `Map` by default?

What does the second argument of `JSON.parse(text, reviver)` do?