@livestore/livestore 0.4.0-dev.18 → 0.4.0-dev.19

package/docs/patterns/storybook/index.md

@@ -0,0 +1,192 @@
+# 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

@@ -0,0 +1,9 @@
+# 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

@@ -0,0 +1,8 @@
+# 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/reference/cli/index.md

@@ -0,0 +1,57 @@
+# LiveStore CLI
+
+The LiveStore CLI provides tools for creating new projects and integrating with AI assistants through MCP (Model Context Protocol).
+
+:::caution[Experimental - Not Production Ready]
+The LiveStore CLI is an experimental preview and not ready for production use. APIs, commands, and functionality may change significantly. Use for development and evaluation purposes only.
+:::
+
+## Installation
+
+You can use the LiveStore CLI in several ways:
+
+```bash
+# Recommended: Use bunx (no installation needed)
+bunx @livestore/cli --help
+
+# Alternative options:
+npm install -g @livestore/cli        # Global install
+npm install -D @livestore/cli        # Project install
+npx @livestore/cli --help            # Use with npx
+```
+
+## Commands
+
+### `bunx @livestore/cli new-project`
+Create a new LiveStore project from available examples.
+
+```bash
+# Interactive selection
+bunx @livestore/cli new-project
+
+# Specify example and path
+bunx @livestore/cli new-project --example web-todomvc my-project
+
+# Use specific branch
+bunx @livestore/cli new-project --branch dev
+```
+
+### `bunx @livestore/cli mcp`
+MCP server tools for AI assistant integration. See [MCP Integration](/reference/mcp) for details.
+
+```bash
+# Start MCP server
+bunx @livestore/cli mcp
+
+# Available subcommands
+bunx @livestore/cli mcp coach    # AI coaching assistant (requires API key env var)
+bunx @livestore/cli mcp tools    # Development tools server
+
+# Coach command requires API key - check implementation for specific variable name
+# Example: OPENAI_API_KEY=your_key bunx @livestore/cli mcp coach
+```
+
+## Global Options
+
+- `--verbose` - Enable verbose logging
+- `--help` - Show command help

package/docs/reference/concepts/index.md

@@ -0,0 +1,78 @@
+# 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](/reference/devtools)
+- [Events](/reference/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](/reference/reactivity-system)
+  - Db queries `queryDb()`
+  - Computed queries `computed()`
+  - Signals `signal()`
+- Schema
+  - LiveStore uses schema definitions for the following cases:
+    - [Event definitions](/reference/events)
+    - [SQLite state schema](/reference/state/sqlite-schema)
+    - [Query result schemas](/reference/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](/reference/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/reference/debugging/index.md

@@ -0,0 +1,17 @@
+# Debugging a LiveStore app
+
+When working on a LiveStore app you might end up in situations where you need to debug things. LiveStore is built with debuggability in mind and tries to make your life as a developer as easy as possible.
+
+Here are a few things that LiveStore offers to help you debug your app:
+
+- [OpenTelemetry](/reference/opentelemetry) integration for tracing / metrics
+- [Devtools](/reference/devtools) for inspecting the state of the store
+- Store helper methods
+
+## Debugging helpers on the store
+
+The `store` exposes a `_dev` property which contains a few helpers that can help you debug your app.
+
+## Other recommended practices and tools
+
+- Use the step debugger

package/docs/reference/devtools/index.md

@@ -0,0 +1,79 @@
+# Devtools
+
+NOTE: Once LiveStore is open source, the devtools will be a [sponsor-only benefit](/misc/sponsoring).
+
+## Features
+
+- Real-time data browser with 2-way sync
+  ![](https://share.cleanshot.com/F79hpTCY+)
+- Query inspector
+  ![](https://share.cleanshot.com/pkr2jqgb+)
+- Eventlog browser
+  ![](https://share.cleanshot.com/PTgXpcPm+)
+- Sync status
+  ![](https://share.cleanshot.com/VsKY3KnR+)
+- Export/import
+  ![](https://share.cleanshot.com/LQKYX6rq+)
+- Reactivity graph / signals inspector
+  ![](https://share.cleanshot.com/M26FHD6j+)
+- SQLite playground
+  ![](https://share.cleanshot.com/BcWmLmn2+)
+
+## Adapters
+
+### `@livestore/adapter-web`:
+
+Requires the `@livestore/devtools-vite` package to be installed and configured in your Vite config:
+
+## `reference/devtools/vite-config.ts`
+
+```ts filename="reference/devtools/vite-config.ts"
+
+export default defineConfig({
+  // ...
+  plugins: [livestoreDevtoolsPlugin({ schemaPath: './src/livestore/schema.ts' })],
+})
+```
+
+The devtools can be opened in a separate tab (via e.g. `localhost:3000/_livestore/web). You should see the Devtools URL logged in the browser console when running the app.
+
+#### Chrome extension
+
+You can also use the Devtools Chrome extension.
+
+![](https://share.cleanshot.com/wlM4ybFn+)
+
+Please make sure to manually install the extension version matching the LiveStore version you are using by downloading the appropriate version from the [GitHub releases page](https://github.com/livestorejs/livestore/releases) and installing it manually via `chrome://extensions/`.
+
+To install the extension:
+
+1. **Unpack the ZIP file** (e.g. `livestore-devtools-chrome-0.3.0.zip`) into a folder on your computer.
+2. Navigate to `chrome://extensions/` and enable **Developer mode** (toggle in the top-right corner).
+3. Click **"Load unpacked"** and select the unpacked folder or drag and drop the folder onto the page.
+
+### `@livestore/adapter-expo`:
+
+Requires the `@livestore/devtools-expo` package to be installed and configured in your metro config:
+
+## `reference/devtools/metro-config.ts`
+
+```ts filename="reference/devtools/metro-config.ts"
+// @noErrors
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config')
+const { addLiveStoreDevtoolsMiddleware } = require('@livestore/devtools-expo')
+
+const config = getDefaultConfig(__dirname)
+
+addLiveStoreDevtoolsMiddleware(config, { schemaPath: './src/livestore/schema.ts' })
+
+module.exports = config
+```
+
+You can open the devtools by pressing `Shift+m` in the Expo CLI process and then selecting `@livestore/devtools-expo` which will open the devtools in a new tab.
+  
+### `@livestore/adapter-node`:
+
+Devtools are configured out of the box for the `makePersistedAdapter` variant (note currently not supported for the `makeInMemoryAdapter` variant).
+
+You should see the Devtools URL logged when running the app.

package/docs/reference/events/index.md

@@ -0,0 +1,241 @@
+# Events
+
+## Event definitions
+
+There are two types of events:
+
+- `synced`: Events that are synced across clients
+- `clientOnly`: Events that are only processed locally on the client (but still synced across client sessions e.g. across browser tabs/windows)
+
+An event definition consists of a unique name of the event and a schema for the event arguments. It's recommended to version event definitions to make it easier to evolve them over time.
+
+Events will be synced across clients and materialized into state (i.e. SQLite tables) via [materializers](/reference/state/materializers).
+
+### Example
+
+## `reference/events/livestore-schema.ts`
+
+```ts filename="reference/events/livestore-schema.ts"
+// livestore/schema.ts
+
+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 }),
+  }),
+} as const
+```
+
+### Best Practices
+
+- It's strongly recommended to use past-tense event names (e.g. `todoCreated`/`createdTodo` instead of `todoCreate`/`createTodo`) to indicate something already occurred.
+- When generating IDs for events (e.g. for the todo in the example above), it's recommended to use a globally unique ID generator (e.g. UUID, nanoid, etc.) to avoid conflicts. For convenience, `@livestore/livestore` re-exports the `nanoid` function.
+- TODO: write down more best practices
+- TODO: mention AI linting (either manually or via a CI step)
+  - core idea: feed list of best practices to AI and check if events adhere to them + get suggestions if not
+- It's recommended to avoid `DELETE` events and instead use soft-deletes (e.g. add a `deleted` date/boolean column with a default value of `null`). This helps avoid some common concurrency issues.
+
+### Unknown events
+
+Older clients might receive events that were introduced in newer app versions. Configure the behaviour centrally via `unknownEventHandling` when constructing the schema:
+
+## `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 })
+    },
+  },
+})
+```
+
+Pick `'warn'` (default) to log every occurrence, `'ignore'` to silently drop new events until the client updates, `'fail'` to halt immediately, or `'callback'` to delegate to custom logging/telemetry while continuing to process the log.
+
+### Schema evolution \{#schema-evolution\}
+
+- Event definitions can't be removed after they were added to your app.
+- Event schema definitions can be evolved as long as the changes are forward-compatible.
+  - That means data encoded with the old schema can be decoded with the new schema.
+  - In practice, this means ...
+    - for structs ...
+      - you can add new fields if they have default values or are optional
+      - you can remove fields
+
+## Event format
+
+Each event has the following structure:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Event name matching the event definition |
+| `args` | Event arguments as defined by the event schema |
+| `seqNum` | Sequence number identifying this event |
+| `parentSeqNum` | Parent event's sequence number (for causal ordering) |
+| `clientId` | Identifier of the client that created the event |
+| `sessionId` | Identifier of the session |
+
+### Encoded vs decoded events
+
+Events exist in two formats:
+
+**Decoded** - Native TypeScript types used in application code:
+
+```json
+{
+  "name": "todoCreated-v1",
+  "args": { "id": "abc123", "text": "Buy milk", "createdAt": Date },
+  "seqNum": 5,
+  "parentSeqNum": 4,
+  "clientId": "client-xyz",
+  "sessionId": "session-123"
+}
+```
+
+**Encoded** - Serialized format for storage and sync:
+
+```json
+{
+  "name": "todoCreated-v1",
+  "args": { "id": "abc123", "text": "Buy milk", "createdAt": "2024-01-15T10:30:00.000Z" },
+  "seqNum": 5,
+  "parentSeqNum": 4,
+  "clientId": "client-xyz",
+  "sessionId": "session-123"
+}
+```
+
+The `args` field is encoded according to the event's schema (e.g., `Date` objects become ISO strings, binary data becomes base64). LiveStore handles encoding/decoding automatically.
+
+### Client-side sequence numbers
+
+On the client, sequence numbers are expanded to track additional information for local events:
+
+```json
+{
+  "seqNum": { "global": 5, "client": 1, "rebaseGeneration": 0 },
+  "parentSeqNum": { "global": 5, "client": 0, "rebaseGeneration": 0 }
+}
+```
+
+- **global**: Globally unique integer assigned by the sync backend (`EventSequenceNumber.Global`)
+- **client**: Client-local counter (0 for synced events, increments for client-only events) (`EventSequenceNumber.Client`)
+- **rebaseGeneration**: Increments when the client rebases unconfirmed events
+
+Events can be represented as strings like `e5` (global event 5), `e5.1` (client-local event), or `e5r1` (after a rebase).
+
+For the full type definitions, see [`LiveStoreEvent`](https://github.com/livestorejs/livestore/tree/dev/packages/@livestore/common/src/schema/LiveStoreEvent) and [`EventSequenceNumber`](https://github.com/livestorejs/livestore/tree/dev/packages/@livestore/common/src/schema/EventSequenceNumber).
+
+### Event type namespaces
+
+LiveStore organizes event types into namespaces based on their usage context:
+
+| Namespace | Description | Sequence Number Format |
+|-----------|-------------|----------------------|
+| `LiveStoreEvent.Input` | Events without sequence numbers (for committing) | None |
+| `LiveStoreEvent.Global` | Sync backend format | Integer (`seqNum: number`) |
+| `LiveStoreEvent.Client` | Client-side format with full metadata | Struct (`seqNum: { global, client, rebaseGeneration }`) |
+
+## `reference/events/event-type-namespaces.ts`
+
+```ts filename="reference/events/event-type-namespaces.ts"
+
+// Input events (no sequence numbers) - used when committing
+const _input: LiveStoreEvent.Input.Decoded = {
+  name: 'todoCreated-v1',
+  args: { id: 'abc123', text: 'Buy milk' },
+}
+
+// Global events (sync backend format) - integer sequence numbers
+const _global: LiveStoreEvent.Global.Encoded = {
+  name: 'todoCreated-v1',
+  args: { id: 'abc123', text: 'Buy milk' },
+  seqNum: EventSequenceNumber.Global.make(5),
+  parentSeqNum: EventSequenceNumber.Global.make(4),
+  clientId: 'client-xyz',
+  sessionId: 'session-123',
+}
+
+// Client events (local format) - composite sequence numbers
+const _client: LiveStoreEvent.Client.Encoded = {
+  name: 'todoCreated-v1',
+  args: { id: 'abc123', text: 'Buy milk' },
+  seqNum: EventSequenceNumber.Client.Composite.make({ global: 5, client: 0, rebaseGeneration: 0 }),
+  parentSeqNum: EventSequenceNumber.Client.Composite.make({ global: 4, client: 0, rebaseGeneration: 0 }),
+  clientId: 'client-xyz',
+  sessionId: 'session-123',
+}
+```
+
+## Commiting events
+
+## `reference/events/commit.ts`
+
+```ts filename="reference/events/commit.ts"
+// somewhere in your app
+
+declare const store: Store
+
+store.commit(events.todoCreated({ id: '1', text: 'Buy milk' }))
+```
+
+### `reference/events/livestore-schema.ts`
+
+```ts filename="reference/events/livestore-schema.ts"
+// livestore/schema.ts
+
+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 }),
+  }),
+} as const
+```
+
+## Eventlog
+
+The history of all events that have been committed is stored forms the "eventlog". It is persisted in the client as well as in the sync backend.
+
+Example `eventlog.db`:
+
+![](https://share.cleanshot.com/R6ny879w+)