cry-synced-db-client 0.1.195 → 0.1.196

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Versions
 
+## 0.1.196 (2026-06-10)
+
+### `refreshImmediately` — blokirni server-fetch z verzijsko primerjavo
+
+Nova opcija `refreshImmediately` na `QueryOpts` za `findById` in `findByIds`.
+Ko je `true` in smo online, vedno najprej blokirno pridobi podatke s serverja.
+Če je `_rev` na serverju višji od lokalnega v Dexie, posodobi Dexie + in-mem.
+Vrne novejši podatek (server če je bil novejši, sicer lokalni). Ob napaki
+serverja pade nazaj na lokalne podatke.
+
+Razlika od `referToServer`: `refreshImmediately` vedno kliče server (tudi če
+zapis obstaja lokalno), ne samo ob cache miss-u.
+Razlika od `refreshInBackground`: `refreshImmediately` je blokiren — počaka
+na odgovor serverja in vrne ažuriran podatek.
+
+Internal:
+- `_refreshImmediately()` — nova zasebna metoda: fetča s serverja, primerja
+  `_rev`, posodobi Dexie samo če server novejši; za iteme z dirty spremembami
+  delegira `processCollectionServerData`
+- `_isServerNewer()` — primerjava `_rev` vrednosti
+- `findById` / `findByIds` — zgodnja `refreshImmediately` pot pred in-mem
+  hitre poti
+
 ## 0.1.195 (2026-06-09)
 
 ### `ensureItemsAreLoaded` always fetches all IDs from server

package/dist/index.js

@@ -5488,6 +5488,22 @@ var _SyncedDb = class _SyncedDb {
     if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) {
       return this.writeOnlyFindById(collection, id);
     }
+    if ((opts == null ? void 0 : opts.refreshImmediately) && this.isOnline()) {
+      try {
+        await this._refreshImmediately(collection, [id]);
+      } catch (e) {
+      }
+      const item2 = await this.dexieDb.getById(collection, id);
+      if (!item2) return null;
+      if (!(opts == null ? void 0 : opts.returnDeleted) && item2._deleted) return null;
+      if (!(opts == null ? void 0 : opts.returnArchived) && item2._archived) return null;
+      let result2 = item2;
+      if (opts == null ? void 0 : opts.project) {
+        const [projected] = applyQueryOpts([result2], { project: opts.project });
+        result2 = projected;
+      }
+      return result2;
+    }
     if (!(opts == null ? void 0 : opts.returnDeleted) && !(opts == null ? void 0 : opts.returnArchived)) {
       const memItem = this.inMemDb.getById(collection, id);
       if (memItem) {
@@ -5542,6 +5558,21 @@ var _SyncedDb = class _SyncedDb {
       return this.writeOnlyFindByIds(collection, ids);
     }
     if (ids.length === 0) return [];
+    if ((opts == null ? void 0 : opts.refreshImmediately) && this.isOnline()) {
+      try {
+        await this._refreshImmediately(collection, ids);
+      } catch (e) {
+      }
+      const items2 = await this.dexieDb.getByIds(collection, ids);
+      const results2 = [];
+      for (const item of items2) {
+        if (!item) continue;
+        if (!(opts == null ? void 0 : opts.returnDeleted) && item._deleted) continue;
+        if (!(opts == null ? void 0 : opts.returnArchived) && item._archived) continue;
+        results2.push(item);
+      }
+      return applyQueryOpts(results2, opts);
+    }
     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;
@@ -5719,6 +5750,71 @@ var _SyncedDb = class _SyncedDb {
       networkError(`[SyncedDb] referToServer failed for ${collection}:`, err);
     });
   }
+  /**
+   * Blocking fetch of specific IDs from the server with version comparison.
+   * Used by findById/findByIds when `refreshImmediately: true`.
+   *
+   * Always fetches from server (never skips). For items WITHOUT pending
+   * dirty changes: compares `_rev` — only updates Dexie + inMem when the
+   * server `_rev` is strictly higher than the local `_rev`. For items WITH
+   * pending dirty changes: delegates to `processCollectionServerData` which
+   * runs full conflict resolution (server-wins on higher `_rev`, local fields
+   * not present on server are preserved).
+   */
+  async _refreshImmediately(collection, ids) {
+    if (ids.length === 0) return;
+    const serverItems = await this.connectionManager.withRestTimeout(
+      this.restInterface.findByIds(collection, ids),
+      "refreshImmediately"
+    );
+    if (!serverItems || serverItems.length === 0) return;
+    const serverById = /* @__PURE__ */ new Map();
+    for (const item of serverItems) {
+      serverById.set(String(item._id), item);
+    }
+    const localItems = await this.dexieDb.getByIds(collection, ids);
+    const dirtyMap = await this.dexieDb.getDirtyChangesBatch(collection, ids);
+    const toSaveDexie = [];
+    const toSaveInMem = [];
+    const dirtyServerItems = [];
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      const serverItem = serverById.get(id);
+      if (!serverItem) continue;
+      const localItem = localItems[i];
+      if (dirtyMap.has(id)) {
+        dirtyServerItems.push(serverItem);
+      } else if (!localItem) {
+        toSaveDexie.push(serverItem);
+        if (!serverItem._deleted && !serverItem._archived) {
+          toSaveInMem.push(serverItem);
+        }
+      } else if (this._isServerNewer(serverItem, localItem)) {
+        toSaveDexie.push(serverItem);
+        if (!serverItem._deleted && !serverItem._archived) {
+          toSaveInMem.push(serverItem);
+        }
+      }
+    }
+    if (toSaveDexie.length > 0) {
+      await this.dexieDb.saveMany(collection, toSaveDexie);
+    }
+    if (toSaveInMem.length > 0) {
+      this.inMemManager.writeBatch(collection, toSaveInMem, "upsert", { source: "incremental" });
+    }
+    if (dirtyServerItems.length > 0) {
+      await this.syncEngine.processCollectionServerData(collection, dirtyServerItems, { source: "incremental" });
+    }
+  }
+  /**
+   * Compare two items by `_rev` — returns true if `serverItem` has a
+   * strictly higher revision than `localItem`.
+   */
+  _isServerNewer(serverItem, localItem) {
+    const serverRev = typeof serverItem._rev === "number" ? serverItem._rev : 0;
+    const localRev = typeof localItem._rev === "number" ? localItem._rev : 0;
+    return serverRev > localRev;
+  }
   /**
    * Fire-and-forget background fetch of specific IDs from the server.
    * Used by findById/findByIds when `refreshInBackground: true`.

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

@@ -242,6 +242,23 @@ export declare class SyncedDb implements I_SyncedDb {
      * Dexie + in-mem.
      */
     private referToServerSync;
+    /**
+     * Blocking fetch of specific IDs from the server with version comparison.
+     * Used by findById/findByIds when `refreshImmediately: true`.
+     *
+     * Always fetches from server (never skips). For items WITHOUT pending
+     * dirty changes: compares `_rev` — only updates Dexie + inMem when the
+     * server `_rev` is strictly higher than the local `_rev`. For items WITH
+     * pending dirty changes: delegates to `processCollectionServerData` which
+     * runs full conflict resolution (server-wins on higher `_rev`, local fields
+     * not present on server are preserved).
+     */
+    private _refreshImmediately;
+    /**
+     * Compare two items by `_rev` — returns true if `serverItem` has a
+     * strictly higher revision than `localItem`.
+     */
+    private _isServerNewer;
     /**
      * Fire-and-forget background fetch of specific IDs from the server.
      * Used by findById/findByIds when `refreshInBackground: true`.

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

@@ -41,6 +41,22 @@ export type QueryOpts = Partial<{
      * Ignorirano na find/findOne (tam uporabi `referToServer`).
      */
     refreshInBackground: boolean;
+    /**
+     * findById/findByIds (privzeto false): če je true in smo online, vedno
+     * najprej blokirno pridobi podatek s serverja. Če je verzija na serverju
+     * novejša od verzije v Dexie (višji `_ts`), posodobi Dexie + in-mem
+     * skozi konflikt resolucijo. Vrne novejši podatek (server če je bil
+     * novejši, sicer lokalni). Ob napaki pri klicu na server pade nazaj
+     * na lokalne podatke.
+     *
+     * Razlika od `referToServer`: ta vedno pokliče server (tudi če zapis
+     * obstaja lokalno), ne samo ob cache miss-u.
+     * Razlika od `refreshInBackground`: ta je blokiren — počaka na odgovor
+     * serverja in vrne ažuriran podatek.
+     *
+     * Ignorirano na find/findOne.
+     */
+    refreshImmediately: 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

@@ -1091,6 +1091,10 @@ export interface I_SyncedDb {
      *   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.
+     * refreshImmediately (privzeto false): če je true in smo online, vedno
+     *   najprej blokirno pridobi podatek s serverja. Če je server verzija
+     *   novejša (višji `_ts`), posodobi Dexie + in-mem. Vrne novejši podatek.
+     *   Ob napaki serverja pade nazaj na lokalne podatke.
      *
      * Auto-registracija: če `collection` ni registrirana v runtime sync
      * configu, se avtomatsko doda kot **temporary** s queryjem
@@ -1107,6 +1111,10 @@ export interface I_SyncedDb {
      *   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.
+     * refreshImmediately (privzeto false): če je true in smo online, vedno
+     *   najprej blokirno pridobi podatke s serverja. Če je server verzija
+     *   novejša (višji `_ts`), posodobi Dexie + in-mem. Vrne novejše podatke.
+     *   Ob napaki serverja pade nazaj na lokalne podatke.
      *
      * Auto-registracija: enako kot `findById` — če `collection` ni v
      * runtime sync configu, se doda kot temporary s queryjem

package/package.json

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