IndexedDB Basics

// ❌ Problem 1: Blocking the main thread
// Storing 200KB of data blocks for ~5ms
const bigData = JSON.stringify(generateLargeDataset()); // ~5ms
localStorage.setItem("cache", bigData);                  // ~3ms
// Total: ~8ms of main thread blocked. At 60fps, that's half a frame.

// ❌ Problem 2: Size limit
try {
  localStorage.setItem("huge", "x".repeat(10_000_000)); // 10MB
} catch (e) {
  console.error(e); // QuotaExceededError!
}

// ❌ Problem 3: No querying
// "Find all products where price < 50"
const allProducts = JSON.parse(localStorage.getItem("products"));
const cheap = allProducts.filter(p => p.price < 50);
// Had to load and parse ALL products just to filter.
// With 10,000 products, this is slow and wasteful.

// ❌ Problem 4: No binary data
// Can't store images, audio, or files without base64 encoding
// (which increases size by ~33%)

┌──────────────────────────────────────────────────┐
│                   IndexedDB                      │
│                                                  │
│  ┌─────────────────────────────────────────┐     │
│  │          Database: "MyApp"              │     │
│  │          (version: 3)                   │     │
│  │                                         │     │
│  │  ┌──────────────────────────────────┐   │     │
│  │  │  Object Store: "products"        │   │     │
│  │  │  keyPath: "id"                   │   │     │
│  │  │                                  │   │     │
│  │  │  { id: 1, name: "Shoes",         │   │     │
│  │  │    price: 99, category: "foot" } │   │     │
│  │  │  { id: 2, name: "Shirt",         │   │     │
│  │  │    price: 45, category: "top" }  │   │     │
│  │  │                                  │   │     │
│  │  │  Indexes:                        │   │     │
│  │  │    "by-category" → category      │   │     │
│  │  │    "by-price"    → price         │   │     │
│  │  └──────────────────────────────────┘   │     │
│  │                                         │     │
│  │  ┌──────────────────────────────────┐   │     │
│  │  │  Object Store: "users"           │   │     │
│  │  │  keyPath: "email"                │   │     │
│  │  └──────────────────────────────────┘   │     │
│  │                                         │     │
│  └─────────────────────────────────────────┘     │
│                                                  │
│  Features:                                       │
│  • Async API (non-blocking)                      │
│  • Stores JS objects natively                    │
│  • Supports blobs, files, ArrayBuffers           │
│  • Indexes for fast queries                      │
│  • Transactions for data integrity               │
│  • 50MB+ storage (browser-dependent)             │
│  • Origin-scoped (same-origin policy)            │
└──────────────────────────────────────────────────┘

// Option 1: In-line key (keyPath)
// The key is a property of the stored object
const store = db.createObjectStore("products", { keyPath: "id" });
store.add({ id: 1, name: "Shoes", price: 99 });
// Key is object.id → 1

// Option 2: Out-of-line key
// The key is provided separately, not part of the object
const store2 = db.createObjectStore("logs", { autoIncrement: true });
store2.add({ message: "User logged in", timestamp: Date.now() });
// Key is auto-generated: 1, 2, 3, ...

// Option 3: Key generator + keyPath
const store3 = db.createObjectStore("messages", {
  keyPath: "id",
  autoIncrement: true,
});
store3.add({ text: "Hello", sender: "Alice" });
// Object gets { id: 1, text: "Hello", sender: "Alice" }

indexedDB.open("MyApp", 1)
  │
  ├─ First time (or version upgrade)?
  │   └─ onupgradeneeded
  │       ├─ createObjectStore("products", { keyPath: "id" })
  │       ├─ createIndex("by-category", "category")
  │       └─ Schema is now defined
  │
  ├─ onsuccess → database is open
  │   │
  │   ├─ db.transaction(["products"], "readwrite")
  │   │   └─ store.add({ id: 1, name: "Shoes", price: 99 })
  │   │       ├─ onsuccess → record added
  │   │       └─ onerror → handle error
  │   │
  │   ├─ db.transaction(["products"], "readonly")
  │   │   └─ store.get(1)
  │   │       └─ onsuccess → { id: 1, name: "Shoes", price: 99 }
  │   │
  │   └─ db.transaction(["products"], "readonly")
  │       └─ store.index("by-category").getAll("footwear")
  │           └─ onsuccess → [all footwear products]
  │
  └─ onerror → database failed to open

const request = indexedDB.open("ShopDB", 1);

// Runs ONLY on first create or version upgrade
request.onupgradeneeded = (event) => {
  const db = event.target.result;

  // Create an object store with "id" as the primary key
  const store = db.createObjectStore("products", { keyPath: "id" });

  // Create indexes for fast lookups
  store.createIndex("by-category", "category", { unique: false });
  store.createIndex("by-price", "price", { unique: false });
};

request.onsuccess = (event) => {
  const db = event.target.result;
  console.log("Database opened:", db.name, "v" + db.version);
  // Now you can start transactions
};

request.onerror = (event) => {
  console.error("Failed to open DB:", event.target.error);
};

// Assuming 'db' is the opened database from above

// ─── CREATE (add) ───────────────────────────────
function addProduct(db, product) {
  const tx = db.transaction("products", "readwrite");
  const store = tx.objectStore("products");
  const req = store.add(product); // Fails if key already exists

  req.onsuccess = () => console.log("Added:", product.id);
  req.onerror = () => console.error("Add failed:", req.error);
}

addProduct(db, { id: 1, name: "Shoes", price: 99, category: "footwear" });

// ─── READ (get) ─────────────────────────────────
function getProduct(db, id) {
  const tx = db.transaction("products", "readonly");
  const store = tx.objectStore("products");
  const req = store.get(id);

  req.onsuccess = () => console.log("Found:", req.result);
  // req.result → { id: 1, name: "Shoes", price: 99, category: "footwear" }
}

// ─── UPDATE (put) ───────────────────────────────
function updateProduct(db, product) {
  const tx = db.transaction("products", "readwrite");
  const store = tx.objectStore("products");
  store.put(product); // Creates or replaces by key
}

updateProduct(db, { id: 1, name: "Shoes", price: 79, category: "footwear" });

// ─── DELETE ─────────────────────────────────────
function deleteProduct(db, id) {
  const tx = db.transaction("products", "readwrite");
  const store = tx.objectStore("products");
  store.delete(id);
}

// ─── GET ALL ────────────────────────────────────
function getAllProducts(db) {
  const tx = db.transaction("products", "readonly");
  const store = tx.objectStore("products");
  const req = store.getAll();

  req.onsuccess = () => console.log("All products:", req.result);
}

// Find all products in the "footwear" category
function getByCategory(db, category) {
  const tx = db.transaction("products", "readonly");
  const store = tx.objectStore("products");
  const index = store.index("by-category");
  const req = index.getAll(category);

  req.onsuccess = () => {
    console.log("Footwear:", req.result);
    // [{ id: 1, name: "Shoes", ... }, { id: 3, name: "Boots", ... }]
  };
}

// Find products in a price range using a cursor
function getByPriceRange(db, min, max) {
  const tx = db.transaction("products", "readonly");
  const index = tx.objectStore("products").index("by-price");
  const range = IDBKeyRange.bound(min, max);
  const results = [];

  index.openCursor(range).onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      results.push(cursor.value);
      cursor.continue(); // Move to next record
    } else {
      console.log("Products $" + min + "-$" + max + ":", results);
    }
  };
}

Use LocalStorage when:
  ✅ Data is small (< 50KB total)
  ✅ Simple key-value pairs (theme, language, flags)
  ✅ You want the simplest possible API
  ✅ No querying needed — just get/set by key
  ✅ Cross-tab sync is useful (storage event)

Use IndexedDB when:
  ✅ Data is large (100KB – hundreds of MB)
  ✅ Structured data with relationships
  ✅ You need to query by properties (not just key)
  ✅ Binary data (images, files, audio)
  ✅ Offline-first / PWA requirements
  ✅ Performance matters (async, non-blocking)
  ✅ You need transactions for data integrity

// Pattern: serve from IndexedDB instantly, update in background

async function fetchWithCache(url) {
  const db = await openDB("ApiCache", 1);

  // 1. Check IndexedDB cache
  const cached = await db.get("responses", url);

  if (cached && Date.now() - cached.timestamp < 60_000) {
    // Fresh cache (< 1 min) — return immediately
    return cached.data;
  }

  if (cached) {
    // Stale cache — return it immediately, refresh in background
    refreshInBackground(db, url);
    return cached.data;
  }

  // No cache — fetch from network
  const data = await fetch(url).then(r => r.json());
  await db.put("responses", { url, data, timestamp: Date.now() });
  return data;
}

async function refreshInBackground(db, url) {
  try {
    const data = await fetch(url).then(r => r.json());
    await db.put("responses", { url, data, timestamp: Date.now() });
  } catch (e) {
    // Network failed — stale cache is still better than nothing
  }
}

// ❌ WRONG: async operation inside a transaction
const tx = db.transaction("products", "readwrite");
const store = tx.objectStore("products");

const response = await fetch("/api/products"); // ← Transaction dies here!
const products = await response.json();

// This fails — the transaction already auto-committed
// while we were waiting for fetch()
store.add(products[0]); // TransactionInactiveError!

// ✅ CORRECT: fetch first, then use transaction
const response = await fetch("/api/products");
const products = await response.json();

const tx = db.transaction("products", "readwrite");
const store = tx.objectStore("products");
for (const product of products) {
  store.put(product); // All sync operations — transaction stays alive
}

import { openDB } from "idb";

// Open database (Promise-based, clean syntax)
const db = await openDB("ShopDB", 1, {
  upgrade(db) {
    const store = db.createObjectStore("products", { keyPath: "id" });
    store.createIndex("by-category", "category");
  },
});

// Add a product
await db.add("products", { id: 1, name: "Shoes", price: 99, category: "footwear" });

// Get by key
const product = await db.get("products", 1);

// Get all
const all = await db.getAll("products");

// Query by index
const footwear = await db.getAllFromIndex("products", "by-category", "footwear");

// Update
await db.put("products", { id: 1, name: "Shoes", price: 79, category: "footwear" });

// Delete
await db.delete("products", 1);

// Compare: 5 lines with idb vs 15+ lines with raw API
// Same IndexedDB underneath — just a cleaner interface