cry-synced-db-client 0.1.67 → 0.1.71

package/dist/index.js

@@ -121,6 +121,103 @@ function filterByQuery(items, query) {
   }
   return items.filter((item) => matchesQuery(item, query));
 }
+function sortItems(items, sort) {
+  const sortEntries = Object.entries(sort);
+  if (sortEntries.length === 0)
+    return items;
+  return [...items].sort((a, b) => {
+    for (const [field, direction] of sortEntries) {
+      const aVal = getNestedValue(a, field);
+      const bVal = getNestedValue(b, field);
+      const cmp = compareValues(aVal, bVal);
+      if (cmp !== 0)
+        return cmp * direction;
+    }
+    return 0;
+  });
+}
+function compareValues(a, b) {
+  if (a === b)
+    return 0;
+  if (a == null && b == null)
+    return 0;
+  if (a == null)
+    return -1;
+  if (b == null)
+    return 1;
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return (a ? 1 : 0) - (b ? 1 : 0);
+  }
+  const sa = String(a);
+  const sb = String(b);
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+function applySkipLimit(items, skip, limit) {
+  let result = items;
+  if (skip && skip > 0) {
+    result = result.slice(skip);
+  }
+  if (limit != null && limit >= 0) {
+    result = result.slice(0, limit);
+  }
+  return result;
+}
+function projectItem(item, project) {
+  const entries = Object.entries(project);
+  if (entries.length === 0)
+    return item;
+  const hasIncludes = entries.some(([, v]) => v === true || v === 1);
+  if (hasIncludes) {
+    const result = {};
+    const excludeId = project._id === false || project._id === 0;
+    if (!excludeId && item._id !== undefined) {
+      result._id = item._id;
+    }
+    for (const [field, value] of entries) {
+      if (field === "_id")
+        continue;
+      if (value === true || value === 1) {
+        const val = getNestedValue(item, field);
+        if (val !== undefined) {
+          result[field] = val;
+        }
+      }
+    }
+    return result;
+  } else {
+    const result = { ...item };
+    for (const [field, value] of entries) {
+      if (value === false || value === 0) {
+        delete result[field];
+      }
+    }
+    return result;
+  }
+}
+function applyQueryOpts(items, opts) {
+  if (!opts)
+    return items;
+  let result = items;
+  if (opts.sort && Object.keys(opts.sort).length > 0) {
+    result = sortItems(result, opts.sort);
+  }
+  if (opts.skip || opts.limit != null) {
+    result = applySkipLimit(result, opts.skip, opts.limit);
+  }
+  if (opts.project) {
+    result = result.map((item) => projectItem(item, opts.project));
+  }
+  return result;
+}
 
 // src/db/managers/InMemManager.ts
 class InMemManager {
@@ -2032,6 +2129,7 @@ class SyncEngine {
     let receivedCount = 0;
     let sentCount = 0;
     let conflictsResolved = 0;
+    const collectionStats = {};
     try {
       this.deps.cancelRestUploadTimer();
       await this.deps.awaitRestUpload();
@@ -2069,6 +2167,11 @@ class SyncEngine {
       for (const [collectionName, config] of configMap) {
         const serverData = allServerData[collectionName] || [];
         receivedCount += serverData.length;
+        collectionStats[collectionName] = {
+          receivedCount: serverData.length,
+          sentCount: 0,
+          receivedItems: serverData
+        };
         const stats = await this.processIncomingServerData(collectionName, config, serverData);
         conflictsResolved += stats.conflictsResolved;
         if (stats.updatedIds.length > 0) {
@@ -2080,13 +2183,25 @@ class SyncEngine {
       }
       const uploadStats = await this.uploadDirtyItems(calledFrom);
       sentCount = uploadStats.sentCount;
+      for (const [collectionName, stats] of Object.entries(uploadStats.collectionSentCounts || {})) {
+        if (collectionStats[collectionName]) {
+          collectionStats[collectionName].sentCount = stats;
+        } else {
+          collectionStats[collectionName] = {
+            receivedCount: 0,
+            sentCount: stats,
+            receivedItems: []
+          };
+        }
+      }
       this.callOnSync({
         durationMs: Date.now() - startTime,
         receivedCount,
         sentCount,
         conflictsResolved,
         success: true,
-        calledFrom
+        calledFrom,
+        collections: collectionStats
       });
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
@@ -2099,7 +2214,8 @@ class SyncEngine {
         conflictsResolved,
         success: false,
         error: err instanceof Error ? err : new Error(String(err)),
-        calledFrom
+        calledFrom,
+        collections: collectionStats
       });
       throw err;
     }
@@ -2158,6 +2274,7 @@ class SyncEngine {
       throw err;
     }
     let sentCount = 0;
+    const collectionSentCounts = {};
     for (const result of results) {
       const { collection, results: { inserted, updated, deleted, errors } } = result;
       const allSuccessIds = [
@@ -2168,6 +2285,7 @@ class SyncEngine {
       if (allSuccessIds.length > 0) {
         await this.dexieDb.clearDirtyChangesBatch(collection, allSuccessIds);
       }
+      let collectionSentCount = 0;
       const insertedAndUpdated = [...inserted, ...updated];
       if (insertedAndUpdated.length > 0) {
         const idsToCheck = insertedAndUpdated.map((e) => e._id);
@@ -2202,12 +2320,17 @@ class SyncEngine {
           this.deps.writeToInMemBatch(collection, inMemUpdateBatch, "upsert");
         }
         sentCount += insertedAndUpdated.length;
+        collectionSentCount += insertedAndUpdated.length;
       }
       if (deleted.length > 0) {
         const deleteIds = deleted.map((e) => e._id);
         await this.dexieDb.deleteMany(collection, deleteIds);
         this.deps.writeToInMemBatch(collection, deleteIds.map((id) => ({ _id: id })), "delete");
         sentCount += deleted.length;
+        collectionSentCount += deleted.length;
+      }
+      if (collectionSentCount > 0) {
+        collectionSentCounts[collection] = collectionSentCount;
       }
       const allItems = [...inserted, ...updated, ...deleted];
       let maxTs = undefined;
@@ -2234,7 +2357,7 @@ class SyncEngine {
         console.error(`Sync errors for ${collection}:`, errors);
       }
     }
-    return { sentCount };
+    return { sentCount, collectionSentCounts };
   }
   async uploadDirtyItemsForCollection(collection) {
     const dirtyItems = await this.dexieDb.getDirty(collection);
@@ -2287,6 +2410,16 @@ class SyncEngine {
     }
     return { sentCount };
   }
+  async processCollectionServerData(collectionName, serverData) {
+    const config = this.collections.get(collectionName);
+    if (!config)
+      return { updatedIds: [] };
+    const result = await this.processIncomingServerData(collectionName, config, serverData);
+    if (result.updatedIds.length > 0) {
+      this.deps.broadcastUpdates({ [collectionName]: result.updatedIds });
+    }
+    return { updatedIds: result.updatedIds };
+  }
   async processIncomingServerData(collectionName, config, serverData) {
     if (serverData.length === 0) {
       return { conflictsResolved: 0, maxTs: undefined, updatedIds: [] };
@@ -2313,14 +2446,14 @@ class SyncEngine {
           conflictsResolved++;
           const resolved = this.resolveCollectionConflict(collectionName, config, localItem, serverItem, "sync");
           dexieBatch.push(resolved);
-          if (!resolved._deleted) {
+          if (!resolved._deleted && !resolved._archived) {
             inMemSaveBatch.push(resolved);
           } else {
             inMemDeleteIds.push(serverItem._id);
           }
         } else {
           dexieBatch.push(serverItem);
-          if (!serverItem._deleted) {
+          if (!serverItem._deleted && !serverItem._archived) {
             inMemSaveBatch.push(serverItem);
           } else {
             inMemDeleteIds.push(serverItem._id);
@@ -2328,7 +2461,7 @@ class SyncEngine {
         }
       } else {
         dexieBatch.push(serverItem);
-        if (!serverItem._deleted) {
+        if (!serverItem._deleted && !serverItem._archived) {
           inMemSaveBatch.push(serverItem);
         }
       }
@@ -2571,12 +2704,12 @@ class ServerUpdateHandler {
       if (dirtyChange && !metaChanged) {
         await this.dexieDb.clearDirtyChange(collection, serverItem._id);
       }
-      if (!serverItem._deleted) {
+      if (!serverItem._deleted && !serverItem._archived) {
         this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert");
       }
     } else {
       await this.dexieDb.insert(collection, serverItem);
-      if (!serverItem._deleted) {
+      if (!serverItem._deleted && !serverItem._archived) {
         this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert");
       }
     }
@@ -2602,7 +2735,7 @@ class ServerUpdateHandler {
       }
       const currentInMemState = { ...localItem, ...pendingChange.data };
       const merged = this.mergeLocalWithDelta(currentInMemState, serverDelta);
-      if (!merged._deleted) {
+      if (!merged._deleted && !merged._archived) {
         this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert");
       }
       return;
@@ -2614,7 +2747,7 @@ class ServerUpdateHandler {
       if (metaChanged) {
         await this.dexieDb.save(collection, serverDelta._id, merged);
       }
-      if (!merged._deleted) {
+      if (!merged._deleted && !merged._archived) {
         this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert");
       }
     } else {
@@ -2622,7 +2755,7 @@ class ServerUpdateHandler {
         return;
       const merged = this.mergeLocalWithDelta(localItem, serverDelta);
       await this.dexieDb.save(collection, serverDelta._id, merged);
-      if (!merged._deleted) {
+      if (!merged._deleted && !merged._archived) {
         this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert");
       } else {
         this.deps.writeToInMemBatch(collection, [{ _id: serverDelta._id }], "delete");
@@ -2885,12 +3018,15 @@ class SyncedDb {
   initialized = false;
   syncing = false;
   syncLock = false;
+  wsUpdateQueue = [];
   updaterId;
   syncedDbInstanceId;
   syncMetaCache = new Map;
   unsubscribeServerUpdates;
   cleanupNotifierCallbacks;
   beforeUnloadHandler;
+  defaultReturnDeleted;
+  defaultReturnArchived;
   onSync;
   onConflictResolved;
   onWsNotification;
@@ -2905,6 +3041,8 @@ class SyncedDb {
     this.updaterId = Math.random().toString(36).substring(2, 15);
     this.syncedDbInstanceId = `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
     const windowId = config._testWindowId ?? this.getOrCreateWindowId();
+    this.defaultReturnDeleted = config.returnDeleted ?? false;
+    this.defaultReturnArchived = config.returnArchived ?? false;
     this.onSync = config.onSync;
     this.onConflictResolved = config.onConflictResolved;
     this.onWsNotification = config.onWsNotification;
@@ -3113,7 +3251,7 @@ class SyncedDb {
     await this.pendingChanges.recoverPendingWrites();
     for (const [name] of this.collections) {
       const data = await this.dexieDb.getAll(name);
-      const activeData = data.filter((item) => !item._deleted);
+      const activeData = data.filter((item) => !item._deleted && !item._archived);
       this.inMemManager.initCollection(name, activeData);
       const meta = await this.dexieDb.getSyncMeta(name);
       if (meta) {
@@ -3134,7 +3272,13 @@ class SyncedDb {
         if (cleanup)
           this.cleanupNotifierCallbacks = cleanup;
       }
-      this.unsubscribeServerUpdates = this.serverUpdateNotifier.subscribe((payload) => this.serverUpdateHandler.handleServerUpdate(payload));
+      this.unsubscribeServerUpdates = this.serverUpdateNotifier.subscribe((payload) => {
+        if (this.syncing) {
+          this.wsUpdateQueue.push(payload);
+          return;
+        }
+        return this.serverUpdateHandler.handleServerUpdate(payload);
+      });
       try {
         await this.serverUpdateNotifier.connect();
       } catch (err) {
@@ -3198,41 +3342,119 @@ class SyncedDb {
   async setOnline(online) {
     await this.connectionManager.setOnline(online);
   }
-  async findById(collection, id) {
+  async findById(collection, id, opts) {
     this.assertCollection(collection);
+    opts = this.resolveOpts(opts);
+    if ((opts?.returnDeleted || opts?.returnArchived) && this.isOnline()) {
+      try {
+        const serverItem = await this.connectionManager.withRestTimeout(this.restInterface.findById(collection, id), "findById");
+        if (serverItem) {
+          await this.dexieDb.saveMany(collection, [serverItem]);
+          if (!serverItem._deleted && !serverItem._archived) {
+            this.inMemManager.writeBatch(collection, [serverItem], "upsert");
+          }
+        }
+      } catch {}
+    }
     const item = await this.dexieDb.getById(collection, id);
-    if (!item || item._deleted)
+    if (!item)
       return null;
-    return item;
+    if (!opts?.returnDeleted && item._deleted)
+      return null;
+    if (!opts?.returnArchived && item._archived)
+      return null;
+    let result = item;
+    if (opts?.project) {
+      const [projected] = applyQueryOpts([result], { project: opts.project });
+      result = projected;
+    }
+    if (opts?.referToServer && this.isOnline()) {
+      this.referToServerSync(collection);
+    }
+    return result;
   }
-  async findByIds(collection, ids) {
+  async findByIds(collection, ids, opts) {
     this.assertCollection(collection);
+    opts = this.resolveOpts(opts);
     if (ids.length === 0)
       return [];
+    if ((opts?.returnDeleted || opts?.returnArchived) && this.isOnline()) {
+      try {
+        const serverItems = await this.connectionManager.withRestTimeout(this.restInterface.findByIds(collection, ids), "findByIds");
+        if (serverItems && serverItems.length > 0) {
+          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");
+          }
+        }
+      } catch {}
+    }
     const items = await this.dexieDb.getByIds(collection, ids);
     const results = [];
     for (const item of items) {
-      if (item && !item._deleted) {
-        results.push(item);
-      }
+      if (!item)
+        continue;
+      if (!opts?.returnDeleted && item._deleted)
+        continue;
+      if (!opts?.returnArchived && item._archived)
+        continue;
+      results.push(item);
     }
-    return results;
+    const final = applyQueryOpts(results, opts);
+    if (opts?.referToServer && this.isOnline()) {
+      this.referToServerSync(collection);
+    }
+    return final;
   }
-  async findOne(collection, query) {
+  async findOne(collection, query, opts) {
     this.assertCollection(collection);
+    opts = this.resolveOpts(opts);
+    if ((opts?.returnDeleted || opts?.returnArchived) && this.isOnline()) {
+      await this.syncCollectionForFind(collection, query, opts);
+    }
     const all = await this.dexieDb.getAll(collection);
-    const active = all.filter((item) => !item._deleted);
+    const active = all.filter((item) => {
+      if (!opts?.returnDeleted && item._deleted)
+        return false;
+      if (!opts?.returnArchived && item._archived)
+        return false;
+      return true;
+    });
     const filtered = filterByQuery(active, query);
-    if (filtered.length === 0)
+    if (filtered.length === 0) {
+      if (opts?.referToServer && this.isOnline()) {
+        this.referToServerSync(collection, query);
+      }
       return null;
-    return filtered[0];
+    }
+    const sorted = applyQueryOpts(filtered, { sort: opts?.sort, project: opts?.project });
+    const result = sorted[0];
+    if (opts?.referToServer && this.isOnline()) {
+      this.referToServerSync(collection, query);
+    }
+    return result;
   }
-  async find(collection, query) {
+  async find(collection, query, opts) {
     this.assertCollection(collection);
+    opts = this.resolveOpts(opts);
+    if ((opts?.returnDeleted || opts?.returnArchived) && this.isOnline()) {
+      await this.syncCollectionForFind(collection, query, opts);
+    }
     const all = await this.dexieDb.getAll(collection);
-    const active = all.filter((item) => !item._deleted);
+    const active = all.filter((item) => {
+      if (!opts?.returnDeleted && item._deleted)
+        return false;
+      if (!opts?.returnArchived && item._archived)
+        return false;
+      return true;
+    });
     const filtered = query ? filterByQuery(active, query) : active;
-    return filtered;
+    const result = applyQueryOpts(filtered, opts);
+    if (opts?.referToServer && this.isOnline()) {
+      this.referToServerSync(collection, query);
+    }
+    return result;
   }
   async aggregate(collection, pipeline, opts) {
     this.assertCollection(collection);
@@ -3241,6 +3463,67 @@ class SyncedDb {
     }
     return this.connectionManager.withRestTimeout(this.restInterface.aggregate(collection, pipeline, opts), "aggregate");
   }
+  async syncCollectionForFind(collection, query, opts) {
+    const meta = this.syncMetaCache.get(collection);
+    const timestamp = meta?.lastSyncTs || 0;
+    try {
+      const serverData = await this.connectionManager.withRestTimeout(this.restInterface.findNewer(collection, timestamp, query, {
+        returnDeleted: opts?.returnDeleted || false,
+        returnArchived: opts?.returnArchived || false
+      }), "syncCollectionForFind");
+      if (serverData.length > 0) {
+        await this.syncEngine.processCollectionServerData(collection, serverData);
+      }
+    } catch {}
+  }
+  referToServerSync(collection, query) {
+    const meta = this.syncMetaCache.get(collection);
+    const timestamp = meta?.lastSyncTs || 0;
+    this.connectionManager.withRestTimeout(this.restInterface.findNewer(collection, timestamp, query, { returnDeleted: true }), "referToServer").then(async (serverData) => {
+      if (serverData.length > 0) {
+        await this.syncEngine.processCollectionServerData(collection, serverData);
+      }
+    }).catch((err) => {
+      console.error(`referToServer sync failed for ${collection}:`, err);
+    });
+  }
+  async ensureItemsAreLoaded(collection, ids, withDeleted) {
+    this.assertCollection(collection);
+    if (ids.length === 0)
+      return;
+    const localItems = await this.dexieDb.getByIds(collection, ids);
+    const missingIds = [];
+    for (let i = 0;i < ids.length; i++) {
+      if (!localItems[i]) {
+        missingIds.push(ids[i]);
+      }
+    }
+    if (missingIds.length === 0)
+      return;
+    if (!this.isOnline())
+      return;
+    const serverItems = await this.connectionManager.withRestTimeout(this.restInterface.findByIds(collection, missingIds), "ensureItemsAreLoaded");
+    if (!serverItems || serverItems.length === 0)
+      return;
+    const toSaveDexie = [];
+    const toSaveInMem = [];
+    for (const item of serverItems) {
+      if (!item)
+        continue;
+      if (!withDeleted && item._deleted)
+        continue;
+      toSaveDexie.push(item);
+      if (!item._deleted && !item._archived) {
+        toSaveInMem.push(item);
+      }
+    }
+    if (toSaveDexie.length > 0) {
+      await this.dexieDb.saveMany(collection, toSaveDexie);
+    }
+    if (toSaveInMem.length > 0) {
+      this.inMemManager.writeBatch(collection, toSaveInMem, "upsert");
+    }
+  }
   async save(collection, id, update) {
     this.assertCollection(collection);
     const existing = await this.dexieDb.getById(collection, id);
@@ -3255,7 +3538,7 @@ class SyncedDb {
     this.pendingChanges.schedule(collection, id, newData, 0, "save");
     const currentMem = this.inMemDb.getById(collection, id);
     const merged = { ...currentMem || existing || { _id: id }, ...update };
-    if (!existing?._deleted) {
+    if (!existing?._deleted && !existing?._archived) {
       this.inMemManager.writeBatch(collection, [merged], "upsert");
     }
     return merged;
@@ -3275,7 +3558,7 @@ class SyncedDb {
     this.assertCollection(collection);
     const id = data._id || new ObjectId2;
     const existing = await this.dexieDb.getById(collection, id);
-    if (existing && !existing._deleted) {
+    if (existing && !existing._deleted && !existing._archived) {
       console.warn(`SyncedDb.insert: Object ${String(id)} already exists in ${collection}, overwriting`);
     }
     const insertChanges = { ...data, _lastUpdaterId: this.updaterId };
@@ -3416,6 +3699,16 @@ class SyncedDb {
     } finally {
       this.syncing = false;
       this.syncLock = false;
+      await this.processQueuedWsUpdates();
+    }
+  }
+  async processQueuedWsUpdates() {
+    if (this.wsUpdateQueue.length === 0)
+      return;
+    const queue = this.wsUpdateQueue;
+    this.wsUpdateQueue = [];
+    for (const payload of queue) {
+      await this.serverUpdateHandler.handleServerUpdate(payload);
     }
   }
   isSyncing() {
@@ -3545,6 +3838,16 @@ class SyncedDb {
   getOrCreateWindowId() {
     return `shared-${this.tenant}`;
   }
+  resolveOpts(opts) {
+    if (!this.defaultReturnDeleted && !this.defaultReturnArchived) {
+      return opts;
+    }
+    return {
+      ...opts,
+      returnDeleted: opts?.returnDeleted ?? this.defaultReturnDeleted,
+      returnArchived: opts?.returnArchived ?? this.defaultReturnArchived
+    };
+  }
   assertCollection(name) {
     if (!this.collections.has(name)) {
       throw new Error(`Collection "${name}" not configured`);
@@ -5906,7 +6209,7 @@ var unpackr = new Unpackr({ structuredClone: true });
 var pack2 = (x) => packr.pack(preprocessForPack(x));
 var unpack2 = (x) => unpackr.unpack(x);
 var DEFAULT_TIMEOUT = 5000;
-var DEFAULT_PROGRESS_CHUNK_SIZE = 16384;
+var DEFAULT_PROGRESS_CHUNK_SIZE = 16 * 1024;
 
 class RestProxy {
   endpoint;
@@ -6450,9 +6753,13 @@ class Ebus2ProxyServerUpdateNotifier {
   }
 }
 export {
+  sortItems,
   resolveConflict,
+  projectItem,
   matchesQuery,
   filterByQuery,
+  applySkipLimit,
+  applyQueryOpts,
   SyncedDb,
   RestProxy,
   Ebus2ProxyServerUpdateNotifier,

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

@@ -1,7 +1,7 @@
 import type { AggregateOptions } from "mongodb";
 import type { I_SyncedDb, SyncedDbConfig, WsNotificationInfo } from "../types/I_SyncedDb";
 import type { MetaUpdateBroadcast } from "../types/I_DexieDb";
-import type { QuerySpec, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
+import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
 import type { Id, DbEntity } from "../types/DbEntity";
 /**
  * Main synchronized database implementation.
@@ -26,12 +26,15 @@ export declare class SyncedDb implements I_SyncedDb {
     private initialized;
     private syncing;
     private syncLock;
+    private wsUpdateQueue;
     private readonly updaterId;
     private readonly syncedDbInstanceId;
     private syncMetaCache;
     private unsubscribeServerUpdates?;
     private cleanupNotifierCallbacks?;
     private beforeUnloadHandler?;
+    private readonly defaultReturnDeleted;
+    private readonly defaultReturnArchived;
     private readonly onSync?;
     private readonly onConflictResolved?;
     private readonly onWsNotification?;
@@ -51,11 +54,22 @@ export declare class SyncedDb implements I_SyncedDb {
     forceOffline(forced: boolean): void;
     isForcedOffline(): boolean;
     setOnline(online: boolean): Promise<void>;
-    findById<T extends DbEntity>(collection: string, id: Id): Promise<T | null>;
-    findByIds<T extends DbEntity>(collection: string, ids: Id[]): Promise<T[]>;
-    findOne<T extends DbEntity>(collection: string, query: QuerySpec<T>): Promise<T | null>;
-    find<T extends DbEntity>(collection: string, query?: QuerySpec<T>): Promise<T[]>;
+    findById<T extends DbEntity>(collection: string, id: Id, opts?: QueryOpts): Promise<T | null>;
+    findByIds<T extends DbEntity>(collection: string, ids: Id[], opts?: QueryOpts): Promise<T[]>;
+    findOne<T extends DbEntity>(collection: string, query: QuerySpec<T>, opts?: QueryOpts): Promise<T | null>;
+    find<T extends DbEntity>(collection: string, query?: QuerySpec<T>, opts?: QueryOpts): Promise<T[]>;
     aggregate<T>(collection: string, pipeline: object[], opts?: AggregateOptions): Promise<T[]>;
+    /**
+     * Sync a collection from server before querying locally.
+     * Used when returnDeleted/returnArchived is specified on find/findOne.
+     */
+    private syncCollectionForFind;
+    /**
+     * Fire-and-forget background sync for a single collection.
+     * Calls findNewer with the last sync timestamp and processes results.
+     */
+    private referToServerSync;
+    ensureItemsAreLoaded(collection: string, ids: string[], withDeleted?: boolean): Promise<void>;
     save<T extends DbEntity>(collection: string, id: Id, update: Partial<T>): Promise<T>;
     upsert<T extends DbEntity>(collection: string, query: QuerySpec<T>, update: UpdateSpec<T>): Promise<T>;
     insert<T extends DbEntity>(collection: string, data: InsertSpec<T>): Promise<T>;
@@ -65,6 +79,7 @@ export declare class SyncedDb implements I_SyncedDb {
     hardDelete<T extends DbEntity>(collection: string, query: QuerySpec<T>): Promise<number>;
     ping(timeoutMs?: number): Promise<boolean>;
     sync(calledFrom?: string): Promise<void>;
+    private processQueuedWsUpdates;
     isSyncing(): boolean;
     upsertBatch<T extends DbEntity>(collection: string, batch: BatchSpec<T>): Promise<T[]>;
     getMemoryCollection<T extends DbEntity>(collection: string): T[];
@@ -94,5 +109,10 @@ export declare class SyncedDb implements I_SyncedDb {
      * so we use a constant value to ensure all tabs compete for the same lock.
      */
     private getOrCreateWindowId;
+    /**
+     * Resolve effective QueryOpts by merging global defaults with per-call opts.
+     * Per-call values take precedence over global defaults.
+     */
+    private resolveOpts;
     private assertCollection;
 }

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

@@ -6,6 +6,7 @@
  * - Processing incoming data with conflict resolution
  * - Uploading dirty items to server
  */
+import type { LocalDbEntity } from "../../types/DbEntity";
 import type { I_SyncEngine, SyncEngineConfig } from "../types/managers";
 import type { UploadResult } from "../types/internal";
 export declare class SyncEngine implements I_SyncEngine {
@@ -30,6 +31,13 @@ export declare class SyncEngine implements 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 to process findNewer results.
+     */
+    processCollectionServerData(collectionName: string, serverData: LocalDbEntity[]): Promise<{
+        updatedIds: string[];
+    }>;
     private processIncomingServerData;
     private compareTimestamps;
     private resolveCollectionConflict;

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

@@ -27,6 +27,8 @@ export interface SyncResult {
  */
 export interface UploadResult {
     sentCount: number;
+    /** Per-collection sent counts (collection name -> count) */
+    collectionSentCounts?: Record<string, number>;
 }
 /**
  * Result from processing incoming server data.

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

@@ -242,6 +242,10 @@ export interface I_SyncEngine {
     uploadDirtyItems(calledFrom?: string): Promise<UploadResult>;
     /** 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<{
+        updatedIds: string[];
+    }>;
 }
 export interface ServerUpdateHandlerCallbacks {
     onWsNotification?: (info: WsNotificationInfo) => void;

package/dist/src/index.d.ts

@@ -8,4 +8,4 @@ export type { RestProxyConfig } from "./db/RestProxy";
 export { Ebus2ProxyServerUpdateNotifier } from "./db/Ebus2ProxyServerUpdateNotifier";
 export type { Ebus2ProxyServerUpdateNotifierConfig } from "./db/Ebus2ProxyServerUpdateNotifier";
 export { resolveConflict } from "./utils/conflictResolution";
-export { filterByQuery, matchesQuery } from "./utils/localQuery";
+export { filterByQuery, matchesQuery, sortItems, applySkipLimit, projectItem, applyQueryOpts } from "./utils/localQuery";

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

@@ -14,6 +14,7 @@ export interface DbEntity {
     _ts?: Timestamp;
     _csq?: number;
     _deleted?: Date;
+    _archived?: Date;
     _blocked?: boolean;
     /** ID zadnjega updaterja - za detekcijo loopback */
     _lastUpdaterId?: string;

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

@@ -5,7 +5,7 @@ export type CollectionUpdateResult = Types.CollectionUpdateResult;
 export type Obj = {
     [key: string]: any;
 };
-export type QuerySpec<T> = Partial<Record<keyof T | "_deleted" | "_blocked" | "_ts" | "_id", any>>;
+export type QuerySpec<T> = Partial<Record<keyof T | "_deleted" | "_archived" | "_blocked" | "_ts" | "_id", any>>;
 export type Projection = SchemaMember<any, Document | number | boolean | any>;
 export type QueryOpts = Partial<{
     project: Projection;
@@ -16,6 +16,10 @@ export type QueryOpts = Partial<{
     readPreference: ReadPreference;
     /** Če je true, vrne tudi soft-deleted objekte (z _deleted poljem) */
     returnDeleted: boolean;
+    /** Če je true, vrne tudi archived objekte (z _archived poljem) */
+    returnArchived: boolean;
+    /** Če je true, vrne lokalne rezultate in nato v ozadju sinhronizira s serverjem */
+    referToServer: boolean;
 }>;
 export type KeyOf<T> = keyof T | "$bit" | "$set" | "$inc" | "$currentDate" | "$min" | "$max" | "$mul" | "$rename" | "$setOnInsert" | "$unset" | "$pull" | "$push" | "$pop" | "$addToSet" | "$pushAll" | "_rev" | "_ts" | "_csq" | "_deleted";
 export type InsertKeyOf<T> = keyof T | "_rev" | "_ts" | "_csq" | "_deleted";

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

@@ -1,6 +1,6 @@
 import type { AggregateOptions } from "mongodb";
 import type { Id, DbEntity, LocalDbEntity } from "./DbEntity";
-import type { QuerySpec, UpdateSpec, InsertSpec, BatchSpec, I_RestInterface, CollectionUpdateRequest, CollectionUpdateResult, GetNewerSpec } from "./I_RestInterface";
+import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec, I_RestInterface, CollectionUpdateRequest, CollectionUpdateResult, GetNewerSpec } from "./I_RestInterface";
 import type { I_DexieDb } from "./I_DexieDb";
 import type { I_InMemDb } from "./I_InMemDb";
 import type { I_ServerUpdateNotifier } from "./I_ServerUpdateNotifier";
@@ -198,6 +198,17 @@ export interface ConflictResolutionReport {
     /** Timestamp when conflict was resolved */
     timestamp: Date;
 }
+/**
+ * Per-collection sync statistics
+ */
+export interface CollectionSyncStats {
+    /** Number of items received from server for this collection */
+    receivedCount: number;
+    /** Number of dirty items sent to server for this collection */
+    sentCount: number;
+    /** The actual items received from server (for debugging/logging) */
+    receivedItems: LocalDbEntity[];
+}
 /**
  * Informacije o sinhronizaciji za debugging/logging
  */
@@ -216,6 +227,8 @@ export interface SyncInfo {
     error?: Error;
     /** Where sync was called from (for debugging) */
     calledFrom?: string;
+    /** Per-collection sync statistics (collection name -> stats) */
+    collections?: Record<string, CollectionSyncStats>;
 }
 /**
  * Configuration for collection sync behavior (used in sync() method only, not uploadDirtyItems)
@@ -338,6 +351,20 @@ export interface SyncedDbConfig {
      * whenever objects are written to in-mem. Default: false.
      */
     useObjectMetadata?: boolean;
+    /**
+     * Global default for returning soft-deleted items in find operations.
+     * When true, all find* methods include deleted items unless overridden per-call.
+     * Per-call opts.returnDeleted takes precedence over this setting.
+     * Default: false
+     */
+    returnDeleted?: boolean;
+    /**
+     * Global default for returning archived items in find operations.
+     * When true, all find* methods include archived items unless overridden per-call.
+     * Per-call opts.returnArchived takes precedence over this setting.
+     * Default: false
+     */
+    returnArchived?: boolean;
     /**
      * Enable sync on wake from sleep for leader tab.
      * When enabled, detects wake via pageshow/focus/visibilitychange events
@@ -423,13 +450,18 @@ export interface I_SyncedDb {
      */
     isForcedOffline(): boolean;
     /** Poišče objekt po ID-ju */
-    findById<T extends DbEntity>(collection: string, id: Id): Promise<T | null>;
+    findById<T extends DbEntity>(collection: string, id: Id, opts?: QueryOpts): Promise<T | null>;
     /** Poišče objekte po ID-jih */
-    findByIds<T extends DbEntity>(collection: string, ids: Id[]): Promise<T[]>;
+    findByIds<T extends DbEntity>(collection: string, ids: Id[], opts?: QueryOpts): Promise<T[]>;
     /** Poišče prvi objekt, ki ustreza poizvedbi */
-    findOne<T extends DbEntity>(collection: string, query: QuerySpec<T>): Promise<T | null>;
+    findOne<T extends DbEntity>(collection: string, query: QuerySpec<T>, opts?: QueryOpts): Promise<T | null>;
     /** Poišče vse objekte, ki ustrezajo poizvedbi */
-    find<T extends DbEntity>(collection: string, query?: QuerySpec<T>): Promise<T[]>;
+    find<T extends DbEntity>(collection: string, query?: QuerySpec<T>, opts?: QueryOpts): Promise<T[]>;
+    /**
+     * Preveri prisotnost podanih ID-jev v lokalni bazi.
+     * Manjkajoče naloži s serverja (če je online).
+     */
+    ensureItemsAreLoaded(collection: string, ids: string[], withDeleted?: boolean): Promise<void>;
     /** Izvede agregacijo na serverju (offline vrne []) */
     aggregate<T>(collection: string, pipeline: object[], opts?: AggregateOptions): Promise<T[]>;
     /**

package/dist/src/utils/localQuery.d.ts

@@ -1,4 +1,4 @@
-import type { QuerySpec } from "../types/I_RestInterface";
+import type { QuerySpec, QueryOpts, Projection } from "../types/I_RestInterface";
 import type { DbEntity } from "../types/DbEntity";
 /**
  * Preveri, ali objekt ustreza MongoDB-style query specifikaciji
@@ -9,3 +9,22 @@ export declare function matchesQuery<T extends DbEntity>(item: T, query: QuerySp
  * Filtriraj array objektov po query
  */
 export declare function filterByQuery<T extends DbEntity>(items: T[], query?: QuerySpec<T>): T[];
+/**
+ * Sortiraj array objektov po MongoDB-style sort specifikaciji.
+ * Podpira multi-field sort: { name: 1, age: -1 }
+ */
+export declare function sortItems<T>(items: T[], sort: Record<string, -1 | 1>): T[];
+/**
+ * Uporabi skip in limit na array.
+ */
+export declare function applySkipLimit<T>(items: T[], skip?: number, limit?: number): T[];
+/**
+ * Uporabi projekcijo na en objekt.
+ * Podpira include mode ({ field: true }) in exclude mode ({ field: false }).
+ * _id je vedno vključen, razen če je eksplicitno izključen.
+ */
+export declare function projectItem<T>(item: T, project: Projection): Partial<T>;
+/**
+ * Uporabi QueryOpts na array: sort → skip → limit → project
+ */
+export declare function applyQueryOpts<T>(items: T[], opts?: QueryOpts): T[];

package/package.json

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