@electric-sql/client 1.1.2 → 1.1.4

package/README.md

@@ -99,26 +99,84 @@ shape.subscribe(({ rows }) => {
 
 ### Error Handling
 
-The ShapeStream provides two ways to handle errors:
+The ShapeStream provides robust error handling with automatic retry support:
 
-1. Using the `onError` handler:
+#### 1. Stream-level error handler with retry control
+
+The `onError` handler gives you full control over error recovery:
 
 ```typescript
 const stream = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
-  params: {
-    table: `foo`,
-  },
+  params: { table: `foo` },
   onError: (error) => {
-    // Handle all stream errors here
     console.error('Stream error:', error)
+
+    // IMPORTANT: Return an object to keep syncing!
+    // Return void/undefined to stop syncing permanently.
+
+    // Note: 5xx errors and network errors are automatically retried,
+    // so onError is mainly for handling client errors (4xx)
+
+    if (error instanceof FetchError) {
+      if (error.status === 401) {
+        // Unauthorized - refresh token and retry
+        const newToken = getRefreshedToken()
+        return {
+          headers: {
+            Authorization: `Bearer ${newToken}`,
+          },
+        }
+      }
+
+      if (error.status === 403) {
+        // Forbidden - maybe change user context
+        return {
+          params: {
+            table: `foo`,
+            where: `user_id = $1`,
+            params: [fallbackUserId],
+          },
+        }
+      }
+    }
+
+    // Stop syncing for other errors (return void)
   },
 })
 ```
 
-If no `onError` handler is provided, the ShapeStream will throw errors that occur during streaming.
+**Critical**: The `onError` callback's return value controls whether syncing continues:
 
-2. Individual subscribers can optionally handle errors specific to their subscription:
+- **Return an object** (even empty `{}`) to retry syncing:
+  - `{}` - Retry with same params and headers
+  - `{ params }` - Retry with modified params
+  - `{ headers }` - Retry with modified headers
+  - `{ params, headers }` - Retry with both modified
+- **Return void/undefined** to stop the stream permanently
+
+The handler supports async operations:
+
+```typescript
+onError: async (error) => {
+  if (error instanceof FetchError && error.status === 401) {
+    // Perform async token refresh
+    const newToken = await refreshAuthToken()
+    return {
+      headers: { Authorization: `Bearer ${newToken}` },
+    }
+  }
+  return {} // Retry other errors
+}
+```
+
+**Automatic retries**: The client automatically retries 5xx server errors, network errors, and 429 rate limits with exponential backoff. The `onError` callback is only invoked after these retries are exhausted, or for non-retryable errors like 4xx client errors.
+
+**Without `onError`**: If no `onError` handler is provided, non-retryable errors (like 4xx client errors) will be thrown and the stream will stop.
+
+#### 2. Subscription-level error callbacks
+
+Individual subscribers can handle errors specific to their subscription:
 
 ```typescript
 stream.subscribe(
@@ -132,7 +190,11 @@ stream.subscribe(
 )
 ```
 
-Common error types include:
+Note: Subscription error callbacks cannot control retry behavior - use the stream-level `onError` for that.
+
+#### Common Error Types
+
+Setup errors:
 
 - `MissingShapeUrlError`: Missing required URL parameter
 - `InvalidSignalError`: Invalid AbortSignal instance
@@ -140,12 +202,12 @@ Common error types include:
 
 Runtime errors:
 
-- `FetchError`: HTTP errors during shape fetching
+- `FetchError`: HTTP errors during shape fetching (includes `status`, `url`, `headers`)
 - `FetchBackoffAbortError`: Fetch aborted using AbortSignal
 - `MissingShapeHandleError`: Missing required shape handle
-- `ParserNullValueError`: Parser encountered NULL value in a column that doesn't allow NULL values
+- `ParserNullValueError`: NULL value in a non-nullable column
 
-See the [typescript client docs on the website](https://electric-sql.com/docs/api/clients/typescript#error-handling) for more details on error handling.
+See the [TypeScript client docs](https://electric-sql.com/docs/api/clients/typescript#error-handling) for more details.
 
 And in general, see the [docs website](https://electric-sql.com) and [examples](https://electric-sql.com/demos) for more information.
 

package/dist/cjs/index.cjs

@@ -353,6 +353,7 @@ var SUBSET_PARAM_ORDER_BY = `subset__order_by`;
 var SUBSET_PARAM_WHERE_PARAMS = `subset__params`;
 var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   LIVE_QUERY_PARAM,
+  LIVE_SSE_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   LIVE_CACHE_BUSTER_QUERY_PARAM,
@@ -369,16 +370,33 @@ var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
 var HTTP_RETRY_STATUS_CODES = [429];
 var BackoffDefaults = {
   initialDelay: 100,
-  maxDelay: 1e4,
-  multiplier: 1.3
+  maxDelay: 6e4,
+  // Cap at 60s - reasonable for long-lived connections
+  multiplier: 1.3,
+  maxRetries: Infinity
+  // Retry forever - clients may go offline and come back
 };
+function parseRetryAfterHeader(retryAfter) {
+  if (!retryAfter) return 0;
+  const retryAfterSec = Number(retryAfter);
+  if (Number.isFinite(retryAfterSec) && retryAfterSec > 0) {
+    return retryAfterSec * 1e3;
+  }
+  const retryDate = Date.parse(retryAfter);
+  if (!isNaN(retryDate)) {
+    const deltaMs = retryDate - Date.now();
+    return Math.max(0, Math.min(deltaMs, 36e5));
+  }
+  return 0;
+}
 function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
   const {
     initialDelay,
     maxDelay,
     multiplier,
     debug = false,
-    onFailedAttempt
+    onFailedAttempt,
+    maxRetries = Infinity
   } = backoffOptions;
   return (...args) => __async(this, null, function* () {
     var _a;
@@ -389,7 +407,9 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
     while (true) {
       try {
         const result = yield fetchClient(...args);
-        if (result.ok) return result;
+        if (result.ok) {
+          return result;
+        }
         const err = yield FetchError.fromResponse(result, url.toString());
         throw err;
       } catch (e) {
@@ -399,12 +419,27 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
         } else if (e instanceof FetchError && !HTTP_RETRY_STATUS_CODES.includes(e.status) && e.status >= 400 && e.status < 500) {
           throw e;
         } else {
-          yield new Promise((resolve) => setTimeout(resolve, delay));
-          delay = Math.min(delay * multiplier, maxDelay);
+          attempt++;
+          if (attempt > maxRetries) {
+            if (debug) {
+              console.log(
+                `Max retries reached (${attempt}/${maxRetries}), giving up`
+              );
+            }
+            throw e;
+          }
+          const serverMinimumMs = e instanceof FetchError && e.headers ? parseRetryAfterHeader(e.headers[`retry-after`]) : 0;
+          const jitter = Math.random() * delay;
+          const clientBackoffMs = Math.min(jitter, maxDelay);
+          const waitMs = Math.max(serverMinimumMs, clientBackoffMs);
           if (debug) {
-            attempt++;
-            console.log(`Retry attempt #${attempt} after ${delay}ms`);
+            const source = serverMinimumMs > 0 ? `server+client` : `client`;
+            console.log(
+              `Retry attempt #${attempt} after ${waitMs}ms (${source}, serverMin=${serverMinimumMs}ms, clientBackoff=${clientBackoffMs}ms)`
+            );
           }
+          yield new Promise((resolve) => setTimeout(resolve, waitMs));
+          delay = Math.min(delay * multiplier, maxDelay);
         }
       }
     }
@@ -775,9 +810,8 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _ShapeStream_instances, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn, fetchSnapshot_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _ShapeStream_instances, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn, fetchSnapshot_fn;
 var ShapeStream = class {
-  // Maximum delay cap (ms)
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
     __privateAdd(this, _error, null);
@@ -821,6 +855,8 @@ var ShapeStream = class {
     __privateAdd(this, _sseBackoffBaseDelay, 100);
     // Base delay for exponential backoff (ms)
     __privateAdd(this, _sseBackoffMaxDelay, 5e3);
+    // Maximum delay cap (ms)
+    __privateAdd(this, _unsubscribeFromVisibilityChanges);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -876,7 +912,9 @@ var ShapeStream = class {
     };
   }
   unsubscribeAll() {
+    var _a;
     __privateGet(this, _subscribers).clear();
+    (_a = __privateGet(this, _unsubscribeFromVisibilityChanges)) == null ? void 0 : _a.call(this);
   }
   /** Unix time at which we last synced. Undefined when `isLoading` is true. */
   lastSyncedAt() {
@@ -1003,6 +1041,7 @@ _maxShortSseConnections = new WeakMap();
 _sseFallbackToLongPolling = new WeakMap();
 _sseBackoffBaseDelay = new WeakMap();
 _sseBackoffMaxDelay = new WeakMap();
+_unsubscribeFromVisibilityChanges = new WeakMap();
 _ShapeStream_instances = new WeakSet();
 start_fn = function() {
   return __async(this, null, function* () {
@@ -1072,7 +1111,8 @@ requestShape_fn = function() {
         return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
       }
       if (e instanceof FetchBackoffAbortError) {
-        if (requestAbortController.signal.aborted && requestAbortController.signal.reason === PAUSE_STREAM) {
+        const currentState = __privateGet(this, _state);
+        if (requestAbortController.signal.aborted && requestAbortController.signal.reason === PAUSE_STREAM && currentState === `pause-requested`) {
           __privateSet(this, _state, `paused`);
         }
         return;
@@ -1333,7 +1373,10 @@ pause_fn = function() {
   }
 };
 resume_fn = function() {
-  if (__privateGet(this, _started) && __privateGet(this, _state) === `paused`) {
+  if (__privateGet(this, _started) && (__privateGet(this, _state) === `paused` || __privateGet(this, _state) === `pause-requested`)) {
+    if (__privateGet(this, _state) === `pause-requested`) {
+      __privateSet(this, _state, `active`);
+    }
     __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
   }
 };
@@ -1405,6 +1448,9 @@ subscribeToVisibilityChanges_fn = function() {
       }
     };
     document.addEventListener(`visibilitychange`, visibilityHandler);
+    __privateSet(this, _unsubscribeFromVisibilityChanges, () => {
+      document.removeEventListener(`visibilitychange`, visibilityHandler);
+    });
   }
 };
 /**