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

package/dist/index.js

@@ -1,5 +1,5 @@
-import { rowComparator, idOf, cursorOfRow, streamKey, isAfterCursor, FreshnessTracker } from './chunk-TANEBEGU.js';
-export { cursorOfRow, decodeCursor, encodeCursor, keyColumns, rowComparator } from './chunk-TANEBEGU.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;
@@ -76,13 +159,14 @@ var SnapshotStore = class {
   constructor(initial) {
     this.snapshot = initial;
   }
-  getSnapshot() {
+  // React invokes external-store callbacks as standalone functions.
+  getSnapshot = () => {
     return this.snapshot;
-  }
-  subscribe(listener) {
+  };
+  subscribe = (listener) => {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
-  }
+  };
   replace(next) {
     if (Object.is(next, this.snapshot)) return;
     this.snapshot = next;
@@ -113,6 +197,538 @@ function shallowEqualResult(a, b) {
   return true;
 }
 
+// src/query.ts
+var infiniteQueryKey = (options) => JSON.stringify([
+  options.queryKey,
+  options.orderBy,
+  options.direction ?? "desc",
+  options.pageSize ?? 25,
+  options.maxRows ?? 500,
+  options.enabled !== false
+]);
+var OfflineError = class extends Error {
+  name = "OfflineError";
+  constructor() {
+    super("Additional records require a connection.");
+  }
+};
+var InfiniteQueryStore = class {
+  constructor(deps, options) {
+    this.deps = deps;
+    this.options = options;
+    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"
+      );
+    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;
+  store;
+  pageSize;
+  maxRows;
+  compare;
+  table;
+  target;
+  anchor;
+  revision = 0;
+  local = /* @__PURE__ */ new Map();
+  retained = /* @__PURE__ */ new Map();
+  tombstones = /* @__PURE__ */ new Set();
+  filtered = /* @__PURE__ */ new Set();
+  inSession = /* @__PURE__ */ new Set();
+  pages = [];
+  localPending = true;
+  localStamp = Number.NEGATIVE_INFINITY;
+  localError;
+  apiError;
+  apiPending = false;
+  apiFailed = false;
+  offline;
+  generation = 0;
+  watchGeneration = 0;
+  lastLocalWatch = 0;
+  refs = 0;
+  activeRefs = 0;
+  checkpointRefresh;
+  localAbort = new AbortController();
+  ready = false;
+  disposed = false;
+  unwatch;
+  stops = [];
+  request;
+  requestKey;
+  get isDisposed() {
+    return this.disposed || this.refs <= 0 && this.unwatch !== void 0;
+  }
+  retain(active = true) {
+    this.refs += 1;
+    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((completion) => {
+        if (completion.stream === null) this.checkpointRefresh.request();
+      }),
+      this.deps.driver.onStatusChanged(() => this.networkChanged()),
+      this.deps.connectivity.subscribe(() => this.networkChanged())
+    ];
+    this.watch();
+    void this.deps.crud.ready().then(() => {
+      this.ready = true;
+      this.pump();
+    }).catch((error) => {
+      if (this.disposed) return;
+      this.localPending = false;
+      this.localError = error instanceof Error ? error : new Error(String(error));
+      this.render();
+    });
+  }
+  release(active = true) {
+    this.refs -= 1;
+    if (active) this.activeRefs -= 1;
+    queueMicrotask(() => {
+      if (this.refs <= 0) this.dispose();
+      else if (this.activeRefs <= 0) this.pause();
+    });
+  }
+  swapRoot() {
+    this.disposed = true;
+    this.local.clear();
+    this.retained.clear();
+    this.clearPages();
+    this.render(true);
+  }
+  dispose() {
+    this.disposed = true;
+    this.pause();
+    this.clearPages();
+    this.local.clear();
+    this.retained.clear();
+    this.tombstones.clear();
+    this.filtered.clear();
+    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;
+  }
+  cancelRequest() {
+    this.request?.abort();
+    if (this.requestKey) this.deps.snapshots.invalidate(this.requestKey);
+    this.requestKey = void 0;
+  }
+  networkChanged() {
+    if (this.disposed) return;
+    const offline = this.readOffline();
+    const reconnect = this.offline && !offline;
+    this.offline = offline;
+    if (offline && this.request) {
+      this.cancelRequest();
+      this.generation += 1;
+      this.apiPending = false;
+      this.request = void 0;
+      this.watch();
+    }
+    if (reconnect) {
+      this.apiFailed = false;
+      this.apiError = void 0;
+      this.pump();
+    }
+    this.render();
+  }
+  identity(row) {
+    if (this.options.getRowIdentity) return this.options.getRowIdentity(row);
+    if (!this.table)
+      throw new Error(
+        "powersync-bridge: provide table or getRowIdentity when the adapter cannot infer the business table"
+      );
+    return { table: this.table, id: idOf(row) };
+  }
+  pending(row) {
+    const { table, id } = this.identity(row);
+    return Boolean(
+      this.deps.crud.pendingOp(table, id) || this.pages.some((page) => this.deps.crud.pendingOp(table, id, page.window))
+    );
+  }
+  localBuilder() {
+    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;
+    let prepared;
+    try {
+      prepared = this.deps.adapter.prepare(this.localBuilder());
+      if (!this.table && prepared.tables.length === 1) this.table = prepared.tables[0];
+      if (!this.table && !this.options.getRowIdentity)
+        throw new Error(
+          "powersync-bridge: provide table or getRowIdentity when the adapter cannot infer the business table"
+        );
+    } catch (error) {
+      this.localPending = false;
+      this.localError = error instanceof Error ? error : new Error(String(error));
+      this.render();
+      return;
+    }
+    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;
+          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;
+        this.localPending = false;
+        this.localError = error;
+        this.render();
+      }
+    );
+    this.render();
+  }
+  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 || !isCurrent())
+      return;
+    const previous = this.local;
+    const firstEmission = this.lastLocalWatch !== token;
+    this.lastLocalWatch = token;
+    const next = new Map(rows.map((row) => [idOf(row), row]));
+    const removed = /* @__PURE__ */ new Map();
+    for (const [id, row] of previous)
+      if (!next.has(id)) {
+        removed.set(id, row);
+        this.tombstones.add(id);
+      }
+    for (const [id, row] of next) {
+      if (previous.size && (!firstEmission || previous.has(id)) && JSON.stringify(previous.get(id)) !== JSON.stringify(row) && !this.pending(row))
+        this.inSession.add(id);
+      this.tombstones.delete(id);
+      this.filtered.delete(id);
+      this.retained.delete(id);
+    }
+    this.local = next;
+    this.localPending = false;
+    this.localError = void 0;
+    this.localStamp = stamp;
+    this.render();
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of removed.values()) {
+      const identity = this.identity(row);
+      const group = groups.get(identity.table) ?? /* @__PURE__ */ new Map();
+      group.set(identity.id, row);
+      groups.set(identity.table, group);
+    }
+    try {
+      for (const [table, group] of groups) {
+        const classes = await classifyRemovals(
+          {
+            driver: this.deps.driver,
+            clock: this.deps.clock,
+            table,
+            provenance: () => void 0,
+            isInWindow: this.options.isInWindow
+          },
+          group
+        );
+        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;
+          const classification = classes.get(identity.id);
+          if (!classification) continue;
+          if (classification === "delete") this.tombstones.add(row.id);
+          else if (classification === "filtered") {
+            this.tombstones.delete(row.id);
+            this.filtered.add(row.id);
+          } else {
+            this.tombstones.delete(row.id);
+            this.retained.set(row.id, row);
+          }
+        }
+      }
+    } catch (error) {
+      if (token !== this.watchGeneration || generation !== this.generation || this.disposed) return;
+      this.localError = error instanceof Error ? error : new Error(String(error));
+    }
+    const retained = [...this.retained.values()].sort(this.compare).slice(0, this.maxRows);
+    this.retained.clear();
+    for (const row of retained) this.retained.set(row.id, row);
+    const known = /* @__PURE__ */ new Set([
+      ...this.local.keys(),
+      ...this.retained.keys(),
+      ...this.pages.flatMap((page) => page.rows.map((row) => row.id))
+    ]);
+    for (const set of [this.inSession, this.tombstones, this.filtered]) {
+      if (set.size > this.maxRows * 4) {
+        for (const id of set) if (!known.has(id)) set.delete(id);
+      }
+    }
+    this.render();
+  }
+  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 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 || !isCurrent())
+        return;
+      this.localError = error instanceof Error ? error : new Error(String(error));
+      this.render();
+    }
+  }
+  clearPages() {
+    for (const page of this.pages) this.deps.crud.closeWindow(page.window);
+    this.pages = [];
+  }
+  apiEnd() {
+    return this.pages.at(-1)?.end === true;
+  }
+  apiCount() {
+    return this.pages.reduce((count, page) => count + page.rows.length, 0);
+  }
+  apiCursor() {
+    const last = this.pages.at(-1)?.rows.at(-1);
+    return last ? last : this.anchor;
+  }
+  cursorKey(row) {
+    if (!row) return void 0;
+    const [first, second] = keyColumns(this.options.orderBy);
+    return [row[first], row[second]];
+  }
+  pump() {
+    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;
+    if (this.apiCount() >= this.target && this.entries().length >= this.target) return;
+    const cursor = this.apiCursor();
+    const generation = this.generation;
+    const request = new AbortController();
+    this.request = request;
+    const window = this.deps.crud.openWindow();
+    this.apiPending = true;
+    this.render();
+    const key = [
+      "powersync-bridge.query",
+      this.deps.identityKey,
+      this.deps.epoch,
+      infiniteQueryKey(this.options),
+      this.cursorKey(this.anchor),
+      this.revision,
+      generation,
+      this.cursorKey(cursor)
+    ];
+    this.requestKey = key;
+    void this.deps.snapshots.fetch(key, this.options.staleTime ?? 6e4, async (signal) => {
+      const abort = () => request.abort();
+      signal.addEventListener("abort", abort, { once: true });
+      try {
+        return await withTimeout(
+          this.deps.clock,
+          this.options.fetchPage({ cursor, limit: this.pageSize + 1, signal: request.signal }).then((rows) => ({ rows })),
+          3e4,
+          request.signal
+        );
+      } finally {
+        signal.removeEventListener("abort", abort);
+      }
+    }).then((record) => {
+      if (this.disposed || generation !== this.generation || request.signal.aborted) {
+        this.deps.crud.closeWindow(window);
+        return;
+      }
+      const rows = [...record.rows];
+      for (let index = 1; index < rows.length; index++) {
+        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"
+          );
+      }
+      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");
+      this.pages.push({
+        cursor,
+        rows: rows.slice(0, this.pageSize),
+        end: rows.length <= this.pageSize,
+        fetchedAt: record.fetchedAt,
+        window
+      });
+      this.apiError = void 0;
+    }).catch((error) => {
+      this.deps.crud.closeWindow(window);
+      if (this.disposed || generation !== this.generation || request.signal.aborted) return;
+      this.apiFailed = true;
+      this.apiError = error instanceof Error ? error : new Error(String(error));
+      request.abort();
+    }).finally(() => {
+      if (generation !== this.generation || this.disposed) return;
+      this.apiPending = false;
+      this.request = void 0;
+      this.requestKey = void 0;
+      this.render();
+      this.pump();
+    });
+  }
+  entries() {
+    const api = /* @__PURE__ */ new Map();
+    for (const page of this.pages) for (const row of page.rows) api.set(row.id, { row, page });
+    const ids = /* @__PURE__ */ new Set([...this.local.keys(), ...this.retained.keys(), ...api.keys()]);
+    const entries = [];
+    for (const id of ids) {
+      if (this.tombstones.has(id) || this.filtered.has(id)) continue;
+      const local = this.local.get(id);
+      const remote = api.get(id);
+      const row = local ?? remote?.row ?? this.retained.get(id);
+      if (!row) continue;
+      if (this.pending(row)) {
+        if (local) entries.push({ row: local, origin: "local", presentLocally: true });
+        continue;
+      }
+      if (remote) {
+        entries.push(
+          local && this.localStamp > remote.page.fetchedAt ? { row: local, origin: "local", presentLocally: true } : { row: remote.row, origin: "api", presentLocally: Boolean(local) }
+        );
+      } else if (local) {
+        const covering = this.pages.find((page) => {
+          if (page.cursor !== void 0 && this.compare(local, page.cursor) <= 0) return false;
+          const last = page.rows.at(-1);
+          return page.end || Boolean(last && this.compare(local, last) <= 0);
+        });
+        if (!covering || this.inSession.has(id) || this.localStamp > covering.fetchedAt)
+          entries.push({ row: local, origin: "local", presentLocally: true });
+      } else entries.push({ row, origin: "local", presentLocally: false });
+    }
+    return entries.sort((a, b) => this.compare(a.row, b.row));
+  }
+  result(empty = false) {
+    const enabled = !empty && this.options.enabled !== false;
+    const entries = enabled ? this.entries() : [];
+    const items = entries.slice(0, this.target);
+    const more = entries.length > this.target || !this.apiEnd();
+    const missing = items.length < this.target;
+    const errors = {};
+    if (this.localError) errors.local = this.localError;
+    if (this.apiError) errors.api = this.apiError;
+    const offlineError = this.offline && missing && !this.localPending ? new OfflineError() : void 0;
+    const error = enabled && missing && !this.localPending && !this.apiPending ? this.localError ?? this.apiError ?? offlineError : void 0;
+    return {
+      data: items.map((item) => item.row),
+      items,
+      isLoading: enabled && items.length === 0 && !error && (this.localPending || this.apiPending),
+      isFetching: enabled && (this.localPending || this.apiPending),
+      isFetchingNextPage: enabled && this.target > this.pageSize && (this.localPending || this.apiPending),
+      hasNextPage: enabled && this.target < this.maxRows && more,
+      needsOlderWindow: enabled && items.length >= this.maxRows && more,
+      error,
+      errors,
+      isError: Boolean(error),
+      windowRevision: this.revision
+    };
+  }
+  render(empty = false) {
+    if (this.disposed && !empty) return;
+    const result = this.result(empty);
+    if (!shallowEqualResult(
+      this.store.getSnapshot(),
+      result
+    ))
+      this.store.replace(result);
+  }
+  fetchNextPage = () => {
+    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.activeRefs <= 0 || this.options.enabled === false) return;
+    this.apiFailed = false;
+    this.apiError = void 0;
+    this.watch();
+    this.pump();
+  };
+  refresh = () => {
+    this.reset(this.anchor);
+  };
+  continueOlder = () => {
+    const last = this.store.getSnapshot().data.at(-1);
+    if (last) this.reset(last);
+  };
+  reset(anchor) {
+    if (this.disposed || this.activeRefs <= 0 || this.options.enabled === false) return;
+    this.generation += 1;
+    this.cancelRequest();
+    this.request = void 0;
+    this.apiPending = false;
+    this.apiFailed = false;
+    this.apiError = void 0;
+    this.localError = void 0;
+    this.clearPages();
+    this.local.clear();
+    this.retained.clear();
+    this.inSession.clear();
+    this.tombstones.clear();
+    this.filtered.clear();
+    this.target = this.pageSize;
+    this.anchor = anchor;
+    this.revision += 1;
+    this.watch();
+    this.pump();
+  }
+};
+
 // src/flagger.ts
 var AutoSyncFlagStore = class {
   constructor(driver, clock, config, ids) {
@@ -309,6 +925,7 @@ var InfiniteListStore = class {
   reason;
   awaitingSync = false;
   loading = false;
+  localPagePending = false;
   errors = {};
   warnings = [];
   errorCount = 0;
@@ -317,14 +934,16 @@ var InfiniteListStore = class {
   refs = 0;
   retain() {
     this.refs += 1;
-    if (this.refs === 1) this.subscribeLocal();
+    if (this.refs === 1 && this.unsubDiffs === null) this.subscribeLocal();
   }
   release() {
     this.refs -= 1;
-    if (this.refs <= 0) this.dispose();
+    if (this.refs <= 0) queueMicrotask(() => {
+      if (this.refs <= 0) this.dispose();
+    });
   }
   get isDisposed() {
-    return this.disposed;
+    return this.disposed || this.refs <= 0 && this.unsubDiffs !== null;
   }
   swapRoot() {
     this.store.replace(emptyInfiniteResult());
@@ -338,6 +957,11 @@ var InfiniteListStore = class {
     for (const h of this.subs.values()) h.unsubscribe();
     this.subs.clear();
     this.lru.length = 0;
+    this.local.clear();
+    this.apiRows.clear();
+    this.retained.clear();
+    this.tombstones.clear();
+    this.store.replace(emptyInfiniteResult());
   }
   // ---------------------------------------------------------------------------
   subscribeLocal() {
@@ -349,6 +973,10 @@ var InfiniteListStore = class {
       (diff) => void this.onDiff(diff),
       (err) => {
         this.localError = err;
+        if (this.localPagePending) {
+          this.localPagePending = false;
+          this.loading = false;
+        }
         this.render();
       }
     );
@@ -368,6 +996,11 @@ var InfiniteListStore = class {
       this.apiRows.delete(id);
     }
     this.local = next;
+    this.localError = void 0;
+    if (this.localPagePending) {
+      this.localPagePending = false;
+      this.loading = false;
+    }
     this.emissionSeen = true;
     const removed = /* @__PURE__ */ new Map();
     for (const [id, row] of prev) if (!next.has(id)) removed.set(id, row);
@@ -422,6 +1055,8 @@ var InfiniteListStore = class {
   async loadMore() {
     if (this.disposed || this.loading || this.boundary === "end") return;
     if (this.lookahead) {
+      this.localPagePending = true;
+      this.loading = true;
       this.pages += 1;
       this.boundary = "more";
       this.reason = void 0;
@@ -576,6 +1211,8 @@ var InfiniteListStore = class {
     }
   }
   absorbApi(rows) {
+    const { api: _previousApiError, ...remainingErrors } = this.errors;
+    this.errors = remainingErrors;
     this.errorCount = 0;
     this.nextRetryAt = 0;
     for (const row of rows) {
@@ -583,6 +1220,11 @@ var InfiniteListStore = class {
       if (this.local.has(id) || this.apiRows.has(id) || this.tombstones.has(id)) continue;
       this.apiRows.set(id, row);
     }
+    const loadedPages = Math.max(this.pages, Math.ceil(this.mergedEntries().length / this.def.pageSize));
+    if (loadedPages > this.pages) {
+      this.pages = loadedPages;
+      this.subscribeLocal();
+    }
     if (rows.length === 0) {
       this.boundary = "end";
       this.reason = void 0;
@@ -750,7 +1392,7 @@ var CrudMirror = class {
     for (const r of refs) next.set(refKey(r.table, r.id), r);
     const added = [];
     const completed = [];
-    for (const [k, r] of next) if (!this.live.has(k)) added.push(r);
+    for (const [k, r] of next) if (this.live.get(k)?.op !== r.op) added.push(r);
     for (const [k, r] of this.live) if (!next.has(k)) completed.push(r);
     if (added.length || completed.length) this.apply({ added, completed });
   }
@@ -819,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;
@@ -828,6 +1474,9 @@ var RacedListStore = class {
   compare;
   table;
   abort = new AbortController();
+  observation = 0;
+  checkpointRefresh;
+  localFreshAt = Number.NEGATIVE_INFINITY;
   startedAt;
   snap = null;
   snapPending = false;
@@ -846,19 +1495,25 @@ 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.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) this.dispose();
+    if (active) this.activeRefs -= 1;
+    queueMicrotask(() => {
+      if (this.refs <= 0) this.dispose();
+      else if (this.activeRefs <= 0) this.pause();
+    });
   }
   get isDisposed() {
-    return this.disposed;
+    return this.disposed || this.refs <= 0 && this.unsubDiffs !== null;
   }
   /** Synchronous part of an identity swap: the snapshot becomes empty 'pending' at once (R15). */
   swapRoot() {
@@ -867,46 +1522,83 @@ var RacedListStore = class {
   }
   dispose() {
     this.disposed = true;
-    this.abort.abort(new Error("disposed"));
+    this.pause();
+    if (this.snapWindow) this.deps.crud.closeWindow(this.snapWindow);
+    this.snapWindow = null;
+    this.local?.clear();
+    this.local = null;
+    this.snap = null;
+    this.prepared = null;
+    this.overlay.clear();
+    this.inSession.clear();
+    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?.();
-    if (this.snapWindow) this.deps.crud.closeWindow(this.snapWindow);
-    this.snapWindow = null;
+    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();
@@ -914,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) {
@@ -952,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();
@@ -970,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;
@@ -977,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,
@@ -996,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) {
@@ -1019,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;
@@ -1040,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);
@@ -1087,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) {
@@ -1115,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 = {};
@@ -1166,12 +1880,27 @@ var SnapshotCache = class {
     if (existing && (existing.result === null || now - existing.result.fetchedAt < staleTime)) {
       return existing.promise;
     }
+    for (const [entryKey, entry2] of this.entries) {
+      if (entry2.result && now - entry2.result.fetchedAt >= staleTime) this.entries.delete(entryKey);
+    }
+    if (this.entries.size >= 64) {
+      for (const [entryKey, entry2] of this.entries) {
+        if (entry2.result) {
+          this.entries.delete(entryKey);
+          break;
+        }
+      }
+    }
     const controller = new AbortController();
     const run = async (signal) => {
       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(
@@ -1185,6 +1914,14 @@ var SnapshotCache = class {
     return promise;
   }
   /** Cancel every in-flight fetch under a key prefix (identity swap). */
+  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). */
   abortAll(prefix) {
     const p = JSON.stringify(prefix).slice(0, -1);
     for (const [k, e] of this.entries) {
@@ -1215,10 +1952,12 @@ var Bridge = class {
   clock;
   /** Increments on every identity swap; hooks subscribe to re-acquire their stores. */
   epochStore;
+  connectivity = new SnapshotStore(void 0);
   identity = new IdentityTracker();
   freshness;
   crud;
   snapshots;
+  backgroundReads = new BackgroundReads();
   epochSnapshot;
   stores = /* @__PURE__ */ new Map();
   gates;
@@ -1226,12 +1965,16 @@ var Bridge = class {
   identityOpts;
   onEvicted;
   disposed = false;
+  onNetwork = () => this.setOnline(globalThis.navigator?.onLine);
   constructor(opts) {
     this.driver = opts.driver;
     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;
@@ -1244,6 +1987,8 @@ var Bridge = class {
     this.crud.start();
     this.freshness.onClear(() => this.identity.signalClear());
     this.identity.onChange(() => this.swapEpoch());
+    globalThis.addEventListener?.("online", this.onNetwork);
+    globalThis.addEventListener?.("offline", this.onNetwork);
   }
   get epoch() {
     return this.identity.epoch;
@@ -1251,6 +1996,32 @@ var Bridge = class {
   get identityKey() {
     return this.identity.currentKey;
   }
+  setOnline(online) {
+    this.connectivity.replace(online);
+  }
+  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,
+          backgroundReads: this.backgroundReads
+        },
+        options
+      )
+    );
+  }
   /** Resolves once the initial upload-queue read has landed (tests). */
   ready() {
     return this.crud.ready();
@@ -1264,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,
@@ -1326,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,
@@ -1352,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())}`;
@@ -1361,6 +2137,8 @@ var Bridge = class {
   dispose() {
     if (this.disposed) return;
     this.disposed = true;
+    globalThis.removeEventListener?.("online", this.onNetwork);
+    globalThis.removeEventListener?.("offline", this.onNetwork);
     for (const s of this.stores.values()) s.dispose();
     this.stores.clear();
     this.snapshots.clear();
@@ -1380,6 +2158,6 @@ function defineInfiniteList(input) {
   return { kind: "infinite", ...input };
 }
 
-export { AutoSyncFlagStore, Bridge, DEFAULT_VOLATILE_CLAIMS, InfiniteListStore, OnDemandStreamStore, RacedListStore, SnapshotStore, classifyRemovals, createBridge, decodeJwtPayload, defineInfiniteList, defineRacedList, emptyInfiniteResult, emptyRacedResult, identityKeyFromClaims, identityKeyFromToken, probePresence, realClock };
+export { AutoSyncFlagStore, Bridge, DEFAULT_VOLATILE_CLAIMS, InfiniteListStore, InfiniteQueryStore, OfflineError, OnDemandStreamStore, RacedListStore, SnapshotStore, classifyRemovals, createBridge, decodeJwtPayload, defineInfiniteList, defineRacedList, emptyInfiniteResult, emptyRacedResult, identityKeyFromClaims, identityKeyFromToken, infiniteQueryKey, probePresence, realClock };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map