cry-synced-db-client 0.1.144 → 0.1.146

package/CHANGELOG.md

@@ -108,6 +108,67 @@ Signature is identical. No other callback changes.
   - Noop when offline or on writeOnly collections.
   - Ignored on `find` / `findOne` (use `referToServer` there).
 
+## 0.1.146 (2026-04-25)
+
+### Fix: INITIAL SYNC re-fetched whole dataset on every reload (cursor race)
+
+`syncMetaCache` was populated lazily inside `loadCollectionToInMem` — one
+collection at a time, only after that collection's records finished hydrating
+into in-memory state. When `ConnectionManager.tryGoOnline` fired
+`sync("INITIAL SYNC")` on WS connect (or `setSyncOnlyTheseCollections`
+expanded the allowed set under a fresh login), the sync engine read
+`syncMetaCache.get(collection)?.lastSyncTs` for each collection — and for
+collections whose hydration hadn't completed yet, it found nothing and fell
+back to `timestamp: 0` (`SyncEngine.ts:94`). The server then returned every
+matching row since epoch, not a delta.
+
+In one observed reproducer with 62 sync'd collections, 58 of them arrived at
+the server with `timestamp: 0` and the server replied with 60 131 rows on a
+session that already had 58 745 rows cached locally — i.e. ~full re-fetch
+every reload, regardless of how recently the client had synced.
+
+`init()` now eagerly preloads sync cursors for every registered collection
+into `syncMetaCache` before `connectionManager.startTimers()` runs, via a
+parallel fan-out of `getSyncMeta` reads. Cursor cache availability is
+decoupled from in-mem record hydration: a sync triggered the moment WS comes
+up reads a fully populated cache, regardless of where hydration is. One Dexie
+point-lookup per registered collection — cheap.
+
+The lazy populate inside `loadCollectionToInMem` is retained as a defensive
+overwrite for collections registered after init (e.g. via dynamic
+`addCollection`).
+
+## 0.1.145 (2026-04-25)
+
+### Fix: `onSyncProgress` back-track during initial sync
+
+`onSyncProgress` is fired from two distinct phases that can run **concurrently**
+during initial sync — Dexie → in-mem hydration (`SyncedDb.loadCollectionsToInMem`)
+and server → Dexie download (`SyncEngine.findNewerManyStream`). Each phase
+carries its own `loaded`/`total`, so consumers wiring the callback into a single
+progress bar saw the percentage back-track every time a tick from the other
+phase arrived (e.g. dexie 9/58 → server 1/62 → dexie 10/58 → server 2/62 …).
+
+The payload now carries a `phase: 'dexie' | 'server'` discriminator so consumers
+can attribute each tick to its source and either filter or render the two
+streams separately. **Non-breaking**: consumers that destructure
+`{ collection, loaded, total }` and ignore `phase` keep working unchanged.
+
+Type change in `I_SyncedDb.SyncedDbConfig` and internal `SyncEngineCallbacks`:
+```ts
+onSyncProgress?: (info: {
+  phase: 'dexie' | 'server';
+  collection: string;
+  loaded: number;
+  total: number;
+  items: number;
+}) => void;
+```
+
+The JSDoc on `onSyncProgress` previously claimed "Fires only during
+init/setSyncOnlyTheseCollections" — that was wrong; it also fires during server
+sync. Doc corrected.
+
 ## 0.1.136 (2026-04-20)
 
 - `DexieDb.saveMany` is now fail-safe:

package/dist/index.js

@@ -2502,6 +2502,7 @@ var _SyncEngine = class _SyncEngine {
               if (!completedCollections.has(collection)) {
                 completedCollections.add(collection);
                 this.callbackSafe(this.callbacks.onSyncProgress, {
+                  phase: "server",
                   collection,
                   loaded: completedCollections.size,
                   total: syncSpecs.length,
@@ -3800,6 +3801,7 @@ var _SyncedDb = class _SyncedDb {
       }
     }
     await this.pendingChanges.recoverPendingWrites();
+    await this.preloadAllSyncMetas();
     const allowedColls = [...this.collections.keys()].filter((n) => this.isSyncAllowed(n));
     await this.loadCollectionsToInMem(allowedColls, "init");
     this.leaderElection.init();
@@ -4983,6 +4985,7 @@ var _SyncedDb = class _SyncedDb {
           totalItems += items;
           loaded++;
           this.safeCallback(this.onSyncProgress, {
+            phase: "dexie",
             collection: name,
             loaded,
             total: names.length,
@@ -5017,6 +5020,25 @@ var _SyncedDb = class _SyncedDb {
     }
     return allItems.length;
   }
+  /**
+   * Bulk-read sync cursors for every registered collection into syncMetaCache.
+   * Called once during init() before sync can fire. Decouples cursor cache
+   * availability from in-mem record hydration, eliminating the race where a
+   * sync triggered by ConnectionManager.tryGoOnline (or by setSyncOnlyTheseCollections
+   * expanding the allowed set) reads an unpopulated cache and sends timestamp:0
+   * for un-hydrated collections.
+   */
+  async preloadAllSyncMetas() {
+    const names = [...this.collections.keys()];
+    const results = await Promise.all(
+      names.map(
+        (name) => this.dexieDb.getSyncMeta(name).then((meta) => ({ name, meta }))
+      )
+    );
+    for (const { name, meta } of results) {
+      if (meta) this.syncMetaCache.set(name, meta);
+    }
+  }
   assertCollection(name) {
     if (!this.collections.has(name)) {
       throw new Error(`SyncedDb: Collection "${(name == null ? void 0 : name.toString()) || "?"}" not configured`);

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

@@ -291,6 +291,15 @@ export declare class SyncedDb implements I_SyncedDb {
      */
     private loadCollectionsToInMem;
     private loadCollectionToInMem;
+    /**
+     * Bulk-read sync cursors for every registered collection into syncMetaCache.
+     * Called once during init() before sync can fire. Decouples cursor cache
+     * availability from in-mem record hydration, eliminating the race where a
+     * sync triggered by ConnectionManager.tryGoOnline (or by setSyncOnlyTheseCollections
+     * expanding the allowed set) reads an unpopulated cache and sends timestamp:0
+     * for un-hydrated collections.
+     */
+    private preloadAllSyncMetas;
     private assertCollection;
     private static readonly STRINGIFIED_FALSY;
     /** Stringify an Id parameter (ObjectId → hex string). */

package/dist/src/db/types/managers.d.ts

@@ -235,6 +235,7 @@ export interface SyncEngineCallbacks {
     }) => void;
     onSyncEnd?: (info: SyncInfo) => void;
     onSyncProgress?: (info: {
+        phase: 'dexie' | 'server';
         collection: string;
         loaded: number;
         total: number;

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

@@ -345,8 +345,15 @@ export interface SyncedDbConfig {
         totalItems: number;
         durationMs: number;
     }) => void;
-    /** Callback after each collection is loaded during full sync (Dexie→inMem). Fires only during init/setSyncOnlyTheseCollections. */
+    /**
+     * Callback after each collection completes loading. Fires from two distinct phases that can run
+     * concurrently — `phase` discriminates the source so consumers can render progress coherently:
+     *  - `'dexie'`  — Dexie → in-memory hydration during init/setSyncOnlyTheseCollections
+     *  - `'server'` — server → Dexie download during full/initial sync (findNewerManyStream)
+     * `loaded`/`total` are scoped to the phase that emitted the event.
+     */
     onSyncProgress?: (info: {
+        phase: 'dexie' | 'server';
         collection: string;
         loaded: number;
         total: number;

package/package.json

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