Intermediate

// => Converts IDBRequest events into a Promise
function requestToPromise(request) {
  // => request is IDBRequest-like (has onsuccess/onerror)
  return new Promise((resolve, reject) => {
    request.onsuccess = () => resolve(request.result);
    // => Resolve with result once it's available
    request.onerror = () => reject(request.error);
    // => Reject with DOMException on failure
  });
}
 
// => Usage: wrap store.get in a promise
async function demo(db) {
  const tx = db.transaction("kv", "readonly");
  // => Get store handle
  const store = tx.objectStore("kv");
  // => Wrap the request — await returns the value directly
  const value = await requestToPromise(store.get("key1"));
  // => No nested callbacks; linear flow
  console.log("Got:", value);
  // => Output depends on stored data
}

// => Wrap request (per-operation)
const reqP = (r) =>
  // => r is any IDBRequest-like object with onsuccess/onerror
  new Promise((ok, err) => {
    r.onsuccess = () => ok(r.result);
    // => Resolve with the request's result value
    r.onerror = () => err(r.error);
    // => Reject with the DOMException on failure
  });
 
// => Wrap transaction completion (per-unit-of-work)
const txP = (tx) =>
  // => tx is IDBTransaction — resolves on commit, rejects on abort/error
  new Promise((ok, err) => {
    tx.oncomplete = () => ok();
    // => oncomplete fires after all requests commit
    tx.onerror = () => err(tx.error);
    // => Request error bubbles up to tx.error
    tx.onabort = () => err(tx.error || new Error("aborted"));
    // => Explicit aborts also count as failures
  });
 
// => Combined usage — clean async transaction
async function saveUser(db, user) {
  // => db is IDBDatabase; user is the object to persist
  const tx = db.transaction("users", "readwrite");
  // => Open readwrite transaction scoped to "users"
  const store = tx.objectStore("users");
  // => store is IDBObjectStore for "users" in this transaction
  // => Issue request and immediately await commit
  store.put(user);
  // => store.put returns IDBRequest; ignore it, let tx commit
  await txP(tx);
  // => Resolves once write is durable
  console.log("User saved");
  // => Output: User saved
}

async function fetchMany(db, ids) {
  // => db is IDBDatabase; ids is an array of primary keys to fetch
  // => Open readonly transaction once
  const tx = db.transaction("items", "readonly");
  // => One transaction for all reads — amortizes lock/setup overhead
  const store = tx.objectStore("items");
  // => store is IDBObjectStore for "items" in this transaction
 
  // => Fire all reads in parallel (browser executes them concurrently)
  const promises = ids.map((id) => reqP(store.get(id)));
  // => reqP (from previous example) wraps each IDBRequest
  // => All requests are issued synchronously before any await
 
  // => Wait for all to resolve in parallel
  const values = await Promise.all(promises);
  // => values is array aligned with ids input
  // => Each element is the record for that id (or undefined)
 
  await txP(tx);
  // => Tx auto-commits once all requests done
  return values;
  // => Caller receives all fetched records in one array
}
 
// => Usage
const items = await fetchMany(db, [1, 2, 3, 4, 5]);
// => Opens one transaction, fires 5 reads, awaits all
console.log("Fetched", items.length, "items");
// => Output: Fetched 5 items

npm install idb

// => Import the openDB helper
import { openDB } from "idb";
// => idb is a ~1 KB wrapper — no runtime dependencies beyond IndexedDB
 
// => Open database; upgrade callback receives IDBPDatabase (promise version)
const db = await openDB("tasks", 1, {
  // => upgrade runs inside a versionchange transaction (like onupgradeneeded)
  upgrade(db, oldVersion, newVersion, tx) {
    // => db is a promise-flavored wrapper around IDBDatabase
    // => oldVersion is the current stored version; newVersion is target
    db.createObjectStore("tasks", { keyPath: "id" });
    // => Synchronous API — no event handlers
    // => Store created; id property is the primary key
  },
});
// => db is IDBPDatabase (promise-wrapped IDBDatabase) ready for use
 
// => Direct read — no transaction ceremony for simple cases
const task = await db.get("tasks", 1);
// => idb creates an implicit readonly transaction
console.log(task);
// => Output: the task with id=1 (or undefined)
// => undefined if no record exists yet for id=1
 
// => Direct write — idb creates an implicit readwrite transaction
await db.put("tasks", { id: 1, title: "Buy bread", done: false });
// => Returns when the transaction commits
// => idb opens transaction, writes, commits — one await does all
 
// => For multi-step work, open an explicit transaction
const tx = db.transaction("tasks", "readwrite");
// => tx is IDBPTransaction — promise-wrapped IDBTransaction
await tx.store.put({ id: 2, title: "Study" });
// => tx.store is IDBPObjectStore for the first listed store
await tx.store.put({ id: 3, title: "Sleep" });
// => Both puts share the same transaction
await tx.done;
// => tx.done is a Promise that resolves on oncomplete
// => Awaiting tx.done guarantees both writes are durable
 
db.close();
// => Release the DB handle when done

import { openDB } from "idb";
// => Using idb for cleaner syntax; migration logic is the same as raw API
 
// => Current schema is at version 3
const db = await openDB("app", 3, {
  upgrade(db, oldVersion, newVersion, tx) {
    // => switch without break: fall through all versions from oldVersion+1
    // => oldVersion is stored version (0 = new install); newVersion is 3
    switch (oldVersion) {
      case 0: {
        // => Fresh install — create initial store
        const users = db.createObjectStore("users", { keyPath: "id" });
        // => users store created at v1; data persists through all upgrades
        // => (fall through to case 1)
      }
      // falls through
      case 1: {
        // => Add email index introduced in v2
        const users = tx.objectStore("users");
        // => During upgrade, use tx.objectStore (not db.transaction)
        // => tx is the versionchange transaction — already in progress
        users.createIndex("by_email", "email");
        // => Index added to existing store; prior records are auto-indexed
        // => (fall through to case 2)
      }
      // falls through
      case 2: {
        // => Add posts store introduced in v3
        db.createObjectStore("posts", { keyPath: "id" });
        // => No fall-through needed for last case
        // => v3 schema: users + by_email index + posts store
      }
    }
  },
});
// => Every user — fresh, v1, or v2 — ends up with the same v3 schema
db.close();
// => Close the connection when done

import { openDB } from "idb";
// => idb for cleaner async syntax; raw cursor API works identically
 
const db = await openDB("customers", 2, {
  upgrade(db, oldVersion, newVersion, tx) {
    // => oldVersion is the stored version; newVersion is 2
    if (oldVersion < 1) {
      // => Fresh install: create initial store
      db.createObjectStore("customers", { keyPath: "id" });
      // => "customers" store created with inline "id" key
    }
    if (oldVersion < 2) {
      // => v2 splits full_name into first_name and last_name
      const store = tx.objectStore("customers");
      // => Reuse the versionchange transaction — cannot open new ones during upgrade
      // => Open cursor inside the upgrade transaction
      const cursorReq = store.openCursor();
      // => Returns IDBRequest; addEventListener("success") or onsuccess both work
      cursorReq.addEventListener("success", (e) => {
        // => Fires per record during the migration
        const cursor = e.target.result;
        // => cursor is IDBCursorWithValue or null when done
        if (cursor) {
          const value = cursor.value;
          // => value is the current record object
          // => Parse legacy full_name field
          const parts = (value.full_name || "").split(" ");
          // => Split by first space: ["First", "Last..."]
          value.first_name = parts[0] || "";
          // => Preserve empty string if no name at all
          value.last_name = parts.slice(1).join(" ");
          // => Remainder after first word becomes last_name
          // => Drop the old field to save space
          delete value.full_name;
          // => full_name removed; replaced by first_name + last_name
          // => Write transformed value back at the same key
          cursor.update(value);
          // => Atomic in-place update within the versionchange tx
          cursor.continue();
          // => Advance to next record
        }
      });
    }
  },
});
// => After upgrade, every customer record has new fields
db.close();
// => Schema migration complete; connection closed

import { openDB } from "idb";
// => Using idb; same deleteObjectStore/deleteIndex methods as raw API
 
const db = await openDB("cleanup", 5, {
  upgrade(db, oldVersion) {
    // => oldVersion is the stored version; target is 5
    // => Pretend earlier versions created these
    if (oldVersion < 4) {
      // => Only delete if user is upgrading from before v4
      // => Legacy "temp_cache" store no longer needed at v5
      if (db.objectStoreNames.contains("temp_cache")) {
        // => Guard: check existence before deleting (idempotent)
        db.deleteObjectStore("temp_cache");
        // => Data is gone forever — deletion is irreversible
        // => All records and indexes in "temp_cache" are removed
      }
    }
    if (oldVersion < 5) {
      // => Only drop index when upgrading from before v5
      // => Drop an obsolete index without dropping the whole store
      const store = db.transaction.objectStore("orders");
      // => Access "orders" via the versionchange tx (not db.transaction)
      if (store.indexNames.contains("by_legacy_code")) {
        // => Guard: check existence before deleting (idempotent)
        store.deleteIndex("by_legacy_code");
        // => Records still present; only the index is removed
        // => Store data is unaffected; just the lookup structure is gone
      }
    }
  },
});
db.close();
// => All schema cleanup complete; connection closed

// => Global write queue (one per DB connection)
let writeQueue = Promise.resolve();
// => Start as a resolved promise — first write proceeds immediately
 
async function queuedWrite(fn) {
  // => Chain fn onto the queue; return its result
  const next = writeQueue.then(() => fn());
  // => Ignore fn's error in queue chain — subsequent writes still proceed
  // => next is a Promise that resolves when fn() completes
  writeQueue = next.catch(() => {});
  // => Update queue tail to the settled version of next
  // => catch swallows fn errors so the queue keeps draining
  return next;
  // => Caller awaits this to get fn's return value or error
}
 
// => Usage: two concurrent writes that would otherwise race
async function increment(db, key) {
  // => db is IDBDatabase; key is the counter name
  const tx = db.transaction("counters", "readwrite");
  // => Readwrite tx needed for read-modify-write
  const store = tx.objectStore("counters");
  // => store is IDBObjectStore for "counters"
  const current = (await reqP(store.get(key))) || { id: key, count: 0 };
  // => Fetch existing counter or start at 0 if not found
  current.count += 1;
  // => Increment the counter value in memory
  // => Read-modify-write cycle
  store.put(current);
  // => Write the incremented counter back
  await txP(tx);
  // => Wait for the transaction to commit before resolving
}
 
// => These two calls would race if not queued
await Promise.all([
  queuedWrite(() => increment(db, "hits")),
  // => First increment queued — runs immediately
  queuedWrite(() => increment(db, "hits")),
  // => Second increment queued — waits for first to finish
]);
// => Queue ensures they run sequentially; final count is 2 (not 1)
console.log("Done");
// => Output: Done

async function updateWithRetry(db, id, mutator) {
  // => db is IDBDatabase; id is record key; mutator transforms the record
  for (let attempt = 0; attempt < 5; attempt++) {
    // => Up to 5 retries on conflict; throw after exhausting
    // => Read current state and its version
    const txR = db.transaction("docs", "readonly");
    // => Readonly tx to read current state
    const current = await reqP(txR.objectStore("docs").get(id));
    // => current is the record with its current version number
    await txP(txR);
    // => Wait for readonly tx to complete before proceeding
 
    // => Build updated record with incremented version
    const updated = mutator(current);
    // => mutator is a user-supplied transform function
    updated.version = current.version + 1;
    // => Increment version to signal this record changed
 
    // => Attempt write, but only if version hasn't changed
    const txW = db.transaction("docs", "readwrite");
    // => Readwrite tx to check-and-write atomically
    const store = txW.objectStore("docs");
    // => store is IDBObjectStore for "docs" in the write tx
    const latest = await reqP(store.get(id));
    // => Re-read inside the write tx to detect concurrent changes
    if (latest.version !== current.version) {
      // => Another writer won — abort and retry
      txW.abort();
      // => Discard this attempt's transaction
      continue;
      // => Loop back and start fresh with a new read
    }
    // => Version still matches — our update is safe
    store.put(updated);
    // => Write the updated record with the new version
    await txP(txW);
    // => Wait for write tx to commit
    // => Success
    return updated;
    // => Return the committed update
  }
  throw new Error("Too many conflicts");
  // => Five consecutive conflicts indicate a pathological race
}
 
// => Usage
const result = await updateWithRetry(db, "doc1", (d) => ({
  ...d,
  // => Spread existing fields and override title
  title: "New",
}));
console.log("Saved v" + result.version);
// => Output: Saved v2 (or higher after retries)

// service-worker.js
// => Imports can't be top-level in classic service workers; use importScripts
importScripts("https://unpkg.com/idb@8/build/umd.js");
// => Loads idb as a UMD module; available as window.idb in SW scope
 
self.addEventListener("fetch", (event) => {
  // => Intercept every fetch request in this SW's scope
  event.respondWith(
    (async () => {
      // => Open DB from service worker scope
      const db = await idb.openDB("cache", 1, {
        upgrade(db) {
          // => Create response cache store keyed by URL
          db.createObjectStore("responses", { keyPath: "url" });
          // => url is both the key and the store's keyPath
        },
      });
      const url = event.request.url;
      // => Full URL of the intercepted request
 
      // => Try cache first
      const cached = await db.get("responses", url);
      // => Look up stored response by URL key
      if (cached) {
        // => Return stored Response body
        return new Response(cached.body, { headers: cached.headers });
        // => Reconstructed Response from stored body + headers
      }
 
      // => Network fallback
      const resp = await fetch(event.request);
      // => Forward to network when not in cache
      const body = await resp.clone().text();
      // => Clone before reading — original resp still usable for return
      // => Persist for next time
      await db.put("responses", {
        url,
        body,
        // => headers serialized as plain object (Headers is not cloneable)
        headers: Object.fromEntries(resp.headers),
      });
      return resp;
      // => Return the original network response to the page
    })(),
  );
});

// => Create named channel (shared across tabs for this origin)
const channel = new BroadcastChannel("db-updates");
// => All tabs/SWs with same name and origin share this channel
 
async function addTodo(db, todo) {
  // => db is IDBDatabase (idb-wrapped); todo is the new record
  // => Write to IndexedDB normally
  await db.put("todos", todo);
  // => Write is committed; now notify other tabs
  // => Notify all other tabs/service workers
  channel.postMessage({ type: "todo-added", id: todo.id });
  // => postMessage is fire-and-forget; no await needed
  // => Other tabs receive this message asynchronously
}
 
// => In another tab, listen for updates
channel.addEventListener("message", async (event) => {
  // => event.data is the object passed to postMessage
  if (event.data.type === "todo-added") {
    // => Re-read the fresh record from our own DB connection
    const fresh = await db.get("todos", event.data.id);
    // => Reading from our own DB handle — reflects the committed write
    // => Update local UI state
    render(fresh);
    // => render() refreshes the UI with the new todo
  }
});

import { openDB } from "idb";
// => Using idb for cleaner async syntax
 
const db = await openDB("media", 1, {
  upgrade(db) {
    // => Schema: "files" store keyed by filename
    db.createObjectStore("files", { keyPath: "name" });
    // => name is the primary key — filename string
  },
});
// => db is IDBPDatabase ready for Blob storage
 
// => Fetch an image as Blob
const resp = await fetch("/logo.png");
// => HTTP GET to fetch the image
const blob = await resp.blob();
// => blob is Blob with type "image/png"
// => Blob is a binary container — no text encoding needed
 
// => Store Blob directly — no serialization
await db.put("files", {
  name: "logo.png",
  blob,
  // => Blob stored natively via structured clone
  size: blob.size,
  // => size in bytes for metadata queries
});
// => Browser writes binary data efficiently
 
// => Read back — still a Blob
const record = await db.get("files", "logo.png");
// => Retrieve the stored file record by name key
console.log(record.blob instanceof Blob);
// => Output: true
// => Blob survived round-trip — no base64 decoding needed
 
// => Create an object URL to display the image
const url = URL.createObjectURL(record.blob);
// => url is a blob: URL usable in <img src>
document.querySelector("img#logo").src = url;
// => Image displayed directly from IndexedDB without network
// => Remember to URL.revokeObjectURL(url) when done
db.close();
// => Close the DB handle when done

import { openDB } from "idb";
// => Using idb for concise async API
 
const db = await openDB("uploads", 1, {
  upgrade(db) {
    // => Schema: pending uploads store with auto-generated ids
    db.createObjectStore("pending", { keyPath: "id", autoIncrement: true });
    // => autoIncrement generates sequential ids; keyPath writes id into the record
  },
});
// => db is IDBPDatabase ready for file queuing
 
// => On user file selection, persist immediately
async function queueUpload(file) {
  // => file is a File object from <input type="file"> or drag-and-drop
  // => Store File object (which extends Blob) with metadata
  const id = await db.add("pending", {
    file,
    // => File object stored natively — no base64 encoding
    name: file.name,
    // => Original filename for FormData reconstruction
    type: file.type,
    // => MIME type for Content-Type header
    size: file.size,
    // => Size in bytes for progress tracking
    createdAt: Date.now(),
    // => Timestamp for retry ordering
  });
  console.log("Queued upload id", id);
  // => id is the auto-generated integer key
  // => Even if user closes tab now, file is safely stored
  return id;
  // => Return id so caller can track this upload
}
 
// => Flush queue when online
async function flush() {
  const pending = await db.getAll("pending");
  // => Load all pending uploads from the queue
  for (const record of pending) {
    // => Process uploads in insertion order
    try {
      const fd = new FormData();
      // => FormData for multipart file upload
      fd.append("file", record.file, record.name);
      // => Attach the stored File with its original name
      // => Send to server
      await fetch("/api/upload", { method: "POST", body: fd });
      // => Upload succeeded; remove from queue
      // => Remove from queue on success
      await db.delete("pending", record.id);
      // => Deletion by auto-generated id key
    } catch (err) {
      console.warn("Retry later:", err);
      // => Keep in queue — will retry next flush
      // => Break or continue — depends on whether ordering matters
    }
  }
}
 
window.addEventListener("online", flush);
// => Automatically flush when connectivity returns
// => Also call flush() on app boot to handle restarts mid-upload

import { openDB } from "idb";
// => Using idb for async cursor API
 
async function getPage(db, startAfterKey, pageSize) {
  // => db is IDBPDatabase; startAfterKey is null for first page
  const tx = db.transaction("messages", "readonly");
  // => Readonly tx — pagination never writes
  const store = tx.objectStore("messages");
  // => store is IDBPObjectStore for "messages"
 
  // => Build range starting AFTER the last key we saw
  const range = startAfterKey ? IDBKeyRange.lowerBound(startAfterKey, true) : null;
  // => true makes the lower bound exclusive — don't re-include last key
  // => null range = start from the beginning (first page)
 
  const results = [];
  // => Accumulate up to pageSize records
  let cursor = await store.openCursor(range);
  // => idb returns null when done, or the cursor on match
  while (cursor && results.length < pageSize) {
    // => Collect up to pageSize records
    results.push(cursor.value);
    // => Each cursor.value is a full message record
    cursor = await cursor.continue();
    // => continue() returns a promise for the next cursor step (idb-specific)
    // => Returns null when range is exhausted
  }
  await tx.done;
  // => Wait for transaction to complete
 
  // => Return page + cursor for the next call
  return {
    items: results,
    // => items is the array of records for this page
    nextKey: results.length === pageSize ? results[results.length - 1].id : null,
    // => Null nextKey means no more data
    // => Non-null nextKey is the id to pass as startAfterKey next time
  };
}
 
// => Usage
let page = await getPage(db, null, 20);
// => First page, no startAfterKey
console.log("Page 1:", page.items.length);
// => Output: Page 1: 20 (or fewer if store has <20 records)
if (page.nextKey) {
  page = await getPage(db, page.nextKey, 20);
  // => Next page starting after the last id we saw
  console.log("Page 2:", page.items.length);
  // => Output: Page 2: up to 20 records
}

async function renderStream(db, container) {
  // => db is IDBPDatabase; container is a DOM element to append rows to
  container.textContent = "";
  // => Clear previous content before streaming new results
  // => Start cursor iteration
  const tx = db.transaction("messages", "readonly");
  // => Readonly tx for streaming — cursor never writes
  let cursor = await tx.objectStore("messages").openCursor();
  // => cursor is IDBPCursorWithValue or null when done (idb-specific)
 
  while (cursor) {
    // => Loop continues as long as cursor points to a record
    // => Append one row at a time as records arrive
    const row = document.createElement("div");
    // => Create DOM element for this message
    row.textContent = cursor.value.text;
    // => Set text from the current record
    container.appendChild(row);
    // => Appended immediately — user sees row before next record loads
    // => Browser can paint between iterations — no layout stall
 
    // => Yield occasionally to allow rendering
    if (cursor.value.id % 50 === 0) {
      // => Every 50 records, yield control to the browser
      await new Promise((r) => requestAnimationFrame(r));
      // => Break up long synchronous iteration
      // => requestAnimationFrame fires just before the next repaint
    }
    cursor = await cursor.continue();
    // => Advance to next record; returns null at end of store
  }
  await tx.done;
  // => Transaction completes after all records are processed
  console.log("Streaming complete");
  // => Output: Streaming complete
}

// => Estimate returns { usage, quota } in bytes
const estimate = await navigator.storage.estimate();
// => usage: bytes currently used by this origin
// => quota: bytes available before QuotaExceededError
// => Both values are approximate — browsers may round or cap them
 
console.log(`Using ${(estimate.usage / 1_000_000).toFixed(1)} MB`);
// => Output: Using 3.2 MB (example)
// => Divide by 1_000_000 to convert bytes to megabytes
console.log(`Quota ${(estimate.quota / 1_000_000_000).toFixed(1)} GB`);
// => Output: Quota 12.5 GB (browser-dependent)
// => Chrome ~60% of free disk; Firefox ~10%; Safari ~1 GB
 
const ratio = estimate.usage / estimate.quota;
// => ratio is a decimal: 0.8 = 80% of quota used
if (ratio > 0.8) {
  // => Threshold at 80% — adjust based on your app's cleanup cost
  console.warn("Approaching quota — consider cleanup");
  // => Trigger cache eviction or prompt user
  // => At 0.85, begin eviction; at 0.95, prompt user
}

// => Request persistence — returns boolean indicating granted status
const granted = await navigator.storage.persist();
// => Some browsers prompt the user; others auto-grant based on engagement
// => Chrome auto-grants for installed PWAs and bookmarked origins
 
if (granted) {
  // => Storage is protected from automatic eviction
  console.log("Storage is persistent — immune to eviction");
  // => Output: Storage is persistent — immune to eviction
} else {
  // => Storage may be cleared when disk space is low
  console.log("Best-effort storage — may be cleared under pressure");
  // => Output: Best-effort storage — may be cleared under pressure
  // => Consider degraded-mode UI that warns users to backup data
}
 
// => Check status without requesting (no prompt)
const isPersisted = await navigator.storage.persisted();
// => Returns boolean without triggering any permission prompt
console.log("Currently persistent:", isPersisted);
// => Output: Currently persistent: true or false
// => Use this on boot to decide whether to show a "protect my data" button

async function safeWrite(db, store, record) {
  // => db is IDBPDatabase; store is the store name; record is the value
  try {
    await db.put(store, record);
    // => Happy path — write succeeded
    return { ok: true };
    // => Caller can check { ok: true } to know write completed
  } catch (err) {
    if (err.name === "QuotaExceededError") {
      // => Storage full — trigger cleanup
      console.warn("Quota hit; running cleanup");
      await evictOldRecords(db);
      // => Free up space before retrying
      // => Retry once after cleanup
      try {
        await db.put(store, record);
        // => Second attempt after eviction
        return { ok: true, cleaned: true };
        // => Caller knows eviction was needed
      } catch {
        // => Still failing — surface to user
        return { ok: false, reason: "storage-full" };
        // => User must manually free space or accept data loss
      }
    }
    throw err;
    // => Propagate other errors unchanged
    // => ConstraintError, NotReadableError, etc. bubble to caller
  }
}
 
async function evictOldRecords(db) {
  // => Example: delete entries older than 30 days
  const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
  // => 30 days in milliseconds; createdAt older than this is evictable
  const tx = db.transaction("cache", "readwrite");
  // => Readwrite tx required for cursor.delete()
  let cursor = await tx.objectStore("cache").openCursor();
  // => Iterate all cache entries to find stale ones
  while (cursor) {
    if (cursor.value.createdAt < cutoff) {
      // => Record is older than the 30-day threshold
      cursor.delete();
      // => Free space by removing stale cache entries
      // => Deletion is queued; committed when tx commits
    }
    cursor = await cursor.continue();
    // => Advance regardless of whether we deleted
  }
  await tx.done;
  // => Wait for all deletions to commit
}

async function exportDB(db) {
  // => db is IDBPDatabase; iterates all stores and serializes to JSON
  const backup = { version: db.version, stores: {} };
  // => Include DB version so import can recreate at the right version
 
  // => Iterate every store in the DB
  for (const storeName of db.objectStoreNames) {
    // => db.objectStoreNames is DOMStringList — iterable
    const tx = db.transaction(storeName, "readonly");
    // => One readonly tx per store — avoids holding a multi-store lock
    // => Read all records at once (caveat: memory)
    backup.stores[storeName] = await tx.objectStore(storeName).getAll();
    // => getAll() returns all records as an array
    await tx.done;
    // => Wait for this store's tx to complete before moving to next
  }
 
  // => Serialize to JSON string (loses Blobs, Dates, Sets — see Example 48)
  return JSON.stringify(backup);
  // => Returns a string; caller decides whether to download or upload
}
 
// => Usage: download as file
const json = await exportDB(db);
// => json is the full database serialized as a JSON string
const blob = new Blob([json], { type: "application/json" });
// => Wrap in Blob for download
const a = document.createElement("a");
// => Create invisible anchor element to trigger download
a.href = URL.createObjectURL(blob);
// => Create a blob: URL for the JSON data
a.download = "backup.json";
// => Set the filename that the browser will use
a.click();
// => User gets a backup.json download
// => Call URL.revokeObjectURL(a.href) after the click to free memory

async function importDB(db, jsonText) {
  // => db is IDBPDatabase; jsonText is the JSON backup string
  const backup = JSON.parse(jsonText);
  // => backup is { version, stores: { storeName: [...records] } }
 
  for (const [storeName, records] of Object.entries(backup.stores)) {
    // => Iterate each store in the backup
    const tx = db.transaction(storeName, "readwrite");
    // => Readwrite tx — we'll clear and repopulate
    const store = tx.objectStore(storeName);
    // => store is IDBPObjectStore for this tx
    // => Clear existing data before importing
    await store.clear();
    // => Reset store to empty before importing — prevents duplicate key errors
 
    for (const record of records) {
      // => Iterate each record from the backup array
      // => Reconstruct known Date fields by convention
      if (record.createdAt) record.createdAt = new Date(record.createdAt);
      // => JSON.parse gives strings like "2026-01-01T00:00:00.000Z"; convert to Date
      if (record.updatedAt) record.updatedAt = new Date(record.updatedAt);
      // => Same pattern for any date field
      // => Reconstruct Sets stored as arrays
      if (Array.isArray(record.tags_set)) {
        // => JSON serialized Set as array; restore it as Set
        record.tags_set = new Set(record.tags_set);
        // => Now a proper Set again — queries and iteration work correctly
      }
      await store.put(record);
      // => Write reconstructed record back to the store
    }
    await tx.done;
    // => Wait for this store's tx to commit before next store
  }
  console.log("Import complete");
  // => Output: Import complete
}

// => Code to set up visible data in DevTools
import { openDB } from "idb";
// => openDB is the idb wrapper — returns IDBPDatabase
const db = await openDB("devtools-demo", 1, {
  // => upgrade runs when version bumps (first open = version 0 → 1)
  upgrade(db) {
    // => db is IDBPDatabase inside upgrade; create the object store
    const store = db.createObjectStore("contacts", { keyPath: "id" });
    // => keyPath: "id" means records are keyed by their .id property
    // => Create indexes so DevTools shows index views too
    store.createIndex("by_name", "name");
    // => by_name index — DevTools will list it under the store
  },
});
 
// => Write some records — put replaces any existing entry with same key
await db.put("contacts", { id: 1, name: "Aisha", email: "a@x.com" });
// => Record 1 stored with id=1
await db.put("contacts", { id: 2, name: "Budi", email: "b@x.com" });
// => Record 2 stored with id=2
 
// => Open DevTools > Application > IndexedDB > devtools-demo > contacts
// => You should see two records with all fields
// => Right-click to delete, or use the trash icon to clear the store
// => Firefox: Storage tab > Indexed DB (similar UI)
// => Edits you make in DevTools persist — useful for manual testing
 
console.log("Open DevTools to inspect");
// => Output: Open DevTools to inspect
// => After running this code, switch to the DevTools panel to explore
db.close();
// => Release connection so other tabs can open new versions
// => Closing also helps DevTools show the freshest state

import { openDB } from "idb";
// => Open (or create) the "products" database at version 1
const db = await openDB("products", 1, {
  upgrade(db) {
    // => Create "products" object store keyed by .id
    const store = db.createObjectStore("products", { keyPath: "id" });
    // => Index on "category" for fast category lookups
    store.createIndex("by_category", "category");
  },
});
// => Seed three products — two books, one pen
await db.put("products", { id: 1, category: "book", title: "Atlas" });
// => id=1, category="book"
await db.put("products", { id: 2, category: "book", title: "Meditations" });
// => id=2, category="book"
await db.put("products", { id: 3, category: "pen", title: "Rollerball" });
// => id=3, category="pen" — will be excluded from our query
 
// => openKeyCursor iterates keys without loading values
const tx = db.transaction("products", "readonly");
// => Readonly tx — no modifications needed
const index = tx.objectStore("products").index("by_category");
// => Use the by_category index to restrict scan to "book" entries
 
const ids = [];
// => IDBKeyRange.only("book") — only entries where category === "book"
let cursor = await index.openKeyCursor(IDBKeyRange.only("book"));
// => openKeyCursor returns keys only — no record values deserialized
while (cursor) {
  // => cursor.primaryKey is the store's primary key (id)
  // => cursor.key is the indexed value (category here — always "book")
  ids.push(cursor.primaryKey);
  // => Collect the primary key (id) without loading the full record
  cursor = await cursor.continue();
  // => Advance to next matching entry in the index
}
await tx.done;
// => Transaction committed automatically — all reads succeeded
 
console.log("Book IDs:", ids);
// => Output: Book IDs: [ 1, 2 ]
db.close();
// => Release connection handle

// => findFirstMatching returns the first record satisfying predicate
async function findFirstMatching(db, predicate) {
  // => Open readonly tx on "events" — no writes needed
  const tx = db.transaction("events", "readonly");
  // => openCursor with no args iterates in primary-key order
  let cursor = await tx.objectStore("events").openCursor();
 
  while (cursor) {
    // => Check if this record matches the caller's condition
    if (predicate(cursor.value)) {
      // => Found a match — stop without calling continue
      const match = cursor.value;
      // => Capture value before transaction commits or closes
      // => Transaction auto-commits once we leave the loop
      return match;
      // => Returning here exits the loop — no more records read
    }
    cursor = await cursor.continue();
    // => No match — advance to next record in key order
  }
  // => Exhausted all records without a match
  await tx.done;
  // => Explicitly await done only in the no-match path
  return null;
  // => Signal caller: no record found
}
 
// => Usage: find first event of a given type
const event = await findFirstMatching(db, (e) => e.type === "error");
// => predicate receives each cursor.value; stops at first match
console.log(event ? "Found" : "None");
// => Output: Found or None

import { openDB } from "idb";
// => Open/create "sales" DB at version 1
const db = await openDB("sales", 1, {
  upgrade(db) {
    // => Create "orders" store keyed by .id
    const store = db.createObjectStore("orders", { keyPath: "id" });
    // => Index on "date" string (ISO 8601 sorts lexicographically = chronologically)
    store.createIndex("by_date", "date");
  },
});
// => Seed ...
// => (populate with sample orders before querying)
 
// => "Find all high-value orders in Q1 2026"
async function query(db) {
  // => Readonly tx — we only read, never write
  const tx = db.transaction("orders", "readonly");
  // => Access the by_date index to use key ranges on date
  const index = tx.objectStore("orders").index("by_date");
 
  // => Range on indexed field (cheap, uses B-tree)
  // => IDBKeyRange.bound(lower, upper) — inclusive on both ends by default
  const range = IDBKeyRange.bound("2026-01-01", "2026-03-31");
  // => Only orders dated 2026-01-01 through 2026-03-31 will be visited
  const results = [];
  // => Accumulate matching records here
  let cursor = await index.openCursor(range);
  // => openCursor with range — only entries inside the range are visited
 
  while (cursor) {
    // => In-loop predicate on non-indexed field
    if (cursor.value.total > 1000) {
      // => Only add orders meeting both date AND value criteria
      results.push(cursor.value);
      // => cursor.value is the full order record
    }
    cursor = await cursor.continue();
    // => Advance to next order in date order
  }
  await tx.done;
  // => Transaction committed — all reads complete
  return results;
  // => Array of orders: date in Q1 2026 AND total > 1000
  // => Length varies based on how many orders pass both filters
}

npm install --save-dev fake-indexeddb

// test-setup.js (loaded by your test runner)
import "fake-indexeddb/auto";
// => Auto-installs global indexedDB and IDBKeyRange
// => fake-indexeddb replaces the browser global — no other config needed
 
// users.test.js
import { openDB } from "idb";
// => idb works transparently on top of fake-indexeddb
import { describe, test, expect } from "vitest";
// => Vitest runs in Node — no browser context available
 
describe("user repository", () => {
  test("stores and retrieves a user", async () => {
    // => Each test can use a unique DB name for isolation
    // => Math.random ensures no two tests share the same in-memory DB
    const db = await openDB("users-test-" + Math.random(), 1, {
      upgrade(db) {
        // => Create "users" store keyed by .id
        db.createObjectStore("users", { keyPath: "id" });
      },
    });
 
    await db.put("users", { id: 1, name: "Aisha" });
    // => Write record — stored in fake-indexeddb's in-memory map
    const user = await db.get("users", 1);
    // => Read back the same record by primary key
 
    expect(user.name).toBe("Aisha");
    // => Assertion runs in-memory — no browser needed
    // => Behavior matches Chrome/Firefox IndexedDB spec closely
    db.close();
    // => Release the in-memory DB handle
  });
});

import { openDB, deleteDB } from "idb";
// => deleteDB removes an existing database completely — clean slate
 
// => Factory creates a fresh DB per test
async function createTestDB(name, fixtures = {}) {
  // => Ensure any previous copy is gone — prevents state leakage between tests
  await deleteDB(name);
  // => deleteDB is a no-op if the DB doesn't exist yet — safe to call always
 
  const db = await openDB(name, 1, {
    upgrade(db) {
      // => Define schema fresh each time — mirrors production schema
      const users = db.createObjectStore("users", { keyPath: "id" });
      // => keyPath: "id" — records keyed by their .id property
      users.createIndex("by_email", "email");
      // => by_email index enables email-based lookups in tests
      db.createObjectStore("posts", { keyPath: "id" });
      // => posts store — separate from users store
    },
  });
 
  // => Seed any fixtures provided by the caller
  for (const [storeName, records] of Object.entries(fixtures)) {
    // => Iterate each store name and its array of records
    const tx = db.transaction(storeName, "readwrite");
    // => Readwrite tx for this store only
    for (const r of records) await tx.store.put(r);
    // => Write each fixture record — put handles both insert and update
    await tx.done;
    // => Commit this store's seed data before moving to next store
  }
 
  return db;
  // => Caller gets a populated IDBPDatabase ready for assertions
  // => db is open — caller must close it after the test
}
 
// => Usage in a test
const db = await createTestDB("test-1", {
  users: [{ id: 1, email: "a@x.com" }],
  // => One user seeded with known email
  posts: [{ id: 1, authorId: 1, title: "Hello" }],
  // => One post seeded with known authorId and title
});
// => DB now has a known, predictable state
// => Test can assert against id=1 user and post without guessing

// => bench wraps any async operation with performance.now timing
async function bench(label, fn) {
  // => Record start time with sub-millisecond precision
  const start = performance.now();
  await fn();
  // => fn() is the operation under test — awaited to completion
  // => Difference in ms (with sub-millisecond precision)
  const ms = performance.now() - start;
  // => ms = elapsed wall-clock time for the awaited operation
  console.log(`${label}: ${ms.toFixed(2)} ms`);
  // => Print two decimal places — e.g., "getAll: 83.40 ms"
}
 
// => Seed 10k records for benchmarking
const seedTx = db.transaction("items", "readwrite");
// => Readwrite tx — needed to insert records
for (let i = 0; i < 10_000; i++) {
  // => Queue all 10k puts without awaiting — IDB batches them
  seedTx.store.put({ id: i, name: "item " + i });
  // => Each put is a request; not awaited here so they pipeline
}
await seedTx.done;
// => All 10k records committed atomically
 
// => Benchmark three common patterns
await bench("getAll", async () => {
  await db.getAll("items");
  // => Loads ALL 10k records into a single JS array
});
// => Output: getAll: ~80 ms (example)
// => Fast because one request returns all records in one round-trip
 
await bench("cursor", async () => {
  const tx = db.transaction("items", "readonly");
  // => Readonly tx — we only read
  let cursor = await tx.store.openCursor();
  // => openCursor positions at first record
  while (cursor) cursor = await cursor.continue();
  // => Each continue() is a separate IDB round-trip — 10k round-trips
  await tx.done;
  // => Transaction committed after all records visited
});
// => Output: cursor: ~120 ms (example — one round-trip per record)
// => Slower because each record = one IDB event cycle
 
await bench("getAllKeys", async () => {
  await db.getAllKeys("items");
  // => Returns only primary keys — no value deserialization
});
// => Output: getAllKeys: ~30 ms (no value deserialization)
// => Fastest pattern when you only need to know which keys exist