@electric-sql/client 1.5.0 → 1.5.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -51,6 +51,7 @@ import {
   REPLICA_PARAM,
   FORCE_DISCONNECT_AND_REFRESH,
   PAUSE_STREAM,
+  SYSTEM_WAKE,
   EXPERIMENTAL_LIVE_SSE_QUERY_PARAM,
   LIVE_SSE_QUERY_PARAM,
   ELECTRIC_PROTOCOL_QUERY_PARAMS,
@@ -598,6 +599,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #sseBackoffBaseDelay = 100 // Base delay for exponential backoff (ms)
   #sseBackoffMaxDelay = 5000 // Maximum delay cap (ms)
   #unsubscribeFromVisibilityChanges?: () => void
+  #unsubscribeFromWakeDetection?: () => void
   #staleCacheBuster?: string // Cache buster set when stale CDN response detected, used on retry requests to bypass cache
   #staleCacheRetryCount = 0
   #maxStaleCacheRetries = 3
@@ -666,6 +668,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.#fetchClient = createFetchWithConsumedMessages(this.#sseFetchClient)
 
     this.#subscribeToVisibilityChanges()
+    this.#subscribeToWakeDetection()
   }
 
   get shapeHandle() {
@@ -735,6 +738,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
         }
         this.#connected = false
         this.#tickPromiseRejecter?.()
+        this.#unsubscribeFromWakeDetection?.()
         return
       }
 
@@ -745,12 +749,14 @@ export class ShapeStream<T extends Row<unknown> = Row>
       }
       this.#connected = false
       this.#tickPromiseRejecter?.()
+      this.#unsubscribeFromWakeDetection?.()
       throw err
     }
 
     // Normal completion, clean up
     this.#connected = false
     this.#tickPromiseRejecter?.()
+    this.#unsubscribeFromWakeDetection?.()
   }
 
   async #requestShape(): Promise<void> {
@@ -785,13 +791,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
         resumingFromPause,
       })
     } catch (e) {
-      // Handle abort error triggered by refresh
+      const abortReason = requestAbortController.signal.reason
+      const isRestartAbort =
+        requestAbortController.signal.aborted &&
+        (abortReason === FORCE_DISCONNECT_AND_REFRESH ||
+          abortReason === SYSTEM_WAKE)
+
       if (
         (e instanceof FetchError || e instanceof FetchBackoffAbortError) &&
-        requestAbortController.signal.aborted &&
-        requestAbortController.signal.reason === FORCE_DISCONNECT_AND_REFRESH
+        isRestartAbort
       ) {
-        // Start a new request
         return this.#requestShape()
       }
 
@@ -1118,13 +1127,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
             `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
         )
       } else {
+        // We already have a valid handle, so ignore the stale response entirely
+        // to prevent a mismatch between our current handle and the stale offset.
         console.warn(
           `[Electric] Received stale cached response with expired shape handle. ` +
             `This should not happen and indicates a proxy/CDN caching misconfiguration. ` +
             `The response contained handle "${shapeHandle}" which was previously marked as expired. ` +
             `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. ` +
-            `Ignoring the stale handle and continuing with handle "${this.#shapeHandle}".`
+            `Ignoring the stale response and continuing with handle "${this.#shapeHandle}".`
         )
+        return
       }
     }
 
@@ -1429,6 +1441,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   unsubscribeAll(): void {
     this.#subscribers.clear()
     this.#unsubscribeFromVisibilityChanges?.()
+    this.#unsubscribeFromWakeDetection?.()
   }
 
   /** Unix time at which we last synced. Undefined when `isLoading` is true. */
@@ -1540,12 +1553,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
     })
   }
 
-  #subscribeToVisibilityChanges() {
-    if (
+  #hasBrowserVisibilityAPI(): boolean {
+    return (
       typeof document === `object` &&
       typeof document.hidden === `boolean` &&
       typeof document.addEventListener === `function`
-    ) {
+    )
+  }
+
+  #subscribeToVisibilityChanges() {
+    if (this.#hasBrowserVisibilityAPI()) {
       const visibilityHandler = () => {
         if (document.hidden) {
           this.#pause()
@@ -1563,6 +1580,52 @@ export class ShapeStream<T extends Row<unknown> = Row>
     }
   }
 
+  /**
+   * Detects system wake from sleep using timer gap detection.
+   * When the system sleeps, setInterval timers are paused. On wake,
+   * the elapsed wall-clock time since the last tick will be much larger
+   * than the interval period, indicating the system was asleep.
+   *
+   * Only active in non-browser environments (Bun, Node.js) where
+   * `document.visibilitychange` is not available. In browsers,
+   * `#subscribeToVisibilityChanges` handles this instead. Without wake
+   * detection, in-flight HTTP requests (long-poll or SSE) may hang until
+   * the OS TCP timeout.
+   */
+  #subscribeToWakeDetection() {
+    if (this.#hasBrowserVisibilityAPI()) return
+
+    const INTERVAL_MS = 2_000
+    const WAKE_THRESHOLD_MS = 4_000
+
+    let lastTickTime = Date.now()
+
+    const timer = setInterval(() => {
+      const now = Date.now()
+      const elapsed = now - lastTickTime
+      lastTickTime = now
+
+      if (elapsed > INTERVAL_MS + WAKE_THRESHOLD_MS) {
+        if (this.#state === `active` && this.#requestAbortController) {
+          this.#isRefreshing = true
+          this.#requestAbortController.abort(SYSTEM_WAKE)
+          queueMicrotask(() => {
+            this.#isRefreshing = false
+          })
+        }
+      }
+    }, INTERVAL_MS)
+
+    // Ensure the timer doesn't prevent the process from exiting
+    if (typeof timer === `object` && `unref` in timer) {
+      timer.unref()
+    }
+
+    this.#unsubscribeFromWakeDetection = () => {
+      clearInterval(timer)
+    }
+  }
+
   /**
    * Resets the state of the stream, optionally with a provided
    * shape handle
@@ -1687,8 +1750,32 @@ export class ShapeStream<T extends Row<unknown> = Row>
       fetchOptions = { headers: result.requestHeaders }
     }
 
-    const response = await this.#fetchClient(fetchUrl.toString(), fetchOptions)
+    // Capture handle before fetch to avoid race conditions if it changes during the request
+    const usedHandle = this.#shapeHandle
+
+    let response: Response
+    try {
+      response = await this.#fetchClient(fetchUrl.toString(), fetchOptions)
+    } catch (e) {
+      // Handle 409 "must-refetch" - shape handle changed/expired.
+      // The fetch wrapper throws FetchError for non-OK responses, so we catch here.
+      // Unlike #requestShape, we don't call #reset() here as that would
+      // clear #activeSnapshotRequests and break requestSnapshot's pause/resume logic.
+      if (e instanceof FetchError && e.status === 409) {
+        if (usedHandle) {
+          const shapeKey = canonicalShapeKey(fetchUrl)
+          expiredShapesCache.markExpired(shapeKey, usedHandle)
+        }
+
+        this.#shapeHandle =
+          e.headers[SHAPE_HANDLE_HEADER] || `${usedHandle ?? `handle`}-next`
+
+        return this.fetchSnapshot(opts)
+      }
+      throw e
+    }
 
+    // Handle non-OK responses from custom fetch clients that bypass the wrapper chain
     if (!response.ok) {
       throw await FetchError.fromResponse(response, fetchUrl.toString())
     }

package/src/constants.ts

@@ -20,6 +20,7 @@ export const EXPERIMENTAL_LIVE_SSE_QUERY_PARAM = `experimental_live_sse`
 export const LIVE_SSE_QUERY_PARAM = `live_sse`
 export const FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`
 export const PAUSE_STREAM = `pause-stream`
+export const SYSTEM_WAKE = `system-wake`
 export const LOG_MODE_QUERY_PARAM = `log`
 export const SUBSET_PARAM_WHERE = `subset__where`
 export const SUBSET_PARAM_LIMIT = `subset__limit`