@electric-sql/client 1.0.9 → 1.0.11

package/dist/index.legacy-esm.js

@@ -37,6 +37,14 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var __privateWrapper = (obj, member, setter, getter) => ({
+  set _(value) {
+    __privateSet(obj, member, value, setter);
+  },
+  get _() {
+    return __privateGet(obj, member, getter);
+  }
+});
 
 // src/error.ts
 var FetchError = class _FetchError extends Error {
@@ -188,8 +196,9 @@ function pgArrayParser(value, parser) {
   return loop(value)[0];
 }
 var MessageParser = class {
-  constructor(parser) {
+  constructor(parser, transformer) {
     this.parser = __spreadValues(__spreadValues({}, defaultParser), parser);
+    this.transformer = transformer;
   }
   parse(messages, schema) {
     return JSON.parse(messages, (key, value) => {
@@ -198,6 +207,7 @@ var MessageParser = class {
         Object.keys(row).forEach((key2) => {
           row[key2] = this.parseRow(key2, row[key2], schema);
         });
+        if (this.transformer) value = this.transformer(value);
       }
       return value;
     });
@@ -254,6 +264,13 @@ function getOffset(message) {
   }
   return `${lsn}_0`;
 }
+function isVisibleInSnapshot(txid, snapshot) {
+  const xid = BigInt(txid);
+  const xmin = BigInt(snapshot.xmin);
+  const xmax = BigInt(snapshot.xmax);
+  const xip = snapshot.xip_list.map(BigInt);
+  return xid < xmin || xid < xmax && !xip.includes(xid);
+}
 
 // src/constants.ts
 var LIVE_CACHE_BUSTER_HEADER = `electric-cursor`;
@@ -263,6 +280,7 @@ var SHAPE_SCHEMA_HEADER = `electric-schema`;
 var CHUNK_UP_TO_DATE_HEADER = `electric-up-to-date`;
 var COLUMNS_QUERY_PARAM = `columns`;
 var LIVE_CACHE_BUSTER_QUERY_PARAM = `cursor`;
+var EXPIRED_HANDLE_QUERY_PARAM = `expired_handle`;
 var SHAPE_HANDLE_QUERY_PARAM = `handle`;
 var LIVE_QUERY_PARAM = `live`;
 var OFFSET_QUERY_PARAM = `offset`;
@@ -273,11 +291,24 @@ var WHERE_PARAMS_PARAM = `params`;
 var EXPERIMENTAL_LIVE_SSE_QUERY_PARAM = `experimental_live_sse`;
 var FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`;
 var PAUSE_STREAM = `pause-stream`;
+var LOG_MODE_QUERY_PARAM = `log`;
+var SUBSET_PARAM_WHERE = `subset__where`;
+var SUBSET_PARAM_LIMIT = `subset__limit`;
+var SUBSET_PARAM_OFFSET = `subset__offset`;
+var SUBSET_PARAM_ORDER_BY = `subset__order_by`;
+var SUBSET_PARAM_WHERE_PARAMS = `subset__params`;
 var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   LIVE_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
-  LIVE_CACHE_BUSTER_QUERY_PARAM
+  LIVE_CACHE_BUSTER_QUERY_PARAM,
+  EXPIRED_HANDLE_QUERY_PARAM,
+  LOG_MODE_QUERY_PARAM,
+  SUBSET_PARAM_WHERE,
+  SUBSET_PARAM_LIMIT,
+  SUBSET_PARAM_OFFSET,
+  SUBSET_PARAM_ORDER_BY,
+  SUBSET_PARAM_WHERE_PARAMS
 ];
 
 // src/fetch.ts
@@ -388,10 +419,20 @@ function createFetchWithResponseHeadersCheck(fetchClient) {
       const headers = response.headers;
       const missingHeaders = [];
       const addMissingHeaders = (requiredHeaders) => missingHeaders.push(...requiredHeaders.filter((h) => !headers.has(h)));
-      addMissingHeaders(requiredElectricResponseHeaders);
       const input = args[0];
       const urlString = input.toString();
       const url = new URL(urlString);
+      const isSnapshotRequest = [
+        SUBSET_PARAM_WHERE,
+        SUBSET_PARAM_WHERE_PARAMS,
+        SUBSET_PARAM_LIMIT,
+        SUBSET_PARAM_OFFSET,
+        SUBSET_PARAM_ORDER_BY
+      ].some((p) => url.searchParams.has(p));
+      if (isSnapshotRequest) {
+        return response;
+      }
+      addMissingHeaders(requiredElectricResponseHeaders);
       if (url.searchParams.get(LIVE_QUERY_PARAM) === `true`) {
         addMissingHeaders(requiredLiveResponseHeaders);
       }
@@ -507,6 +548,123 @@ function noop() {
 import {
   fetchEventSource
 } from "@microsoft/fetch-event-source";
+
+// src/expired-shapes-cache.ts
+var ExpiredShapesCache = class {
+  constructor() {
+    this.data = {};
+    this.max = 250;
+    this.storageKey = `electric_expired_shapes`;
+    this.load();
+  }
+  getExpiredHandle(shapeUrl) {
+    const entry = this.data[shapeUrl];
+    if (entry) {
+      entry.lastUsed = Date.now();
+      this.save();
+      return entry.expiredHandle;
+    }
+    return null;
+  }
+  markExpired(shapeUrl, handle) {
+    this.data[shapeUrl] = { expiredHandle: handle, lastUsed: Date.now() };
+    const keys = Object.keys(this.data);
+    if (keys.length > this.max) {
+      const oldest = keys.reduce(
+        (min, k) => this.data[k].lastUsed < this.data[min].lastUsed ? k : min
+      );
+      delete this.data[oldest];
+    }
+    this.save();
+  }
+  save() {
+    if (typeof localStorage === `undefined`) return;
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.data));
+    } catch (e) {
+    }
+  }
+  load() {
+    if (typeof localStorage === `undefined`) return;
+    try {
+      const stored = localStorage.getItem(this.storageKey);
+      if (stored) {
+        this.data = JSON.parse(stored);
+      }
+    } catch (e) {
+      this.data = {};
+    }
+  }
+  clear() {
+    this.data = {};
+    this.save();
+  }
+};
+var expiredShapesCache = new ExpiredShapesCache();
+
+// src/snapshot-tracker.ts
+var SnapshotTracker = class {
+  constructor() {
+    this.activeSnapshots = /* @__PURE__ */ new Map();
+    this.xmaxSnapshots = /* @__PURE__ */ new Map();
+    this.snapshotsByDatabaseLsn = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Add a new snapshot for tracking
+   */
+  addSnapshot(metadata, keys) {
+    var _a, _b, _c, _d;
+    this.activeSnapshots.set(metadata.snapshot_mark, {
+      xmin: BigInt(metadata.xmin),
+      xmax: BigInt(metadata.xmax),
+      xip_list: metadata.xip_list.map(BigInt),
+      keys
+    });
+    const xmaxSet = (_b = (_a = this.xmaxSnapshots.get(BigInt(metadata.xmax))) == null ? void 0 : _a.add(metadata.snapshot_mark)) != null ? _b : /* @__PURE__ */ new Set([metadata.snapshot_mark]);
+    this.xmaxSnapshots.set(BigInt(metadata.xmax), xmaxSet);
+    const databaseLsnSet = (_d = (_c = this.snapshotsByDatabaseLsn.get(BigInt(metadata.database_lsn))) == null ? void 0 : _c.add(metadata.snapshot_mark)) != null ? _d : /* @__PURE__ */ new Set([metadata.snapshot_mark]);
+    this.snapshotsByDatabaseLsn.set(
+      BigInt(metadata.database_lsn),
+      databaseLsnSet
+    );
+  }
+  /**
+   * Remove a snapshot from tracking
+   */
+  removeSnapshot(snapshotMark) {
+    this.activeSnapshots.delete(snapshotMark);
+  }
+  /**
+   * Check if a change message should be filtered because its already in an active snapshot
+   * Returns true if the message should be filtered out (not processed)
+   */
+  shouldRejectMessage(message) {
+    const txids = message.headers.txids || [];
+    if (txids.length === 0) return false;
+    const xid = Math.max(...txids);
+    for (const [xmax, snapshots] of this.xmaxSnapshots.entries()) {
+      if (xid >= xmax) {
+        for (const snapshot of snapshots) {
+          this.removeSnapshot(snapshot);
+        }
+      }
+    }
+    return [...this.activeSnapshots.values()].some(
+      (x) => x.keys.has(message.key) && isVisibleInSnapshot(xid, x)
+    );
+  }
+  lastSeenUpdate(newDatabaseLsn) {
+    for (const [dbLsn, snapshots] of this.snapshotsByDatabaseLsn.entries()) {
+      if (dbLsn <= newDatabaseLsn) {
+        for (const snapshot of snapshots) {
+          this.removeSnapshot(snapshot);
+        }
+      }
+    }
+  }
+};
+
+// src/client.ts
 var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   LIVE_CACHE_BUSTER_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
@@ -543,9 +701,18 @@ async function resolveHeaders(headers) {
   );
   return Object.fromEntries(resolvedEntries);
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _connected, _shapeHandle, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _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, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn;
+function canonicalShapeKey(url) {
+  const cleanUrl = new URL(url.origin + url.pathname);
+  for (const [key, value] of url.searchParams) {
+    if (!ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) {
+      cleanUrl.searchParams.set(key, value);
+    }
+  }
+  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, _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 ShapeStream = class {
-  // promise chain for incoming messages
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
     __privateAdd(this, _error, null);
@@ -561,8 +728,10 @@ var ShapeStream = class {
     __privateAdd(this, _lastSyncedAt);
     // unix time
     __privateAdd(this, _isUpToDate, false);
+    __privateAdd(this, _isMidStream, true);
     __privateAdd(this, _connected, false);
     __privateAdd(this, _shapeHandle);
+    __privateAdd(this, _mode);
     __privateAdd(this, _schema);
     __privateAdd(this, _onError);
     __privateAdd(this, _requestAbortController);
@@ -571,16 +740,26 @@ var ShapeStream = class {
     __privateAdd(this, _tickPromiseResolver);
     __privateAdd(this, _tickPromiseRejecter);
     __privateAdd(this, _messageChain, Promise.resolve([]));
-    var _a, _b, _c;
+    // promise chain for incoming messages
+    __privateAdd(this, _snapshotTracker, new SnapshotTracker());
+    __privateAdd(this, _activeSnapshotRequests, 0);
+    // counter for concurrent snapshot requests
+    __privateAdd(this, _midStreamPromise);
+    __privateAdd(this, _midStreamPromiseResolver);
+    var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
     __privateSet(this, _lastOffset, (_a = this.options.offset) != null ? _a : `-1`);
     __privateSet(this, _liveCacheBuster, ``);
     __privateSet(this, _shapeHandle, this.options.handle);
-    __privateSet(this, _messageParser, new MessageParser(options.parser));
+    __privateSet(this, _messageParser, new MessageParser(
+      options.parser,
+      options.transformer
+    ));
     __privateSet(this, _onError, this.options.onError);
-    const baseFetchClient = (_b = options.fetchClient) != null ? _b : (...args) => fetch(...args);
-    const backOffOpts = __spreadProps(__spreadValues({}, (_c = options.backoffOptions) != null ? _c : BackoffDefaults), {
+    __privateSet(this, _mode, (_b = this.options.mode) != null ? _b : `full`);
+    const baseFetchClient = (_c = options.fetchClient) != null ? _c : (...args) => fetch(...args);
+    const backOffOpts = __spreadProps(__spreadValues({}, (_d = options.backoffOptions) != null ? _d : BackoffDefaults), {
       onFailedAttempt: () => {
         var _a2, _b2;
         __privateSet(this, _connected, false);
@@ -609,6 +788,9 @@ var ShapeStream = class {
   get lastOffset() {
     return __privateGet(this, _lastOffset);
   }
+  get mode() {
+    return __privateGet(this, _mode);
+  }
   subscribe(callback, onError = () => {
   }) {
     const subscriptionId = Math.random();
@@ -659,6 +841,54 @@ var ShapeStream = class {
     await __privateMethod(this, _ShapeStream_instances, nextTick_fn).call(this);
     __privateSet(this, _isRefreshing, false);
   }
+  /**
+   * Request a snapshot for subset of data.
+   *
+   * Only available when mode is `changes_only`.
+   * Returns the insertion point & the data, but more importantly injects the data
+   * into the subscribed data stream. Returned value is unlikely to be useful for the caller,
+   * unless the caller has complicated additional logic.
+   *
+   * Data will be injected in a way that's also tracking further incoming changes, and it'll
+   * skip the ones that are already in the snapshot.
+   *
+   * @param opts - The options for the snapshot request.
+   * @returns The metadata and the data for the snapshot.
+   */
+  async requestSnapshot(opts) {
+    if (__privateGet(this, _mode) === `full`) {
+      throw new Error(
+        `Snapshot requests are not supported in ${__privateGet(this, _mode)} mode, as the consumer is guaranteed to observe all data`
+      );
+    }
+    if (!__privateGet(this, _started)) await __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
+    await __privateMethod(this, _ShapeStream_instances, waitForStreamEnd_fn).call(this);
+    __privateWrapper(this, _activeSnapshotRequests)._++;
+    try {
+      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 dataWithEndBoundary = data.concat([
+        { headers: __spreadValues({ control: `snapshot-end` }, metadata) }
+      ]);
+      __privateGet(this, _snapshotTracker).addSnapshot(
+        metadata,
+        new Set(data.map((message) => message.key))
+      );
+      __privateMethod(this, _ShapeStream_instances, onMessages_fn).call(this, dataWithEndBoundary, false);
+      return {
+        metadata,
+        data
+      };
+    } finally {
+      __privateWrapper(this, _activeSnapshotRequests)._--;
+      if (__privateGet(this, _activeSnapshotRequests) === 0) {
+        __privateMethod(this, _ShapeStream_instances, resume_fn).call(this);
+      }
+    }
+  }
 };
 _error = new WeakMap();
 _fetchClient2 = new WeakMap();
@@ -671,8 +901,10 @@ _lastOffset = new WeakMap();
 _liveCacheBuster = new WeakMap();
 _lastSyncedAt = new WeakMap();
 _isUpToDate = new WeakMap();
+_isMidStream = new WeakMap();
 _connected = new WeakMap();
 _shapeHandle = new WeakMap();
+_mode = new WeakMap();
 _schema = new WeakMap();
 _onError = new WeakMap();
 _requestAbortController = new WeakMap();
@@ -681,6 +913,10 @@ _tickPromise = new WeakMap();
 _tickPromiseResolver = new WeakMap();
 _tickPromiseRejecter = new WeakMap();
 _messageChain = new WeakMap();
+_snapshotTracker = new WeakMap();
+_activeSnapshotRequests = new WeakMap();
+_midStreamPromise = new WeakMap();
+_midStreamPromiseResolver = new WeakMap();
 _ShapeStream_instances = new WeakSet();
 start_fn = async function() {
   var _a;
@@ -744,6 +980,10 @@ requestShape_fn = async function() {
     }
     if (!(e instanceof FetchError)) throw e;
     if (e.status == 409) {
+      if (__privateGet(this, _shapeHandle)) {
+        const shapeKey = canonicalShapeKey(fetchUrl);
+        expiredShapesCache.markExpired(shapeKey, __privateGet(this, _shapeHandle));
+      }
       const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER] || `${__privateGet(this, _shapeHandle)}-next`;
       __privateMethod(this, _ShapeStream_instances, reset_fn).call(this, newShapeHandle);
       await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, e.json);
@@ -761,14 +1001,12 @@ requestShape_fn = async function() {
   (_b = __privateGet(this, _tickPromiseResolver)) == null ? void 0 : _b.call(this);
   return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
 };
-constructUrl_fn = async function(url, resumingFromPause) {
+constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   const [requestHeaders, params] = await Promise.all([
     resolveHeaders(this.options.headers),
     this.options.params ? toInternalParams(convertWhereParamsToObj(this.options.params)) : void 0
   ]);
-  if (params) {
-    validateParams(params);
-  }
+  if (params) validateParams(params);
   const fetchUrl = new URL(url);
   if (params) {
     if (params.table) setQueryParam(fetchUrl, TABLE_QUERY_PARAM, params.table);
@@ -788,7 +1026,20 @@ constructUrl_fn = async function(url, resumingFromPause) {
       setQueryParam(fetchUrl, key, value);
     }
   }
+  if (subsetParams) {
+    if (subsetParams.where)
+      setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, subsetParams.where);
+    if (subsetParams.params)
+      setQueryParam(fetchUrl, SUBSET_PARAM_WHERE_PARAMS, subsetParams.params);
+    if (subsetParams.limit)
+      setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit);
+    if (subsetParams.offset)
+      setQueryParam(fetchUrl, SUBSET_PARAM_OFFSET, subsetParams.offset);
+    if (subsetParams.orderBy)
+      setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, subsetParams.orderBy);
+  }
   fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _lastOffset));
+  fetchUrl.searchParams.set(LOG_MODE_QUERY_PARAM, __privateGet(this, _mode));
   if (__privateGet(this, _isUpToDate)) {
     if (!__privateGet(this, _isRefreshing) && !resumingFromPause) {
       fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`);
@@ -801,6 +1052,11 @@ constructUrl_fn = async function(url, resumingFromPause) {
   if (__privateGet(this, _shapeHandle)) {
     fetchUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, __privateGet(this, _shapeHandle));
   }
+  const shapeKey = canonicalShapeKey(fetchUrl);
+  const expiredHandle = expiredShapesCache.getExpiredHandle(shapeKey);
+  if (expiredHandle) {
+    fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle);
+  }
   fetchUrl.searchParams.sort();
   return {
     fetchUrl,
@@ -847,7 +1103,9 @@ onInitialResponse_fn = async function(response) {
   }
 };
 onMessages_fn = async function(batch, isSseMessage = false) {
+  var _a;
   if (batch.length > 0) {
+    __privateSet(this, _isMidStream, true);
     const lastMessage = batch[batch.length - 1];
     if (isUpToDateMessage(lastMessage)) {
       if (isSseMessage) {
@@ -858,8 +1116,16 @@ onMessages_fn = async function(batch, isSseMessage = false) {
       }
       __privateSet(this, _lastSyncedAt, Date.now());
       __privateSet(this, _isUpToDate, true);
+      __privateSet(this, _isMidStream, false);
+      (_a = __privateGet(this, _midStreamPromiseResolver)) == null ? void 0 : _a.call(this);
     }
-    await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, batch);
+    const messagesToProcess = batch.filter((message) => {
+      if (isChangeMessage(message)) {
+        return !__privateGet(this, _snapshotTracker).shouldRejectMessage(message);
+      }
+      return true;
+    });
+    await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, messagesToProcess);
   }
 };
 fetchShape_fn = async function(opts) {
@@ -948,6 +1214,22 @@ nextTick_fn = async function() {
   });
   return __privateGet(this, _tickPromise);
 };
+waitForStreamEnd_fn = async function() {
+  if (!__privateGet(this, _isMidStream)) {
+    return;
+  }
+  if (__privateGet(this, _midStreamPromise)) {
+    return __privateGet(this, _midStreamPromise);
+  }
+  __privateSet(this, _midStreamPromise, new Promise((resolve) => {
+    __privateSet(this, _midStreamPromiseResolver, resolve);
+  }));
+  __privateGet(this, _midStreamPromise).finally(() => {
+    __privateSet(this, _midStreamPromise, void 0);
+    __privateSet(this, _midStreamPromiseResolver, void 0);
+  });
+  return __privateGet(this, _midStreamPromise);
+};
 publish_fn = async function(messages) {
   __privateSet(this, _messageChain, __privateGet(this, _messageChain).then(
     () => Promise.all(
@@ -990,8 +1272,31 @@ reset_fn = function(handle) {
   __privateSet(this, _liveCacheBuster, ``);
   __privateSet(this, _shapeHandle, handle);
   __privateSet(this, _isUpToDate, false);
+  __privateSet(this, _isMidStream, true);
   __privateSet(this, _connected, false);
   __privateSet(this, _schema, void 0);
+  __privateSet(this, _activeSnapshotRequests, 0);
+};
+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`,
@@ -1013,7 +1318,7 @@ function validateOptions(options) {
   if (options.signal && !(options.signal instanceof AbortSignal)) {
     throw new InvalidSignalError();
   }
-  if (options.offset !== void 0 && options.offset !== `-1` && !options.handle) {
+  if (options.offset !== void 0 && options.offset !== `-1` && options.offset !== `now` && !options.handle) {
     throw new MissingShapeHandleError();
   }
   validateParams(options.params);
@@ -1042,12 +1347,15 @@ function convertWhereParamsToObj(allPgParams) {
 }
 
 // src/shape.ts
-var _data, _subscribers2, _status, _error2, _Shape_instances, process_fn, updateShapeStatus_fn, handleError_fn, notify_fn;
+var _data, _subscribers2, _insertedKeys, _requestedSubSnapshots, _reexecuteSnapshotsPending, _status, _error2, _Shape_instances, process_fn, reexecuteSnapshots_fn, awaitUpToDate_fn, updateShapeStatus_fn, handleError_fn, notify_fn;
 var Shape = class {
   constructor(stream) {
     __privateAdd(this, _Shape_instances);
     __privateAdd(this, _data, /* @__PURE__ */ new Map());
     __privateAdd(this, _subscribers2, /* @__PURE__ */ new Map());
+    __privateAdd(this, _insertedKeys, /* @__PURE__ */ new Set());
+    __privateAdd(this, _requestedSubSnapshots, /* @__PURE__ */ new Set());
+    __privateAdd(this, _reexecuteSnapshotsPending, false);
     __privateAdd(this, _status, `syncing`);
     __privateAdd(this, _error2, false);
     this.stream = stream;
@@ -1106,6 +1414,20 @@ var Shape = class {
   isConnected() {
     return this.stream.isConnected();
   }
+  /** Current log mode of the underlying stream */
+  get mode() {
+    return this.stream.mode;
+  }
+  /**
+   * Request a snapshot for subset of data. Only available when mode is changes_only.
+   * Returns void; data will be emitted via the stream and processed by this Shape.
+   */
+  async requestSnapshot(params) {
+    const key = JSON.stringify(params);
+    __privateGet(this, _requestedSubSnapshots).add(key);
+    await __privateMethod(this, _Shape_instances, awaitUpToDate_fn).call(this);
+    await this.stream.requestSnapshot(params);
+  }
   subscribe(callback) {
     const subscriptionId = Math.random();
     __privateGet(this, _subscribers2).set(subscriptionId, callback);
@@ -1122,6 +1444,9 @@ var Shape = class {
 };
 _data = new WeakMap();
 _subscribers2 = new WeakMap();
+_insertedKeys = new WeakMap();
+_requestedSubSnapshots = new WeakMap();
+_reexecuteSnapshotsPending = new WeakMap();
 _status = new WeakMap();
 _error2 = new WeakMap();
 _Shape_instances = new WeakSet();
@@ -1130,33 +1455,89 @@ process_fn = function(messages) {
   messages.forEach((message) => {
     if (isChangeMessage(message)) {
       shouldNotify = __privateMethod(this, _Shape_instances, updateShapeStatus_fn).call(this, `syncing`);
-      switch (message.headers.operation) {
-        case `insert`:
-          __privateGet(this, _data).set(message.key, message.value);
-          break;
-        case `update`:
-          __privateGet(this, _data).set(message.key, __spreadValues(__spreadValues({}, __privateGet(this, _data).get(message.key)), message.value));
-          break;
-        case `delete`:
-          __privateGet(this, _data).delete(message.key);
-          break;
+      if (this.mode === `full`) {
+        switch (message.headers.operation) {
+          case `insert`:
+            __privateGet(this, _data).set(message.key, message.value);
+            break;
+          case `update`:
+            __privateGet(this, _data).set(message.key, __spreadValues(__spreadValues({}, __privateGet(this, _data).get(message.key)), message.value));
+            break;
+          case `delete`:
+            __privateGet(this, _data).delete(message.key);
+            break;
+        }
+      } else {
+        switch (message.headers.operation) {
+          case `insert`:
+            __privateGet(this, _insertedKeys).add(message.key);
+            __privateGet(this, _data).set(message.key, message.value);
+            break;
+          case `update`:
+            if (__privateGet(this, _insertedKeys).has(message.key)) {
+              __privateGet(this, _data).set(message.key, __spreadValues(__spreadValues({}, __privateGet(this, _data).get(message.key)), message.value));
+            }
+            break;
+          case `delete`:
+            if (__privateGet(this, _insertedKeys).has(message.key)) {
+              __privateGet(this, _data).delete(message.key);
+              __privateGet(this, _insertedKeys).delete(message.key);
+            }
+            break;
+        }
       }
     }
     if (isControlMessage(message)) {
       switch (message.headers.control) {
         case `up-to-date`:
           shouldNotify = __privateMethod(this, _Shape_instances, updateShapeStatus_fn).call(this, `up-to-date`);
+          if (__privateGet(this, _reexecuteSnapshotsPending)) {
+            __privateSet(this, _reexecuteSnapshotsPending, false);
+            void __privateMethod(this, _Shape_instances, reexecuteSnapshots_fn).call(this);
+          }
           break;
         case `must-refetch`:
           __privateGet(this, _data).clear();
+          __privateGet(this, _insertedKeys).clear();
           __privateSet(this, _error2, false);
           shouldNotify = __privateMethod(this, _Shape_instances, updateShapeStatus_fn).call(this, `syncing`);
+          __privateSet(this, _reexecuteSnapshotsPending, true);
           break;
       }
     }
   });
   if (shouldNotify) __privateMethod(this, _Shape_instances, notify_fn).call(this);
 };
+reexecuteSnapshots_fn = async function() {
+  await __privateMethod(this, _Shape_instances, awaitUpToDate_fn).call(this);
+  await Promise.all(
+    Array.from(__privateGet(this, _requestedSubSnapshots)).map(async (jsonParams) => {
+      try {
+        const snapshot = JSON.parse(jsonParams);
+        await this.stream.requestSnapshot(snapshot);
+      } catch (_) {
+      }
+    })
+  );
+};
+awaitUpToDate_fn = async function() {
+  if (this.stream.isUpToDate) return;
+  await new Promise((resolve) => {
+    const check = () => {
+      if (this.stream.isUpToDate) {
+        clearInterval(interval);
+        unsub();
+        resolve();
+      }
+    };
+    const interval = setInterval(check, 10);
+    const unsub = this.stream.subscribe(
+      () => check(),
+      () => check()
+    );
+    check();
+  });
+};
 updateShapeStatus_fn = function(status) {
   const stateChanged = __privateGet(this, _status) !== status;
   __privateSet(this, _status, status);
@@ -1181,6 +1562,7 @@ export {
   ShapeStream,
   isChangeMessage,
   isControlMessage,
+  isVisibleInSnapshot,
   resolveValue
 };
 //# sourceMappingURL=index.legacy-esm.js.map