Chapter 49: IndexedDB Client-Side Database

ObjectStores & Primary Keys

Designing schema containers, mastering in-line vs out-of-line keys, auto-increment generators, and composite key paths.

LEARNING OBJECTIVES ⌵

Understand the role of an IDBObjectStore as the primary storage collection in IndexedDB.
Differentiate between the four fundamental keying strategies in IndexedDB.
Implement composite (multi-field) primary keys using array keyPath definitions.
Identify valid vs invalid IndexedDB key data types according to the W3C specification.

🎬 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 modern warehouse fulfillment center.

An ObjectStore is like a specialized storage aisle in the warehouse (for example, the "Electronics Aisle" or the "Customer Accounts Aisle"). Every item placed on the shelves must have an inventory tracking identifier—a Primary Key—so workers can instantly pinpoint and retrieve it.

How do items get their inventory tracking numbers?

The In-Line Barcode (keyPath: "sku"): The manufacturer prints the barcode directly onto the product's packaging. When you receive the product, the warehouse system reads the existing sku property inside the object itself.
The In-Line Smart Stamper (keyPath: "id", autoIncrement: true): The product arrives as a blank box without an ID. The receiving machine automatically laser-prints an incremental number (1, 2, 3...) right onto the product and records that number in the object's id field.
The Out-of-Line Shelf Tag (autoIncrement: false, no keyPath): The items are plain unmarked goods. The warehouse manager manually writes an external tag on the shelf slot (e.g., "slot-A9") during delivery (store.add(item, "slot-A9")). The item itself has no clue what slot it sits in.
The Out-of-Line Auto-Ticket Machine (autoIncrement: true, no keyPath): Unmarked goods enter the conveyor belt, and a ticket dispenser hands the worker a sequential receipt number (1, 2, 3...) while placing the item on the shelf.

Technical Deep Dive & Specifications

The Four Primary Keying Strategies

When creating an ObjectStore using db.createObjectStore(storeName, options), you configure how keys are resolved for every record:

+----------------------------------------------------------------------------------------------------+
|                                INDEXEDDB KEYING STRATEGY MATRIX                                    |
+-------------------+---------------------+-------------------------+--------------------------------+
| Key Strategy      | createObjectStore   | How Key is Determined   | Example store.add() Call       |
|                   | Options             |                         |                                |
+-------------------+---------------------+-------------------------+--------------------------------+
| 1. In-Line Only   | { keyPath: "id" }   | Extracted directly from | `store.add({ id: "u_1", ...})` |
|                   |                     | the object property     | (Fails if 'id' is missing)     |
+-------------------+---------------------+-------------------------+--------------------------------+
| 2. In-Line + Auto | { keyPath: "id",    | If object has 'id', it  | `store.add({ name: "Dan" })`   |
|    Increment      |   autoIncrement:    | is used; otherwise,     | (Auto-assigns id: 1 to object) |
|                   |   true }            | generator creates one   |                                |
+-------------------+---------------------+-------------------------+--------------------------------+
| 3. Out-of-Line    | { }                 | Must pass key as second | `store.add({ name: "Eva" },    |
|    Manual         | (no options)        | parameter in add()/put()|            "user_eva_99")`     |
+-------------------+---------------------+-------------------------+--------------------------------+
| 4. Out-of-Line    | { autoIncrement:    | Generator creates key;  | `store.add({ name: "Frank" })` |
|    Auto Increment |   true }            | returns key on success  | (Returns key 1; object unmod.) |
+-------------------+---------------------+-------------------------+--------------------------------+

Valid vs Invalid Key Types

IndexedDB enforces strict rules regarding what JavaScript values qualify as valid keys:

+---------------------------------------------------------------------------------+
|                               VALID KEY TYPES                                   |
+---------------------------------------------------------------------------------+
| ✅ String         | Any valid UTF-16 string (e.g. "order_9812", "[email protected]") |
| ✅ Number         | Any finite IEEE 754 number (e.g. 1, 42.5). NOT NaN or Infinity!|
| ✅ Date           | Valid Date objects (e.g. new Date()). NOT Invalid Date!       |
| ✅ ArrayBuffer    | Binary buffer instances (or TypedArray views)                   |
| ✅ Array          | Arrays where EVERY element is itself a valid key (Compound Key) |
+---------------------------------------------------------------------------------+
|                              INVALID KEY TYPES                                  |
+---------------------------------------------------------------------------------+
| ❌ Boolean        | true, false (Throws DataError)                                  |
| ❌ Null / Undef   | null, undefined (Throws DataError)                              |
| ❌ Plain Object   | { foo: "bar" } cannot be a key (Throws DataError)               |
| ❌ RegExp / Map   | Non-primitive collections and regular expressions               |
+---------------------------------------------------------------------------------+

Compound (Composite) Primary Keys

You can define a composite primary key by passing an array of property paths to keyPath:

// Compound key: Unique combination of tenantId and invoiceNumber
const store = db.createObjectStore('invoices', { 
  keyPath: ['tenantId', 'invoiceNumber'] 
});

// Storing a record:
store.add({
  tenantId: 'acme_corp',
  invoiceNumber: 10452,
  amount: 4500.00
});
// Key in store is evaluated as: ['acme_corp', 10452]

💻 Interactive Code Playground

Starter Code

Save this file as object-stores.html and open it in your browser.

Line-by-Line Code Breakdown

Line 55 (d.createObjectStore('articles', { keyPath: 'id', autoIncrement: true })): Generates an auto-incrementing integer key and writes it directly into the object's id property.
Line 57 (d.createObjectStore('blobs')): Creates an out-of-line store. Every insertion requires passing the key as the second parameter: store.add(data, key).
Line 59 (d.createObjectStore('metrics', { keyPath: ['server', 'timestamp'] })): Configures a compound key. An entry is valid only if both server and timestamp contain valid key data types.
Lines 70–75 (store.add(article)): Notice that when autoIncrement is combined with keyPath: 'id', IndexedDB mutates the in-memory object by attaching the generated id.
Lines 104–109 (store.add({ data: 1 }, true)): Demonstrates that passing a Boolean (true) as a primary key violates the IndexedDB specification and immediately throws a DataError.

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>IndexedDB ObjectStores Explorer</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 800px;
      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;
      border: 1px solid #334155;
      border-radius: 8px;
      padding: 1rem;
    }
    button {
      background: #0ea5e9;
      color: white;
      border: none;
      padding: 0.5rem 1rem;
      border-radius: 6px;
      cursor: pointer;
      font-weight: 600;
      width: 100%;
      margin-top: 0.5rem;
    }
    button:hover { background: #0284c7; }
    #logOutput {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 180px;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>

<h1>ObjectStore Keying Playground</h1>

<div class="grid">
    <div class="card">
      <h3>1. In-Line Auto-Increment</h3>
      <p>Store: <code>articles</code> (keyPath: "id", autoIncrement: true)</p>
      <button id="addArticleBtn">Insert Article</button>
    </div>

<div class="card">
      <h3>2. Out-of-Line Key</h3>
      <p>Store: <code>blobs</code> (no keyPath, out-of-line manual key)</p>
      <button id="addBlobBtn">Insert Named Blob</button>
    </div>

<div class="card">
      <h3>3. Compound Key</h3>
      <p>Store: <code>metrics</code> (keyPath: ["server", "timestamp"])</p>
      <button id="addMetricBtn">Insert Server Metric</button>
    </div>

<div class="card">
      <h3>4. Test Invalid Key</h3>
      <p>Attempting to use a <code>Boolean</code> as primary key</p>
      <button id="testInvalidBtn">Trigger Invalid Key Error</button>
    </div>
  </div>

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

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

req.onupgradeneeded = (e) => {
      const d = e.target.result;
      log('🛠️ Creating 3 distinct ObjectStores...');
      // 1. In-line with autoIncrement
      d.createObjectStore('articles', { keyPath: 'id', autoIncrement: true });
      // 2. Out-of-line without keyPath
      d.createObjectStore('blobs');
      // 3. Composite/Compound key
      d.createObjectStore('metrics', { keyPath: ['server', 'timestamp'] });
    };

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

// 1. In-line Auto-Increment
    document.getElementById('addArticleBtn').addEventListener('click', () => {
      const tx = db.transaction('articles', 'readwrite');
      const store = tx.objectStore('articles');
      const article = { title: 'Understanding IndexedDB', tags: ['web', 'html5'] };
      const reqAdd = store.add(article);

reqAdd.onsuccess = () => {
        log(`📰 Article inserted! Generated key: ${reqAdd.result}, Object id: ${article.id}`);
      };
    });

// 2. Out-of-Line Manual Key
    document.getElementById('addBlobBtn').addEventListener('click', () => {
      const tx = db.transaction('blobs', 'readwrite');
      const store = tx.objectStore('blobs');
      const customKey = `asset_logo_${Date.now()}`;
      const payload = { mime: 'image/png', bytes: [137, 80, 78, 71] };
      const reqAdd = store.add(payload, customKey);

reqAdd.onsuccess = () => {
        log(`📦 Blob stored with out-of-line key: "${customKey}"`);
      };
    });

// 3. Compound Key
    document.getElementById('addMetricBtn').addEventListener('click', () => {
      const tx = db.transaction('metrics', 'readwrite');
      const store = tx.objectStore('metrics');
      const sample = {
        server: 'us-east-1',
        timestamp: Date.now(),
        cpuUsage: (Math.random() * 100).toFixed(2) + '%'
      };
      const reqAdd = store.add(sample);

reqAdd.onsuccess = () => {
        log(`📈 Compound Metric stored! Key: ${JSON.stringify(reqAdd.result)}`);
      };
    });

// 4. Invalid Key Test
    document.getElementById('testInvalidBtn').addEventListener('click', () => {
      try {
        const tx = db.transaction('blobs', 'readwrite');
        const store = tx.objectStore('blobs');
        log('⚠️ Attempting store.add({ data: 1 }, true) [Boolean Key]...');
        store.add({ data: 1 }, true); // Throws DataError
      } catch (err) {
        log(`❌ Caught Expected Error: ${err.name} - ${err.message}`);
      }
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[02:40:01] 🛠️ Creating 3 distinct ObjectStores...
[02:40:01] ✅ KeySchemesDB ready for testing.
[02:40:05] 📰 Article inserted! Generated key: 1, Object id: 1
[02:40:08] 📦 Blob stored with out-of-line key: "asset_logo_1718000100"
[02:40:11] 📈 Compound Metric stored! Key: ["us-east-1", 1718000103]
[02:40:14] ⚠️ Attempting store.add({ data: 1 }, true) [Boolean Key]...
[02:40:14] ❌ Caught Expected Error: DataError - The data provided to an operation does not meet requirements.

🏋️ Hands-On Exercise

🎯 The Challenge: Multi-Tenant Schema Architect

Instructions:

Create an IndexedDB database named SaaSPlatform at Version 1.
In onupgradeneeded, create an ObjectStore named tenant_files configured with:
- A compound primary key consisting of tenantId and filePath.
Insert two records for tenantId: "tenant_alpha":
- { tenantId: "tenant_alpha", filePath: "/docs/readme.txt", size: 1024 }
- { tenantId: "tenant_alpha", filePath: "/images/hero.png", size: 204800 }
Attempt to insert a duplicate record with the exact same tenantId and filePath and verify that IndexedDB triggers a ConstraintError.

🏁 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>SaaS Schema Architect</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>SaaS Multi-Tenant Key Test</h1>
  <button id="runTest">Execute Insertion & Constraint Test</button>
  <pre id="output"></pre>

  <script>
    document.getElementById('runTest').addEventListener('click', () => {
      const out = document.getElementById('output');
      out.textContent = '';
      const log = (msg) => out.textContent += `${msg}\n`;

      const req = indexedDB.open('SaaSPlatform', 1);

      req.onupgradeneeded = (e) => {
        const db = e.target.result;
        db.createObjectStore('tenant_files', { keyPath: ['tenantId', 'filePath'] });
        log('✅ ObjectStore "tenant_files" created with compound key ["tenantId", "filePath"]');
      };

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

        const file1 = { tenantId: 'tenant_alpha', filePath: '/docs/readme.txt', size: 1024 };
        const file2 = { tenantId: 'tenant_alpha', filePath: '/images/hero.png', size: 204800 };

        store.add(file1);
        store.add(file2);
        log('✅ Inserted 2 valid tenant file records.');

        // Attempt duplicate insertion
        const dupReq = store.add(file1);
        dupReq.onsuccess = () => log('⚠️ Duplicate unexpectedly succeeded!');
        dupReq.onerror = (errEvent) => {
          log(`🔒 Expected Duplicate Blocked! Error: ${dupReq.error.name} - ${dupReq.error.message}`);
          errEvent.preventDefault(); // Prevent aborting the transaction
        };

        tx.oncomplete = () => {
          log('🎉 Transaction complete.');
          db.close();
        };
      };
    });
  </script>
</body>
</html>

Why this works: IndexedDB evaluates the compound key ['tenant_alpha', '/docs/readme.txt']. Because primary keys within an ObjectStore must be unique, attempting to re-insert an identical key fires a ConstraintError. Calling errEvent.preventDefault() stops the error from bubbling up and aborting other pending operations in the transaction.

⚠️ Common Pitfalls

Supplying an Out-of-Line Key to an In-Line Store: If a store was defined with keyPath: "id", executing store.add({ id: 1, name: "A" }, 1) throws an InvalidAccessError: Failed to execute 'add' on 'IDBObjectStore': The object store uses in-line keys and the key parameter was provided.
Using Invalid Key Types in keyPath: Attempting to use true, false, null, or an empty object as a primary key throws a DataError.
Modifying In-Line Key Properties Post-Creation: If you update an object and change its keyPath value, calling store.put(updatedObj) will insert a brand new record instead of updating the existing one.

💡 Pro Tips

Leverage Composite Keys for Hierarchical Isolation: In multi-tenant, workspace-based, or folder-based web apps, using compound keys like ['workspaceId', 'documentId'] provides instant tenant isolation without requiring separate ObjectStores.
Use UUIDs / CUIDs for Distributed Offline Systems: When building offline-first apps that sync with a server, prefer client-generated UUIDv4 or ULID strings over autoIncrement: true to prevent ID collisions during multi-device synchronization.

📌 Key Takeaways

An IDBObjectStore is the core container in IndexedDB, holding records organized by primary keys.
In-line keys extract the primary key from an internal property (keyPath), while out-of-line keys are passed as explicit arguments.
autoIncrement: true instructs the browser engine to generate sequential numeric keys automatically.
Compound keys (keyPath: ['fieldA', 'fieldB']) enforce uniqueness across multiple properties.
Numbers, strings, Dates, ArrayBuffers, and Arrays of valid keys are legal key types; Booleans, objects, and null values are illegal.
--

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

? Question 1 / 3

What error is thrown if you pass an explicit key argument to `store.add(data, "key123")` on an ObjectStore configured with `{ keyPath: "id" }`?

Topic: HTML Fundamentals

? Question 2 / 3

Which of the following JavaScript values is a VALID primary key in IndexedDB?

Topic: HTML Fundamentals

? Question 3 / 3

How does setting `autoIncrement: true` behave when combined with `keyPath: "id"`?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Four Primary Keying Strategies

Valid vs Invalid Key Types

Compound (Composite) Primary Keys

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Multi-Tenant Schema Architect

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What error is thrown if you pass an explicit key argument to store.add(data, "key123") on an ObjectStore configured with { keyPath: "id" }?

Which of the following JavaScript values is a VALID primary key in IndexedDB?

How does setting autoIncrement: true behave when combined with keyPath: "id"?

What error is thrown if you pass an explicit key argument to `store.add(data, "key123")` on an ObjectStore configured with `{ keyPath: "id" }`?

How does setting `autoIncrement: true` behave when combined with `keyPath: "id"`?