@electric-sql/client 1.1.2 → 1.1.3

package/dist/index.d.ts

@@ -135,16 +135,24 @@ interface BackoffOptions {
     initialDelay: number;
     /**
      * Maximum retry delay in milliseconds
+     * After reaching this, delay stays constant (e.g., retry every 60s)
      */
     maxDelay: number;
     multiplier: number;
     onFailedAttempt?: () => void;
     debug?: boolean;
+    /**
+     * Maximum number of retry attempts before giving up.
+     * Set to Infinity (default) for indefinite retries - needed for offline scenarios
+     * where clients may go offline and come back later.
+     */
+    maxRetries?: number;
 }
 declare const BackoffDefaults: {
     initialDelay: number;
     maxDelay: number;
     multiplier: number;
+    maxRetries: number;
 };
 
 declare const LIVE_CACHE_BUSTER_QUERY_PARAM = "cursor";
@@ -296,10 +304,51 @@ interface ShapeStreamOptions<T = never> {
     transformer?: TransformFunction<T>;
     /**
      * A function for handling shapestream errors.
-     * This is optional, when it is not provided any shapestream errors will be thrown.
-     * If the function returns an object containing parameters and/or headers
-     * the shapestream will apply those changes and try syncing again.
-     * If the function returns void the shapestream is stopped.
+     *
+     * **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 automatic retries are exhausted, or for non-retryable
+     * errors like 4xx client errors.
+     *
+     * When not provided, non-retryable errors will be thrown and syncing will stop.
+     *
+     * **Return value behavior**:
+     * - Return an **object** (RetryOpts or empty `{}`) to retry syncing:
+     *   - `{}` - Retry with the same params and headers
+     *   - `{ params }` - Retry with modified params
+     *   - `{ headers }` - Retry with modified headers (e.g., refreshed auth token)
+     *   - `{ params, headers }` - Retry with both modified
+     * - Return **void** or **undefined** to stop the stream permanently
+     *
+     * **Important**: If you want syncing to continue after an error (e.g., to retry
+     * on network failures), you MUST return at least an empty object `{}`. Simply
+     * logging the error and returning nothing will stop syncing.
+     *
+     * Supports async functions that return `Promise<void | RetryOpts>`.
+     *
+     * @example
+     * ```typescript
+     * // Retry on network errors, stop on others
+     * onError: (error) => {
+     *   console.error('Stream error:', error)
+     *   if (error instanceof FetchError && error.status >= 500) {
+     *     return {} // Retry with same params
+     *   }
+     *   // Return void to stop on other errors
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Refresh auth token on 401
+     * onError: async (error) => {
+     *   if (error instanceof FetchError && error.status === 401) {
+     *     const newToken = await refreshAuthToken()
+     *     return { headers: { Authorization: `Bearer ${newToken}` } }
+     *   }
+     *   return {} // Retry other errors
+     * }
+     * ```
      */
     onError?: ShapeStreamErrorHandler;
 }

package/dist/index.legacy-esm.js

@@ -300,6 +300,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,
@@ -316,16 +317,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 async (...args) => {
     var _a;
@@ -336,7 +354,9 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
     while (true) {
       try {
         const result = await fetchClient(...args);
-        if (result.ok) return result;
+        if (result.ok) {
+          return result;
+        }
         const err = await FetchError.fromResponse(result, url.toString());
         throw err;
       } catch (e) {
@@ -346,12 +366,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 {
-          await 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)`
+            );
           }
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+          delay = Math.min(delay * multiplier, maxDelay);
         }
       }
     }