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

package/docs/reference/framework-integrations/solid-integration/index.md

@@ -0,0 +1,293 @@
+# Solid integration
+
+## Example
+
+See [examples](/examples) for a complete example.
+
+## `reference/solid-integration/livestore/store.ts`
+
+```ts filename="reference/solid-integration/livestore/store.ts"
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+})
+
+export const store = await getStore({
+  adapter,
+  schema,
+  storeId: 'default',
+})
+```
+
+### `reference/solid-integration/livestore/schema.ts`
+
+```ts filename="reference/solid-integration/livestore/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 }),
+    },
+  }),
+  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' } },
+  }),
+}
+
+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 }),
+  }),
+  uiStateSet: tables.uiState.set,
+}
+
+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/solid-integration/MainSection.tsx`
+
+```tsx filename="reference/solid-integration/MainSection.tsx"
+/** biome-ignore-all lint/a11y/noLabelWithoutControl: TODO 🫠 */
+/** @jsxImportSource solid-js */
+
+export const MainSection: Component = () => {
+  const todos = query(visibleTodos$, [] as (typeof tables.todos.Type)[])
+  const todoItems = () => todos() ?? ([] as (typeof tables.todos.Type)[])
+
+  const toggleTodo = ({ id, completed }: typeof tables.todos.Type) =>
+    store()?.commit(completed ? events.todoUncompleted({ id }) : events.todoCompleted({ id }))
+
+  const deleteTodo = (id: string) => store()?.commit(events.todoDeleted({ id, deletedAt: new Date() }))
+
+  return (
+    <section class="main">
+      <ul class="todo-list">
+        <For each={todoItems()}>
+          {(todo: typeof tables.todos.Type) => (
+            <li>
+              <div class="view">
+                <input type="checkbox" class="toggle" checked={todo.completed} onChange={() => toggleTodo(todo)} />
+                <label>{todo.text}</label>
+                <button type="button" class="destroy" onClick={() => deleteTodo(todo.id)} />
+              </div>
+            </li>
+          )}
+        </For>
+      </ul>
+    </section>
+  )
+}
+```
+
+### `reference/solid-integration/livestore/queries.ts`
+
+```ts filename="reference/solid-integration/livestore/queries.ts"
+
+export const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })
+
+export const visibleTodos$ = queryDb(
+  (get) => {
+    const { filter } = get(uiState$)
+
+    return tables.todos.where({
+      deletedAt: null,
+      completed: filter === 'all' ? undefined : filter === 'completed',
+    })
+  },
+  { label: 'visibleTodos' },
+)
+```
+
+### `reference/solid-integration/livestore/schema.ts`
+
+```ts filename="reference/solid-integration/livestore/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 }),
+    },
+  }),
+  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' } },
+  }),
+}
+
+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 }),
+  }),
+  uiStateSet: tables.uiState.set,
+}
+
+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/solid-integration/livestore/store.ts`
+
+```ts filename="reference/solid-integration/livestore/store.ts"
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+})
+
+export const store = await getStore({
+  adapter,
+  schema,
+  storeId: 'default',
+})
+```
+
+### Logging
+
+You can control logging for Solid's runtime helpers via optional options passed to `getStore`:
+
+## `reference/solid-integration/store-logging.ts`
+
+```ts filename="reference/solid-integration/store-logging.ts"
+
+// ---cut---
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+})
+
+const _store = await getStore({
+  schema,
+  adapter,
+  storeId: 'default',
+  // Optional: swap logger and minimum log level
+  logger: Logger.prettyWithThread('window'),
+  logLevel: LogLevel.Info, // use LogLevel.None to disable logs
+})
+```
+
+### `reference/solid-integration/livestore/schema.ts`
+
+```ts filename="reference/solid-integration/livestore/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 }),
+    },
+  }),
+  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' } },
+  }),
+}
+
+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 }),
+  }),
+  uiStateSet: tables.uiState.set,
+}
+
+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 })
+```

package/docs/reference/framework-integrations/svelte-integration/index.md

@@ -0,0 +1,42 @@
+# Svelte integration
+
+LiveStore's Svelte bindings expose a single helper, `createStore`, which binds `store.query` into Svelte's reactivity. When you call `store.query` inside markup or `$effect`, query results automatically re-run when LiveStore emits updates, and requests are cancelled on teardown via Svelte's abort signal.
+
+## Example
+
+## `reference/framework-integrations/svelte/create-store.svelte`
+
+```svelte filename="reference/framework-integrations/svelte/create-store.svelte"
+<script lang="ts">
+
+  const adapter = makePersistedAdapter({
+    storage: { type: 'opfs' },
+    worker: LiveStoreWorker,
+    sharedWorker: LiveStoreSharedWorker,
+  })
+
+  const store = await createStore<typeof schema>({
+    adapter,
+    schema,
+    storeId: 'default',
+  })
+
+  const todos$ = queryDb(tables.todos.where({ completed: false }), {
+    label: 'todos',
+  })
+</script>
+
+<ul>
+  {#each store.query(todos$) as todo (todo.id)}
+    <li>{todo.text}</li>
+  {/each}
+</ul>
+```
+
+## Usage notes
+
+- `createStore` is async; instantiate it where you have access to the adapter (e.g. route load, `onMount`, or a top-level module when running in the browser).
+- `store.query` opts into Svelte reactivity when called inside `$effect` or markup. Outside reactive contexts, you can still use `store.subscribe` directly.
+- Works with the Web adapter out of the box. For SSR routes, construct the store on the client since `@livestore/adapter-web` is browser-only.
+
+See the <a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples/web-todomvc-svelte`}>Svelte TodoMVC example</a> for a complete app.

package/docs/reference/framework-integrations/vue-integration/index.md

@@ -0,0 +1,98 @@
+# Vue integration for LiveStore
+
+The [vue-livestore](https://github.com/slashv/vue-livestore) package provides integration with Vue. It's currently in beta but aims to match feature parity with the React integration.
+
+## API
+
+### `LiveStoreProvider`
+
+In order to use LiveStore with Vue, you need to wrap your application in a `LiveStoreProvider`.
+
+```vue
+<script setup lang="ts">
+
+</script>
+
+<template>
+  <LiveStoreProvider :options="{ schema, adapter, storeId }">
+    <template #loading>
+      <div>Loading LiveStore...</div>
+    </template>
+    <ToDos />
+  </LiveStoreProvider>
+</template>
+```
+
+### useStore
+
+```ts
+const { store } = useStore()
+
+const createTodo = () => {
+  store.commit(
+    events.todoCreated({ id: crypto.randomUUID(), text: 'Eat broccoli' })
+  )
+}
+```
+
+### useQuery
+
+```vue
+<script setup lang="ts">
+
+const visibleTodos$ = queryDb(
+  () => tables.todos.where({ deletedAt: null }),
+  { label: 'visibleTodos' },
+)
+
+const todos = useQuery(visibleTodos$)
+</script>
+
+<template>
+  <div>
+    <ul>
+      <li v-for="todo in todos" :key="todo.id">
+        {{ todo.text }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+### useClientDocument
+
+**[!] The interface for useClientDocument is experimental and might change**
+
+Since it's more common in Vue to work with a single writable ref (as compared to state, setState in React) the useClientDocument composable for Vue tries to make that easier by directly returning a collection of refs.
+
+The current implementation destructures all client state variables into the return object which allows directly binding to v-model or editing the .value reactivly.
+
+```vue
+<script setup lang="ts">
+
+const { newTodoText, filters } = useClientDocument(tables.uiState)
+</script>
+
+<template>
+<input type="text" v-model="newTodoText">
+
+<select v-model="filters">
+  <option value="all">All</option>
+  ...
+<select>
+</template>
+```
+
+## Usage with ...
+
+### Vite
+
+LiveStore and vue-livestore works with Vite out of the box.
+
+### Nuxt.js
+
+Works out of the box with Nuxt if SSR is disabled by just wrapping the main content in a LiveStoreProvider. Example repo upcoming.
+
+## Technical notes
+
+- Vue-livestore uses the provider component pattern similar to the React integration. In Vue the plugin pattern is more common but it isn't clear that that's the most suitable structure for LiveStore in Vue. We might switch to the plugin pattern if we later find that more suitable especially with regards to Nuxt support and supporting multiple stores.

package/docs/reference/mcp/index.md

@@ -0,0 +1,165 @@
+# MCP Integration
+
+LiveStore includes MCP (Model Context Protocol) integration that allows AI assistants like Claude to access LiveStore documentation, examples, and development tools.
+
+:::caution[Experimental]
+The MCP integration is experimental and under active development. Features may change.
+:::
+
+For installation and general CLI usage, see the [LiveStore CLI](/reference/cli) documentation.
+
+## What is MCP?
+
+MCP (Model Context Protocol) is a standard for providing AI assistants with access to external resources and tools. LiveStore's MCP server gives AI assistants access to:
+
+- LiveStore documentation and guides
+- Schema examples for common app types
+- Development tools and utilities
+
+## Usage
+
+Start the MCP server:
+
+```bash
+bunx @livestore/cli mcp
+```
+
+## Available Commands
+
+### `bunx @livestore/cli mcp coach`
+Starts an AI coaching assistant with access to LiveStore documentation and best practices.
+
+### `bunx @livestore/cli mcp tools`
+Provides development tools and utilities for working with LiveStore projects.
+
+### LiveStore Runtime Tools
+
+- `livestore_instance_connect`
+  - Connects a single in-process LiveStore instance by dynamically importing a module that exports `schema` and a `syncBackend` factory (and optionally `syncPayload`).
+  - Notes:
+    - Only one instance can be active at a time; connecting again shuts down and replaces the previous instance.
+    - Reconnecting creates a fresh, in-memory client database. The visible state is populated by your backend's initial sync. Until sync completes, queries may return empty or partial results.
+  - Module contract (generic example):
+
+## `reference/mcp/module-contract.ts`
+
+```ts filename="reference/mcp/module-contract.ts"
+
+export { schema } from './schema.ts'
+
+export const syncBackend = makeWsSync({ url: process.env.LIVESTORE_SYNC_URL ?? 'ws://localhost:8787' })
+
+export const syncPayload = { authToken: process.env.LIVESTORE_SYNC_AUTH_TOKEN ?? 'insecure-token-change-me' }
+```
+
+### `reference/mcp/schema.ts`
+
+```ts filename="reference/mcp/schema.ts"
+
+const events = {
+  entityCreated: Events.synced({
+    name: 'v1.EntityCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      createdAt: Schema.DateFromString,
+    }),
+  }),
+}
+
+const tables = {
+  entities: State.SQLite.table({
+    name: 'entities',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      title: State.SQLite.text({ default: '' }),
+      createdAt: State.SQLite.text({ default: '' }),
+    },
+  }),
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.EntityCreated': ({ id, title, createdAt }) =>
+    tables.entities.insert({ id, title, createdAt: createdAt.toISOString() }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+- Params example: `{ "storePath": "<path-to-your-mcp-module>.ts", "storeId": "<store-id>" }`
+  - Returns example:
+    `{ "storeId": "<store-id>", "clientId": "client-123", "sessionId": "session-abc", "schemaInfo": { "tableNames": ["..."], "eventNames": ["..."] } }`
+
+- `livestore_instance_query`
+  - Executes raw SQL against the client database (read-only).
+  - Notes:
+    - SQLite dialect; use valid SQLite syntax.
+    - `bindValues` must be an array (positional `?`) or a record (named `$key`). Do not pass stringified JSON.
+  - Params example (positional): `{ "sql": "SELECT * FROM my_table WHERE userId = ?", "bindValues": ["u1"] }`
+  - Params example (named): `{ "sql": "SELECT * FROM my_table WHERE userId = $userId", "bindValues": { "userId": "u1" } }`
+  - Returns example: `{ "rows": [{ "col": "value" }], "rowCount": 1 }`
+
+- `livestore_instance_commit_events`
+  - Commits one or more events defined by your connected schema.
+  - Notes:
+    - Use the canonical event name declared in your schema (e.g., `v1.EntityCreated`).
+    - `args` must be a non-stringified JSON object matching the event schema. Date fields typically accept ISO 8601 strings.
+  - Params example: `{ "events": [{ "name": "v1.EntityCreated", "args": { "id": "e1", "title": "Hello", "createdAt": "2024-01-01T00:00:00.000Z" } }] }`
+  - Returns example: `{ "committed": 1 }`
+
+- `livestore_instance_status`
+  - Reports instance/runtime info.
+  - Returns example (connected): `{ "_tag": "connected", "storeId": "<store-id>", "clientId": "client-123", "sessionId": "session-abc", "tableCounts": { "my_table": 12 } }`
+  - Returns example (not connected): `{ "_tag": "disconnected" }`
+
+- `livestore_instance_disconnect`
+  - Disconnects the current LiveStore instance and releases resources.
+  - Returns: `{ "_tag": "disconnected" }`
+
+## Local Cloudflare Sync (dev)
+
+Run a local Cloudflare sync backend:
+
+1. Start the sync worker (wrangler):
+   - `cd tests/integration/src/tests/adapter-cloudflare/fixtures`
+   - `wrangler dev`
+   - You should see an info page at `http://localhost:8787/`.
+
+2. Start the MCP server in another terminal:
+   - `bunx @livestore/cli mcp server`
+
+3. From your MCP client (e.g., Claude Desktop), call tools:
+   - Use your own MCP module path and storeId. The repo also provides an example: `examples/cf-chat/mcp.ts`.
+   - Connect: `livestore_instance_connect` with `{ "storePath": "<path-to-your-mcp-module>.ts", "storeId": "<store-id>" }`
+   - Commit: `livestore_instance_commit_events` with `[ { "name": "v1.EntityCreated", "args": { "id": "e1", "title": "Hello", "createdAt": "2024-01-01T00:00:00.000Z" } } ]`
+   - Query: `livestore_instance_query` with `{ "sql": "SELECT * FROM my_table ORDER BY createdAt DESC LIMIT 5" }`
+   - Status: `livestore_instance_status`
+   - Disconnect: `livestore_instance_disconnect`
+
+## Adding to Claude
+
+To use with Claude Desktop, add the MCP server to your Claude configuration:
+
+```json
+{
+  "mcpServers": {
+    "livestore": {
+      "command": "bunx",
+      "args": ["@livestore/cli", "mcp"]
+    }
+  }
+}
+```
+
+## Available Resources
+
+The MCP server provides access to:
+
+- **Documentation**: Overview, features, getting started guides
+- **Architecture**: Technical design and principles  
+- **Schema Examples**: Pre-built schemas for todo, blog, e-commerce, and social apps
+- **Development Tools**: Project scaffolding and utilities
+
+This enables AI assistants to provide context-aware help with LiveStore development.

package/docs/reference/opentelemetry/index.md

@@ -0,0 +1,36 @@
+# OpenTelemetry
+
+LiveStore has built-in support for OpenTelemetry.
+
+## Usage with React
+
+```tsx
+// otel.ts
+const makeTracer = () => {
+  const url = import.meta.env.VITE_OTEL_EXPORTER_OTLP_ENDPOINT
+  const provider = new WebTracerProvider({
+    spanProcessors: [new SimpleSpanProcessor(new OTLPTraceExporter({ url }))],
+  })
+
+  provider.register()
+
+  return provider.getTracer('livestore')
+}
+
+export const tracer = makeTracer()
+
+// In your main entry file
+
+export const App: React.FC = () => (
+  <LiveStoreProvider
+    // ...
+    otelOptions={{ tracer }}
+  >
+    <AppBody />
+  </LiveStoreProvider>
+)
+
+// And in your `livestore.worker.ts`
+
+makeWorker({ schema, otelOptions: { tracer } })
+```