cry-synced-db-client 0.1.191 → 0.1.194

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Versions
 
+## 0.1.193 (2026-05-25)
+
+Adds per-collection preload status reporting (non-breaking, additive).
+
+### `getPreloadStatus()` + `onPreloadStatusChange`
+
+New synchronous getter `getPreloadStatus(): PreloadStatus` and config callback
+`onPreloadStatusChange?(status)` expose hydration status for every readable
+(non-`writeOnly`), in-scope collection:
+
+- Per-collection `state` (`pending` / `hydrated` / `failed`), `itemCount`,
+  `lastError`, `everDownloaded` (informational), and a derived `ready` flag
+  (`ready = (state === "hydrated")` — the local cache is loaded into in-mem;
+  empty is valid). Data *freshness* is a separate, global concern
+  (`lastSuccessfulServerSync`), deliberately **not** folded into `ready`:
+  gating on a per-collection cursor wedged the aggregate at `partial` for
+  genuinely-empty, never-synced collections (every tenant has several).
+- Rolled-up `aggregate`: `idle` / `full` / `partial` / `failed`.
+
+The callback fires on each hydration transition (success/failure), on scope
+changes (`setSyncOnlyTheseCollections`), and at sync end (a download that
+advances a cursor can flip a hydrated-empty collection to ready).
+
+### Per-collection hydration failures no longer abort the batch
+
+`loadCollectionsToInMem`'s worker pool now isolates a single collection's
+Dexie hydration failure (try/catch per collection) instead of rejecting the
+whole `Promise.all` — matching the existing `Promise.allSettled` tolerance in
+`addCollectionsToSync`. The failure is recorded as `state: "failed"` and
+surfaced via `getPreloadStatus()` (`aggregate: "partial"`) rather than throwing
+out of `init()`.
+
 ## 0.1.191 (2026-05-22)
 
 Adopts the cry-db 2.5.0 sync contract. **Requires cry-db ≥ 2.5.0 on the

package/dist/index.js

@@ -4691,6 +4691,8 @@ var _SyncedDb = class _SyncedDb {
     this.syncOnlyCollections = null;
     // Sync metadata cache
     this.syncMetaCache = /* @__PURE__ */ new Map();
+    // Per-collection hydration status (powers getPreloadStatus / onPreloadStatusChange)
+    this.preloadStatusMap = /* @__PURE__ */ new Map();
     this._pendingFullResync = false;
     var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
     this.tenant = config.tenant;
@@ -4710,6 +4712,7 @@ var _SyncedDb = class _SyncedDb {
     this.onDexieSyncStart = config.onDexieSyncStart;
     this.onDexieSyncEnd = config.onDexieSyncEnd;
     this.onSyncProgress = config.onSyncProgress;
+    this.onPreloadStatusChange = config.onPreloadStatusChange;
     this.onServerSyncStart = config.onServerSyncStart;
     this.onServerSyncEnd = config.onServerSyncEnd;
     this.onConflictResolved = config.onConflictResolved;
@@ -4729,6 +4732,7 @@ var _SyncedDb = class _SyncedDb {
     this.evictOnWake = (_g = config.evictOnWake) != null ? _g : false;
     for (const col of config.collections) {
       this.collections.set(col.name, col);
+      if (!col.writeOnly) this.preloadStatusMap.set(col.name, { state: "pending", itemCount: 0 });
     }
     this.inMemManager = new InMemManager({
       inMemDb: this.inMemDb,
@@ -5029,6 +5033,9 @@ var _SyncedDb = class _SyncedDb {
       const existing = this.collections.get(spec.name);
       if (existing && !existing.temporaryConfig) continue;
       this.collections.set(spec.name, spec);
+      if (!spec.writeOnly && !this.preloadStatusMap.has(spec.name)) {
+        this.preloadStatusMap.set(spec.name, { state: "pending", itemCount: 0 });
+      }
       if (this.syncOnlyCollections) {
         this.syncOnlyCollections.add(spec.name);
       }
@@ -5149,8 +5156,10 @@ var _SyncedDb = class _SyncedDb {
     for (const [name] of this.collections) {
       if (this.isSyncAllowed(name) && !prevAllowed.has(name)) {
         newlyAllowed.push(name);
+        this.preloadStatusMap.set(name, { state: "pending", itemCount: 0 });
       }
     }
+    this.emitPreloadStatusChange();
     if (newlyAllowed.length > 0) {
       await this.loadCollectionsToInMem(newlyAllowed, "setSyncOnlyTheseCollections");
     }
@@ -6079,6 +6088,7 @@ var _SyncedDb = class _SyncedDb {
       }
     } finally {
       this.syncLock = false;
+      this.emitPreloadStatusChange();
     }
   }
   async processQueuedWsUpdates() {
@@ -6895,7 +6905,11 @@ var _SyncedDb = class _SyncedDb {
       async () => {
         while (queue.length > 0) {
           const name = queue.shift();
-          const items = await this.loadCollectionToInMem(name);
+          let items = 0;
+          try {
+            items = await this.loadCollectionToInMem(name);
+          } catch (e) {
+          }
           totalItems += items;
           loaded++;
           this.safeCallback(this.onSyncProgress, {
@@ -6917,7 +6931,73 @@ var _SyncedDb = class _SyncedDb {
     });
     return totalItems;
   }
+  /**
+   * Hydrate a single collection from Dexie, recording the outcome in
+   * {@link preloadStatusMap} (hydrated / failed) for {@link getPreloadStatus}.
+   * Rethrows on failure so existing callers (e.g. the `Promise.allSettled` in
+   * addCollectionsToSync, the per-collection try/catch in loadCollectionsToInMem)
+   * keep their current behavior.
+   */
   async loadCollectionToInMem(name) {
+    var _a;
+    try {
+      const count = await this._hydrateCollectionFromDexie(name);
+      this.preloadStatusMap.set(name, { state: "hydrated", itemCount: count, hydratedAt: /* @__PURE__ */ new Date() });
+      this.emitPreloadStatusChange();
+      return count;
+    } catch (err) {
+      const prev = this.preloadStatusMap.get(name);
+      this.preloadStatusMap.set(name, {
+        state: "failed",
+        itemCount: (_a = prev == null ? void 0 : prev.itemCount) != null ? _a : 0,
+        hydratedAt: prev == null ? void 0 : prev.hydratedAt,
+        lastError: err instanceof Error ? err.message : String(err)
+      });
+      this.emitPreloadStatusChange();
+      throw err;
+    }
+  }
+  /**
+   * Per-collection hydration status + rolled-up aggregate, over readable
+   * (non-`writeOnly`), in-scope collections. See {@link I_SyncedDb.getPreloadStatus}.
+   */
+  getPreloadStatus() {
+    var _a, _b;
+    const collections = [];
+    let readyCount = 0;
+    let failedCount = 0;
+    let pendingCount = 0;
+    for (const name of this.collections.keys()) {
+      if (!this.isSyncAllowed(name)) continue;
+      const rec = (_a = this.preloadStatusMap.get(name)) != null ? _a : { state: "pending", itemCount: 0 };
+      const everDownloaded = !!((_b = this.syncMetaCache.get(name)) == null ? void 0 : _b.lastSyncTs);
+      const ready = rec.state === "hydrated";
+      if (rec.state === "failed") failedCount++;
+      else if (ready) readyCount++;
+      else pendingCount++;
+      collections.push({
+        name,
+        state: rec.state,
+        itemCount: rec.itemCount,
+        ready,
+        hydratedAt: rec.hydratedAt,
+        lastError: rec.lastError,
+        everDownloaded
+      });
+    }
+    const expectedCount = collections.length;
+    let aggregate;
+    if (expectedCount === 0) aggregate = "idle";
+    else if (readyCount === expectedCount) aggregate = "full";
+    else if (failedCount === expectedCount) aggregate = "failed";
+    else aggregate = "partial";
+    return { aggregate, collections, expectedCount, readyCount, failedCount, pendingCount };
+  }
+  /** Emit onPreloadStatusChange with a fresh snapshot (skips computation when no listener). */
+  emitPreloadStatusChange() {
+    if (this.onPreloadStatusChange) this.safeCallback(this.onPreloadStatusChange, this.getPreloadStatus());
+  }
+  async _hydrateCollectionFromDexie(name) {
     const allItems = [];
     await this.dexieDb.forEachBatch(name, 2e3, async (chunk) => {
       for (let i = 0; i < chunk.length; i++) {

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

@@ -1,5 +1,5 @@
 import type { AggregateOptions } from "mongodb";
-import type { I_SyncedDb, SyncedDbConfig, CollectionConfig, WsNotificationInfo, EvictionInfo, EvictionCollectionInfo } from "../types/I_SyncedDb";
+import type { I_SyncedDb, SyncedDbConfig, CollectionConfig, WsNotificationInfo, EvictionInfo, EvictionCollectionInfo, PreloadStatus } from "../types/I_SyncedDb";
 import type { DirtyMeta, MetaUpdateBroadcast } from "../types/I_DexieDb";
 import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
 import type { Id, DbEntity } from "../types/DbEntity";
@@ -34,6 +34,7 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly syncedDbInstanceId;
     private readonly dexieLoadConcurrency;
     private syncMetaCache;
+    private readonly preloadStatusMap;
     private unsubscribeServerUpdates?;
     private cleanupNotifierCallbacks?;
     private beforeUnloadHandler?;
@@ -46,6 +47,7 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onDexieSyncStart?;
     private readonly onDexieSyncEnd?;
     private readonly onSyncProgress?;
+    private readonly onPreloadStatusChange?;
     private readonly onServerSyncStart?;
     private readonly onServerSyncEnd?;
     private readonly onConflictResolved?;
@@ -516,7 +518,22 @@ export declare class SyncedDb implements I_SyncedDb {
      * @returns total items loaded
      */
     private loadCollectionsToInMem;
+    /**
+     * Hydrate a single collection from Dexie, recording the outcome in
+     * {@link preloadStatusMap} (hydrated / failed) for {@link getPreloadStatus}.
+     * Rethrows on failure so existing callers (e.g. the `Promise.allSettled` in
+     * addCollectionsToSync, the per-collection try/catch in loadCollectionsToInMem)
+     * keep their current behavior.
+     */
     private loadCollectionToInMem;
+    /**
+     * Per-collection hydration status + rolled-up aggregate, over readable
+     * (non-`writeOnly`), in-scope collections. See {@link I_SyncedDb.getPreloadStatus}.
+     */
+    getPreloadStatus(): PreloadStatus;
+    /** Emit onPreloadStatusChange with a fresh snapshot (skips computation when no listener). */
+    private emitPreloadStatusChange;
+    private _hydrateCollectionFromDexie;
     /**
      * Bulk-read sync cursors for every registered collection into syncMetaCache.
      * Called once during init() before sync can fire. Decouples cursor cache

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

@@ -400,6 +400,55 @@ export interface SyncInfo {
     /** Per-collection sync statistics (collection name -> stats) */
     collections?: Record<string, CollectionSyncStats>;
 }
+/** Per-collection hydration state for preload status reporting. */
+export type CollectionHydrationState = "pending" | "hydrated" | "failed";
+/** Hydration status of a single synced (readable, in-scope) collection. */
+export interface CollectionPreloadStatus {
+    /** Collection name. */
+    name: string;
+    /** Current hydration state. */
+    state: CollectionHydrationState;
+    /** In-mem item count after the last successful hydration (0 is valid). */
+    itemCount: number;
+    /**
+     * Whether the local cache is loaded into in-mem (`state === "hydrated"`).
+     * Empty is valid — a genuinely empty, never-synced collection is still ready.
+     * Data *freshness* is a separate, global concern (`lastSuccessfulServerSync`),
+     * not tracked per-collection.
+     */
+    ready: boolean;
+    /** Timestamp of the last successful Dexie→in-mem hydration. */
+    hydratedAt?: Date;
+    /** Error message from the last failed hydration (set when `state === "failed"`). */
+    lastError?: string;
+    /**
+     * Informational: true once a server download has advanced this collection's
+     * cursor (`lastSyncTs` set). NOT part of `ready` — an unused collection may
+     * never get a cursor yet is perfectly loadable.
+     */
+    everDownloaded: boolean;
+}
+/** Rolled-up preload status across all readable, in-scope collections. */
+export type PreloadAggregate = "idle" | "full" | "partial" | "failed";
+/** Snapshot of preload/hydration status — see {@link I_SyncedDb.getPreloadStatus}. */
+export interface PreloadStatus {
+    /**
+     * `full` = every expected collection ready; `failed` = all expected failed;
+     * `partial` = anything in between (some ready and/or pending and/or failed);
+     * `idle` = no readable, in-scope collections expected.
+     */
+    aggregate: PreloadAggregate;
+    /** Per-collection detail for every readable, in-scope collection. */
+    collections: CollectionPreloadStatus[];
+    /** Count of readable, in-scope collections (the denominator for `aggregate`). */
+    expectedCount: number;
+    /** Number of `ready` collections. */
+    readyCount: number;
+    /** Number of `failed` collections. */
+    failedCount: number;
+    /** Number of `pending` (not-yet-ready, not-failed) collections. */
+    pendingCount: number;
+}
 /** Per-collection eviction statistics. */
 export interface EvictionCollectionInfo {
     /** Collection name. */
@@ -590,6 +639,12 @@ export interface SyncedDbConfig {
         total: number;
         items: number;
     }) => void;
+    /**
+     * Callback when per-collection hydration status changes (hydration end,
+     * hydration failure, scope change, or sync end — when a download advances a
+     * cursor). Receives the same snapshot as {@link I_SyncedDb.getPreloadStatus}.
+     */
+    onPreloadStatusChange?: (status: PreloadStatus) => void;
     /** Callback when server download starts (findNewerManyStream) */
     onServerSyncStart?: (info: {
         calledFrom?: string;
@@ -1006,6 +1061,14 @@ export interface I_SyncedDb {
      * Persisted in Dexie via syncMeta key `__lastInitialSync`.
      */
     lastInitialSync(): Date | undefined;
+    /**
+     * Snapshot of per-collection hydration status plus a rolled-up aggregate
+     * (`full` / `partial` / `failed` / `idle`). Computed over readable
+     * (non-`writeOnly`), in-scope collections — so during a
+     * `setSyncOnlyTheseCollections` subset only those collections are reported.
+     * Synchronous; safe to call any time after construction.
+     */
+    getPreloadStatus(): PreloadStatus;
     /** Ali je povezan na server */
     isOnline(): boolean;
     /** Nastavi online/offline status. Returns a promise when going online. */

package/package.json

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