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

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

@@ -0,0 +1,625 @@
+# 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()
+}
+```
+
+## Effect integration
+
+For applications using [Effect](https://effect.website), LiveStore provides a type-safe way to access stores through the Effect layer system via `makeStoreContext()`.
+
+### Creating a typed store context
+
+Use `makeStoreContext()` to create a typed context that preserves your schema types:
+
+## `reference/store/effect/make-store-context.ts`
+
+```ts filename="reference/store/effect/make-store-context.ts"
+
+// ---cut---
+// Define a typed store context with your schema
+export const TodoStore = Store.Tag(schema, 'todos')
+
+// Create a layer to initialize the store
+const adapter = makeAdapter({ storage: { type: 'fs' } })
+
+export const TodoStoreLayer = TodoStore.layer({
+  adapter,
+  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
+})
+```
+
+### `reference/store/effect/schema.ts`
+
+```ts filename="reference/store/effect/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 }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: 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 }),
+  ),
+  [events.todoCompleted.name]: defineMaterializer(events.todoCompleted, ({ id }) =>
+    tables.todos.update({ completed: true }).where({ id }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+export const storeTables = tables
+export const storeEvents = events
+```
+
+The factory takes your schema type as a generic parameter and returns a `StoreContext` with:
+- `Tag` - Context tag for dependency injection
+- `Layer` - Creates a layer that initializes the store
+- `DeferredTag` - For async initialization patterns
+- `DeferredLayer` - Layer providing the deferred context
+- `fromDeferred` - Layer that waits for deferred initialization
+
+### Using the store in Effect services
+
+Access the store in Effect code with full type safety and autocomplete:
+
+## `reference/store/effect/usage-in-service.ts`
+
+```ts filename="reference/store/effect/usage-in-service.ts"
+
+// ---cut---
+// Access the store in Effect code with full type safety
+const _todoService = Effect.gen(function* () {
+  // Yield the store directly (it's a Context.Tag)
+  const { store } = yield* TodoStore
+
+  // Query with autocomplete for tables
+  const todos = store.query(storeTables.todos.select())
+
+  // Commit events
+  store.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))
+
+  return todos
+})
+
+// Or use static accessors for a more functional style
+const _todoServiceAlt = Effect.gen(function* () {
+  // Query using static accessor
+  const todos = yield* TodoStore.query(storeTables.todos.select())
+
+  // Commit using static accessor
+  yield* TodoStore.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))
+
+  return todos
+})
+```
+
+### `reference/store/effect/make-store-context.ts`
+
+```ts filename="reference/store/effect/make-store-context.ts"
+
+// ---cut---
+// Define a typed store context with your schema
+export const TodoStore = Store.Tag(schema, 'todos')
+
+// Create a layer to initialize the store
+const adapter = makeAdapter({ storage: { type: 'fs' } })
+
+export const TodoStoreLayer = TodoStore.layer({
+  adapter,
+  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
+})
+```
+
+### `reference/store/effect/schema.ts`
+
+```ts filename="reference/store/effect/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 }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: 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 }),
+  ),
+  [events.todoCompleted.name]: defineMaterializer(events.todoCompleted, ({ id }) =>
+    tables.todos.update({ completed: true }).where({ id }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+export const storeTables = tables
+export const storeEvents = events
+```
+
+### Layer composition
+
+Compose store layers with your application services:
+
+## `reference/store/effect/layer-composition.ts`
+
+```ts filename="reference/store/effect/layer-composition.ts"
+
+// ---cut---
+// Define services that depend on the store
+class TodoService extends Effect.Service<TodoService>()('TodoService', {
+  effect: Effect.gen(function* () {
+    const { store } = yield* TodoStore
+
+    const createTodo = (id: string, text: string) =>
+      Effect.sync(() => store.commit(storeEvents.todoCreated({ id, text })))
+
+    const completeTodo = (id: string) => Effect.sync(() => store.commit(storeEvents.todoCompleted({ id })))
+
+    return { createTodo, completeTodo } as const
+  }),
+  dependencies: [TodoStoreLayer],
+}) {}
+
+// Compose everything into a main layer
+const MainLayer = Layer.mergeAll(TodoStoreLayer, TodoService.Default)
+
+// Use in your application
+const program = Effect.gen(function* () {
+  const todoService = yield* TodoService
+  yield* todoService.createTodo('1', 'Learn Effect')
+  yield* todoService.completeTodo('1')
+})
+
+// Provide MainLayer when running (OtelTracer is also required)
+void program.pipe(Effect.provide(MainLayer))
+```
+
+### `reference/store/effect/make-store-context.ts`
+
+```ts filename="reference/store/effect/make-store-context.ts"
+
+// ---cut---
+// Define a typed store context with your schema
+export const TodoStore = Store.Tag(schema, 'todos')
+
+// Create a layer to initialize the store
+const adapter = makeAdapter({ storage: { type: 'fs' } })
+
+export const TodoStoreLayer = TodoStore.layer({
+  adapter,
+  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
+})
+```
+
+### `reference/store/effect/schema.ts`
+
+```ts filename="reference/store/effect/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 }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: 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 }),
+  ),
+  [events.todoCompleted.name]: defineMaterializer(events.todoCompleted, ({ id }) =>
+    tables.todos.update({ completed: true }).where({ id }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+export const storeTables = tables
+export const storeEvents = events
+```
+
+### Multiple stores with Effect
+
+Each store gets a unique context tag, allowing multiple stores in the same Effect context:
+
+## `reference/store/effect/multiple-stores.ts`
+
+```ts filename="reference/store/effect/multiple-stores.ts"
+
+// For demonstration, we'll use the same schema for both stores
+const settingsSchema = mainSchema
+
+// ---cut---
+// Define multiple typed store contexts
+const MainStore = Store.Tag(mainSchema, 'main')
+const SettingsStore = Store.Tag(settingsSchema, 'settings')
+
+// Each store has its own layer
+const adapter = makeAdapter({ storage: { type: 'fs' } })
+
+const MainStoreLayer = MainStore.layer({ adapter, batchUpdates: (cb) => cb() })
+const SettingsStoreLayer = SettingsStore.layer({ adapter, batchUpdates: (cb) => cb() })
+
+// Compose layers together
+const _AllStoresLayer = Layer.mergeAll(MainStoreLayer, SettingsStoreLayer)
+
+// Both stores available in Effect code
+const _program = Effect.gen(function* () {
+  const { store: mainStore } = yield* MainStore
+  const { store: settingsStore } = yield* SettingsStore
+
+  // Each store is independently typed
+  return { mainStore, settingsStore }
+})
+```
+
+### `reference/store/effect/schema.ts`
+
+```ts filename="reference/store/effect/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 }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: 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 }),
+  ),
+  [events.todoCompleted.name]: defineMaterializer(events.todoCompleted, ({ id }) =>
+    tables.todos.update({ completed: true }).where({ id }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+export const storeTables = tables
+export const storeEvents = events
+```
+
+For more Effect patterns including Effect Atom integration, see the [Effect patterns](/patterns/effect) page.
+
+## 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/{reference → building-with-livestore}/syncing/index.md

@@ -2,7 +2,7 @@
 
 ## How it works
 
-LiveStore is based on [the idea of event-sourcing](/evaluation/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.
+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.
 
@@ -42,7 +42,7 @@ The sync backend acts as the global authority and determines the total order of
   - 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
+### Client sessions
 
 - Each client has at least one client session
 - Client sessions within the same client share local data
@@ -51,7 +51,7 @@ The sync backend acts as the global authority and determines the total order of
 - 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)
+## Auth (authentication & authorization)
 
 - TODO
   - Provide basic example
@@ -64,7 +64,7 @@ The sync backend acts as the global authority and determines the total order of
 #### Pulling events (without unpushed events)
 
 ```d2
-...@../../../base.d2
+...@../../../../src/content/base.d2
 
 shape: sequence_diagram
 
@@ -85,7 +85,7 @@ Client -> Client: "Client is in sync"
 #### Pushing events
 
 ```d2
-...@../../../base.d2
+...@../../../../src/content/base.d2
 
 shape: sequence_diagram