cry-synced-db-client 0.1.148 → 0.1.151

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## 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

package/dist/index.js

@@ -69,16 +69,13 @@ function matchesQuery(item, query) {
 function matchesCondition(item, key, condition) {
   const value = getNestedValue(item, key);
   if (condition === null || typeof condition !== "object") {
-    return value === condition;
+    return scalarMatches(value, condition);
   }
   if (condition instanceof Date) {
-    if (value instanceof Date) {
-      return value.getTime() === condition.getTime();
-    }
-    return false;
+    return scalarMatches(value, condition);
   }
   if (Array.isArray(condition)) {
-    return condition.includes(value);
+    return condition.some((c) => scalarMatches(value, c));
   }
   for (const [op, opValue] of Object.entries(condition)) {
     if (!matchesOperator(value, op, opValue)) {
@@ -90,29 +87,32 @@ function matchesCondition(item, key, condition) {
 function matchesOperator(value, operator, operand) {
   switch (operator) {
     case "$eq":
-      return equals(value, operand);
+      return scalarMatches(value, operand);
     case "$ne":
-      return !equals(value, operand);
+      return !scalarMatches(value, operand);
     case "$gt":
-      return value > operand;
+      return compareScalarOrArray(value, (v) => v > operand);
     case "$gte":
-      return value >= operand;
+      return compareScalarOrArray(value, (v) => v >= operand);
     case "$lt":
-      return value < operand;
+      return compareScalarOrArray(value, (v) => v < operand);
     case "$lte":
-      return value <= operand;
+      return compareScalarOrArray(value, (v) => v <= operand);
     case "$in":
       if (!Array.isArray(operand)) return false;
-      return operand.some((item) => equals(value, item));
+      return operand.some((item) => scalarMatches(value, item));
     case "$nin":
       if (!Array.isArray(operand)) return true;
-      return !operand.some((item) => equals(value, item));
+      return !operand.some((item) => scalarMatches(value, item));
     case "$exists":
       return operand ? value !== void 0 : value === void 0;
     case "$regex": {
-      if (typeof value !== "string") return false;
       const regex = operand instanceof RegExp ? operand : new RegExp(operand);
-      return regex.test(value);
+      if (typeof value === "string") return regex.test(value);
+      if (Array.isArray(value)) {
+        return value.some((v) => typeof v === "string" && regex.test(v));
+      }
+      return false;
     }
     case "$elemMatch":
       if (!Array.isArray(value)) return false;
@@ -152,6 +152,19 @@ function getNestedValue(obj, path) {
   }
   return current;
 }
+function scalarMatches(value, scalar) {
+  if (equals(value, scalar)) return true;
+  if (Array.isArray(value)) {
+    return value.some((elem) => equals(elem, scalar));
+  }
+  return false;
+}
+function compareScalarOrArray(value, predicate) {
+  if (Array.isArray(value)) {
+    return value.some((v) => predicate(v));
+  }
+  return predicate(value);
+}
 function equals(a, b) {
   var _a, _b;
   if (a === b) return true;
@@ -272,12 +285,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 +324,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 +2498,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 +2522,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) {
@@ -2723,13 +2746,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" }
             );
           }
         }
@@ -2745,7 +2769,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;
@@ -2855,17 +2879,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: [] };
     }
@@ -2927,13 +2957,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 }
         );
       }
     }
@@ -3207,12 +3238,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" });
       }
     }
   }
@@ -3241,7 +3272,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;
     }
@@ -3253,16 +3284,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" });
       }
     }
   }
@@ -3278,7 +3309,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
@@ -3603,8 +3634,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)
@@ -3683,8 +3714,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),
@@ -3708,8 +3739,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),
@@ -4018,7 +4049,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) {
@@ -4077,7 +4108,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) {
@@ -4196,7 +4227,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) {
     }
@@ -4214,7 +4246,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);
@@ -4236,7 +4268,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);
     });
@@ -4274,7 +4306,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 ====================
@@ -4309,7 +4341,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;
   }
@@ -4349,7 +4381,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;
   }
@@ -4373,7 +4405,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;
   }
@@ -4410,7 +4442,8 @@ var _SyncedDb = class _SyncedDb {
       this.inMemManager.writeBatch(
         collection,
         idsToDelete.map((id) => ({ _id: id })),
-        "delete"
+        "delete",
+        { source: "incremental" }
       );
     }
     return idsToDelete.length;
@@ -4431,7 +4464,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) {
@@ -4468,7 +4501,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);
@@ -4848,7 +4881,8 @@ var _SyncedDb = class _SyncedDb {
         this.inMemManager.writeBatch(
           collection,
           evictIds.map((id) => ({ _id: id })),
-          "delete"
+          "delete",
+          { source: "incremental" }
         );
       }
       this.crossTabSync.broadcastReload([collection]);
@@ -5101,7 +5135,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/dist/src/utils/localQuery.d.ts

@@ -5,6 +5,10 @@ import type { DbEntity } from "../types/DbEntity";
  * Podpira polje-operatorje: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin,
  * $exists, $regex, $elemMatch, $size, $all — in logične operatorje
  * $and, $or, $nor na top-levelu.
+ *
+ * Skalarni operandi se ujemajo tudi z array-polji (MongoDB semantika):
+ * `{ a: "ok" }` matcha tako `{ a: "ok" }` kot `{ a: ["ok", "more"] }`.
+ * Velja za neposredno enakost, $eq, $ne, $in, $nin, $gt/$gte/$lt/$lte in $regex.
  */
 export declare function matchesQuery<T extends DbEntity>(item: T, query: QuerySpec<T>): boolean;
 /**

package/package.json

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