pbtsdb 2.0.0 → 2.0.1

package/README.md

@@ -21,6 +21,7 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
   - [Related data](#related-data)
   - [React Integration](#react-integration)
   - [Subscriptions](#subscriptions)
+  - [Sync Status API](#sync-status-api)
   - [Utility Functions](#utility-functions)
 - [Usage Examples](#usage-examples)
   - [Includes (Nested Subqueries)](#includes-nested-subqueries)
@@ -293,6 +294,49 @@ resetRealtime(pb); // open it again; every ready collection reloads
 
 `disconnectRealtime(pb)` closes the connection and keeps it closed until `resetRealtime(pb)`. Collections keep working over REST and keep their subscriptions registered. Use it at logout, or at startup where realtime is not wanted, such as an embedded view.
 
+### Sync Status
+
+Two problems are visible only to pbtsdb: the realtime stream dropping while REST still works, so lists look fine but stop updating; and a query sleeping in its load retry backoff, so a list sits in "loading" with no reason shown. `getSyncStatus(pb)` reports both, for every collection of one client:
+
+```typescript
+import { getSyncStatus, subscribeSyncStatus } from 'pbtsdb';
+
+const status = getSyncStatus(pb);
+// {
+//     realtime:
+//         | { state: 'disabled' }    // disconnectRealtime(pb), or no collection has subscribed yet
+//         | { state: 'connecting' }  // the first connection of a session is opening
+//         | { state: 'connected' }   // stream open, PB_CONNECT received
+//         | { state: 'reconnecting'; attempt: number; nextRetryAt: number; since: number },
+//     loads: {
+//         retrying: number,       // live queries sleeping in loadRetryDelays backoff
+//         failingSince?: number,  // when the oldest of them first failed, epoch ms
+//         failed: number,         // live queries whose load ended in a 4xx that is not retried
+//     },
+// }
+
+const stop = subscribeSyncStatus(pb, status => console.log(status));
+```
+
+`reconnecting` means the stream was up and dropped, or a retry never came up, and the next retry is scheduled; the first connection of a session reports `connecting` instead. `nextRetryAt` and `since` are epoch milliseconds, and `nextRetryAt` changes only when a new retry is scheduled. `disabled` is not a problem state: it is what `disconnectRealtime(pb)` asks for, and what an app sees before login.
+
+`retrying` counts only demands a live query still holds; a parked subset or an unmounted query is never counted. `failed` is separate because a 403 or 404 is an answer, not an outage; the count drops when the query reloads or unmounts.
+
+The snapshot is stable: `getSyncStatus(pb)` returns the same object, with the same nested objects, until a value changes. The React entry point wraps it in `useSyncStatus(pb)`:
+
+```tsx
+import { useSyncStatus } from 'pbtsdb';
+
+function SyncNotice() {
+    const { realtime, loads } = useSyncStatus(pb);
+    if (realtime.state === 'reconnecting') return <p>Live updates paused, reconnecting…</p>;
+    if (loads.retrying > 0) return <p>Retrying {loads.retrying} queries…</p>;
+    return null;
+}
+```
+
+The shape of `SyncStatus` is public and changes only in a major release.
+
 ### Subset Lifetime
 
 In on-demand mode a live query's subset is released when the last subscriber unmounts, after a grace window of `subsetGcTime` milliseconds (default 5000). A query with an equal request that mounts within the window reuses the rows with no request. Realtime keeps the parked rows fresh, and rows a parent filed through a relation stay for the same window, so a panel that mounts and unmounts quickly costs no refetch. `collection.reload()` releases every parked subset. An auth change releases every waiting subset and every accepted row at once and reloads every live subset under the new auth, whether or not realtime is connected, so a load right after a logout never reuses the previous user's rows and the order of `authStore.clear()` and `disconnectRealtime(pb)` does not matter. Set `subsetGcTime: 0` to release a subset as soon as it unloads; `0` also keeps accepted rows until a reload or idle instead of expiring them.
@@ -751,6 +795,32 @@ An `expand` you add here is yours: pbtsdb strips only the paths it requested
 through `alwaysFetchRelations` and `fetchRelations()`, so records expanded by
 this option stay on the echoed rows, untyped.
 
+### Sync Status API
+
+#### getSyncStatus()
+
+```typescript
+getSyncStatus(pb: PocketBase): SyncStatus
+```
+
+The current [sync status](#sync-status) of `pb`'s collections. The returned object is stable until a value changes.
+
+#### subscribeSyncStatus()
+
+```typescript
+subscribeSyncStatus(pb: PocketBase, listener: (status: SyncStatus) => void): () => void
+```
+
+Calls `listener` with each new snapshot. Returns the unsubscribe function.
+
+#### useSyncStatus()
+
+```typescript
+useSyncStatus(pb: PocketBase): SyncStatus
+```
+
+React hook over the two functions above, built on `useSyncExternalStore`. Exported from `pbtsdb`, not from `pbtsdb/core`.
+
 ### Utility Functions
 
 #### newRecordId()

package/dist/{chunk-4CRCARB3.js → chunk-TTENGDS3.js}

@@ -1530,7 +1530,9 @@ function createSyncAdapter(deps) {
       loading: void 0,
       parked: void 0,
       landed: false,
-      wake: void 0
+      wake: void 0,
+      retryingSince: void 0,
+      failed: false
     };
     if (mode !== "query") return { ...base, filters: void 0, counted: false };
     const filters = realtimeFiltersFor(toRequest({ where: realtimeWhereFor(opts) }));
@@ -1652,11 +1654,36 @@ function createSyncAdapter(deps) {
     run.eagerWake?.();
     for (const demand of run.demands.values()) demand.wake?.();
   }
+  const { onLoadStatusChange } = deps;
+  function loadStatus() {
+    const status = { retrying: 0, failed: 0 };
+    const run = current;
+    if (!run) return status;
+    const count = (retryingSince, failed) => {
+      if (failed) status.failed += 1;
+      if (retryingSince === void 0) return;
+      status.retrying += 1;
+      if (status.failingSince === void 0 || retryingSince < status.failingSince) {
+        status.failingSince = retryingSince;
+      }
+    };
+    for (const demand of run.demands.values()) {
+      if (demand.parked === void 0) count(demand.retryingSince, demand.failed);
+    }
+    count(run.eagerRetryingSince, run.eagerFailed);
+    return status;
+  }
   async function retryAllowed(run, opts, demand, seq, attempt, error) {
     if (superseded(run, opts, demand, seq)) return false;
-    if (loadRetryDelays.length === 0 || !isRetryable(error)) throw error;
+    if (loadRetryDelays.length === 0 || !isRetryable(error)) {
+      demand.failed = true;
+      onLoadStatusChange();
+      throw error;
+    }
     const delay = retryDelay(attempt, error);
     logger.warn("Subset load failed; retrying", { collectionName, attempt, delay, error });
+    demand.retryingSince ?? (demand.retryingSince = Date.now());
+    onLoadStatusChange();
     await sleep(delay, (wake) => {
       demand.wake = wake;
     });
@@ -1664,17 +1691,35 @@ function createSyncAdapter(deps) {
     return !superseded(run, opts, demand, seq);
   }
   async function fetchWithRetry(run, opts, demand, seq, refetch) {
-    for (let attempt = 0; ; attempt++) {
-      try {
-        return await fetchRows(run, demand.request, opts.signal, refetch, demand.filters);
-      } catch (error) {
-        if (!await retryAllowed(run, opts, demand, seq, attempt, error)) return void 0;
+    try {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          return await fetchRows(
+            run,
+            demand.request,
+            opts.signal,
+            refetch,
+            demand.filters
+          );
+        } catch (error) {
+          if (!await retryAllowed(run, opts, demand, seq, attempt, error)) {
+            return void 0;
+          }
+        }
+      }
+    } finally {
+      if (demand.seq === seq) {
+        demand.retryingSince = void 0;
+        onLoadStatusChange();
       }
     }
   }
   function load(run, opts, demand, wait, refetch) {
     demand.wake?.();
     const seq = ++demand.seq;
+    demand.failed = false;
+    demand.retryingSince = void 0;
+    onLoadStatusChange();
     const before = uncoveredRows(demand);
     const loading = (async () => {
       const result = await fetchWithRetry(run, opts, demand, seq, refetch);
@@ -1697,6 +1742,7 @@ function createSyncAdapter(deps) {
     run.demands.delete(opts);
     if (demand.counted) realtime.releaseQueryFilters(demand.filters);
     membership2.drop([opts]);
+    onLoadStatusChange();
   }
   function unloadSubset(run, opts) {
     try {
@@ -1709,6 +1755,7 @@ function createSyncAdapter(deps) {
       demand.parked = setTimeout(() => {
         if (current === run) expire(run, opts);
       }, subsetGcTime);
+      onLoadStatusChange();
     } catch (error) {
       logger.error("unloadSubset failed", { collectionName, error });
     }
@@ -1724,6 +1771,7 @@ function createSyncAdapter(deps) {
       if (parked.parked === void 0 || keyOf(parked) !== key) continue;
       clearTimeout(parked.parked);
       run.demands.delete(opts);
+      onLoadStatusChange();
       return opts;
     }
     return void 0;
@@ -1782,31 +1830,46 @@ function createSyncAdapter(deps) {
       return load(run, opts, demand, "visible", opts.refetch === true).then(() => void 0);
     };
   }
+  async function eagerRetryAllowed(run, seq, attempt, error) {
+    const stale = () => run.abort.signal.aborted || run.eagerSeq !== seq;
+    if (stale()) throw error;
+    if (loadRetryDelays.length === 0 || !isRetryable(error)) {
+      run.eagerFailed = true;
+      onLoadStatusChange();
+      throw error;
+    }
+    const delay = retryDelay(attempt, error);
+    logger.warn("Eager load failed; retrying", { collectionName, attempt, delay, error });
+    run.eagerRetryingSince ?? (run.eagerRetryingSince = Date.now());
+    onLoadStatusChange();
+    await sleep(delay, (wake) => {
+      run.eagerWake = wake;
+    });
+    run.eagerWake = void 0;
+    if (stale()) throw error;
+  }
   async function fetchEagerWithRetry(run, seq) {
-    for (let attempt = 0; ; attempt++) {
-      try {
-        return await fetchRows(run, {}, void 0, false, void 0);
-      } catch (error) {
-        const stale = () => run.abort.signal.aborted || run.eagerSeq !== seq;
-        if (loadRetryDelays.length === 0 || !isRetryable(error) || stale()) throw error;
-        const delay = retryDelay(attempt, error);
-        logger.warn("Eager load failed; retrying", {
-          collectionName,
-          attempt,
-          delay,
-          error
-        });
-        await sleep(delay, (wake) => {
-          run.eagerWake = wake;
-        });
-        run.eagerWake = void 0;
-        if (stale()) throw error;
+    try {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          return await fetchRows(run, {}, void 0, false, void 0);
+        } catch (error) {
+          await eagerRetryAllowed(run, seq, attempt, error);
+        }
+      }
+    } finally {
+      if (run.eagerSeq === seq) {
+        run.eagerRetryingSince = void 0;
+        onLoadStatusChange();
       }
     }
   }
   function loadEagerRows(run) {
     run.eagerWake?.();
     const seq = ++run.eagerSeq;
+    run.eagerFailed = false;
+    run.eagerRetryingSince = void 0;
+    onLoadStatusChange();
     const loading = (async () => {
       const { rows, filings } = await fetchEagerWithRetry(run, seq);
       if (run.abort.signal.aborted || run.eagerSeq !== seq) {
@@ -1894,7 +1957,9 @@ function createSyncAdapter(deps) {
         demands: /* @__PURE__ */ new Map(),
         eagerSeq: 0,
         eagerLoad: void 0,
-        eagerWake: void 0
+        eagerWake: void 0,
+        eagerRetryingSince: void 0,
+        eagerFailed: false
       };
       current = run;
       store.attach(channel);
@@ -1912,6 +1977,7 @@ function createSyncAdapter(deps) {
         subsets.clear();
         if (syncMode === "on-demand") realtime.resetQueryFilters();
         deps.onCleanup();
+        onLoadStatusChange();
       };
       if (syncMode === "eager") {
         void startEager(run, params.markReady, params.markError);
@@ -1944,7 +2010,8 @@ function createSyncAdapter(deps) {
       return [...current.demands].filter(
         ([opts, demand]) => demand.parked === void 0 && demand.landed && matcherFor(opts.where, true)(row)
       ).map(([opts]) => opts);
-    }
+    },
+    loadStatus
   };
 }
 
@@ -2012,12 +2079,25 @@ function createRealtimeClient(deps) {
   let resubmit = false;
   let attempts = 0;
   let reconnectTimer;
+  let lostAt;
+  let nextRetryAt = 0;
   let everConnected = false;
   let session = 0;
   let disabled = false;
   function topics() {
     return [...listeners.keys()];
   }
+  function status() {
+    if (disabled || !source && reconnectTimer === void 0) return { state: "disabled" };
+    if (connected) return { state: "connected" };
+    if (lostAt !== void 0) {
+      return { state: "reconnecting", attempt: attempts, nextRetryAt, since: lostAt };
+    }
+    return { state: "connecting" };
+  }
+  function statusChanged() {
+    deps.onStatusChange?.();
+  }
   function dispatcherFor(topic) {
     let dispatch = dispatchers.get(topic);
     if (!dispatch) {
@@ -2048,6 +2128,7 @@ function createRealtimeClient(deps) {
       close(true);
       clientId = void 0;
       lastSeq = void 0;
+      statusChanged();
       return;
     }
     if (sameList(list, confirmed)) return;
@@ -2071,6 +2152,7 @@ function createRealtimeClient(deps) {
     close(true);
     clientId = void 0;
     lastSeq = void 0;
+    statusChanged();
     settleWaiters(pending);
   }
   async function postTopics(pending, startedSession) {
@@ -2140,6 +2222,7 @@ function createRealtimeClient(deps) {
     if (forget) {
       confirmed = [];
       everConnected = false;
+      lostAt = void 0;
       session += 1;
     }
   }
@@ -2153,6 +2236,7 @@ function createRealtimeClient(deps) {
     clientId = void 0;
     lastSeq = void 0;
     attempts = 0;
+    lostAt = void 0;
     session += 1;
     if (listeners.size > 0) {
       try {
@@ -2161,10 +2245,13 @@ function createRealtimeClient(deps) {
         logger.error("Failed to reconnect after reset", { error });
       }
     }
+    statusChanged();
   }
   function scheduleReconnect() {
     const delay = backoff[Math.min(attempts, backoff.length - 1)] ?? 0;
     attempts += 1;
+    lostAt ?? (lostAt = Date.now());
+    nextRetryAt = Date.now() + delay;
     reconnectTimer = setTimeout(() => {
       reconnectTimer = void 0;
       if (listeners.size > 0) connect();
@@ -2175,12 +2262,14 @@ function createRealtimeClient(deps) {
     logger.debug("Realtime connection lost", { clientId });
     close(false);
     scheduleReconnect();
+    statusChanged();
   }
   function connect() {
     if (source || disabled) return;
     const previousId = clientId;
     const target = openSource(connectUrl());
     source = target;
+    statusChanged();
     target.addEventListener("error", () => handleConnectionLost(target));
     target.addEventListener("PB_CONNECT", (ev) => {
       if (source !== target) return;
@@ -2203,16 +2292,20 @@ function createRealtimeClient(deps) {
       attachAll(target);
       const isReconnect = everConnected;
       everConnected = true;
+      statusChanged();
       submit().then(
         () => {
           if (source !== target) return;
           attempts = 0;
+          lostAt = void 0;
+          statusChanged();
           if (isReconnect) deps.onReconnect?.(resumed);
         },
         () => {
           if (source !== target || !isReconnect) return;
           close(false);
           scheduleReconnect();
+          statusChanged();
         }
       );
     });
@@ -2268,6 +2361,7 @@ function createRealtimeClient(deps) {
     },
     topics,
     isConnected: () => connected,
+    status,
     clientId: () => clientId,
     disconnect() {
       close(true);
@@ -2277,6 +2371,7 @@ function createRealtimeClient(deps) {
       waiters = [];
       listeners.clear();
       dispatchers.clear();
+      statusChanged();
       settleWaiters(pending, new RealtimeDisconnectedError());
     },
     simulateDisconnect() {
@@ -2297,11 +2392,77 @@ function createRealtimeClient(deps) {
       if (!disabled) return;
       disabled = false;
       if (listeners.size > 0) connect();
+      statusChanged();
     },
     isEnabled: () => !disabled
   };
 }
 
+// src/sync-status.ts
+function sameRealtime(a, b) {
+  if (a.state !== b.state) return false;
+  if (a.state !== "reconnecting" || b.state !== "reconnecting") return true;
+  return a.attempt === b.attempt && a.nextRetryAt === b.nextRetryAt && a.since === b.since;
+}
+function sameLoads(a, b) {
+  return a.retrying === b.retrying && a.failed === b.failed && a.failingSince === b.failingSince;
+}
+function mergeLoads(sources) {
+  const merged = { retrying: 0, failed: 0 };
+  for (const loads of sources) {
+    merged.retrying += loads.retrying;
+    merged.failed += loads.failed;
+    if (loads.failingSince === void 0) continue;
+    if (merged.failingSince === void 0 || loads.failingSince < merged.failingSince) {
+      merged.failingSince = loads.failingSince;
+    }
+  }
+  return merged;
+}
+function createSyncStatusStore(deps) {
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = { realtime: deps.realtime(), loads: mergeLoads(deps.loads()) };
+  function next() {
+    const realtime = deps.realtime();
+    const loads = mergeLoads(deps.loads());
+    const realtimeChanged = !sameRealtime(snapshot.realtime, realtime);
+    const loadsChanged = !sameLoads(snapshot.loads, loads);
+    if (!realtimeChanged && !loadsChanged) return void 0;
+    return {
+      realtime: realtimeChanged ? realtime : snapshot.realtime,
+      loads: loadsChanged ? loads : snapshot.loads
+    };
+  }
+  let notified = snapshot;
+  let scheduled = false;
+  function get() {
+    const changed = next();
+    if (changed) snapshot = changed;
+    return snapshot;
+  }
+  function notify() {
+    scheduled = false;
+    const current = get();
+    if (current === notified) return;
+    notified = current;
+    for (const listener of listeners) listener(current);
+  }
+  return {
+    get,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    refresh() {
+      if (scheduled) return;
+      scheduled = true;
+      queueMicrotask(notify);
+    }
+  };
+}
+
 // src/transport.ts
 var entries = /* @__PURE__ */ new WeakMap();
 function watchAuth(pb, entry) {
@@ -2317,14 +2478,23 @@ function entryFor(pb) {
   let entry = entries.get(pb);
   if (!entry) {
     const reconnectListeners = /* @__PURE__ */ new Set();
+    const loadSources = /* @__PURE__ */ new Set();
+    let status;
     const client = createRealtimeClient({
-      url: pb.buildURL("/api/realtime"),
+      get url() {
+        return pb.buildURL("/api/realtime");
+      },
       send: (body) => pb.send("/api/realtime", { method: "POST", body, requestKey: null }),
       onReconnect: (resumed) => {
         for (const listener of reconnectListeners) listener(resumed);
-      }
+      },
+      onStatusChange: () => status?.refresh()
     });
-    entry = { client, reconnectListeners, authListeners: /* @__PURE__ */ new Set() };
+    status = createSyncStatusStore({
+      realtime: client.status,
+      loads: () => [...loadSources].map((source) => source())
+    });
+    entry = { client, reconnectListeners, authListeners: /* @__PURE__ */ new Set(), status, loadSources };
     watchAuth(pb, entry);
     entries.set(pb, entry);
   }
@@ -2339,6 +2509,12 @@ function resetRealtime(pb) {
 function disconnectRealtime(pb) {
   entryFor(pb).client.disable();
 }
+function getSyncStatus(pb) {
+  return entryFor(pb).status.get();
+}
+function subscribeSyncStatus(pb, listener) {
+  return entryFor(pb).status.subscribe(listener);
+}
 function transportFor(pb) {
   const entry = entryFor(pb);
   return {
@@ -2358,7 +2534,16 @@ function transportFor(pb) {
         entry.authListeners.delete(listener);
       };
     },
-    reconnectListenerCount: () => entry.reconnectListeners.size
+    reconnectListenerCount: () => entry.reconnectListeners.size,
+    addLoadSource(source) {
+      entry.loadSources.add(source);
+      return () => {
+        entry.loadSources.delete(source);
+        entry.status.refresh();
+      };
+    },
+    loadStatusChanged: entry.status.refresh,
+    loadSourceCount: () => entry.loadSources.size
   };
 }
 
@@ -2571,7 +2756,8 @@ function buildCollection(input) {
       held.clearFiled();
       for (const timer of acceptedTimers) clearTimeout(timer);
       acceptedTimers.clear();
-    }
+    },
+    onLoadStatusChange: transport.loadStatusChanged
   });
   function resolveHandler(option, fallback) {
     return option === false ? void 0 : option ?? fallback;
@@ -2675,6 +2861,7 @@ function buildCollection(input) {
   collection.on("status:change", (event) => {
     if (event.status === "cleaned-up") subsets.clear();
     if (!removeTransportListeners && (event.status === "loading" || event.status === "ready")) {
+      const removeLoadSource = transport.addLoadSource(adapter.loadStatus);
       const removeReconnect = transport.onReconnect((resumed) => {
         if (resumed || !realtime.isOpen()) return;
         if (!collection.isReady()) {
@@ -2691,6 +2878,7 @@ function buildCollection(input) {
         if (store.isAttached()) reloadFor("auth change");
       });
       removeTransportListeners = () => {
+        removeLoadSource();
         removeReconnect();
         removeAuth();
       };
@@ -2949,6 +3137,6 @@ function newRecordId() {
   return result;
 }
 
-export { convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, disconnectRealtime, newRecordId, resetLogger, resetRealtime, setLogger };
-//# sourceMappingURL=chunk-4CRCARB3.js.map
-//# sourceMappingURL=chunk-4CRCARB3.js.map
+export { convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, disconnectRealtime, getSyncStatus, newRecordId, resetLogger, resetRealtime, setLogger, subscribeSyncStatus };
+//# sourceMappingURL=chunk-TTENGDS3.js.map
+//# sourceMappingURL=chunk-TTENGDS3.js.map