cry-synced-db-client 0.1.189 → 0.1.190

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Versions
 
+## 0.1.190 (2026-05-15)
+
+### `addCollectionsToSync(specs[])` — batch register with single-RTT download
+
+Plural counterpart to `addCollectionToSync`. Per-spec semantics are
+identical (permanent existing = skip; temporary or absent = install),
+but the install work is decomposed into three phases optimized for
+batching:
+
+1. **Filter + register (sync)** — every survivor's
+   `this.collections.set()` and `syncOnlyTheseCollections` extension
+   happen up front, so a sync triggered mid-install already sees the
+   new collections.
+2. **Hydrate (parallel)** — Dexie cursor reads + in-mem hydrations
+   fan out via `Promise.allSettled`. Per-collection failure is logged
+   and isolated; the collection stays installed and hydrates on the
+   next sync tick.
+3. **Download (one RTT)** — every newly-installed non-`writeOnly`
+   spec is bundled into a **single `findNewerMany` request**, then
+   each result is fed through `processCollectionServerData` for
+   conflict resolution. **N collections = 1 RTT** of wall-clock time.
+
+```ts
+// Login flow: install a workspace's collections in one shot.
+await syncedDb.addCollectionsToSync([
+  { name: "obravnave", syncConfig: { query: () => ({ lokacija_id }) } },
+  { name: "zivali",    syncConfig: { query: () => ({ tenant }) } },
+  { name: "racuni",    syncConfig: { query: () => ({ leto }) } },
+  { name: "audit_log", writeOnly: true }, // installed but excluded from RTT
+]);
+// → 1 findNewerMany covering [obravnave, zivali, racuni].
+```
+
+Skipped specs (existing permanent) consume zero install work. No-op
+when `specs` is empty or every spec is skipped. Network failure on the
+batched download leaves collections registered; next auto-sync tick
+retries via the normal sync flow.
+
+Compared to looping `addCollectionToSync(spec)` per item:
+- N collections × per-collection RTT (sequential or `Promise.all`)
+  → 1 RTT for the whole batch.
+- Hydration also parallelized.
+- Compatible with `syncOnlyTheseCollections` filter (each addition
+  extends the active set).
+
 ## 0.1.189 (2026-05-15)
 
 ### Periodic full-resync maintenance heartbeat

package/dist/index.js

@@ -4770,6 +4770,99 @@ var _SyncedDb = class _SyncedDb {
     }
     await this._installCollectionConfig(spec);
   }
+  /**
+   * Batch register. See `I_SyncedDb.addCollectionsToSync`.
+   *
+   * The work decomposes into three phases:
+   *
+   *   1. Filter + synchronously seed `this.collections` and the
+   *      `syncOnlyCollections` filter so any concurrent sync triggered
+   *      mid-install already sees the new collections.
+   *   2. Parallel Dexie cursor load + in-mem hydration.
+   *   3. Parallel per-collection one-shot download.
+   *
+   * Per-spec errors in phase 2/3 are isolated via `Promise.allSettled`:
+   * one collection's hydration / download failure does not block the
+   * others. Failures are logged and the spec is left installed (its
+   * cache will hydrate on the next sync tick).
+   */
+  async addCollectionsToSync(specs) {
+    var _a;
+    if (specs.length === 0) return;
+    const toInstall = [];
+    for (const spec of specs) {
+      const existing = this.collections.get(spec.name);
+      if (existing && !existing.temporaryConfig) continue;
+      this.collections.set(spec.name, spec);
+      if (this.syncOnlyCollections) {
+        this.syncOnlyCollections.add(spec.name);
+      }
+      toInstall.push(spec);
+    }
+    if (toInstall.length === 0) return;
+    const hydrationResults = await Promise.allSettled(
+      toInstall.map(async (spec) => {
+        const meta = await this.dexieDb.getSyncMeta(spec.name);
+        if (meta) this.syncMetaCache.set(spec.name, meta);
+        if (!spec.writeOnly) {
+          await this.loadCollectionToInMem(spec.name);
+        }
+      })
+    );
+    for (let i = 0; i < hydrationResults.length; i++) {
+      const r = hydrationResults[i];
+      if (r.status === "rejected") {
+        console.error(
+          `[SyncedDb] addCollectionsToSync: hydration failed for "${toInstall[i].name}":`,
+          r.reason
+        );
+      }
+    }
+    if (!this.connectionManager.canSync()) return;
+    const downloadable = toInstall.filter((s) => !s.writeOnly);
+    if (downloadable.length === 0) return;
+    const plans = [];
+    const fetchSpecs = [];
+    for (const spec of downloadable) {
+      const rawQuery = (_a = spec.syncConfig) == null ? void 0 : _a.query;
+      const query = typeof rawQuery === "function" ? rawQuery() : rawQuery;
+      const meta = this.syncMetaCache.get(spec.name);
+      const timestamp = (meta == null ? void 0 : meta.lastSyncTs) || 0;
+      plans.push({ spec, wasFirstTime: !timestamp });
+      fetchSpecs.push({
+        collection: spec.name,
+        timestamp,
+        query,
+        opts: { returnDeleted: true }
+      });
+    }
+    let results;
+    try {
+      results = await this.connectionManager.withRestTimeout(
+        this.restInterface.findNewerMany(fetchSpecs),
+        "addCollectionsToSync"
+      );
+    } catch (err) {
+      console.error(
+        `[SyncedDb] addCollectionsToSync: batched findNewerMany failed:`,
+        err
+      );
+      return;
+    }
+    for (const plan of plans) {
+      const data = results[plan.spec.name];
+      if (!data || data.length === 0) continue;
+      const source = plan.wasFirstTime ? "initial" : "incremental";
+      try {
+        await this.syncEngine.processCollectionServerData(plan.spec.name, data, { source });
+      } catch (err) {
+        console.error(
+          `[SyncedDb] addCollectionsToSync: processCollectionServerData failed for "${plan.spec.name}":`,
+          err
+        );
+      }
+    }
+  }
   /**
    * Replace the collection config and re-sync. See `I_SyncedDb.replaceSyncCollection`.
    */

package/dist/src/db/SyncedDb.d.ts

@@ -100,6 +100,23 @@ export declare class SyncedDb implements I_SyncedDb {
      * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
      */
     addCollectionToSync(spec: CollectionConfig): Promise<void>;
+    /**
+     * Batch register. See `I_SyncedDb.addCollectionsToSync`.
+     *
+     * The work decomposes into three phases:
+     *
+     *   1. Filter + synchronously seed `this.collections` and the
+     *      `syncOnlyCollections` filter so any concurrent sync triggered
+     *      mid-install already sees the new collections.
+     *   2. Parallel Dexie cursor load + in-mem hydration.
+     *   3. Parallel per-collection one-shot download.
+     *
+     * Per-spec errors in phase 2/3 are isolated via `Promise.allSettled`:
+     * one collection's hydration / download failure does not block the
+     * others. Failures are logged and the spec is left installed (its
+     * cache will hydrate on the next sync tick).
+     */
+    addCollectionsToSync(specs: CollectionConfig[]): Promise<void>;
     /**
      * Replace the collection config and re-sync. See `I_SyncedDb.replaceSyncCollection`.
      */

package/dist/src/types/I_SyncedDb.d.ts

@@ -943,6 +943,34 @@ export interface I_SyncedDb {
      * @param spec Collection config to register
      */
     addCollectionToSync(spec: CollectionConfig): Promise<void>;
+    /**
+     * Batch variant of `addCollectionToSync`. Semantics are identical
+     * per-spec (permanent existing: no-op; temporary or absent: install).
+     *
+     * Three-phase install:
+     *
+     *  1. **Filter + register (sync)** — `this.collections.set()` and
+     *     `syncOnlyTheseCollections` extensions happen up front so any
+     *     concurrent sync triggered mid-install already sees the new
+     *     collections.
+     *  2. **Hydrate (parallel)** — Dexie cursor reads + in-mem
+     *     hydrations run via `Promise.allSettled`. Per-collection
+     *     failures are logged and isolated; the collection stays
+     *     installed and hydrates on the next sync tick.
+     *  3. **Download (one RTT)** — every newly-installed non-writeOnly
+     *     collection is bundled into a SINGLE `findNewerMany` request,
+     *     then each result is fed through `processCollectionServerData`
+     *     for conflict resolution. N collections cost 1 RTT total
+     *     instead of N parallel RTTs.
+     *
+     * Skipped specs (existing permanent) consume no install work. No-op
+     * when `specs` is empty or every spec is a no-op. Network failure on
+     * the batched download leaves the collections installed; the next
+     * auto-sync tick retries via the normal sync flow.
+     *
+     * @param specs Array of collection configs to register
+     */
+    addCollectionsToSync(specs: CollectionConfig[]): Promise<void>;
     /**
      * Replace the collection config and re-sync.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.189",
+  "version": "0.1.190",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",