cry-synced-db-client 0.1.188 → 0.1.189

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Versions
 
+## 0.1.189 (2026-05-15)
+
+### Periodic full-resync maintenance heartbeat
+
+New `SyncedDbConfig` options that guarantee a full server re-read at a
+configurable cadence — useful when long-running tabs accumulate
+server-side state drift (eviction window misses, race-ridden
+tombstones, missed WS-push notifications while the tab was throttled).
+
+```ts
+new SyncedDb({
+  // ...
+  forceFullResyncIfOlderThanDays: 7,   // threshold (off when undefined)
+  forceFullResyncCheckEveryHrs: 24,    // continuous re-check (init-only when undefined)
+  onForceFullResyncTriggered: (info) => {
+    // info: { reason: "init" | "timer", lastFullSyncDate?, daysSinceLastFullSync?, thresholdDays, timestamp }
+    syslog.info("force-full-resync", info);
+  },
+});
+```
+
+**What it does** — when `lastSuccessfulServerSync()` is older than the
+threshold (checked once at `init()` + continuously every
+`forceFullResyncCheckEveryHrs`):
+
+1. `onForceFullResyncTriggered` fires (idempotent — flag-gated, no
+   re-fire if a previous trigger is still pending).
+2. Internal `_pendingFullResync` flag is set.
+3. If `canSync()`, fires `sync("force-full-resync:<reason>")`.
+4. The consuming sync slot resets **every** collection's
+   `syncMeta.lastSyncTs` (Dexie + cache) just before `syncEngine.sync`
+   runs. Server returns the full dataset.
+5. Conflict resolution overwrites local rows record-by-record as the
+   stream lands. Bundled eviction sweeps records the server no longer
+   reports.
+6. On success the flag is cleared. On failure (offline, server error,
+   abort) the flag persists; the next sync slot retries.
+
+**Safety guarantees** — `_dirty_changes` and Dexie main rows are
+**never deleted** by this flow. The trigger only mutates cursors;
+conflict resolution + eviction handle row updates and out-of-scope
+removal as part of normal sync. A failed resync leaves the local
+cache exactly as it was. There is no window where Dexie is empty
+and the server response hasn't yet landed — fundamentally different
+from the legacy `refreshDatabaseFromServer()` which wipes Dexie
+before re-downloading.
+
+Implementation notes:
+
+- The check (`_checkForceFullResyncThreshold`) is cheap (memory + Date
+  math). The continuous timer runs for the SyncedDb's lifetime
+  (`init() → close()`); ticks during an in-flight sync no-op via
+  `syncLock`. The flag is boolean — multiple triggers between sync
+  slots collapse to one.
+- Records with `_lastFullSyncDate === undefined` (never synced) are
+  NOT considered stale — initial sync handles those.
+- Subset mode (`syncOnlyCollections !== null`) never sets
+  `__lastFullSync`, so the trigger never fires in that mode.
+- `dropDatabase()` clears `__lastFullSync`, restoring "never synced".
+
 ## 0.1.188 (2026-05-15)
 
 ### `clearDirty()` — manual dirty drain + `onBeforeDirtyClearAll` callback

package/dist/index.js

@@ -4456,6 +4456,7 @@ var _SyncedDb = class _SyncedDb {
     this.syncOnlyCollections = null;
     // Sync metadata cache
     this.syncMetaCache = /* @__PURE__ */ new Map();
+    this._pendingFullResync = false;
     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;
@@ -4485,6 +4486,9 @@ var _SyncedDb = class _SyncedDb {
     this.onSaveIdMismatch = config.onSaveIdMismatch;
     this.onUploadSkip = config.onUploadSkip;
     this.onBeforeDirtyClearAll = config.onBeforeDirtyClearAll;
+    this.forceFullResyncIfOlderThanDays = config.forceFullResyncIfOlderThanDays;
+    this.forceFullResyncCheckEveryHrs = config.forceFullResyncCheckEveryHrs;
+    this.onForceFullResyncTriggered = config.onForceFullResyncTriggered;
     this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
     this.scopeExitLookbehindMs = (_f = config.scopeExitLookbehindMs) != null ? _f : 0;
     this.evictOnWake = (_g = config.evictOnWake) != null ? _g : false;
@@ -4925,6 +4929,8 @@ var _SyncedDb = class _SyncedDb {
       };
       document.addEventListener("visibilitychange", this.visibilityFlushHandler);
     }
+    this._checkForceFullResyncThreshold("init");
+    this._startForceResyncCheckTimer();
     this.initialized = true;
   }
   /**
@@ -5004,6 +5010,73 @@ var _SyncedDb = class _SyncedDb {
       this._lastInitialSyncDate = new Date(meta.lastSyncTs);
     }
   }
+  /**
+   * Trip the `_pendingFullResync` flag iff `_lastFullSyncDate` is older
+   * than `forceFullResyncIfOlderThanDays`. Fires `onForceFullResyncTriggered`
+   * exactly once per trigger event (idempotent — repeated calls while the
+   * flag is already set are a no-op). Attempts to kick off a sync
+   * immediately if `canSync()`; otherwise the flag waits for the next
+   * online sync slot (auto-sync timer, reconnect, manual `sync()`, …).
+   *
+   * Never deletes Dexie data; the actual cursor reset happens inside
+   * `sync()` just before `syncEngine.sync()` runs (see `_resetSyncCursors`).
+   */
+  _checkForceFullResyncThreshold(reason) {
+    if (this._pendingFullResync) return;
+    const days = this.forceFullResyncIfOlderThanDays;
+    if (!days || days <= 0) return;
+    const last = this._lastFullSyncDate;
+    if (!last) return;
+    const ageMs = Date.now() - last.getTime();
+    const ageDays = ageMs / 864e5;
+    if (ageDays < days) return;
+    this._pendingFullResync = true;
+    this.safeCallback(this.onForceFullResyncTriggered, {
+      reason,
+      lastFullSyncDate: last,
+      daysSinceLastFullSync: ageDays,
+      thresholdDays: days,
+      timestamp: /* @__PURE__ */ new Date()
+    });
+    if (this.connectionManager.canSync()) {
+      this.sync(`force-full-resync:${reason}`).catch((err) => {
+        console.error(`[SyncedDb] force full resync sync() failed: ${err}`, err);
+      });
+    }
+  }
+  _startForceResyncCheckTimer() {
+    const hrs = this.forceFullResyncCheckEveryHrs;
+    if (!hrs || hrs <= 0) return;
+    this._forceResyncCheckTimer = setInterval(() => {
+      this._checkForceFullResyncThreshold("timer");
+    }, hrs * 36e5);
+  }
+  /**
+   * Cursor-reset path for the force-full-resync flow. Resets every
+   * collection's `syncMeta.lastSyncTs` to undefined (Dexie + cache) so
+   * the next `syncEngine.sync` call fetches from the beginning. Does
+   * NOT delete Dexie main rows, in-mem rows, or `_dirty_changes`.
+   * Conflict resolution + eviction (handled by the normal sync flow)
+   * sweep what needs sweeping AFTER the server response arrives — so
+   * a failed sync leaves local data intact.
+   *
+   * Per-collection deleteSyncMeta failures are logged and tolerated
+   * (cache is cleared unconditionally → in-memory effect is fully
+   * reset even if some Dexie rows lingered).
+   */
+  async _resetSyncCursors() {
+    for (const [name] of this.collections) {
+      try {
+        await this.dexieDb.deleteSyncMeta(name);
+      } catch (err) {
+        console.error(
+          `[SyncedDb] _resetSyncCursors: deleteSyncMeta(${name}) failed: ${err}`,
+          err
+        );
+      }
+    }
+    this.syncMetaCache.clear();
+  }
   async close() {
     var _a, _b;
     if (this.closed) return;
@@ -5011,6 +5084,10 @@ var _SyncedDb = class _SyncedDb {
     this.leaderElection.setClosing(true);
     this.pendingChanges.cancelRestUploadTimer();
     this.connectionManager.stopTimers();
+    if (this._forceResyncCheckTimer) {
+      clearInterval(this._forceResyncCheckTimer);
+      this._forceResyncCheckTimer = void 0;
+    }
     await this.pendingChanges.flushAll();
     (_a = this.networkStatus) == null ? void 0 : _a.dispose();
     (_b = this.wakeSync) == null ? void 0 : _b.dispose();
@@ -5634,6 +5711,10 @@ var _SyncedDb = class _SyncedDb {
           this._applyScopeExitChunkToPlan(evictionPlan, specId, items);
         }
       } : void 0;
+      const consumingPendingFullResync = this._pendingFullResync;
+      if (consumingPendingFullResync) {
+        await this._resetSyncCursors();
+      }
       try {
         await this.syncEngine.sync(calledFrom, evictionExtras);
         if (!this.syncOnlyCollections) {
@@ -5646,6 +5727,7 @@ var _SyncedDb = class _SyncedDb {
           this._setLastFullSync(now).catch((err) => {
             console.error(`[SyncedDb] Failed to persist lastFullSync: ${err}`, err);
           });
+          if (consumingPendingFullResync) this._pendingFullResync = false;
         }
       } catch (err) {
         if (evictionExtras) evictionServerFailed = true;

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

@@ -57,6 +57,11 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onSaveIdMismatch?;
     private readonly onUploadSkip?;
     private readonly onBeforeDirtyClearAll?;
+    private readonly forceFullResyncIfOlderThanDays?;
+    private readonly forceFullResyncCheckEveryHrs?;
+    private readonly onForceFullResyncTriggered?;
+    private _pendingFullResync;
+    private _forceResyncCheckTimer?;
     private readonly evictStaleRecordsEveryHrs;
     private readonly scopeExitLookbehindMs;
     private readonly evictOnWake;
@@ -168,6 +173,33 @@ export declare class SyncedDb implements I_SyncedDb {
     _setLastInitialSync(date: Date): Promise<void>;
     /** @internal Load cached value from Dexie */
     private _loadLastInitialSync;
+    /**
+     * Trip the `_pendingFullResync` flag iff `_lastFullSyncDate` is older
+     * than `forceFullResyncIfOlderThanDays`. Fires `onForceFullResyncTriggered`
+     * exactly once per trigger event (idempotent — repeated calls while the
+     * flag is already set are a no-op). Attempts to kick off a sync
+     * immediately if `canSync()`; otherwise the flag waits for the next
+     * online sync slot (auto-sync timer, reconnect, manual `sync()`, …).
+     *
+     * Never deletes Dexie data; the actual cursor reset happens inside
+     * `sync()` just before `syncEngine.sync()` runs (see `_resetSyncCursors`).
+     */
+    private _checkForceFullResyncThreshold;
+    private _startForceResyncCheckTimer;
+    /**
+     * Cursor-reset path for the force-full-resync flow. Resets every
+     * collection's `syncMeta.lastSyncTs` to undefined (Dexie + cache) so
+     * the next `syncEngine.sync` call fetches from the beginning. Does
+     * NOT delete Dexie main rows, in-mem rows, or `_dirty_changes`.
+     * Conflict resolution + eviction (handled by the normal sync flow)
+     * sweep what needs sweeping AFTER the server response arrives — so
+     * a failed sync leaves local data intact.
+     *
+     * Per-collection deleteSyncMeta failures are logged and tolerated
+     * (cache is cleared unconditionally → in-memory effect is fully
+     * reset even if some Dexie rows lingered).
+     */
+    private _resetSyncCursors;
     close(): Promise<void>;
     isOnline(): boolean;
     forceOffline(forced: boolean): void;

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

@@ -113,6 +113,34 @@ export interface BeforeDirtyClearAllInfo {
     /** Timestamp when the callback fires. */
     timestamp: Date;
 }
+/**
+ * Callback payload fired when the `forceFullResyncIfOlderThanDays`
+ * threshold trips — either on `init()` (`reason: "init"`) or on a
+ * `forceFullResyncCheckEveryHrs` timer tick (`reason: "timer"`).
+ *
+ * Fires BEFORE the cursor reset / sync. Use for telemetry, syslog,
+ * UI ("refreshing your data…"), or to gate UX during the resync.
+ *
+ * The trigger sets an internal `_pendingFullResync` flag and tries to
+ * initiate a sync immediately. If offline or `forcedOffline`, the
+ * flag persists in memory; the next online sync slot consumes it.
+ * On sync failure, the flag persists and the next slot retries.
+ * Dexie data is NEVER deleted as part of this flow — only cursors
+ * are reset; conflict resolution overwrites local rows record-by-
+ * record as the server response streams in.
+ */
+export interface ForceFullResyncInfo {
+    /** What triggered the resync check. */
+    reason: "init" | "timer";
+    /** Last successful full sync timestamp; undefined if never synced. */
+    lastFullSyncDate?: Date;
+    /** Age of last full sync in days; undefined if never synced. */
+    daysSinceLastFullSync?: number;
+    /** Configured threshold (`forceFullResyncIfOlderThanDays`) in days. */
+    thresholdDays: number;
+    /** Wall-clock at trigger time. */
+    timestamp: Date;
+}
 /**
  * Callback payload for server write requests (before sending)
  */
@@ -682,6 +710,60 @@ export interface SyncedDbConfig {
      * don't fire this callback.
      */
     onBeforeDirtyClearAll?: (info: BeforeDirtyClearAllInfo) => void;
+    /**
+     * Periodic full-resync maintenance heartbeat.
+     *
+     * If `lastSuccessfulServerSync()` is older than this many days, the
+     * library schedules a **safe full resync**:
+     *
+     *   1. Reset every collection's `syncMeta.lastSyncTs` to 0 (Dexie + cache).
+     *   2. Run `sync()` — cursors at 0 force the server to return everything.
+     *   3. Each record applied via normal conflict resolution; eviction
+     *      sweeps records the server no longer reports.
+     *
+     * Dexie main rows and `_dirty_changes` are **never deleted**. If the
+     * resync fails (offline, server error, timeout, tab closed), the
+     * local cache stays exactly as it was; cursors remain at 0 so the
+     * next online sync retries.
+     *
+     * Checked at `init()` (once, after Dexie sync metas have loaded) and
+     * on each `forceFullResyncCheckEveryHrs` timer tick. Records with
+     * `_lastFullSyncDate === undefined` (never synced) are NOT considered
+     * stale — the normal initial sync handles them.
+     *
+     * Default: `undefined` (disabled). Set to a positive integer to enable.
+     *
+     * @see forceFullResyncCheckEveryHrs for the timer interval.
+     * @see onForceFullResyncTriggered for the telemetry hook.
+     */
+    forceFullResyncIfOlderThanDays?: number;
+    /**
+     * Continuous timer interval (in hours) that re-checks the
+     * `forceFullResyncIfOlderThanDays` threshold. The timer keeps running
+     * for the lifetime of the SyncedDb (`init()` → `close()`) and never
+     * self-disables — every tick is a cheap memory + Date math check.
+     *
+     * Set to `undefined` (default) to only check at `init()`. Set to e.g.
+     * `24` to check every 24h. Independent of
+     * `forceFullResyncIfOlderThanDays`: the timer fires regardless, but
+     * does nothing if the threshold is unset or not exceeded.
+     *
+     * Multiple triggers between sync attempts are idempotent (the flag is
+     * boolean). A timer tick during an in-flight sync no-ops; the next
+     * sync slot picks up the pending flag.
+     */
+    forceFullResyncCheckEveryHrs?: number;
+    /**
+     * Fires when `forceFullResyncIfOlderThanDays` trips — BEFORE the
+     * cursor reset and sync. Use for telemetry / syslog / UI banners
+     * ("refreshing your data…").
+     *
+     * Fires at most once per trigger event. Even if the trigger sets the
+     * flag while a previous trigger's flag is still pending, this
+     * callback does NOT re-fire — the `_pendingFullResync` flag is
+     * boolean.
+     */
+    onForceFullResyncTriggered?: (info: ForceFullResyncInfo) => void;
     /**
      * Enable in-memory object metadata feature.
      * When true, collections with hasMetadata=true will have their metadata callbacks invoked

package/package.json

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