@electric-sql/client 1.4.2 → 1.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -429,6 +429,27 @@ export 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`
 }
 
 export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
@@ -1097,13 +1118,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
             `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
         )
       } else {
+        // We already have a valid handle, so ignore the stale response entirely
+        // to prevent a mismatch between our current handle and the stale offset.
         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 "${this.#shapeHandle}".`
+            `Ignoring the stale response and continuing with handle "${this.#shapeHandle}".`
         )
+        return
       }
     }
 
@@ -1632,6 +1656,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
    * 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.
    */
@@ -1639,27 +1667,59 @@ export class ShapeStream<T extends Row<unknown> = Row>
     metadata: SnapshotMetadata
     data: Array<ChangeMessage<T>>
   }> {
-    const { fetchUrl, requestHeaders } = await this.#constructUrl(
-      this.options.url,
-      true,
-      opts
-    )
+    const method = opts.method ?? this.options.subsetMethod ?? `GET`
+    const usePost = method === `POST`
+
+    let fetchUrl: URL
+    let fetchOptions: RequestInit
+
+    if (usePost) {
+      const result = await this.#constructUrl(this.options.url, true)
+      fetchUrl = result.fetchUrl
+      fetchOptions = {
+        method: `POST`,
+        headers: {
+          ...result.requestHeaders,
+          'Content-Type': `application/json`,
+        },
+        body: JSON.stringify(this.#buildSubsetBody(opts)),
+      }
+    } else {
+      const result = await this.#constructUrl(this.options.url, true, opts)
+      fetchUrl = result.fetchUrl
+      fetchOptions = { headers: result.requestHeaders }
+    }
 
-    const response = await this.#fetchClient(fetchUrl.toString(), {
-      headers: requestHeaders,
-    })
+    // Capture handle before fetch to avoid race conditions if it changes during the request
+    const usedHandle = this.#shapeHandle
 
+    let response: Response
+    try {
+      response = await this.#fetchClient(fetchUrl.toString(), fetchOptions)
+    } catch (e) {
+      // Handle 409 "must-refetch" - shape handle changed/expired.
+      // The fetch wrapper throws FetchError for non-OK responses, so we catch here.
+      // Unlike #requestShape, we don't call #reset() here as that would
+      // clear #activeSnapshotRequests and break requestSnapshot's pause/resume logic.
+      if (e instanceof FetchError && e.status === 409) {
+        if (usedHandle) {
+          const shapeKey = canonicalShapeKey(fetchUrl)
+          expiredShapesCache.markExpired(shapeKey, usedHandle)
+        }
+
+        this.#shapeHandle =
+          e.headers[SHAPE_HANDLE_HEADER] || `${usedHandle ?? `handle`}-next`
+
+        return this.fetchSnapshot(opts)
+      }
+      throw e
+    }
+
+    // Handle non-OK responses from custom fetch clients that bypass the wrapper chain
     if (!response.ok) {
-      throw new FetchError(
-        response.status,
-        undefined,
-        undefined,
-        Object.fromEntries([...response.headers.entries()]),
-        fetchUrl.toString()
-      )
+      throw await FetchError.fromResponse(response, fetchUrl.toString())
     }
 
-    // Use schema from stream if available, otherwise extract from response header
     const schema: Schema =
       this.#schema ??
       getSchemaFromHeaders(response.headers, {
@@ -1673,10 +1733,51 @@ export class ShapeStream<T extends Row<unknown> = Row>
       schema
     )
 
-    return {
-      metadata,
-      data,
+    return { metadata, data }
+  }
+
+  #buildSubsetBody(opts: SubsetParams): Record<string, unknown> {
+    const body: Record<string, unknown> = {}
+
+    if (opts.whereExpr) {
+      body.where = compileExpression(
+        opts.whereExpr,
+        this.options.columnMapper?.encode
+      )
+      body.where_expr = opts.whereExpr
+    } else if (opts.where && typeof opts.where === `string`) {
+      body.where = encodeWhereClause(
+        opts.where,
+        this.options.columnMapper?.encode
+      )
+    }
+
+    if (opts.params) {
+      body.params = opts.params
+    }
+
+    if (opts.limit !== undefined) {
+      body.limit = opts.limit
+    }
+
+    if (opts.offset !== undefined) {
+      body.offset = opts.offset
+    }
+
+    if (opts.orderByExpr) {
+      body.order_by = compileOrderBy(
+        opts.orderByExpr,
+        this.options.columnMapper?.encode
+      )
+      body.order_by_expr = opts.orderByExpr
+    } else if (opts.orderBy && typeof opts.orderBy === `string`) {
+      body.order_by = encodeWhereClause(
+        opts.orderBy,
+        this.options.columnMapper?.encode
+      )
     }
+
+    return body
   }
 }
 

package/src/types.ts

@@ -102,6 +102,16 @@ export 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`
 }
 
 export type ControlMessage = {