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

package/docs/building-with-livestore/state/materializers/index.md

@@ -1,300 +0,0 @@
-# Materializers
-
-Materializers are functions that allow you to write to your database in response to events. Materializers are executed in the order of the events in the eventlog.
-
-## Example
-
-## `reference/state/materializers/example.ts`
-
-```ts filename="reference/state/materializers/example.ts"
-
-export const todos = State.SQLite.table({
-  name: 'todos',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    text: State.SQLite.text(),
-    completed: State.SQLite.boolean({ default: false }),
-    previousIds: State.SQLite.json({
-      schema: Schema.Array(Schema.String),
-      nullable: true,
-    }),
-  },
-})
-
-export const table1 = State.SQLite.table({
-  name: 'settings',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    someVal: State.SQLite.integer({ default: 0 }),
-  },
-})
-
-export const table2 = State.SQLite.table({
-  name: 'preferences',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    otherVal: State.SQLite.text({ default: 'default' }),
-  },
-})
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'todoCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      text: Schema.String,
-      completed: Schema.Boolean.pipe(Schema.optional),
-    }),
-  }),
-  userPreferencesUpdated: Events.synced({
-    name: 'userPreferencesUpdated',
-    schema: Schema.Struct({ userId: Schema.String, theme: Schema.String }),
-  }),
-  factoryResetApplied: Events.synced({
-    name: 'factoryResetApplied',
-    schema: Schema.Struct({}),
-  }),
-} as const
-
-export const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text, completed }) =>
-    todos.insert({ id, text, completed: completed ?? false }),
-  ),
-  [events.userPreferencesUpdated.name]: defineMaterializer(events.userPreferencesUpdated, ({ userId, theme }) => {
-    console.log(`User ${userId} updated theme to ${theme}.`)
-    return []
-  }),
-  [events.factoryResetApplied.name]: defineMaterializer(events.factoryResetApplied, () => [
-    table1.update({ someVal: 0 }),
-    table2.update({ otherVal: 'default' }),
-  ]),
-})
-```
-
-## Reading from the database in materializers
-
-Sometimes it can be useful to query your current state when executing a materializer. This can be done by using `ctx.query` in your materializer function.
-
-## `reference/state/materializers/with-query.ts`
-
-```ts filename="reference/state/materializers/with-query.ts"
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'todoCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      text: Schema.String,
-      completed: Schema.Boolean.pipe(Schema.optional),
-    }),
-  }),
-} as const
-
-export const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text, completed }, ctx) => {
-    const previousIds = ctx.query(todos.select('id'))
-    return todos.insert({ id, text, completed: completed ?? false, previousIds })
-  }),
-})
-```
-
-### `reference/state/materializers/example.ts`
-
-```ts filename="reference/state/materializers/example.ts"
-
-export const todos = State.SQLite.table({
-  name: 'todos',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    text: State.SQLite.text(),
-    completed: State.SQLite.boolean({ default: false }),
-    previousIds: State.SQLite.json({
-      schema: Schema.Array(Schema.String),
-      nullable: true,
-    }),
-  },
-})
-
-export const table1 = State.SQLite.table({
-  name: 'settings',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    someVal: State.SQLite.integer({ default: 0 }),
-  },
-})
-
-export const table2 = State.SQLite.table({
-  name: 'preferences',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    otherVal: State.SQLite.text({ default: 'default' }),
-  },
-})
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'todoCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      text: Schema.String,
-      completed: Schema.Boolean.pipe(Schema.optional),
-    }),
-  }),
-  userPreferencesUpdated: Events.synced({
-    name: 'userPreferencesUpdated',
-    schema: Schema.Struct({ userId: Schema.String, theme: Schema.String }),
-  }),
-  factoryResetApplied: Events.synced({
-    name: 'factoryResetApplied',
-    schema: Schema.Struct({}),
-  }),
-} as const
-
-export const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text, completed }) =>
-    todos.insert({ id, text, completed: completed ?? false }),
-  ),
-  [events.userPreferencesUpdated.name]: defineMaterializer(events.userPreferencesUpdated, ({ userId, theme }) => {
-    console.log(`User ${userId} updated theme to ${theme}.`)
-    return []
-  }),
-  [events.factoryResetApplied.name]: defineMaterializer(events.factoryResetApplied, () => [
-    table1.update({ someVal: 0 }),
-    table2.update({ otherVal: 'default' }),
-  ]),
-})
-```
-
-## Transactional behaviour
-
-A materializer is always executed in a transaction. This transaction applies to:
-- All database write operations returned by the materializer.
-- Any `ctx.query` calls made within the materializer, ensuring a consistent view of the data.
-
-Materializers can return:
-- A single database write operation.
-- An array of database write operations.
-- `void` (i.e., no return value) if no database modifications are needed.
-- An `Effect` that resolves to one of the above (e.g., `Effect.succeed(writeOp)` or `Effect.void`).
-
-The `context` object passed to each materializer provides `query` for database reads, `db` for direct database access if needed, and `event` for the full event details.
-
-## Error handling
-
-If a materializer function throws an error, or if an `Effect` returned by a materializer fails, the entire transaction for that event will be rolled back. This means any database changes attempted by that materializer for the failing event will not be persisted. The error will be logged, and the system will typically halt or flag the event as problematic, depending on the specific LiveStore setup.
-
-If the error happens on the client which tries to commit the event, the event will never be committed and pushed to the sync backend.
-
-In the future there will be ways to configure the error-handling behaviour, e.g. to allow skipping an incoming event when a materializer fails in order to avoid the app getting stuck. However, skipping events might also lead to diverging state across clients and should be used with caution.
-
-## Best practices
-
-### Side-effect free / deterministic
-
-It's strongly recommended to make sure your materializers are side-effect free and deterministic. This also implies passing in all necessary data via the event payload.
-
-Example:
-
-## `reference/state/materializers/deterministic.ts`
-
-```ts filename="reference/state/materializers/deterministic.ts"
-
-declare const store: Store
-
-export const nondeterministicEvents = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ text: Schema.String }),
-  }),
-} as const
-
-export const nondeterministicMaterializers = State.SQLite.materializers(nondeterministicEvents, {
-  [nondeterministicEvents.todoCreated.name]: defineMaterializer(nondeterministicEvents.todoCreated, ({ text }) =>
-    todos.insert({ id: randomUUID(), text }),
-  ),
-})
-
-store.commit(nondeterministicEvents.todoCreated({ text: 'Buy groceries' }))
-
-export const deterministicEvents = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-export const deterministicMaterializers = State.SQLite.materializers(deterministicEvents, {
-  [deterministicEvents.todoCreated.name]: defineMaterializer(deterministicEvents.todoCreated, ({ id, text }) =>
-    todos.insert({ id, text }),
-  ),
-})
-
-store.commit(deterministicEvents.todoCreated({ id: nanoid(), text: 'Buy groceries' }))
-```
-
-### `reference/state/materializers/example.ts`
-
-```ts filename="reference/state/materializers/example.ts"
-
-export const todos = State.SQLite.table({
-  name: 'todos',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    text: State.SQLite.text(),
-    completed: State.SQLite.boolean({ default: false }),
-    previousIds: State.SQLite.json({
-      schema: Schema.Array(Schema.String),
-      nullable: true,
-    }),
-  },
-})
-
-export const table1 = State.SQLite.table({
-  name: 'settings',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    someVal: State.SQLite.integer({ default: 0 }),
-  },
-})
-
-export const table2 = State.SQLite.table({
-  name: 'preferences',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    otherVal: State.SQLite.text({ default: 'default' }),
-  },
-})
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'todoCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      text: Schema.String,
-      completed: Schema.Boolean.pipe(Schema.optional),
-    }),
-  }),
-  userPreferencesUpdated: Events.synced({
-    name: 'userPreferencesUpdated',
-    schema: Schema.Struct({ userId: Schema.String, theme: Schema.String }),
-  }),
-  factoryResetApplied: Events.synced({
-    name: 'factoryResetApplied',
-    schema: Schema.Struct({}),
-  }),
-} as const
-
-export const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text, completed }) =>
-    todos.insert({ id, text, completed: completed ?? false }),
-  ),
-  [events.userPreferencesUpdated.name]: defineMaterializer(events.userPreferencesUpdated, ({ userId, theme }) => {
-    console.log(`User ${userId} updated theme to ${theme}.`)
-    return []
-  }),
-  [events.factoryResetApplied.name]: defineMaterializer(events.factoryResetApplied, () => [
-    table1.update({ someVal: 0 }),
-    table2.update({ otherVal: 'default' }),
-  ]),
-})
-```

package/docs/building-with-livestore/state/sql-queries/index.md

@@ -1,94 +0,0 @@
-# SQL queries
-
-## Query builder
-
-LiveStore also provides a small query builder for the most common queries. The query builder automatically derives the appropriate result schema internally.
-
-## `reference/state/sql-queries/query-builder.ts`
-
-```ts filename="reference/state/sql-queries/query-builder.ts"
-
-const table = State.SQLite.table({
-  name: 'my_table',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    name: State.SQLite.text(),
-    tags: State.SQLite.json({ schema: Schema.Array(Schema.String), default: [] }),
-  },
-})
-
-// Read queries
-table.select('name')
-table.where('name', '=', 'Alice')
-table.where({ name: 'Alice' })
-table.orderBy('name', 'desc').offset(10).limit(10)
-table.count().where('name', 'LIKE', '%Ali%')
-
-// JSON array containment queries
-// NOTE: These use SQLite's json_each() which cannot be indexed
-table.where({ tags: { op: 'JSON_CONTAINS', value: 'important' } })
-table.where({ tags: { op: 'JSON_NOT_CONTAINS', value: 'archived' } })
-
-// Write queries
-table.insert({ id: '123', name: 'Bob' })
-table.update({ name: 'Alice' }).where({ id: '123' })
-table.delete().where({ id: '123' })
-
-// Upserts (insert or update on conflict)
-table.insert({ id: '123', name: 'Charlie' }).onConflict('id', 'replace')
-table.insert({ id: '456', name: 'Diana' }).onConflict('id', 'update', { name: 'Diana Updated' })
-```
-
-## Raw SQL queries
-
-LiveStore supports arbitrary SQL queries on top of SQLite. In order for LiveStore to handle the query results correctly, you need to provide the result schema.
-
-## `reference/state/sql-queries/raw-sql.ts`
-
-```ts filename="reference/state/sql-queries/raw-sql.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps reactive references */
-// ---cut---
-
-const table = State.SQLite.table({
-  name: 'my_table',
-  columns: {
-    id: State.SQLite.text({ primaryKey: true }),
-    name: State.SQLite.text(),
-  },
-})
-
-const filtered$ = queryDb({
-  query: sql`select * from my_table where name = 'Alice'`,
-  schema: Schema.Array(table.rowSchema),
-})
-
-const count$ = queryDb({
-  query: sql`select count(*) as count from my_table`,
-  schema: Schema.Struct({ count: Schema.Number }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse()),
-})
-```
-
-## JSON array containment
-
-For JSON array columns, you can use `JSON_CONTAINS` and `JSON_NOT_CONTAINS` operators to check if an array contains (or doesn't contain) a specific value:
-
-```ts
-// Find items with a specific tag
-table.where({ tags: { op: 'JSON_CONTAINS', value: 'important' } })
-
-// Find items without a specific tag
-table.where({ tags: { op: 'JSON_NOT_CONTAINS', value: 'archived' } })
-```
-
-:::caution[Performance consideration]
-These operators use SQLite's `json_each()` table-valued function which **cannot be indexed** and requires a full table scan. For large tables with frequent lookups, consider denormalizing the data into a separate indexed table.
-:::
-
-## Best practices
-
-- Query results should be treated as immutable/read-only
-- For queries which could return many rows, it's recommended to paginate the results
-  - Usually both via paginated/virtualized rendering as well as paginated queries
-	- You'll get best query performance by using a `WHERE` clause over an indexed column combined with a `LIMIT` clause. Avoid `OFFSET` as it can be slow on large tables
-- For very large/complex queries, it can also make sense to implement incremental view maintenance (IVM) for your queries
-  - You can for example do this by have a separate table which is a materialized version of your query results which you update manually (and ideally incrementally) as the underlying data changes.

package/docs/building-with-livestore/state/sqlite/index.md

@@ -1,45 +0,0 @@
-# SQLite in LiveStore
-
-LiveStore heavily uses SQLite as its default state/read model.
-
-## Implementation notes
-
-- LiveStore relies on the following SQLite extensions to be available: `-DSQLITE_ENABLE_BYTECODE_VTAB -DSQLITE_ENABLE_SESSION -DSQLITE_ENABLE_PREUPDATE_HOOK`
-  - [bytecode](https://www.sqlite.org/bytecodevtab.html)
-  - [session](https://www.sqlite.org/sessionintro.html) (incl. preupdate)
-
-- For web / node adapter:
-  - LiveStore uses [a fork](https://github.com/livestorejs/wa-sqlite) of the [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) SQLite WASM library.
-  - Write‑ahead logging (WAL) is currently not supported/enabled for the web adapter using OPFS (AccessHandlePoolVFS). The underlying VFS does not support WAL reliably in this setup; we disable it until it’s safe to use. See our tracking issue and upstream notes:
-    - LiveStore: https://github.com/livestorejs/livestore/issues/258
-    - wa‑sqlite examples (comparison table shows WAL unsupported for AccessHandlePoolVFS): https://github.com/rhashimoto/wa-sqlite/blob/master/src/examples/README.md
-    - Related discussion on single‑connection OPFS and locking: https://github.com/rhashimoto/wa-sqlite/discussions/81
-  - In the future LiveStore might use a non‑WASM build for Node/Bun/Deno/etc.
-- For Expo adapter:
-  - LiveStore uses the official expo-sqlite library which supports LiveStore's SQLite requirements.
-
-- LiveStore uses the `session` extension to enable efficient database rollback which is needed when the eventlog is rolled back as part of a rebase. An alternative implementation strategy would be to rely on snapshotting (i.e. periodically create database snapshots and roll back to the latest snapshot + applied missing mutations).
-
-## Default tables
-
-LiveStore operates two SQLite databases by default: a state database (your materialized tables) and an event log database (the immutable event stream and sync metadata). In addition to your own application tables, LiveStore creates a small set of internal tables in each database.
-
-### State database
-
-- `__livestore_schema`
-  - Tracks the schema hash and last update time per materialized table. Used for migrations and compatibility checks.
-- `__livestore_schema_event_defs`
-  - Tracks the schema hash and last update time per event definition. Used to detect incompatible event schema changes during rematerialization.
-- `__livestore_session_changeset`
-  - Stores SQLite session changeset blobs keyed by event sequence numbers. Used to efficiently roll back and re‑apply state during rebases.
-- Your application tables
-  - All tables you define via `State.SQLite.table(...)` live in the state database.
-
-### Eventlog database
-
-- `eventlog`
-  - Append‑only table containing all events (sequence numbers, parent links, event name, encoded args, client/session IDs, schema hash, optional sync metadata). Used to reconstruct state and for sync.
-- `__livestore_sync_status`
-  - Stores the current head and optional backend identity for synchronization bookkeeping.
-
-Note: The event log database’s use of SQLite is an implementation detail. It is not a public interface and is not intended for direct reads or writes. Query state via your materialized tables and LiveStore APIs; do not depend on the event log database layout or mutate it directly.