@electric-sql/client 1.4.2 → 1.5.1

package/dist/index.d.ts

@@ -84,6 +84,16 @@ type SubsetParams = {
     whereExpr?: SerializedExpression;
     /** Structured ORDER BY clauses (preferred when available) */
     orderByExpr?: SerializedOrderByClause[];
+    /**
+     * HTTP method to use for the request. Overrides `subsetMethod` from ShapeStreamOptions.
+     * - `GET` (default): Sends subset params as query parameters. May fail with 414 errors
+     *   for large queries.
+     * - `POST`: Sends subset params in request body as JSON. Recommended to avoid URL
+     *   length limits with large WHERE clauses or many parameters.
+     *
+     * In Electric 2.0, GET will be deprecated and only POST will be supported.
+     */
+    method?: `GET` | `POST`;
 };
 type ControlMessage = {
     headers: (Header & {
@@ -629,6 +639,26 @@ interface ShapeStreamOptions<T = never> {
      * ```
      */
     onError?: ShapeStreamErrorHandler;
+    /**
+     * HTTP method to use for subset snapshot requests (`requestSnapshot`/`fetchSnapshot`).
+     *
+     * - `'GET'` (default): Sends subset params as URL query parameters. May fail with
+     *   HTTP 414 errors for large queries with many parameters.
+     * - `'POST'`: Sends subset params in request body as JSON. Recommended for queries
+     *   with large parameter lists (e.g., `WHERE id = ANY($1)` with hundreds of IDs).
+     *
+     * This can be overridden per-request by passing `method` in the subset params.
+     *
+     * @example
+     * ```typescript
+     * const stream = new ShapeStream({
+     *   url: 'http://localhost:3000/v1/shape',
+     *   params: { table: 'items' },
+     *   subsetMethod: 'POST', // Use POST for all subset requests
+     * })
+     * ```
+     */
+    subsetMethod?: `GET` | `POST`;
 }
 interface ShapeStreamInterface<T extends Row<unknown> = Row> {
     subscribe(callback: (messages: Message<T>[]) => MaybePromise<void> | {
@@ -748,6 +778,10 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
      * Fetch a snapshot for subset of data.
      * Returns the metadata and the data, but does not inject it into the subscribed data stream.
      *
+     * By default, uses GET to send subset parameters as query parameters. This may hit URL length
+     * limits (HTTP 414) with large WHERE clauses or many parameters. Set `method: 'POST'` or use
+     * `subsetMethod: 'POST'` on the stream to send parameters in the request body instead.
+     *
      * @param opts - The options for the snapshot request.
      * @returns The metadata and the data for the snapshot.
      */

package/dist/index.legacy-esm.js

@@ -1142,7 +1142,7 @@ 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, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _staleCacheBuster, _staleCacheRetryCount, _maxStaleCacheRetries, _ShapeStream_instances, replayMode_get, 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;
+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, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _staleCacheBuster, _staleCacheRetryCount, _maxStaleCacheRetries, _ShapeStream_instances, replayMode_get, 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, buildSubsetBody_fn;
 var ShapeStream = class {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
@@ -1357,25 +1357,53 @@ var ShapeStream = class {
    * Fetch a snapshot for subset of data.
    * Returns the metadata and the data, but does not inject it into the subscribed data stream.
    *
+   * By default, uses GET to send subset parameters as query parameters. This may hit URL length
+   * limits (HTTP 414) with large WHERE clauses or many parameters. Set `method: 'POST'` or use
+   * `subsetMethod: 'POST'` on the stream to send parameters in the request body instead.
+   *
    * @param opts - The options for the snapshot request.
    * @returns The metadata and the data for the snapshot.
    */
   async fetchSnapshot(opts) {
-    var _a;
-    const { fetchUrl, requestHeaders } = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
-    const response = await __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), {
-      headers: requestHeaders
-    });
+    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: JSON.stringify(__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, _shapeHandle);
+    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);
+        }
+        __privateSet(this, _shapeHandle, e.headers[SHAPE_HANDLE_HEADER] || `${usedHandle != null ? usedHandle : `handle`}-next`);
+        return this.fetchSnapshot(opts);
+      }
+      throw e;
+    }
     if (!response.ok) {
-      throw new FetchError(
-        response.status,
-        void 0,
-        void 0,
-        Object.fromEntries([...response.headers.entries()]),
-        fetchUrl.toString()
-      );
+      throw await FetchError.fromResponse(response, fetchUrl.toString());
     }
-    const schema = (_a = __privateGet(this, _schema)) != null ? _a : getSchemaFromHeaders(response.headers, {
+    const schema = (_c = __privateGet(this, _schema)) != null ? _c : getSchemaFromHeaders(response.headers, {
       required: true,
       url: fetchUrl.toString()
     });
@@ -1384,10 +1412,7 @@ var ShapeStream = class {
       rawData,
       schema
     );
-    return {
-      metadata,
-      data
-    };
+    return { metadata, data };
   }
 };
 _error = new WeakMap();
@@ -1703,8 +1728,9 @@ onInitialResponse_fn = async function(response) {
       );
     } else {
       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 handle and continuing with handle "${__privateGet(this, _shapeHandle)}".`
+        `[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, _shapeHandle)}".`
       );
+      return;
     }
   }
   const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER);
@@ -1957,6 +1983,44 @@ reset_fn = function(handle) {
   __privateSet(this, _staleCacheBuster, void 0);
   __privateSet(this, _staleCacheRetryCount, 0);
 };
+buildSubsetBody_fn = function(opts) {
+  var _a, _b, _c, _d;
+  const body = {};
+  if (opts.whereExpr) {
+    body.where = compileExpression(
+      opts.whereExpr,
+      (_a = this.options.columnMapper) == null ? void 0 : _a.encode
+    );
+    body.where_expr = opts.whereExpr;
+  } else if (opts.where && typeof opts.where === `string`) {
+    body.where = encodeWhereClause(
+      opts.where,
+      (_b = this.options.columnMapper) == null ? void 0 : _b.encode
+    );
+  }
+  if (opts.params) {
+    body.params = opts.params;
+  }
+  if (opts.limit !== void 0) {
+    body.limit = opts.limit;
+  }
+  if (opts.offset !== void 0) {
+    body.offset = opts.offset;
+  }
+  if (opts.orderByExpr) {
+    body.order_by = compileOrderBy(
+      opts.orderByExpr,
+      (_c = this.options.columnMapper) == null ? void 0 : _c.encode
+    );
+    body.order_by_expr = opts.orderByExpr;
+  } else if (opts.orderBy && typeof opts.orderBy === `string`) {
+    body.order_by = encodeWhereClause(
+      opts.orderBy,
+      (_d = this.options.columnMapper) == null ? void 0 : _d.encode
+    );
+  }
+  return body;
+};
 ShapeStream.Replica = {
   FULL: `full`,
   DEFAULT: `default`