cry-synced-db-client 0.1.69 → 0.1.72

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 {
@@ -2069,11 +2166,12 @@ class SyncEngine {
       const allUpdatedIds = {};
       for (const [collectionName, config] of configMap) {
         const serverData = allServerData[collectionName] || [];
+        delete allServerData[collectionName];
         receivedCount += serverData.length;
         collectionStats[collectionName] = {
           receivedCount: serverData.length,
           sentCount: 0,
-          receivedItems: serverData
+          receivedItems: []
         };
         const stats = await this.processIncomingServerData(collectionName, config, serverData);
         conflictsResolved += stats.conflictsResolved;
@@ -2313,60 +2411,79 @@ 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 };
+  }
+  static SYNC_BATCH_SIZE = 200;
   async processIncomingServerData(collectionName, config, serverData) {
     if (serverData.length === 0) {
       return { conflictsResolved: 0, maxTs: undefined, updatedIds: [] };
     }
     let maxTs;
     let conflictsResolved = 0;
-    const serverIds = serverData.map((item) => item._id);
-    const localItems = await this.dexieDb.getByIds(collectionName, serverIds);
-    const dirtyChangesMap = await this.dexieDb.getDirtyChangesBatch(collectionName, serverIds);
-    const dexieBatch = [];
-    const inMemSaveBatch = [];
-    const inMemDeleteIds = [];
-    for (let i = 0;i < serverData.length; i++) {
-      const serverItem = serverData[i];
-      const localItem = localItems[i];
-      const dirtyChange = dirtyChangesMap.get(String(serverItem._id));
-      if (serverItem._ts) {
-        if (!maxTs || this.compareTimestamps(serverItem._ts, maxTs) > 0) {
-          maxTs = serverItem._ts;
+    const allUpdatedIds = [];
+    const BATCH = SyncEngine.SYNC_BATCH_SIZE;
+    for (let offset = 0;offset < serverData.length; offset += BATCH) {
+      const chunk = serverData.slice(offset, offset + BATCH);
+      const chunkIds = chunk.map((item) => item._id);
+      const localItems = await this.dexieDb.getByIds(collectionName, chunkIds);
+      const dirtyChangesMap = await this.dexieDb.getDirtyChangesBatch(collectionName, chunkIds);
+      const dexieBatch = [];
+      const inMemSaveBatch = [];
+      const inMemDeleteIds = [];
+      for (let i = 0;i < chunk.length; i++) {
+        const serverItem = chunk[i];
+        const localItem = localItems[i];
+        const dirtyChange = dirtyChangesMap.get(String(serverItem._id));
+        if (serverItem._ts) {
+          if (!maxTs || this.compareTimestamps(serverItem._ts, maxTs) > 0) {
+            maxTs = serverItem._ts;
+          }
         }
-      }
-      if (localItem) {
-        if (dirtyChange) {
-          conflictsResolved++;
-          const resolved = this.resolveCollectionConflict(collectionName, config, localItem, serverItem, "sync");
-          dexieBatch.push(resolved);
-          if (!resolved._deleted) {
-            inMemSaveBatch.push(resolved);
+        if (localItem) {
+          if (dirtyChange) {
+            conflictsResolved++;
+            const resolved = this.resolveCollectionConflict(collectionName, config, localItem, serverItem, "sync");
+            dexieBatch.push(resolved);
+            if (!resolved._deleted && !resolved._archived) {
+              inMemSaveBatch.push(resolved);
+            } else {
+              inMemDeleteIds.push(serverItem._id);
+            }
           } else {
-            inMemDeleteIds.push(serverItem._id);
+            dexieBatch.push(serverItem);
+            if (!serverItem._deleted && !serverItem._archived) {
+              inMemSaveBatch.push(serverItem);
+            } 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);
           }
         }
-      } else {
-        dexieBatch.push(serverItem);
-        if (!serverItem._deleted) {
-          inMemSaveBatch.push(serverItem);
-        }
       }
-    }
-    if (dexieBatch.length > 0) {
-      await this.dexieDb.saveMany(collectionName, dexieBatch);
-    }
-    if (inMemSaveBatch.length > 0) {
-      this.deps.writeToInMemBatch(collectionName, inMemSaveBatch, "upsert");
-    }
-    if (inMemDeleteIds.length > 0) {
-      this.deps.writeToInMemBatch(collectionName, inMemDeleteIds.map((id) => ({ _id: id })), "delete");
+      if (dexieBatch.length > 0) {
+        await this.dexieDb.saveMany(collectionName, dexieBatch);
+      }
+      if (inMemSaveBatch.length > 0) {
+        this.deps.writeToInMemBatch(collectionName, inMemSaveBatch, "upsert");
+      }
+      if (inMemDeleteIds.length > 0) {
+        this.deps.writeToInMemBatch(collectionName, inMemDeleteIds.map((id) => ({ _id: id })), "delete");
+      }
+      for (const id of chunkIds) {
+        allUpdatedIds.push(String(id));
+      }
     }
     if (maxTs) {
       await this.dexieDb.setSyncMeta(collectionName, maxTs);
@@ -2376,8 +2493,7 @@ class SyncEngine {
         lastSyncTs: maxTs
       });
     }
-    const updatedIds = serverIds.map((id) => String(id));
-    return { conflictsResolved, maxTs, updatedIds };
+    return { conflictsResolved, maxTs, updatedIds: allUpdatedIds };
   }
   compareTimestamps(a, b) {
     const aT = typeof a === "object" && "t" in a ? a.t : 0;
@@ -2597,12 +2713,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");
       }
     }
@@ -2628,7 +2744,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;
@@ -2640,7 +2756,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 {
@@ -2648,7 +2764,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");
@@ -2918,6 +3034,8 @@ class SyncedDb {
   unsubscribeServerUpdates;
   cleanupNotifierCallbacks;
   beforeUnloadHandler;
+  defaultReturnDeleted;
+  defaultReturnArchived;
   onSync;
   onConflictResolved;
   onWsNotification;
@@ -2932,6 +3050,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;
@@ -3140,8 +3260,15 @@ 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);
-      this.inMemManager.initCollection(name, activeData);
+      let writeIdx = 0;
+      for (let i = 0;i < data.length; i++) {
+        const item = data[i];
+        if (!item._deleted && !item._archived) {
+          data[writeIdx++] = item;
+        }
+      }
+      data.length = writeIdx;
+      this.inMemManager.initCollection(name, data);
       const meta = await this.dexieDb.getSyncMeta(name);
       if (meta) {
         this.syncMetaCache.set(name, meta);
@@ -3231,41 +3358,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);
@@ -3274,6 +3479,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);
@@ -3288,7 +3554,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;
@@ -3308,7 +3574,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 };
@@ -3588,6 +3854,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`);
@@ -5949,7 +6225,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;
@@ -6493,9 +6769,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.
@@ -33,6 +33,8 @@ export declare class SyncedDb implements I_SyncedDb {
     private unsubscribeServerUpdates?;
     private cleanupNotifierCallbacks?;
     private beforeUnloadHandler?;
+    private readonly defaultReturnDeleted;
+    private readonly defaultReturnArchived;
     private readonly onSync?;
     private readonly onConflictResolved?;
     private readonly onWsNotification?;
@@ -52,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>;
@@ -96,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,15 @@ 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[];
+    }>;
+    /** Max items to process per batch in processIncomingServerData */
+    private static readonly SYNC_BATCH_SIZE;
     private processIncomingServerData;
     private compareTimestamps;
     private resolveCollectionConflict;

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";
@@ -206,7 +206,7 @@ export interface CollectionSyncStats {
     receivedCount: number;
     /** Number of dirty items sent to server for this collection */
     sentCount: number;
-    /** The actual items received from server (for debugging/logging) */
+    /** @deprecated Use receivedCount instead. Will be empty array in future streaming mode. */
     receivedItems: LocalDbEntity[];
 }
 /**
@@ -351,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
@@ -436,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.69",
+  "version": "0.1.72",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",