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

package/docs/patterns/storybook/index.md

@@ -1,192 +0,0 @@
-# Storybook testing (React)
-
-export const CODE = {
-  todoInputStories: `import type { Meta, StoryObj } from '@storybook/react'
-
-const meta: Meta<typeof TodoInput> = {
-  title: 'TodoMVC/TodoInput',
-  component: TodoInput,
-}
-
-export default meta
-type Story = StoryObj<typeof TodoInput>
-
-export const Default: Story = {}
-
-export const WithInitialText: Story = {
-  decorators: [
-    createLiveStoreDecorator([
-      events.uiStateSet({ newTodoText: 'Buy groceries' })
-    ])
-  ],
-}`,
-  
-  storybookPreview: `import React from 'react'
-
-// Default decorator with no seed data
-const LiveStoreDecorator = createLiveStoreDecorator()
-
-export const decorators = [LiveStoreDecorator]`,
-
-  decorator: `import React from 'react'
-
-// Create LiveStore decorator with optional seeding
-export const createLiveStoreDecorator = (seedEvents = []) => (Story) => {
-  const onBoot = (store) => {
-    // Seed data through events during boot
-    if (seedEvents.length > 0) {
-      store.commit(...seedEvents)
-    }
-  }
-
-  return (
-    <LiveStoreProvider
-      schema={schema}
-      adapter={makeInMemoryAdapter()}
-      batchUpdates={batchUpdates}
-      boot={onBoot}
-      renderLoading={(status) => <div>Loading LiveStore ({status.stage})...</div>}
-    >
-      <Story />
-    </LiveStoreProvider>
-  )
-}`,
-
-  todoInput: `import React from 'react'
-
-// Define queries (like in TodoMVC)
-const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })
-
-export const TodoInput = () => {
-  const { store } = useStore()
-  const { newTodoText } = store.useQuery(uiState$)
-
-  const updateNewTodoText = (text: string) => 
-    store.commit(events.uiStateSet({ newTodoText: text }))
-
-  const createTodo = () => {
-    if (newTodoText.trim()) {
-      store.commit(
-        events.todoCreated({ id: crypto.randomUUID(), text: newTodoText }),
-        events.uiStateSet({ newTodoText: '' }),
-      )
-    }
-  }
-
-  return (
-    <div>
-      <h2>Add Todo</h2>
-      <input
-        type="text"
-        placeholder="What needs to be done?"
-        value={newTodoText}
-        onChange={(e) => updateNewTodoText(e.target.value)}
-        onKeyDown={(e) => {
-          if (e.key === 'Enter') {
-            createTodo()
-          }
-        }}
-      />
-      <button onClick={createTodo}>
-        Add
-      </button>
-    </div>
-  )
-}`,
-
-  schema: `import { Events, makeSchema, Schema, SessionIdSymbol, State } from '@livestore/livestore'
-
-// Define tables (based on TodoMVC example)
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text({ default: '' }),
-      completed: State.SQLite.boolean({ default: false }),
-      deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }),
-    },
-  }),
-  // Client document for UI state
-  uiState: State.SQLite.clientDocument({
-    name: 'uiState',
-    schema: Schema.Struct({ 
-      newTodoText: Schema.String, 
-      filter: Schema.Literal('all', 'active', 'completed') 
-    }),
-    default: { 
-      id: SessionIdSymbol, 
-      value: { newTodoText: '', filter: 'all' } 
-    },
-  }),
-}
-
-// Define events (exactly from TodoMVC)
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-  todoCompleted: Events.synced({
-    name: 'v1.TodoCompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoUncompleted: Events.synced({
-    name: 'v1.TodoUncompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoDeleted: Events.synced({
-    name: 'v1.TodoDeleted',
-    schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
-  }),
-  todoClearedCompleted: Events.synced({
-    name: 'v1.TodoClearedCompleted',
-    schema: Schema.Struct({ deletedAt: Schema.Date }),
-  }),
-  // Auto-generated client document event
-  uiStateSet: tables.uiState.set,
-}
-
-// Define materializers to map events to state
-const materializers = State.SQLite.materializers(events, {
-  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }),
-  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
-  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
-  'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }),
-  'v1.TodoClearedCompleted': ({ deletedAt }) => tables.todos.update({ deletedAt }).where({ completed: true }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })`
-}
-
-LiveStore works seamlessly with Storybook for React component development and testing.
-
-**Note:** This guide focuses on React. For other frameworks, adapt patterns accordingly.
-
-## Setup
-
-First, [install Storybook](https://storybook.js.org/docs/get-started/install) in your React project.
-
-## Configuration
-
-Create a decorator that wraps stories with a fresh LiveStore instance and use the TodoMVC schema for realistic examples.
-
-<Tabs>
-<TabItem label="Stories">
-<Code code={CODE.todoInputStories} lang="tsx" title="src/TodoInput.stories.tsx" />
-</TabItem>
-<TabItem label="Storybook Config">
-<Code code={CODE.storybookPreview} lang="js" title=".storybook/preview.js" />
-</TabItem>
-<TabItem label="Decorator">
-<Code code={CODE.decorator} lang="js" title="src/decorator.js" />
-</TabItem>
-<TabItem label="Component">
-<Code code={CODE.todoInput} lang="tsx" title="src/TodoInput.tsx" />
-</TabItem>
-<TabItem label="Schema">
-<Code code={CODE.schema} lang="ts" title="src/schema.ts" />
-</TabItem>
-</Tabs>

package/docs/patterns/undo-redo/index.md

@@ -1,9 +0,0 @@
-# Undo/Redo
-
-Undo/redo functionality should be generally modeled through explicit events instead of "removing" events from the event history.
-
-## Example
-
-```ts
-// TODO (contribution welcome)
-```

package/docs/patterns/version-control/index.md

@@ -1,8 +0,0 @@
-# Version control
-
-LiveStore's event sourcing approach allows you to implement version control functionality in your application (similar to Git but for your application domain). This could include features like:
-
-- Branching
-- Semantic commit messages & grouping
-- History tracking
-- Semantic/interactive merges

package/docs/platform-adapters/cloudflare-durable-object-adapter/index.md

@@ -1,453 +0,0 @@
-# Cloudflare Durable Object adapter
-
-The Cloudflare Durable Object adapter enables running LiveStore applications on Cloudflare Workers with stateful Durable Objects for synchronized real-time data.
-
-## Installation
-
-```bash
-pnpm add @livestore/adapter-cloudflare @livestore/sync-cf
-```
-
-## Configuration
-
-### Wrangler configuration
-
-Configure your `wrangler.toml` with the required Durable Object bindings:
-
-```toml
-name = "my-livestore-app"
-main = "./src/worker.ts"
-compatibility_date = "2025-05-07"
-compatibility_flags = [
-  "enable_request_signal", # Required for HTTP RPC streams
-]
-
-[[durable_objects.bindings]]
-name = "SYNC_BACKEND_DO"
-class_name = "SyncBackendDO"
-
-[[durable_objects.bindings]]
-name = "CLIENT_DO"
-class_name = "LiveStoreClientDO"
-
-[[migrations]]
-tag = "v1"
-new_sqlite_classes = ["SyncBackendDO", "LiveStoreClientDO"]
-
-[[d1_databases]]
-binding = "DB"
-database_name = "my-livestore-db"
-database_id = "your-database-id"
-```
-
-### Environment types
-
-Define your Worker bindings so TypeScript can guide you when wiring Durable Objects:
-
-## `reference/platform-adapters/cloudflare/env.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/env.ts"
-
-export type Env = {
-  CLIENT_DO: CfTypes.DurableObjectNamespace<ClientDoWithRpcCallback>
-  SYNC_BACKEND_DO: CfTypes.DurableObjectNamespace<SyncBackendRpcInterface>
-  DB: CfTypes.D1Database
-}
-```
-
-We also use a small helper to extract the store identifier from incoming requests:
-
-## `reference/platform-adapters/cloudflare/shared.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/shared.ts"
-
-export const storeIdFromRequest = (request: CfTypes.Request) => {
-  const url = new URL(request.url)
-  const storeId = url.searchParams.get('storeId')
-
-  if (storeId === null) {
-    throw new Error('storeId is required in URL search params')
-  }
-
-  return storeId
-}
-```
-
-## Basic setup
-
-### 1. Create the sync backend Durable Object
-
-The sync backend handles pushing and pulling events between clients:
-
-## `reference/platform-adapters/cloudflare/sync-backend.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/sync-backend.ts"
-
-export class SyncBackendDO extends SyncBackend.makeDurableObject({
-  // Optional: Handle push events
-  // onPush: async (message, { storeId }) => {
-  //   console.log(`onPush for store (${storeId})`, message.batch)
-  // },
-}) {}
-```
-
-### 2. Create the client Durable Object
-
-Each client Durable Object hosts a LiveStore instance and exposes DO RPC callbacks:
-
-## `reference/platform-adapters/cloudflare/client-do.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/client-do.ts"
-/// <reference types="@cloudflare/workers-types" />
-
-type AlarmInfo = {
-  isRetry: boolean
-  retryCount: number
-}
-
-export class LiveStoreClientDO extends DurableObject<Env> implements ClientDoWithRpcCallback {
-  __DURABLE_OBJECT_BRAND: never = undefined as never
-
-  private storeId: string | undefined
-  private cachedStore: Store<typeof schema> | undefined
-  private storeSubscription: Unsubscribe | undefined
-  private readonly todosQuery = tables.todos.select()
-
-  async fetch(request: Request): Promise<Response> {
-    // @ts-expect-error TODO remove casts once CF types are fixed in https://github.com/cloudflare/workerd/issues/4811
-    this.storeId = storeIdFromRequest(request)
-
-    const store = await this.getStore()
-    await this.subscribeToStore()
-
-    const todos = store.query(this.todosQuery)
-    return new Response(JSON.stringify(todos, null, 2), {
-      headers: { 'Content-Type': 'application/json' },
-    })
-  }
-
-  private async getStore() {
-    if (this.cachedStore !== undefined) {
-      return this.cachedStore
-    }
-
-    const storeId = this.storeId ?? nanoid()
-
-    const store = await createStoreDoPromise({
-      schema,
-      storeId,
-      clientId: 'client-do',
-      sessionId: nanoid(),
-      durableObject: {
-        // @ts-expect-error TODO remove once CF types are fixed in https://github.com/cloudflare/workerd/issues/4811
-        ctx: this.ctx,
-        env: this.env,
-        bindingName: 'CLIENT_DO',
-      },
-      syncBackendStub: this.env.SYNC_BACKEND_DO.get(this.env.SYNC_BACKEND_DO.idFromName(storeId)),
-      livePull: true,
-    })
-
-    this.cachedStore = store
-    return store
-  }
-
-  private async subscribeToStore() {
-    const store = await this.getStore()
-
-    if (this.storeSubscription === undefined) {
-      this.storeSubscription = store.subscribe(this.todosQuery, (todos: ReadonlyArray<typeof tables.todos.Type>) => {
-        console.log(`todos for store (${this.storeId})`, todos)
-      })
-    }
-
-    await this.ctx.storage.setAlarm(Date.now() + 1000)
-  }
-
-  alarm(_alarmInfo?: AlarmInfo): void | Promise<void> {
-    return this.subscribeToStore()
-  }
-
-  async syncUpdateRpc(payload: unknown) {
-    await handleSyncUpdateRpc(payload)
-  }
-}
-```
-
-### `reference/platform-adapters/cloudflare/env.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/env.ts"
-
-export type Env = {
-  CLIENT_DO: CfTypes.DurableObjectNamespace<ClientDoWithRpcCallback>
-  SYNC_BACKEND_DO: CfTypes.DurableObjectNamespace<SyncBackendRpcInterface>
-  DB: CfTypes.D1Database
-}
-```
-
-### `reference/platform-adapters/cloudflare/schema.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text({ default: '' }),
-      completed: State.SQLite.boolean({ default: false }),
-      deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }),
-    },
-  }),
-}
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-  todoCompleted: Events.synced({
-    name: 'v1.TodoCompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoUncompleted: Events.synced({
-    name: 'v1.TodoUncompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoDeleted: Events.synced({
-    name: 'v1.TodoDeleted',
-    schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
-  }),
-  todoClearedCompleted: Events.synced({
-    name: 'v1.TodoClearedCompleted',
-    schema: Schema.Struct({ deletedAt: Schema.Date }),
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }),
-  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
-  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
-  'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }),
-  'v1.TodoClearedCompleted': ({ deletedAt }) => tables.todos.update({ deletedAt }).where({ completed: true }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-### `reference/platform-adapters/cloudflare/shared.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/shared.ts"
-
-export const storeIdFromRequest = (request: CfTypes.Request) => {
-  const url = new URL(request.url)
-  const storeId = url.searchParams.get('storeId')
-
-  if (storeId === null) {
-    throw new Error('storeId is required in URL search params')
-  }
-
-  return storeId
-}
-```
-
-### 3. Worker fetch handler
-
-The worker routes incoming requests either to the sync backend or to the client Durable Object:
-
-## `reference/platform-adapters/cloudflare/worker.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/worker.ts"
-
-export default {
-  fetch: async (request: CfTypes.Request, env: Env, ctx: CfTypes.ExecutionContext) => {
-    const url = new URL(request.url)
-
-    const searchParams = SyncBackend.matchSyncRequest(request)
-    if (searchParams !== undefined) {
-      return SyncBackend.handleSyncRequest({
-        request,
-        searchParams,
-        env,
-        ctx,
-        syncBackendBinding: 'SYNC_BACKEND_DO',
-        headers: {},
-      })
-    }
-
-    if (url.pathname.endsWith('/client-do')) {
-      const storeId = storeIdFromRequest(request)
-      const id = env.CLIENT_DO.idFromName(storeId)
-      return env.CLIENT_DO.get(id).fetch(request)
-    }
-
-    return new Response('Not found', { status: 404 }) as unknown as CfTypes.Response
-  },
-} satisfies SyncBackend.CFWorker<Env>
-```
-
-### `reference/platform-adapters/cloudflare/env.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/env.ts"
-
-export type Env = {
-  CLIENT_DO: CfTypes.DurableObjectNamespace<ClientDoWithRpcCallback>
-  SYNC_BACKEND_DO: CfTypes.DurableObjectNamespace<SyncBackendRpcInterface>
-  DB: CfTypes.D1Database
-}
-```
-
-### `reference/platform-adapters/cloudflare/shared.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/shared.ts"
-
-export const storeIdFromRequest = (request: CfTypes.Request) => {
-  const url = new URL(request.url)
-  const storeId = url.searchParams.get('storeId')
-
-  if (storeId === null) {
-    throw new Error('storeId is required in URL search params')
-  }
-
-  return storeId
-}
-```
-
-## API reference
-
-### `createStoreDoPromise(options)`
-
-Creates a LiveStore instance inside a Durable Object.
-
-**Options:**
-- `schema` – LiveStore schema definition
-- `storeId` – Unique identifier for the store
-- `clientId` – Client identifier
-- `sessionId` – Session identifier (use `nanoid()`)
-- `durableObject` – Context about the Durable Object hosting the store:
-  - `state` – Durable Object state handle (for example `this.ctx`)
-  - `env` – Environment bindings for the Durable Object
-  - `bindingName` – Name other workers use to reach this Durable Object
-- `syncBackendStub` – Durable Object stub used to reach the sync backend
-- `livePull` – Enable real-time updates (default: `false`)
-- `resetPersistence` – Drop LiveStore state/eventlog persistence before booting (development only, default: `false`)
-- `logger?` – Optional Effect logger layer to customize formatting/output
-- `logLevel?` – Optional minimum log level (use `LogLevel.None` to disable logs)
-
-### `syncUpdateRpc(payload)`
-
-Client Durable Objects must implement this method so the sync backend can deliver live updates. `createStoreDoPromise` wires it up automatically—just forward the payload to `handleSyncUpdateRpc` (see the client Durable Object example above).
-
-## Resetting LiveStore persistence (development only)
-
-When iterating locally, you can instruct the adapter to wipe the Durable Object’s LiveStore databases before booting by enabling `resetPersistence`. Guard this behind a protected route or admin token.
-
-## `reference/platform-adapters/cloudflare/reset.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/reset.ts"
-
-export const maybeResetStore = async ({
-  request,
-  env,
-  ctx,
-}: {
-  request: Request
-  env: Env
-  ctx: CfTypes.DurableObjectState
-}) => {
-  const url = new URL(request.url)
-  const shouldReset = url.pathname === '/internal/livestore-dev-reset'
-
-  const storeId = url.searchParams.get('storeId') ?? nanoid()
-
-  const store = await createStoreDoPromise({
-    schema,
-    storeId,
-    clientId: 'client-do',
-    sessionId: nanoid(),
-    durableObject: { ctx, env, bindingName: 'CLIENT_DO' },
-    syncBackendStub: env.SYNC_BACKEND_DO.get(env.SYNC_BACKEND_DO.idFromName(storeId)),
-    livePull: true,
-    resetPersistence: shouldReset,
-  })
-
-  return store
-}
-```
-
-### `reference/platform-adapters/cloudflare/env.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/env.ts"
-
-export type Env = {
-  CLIENT_DO: CfTypes.DurableObjectNamespace<ClientDoWithRpcCallback>
-  SYNC_BACKEND_DO: CfTypes.DurableObjectNamespace<SyncBackendRpcInterface>
-  DB: CfTypes.D1Database
-}
-```
-
-### `reference/platform-adapters/cloudflare/schema.ts`
-
-```ts filename="reference/platform-adapters/cloudflare/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text({ default: '' }),
-      completed: State.SQLite.boolean({ default: false }),
-      deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }),
-    },
-  }),
-}
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-  todoCompleted: Events.synced({
-    name: 'v1.TodoCompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoUncompleted: Events.synced({
-    name: 'v1.TodoUncompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoDeleted: Events.synced({
-    name: 'v1.TodoDeleted',
-    schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
-  }),
-  todoClearedCompleted: Events.synced({
-    name: 'v1.TodoClearedCompleted',
-    schema: Schema.Struct({ deletedAt: Schema.Date }),
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }),
-  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
-  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
-  'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }),
-  'v1.TodoClearedCompleted': ({ deletedAt }) => tables.todos.update({ deletedAt }).where({ completed: true }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-:::caution
-Resetting persistence deletes all LiveStore state and eventlog data stored inside the Durable Object. Only expose this behaviour in guarded development flows and never to production traffic.
-:::
-
-## Advanced features
-
-- Use `livePull: true` to receive push-based updates via Durable Object RPC callbacks.
-- Subscribe to data changes inside the Durable Object to trigger side effects (see the client Durable Object example).
-- Wire additional routes in the worker fetch handler to expose debugging endpoints or admin operations.
-
-For sync backend-related APIs like `makeDurableObject`, `handleSyncRequest`, and `matchSyncRequest`, see the [Cloudflare sync provider documentation](/sync-providers/cloudflare).

package/docs/platform-adapters/electron-adapter/index.md

@@ -1,15 +0,0 @@
-# Electron adapter
-
-## Using LiveStore with Electron
-
-LiveStore can already be used in Electron through the [web adapter](/platform-adapters/web-adapter), which works perfectly fine for most use cases. The web adapter leverages the browser APIs available in Electron's renderer process, providing full LiveStore functionality including reactive queries, offline-first operation, and sync capabilities.
-
-## Native Electron Adapter
-
-While the web adapter works well, there is room for further improvement through a dedicated native Electron adapter. A native adapter would leverage Electron's unique capabilities including:
-
-- **Transparent database file persistence** - Direct file system access instead of browser storage abstractions (IndexedDB/OPFS)
-- **Performance improvements** - Native SQLite bindings via Node.js integration
-- **Better integration with Electron's main process** - Coordination between main and renderer processes
-
-Development of the native Electron adapter is tracked in [this GitHub issue](https://github.com/livestorejs/livestore/issues/296). Contributors are welcome to help with the implementation, and sponsorship opportunities are available to accelerate development of this adapter.