Browser Storage, OPFS & IndexedDB Architecture Studio

The Origin Private File System (OPFS) is a high-performance private filesystem sandbox provided by the File System Access API. Unlike standard web storage (IndexedDB, localStorage), which requires structured cloning and serializing objects across IPC boundaries, OPFS grants direct, synchronous access to raw byte streams via FileSystemSyncAccessHandle inside Web Workers. WebAssembly modules (such as SQLite compiled to Wasm) can execute direct in-place reads and writes (read(), write(), truncate(), flush()) at specific byte offsets with microsecond latency, achieving near-native NVMe SSD speeds (hundreds of megabytes per second) with zero garbage collection overhead.

Browsers manage client storage under two modes: "Best-Effort" (default) and "Persistent". Under Best-Effort, when the host device runs low on disk space, the browser automatically purges origin data without user warning, typically following a Least Recently Used (LRU) algorithm. In Chromium (Chrome/Edge), an origin can consume up to 60% of total available disk space. In Firefox, an origin can consume up to 10% of total disk space (capped by group limits). In Safari / WebKit, storage is aggressively limited: origins are initially restricted to 1 GB, and Safari will prompt the user for permission before expanding. Calling navigator.storage.persist() requests persistent storage immunity from automatic LRU eviction.

localStorage has three severe architectural bottlenecks: (1) Synchronous I/O on the Main Thread: Every read (getItem) and write (setItem) blocks the browser main thread. While waiting for disk I/O, the browser cannot render frames, process touch gestures, or execute animations, causing UI jank. (2) Strict String-Only Storage: Every object or array must be serialized to a JSON string, creating heavy CPU and memory churn. (3) 5 MB Storage Ceiling: Exceeding 5 MB throws a QuotaExceededError. Production web applications should never use localStorage for state caching; IndexedDB or OPFS should always be used asynchronously off the main thread.

The official SQLite WebAssembly distribution implements an OPFS Virtual File System (VFS) driver (sqlite3-opfs-async-vfs or the synchronous OPFS VFS). In a dedicated Web Worker, SQLite maps database pages (typically 4 KB) directly to a file within OPFS using FileSystemSyncAccessHandle. Transactional write-ahead logging (WAL) and atomic commits (fsync / flush()) map directly to the operating system filesystem calls. This enables complex relational SQL queries, joins, indexes, and full-text search directly inside client browsers at native speeds, powering modern local-first applications.

CacheStorage is specifically designed to store pairs of HTTP Request and Response objects, managed primarily by Service Workers for offline Progressive Web App (PWA) asset caching. It is optimized for streaming large binary Blobs, images, audio, video, and bundled JavaScript/CSS files. IndexedDB is a transactional NoSQL object store designed for structured, indexable application data (JSON objects, records, key-value trees). While you can store Blobs in IndexedDB, CacheStorage is substantially more efficient for HTTP response caching because Service Workers can return cached responses directly to fetch events via event.respondWith(caches.match(request)) without memory deserialization.