cry-synced-db-client 0.1.144 → 0.1.145

package/CHANGELOG.md

@@ -108,6 +108,37 @@ Signature is identical. No other callback changes.
   - Noop when offline or on writeOnly collections.
   - Ignored on `find` / `findOne` (use `referToServer` there).
 
+## 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,
@@ -4983,6 +4984,7 @@ var _SyncedDb = class _SyncedDb {
           totalItems += items;
           loaded++;
           this.safeCallback(this.onSyncProgress, {
+            phase: "dexie",
             collection: name,
             loaded,
             total: names.length,

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.145",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",