@bunbase-ae/react-sdk 1.0.0 → 1.0.1-next.3.ee6c18d

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@bunbase-ae/react-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1-next.3.ee6c18d",
   "type": "module",
   "description": "React hooks for BunBase — caching, mutations, auth, realtime",
+  "homepage": "https://docs-bunbase.palmcode.ae/sdk/react",
   "files": [
     "src"
   ],

package/src/cache.ts

@@ -24,6 +24,18 @@ export interface CacheEntry {
   /** Stored so focus-triggered refetch can re-run without external reference. */
   fetcher: (() => Promise<unknown>) | null;
   staleTime: number;
+  retryableError: boolean;
+  /** Number of consecutive fetch failures — used to compute exponential backoff. */
+  consecutiveErrors: number;
+  /** Epoch ms before which fetch() is a no-op (exponential backoff window). */
+  backoffUntil: number;
+  /**
+   * True when this entry was explicitly invalidated (via `invalidate()`) and has
+   * not yet been re-fetched. Subscription callbacks use this flag to distinguish
+   * "app-triggered invalidation → fetch" from "settled fetch → re-render only",
+   * which prevents error/success notifications from spawning a new fetch cycle.
+   */
+  invalidated: boolean;
 }
 
 // ─── Storage adapter ─────────────────────────────────────────────────────────
@@ -159,6 +171,10 @@ export class QueryCache {
               promise: null,
               fetcher: null,
               staleTime: stored.staleTime,
+              retryableError: false,
+              consecutiveErrors: 0,
+              backoffUntil: 0,
+              invalidated: false,
             });
           } catch {
             // Corrupt entry — skip silently.
@@ -212,10 +228,18 @@ export class QueryCache {
 
   isStale(key: string): boolean {
     const e = this.entries.get(key);
-    if (!e || e.status !== "success") return true;
+    if (!e) return true;
+    // Errored entries have staleAt = backoffUntil; they are stale once the backoff expires.
+    if (e.status === "error") return Date.now() >= e.staleAt;
+    if (e.status !== "success") return true;
     return Date.now() >= e.staleAt;
   }
 
+  /** True only when this entry was explicitly invalidated and hasn't been re-fetched yet. */
+  isInvalidated(key: string): boolean {
+    return this.entries.get(key)?.invalidated === true;
+  }
+
   // ─── Fetch ──────────────────────────────────────────────────────────────────
 
   /**
@@ -235,6 +259,9 @@ export class QueryCache {
     // Data is fresh — nothing to do.
     if (existing?.status === "success" && Date.now() < existing.staleAt) return;
 
+    // Respect exponential backoff after consecutive errors.
+    if (existing?.backoffUntil && Date.now() < existing.backoffUntil) return;
+
     // Keep existing data visible while refetching (SWR).
     const entry: CacheEntry = {
       data: existing?.data,
@@ -244,6 +271,10 @@ export class QueryCache {
       promise: null,
       fetcher,
       staleTime,
+      retryableError: false,
+      consecutiveErrors: existing?.consecutiveErrors ?? 0,
+      backoffUntil: existing?.backoffUntil ?? 0,
+      invalidated: false,
     };
 
     const promise: Promise<void> = fetcher().then(
@@ -259,6 +290,10 @@ export class QueryCache {
           promise: null,
           fetcher,
           staleTime,
+          retryableError: false,
+          consecutiveErrors: 0,
+          backoffUntil: 0,
+          invalidated: false,
         };
         this.entries.set(key, next);
         this.persist(key, next);
@@ -268,14 +303,22 @@ export class QueryCache {
       (err: unknown) => {
         const current = this.entries.get(key);
         if (current?.promise !== promise) return;
+        const consecutiveErrors = (current.consecutiveErrors ?? 0) + 1;
+        // Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s cap.
+        const backoffMs = Math.min(1_000 * 2 ** (consecutiveErrors - 1), 30_000);
+        const backoffUntil = Date.now() + backoffMs;
         this.entries.set(key, {
           data: current?.data,
           error: err instanceof Error ? err : new Error(String(err)),
           status: "error",
-          staleAt: 0,
+          staleAt: backoffUntil,
           promise: null,
           fetcher,
           staleTime,
+          retryableError: isRetryableError(err),
+          consecutiveErrors,
+          backoffUntil,
+          invalidated: false,
         });
         this.notify(key);
       },
@@ -292,7 +335,17 @@ export class QueryCache {
   refetch(key: string): void {
     const entry = this.entries.get(key);
     if (!entry?.fetcher) return;
-    this.entries.set(key, { ...entry, staleAt: 0, promise: null });
+    // Clear backoff and reset error state so the forced refetch always proceeds.
+    this.entries.set(key, {
+      ...entry,
+      error: null,
+      status: entry.data !== undefined ? "success" : "loading",
+      staleAt: 0,
+      promise: null,
+      retryableError: false,
+      backoffUntil: 0,
+      invalidated: true,
+    });
     this.fetch(key, entry.fetcher, entry.staleTime);
   }
 
@@ -303,13 +356,27 @@ export class QueryCache {
    *
    * Data is KEPT so components remain in a loaded state (not loading) while the
    * background re-fetch runs. Subscribers should call `cache.fetch()` when they
-   * receive a notification and find the entry is stale.
+   * receive a notification and find the entry is invalidated.
    */
   invalidate(prefix: string): void {
     const toNotify: string[] = [];
     for (const [key, entry] of this.entries) {
       if (key.startsWith(prefix)) {
-        this.entries.set(key, { ...entry, staleAt: 0, promise: null });
+        this.entries.set(key, {
+          ...entry,
+          error: null,
+          status:
+            entry.status === "error"
+              ? entry.data !== undefined
+                ? "success"
+                : "loading"
+              : entry.status,
+          staleAt: 0,
+          promise: null,
+          retryableError: false,
+          backoffUntil: 0,
+          invalidated: true,
+        });
         toNotify.push(key);
       }
     }
@@ -331,6 +398,10 @@ export class QueryCache {
       promise: null,
       fetcher: null,
       staleTime,
+      retryableError: false,
+      consecutiveErrors: 0,
+      backoffUntil: 0,
+      invalidated: false,
     };
     this.entries.set(key, entry);
     this.persist(key, entry);
@@ -354,6 +425,10 @@ export class QueryCache {
       promise: null,
       fetcher: existing?.fetcher ?? null,
       staleTime,
+      retryableError: false,
+      consecutiveErrors: 0,
+      backoffUntil: 0,
+      invalidated: false,
     };
     this.entries.set(key, entry);
     this.persist(key, entry);
@@ -390,14 +465,20 @@ export class QueryCache {
     }
   }
 
-  /** Re-fetch all stale or errored entries. Called on window focus. */
+  /** Re-fetch all stale entries. Called on window focus. */
   refetchStale(): void {
     for (const [key, entry] of this.entries) {
       if (!entry.fetcher) continue;
-      const isStale = entry.status === "error" || Date.now() >= entry.staleAt;
-      if (isStale && !entry.promise) {
+      // Errored entries have staleAt = backoffUntil, so the same check handles them.
+      if (!entry.promise && Date.now() >= entry.staleAt) {
         this.fetch(key, entry.fetcher, entry.staleTime);
       }
     }
   }
 }
+
+function isRetryableError(error: unknown): boolean {
+  if (!error || typeof error !== "object" || !("status" in error)) return true;
+  const status = (error as { status?: unknown }).status;
+  return typeof status !== "number" || status < 400 || status >= 500;
+}

package/src/useAuth.ts

@@ -170,5 +170,6 @@ export function useAuth<T>(selector?: (s: UseAuthResult) => T): UseAuthResult |
   return useSyncExternalStore(
     useCallback((fn) => client.auth.subscribeSnapshot(fn), [client]),
     getSnapshot,
+    getSnapshot,
   ) as UseAuthResult | T;
 }

package/src/useList.ts

@@ -74,7 +74,10 @@ export function useList<
   useEffect(
     () =>
       cache.subscribe(cacheKey, () => {
-        if (enabledRef.current && cache.isStale(cacheKey)) {
+        // Only re-fetch when the entry was explicitly invalidated (invalidate() /
+        // refetch() / interval). Do NOT re-fetch on error or success notifications —
+        // that would create a tight retry loop bypassing refetchInterval and backoff.
+        if (enabledRef.current && cache.isInvalidated(cacheKey)) {
           cache.fetch(cacheKey, () => fetcherRef.current(), staleTimeRef.current);
         }
         rerender();

package/src/useRecord.ts

@@ -47,7 +47,8 @@ export function useRecord<
   useEffect(() => {
     if (!cacheKey) return;
     return cache.subscribe(cacheKey, () => {
-      if (cacheKey && cache.isStale(cacheKey)) {
+      // Only re-fetch on explicit invalidation — not on error/success notifications.
+      if (cacheKey && cache.isInvalidated(cacheKey)) {
         cache.fetch(cacheKey, () => fetcherRef.current(), staleTimeRef.current);
       }
       rerender();