@electric-sql/client 1.5.6 → 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.6",
+  "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. ` +
@@ -1650,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 } },
@@ -1663,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,
@@ -1682,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`
@@ -1703,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)
@@ -1757,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/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

@@ -704,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 */