Browser Storage APIs: localStorage, IndexedDB, and Beyond

A deep dive into browser-side persistence, examining the design trade-offs behind each storage API, their quota models, transaction semantics, and eviction behavior. The WHATWG Storage Standard (Living Standard) unifies quota management under a single bucket model, while individual APIs—Web Storage (localStorage/sessionStorage), IndexedDB (W3C, version 3.0), and the Cache API (W3C)—each optimize for different access patterns. Choosing the right API depends on data shape, access frequency, thread requirements, and durability guarantees—not just capacity limits.

Abstract

Browser storage is not one system—it’s five APIs with different serialization models, threading guarantees, and eviction behaviors, all sharing a per-origin quota.

Core mental model:

• localStorage/sessionStorage store DOMString key-value pairs synchronously on the main thread—fast for small reads, dangerous for large data. localStorage persists across sessions; sessionStorage dies with the tab
• IndexedDB is an asynchronous, transactional object store using the structured clone algorithm—handles complex objects and binary data at scale, but its transaction model has subtle lifetime rules that break naively async code
• Cache API stores Request → Response pairs and is optimized for service worker integration (covered in depth in the Service Workers and Cache API article)
• Origin Private File System (OPFS) provides raw file system access with synchronous I/O in workers—the fastest storage option for compute-heavy workloads
• Quota is per-origin and varies dramatically by browser (Chrome: ~60% of disk, Firefox: up to 2 GiB per group, Safari: 1 GiB with 7-day eviction). All script-writable storage shares this budget

The Storage Landscape

Choosing the Right API

Design insight: The split between synchronous and asynchronous APIs reflects a fundamental tension. Web Storage (localStorage/sessionStorage) was designed in 2009 for simple needs—synchronous access made the API trivial to use. But synchronous storage on the main thread doesn’t scale. IndexedDB (first spec 2011, current version 3.0) was designed as the scalable replacement, trading simplicity for async transactions, structured data, and indexing.

When Cookies Still Win

Storage APIs don’t replace cookies for all use cases:

• Authentication tokens: HttpOnly cookies can’t be read by JavaScript, preventing XSS (Cross-Site Scripting) token theft. localStorage tokens are always vulnerable
• Server-side access: Cookies are sent with every HTTP request; storage APIs are client-only
• Expiration control: Expires and Max-Age provide server-controlled TTL (Time to Live). Storage APIs have no built-in expiration
• Security attributes: Secure, SameSite, and HttpOnly have no storage API equivalents

Web Storage: localStorage and sessionStorage

The Web Storage specification (WHATWG HTML Standard) defines two Storage objects that share an identical interface but differ in lifetime and scope.

Interface and Serialization

Both APIs expose the same Storage interface:

1
// All values are coerced to DOMString
2
localStorage.setItem("count", "42") // Store
3
localStorage.getItem("count") // "42" (always a string)
4
localStorage.removeItem("count") // Delete single key
5
localStorage.clear() // Delete all keys for this origin
6
localStorage.key(0) // Get key name by index
7
localStorage.length // Number of stored pairs
8

9
// Property-style access also works (but setItem/getItem is preferred)
10
localStorage.username = "alice" // Same as setItem("username", "alice")
11
delete localStorage.username // Same as removeItem("username")

Serialization trap: Every value is coerced to a string via toString(). Objects become "[object Object]" unless explicitly serialized:

1
// ❌ Silent data loss
2
localStorage.setItem("user", { name: "Alice" })
3
localStorage.getItem("user") // "[object Object]"
4

5
// ✅ Explicit serialization
6
localStorage.setItem("user", JSON.stringify({ name: "Alice" }))
7
JSON.parse(localStorage.getItem("user")!) // { name: "Alice" }
8

9
// ⚠️ JSON.parse(null) returns null, but JSON.parse("undefined") throws
10
const value = localStorage.getItem("missing") // null
11
JSON.parse(value) // null (safe)

localStorage vs sessionStorage

Design reasoning: sessionStorage exists because localStorage’s cross-tab sharing creates problems for multi-step workflows. A shopping cart checkout in two tabs would share state via localStorage, causing race conditions. sessionStorage provides tab-isolated state. The WHATWG spec notes sessionStorage is “intended to allow separate instances of the same web application to run in different windows without interfering with each other.”

The Synchronous Problem

Web Storage is synchronous and blocks the main thread. Every getItem/setItem call performs I/O on the UI thread:

1
// ⚠️ Blocks UI during operation
2
// For small data (< 100 keys, simple values), this is imperceptible
3
localStorage.setItem("pref", "dark")
4

5
// ❌ Blocking with large data causes jank
6
// 5 MiB of JSON parsing on the main thread
7
const bigData = JSON.parse(localStorage.getItem("cache")!)
8
// User cannot scroll, click, or interact during this operation

Why synchronous? The spec was written in 2009 when storage needs were simpler and the main thread was less contended. The synchronous API is also why the spec recommends a conservative 5 MiB limit—larger quotas would make blocking worse. The spec literally warns: “User agents should limit the total amount of space allowed for storage areas.”

Storage Events: Cross-Tab Communication

When localStorage changes, the browser fires a storage event on every other same-origin window—never on the originating tab:

1
// Tab A: writes data
2
localStorage.setItem("theme", "dark")
3
// No storage event fires in Tab A
4

5
// Tab B: receives the change
6
window.addEventListener("storage", (event) => {
7
  // event.key        - "theme"
8
  // event.oldValue   - "light" (previous value, or null)
9
  // event.newValue   - "dark" (new value, or null if removed)
10
  // event.url        - URL of the tab that made the change
11
  // event.storageArea - reference to localStorage or sessionStorage
12

13
  if (event.key === "theme") {
14
    applyTheme(event.newValue)
15
  }
16
})
7 collapsed lines
17

18
// Cross-tab messaging pattern: broadcast via localStorage
19
function broadcast(channel: string, data: unknown) {
20
  localStorage.setItem(`__msg_${channel}`, JSON.stringify({ data, timestamp: Date.now() }))
21
  // Clean up to avoid filling storage
22
  localStorage.removeItem(`__msg_${channel}`)
23
}

Edge case: The storage event fires even when newValue === oldValue—setting a key to its current value still triggers events on other tabs. The event fires after the storage area changes, so by the time a listener runs, localStorage.getItem(event.key) may already reflect a subsequent change.

BroadcastChannel alternative: For cross-tab messaging without touching storage, use BroadcastChannel. It doesn’t persist data and avoids I/O overhead. localStorage storage events are a legacy workaround from before BroadcastChannel existed.

Edge Cases and Failure Modes

QuotaExceededError: Thrown when setItem() exceeds the ~5 MiB limit. The spec says: “If it couldn’t set the new value, the method must throw a ‘QuotaExceededError’ DOMException.”

1
try {
2
  localStorage.setItem("key", largeValue)
3
} catch (e) {
4
  if (e instanceof DOMException && e.name === "QuotaExceededError") {
5
    // Storage full—evict old entries or warn user
6
  }
7
}

Private browsing: In all modern browsers, localStorage works in private/incognito mode but data is ephemeral—deleted when the private window closes. Safari previously threw QuotaExceededError on any setItem in private mode (fixed in Safari 11+).

Disabled storage: Users can disable web storage entirely. Feature detection is required:

1
function isStorageAvailable(): boolean {
2
  try {
3
    const test = "__storage_test__"
4
    localStorage.setItem(test, test)
5
    localStorage.removeItem(test)
6
    return true
7
  } catch {
8
    return false
9
  }
10
}

5 MiB is in UTF-16 code units: The storage limit is typically measured in UTF-16 code units (2 bytes each), so 5 MiB allows ~2.5 million characters. Non-BMP characters consume two code units each.

IndexedDB: Transactional Object Store

IndexedDB (W3C, version 3.0) is an asynchronous, transactional, indexed object store designed for structured data at scale. It uses the structured clone algorithm for serialization, supports multi-column indexes, and provides ACID-like (Atomicity, Consistency, Isolation, Durability) transactions within a single origin.

Data Model

• Database: Named container with a version number. Multiple databases per origin are allowed
• Object store: Named collection of records (analogous to a table). Records are key-value pairs where values are structured-cloneable objects
• Index: Secondary key path into an object store, enabling efficient queries on non-primary-key fields
• Key: Every record has a key—either an explicit keyPath property, an out-of-line key, or an auto-incrementing key generator

Valid key types (from the spec, in sort order): numbers (except NaN), Date objects (except invalid), strings, ArrayBuffer/typed arrays, and arrays (which sort element-by-element, enabling compound keys).

Database Versioning and Schema Upgrades

IndexedDB uses an integer version scheme. Schema changes (creating/deleting object stores and indexes) can only happen inside an upgradeneeded event:

3 collapsed lines
1
// Helper for promisifying (collapsed)
2
function openDB(name: string, version: number): Promise<IDBDatabase> {
3
  return new Promise((resolve, reject) => {
4
    const request = indexedDB.open("myapp", 3)
5

6
    request.onupgradeneeded = (event) => {
7
      const db = request.result
8
      const oldVersion = event.oldVersion
9

10
      // Incremental migrations based on old version
11
      if (oldVersion < 1) {
12
        const users = db.createObjectStore("users", { keyPath: "id" })
13
        users.createIndex("by-email", "email", { unique: true })
14
      }
15
      if (oldVersion < 2) {
16
        const orders = db.createObjectStore("orders", {
17
          keyPath: "id",
18
          autoIncrement: true,
19
        })
20
        orders.createIndex("by-date", "createdAt")
21
      }
22
      if (oldVersion < 3) {
23
        // Add index to existing store
24
        const users = request.transaction!.objectStore("users")
25
        users.createIndex("by-role", "role")
26
      }
27
    }
28

5 collapsed lines
29
    // Resolve/reject handlers (collapsed)
30
    request.onsuccess = () => resolve(request.result)
31
    request.onerror = () => reject(request.error)
32
  })
33
}

Design reasoning: The version-based upgrade mechanism exists because IndexedDB is a client-side database—you can’t run migrations on all clients simultaneously like a server DB. Each client may be at any historical version. The upgradeneeded event fires with oldVersion so you can apply incremental migrations. The versionchange transaction has exclusive access to the database, preventing concurrent schema modifications.

The blocked / versionchange Problem

Version upgrades require exclusive database access. If other tabs have open connections, the upgrade can’t proceed:

1
// Tab A: has an open connection
2
const db = await openDB("myapp", 2)
3

4
// Tab B: tries to upgrade to version 3
5
const request = indexedDB.open("myapp", 3)
6

7
// Step 1: Tab A receives versionchange event
8
db.onversionchange = () => {
9
  db.close() // Must close to unblock Tab B
10
  // Optionally: alert user to reload
11
}
12

13
// Step 2: If Tab A doesn't close, Tab B receives blocked event
14
request.onblocked = () => {
15
  // Upgrade can't proceed until Tab A closes its connection
16
  console.warn("Database upgrade blocked by another tab")
17
}

This is a common production bug: If you don’t handle onversionchange, your app silently blocks other tabs from upgrading. Always close the database on versionchange.

Transactions

IndexedDB provides three transaction modes:

3 collapsed lines
1
// Assume db is already opened (collapsed)
2
const db = await openDB("myapp", 1)
3

4
const tx = db.transaction(["users", "orders"], "readwrite")
5
const users = tx.objectStore("users")
6
const orders = tx.objectStore("orders")
7

8
// All operations within this transaction are atomic
9
await wrapRequest(users.put({ id: "u1", name: "Alice", role: "admin" }))
10
await wrapRequest(orders.add({ userId: "u1", item: "Widget", createdAt: new Date() }))
11

12
tx.oncomplete = () => console.log("Transaction committed")
13
tx.onerror = () => console.error("Transaction failed:", tx.error)
14
tx.onabort = () => console.warn("Transaction aborted")

Transaction Lifetime: The Critical Gotcha

Transactions auto-commit when the event loop returns to its idle state after all pending requests are resolved. This means inserting any async operation that yields to the event loop (like fetch, setTimeout, or await-ing a non-IDB promise) will cause the transaction to become inactive:

1
const tx = db.transaction("users", "readwrite")
2
const store = tx.objectStore("users")
3

4
// ✅ Works: back-to-back IDB operations keep transaction active
5
store.put({ id: "1", name: "Alice" })
6
store.put({ id: "2", name: "Bob" })
7

8
// ❌ Breaks: fetch yields to the event loop, transaction becomes inactive
9
store.put({ id: "1", name: "Alice" })
10
const data = await fetch("/api/user/2") // Transaction dies here
11
store.put(await data.json()) // TransactionInactiveError

The spec says: A transaction is active when it’s first created, becomes inactive when “control returns to the event loop”, and reactivates when a success/error event fires for one of its requests. Once all requests complete and control returns to the event loop with no pending requests, the transaction auto-commits.

Fix: Gather all data before starting the transaction, or use separate transactions:

1
// ✅ Fetch first, then transact
2
const data = await fetch("/api/users").then((r) => r.json())
3

4
const tx = db.transaction("users", "readwrite")
5
const store = tx.objectStore("users")
6
for (const user of data) {
7
  store.put(user)
8
}

Durability Hints

IndexedDB 3.0 introduced durability hints via the durability option on transactions:

1
// "relaxed" (default in Chrome 121+, Firefox 40+, Safari): OS may buffer writes
2
const tx = db.transaction("users", "readwrite", { durability: "relaxed" })
3

4
// "strict": flush to persistent storage before reporting complete
5
const tx2 = db.transaction("users", "readwrite", { durability: "strict" })

Performance impact: Relaxed durability provides 3–30x throughput improvement by deferring OS buffer flushes. The trade-off: data written in a relaxed transaction may be lost if the OS crashes (not just the browser—power failure or kernel panic). Browser crashes and tab crashes are still safe because the browser process commits to its WAL (Write-Ahead Log) before reporting success.

Design reasoning: Most web apps don’t need strict durability—the data is a cache of server state. Relaxed durability matches what users expect: if the power goes out, losing the last few seconds of client-side data is acceptable. strict matters for apps where the browser is the primary data store (offline-first productivity tools, local databases).

Structured Clone: What Can Be Stored

IndexedDB serializes values using the structured clone algorithm, which supports more types than JSON:

Cloneable (stored correctly):

• Primitives (string, number, boolean, null, undefined, BigInt)
• Date, RegExp (except lastIndex)
• ArrayBuffer, typed arrays, DataView
• Blob, File, FileList
• ImageBitmap, ImageData
• Map, Set
• Array, plain objects (own enumerable properties)

Not cloneable (throws DataCloneError):

• Functions and closures
• DOM nodes
• Symbols
• Property descriptors (getters, setters)
• Prototype chains (class instances lose their prototype)
• Error objects (in some older browsers)

1
// ✅ Rich objects survive structured clone
2
store.put({
3
  id: "1",
4
  created: new Date(), // Date preserved (JSON would stringify)
5
  tags: new Set(["a", "b"]), // Set preserved (JSON would lose it)
6
  binary: new Uint8Array([1, 2]), // Binary preserved (JSON can't do this)
7
})
8

9
// ❌ Class instances lose their prototype
10
class User {
11
  greet() {
12
    return "hi"
13
  }
14
}
15
store.put({ id: "1", user: new User() })
16
// Retrieved object has no greet() method—it's a plain object

Indexes and Querying

Indexes enable efficient lookups on non-primary-key fields:

5 collapsed lines
1
// Schema setup (collapsed)
2
const store = db.createObjectStore("products", { keyPath: "id" })
3
store.createIndex("by-category", "category")
4
store.createIndex("by-price", "price")
5
store.createIndex("by-cat-price", ["category", "price"]) // Compound index
6

7
// Query by index using key ranges
8
const tx = db.transaction("products", "readonly")
9
const index = tx.objectStore("products").index("by-price")
10

11
// Exact match
12
const request = index.get(29.99)
13

14
// Range queries with IDBKeyRange
15
index.getAll(IDBKeyRange.bound(10, 50)) // 10 ≤ price ≤ 50
16
index.getAll(IDBKeyRange.bound(10, 50, true, false)) // 10 < price ≤ 50
17
index.getAll(IDBKeyRange.lowerBound(100)) // price ≥ 100
18
index.getAll(IDBKeyRange.upperBound(20)) // price ≤ 20
19

20
// Compound index query: category="electronics" AND price 50-200
21
const compoundIndex = tx.objectStore("products").index("by-cat-price")
22
compoundIndex.getAll(IDBKeyRange.bound(["electronics", 50], ["electronics", 200]))

Cursor-based iteration for large result sets:

1
const tx = db.transaction("products", "readonly")
2
const index = tx.objectStore("products").index("by-price")
3

4
const cursor = index.openCursor(IDBKeyRange.lowerBound(50), "next")
5

6
cursor.onsuccess = () => {
7
  const result = cursor.result
8
  if (result) {
9
    processProduct(result.value)
10
    result.continue() // Move to next record
11
  }
12
}

Edge Cases and Failure Modes

Storage corruption: Can occur from repeated clearing during active I/O operations, or from structured clone failures on upgrade. Recovery requires deleting and rebuilding the database:

1
const deleteRequest = indexedDB.deleteDatabase("myapp")
2
deleteRequest.onsuccess = () => {
3
  // Recreate from server or defaults
4
}
5
deleteRequest.onblocked = () => {
6
  // Other tabs still have open connections
7
}

QuotaExceededError in IndexedDB: Unlike localStorage, this can happen during any write operation—including during transactions. A failed write aborts the entire transaction:

1
tx.onerror = (event) => {
2
  if (tx.error?.name === "QuotaExceededError") {
3
    // Entire transaction was rolled back
4
    // Evict old data and retry
5
  }
6
}

Private browsing limits: Chrome limits IndexedDB to ~32 MiB per database and ~500 MiB total in incognito. All data is deleted when the incognito window closes.

IDB on the main thread vs workers: IndexedDB is available in web workers (including service workers and shared workers), which avoids main-thread I/O entirely. For large writes, always use a worker:

1
// Heavy IndexedDB writes in a web worker—zero main thread impact
2
self.onmessage = async (event) => {
3
  const db = await openDB("bulk", 1)
4
  const tx = db.transaction("data", "readwrite")
5
  for (const record of event.data.records) {
6
    tx.objectStore("data").put(record)
7
  }
8
  tx.oncomplete = () => self.postMessage({ status: "done" })
9
}

Origin Private File System (OPFS)

The Origin Private File System (WHATWG File System Standard) provides a sandboxed file system per origin with synchronous access in workers—the fastest storage API available in browsers.

Why OPFS Exists

IndexedDB’s structured clone overhead and transaction model add latency that matters for compute-heavy workloads. OPFS provides raw byte access:

• SQLite in the browser: Projects like sql.js and the official SQLite Wasm build use OPFS as their backing store
• Wasm state persistence: Emscripten and other Wasm toolchains map OPFS to a virtual filesystem
• Large binary data: Image/video processing pipelines that need direct byte access without serialization overhead

API Surface

OPFS has two access modes:

1
// Async access (available on main thread and workers)
2
const root = await navigator.storage.getDirectory()
3
const fileHandle = await root.getFileHandle("data.bin", { create: true })
4

5
// Async read/write via File and WritableStream
6
const file = await fileHandle.getFile() // Returns a File (Blob subclass)
7
const writable = await fileHandle.createWritable()
8
await writable.write(new Uint8Array([1, 2, 3]))
9
await writable.close()

1
// Synchronous access (workers only)—MUCH faster
2
const root = await navigator.storage.getDirectory()
3
const fileHandle = await root.getFileHandle("data.bin", { create: true })
4

5
const syncHandle = await fileHandle.createSyncAccessHandle()
6

7
// Direct byte operations—no promises, no structured clone
8
const buffer = new ArrayBuffer(1024)
9
syncHandle.read(buffer, { at: 0 }) // Read 1024 bytes from offset 0
10
syncHandle.write(new Uint8Array([1, 2, 3]), { at: 0 })
11
syncHandle.flush() // Ensure data is written to disk
12
syncHandle.close() // Release the lock

Design reasoning: createSyncAccessHandle() is restricted to workers because synchronous I/O on the main thread would block user interaction—the same problem that makes large localStorage operations problematic. By limiting sync access to workers, the spec provides the performance of synchronous I/O without the main-thread penalty.

Limitations: OPFS files are invisible to the user (no file picker), not shareable across origins, and count against the same origin quota as IndexedDB and Cache API.

Storage Quotas and Eviction

The WHATWG Storage Standard defines a unified quota model for all script-writable storage (IndexedDB, Cache API, OPFS). Web Storage (localStorage/sessionStorage) has its own separate ~5 MiB limit.

Quota by Browser

The StorageManager API

1
// Check current usage
2
const estimate = await navigator.storage.estimate()
3
console.log(`Used: ${(estimate.usage! / 1024 / 1024).toFixed(1)} MiB`)
4
console.log(`Quota: ${(estimate.quota! / 1024 / 1024).toFixed(0)} MiB`)
5
console.log(`Available: ${((estimate.quota! - estimate.usage!) / 1024 / 1024).toFixed(0)} MiB`)
6

7
// Request persistent storage (prevents eviction under pressure)
8
const persisted = await navigator.storage.persist()
9
if (persisted) {
10
  console.log("Storage marked persistent—won't be evicted automatically")
11
} else {
12
  console.log("Browser denied persistence request")
13
}
14

15
// Check persistence status
16
const isPersisted = await navigator.storage.persisted()

Persistent vs best-effort: By default, all storage is “best-effort”—the browser can evict it under storage pressure without asking the user. Calling navigator.storage.persist() requests “persistent” mode, which requires user approval (explicit or implicit) before the browser can delete the data. Chrome auto-grants persistence for installed PWAs (Progressive Web Apps) and sites with high engagement; Firefox shows a permission prompt; Safari does not support the persistence API.

Safari’s 7-Day Eviction (ITP)

Since Safari 13.1 (March 2020), Intelligent Tracking Prevention (ITP) deletes all script-writable storage after 7 days without user interaction for a given origin. This affects localStorage, IndexedDB, Cache API, and service worker registrations.

What counts as “user interaction”: The user must tap or click on the site (not just visit via redirect). Navigation via window.open() or link decoration does not reset the timer.

Exempt scenarios:

• PWAs added to the home screen
• Sites the user has explicitly interacted with in the last 7 days

Impact: Any offline-first app on Safari that the user doesn’t visit weekly will lose all client-side data. Server-side persistence is mandatory for Safari users.

Storage Partitioning

Modern browsers partition storage by top-level site to prevent cross-site tracking:

Chrome (115+): Third-party storage is partitioned by the top-level site. An iframe from cdn.example.com embedded on siteA.com gets different storage than the same iframe on siteB.com. This affects IndexedDB, Cache API, localStorage, and service workers.

Firefox (103+): State Partitioning double-keys all storage by (resource origin, top-level eTLD+1). Enabled by default in Enhanced Tracking Protection.

Safari: Permanently blocks third-party storage access. The Storage Access API allows embedded contexts to request first-party storage access after a user gesture.

Practical impact: If your app uses iframes or third-party embeds that rely on shared storage, storage partitioning breaks those assumptions. Use the Storage Access API or document.requestStorageAccess() for legitimate cross-site storage needs.

Practical Patterns

Wrapper with Fallback

4 collapsed lines
1
// Type definitions (collapsed)
2
type StorageValue = string | number | boolean | object | null
3
interface StorageAdapter {
4
  get(key: string): Promise<StorageValue>
5
  set(key: string, value: StorageValue): Promise<void>
6
}
7

8
// localStorage adapter with quota handling
9
const localStorageAdapter: StorageAdapter = {
10
  async get(key) {
11
    const raw = localStorage.getItem(key)
12
    return raw ? JSON.parse(raw) : null
13
  },
14
  async set(key, value) {
15
    try {
16
      localStorage.setItem(key, JSON.stringify(value))
17
    } catch (e) {
18
      if (e instanceof DOMException && e.name === "QuotaExceededError") {
19
        // Evict oldest entries and retry, or fall back to IndexedDB
20
        throw new Error("localStorage quota exceeded")
21
      }
22
      throw e
23
    }
24
  },
5 collapsed lines
25
}
26

27
// Usage (collapsed)
28
const adapter = isStorageAvailable() ? localStorageAdapter : indexedDBAdapter
29
await adapter.set("prefs", { theme: "dark", lang: "en" })

IndexedDB Promise Wrapper

The raw IndexedDB API uses event callbacks. A thin promise wrapper reduces boilerplate:

1
function wrapRequest<T>(request: IDBRequest<T>): Promise<T> {
2
  return new Promise((resolve, reject) => {
3
    request.onsuccess = () => resolve(request.result)
4
    request.onerror = () => reject(request.error)
5
  })
6
}
7

8
function wrapTransaction(tx: IDBTransaction): Promise<void> {
9
  return new Promise((resolve, reject) => {
10
    tx.oncomplete = () => resolve()
11
    tx.onerror = () => reject(tx.error)
12
    tx.onabort = () => reject(tx.error || new DOMException("Transaction aborted"))
13
  })
14
}
15

16
// Usage
17
const tx = db.transaction("users", "readwrite")
18
tx.objectStore("users").put({ id: "1", name: "Alice" })
19
await wrapTransaction(tx) // Resolves when transaction commits

Consider libraries: For production use, idb by Jake Archibald provides a well-tested promise wrapper. Dexie.js adds query builder syntax and live queries. These eliminate the boilerplate without hiding important semantics.

Cache Invalidation with Version Keys

1
// Simple TTL-based invalidation for localStorage
2
function setWithTTL(key: string, value: unknown, ttlMs: number) {
3
  const entry = { value, expiry: Date.now() + ttlMs }
4
  localStorage.setItem(key, JSON.stringify(entry))
5
}
6

7
function getWithTTL<T>(key: string): T | null {
8
  const raw = localStorage.getItem(key)
9
  if (!raw) return null
10

11
  const entry = JSON.parse(raw)
12
  if (Date.now() > entry.expiry) {
13
    localStorage.removeItem(key)
14
    return null
15
  }
16
  return entry.value
17
}

Conclusion

Browser storage APIs form a spectrum from simple-but-blocking (localStorage) to powerful-but-complex (IndexedDB) to raw-but-fast (OPFS). The right choice depends on your data shape, access patterns, and threading requirements—not just capacity.

localStorage works for small, string-serializable preferences that need cross-tab visibility. IndexedDB handles structured app data at scale, but its transaction lifetime rules, version upgrade protocol, and blocked/versionchange coordination require careful implementation. OPFS enables performance-critical workloads like client-side SQLite. The Cache API bridges service worker caching (covered in the companion article).

The quota model is the unifying constraint: all script-writable storage (except Web Storage’s separate ~5 MiB) shares a per-origin budget that varies dramatically by browser. Safari’s 7-day ITP eviction makes server-side persistence non-optional for any serious app. Storage partitioning changes the rules for third-party contexts. Design for eviction, not just persistence.

Appendix

Prerequisites

• JavaScript Promises and async/await
• Basic understanding of the same-origin policy
• Familiarity with JSON serialization

Terminology

• Origin: Scheme + host + port tuple (e.g., https://example.com:443). Storage is scoped per origin
• eTLD+1: Effective Top-Level Domain plus one label (e.g., example.com for sub.example.com). Used for quota grouping in Firefox
• Structured clone: Serialization algorithm that supports more types than JSON (Date, Map, Set, ArrayBuffer, Blob). Used by IndexedDB and postMessage()
• WAL (Write-Ahead Log): Journaling strategy where changes are written to a log before applying to the main data file. Used by IndexedDB implementations for crash recovery
• OPFS: Origin Private File System—a sandboxed, per-origin virtual file system with synchronous access in workers
• ITP: Intelligent Tracking Prevention—Safari’s privacy feature that restricts cross-site tracking and evicts storage after 7 days without interaction
• best-effort storage: Default storage mode where the browser can evict data under storage pressure without user consent
• persistent storage: Storage mode (requested via navigator.storage.persist()) where user consent is required before eviction

Summary

• localStorage is synchronous, blocks the main thread, stores DOMString KV pairs, has a ~5 MiB limit, and enables cross-tab communication via storage events
• sessionStorage shares the same API but is scoped to a single tab and dies when the tab closes
• IndexedDB 3.0 provides async transactional storage with structured clone serialization, multi-column indexes, and cursor-based iteration. Transactions auto-commit when the event loop is idle—inserting non-IDB async operations kills them
• OPFS offers the fastest storage via synchronous FileSystemSyncAccessHandle in workers—ideal for SQLite/Wasm workloads
• Quota is per-origin: Chrome ~60% of disk, Firefox up to 2 GiB per group, Safari 1 GiB with 7-day ITP eviction. navigator.storage.persist() requests eviction protection
• Storage partitioning (Chrome 115+, Firefox 103+, Safari) isolates third-party storage by top-level site, breaking cross-site storage sharing

References

Specifications (Primary Sources)

• Storage Standard - WHATWG Living Standard (quota model, storage buckets, persistence)
• Web Storage - HTML Standard - WHATWG (localStorage, sessionStorage)
• Indexed Database API 3.0 - W3C (transactions, object stores, indexes, versioning)
• File System Standard - WHATWG (OPFS, FileSystemSyncAccessHandle)
• Service Worker Specification - W3C (Cache interface, CacheStorage)

Official Documentation

• Storage quotas and eviction criteria - MDN
• IndexedDB API - MDN
• Web Storage API - MDN
• Origin Private File System - MDN
• Structured clone algorithm - MDN
• Storage Access API - MDN

Core Maintainer Content and Technical Resources

• Storage for the Web - web.dev - Chrome DevRel overview of storage APIs
• IndexedDB Durability Mode Now Defaults to Relaxed - Chrome Blog
• Storage Partitioning - Chrome Privacy Sandbox
• Updates to Storage Policy - WebKit Blog
• Full Third-Party Cookie Blocking and More - WebKit Blog - Safari ITP storage cap details
• State Partitioning - MDN - Firefox storage partitioning
• SQLite Wasm - Official SQLite WebAssembly build using OPFS