cry-synced-db-client 0.1.187 → 0.1.189

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # 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
+
+Public counterpart to `getDirty` / `getDirtyMeta` for the "stuck dirty
+drain" recovery flow. Use case: a known-bad dirty entry can't upload
+(e.g. pre-fix `sestevki` parent+descendant producing repeated 500-loops
+on klikvet tabs running pre-0.1.185 bundles) and the operator wants to
+forfeit the pending local intent in favor of server state — without
+calling the heavier `dropCollection` / `dropDatabase` which also wipes
+the main row data.
+
+```typescript
+clearDirty(
+  collection?: string,
+  ids?: Id[],
+  calledFrom?: string,
+): Promise<DirtyMeta[]>
+```
+
+Returns the `DirtyMeta[]` of every entry that was actually removed, so
+the caller can archive what was lost.
+
+| Call shape | Effect | Fires `onBeforeDirtyClearAll` |
+|---|---|---|
+| `clearDirty()` / `clearDirty(undefined)` | Clear ALL dirty in EVERY collection | ✅ once per collection that has dirty |
+| `clearDirty(coll)` | Clear all dirty in one collection | ❌ |
+| `clearDirty(coll, ids)` | Clear specific ids in that collection | ❌ |
+| `clearDirty(undefined, ids)` | Throws — ambiguous | — |
+
+The new config callback:
+
+```typescript
+onBeforeDirtyClearAll?: (info: BeforeDirtyClearAllInfo) => void;
+
+interface BeforeDirtyClearAllInfo {
+  reason: string;             // `calledFrom` if provided, else "manual"
+  collection: string;
+  items: DirtyMeta[];         // every entry in that collection (no `changes` payload)
+  calledFrom?: string;        // passthrough of the third arg
+  timestamp: Date;
+}
+```
+
+Fires **only** on the clear-all path, **before** the Dexie delete runs,
+**once per collection** with dirty. Use to archive the dirty state to
+syslog / audit trail before it disappears. Per-collection /
+per-id `clearDirty` calls are intentionally silent — the caller already
+knows what they're touching.
+
+```typescript
+new SyncedDb({
+  // ...
+  onBeforeDirtyClearAll: (info) => {
+    syslog.warn("dirty cleared", {
+      collection: info.collection,
+      count: info.items.length,
+      reason: info.reason,
+      ids: info.items.map((m) => m.id),
+    });
+  },
+});
+
+// Nuke everything across collections, tagged for the audit log.
+const cleared = await syncedDb.clearDirty(undefined, undefined, "stuck-drain");
+
+// Targeted: drop two known-bad rows in `obiski` (silent — no callback).
+await syncedDb.clearDirty("obiski", ["6a032a59...", "6a05a1ba..."]);
+
+// Inspect first, then decide.
+const meta = await syncedDb.getDirtyMeta();
+for (const [coll, items] of Object.entries(meta)) {
+  if (items.length > 100) {
+    await syncedDb.clearDirty(coll, undefined, `over-threshold:${items.length}`);
+  }
+}
+```
+
+`clearDirty` does NOT await in-flight uploads — call `flushToServer()`
+first if a last-chance upload is desired. It also does not touch the
+main row data; in-mem and Dexie rows are preserved at whatever state
+they're at (typically: the server's view if WS-push has landed
+recently, otherwise the pre-rollback local intent).
+
 ## 0.1.187 (2026-05-16)
 
 ### Fix: `setByPath` auto-creates plain-object intermediates (root cause of `sestevki` parent+child conflict)

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;
@@ -4484,6 +4485,10 @@ var _SyncedDb = class _SyncedDb {
     this.onEviction = config.onEviction;
     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;
@@ -4924,6 +4929,8 @@ var _SyncedDb = class _SyncedDb {
       };
       document.addEventListener("visibilitychange", this.visibilityFlushHandler);
     }
+    this._checkForceFullResyncThreshold("init");
+    this._startForceResyncCheckTimer();
     this.initialized = true;
   }
   /**
@@ -5003,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;
@@ -5010,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();
@@ -5633,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) {
@@ -5645,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;
@@ -5759,6 +5842,68 @@ var _SyncedDb = class _SyncedDb {
     }
     return result;
   }
+  /**
+   * Manually clear pending dirty changes WITHOUT touching the main
+   * row data. Counterpart to `getDirty` / `getDirtyMeta` for the
+   * "stuck dirty drain" recovery flow — when a known-bad dirty entry
+   * can't be uploaded (e.g. pre-fix sestevki parent+descendant
+   * conflict producing repeated 500s) and the operator wants to
+   * forfeit the pending local intent in favor of server state.
+   *
+   * Three call shapes:
+   *
+   * | Call | Effect |
+   * |---|---|
+   * | `clearDirty()` / `clearDirty(undefined)` | Clear ALL dirty in EVERY collection. Fires `onBeforeDirtyClearAll` once per collection that has dirty (BEFORE the Dexie delete). |
+   * | `clearDirty(coll)` | Clear all dirty in one collection. No callback. |
+   * | `clearDirty(coll, ids)` | Clear specific ids in that collection. No callback. |
+   * | `clearDirty(undefined, ids)` | Throws — ambiguous (which collection do the ids belong to?). |
+   *
+   * Returns the `DirtyMeta[]` of every entry that was actually
+   * removed so the caller can log / archive what was lost.
+   *
+   * Pairs naturally with `getDirtyMeta()` for the inspect-then-clear
+   * pattern. Doesn't await in-flight uploads — caller's
+   * responsibility to call `flushToServer()` first if a last-chance
+   * upload is desired.
+   */
+  async clearDirty(collection, ids, calledFrom) {
+    if (!collection && ids && ids.length > 0) {
+      throw new Error(
+        `[SyncedDb] clearDirty: 'ids' requires a 'collection' \u2014 ids alone are ambiguous across collections.`
+      );
+    }
+    const cleared = [];
+    if (!collection) {
+      for (const [name] of this.collections) {
+        const metas2 = await this.dexieDb.getDirtyMeta(name);
+        if (metas2.length === 0) continue;
+        this.safeCallback(this.onBeforeDirtyClearAll, {
+          reason: calledFrom != null ? calledFrom : "manual",
+          collection: name,
+          items: metas2,
+          calledFrom,
+          timestamp: /* @__PURE__ */ new Date()
+        });
+        await this.dexieDb.clearDirtyChanges(name);
+        for (const m of metas2) cleared.push(m);
+      }
+      return cleared;
+    }
+    this.assertCollection(collection);
+    if (ids && ids.length > 0) {
+      const idStrings = new Set(ids.map((id) => String(id)));
+      const allMetas = await this.dexieDb.getDirtyMeta(collection);
+      for (const m of allMetas) {
+        if (idStrings.has(String(m.id))) cleared.push(m);
+      }
+      await this.dexieDb.clearDirtyChangesBatch(collection, ids);
+      return cleared;
+    }
+    const metas = await this.dexieDb.getDirtyMeta(collection);
+    await this.dexieDb.clearDirtyChanges(collection);
+    return metas;
+  }
   // ==================== Data Deletion ====================
   async dropCollection(collection, force = false) {
     this.assertCollection(collection);

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

@@ -56,6 +56,12 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onEviction?;
     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;
@@ -167,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;
@@ -238,6 +271,32 @@ export declare class SyncedDb implements I_SyncedDb {
     getOnWakeSync(): ((info: import("./types/managers").WakeSyncInfo) => void) | undefined;
     getDirty<T extends DbEntity>(): Promise<Readonly<Record<string, readonly T[]>>>;
     getDirtyMeta(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
+    /**
+     * Manually clear pending dirty changes WITHOUT touching the main
+     * row data. Counterpart to `getDirty` / `getDirtyMeta` for the
+     * "stuck dirty drain" recovery flow — when a known-bad dirty entry
+     * can't be uploaded (e.g. pre-fix sestevki parent+descendant
+     * conflict producing repeated 500s) and the operator wants to
+     * forfeit the pending local intent in favor of server state.
+     *
+     * Three call shapes:
+     *
+     * | Call | Effect |
+     * |---|---|
+     * | `clearDirty()` / `clearDirty(undefined)` | Clear ALL dirty in EVERY collection. Fires `onBeforeDirtyClearAll` once per collection that has dirty (BEFORE the Dexie delete). |
+     * | `clearDirty(coll)` | Clear all dirty in one collection. No callback. |
+     * | `clearDirty(coll, ids)` | Clear specific ids in that collection. No callback. |
+     * | `clearDirty(undefined, ids)` | Throws — ambiguous (which collection do the ids belong to?). |
+     *
+     * Returns the `DirtyMeta[]` of every entry that was actually
+     * removed so the caller can log / archive what was lost.
+     *
+     * Pairs naturally with `getDirtyMeta()` for the inspect-then-clear
+     * pattern. Doesn't await in-flight uploads — caller's
+     * responsibility to call `flushToServer()` first if a last-chance
+     * upload is desired.
+     */
+    clearDirty(collection?: string, ids?: Id[], calledFrom?: string): Promise<DirtyMeta[]>;
     dropCollection(collection: string, force?: boolean): Promise<void>;
     dropDatabase(force?: boolean): Promise<void>;
     /**

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

@@ -91,6 +91,56 @@ export interface SaveIdMismatchInfo {
     /** Timestamp when mismatch detected */
     timestamp: Date;
 }
+/**
+ * Callback payload fired by `clearDirty()` when called WITHOUT a
+ * `collection` argument (clear-all path). One invocation per
+ * collection that has ≥1 dirty entry, fired BEFORE the underlying
+ * Dexie delete runs — caller can archive/inspect the records.
+ *
+ * Per-collection `clearDirty(coll, ...)` calls do NOT fire this
+ * callback (targeted operation; caller already knows what they're
+ * touching).
+ */
+export interface BeforeDirtyClearAllInfo {
+    /** What triggered the clear-all (e.g. "manual", custom string from caller). */
+    reason: string;
+    /** Collection whose dirty entries are about to be deleted. */
+    collection: string;
+    /** Meta of every dirty entry in this collection (no `changes` payload). */
+    items: import("./I_DexieDb").DirtyMeta[];
+    /** Optional caller tag passed through `clearDirty(undefined, undefined, calledFrom)`. */
+    calledFrom?: string;
+    /** 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)
  */
@@ -649,6 +699,71 @@ export interface SyncedDbConfig {
      * where `this._id` and `this.protokol._id` had drifted apart.
      */
     onSaveIdMismatch?: (info: SaveIdMismatchInfo) => void;
+    /**
+     * Fired by `clearDirty()` (no collection argument — clear-all path)
+     * BEFORE the Dexie delete runs, once per collection that has
+     * dirty entries. Use to archive the dirty state to syslog / audit
+     * trail before it's gone, or to abort by throwing (the throw
+     * aborts only the in-flight clear, doesn't propagate).
+     *
+     * Per-collection `clearDirty(coll, ...)` calls are SILENT — they
+     * 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.187",
+  "version": "0.1.189",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",