cry-synced-db-client 0.1.181 → 0.1.182

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Versions
 
+## 0.1.182 (2026-05-14)
+
+### `networkError` utility — quiet log noise during sustained offline
+
+New `src/utils/networkError.ts`:
+
+```ts
+export function networkError(message: string, ...rest: unknown[]): void {
+  const isOnline =
+    typeof navigator === "undefined" || navigator.onLine !== false;
+  if (isOnline) {
+    console.error(message, ...rest);
+  } else {
+    console.info(message, ...rest);
+  }
+}
+```
+
+Applied to 15 sites where the failure mode reduces to "REST/WS
+unreachable because the network is down":
+
+| Module | Site |
+|---|---|
+| `ConnectionManager` | Failed to go online after forceOffline release |
+| `ConnectionManager` | Auto-sync failed |
+| `ConnectionManager` | Reconnect tryGoOnline failed |
+| `PendingChangesManager` | REST upload failed |
+| `WakeSyncManager` | Wake sync (`<trigger>`) failed |
+| `SyncEngine` | uploadDirtyItems failed (download succeeded) |
+| `SyncEngine` | Sync failed |
+| `SyncedDb` | tryGoOnline on becameLeader failed |
+| `SyncedDb` | referToServer failed for `<collection>` |
+| `SyncedDb` | refreshInBackground failed for `<collection>` |
+| `SyncedDb` | Failed to hard delete `<id>` |
+| `SyncedDb` | `[evict]` server-assisted pass failed |
+| `SyncedDb` | `[evict]` server-assisted batch failed |
+| `Ebus2ProxyNotifier` | WebSocket error: `<event.type>` |
+| `Ebus2ProxyNotifier` | Reconnection failed |
+
+Effect: a 5-minute offline period that previously produced ~25–30
+`console.error` lines (auto-sync ticks every 60s, reconnect probes
+every 60s, WS reconnect backoff, dirty-flush retries) now produces 0.
+The events are still logged at `console.info` so an operator inspecting
+them sees the full timeline — they just don't surface as "errors" in
+sentry/log dashboards.
+
+What's NOT routed through `networkError` (intentional — these are real
+bugs regardless of network state):
+- Caller bugs (falsy `_id`, missing `_id`, id mismatch, no id provided)
+- Dexie failures (`bulkPut failed`, `Failed to write to Dexie`, etc.)
+- Consumer-supplied callback throws (`onSyncEnd callback failed`, etc.)
+- WS protocol errors (malformed msgpack, server-side error frames)
+- Server-side per-item rejection (`Sync upload error [coll] _id=...`)
+- `DB-WARNING` per-item warnings
+- BroadcastChannel failures (cross-tab, local, not network)
+
+Caveat: `navigator.onLine` only reports the OS network interface, not
+server reachability. WiFi-on-but-server-unreachable still logs at error
+severity, which is the correct behavior — that failure is unexpected
+from the browser's point of view.
+
+Bundle: 356.0 KB → 356.2 KB. Tests: 736 bun + 18 vitest still pass.
+
 ## 0.1.181 (2026-05-14)
 
 ### `measureEndToEndRtt` now rides `callWorker` over the WebSocket

package/dist/index.js

@@ -732,6 +732,16 @@ function childPathForArrayElement(prefix, element, index) {
   return prefix ? `${prefix}.${index}` : String(index);
 }
 
+// src/utils/networkError.ts
+function networkError(message, ...rest) {
+  const isOnline = typeof navigator === "undefined" || navigator.onLine !== false;
+  if (isOnline) {
+    console.error(message, ...rest);
+  } else {
+    console.info(message, ...rest);
+  }
+}
+
 // src/db/managers/InMemManager.ts
 var InMemManager = class {
   constructor(config) {
@@ -1422,7 +1432,7 @@ var ConnectionManager = class {
     } else {
       this.deps.tryBecomeLeader();
       this.tryGoOnline().catch((err) => {
-        console.error(`[Connection] Failed to go online after forceOffline release: ${err}`, err);
+        networkError(`[Connection] Failed to go online after forceOffline release: ${err}`, err);
       });
     }
   }
@@ -1480,7 +1490,7 @@ var ConnectionManager = class {
       this.autoSyncTimer = setInterval(() => {
         if (this.forcedOffline || !this.online) return;
         this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
-          console.error(`[Connection] Auto-sync failed: ${err}`, err);
+          networkError(`[Connection] Auto-sync failed: ${err}`, err);
         });
       }, intervalMs);
     }
@@ -1489,7 +1499,7 @@ var ConnectionManager = class {
       this.reconnectTimer = setInterval(() => {
         if (this.forcedOffline || this.online || this.tryGoOnlineInFlight) return;
         this.tryGoOnline().catch((err) => {
-          console.error(`[Connection] Reconnect tryGoOnline failed: ${err}`, err);
+          networkError(`[Connection] Reconnect tryGoOnline failed: ${err}`, err);
         });
       }, retryMs);
     }
@@ -2827,7 +2837,7 @@ var PendingChangesManager = class {
     try {
       await this.deps.uploadDirtyItems();
     } catch (err) {
-      console.error(`[PendingChanges] REST upload failed: ${err}`, err);
+      networkError(`[PendingChanges] REST upload failed: ${err}`, err);
     } finally {
       this.isUploadingToRest = false;
       resolveUpload();
@@ -3209,7 +3219,7 @@ var _SyncEngine = class _SyncEngine {
           }
         }
       } catch (err) {
-        console.error(
+        networkError(
           "[SyncEngine] uploadDirtyItems failed (download succeeded, staying online):",
           err
         );
@@ -3236,7 +3246,7 @@ var _SyncEngine = class _SyncEngine {
       });
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
-      console.error(`[SyncEngine] Sync failed: ${err}`, err);
+      networkError(`[SyncEngine] Sync failed: ${err}`, err);
       this.deps.onSyncFailed(`Sync failed: ${reason}`);
       this.callOnSyncEnd({
         durationMs: Date.now() - startTime,
@@ -4291,7 +4301,7 @@ var WakeSyncManager = class {
         }
       }
       this.deps.sync(`wake-sync:${trigger}`).catch((err) => {
-        console.error(`[WakeSync] Wake sync (${trigger}) failed:`, err);
+        networkError(`[WakeSync] Wake sync (${trigger}) failed:`, err);
       });
     }, this.debounceMs);
   }
@@ -4447,7 +4457,7 @@ var _SyncedDb = class _SyncedDb {
         onBecameLeader: () => {
           if (this.initialized && !this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
             this.connectionManager.tryGoOnline().catch((err) => {
-              console.error(`[SyncedDb] tryGoOnline on becameLeader failed: ${err}`, err);
+              networkError(`[SyncedDb] tryGoOnline on becameLeader failed: ${err}`, err);
             });
           }
           if (config.onBecameLeader) {
@@ -5246,7 +5256,7 @@ var _SyncedDb = class _SyncedDb {
         await this.syncEngine.processCollectionServerData(collection, serverData, { source: "refresh" });
       }
     }).catch((err) => {
-      console.error(`[SyncedDb] referToServer failed for ${collection}:`, err);
+      networkError(`[SyncedDb] referToServer failed for ${collection}:`, err);
     });
   }
   /**
@@ -5267,7 +5277,7 @@ var _SyncedDb = class _SyncedDb {
       if (!serverItems || serverItems.length === 0) return;
       await this.syncEngine.processCollectionServerData(collection, serverItems, { source: "incremental" });
     }).catch((err) => {
-      console.error(`[SyncedDb] refreshInBackground failed for ${collection}:`, err);
+      networkError(`[SyncedDb] refreshInBackground failed for ${collection}:`, err);
     });
   }
   async ensureItemsAreLoaded(collection, ids, withDeleted) {
@@ -5532,7 +5542,7 @@ var _SyncedDb = class _SyncedDb {
             this.inMemManager.writeBatch(collection, [{ _id: item.id }], "delete", { source: "incremental" });
             results.push(true);
           } catch (err) {
-            console.error(`[SyncedDb] Failed to hard delete ${String(item.id)}:`, err);
+            networkError(`[SyncedDb] Failed to hard delete ${String(item.id)}:`, err);
             results.push(false);
           }
         }
@@ -5913,7 +5923,7 @@ var _SyncedDb = class _SyncedDb {
         for (const id of serverExits) evictIds.push(id);
         serverEvictedCount = serverExits.length;
       } catch (err) {
-        console.error(
+        networkError(
           `[SyncedDb] [evict] server-assisted pass failed for ${collection} (proceeding with local-only):`,
           err
         );
@@ -6030,7 +6040,7 @@ var _SyncedDb = class _SyncedDb {
         }
       } catch (err) {
         serverFailed = true;
-        console.error(
+        networkError(
           "[SyncedDb] [evict] server-assisted batch failed (proceeding with local-only):",
           err
         );
@@ -10113,7 +10123,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
     }
   }
   handleError(event) {
-    console.error(`[Ebus2ProxyNotifier] WebSocket error: ${event.type}`, event);
+    networkError(`[Ebus2ProxyNotifier] WebSocket error: ${event.type}`, event);
   }
   handleMessage(event) {
     try {
@@ -10234,7 +10244,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
       this.reconnectTimer = void 0;
       if (this.shouldReconnect && !this.forcedOffline) {
         this.createWebSocket().catch((err) => {
-          console.error(`[Ebus2ProxyNotifier] Reconnection failed: ${err}`, err);
+          networkError(`[Ebus2ProxyNotifier] Reconnection failed: ${err}`, err);
           this.currentReconnectDelay = Math.min(
             this.currentReconnectDelay * 2,
             this.maxReconnectDelayMs

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

@@ -0,0 +1,28 @@
+/**
+ * Log a failure at appropriate severity depending on perceived network
+ * connectivity.
+ *
+ * - **Online** (`navigator.onLine === true`, or `navigator` unavailable
+ *   like in Node/SSR): routes to `console.error`. Failures while the
+ *   browser thinks it's online are unexpected — operators should see
+ *   them.
+ * - **Offline** (`navigator.onLine === false`): routes to
+ *   `console.info`. Sync/upload/reconnect failures are the expected
+ *   steady-state and shouldn't pollute the error stream.
+ *
+ * Use this ONLY for sites whose failure reduces to "the network is
+ * down" — caller bugs, Dexie failures, parse errors, and consumer
+ * callback throws must keep using `console.error` directly so they're
+ * visible regardless of connectivity.
+ *
+ * Signature mirrors `console.error` — first arg is the tag-line string
+ * (per the console-reporting skill), remaining args are objects /
+ * values for devtools inspection.
+ *
+ * Caveat: `navigator.onLine` only tells you whether the browser has a
+ * network interface; it can't detect "WiFi connected but server
+ * unreachable". In that case this still routes to `console.error`,
+ * which is correct — the failure is unexpected from the browser's
+ * point of view.
+ */
+export declare function networkError(message: string, ...rest: unknown[]): void;

package/package.json

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