@electric-sql/client 1.5.5 → 1.5.7

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.5",
+  "version": "1.5.7",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -15,7 +15,12 @@ import {
   encodeWhereClause,
   quoteIdentifier,
 } from './column-mapper'
-import { getOffset, isUpToDateMessage, isChangeMessage } from './helpers'
+import {
+  getOffset,
+  isUpToDateMessage,
+  isChangeMessage,
+  bigintSafeStringify,
+} from './helpers'
 import {
   FetchError,
   FetchBackoffAbortError,
@@ -987,7 +992,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
         // Serialize params as JSON to keep the parameter name constant for proxy configs
         fetchUrl.searchParams.set(
           SUBSET_PARAM_WHERE_PARAMS,
-          JSON.stringify(subsetParams.params)
+          bigintSafeStringify(subsetParams.params)
         )
       if (subsetParams.limit)
         setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit)
@@ -1261,7 +1266,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
     const batch = this.#messageParser.parse<Array<Message<T>>>(messages, schema)
 
     if (!Array.isArray(batch)) {
-      const preview = JSON.stringify(batch)?.slice(0, 200)
+      const preview = bigintSafeStringify(batch)?.slice(0, 200)
       throw new FetchError(
         response.status,
         `Received non-array response body from shape endpoint. ` +
@@ -1342,7 +1347,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
@@ -1639,7 +1655,8 @@ export class ShapeStream<T extends Row<unknown> = Row>
     }, 30_000)
 
     try {
-      const { metadata, data } = await this.fetchSnapshot(opts)
+      const { metadata, data, responseOffset, responseHandle } =
+        await this.fetchSnapshot(opts)
 
       const dataWithEndBoundary = (data as Array<Message<T>>).concat([
         { headers: { control: `snapshot-end`, ...metadata } },
@@ -1652,6 +1669,31 @@ export class ShapeStream<T extends Row<unknown> = Row>
       )
       this.#onMessages(dataWithEndBoundary, false)
 
+      // On cold start the stream's offset is still at "now". Advance it
+      // to the snapshot's position so no updates are missed in between.
+      if (responseOffset !== null || responseHandle !== null) {
+        const transition = this.#syncState.handleResponseMetadata({
+          status: 200,
+          responseHandle,
+          responseOffset,
+          responseCursor: null,
+          expiredHandle: null,
+          now: Date.now(),
+          maxStaleCacheRetries: this.#maxStaleCacheRetries,
+          createCacheBuster: () =>
+            `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
+        })
+        if (transition.action === `accepted`) {
+          this.#syncState = transition.state
+        } else {
+          console.warn(
+            `[Electric] Snapshot response metadata was not accepted ` +
+              `by state "${this.#syncState.kind}" (action: ${transition.action}). ` +
+              `Stream offset was not advanced from snapshot.`
+          )
+        }
+      }
+
       return {
         metadata,
         data,
@@ -1671,11 +1713,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
    * `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.
+   * @returns The metadata, data, and the response's offset/handle for state advancement.
    */
   async fetchSnapshot(opts: SubsetParams): Promise<{
     metadata: SnapshotMetadata
     data: Array<ChangeMessage<T>>
+    responseOffset: Offset | null
+    responseHandle: string | null
   }> {
     const method = opts.method ?? this.options.subsetMethod ?? `GET`
     const usePost = method === `POST`
@@ -1692,7 +1736,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
           ...result.requestHeaders,
           'Content-Type': `application/json`,
         },
-        body: JSON.stringify(this.#buildSubsetBody(opts)),
+        body: bigintSafeStringify(this.#buildSubsetBody(opts)),
       }
     } else {
       const result = await this.#constructUrl(this.options.url, true, opts)
@@ -1746,7 +1790,11 @@ export class ShapeStream<T extends Row<unknown> = Row>
       schema
     )
 
-    return { metadata, data }
+    const responseOffset =
+      (response.headers.get(CHUNK_LAST_OFFSET_HEADER) as Offset) || null
+    const responseHandle = response.headers.get(SHAPE_HANDLE_HEADER)
+
+    return { metadata, data, responseOffset, responseHandle }
   }
 
   #buildSubsetBody(opts: SubsetParams): Record<string, unknown> {

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

@@ -71,6 +71,21 @@ export function getOffset(message: ControlMessage): Offset | undefined {
   return lsn ? (`${lsn}_0` as Offset) : undefined
 }
 
+function bigintReplacer(_key: string, value: unknown): unknown {
+  return typeof value === `bigint` ? value.toString() : value
+}
+
+/**
+ * BigInt-safe version of JSON.stringify.
+ * Converts BigInt values to their string representation (as JSON strings,
+ * e.g. `{ id: 42n }` becomes `{"id":"42"}`) instead of throwing.
+ * Assumes input is a JSON-serializable value — passing `undefined` at the
+ * top level will return `undefined` (matching `JSON.stringify` behavior).
+ */
+export function bigintSafeStringify(value: unknown): string {
+  return JSON.stringify(value, bigintReplacer)
+}
+
 /**
  * Checks if a transaction is visible in a snapshot.
  *

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) }
   }
 
@@ -691,6 +704,16 @@ export class PausedState extends ShapeStreamState {
     return this.previousState.replayCursor
   }
 
+  handleResponseMetadata(
+    input: ResponseMetadataInput
+  ): ResponseMetadataTransition {
+    const transition = this.previousState.handleResponseMetadata(input)
+    if (transition.action === `accepted`) {
+      return { action: `accepted`, state: new PausedState(transition.state) }
+    }
+    return transition
+  }
+
   withHandle(handle: string): PausedState {
     return new PausedState(this.previousState.withHandle(handle))
   }

package/src/shape.ts

@@ -1,5 +1,9 @@
 import { Message, Offset, Row } from './types'
-import { isChangeMessage, isControlMessage } from './helpers'
+import {
+  isChangeMessage,
+  isControlMessage,
+  bigintSafeStringify,
+} from './helpers'
 import { FetchError } from './error'
 import { LogMode, ShapeStreamInterface } from './client'
 
@@ -141,7 +145,7 @@ export class Shape<T extends Row<unknown> = Row> {
     params: Parameters<ShapeStreamInterface<T>[`requestSnapshot`]>[0]
   ): Promise<void> {
     // Track this snapshot request for future re-execution on shape rotation
-    const key = JSON.stringify(params)
+    const key = bigintSafeStringify(params)
     this.#requestedSubSnapshots.add(key)
     // Ensure the stream is up-to-date so schema is available for parsing
     await this.#awaitUpToDate()

package/src/types.ts

@@ -91,7 +91,7 @@ export type SubsetParams = {
   /** Legacy string format WHERE clause */
   where?: string
   /** Positional parameter values for WHERE clause */
-  params?: Record<string, string>
+  params?: Record<string, string | bigint | number>
   /** Maximum number of rows to return */
   limit?: number
   /** Number of rows to skip */