@electric-sql/client 1.5.6 → 1.5.7

package/dist/index.d.ts

@@ -73,7 +73,7 @@ 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 */
@@ -783,11 +783,13 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
      * `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.
      */
     fetchSnapshot(opts: SubsetParams): Promise<{
         metadata: SnapshotMetadata;
         data: Array<ChangeMessage<T>>;
+        responseOffset: Offset | null;
+        responseHandle: string | null;
     }>;
 }
 

package/dist/index.legacy-esm.js

@@ -439,6 +439,12 @@ function getOffset(message) {
   const lsn = message.headers.global_last_seen_lsn;
   return lsn ? `${lsn}_0` : void 0;
 }
+function bigintReplacer(_key, value) {
+  return typeof value === `bigint` ? value.toString() : value;
+}
+function bigintSafeStringify(value) {
+  return JSON.stringify(value, bigintReplacer);
+}
 function isVisibleInSnapshot(txid, snapshot) {
   const xid = BigInt(txid);
   const xmin = BigInt(snapshot.xmin);
@@ -1704,6 +1710,13 @@ var PausedState = class _PausedState extends ShapeStreamState {
   get replayCursor() {
     return this.previousState.replayCursor;
   }
+  handleResponseMetadata(input) {
+    const transition = this.previousState.handleResponseMetadata(input);
+    if (transition.action === `accepted`) {
+      return { action: `accepted`, state: new _PausedState(transition.state) };
+    }
+    return transition;
+  }
   withHandle(handle) {
     return new _PausedState(this.previousState.withHandle(handle));
   }
@@ -2094,7 +2107,7 @@ var ShapeStream = class {
       );
     }, 3e4);
     try {
-      const { metadata, data } = await this.fetchSnapshot(opts);
+      const { metadata, data, responseOffset, responseHandle } = await this.fetchSnapshot(opts);
       const dataWithEndBoundary = data.concat([
         { headers: __spreadValues({ control: `snapshot-end` }, metadata) },
         { headers: __spreadValues({ control: `subset-end` }, opts) }
@@ -2104,6 +2117,25 @@ var ShapeStream = class {
         new Set(data.map((message) => message.key))
       );
       __privateMethod(this, _ShapeStream_instances, onMessages_fn).call(this, dataWithEndBoundary, false);
+      if (responseOffset !== null || responseHandle !== null) {
+        const transition = __privateGet(this, _syncState).handleResponseMetadata({
+          status: 200,
+          responseHandle,
+          responseOffset,
+          responseCursor: null,
+          expiredHandle: null,
+          now: Date.now(),
+          maxStaleCacheRetries: __privateGet(this, _maxStaleCacheRetries),
+          createCacheBuster: () => `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+        });
+        if (transition.action === `accepted`) {
+          __privateSet(this, _syncState, transition.state);
+        } else {
+          console.warn(
+            `[Electric] Snapshot response metadata was not accepted by state "${__privateGet(this, _syncState).kind}" (action: ${transition.action}). Stream offset was not advanced from snapshot.`
+          );
+        }
+      }
       return {
         metadata,
         data
@@ -2122,7 +2154,7 @@ var ShapeStream = class {
    * `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) {
     var _a, _b, _c;
@@ -2138,7 +2170,7 @@ var ShapeStream = class {
         headers: __spreadProps(__spreadValues({}, result.requestHeaders), {
           "Content-Type": `application/json`
         }),
-        body: JSON.stringify(__privateMethod(this, _ShapeStream_instances, buildSubsetBody_fn).call(this, opts))
+        body: bigintSafeStringify(__privateMethod(this, _ShapeStream_instances, buildSubsetBody_fn).call(this, opts))
       };
     } else {
       const result = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
@@ -2173,7 +2205,9 @@ var ShapeStream = class {
       rawData,
       schema
     );
-    return { metadata, data };
+    const responseOffset = response.headers.get(CHUNK_LAST_OFFSET_HEADER) || null;
+    const responseHandle = response.headers.get(SHAPE_HANDLE_HEADER);
+    return { metadata, data, responseOffset, responseHandle };
   }
 };
 _error = new WeakMap();
@@ -2386,7 +2420,7 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
     if (subsetParams.params)
       fetchUrl.searchParams.set(
         SUBSET_PARAM_WHERE_PARAMS,
-        JSON.stringify(subsetParams.params)
+        bigintSafeStringify(subsetParams.params)
       );
     if (subsetParams.limit)
       setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit);
@@ -2565,7 +2599,7 @@ requestShapeLongPoll_fn = async function(opts) {
   const messages = res || `[]`;
   const batch = __privateGet(this, _messageParser).parse(messages, schema);
   if (!Array.isArray(batch)) {
-    const preview = (_a = JSON.stringify(batch)) == null ? void 0 : _a.slice(0, 200);
+    const preview = (_a = bigintSafeStringify(batch)) == null ? void 0 : _a.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}`,
@@ -2929,7 +2963,7 @@ var Shape = class {
    * Returns void; data will be emitted via the stream and processed by this Shape.
    */
   async requestSnapshot(params) {
-    const key = JSON.stringify(params);
+    const key = bigintSafeStringify(params);
     __privateGet(this, _requestedSubSnapshots).add(key);
     await __privateMethod(this, _Shape_instances, awaitUpToDate_fn).call(this);
     await this.stream.requestSnapshot(params);