cry-synced-db-client 0.1.147 → 0.1.150

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 ## Unreleased
 
+### `SyncSource` flag in `I_InMemDb.saveMany` / `deleteManyByIds`
+
+The in-mem write API now accepts an opcijski `opts: { source?: SyncSource }`
+parameter that labels the **origin** of each batch:
+
+- `'initial'`     — first full sync of a collection (no prior `lastSyncTs`)
+- `'refresh'`     — `referToServerSync` background reload (timestamp = 0
+  for already-synced collection, e.g. when the app needs records outside
+  the current sync window)
+- `'incremental'` — everything else: delta sync, server WS push,
+  optimistic local writes (`save` / `insert` / `deleteOne` / `deleteMany`
+  / `hardDelete`), `findById` / `findByIds` `returnDeleted` server fetch,
+  `ensureItemsAreLoaded`, `refreshByIdsInBackground`, eviction deletes
+
+**Default**: when no `opts` is passed, `InMemManager.writeBatch`
+normalizes to `'incremental'`. Backward compatible — existing
+`I_InMemDb` implementations that ignore `opts` keep working unchanged.
+
+The signal is **advisory**: it does not change sync semantics or
+conflict resolution. Consumers can use it to apply per-source policies
+(e.g. selective Vue reactivity in the in-mem store: items first seen
+via `'incremental'` upgrade to reactive proxies; `'initial'` /
+`'refresh'` floods stay as plain JS objects).
+
+Threading: `SyncEngine` resolves `'initial'` per collection from
+`syncMetaCache` lookup at the start of each `sync()` cycle (no prior
+`lastSyncTs` ⇒ `'initial'`), and propagates the source via the
+`writeToInMemBatch` deps callback through `InMemManager` to
+`I_InMemDb.saveMany` / `deleteManyByIds`. `SyncedDb.referToServerSync`
+hardcodes `'refresh'`; `syncCollectionForFind` derives source from the
+local `timestamp === 0` check.
+
+Tests: `test/syncSource.test.ts` (9 cases) covers initial / incremental
+/ refresh propagation across all public write paths. `MockInMemDb`
+exposes `recordedCalls: RecordedInMemCall[]` for assertion.
+
+### `uploadDirtyItems` follow-up pass — drain in-sync writes immediately
+
+Writes that land **during** a sync iteration had their
+`scheduleRestUpload()` guarded out by `isSyncing()` (silent drop, no
+re-schedule), so they sat in `_dirty_changes` until the next 60s
+auto-sync tick. Particularly visible for high-frequency writeOnly
+collections (e.g. `prehodi`, written on every route change) on tablets
+with intensive navigation: dirty items piled up until the next tick.
+
+`SyncEngine.sync()` now performs a single follow-up pass right after the
+primary `uploadDirtyItems()` call:
+
+1. `flushAllPendingChanges()` — forces any in-flight 500ms Dexie
+   debounces to land in `_dirty_changes` before the second snapshot.
+2. `uploadDirtyItems(calledFrom + ":followUp")` — drains entries that
+   accumulated during the first pass's server roundtrip.
+
+Single pass (not a loop) — bounded work; later writes after sync
+completes will trigger their own `scheduleRestUpload()` once the
+`isSyncing` flag clears. Sequential `await` ordering means no concurrent
+server roundtrips and no new race conditions vs. the existing
+snapshot-then-clear pattern in `_dirty_changes`. Stats from the
+follow-up pass are merged into `uploadStats` so `onSyncEnd` /
+`collectionStats.sentCount` reflect both passes.
+
+Errors in the follow-up are caught by the same outer `try/catch` as the
+first pass — a follow-up failure does not roll back the first pass's
+already-cleared dirty entries; affected items are caught at the next
+sync tick (same retry semantics as before).
+
 ### Auto-eviction co-located with sync — one round-trip total
 
 When `evictStaleRecordsEveryHrs > 0` and the interval has elapsed, the

package/dist/index.js

@@ -272,12 +272,19 @@ var InMemManager = class {
   /**
    * Write batch of items to in-mem.
    * Handles metadata callbacks automatically when useObjectMetadata is enabled.
+   *
+   * @param opts.source — origin of the write ('initial' | 'refresh' | 'incremental').
+   *   Implementacija I_InMemDb lahko ta signal uporabi za optimizacije
+   *   (npr. selektivna reactivity); ne vpliva na sync semantiko.
+   *   Default: 'incremental'.
    */
-  writeBatch(collection, items, operation) {
+  writeBatch(collection, items, operation, opts) {
+    var _a;
     if (items.length === 0) return;
     const config = this.collections.get(collection);
+    const source = (_a = opts == null ? void 0 : opts.source) != null ? _a : "incremental";
     if (operation === "upsert") {
-      this.inMemDb.saveMany(collection, items);
+      this.inMemDb.saveMany(collection, items, { source });
       if (this.useObjectMetadata && (config == null ? void 0 : config.hasMetadata)) {
         const ids = [];
         for (const item of items) ids.push(item._id);
@@ -304,7 +311,7 @@ var InMemManager = class {
     } else if (operation === "delete") {
       const ids = [];
       for (const item of items) ids.push(item._id);
-      this.inMemDb.deleteManyByIds(collection, ids);
+      this.inMemDb.deleteManyByIds(collection, ids, { source });
       if (this.useObjectMetadata && (config == null ? void 0 : config.hasMetadata)) {
         this.deleteObjectsMetadataInternal(collection, ids);
       }
@@ -2478,10 +2485,13 @@ var _SyncEngine = class _SyncEngine {
       const findNewerManyStartTime = Date.now();
       const collectionState = /* @__PURE__ */ new Map();
       for (const [name] of configMap) {
+        const prior = this.deps.getSyncMetaCache().get(name);
+        const isInitial = !(prior == null ? void 0 : prior.lastSyncTs);
         collectionState.set(name, {
           maxTs: void 0,
           conflicts: 0,
-          receivedCount: 0
+          receivedCount: 0,
+          source: isInitial ? "initial" : "incremental"
         });
       }
       try {
@@ -2499,7 +2509,7 @@ var _SyncEngine = class _SyncEngine {
               if (!config) return;
               const state = collectionState.get(collection);
               state.receivedCount += items.length;
-              const stats = await this.processIncomingServerData(collection, config, items);
+              const stats = await this.processIncomingServerData(collection, config, items, state.source);
               state.conflicts += stats.conflictsResolved;
               if (stats.maxTs) {
                 if (!state.maxTs || this.compareTimestamps(stats.maxTs, state.maxTs) > 0) {
@@ -2553,6 +2563,17 @@ var _SyncEngine = class _SyncEngine {
       let uploadStats = { sentCount: 0 };
       try {
         uploadStats = await this.uploadDirtyItems(calledFrom);
+        await this.deps.flushAllPendingChanges();
+        const followUp = await this.uploadDirtyItems(`${calledFrom != null ? calledFrom : "sync"}:followUp`);
+        if (followUp.sentCount > 0) {
+          uploadStats.sentCount += followUp.sentCount;
+          if (followUp.collectionSentCounts) {
+            uploadStats.collectionSentCounts = uploadStats.collectionSentCounts || {};
+            for (const [c, n] of Object.entries(followUp.collectionSentCounts)) {
+              uploadStats.collectionSentCounts[c] = (uploadStats.collectionSentCounts[c] || 0) + n;
+            }
+          }
+        }
       } catch (err) {
         console.error(
           "uploadDirtyItems failed (download succeeded, staying online):",
@@ -2712,13 +2733,14 @@ var _SyncEngine = class _SyncEngine {
             await this.dexieDb.deleteMany(collection, dexieDeleteIds);
           }
           if (inMemUpdateBatch.length > 0) {
-            this.deps.writeToInMemBatch(collection, inMemUpdateBatch, "upsert");
+            this.deps.writeToInMemBatch(collection, inMemUpdateBatch, "upsert", { source: "incremental" });
           }
           if (inMemDeleteIds.length > 0) {
             this.deps.writeToInMemBatch(
               collection,
               inMemDeleteIds.map((id) => ({ _id: id })),
-              "delete"
+              "delete",
+              { source: "incremental" }
             );
           }
         }
@@ -2734,7 +2756,7 @@ var _SyncEngine = class _SyncEngine {
         }
         await this.dexieDb.deleteMany(collection, deleteIds);
         if (!isWriteOnly) {
-          this.deps.writeToInMemBatch(collection, deleteDbEntities, "delete");
+          this.deps.writeToInMemBatch(collection, deleteDbEntities, "delete", { source: "incremental" });
         }
         sentCount += deleted.length;
         collectionSentCount += deleted.length;
@@ -2844,17 +2866,23 @@ var _SyncEngine = class _SyncEngine {
   /**
    * Process incoming server data for a single collection.
    * Used by referToServer to process findNewer results.
+   *
+   * @param opts.source — origin label posredovan v writeBatch → inMemDb.
+   *   Default `'incremental'`. Caller naj uporabi `'refresh'` za množični
+   *   reload (referToServerSync) in `'initial'` za first-time fill.
    */
-  async processCollectionServerData(collectionName, serverData) {
+  async processCollectionServerData(collectionName, serverData, opts) {
+    var _a;
     const config = this.collections.get(collectionName);
     if (!config) return { updatedIds: [] };
-    const result = await this.processIncomingServerData(collectionName, config, serverData);
+    const source = (_a = opts == null ? void 0 : opts.source) != null ? _a : "incremental";
+    const result = await this.processIncomingServerData(collectionName, config, serverData, source);
     if (result.updatedIds.length > 0) {
       this.deps.broadcastUpdates({ [collectionName]: result.updatedIds });
     }
     return { updatedIds: result.updatedIds };
   }
-  async processIncomingServerData(collectionName, config, serverData) {
+  async processIncomingServerData(collectionName, config, serverData, source = "incremental") {
     if (serverData.length === 0) {
       return { conflictsResolved: 0, maxTs: void 0, updatedIds: [] };
     }
@@ -2916,13 +2944,14 @@ var _SyncEngine = class _SyncEngine {
         await this.dexieDb.saveMany(collectionName, dexieBatch);
       }
       if (inMemSaveBatch.length > 0) {
-        this.deps.writeToInMemBatch(collectionName, inMemSaveBatch, "upsert");
+        this.deps.writeToInMemBatch(collectionName, inMemSaveBatch, "upsert", { source });
       }
       if (inMemDeleteIds.length > 0) {
         this.deps.writeToInMemBatch(
           collectionName,
           inMemDeleteIds.map((id) => ({ _id: id })),
-          "delete"
+          "delete",
+          { source }
         );
       }
     }
@@ -3196,12 +3225,12 @@ var ServerUpdateHandler = class {
         await this.dexieDb.clearDirtyChange(collection, serverItem._id);
       }
       if (!serverItem._deleted && !serverItem._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert");
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert", { source: "incremental" });
       }
     } else {
       await this.dexieDb.insert(collection, serverItem);
       if (!serverItem._deleted && !serverItem._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert");
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert", { source: "incremental" });
       }
     }
   }
@@ -3230,7 +3259,7 @@ var ServerUpdateHandler = class {
       const currentInMemState = Object.assign({}, localItem, pendingChange.data);
       const merged = this.mergeLocalWithDelta(currentInMemState, serverDelta);
       if (!merged._deleted && !merged._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert");
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", { source: "incremental" });
       }
       return;
     }
@@ -3242,16 +3271,16 @@ var ServerUpdateHandler = class {
         await this.dexieDb.save(collection, serverDelta._id, merged);
       }
       if (!merged._deleted && !merged._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert");
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", { source: "incremental" });
       }
     } else {
       if (!metaChanged) return;
       const merged = this.mergeLocalWithDelta(localItem, serverDelta);
       await this.dexieDb.save(collection, serverDelta._id, merged);
       if (!merged._deleted && !merged._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert");
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", { source: "incremental" });
       } else {
-        this.deps.writeToInMemBatch(collection, [{ _id: serverDelta._id }], "delete");
+        this.deps.writeToInMemBatch(collection, [{ _id: serverDelta._id }], "delete", { source: "incremental" });
       }
     }
   }
@@ -3267,7 +3296,7 @@ var ServerUpdateHandler = class {
     } else {
       await this.dexieDb.deleteOne(collection, id);
     }
-    this.deps.writeToInMemBatch(collection, [{ _id: id }], "delete");
+    this.deps.writeToInMemBatch(collection, [{ _id: id }], "delete", { source: "incremental" });
   }
   // ============================================================
   // Private Helpers
@@ -3592,8 +3621,8 @@ var _SyncedDb = class _SyncedDb {
         isLeader: () => this.leaderElection.isLeader(),
         getCollections: () => this.collections,
         dexieDb: this.dexieDb,
-        writeToInMemBatch: (collection, items, operation) => {
-          this.inMemManager.writeBatch(collection, items, operation);
+        writeToInMemBatch: (collection, items, operation, opts) => {
+          this.inMemManager.writeBatch(collection, items, operation, opts);
         },
         isSyncAllowed: (collection) => this.isSyncAllowed(collection),
         reloadCollectionFromDexie: (collection) => this.loadCollectionToInMem(collection).then(() => void 0)
@@ -3672,8 +3701,8 @@ var _SyncedDb = class _SyncedDb {
       deps: {
         getSyncMetaCache: () => this.syncMetaCache,
         setSyncMetaCache: (collection, meta) => this.syncMetaCache.set(collection, meta),
-        writeToInMemBatch: (collection, items, operation) => {
-          this.inMemManager.writeBatch(collection, items, operation);
+        writeToInMemBatch: (collection, items, operation, opts) => {
+          this.inMemManager.writeBatch(collection, items, operation, opts);
         },
         getInMemById: (collection, id) => this.inMemDb.getById(collection, id),
         withSyncTimeout: (promise, operation) => this.connectionManager.withSyncTimeout(promise, operation),
@@ -3697,8 +3726,8 @@ var _SyncedDb = class _SyncedDb {
       deps: {
         isLeader: () => this.leaderElection.isLeader(),
         canReceiveServerUpdates: () => this.connectionManager.canReceiveServerUpdates(),
-        writeToInMemBatch: (collection, items, operation) => {
-          this.inMemManager.writeBatch(collection, items, operation);
+        writeToInMemBatch: (collection, items, operation, opts) => {
+          this.inMemManager.writeBatch(collection, items, operation, opts);
         },
         broadcastUpdates: (updates) => this.crossTabSync.broadcastMetaUpdate(updates),
         getPendingChange: (collection, id) => this.pendingChanges.getPendingChange(collection, id),
@@ -4007,7 +4036,7 @@ var _SyncedDb = class _SyncedDb {
         if (serverItem) {
           await this.dexieDb.saveMany(collection, [serverItem]);
           if (!serverItem._deleted && !serverItem._archived) {
-            this.inMemManager.writeBatch(collection, [serverItem], "upsert");
+            this.inMemManager.writeBatch(collection, [serverItem], "upsert", { source: "incremental" });
           }
         }
       } catch (e) {
@@ -4066,7 +4095,7 @@ var _SyncedDb = class _SyncedDb {
           await this.dexieDb.saveMany(collection, serverItems);
           const toInMem = serverItems.filter((s) => !s._deleted && !s._archived);
           if (toInMem.length > 0) {
-            this.inMemManager.writeBatch(collection, toInMem, "upsert");
+            this.inMemManager.writeBatch(collection, toInMem, "upsert", { source: "incremental" });
           }
         }
       } catch (e) {
@@ -4185,7 +4214,8 @@ var _SyncedDb = class _SyncedDb {
         "syncCollectionForFind"
       );
       if (serverData.length > 0) {
-        await this.syncEngine.processCollectionServerData(collection, serverData);
+        const source = timestamp === 0 ? "initial" : "incremental";
+        await this.syncEngine.processCollectionServerData(collection, serverData, { source });
       }
     } catch (e) {
     }
@@ -4203,7 +4233,7 @@ var _SyncedDb = class _SyncedDb {
       "referToServer"
     ).then(async (serverData) => {
       if (serverData.length > 0) {
-        await this.syncEngine.processCollectionServerData(collection, serverData);
+        await this.syncEngine.processCollectionServerData(collection, serverData, { source: "refresh" });
       }
     }).catch((err) => {
       console.error(`referToServer failed for ${collection}:`, err);
@@ -4225,7 +4255,7 @@ var _SyncedDb = class _SyncedDb {
       "refreshInBackground"
     ).then(async (serverItems) => {
       if (!serverItems || serverItems.length === 0) return;
-      await this.syncEngine.processCollectionServerData(collection, serverItems);
+      await this.syncEngine.processCollectionServerData(collection, serverItems, { source: "incremental" });
     }).catch((err) => {
       console.error(`refreshInBackground failed for ${collection}:`, err);
     });
@@ -4263,7 +4293,7 @@ var _SyncedDb = class _SyncedDb {
       await this.dexieDb.saveMany(collection, toSaveDexie);
     }
     if (toSaveInMem.length > 0) {
-      this.inMemManager.writeBatch(collection, toSaveInMem, "upsert");
+      this.inMemManager.writeBatch(collection, toSaveInMem, "upsert", { source: "incremental" });
     }
   }
   // ==================== Write Operations ====================
@@ -4298,7 +4328,7 @@ var _SyncedDb = class _SyncedDb {
     const currentMem = isWriteOnly ? null : this.inMemDb.getById(collection, id);
     const merged = __spreadValues(__spreadValues({}, currentMem || existing || { _id: id }), update);
     if (!isWriteOnly && !(existing == null ? void 0 : existing._deleted) && !(existing == null ? void 0 : existing._archived)) {
-      this.inMemManager.writeBatch(collection, [merged], "upsert");
+      this.inMemManager.writeBatch(collection, [merged], "upsert", { source: "incremental" });
     }
     return merged;
   }
@@ -4338,7 +4368,7 @@ var _SyncedDb = class _SyncedDb {
     });
     this.pendingChanges.schedule(collection, id, newData, 0, "insert");
     if (!((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly)) {
-      this.inMemManager.writeBatch(collection, [newData], "upsert");
+      this.inMemManager.writeBatch(collection, [newData], "upsert", { source: "incremental" });
     }
     return newData;
   }
@@ -4362,7 +4392,7 @@ var _SyncedDb = class _SyncedDb {
     };
     this.pendingChanges.schedule(collection, id, deleteUpdate, 0, "deleteOne");
     if (!((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly)) {
-      this.inMemManager.writeBatch(collection, [{ _id: id }], "delete");
+      this.inMemManager.writeBatch(collection, [{ _id: id }], "delete", { source: "incremental" });
     }
     return existing;
   }
@@ -4399,7 +4429,8 @@ var _SyncedDb = class _SyncedDb {
       this.inMemManager.writeBatch(
         collection,
         idsToDelete.map((id) => ({ _id: id })),
-        "delete"
+        "delete",
+        { source: "incremental" }
       );
     }
     return idsToDelete.length;
@@ -4420,7 +4451,7 @@ var _SyncedDb = class _SyncedDb {
       "hardDeleteOne"
     );
     await this.dexieDb.deleteOne(collection, id);
-    this.inMemManager.writeBatch(collection, [{ _id: id }], "delete");
+    this.inMemManager.writeBatch(collection, [{ _id: id }], "delete", { source: "incremental" });
     return existing;
   }
   async hardDelete(collection, query) {
@@ -4457,7 +4488,7 @@ var _SyncedDb = class _SyncedDb {
               "hardDelete"
             );
             await this.dexieDb.deleteOne(collection, item.id);
-            this.inMemManager.writeBatch(collection, [{ _id: item.id }], "delete");
+            this.inMemManager.writeBatch(collection, [{ _id: item.id }], "delete", { source: "incremental" });
             results.push(true);
           } catch (err) {
             console.error(`Failed to hard delete ${String(item.id)}:`, err);
@@ -4837,7 +4868,8 @@ var _SyncedDb = class _SyncedDb {
         this.inMemManager.writeBatch(
           collection,
           evictIds.map((id) => ({ _id: id })),
-          "delete"
+          "delete",
+          { source: "incremental" }
         );
       }
       this.crossTabSync.broadcastReload([collection]);
@@ -5090,7 +5122,8 @@ var _SyncedDb = class _SyncedDb {
           this.inMemManager.writeBatch(
             p.collection,
             uniqueEvictIds.map((id) => ({ _id: id })),
-            "delete"
+            "delete",
+            { source: "incremental" }
           );
         }
         this.crossTabSync.broadcastReload([p.collection]);

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

@@ -7,6 +7,7 @@
  * - Encapsulation: Hides metadata storage implementation
  */
 import type { Id, DbEntity } from "../../types/DbEntity";
+import type { SyncSource } from "../../types/I_InMemDb";
 import type { I_InMemManager, InMemManagerConfig } from "../types/managers";
 export declare class InMemManager implements I_InMemManager {
     private readonly inMemDb;
@@ -18,8 +19,15 @@ export declare class InMemManager implements I_InMemManager {
     /**
      * Write batch of items to in-mem.
      * Handles metadata callbacks automatically when useObjectMetadata is enabled.
+     *
+     * @param opts.source — origin of the write ('initial' | 'refresh' | 'incremental').
+     *   Implementacija I_InMemDb lahko ta signal uporabi za optimizacije
+     *   (npr. selektivna reactivity); ne vpliva na sync semantiko.
+     *   Default: 'incremental'.
      */
-    writeBatch<T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete"): void;
+    writeBatch<T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete", opts?: {
+        source?: SyncSource;
+    }): void;
     /**
      * Initialize collection from Dexie data.
      * Called during SyncedDb.init().

package/dist/src/db/sync/SyncEngine.d.ts

@@ -7,6 +7,7 @@
  * - Uploading dirty items to server
  */
 import type { LocalDbEntity } from "../../types/DbEntity";
+import type { SyncSource } from "../../types/I_InMemDb";
 import type { I_SyncEngine, SyncEngineConfig, SyncExtras } from "../types/managers";
 import type { UploadResult } from "../types/internal";
 export declare class SyncEngine implements I_SyncEngine {
@@ -39,8 +40,14 @@ export declare class SyncEngine implements I_SyncEngine {
     /**
      * Process incoming server data for a single collection.
      * Used by referToServer to process findNewer results.
+     *
+     * @param opts.source — origin label posredovan v writeBatch → inMemDb.
+     *   Default `'incremental'`. Caller naj uporabi `'refresh'` za množični
+     *   reload (referToServerSync) in `'initial'` za first-time fill.
      */
-    processCollectionServerData(collectionName: string, serverData: LocalDbEntity[]): Promise<{
+    processCollectionServerData(collectionName: string, serverData: LocalDbEntity[], opts?: {
+        source?: SyncSource;
+    }): Promise<{
         updatedIds: string[];
     }>;
     /** Max items to process per batch in processIncomingServerData */

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

@@ -4,7 +4,7 @@
  */
 import type { Id, DbEntity, LocalDbEntity } from "../../types/DbEntity";
 import type { I_DexieDb, SyncMeta, MetaUpdateBroadcast } from "../../types/I_DexieDb";
-import type { I_InMemDb } from "../../types/I_InMemDb";
+import type { I_InMemDb, SyncSource } from "../../types/I_InMemDb";
 import type { I_RestInterface } from "../../types/I_RestInterface";
 import type { PublishDataPayload } from "../../types/PublishRevsPayload";
 import type { CollectionConfig, SyncInfo, ConflictResolutionReport, ServerWriteRequestInfo, ServerWriteResultInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, CrossTabSyncInfo } from "../../types/I_SyncedDb";
@@ -49,7 +49,9 @@ export interface CrossTabSyncDeps {
     /** DexieDb instance. */
     dexieDb: I_DexieDb;
     /** Write to in-mem batch. */
-    writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete") => void;
+    writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete", opts?: {
+        source?: SyncSource;
+    }) => void;
     /** Whether a collection participates in sync (not writeOnly, not filtered out). */
     isSyncAllowed: (collection: string) => boolean;
     /** Reload a collection fully from Dexie into in-mem (called on reload broadcast). */
@@ -212,7 +214,9 @@ export interface InMemManagerConfig {
 }
 export interface I_InMemManager {
     /** Write batch of items to in-mem. */
-    writeBatch<T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete"): void;
+    writeBatch<T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete", opts?: {
+        source?: import("../../types/I_InMemDb").SyncSource;
+    }): void;
     /** Initialize collection from Dexie data. */
     initCollection<T extends DbEntity>(collection: string, items: T[]): void;
     /** Clear collection data and metadata. */
@@ -261,7 +265,9 @@ export interface SyncEngineCallbacks {
 export interface SyncEngineDeps {
     getSyncMetaCache: () => Map<string, SyncMeta>;
     setSyncMetaCache: (collection: string, meta: SyncMeta) => void;
-    writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete") => void;
+    writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete", opts?: {
+        source?: SyncSource;
+    }) => void;
     getInMemById: <T extends DbEntity>(collection: string, id: Id) => T | undefined;
     withSyncTimeout: <T>(promise: Promise<T>, operation: string) => Promise<T>;
     /** Notify consumers that a sync cycle failed. Does not mutate online state. */
@@ -311,7 +317,9 @@ export interface I_SyncEngine {
     /** Upload dirty items for a specific collection. */
     uploadDirtyItemsForCollection(collection: string): Promise<UploadResult>;
     /** Process incoming server data for a single collection (used by referToServer). */
-    processCollectionServerData(collectionName: string, serverData: import("../../types/DbEntity").LocalDbEntity[]): Promise<{
+    processCollectionServerData(collectionName: string, serverData: import("../../types/DbEntity").LocalDbEntity[], opts?: {
+        source?: SyncSource;
+    }): Promise<{
         updatedIds: string[];
     }>;
 }
@@ -323,7 +331,9 @@ export interface ServerUpdateHandlerDeps {
     canReceiveServerUpdates: () => boolean;
     getPendingChange: (collection: string, id: Id) => PendingChange | undefined;
     broadcastUpdates: (updates: Record<string, string[]>) => void;
-    writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete") => void;
+    writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete", opts?: {
+        source?: SyncSource;
+    }) => void;
     /** Whether a collection participates in sync (not writeOnly, not filtered out). */
     isSyncAllowed: (collection: string) => boolean;
 }

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

@@ -1,13 +1,34 @@
 import type { Id, DbEntity } from "./DbEntity";
+/**
+ * Izvor sync zapisa. Implementacija I_InMemDb lahko ta signal
+ * uporabi za optimizacije (npr. selektivna reactivity v klijentu),
+ * ne vpliva pa na sync semantiko.
+ *
+ * - 'initial'     — full snapshot pri prvem polnjenju kolekcije
+ * - 'refresh'     — refreshLocal pull (množični reload obstoječe kolekcije)
+ * - 'incremental' — delta s servera (vključno z lokalnim optimistic write
+ *                   pred server confirmom)
+ */
+export type SyncSource = "initial" | "refresh" | "incremental";
+/**
+ * Opcije za zapisovalne operacije.
+ * Field-i so opcijski — implementacije, ki jih ne uporabljajo, jih lahko ignorirajo.
+ */
+export interface SaveManyOpts {
+    source?: SyncSource;
+}
+export interface DeleteManyByIdsOpts {
+    source?: SyncSource;
+}
 /**
  * Interface za in-memory bazo podatkov
  * UI samo bere iz te baze, posodablja jo samo sync-db
  */
 export interface I_InMemDb {
     /** Shrani/posodobi več objektov naenkrat (bulk upsert) */
-    saveMany<T extends DbEntity>(collection: string, items: T[]): void;
+    saveMany<T extends DbEntity>(collection: string, items: T[], opts?: SaveManyOpts): void;
     /** Izbriše več objektov iz kolekcije po ID-jih */
-    deleteManyByIds(collection: string, ids: Id[]): void;
+    deleteManyByIds(collection: string, ids: Id[], opts?: DeleteManyByIdsOpts): void;
     /** Shrani celotno kolekcijo (nadomesti obstoječo) */
     saveCollection<T extends DbEntity>(collection: string, data: T[]): void;
     /** Izbriše celotno kolekcijo */

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

@@ -1,7 +1,7 @@
 export type { Id, Entity, IdOrEntity, DbEntity, LocalDbEntity } from "./DbEntity";
 export type { PublishableOperation, PublishRevsPayloadInsert, PublishRevsPayloadUpdate, PublishRevsPayloadDelete, PublishRevsPayloadUpdateMany, PublishRevsPayloadDeleteMany, PublishRevsPayloadBatchItem, PublishRevsPayloadBatch, PublishRevsPayload, PublishRevsSpec, PublishDataPayloadBase, PublishDataPayloadInsert, PublishDataPayloadUpdate, PublishDataPayloadDelete, PublishDataPayloadBatch, PublishDataPayload, PublishDataSpec, PublishSpec, } from "./PublishRevsPayload";
 export type { Obj, QuerySpec, Projection, QueryOpts, KeyOf, InsertKeyOf, InsertSpec, UpdateSpec, BatchSpec, UpsertOptions, GetNewerSpec, I_RestInterface as RestInterface, } from "./I_RestInterface";
-export type { I_InMemDb as InMemDb } from "./I_InMemDb";
+export type { I_InMemDb as InMemDb, SyncSource, SaveManyOpts, DeleteManyByIdsOpts } from "./I_InMemDb";
 export type { I_DexieDb as DexieDb, SyncMeta, DirtyChange, DirtyMeta } from "./I_DexieDb";
 export type { I_ServerUpdateNotifier as ServerUpdateNotifier, ServerUpdateCallback, ServerUpdateNotifierCallbacks } from "./I_ServerUpdateNotifier";
 export type { I_SyncedDb as SyncedDb, SyncedDbConfig, CollectionConfig, CollectionSyncConfig, SyncInfo, ServerWriteRequestInfo, ServerWriteResultInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, InfrastructureErrorType, InfrastructureErrorInfo, ConflictSource, ConflictResolutionReport, CrossTabSyncInfo, EvictionInfo, EvictionCollectionInfo, } from "./I_SyncedDb";

package/package.json

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