@electric-sql/client 1.4.1 → 1.5.0

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.1",
+  "version": "1.5.0",
   "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> {
@@ -538,7 +559,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   readonly #messageParser: MessageParser<T>
 
   readonly #subscribers = new Map<
-    number,
+    object,
     [
       (messages: Message<T>[]) => MaybePromise<void>,
       ((error: Error) => void) | undefined,
@@ -1161,8 +1182,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
           const currentCursor = this.#liveCacheBuster
 
           if (currentCursor === this.#lastSeenCursor) {
-            // Same cursor = still replaying cached responses
-            // Suppress this up-to-date notification
+            // Same cursor as previous session - suppress this up-to-date notification.
+            // Exit replay mode after first suppression to ensure we don't get stuck
+            // if CDN keeps returning the same cursor indefinitely.
+            this.#lastSeenCursor = undefined
             return
           }
         }
@@ -1393,7 +1416,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
     callback: (messages: Message<T>[]) => MaybePromise<void>,
     onError: (error: Error) => void = () => {}
   ) {
-    const subscriptionId = Math.random()
+    const subscriptionId = {}
 
     this.#subscribers.set(subscriptionId, [callback, onError])
     if (!this.#started) this.#start()
@@ -1630,6 +1653,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.
    */
@@ -1637,27 +1664,35 @@ 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,
-    })
+    const response = await this.#fetchClient(fetchUrl.toString(), fetchOptions)
 
     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, {
@@ -1671,10 +1706,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/shape.ts

@@ -51,7 +51,7 @@ export class Shape<T extends Row<unknown> = Row> {
   readonly stream: ShapeStreamInterface<T>
 
   readonly #data: ShapeData<T> = new Map()
-  readonly #subscribers = new Map<number, ShapeChangedCallback<T>>()
+  readonly #subscribers = new Map<object, ShapeChangedCallback<T>>()
   readonly #insertedKeys = new Set<string>()
   readonly #requestedSubSnapshots = new Set<string>()
   #reexecuteSnapshotsPending = false
@@ -149,7 +149,7 @@ export class Shape<T extends Row<unknown> = Row> {
   }
 
   subscribe(callback: ShapeChangedCallback<T>): () => void {
-    const subscriptionId = Math.random()
+    const subscriptionId = {}
 
     this.#subscribers.set(subscriptionId, callback)
 

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 = {