@electric-sql/client 1.1.3 → 1.1.5

package/dist/index.d.ts

@@ -368,16 +368,14 @@ interface ShapeStreamInterface<T extends Row<unknown> = Row> {
     error?: unknown;
     mode: LogMode;
     forceDisconnectAndRefresh(): Promise<void>;
-    requestSnapshot(params: {
-        where?: string;
-        params?: Record<string, string>;
-        limit: number;
-        offset?: number;
-        orderBy: string;
-    }): Promise<{
+    requestSnapshot(params: SubsetParams): Promise<{
         metadata: SnapshotMetadata;
         data: Array<Message<T>>;
     }>;
+    fetchSnapshot(opts: SubsetParams): Promise<{
+        metadata: SnapshotMetadata;
+        data: Array<ChangeMessage<T>>;
+    }>;
 }
 /**
  * Reads updates to a shape from Electric using HTTP requests and long polling or
@@ -451,7 +449,7 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
      */
     forceDisconnectAndRefresh(): Promise<void>;
     /**
-     * Request a snapshot for subset of data.
+     * Request a snapshot for subset of data and inject it into the subscribed data stream.
      *
      * Only available when mode is `changes_only`.
      * Returns the insertion point & the data, but more importantly injects the data
@@ -468,6 +466,17 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
         metadata: SnapshotMetadata;
         data: Array<ChangeMessage<T>>;
     }>;
+    /**
+     * Fetch a snapshot for subset of data.
+     * Returns the metadata and the data, but does not inject it into the subscribed data stream.
+     *
+     * @param opts - The options for the snapshot request.
+     * @returns The metadata and the data for the snapshot.
+     */
+    fetchSnapshot(opts: SubsetParams): Promise<{
+        metadata: SnapshotMetadata;
+        data: Array<ChangeMessage<T>>;
+    }>;
 }
 
 type ShapeData<T extends Row<unknown> = Row> = Map<string, T>;

package/dist/index.legacy-esm.js

@@ -203,15 +203,37 @@ var MessageParser = class {
   parse(messages, schema) {
     return JSON.parse(messages, (key, value) => {
       if ((key === `value` || key === `old_value`) && typeof value === `object` && value !== null) {
-        const row = value;
-        Object.keys(row).forEach((key2) => {
-          row[key2] = this.parseRow(key2, row[key2], schema);
-        });
-        if (this.transformer) value = this.transformer(value);
+        return this.transformMessageValue(value, schema);
       }
       return value;
     });
   }
+  /**
+   * Parse an array of ChangeMessages from a snapshot response.
+   * Applies type parsing and transformations to the value and old_value properties.
+   */
+  parseSnapshotData(messages, schema) {
+    return messages.map((message) => {
+      const msg = message;
+      if (msg.value && typeof msg.value === `object` && msg.value !== null) {
+        msg.value = this.transformMessageValue(msg.value, schema);
+      }
+      if (msg.old_value && typeof msg.old_value === `object` && msg.old_value !== null) {
+        msg.old_value = this.transformMessageValue(msg.old_value, schema);
+      }
+      return msg;
+    });
+  }
+  /**
+   * Transform a message value or old_value object by parsing its columns.
+   */
+  transformMessageValue(value, schema) {
+    const row = value;
+    Object.keys(row).forEach((key) => {
+      row[key] = this.parseRow(key, row[key], schema);
+    });
+    return this.transformer ? this.transformer(row) : row;
+  }
   // Parses the message values using the provided parser based on the schema information
   parseRow(key, value, schema) {
     var _b;
@@ -751,9 +773,8 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _ShapeStream_instances, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn, fetchSnapshot_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _ShapeStream_instances, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn;
 var ShapeStream = class {
-  // Maximum delay cap (ms)
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
     __privateAdd(this, _error, null);
@@ -797,6 +818,8 @@ var ShapeStream = class {
     __privateAdd(this, _sseBackoffBaseDelay, 100);
     // Base delay for exponential backoff (ms)
     __privateAdd(this, _sseBackoffMaxDelay, 5e3);
+    // Maximum delay cap (ms)
+    __privateAdd(this, _unsubscribeFromVisibilityChanges);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -852,7 +875,9 @@ var ShapeStream = class {
     };
   }
   unsubscribeAll() {
+    var _a;
     __privateGet(this, _subscribers).clear();
+    (_a = __privateGet(this, _unsubscribeFromVisibilityChanges)) == null ? void 0 : _a.call(this);
   }
   /** Unix time at which we last synced. Undefined when `isLoading` is true. */
   lastSyncedAt() {
@@ -893,7 +918,7 @@ var ShapeStream = class {
     __privateSet(this, _isRefreshing, false);
   }
   /**
-   * Request a snapshot for subset of data.
+   * Request a snapshot for subset of data and inject it into the subscribed data stream.
    *
    * Only available when mode is `changes_only`.
    * Returns the insertion point & the data, but more importantly injects the data
@@ -919,8 +944,7 @@ var ShapeStream = class {
       if (__privateGet(this, _activeSnapshotRequests) === 1) {
         __privateMethod(this, _ShapeStream_instances, pause_fn).call(this);
       }
-      const { fetchUrl, requestHeaders } = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
-      const { metadata, data } = await __privateMethod(this, _ShapeStream_instances, fetchSnapshot_fn).call(this, fetchUrl, requestHeaders);
+      const { metadata, data } = await this.fetchSnapshot(opts);
       const dataWithEndBoundary = data.concat([
         { headers: __spreadValues({ control: `snapshot-end` }, metadata) }
       ]);
@@ -940,6 +964,42 @@ var ShapeStream = class {
       }
     }
   }
+  /**
+   * Fetch a snapshot for subset of data.
+   * Returns the metadata and the data, but does not inject it into the subscribed data stream.
+   *
+   * @param opts - The options for the snapshot request.
+   * @returns The metadata and the data for the snapshot.
+   */
+  async fetchSnapshot(opts) {
+    var _a;
+    const { fetchUrl, requestHeaders } = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
+    const response = await __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), {
+      headers: requestHeaders
+    });
+    if (!response.ok) {
+      throw new FetchError(
+        response.status,
+        void 0,
+        void 0,
+        Object.fromEntries([...response.headers.entries()]),
+        fetchUrl.toString()
+      );
+    }
+    const schema = (_a = __privateGet(this, _schema)) != null ? _a : getSchemaFromHeaders(response.headers, {
+      required: true,
+      url: fetchUrl.toString()
+    });
+    const { metadata, data: rawData } = await response.json();
+    const data = __privateGet(this, _messageParser).parseSnapshotData(
+      rawData,
+      schema
+    );
+    return {
+      metadata,
+      data
+    };
+  }
 };
 _error = new WeakMap();
 _fetchClient2 = new WeakMap();
@@ -975,6 +1035,7 @@ _maxShortSseConnections = new WeakMap();
 _sseFallbackToLongPolling = new WeakMap();
 _sseBackoffBaseDelay = new WeakMap();
 _sseBackoffMaxDelay = new WeakMap();
+_unsubscribeFromVisibilityChanges = new WeakMap();
 _ShapeStream_instances = new WeakSet();
 start_fn = async function() {
   var _a, _b, _c, _d, _e;
@@ -1041,7 +1102,8 @@ requestShape_fn = async function() {
       return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
     }
     if (e instanceof FetchBackoffAbortError) {
-      if (requestAbortController.signal.aborted && requestAbortController.signal.reason === PAUSE_STREAM) {
+      const currentState = __privateGet(this, _state);
+      if (requestAbortController.signal.aborted && requestAbortController.signal.reason === PAUSE_STREAM && currentState === `pause-requested`) {
         __privateSet(this, _state, `paused`);
       }
       return;
@@ -1107,7 +1169,8 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   }
   fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _lastOffset));
   fetchUrl.searchParams.set(LOG_MODE_QUERY_PARAM, __privateGet(this, _mode));
-  if (__privateGet(this, _isUpToDate)) {
+  const isSnapshotRequest = subsetParams !== void 0;
+  if (__privateGet(this, _isUpToDate) && !isSnapshotRequest) {
     if (!__privateGet(this, _isRefreshing) && !resumingFromPause) {
       fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`);
     }
@@ -1160,11 +1223,7 @@ onInitialResponse_fn = async function(response) {
   if (liveCacheBuster) {
     __privateSet(this, _liveCacheBuster, liveCacheBuster);
   }
-  const getSchema = () => {
-    const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER);
-    return schemaHeader ? JSON.parse(schemaHeader) : {};
-  };
-  __privateSet(this, _schema, (_a = __privateGet(this, _schema)) != null ? _a : getSchema());
+  __privateSet(this, _schema, (_a = __privateGet(this, _schema)) != null ? _a : getSchemaFromHeaders(headers));
   if (status === 204) {
     __privateSet(this, _lastSyncedAt, Date.now());
   }
@@ -1287,7 +1346,10 @@ pause_fn = function() {
   }
 };
 resume_fn = function() {
-  if (__privateGet(this, _started) && __privateGet(this, _state) === `paused`) {
+  if (__privateGet(this, _started) && (__privateGet(this, _state) === `paused` || __privateGet(this, _state) === `pause-requested`)) {
+    if (__privateGet(this, _state) === `pause-requested`) {
+      __privateSet(this, _state, `active`);
+    }
     __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
   }
 };
@@ -1353,6 +1415,9 @@ subscribeToVisibilityChanges_fn = function() {
       }
     };
     document.addEventListener(`visibilitychange`, visibilityHandler);
+    __privateSet(this, _unsubscribeFromVisibilityChanges, () => {
+      document.removeEventListener(`visibilitychange`, visibilityHandler);
+    });
   }
 };
 /**
@@ -1371,31 +1436,20 @@ reset_fn = function(handle) {
   __privateSet(this, _consecutiveShortSseConnections, 0);
   __privateSet(this, _sseFallbackToLongPolling, false);
 };
-fetchSnapshot_fn = async function(url, headers) {
-  const response = await __privateGet(this, _fetchClient2).call(this, url.toString(), { headers });
-  if (!response.ok) {
-    throw new FetchError(
-      response.status,
-      void 0,
-      void 0,
-      Object.fromEntries([...response.headers.entries()]),
-      url.toString()
-    );
-  }
-  const { metadata, data } = await response.json();
-  const batch = __privateGet(this, _messageParser).parse(
-    JSON.stringify(data),
-    __privateGet(this, _schema)
-  );
-  return {
-    metadata,
-    data: batch
-  };
-};
 ShapeStream.Replica = {
   FULL: `full`,
   DEFAULT: `default`
 };
+function getSchemaFromHeaders(headers, options) {
+  const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER);
+  if (!schemaHeader) {
+    if ((options == null ? void 0 : options.required) && (options == null ? void 0 : options.url)) {
+      throw new MissingHeadersError(options.url, [SHAPE_SCHEMA_HEADER]);
+    }
+    return {};
+  }
+  return JSON.parse(schemaHeader);
+}
 function validateParams(params) {
   if (!params) return;
   const reservedParams = Object.keys(params).filter(