cry-synced-db-client 0.1.151 → 0.1.155

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Versions
 
+## 0.1.154
+
+### `evictOnWake` config
+
+New optional field on `SyncedDbConfig`. When set to `true`, scope-exit
+eviction runs on every wake event (`sync()` whose `calledFrom` starts
+with `'wake-sync:'`), bypassing the `evictStaleRecordsEveryHrs` interval
+gate. The eviction is bundled into the wake sync's `findNewerManyStream`
+call — single RTT, same shape as existing 8h auto-eviction.
+
+Use with `scopeExitLookbehindMs` to ensure scope-exit detection covers
+records mutated within the lookbehind window. Together they guarantee
+cross-device close-outs become visible on the very next wake instead of
+waiting up to `evictStaleRecordsEveryHrs`.
+
+`evictStaleRecordsEveryHrs` continues to gate non-wake syncs (interval
+auto-sync ticks, manual `sync()` calls without `'wake-sync:*'` prefix).
+
+Default: `false`.
+
+## 0.1.153
+
+### `scopeExitLookbehindMs` config
+
+New optional field on `SyncedDbConfig`. When set (> 0), server-assisted
+scope-exit detection (auto-eviction bundled with `sync()`, plus the batch
+`evictOutOfScopeRecordsAll` path) uses `_ts > now - scopeExitLookbehindMs`
+instead of `_ts > lastSyncTs` for the `findNewerMany` spec timestamp.
+
+Why: with the legacy `lastSyncTs` cursor, the scope-exit query
+`{$nor:[positiveQuery], _id:{$in:chunk}, _ts > lastSyncTs}` excluded any
+record whose server-side `_ts` predates the device's `lastSyncTs`. Typical
+cross-device close-out scenario (device A closes a record while device B
+is offline; B comes back online and syncs many newer records, advancing
+`lastSyncTs` past the close-out's `_ts`) → server returned 0 scope-exit
+candidates forever. Per-call override via
+`evictOutOfScopeRecords({outOfWindowLookbehindMs})` is unchanged and now
+also falls back to `scopeExitLookbehindMs` when no per-call value is given.
+
+Default: `0` (legacy behavior). Recommended for multi-device deployments:
+`3 * 24 * 3600 * 1000` (3 days). Combine with periodic
+`refreshDatabaseFromServer()` (e.g. when `lastInitialSync()` exceeds the
+same threshold) to also cover scope-exit events older than the lookbehind
+window.
+
 ## Unreleased
 
 ### `SyncSource` flag in `I_InMemDb.saveMany` / `deleteManyByIds`

package/dist/index.js

@@ -273,6 +273,183 @@ function applyQueryOpts(items, opts) {
   return result;
 }
 
+// src/utils/computeDiff.ts
+function isObjectIdLike(v) {
+  return !!(v && typeof v === "object" && (v._bsontype === "ObjectId" || v._bsontype === "ObjectID") && typeof v.toString === "function");
+}
+function isPlainObject(v) {
+  if (v === null || typeof v !== "object") return false;
+  if (Array.isArray(v)) return false;
+  if (v instanceof Date) return false;
+  if (isObjectIdLike(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function deepEquals(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (a === void 0 || b === void 0) return false;
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+  if (isObjectIdLike(a) && isObjectIdLike(b)) {
+    return String(a) === String(b);
+  }
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEquals(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
+    if (!deepEquals(a[k], b[k])) return false;
+  }
+  return true;
+}
+function allElementsHaveId(arr) {
+  if (arr.length === 0) return false;
+  for (const e of arr) {
+    if (!e || typeof e !== "object") return false;
+    if (e._id == null) return false;
+  }
+  return true;
+}
+function sameIdSequence(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (String(a[i]._id) !== String(b[i]._id)) return false;
+  }
+  return true;
+}
+function computeArrayDiff(existingArr, updateArr, basePath, diff) {
+  if (existingArr.length === 0) {
+    if (updateArr.length > 0) diff[basePath] = updateArr;
+    return;
+  }
+  if (!allElementsHaveId(existingArr) || !allElementsHaveId(updateArr)) {
+    if (!deepEquals(existingArr, updateArr)) {
+      diff[basePath] = updateArr;
+    }
+    return;
+  }
+  if (!sameIdSequence(existingArr, updateArr)) {
+    diff[basePath] = updateArr;
+    return;
+  }
+  for (let i = 0; i < updateArr.length; i++) {
+    computeDiffInto(
+      existingArr[i],
+      updateArr[i],
+      `${basePath}.${i}`,
+      diff
+    );
+  }
+}
+function computeDiffInto(existing, update, basePath, diff) {
+  if (deepEquals(existing, update)) return;
+  if (update === null || update === void 0 || typeof update !== "object" || update instanceof Date || isObjectIdLike(update)) {
+    diff[basePath] = update;
+    return;
+  }
+  if (existing === null || existing === void 0 || typeof existing !== "object" || existing instanceof Date || isObjectIdLike(existing)) {
+    diff[basePath] = update;
+    return;
+  }
+  if (Array.isArray(update) !== Array.isArray(existing)) {
+    diff[basePath] = update;
+    return;
+  }
+  if (Array.isArray(update)) {
+    computeArrayDiff(existing, update, basePath, diff);
+    return;
+  }
+  if (!isPlainObject(update) || !isPlainObject(existing)) {
+    diff[basePath] = update;
+    return;
+  }
+  for (const key of Object.keys(update)) {
+    const childPath = basePath ? `${basePath}.${key}` : key;
+    computeDiffInto(existing[key], update[key], childPath, diff);
+  }
+}
+function computeDiff(existing, update) {
+  const diff = {};
+  if (!update || typeof update !== "object") return diff;
+  if (existing === null || existing === void 0) {
+    return __spreadValues({}, update);
+  }
+  for (const key of Object.keys(update)) {
+    computeDiffInto(existing[key], update[key], key, diff);
+  }
+  return diff;
+}
+function isDescendantOrEqual(path, candidate) {
+  if (path === candidate) return true;
+  return path.startsWith(candidate + ".");
+}
+function setByPath(target2, path, value) {
+  if (target2 === null || target2 === void 0) return false;
+  const parts = path.split(".");
+  let current = target2;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    const idx = /^\d+$/.test(part) ? Number(part) : null;
+    let next;
+    if (Array.isArray(current) && idx !== null) {
+      next = current[idx];
+    } else if (typeof current === "object") {
+      next = current[part];
+    } else {
+      return false;
+    }
+    if (next === null || next === void 0) return false;
+    current = next;
+  }
+  const last = parts[parts.length - 1];
+  const lastIdx = /^\d+$/.test(last) ? Number(last) : null;
+  if (Array.isArray(current) && lastIdx !== null) {
+    current[lastIdx] = value;
+  } else if (typeof current === "object") {
+    current[last] = value;
+  } else {
+    return false;
+  }
+  return true;
+}
+function mergeDirtyPath(accumulated, newPath, newValue) {
+  for (const existingKey of Object.keys(accumulated)) {
+    if (existingKey === newPath) continue;
+    if (isDescendantOrEqual(newPath, existingKey)) {
+      const relativePath = newPath.substring(existingKey.length + 1);
+      const ok = setByPath(accumulated[existingKey], relativePath, newValue);
+      if (ok) return;
+      break;
+    }
+  }
+  const toDelete = [];
+  for (const existingKey of Object.keys(accumulated)) {
+    if (existingKey === newPath) continue;
+    if (isDescendantOrEqual(existingKey, newPath)) {
+      toDelete.push(existingKey);
+    }
+  }
+  for (const k of toDelete) delete accumulated[k];
+  accumulated[newPath] = newValue;
+}
+function mergeDirtyChanges(accumulated, newChanges) {
+  for (const path of Object.keys(newChanges)) {
+    mergeDirtyPath(accumulated, path, newChanges[path]);
+  }
+}
+
 // src/db/managers/InMemManager.ts
 var InMemManager = class {
   constructor(config) {
@@ -1303,7 +1480,7 @@ var CustomTransformerRegistry = class {
 var getType = (payload) => Object.prototype.toString.call(payload).slice(8, -1);
 var isUndefined = (payload) => typeof payload === "undefined";
 var isNull = (payload) => payload === null;
-var isPlainObject = (payload) => {
+var isPlainObject2 = (payload) => {
   if (typeof payload !== "object" || payload === null)
     return false;
   if (payload === Object.prototype)
@@ -1312,7 +1489,7 @@ var isPlainObject = (payload) => {
     return true;
   return Object.getPrototypeOf(payload) === Object.prototype;
 };
-var isEmptyObject = (payload) => isPlainObject(payload) && Object.keys(payload).length === 0;
+var isEmptyObject = (payload) => isPlainObject2(payload) && Object.keys(payload).length === 0;
 var isArray = (payload) => Array.isArray(payload);
 var isString = (payload) => typeof payload === "string";
 var isNumber = (payload) => typeof payload === "number" && !isNaN(payload);
@@ -1625,7 +1802,7 @@ var setDeep = (object, path, mapper) => {
     if (isArray(parent)) {
       const index = +key;
       parent = parent[index];
-    } else if (isPlainObject(parent)) {
+    } else if (isPlainObject2(parent)) {
       parent = parent[key];
     } else if (isSet(parent)) {
       const row = +key;
@@ -1651,7 +1828,7 @@ var setDeep = (object, path, mapper) => {
   const lastKey = path[path.length - 1];
   if (isArray(parent)) {
     parent[+lastKey] = mapper(parent[+lastKey]);
-  } else if (isPlainObject(parent)) {
+  } else if (isPlainObject2(parent)) {
     parent[lastKey] = mapper(parent[lastKey]);
   }
   if (isSet(parent)) {
@@ -1736,7 +1913,7 @@ function applyReferentialEqualityAnnotations(plain, annotations, version) {
   }
   return plain;
 }
-var isDeep = (object, superJson) => isPlainObject(object) || isArray(object) || isMap(object) || isSet(object) || isError(object) || isInstanceOfRegisteredClass(object, superJson);
+var isDeep = (object, superJson) => isPlainObject2(object) || isArray(object) || isMap(object) || isSet(object) || isError(object) || isInstanceOfRegisteredClass(object, superJson);
 function addIdentity(object, path, identities) {
   const existingSet = identities.get(object);
   if (existingSet) {
@@ -1814,7 +1991,7 @@ var walker = (object, identities, superJson, dedupe, path = [], objectsInThisPat
     transformedValue[index] = recursiveResult.transformedValue;
     if (isArray(recursiveResult.annotations)) {
       innerAnnotations[escapeKey(index)] = recursiveResult.annotations;
-    } else if (isPlainObject(recursiveResult.annotations)) {
+    } else if (isPlainObject2(recursiveResult.annotations)) {
       forEach(recursiveResult.annotations, (tree, key) => {
         innerAnnotations[escapeKey(index) + "." + key] = tree;
       });
@@ -1844,7 +2021,7 @@ function isArray2(payload) {
 }
 
 // node_modules/is-what/dist/isPlainObject.js
-function isPlainObject2(payload) {
+function isPlainObject3(payload) {
   if (getType2(payload) !== "Object")
     return false;
   const prototype = Object.getPrototypeOf(payload);
@@ -1869,7 +2046,7 @@ function copy(target2, options = {}) {
   if (isArray2(target2)) {
     return target2.map((item) => copy(item, options));
   }
-  if (!isPlainObject2(target2)) {
+  if (!isPlainObject3(target2)) {
     return target2;
   }
   const props = Object.getOwnPropertyNames(target2);
@@ -2384,7 +2561,7 @@ function mergeObjects(local, external) {
     }
     if (Array.isArray(localValue) && Array.isArray(externalValue)) {
       result[key] = mergeArrays(localValue, externalValue);
-    } else if (isPlainObject3(localValue) && isPlainObject3(externalValue)) {
+    } else if (isPlainObject4(localValue) && isPlainObject4(externalValue)) {
       result[key] = mergeObjects(localValue, externalValue);
     } else if (serverWinsOnConflict) {
       result[key] = externalValue;
@@ -2403,7 +2580,7 @@ function mergeArrays(local, external) {
     for (const item of external) set2.add(item);
     return Array.from(set2);
   }
-  if (isPlainObject3(firstLocal) || isPlainObject3(firstExternal)) {
+  if (isPlainObject4(firstLocal) || isPlainObject4(firstExternal)) {
     return mergeObjectArrays(local, external);
   }
   const set = new Set(local);
@@ -2437,7 +2614,7 @@ function mergeObjectArrays(local, external) {
   }
   return result;
 }
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
 }
 
@@ -3549,7 +3726,7 @@ var _SyncedDb = class _SyncedDb {
     this.syncOnlyCollections = null;
     // Sync metadata cache
     this.syncMetaCache = /* @__PURE__ */ new Map();
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
     this.tenant = config.tenant;
     this.dexieDb = config.dexieDb;
     this.inMemDb = config.inMemDb;
@@ -3576,13 +3753,15 @@ var _SyncedDb = class _SyncedDb {
     this.onEvictionStart = config.onEvictionStart;
     this.onEviction = config.onEviction;
     this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
+    this.scopeExitLookbehindMs = (_f = config.scopeExitLookbehindMs) != null ? _f : 0;
+    this.evictOnWake = (_g = config.evictOnWake) != null ? _g : false;
     for (const col of config.collections) {
       this.collections.set(col.name, col);
     }
     this.inMemManager = new InMemManager({
       inMemDb: this.inMemDb,
       collections: this.collections,
-      useObjectMetadata: (_f = config.useObjectMetadata) != null ? _f : false
+      useObjectMetadata: (_h = config.useObjectMetadata) != null ? _h : false
     });
     this.leaderElection = new LeaderElectionManager({
       tenant: this.tenant,
@@ -3617,7 +3796,7 @@ var _SyncedDb = class _SyncedDb {
       tenant: this.tenant,
       instanceId: this.syncedDbInstanceId,
       windowId,
-      debounceMs: (_g = config.crossTabSyncDebounceMs) != null ? _g : 100,
+      debounceMs: (_i = config.crossTabSyncDebounceMs) != null ? _i : 100,
       callbacks: {
         onCrossTabSync: config.onCrossTabSync,
         onInfrastructureError: config.onInfrastructureError ? (type, message, error) => {
@@ -3643,8 +3822,8 @@ var _SyncedDb = class _SyncedDb {
     });
     this.connectionManager = new ConnectionManager({
       restInterface: this.restInterface,
-      restTimeoutMs: (_h = config.restTimeoutMs) != null ? _h : 9e4,
-      syncTimeoutMs: (_i = config.syncTimeoutMs) != null ? _i : 12e4,
+      restTimeoutMs: (_j = config.restTimeoutMs) != null ? _j : 9e4,
+      syncTimeoutMs: (_k = config.syncTimeoutMs) != null ? _k : 12e4,
       autoSyncIntervalMs: config.autoSyncIntervalMs,
       onlineRetryIntervalMs: config.onlineRetryIntervalMs,
       callbacks: {
@@ -3671,8 +3850,8 @@ var _SyncedDb = class _SyncedDb {
     });
     this.pendingChanges = new PendingChangesManager({
       tenant: this.tenant,
-      debounceDexieWritesMs: (_j = config.debounceDexieWritesMs) != null ? _j : 500,
-      debounceRestWritesMs: (_k = config.debounceRestWritesMs) != null ? _k : 100,
+      debounceDexieWritesMs: (_l = config.debounceDexieWritesMs) != null ? _l : 500,
+      debounceRestWritesMs: (_m = config.debounceRestWritesMs) != null ? _m : 100,
       callbacks: {
         onDexieWriteRequest: config.onDexieWriteRequest,
         onDexieWriteResult: config.onDexieWriteResult,
@@ -3749,8 +3928,8 @@ var _SyncedDb = class _SyncedDb {
     });
     if (config.wakeSyncEnabled) {
       this.wakeSync = new WakeSyncManager({
-        gapThresholdMs: (_l = config.wakeSyncGapThresholdMs) != null ? _l : 1e4,
-        debounceMs: (_m = config.wakeSyncDebounceMs) != null ? _m : 2e3,
+        gapThresholdMs: (_n = config.wakeSyncGapThresholdMs) != null ? _n : 1e4,
+        debounceMs: (_o = config.wakeSyncDebounceMs) != null ? _o : 2e3,
         callbacks: {
           onWakeSync: config.onWakeSync
         },
@@ -3765,7 +3944,7 @@ var _SyncedDb = class _SyncedDb {
     }
     if (config.networkStatusEnabled) {
       this.networkStatus = new NetworkStatusManager({
-        debounceMs: (_n = config.networkStatusDebounceMs) != null ? _n : 100,
+        debounceMs: (_p = config.networkStatusDebounceMs) != null ? _p : 100,
         callbacks: {
           onBrowserNetworkChange: config.onBrowserNetworkChange,
           onBrowserOnline: config.onBrowserOnline,
@@ -4327,10 +4506,12 @@ var _SyncedDb = class _SyncedDb {
         `SyncedDb.save: Object ${String(id)} not found in ${collection}, creating new`
       );
     }
+    const fullChanges = __spreadProps(__spreadValues({}, update), { _lastUpdaterId: this.updaterId });
+    const diff = computeDiff(existing, fullChanges);
     await this.dexieDb.addDirtyChange(
       collection,
       id,
-      __spreadProps(__spreadValues({}, update), { _lastUpdaterId: this.updaterId }),
+      diff,
       { _ts: existing == null ? void 0 : existing._ts, _rev: existing == null ? void 0 : existing._rev }
     );
     const newData = __spreadProps(__spreadValues({}, update), {
@@ -4534,7 +4715,7 @@ var _SyncedDb = class _SyncedDb {
       this.crossTabSync.startServerSync();
       let evictionPlan;
       let evictionServerFailed = false;
-      if (await this._isAutoEvictionDue()) {
+      if (await this._isAutoEvictionDue(calledFrom)) {
         try {
           evictionPlan = await this._collectScopeExitPlan("auto");
         } catch (err) {
@@ -4850,11 +5031,12 @@ var _SyncedDb = class _SyncedDb {
     let serverEvictedCount = 0;
     if (serverAssisted && serverCandidateIds.length > 0) {
       let scopeExitTimestamp;
-      const lookbehindMs = opts == null ? void 0 : opts.outOfWindowLookbehindMs;
-      if (lookbehindMs != null && lookbehindMs > 0) {
+      const callerLookbehindMs = opts == null ? void 0 : opts.outOfWindowLookbehindMs;
+      const effectiveLookbehindMs = callerLookbehindMs != null && callerLookbehindMs > 0 ? callerLookbehindMs : this.scopeExitLookbehindMs;
+      if (effectiveLookbehindMs > 0) {
         scopeExitTimestamp = Math.max(
           0,
-          Math.floor((Date.now() - lookbehindMs) / 1e3)
+          Math.floor((Date.now() - effectiveLookbehindMs) / 1e3)
         );
       } else {
         scopeExitTimestamp = (_d = (_c = this.syncMetaCache.get(collection)) == null ? void 0 : _c.lastSyncTs) != null ? _d : 0;
@@ -5010,7 +5192,7 @@ var _SyncedDb = class _SyncedDb {
    * callback is a reliable lifecycle marker.
    */
   async _collectScopeExitPlan(trigger) {
-    var _a, _b, _c;
+    var _a;
     const startTime = Date.now();
     const eligible = [];
     for (const [name, config] of this.collections) {
@@ -5060,7 +5242,7 @@ var _SyncedDb = class _SyncedDb {
         collection: name,
         config,
         query,
-        timestamp: (_c = (_b = this.syncMetaCache.get(name)) == null ? void 0 : _b.lastSyncTs) != null ? _c : 0,
+        timestamp: this._scopeExitTimestamp(name),
         evictIds,
         localEvictedCount: evictIds.length,
         serverEvictedCount: 0,
@@ -5168,14 +5350,44 @@ var _SyncedDb = class _SyncedDb {
     this.safeCallback(this.onEviction, info);
     return info;
   }
+  /**
+   * Compute the `timestamp` value used in server-assisted scope-exit
+   * `findNewerMany` specs for a given collection. Honors the global
+   * `scopeExitLookbehindMs` config: when > 0, the scope-exit query
+   * uses `_ts > now - lookbehindMs`; otherwise falls back to the
+   * collection's lastSyncTs cursor (legacy behavior).
+   *
+   * Per-call override (`evictOutOfScopeRecords({outOfWindowLookbehindMs})`)
+   * is computed at the call site — this helper covers the auto-eviction
+   * path and `evictOutOfScopeRecordsAll`.
+   */
+  _scopeExitTimestamp(collection) {
+    var _a, _b;
+    if (this.scopeExitLookbehindMs > 0) {
+      return Math.max(
+        0,
+        Math.floor((Date.now() - this.scopeExitLookbehindMs) / 1e3)
+      );
+    }
+    return (_b = (_a = this.syncMetaCache.get(collection)) == null ? void 0 : _a.lastSyncTs) != null ? _b : 0;
+  }
   /**
    * Whether auto-eviction is due to run on the next sync. Mirrors the
    * gating logic of the old `maybeAutoEvict` (interval check + persisted
    * `__lastEviction` cursor) but split out so `sync()` can pre-compute
    * the eviction plan BEFORE issuing the streamed `findNewerMany` —
    * letting scope-exit specs ride along on the same call.
+   *
+   * `calledFrom` is honored when `evictOnWake` is true: any sync whose
+   * `calledFrom` starts with `'wake-sync:'` forces eviction regardless
+   * of the `evictStaleRecordsEveryHrs` interval gate. This ensures
+   * cross-device scope-exit records become visible on the very next
+   * wake instead of waiting up to the configured interval.
    */
-  async _isAutoEvictionDue() {
+  async _isAutoEvictionDue(calledFrom) {
+    if (this.evictOnWake && (calledFrom == null ? void 0 : calledFrom.startsWith("wake-sync:"))) {
+      return true;
+    }
     if (this.evictStaleRecordsEveryHrs <= 0) return false;
     const intervalMs = this.evictStaleRecordsEveryHrs * 36e5;
     if (!this._lastEvictionDate) {
@@ -5656,7 +5868,7 @@ var DexieDb = class extends Dexie {
     const existing = await this.dirtyChanges.get([collection, stringId]);
     const now = Date.now();
     if (existing) {
-      Object.assign(existing.changes, changes);
+      mergeDirtyChanges(existing.changes, changes);
       existing.updatedAt = now;
       await this.dirtyChanges.put(existing);
     } else {
@@ -5684,7 +5896,7 @@ var DexieDb = class extends Dexie {
       const stringId = this.idToString(changeItem.id);
       const existing = existingEntries[i];
       if (existing) {
-        Object.assign(existing.changes, changeItem.changes);
+        mergeDirtyChanges(existing.changes, changeItem.changes);
         existing.updatedAt = now;
         toWrite.push(existing);
       } else {

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

@@ -53,6 +53,8 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onEvictionStart?;
     private readonly onEviction?;
     private readonly evictStaleRecordsEveryHrs;
+    private readonly scopeExitLookbehindMs;
+    private readonly evictOnWake;
     private _lastEvictionDate?;
     constructor(config: SyncedDbConfig);
     getInstanceId(): string;
@@ -295,12 +297,30 @@ export declare class SyncedDb implements I_SyncedDb {
      * info and still fires the callback so consumers see a lifecycle event.
      */
     private _applyScopeExitPlan;
+    /**
+     * Compute the `timestamp` value used in server-assisted scope-exit
+     * `findNewerMany` specs for a given collection. Honors the global
+     * `scopeExitLookbehindMs` config: when > 0, the scope-exit query
+     * uses `_ts > now - lookbehindMs`; otherwise falls back to the
+     * collection's lastSyncTs cursor (legacy behavior).
+     *
+     * Per-call override (`evictOutOfScopeRecords({outOfWindowLookbehindMs})`)
+     * is computed at the call site — this helper covers the auto-eviction
+     * path and `evictOutOfScopeRecordsAll`.
+     */
+    private _scopeExitTimestamp;
     /**
      * Whether auto-eviction is due to run on the next sync. Mirrors the
      * gating logic of the old `maybeAutoEvict` (interval check + persisted
      * `__lastEviction` cursor) but split out so `sync()` can pre-compute
      * the eviction plan BEFORE issuing the streamed `findNewerMany` —
      * letting scope-exit specs ride along on the same call.
+     *
+     * `calledFrom` is honored when `evictOnWake` is true: any sync whose
+     * `calledFrom` starts with `'wake-sync:'` forces eviction regardless
+     * of the `evictStaleRecordsEveryHrs` interval gate. This ensures
+     * cross-device scope-exit records become visible on the very next
+     * wake instead of waiting up to the configured interval.
      */
     private _isAutoEvictionDue;
     /**

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

@@ -550,6 +550,39 @@ export interface SyncedDbConfig {
      * Default: 0 (disabled).
      */
     evictStaleRecordsEveryHrs?: number;
+    /**
+     * Default lookbehind window (ms) for server-assisted scope-exit detection
+     * in auto-eviction (`sync()` bundled) and `evictOutOfScopeRecordsAll`.
+     * When set (> 0), the scope-exit query uses `_ts > now - lookbehindMs`
+     * instead of `_ts > lastSyncTs`. This catches records whose server-side
+     * `_ts` predates `lastSyncTs` but still fail `$nor [positiveQuery]`
+     * server-side (typical cross-device close-out scenario where the local
+     * client was offline at the moment of mutation and findNewer's positive
+     * query never re-shipped the post-mutation row).
+     *
+     * Per-call override remains via `evictOutOfScopeRecords({outOfWindowLookbehindMs})`.
+     *
+     * Default: 0 (= use lastSyncTs cursor — current behavior).
+     * Recommended for multi-device deployments: 3 * 24 * 3600 * 1000 (3 days).
+     */
+    scopeExitLookbehindMs?: number;
+    /**
+     * Force scope-exit eviction on every wake event (`calledFrom` starts
+     * with `'wake-sync:'`), bypassing the `evictStaleRecordsEveryHrs`
+     * interval gate. Eviction is bundled into the wake sync's
+     * `findNewerManyStream` call (single RTT, same as positive sync).
+     *
+     * Combine with `scopeExitLookbehindMs` so the scope-exit query covers
+     * records mutated within the lookbehind window — guarantees that
+     * cross-device close-outs become visible to the local cache on the
+     * very next wake instead of waiting up to `evictStaleRecordsEveryHrs`.
+     *
+     * `evictStaleRecordsEveryHrs` still gates non-wake syncs (interval
+     * sync, manual `sync()` triggers without `'wake-sync:*'` prefix).
+     *
+     * Default: false.
+     */
+    evictOnWake?: boolean;
     /**
      * Callback fired before each eviction run begins, after the eligible
      * collection list has been resolved. Useful as a debug breadcrumb to

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

@@ -0,0 +1,76 @@
+/**
+ * computeDiff — produces minimal MongoDB-style dot-notation paths
+ * representing the actual differences between `existing` and `update`.
+ *
+ * PURPOSE: Solves the "stale array upload" bug where a save() call
+ * with a full nested array captures unchanged fields into the dirty
+ * change. When the device later uploads, those unchanged fields
+ * overwrite concurrent edits made by other devices.
+ *
+ * INVARIANT: applyDiff(existing, computeDiff(existing, update)) deep-equals
+ * the merged result of `existing` ⊔ `update` (where update wins on conflicts,
+ * and missing keys in update preserve existing values).
+ *
+ * STRATEGY:
+ * - Primitives, Date, ObjectId: emit single path if value differs
+ * - Plain objects: recurse, accumulating paths
+ * - Arrays of objects with _id (same composition + order): element-wise diff
+ * - Arrays with composition or order changes: full replace at array path
+ * - Arrays of primitives or mixed types: full replace
+ *
+ * MongoDB native supports dot-notation in $set, so output paths can be
+ * passed directly to the server without protocol changes.
+ */
+/** Deep equality for values that may include Date, ObjectId, plain objects, arrays. */
+export declare function deepEquals(a: any, b: any): boolean;
+/**
+ * Compute the minimal set of MongoDB dot-notation $set paths
+ * that transform `existing` into `update` (only for keys present in `update`).
+ *
+ * @returns Record where keys are dot-notation paths and values are new values.
+ *   Empty object means no changes.
+ *
+ * @example
+ * existing = { koraki: [{ _id: "k1", diag: "old", ter: "x" }] }
+ * update   = { koraki: [{ _id: "k1", diag: "new", ter: "x" }] }
+ * → { "koraki.0.diag": "new" }
+ *
+ * @example
+ * existing = { koraki: [{ _id: "k1" }] }
+ * update   = { koraki: [{ _id: "k1" }, { _id: "k2", diag: "x" }] }
+ * → { "koraki": [{ _id: "k1" }, { _id: "k2", diag: "x" }] }  // composition change
+ */
+export declare function computeDiff(existing: Record<string, any> | null | undefined, update: Record<string, any>): Record<string, any>;
+/**
+ * Detect whether a `changes` object uses dot-notation paths (new format)
+ * or top-level keys with full nested values (legacy format).
+ *
+ * Used to decide whether smart path-based merging applies, or fall back
+ * to legacy Object.assign accumulation.
+ */
+export declare function hasDotNotationPaths(changes: Record<string, any>): boolean;
+/**
+ * Smart-merge a single (path, value) entry into an accumulated dirty changes
+ * object. Resolves three relationships between the new path and existing keys:
+ *
+ * 1. New path is a DESCENDANT of an existing key (e.g. existing has "koraki",
+ *    new is "koraki.0.diag"): mutate the value inside the existing parent
+ *    rather than adding a conflicting child path.
+ *
+ * 2. New path is an ANCESTOR of existing keys (e.g. existing has "koraki.0.diag",
+ *    new is "koraki" with full array): remove the now-redundant descendants and
+ *    set the parent path. The new full value supersedes any field-level deltas.
+ *
+ * 3. New path is ORTHOGONAL to existing keys: simple set (Object.assign-equivalent).
+ *
+ * Used by DexieDb.addDirtyChange to accumulate changes across multiple save()
+ * calls without producing MongoDB-conflicting payloads (parent + child paths
+ * in same $set yields nondeterministic results).
+ */
+export declare function mergeDirtyPath(accumulated: Record<string, any>, newPath: string, newValue: any): void;
+/**
+ * Bulk-merge an entire changes object into the accumulator using path semantics.
+ * Order matters: paths are processed sequentially, so later entries can supersede
+ * earlier ones. This is acceptable because mergeDirtyPath is idempotent.
+ */
+export declare function mergeDirtyChanges(accumulated: Record<string, any>, newChanges: Record<string, any>): void;

package/package.json

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