@livequery/client 2.0.133 → 2.0.135

package/README.md

@@ -2,37 +2,24 @@
 
 Reactive local-first data primitives for browser clients.
 
-This repository is the client library package, not an application. Changes here should preserve reusable public API behavior unless a task explicitly targets a breaking change.
+`@livequery/client` is a client library, not an application framework. It gives you a small set of reusable primitives for local storage, remote transport, reactive collections, reactive documents, optimistic mutations, filtering, sorting, pagination cursors, and action triggers.
 
-This package provides the core building blocks behind Livequery collections: reactive document state, pluggable local storage, pluggable transporters, optimistic mutations, and typed inline filters.
+The package is ESM-first and currently targets browser clients. `LivequeryCollection.initialize()` returns early when `window` is unavailable, so do not treat the collection wrapper as SSR-safe state by default.
 
-## AI Agent Guidance
-
-Repository-specific agent guidance lives in `AGENTS.md` and `copilot-instructions.md`.
-
-- `AGENTS.md` is the implementation-focused guide for coding agents modifying this package.
-- `copilot-instructions.md` provides repo-level instructions for Copilot when generating or reviewing code in this workspace.
-- Both documents assume this repo is a library package, so agent changes should avoid app-specific scaffolding and should preserve public API compatibility by default.
-- Agents generating consumer code should also follow the usage patterns documented below: create a shared `LivequeryClient`, initialize collections before querying, and subscribe to collection state instead of relying on one-time `.value` reads.
-
-## Installation
+## Install
 
 ```bash
 bun add @livequery/client rxjs
 ```
 
-For React projects:
+For React projects you may also use a React bridge package if your app has one:
 
 ```bash
 bun add @livequery/client @livequery/react rxjs
 ```
 
-The package is published as ESM and targets browser usage.
-
 ## Public Exports
 
-The package re-exports:
-
 ```ts
 export * from "./LivequeryCollection"
 export * from "./LivequeryClient"
@@ -44,49 +31,9 @@ export * from "./helpers/filterDocs"
 export * from "./LivequeryDocument"
 ```
 
-## Core Types
-
-### `Doc`
-
-Every record must have an `id`.
-
-```ts
-type Doc<T = {}> = T & {
-  id: string
-}
-```
-
-### `DocState`
-
-Collections and documents expose `DocState<T>`, which adds optimistic mutation metadata.
-
-```ts
-type DocState<T extends Doc> = T & {
-  _deleting?: boolean
-  _deleting_error?: { code: string; message: string; transporter_id: string }
-  _updating?: boolean
-  _updating_error?: { code: string; message: string; transporter_id: string }
-  _adding?: boolean
-  _adding_error?: { code: string; message: string; transporter_id: string }
-  _remotes?: Record<string, string | number>
-  _prev?: Partial<T>
-}
-```
-
-### `DataChangeEvent`
-
-Transporters stream incremental change events back into the client.
+The public storage interface is intentionally named `LivequeryStorge`. The spelling is part of the current public API.
 
-```ts
-type DataChangeEvent = {
-  collection_ref: string
-  id: string
-  type: "added" | "removed" | "modified"
-  data?: Record<string, any>
-}
-```
-
-## Architecture
+## Mental Model
 
 ```text
 LivequeryCollection / LivequeryDocument
@@ -98,19 +45,30 @@ LivequeryCollection / LivequeryDocument
 LivequeryStorge  LivequeryTransporter(s)
 ```
 
-- `LivequeryCollection` owns the reactive state for one collection ref or one document ref.
-- `LivequeryDocument` wraps an item as a `BehaviorSubject` with convenience mutation methods.
-- `LivequeryClient` coordinates storage, transporters, optimistic writes, and fan-out to watchers.
-- `LivequeryStorge` is the local persistence contract.
-- `LivequeryTransporter` is the remote sync contract.
+- `LivequeryClient` is the coordination core. It owns collection registrations, query orchestration, transporter fan-out, local storage writes, broadcast delivery, and optimistic mutation reconciliation.
+- `LivequeryCollection<T>` is the main consumer-facing list or document wrapper. It exposes reactive subjects such as `items`, `loading`, `filters`, `paging`, `summary`, and `error`.
+- `LivequeryDocument<T>` wraps one document in a `BehaviorSubject` and forwards `update`, `del`, `trigger`, and `select` calls to its collection.
+- `LivequeryStorge` is the local persistence contract used by the client.
+- `LivequeryMemoryStorage` is the in-memory reference storage adapter.
+- `LivequeryTransporter` is the remote sync/action contract.
+
+## Refs
+
+Livequery distinguishes collection refs and document refs by path segment count:
+
+- Collection ref: odd number of path segments, for example `todos` or `users/user-1/posts`.
+- Document ref: even number of path segments, for example `todos/todo-1` or `users/user-1/posts/post-1`.
+
+`LivequeryCollection.initialize(ref)` derives `collection_ref` from this rule. For `todos/todo-1`, the collection ref is `todos` and the document id is `todo-1`.
 
 ## Quick Start
 
 ```ts
 import {
-  LivequeryCollection,
   LivequeryClient,
+  LivequeryCollection,
   LivequeryMemoryStorage,
+  type DataChangeEvent,
   type Doc,
   type LivequeryQueryResult,
   type LivequeryTransporter,
@@ -126,11 +84,25 @@ type Todo = Doc<{
 const storage = new LivequeryMemoryStorage()
 
 const transporter: LivequeryTransporter = {
-  query(_query) {
+  query(query) {
+    const changes: DataChangeEvent[] = [
+      {
+        collection_ref: query.ref,
+        id: "todo-1",
+        type: "added",
+        data: {
+          id: "todo-1",
+          title: "Read the docs",
+          done: false,
+          createdAt: Date.now(),
+        },
+      },
+    ]
+
     return of<Partial<LivequeryQueryResult>>({
-      changes: [],
-      summary: {},
-      paging: { total: 0, current: 0 },
+      changes,
+      paging: { total: 1, current: 1 },
+      summary: { open: 1 },
       metadata: {},
       source: "query",
     })
@@ -138,14 +110,14 @@ const transporter: LivequeryTransporter = {
   async add(_ref, doc) {
     return { id: crypto.randomUUID(), ...doc } as Todo
   },
-  async update(_ref, id, doc) {
-    return { id, ...doc } as Todo
+  async update(_ref, id, patch) {
+    return { id, ...patch } as Todo
   },
   async delete(_ref, id) {
     return { id } as Todo
   },
-  async trigger(_action) {
-    return { ok: true }
+  async trigger(action) {
+    return { ok: true, action: action.action }
   },
 }
 
@@ -157,216 +129,490 @@ const client = new LivequeryClient({
 })
 
 const todos = new LivequeryCollection<Todo>(client, {
-  filters: { "createdAt:sort": "desc" },
-  mode: "server-first",
+  mode: "cache-first",
+  filters: {
+    "createdAt:sort": "desc",
+  },
 })
 
 todos.initialize("todos")
 
-todos.items.subscribe((items) => {
-  console.log(items.map((doc) => doc.value))
+const subscription = todos.items.subscribe((items) => {
+  console.log(items.map((item) => item.value))
+})
+
+await todos.query({
+  ":limit": 20,
+  "done:boolean": "false",
+  "createdAt:sort": "desc",
+})
+
+await todos.add({
+  title: "Ship feature",
+  done: false,
+  createdAt: Date.now(),
+})
+
+await todos.update({
+  id: "todo-1",
+  done: true,
 })
 
-await todos.query({ ":limit": 20, "createdAt:sort": "desc" })
-await todos.add({ title: "Buy milk", done: false, createdAt: Date.now() })
-await todos.update("todo-1", { done: true })
 await todos.delete("todo-1")
 
-// Override mutation behavior when needed
-await todos.add({ title: "Draft", done: false, createdAt: Date.now() }, "local-only")
+subscription.unsubscribe()
 ```
 
+## Core Types
+
+### `Doc`
+
+Every document must have an `id`.
+
+```ts
+type Doc<T = {}> = T & {
+  id: string
+}
+```
+
+Use it to define app records:
+
+```ts
+type Post = Doc<{
+  title: string
+  published: boolean
+  author: {
+    id: string
+    name: string
+  }
+}>
+```
+
+### `DocState`
+
+`DocState<T>` is the runtime shape exposed by collections and documents. It includes your document fields plus internal optimistic metadata.
+
+```ts
+type DocState<T extends Doc> = T & {
+  _deleting?: boolean
+  _local_only?: boolean
+  _deleting_error?: { code: string; message: string; transporter_id: string }
+  _updating?: boolean
+  _updating_error?: { code: string; message: string; transporter_id: string }
+  _adding?: boolean
+  _adding_error?: { code: string; message: string; transporter_id: string }
+  _remotes?: Record<string, string | number>
+  _prev?: Record<string, any>
+  _selected?: boolean
+  _index?: number
+}
+```
+
+Do not strip `_adding`, `_updating`, `_deleting`, or error fields if your UI needs to show mutation progress or failure state.
+
+### `DataChangeEvent`
+
+Transporter query streams and internal broadcasts use incremental change events:
+
+```ts
+type DataChangeEvent = {
+  collection_ref: string
+  id: string
+  type: "added" | "removed" | "modified"
+  data?: Record<string, any>
+}
+```
+
+Events are incremental, not full snapshot replacements. A `modified` event may contain only changed fields.
+
 ## `LivequeryClient`
 
-Create one client with a storage adapter and one or more transporters:
+`LivequeryClient` coordinates storage, transporters, query streams, optimistic writes, and collection broadcasts.
 
 ```ts
 const client = new LivequeryClient({
-  storage,
+  storage: new LivequeryMemoryStorage(),
   transporters: {
     primary: transporter,
   },
 })
 ```
 
-### Mutation flow
+### Constructor
+
+```ts
+new LivequeryClient({
+  storage,
+  transporters,
+})
+```
+
+- `storage`: a `LivequeryStorge` adapter.
+- `transporters`: a map of transporter id to `LivequeryTransporter`. Use one transporter for a simple app. Use multiple transporters when the same client should fan out to more than one backend.
+
+### `watch(ref, collection_id, mode)`
+
+Registers a collection or document watcher and returns an observable data stream.
+
+Most app code should not call `watch()` directly. `LivequeryCollection.initialize()` calls it for you. Use it only when building a custom wrapper around `LivequeryClient`.
+
+### `query(req)`
+
+Lower-level query entry point used by `LivequeryCollection.query()`.
+
+```ts
+await client.query<Todo>({
+  ref: "todos",
+  collection_id: todos.id,
+  filters: { "done:boolean": "false" },
+})
+```
+
+Consumers should usually call `collection.query(filters)` instead.
+
+### `add(collection_ref, documents, mode)`
+
+Lower-level mutation entry point used by `LivequeryCollection.add()`.
+
+- `server-first`: push to transporters first.
+- `local-first`: add to storage with `_adding: true`, broadcast locally, then push remote and reconcile.
+- `local-only`: add to storage with `_adding: true` and `_local_only: true`, broadcast locally, and skip transporters.
+
+### `update(collection_ref, documents, mode)`
+
+Lower-level mutation entry point used by `LivequeryCollection.update()`.
 
-For `add`, `update`, and `delete`, behavior depends on action mode:
+For local-first style updates, the client reads the old local document, records previous field values in `_prev`, stores `_updating: true`, broadcasts a `modified` event, then pushes only changed fields to transporters.
 
-1. `server-first`: pushes directly to transporters and returns transporter results.
-2. `local-first`: writes optimistic state to local storage, broadcasts changes, then pushes to transporters and reconciles flags/errors.
-3. `local-only`: writes locally and broadcasts only; no transporter calls are made.
+### `delete(collection_ref, ids, mode)`
 
-Documents created locally receive ids prefixed with `local:` until a transporter returns a persisted id.
+Lower-level delete entry point used by `LivequeryCollection.delete()`.
 
-### Query modes
+- Local-only documents and explicit `local-only` deletes are hard-deleted from storage.
+- Documents with transporters are soft-deleted first with `_deleting: true`, then hard-deleted after remote confirmation.
+- Remote delete errors are persisted as `_deleting_error`.
 
-Collections support four modes through `LivequeryCollectionOptions.mode`:
+### `trigger(action)`
 
-- `server-first`: queries are driven by transporters, and collection state is built from streamed change events.
-- `cache-first`: first query can hydrate from local storage, then transporters refresh the result.
-- `local-first`: queries resolve from local storage while remote sync runs in the background and rebroadcasts matching changes.
-- `local-only`: queries resolve exclusively from local storage. No transporters are contacted for reads. Mutations run in `local-only` mode are kept local and never pushed to any transporter.
+Calls transporter `trigger()` methods and returns an RxJS observable.
 
-Implementation detail: in `local-first` mode, filters are applied by the storage adapter, while the remote query path is triggered with empty filters and matching is re-checked when added events are broadcast locally. In `local-only` mode the transporter path is skipped for queries, and mutations stay local only when you explicitly execute them with `mode: "local-only"`.
+```ts
+client.trigger<{ archived: boolean }>({
+  ref: "todos",
+  action: "archive-done",
+  payload: { olderThan: Date.now() - 7 * 86400_000 },
+  transporter_id: "primary",
+})
+```
 
-### Local-only guide
+Use `collection.trigger()` for normal consumer code.
 
-For a focused walkthrough of local-only behavior, use cases, and caveats, see [docs/local-only.md](docs/local-only.md).
+### `flush(collection_ref)`
 
-This behavior description is aligned with the current `2.0.123` release line.
+Broadcasts a wildcard local removal for a collection and clears storage.
+
+```ts
+await client.flush("todos")
+```
+
+This is broad because the current storage contract has `flush(): Promise<void>` without a collection argument.
+
+### `destroy()`
+
+Unsubscribes the client's internal query pipelines. Call it when permanently disposing a client instance.
 
 ## `LivequeryCollection`
 
-`LivequeryCollection<T>` manages one collection or one document ref.
+`LivequeryCollection<T>` is the primary app-facing API. It manages one collection ref or one document ref and exposes reactive state through `BehaviorSubject`s.
+
+```ts
+const todos = new LivequeryCollection<Todo>(client, {
+  mode: "local-first",
+  lazy: false,
+  debounce: 250,
+  filters: {
+    "done:boolean": "false",
+    "createdAt:sort": "desc",
+  },
+})
+```
+
+### Options
 
 ```ts
 type LivequeryCollectionOptions<T extends Doc> = {
-  client: LivequeryClient
   filters: Partial<LivequeryFilters<T>>
   lazy: boolean
   debounce: number
-  mode: "server-first" | "local-first" | "cache-first" | "local-only"
+  mode: "server-first" | "cache-first" | "local-first" | "local-only"
 }
 ```
 
-### Create and initialize a collection
+- `filters`: initial query filters.
+- `lazy`: when not `true`, `initialize()` schedules an automatic query with current filters.
+- `debounce`: enables `debounceQuery()`.
+- `mode`: controls query behavior. Mutation methods still default to `server-first` unless you pass a mode override.
 
-The current constructor takes `client` as the first argument and options as the second argument.
+### Reactive Properties
 
 ```ts
-const posts = new LivequeryCollection<Post>(client, {
-  filters: { "publishedAt:sort": "desc" },
-  lazy: false,
-  debounce: 250,
+items: BehaviorSubject<LivequeryDocument<DocState<T>>[]>
+summary: BehaviorSubject<Record<string, any>>
+loading: BehaviorSubject<null | "all" | "next" | "prev">
+filters: BehaviorSubject<Partial<LivequeryFilters<T>>>
+paging: BehaviorSubject<LivequeryPaging>
+selected: BehaviorSubject<Set<string>>
+error: BehaviorSubject<{ code: string; message: string } | null>
+ref: string | undefined
+collection_ref: string | undefined
+id: string
+```
+
+Reading `.value` gives a snapshot. Subscribe for live updates:
+
+```ts
+const sub = todos.items.subscribe((documents) => {
+  for (const document of documents) {
+    console.log(document.value.id, document.value.title)
+  }
+})
+
+sub.unsubscribe()
+```
+
+### `initialize(ref)`
+
+Initializes the collection and registers it with the client.
+
+```ts
+todos.initialize("todos")
+```
+
+Call `initialize()` before `query()`, `add()`, `update()`, `delete()`, `trigger()`, or `flush()`. The method returns a subscription when running in the browser. It returns early on the server.
+
+### `query(filters)`
+
+Runs a query and replaces current `items` when cached/local documents are returned.
+
+```ts
+await todos.query({
+  ":limit": 20,
+  "done:boolean": "false",
+  "createdAt:sort": "desc",
+})
+```
+
+### `debounceQuery(filters)`
+
+Pushes filters into a debounced query subject. This only has an effect when the collection was created with a truthy `debounce` option.
+
+```ts
+const searchTodos = new LivequeryCollection<Todo>(client, {
   mode: "cache-first",
+  debounce: 300,
 })
 
-posts.initialize("posts")
+searchTodos.initialize("todos")
+await searchTodos.debounceQuery({ "title:like": "milk" })
 ```
 
-`initialize(ref)` subscribes the collection to `LivequeryClient.watch(ref, id, mode)`. In the current implementation, it is browser-only and returns early when `window` is unavailable.
+### `sort(field, order)`
 
-### Collection refs and document refs
+Sorts by a field or resets to insertion order.
 
-If a ref has an even number of path segments, the last segment is treated as a document id.
+```ts
+await todos.sort("createdAt", "desc")
+await todos.sort("title", "asc")
+await todos.sort("reset", "asc")
+```
+
+For non-`local-only` collections, sorting calls `query()` with a `field:sort` filter. For `local-only`, sorting is applied to current items in memory.
+
+### `loadMore()`, `loadPrev()`, `loadAround(cursor)`
+
+Cursor helpers based on `paging.value`.
 
 ```ts
-posts.initialize("posts")
-singlePost.initialize("posts/post-1")
+if (todos.paging.value.next) {
+  await todos.loadMore()
+}
+
+if (todos.paging.value.prev) {
+  await todos.loadPrev()
+}
+
+await todos.loadAround("cursor-123")
 ```
 
-For collection mutations, `add`, `update`, and `delete` always target the collection portion of the ref.
+- `loadMore()` adds `:after`.
+- `loadPrev()` adds `:before`.
+- `loadAround(cursor)` currently sets both `:after` and `:before` to the same cursor.
+
+### `add(payload, mode?)`
+
+Adds one or many documents.
+
+```ts
+const todo = await todos.add({
+  title: "Buy milk",
+  done: false,
+  createdAt: Date.now(),
+})
+
+const localDraft = await todos.add(
+  { title: "Draft", done: false, createdAt: Date.now() },
+  "local-only"
+)
+
+const many = await todos.add([
+  { title: "A", done: false, createdAt: Date.now() },
+  { title: "B", done: false, createdAt: Date.now() },
+])
+```
 
-### Reactive state
+The return shape follows the input shape: one payload returns one document; an array returns an array.
 
-- `items`: `BehaviorSubject<LivequeryDocument<DocState<T>>[]>`
-- `summary`: `BehaviorSubject<Record<string, any>>`
-- `loading`: `BehaviorSubject<null | "all" | "next" | "prev">`
-- `filters`: `BehaviorSubject<Partial<LivequeryFilters<T>>>`
-- `paging`: `BehaviorSubject<LivequeryPaging>`
-- `error`: `BehaviorSubject<{ code: string; message: string } | null>`
+Important: the current method signature defaults `mode` to `"server-first"`. A collection configured with `mode: "local-only"` still needs `add(payload, "local-only")` if you want the mutation to stay local.
 
-`items` is a `BehaviorSubject`, not a plain array. Reading `collection.items.value` gives the current snapshot only. If you need live updates, subscribe.
+### `update(payload, mode?)`
+
+Updates one or many documents. Include `id` in every payload.
 
 ```ts
-const subscription = posts.items.subscribe((items) => {
-  console.log("realtime items", items.map((doc) => doc.value))
+await todos.update({
+  id: "todo-1",
+  done: true,
 })
 
-subscription.unsubscribe()
+await todos.update(
+  { id: "todo-1", title: "Local title" },
+  "local-only"
+)
+
+await todos.update([
+  { id: "todo-1", done: true },
+  { id: "todo-2", done: false },
+])
 ```
 
-In React, reading only `collection.items.value` during render will not trigger rerenders when new events arrive. Bridge the `BehaviorSubject` into component state.
+### `delete(idOrIds, mode?)`
 
-```tsx
-function TodoList({ collection }: { collection: LivequeryCollection<Todo> }) {
-  const [items, setItems] = useState(() => collection.items.value)
+Deletes one or many documents.
 
-  useEffect(() => {
-    const subscription = collection.items.subscribe(setItems)
-    return () => subscription.unsubscribe()
-  }, [collection])
+```ts
+await todos.delete("todo-1")
+await todos.delete(["todo-1", "todo-2"])
+await todos.delete("todo-draft", "local-only")
+```
 
-  return (
-    <ul>
-      {items.map((item) => (
-        <li key={item.value.id}>{item.value.title}</li>
-      ))}
-    </ul>
-  )
-}
+### `select(mode, id?)`
+
+Maintains `selected` state and writes `_selected` back into documents with local-only updates.
+
+```ts
+todos.select("all")
+todos.select("none")
+todos.select("toggle")
+todos.select("toggle", "todo-1")
+todos.select(true, "todo-1")
+todos.select(false, "todo-1")
 ```
 
-### Main methods
+### `trigger(action, payload?, transporter_id?)`
+
+Calls transporter actions for this collection ref.
 
 ```ts
-type ActionMode = "server-first" | "local-first" | "local-only"
+const result = await todos.trigger<{ count: number }>("archive-done", {
+  olderThan: Date.now() - 7 * 86400_000,
+})
 
-query(filters: Partial<LivequeryFilters<T>>): Promise<void>
-debounceQuery(filters: Partial<LivequeryFilters<T>>): Promise<void>
-loadMore(): Promise<void>
-loadPrev(): Promise<void>
-loadAround(cursor: string): Promise<void>
-add<Input extends Partial<T> | Partial<T>[]>(payload: Input, mode?: ActionMode): Promise<Input extends Partial<T>[] ? T[] : T>
-update<Input extends Partial<T> | Partial<T>[]>(id: string, payload: Input, mode?: ActionMode): Promise<Input extends Partial<T>[] ? T[] : T>
-delete<Input extends string | string[]>(id: Input, mode?: ActionMode): Promise<Input extends string[] ? DocState<T>[] : DocState<T>>
-trigger<R>(action: string, payload?: Record<string, any>): Observable<{ data: R; error?: Error }> & PromiseLike<R>
-resetError(): void
-watch(check: (prev: T, next: T) => boolean): Observable<[DocState<T>, DocState<T>]>
+todos.trigger("refresh-index").subscribe((value) => {
+  console.log(value)
+})
 ```
 
-Notes about current behavior:
+The returned value is an observable with a Promise-like `then()` method.
 
-- `query()` requires `initialize()` to have run first so the collection has a `ref` and watcher registration.
-- `debounceQuery()` only emits through the debounced path when `options.debounce` is truthy.
-- `loadMore()` uses `paging.next.cursor` as `:after`.
-- `loadPrev()` uses `paging.prev.cursor` as `:before`.
-- `loadAround()` currently sets both `:after` and `:before` to the provided cursor.
-- `add`, `update`, and `delete` accept a mode override. In the current implementation, omitted mode defaults to `"server-first"`.
-- In `"server-first"`, mutations are remote-first and do not rely on optimistic local writes.
-- `add(payload, "local-only")` stores the document in local storage only and never contacts any transporter. The document receives a `local:` prefixed id and is marked with `_local_only` internally.
-- Collection mutations preserve the input shape in TypeScript: pass one item and you get one result; pass an array and you get an array.
-- `mode: "local-only"` on the collection controls query behavior. To keep a mutation local-only, pass `"local-only"` explicitly to `add`, `update`, `delete`, `LivequeryDocument.update`, or `LivequeryDocument.del`.
+### `resetError()`
 
-## `LivequeryDocument`
+Clears the collection error subject.
+
+```ts
+todos.resetError()
+```
 
-Each entry inside `collection.items` is a `LivequeryDocument`, which extends `BehaviorSubject<DocState<T>>`.
+### `watch(check)`
+
+Watches pairwise document changes and emits when `check(prev, next)` returns `true`.
 
 ```ts
-class LivequeryDocument<T extends Doc> extends BehaviorSubject<DocState<T>> {
-  update(data: Partial<T>, mode?: ActionMode): Promise<T | undefined>
-  del(mode?: ActionMode): Promise<DocState<T> | undefined>
-  trigger<R>(action: string, payload: Record<string, any>): Observable<{ data: R; error?: Error }> & PromiseLike<R>
-}
+const doneSub = todos.watch((prev, next) => prev.done !== next.done).subscribe(([prev, next]) => {
+  console.log(prev.id, "done changed", prev.done, "=>", next.done)
+})
+
+doneSub.unsubscribe()
+```
+
+### `flush()`
+
+Flushes storage through the client for this collection's `collection_ref`.
+
+```ts
+await todos.flush()
 ```
 
-Example:
+## `LivequeryDocument`
+
+Every item in `collection.items.value` is a `LivequeryDocument<T>`. It extends `BehaviorSubject<DocState<T>>`.
 
 ```ts
 const first = todos.items.value[0]
 
-first.subscribe((doc) => {
-  console.log(doc.title, doc._updating)
+first.subscribe((value) => {
+  console.log(value.title, value._updating)
 })
+```
+
+### `update(data, mode?)`
+
+Updates the current document through its collection. The document id is added automatically.
 
+```ts
 await first.update({ done: true })
+await first.update({ title: "Local edit" }, "local-only")
+```
+
+### `del(mode?)`
+
+Deletes the current document through its collection.
+
+```ts
 await first.del()
+await first.del("local-only")
+```
 
-// Explicit local-only mutation
-await first.update({ done: false }, "local-only")
+### `trigger(action, payload?)`
 
-// Observable style
-first.trigger("archive", { reason: "completed" }).subscribe()
+Calls a collection trigger using the document's collection ref.
 
-// Promise-like style
-const archived = await first.trigger<{ archived: boolean }>("archive", { reason: "completed" })
-console.log(archived.archived)
+```ts
+await first.trigger("archive", { reason: "completed" })
+```
+
+### `select(selected)`
+
+Forwards selection changes to the parent collection.
+
+```ts
+first.select("toggle")
+first.select(true)
+first.select(false)
 ```
 
 ## `LivequeryStorge`
 
-Local persistence adapters must implement:
+Storage adapters provide local persistence and local filtering.
 
 ```ts
 type LivequeryStorge = {
@@ -378,27 +624,46 @@ type LivequeryStorge = {
     paging: LivequeryPaging
   }>
   get<T extends Doc>(ref: string, id: string): Promise<T | null>
-  add<T extends Doc>(collection: string, document: Partial<DocState<T>>): Promise<T>
-  update<T extends Doc>(collection: string, id: string, document: Record<string, any>): Promise<T | null>
-  delete<T extends Doc>(collection: string, id: string): Promise<T | null>
+  add<T extends Doc>(collection: string, document: Partial<DocState<T>>): Promise<DocState<T>>
+  update<T extends Doc>(collection: string, id: string, document: Record<string, any>): Promise<DocState<T> | null>
+  delete<T extends Doc>(collection: string, id: string): Promise<DocState<T> | null>
   flush(): Promise<void>
 }
 ```
 
-The package ships with `LivequeryMemoryStorage`, an in-memory adapter useful for tests, demos, and ephemeral state.
+Adapter guidance:
 
-### `LivequeryMemoryStorage`
+- `query()` should apply the same filter semantics as `filterDocs()` when possible.
+- `get()` must return the full local document because local broadcast filtering reads it for `modified` events.
+- `add()` should generate an id when one is missing.
+- `update()` should merge patch fields into the stored document.
+- `delete()` should return the deleted document or `null`.
+- `flush()` currently clears all storage.
 
-The built-in adapter:
+## `LivequeryMemoryStorage`
+
+The built-in in-memory adapter is useful for demos, tests, and ephemeral browser state.
+
+```ts
+const storage = new LivequeryMemoryStorage()
+
+await storage.add<Todo>("todos", {
+  title: "Local only",
+  done: false,
+  createdAt: Date.now(),
+})
+
+const page = await storage.query<Todo>("todos", {
+  "done:boolean": "false",
+  "createdAt:sort": "desc",
+})
+```
 
-- stores documents in `Map<string, Map<string, Doc>>`
-- generates a local id with `local:${crypto.randomUUID()}` when `id` is missing
-- applies filters through the exported `filterDocs()` helper
-- supports nested sort keys such as `profile.createdAt:sort`
+It stores documents in a `Map<string, Map<string, Doc>>`, generates ids with `uuidv7`, applies runtime filtering through `filterDocs()`, and supports nested path sorting such as `"author.profile.createdAt:sort"`.
 
 ## `LivequeryTransporter`
 
-Remote adapters must implement:
+Transporters connect the client to remote systems.
 
 ```ts
 type LivequeryTransporter = {
@@ -410,27 +675,139 @@ type LivequeryTransporter = {
 }
 ```
 
-### Query result shape
+### Query Streams
+
+`query()` returns an observable because transporters can emit:
+
+- initial query changes
+- pagination updates
+- summary updates
+- later realtime changes
 
 ```ts
-type LivequeryQueryResult = {
-  error: { code: string; message: string }
-  changes: DataChangeEvent[]
-  summary: Record<string, any>
-  paging: LivequeryPaging
-  metadata: Record<string, any>
-  source: "query" | "action" | "realtime"
-  loading?: "all" | "next" | "prev" | null
+import { Observable } from "rxjs"
+
+const apiTransporter: LivequeryTransporter = {
+  query(query) {
+    return new Observable((subscriber) => {
+      fetch(`/api/${query.ref}`)
+        .then((res) => res.json())
+        .then((documents: Todo[]) => {
+          subscriber.next({
+            changes: documents.map((doc) => ({
+              collection_ref: query.ref,
+              id: doc.id,
+              type: "added",
+              data: doc,
+            })),
+            paging: {
+              total: documents.length,
+              current: documents.length,
+            },
+            source: "query",
+          })
+        })
+        .catch((error) => {
+          subscriber.next({
+            error: {
+              code: "QUERY_FAILED",
+              message: String(error),
+            },
+            source: "query",
+          })
+        })
+    })
+  },
+  async add(ref, doc) {
+    const res = await fetch(`/api/${ref}`, {
+      method: "POST",
+      body: JSON.stringify(doc),
+      headers: { "content-type": "application/json" },
+    })
+    return res.json()
+  },
+  async update(ref, id, patch) {
+    const res = await fetch(`/api/${ref}/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify(patch),
+      headers: { "content-type": "application/json" },
+    })
+    return res.json()
+  },
+  async delete(ref, id) {
+    const res = await fetch(`/api/${ref}/${id}`, {
+      method: "DELETE",
+    })
+    return res.json()
+  },
+  async trigger(action) {
+    const res = await fetch(`/api/${action.ref}:trigger`, {
+      method: "POST",
+      body: JSON.stringify(action),
+      headers: { "content-type": "application/json" },
+    })
+    return res.json()
+  },
 }
 ```
 
-Transporters can emit partial results. In practice, the most useful fields are `changes`, `paging`, `summary`, `metadata`, and `error`.
+## Query Modes
+
+### `server-first`
+
+Transporters drive the query result. Collection state is built from streamed change events.
+
+Use it when remote data is the source of truth and local cache is secondary.
+
+### `cache-first`
+
+The first query can hydrate from storage, then transporters refresh in the background.
+
+Use it when fast initial UI matters but remote sync should still run.
+
+### `local-first`
+
+Storage serves the query immediately. Transporters refresh in the background. Remote query changes are written into storage and then broadcast back into matching local collections.
+
+For `local-first`, the remote query path receives empty filters. Local filtering is enforced by storage query results and by broadcast filtering.
 
-## Query Filters
+### `local-only`
 
-Filters are flat keys derived from the document type.
+Queries resolve only from storage and skip transporters. Mutations stay local only when you explicitly call them with `mode: "local-only"`.
 
-### Pagination keys
+Use it for drafts, temporary UI state, offline-only collections, or local workspaces.
+
+```ts
+const drafts = new LivequeryCollection<Todo>(client, {
+  mode: "local-only",
+})
+
+drafts.initialize("drafts")
+
+await drafts.add(
+  { title: "Unpublished draft", done: false, createdAt: Date.now() },
+  "local-only"
+)
+```
+
+## Broadcast Filtering
+
+For `local-first` and `local-only` collection watchers, `LivequeryClient` filters broadcast events against the collection's current filters before delivering them:
+
+- `added`: forwarded only when `event.data` matches filters.
+- `modified`: reads the full document from storage and forwards `modified` only if the full document still matches filters.
+- `modified` that no longer matches filters is converted to `removed` for that collection.
+- `removed`: forwarded without filter checks.
+
+Within one broadcast call, full-document reads are cached by `collection_ref/id` so multiple local collections do not repeatedly call storage for the same modified document.
+
+Current limitation: if a document was not already present in a filtered collection and a later `modified` event makes it match, the client does not yet convert that `modified` into `added`. A later query will include it.
+
+## Filters
+
+Filters are flat object keys derived from document fields.
+
+### Pagination Keys
 
 - `:limit`
 - `:before`
@@ -438,55 +815,150 @@ Filters are flat keys derived from the document type.
 - `:around`
 - `:page`
 
-### Supported operators
+### Operators
 
-- `field:sort` with `"asc" | "desc"` for string and number fields
-- `field:gt`, `field:gte`, `field:lt`, `field:lte` for numeric fields
-- `field:eq-number` for numeric equality
-- `field` for string equality
-- `field:in`, `field:nin` for string or number membership
-- `field:include` for array containment
-- `field:boolean` with `"true" | "false" | "not-true" | "not-false"`
-- `field:like` for case-insensitive substring matching on strings
-- `field:null` with `"null-only" | "not-null"`
+- `field`: strict equality
+- `field:sort`: `"asc" | "desc"`
+- `field:gt`, `field:gte`, `field:lt`, `field:lte`: numeric comparisons
+- `field:eq-number`: numeric equality after `Number(value)`
+- `field:in`, `field:nin`: membership for string or number values
+- `field:include`: array contains value
+- `field:boolean`: `"true" | "false" | "not-true" | "not-false"`
+- `field:like`: case-insensitive substring check
+- `field:null`: `"null-only" | "not-null"`
 
-Nested field paths are supported, for example `"profile.createdAt:sort"`.
+Nested field paths are supported:
 
 ```ts
-await todos.query({
-  ":limit": 20,
-  "done:boolean": "false",
-  "title:like": "milk",
-  "createdAt:gte": 1714176000000,
+await posts.query({
+  "author.id": "user-1",
+  "stats.views:gte": 100,
+  "published:boolean": "true",
+  "title:like": "livequery",
   "createdAt:sort": "desc",
 })
 ```
 
-## Helper Exports
+## Helper Functions
+
+### `filterDocs(documents, filters)`
 
-### `filterDocs()`
+Filters an array with the same runtime semantics used by `LivequeryMemoryStorage`.
 
 ```ts
 import { filterDocs } from "@livequery/client"
 
-const visible = filterDocs(docs, {
+const openTodos = filterDocs(todos, {
   "done:boolean": "false",
-  "title:like": "milk",
 })
 ```
 
-### `matchesAllFilters()`
+### `matchesAllFilters(doc, filters)`
+
+Predicate helper for checking one document.
+
+```ts
+import { matchesAllFilters } from "@livequery/client"
+
+if (matchesAllFilters(todo, { "done:boolean": "false" })) {
+  console.log("todo is open")
+}
+```
+
+## React Usage
+
+Bridge `BehaviorSubject` values into React state.
+
+```tsx
+import { useEffect, useMemo, useState } from "react"
+import { LivequeryCollection, type DocState } from "@livequery/client"
+
+function TodoList({ collection }: { collection: LivequeryCollection<Todo> }) {
+  const [items, setItems] = useState(() => collection.items.value)
+  const [loading, setLoading] = useState(() => collection.loading.value)
+
+  useEffect(() => {
+    const sub = collection.items.subscribe(setItems)
+    const loadingSub = collection.loading.subscribe(setLoading)
+    return () => {
+      sub.unsubscribe()
+      loadingSub.unsubscribe()
+    }
+  }, [collection])
+
+  return (
+    <ul aria-busy={loading !== null}>
+      {items.map((item) => (
+        <li key={item.value.id}>
+          <label>
+            <input
+              type="checkbox"
+              checked={item.value.done}
+              onChange={() => item.update({ done: !item.value.done })}
+            />
+            {item.value.title}
+            {item.value._updating ? " Saving..." : null}
+          </label>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Do not read `collection.items.value` once during render and expect the UI to stay in sync. Subscribe or use a framework-specific adapter.
+
+## Common Usage Patterns
+
+### App-Level Client
+
+Create one shared client per data boundary.
+
+```ts
+export const livequery = new LivequeryClient({
+  storage: new LivequeryMemoryStorage(),
+  transporters: {
+    primary: apiTransporter,
+  },
+})
+```
+
+### Collection Factory
+
+```ts
+export function createTodoCollection() {
+  const collection = new LivequeryCollection<Todo>(livequery, {
+    mode: "cache-first",
+    filters: {
+      "createdAt:sort": "desc",
+    },
+  })
+  collection.initialize("todos")
+  return collection
+}
+```
+
+### Document Ref
+
+```ts
+const todo = new LivequeryCollection<Todo>(client, {
+  mode: "cache-first",
+})
+
+todo.initialize("todos/todo-1")
+await todo.query({})
+```
 
-The helper module also exports `matchesAllFilters(doc, filters)` for direct predicate checks.
+A document ref still exposes `items`; the matching document is represented as a one-item collection.
 
 ## Caveats
 
-- `initialize()` is browser-only because it exits early when `window` is unavailable.
-- The public storage interface name is intentionally spelled `LivequeryStorge`, matching the source.
-- Optimistic flags such as `_adding`, `_updating`, `_deleting`, and `_prev` are system-managed fields.
-- Transporter query streams are expected to emit incremental `changes`, not full snapshots.
-- `LivequeryCollection` declares a `metadata` subject but does not initialize it in the constructor, so transporter-emitted `metadata` is not safe to rely on yet.
-- `trigger()` supports both styles: subscribe as `Observable<{ data, error? }>` or await as a Promise-like value for ergonomic async usage.
+- `LivequeryCollection.initialize()` is browser-only in the current implementation.
+- Mutations default to `server-first` because the method parameter has that default. Pass `"local-first"` or `"local-only"` explicitly when needed.
+- `LivequeryCollection` has no initialized `metadata` subject in the current constructor, so transporter `metadata` should not be considered reliable consumer state yet.
+- `trigger()` returns an observable with a Promise-like `then()` method.
+- Transporter streams should emit incremental changes. Do not send full snapshots as repeated `added` events unless the client can safely deduplicate by id.
+- There is no dedicated test suite in this package yet. Use `bun run build` for the current validation baseline.
 
 ## Development
 
@@ -501,3 +973,4 @@ Available scripts:
 - `bun run build:types`
 - `bun run build`
 - `bun run build:watch`
+- `bun run prepublishOnly`