LiveStore Documentation

LiveStore is a client-centric data layer designed to replace state management libraries like Redux or MobX. It provides a reactive embedded SQLite database with real-time synchronization capabilities.

Key features include:

• Reactive Query Layer: Full SQLite support for instant queries.
• Multi-platform Adapters: Support for web, mobile, server/edge, and desktop.
• Offline-First: Built for true offline workflows.
• Data Modeling: Flexible schema management and custom merge conflict resolution.
• Synchronization: Sync via supported providers (e.g., Cloudflare) or custom implementations using event-sourcing.

The @livestore/adapter-web is designed for browser environments. It provides a robust storage and synchronization layer using the following technologies:

• Storage: Uses SQLite WASM with OPFS (Origin Private File System) for persistent browser storage.
• Concurrency: Runs in Web Workers and SharedWorkers to enable coordination across multiple browser tabs.
• Persistence: Utilizes an OPFS Access Handle Pool VFS for data persistence.
• Connectivity: Supports WebSocket connections for synchronization and developer tools.

@livestore/webmesh is a library designed to connect multiple nodes (such as browser windows, tabs, workers, or threads) in a network-like topology. It enables the establishment of communication channels between these nodes.

Channel Types

• ProxyChannel: A virtual channel that proxies messages along edges via hop nodes.
• DirectChannel: An end-to-end channel that supports transferable objects (e.g., Uint8Array).
• BroadcastChannel: A virtual channel that broadcasts messages to all connected nodes.

Both ProxyChannel and DirectChannel provide TCP-like properties: they have unique names across the network, support auto-reconnection, ensure ordered messages, and are reliable (buffering messages and acknowledging each one).

A LiveStore instance (identified by a storeId) provides a unified surface for interacting with a single object or domain. The API is designed around two core principles:

1. Synchronous Reads: store.query runs against the session's in-memory SQLite synchronously. It does not return a Promise and does not require a loading state, providing an immediate local source of truth.
2. Instant Writes: store.commit validates and materializes changes locally, refreshes affected queries, and returns synchronously. Persistence and synchronization with the leader happen asynchronously in the background.

Note on Error Handling: If a commit fails locally, the store shuts down rather than throwing an error back to the caller.

The Cloudflare Sync Provider uses a specific topology where a client connects to a Cloudflare Worker, which in turn manages a Durable Object (DO) per storeId. The Durable Object acts as the central arbiter for pushes and fans out live pull streams to subscribers.

Topology Flow: client (SyncBackend impl) ──ws | http | do-rpc──▶ CF worker ──▶ Durable Object (per storeId)

LiveStore's web runtime uses a multi-layered worker architecture to manage state and synchronization across multiple browser tabs. The topology consists of:

1. Tabs (Main Thread): Each tab maintains a client session and an in-memory SQLite instance. Tabs communicate with the Shared Worker via an Effect RpcClient (SharedWorkerRpcs).
2. Shared Worker: Acts as a mediator. It parses its storeId from self.name. It holds no state of its own but manages the connection to the current leader.
3. Leader Worker: A dedicated worker (livestore-worker-<storeId>-<sessionId>) that hosts the makeLeaderThreadLayer. This worker is spawned by the leader-elect tab.

Communication flows from Tabs $\rightarrow$ Shared Worker $\rightarrow$ Leader Worker.

LiveStore distinguishes between clients and sessions:

• Client: A logical group of client sessions on one device or runtime that share local data. It is identified by a randomly generated clientId.
• Client session: A single running instance within a client (e.g., a specific browser tab). It is identified by a sessionId (which persists across tab reloads in web environments). Each session hosts a store and its own reactivity graph.

Warning: This feature is experimental and not part of the shipping contract.

Facts are key/value constraints that an event can set, unset, require, or read. They are intended for ordering constraints, compaction, and conflict detection in next-gen sync.

Currently, facts are not wired into materialization; the materializer context's currentFacts is a constant empty Map.