@livestore/livestore 0.4.0-dev.21 → 0.4.0-dev.23

package/docs/overview/concepts/index.md

@@ -1,78 +0,0 @@
-# Concepts
-
-![](https://share.cleanshot.com/sv62BGww+)
-
-## Overview
-
-- Adapter (platform adapter)
-  - An adapter can instantiate a client session for a given platform (e.g. web, Expo)
-- Client
-  - A logical group of client sessions
-  - Identified by a `clientId` - a randomly generated 6-char nanoid
-  - Each client has at least one client session
-  - Sessions within a client share local data
-  - Client session
-    - An instance within a client
-    - Identified by a `sessionId`
-    - In web: sessionId can persist across tab reloads
-    - Multiple sessions can exist within a single client (e.g., multiple browser tabs)
-    - Store
-    - Reactivity graph
-- [Devtools](/building-with-livestore/devtools)
-- [Events](/building-with-livestore/events)
-  - Event definition
-  - Eventlog
-  - Synced vs client-only events
-- Framework integration
-  - A framework integration is a package that provides a way to integrate LiveStore with a framework (e.g. React, Solid, Svelte, etc.)
-- [Reactivity system](/building-with-livestore/reactivity-system)
-  - Db queries `queryDb()`
-  - Computed queries `computed()`
-  - Signals `signal()`
-- Schema
-  - LiveStore uses schema definitions for the following cases:
-    - [Event definitions](/building-with-livestore/events)
-    - [SQLite state schema](/building-with-livestore/state/sqlite-schema)
-    - [Query result schemas](/building-with-livestore/state/sql-queries)
-  - LiveStore uses the [Effect Schema module](/patterns/effect) to define fine-granular schemas
-- State
-  - Derived from the eventlog via materializers
-  - Materializer
-    - Event handler function that maps an event to a state change
-  - SQLite state / database
-    - In-memory SQLite database within the client session thread (usually main thread)
-      - Used by the reactivity graph
-    - Persisted SQLite database (usually running on the leader thread)
-    - Fully derived from the eventlog
-- [Store](/building-with-livestore/store)
-  - A store exposes most of LiveStore's functionality to the application layer and is the main entry point for using LiveStore.
-  - To create a store you need to provide a schema and a platform adapter which creates a client session.
-  - A store is often created, managed and accessed through a framework integration (like React).
-  - A store is identified by a `storeId` which is also used for syncing events between clients.
-- Sync provider
-  - A sync provider is a package that provides a sync backend and a sync client.
-  - Sync backend
-    - A central server that is responsible for syncing the eventlog between clients
-
-### Implementation details
-
-- Leader thread
-  - Responsible for syncing and persisting of data
-- Sync processor
-  - LeaderSyncProcessor
-  - ClientSessionSyncProcessor
-
-## Pluggable architecture
-
-LiveStore is designed to be pluggable in various ways:
-
-- Platform adapters
-- Sync providers
-- Framework integrations
-
-## Important notes on identity
-
-- LiveStore does not have built-in concepts of "users" or "devices"
-- User identity must be modeled within your application domain through events and application logic
-- The `clientId` identifies a client instance, not a user
-- Multiple clients can represent the same user (e.g., different browsers or devices)

package/docs/overview/how-livestore-works/index.md

@@ -1,56 +0,0 @@
-# How LiveStore works
-
-### TLDR
-
-LiveStore uses event sourcing to sync events across clients and materialize state into a local, reactive SQLite database.
-
-<HowItWorksDiagram class="my-8" />
-
-## How LiveStore works client-side
-
-On the client, LiveStore provides a reactive SQLite database for application state, which is kept consistent through an underlying event sourcing mechanism.
-
-#### Local reactive SQLite
-
-Application state is materialized into a local SQLite database, offering high-performance, offline-capable data access. This SQLite database is reactive: UI components subscribe to data changes and update automatically when the state changes. LiveStore uses in-memory SQLite for sub-millisecond queries and persistent SQLite for durable storage across application sessions.
-
-#### Event Sourcing
-
-Underpinning the reactive state, LiveStore implements the event sourcing pattern. All data modifications are captured as an immutable, ordered sequence of events. This eventlog serves as the canonical history, enabling reliable state reconstruction and providing inherent auditability, which aids in debugging. The reactive SQLite state is a projection of this eventlog.
-
-#### Client-side event flow
-
-1.  **Event Committing:** User interactions within the application generate events detailing the specific action (e.g., `TodoCreated`, `TaskCompleted`).
-2.  **Local Persistence & Materialization:** The committed event is atomically persisted to the local eventlog and immediately materialized as state into the SQLite database.
-3.  **UI Reactivity:** Changes to the SQLite database trigger the reactivity system, causing subscribed UI components (e.g. React components) to automatically update and reflect the new state.
-
-## How LiveStore syncing works
-
-LiveStore extends its local event-sourcing model globally by synchronizing events across all clients, typically through a central sync backend. This ensures that the eventlog, serving as the single source of truth, is consistently replicated, leading to an eventually consistent state for all participants.
-
-#### Push/pull event synchronization
-
-Inspired by Git, LiveStore employs a push/pull model for event synchronization. Clients must first pull the latest events from the sync backend to ensure their local eventlog is up-to-date before they can push their own newly committed local events. This model helps maintain a global total order of events. Local pending events that haven't been pushed are rebased on top of the latest upstream events before being pushed.
-
-#### Sync provider integration
-
-LiveStore supports various sync backend implementations, and it's straightforward for developers to create their own. The sync backend is responsible for storing events, enforcing the total event order, and notifying clients of new events.
-
-#### Conflict resolution
-
-When concurrent operations from different clients lead to conflicting events, LiveStore defaults to a "last-write-wins" strategy. However, it also provides the capability for developers to implement custom merge conflict resolution logic tailored to their application's specific needs.
-
-#### Overall syncing data flow
-
-After a local event is committed and materialized (as per the client-side flow), LiveStore attempts to push this event to the sync backend. Simultaneously, LiveStore is pulling events from the sync backend in the background.
-
-Two main scenarios can occur during a push attempt:
-
-1.  **Client In Sync:** If the client's local eventlog is already up-to-date with the sync backend (i.e., no new remote events have arrived since the last pull/push), the local event is pushed directly.
-2.  **Concurrent Incoming Events:** If new remote events have been pulled in the background, or are discovered during the push attempt, the client first processes these incoming remote events. Any local, unpushed events are then rebased on top of these new remote events before being pushed to the sync backend.
-
-In both scenarios, once remote events are received (either through background pulling or during a push cycle), they are persisted to the local eventlog, materialized into the local SQLite database, and the UI reacts to the new state, ensuring eventual consistency.
-
-## Platform adapters
-
-LiveStore includes platform adapters to integrate with various environments, such as web browsers, mobile applications (iOS/Android), desktop applications, and Node.js.

package/docs/overview/introduction/index.md

@@ -1,5 +0,0 @@
-# Introduction
-
-## What is LiveStore?
-
-TBD

package/docs/overview/technology-comparison/index.md

@@ -1,40 +0,0 @@
-# Technology comparison
-
-## TLDR of what sets LiveStore apart
-
-- Uses combination of reactive, in-memory + synced, persisted SQLite for instant, synchronous queries
-- Based on event-sourcing methodologies
-- Client-centric (with great devtools)
-
-## Other local-first/syncing technologies
-
-To compare LiveStore with other local-first/syncing technologies, please see the [Local-First Landscape](https://www.localfirst.fm/landscape) resource.
-
-## LiveStore vs Redux
-
-LiveStore shares a lot of similarities with Redux in that sense that both are based on event-sourcing methodologies. Let's compare some of the core concepts:
-
-- Redux actions are similar to LiveStore events: Both are used to describe "things that have happened"
-- Redux views are similar to LiveStore's state (e.g. SQLite tables): Both are derived from the history of events/actions.
-  - A major difference here is that LiveStore's state materialized as a SQLite database allows for a lot more flexibility via dynamic queries and aggregations vs Redux's static views.
-- Redux reducers are similar to LiveStore's materializers: Both are used to transform events/actions into a final state.
-- Both Redux and LiveStore are client-centric.
-- Both Redux and LiveStore provide powerful [devtools](/building-with-livestore/devtools).
-
-While LiveStore can be used for the same use cases as Redux, LiveStore goes far beyond Redux in the following ways:
-
-- LiveStore leverages SQLite for a more powerful state model allowing for flexible queries and aggregations with much simpler materialization logic.
-- LiveStore supports client-persistence out of the box.
-- LiveStore comes with a built-in [sync engine](/building-with-livestore/syncing) syncing events between clients.
-
-As a downside compared to Redux, LiveStore has a slightly larger bundle size.
-
-## Other state management libraries
-
-- Zustand
-- Redux Toolkit (RTK)
-- MobX
-- Jotai
-- Xstate
-- Recoil
-- TanStack Query

package/docs/overview/when-livestore/index.md

@@ -1,81 +0,0 @@
-# When to use LiveStore (and when not)
-
-Choosing a data layer for a local-first app is a big decision and should be considered carefully.  On a high level, LiveStore can be a good fit if ...
-- you are looking for a principled data layer that works across platforms
-- you want to use SQLite for your queries
-- you like [event sourcing](/understanding-livestore/event-sourcing) to model data changes
-- you are working on a new app as LiveStore doesn't yet provide a way to [re-use an existing database](/misc/faq#existing-database)
-- the current [state of the project](/misc/state-of-the-project) aligns with your own timeline and requirements
-
-## Evaluation exercise
-
-A great way to evaluate whether LiveStore is a good fit for your application, is by trying to model your application events (and optionally state) schema. This exercise can be done in a few minutes and can give you a good indication of whether LiveStore is a good fit for your application.
-
-### Example: Calendar/scheduling app
-
-Let's say you are building a calendar/scheduling app, your events might include:
-
-- `AppointmentScheduled`
-- `AppointmentRescheduled`
-- `AppointmentCancelled`
-- `ParticipantInvitedToAppointment`
-- `ParticipantRespondedToInvite`
-
-From this you might want to derive the following state (modeled as SQLite tables):
-
-- `Appointment`
-  - `id`
-  - `title`
-  - `description`
-  - `participants`
-- `Participant`
-  - `id`
-  - `name`
-  - `email`
-
-## Great use cases for LiveStore
-
-- High-performance desktop/web/mobile apps
-  - e.g. productivity apps like 
-- AI agents
-- Apps that need ...
-  - solid offline support
-  - audit logs
-
-## Benefits of LiveStore
-
-- Unified data layer combining local reactive state with globally synced data
-- Easy to ...
-  - reason about
-  - debug
-  - test
-  - evolve
-  - operate
-
-## Reasons when not to use LiveStore
-
-- You have an existing database which is the source of truth of your data. (Better use [Zero](https://zero.rocicorp.dev) or [ElectricSQL](https://www.electricsql.com) for this.)
-- Your app data is highly connected across users (like a social network / marketplace / etc.) or modeling your data via read-write model separation/event sourcing doesn't seem feasible.
-- You want to build a more traditional client-server application with your primary data source being a remote server.
-- You want a full-stack batteries-included solution (e.g. auth, storage, etc.). (Technologies like [Jazz](https://jazz.tools) or [Instant](https://instantdb.com) might be a better fit.)
-- You don't like to model your data via read-write model separation/event sourcing or the trade-offs it involves.
-- You're a new developer and are just getting started. LiveStore is a relatively advanced technology with many design trade-offs that might make most sense after you have already experienced some of the problems LiveStore is trying to solve.
-- You want to keep your app bundle size as small as possible. LiveStore adds a few hundred kB to your app bundle size (mostly due to bundling SQLite).
-
-## Considerations
-
-### Database constraints
-
-- All the client app data should fit into a in-memory SQLite database
-  - Depending on the target device having databases up to 1GB in size should be okay.
-  - If you you have more data, you can consider segmenting your database into multiple SQLite database (e.g. segmented per project, workspace, document, ...).
-  - You can either use the `storeId` option for the segmentation or there could also be a way to use the [SQLite attach feature](https://www.sqlite.org/lang_attach.html) to dynamically attach/detach databases.
-
-### Syncing
-
-LiveStore's syncing system is designed for small/medium-level concurrency scenarios (e.g. 10s / low 100s of users collaborating on the same thing for a given eventlog).
-  - Collaboration on multiple different eventlogs concurrently is supported and should be used to "scale horizontally".
-
-### Other considerations
-
-- How data flows / what's the source of truth?

package/docs/overview/why-livestore/index.md

@@ -1,5 +0,0 @@
-# Why LiveStore?
-
-## Why should you use LiveStore?
-
-TBD

package/docs/patterns/ai/index.md

@@ -1,15 +0,0 @@
-# AI
-
-- LiveStore is a great fit for building AI applications.
-- Scenarios:
-  - Local RAG (via sqlite-vec (see [feature request](https://github.com/livestorejs/livestore/issues/127)) + local LLM e.g. Gemini Nano embedded in Chrome)
-  - Agentic applications
-
-- Event <> tool calls
-  - Nice mapping
-
-## Example
-
-```ts
-// TODO (contribution welcome)
-```

package/docs/patterns/anonymous-user-transition/index.md

@@ -1,10 +0,0 @@
-# Anonymous user transition
-
-## Basic idea
-
-- Locally choose a unique identifier for the user (e.g. via `crypto.randomUUID()`).
-	- You might want to handle the very unlikely case that the identifier is not unique (collision) on the sync backend.
-- Persist this identifier locally (either via a separate LiveStore instance or via `localStorage`).
-- Use this identifier in the `storeId` for the user-related LiveStore instance.
-	- Initially when the user is anonymous, the store won't be synced yet (i.e. no sync backend used in adapter).
-	- As part of the auth flow, the LiveStore instance is now synced with the same `storeId` to a sync backend which will sync all local events to the sync backend making sure the user keeps all their data.

package/docs/patterns/app-evolution/index.md

@@ -1,72 +0,0 @@
-# App evolution
-
-When building an app with LiveStore, you'll need to keep some things in mind when evolving your app.
-
-## Schema changes
-
-### State schema changes
-
-Generally any kind of changes to your state schema (e.g. SQLite tables, ...) can be done at any time without any further considerations assuming the event materializer is updated to support the new schema.
-
-### Event schema changes
-
-Event schema changes require a bit more consideration. Changes to the event schema should generally be done in a backwards-compatible way. See [Event schema evolution](/building-with-livestore/events#schema-evolution) for more details.
-
-## Parallel different app versions
-
-In scenarios where you have multiple app versions rolled out in parallel (e.g. app version v3 with event schema v3 and app version v4 with event schema v4), you'll need to keep the following in mind:
-
-App instances running version 4 might commit events that are not yet supported by version 3. Your app needs to decide how to handle this scenario in one of the following ways:
-
-- Ignore unknown events
-- Cause an error in the app for unknown events
-- Handle events with a "catch all" event handler
-- Let app render a "app update required" screen. App can still be used in read-only mode.
-- ...
-
-LiveStore exposes a dedicated `unknownEventHandling` configuration on `makeSchema` so you can codify the desired behaviour instead of sprinkling ad-hoc checks across your app. The default is `'warn'`, which logs every unknown event and keeps processing.
-
-## `reference/events/unknown-event-handling.ts`
-
-```ts filename="reference/events/unknown-event-handling.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-    },
-  }),
-} as const
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-// ---cut---
-
-const _schema = makeSchema({
-  events,
-  state,
-  unknownEventHandling: {
-    strategy: 'callback',
-    onUnknownEvent: (event, error) => {
-      console.warn('LiveStore saw an unknown event', { event, reason: error.reason })
-    },
-  },
-})
-```
-
-Set the strategy to `'ignore'` to silently skip forward-only events, `'fail'` to stop immediately (useful during development), or `'callback'` to forward them to custom telemetry while continuing to replay the log.

package/docs/patterns/auth/index.md

@@ -1,226 +0,0 @@
-# Auth
-
-LiveStore doesn't include built-in authentication or authorization support, but you can implement it in your app's logic.
-
-## Pass an auth payload to the sync backend
-
-Use the `syncPayload` store option to send a custom payload to your sync backend.
-
-### Example
-
-The following example sends the authenticated user's JWT to the server.
-
-## `patterns/auth/live-store-provider.tsx`
-
-```tsx filename="patterns/auth/live-store-provider.tsx"
-
-const schema = {} as Parameters<typeof LiveStoreProvider>[0]['schema']
-const storeId = 'demo-store'
-const user = { jwt: 'user-token' }
-const children: ReactNode = null
-const adapter = makeInMemoryAdapter()
-
-// ---cut---
-export const AuthenticatedProvider = () => (
-  <LiveStoreProvider
-    schema={schema}
-    storeId={storeId}
-    adapter={adapter}
-    batchUpdates={batchUpdates}
-    syncPayload={{
-      authToken: user.jwt, // Using a JWT
-    }}
-  >
-    {/* ... */}
-    {children}
-  </LiveStoreProvider>
-)
-```
-
-On the sync server, validate the token and allow or reject the sync based on the result. See the following example:
-
-## `patterns/auth/pass-auth-payload.ts`
-
-```ts filename="patterns/auth/pass-auth-payload.ts"
-
-const JWT_SECRET = 'a-string-secret-at-least-256-bits-long'
-
-export class SyncBackendDO extends makeDurableObject({
-  onPush: async (message) => {
-    console.log('onPush', message.batch)
-  },
-  onPull: async (message) => {
-    console.log('onPull', message)
-  },
-}) {}
-
-export default makeWorker({
-  syncBackendBinding: 'SYNC_BACKEND_DO',
-  validatePayload: async (payload: any, context) => {
-    const { storeId } = context
-    const { authToken } = payload
-
-    if (!authToken) {
-      throw new Error('No auth token provided')
-    }
-
-    const user = await getUserFromToken(authToken)
-
-    if (!user) {
-      throw new Error('Invalid auth token')
-    } else {
-      // User is authenticated!
-      console.log('Sync backend payload', JSON.stringify(user, null, 2))
-    }
-
-    // Check if token is expired
-    if (payload.exp && payload.exp < Date.now() / 1000) {
-      throw new Error('Token expired')
-    }
-
-    await checkUserAccess(user, storeId)
-  },
-  enableCORS: true,
-})
-
-async function getUserFromToken(token: string): Promise<jose.JWTPayload | undefined> {
-  try {
-    const { payload } = await jose.jwtVerify(token, new TextEncoder().encode(JWT_SECRET))
-    return payload
-  } catch (error) {
-    console.log('⚠️ Error verifying token', error)
-  }
-}
-
-async function checkUserAccess(payload: jose.JWTPayload, storeId: string): Promise<void> {
-  // Check if user is authorized to access the store
-  console.log('Checking access for store', storeId, 'with payload', payload)
-}
-```
-
-The above example uses [`jose`](https://www.npmjs.com/package/jose), a popular JavaScript module that supports JWTs. It works across various runtimes, including Node.js, Cloudflare Workers, Deno, Bun, and others.
-
-The `validatePayload` function receives the `authToken`, checks if the payload exists, and verifies that it's valid and hasn't expired. If all checks pass, sync continues as normal. If any check fails, the server rejects the sync.
-
-The client app still works as expected, but saves data locally. If the user re-authenticates or refreshes the token later, LiveStore syncs any local changes made while the user was unauthenticated.
-
-## Re-validate payload inside the Durable Object
-
-When you rely on `syncPayload`, treat it as untrusted input. Decode the token inside `validatePayload` to gate the connection, and then repeat the same verification inside the Durable Object before trusting per-push metadata.
-
-## `patterns/auth/keep-payload-canonical.ts`
-
-```ts filename="patterns/auth/keep-payload-canonical.ts"
-
-// ---cut---
-type SyncPayload = { authToken?: string; userId?: string }
-
-type AuthorizedSession = {
-  authToken: string
-  userId: string
-}
-
-const ensureAuthorized = (payload: unknown): AuthorizedSession => {
-  if (payload === undefined || payload === null || typeof payload !== 'object') {
-    throw new Error('Missing auth payload')
-  }
-
-  const { authToken, userId } = payload as SyncPayload
-  if (!authToken) {
-    throw new Error('Missing auth token')
-  }
-
-  const claims = verifyJwt(authToken)
-  if (!claims.sub) {
-    throw new Error('Token missing subject claim')
-  }
-
-  if (userId !== undefined && userId !== claims.sub) {
-    throw new Error('Payload userId mismatch')
-  }
-
-  return { authToken, userId: claims.sub }
-}
-
-export default makeWorker({
-  syncBackendBinding: 'SYNC_BACKEND_DO',
-  validatePayload: (payload) => {
-    ensureAuthorized(payload)
-  },
-})
-
-export class SyncBackendDO extends makeDurableObject({
-  onPush: async (message: SyncMessage.PushRequest, { payload }) => {
-    const { userId } = ensureAuthorized(payload)
-    await ensureTenantAccess(userId, message.batch)
-  },
-}) {}
-
-const ensureTenantAccess = async (_userId: string, _batch: SyncMessage.PushRequest['batch']) => {
-  // Replace with your application-specific access checks.
-}
-```
-
-### `patterns/auth/verify-jwt.ts`
-
-```ts filename="patterns/auth/verify-jwt.ts"
-export type Claims = {
-  sub?: string
-}
-
-export const verifyJwt = (token: string): Claims => {
-  if (token.length === 0) {
-    throw new Error('Missing token')
-  }
-
-  // Replace with real JWT verification (e.g. via `jose`)
-  return { sub: token }
-}
-```
-
-- `validatePayload` runs once per connection and rejects mismatched tokens before LiveStore upgrades to WebSocket.
-- `onPush` (and `onPull`, if you need it) must repeat the verification because the payload forwarded to the Durable Object is the original client input.
-- The HTTP transport does not forward payloads today; embed the necessary authorization context directly in the events or move those clients to WebSocket/DO-RPC if you must rely on shared payload metadata.
-
-You can extend `ensureAuthorized` to project additional claims, memoise verification per `authToken`, or enforce application-specific policies without changing LiveStore internals.
-
-## Client identity vs user identity
-
-LiveStore's `clientId` identifies a client instance, while user identity is an application-level concern that must be modeled through your application's events and logic.
-
-### Key points
-- `clientId`: Automatically managed by LiveStore, identifies a client instance
-- User identity: Managed by your application through events and syncPayload
-
-### Using syncPayload for authentication
-
-The `syncPayload` is primarily intended for authentication purposes:
-
-## `patterns/auth/live-store-provider.tsx`
-
-```tsx filename="patterns/auth/live-store-provider.tsx"
-
-const schema = {} as Parameters<typeof LiveStoreProvider>[0]['schema']
-const storeId = 'demo-store'
-const user = { jwt: 'user-token' }
-const children: ReactNode = null
-const adapter = makeInMemoryAdapter()
-
-// ---cut---
-export const AuthenticatedProvider = () => (
-  <LiveStoreProvider
-    schema={schema}
-    storeId={storeId}
-    adapter={adapter}
-    batchUpdates={batchUpdates}
-    syncPayload={{
-      authToken: user.jwt, // Using a JWT
-    }}
-  >
-    {/* ... */}
-    {children}
-  </LiveStoreProvider>
-)
-```
-
-User identification and semantic data (like user IDs) should typically be handled through your event payloads and application state rather than relying solely on the sync payload.