@livequery/core 2.0.91 → 2.0.96

package/README.md

@@ -1,76 +1,97 @@
 # @livequery/core
 
-A local-first reactive data library for browser clients. Type-safe, RxJS-based collection system with pluggable storage and transporter adapters, optimistic local mutations, and real-time synchronisation support.
-
-## Table of Contents
-
-- [Architecture](#architecture)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-  - [Doc](#doc)
-  - [LivequeryStorge](#livequerystorge)
-  - [LivequeryTransporter](#livequerytransporter)
-  - [LivequeryCore](#livequerycore)
-  - [LivequeryCollection](#livequerycollection)
-  - [LivequeryDocument](#livequerydocument)
-- [Query Filters](#query-filters)
-- [API Reference](#api-reference)
-  - [LivequeryMemoryStorage](#livequerymemorystorage)
-  - [LivequeryCollection methods](#livequerycollection-methods)
-- [Writing a Custom Transporter](#writing-a-custom-transporter)
-- [Writing a Custom Storage Adapter](#writing-a-custom-storage-adapter)
-- [Types Reference](#types-reference)
-
----
+Reactive local-first data primitives for browser clients.
 
-## Architecture
+This package provides the core building blocks behind Livequery collections: reactive document state, pluggable local storage, pluggable transporters, optimistic mutations, and typed inline filters.
+
+## Installation
 
+```bash
+bun add @livequery/core rxjs
 ```
-┌─────────────────────────────────────┐
-│          Your Application           │
-│  LivequeryCollection                │
-│  .items / .loading / .paging        │
-│  .query() / .add() / .update() / .delete()
-└──────────────┬──────────────────────┘
-               │
-┌──────────────▼──────────────────────┐
-│           LivequeryCore             │
-│  - coordinates storage & transport  │
-│  - optimistic local mutations       │
-│  - broadcasts changes to collections│
-└───────┬──────────────┬──────────────┘
-        │              │
-┌───────▼──────┐ ┌─────▼──────────────┐
-│ LivequeryStorge│ │ LivequeryTransporter│
-│  (local)     │ │  (remote backend)   │
-│              │ │  (can be many)      │
-└──────────────┘ └────────────────────┘
+
+For React projects:
+
+```bash
+bun add @livequery/core @livequery/react rxjs
 ```
 
-**Data flow for a mutation (add / update / delete):**
-1. `LivequeryCollection.add/update/delete` calls `LivequeryCore.add/update/delete`.
-2. The core applies the change to local storage immediately (optimistic update).
-3. The change is broadcast to all live collections watching the same `ref`.
-4. The core then calls every configured transporter to push the change remotely.
+The package is published as ESM and targets browser usage.
 
-**Data flow for a query:**
-1. `LivequeryCollection.query(filters)` calls `LivequeryCore.query`.
-2. The core returns locally-stored documents instantly from storage.
-3. In parallel, it fires the query against every transporter.
-4. Each transporter streams `DataChangeEvent[]` back into the collection, which merges them reactively.
+## Public Exports
 
----
+The package re-exports:
 
-## Installation
+```ts
+export * from "./LivequeryCollection"
+export * from "./LivequeryCore"
+export * from "./LivequeryMemoryStorage"
+export * from "./LivequeryStorge"
+export * from "./LivequeryTransporter"
+export * from "./types"
+export * from "./helpers/filterDocs"
+export * from "./LivequeryDocument"
+```
 
-```bash
-npm install @livequery/core rxjs
-# or
-bun add @livequery/core rxjs
+## 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 core.
+
+```ts
+type DataChangeEvent = {
+  collection_ref: string
+  id: string
+  type: "added" | "removed" | "modified"
+  data?: Record<string, any>
+}
+```
+
+## Architecture
+
+```text
+LivequeryCollection / LivequeryDocument
+            |
+            v
+        LivequeryCore
+        /          \
+       v            v
+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.
+- `LivequeryCore` coordinates storage, transporters, optimistic writes, and fan-out to watchers.
+- `LivequeryStorge` is the local persistence contract.
+- `LivequeryTransporter` is the remote sync contract.
 
 ## Quick Start
 
@@ -80,527 +101,366 @@ import {
   LivequeryCore,
   LivequeryMemoryStorage,
   type Doc,
+  type LivequeryQueryResult,
   type LivequeryTransporter,
 } from "@livequery/core"
 import { of } from "rxjs"
 
-// 1. Define your document shape
-type Todo = Doc & {
+type Todo = Doc<{
   title: string
   done: boolean
   createdAt: number
-}
+}>
 
-// 2. Create a storage (in-memory for this example)
 const storage = new LivequeryMemoryStorage()
 
-// 3. Create a transporter (no-op; replace with your real backend)
 const transporter: LivequeryTransporter = {
   query(_query) {
-    return of({ changes: [], summary: {}, paging: { total: 0, current: 0 }, metadata: {}, source: "query" as const })
+    return of<Partial<LivequeryQueryResult>>({
+      changes: [],
+      summary: {},
+      paging: { total: 0, current: 0 },
+      metadata: {},
+      source: "query",
+    })
+  },
+  async add(_ref, doc) {
+    return { id: crypto.randomUUID(), ...doc } as Todo
+  },
+  async update(_ref, id, doc) {
+    return { id, ...doc } as Todo
+  },
+  async delete(_ref, id) {
+    return { id } as Todo
+  },
+  async trigger(_action) {
+    return { ok: true }
   },
-  add: async (_ref, doc) => ({ ...doc, id: crypto.randomUUID() } as any),
-  update: async (_ref, _id, doc) => doc as any,
-  delete: async (_ref, _id) => ({} as any),
-  trigger: async (_action) => ({} as any),
 }
 
-// 4. Create the core
 const core = new LivequeryCore({
   storage,
-  transporters: { primary: transporter },
+  transporters: {
+    primary: transporter,
+  },
 })
 
-// 5. Create a reactive collection and initialize it
-const todos = new LivequeryCollection<Todo>({ filters: { "createdAt:sort": "desc" } })
-todos.initialize(core, "todos")
-
-// 6. Subscribe to reactive state
-todos.items.subscribe((docs) => {
-  console.log("items:", docs.map((doc) => doc.value))
+const todos = new LivequeryCollection<Todo>(core, {
+  filters: { "createdAt:sort": "desc" },
+  mode: "server-first",
 })
-todos.loading.subscribe((state) => console.log("loading:", state))
-todos.paging.subscribe((p) => console.log("paging:", p))
 
-// 7. Query with filters
-await todos.query({ "createdAt:sort": "desc", ":limit": 20 })
+todos.initialize("todos")
 
-// 8. Mutate data
+todos.items.subscribe((items) => {
+  console.log(items.map((doc) => doc.value))
+})
+
+await todos.query({ ":limit": 20, "createdAt:sort": "desc" })
 await todos.add({ title: "Buy milk", done: false, createdAt: Date.now() })
-await todos.update("some-id", { done: true })
-await todos.delete("some-id")
+await todos.update("todo-1", { done: true })
+await todos.delete("todo-1")
 ```
 
----
-
-## Core Concepts
+## `LivequeryCore`
 
-### Doc
-
-Every document stored in livequery must extend `Doc<T>`:
+Create one core with a storage adapter and one or more transporters:
 
 ```ts
-type Doc<T = {}> = T & {
-  id: string
-}
+const core = new LivequeryCore({
+  storage,
+  transporters: {
+    primary: transporter,
+  },
+})
 ```
 
-Your types extend this base:
+### Mutation flow
 
-```ts
-type Post = Doc & {
-  title: string
-  body: string
-  publishedAt: number
-}
-```
+For `add`, `update`, and `delete`, the core:
 
-When a document is held inside a `LivequeryCollection`, it is wrapped in `DocState<T>` which adds optimistic-update tracking fields:
+1. writes to local storage first
+2. broadcasts the optimistic change to active watchers
+3. pushes the mutation to each transporter
+4. clears optimistic flags or stores mutation errors after the remote call finishes
 
-```ts
-type DocState<T extends Doc> = T & {
-  _deleting?: boolean    // pending deletion
-  _updating?: boolean    // pending update
-  _adding?: boolean      // pending add
-  _remotes?: Record<string, string | number>  // per-transporter version cursors
-  _prev?: Partial<T>     // previous values before last local mutation
-}
-```
+Documents created locally receive ids prefixed with `local:` until a transporter returns a persisted id.
 
----
+### Query modes
 
-### LivequeryStorge
+Collections support three modes through `LivequeryCollectionOptions.mode`:
 
-`LivequeryStorge` is the interface for local persistence. The library ships with `LivequeryMemoryStorage`. You can create adapters for `localStorage`, `IndexedDB`, SQLite, etc.
+- `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.
 
-```ts
-type LivequeryStorge = {
-  query<T extends Doc>(
-    collection: string,
-    filters?: Record<string, any>
-  ): Promise<{ documents: T[]; paging: LivequeryPaging }>
+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.
 
-  get<T extends Doc>(ref: string, id: string): Promise<T | null>
-  add<T extends Doc>(collection: string, document: 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>
+## `LivequeryCollection`
+
+`LivequeryCollection<T>` manages one collection or one document ref.
+
+```ts
+type LivequeryCollectionOptions<T extends Doc> = {
+  core: LivequeryCore
+  filters: Partial<LivequeryFilters<T>>
+  lazy: boolean
+  debounce: number
+  mode: "server-first" | "local-first" | "cache-first"
 }
 ```
 
----
-
-### LivequeryTransporter
+### Create and initialize a collection
 
-A transporter connects the core to a remote backend (REST API, WebSocket, Firebase, etc.). You can provide **multiple** transporters; the core fans out queries and mutations to all of them.
+The current constructor takes `core` as the first argument and options as the second argument.
 
 ```ts
-type LivequeryTransporter = {
-  // Called for every query. Returns an Observable so the remote can stream realtime updates.
-  query<T extends Doc>(
-    query: LivequeryQueryParams<T>
-  ): Observable<Partial<LivequeryQueryResult>>
-
-  // Called for optimistic mutations
-  add<T extends Doc>(ref: string, doc: Omit<T, 'id'>): Promise<T>
-  update<T extends Doc>(ref: string, id: string, doc: Partial<T>): Promise<T>
-  delete<T extends Doc>(ref: string, id: string): Promise<T>
+const posts = new LivequeryCollection<Post>(core, {
+  filters: { "publishedAt:sort": "desc" },
+  lazy: false,
+  debounce: 250,
+  mode: "cache-first",
+})
 
-  // Called for custom actions
-  trigger<T>(action: LivequeryAction): Promise<T>
-}
+posts.initialize("posts")
 ```
 
----
+`initialize(ref)` subscribes the collection to `LivequeryCore.watch(ref, id, mode)`. In the current implementation, it is browser-only and returns early when `window` is unavailable.
 
-### LivequeryCore
+### Collection refs and document refs
 
-The central coordinator. Instantiate once and share across your app.
+If a ref has an even number of path segments, the last segment is treated as a document id.
 
 ```ts
-const core = new LivequeryCore({
-  storage,                      // LivequeryStorge implementation
-  transporters: {               // one or more named transporters
-    primary: myTransporter,
-  },
-})
+posts.initialize("posts")
+singlePost.initialize("posts/post-1")
 ```
 
----
+For collection mutations, `add`, `update`, and `delete` always target the collection portion of the ref.
+
+### Reactive state
 
-### LivequeryCollection
+- `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>`
 
-`LivequeryCollection<T>` holds reactive state for one collection path (`ref`). Its state is exposed as a set of `BehaviorSubject` properties.
+`items` is a `BehaviorSubject`, not a plain array. Reading `collection.items.value` gives the current snapshot only. If you need live updates, subscribe.
 
 ```ts
-const posts = new LivequeryCollection<Post>({
-  filters: { "publishedAt:sort": "desc" },
-  lazy: true,    // true = don't auto-load on initialize(); false = load immediately (default)
-  debounce: 300, // optional debounce time in ms for debounceQuery()
+const subscription = posts.items.subscribe((items) => {
+  console.log("realtime items", items.map((doc) => doc.value))
 })
 
-// Wire up the core and the collection path, then start watching
-posts.initialize(core, "posts")
+subscription.unsubscribe()
 ```
 
-#### Reactive state properties
+In React, reading only `collection.items.value` during render will not trigger rerenders when new events arrive. Bridge the `BehaviorSubject` into component state.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `items` | `BehaviorSubject<LivequeryDocument<DocState<T>>[]>` | Current list of documents |
-| `loading` | `BehaviorSubject<LivequeryLoadingState \| null>` | `null`, `'all'`, `'next'`, or `'prev'` |
-| `filters` | `BehaviorSubject<Partial<LivequeryFilters<T>>>` | Active filters |
-| `paging` | `BehaviorSubject<LivequeryPaging>` | Pagination info |
-| `summary` | `BehaviorSubject<Record<string, any>>` | Aggregation data from transporter |
-| `metadata` | `BehaviorSubject<Record<string, any>>` | Arbitrary metadata from transporter |
-| `error` | `BehaviorSubject<{code: string, message: string} \| null>` | Last error from transporter |
+```tsx
+function TodoList({ collection }: { collection: LivequeryCollection<Todo> }) {
+  const [items, setItems] = useState(() => collection.items.value)
+
+  useEffect(() => {
+    const subscription = collection.items.subscribe(setItems)
+    return () => subscription.unsubscribe()
+  }, [collection])
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.value.id}>{item.value.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Main methods
 
 ```ts
-posts.items.subscribe((docs) => console.log(docs.map(d => d.value)))
-posts.loading.subscribe((state) => console.log("loading:", state))
-// state is null | 'all' | 'next' | 'prev'
+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(payload: Partial<T>): Promise<T>
+update(id: string, payload: Partial<T>): Promise<T | undefined>
+delete(id: string): Promise<void | T | undefined>
+trigger<R>(action: string, payload?: Record<string, any>): Observable<{ data: R; error?: Error }>
+resetError(): void
+watch(check: (prev: T, next: T) => boolean): Observable<[DocState<T>, DocState<T>]>
 ```
 
----
+Notes about current behavior:
+
+- `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.
 
-### LivequeryDocument
+## `LivequeryDocument`
 
-Each element of `collection.items.value` is a `LivequeryDocument<DocState<T>>`, which extends `BehaviorSubject<T>`. It provides convenient mutation helpers scoped to that document.
+Each entry inside `collection.items` is a `LivequeryDocument`, which extends `BehaviorSubject<DocState<T>>`.
 
 ```ts
-class LivequeryDocument<T extends Doc> extends BehaviorSubject<T> {
-  update(data: Partial<T>): Promise<void>
-  del(): Promise<void>
+class LivequeryDocument<T extends Doc> extends BehaviorSubject<DocState<T>> {
+  update(data: Partial<T>): Promise<T | undefined>
+  del(): Promise<void | T | undefined>
   trigger<R>(action: string, payload: Record<string, any>): Observable<{ data: R; error?: Error }>
 }
 ```
 
-```ts
-const doc = posts.items.value[0]
+Example:
 
-// Subscribe to individual document changes
-doc.subscribe((post) => console.log("post changed:", post))
+```ts
+const first = todos.items.value[0]
 
-// Mutate directly on the document
-await doc.update({ title: "Updated title" })
-await doc.del()
+first.subscribe((doc) => {
+  console.log(doc.title, doc._updating)
+})
 
-// Fire a custom action
-doc.trigger("publish", { scheduledAt: Date.now() }).subscribe()
+await first.update({ done: true })
+await first.del()
+first.trigger("archive", { reason: "completed" }).subscribe()
 ```
 
----
+## `LivequeryStorge`
 
-## Query Filters
-
-Filters are fully type-safe. The TypeScript compiler will only allow valid field paths and operators for your document type.
-
-### Pagination / sorting
-
-| Key | Type | Description |
-|-----|------|-------------|
-| `"<field>:sort"` | `"asc" \| "desc"` | Sort by a string field |
-| `":limit"` | `number` | Max items per page |
-| `":page"` | `number` | Page number (1-based) |
-| `":before"` | `string` | Cursor for previous-page fetch |
-| `":after"` | `string` | Cursor for next-page fetch |
-
-### Field operators
-
-| Operator | Applies to | Description |
-|----------|-----------|-------------|
-| `gt` | `number` | Greater than |
-| `gte` | `number` | Greater than or equal |
-| `lt` | `number` | Less than |
-| `lte` | `number` | Less than or equal |
-| `eq-number` | `number` | Strict numeric equality |
-| `in` | `number \| string` | Value is in array |
-| `nin` | `number \| string` | Value is NOT in array |
-| `include` | `number[] \| string[]` | Array field includes value |
-| `boolean` | `boolean` | `"true"`, `"false"`, `"not-true"`, `"not-false"` |
-| `like` | `string` | Case-insensitive substring match |
-| `null` | any | `"null-only"` or `"not-null"` |
+Local persistence adapters must implement:
 
 ```ts
-type Article = Doc & {
-  score: number
-  tags: string[]
-  title: string
-  archived: boolean
-  deletedAt: number | null
-}
-
-const filters: LivequeryFilters<Article> = {
-  "score:gte": 5,
-  "tags:include": "typescript",
-  "title:like": "livequery",
-  "archived:boolean": "false",
-  "deletedAt:null": "null-only",
-  "score:sort": "desc",
-  ":limit": 20,
-  ":page": 1,
-  ":before": "",
-  ":after": "",
+type LivequeryStorge = {
+  query<T extends Doc>(
+    collection: string,
+    filters?: Record<string, any>
+  ): Promise<{
+    documents: T[]
+    paging: LivequeryPaging
+  }>
+  get<T extends Doc>(ref: string, id: string): Promise<T | null>
+  add<T extends Doc>(collection: string, document: 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>
 }
 ```
 
----
+The package ships with `LivequeryMemoryStorage`, an in-memory adapter useful for tests, demos, and ephemeral state.
 
-## API Reference
+### `LivequeryMemoryStorage`
 
-### LivequeryMemoryStorage
+The built-in adapter:
 
-An in-memory `LivequeryStorge` implementation backed by a `Map`. Data is lost on page reload. Useful for testing and offline-first prototypes.
+- 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`
 
-```ts
-const storage = new LivequeryMemoryStorage()
-```
+## `LivequeryTransporter`
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `query` | `(collection, filters?) → Promise<{documents, paging}>` | Filter, sort and paginate documents |
-| `get` | `(collection, id) → Promise<T \| null>` | Fetch a single document by id |
-| `add` | `(collection, document) → Promise<T>` | Upsert a document (insert or replace by id) |
-| `update` | `(collection, id, partial) → Promise<T \| null>` | Merge partial fields into existing document |
-| `delete` | `(collection, id) → Promise<T \| null>` | Remove and return a document |
-| `clear` | `(collection?) → void` | Clear one collection or all collections |
+Remote adapters must implement:
 
 ```ts
-storage.clear("todos")   // clear one collection
-storage.clear()          // clear everything
+type LivequeryTransporter = {
+  query<T extends Doc>(query: LivequeryQueryParams<T>): Observable<Partial<LivequeryQueryResult>>
+  add<T extends Doc>(ref: string, doc: Omit<T, "id">): Promise<T>
+  update<T extends Doc>(ref: string, id: string, doc: Partial<T>): Promise<T>
+  delete<T extends Doc>(ref: string, id: string): Promise<T>
+  trigger<T>(action: LivequeryAction): Promise<T>
+}
 ```
 
----
-
-### LivequeryCollection methods
-
-| Method | Description |
-|--------|-------------|
-| `initialize(core, ref)` | Wire up the core for a given collection path; optionally auto-loads (required before use) |
-| `query(filters)` | Execute a fresh query replacing current items |
-| `debounceQuery(filters)` | Queue a debounced query (uses the `debounce` option) |
-| `loadMore()` | Append next page using `paging.next.cursor` |
-| `loadPrev()` | Prepend previous page using `paging.prev.cursor` |
-| `loadAround(cursor)` | Load items around a specific cursor (both directions) |
-| `add(payload)` | Optimistically add a new document |
-| `update(id, payload)` | Optimistically update a document |
-| `delete(id)` | Optimistically delete a document |
-| `trigger(action, payload?)` | Fire a custom action via the transporter |
-| `watch(check)` | Returns an Observable that emits when a document changes, filtered by `check` |
-| `resetError()` | Clear the current `error` state |
+### Query result shape
 
 ```ts
-// Paginate
-await collection.loadMore()
-await collection.loadPrev()
-await collection.loadAround("cursor-abc")
-
-// Mutate
-await collection.add({ title: "New item", done: false, createdAt: Date.now() })
-await collection.update("doc-id", { done: true })
-await collection.delete("doc-id")
-
-// Custom action handled by your transporter
-collection.trigger("sendEmail", { to: "user@example.com" }).subscribe()
-
-// Watch for field changes across all items
-collection.watch((prev, next) => prev.done !== next.done).subscribe(([prev, next]) => {
-  console.log("done changed", prev, next)
-})
+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
+}
 ```
 
----
-
-## Writing a Custom Transporter
-
-Implement `LivequeryTransporter` to connect to any backend:
+Transporters can emit partial results. In practice, the most useful fields are `changes`, `paging`, `summary`, `metadata`, and `error`.
 
-```ts
-import { Observable } from "rxjs"
-import type {
-  LivequeryTransporter, Doc,
-  LivequeryQueryParams, LivequeryAction
-} from "@livequery/core"
+## Query Filters
 
-const httpTransporter: LivequeryTransporter = {
-  query<T extends Doc>(params: LivequeryQueryParams<T>) {
-    return new Observable(subscriber => {
-      fetch(`/api/${params.ref}?${new URLSearchParams(params.filters as any)}`)
-        .then(r => r.json())
-        .then(data => {
-          subscriber.next({
-            changes: data.items.map((item: T) => ({ id: item.id, type: "added", data: item })),
-            paging: data.paging,
-            summary: data.summary ?? {},
-            metadata: {},
-            source: "query",
-          })
-          subscriber.complete()
-        })
-        .catch(err => subscriber.error(err))
-    })
-  },
+Filters are flat keys derived from the document type.
 
-  async add<T extends Doc>(ref: string, doc: Omit<T, 'id'>) {
-    const res = await fetch(`/api/${ref}`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(doc),
-    })
-    return res.json() as Promise<T>
-  },
+### Pagination keys
 
-  async update<T extends Doc>(ref: string, id: string, doc: Partial<T>) {
-    const res = await fetch(`/api/${ref}/${id}`, {
-      method: "PATCH",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(doc),
-    })
-    return res.json() as Promise<T>
-  },
+- `:limit`
+- `:before`
+- `:after`
+- `:around`
+- `:page`
 
-  async delete<T extends Doc>(ref: string, id: string) {
-    const res = await fetch(`/api/${ref}/${id}`, { method: "DELETE" })
-    return res.json() as Promise<T>
-  },
+### Supported operators
 
-  async trigger<T>(action: LivequeryAction) {
-    const res = await fetch(`/api/${action.ref}/${action.action}`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(action.payload),
-    })
-    return res.json() as Promise<T>
-  },
-}
-```
-
----
+- `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"`
 
-## Writing a Custom Storage Adapter
-
-Implement `LivequeryStorge` to persist data in `localStorage`, `IndexedDB`, SQLite, etc.:
+Nested field paths are supported, for example `"profile.createdAt:sort"`.
 
 ```ts
-import type { LivequeryStorge, Doc, LivequeryPaging } from "@livequery/core"
-
-class LocalStorageAdapter implements LivequeryStorge {
-  private read<T>(collection: string): T[] {
-    return JSON.parse(localStorage.getItem(collection) ?? "[]")
-  }
-  private write<T>(collection: string, docs: T[]) {
-    localStorage.setItem(collection, JSON.stringify(docs))
-  }
-
-  async query<T extends Doc>(collection: string, filters?: Record<string, any>) {
-    const docs = this.read<T>(collection)
-    // apply filters, sort, paginate …
-    return { documents: docs, paging: { total: docs.length, current: docs.length } }
-  }
-
-  async get<T extends Doc>(collection: string, id: string) {
-    return this.read<T>(collection).find(d => d.id === id) ?? null
-  }
-
-  async add<T extends Doc>(collection: string, document: T) {
-    const docs = this.read<T>(collection)
-    const i = docs.findIndex(d => d.id === document.id)
-    if (i >= 0) docs[i] = document; else docs.push(document)
-    this.write(collection, docs)
-    return document
-  }
-
-  async update<T extends Doc>(collection: string, id: string, patch: Record<string, any>) {
-    const docs = this.read<T>(collection)
-    const i = docs.findIndex(d => d.id === id)
-    if (i < 0) return null
-    docs[i] = { ...docs[i], ...patch }
-    this.write(collection, docs)
-    return docs[i]
-  }
-
-  async delete<T extends Doc>(collection: string, id: string) {
-    const docs = this.read<T>(collection)
-    const i = docs.findIndex(d => d.id === id)
-    if (i < 0) return null
-    const [removed] = docs.splice(i, 1)
-    this.write(collection, docs)
-    return removed ?? null
-  }
-}
+await todos.query({
+  ":limit": 20,
+  "done:boolean": "false",
+  "title:like": "milk",
+  "createdAt:gte": 1714176000000,
+  "createdAt:sort": "desc",
+})
 ```
 
----
+## Helper Exports
 
-## Types Reference
+### `filterDocs()`
 
 ```ts
-// Base document type — all documents must have an `id`
-type Doc<T = {}> = T & { id: string }
-
-// Document state inside a collection (tracks optimistic-update flags)
-type DocState<T extends Doc> = T & {
-  _deleting?: boolean
-  _updating?: boolean
-  _adding?: boolean
-  _remotes?: Record<string, string | number>  // per-transporter version cursors
-  _prev?: Partial<T>                          // previous values before last local mutation
-}
-
-// Change event emitted by transporters and the core
-type DataChangeEvent = {
-  collection_ref: string
-  id: string
-  type: 'added' | 'removed' | 'modified'
-  data?: Record<string, any>
-}
-
-// Query parameters forwarded to every transporter
-type LivequeryQueryParams<T extends Doc> = {
-  ref: string
-  filters?: Partial<LivequeryFilters<T>>
-  headers?: Record<string, string>
-}
+import { filterDocs } from "@livequery/core"
 
-// Result streamed back from a transporter query
-type LivequeryQueryResult = {
-  error: { code: string, message: string }
-  changes: DataChangeEvent[]
-  summary: Record<string, any>
-  paging: LivequeryPaging
-  metadata: Record<string, any>
-  source: 'query' | 'action' | 'realtime'
-}
+const visible = filterDocs(docs, {
+  "done:boolean": "false",
+  "title:like": "milk",
+})
+```
 
-// Action sent to a transporter for custom operations
-type LivequeryAction = {
-  ref: string
-  action: string
-  payload?: Record<string, any>
-}
+### `matchesAllFilters()`
 
-// Pagination info
-type LivequeryPaging = {
-  total: number
-  current: number
-  next?: { count: number; cursor: string }
-  prev?: { count: number; cursor: string }
-}
+The helper module also exports `matchesAllFilters(doc, filters)` for direct predicate checks.
 
-// Loading state for a collection
-type LivequeryLoadingState = null | 'next' | 'prev' | 'all'
-```
+## 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()` is typed at the collection and document layer as `Observable<{ data, error? }>` but currently forwards raw transporter results from `LivequeryCore.trigger()`.
 
-## Build
+## Development
 
 ```bash
 bun run build
 ```
 
-Output is placed in `dist/` as ESM with TypeScript declarations (browser target).
+Available scripts:
 
-```bash
-bun run build:watch   # watch mode (JS only, no type declarations)
-bun run clean         # remove dist/
-```
+- `bun run clean`
+- `bun run build:js`
+- `bun run build:types`
+- `bun run build`
+- `bun run build:watch`