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

package/docs/building-with-livestore/store/index.md

@@ -1,281 +0,0 @@
-# Store
-
-The `Store` is the most common way to interact with LiveStore from your application code. It provides a way to query data, commit events, and subscribe to data changes.
-
-## Creating a store
-
-For how to create a store in React, see the [React integration docs](/framework-integrations/react-integration). The following example shows how to create a store manually:
-
-## `reference/store/create-store.ts`
-
-```ts filename="reference/store/create-store.ts"
-
-const adapter = makeAdapter({
-  storage: { type: 'fs' },
-  // sync: { backend: makeWsSync({ url: '...' }) },
-})
-
-export const bootstrap = async () => {
-  const store = await createStorePromise({
-    schema,
-    adapter,
-    storeId: 'some-store-id',
-  })
-
-  return store
-}
-```
-
-### `reference/store/schema.ts`
-
-```ts filename="reference/store/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} 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, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-export const storeTables = tables
-export const storeEvents = events
-```
-
-## Using a store
-
-### Querying data
-
-## `reference/store/query-data.ts`
-
-```ts filename="reference/store/query-data.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet shows query result */
-// ---cut---
-
-declare const store: Store
-
-const todos = store.query(storeTables.todos)
-console.log(todos)
-```
-
-### `reference/store/schema.ts`
-
-```ts filename="reference/store/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} 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, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-export const storeTables = tables
-export const storeEvents = events
-```
-
-### Subscribing to data
-
-## `reference/store/subscribe.ts`
-
-```ts filename="reference/store/subscribe.ts"
-
-declare const store: Store
-
-const unsubscribe = store.subscribe(storeTables.todos, (todos) => {
-  console.log(todos)
-})
-
-unsubscribe()
-```
-
-### `reference/store/schema.ts`
-
-```ts filename="reference/store/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} 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, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-export const storeTables = tables
-export const storeEvents = events
-```
-
-### Committing events
-
-## `reference/store/commit-event.ts`
-
-```ts filename="reference/store/commit-event.ts"
-
-declare const store: Store
-
-store.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))
-```
-
-### `reference/store/schema.ts`
-
-```ts filename="reference/store/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} 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, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-export const storeTables = tables
-export const storeEvents = events
-```
-
-### Streaming events
-
-Currently only events confirmed by the sync backend are supported.
-
-## `reference/store/stream-events.ts`
-
-```ts filename="reference/store/stream-events.ts"
-
-declare const store: Store
-
-// Run once
-for await (const event of store.events()) {
-  console.log('event from leader', event)
-}
-
-// Continuos stream
-const iterator = store.events()[Symbol.asyncIterator]()
-try {
-  while (true) {
-    const { value, done } = await iterator.next()
-    if (done) break
-    console.log('event from stream:', value)
-  }
-} finally {
-  await iterator.return?.()
-}
-```
-
-### Shutting down a store
-
-LiveStore provides two APIs for shutting down a store:
-
-## `reference/store/shutdown.ts`
-
-```ts filename="reference/store/shutdown.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet demonstrates shutdown helpers */
-// ---cut---
-
-declare const store: Store
-
-const effectShutdown = Effect.gen(function* () {
-  yield* Effect.log('Shutting down store')
-  yield* store.shutdown()
-})
-
-const shutdownWithPromise = async () => {
-  await store.shutdownPromise()
-}
-```
-
-## Multiple stores
-
-You can create and use multiple stores in the same app. This can be useful when breaking up your data model into smaller pieces.
-
-## Development/debugging helpers
-
-A store instance also exposes a `_dev` property that contains some helpful methods for development. For convenience you can access a store on `globalThis`/`window` like via `__debugLiveStore.default._dev` (`default` is the store id):
-
-```ts
-// Download the SQLite database
-__debugLiveStore.default._dev.downloadDb()
-
-// Download the eventlog database
-__debugLiveStore.default._dev.downloadEventlogDb()
-
-// Reset the store
-__debugLiveStore.default._dev.hardReset()
-
-// See the current sync state
-__debugLiveStore.default._dev.syncStates()
-```

package/docs/building-with-livestore/syncing/index.md

@@ -1,136 +0,0 @@
-# Syncing
-
-## How it works
-
-LiveStore is based on [the idea of event-sourcing](/understanding-livestore/event-sourcing) which means it syncs events across clients (via a central sync backend) and then materializes the events in the local SQLite database. This means LiveStore isn't syncing the SQLite database itself directly but only the events that are used to materialize the database making sure it's kept in sync across clients.
-
-The syncing mechanism is similar to how Git works in that regard that it's based on a "push/pull" model. Upstream events always need to be pulled before a client can push its own events to preserve a [global total order of events](https://medium.com/baseds/ordering-distributed-events-29c1dd9d1eff). Local pending events which haven't been pushed yet need to be rebased on top of the latest upstream events before they can be pushed.
-
-<SyncingDiagram />
-
-## Events
-
-A LiveStore event consists of the following data:
-- `seqNum`: event sequence number
-- `parentSeqNum`: parent event sequence number
-- `name`: event name (refers to a event definition in the schema)
-- `args`: event arguments (encoded using the event's schema definition, usually JSON)
-
-### Event sequence numbers
-
-- Event sequence numbers: monotonically increasing integers
-  - client event sequence number to sync across client sessions (never exposed to the sync backend)
-
-### Sync heads
-
-- The latest event in a eventlog is referred to as the "head" (similar to how Git refers to the latest commit as the "head").
-- Given that LiveStore does hierarchical syncing between the client session, the client leader and the sync backend, there are three heads (i.e. the client session head, the client leader head, and the sync backend head).
-
-## Sync backend
-
-The sync backend acts as the global authority and determines the total order of events ("causality"). It's responsible for storing and querying events and for notifying clients when new events are available.
-
-### Requirements for sync backend
-
-- Needs to provide an efficient way to query an ordered list of events given a starting event ID (often referred to as cursor).
-- Ideally provides a "reactivity" mechanism to notify clients when new events are available (e.g. via WebSocket, HTTP long-polling, etc).
-  - Alternatively, the client can periodically query for new events which is less efficient.
-
-## Clients
-
-- Each client initially chooses a random `clientId` as its globally unique ID
-  - LiveStore uses a 6-char nanoid
-	- In the unlikely event of a collision which is detected by the sync backend the first time a client tries to push, the client chooses a new random `clientId`, patches the local events with the new `clientId`, and tries again.
-
-### Client sessions
-
-- Each client has at least one client session
-- Client sessions within the same client share local data
-- In web adapters: multiple tabs/windows can be different sessions within the same client
-- Sessions are identified by a `sessionId` which can persist (e.g., across tab reloads in web)
-- For adapters which support multiple client sessions (e.g. web), LiveStore also supports local syncing across client sessions (e.g. across browser tabs or worker threads)
-- Client session events are not synced to the sync backend
-
-## Auth (authentication & authorization)
-
-- TODO
-  - Provide basic example
-  - Encryption
-
-## Advanced
-
-### Sequence diagrams
-
-#### Pulling events (without unpushed events)
-
-```d2
-...@../../../../src/content/base.d2
-
-shape: sequence_diagram
-
-Client: {
-  label: "Client"
-}
-
-SyncBackend: {
-  label: "Sync Backend"
-}
-
-Client -> SyncBackend: "`pull` request\n(head_cursor)"
-SyncBackend -> SyncBackend: "Get new events\n(since head_cursor)"
-SyncBackend -> Client: "New events"
-Client -> Client: "Client is in sync"
-```
-
-#### Pushing events
-
-```d2
-...@../../../../src/content/base.d2
-
-shape: sequence_diagram
-
-Client: {
-  label: "Client"
-}
-
-SyncBackend: {
-  label: "Sync Backend"
-}
-
-Client -> Client: "Commit events"
-Client -> SyncBackend: "`push` request\n(new_local_events)"
-SyncBackend -> SyncBackend: "Validate & persist"
-SyncBackend -> Client: "Push success"
-Client -> Client: "Client is in sync"
-```
-
-### Rebasing
-
-### Merge conflicts
-
-- Merge conflict handling isn't implemented yet (see [this issue](https://github.com/livestorejs/livestore/issues/253)).
-- Merge conflict detection and resolution will be based on the upcoming [facts system functionality](https://github.com/livestorejs/livestore/issues/254).
-
-### Compaction
-
-- Compaction isn't implemented yet (see [this issue](https://github.com/livestorejs/livestore/issues/136))
-- Compaction will be based on the upcoming [facts system functionality](https://github.com/livestorejs/livestore/issues/254).
-
-### Partitioning
-
-- Currently LiveStore assumes a 1:1 mapping between an eventlog and a SQLite database.
-- In the future, LiveStore aims to support multiple eventlogs (see [this issue](https://github.com/livestorejs/livestore/issues/255)).
-
-## Design decisions / trade-offs
-
-- Require a central sync backend to enforce a global total order of events.
-  - This means LiveStore can't be used in a fully decentralized/P2P manner.
-- Do rebasing on the client side (instead of on the sync backend). This allows the user to have more control over the rebase process.
-
-## Notes
-
-- Rich text data is best handled via CRDTs (see [#263](https://github.com/livestorejs/livestore/issues/263))
-
-## Further reading
-
-- Distributed Systems lecture series by Martin Kleppmann: [YouTube playlist](https://www.youtube.com/playlist?list=PLeKd45zvjcDFUEv_ohr_HdUFe97RItdiB) / [lecture notes](https://www.cl.cam.ac.uk/teaching/2122/ConcDisSys/dist-sys-notes.pdf)

package/docs/building-with-livestore/tools/cli/index.md

@@ -1,177 +0,0 @@
-# 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
-
-### `livestore new-project`
-Create a new LiveStore project from available examples.
-
-```bash
-# Interactive selection
-livestore new-project
-
-# Specify example and path
-livestore new-project --example web-todomvc my-project
-
-# Use specific branch
-livestore new-project --branch dev
-```
-
-### `livestore mcp`
-MCP server tools for AI assistant integration. See [MCP Integration](/building-with-livestore/tools/mcp) for details.
-
-```bash
-# Start MCP server
-livestore mcp
-
-# Available subcommands
-livestore mcp coach    # AI coaching assistant (requires API key env var)
-livestore mcp tools    # Development tools server
-
-# Coach command requires API key - check implementation for specific variable name
-# Example: OPENAI_API_KEY=your_key livestore mcp coach
-```
-
-### `livestore sync`
-
-Import and export events from the sync backend. Useful for backup, migration, and debugging.
-
-#### Export
-
-Export all events from the sync backend to a JSON file:
-
-```bash
-livestore sync export \
-  --config livestore-cli.config.ts \
-  --store-id my-store \
-  events.json
-```
-
-**Example output:**
-
-```
-Exporting events from LiveStore...
-   Config: livestore-cli.config.ts
-   Store ID: my-store
-   Output: events.json
-
-Connecting to sync backend...
-✓ Connected to sync backend: @livestore/cf-sync
-Pulling events from sync backend...
-Pulled 127 events
-Exported 127 events to /path/to/events.json
-```
-
-**Options:**
-- `--config, -c` (required) - Path to a config module that exports `schema` and `syncBackend`
-- `--store-id, -i` (required) - Store identifier
-- `--client-id` - Client identifier for the sync connection (default: `cli-export`)
-- Large exports load data in memory; for very large stores run this on a machine with sufficient RAM.
-
-#### Import
-
-Import events from a JSON file to the sync backend:
-
-```bash
-livestore sync import \
-  --config livestore-cli.config.ts \
-  --store-id my-store \
-  events.json
-```
-
-**Example output:**
-
-```
-Importing events to LiveStore...
-   Config: livestore-cli.config.ts
-   Store ID: my-store
-   Input: events.json
-
-Reading import file...
-Found 127 events in export file
-Checking for existing events...
-Connecting to sync backend...
-✓ Connected to sync backend: @livestore/cf-sync
-Pushing events to sync backend...
-  Pushed 100/127 events
-  Pushed 127/127 events
-Successfully imported 127 events
-```
-
-**Options:**
-- `--config, -c` (required) - Path to a config module that exports `schema` and `syncBackend`
-- `--store-id, -i` (required) - Store identifier
-- `--client-id` - Client identifier for the sync connection (default: `cli-import`)
-- `--force, -f` - Force import even if store ID in the file doesn't match
-- `--dry-run` - Validate the import file without actually importing
-- Large imports are memory-intensive because the JSON is loaded fully before validation/push.
-
-**Note:** The sync backend must be empty when importing. The import will fail if events already exist.
-
-### Config file
-
-Both MCP and sync commands require a config file (conventionally named `livestore-cli.config.ts`) that exports:
-
-## `reference/cli/config.ts`
-
-```ts filename="reference/cli/config.ts"
-
-// Re-export your app's schema (adjust path to your project)
-export { schema } from './schema.ts'
-
-// Provide a sync backend constructor
-export const syncBackend = makeWsSync({
-  url: process.env.LIVESTORE_SYNC_URL ?? 'ws://localhost:8787',
-})
-
-// Optionally, pass an auth payload (must be JSON-serializable)
-export const syncPayload = {
-  authToken: process.env.LIVESTORE_SYNC_AUTH_TOKEN,
-}
-```
-
-### `reference/cli/schema.ts`
-
-```ts filename="reference/cli/schema.ts"
-
-const events = {}
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-}
-
-const state = State.SQLite.makeState({ tables, materializers: {} })
-
-export const schema = makeSchema({ events, state })
-```
-
-## Global options
-
-- `--verbose` - Enable verbose logging
-- `--help` - Show command help