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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunbase-ae/react-sdk",
-  "version": "1.0.1-next.2.7e6534b",
+  "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",

package/src/cache.ts

@@ -25,6 +25,17 @@ export interface CacheEntry {
   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 ─────────────────────────────────────────────────────────
@@ -161,6 +172,9 @@ export class QueryCache {
               fetcher: null,
               staleTime: stored.staleTime,
               retryableError: false,
+              consecutiveErrors: 0,
+              backoffUntil: 0,
+              invalidated: false,
             });
           } catch {
             // Corrupt entry — skip silently.
@@ -215,11 +229,17 @@ export class QueryCache {
   isStale(key: string): boolean {
     const e = this.entries.get(key);
     if (!e) return true;
-    if (e.status === "error") return false;
+    // 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 ──────────────────────────────────────────────────────────────────
 
   /**
@@ -239,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,
@@ -249,6 +272,9 @@ export class QueryCache {
       fetcher,
       staleTime,
       retryableError: false,
+      consecutiveErrors: existing?.consecutiveErrors ?? 0,
+      backoffUntil: existing?.backoffUntil ?? 0,
+      invalidated: false,
     };
 
     const promise: Promise<void> = fetcher().then(
@@ -265,6 +291,9 @@ export class QueryCache {
           fetcher,
           staleTime,
           retryableError: false,
+          consecutiveErrors: 0,
+          backoffUntil: 0,
+          invalidated: false,
         };
         this.entries.set(key, next);
         this.persist(key, next);
@@ -274,16 +303,22 @@ export class QueryCache {
       (err: unknown) => {
         const current = this.entries.get(key);
         if (current?.promise !== promise) return;
-        const retryableError = isRetryableError(err);
+        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,
+          retryableError: isRetryableError(err),
+          consecutiveErrors,
+          backoffUntil,
+          invalidated: false,
         });
         this.notify(key);
       },
@@ -300,6 +335,7 @@ export class QueryCache {
   refetch(key: string): void {
     const entry = this.entries.get(key);
     if (!entry?.fetcher) return;
+    // Clear backoff and reset error state so the forced refetch always proceeds.
     this.entries.set(key, {
       ...entry,
       error: null,
@@ -307,6 +343,8 @@ export class QueryCache {
       staleAt: 0,
       promise: null,
       retryableError: false,
+      backoffUntil: 0,
+      invalidated: true,
     });
     this.fetch(key, entry.fetcher, entry.staleTime);
   }
@@ -318,7 +356,7 @@ 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[] = [];
@@ -336,6 +374,8 @@ export class QueryCache {
           staleAt: 0,
           promise: null,
           retryableError: false,
+          backoffUntil: 0,
+          invalidated: true,
         });
         toNotify.push(key);
       }
@@ -359,6 +399,9 @@ export class QueryCache {
       fetcher: null,
       staleTime,
       retryableError: false,
+      consecutiveErrors: 0,
+      backoffUntil: 0,
+      invalidated: false,
     };
     this.entries.set(key, entry);
     this.persist(key, entry);
@@ -383,6 +426,9 @@ export class QueryCache {
       fetcher: existing?.fetcher ?? null,
       staleTime,
       retryableError: false,
+      consecutiveErrors: 0,
+      backoffUntil: 0,
+      invalidated: false,
     };
     this.entries.set(key, entry);
     this.persist(key, entry);
@@ -419,13 +465,12 @@ 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 shouldRetryError = entry.status === "error" && entry.retryableError;
-      const isStale = entry.status === "success" && Date.now() >= entry.staleAt;
-      if ((shouldRetryError || 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);
       }
     }

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();