cry-synced-db-client 0.1.139 → 0.1.141

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+### BREAKING: Self-healing sync/reconnect lifecycle
+
+Fixes a class of bugs where the 60s auto-sync scheduler silently died after a
+sync failure or leader flap and was never re-armed until a page reload (see
+`/tmp/cry-synced-db-client-sync-interval-bug.md`). Reproducers spanned 5
+tenants, 62–296 min of dead scheduler with dirty items accumulating.
+
+- Removed `onForcedOffline` callback and `ConnectionManager.goOffline()` method.
+- Added `onSyncFailed(reason)` callback — fires on each sync failure but does
+  **not** mutate online state. The next auto-sync / reconnect tick retries.
+- Added `onlineRetryIntervalMs` config (default 60000, 0 = disable) — periodic
+  `tryGoOnline()` probe while offline but not forcedOffline. Always-live from
+  `init()` to `close()` so recovery does not depend on external signals.
+- `autoSyncTimer` and the new reconnect timer are both always-live from `init()`
+  to `close()`. `setOnline(false)`, `forceOffline(true)`, and sync failure no
+  longer clear timers — only flip flags; each tick is defensive.
+- `SyncedDb.sync()` now opportunistically calls `tryGoOnline()` when internally
+  offline (but not forcedOffline). Syncs while `forceOffline(true)` still throw
+  `Cannot sync while in forced offline mode`.
+- `onBecameLeader` now triggers `tryGoOnline()` when offline and post-init,
+  covering visibility re-claim and leader flap after mobile browser discards
+  state.
+- `syncLock` is now acquired before the early `tryGoOnline()` in
+  `SyncedDb.sync()` so the internal `INITIAL SYNC` that `tryGoOnline()` kicks
+  off is a no-op inside the outer call (avoids double sync).
+
+**Migration for consumers:**
+`onForcedOffline: (reason) => log(reason)` → `onSyncFailed: (reason) => log(reason)`.
+Signature is identical. No other callback changes.
+
 - 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

package/dist/index.js

@@ -842,46 +842,41 @@ var CrossTabSyncManager = class {
 };
 
 // src/db/managers/ConnectionManager.ts
+var DEFAULT_ONLINE_RETRY_INTERVAL_MS = 6e4;
 var ConnectionManager = class {
   constructor(config) {
     this.online = false;
     this.forcedOffline = false;
+    this.tryGoOnlineInFlight = false;
+    this.closed = false;
+    var _a;
     this.restInterface = config.restInterface;
     this.restTimeoutMs = config.restTimeoutMs;
     this.syncTimeoutMs = config.syncTimeoutMs;
     this.autoSyncIntervalMs = config.autoSyncIntervalMs;
+    this.onlineRetryIntervalMs = (_a = config.onlineRetryIntervalMs) != null ? _a : DEFAULT_ONLINE_RETRY_INTERVAL_MS;
     this.callbacks = config.callbacks;
     this.deps = config.deps;
   }
-  /**
-   * Current online status (considering forcedOffline).
-   */
+  /** Current online status (considering forcedOffline). */
   isOnline() {
     return this.online && !this.forcedOffline;
   }
-  /**
-   * Is forced offline mode active?
-   */
   isForcedOffline() {
     return this.forcedOffline;
   }
-  /**
-   * Can we sync with server?
-   */
   canSync() {
     return this.online && !this.forcedOffline;
   }
-  /**
-   * Can we receive server updates?
-   */
   canReceiveServerUpdates() {
     return !this.forcedOffline;
   }
   /**
-   * Set online status.
-   * Note: Going offline does NOT release leadership. With window-scoped locks,
-   * a tab should remain leader within its window to process WebSocket notifications
-   * even while offline.
+   * Set online status. Does NOT stop any timers.
+   *
+   * - `setOnline(true)` attempts `tryGoOnline` (ping → flip state).
+   * - `setOnline(false)` flips state to offline and fires `onOnlineStatusChange`.
+   *   The reconnect timer will continue attempting to come back online.
    */
   async setOnline(online) {
     var _a, _b;
@@ -889,19 +884,19 @@ var ConnectionManager = class {
     if (online) {
       await this.tryGoOnline();
     } else {
-      this.online = online;
-      this.stopAutoSync();
+      this.online = false;
       (_b = (_a = this.callbacks).onOnlineStatusChange) == null ? void 0 : _b.call(_a, false);
     }
   }
   /**
-   * Force offline mode.
+   * Force offline mode. Does NOT stop timers — reconnect timer will still
+   * check `forcedOffline` and skip while true. When released, `tryGoOnline`
+   * fires immediately to avoid waiting for the next tick.
    */
   forceOffline(forced) {
     if (this.forcedOffline === forced) return;
     this.forcedOffline = forced;
     if (forced) {
-      this.stopAutoSync();
       this.deps.releaseLeaderLock();
     } else {
       this.deps.tryBecomeLeader();
@@ -911,50 +906,86 @@ var ConnectionManager = class {
     }
   }
   /**
-   * Go offline with reason.
-   * Note: This does NOT release leadership. With window-scoped locks,
-   * a tab should remain leader within its window to process WebSocket notifications
-   * even while offline due to network issues.
+   * Attempt to transition from offline to online.
+   * Idempotent, guards against concurrent calls and forcedOffline.
    */
-  goOffline(reason) {
-    var _a, _b;
-    const wasOnline = this.online;
-    this.online = false;
-    this.stopAutoSync();
-    if (wasOnline) {
-      (_b = (_a = this.callbacks).onOnlineStatusChange) == null ? void 0 : _b.call(_a, false);
-    }
-    if (this.callbacks.onForcedOffline) {
+  async tryGoOnline() {
+    var _a, _b, _c;
+    if (this.closed) return;
+    if (this.forcedOffline) return;
+    if (this.tryGoOnlineInFlight) return;
+    this.tryGoOnlineInFlight = true;
+    try {
+      const wasOffline = !this.online;
+      if (wasOffline) {
+        let pingResult;
+        try {
+          pingResult = await this.withSyncTimeout(
+            this.restInterface.ping(),
+            "ping"
+          );
+        } catch (err) {
+          console.warn("tryGoOnline: ping failed:", err);
+          this.online = false;
+          return;
+        }
+        if (!pingResult) {
+          const url = (_a = this.restInterface.endpoint) != null ? _a : "unknown";
+          console.warn(`Ping to ${url} failed - staying offline`);
+          return;
+        }
+        this.online = true;
+        (_c = (_b = this.callbacks).onOnlineStatusChange) == null ? void 0 : _c.call(_b, true);
+        if (!this.deps.isLeader()) {
+          this.deps.tryBecomeLeader();
+        }
+      }
       try {
-        this.callbacks.onForcedOffline(reason);
+        await this.deps.sync("INITIAL SYNC");
       } catch (err) {
-        console.error("onForcedOffline callback failed:", err);
+        console.warn("INITIAL SYNC after tryGoOnline failed (stays online):", err);
       }
+    } finally {
+      this.tryGoOnlineInFlight = false;
     }
   }
   /**
-   * Start auto-sync timer.
+   * Start both timers. Idempotent. Called by SyncedDb.init().
    */
-  startAutoSync() {
-    this.stopAutoSync();
-    if (this.forcedOffline || !this.autoSyncIntervalMs || this.autoSyncIntervalMs <= 0) {
-      return;
+  startTimers() {
+    this.closed = false;
+    if (!this.autoSyncTimer && this.autoSyncIntervalMs && this.autoSyncIntervalMs > 0) {
+      const intervalMs = this.autoSyncIntervalMs;
+      this.autoSyncTimer = setInterval(() => {
+        if (this.forcedOffline || !this.online) return;
+        this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
+          console.error("Auto-sync failed:", err);
+        });
+      }, intervalMs);
+    }
+    if (!this.reconnectTimer && this.onlineRetryIntervalMs && this.onlineRetryIntervalMs > 0) {
+      const retryMs = this.onlineRetryIntervalMs;
+      this.reconnectTimer = setInterval(() => {
+        if (this.forcedOffline || this.online || this.tryGoOnlineInFlight) return;
+        this.tryGoOnline().catch((err) => {
+          console.error("Reconnect tryGoOnline failed:", err);
+        });
+      }, retryMs);
     }
-    const intervalMs = this.autoSyncIntervalMs;
-    this.autoSyncTimer = setInterval(() => {
-      this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
-        console.error("Auto-sync failed:", err);
-      });
-    }, intervalMs);
   }
   /**
-   * Stop auto-sync timer.
+   * Stop both timers. Called by SyncedDb.close().
    */
-  stopAutoSync() {
+  stopTimers() {
+    this.closed = true;
     if (this.autoSyncTimer) {
       clearInterval(this.autoSyncTimer);
       this.autoSyncTimer = void 0;
     }
+    if (this.reconnectTimer) {
+      clearInterval(this.reconnectTimer);
+      this.reconnectTimer = void 0;
+    }
   }
   /**
    * Ping server.
@@ -1025,6 +1056,19 @@ var ConnectionManager = class {
       }
     }
   }
+  /**
+   * Notify consumers of a sync failure. Does not mutate state.
+   * Called from SyncEngine via deps.onSyncFailed wiring.
+   */
+  callOnSyncFailed(reason) {
+    if (this.callbacks.onSyncFailed) {
+      try {
+        this.callbacks.onSyncFailed(reason);
+      } catch (err) {
+        console.error("onSyncFailed callback failed:", err);
+      }
+    }
+  }
   /**
    * Call onWsConnect callback.
    */
@@ -1083,43 +1127,6 @@ var ConnectionManager = class {
   getOnWsReconnect() {
     return this.callbacks.onWsReconnect;
   }
-  // ============================================================
-  // Private Methods
-  // ============================================================
-  async tryGoOnline() {
-    var _a, _b, _c, _d, _e;
-    if (this.forcedOffline) {
-      return;
-    }
-    try {
-      const pingResult = await this.withSyncTimeout(
-        this.restInterface.ping(),
-        "ping"
-      );
-      if (!pingResult) {
-        const url = (_a = this.restInterface.endpoint) != null ? _a : "unknown";
-        console.warn(`Ping to ${url} failed - staying offline`);
-        return;
-      }
-      const wasOffline = !this.online;
-      this.online = true;
-      if (wasOffline) {
-        (_c = (_b = this.callbacks).onOnlineStatusChange) == null ? void 0 : _c.call(_b, true);
-        if (!this.deps.isLeader()) {
-          this.deps.tryBecomeLeader();
-        }
-      }
-      this.startAutoSync();
-      await this.deps.sync("INITIAL SYNC");
-    } catch (err) {
-      console.warn("Failed to go online (ping failed or timed out):", err);
-      const wasOnline = this.online;
-      this.online = false;
-      if (wasOnline) {
-        (_e = (_d = this.callbacks).onOnlineStatusChange) == null ? void 0 : _e.call(_d, false);
-      }
-    }
-  }
 };
 
 // node_modules/superjson/dist/double-indexed-kv.js
@@ -2541,8 +2548,8 @@ var _SyncEngine = class _SyncEngine {
       });
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
-      console.error("Sync failed, going offline:", err);
-      this.deps.goOffline(`Sync failed: ${reason}`);
+      console.error("Sync failed:", err);
+      this.deps.onSyncFailed(`Sync failed: ${reason}`);
       this.callOnSyncEnd({
         durationMs: Date.now() - startTime,
         receivedCount,
@@ -3511,7 +3518,20 @@ var _SyncedDb = class _SyncedDb {
       tenant: this.tenant,
       windowId,
       callbacks: {
-        onBecameLeader: config.onBecameLeader,
+        onBecameLeader: () => {
+          if (this.initialized && !this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
+            this.connectionManager.tryGoOnline().catch((err) => {
+              console.error("tryGoOnline on becameLeader failed:", err);
+            });
+          }
+          if (config.onBecameLeader) {
+            try {
+              config.onBecameLeader();
+            } catch (err) {
+              console.error("onBecameLeader callback failed:", err);
+            }
+          }
+        },
         onLostLeadership: config.onLostLeadership,
         onInfrastructureError: config.onInfrastructureError ? (type, message, error) => {
           config.onInfrastructureError({
@@ -3556,9 +3576,10 @@ var _SyncedDb = class _SyncedDb {
       restTimeoutMs: (_h = config.restTimeoutMs) != null ? _h : 9e4,
       syncTimeoutMs: (_i = config.syncTimeoutMs) != null ? _i : 12e4,
       autoSyncIntervalMs: config.autoSyncIntervalMs,
+      onlineRetryIntervalMs: config.onlineRetryIntervalMs,
       callbacks: {
         onOnlineStatusChange: config.onOnlineStatusChange,
-        onForcedOffline: config.onForcedOffline,
+        onSyncFailed: config.onSyncFailed,
         onWsConnect: config.onWsConnect,
         onWsDisconnect: config.onWsDisconnect,
         onWsReconnect: config.onWsReconnect,
@@ -3628,7 +3649,7 @@ var _SyncedDb = class _SyncedDb {
         },
         getInMemById: (collection, id) => this.inMemDb.getById(collection, id),
         withSyncTimeout: (promise, operation) => this.connectionManager.withSyncTimeout(promise, operation),
-        goOffline: (reason) => this.connectionManager.goOffline(reason),
+        onSyncFailed: (reason) => this.connectionManager.callOnSyncFailed(reason),
         flushAllPendingChanges: () => this.pendingChanges.flushAll(),
         cancelRestUploadTimer: () => this.pendingChanges.cancelRestUploadTimer(),
         awaitRestUpload: () => this.pendingChanges.awaitRestUpload(),
@@ -3769,6 +3790,7 @@ var _SyncedDb = class _SyncedDb {
     this.crossTabSync.init();
     (_a = this.wakeSync) == null ? void 0 : _a.init();
     (_b = this.networkStatus) == null ? void 0 : _b.init();
+    this.connectionManager.startTimers();
     if (this.serverUpdateNotifier) {
       if (this.serverUpdateNotifier.setCallbacks) {
         const cleanup = this.serverUpdateNotifier.setCallbacks({
@@ -3875,7 +3897,7 @@ var _SyncedDb = class _SyncedDb {
     var _a, _b;
     this.leaderElection.setClosing(true);
     this.pendingChanges.cancelRestUploadTimer();
-    this.connectionManager.stopAutoSync();
+    this.connectionManager.stopTimers();
     await this.pendingChanges.flushAll();
     (_a = this.networkStatus) == null ? void 0 : _a.dispose();
     (_b = this.wakeSync) == null ? void 0 : _b.dispose();
@@ -4423,39 +4445,45 @@ var _SyncedDb = class _SyncedDb {
   }
   // ==================== Sync Operations ====================
   async sync(calledFrom) {
-    if (!this.connectionManager.canSync()) {
-      if (this.connectionManager.isForcedOffline()) {
-        throw new Error("Cannot sync while in forced offline mode");
-      }
-      return;
-    }
     if (this.syncLock) return;
     this.syncLock = true;
-    this.syncing = true;
-    this.crossTabSync.startServerSync();
     try {
-      await this.syncEngine.sync(calledFrom);
-      if (!this.syncOnlyCollections) {
-        const now = /* @__PURE__ */ new Date();
-        if (!this._lastFullSyncDate) {
-          this._setLastInitialSync(now).catch((err) => {
-            console.error("Failed to persist lastInitialSync:", err);
+      if (!this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
+        await this.connectionManager.tryGoOnline();
+      }
+      if (!this.connectionManager.canSync()) {
+        if (this.connectionManager.isForcedOffline()) {
+          throw new Error("Cannot sync while in forced offline mode");
+        }
+        return;
+      }
+      this.syncing = true;
+      this.crossTabSync.startServerSync();
+      try {
+        await this.syncEngine.sync(calledFrom);
+        if (!this.syncOnlyCollections) {
+          const now = /* @__PURE__ */ new Date();
+          if (!this._lastFullSyncDate) {
+            this._setLastInitialSync(now).catch((err) => {
+              console.error("Failed to persist lastInitialSync:", err);
+            });
+          }
+          this._setLastFullSync(now).catch((err) => {
+            console.error("Failed to persist lastFullSync:", err);
           });
         }
-        this._setLastFullSync(now).catch((err) => {
-          console.error("Failed to persist lastFullSync:", err);
-        });
+      } finally {
+        this.syncing = false;
+        this.crossTabSync.endServerSync();
+        await this.processQueuedWsUpdates();
+        try {
+          await this.maybeAutoEvict();
+        } catch (err) {
+          console.error("Auto-eviction failed:", err);
+        }
       }
     } finally {
-      this.syncing = false;
       this.syncLock = false;
-      this.crossTabSync.endServerSync();
-      await this.processQueuedWsUpdates();
-      try {
-        await this.maybeAutoEvict();
-      } catch (err) {
-        console.error("Auto-eviction failed:", err);
-      }
     }
   }
   async processQueuedWsUpdates() {

package/dist/src/db/managers/ConnectionManager.d.ts

@@ -1,11 +1,19 @@
 /**
- * ConnectionManager - Manages online/offline state and auto-sync.
+ * ConnectionManager - Manages online/offline state, auto-sync and reconnect.
  *
- * Handles:
- * - Online/offline state transitions
- * - Forced offline mode
- * - Auto-sync timer management
- * - REST/sync timeouts
+ * Invariants:
+ * - `autoSyncTimer` and `reconnectTimer` are always-live from `startTimers()`
+ *   (called by SyncedDb during init) until `stopTimers()` (called by close()).
+ * - Neither timer is cleared by `setOnline(false)`, `forceOffline(true)`, or
+ *   sync failure — state changes only flip flags. Each tick is defensive and
+ *   no-ops when inapplicable.
+ * - `autoSyncTimer` tick: run `sync()` iff `online && !forcedOffline`.
+ * - `reconnectTimer` tick: call `tryGoOnline()` iff `!online && !forcedOffline`
+ *   and no `tryGoOnline` is in flight.
+ * - `tryGoOnline()` pings the server; on success flips `online=true` (next
+ *   auto-sync tick then runs). Historical `goOffline(reason)` method and
+ *   `onForcedOffline` callback are removed — use `onSyncFailed` (logging-only
+ *   callback fired from SyncEngine) or explicit `forceOffline(true)`.
  */
 import type { I_ConnectionManager, ConnectionManagerConfig } from "../types/managers";
 export declare class ConnectionManager implements I_ConnectionManager {
@@ -13,54 +21,48 @@ export declare class ConnectionManager implements I_ConnectionManager {
     private readonly restTimeoutMs;
     private readonly syncTimeoutMs;
     private readonly autoSyncIntervalMs?;
+    private readonly onlineRetryIntervalMs;
     private readonly callbacks;
     private readonly deps;
     private online;
     private forcedOffline;
     private autoSyncTimer?;
+    private reconnectTimer?;
+    private tryGoOnlineInFlight;
+    private closed;
     constructor(config: ConnectionManagerConfig);
-    /**
-     * Current online status (considering forcedOffline).
-     */
+    /** Current online status (considering forcedOffline). */
     isOnline(): boolean;
-    /**
-     * Is forced offline mode active?
-     */
     isForcedOffline(): boolean;
-    /**
-     * Can we sync with server?
-     */
     canSync(): boolean;
-    /**
-     * Can we receive server updates?
-     */
     canReceiveServerUpdates(): boolean;
     /**
-     * Set online status.
-     * Note: Going offline does NOT release leadership. With window-scoped locks,
-     * a tab should remain leader within its window to process WebSocket notifications
-     * even while offline.
+     * Set online status. Does NOT stop any timers.
+     *
+     * - `setOnline(true)` attempts `tryGoOnline` (ping → flip state).
+     * - `setOnline(false)` flips state to offline and fires `onOnlineStatusChange`.
+     *   The reconnect timer will continue attempting to come back online.
      */
     setOnline(online: boolean): Promise<void>;
     /**
-     * Force offline mode.
+     * Force offline mode. Does NOT stop timers — reconnect timer will still
+     * check `forcedOffline` and skip while true. When released, `tryGoOnline`
+     * fires immediately to avoid waiting for the next tick.
      */
     forceOffline(forced: boolean): void;
     /**
-     * Go offline with reason.
-     * Note: This does NOT release leadership. With window-scoped locks,
-     * a tab should remain leader within its window to process WebSocket notifications
-     * even while offline due to network issues.
+     * Attempt to transition from offline to online.
+     * Idempotent, guards against concurrent calls and forcedOffline.
      */
-    goOffline(reason: string): void;
+    tryGoOnline(): Promise<void>;
     /**
-     * Start auto-sync timer.
+     * Start both timers. Idempotent. Called by SyncedDb.init().
      */
-    startAutoSync(): void;
+    startTimers(): void;
     /**
-     * Stop auto-sync timer.
+     * Stop both timers. Called by SyncedDb.close().
      */
-    stopAutoSync(): void;
+    stopTimers(): void;
     /**
      * Ping server.
      */
@@ -77,6 +79,11 @@ export declare class ConnectionManager implements I_ConnectionManager {
      * Report infrastructure error.
      */
     reportInfrastructureError(type: string, message: string, error?: Error): void;
+    /**
+     * Notify consumers of a sync failure. Does not mutate state.
+     * Called from SyncEngine via deps.onSyncFailed wiring.
+     */
+    callOnSyncFailed(reason: string): void;
     /**
      * Call onWsConnect callback.
      */
@@ -101,5 +108,4 @@ export declare class ConnectionManager implements I_ConnectionManager {
      * Get onWsReconnect callback.
      */
     getOnWsReconnect(): ((attempt: number) => void) | undefined;
-    private tryGoOnline;
 }

package/dist/src/db/types/managers.d.ts

@@ -91,7 +91,10 @@ export interface I_CrossTabSyncManager {
 }
 export interface ConnectionCallbacks {
     onOnlineStatusChange?: (online: boolean) => void;
-    onForcedOffline?: (reason: string) => void;
+    /**
+     * Fired on sync failure. Does NOT mutate online state. For logging only.
+     */
+    onSyncFailed?: (reason: string) => void;
     onWsConnect?: () => void;
     onWsDisconnect?: (reason: string) => void;
     onWsReconnect?: (attempt: number) => void;
@@ -112,6 +115,7 @@ export interface ConnectionManagerConfig {
     restTimeoutMs: number;
     syncTimeoutMs: number;
     autoSyncIntervalMs?: number;
+    onlineRetryIntervalMs?: number;
     callbacks: ConnectionCallbacks;
     deps: ConnectionManagerDeps;
 }
@@ -128,12 +132,15 @@ export interface I_ConnectionManager {
     setOnline(online: boolean): Promise<void>;
     /** Force offline mode. */
     forceOffline(forced: boolean): void;
-    /** Go offline with reason. */
-    goOffline(reason: string): void;
-    /** Start auto-sync timer. */
-    startAutoSync(): void;
-    /** Stop auto-sync timer. */
-    stopAutoSync(): void;
+    /**
+     * Attempt to transition from internal-offline to online (ping + start timers
+     * if successful). No-op if already online, forcedOffline, or a try is in flight.
+     */
+    tryGoOnline(): Promise<void>;
+    /** Start both auto-sync and reconnect timers (idempotent). */
+    startTimers(): void;
+    /** Stop both auto-sync and reconnect timers. Called from close(). */
+    stopTimers(): void;
     /** Ping server. */
     ping(timeoutMs?: number): Promise<boolean>;
     /** Wrap promise with sync timeout. */
@@ -256,7 +263,8 @@ export interface SyncEngineDeps {
     writeToInMemBatch: <T extends DbEntity>(collection: string, items: T[], operation: "upsert" | "delete") => void;
     getInMemById: <T extends DbEntity>(collection: string, id: Id) => T | undefined;
     withSyncTimeout: <T>(promise: Promise<T>, operation: string) => Promise<T>;
-    goOffline: (reason: string) => void;
+    /** Notify consumers that a sync cycle failed. Does not mutate online state. */
+    onSyncFailed: (reason: string) => void;
     flushAllPendingChanges: () => Promise<void>;
     cancelRestUploadTimer: () => void;
     awaitRestUpload: () => Promise<void>;

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

@@ -317,8 +317,13 @@ export interface SyncedDbConfig {
     debounceDexieWritesMs?: number;
     /** Debounce čas za pošiljanje na REST v ms (default: 100) - po uspešnem zapisu v Dexie */
     debounceRestWritesMs?: number;
-    /** Callback ki se pokliče, ko SyncedDb sam preide v offline stanje (npr. ob sync napaki) */
-    onForcedOffline?: (reason: string) => void;
+    /**
+     * Callback fired on each sync failure. Unlike the removed `onForcedOffline`,
+     * this does NOT mutate online state — the library keeps trying on the next
+     * auto-sync tick. Use this callback for logging/telemetry only. To actually
+     * force the database offline, call {@link forceOffline}.
+     */
+    onSyncFailed?: (reason: string) => void;
     /** Callback fired once during init() when the IndexedDB database was created fresh (first ever open). */
     onDatabaseCreated?: () => void;
     /** Callback at the start of each sync cycle. initialSync=true if no full sync has completed yet. */
@@ -381,8 +386,19 @@ export interface SyncedDbConfig {
      * Če je podano, se sync() kliče avtomatsko na ta interval, ko je online.
      * Auto-sync se izvaja samo ko je online in ne bo interferiral z eksplicitnimi sync() klici
      * (uporablja isti syncLock mehanizem).
+     *
+     * Timer je zagnan v init() in ustavljen v close(). Če je offline ali
+     * forcedOffline, tick-i so no-op (ne ubije se timer, naslednji tick bo spet
+     * poskusil). Self-healing: sync napaka ne ustavi timer-ja.
      */
     autoSyncIntervalMs?: number;
+    /**
+     * Interval za periodično poskušanje preklopa iz offline v online, v ms.
+     * Vedno-živi timer: od init() do close(). Če smo offline in ne forcedOffline,
+     * vsak tick pokliče `tryGoOnline()` (ping → če uspešen, gremo online in naslednji
+     * auto-sync tick bo sinhroniziral). Default: 60000 (60 s). 0/undefined disable.
+     */
+    onlineRetryIntervalMs?: number;
     /** Callback when WebSocket connects */
     onWsConnect?: () => void;
     /** Callback when WebSocket disconnects */
@@ -391,7 +407,7 @@ export interface SyncedDbConfig {
     onWsReconnect?: (attempt: number) => void;
     /** Callback when a WebSocket notification is received */
     onWsNotification?: (info: WsNotificationInfo) => void;
-    /** Callback when online status changes (after ping success/failure in tryGoOnline or goOffline) */
+    /** Callback when online status changes (after ping success/failure in tryGoOnline) */
     onOnlineStatusChange?: (online: boolean) => void;
     /** Debounce interval for cross-tab sync broadcasts in ms (default: 100) */
     crossTabSyncDebounceMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.139",
+  "version": "0.1.141",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -36,7 +36,7 @@
     "vitest": "^4.1.2"
   },
   "dependencies": {
-    "cry-db": "^2.4.28",
+    "cry-db": "^2.4.31",
     "cry-helpers": "^2.1.193",
     "msgpackr": "^1.11.9",
     "notepack": "^0.0.2",