@electric-sql/client 1.0.14 → 1.1.1

package/dist/index.d.ts

@@ -135,16 +135,38 @@ 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.
+     *
+     * 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";
@@ -278,9 +300,13 @@ interface ShapeStreamOptions<T = never> {
      */
     subscribe?: boolean;
     /**
-     * Experimental support for Server-Sent Events (SSE) for live updates.
+     * @deprecated No longer experimental, use {@link liveSse} instead.
      */
     experimentalLiveSse?: boolean;
+    /**
+     * Use Server-Sent Events (SSE) for live updates.
+     */
+    liveSse?: boolean;
     /**
      * Initial data loading mode
      */
@@ -348,7 +374,7 @@ interface ShapeStreamInterface<T extends Row<unknown> = Row> {
  * ```
  * const stream = new ShapeStream({
  *   url: `http://localhost:3000/v1/shape`,
- *   experimentalLiveSse: true
+ *   liveSse: true
  * })
  * ```
  *

package/dist/index.legacy-esm.js

@@ -289,6 +289,7 @@ var WHERE_QUERY_PARAM = `where`;
 var REPLICA_PARAM = `replica`;
 var WHERE_PARAMS_PARAM = `params`;
 var EXPERIMENTAL_LIVE_SSE_QUERY_PARAM = `experimental_live_sse`;
+var LIVE_SSE_QUERY_PARAM = `live_sse`;
 var FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`;
 var PAUSE_STREAM = `pause-stream`;
 var LOG_MODE_QUERY_PARAM = `log`;
@@ -315,8 +316,13 @@ 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
+  retryBudgetPercent: 0.1
+  // 10% retry budget prevents amplification
 };
 function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
   const {
@@ -324,8 +330,29 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
     maxDelay,
     multiplier,
     debug = false,
-    onFailedAttempt
+    onFailedAttempt,
+    maxRetries = Infinity,
+    retryBudgetPercent = 0.1
   } = 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];
@@ -335,7 +362,10 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
     while (true) {
       try {
         const result = await fetchClient(...args);
-        if (result.ok) return result;
+        if (result.ok) {
+          delay = initialDelay;
+          return result;
+        }
         const err = await FetchError.fromResponse(result, url.toString());
         throw err;
       } catch (e) {
@@ -345,12 +375,51 @@ 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;
+          }
+          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 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);
         }
       }
     }
@@ -359,6 +428,7 @@ function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
 var NO_BODY_STATUS_CODES = [201, 204, 205];
 function createFetchWithConsumedMessages(fetchClient) {
   return async (...args) => {
+    var _a, _b;
     const url = args[0];
     const res = await fetchClient(...args);
     try {
@@ -368,6 +438,9 @@ function createFetchWithConsumedMessages(fetchClient) {
       const text = await res.text();
       return new Response(text, res);
     } catch (err) {
+      if ((_b = (_a = args[1]) == null ? void 0 : _a.signal) == null ? void 0 : _b.aborted) {
+        throw new FetchBackoffAbortError();
+      }
       throw new FetchError(
         res.status,
         void 0,
@@ -986,7 +1059,7 @@ requestShape_fn = async function() {
       }
       const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER] || `${__privateGet(this, _shapeHandle)}-next`;
       __privateMethod(this, _ShapeStream_instances, reset_fn).call(this, newShapeHandle);
-      await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, e.json);
+      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);
@@ -1129,8 +1202,11 @@ onMessages_fn = async function(batch, isSseMessage = false) {
   }
 };
 fetchShape_fn = async function(opts) {
-  if (__privateGet(this, _isUpToDate) && this.options.experimentalLiveSse && !__privateGet(this, _isRefreshing) && !opts.resumingFromPause) {
+  var _a;
+  const useSse = (_a = this.options.liveSse) != null ? _a : this.options.experimentalLiveSse;
+  if (__privateGet(this, _isUpToDate) && useSse && !__privateGet(this, _isRefreshing) && !opts.resumingFromPause) {
     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);
   }
   return __privateMethod(this, _ShapeStream_instances, requestShapeLongPoll_fn).call(this, opts);