@electric-sql/client 1.1.1 → 1.1.3

package/dist/index.d.ts

@@ -145,28 +145,14 @@ interface BackoffOptions {
      * 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.
-     *
-     * The retry budget provides protection against retry storms even with infinite retries.
      */
     maxRetries?: number;
-    /**
-     * Percentage of requests that can be retries (0.1 = 10%)
-     *
-     * This is the primary load shedding mechanism. It limits the *rate* of retries,
-     * not the total count. Even with infinite retries, at most 10% of your traffic
-     * will be retries, preventing retry storms from amplifying server load.
-     *
-     * The budget resets every 60 seconds, so a temporary spike of errors won't
-     * permanently exhaust the budget.
-     */
-    retryBudgetPercent?: number;
 }
 declare const BackoffDefaults: {
     initialDelay: number;
     maxDelay: number;
     multiplier: number;
     maxRetries: number;
-    retryBudgetPercent: number;
 };
 
 declare const LIVE_CACHE_BUSTER_QUERY_PARAM = "cursor";
@@ -318,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,
@@ -319,11 +320,22 @@ var BackoffDefaults = {
   maxDelay: 6e4,
   // Cap at 60s - reasonable for long-lived connections
   multiplier: 1.3,
-  maxRetries: Infinity,
+  maxRetries: Infinity
   // Retry forever - clients may go offline and come back
-  retryBudgetPercent: 0.1
-  // 10% retry budget prevents amplification
 };
+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,
@@ -331,28 +343,8 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
     multiplier,
     debug = false,
     onFailedAttempt,
-    maxRetries = Infinity,
-    retryBudgetPercent = 0.1
+    maxRetries = Infinity
   } = backoffOptions;
-  let totalRequests = 0;
-  let totalRetries = 0;
-  let budgetResetTime = Date.now() + 6e4;
-  function checkRetryBudget(percent) {
-    const now = Date.now();
-    if (now > budgetResetTime) {
-      totalRequests = 0;
-      totalRetries = 0;
-      budgetResetTime = now + 6e4;
-    }
-    totalRequests++;
-    if (totalRequests < 10) return true;
-    const currentRetryRate = totalRetries / totalRequests;
-    const hasCapacity = currentRetryRate < percent;
-    if (hasCapacity) {
-      totalRetries++;
-    }
-    return hasCapacity;
-  }
   return async (...args) => {
     var _a;
     const url = args[0];
@@ -363,7 +355,6 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
       try {
         const result = await fetchClient(...args);
         if (result.ok) {
-          delay = initialDelay;
           return result;
         }
         const err = await FetchError.fromResponse(result, url.toString());
@@ -376,7 +367,7 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
           throw e;
         } else {
           attempt++;
-          if (attempt >= maxRetries) {
+          if (attempt > maxRetries) {
             if (debug) {
               console.log(
                 `Max retries reached (${attempt}/${maxRetries}), giving up`
@@ -384,31 +375,7 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
             }
             throw e;
           }
-          if (!checkRetryBudget(retryBudgetPercent)) {
-            if (debug) {
-              console.log(
-                `Retry budget exhausted (attempt ${attempt}), backing off`
-              );
-            }
-            await new Promise((resolve) => setTimeout(resolve, maxDelay));
-            continue;
-          }
-          let serverMinimumMs = 0;
-          if (e instanceof FetchError && e.headers) {
-            const retryAfter = e.headers[`retry-after`];
-            if (retryAfter) {
-              const retryAfterSec = Number(retryAfter);
-              if (Number.isFinite(retryAfterSec) && retryAfterSec > 0) {
-                serverMinimumMs = retryAfterSec * 1e3;
-              } else {
-                const retryDate = Date.parse(retryAfter);
-                if (!isNaN(retryDate)) {
-                  const deltaMs = retryDate - Date.now();
-                  serverMinimumMs = Math.max(0, Math.min(deltaMs, 36e5));
-                }
-              }
-            }
-          }
+          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);
@@ -784,8 +751,9 @@ 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, _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, _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);
@@ -819,6 +787,16 @@ var ShapeStream = class {
     // counter for concurrent snapshot requests
     __privateAdd(this, _midStreamPromise);
     __privateAdd(this, _midStreamPromiseResolver);
+    __privateAdd(this, _lastSseConnectionStartTime);
+    __privateAdd(this, _minSseConnectionDuration, 1e3);
+    // Minimum expected SSE connection duration (1 second)
+    __privateAdd(this, _consecutiveShortSseConnections, 0);
+    __privateAdd(this, _maxShortSseConnections, 3);
+    // Fall back to long polling after this many short connections
+    __privateAdd(this, _sseFallbackToLongPolling, false);
+    __privateAdd(this, _sseBackoffBaseDelay, 100);
+    // Base delay for exponential backoff (ms)
+    __privateAdd(this, _sseBackoffMaxDelay, 5e3);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -990,9 +968,16 @@ _snapshotTracker = new WeakMap();
 _activeSnapshotRequests = new WeakMap();
 _midStreamPromise = new WeakMap();
 _midStreamPromiseResolver = new WeakMap();
+_lastSseConnectionStartTime = new WeakMap();
+_minSseConnectionDuration = new WeakMap();
+_consecutiveShortSseConnections = new WeakMap();
+_maxShortSseConnections = new WeakMap();
+_sseFallbackToLongPolling = new WeakMap();
+_sseBackoffBaseDelay = new WeakMap();
+_sseBackoffMaxDelay = new WeakMap();
 _ShapeStream_instances = new WeakSet();
 start_fn = async function() {
-  var _a;
+  var _a, _b, _c, _d, _e;
   __privateSet(this, _started, true);
   try {
     await __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
@@ -1000,24 +985,34 @@ start_fn = async function() {
     __privateSet(this, _error, err);
     if (__privateGet(this, _onError)) {
       const retryOpts = await __privateGet(this, _onError).call(this, err);
-      if (typeof retryOpts === `object`) {
-        __privateMethod(this, _ShapeStream_instances, reset_fn).call(this);
-        if (`params` in retryOpts) {
-          this.options.params = retryOpts.params;
+      if (retryOpts && typeof retryOpts === `object`) {
+        if (retryOpts.params) {
+          this.options.params = __spreadValues(__spreadValues({}, (_a = this.options.params) != null ? _a : {}), retryOpts.params);
         }
-        if (`headers` in retryOpts) {
-          this.options.headers = retryOpts.headers;
+        if (retryOpts.headers) {
+          this.options.headers = __spreadValues(__spreadValues({}, (_b = this.options.headers) != null ? _b : {}), retryOpts.headers);
         }
+        __privateSet(this, _error, null);
         __privateSet(this, _started, false);
-        __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
+        await __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
+        return;
+      }
+      if (err instanceof Error) {
+        __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, err);
       }
+      __privateSet(this, _connected, false);
+      (_c = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _c.call(this);
       return;
     }
-    throw err;
-  } finally {
+    if (err instanceof Error) {
+      __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, err);
+    }
     __privateSet(this, _connected, false);
-    (_a = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _a.call(this);
+    (_d = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _d.call(this);
+    throw err;
   }
+  __privateSet(this, _connected, false);
+  (_e = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _e.call(this);
 };
 requestShape_fn = async function() {
   var _a, _b;
@@ -1062,7 +1057,6 @@ requestShape_fn = async function() {
       await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, Array.isArray(e.json) ? e.json : [e.json]);
       return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
     } else {
-      __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, e);
       throw e;
     }
   } finally {
@@ -1204,7 +1198,7 @@ onMessages_fn = async function(batch, isSseMessage = false) {
 fetchShape_fn = async function(opts) {
   var _a;
   const useSse = (_a = this.options.liveSse) != null ? _a : this.options.experimentalLiveSse;
-  if (__privateGet(this, _isUpToDate) && useSse && !__privateGet(this, _isRefreshing) && !opts.resumingFromPause) {
+  if (__privateGet(this, _isUpToDate) && useSse && !__privateGet(this, _isRefreshing) && !opts.resumingFromPause && !__privateGet(this, _sseFallbackToLongPolling)) {
     opts.fetchUrl.searchParams.set(EXPERIMENTAL_LIVE_SSE_QUERY_PARAM, `true`);
     opts.fetchUrl.searchParams.set(LIVE_SSE_QUERY_PARAM, `true`);
     return __privateMethod(this, _ShapeStream_instances, requestShapeSSE_fn).call(this, opts);
@@ -1228,6 +1222,7 @@ requestShapeLongPoll_fn = async function(opts) {
 requestShapeSSE_fn = async function(opts) {
   const { fetchUrl, requestAbortController, headers } = opts;
   const fetch2 = __privateGet(this, _sseFetchClient);
+  __privateSet(this, _lastSseConnectionStartTime, Date.now());
   try {
     let buffer = [];
     await fetchEventSource(fetchUrl.toString(), {
@@ -1261,6 +1256,27 @@ requestShapeSSE_fn = async function(opts) {
       throw new FetchBackoffAbortError();
     }
     throw error;
+  } finally {
+    const connectionDuration = Date.now() - __privateGet(this, _lastSseConnectionStartTime);
+    const wasAborted = requestAbortController.signal.aborted;
+    if (connectionDuration < __privateGet(this, _minSseConnectionDuration) && !wasAborted) {
+      __privateWrapper(this, _consecutiveShortSseConnections)._++;
+      if (__privateGet(this, _consecutiveShortSseConnections) >= __privateGet(this, _maxShortSseConnections)) {
+        __privateSet(this, _sseFallbackToLongPolling, true);
+        console.warn(
+          `[Electric] SSE connections are closing immediately (possibly due to proxy buffering or misconfiguration). Falling back to long polling. Your proxy must support streaming SSE responses (not buffer the complete response). Configuration: Nginx add 'X-Accel-Buffering: no', Caddy add 'flush_interval -1' to reverse_proxy. Note: Do NOT disable caching entirely - Electric uses cache headers to enable request collapsing for efficiency.`
+        );
+      } else {
+        const maxDelay = Math.min(
+          __privateGet(this, _sseBackoffMaxDelay),
+          __privateGet(this, _sseBackoffBaseDelay) * Math.pow(2, __privateGet(this, _consecutiveShortSseConnections))
+        );
+        const delayMs = Math.floor(Math.random() * maxDelay);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    } else if (connectionDuration >= __privateGet(this, _minSseConnectionDuration)) {
+      __privateSet(this, _consecutiveShortSseConnections, 0);
+    }
   }
 };
 pause_fn = function() {
@@ -1352,6 +1368,8 @@ reset_fn = function(handle) {
   __privateSet(this, _connected, false);
   __privateSet(this, _schema, void 0);
   __privateSet(this, _activeSnapshotRequests, 0);
+  __privateSet(this, _consecutiveShortSseConnections, 0);
+  __privateSet(this, _sseFallbackToLongPolling, false);
 };
 fetchSnapshot_fn = async function(url, headers) {
   const response = await __privateGet(this, _fetchClient2).call(this, url.toString(), { headers });