cry-synced-db-client 0.1.137 → 0.1.139

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Versions
 
+## Unreleased
+
+- Add `refreshInBackground` `QueryOpts` option for `findById` / `findByIds`
+  - Stale-while-revalidate: cache-hit returns local result immediately and
+    triggers a background fetch that updates Dexie + in-mem through conflict
+    resolution (`processCollectionServerData`).
+  - Orthogonal to `referToServer` — does not change miss behaviour. With
+    defaults (`referToServer: true`) misses are still awaited; with
+    `referToServer: false` misses return `null` and bg fetch loads them async.
+  - Dedupes against `referToServer`: IDs fetched blockingly are NOT re-fetched
+    in the background (no double-round-trip).
+  - Noop when offline or on writeOnly collections.
+  - Ignored on `find` / `findOne` (use `referToServer` there).
+
 ## 0.1.136 (2026-04-20)
 
 - `DexieDb.saveMany` is now fail-safe:

package/dist/index.js

@@ -3110,6 +3110,7 @@ var ServerUpdateHandler = class {
         if (updates.length > 0) {
           const updateIds = updates.map((u) => u._id);
           const localItems = await this.dexieDb.getByIds(collectionName, updateIds);
+          const missingIds = [];
           for (let i = 0; i < updates.length; i++) {
             const deltaData = updates[i];
             const localItem = localItems[i];
@@ -3117,14 +3118,18 @@ var ServerUpdateHandler = class {
               await this.handleServerItemUpdate(collectionName, localItem, deltaData);
               updatedIds.push(String(deltaData._id));
             } else {
-              const fullItem = await this.restInterface.findById(
-                collectionName,
-                deltaData._id
-              );
-              if (fullItem) {
-                await this.handleServerItemInsert(collectionName, fullItem);
-                updatedIds.push(String(fullItem._id));
-              }
+              missingIds.push(deltaData._id);
+            }
+          }
+          if (missingIds.length > 0) {
+            const fullItems = await this.restInterface.findByIds(
+              collectionName,
+              missingIds
+            );
+            for (const fullItem of fullItems) {
+              if (!fullItem) continue;
+              await this.handleServerItemInsert(collectionName, fullItem);
+              updatedIds.push(String(fullItem._id));
             }
           }
         }
@@ -3926,7 +3931,12 @@ var _SyncedDb = class _SyncedDb {
     }
     if (!(opts == null ? void 0 : opts.returnDeleted) && !(opts == null ? void 0 : opts.returnArchived)) {
       const memItem = this.inMemDb.getById(collection, id);
-      if (memItem) return memItem;
+      if (memItem) {
+        if ((opts == null ? void 0 : opts.refreshInBackground) && this.isOnline()) {
+          this.refreshByIdsInBackground(collection, [id]);
+        }
+        return memItem;
+      }
     }
     if ((opts == null ? void 0 : opts.referToServer) !== false && this.isOnline()) {
       await this.ensureItemsAreLoaded(
@@ -3934,6 +3944,8 @@ var _SyncedDb = class _SyncedDb {
         [id],
         opts == null ? void 0 : opts.returnDeleted
       );
+    } else if ((opts == null ? void 0 : opts.refreshInBackground) && this.isOnline()) {
+      this.refreshByIdsInBackground(collection, [id]);
     }
     if (((opts == null ? void 0 : opts.returnDeleted) || (opts == null ? void 0 : opts.returnArchived)) && this.isOnline()) {
       try {
@@ -3970,12 +3982,28 @@ var _SyncedDb = class _SyncedDb {
       return this.writeOnlyFindByIds(collection, ids);
     }
     if (ids.length === 0) return [];
-    if ((opts == null ? void 0 : opts.referToServer) !== false && this.isOnline()) {
+    const wantsBgRefresh = (opts == null ? void 0 : opts.refreshInBackground) === true && this.isOnline();
+    const referToServerEnabled = (opts == null ? void 0 : opts.referToServer) !== false && this.isOnline();
+    let hitIds = null;
+    if (wantsBgRefresh && referToServerEnabled && !(opts == null ? void 0 : opts.returnDeleted) && !(opts == null ? void 0 : opts.returnArchived)) {
+      hitIds = [];
+      for (const id of ids) {
+        if (this.inMemDb.getById(collection, id)) {
+          hitIds.push(id);
+        }
+      }
+    }
+    if (referToServerEnabled) {
       await this.ensureItemsAreLoaded(
         collection,
         ids,
         opts == null ? void 0 : opts.returnDeleted
       );
+      if (wantsBgRefresh && hitIds && hitIds.length > 0) {
+        this.refreshByIdsInBackground(collection, hitIds);
+      }
+    } else if (wantsBgRefresh) {
+      this.refreshByIdsInBackground(collection, ids);
     }
     if (((opts == null ? void 0 : opts.returnDeleted) || (opts == null ? void 0 : opts.returnArchived)) && this.isOnline()) {
       try {
@@ -4130,6 +4158,27 @@ var _SyncedDb = class _SyncedDb {
       console.error(`referToServer failed for ${collection}:`, err);
     });
   }
+  /**
+   * Fire-and-forget background fetch of specific IDs from the server.
+   * Used by findById/findByIds when `refreshInBackground: true`.
+   * Always fetches from server (does not skip when items exist locally),
+   * and routes results through conflict resolution so local dirty changes
+   * are preserved.
+   */
+  refreshByIdsInBackground(collection, ids) {
+    var _a;
+    if (ids.length === 0) return;
+    if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) return;
+    this.connectionManager.withRestTimeout(
+      this.restInterface.findByIds(collection, ids),
+      "refreshInBackground"
+    ).then(async (serverItems) => {
+      if (!serverItems || serverItems.length === 0) return;
+      await this.syncEngine.processCollectionServerData(collection, serverItems);
+    }).catch((err) => {
+      console.error(`refreshInBackground failed for ${collection}:`, err);
+    });
+  }
   async ensureItemsAreLoaded(collection, ids, withDeleted) {
     var _a;
     this.assertCollection(collection);

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

@@ -131,6 +131,14 @@ export declare class SyncedDb implements I_SyncedDb {
      * Dexie + in-mem.
      */
     private referToServerSync;
+    /**
+     * Fire-and-forget background fetch of specific IDs from the server.
+     * Used by findById/findByIds when `refreshInBackground: true`.
+     * Always fetches from server (does not skip when items exist locally),
+     * and routes results through conflict resolution so local dirty changes
+     * are preserved.
+     */
+    private refreshByIdsInBackground;
     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>;

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

@@ -26,6 +26,21 @@ export type QueryOpts = Partial<{
      * pošlje query na server in posodobi in-mem z rezultati.
      */
     referToServer: boolean;
+    /**
+     * findById/findByIds (privzeto false): če je zapis lokalno prisoten,
+     * ga vrne takoj, nato pa v ozadju ponovno pridobi iste ID-je s serverja
+     * in jih posodobi v Dexie + in-mem (skozi konflikt resolucijo).
+     *
+     * Ortogonalno do `referToServer`:
+     * - hit + refreshInBackground: vrne lokalno + bg revalidacija
+     * - miss + referToServer:true: await fetch (privzeto); bg refresh NE sprozi
+     *   (misses so ravno bili pobrani — izognemo se duplikatu)
+     * - miss + referToServer:false + refreshInBackground:true: vrne null,
+     *   bg fetch prinese zapis asinhrono
+     *
+     * Ignorirano na find/findOne (tam uporabi `referToServer`).
+     */
+    refreshInBackground: 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

@@ -556,11 +556,19 @@ export interface I_SyncedDb {
     /**
      * Poišče objekt po ID-ju.
      * referToServer (privzeto true): če ne obstaja lokalno, prebere s serverja.
+     * refreshInBackground (privzeto false): lokalne zadetke vrne takoj, nato
+     *   jih v ozadju revalidira s serverja (Dexie + in-mem skozi konflikt
+     *   resolucijo). Ortogonalno do referToServer; ne povzroči duplikata
+     *   server klicev za missing ID-je.
      */
     findById<T extends DbEntity>(collection: string, id: Id, opts?: QueryOpts): Promise<T | null>;
     /**
      * Poišče objekte po ID-jih.
      * referToServer (privzeto true): manjkajoče prebere s serverja.
+     * refreshInBackground (privzeto false): lokalne zadetke vrne takoj, nato
+     *   jih v ozadju revalidira s serverja (Dexie + in-mem skozi konflikt
+     *   resolucijo). Ortogonalno do referToServer; ne povzroči duplikata
+     *   server klicev za missing ID-je.
      */
     findByIds<T extends DbEntity>(collection: string, ids: Id[], opts?: QueryOpts): Promise<T[]>;
     /**

package/package.json

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