@electric-sql/client 1.0.9 → 1.0.11

package/dist/cjs/index.cjs

@@ -53,6 +53,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);
+  }
+});
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -84,6 +92,7 @@ __export(src_exports, {
   ShapeStream: () => ShapeStream,
   isChangeMessage: () => isChangeMessage,
   isControlMessage: () => isControlMessage,
+  isVisibleInSnapshot: () => isVisibleInSnapshot,
   resolveValue: () => resolveValue
 });
 module.exports = __toCommonJS(src_exports);
@@ -240,8 +249,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) => {
@@ -250,6 +260,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;
     });
@@ -306,6 +317,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`;
@@ -315,6 +333,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`;
@@ -325,11 +344,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
@@ -440,10 +472,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);
       }
@@ -557,6 +599,123 @@ function noop() {
 
 // src/client.ts
 var import_fetch_event_source = require("@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,
@@ -601,9 +760,18 @@ 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);
@@ -619,8 +787,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);
@@ -629,16 +799,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);
@@ -667,6 +847,9 @@ var ShapeStream = class {
   get lastOffset() {
     return __privateGet(this, _lastOffset);
   }
+  get mode() {
+    return __privateGet(this, _mode);
+  }
   subscribe(callback, onError = () => {
   }) {
     const subscriptionId = Math.random();
@@ -719,6 +902,56 @@ var ShapeStream = class {
       __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.
+   */
+  requestSnapshot(opts) {
+    return __async(this, null, function* () {
+      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)) yield __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
+      yield __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 } = yield __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
+        const { metadata, data } = yield __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();
@@ -731,8 +964,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();
@@ -741,6 +976,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 = function() {
   return __async(this, null, function* () {
@@ -807,6 +1046,10 @@ requestShape_fn = 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);
         yield __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, e.json);
@@ -825,15 +1068,13 @@ requestShape_fn = function() {
     return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
   });
 };
-constructUrl_fn = function(url, resumingFromPause) {
+constructUrl_fn = function(url, resumingFromPause, subsetParams) {
   return __async(this, null, function* () {
     const [requestHeaders, params] = yield 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);
@@ -853,7 +1094,20 @@ constructUrl_fn = 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`);
@@ -866,6 +1120,11 @@ constructUrl_fn = 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,
@@ -918,7 +1177,9 @@ onInitialResponse_fn = function(response) {
 };
 onMessages_fn = function(batch, isSseMessage = false) {
   return __async(this, null, function* () {
+    var _a;
     if (batch.length > 0) {
+      __privateSet(this, _isMidStream, true);
       const lastMessage = batch[batch.length - 1];
       if (isUpToDateMessage(lastMessage)) {
         if (isSseMessage) {
@@ -929,8 +1190,16 @@ onMessages_fn = 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);
       }
-      yield __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;
+      });
+      yield __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, messagesToProcess);
     }
   });
 };
@@ -1028,6 +1297,24 @@ nextTick_fn = function() {
     return __privateGet(this, _tickPromise);
   });
 };
+waitForStreamEnd_fn = function() {
+  return __async(this, null, 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 = function(messages) {
   return __async(this, null, function* () {
     __privateSet(this, _messageChain, __privateGet(this, _messageChain).then(
@@ -1072,8 +1359,33 @@ 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 = function(url, headers) {
+  return __async(this, null, function* () {
+    const response = yield __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 } = yield response.json();
+    const batch = __privateGet(this, _messageParser).parse(
+      JSON.stringify(data),
+      __privateGet(this, _schema)
+    );
+    return {
+      metadata,
+      data: batch
+    };
+  });
 };
 ShapeStream.Replica = {
   FULL: `full`,
@@ -1095,7 +1407,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);
@@ -1124,12 +1436,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;
@@ -1188,6 +1503,22 @@ 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.
+   */
+  requestSnapshot(params) {
+    return __async(this, null, function* () {
+      const key = JSON.stringify(params);
+      __privateGet(this, _requestedSubSnapshots).add(key);
+      yield __privateMethod(this, _Shape_instances, awaitUpToDate_fn).call(this);
+      yield this.stream.requestSnapshot(params);
+    });
+  }
   subscribe(callback) {
     const subscriptionId = Math.random();
     __privateGet(this, _subscribers2).set(subscriptionId, callback);
@@ -1204,6 +1535,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();
@@ -1212,33 +1546,93 @@ 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 = function() {
+  return __async(this, null, function* () {
+    yield __privateMethod(this, _Shape_instances, awaitUpToDate_fn).call(this);
+    yield Promise.all(
+      Array.from(__privateGet(this, _requestedSubSnapshots)).map((jsonParams) => __async(this, null, function* () {
+        try {
+          const snapshot = JSON.parse(jsonParams);
+          yield this.stream.requestSnapshot(snapshot);
+        } catch (_) {
+        }
+      }))
+    );
+  });
+};
+awaitUpToDate_fn = function() {
+  return __async(this, null, function* () {
+    if (this.stream.isUpToDate) return;
+    yield 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);
@@ -1264,6 +1658,7 @@ notify_fn = function() {
   ShapeStream,
   isChangeMessage,
   isControlMessage,
+  isVisibleInSnapshot,
   resolveValue
 });
 //# sourceMappingURL=index.cjs.map