powersync-bridge 0.0.1-alpha.1 → 0.0.1-alpha.2

package/dist/index.js

@@ -1,5 +1,5 @@
-import { rowComparator, idOf, keyColumns, cursorOfRow, streamKey, isAfterCursor, FreshnessTracker } from './chunk-KAR4QIIU.js';
-export { cursorOfRow, decodeCursor, encodeCursor, keyColumns, rowComparator } from './chunk-KAR4QIIU.js';
+import { rowComparator, idOf, keyColumns, cursorOfRow, streamKey, isAfterCursor, FreshnessTracker } from './chunk-WJDQWVO5.js';
+export { cursorOfRow, decodeCursor, encodeCursor, keyColumns, rowComparator } from './chunk-WJDQWVO5.js';
 
 // src/clock.ts
 var realClock = {
@@ -69,6 +69,89 @@ async function classifyRemovals(ctx, removed) {
   return out;
 }
 
+// src/refresh.ts
+var CoalescedRefresh = class {
+  constructor(read, settled) {
+    this.read = read;
+    this.settled = settled;
+  }
+  read;
+  settled;
+  revision = 0;
+  lifecycle = 0;
+  scheduled = false;
+  running = false;
+  get pending() {
+    return this.scheduled || this.running;
+  }
+  request() {
+    this.revision += 1;
+    if (this.pending) return;
+    this.scheduled = true;
+    const lifecycle = this.lifecycle;
+    queueMicrotask(() => {
+      if (lifecycle !== this.lifecycle) return;
+      this.scheduled = false;
+      void this.drain(lifecycle);
+    });
+  }
+  /** Fence queued/late work without retaining results or preventing a later resume. */
+  cancel() {
+    this.lifecycle += 1;
+    this.scheduled = false;
+    this.running = false;
+  }
+  async drain(lifecycle) {
+    this.running = true;
+    let revision;
+    try {
+      do {
+        revision = this.revision;
+        await this.read(() => lifecycle === this.lifecycle && revision === this.revision);
+      } while (lifecycle === this.lifecycle && revision !== this.revision);
+    } finally {
+      if (lifecycle === this.lifecycle) {
+        this.running = false;
+        this.settled();
+      }
+    }
+  }
+};
+var BackgroundReads = class {
+  running = false;
+  queue = /* @__PURE__ */ new Set();
+  run(read, signal) {
+    if (signal.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      const entry = {
+        cancel: () => {
+          if (!this.queue.delete(entry)) return;
+          signal.removeEventListener("abort", entry.cancel);
+          reject(signal.reason);
+        },
+        run: () => {
+          signal.removeEventListener("abort", entry.cancel);
+          this.running = true;
+          void Promise.resolve().then(read).then(resolve, reject).finally(() => {
+            this.running = false;
+            this.drain();
+          });
+        }
+      };
+      signal.addEventListener("abort", entry.cancel, { once: true });
+      this.queue.add(entry);
+      this.drain();
+    });
+  }
+  drain() {
+    if (this.running) return;
+    const next = this.queue.values().next().value;
+    if (!next) return;
+    this.queue.delete(next);
+    next.run();
+  }
+};
+
 // src/store.ts
 var SnapshotStore = class {
   snapshot;
@@ -136,12 +219,18 @@ var InfiniteQueryStore = class {
     this.pageSize = options.pageSize ?? 25;
     this.maxRows = options.maxRows ?? 500;
     if (!Number.isInteger(this.pageSize) || this.pageSize < 1 || !Number.isInteger(this.maxRows) || this.maxRows < this.pageSize)
-      throw new Error("powersync-bridge: pageSize must be positive and maxRows must be at least pageSize");
+      throw new Error(
+        "powersync-bridge: pageSize must be positive and maxRows must be at least pageSize"
+      );
     this.target = this.pageSize;
     this.compare = rowComparator(options.orderBy, options.direction ?? "desc");
     this.table = options.table;
     this.offline = this.readOffline();
     this.store = new SnapshotStore(this.result());
+    this.checkpointRefresh = new CoalescedRefresh(
+      (isCurrent) => this.checkpoint(isCurrent),
+      () => this.render()
+    );
   }
   deps;
   options;
@@ -170,6 +259,9 @@ var InfiniteQueryStore = class {
   watchGeneration = 0;
   lastLocalWatch = 0;
   refs = 0;
+  activeRefs = 0;
+  checkpointRefresh;
+  localAbort = new AbortController();
   ready = false;
   disposed = false;
   unwatch;
@@ -179,12 +271,19 @@ var InfiniteQueryStore = class {
   get isDisposed() {
     return this.disposed || this.refs <= 0 && this.unwatch !== void 0;
   }
-  retain() {
+  retain(active = true) {
     this.refs += 1;
-    if (this.refs !== 1 || this.unwatch || this.options.enabled === false) return;
+    if (active) this.activeRefs += 1;
+    if (this.activeRefs <= 0 || this.unwatch || this.options.enabled === false || this.disposed)
+      return;
+    this.offline = this.readOffline();
+    this.apiFailed = false;
+    this.apiError = void 0;
     this.stops = [
       this.deps.crud.onChange(() => this.render()),
-      this.deps.freshness.onCompletion(() => void this.checkpoint()),
+      this.deps.freshness.onCompletion((completion) => {
+        if (completion.stream === null) this.checkpointRefresh.request();
+      }),
       this.deps.driver.onStatusChanged(() => this.networkChanged()),
       this.deps.connectivity.subscribe(() => this.networkChanged())
     ];
@@ -199,12 +298,13 @@ var InfiniteQueryStore = class {
       this.render();
     });
   }
-  release() {
+  release(active = true) {
     this.refs -= 1;
-    if (this.refs <= 0)
-      queueMicrotask(() => {
-        if (this.refs <= 0) this.dispose();
-      });
+    if (active) this.activeRefs -= 1;
+    queueMicrotask(() => {
+      if (this.refs <= 0) this.dispose();
+      else if (this.activeRefs <= 0) this.pause();
+    });
   }
   swapRoot() {
     this.disposed = true;
@@ -215,13 +315,7 @@ var InfiniteQueryStore = class {
   }
   dispose() {
     this.disposed = true;
-    this.generation += 1;
-    this.watchGeneration += 1;
-    this.cancelRequest();
-    this.unwatch?.();
-    this.unwatch = void 0;
-    for (const stop of this.stops) stop();
-    this.stops = [];
+    this.pause();
     this.clearPages();
     this.local.clear();
     this.retained.clear();
@@ -230,6 +324,19 @@ var InfiniteQueryStore = class {
     this.inSession.clear();
     this.render(true);
   }
+  pause() {
+    this.generation += 1;
+    this.watchGeneration += 1;
+    this.checkpointRefresh.cancel();
+    this.localAbort.abort();
+    this.cancelRequest();
+    this.request = void 0;
+    this.apiPending = false;
+    this.unwatch?.();
+    this.unwatch = void 0;
+    for (const stop of this.stops) stop();
+    this.stops = [];
+  }
   readOffline() {
     return (this.deps.connectivity.getSnapshot() ?? this.deps.driver.onlineHint()) === false;
   }
@@ -248,6 +355,7 @@ var InfiniteQueryStore = class {
       this.generation += 1;
       this.apiPending = false;
       this.request = void 0;
+      this.watch();
     }
     if (reconnect) {
       this.apiFailed = false;
@@ -274,7 +382,11 @@ var InfiniteQueryStore = class {
     return this.options.query({ cursor: this.anchor, limit: this.target + 1 });
   }
   watch() {
+    if (this.activeRefs <= 0 || this.disposed) return;
     this.unwatch?.();
+    this.localAbort.abort();
+    this.localAbort = new AbortController();
+    this.checkpointRefresh.cancel();
     const token = ++this.watchGeneration;
     const generation = this.generation;
     this.localPending = true;
@@ -295,14 +407,16 @@ var InfiniteQueryStore = class {
     this.unwatch = this.deps.driver.diffs(prepared).subscribe(
       (diff) => {
         void this.acceptLocal(diff.all, token, generation).catch((error) => {
-          if (token !== this.watchGeneration || generation !== this.generation || this.disposed) return;
+          if (token !== this.watchGeneration || generation !== this.generation || this.disposed)
+            return;
           this.localPending = false;
           this.localError = error instanceof Error ? error : new Error(String(error));
           this.render();
         });
       },
       (error) => {
-        if (token !== this.watchGeneration || generation !== this.generation || this.disposed) return;
+        if (token !== this.watchGeneration || generation !== this.generation || this.disposed)
+          return;
         this.localPending = false;
         this.localError = error;
         this.render();
@@ -310,9 +424,10 @@ var InfiniteQueryStore = class {
     );
     this.render();
   }
-  async acceptLocal(rows, token, generation) {
+  async acceptLocal(rows, token, generation, stamp = this.deps.freshness.freshAtFor(void 0), isCurrent = () => true) {
     await this.deps.crud.resync();
-    if (token !== this.watchGeneration || generation !== this.generation || this.disposed) return;
+    if (token !== this.watchGeneration || generation !== this.generation || this.disposed || !isCurrent())
+      return;
     const previous = this.local;
     const firstEmission = this.lastLocalWatch !== token;
     this.lastLocalWatch = token;
@@ -333,7 +448,7 @@ var InfiniteQueryStore = class {
     this.local = next;
     this.localPending = false;
     this.localError = void 0;
-    this.localStamp = this.deps.freshness.freshAtFor(void 0);
+    this.localStamp = stamp;
     this.render();
     const groups = /* @__PURE__ */ new Map();
     for (const row of removed.values()) {
@@ -354,7 +469,8 @@ var InfiniteQueryStore = class {
           },
           group
         );
-        if (token !== this.watchGeneration || generation !== this.generation || this.disposed) return;
+        if (token !== this.watchGeneration || generation !== this.generation || this.disposed)
+          return;
         for (const row of removed.values()) {
           const identity = this.identity(row);
           if (identity.table !== table || this.local.has(row.id)) continue;
@@ -389,15 +505,21 @@ var InfiniteQueryStore = class {
     }
     this.render();
   }
-  async checkpoint() {
-    if (this.disposed || !this.unwatch) return;
+  async checkpoint(isCurrent) {
+    if (this.disposed || !this.unwatch || this.activeRefs <= 0) return;
     const token = this.watchGeneration;
     const generation = this.generation;
+    const stamp = this.deps.freshness.freshAtFor(void 0);
     try {
-      const rows = await this.deps.driver.query(this.deps.adapter.prepare(this.localBuilder()));
-      await this.acceptLocal(rows, token, generation);
+      const signal = this.localAbort.signal;
+      const read = () => isCurrent() ? this.deps.driver.query(this.deps.adapter.prepare(this.localBuilder()), signal) : Promise.resolve(void 0);
+      const rows = await (this.deps.backgroundReads ? this.deps.backgroundReads.run(read, signal) : read());
+      if (!rows) return;
+      if (!isCurrent()) return;
+      await this.acceptLocal(rows, token, generation, stamp, isCurrent);
     } catch (error) {
-      if (token !== this.watchGeneration || generation !== this.generation || this.disposed) return;
+      if (token !== this.watchGeneration || generation !== this.generation || this.disposed || !isCurrent())
+        return;
       this.localError = error instanceof Error ? error : new Error(String(error));
       this.render();
     }
@@ -422,7 +544,7 @@ var InfiniteQueryStore = class {
     return [row[first], row[second]];
   }
   pump() {
-    if (!this.ready || this.disposed || this.options.enabled === false || this.offline || this.apiPending || this.apiFailed || this.apiEnd())
+    if (!this.ready || this.activeRefs <= 0 || this.disposed || this.options.enabled === false || this.offline || this.apiPending || this.apiFailed || this.apiEnd())
       return;
     if (!this.table && !this.options.getRowIdentity) return;
     if (this.pages.length >= Math.ceil(this.maxRows / this.pageSize) + 1) return;
@@ -468,7 +590,9 @@ var InfiniteQueryStore = class {
         const before = rows[index - 1];
         const row = rows[index];
         if (before && row && this.compare(before, row) >= 0)
-          throw new Error("powersync-bridge: API rows must use a strict, stable order with an id tiebreaker");
+          throw new Error(
+            "powersync-bridge: API rows must use a strict, stable order with an id tiebreaker"
+          );
       }
       if (cursor !== void 0 && rows.some((row) => this.compare(row, cursor) <= 0))
         throw new Error("powersync-bridge: API page must advance beyond the supplied cursor");
@@ -561,14 +685,15 @@ var InfiniteQueryStore = class {
       this.store.replace(result);
   }
   fetchNextPage = () => {
-    if (this.disposed || this.options.enabled === false || this.target >= this.maxRows) return;
+    if (this.disposed || this.activeRefs <= 0 || this.options.enabled === false || this.target >= this.maxRows)
+      return;
     if (!this.store.getSnapshot().hasNextPage) return;
     this.target = Math.min(this.target + this.pageSize, this.maxRows);
     this.watch();
     this.pump();
   };
   retry = () => {
-    if (this.disposed || this.options.enabled === false) return;
+    if (this.disposed || this.activeRefs <= 0 || this.options.enabled === false) return;
     this.apiFailed = false;
     this.apiError = void 0;
     this.watch();
@@ -582,7 +707,7 @@ var InfiniteQueryStore = class {
     if (last) this.reset(last);
   };
   reset(anchor) {
-    if (this.disposed || this.options.enabled === false) return;
+    if (this.disposed || this.activeRefs <= 0 || this.options.enabled === false) return;
     this.generation += 1;
     this.cancelRequest();
     this.request = void 0;
@@ -1336,6 +1461,10 @@ var RacedListStore = class {
     this.compare = rowComparator(def.orderKey, def.direction ?? "asc");
     this.table = def.table ?? def.id;
     this.startedAt = deps.clock.now();
+    this.checkpointRefresh = new CoalescedRefresh(
+      (isCurrent) => this.onCompletion(isCurrent),
+      () => this.reconcile()
+    );
   }
   deps;
   def;
@@ -1345,6 +1474,9 @@ var RacedListStore = class {
   compare;
   table;
   abort = new AbortController();
+  observation = 0;
+  checkpointRefresh;
+  localFreshAt = Number.NEGATIVE_INFINITY;
   startedAt;
   snap = null;
   snapPending = false;
@@ -1363,17 +1495,21 @@ var RacedListStore = class {
   tombstones = /* @__PURE__ */ new Set();
   disposed = false;
   refs = 0;
+  activeRefs = 0;
   measured = false;
   localMs = null;
   apiMs = null;
-  retain() {
+  retain(active = true) {
     this.refs += 1;
-    if (this.refs === 1 && this.unsubDiffs === null) this.start();
+    if (active) this.activeRefs += 1;
+    if (this.activeRefs > 0 && this.unsubDiffs === null) this.start();
   }
-  release() {
+  release(active = true) {
     this.refs -= 1;
-    if (this.refs <= 0) queueMicrotask(() => {
+    if (active) this.activeRefs -= 1;
+    queueMicrotask(() => {
       if (this.refs <= 0) this.dispose();
+      else if (this.activeRefs <= 0) this.pause();
     });
   }
   get isDisposed() {
@@ -1386,10 +1522,7 @@ var RacedListStore = class {
   }
   dispose() {
     this.disposed = true;
-    this.abort.abort(new Error("disposed"));
-    this.unsubDiffs?.();
-    this.unsubCrud?.();
-    this.unsubFresh?.();
+    this.pause();
     if (this.snapWindow) this.deps.crud.closeWindow(this.snapWindow);
     this.snapWindow = null;
     this.local?.clear();
@@ -1401,39 +1534,71 @@ var RacedListStore = class {
     this.tombstones.clear();
     this.store.replace(emptyRacedResult());
   }
+  pause() {
+    this.observation += 1;
+    this.checkpointRefresh.cancel();
+    this.abort.abort(new Error("observer stopped"));
+    this.unsubDiffs?.();
+    this.unsubCrud?.();
+    this.unsubFresh?.();
+    this.unsubDiffs = null;
+    this.unsubCrud = null;
+    this.unsubFresh = null;
+    if (this.snapPending) {
+      this.deps.snapshots.invalidate(this.snapshotKey());
+      if (this.snapWindow) this.deps.crud.closeWindow(this.snapWindow);
+      this.snapWindow = this.snap?.window ?? null;
+      this.snapPending = false;
+    }
+  }
   // ---------------------------------------------------------------------------
   start() {
+    if (this.disposed) return;
+    this.abort = new AbortController();
+    const observation = ++this.observation;
     const { driver, adapter, crud, freshness } = this.deps;
     const prepared = adapter.prepare(this.def.query(this.scope));
     this.prepared = prepared;
     this.unsubDiffs = driver.diffs(prepared).subscribe(
-      (diff) => void this.onDiff(diff),
+      (diff) => {
+        if (observation === this.observation) void this.onDiff(diff);
+      },
       (err) => {
+        if (observation !== this.observation) return;
         this.localError = err;
         this.reconcile();
       }
     );
     this.unsubCrud = crud.onChange(() => this.reconcile());
-    this.unsubFresh = freshness.onCompletion(() => void this.onCompletion());
-    if (this.deps.apiLegEnabled) this.startApiLeg();
+    this.unsubFresh = freshness.onCompletion((completion) => {
+      if (completion.stream === null || this.def.stream && completion.stream === streamKey(this.def.stream)) {
+        if (!this.owned) this.checkpointRefresh.request();
+      }
+    });
+    if (this.deps.apiLegEnabled && !this.owned) this.startApiLeg();
     this.reconcile();
   }
   startApiLeg() {
+    const observation = this.observation;
+    const abort = this.abort;
     const { snapshots, crud } = this.deps;
     const staleTime = this.def.staleTime ?? 10 * 6e4;
     this.snapPending = true;
     const window = crud.openWindow();
     this.snapWindow = window;
-    const key = ["powersync-bridge", this.deps.identityKey, this.deps.epoch, this.def.id, this.scopeKey];
+    const key = this.snapshotKey();
     snapshots.fetch(key, staleTime, (signal) => {
       const combined = new AbortController();
       const onAbort = () => combined.abort();
       signal.addEventListener("abort", onAbort, { once: true });
-      this.abort.signal.addEventListener("abort", onAbort, { once: true });
-      return this.def.fetchSnapshot(this.scope, combined.signal);
+      abort.signal.addEventListener("abort", onAbort, { once: true });
+      return this.def.fetchSnapshot(this.scope, combined.signal).finally(() => {
+        signal.removeEventListener("abort", onAbort);
+        abort.signal.removeEventListener("abort", onAbort);
+      });
     }).then(
       (record) => {
-        if (this.disposed) return;
+        if (this.disposed || observation !== this.observation) return;
         this.snapPending = false;
         this.apiMs = this.deps.clock.now() - this.startedAt;
         const rows = /* @__PURE__ */ new Map();
@@ -1441,32 +1606,38 @@ var RacedListStore = class {
           const item = this.def.mapApi(raw);
           rows.set(idOf(item), item);
         }
+        if (this.snap) crud.closeWindow(this.snap.window);
         this.snap = { rows, record, window };
         this.reconcile();
       },
       (err) => {
-        if (this.disposed) return;
+        if (this.disposed || observation !== this.observation) return;
         this.snapPending = false;
         this.snapError = err instanceof Error ? err : new Error(String(err));
         crud.closeWindow(window);
-        this.snapWindow = null;
+        this.snapWindow = this.snap?.window ?? null;
         this.reconcile();
       }
     );
   }
+  snapshotKey() {
+    return ["powersync-bridge", this.deps.identityKey, this.deps.epoch, this.def.id, this.scopeKey];
+  }
   /**
    * A checkpoint completed. Status events and diff emissions are separate SDK events with no
    * ordering guarantee; taking ownership on the stale local map would render the pre-checkpoint
    * value for one frame (fresh→old→fresh). Pre-ownership we re-query once, then reconcile.
    */
-  async onCompletion() {
-    if (this.disposed || this.owned || !this.prepared || !this.emissionSeen) {
-      this.reconcile();
-      return;
-    }
+  async onCompletion(isCurrent) {
+    if (this.disposed || this.owned || !this.prepared || this.activeRefs <= 0) return;
+    const freshAt = this.deps.freshness.freshAtFor(this.def.stream);
     try {
-      const rows = await this.deps.driver.query(this.prepared, this.abort.signal);
-      if (this.disposed) return;
+      const prepared = this.prepared;
+      const signal = this.abort.signal;
+      const read = () => isCurrent() ? this.deps.driver.query(prepared, signal) : Promise.resolve(void 0);
+      const rows = await (this.deps.backgroundReads ? this.deps.backgroundReads.run(read, signal) : read());
+      if (!rows) return;
+      if (this.disposed || !isCurrent()) return;
       const prev = this.local ?? /* @__PURE__ */ new Map();
       const next = /* @__PURE__ */ new Map();
       for (const row of rows) {
@@ -1479,12 +1650,16 @@ var RacedListStore = class {
         }
       }
       this.local = next;
+      this.localFreshAt = Math.max(this.localFreshAt, freshAt);
+      this.emissionSeen = true;
+      this.localError = void 0;
     } catch {
     }
     this.reconcile();
   }
   async onDiff(diff) {
-    if (this.disposed) return;
+    if (this.disposed || this.activeRefs <= 0) return;
+    const observation = this.observation;
     const { crud } = this.deps;
     const prev = this.local;
     const next = /* @__PURE__ */ new Map();
@@ -1497,6 +1672,8 @@ var RacedListStore = class {
       }
     }
     this.local = next;
+    if (!this.checkpointRefresh.pending)
+      this.localFreshAt = this.deps.freshness.freshAtFor(this.def.stream);
     if (!this.emissionSeen) {
       this.emissionSeen = true;
       this.localMs = this.deps.clock.now() - this.startedAt;
@@ -1504,15 +1681,13 @@ var RacedListStore = class {
     void crud.resync();
     if (this.owned && prev) {
       const removed = /* @__PURE__ */ new Map();
-      for (const id of diff.removed) {
-        const row = prev.get(id);
-        if (row) removed.set(id, row);
-      }
-      if (removed.size > 0) await this.applyRemovals(removed);
+      for (const [id, row] of prev) if (!next.has(id)) removed.set(id, row);
+      if (removed.size > 0) await this.applyRemovals(removed, observation);
     }
+    if (observation !== this.observation) return;
     this.reconcile();
   }
-  async applyRemovals(removed) {
+  async applyRemovals(removed, observation) {
     const classes = await classifyRemovals(
       {
         driver: this.deps.driver,
@@ -1523,7 +1698,7 @@ var RacedListStore = class {
       },
       removed
     );
-    if (this.disposed) return;
+    if (this.disposed || observation !== this.observation) return;
     for (const [id, cls] of classes) {
       const entry = this.overlay.get(id);
       switch (cls) {
@@ -1546,18 +1721,24 @@ var RacedListStore = class {
     if (this.disposed) return;
     const result = this.owned ? this.renderOwned() : this.renderRace();
     const prev = this.store.getSnapshot();
-    if (shallowEqualResult(prev, result)) return;
+    if (shallowEqualResult(
+      prev,
+      result
+    ))
+      return;
     this.store.replace(result);
     this.report(result);
   }
   freshAt() {
-    return this.deps.freshness.freshAtFor(this.def.stream);
+    return this.localFreshAt;
   }
   localFresh() {
-    return this.emissionSeen && this.deps.freshness.isFresh(this.def.stream);
+    const connectedAt = this.deps.freshness.sessionConnectAtMs;
+    return this.emissionSeen && connectedAt !== null && this.localFreshAt >= connectedAt;
   }
   tryTakeOwnership() {
     if (this.owned) return true;
+    if (this.checkpointRefresh.pending) return false;
     const apiFreshAt = this.snap?.record.fetchedAt ?? Number.NEGATIVE_INFINITY;
     if (!(this.localFresh() && this.freshAt() > apiFreshAt)) return false;
     this.owned = true;
@@ -1567,7 +1748,8 @@ var RacedListStore = class {
     if (this.snap) {
       if (this.def.apiScopeSupersetOfLocal) {
         for (const [id, row] of this.snap.rows) {
-          if (!overlay.has(id) && !this.tombstones.has(id)) overlay.set(id, { row, origin: "api", presentLocally: false });
+          if (!overlay.has(id) && !this.tombstones.has(id))
+            overlay.set(id, { row, origin: "api", presentLocally: false });
         }
       }
       this.deps.crud.closeWindow(this.snap.window);
@@ -1614,11 +1796,14 @@ var RacedListStore = class {
       const inS = S?.rows.get(id);
       const pending = crud.pendingOp(this.table, id, S?.window);
       if (pending) {
-        if (inLocal !== void 0) entries.push({ row: inLocal, origin: "local", presentLocally: true });
+        if (inLocal !== void 0)
+          entries.push({ row: inLocal, origin: "local", presentLocally: true });
         continue;
       }
       if (inLocal !== void 0 && inS !== void 0) {
-        entries.push(apiFresher ? { row: inS, origin: "api", presentLocally: true } : { row: inLocal, origin: "local", presentLocally: true });
+        entries.push(
+          apiFresher ? { row: inS, origin: "api", presentLocally: true } : { row: inLocal, origin: "local", presentLocally: true }
+        );
         continue;
       }
       if (inLocal !== void 0) {
@@ -1642,7 +1827,9 @@ var RacedListStore = class {
   finalize(entries, stale = false) {
     entries.sort((a, b) => this.compare(a.row, b.row));
     const limited = entries.slice(0, this.def.limit);
-    return limited.map((e) => stale ? { row: e.row, origin: e.origin, presentLocally: e.presentLocally, stale: true } : { row: e.row, origin: e.origin, presentLocally: e.presentLocally });
+    return limited.map(
+      (e) => stale ? { row: e.row, origin: e.origin, presentLocally: e.presentLocally, stale: true } : { row: e.row, origin: e.origin, presentLocally: e.presentLocally }
+    );
   }
   build(items, state, awaiting) {
     const errors = {};
@@ -1709,7 +1896,11 @@ var SnapshotCache = class {
       const res = await fetcher(signal);
       return { rows: res.rows, asOf: res.asOf, requestedAt: now, fetchedAt: this.clock.now() };
     };
-    const promise = this.queryClient ? this.queryClient.fetchQuery({ queryKey: key, queryFn: ({ signal }) => run(signal), staleTime }) : run(controller.signal);
+    const promise = this.queryClient ? this.queryClient.fetchQuery({
+      queryKey: key,
+      queryFn: ({ signal }) => run(signal),
+      staleTime
+    }) : run(controller.signal);
     const entry = { requestedAt: now, promise, result: null, controller };
     this.entries.set(k, entry);
     promise.then(
@@ -1726,6 +1917,8 @@ var SnapshotCache = class {
   invalidate(key) {
     const encoded = JSON.stringify(key);
     this.entries.get(encoded)?.controller.abort(new Error("invalidated"));
+    void this.queryClient?.cancelQueries?.({ queryKey: key, exact: true }).catch(() => {
+    });
     this.entries.delete(encoded);
   }
   /** Cancel every in-flight fetch under a key prefix (identity swap). */
@@ -1764,6 +1957,7 @@ var Bridge = class {
   freshness;
   crud;
   snapshots;
+  backgroundReads = new BackgroundReads();
   epochSnapshot;
   stores = /* @__PURE__ */ new Map();
   gates;
@@ -1777,7 +1971,10 @@ var Bridge = class {
     this.adapter = opts.adapter;
     this.clock = opts.clock ?? realClock;
     this.platform = opts.platform ?? detectPlatform();
-    this.gates = { native: opts.platformGates?.native ?? "local-first", web: opts.platformGates?.web ?? "race" };
+    this.gates = {
+      native: opts.platformGates?.native ?? "local-first",
+      web: opts.platformGates?.web ?? "race"
+    };
     this.measure = opts.measure?.sink;
     this.identityOpts = opts.identity ?? {};
     this.onEvicted = opts.onEvicted;
@@ -1804,19 +2001,26 @@ var Bridge = class {
   }
   query(options) {
     const key = `query:${this.epoch}:${infiniteQueryKey(options)}`;
-    return this.acquire(key, () => new InfiniteQueryStore({
-      driver: this.driver,
-      adapter: this.adapter,
-      crud: this.crud,
-      freshness: this.freshness,
-      snapshots: this.snapshots,
-      clock: this.clock,
-      epoch: this.epoch,
-      identityKey: this.identityKey,
-      apiLegEnabled: true,
-      measure: this.measure,
-      connectivity: this.connectivity
-    }, options));
+    return this.acquire(
+      key,
+      () => new InfiniteQueryStore(
+        {
+          driver: this.driver,
+          adapter: this.adapter,
+          crud: this.crud,
+          freshness: this.freshness,
+          snapshots: this.snapshots,
+          clock: this.clock,
+          epoch: this.epoch,
+          identityKey: this.identityKey,
+          apiLegEnabled: true,
+          measure: this.measure,
+          connectivity: this.connectivity,
+          backgroundReads: this.backgroundReads
+        },
+        options
+      )
+    );
   }
   /** Resolves once the initial upload-queue read has landed (tests). */
   ready() {
@@ -1831,7 +2035,8 @@ var Bridge = class {
     Object.defineProperty(wrapped, "fetchCredentials", {
       value: async () => {
         const creds = await connector.fetchCredentials();
-        if (creds?.token) this.identity.observe(identityKeyFromToken(creds.token, this.identityOpts));
+        if (creds?.token)
+          this.identity.observe(identityKeyFromToken(creds.token, this.identityOpts));
         return creds;
       },
       configurable: true,
@@ -1893,7 +2098,8 @@ var Bridge = class {
           epoch: this.epoch,
           identityKey: this.identityKey,
           apiLegEnabled: this.apiLegEnabled(),
-          measure: this.measure
+          measure: this.measure,
+          backgroundReads: this.backgroundReads
         },
         def,
         scope,
@@ -1919,7 +2125,10 @@ var Bridge = class {
   }
   onDemand(name, params, opts = {}) {
     const key = `ondemand:${this.epoch}:${name}:${JSON.stringify(params)}`;
-    return this.acquire(key, () => new OnDemandStreamStore(this.driver, this.clock, name, params, opts));
+    return this.acquire(
+      key,
+      () => new OnDemandStreamStore(this.driver, this.clock, name, params, opts)
+    );
   }
   autoSync(config, ids) {
     const key = `flag:${this.epoch}:${config.stream}:${JSON.stringify([...ids].sort())}`;