@electric-sql/client 1.5.4 → 1.5.6

package/package.json

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

package/src/client.ts

@@ -865,11 +865,15 @@ export class ShapeStream<T extends Row<unknown> = Row>
         this.#reset(newShapeHandle)
 
         // must refetch control message might be in a list or not depending
-        // on whether it came from an SSE request or long poll - handle both
-        // cases for safety here but worth revisiting 409 handling
-        await this.#publish(
-          (Array.isArray(e.json) ? e.json : [e.json]) as Message<T>[]
-        )
+        // on whether it came from an SSE request or long poll. The body may
+        // also be null/undefined if a proxy returned an unexpected response.
+        // Handle all cases defensively here.
+        const messages409 = Array.isArray(e.json)
+          ? e.json
+          : e.json != null
+            ? [e.json]
+            : []
+        await this.#publish(messages409 as Message<T>[])
         return this.#requestShape()
       } else {
         // errors that have reached this point are not actionable without
@@ -1142,6 +1146,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
   }
 
   async #onMessages(batch: Array<Message<T>>, isSseMessage = false) {
+    if (!Array.isArray(batch)) {
+      console.warn(
+        `[Electric] #onMessages called with non-array argument (${typeof batch}). ` +
+          `This is a client bug — please report it.`
+      )
+      return
+    }
     if (batch.length === 0) return
 
     const lastMessage = batch[batch.length - 1]
@@ -1249,6 +1260,19 @@ export class ShapeStream<T extends Row<unknown> = Row>
     const messages = res || `[]`
     const batch = this.#messageParser.parse<Array<Message<T>>>(messages, schema)
 
+    if (!Array.isArray(batch)) {
+      const preview = JSON.stringify(batch)?.slice(0, 200)
+      throw new FetchError(
+        response.status,
+        `Received non-array response body from shape endpoint. ` +
+          `This may indicate a proxy or CDN is returning an unexpected response. ` +
+          `Expected a JSON array, got ${typeof batch}: ${preview}`,
+        undefined,
+        Object.fromEntries(response.headers.entries()),
+        fetchUrl.toString()
+      )
+    }
+
     await this.#onMessages(batch)
   }
 
@@ -1318,7 +1342,18 @@ export class ShapeStream<T extends Row<unknown> = Row>
         // #start handles it correctly.
         throw new FetchBackoffAbortError()
       }
-      throw error
+      // Re-throw known Electric errors so the caller can handle them
+      // (e.g., 409 shape rotation, stale cache retry, missing headers).
+      // Other errors (body parsing, SSE protocol failures, null body)
+      // are SSE connection failures handled by the fallback mechanism
+      // in the finally block below.
+      if (
+        error instanceof FetchError ||
+        error instanceof StaleCacheError ||
+        error instanceof MissingHeadersError
+      ) {
+        throw error
+      }
     } finally {
       // Check if the SSE connection closed too quickly
       // This can happen when responses are cached or when the proxy/server

package/src/fetch.ts

@@ -226,6 +226,17 @@ export function createFetchWithChunkBuffer(
 
   const prefetchClient = async (...args: Parameters<typeof fetchClient>) => {
     const url = args[0].toString()
+    const method = getRequestMethod(args[0], args[1])
+
+    // Prefetch is only valid for GET requests. The prefetch queue matches
+    // requests by URL alone and ignores HTTP method/body, so a POST request
+    // with the same URL would incorrectly consume the prefetched stream
+    // response instead of making its own request.
+    if (method !== `GET`) {
+      prefetchQueue?.abort()
+      prefetchQueue = undefined
+      return fetchClient(...args)
+    }
 
     // try to consume from the prefetch queue first, and if request is
     // not present abort the prefetch queue as it must no longer be valid
@@ -494,3 +505,18 @@ function chainAborter(
 }
 
 function noop() {}
+
+function getRequestMethod(
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1]
+): string {
+  if (init?.method) {
+    return init.method.toUpperCase()
+  }
+
+  if (typeof Request !== `undefined` && input instanceof Request) {
+    return input.method.toUpperCase()
+  }
+
+  return `GET`
+}

package/src/helpers.ts

@@ -28,7 +28,7 @@ import {
 export function isChangeMessage<T extends Row<unknown> = Row>(
   message: Message<T>
 ): message is ChangeMessage<T> {
-  return `key` in message
+  return message != null && `key` in message
 }
 
 /**
@@ -51,7 +51,7 @@ export function isChangeMessage<T extends Row<unknown> = Row>(
 export function isControlMessage<T extends Row<unknown> = Row>(
   message: Message<T>
 ): message is ControlMessage {
-  return !isChangeMessage(message)
+  return message != null && !isChangeMessage(message)
 }
 
 export function isUpToDateMessage<T extends Row<unknown> = Row>(

package/src/shape-stream-state.ts

@@ -380,6 +380,19 @@ abstract class FetchingState extends ActiveState {
     if (staleResult) return staleResult
 
     const shared = this.parseResponseFields(input)
+
+    // NOTE: 204s are deprecated, the Electric server should not send these
+    // in latest versions but this is here for backwards compatibility.
+    // A 204 means "no content, you're caught up" — transition to live.
+    // Skip SSE detection: a 204 gives no indication SSE will work, and
+    // the 3-attempt fallback cycle adds unnecessary latency.
+    if (input.status === 204) {
+      return {
+        action: `accepted`,
+        state: new LiveState(shared, { sseFallbackToLongPolling: true }),
+      }
+    }
+
     return { action: `accepted`, state: new SyncingState(shared) }
   }