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

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

@@ -0,0 +1,111 @@
+# 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/app-evolution/index.md

@@ -1,4 +1,4 @@
-# App Evolution
+# App evolution
 
 When building an app with LiveStore, you'll need to keep some things in mind when evolving your app.
 
@@ -10,7 +10,7 @@ Generally any kind of changes to your state schema (e.g. SQLite tables, ...) can
 
 ### 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](/reference/events/#schema-evolution) for more details.
+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
 

package/docs/patterns/auth/index.md

@@ -10,31 +10,43 @@ Use the `syncPayload` store option to send a custom payload to your sync backend
 
 The following example sends the authenticated user's JWT to the server.
 
-## `patterns/auth/live-store-provider.tsx`
+## `patterns/auth/store-with-auth.tsx`
 
-```tsx filename="patterns/auth/live-store-provider.tsx"
+```tsx filename="patterns/auth/store-with-auth.tsx"
 
-const schema = {} as Parameters<typeof LiveStoreProvider>[0]['schema']
+const schema = {} as LiveStoreSchema
 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={{
+const useAppStore = () =>
+  useStore({
+    storeId,
+    schema,
+    adapter,
+    batchUpdates,
+    syncPayload: {
       authToken: user.jwt, // Using a JWT
-    }}
-  >
-    {/* ... */}
-    {children}
-  </LiveStoreProvider>
-)
+    },
+  })
+
+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:
@@ -184,43 +196,182 @@ export const verifyJwt = (token: string): Claims => {
 
 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
+## 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
+### 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
+### Using syncPayload for authentication
 
 The `syncPayload` is primarily intended for authentication purposes:
 
-## `patterns/auth/live-store-provider.tsx`
+## `patterns/auth/store-with-auth.tsx`
 
-```tsx filename="patterns/auth/live-store-provider.tsx"
+```tsx filename="patterns/auth/store-with-auth.tsx"
 
-const schema = {} as Parameters<typeof LiveStoreProvider>[0]['schema']
+const schema = {} as LiveStoreSchema
 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={{
+const useAppStore = () =>
+  useStore({
+    storeId,
+    schema,
+    adapter,
+    batchUpdates,
+    syncPayload: {
       authToken: user.jwt, // Using a JWT
-    }}
-  >
-    {/* ... */}
-    {children}
-  </LiveStoreProvider>
-)
+    },
+  })
+
+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.

package/docs/patterns/effect/index.md

@@ -2,6 +2,16 @@
 
 LiveStore itself is built on top of [Effect](https://effect.website) which is a powerful library to write production-grade TypeScript code. It's also possible (and recommended) to use Effect directly in your application code.
 
+## Store context for Effect
+
+For applications built with Effect, LiveStore provides `makeStoreContext()` - a factory that creates typed store contexts for the Effect layer system. This preserves your schema types through Effect's dependency injection and supports multiple stores.
+
+See the [Store Effect integration](/building-with-livestore/store#effect-integration) section for details on:
+- Creating typed store contexts
+- Using stores in Effect services
+- Layer composition patterns
+- Multiple stores in the same app
+
 ## Schema
 
 LiveStore uses the [Effect Schema](https://effect.website/docs/schema/introduction/) library to define schemas for the following:
@@ -16,7 +26,7 @@ For convenience, LiveStore re-exports the `Schema` module from the `effect` pack
 
 LiveStore's reactive primitives (`LiveQueryDef` and `SignalDef`) implement Effect's `Equal` and `Hash` traits, enabling efficient integration with Effect's data structures and collections.
 
-## Effect Atom Integration
+## Effect atom integration
 
 LiveStore integrates seamlessly with [Effect Atom](https://github.com/effect-atom/effect-atom) for reactive state management in React applications. This provides a powerful combination of Effect's functional programming capabilities with LiveStore's event sourcing and CQRS patterns.
 
@@ -28,7 +38,7 @@ Effect Atom is an external package developed by [Tim Smart](https://github.com/t
 pnpm install @effect-atom/atom-livestore @effect-atom/atom-react
 ```
 
-### Store Creation
+### Store creation
 
 Create a LiveStore-backed atom store with persistence and worker support using the `AtomLivestore.Tag` pattern:
 
@@ -202,7 +212,7 @@ The `StoreTag` class provides the following static methods:
 - `StoreTag.makeQuery` - Create query atoms with Effect
 - `StoreTag.makeQueryUnsafe` - Create query atoms without Effect
 
-### Defining Query Atoms
+### Defining query atoms
 
 Create reactive query atoms that automatically update when the underlying data changes:
 
@@ -428,9 +438,9 @@ export const pendingTodosAtom = Atom.make<PendingTodo[]>([])
 export const pendingUsersAtom = Atom.make<PendingUser[]>([])
 ```
 
-### Using Queries in React Components
+### Using queries in React components
 
-Access query results in React components with the `useAtomValue` hook. When using `StoreTag.makeQuery` (non-unsafe API), the result is wrapped in a Result type for proper loading and error handling:
+Access query results in React components with the `useAtomValue()` hook. When using `StoreTag.makeQuery` (non-unsafe API), the result is wrapped in a Result type for proper loading and error handling:
 
 ## `patterns/effect/store-setup/user-list.tsx`
 
@@ -675,7 +685,7 @@ export const pendingTodosAtom = Atom.make<PendingTodo[]>([])
 export const pendingUsersAtom = Atom.make<PendingUser[]>([])
 ```
 
-### Integrating Effect Services
+### Integrating Effect services
 
 Combine Effect services with LiveStore operations using the store's runtime:
 
@@ -891,9 +901,9 @@ export const schema = makeSchema({ events, state })
 export { tables }
 ```
 
-### Advanced Patterns
+### Advanced patterns
 
-#### Optimistic Updates
+#### Optimistic updates
 
 Combine local state with LiveStore for optimistic UI updates. When using `StoreTag.makeQueryUnsafe`, the data is directly available:
 
@@ -1091,7 +1101,7 @@ export const pendingTodosAtom = Atom.make<PendingTodo[]>([])
 export const pendingUsersAtom = Atom.make<PendingUser[]>([])
 ```
 
-#### Derived State
+#### Derived state
 
 Create computed atoms based on LiveStore queries. When using the non-unsafe API, handle the Result type:
 
@@ -1292,7 +1302,7 @@ export const pendingTodosAtom = Atom.make<PendingTodo[]>([])
 export const pendingUsersAtom = Atom.make<PendingUser[]>([])
 ```
 
-#### Batch Operations
+#### Batch operations
 
 Perform multiple commits efficiently (commits are synchronous):
 
@@ -1476,7 +1486,7 @@ export const schema = makeSchema({ events, state })
 export { tables }
 ```
 
-### Best Practices
+### Best practices
 
 1. **Use `StoreTag.makeQuery` for queries**: This ensures proper Effect integration and error handling
 2. **Leverage Effect services**: Integrate business logic through Effect services for better testability

package/docs/patterns/external-data/index.md

@@ -1,4 +1,4 @@
-# External Data
+# External data
 
 LiveStore doesn't provide any built-in functionality to deal with external data. However, LiveStore was designed with this use case in mind (e.g. Overtone integrates with lots of external data like Spotify, ...). One way to deal with external data is to also model it as an event log and materialize it into LiveStore state as well.
 

package/docs/patterns/file-management/index.md

@@ -1,4 +1,4 @@
-# File Management
+# File management
 
 LiveStore doesn't have built-in support for file management but it's easy to use LiveStore alongside existing file storage solutions (e.g. S3).
 

package/docs/patterns/file-structure/index.md

@@ -1,4 +1,4 @@
-# File Structure
+# File structure
 
 While there are no strict requirements/conventions for how to structure your project (files, folders, etc), a common pattern is to have a `src/livestore` folder which contains all the LiveStore related code.
 

package/docs/patterns/offline/index.md

@@ -1,4 +1,4 @@
-# Offline Support
+# Offline support
 
 - LiveStore supports offline data management out of the box. In order to make your app work fully offline, you might need to also consider the following:
   - Design your app in a way to treat the network as an optional feature (e.g. when relying on other APIs / external data)

package/docs/patterns/rich-text-editing/index.md

@@ -1,66 +1,11 @@
-# Rich Text Editing
+# Rich text editing
 
-LiveStore doesn't yet have built-in rich text primitives. It's currently recommended to pair LiveStore with a CRDT library (e.g. [Yjs](https://yjs.dev/), [Automerge](https://automerge.org/), or [Loro](https://loro.dev/)). LiveStore stores a reference (URL/ID) to the CRDT document in its event log. The CRDT library owns the text content and syncs it over its own transport. Both systems sync in parallel. LiveStore handles metadata while the CRDT library handles document bytes.
+LiveStore doesn't yet have any built-in support for rich text editing. It's currently recommended to use a purpose-built library (e.g. [Yjs](https://yjs.dev/) or [Automerge](https://automerge.org/)) for this use case in combination with LiveStore.
 
-## Example: linking a note to an Automerge document
+The idea here is to reference the rich text document from within LiveStore's event log and sync both in parallel.
 
-## `patterns/rich-text-editing/crdt-link.tsx`
+## Example
 
-```tsx filename="patterns/rich-text-editing/crdt-link.tsx"
-
-declare const store: Store
-
-type NoteDoc = { body: string }
-
-// ---cut---
-
-export const note = State.SQLite.table({
-  name: 'note',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    title: State.SQLite.text({ default: '' }),
-    crdtDocUrl: State.SQLite.text({ nullable: false, default: '' }),
-  },
-})
-
-export type Note = typeof note.Type
-export const tables = { note }
-
-export const events = {
-  createNote: Events.synced({
-    name: 'v1.CreateNote',
-    schema: Schema.Struct({
-      noteId: Schema.String,
-      title: Schema.String,
-      crdtDocUrl: Schema.String,
-    }),
-  }),
-}
-
-export const getNoteCrdtRef = (noteId: string): string | undefined => {
-  return store.query(tables.note.select('crdtDocUrl').where({ id: noteId }))[0]
-}
-
-function Editor({ noteCrdtUrl }: { noteCrdtUrl: string }) {
-  const docUrl = noteCrdtUrl as AutomergeUrl
-  const [doc, changeDoc] = useDocument<NoteDoc>(docUrl, { suspense: true })
-
-  return (
-    <textarea
-      value={doc?.body ?? ''}
-      onChange={(event) =>
-        changeDoc((draft: NoteDoc) => {
-          updateText(draft, ['body'], event.target.value)
-        })
-      }
-    />
-  )
-}
-
-export function RichTextNoteEditor({ noteId }: { noteId: string }) {
-  const noteCrdtUrl = getNoteCrdtRef(noteId)
-  if (!noteCrdtUrl) return null
-
-  return <Editor noteCrdtUrl={noteCrdtUrl} />
-}
+```ts
+// TODO
 ```