@livequery/client 2.0.135 → 2.0.139

package/README.md

@@ -24,6 +24,7 @@ bun add @livequery/client @livequery/react rxjs
 export * from "./LivequeryCollection"
 export * from "./LivequeryClient"
 export * from "./LivequeryMemoryStorage"
+export * from "./LivequeryStorage"
 export * from "./LivequeryStorge"
 export * from "./LivequeryTransporter"
 export * from "./types"
@@ -31,7 +32,7 @@ export * from "./helpers/filterDocs"
 export * from "./LivequeryDocument"
 ```
 
-The public storage interface is intentionally named `LivequeryStorge`. The spelling is part of the current public API.
+The public storage interface is `LivequeryStorage`. The previous misspelled name `LivequeryStorge` remains exported as a backward-compatible alias.
 
 ## Mental Model
 
@@ -42,13 +43,13 @@ LivequeryCollection / LivequeryDocument
         LivequeryClient
         /          \
        v            v
-LivequeryStorge  LivequeryTransporter(s)
+LivequeryStorage LivequeryTransporter(s)
 ```
 
 - `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.
+- `LivequeryStorage` is the local persistence contract used by the client. `LivequeryStorge` is a backward-compatible alias.
 - `LivequeryMemoryStorage` is the in-memory reference storage adapter.
 - `LivequeryTransporter` is the remote sync/action contract.
 
@@ -143,7 +144,7 @@ const subscription = todos.items.subscribe((items) => {
 
 await todos.query({
   ":limit": 20,
-  "done:boolean": "false",
+  "done:eq-boolean": "false",
   "createdAt:sort": "desc",
 })
 
@@ -210,6 +211,22 @@ type DocState<T extends Doc> = T & {
 
 Do not strip `_adding`, `_updating`, `_deleting`, or error fields if your UI needs to show mutation progress or failure state.
 
+Field reference:
+
+| Field | Set when | Meaning |
+|---|---|---|
+| `_adding` | `local-first` / `local-only` add in progress | Document is being created on the server |
+| `_adding_error` | Server add rejected | Error from the failed transporter call |
+| `_updating` | `local-first` update in progress | Document is being synced to the server |
+| `_updating_error` | Server update rejected | Error from the failed transporter call |
+| `_deleting` | `local-first` delete in progress | Document is pending deletion on the server |
+| `_deleting_error` | Server delete rejected | Error from the failed transporter call |
+| `_local_only` | `local-only` add | Document was created locally and never sent to the server |
+| `_prev` | `local-first` update pending | Fields that existed before the local update — used to push only changed fields to the server |
+| `_selected` | `select()` called | Whether the document is currently selected |
+| `_index` | Assigned on insert | Stable insertion order used for sort reset |
+| `_remotes` | Transporter-specific | Optional metadata from transporters; not used by the client core |
+
 ### `DataChangeEvent`
 
 Transporter query streams and internal broadcasts use incremental change events:
@@ -247,7 +264,7 @@ new LivequeryClient({
 })
 ```
 
-- `storage`: a `LivequeryStorge` adapter.
+- `storage`: a `LivequeryStorage` 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)`
@@ -264,7 +281,7 @@ Lower-level query entry point used by `LivequeryCollection.query()`.
 await client.query<Todo>({
   ref: "todos",
   collection_id: todos.id,
-  filters: { "done:boolean": "false" },
+  filters: { "done:eq-boolean": "false" },
 })
 ```
 
@@ -331,7 +348,7 @@ const todos = new LivequeryCollection<Todo>(client, {
   lazy: false,
   debounce: 250,
   filters: {
-    "done:boolean": "false",
+    "done:eq-boolean": "false",
     "createdAt:sort": "desc",
   },
 })
@@ -345,6 +362,10 @@ type LivequeryCollectionOptions<T extends Doc> = {
   lazy: boolean
   debounce: number
   mode: "server-first" | "cache-first" | "local-first" | "local-only"
+  seed: {
+    data: T[]
+    persist: boolean
+  }
 }
 ```
 
@@ -352,6 +373,37 @@ type LivequeryCollectionOptions<T extends Doc> = {
 - `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.
+- `seed`: optional initial data. `seed.data` is an array of documents loaded into `items` before any query runs. `seed.persist: false` populates items in memory only — storage is not written. `seed.persist: true` writes the seed to storage before the first query, so a `cache-first` or `local-first` query can read from it immediately.
+
+### `seed`
+
+Pre-populate a collection with data before any query runs. Useful for hardcoded defaults, SSR-hydrated data, or offline stubs.
+
+```ts
+const todos = new LivequeryCollection<Todo>(client, {
+  mode: "cache-first",
+  seed: {
+    data: [
+      { id: "1", title: "Buy milk", done: false, createdAt: Date.now() },
+    ],
+    persist: true,
+  },
+})
+
+todos.initialize("todos")
+// items.value already has the seeded document before the first query
+```
+
+`persist: false` — items are loaded into `items` immediately in the constructor. Storage is never written. The seed disappears after a query replaces items.
+
+`persist: true` — seed data is written to storage before the first auto-query runs. This lets a `cache-first` query read the seed from storage on the first render.
+
+Rules:
+
+- Seed documents must include `id`.
+- When `persist: true` and `lazy: false`, the client calls `seedToStorage()` then starts the auto-query. The auto-query may overwrite seed items when the transporter responds.
+- When `persist: false`, seed items are available immediately in `items.value` from the constructor but are replaced on the first `query()` call.
+- `seed` has no effect on the mode behavior. The collection still uses the configured mode for queries.
 
 ### Reactive Properties
 
@@ -397,7 +449,7 @@ Runs a query and replaces current `items` when cached/local documents are return
 ```ts
 await todos.query({
   ":limit": 20,
-  "done:boolean": "false",
+  "done:eq-boolean": "false",
   "createdAt:sort": "desc",
 })
 ```
@@ -446,7 +498,7 @@ await todos.loadAround("cursor-123")
 
 - `loadMore()` adds `:after`.
 - `loadPrev()` adds `:before`.
-- `loadAround(cursor)` currently sets both `:after` and `:before` to the same cursor.
+- `loadAround(cursor)` loads a page centered on the given cursor. It sets both `:after` and `:before` to the same cursor value — the backend decides what "around a cursor" means for that collection.
 
 ### `add(payload, mode?)`
 
@@ -472,7 +524,42 @@ const many = await todos.add([
 
 The return shape follows the input shape: one payload returns one document; an array returns an array.
 
-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.
+The default mutation mode follows `#defaultMode()`:
+
+| Collection `mode` | Mutation default |
+|---|---|
+| `server-first` | `server-first` |
+| `cache-first` | `server-first` |
+| `local-first` | `local-first` |
+| `local-only` | `local-only` |
+| not set | `server-first` |
+
+```ts
+// local-only collection — mutations also default to local-only
+const drafts = new LivequeryCollection<Todo>(client, { mode: "local-only" })
+drafts.initialize("drafts")
+await drafts.add({ title: "Draft", done: false, createdAt: Date.now() })
+// ✓ stored locally, no server call
+
+// local-first collection — optimistic local write + background server sync
+const notes = new LivequeryCollection<Todo>(client, { mode: "local-first" })
+notes.initialize("notes")
+await notes.add({ title: "Note", done: false, createdAt: Date.now() })
+// ✓ appears immediately, syncs to server in background
+
+// cache-first collection — mutations go server-first by default
+const posts = new LivequeryCollection<Post>(client, { mode: "cache-first" })
+posts.initialize("posts")
+await posts.add({ title: "Post", done: false, createdAt: Date.now() })
+// ✓ blocks until server responds (server-first default)
+```
+
+Pass an explicit mode to override the default on a per-call basis:
+
+```ts
+await drafts.add({ title: "Force server", done: false, createdAt: Date.now() }, "server-first")
+await posts.add({ title: "Local draft", done: false, createdAt: Date.now() }, "local-only")
+```
 
 ### `update(payload, mode?)`
 
@@ -546,14 +633,32 @@ todos.resetError()
 
 Watches pairwise document changes and emits when `check(prev, next)` returns `true`.
 
+Returns `Observable<[DocState<T>, DocState<T>]>` — each emission is a `[previous, current]` pair for the document that changed.
+
 ```ts
-const doneSub = todos.watch((prev, next) => prev.done !== next.done).subscribe(([prev, next]) => {
-  console.log(prev.id, "done changed", prev.done, "=>", next.done)
-})
+// Watch when the `done` field changes on any todo
+const doneSub = todos.watch((prev, next) => prev.done !== next.done)
+  .subscribe(([prev, next]) => {
+    console.log(next.id, "done changed:", prev.done, "→", next.done)
+  })
 
 doneSub.unsubscribe()
+
+// Watch when any field changes
+const anySub = todos.watch((prev, next) => prev !== next).subscribe(([prev, next]) => {
+  console.log("document changed:", next.id)
+})
+
+// Watch for optimistic mutation completion
+const saveSub = todos.watch(
+  (prev, next) => prev._updating === true && next._updating == null
+).subscribe(([, next]) => {
+  console.log("save confirmed for:", next.id)
+})
 ```
 
+`check` is called for every field emission of every document in `items`. Keep it fast. Avoid closures that capture large objects.
+
 ### `flush()`
 
 Flushes storage through the client for this collection's `collection_ref`.
@@ -610,12 +715,12 @@ first.select(true)
 first.select(false)
 ```
 
-## `LivequeryStorge`
+## `LivequeryStorage`
 
 Storage adapters provide local persistence and local filtering.
 
 ```ts
-type LivequeryStorge = {
+type LivequeryStorage = {
   query<T extends Doc>(
     collection: string,
     filters?: Record<string, any>
@@ -631,6 +736,8 @@ type LivequeryStorge = {
 }
 ```
 
+`LivequeryStorge` is still exported as an alias for existing consumers.
+
 Adapter guidance:
 
 - `query()` should apply the same filter semantics as `filterDocs()` when possible.
@@ -654,7 +761,7 @@ await storage.add<Todo>("todos", {
 })
 
 const page = await storage.query<Todo>("todos", {
-  "done:boolean": "false",
+  "done:eq-boolean": "false",
   "createdAt:sort": "desc",
 })
 ```
@@ -753,27 +860,38 @@ const apiTransporter: LivequeryTransporter = {
 
 ## Query Modes
 
+> For detailed data flow diagrams, mutation behavior per mode, and common mistakes, see [docs/modes.md](./docs/modes.md).
+
+| Mode | Query reads from | Transporter called? | Mutation default |
+|------|------|------|------|
+| `server-first` | Transporter | Yes, always | `server-first` |
+| `cache-first` | Storage first, then transporter | Yes, in background | `server-first` |
+| `local-first` | Storage immediately | Yes, full sync in background | `local-first` |
+| `local-only` | Storage only | No | `local-only` |
+
 ### `server-first`
 
-Transporters drive the query result. Collection state is built from streamed change events.
+Transporters drive the query result. Collection state is built from streamed change events. Items are delivered asynchronously through the watch stream, not from the `query()` return value.
 
 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.
+The first query hydrates from local storage instantly, then transporters refresh in the background. For pagination queries (`:before` / `:after`), cache is skipped and the transporter is called directly. Mutations default to `server-first`.
 
 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.
+Storage serves the query immediately. The transporter syncs the full collection in the background by paginating all pages and writing results to storage. Remote changes are rebroadcast to local collections filtered by their current filters.
 
-For `local-first`, the remote query path receives empty filters. Local filtering is enforced by storage query results and by broadcast filtering.
+The server receives **empty filters** — local filtering happens during broadcast, not on the server.
+
+Avoid this mode for large unbounded datasets; it attempts to sync every document locally.
 
 ### `local-only`
 
-Queries resolve only from storage and skip transporters. Mutations stay local only when you explicitly call them with `mode: "local-only"`.
+Queries resolve only from storage. Transporters are never called. No loading state is emitted. Mutations stay local when explicitly called with `mode: "local-only"`.
 
 Use it for drafts, temporary UI state, offline-only collections, or local workspaces.
 
@@ -821,11 +939,13 @@ Filters are flat object keys derived from document fields.
 - `field:sort`: `"asc" | "desc"`
 - `field:gt`, `field:gte`, `field:lt`, `field:lte`: numeric comparisons
 - `field:eq-number`: numeric equality after `Number(value)`
+- `field:neq-number`: numeric inequality 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"`
+- `field:ne`: inequality
+- `field:eq-boolean`, `field:neq-boolean`: boolean equality or inequality
+- `field:eq-null`, `field:neq-null`: null equality or inequality
+- `field:eq-oid`, `field:neq-oid`: ObjectId string equality or inequality for MongoDB-backed datasources
+- `field:like`: regular expression match
 
 Nested field paths are supported:
 
@@ -833,7 +953,7 @@ Nested field paths are supported:
 await posts.query({
   "author.id": "user-1",
   "stats.views:gte": 100,
-  "published:boolean": "true",
+  "published:eq-boolean": "true",
   "title:like": "livequery",
   "createdAt:sort": "desc",
 })
@@ -849,7 +969,7 @@ Filters an array with the same runtime semantics used by `LivequeryMemoryStorage
 import { filterDocs } from "@livequery/client"
 
 const openTodos = filterDocs(todos, {
-  "done:boolean": "false",
+  "done:eq-boolean": "false",
 })
 ```
 
@@ -860,11 +980,57 @@ Predicate helper for checking one document.
 ```ts
 import { matchesAllFilters } from "@livequery/client"
 
-if (matchesAllFilters(todo, { "done:boolean": "false" })) {
+if (matchesAllFilters(todo, { "done:eq-boolean": "false" })) {
   console.log("todo is open")
 }
 ```
 
+### `parseFilters(filters)`
+
+Pre-parses a filter object into a `ParsedFilter[]` array. Call this once per query rather than calling `matchesAllFilters` in a tight loop.
+
+```ts
+import { parseFilters, matchesParsedFilters } from "@livequery/client"
+
+const filters = { "done:eq-boolean": "false", "createdAt:sort": "desc" }
+const parsed = parseFilters(filters)
+
+// Efficient: parse once, match many
+const openTodos = todos.filter(doc => matchesParsedFilters(doc, parsed))
+```
+
+Pagination keys (`:limit`, `:before`, `:after`, `:around`, `:page`) and sort keys (`:sort` suffix) are excluded from the returned array.
+
+### `matchesParsedFilters(doc, parsedFilters)`
+
+Matches one document against a pre-parsed `ParsedFilter[]`. Use together with `parseFilters()` when checking many documents against the same filters.
+
+```ts
+const parsed = parseFilters({ "status": "active", "score:gte": 10 })
+
+for (const doc of largeList) {
+  if (matchesParsedFilters(doc, parsed)) {
+    // ...
+  }
+}
+```
+
+### `getByPath(obj, path)`
+
+Reads a value from a nested object using dot-notation path. Returns `undefined` when any segment is missing.
+
+```ts
+import { getByPath } from "@livequery/client"
+
+const doc = { author: { profile: { name: "Ada" } } }
+
+getByPath(doc, "author.profile.name") // "Ada"
+getByPath(doc, "author.missing.field") // undefined
+getByPath(doc, "title")               // undefined (not present)
+```
+
+Used internally by filter evaluation and storage sorting. Available as a public export for custom storage adapters.
+
 ## React Usage
 
 Bridge `BehaviorSubject` values into React state.
@@ -955,10 +1121,11 @@ A document ref still exposes `items`; the matching document is represented as a
 
 - `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.
+- `ConflictResolverFunction` is exported as a TypeScript type but is not wired into `LivequeryClient`. It documents the intended shape for future conflict resolution support. Do not pass it to the client — there is currently no parameter that accepts it.
 - `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.
+- Run `bun test` to execute the test suite. It covers collection behavior, seed loading, mutation mode defaults, query error propagation, filter parsing, and sort stability.
 
 ## Development
 

package/dist/LivequeryClient.d.ts

@@ -1,10 +1,11 @@
 import { Observable, Subject } from "rxjs";
-import type { LivequeryStorge } from "./LivequeryStorge.js";
+import type { LivequeryStorage } from "./LivequeryStorage.js";
 import type { LivequeryQueryResult, LivequeryTransporter } from "./LivequeryTransporter.js";
 import type { DataChangeEvent, LivequeryAction, Doc, LivequeryQueryParams, DocState, LivequeryFilters, RealtimeChangeSource, ParitalDocState } from "./types.js";
+import { type ParsedFilter } from "./helpers/filterDocs.js";
 export type LivequeryClientOptions = {
     transporters: Record<string, LivequeryTransporter>;
-    storage: LivequeryStorge;
+    storage: LivequeryStorage;
 };
 export type LivequeryLoadingState = null | 'next' | 'prev' | 'all';
 export type SyncRequest = DataChangeEvent & {
@@ -21,7 +22,7 @@ export type ConflictResolverFunction = <T extends Doc>(e: {
     document: T;
 };
 export type LivequeryClientConfig = {
-    storage: LivequeryStorge;
+    storage: LivequeryStorage;
     transporters: Record<string, LivequeryTransporter>;
 };
 export type ActionMode = 'server-first' | 'local-first' | 'local-only';
@@ -34,6 +35,7 @@ export type CollectionMetadata = {
     collection_ref: string;
     mode: 'server-first' | 'local-first' | 'cache-first' | 'local-only';
     filters: Partial<LivequeryFilters<any>>;
+    parsedFilters: ParsedFilter[];
 };
 export declare class LivequeryClient {
     #private;
@@ -52,8 +54,9 @@ export declare class LivequeryClient {
     } | undefined>;
     add<T extends Doc>(collection_ref: string, documents: Partial<DocState<T>>[], mode: ActionMode): Promise<DocState<T>[]>;
     update<T extends Doc>(collection_ref: string, documents: ParitalDocState<T>[], mode: ActionMode): Promise<DocState<T>[]>;
-    delete<T extends Doc>(collection_ref: string, ids: string[], mode: ActionMode): Promise<DocState<T>[]>;
+    delete<T extends Doc>(collection_ref: string, ids: string[], mode: ActionMode): Promise<T[]>;
     trigger<Response>(action: LivequeryAction): Observable<Response>;
+    seedToStorage<T extends Doc>(collection_ref: string, docs: T[]): Promise<void>;
     flush(collection_ref: string): Promise<void>;
     destroy(): void;
 }

package/dist/LivequeryClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LivequeryClient.d.ts","sourceRoot":"","sources":["../src/LivequeryClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LivequeryClient.d.ts","sourceRoot":"","sources":["../src/LivequeryClient.ts"],"names":[],"mappings":"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"}

package/dist/LivequeryClient.js

@@ -50,10 +50,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { defer, EMPTY, expand, filter, finalize, forkJoin, from, groupBy, lastValueFrom, map, merge, mergeMap, Observable, of, scan, shareReplay, Subject, Subscription, switchMap, takeUntil, takeWhile, tap, toArray } from "rxjs";
+import { defer, EMPTY, expand, filter, finalize, forkJoin, from, groupBy, map, merge, mergeMap, Observable, of, scan, shareReplay, Subject, Subscription, switchMap, takeUntil, takeWhile, tap } from "rxjs";
 import { tryCatch } from "./helpers/tryCatch.js";
 import { whenCompleted } from "./helpers/whenCompleted.js";
-import { matchesAllFilters } from "./helpers/filterDocs.js";
+import { matchesParsedFilters, parseFilters } from "./helpers/filterDocs.js";
 import { useDispose } from "./helpers/useDispose.js";
 import { uuidv7 } from 'uuidv7';
 export class LivequeryClient {
@@ -104,7 +104,7 @@ export class LivequeryClient {
         this.#running = merge(
         // Server queries
         this.#queries$.pipe(filter(req => req.collection.mode == 'server-first' || req.collection.mode == 'cache-first'), mergeMap(e => {
-            const deduplicate_key = `${e.collection.collection_id}:${JSON.stringify(e.filters)}`;
+            const deduplicate_key = `${e.collection.collection_id}:${JSON.stringify(e.filters, Object.keys(e.filters || {}).sort())}`;
             const before = e.filters?.[':before'];
             const after = e.filters?.[':after'];
             const around = e.filters?.[':around'];
@@ -156,7 +156,8 @@ export class LivequeryClient {
             collection_id,
             collection_ref,
             mode,
-            filters: {}
+            filters: {},
+            parsedFilters: []
         });
         return data$.pipe(finalize(() => {
             this.#collections.delete(collection_id);
@@ -185,8 +186,9 @@ export class LivequeryClient {
             filters: collection.mode == 'local-first' ? {} : req.filters,
             collection
         }));
-        // If collection 
+        // If collection
         collection.filters = req.filters || {};
+        collection.parsedFilters = parseFilters(collection.filters);
         if (collection.mode == 'local-first') {
             return await this.config.storage.query(req.ref, req.filters);
         }
@@ -218,14 +220,14 @@ export class LivequeryClient {
                 continue;
             }
             if (event.type == 'added') {
-                event.data && matchesAllFilters(event.data, collection.filters) && changes.push(event);
+                event.data && matchesParsedFilters(event.data, collection.parsedFilters) && changes.push(event);
                 continue;
             }
             const cache_key = `${event.collection_ref}/${event.id}`;
             const cached = docs.get(cache_key) || this.config.storage.get(collection.collection_ref, event.id);
             docs.set(cache_key, cached);
             const doc = await cached;
-            if (doc && matchesAllFilters(doc, collection.filters)) {
+            if (doc && matchesParsedFilters(doc, collection.parsedFilters)) {
                 changes.push(event);
                 continue;
             }
@@ -238,6 +240,8 @@ export class LivequeryClient {
         return changes;
     }
     async #broadcast(collection_ref, from, events) {
+        if (events.length === 0)
+            return;
         const collections = this.#refs.get(collection_ref) || new Set();
         const docs = new Map();
         for (const collection_id of collections) {
@@ -272,13 +276,13 @@ export class LivequeryClient {
             });
         }
     }
-    #push(collection_ref, docs, server_first) {
-        return lastValueFrom(from(docs).pipe(mergeMap(doc => from(Object.entries(this.config.transporters)).pipe(mergeMap(async ([tid, transporter]) => {
+    async #push(collection_ref, docs, server_first) {
+        const results = await Promise.all(docs.flatMap(doc => Object.entries(this.config.transporters).map(async ([tid, transporter]) => {
             const id = doc.id;
             if (String(id).startsWith('local:')) {
                 const env_1 = { stack: [], error: void 0, hasError: false };
                 try {
-                    // lock by collection_ref 
+                    // lock by collection_ref
                     const o = new Subject();
                     this.#adding.set(collection_ref, o);
                     const $ = __addDisposableResource(env_1, useDispose(() => {
@@ -289,7 +293,7 @@ export class LivequeryClient {
                     const [e, data] = await tryCatch(() => transporter.add(collection_ref, doc), tid);
                     if (e && server_first)
                         throw e;
-                    // unlock 
+                    // unlock
                     const fnd = {
                         ...data,
                         _adding: undefined,
@@ -312,7 +316,7 @@ export class LivequeryClient {
                     __disposeResources(env_1);
                 }
             }
-            // _deleting flag → soft-delete on remote then hard-delete locally 
+            // _deleting flag → soft-delete on remote then hard-delete locally
             if (doc._deleting) {
                 const [e, data] = await tryCatch(() => transporter.delete(collection_ref, id), tid);
                 if (e && server_first)
@@ -363,20 +367,19 @@ export class LivequeryClient {
                     }]);
                 return data;
             }
-        }))), filter(Boolean), toArray()), { defaultValue: [] });
+        })));
+        return results.filter(Boolean);
     }
     async add(collection_ref, documents, mode) {
         if (mode == 'server-first') {
             const list = documents.map(doc => ({ ...doc, id: `local:${uuidv7()}` }));
             return await this.#push(collection_ref, list, true);
         }
-        const docs = await lastValueFrom(from(documents).pipe(mergeMap(doc => {
-            return this.config.storage.add(collection_ref, {
-                ...doc,
-                _adding: true,
-                ...mode === 'local-only' ? { _local_only: true } : {}
-            });
-        }), toArray()));
+        const docs = await Promise.all(documents.map(doc => this.config.storage.add(collection_ref, {
+            ...doc,
+            _adding: true,
+            ...mode === 'local-only' ? { _local_only: true } : {}
+        })));
         await this.#broadcast(collection_ref, 'action', docs.map(data => ({
             collection_ref,
             id: data.id,
@@ -392,21 +395,17 @@ export class LivequeryClient {
             const list = documents.map(doc => ({ ...doc, _prev: doc }));
             return await this.#push(collection_ref, list, true);
         }
-        const merged = await lastValueFrom(from(documents).pipe(mergeMap(async (doc) => {
+        const merged = (await Promise.all(documents.map(async (doc) => {
             const old = await this.config.storage.get(collection_ref, doc.id);
             if (!old)
                 return;
             const _prev = Object.keys(doc).reduce((acc, key) => {
                 if (key in (old._prev || {}))
                     return acc;
-                return {
-                    ...acc,
-                    [key]: old[key]
-                };
+                return { ...acc, [key]: old[key] };
             }, old._prev || {});
-            const data = await this.config.storage.update(collection_ref, doc.id, { _prev, _updating: true, ...doc, });
-            return data;
-        }), filter(Boolean), toArray()));
+            return await this.config.storage.update(collection_ref, doc.id, { _prev, _updating: true, ...doc });
+        }))).filter(Boolean);
         await this.#broadcast(collection_ref, 'action', merged.map(data => ({
             collection_ref,
             id: data.id,
@@ -423,14 +422,13 @@ export class LivequeryClient {
             return await this.#push(collection_ref, list, true);
         }
         const soft = Object.keys(this.config.transporters).length > 0;
-        const merged = await lastValueFrom(from(ids).pipe(mergeMap(async (id) => {
+        const merged = (await Promise.all(ids.map(async (id) => {
             const is_local_doc = id.startsWith('local:');
             if (!soft || is_local_doc || mode == 'local-only') {
-                const doc = await this.config.storage.delete(collection_ref, id);
-                return doc;
+                return await this.config.storage.delete(collection_ref, id);
             }
             return await this.config.storage.update(collection_ref, id, { _deleting: true });
-        }), filter(Boolean), toArray()));
+        }))).filter(Boolean);
         const deleting_list = merged.filter(doc => doc._deleting);
         const deleted_list = merged.filter(doc => !doc._deleting);
         await this.#broadcast(collection_ref, 'action', deleting_list.map(({ id }) => ({
@@ -453,6 +451,9 @@ export class LivequeryClient {
     trigger(action) {
         return from(Object.entries(this.config.transporters)).pipe(filter(([id]) => action.transporter_id ? id === action.transporter_id : true), mergeMap(([id, transporter]) => transporter.trigger(action)));
     }
+    async seedToStorage(collection_ref, docs) {
+        await Promise.all(docs.map(doc => this.config.storage.add(collection_ref, doc)));
+    }
     async flush(collection_ref) {
         await this.#broadcast(collection_ref, 'realtime', [{ collection_ref, id: '*', type: 'removed' }]);
         return this.config.storage.flush();