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

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

@@ -1,111 +0,0 @@
-# Why LiveStore?
-
-## The problem LiveStore solves
-
-Building modern apps with great UX means handling a lot of complexity:
-
-- **State management**: Keeping UI in sync with data
-- **Persistence**: Surviving refreshes and app restarts  
-- **Offline support**: Working without a network connection
-- **Real-time sync**: Reflecting changes across devices instantly
-- **Conflict resolution**: Handling concurrent edits gracefully
-
-Traditionally, each of these concerns requires separate solutions—a state library, local storage, a sync service, optimistic update logic, retry queues. These pieces don't naturally fit together, leading to complex, fragile code and subtle bugs.
-
-LiveStore provides a _unified architecture_ that handles all of these concerns through one coherent model: event sourcing.
-
-As a positive side-effect, the simplicity of LiveStore's event-driven abstractions also leads to a superior DX compared to the traditional ways of dealing with state.
-
-## What makes LiveStore different
-
-### A real database, not just a cache
-
-Most state management tools treat local data as a _cache_ of server state. This introduces complexity that's hard to manage due to the inherent intricacies of caching.
-
-LiveStore flips this: your local SQLite database is the primary data source, and the server is just a sync target to which data is distributed automatically.
-
-<SourceOfTruthDiagram class="my-8" />
-
-This means:
-- **No loading states for reads**—queries execute synchronously against local SQLite
-- **Full SQL power**—joins, aggregations, complex filters, all instant
-- **Offline by default**—your app works the same whether online or not
-
-### Events as the source of truth
-
-Instead of syncing mutable state (which leads to "who wins?" conflicts), LiveStore syncs an append-only log of events. This is fundamentally easier to reason about:
-
-- Events merge naturally—you're combining histories, not reconciling states
-- Every change is auditable—you have a complete record of what happened
-- State is always rebuildable—replay events to reconstruct any point in time
-
-### Sync that actually works
-
-LiveStore includes a battle-tested sync engine that handles the hard problems:
-
-- **Optimistic updates**: Changes appear instantly, sync happens in the background
-- **Automatic offline queue**: Events committed offline sync when connectivity returns  
-- **Deterministic conflict resolution**: Same events always produce the same state
-- **Pluggable backends**: Use Cloudflare, ElectricSQL, or build your own
-
-### Built for demanding apps
-
-LiveStore was developed as the foundation for [Overtone](https://overtone.pro), a professional music application requiring 120fps performance with complex, real-time collaborative state. It's designed for apps where performance and reliability aren't negotiable.
-
-### Open-source: By developers, for developers
-
-LiveStore is entirely open-source. There is no company behind it and it's only possible through its generous [sponsors](/sustainable-open-source/sponsoring).
-
-## LiveStore vs. the alternatives
-
-### vs. State management libraries (Redux, Zustand, MobX)
-
-These solve state management but not persistence or sync. You'll need to add:
-- Local storage or IndexedDB for persistence
-- A sync layer for real-time updates
-- Optimistic update logic
-- Offline queue management
-
-LiveStore handles all of this out of the box.
-
-### vs. Backend-as-a-Service (Firebase, Supabase)
-
-These provide sync but treat the server as the source of truth. The consequences are:
-- Reads require network round-trips (or complex caching)
-- Offline support is limited or requires significant extra work
-- You're locked into their data model and pricing
-
-LiveStore is client-first, works fully offline, and syncs via any backend you choose.
-
-### vs. Other local-first solutions (ElectricSQL, Zero, PowerSync)
-
-These are excellent if you have an existing Postgres database you want to sync to clients. LiveStore is better when:
-- You're building a new app without legacy data
-- You want event sourcing semantics (not just row-level sync)
-- You need the flexibility to materialize state in different ways
-
-See the [local-first landscape](https://localfirst.fm/landscape) for a comprehensive comparison.
-
-## A great developer experience (DX)
-
-LiveStore is designed to make the right thing easy:
-
-- **Type-safe schema**: Your events, tables, and queries are fully typed
-- **Reactive by default**: UI updates automatically when data changes
-- **Powerful devtools**: Inspect state, browse events, time-travel debug
-- **Cross-platform**: Same mental model on web, mobile, desktop, and server
-
-## When to choose LiveStore
-
-**Choose LiveStore if:**
-- You're building a new app that should work offline
-- You want a unified solution for state, persistence, and sync
-- Your app has complex local state that benefits from SQL queries
-- You value auditability and the ability to replay/debug state changes
-
-**Consider alternatives if:**
-- You need to sync with an existing server database
-- Your data won't fit in client memory
-- You're building a traditional request/response app without offline needs
-
-Still unsure? Try the [evaluation exercise](/overview/when-livestore#evaluation-exercise) to model your app's events and see if it feels natural.

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,377 +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/store-with-auth.tsx`
-
-```tsx filename="patterns/auth/store-with-auth.tsx"
-
-const schema = {} as LiveStoreSchema
-const storeId = 'demo-store'
-const user = { jwt: 'user-token' }
-const adapter = makeInMemoryAdapter()
-
-// ---cut---
-const useAppStore = () =>
-  useStore({
-    storeId,
-    schema,
-    adapter,
-    batchUpdates,
-    syncPayload: {
-      authToken: user.jwt, // Using a JWT
-    },
-  })
-
-export const App = () => {
-  const [storeRegistry] = useState(() => new StoreRegistry())
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <StoreRegistryProvider storeRegistry={storeRegistry}>
-        <AppContent />
-      </StoreRegistryProvider>
-    </Suspense>
-  )
-}
-
-const AppContent = () => {
-  const _store = useAppStore()
-  // Use the store in your components
-  return <div>{/* Your app content */}</div>
-}
-```
-
-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.
-
-## Cookie-based authentication
-
-If you prefer cookie-based authentication (e.g., with [better-auth](https://www.better-auth.com/)), you can forward HTTP headers to your `onPush` and `onPull` callbacks using the `forwardHeaders` option.
-
-### Why forward headers?
-
-Passing tokens in URL parameters (`syncPayload`) exposes them in browser history, server logs, and referrer headers. Cookie-based auth avoids these issues since cookies are sent automatically with each request and aren't logged in URLs.
-
-### Example
-
-The following example forwards `Cookie` and `Authorization` headers to the Durable Object callbacks:
-
-## `patterns/auth/cookie-auth.ts`
-
-```ts filename="patterns/auth/cookie-auth.ts"
-
-export class SyncBackendDO extends makeDurableObject({
-  // Forward Cookie and Authorization headers to onPush/onPull callbacks
-  forwardHeaders: ['Cookie', 'Authorization'],
-
-  onPush: async (message, context) => {
-    const { storeId, headers } = context
-
-    // Access forwarded headers in callbacks
-    const cookie = headers?.get('cookie')
-    const _authorization = headers?.get('authorization')
-
-    if (cookie) {
-      // Parse session from cookie (example with better-auth)
-      const sessionToken = parseCookie(cookie, 'session_token')
-      const session = await getSessionFromToken(sessionToken)
-
-      if (!session) {
-        throw new Error('Invalid session')
-      }
-
-      console.log('Push from user:', session.userId, 'store:', storeId)
-    }
-
-    console.log('onPush', message.batch)
-  },
-
-  onPull: async (message, context) => {
-    const { storeId, headers } = context
-
-    // Same header access in onPull
-    const cookie = headers?.get('cookie')
-
-    if (cookie) {
-      const sessionToken = parseCookie(cookie, 'session_token')
-      const session = await getSessionFromToken(sessionToken)
-
-      if (!session) {
-        throw new Error('Invalid session')
-      }
-
-      console.log('Pull from user:', session.userId, 'store:', storeId)
-    }
-
-    console.log('onPull', message)
-  },
-}) {}
-
-export default makeWorker({
-  syncBackendBinding: 'SYNC_BACKEND_DO',
-  // Optional: validate at worker level using headers
-  validatePayload: async (_payload, context) => {
-    const { headers } = context
-    const cookie = headers.get('cookie')
-
-    if (cookie) {
-      const sessionToken = parseCookie(cookie, 'session_token')
-      const session = await getSessionFromToken(sessionToken)
-
-      if (!session) {
-        throw new Error('Unauthorized: Invalid session')
-      }
-    }
-  },
-  enableCORS: true,
-})
-
-// --- Helper functions (implement based on your auth library) ---
-
-function parseCookie(cookieHeader: string, name: string): string | undefined {
-  const cookies = cookieHeader.split(';').map((c) => c.trim())
-  for (const cookie of cookies) {
-    const [key, value] = cookie.split('=')
-    if (key === name) return value
-  }
-  return undefined
-}
-
-interface Session {
-  userId: string
-  email: string
-}
-
-async function getSessionFromToken(_token: string | undefined): Promise<Session | null> {
-  // Implement session lookup using your auth library
-  // Example with better-auth:
-  // return await auth.api.getSession({ headers: { cookie: `session_token=${token}` } })
-  return { userId: 'user-123', email: 'user@example.com' }
-}
-```
-
-### How it works
-
-1. **Configure `forwardHeaders`** in `makeDurableObject()` to specify which headers to forward.
-2. **Headers are stored** in the WebSocket attachment during connection upgrade, surviving hibernation.
-3. **Access headers** via `context.headers` in `onPush` and `onPull` callbacks.
-4. **Worker-level validation** can also access headers via `context.headers` in `validatePayload`.
-
-### Custom header extraction
-
-For more control, pass a function to `forwardHeaders`:
-
-```typescript
-export class SyncBackendDO extends makeDurableObject({
-  forwardHeaders: (request) => ({
-    'x-user-id': request.headers.get('x-user-id') ?? '',
-    'x-session': request.headers.get('cookie')?.split('session=')[1]?.split(';')[0] ?? '',
-  }),
-  // ...
-}) {}
-```
-
-## 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/store-with-auth.tsx`
-
-```tsx filename="patterns/auth/store-with-auth.tsx"
-
-const schema = {} as LiveStoreSchema
-const storeId = 'demo-store'
-const user = { jwt: 'user-token' }
-const adapter = makeInMemoryAdapter()
-
-// ---cut---
-const useAppStore = () =>
-  useStore({
-    storeId,
-    schema,
-    adapter,
-    batchUpdates,
-    syncPayload: {
-      authToken: user.jwt, // Using a JWT
-    },
-  })
-
-export const App = () => {
-  const [storeRegistry] = useState(() => new StoreRegistry())
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <StoreRegistryProvider storeRegistry={storeRegistry}>
-        <AppContent />
-      </StoreRegistryProvider>
-    </Suspense>
-  )
-}
-
-const AppContent = () => {
-  const _store = useAppStore()
-  // Use the store in your components
-  return <div>{/* Your app content */}</div>
-}
-```
-
-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.