@electric-sql/client 1.5.12 → 1.5.13

package/dist/cjs/index.cjs

@@ -678,11 +678,11 @@ function createFetchWithChunkBuffer(fetchClient, prefetchOptions = ChunkPrefetch
   return prefetchClient;
 }
 var requiredElectricResponseHeaders = [
-  `electric-offset`,
-  `electric-handle`
+  CHUNK_LAST_OFFSET_HEADER,
+  SHAPE_HANDLE_HEADER
 ];
-var requiredLiveResponseHeaders = [`electric-cursor`];
-var requiredNonLiveResponseHeaders = [`electric-schema`];
+var requiredLiveResponseHeaders = [LIVE_CACHE_BUSTER_HEADER];
+var requiredNonLiveResponseHeaders = [SHAPE_SCHEMA_HEADER];
 function createFetchWithResponseHeadersCheck(fetchClient) {
   return async (...args) => {
     const response = await fetchClient(...args);
@@ -1473,18 +1473,15 @@ var ActiveState = class extends ShapeStreamState {
     if (!responseHandle || responseHandle !== expiredHandle) {
       return null;
     }
-    if (__privateGet(this, _shared).handle === void 0 || __privateGet(this, _shared).handle === expiredHandle) {
-      const retryCount = this.staleCacheRetryCount + 1;
-      return {
-        action: `stale-retry`,
-        state: new StaleRetryState(__spreadProps(__spreadValues({}, this.currentFields), {
-          staleCacheBuster: input.createCacheBuster(),
-          staleCacheRetryCount: retryCount
-        })),
-        exceededMaxRetries: retryCount > input.maxStaleCacheRetries
-      };
-    }
-    return { action: `ignored`, state: this };
+    const retryCount = this.staleCacheRetryCount + 1;
+    return {
+      action: `stale-retry`,
+      state: new StaleRetryState(__spreadProps(__spreadValues({}, this.currentFields), {
+        staleCacheBuster: input.createCacheBuster(),
+        staleCacheRetryCount: retryCount
+      })),
+      exceededMaxRetries: retryCount > input.maxStaleCacheRetries
+    };
   }
   // --- handleMessageBatch: template method with onUpToDate override point ---
   handleMessageBatch(input) {
@@ -1983,7 +1980,7 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _syncState, _connected, _mode, _onError, _requestAbortController, _refreshCount, _snapshotCounter, _ShapeStream_instances, isRefreshing_get, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _pauseLock, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _maxShortSseConnections, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _unsubscribeFromWakeDetection, _maxStaleCacheRetries, _recentRequestEntries, _fastLoopWindowMs, _fastLoopThreshold, _fastLoopBackoffBaseMs, _fastLoopBackoffMaxMs, _fastLoopConsecutiveCount, _fastLoopMaxCount, _refetchCacheBuster, start_fn, teardown_fn, requestShape_fn, checkFastLoop_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, nextTick_fn, publish_fn, sendErrorToSubscribers_fn, hasBrowserVisibilityAPI_fn, subscribeToVisibilityChanges_fn, subscribeToWakeDetection_fn, reset_fn, buildSubsetBody_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _syncState, _connected, _mode, _onError, _requestAbortController, _refreshCount, _snapshotCounter, _ShapeStream_instances, isRefreshing_get, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _pauseLock, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _maxShortSseConnections, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _unsubscribeFromWakeDetection, _maxStaleCacheRetries, _recentRequestEntries, _fastLoopWindowMs, _fastLoopThreshold, _fastLoopBackoffBaseMs, _fastLoopBackoffMaxMs, _fastLoopConsecutiveCount, _fastLoopMaxCount, _pendingRequestShapeCacheBuster, _maxSnapshotRetries, start_fn, teardown_fn, requestShape_fn, checkFastLoop_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, nextTick_fn, publish_fn, sendErrorToSubscribers_fn, hasBrowserVisibilityAPI_fn, subscribeToVisibilityChanges_fn, subscribeToWakeDetection_fn, reset_fn, fetchSnapshotWithRetry_fn, buildSubsetBody_fn;
 var ShapeStream = class {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
@@ -2030,7 +2027,8 @@ var ShapeStream = class {
     __privateAdd(this, _fastLoopBackoffMaxMs, 5e3);
     __privateAdd(this, _fastLoopConsecutiveCount, 0);
     __privateAdd(this, _fastLoopMaxCount, 5);
-    __privateAdd(this, _refetchCacheBuster);
+    __privateAdd(this, _pendingRequestShapeCacheBuster);
+    __privateAdd(this, _maxSnapshotRetries, 5);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -2188,7 +2186,8 @@ var ShapeStream = class {
     __privateGet(this, _pauseLock).acquire(snapshotReason);
     const snapshotWarnTimer = setTimeout(() => {
       console.warn(
-        `[Electric] Snapshot "${snapshotReason}" has held the pause lock for 30s \u2014 possible hung request or leaked lock. Current holders: ${[.../* @__PURE__ */ new Set([snapshotReason])].join(`, `)}`
+        `[Electric] Snapshot "${snapshotReason}" has held the pause lock for 30s \u2014 possible hung request or leaked lock. Current holders: ${[.../* @__PURE__ */ new Set([snapshotReason])].join(`, `)}`,
+        new Error(`stack trace`)
       );
     }, 3e4);
     try {
@@ -2217,7 +2216,8 @@ var ShapeStream = class {
           __privateSet(this, _syncState, transition.state);
         } else {
           console.warn(
-            `[Electric] Snapshot response metadata was not accepted by state "${__privateGet(this, _syncState).kind}" (action: ${transition.action}). Stream offset was not advanced from snapshot.`
+            `[Electric] Snapshot response metadata was not accepted by state "${__privateGet(this, _syncState).kind}" (action: ${transition.action}). Stream offset was not advanced from snapshot.`,
+            new Error(`stack trace`)
           );
         }
       }
@@ -2242,64 +2242,7 @@ var ShapeStream = class {
    * @returns The metadata, data, and the response's offset/handle for state advancement.
    */
   async fetchSnapshot(opts) {
-    var _a, _b, _c;
-    const method = (_b = (_a = opts.method) != null ? _a : this.options.subsetMethod) != null ? _b : `GET`;
-    const usePost = method === `POST`;
-    let fetchUrl;
-    let fetchOptions;
-    if (usePost) {
-      const result = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true);
-      fetchUrl = result.fetchUrl;
-      fetchOptions = {
-        method: `POST`,
-        headers: __spreadProps(__spreadValues({}, result.requestHeaders), {
-          "Content-Type": `application/json`
-        }),
-        body: bigintSafeStringify(__privateMethod(this, _ShapeStream_instances, buildSubsetBody_fn).call(this, opts))
-      };
-    } else {
-      const result = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
-      fetchUrl = result.fetchUrl;
-      fetchOptions = { headers: result.requestHeaders };
-    }
-    const usedHandle = __privateGet(this, _syncState).handle;
-    let response;
-    try {
-      response = await __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), fetchOptions);
-    } catch (e) {
-      if (e instanceof FetchError && e.status === 409) {
-        if (usedHandle) {
-          const shapeKey = canonicalShapeKey(fetchUrl);
-          expiredShapesCache.markExpired(shapeKey, usedHandle);
-        }
-        const nextHandle = e.headers[SHAPE_HANDLE_HEADER];
-        if (nextHandle) {
-          __privateSet(this, _syncState, __privateGet(this, _syncState).withHandle(nextHandle));
-        } else {
-          console.warn(
-            `[Electric] Received 409 response without a shape handle header. This likely indicates a proxy or CDN stripping required headers.`
-          );
-          __privateSet(this, _refetchCacheBuster, createCacheBuster());
-        }
-        return this.fetchSnapshot(opts);
-      }
-      throw e;
-    }
-    if (!response.ok) {
-      throw await FetchError.fromResponse(response, fetchUrl.toString());
-    }
-    const schema = (_c = __privateGet(this, _syncState).schema) != null ? _c : getSchemaFromHeaders(response.headers, {
-      required: true,
-      url: fetchUrl.toString()
-    });
-    const { metadata, data: rawData } = await response.json();
-    const data = __privateGet(this, _messageParser).parseSnapshotData(
-      rawData,
-      schema
-    );
-    const responseOffset = response.headers.get(CHUNK_LAST_OFFSET_HEADER) || null;
-    const responseHandle = response.headers.get(SHAPE_HANDLE_HEADER);
-    return { metadata, data, responseOffset, responseHandle };
+    return __privateMethod(this, _ShapeStream_instances, fetchSnapshotWithRetry_fn).call(this, opts, 0);
   }
 };
 _error = new WeakMap();
@@ -2341,7 +2284,8 @@ _fastLoopBackoffBaseMs = new WeakMap();
 _fastLoopBackoffMaxMs = new WeakMap();
 _fastLoopConsecutiveCount = new WeakMap();
 _fastLoopMaxCount = new WeakMap();
-_refetchCacheBuster = new WeakMap();
+_pendingRequestShapeCacheBuster = new WeakMap();
+_maxSnapshotRetries = new WeakMap();
 start_fn = async function() {
   var _a, _b;
   __privateSet(this, _started, true);
@@ -2393,9 +2337,15 @@ teardown_fn = function() {
   (_a = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _a.call(this);
   (_b = __privateGet(this, _unsubscribeFromWakeDetection)) == null ? void 0 : _b.call(this);
 };
-requestShape_fn = async function() {
+requestShape_fn = async function(requestShapeCacheBuster) {
   var _a, _b;
-  if (__privateGet(this, _pauseLock).isPaused) return;
+  const activeCacheBuster = requestShapeCacheBuster != null ? requestShapeCacheBuster : __privateGet(this, _pendingRequestShapeCacheBuster);
+  if (__privateGet(this, _pauseLock).isPaused) {
+    if (activeCacheBuster) {
+      __privateSet(this, _pendingRequestShapeCacheBuster, activeCacheBuster);
+    }
+    return;
+  }
   if (!this.options.subscribe && (((_a = this.options.signal) == null ? void 0 : _a.aborted) || __privateGet(this, _syncState).isUpToDate)) {
     return;
   }
@@ -2412,15 +2362,23 @@ requestShape_fn = async function() {
   }
   const { url, signal } = this.options;
   const { fetchUrl, requestHeaders } = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, url, resumingFromPause);
+  if (activeCacheBuster) {
+    fetchUrl.searchParams.set(CACHE_BUSTER_QUERY_PARAM, activeCacheBuster);
+    fetchUrl.searchParams.sort();
+  }
   const abortListener = await __privateMethod(this, _ShapeStream_instances, createAbortListener_fn).call(this, signal);
   const requestAbortController = __privateGet(this, _requestAbortController);
   if (__privateGet(this, _pauseLock).isPaused) {
     if (abortListener && signal) {
       signal.removeEventListener(`abort`, abortListener);
     }
+    if (activeCacheBuster) {
+      __privateSet(this, _pendingRequestShapeCacheBuster, activeCacheBuster);
+    }
     __privateSet(this, _requestAbortController, void 0);
     return;
   }
+  __privateSet(this, _pendingRequestShapeCacheBuster, void 0);
   try {
     await __privateMethod(this, _ShapeStream_instances, fetchShape_fn).call(this, {
       fetchUrl,
@@ -2447,16 +2405,18 @@ requestShape_fn = async function() {
         expiredShapesCache.markExpired(shapeKey, __privateGet(this, _syncState).handle);
       }
       const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER];
+      let nextRequestShapeCacheBuster;
       if (!newShapeHandle) {
         console.warn(
-          `[Electric] Received 409 response without a shape handle header. This likely indicates a proxy or CDN stripping required headers.`
+          `[Electric] Received 409 response without a shape handle header. This likely indicates a proxy or CDN stripping required headers.`,
+          new Error(`stack trace`)
         );
-        __privateSet(this, _refetchCacheBuster, createCacheBuster());
+        nextRequestShapeCacheBuster = createCacheBuster();
       }
       __privateMethod(this, _ShapeStream_instances, reset_fn).call(this, newShapeHandle);
       const messages409 = Array.isArray(e.json) ? e.json : e.json != null ? [e.json] : [];
       await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, messages409);
-      return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
+      return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this, nextRequestShapeCacheBuster);
     } else {
       throw e;
     }
@@ -2497,7 +2457,8 @@ For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
   }
   if (__privateGet(this, _fastLoopConsecutiveCount) === 1) {
     console.warn(
-      `[Electric] Detected fast retry loop (${__privateGet(this, _fastLoopThreshold)} requests in ${__privateGet(this, _fastLoopWindowMs)}ms at the same offset). Clearing client-side caches and resetting stream to recover. If this persists, check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key, and that required Electric headers are forwarded to the client. For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
+      `[Electric] Detected fast retry loop (${__privateGet(this, _fastLoopThreshold)} requests in ${__privateGet(this, _fastLoopWindowMs)}ms at the same offset). Clearing client-side caches and resetting stream to recover. If this persists, check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key, and that required Electric headers are forwarded to the client. For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`,
+      new Error(`stack trace`)
     );
     if (__privateGet(this, _currentFetchUrl)) {
       const shapeKey = canonicalShapeKey(__privateGet(this, _currentFetchUrl));
@@ -2621,13 +2582,6 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   if (expiredHandle) {
     fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle);
   }
-  if (__privateGet(this, _refetchCacheBuster)) {
-    fetchUrl.searchParams.set(
-      CACHE_BUSTER_QUERY_PARAM,
-      __privateGet(this, _refetchCacheBuster)
-    );
-    __privateSet(this, _refetchCacheBuster, void 0);
-  }
   fetchUrl.searchParams.sort();
   return {
     fetchUrl,
@@ -2680,7 +2634,8 @@ onInitialResponse_fn = async function(response) {
       );
     }
     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. For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL} Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _syncState).staleCacheRetryCount}/${__privateGet(this, _maxStaleCacheRetries)}).`
+      `[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. For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL} Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _syncState).staleCacheRetryCount}/${__privateGet(this, _maxStaleCacheRetries)}).`,
+      new Error(`stack trace`)
     );
     throw new StaleCacheError(
       `Received stale cached response with expired handle "${shapeHandle}". This indicates a proxy/CDN caching misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
@@ -2688,7 +2643,8 @@ onInitialResponse_fn = async function(response) {
   }
   if (transition.action === `ignored`) {
     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 response and continuing with handle "${__privateGet(this, _syncState).handle}".`
+      `[Electric] Response was ignored by state "${__privateGet(this, _syncState).kind}". The response body will be skipped. This may indicate a proxy/CDN caching issue or a client state machine bug.`,
+      new Error(`stack trace`)
     );
     return false;
   }
@@ -2697,7 +2653,8 @@ onInitialResponse_fn = async function(response) {
 onMessages_fn = async function(batch, isSseMessage = false) {
   if (!Array.isArray(batch)) {
     console.warn(
-      `[Electric] #onMessages called with non-array argument (${typeof batch}). This is a client bug \u2014 please report it.`
+      `[Electric] #onMessages called with non-array argument (${typeof batch}). This is a client bug \u2014 please report it.`,
+      new Error(`stack trace`)
     );
     return;
   }
@@ -2844,7 +2801,8 @@ requestShapeSSE_fn = async function(opts) {
     __privateSet(this, _syncState, transition.state);
     if (transition.fellBackToLongPolling) {
       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.`
+        `[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.`,
+        new Error(`stack trace`)
       );
     } else if (transition.wasShortConnection) {
       const maxDelay = Math.min(
@@ -2965,6 +2923,86 @@ reset_fn = function(handle) {
   __privateSet(this, _connected, false);
   __privateGet(this, _pauseLock).releaseAllMatching(`snapshot`);
 };
+fetchSnapshotWithRetry_fn = async function(opts, retryCount, cacheBuster) {
+  var _a, _b, _c;
+  const method = (_b = (_a = opts.method) != null ? _a : this.options.subsetMethod) != null ? _b : `GET`;
+  const usePost = method === `POST`;
+  let fetchUrl;
+  let fetchOptions;
+  if (usePost) {
+    const result = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true);
+    fetchUrl = result.fetchUrl;
+    fetchOptions = {
+      method: `POST`,
+      headers: __spreadProps(__spreadValues({}, result.requestHeaders), {
+        "Content-Type": `application/json`
+      }),
+      body: bigintSafeStringify(__privateMethod(this, _ShapeStream_instances, buildSubsetBody_fn).call(this, opts))
+    };
+  } else {
+    const result = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
+    fetchUrl = result.fetchUrl;
+    fetchOptions = { headers: result.requestHeaders };
+  }
+  if (cacheBuster) {
+    fetchUrl.searchParams.set(CACHE_BUSTER_QUERY_PARAM, cacheBuster);
+    fetchUrl.searchParams.sort();
+  }
+  const usedHandle = __privateGet(this, _syncState).handle;
+  let response;
+  try {
+    response = await __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), fetchOptions);
+  } catch (e) {
+    if (e instanceof FetchError && e.status === 409) {
+      const nextRetryCount = retryCount + 1;
+      if (nextRetryCount > __privateGet(this, _maxSnapshotRetries)) {
+        throw new FetchError(
+          502,
+          void 0,
+          void 0,
+          {},
+          fetchUrl.toString(),
+          `Snapshot request stuck in 409 retry loop after ${__privateGet(this, _maxSnapshotRetries)} attempts. This indicates a proxy/CDN misconfiguration. For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
+        );
+      }
+      if (usedHandle) {
+        const shapeKey = canonicalShapeKey(fetchUrl);
+        expiredShapesCache.markExpired(shapeKey, usedHandle);
+      }
+      const nextHandle = e.headers[SHAPE_HANDLE_HEADER];
+      let nextCacheBuster;
+      if (nextHandle) {
+        __privateSet(this, _syncState, __privateGet(this, _syncState).withHandle(nextHandle));
+        if (nextHandle === usedHandle) {
+          nextCacheBuster = createCacheBuster();
+        }
+      } else {
+        console.warn(
+          `[Electric] Received 409 response without a shape handle header. This likely indicates a proxy or CDN stripping required headers.`,
+          new Error(`stack trace`)
+        );
+        nextCacheBuster = createCacheBuster();
+      }
+      return __privateMethod(this, _ShapeStream_instances, fetchSnapshotWithRetry_fn).call(this, opts, nextRetryCount, nextCacheBuster);
+    }
+    throw e;
+  }
+  if (!response.ok) {
+    throw await FetchError.fromResponse(response, fetchUrl.toString());
+  }
+  const schema = (_c = __privateGet(this, _syncState).schema) != null ? _c : getSchemaFromHeaders(response.headers, {
+    required: true,
+    url: fetchUrl.toString()
+  });
+  const { metadata, data: rawData } = await response.json();
+  const data = __privateGet(this, _messageParser).parseSnapshotData(
+    rawData,
+    schema
+  );
+  const responseOffset = response.headers.get(CHUNK_LAST_OFFSET_HEADER) || null;
+  const responseHandle = response.headers.get(SHAPE_HANDLE_HEADER);
+  return { metadata, data, responseOffset, responseHandle };
+};
 buildSubsetBody_fn = function(opts) {
   var _a, _b, _c, _d;
   const body = {};