@ttt-productions/query-core 0.14.4 → 0.14.6

package/dist/react/firestore/use-firestore-collection.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-collection.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-collection.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useEffect, useState } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  query,\n  getDocs,\n  onSnapshot,\n  type DocumentData,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';\nimport type {\n  FirestoreCollectionOptions,\n  FirestoreSourceState,\n  WithId,\n  WithSourceState,\n} from '../../firestore/types.js';\n\n/**\n * Fetch all documents from a Firestore collection with optional realtime updates.\n * Use this for small collections where you need all documents at once.\n * For large collections, use useFirestoreInfinite or useFirestorePaginated.\n * * @example\n * ```tsx\n * // Fetch all channels in an entity\n * const { data: channels } = useFirestoreCollection<Channel>({\n * collectionPath: `entities/${entityId}/channels`,\n * queryKey: ['channels', entityId],\n * constraints: [orderBy('createdAt', 'asc')],\n * });\n * * // With realtime updates\n * const { data: members } = useFirestoreCollection<Member>({\n * collectionPath: `entities/${entityId}/members`,\n * queryKey: ['members', entityId],\n * subscribe: true,\n * });\n * ```\n */\nexport function useFirestoreCollection<T extends DocumentData = DocumentData>({\n  collectionPath,\n  queryKey,\n  constraints = [],\n  enabled = true,\n  subscribe = false,\n  staleTime,\n  gcTime,\n  select,\n}: FirestoreCollectionOptions<T>): WithSourceState<UseQueryResult<WithId<T>[], Error>> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n\n  // STABILIZE DEPENDENCIES:\n  // We stringify these because [where('a', '==', 'b')] !== [where('a', '==', 'b')] in JS.\n  const constraintsMemo = JSON.stringify(constraints);\n  const queryKeyMemo = JSON.stringify(queryKey);\n\n  // Listener errors can't surface through useQuery (the queryFn is disabled while\n  // subscribed), so they're tracked here and merged into the returned result.\n  const [subscriptionError, setSubscriptionError] = useState<Error | null>(null);\n  // Metadata-derived source state — reset whenever the subscription identity changes.\n  const [sourceState, setSourceState] = useState<FirestoreSourceState>('connecting');\n\n  useEffect(() => {\n    if (!subscribe || !enabled) return;\n\n    setSubscriptionError(null);\n    setSourceState('connecting');\n\n    // Bounded resubscribe: a transient `permission-denied` (e.g. a failed mid-session\n    // App Check token refresh) is retried on the RESUBSCRIBE_DELAYS_MS ladder before the\n    // error is surfaced. `attempt` resets on any healthy snapshot; `disposed`/timers are\n    // cleaned up on unmount so a pending retry never fires after teardown.\n    let currentUnsubscribe: (() => void) | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let attempt = 0;\n    let disposed = false;\n\n    const start = () => {\n      if (disposed) return;\n      const collectionRef = collection(db, collectionPath);\n      const q = constraints.length > 0\n        ? query(collectionRef, ...constraints)\n        : collectionRef;\n\n      currentUnsubscribe = onSnapshot(\n        q,\n        { includeMetadataChanges: true },\n        (snapshot) => {\n          attempt = 0;\n          setSubscriptionError(null);\n          const items = snapshot.docs.map((docSnap) => {\n            const rawData = docSnap.data();\n            const dataWithId = { id: docSnap.id, ...rawData };\n            const data = select ? select(dataWithId) : dataWithId;\n            return data as WithId<T>;\n          });\n          queryClient.setQueryData(queryKey, items);\n          const fromCache = snapshot.metadata?.fromCache ?? false;\n          setSourceState((prev) => (fromCache ? (prev === 'connecting' ? 'connecting' : 'offline') : 'live'));\n        },\n        (error) => {\n          // Heal a transient permission-denied by resubscribing on the backoff ladder,\n          // keeping the last-known data visible. Only surface the error once the ladder\n          // is exhausted; any other error surfaces immediately, as before.\n          if (isPermissionDeniedError(error) && attempt < RESUBSCRIBE_DELAYS_MS.length) {\n            currentUnsubscribe?.();\n            currentUnsubscribe = null;\n            const delay = RESUBSCRIBE_DELAYS_MS[attempt];\n            attempt += 1;\n            setSourceState('connecting');\n            retryTimer = setTimeout(start, delay);\n            return;\n          }\n          console.error('[useFirestoreCollection] Subscription error:', error);\n          setSubscriptionError(error);\n          setSourceState('error');\n          queryClient.setQueryData(queryKey, undefined);\n        }\n      );\n    };\n\n    start();\n\n    return () => {\n      disposed = true;\n      if (retryTimer) clearTimeout(retryTimer);\n      currentUnsubscribe?.();\n    };\n    // queryKey & constraints are tracked via their stringified forms above; select is intentionally\n    // excluded so an inline caller function doesn't force a re-subscribe on every render.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [db, collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe, queryClient]);\n\n  const queryResult = useQuery({\n    queryKey,\n    queryFn: async (): Promise<WithId<T>[]> => {\n      const collectionRef = collection(db, collectionPath);\n      const q = constraints.length > 0\n        ? query(collectionRef, ...constraints)\n        : collectionRef;\n\n      const snapshot = await getDocs(q);\n      return snapshot.docs.map((docSnap) => {\n        const rawData = docSnap.data();\n        // Include id in data passed to select, so it can be renamed/transformed\n        const dataWithId = { id: docSnap.id, ...rawData };\n        const data = select ? select(dataWithId) : dataWithId;\n        return data as WithId<T>;\n      });\n    },\n    enabled: enabled && !subscribe,\n    staleTime: subscribe ? Infinity : staleTime,\n    gcTime,\n  });\n\n  // Merge a listener error into the result so subscribed consumers see a truthful\n  // isError/error/status instead of a forever-pending disabled query.\n  if (subscribe && subscriptionError) {\n    return {\n      ...queryResult,\n      data: undefined,\n      error: subscriptionError,\n      isError: true,\n      isLoadingError: true,\n      isSuccess: false,\n      isPending: false,\n      isLoading: false,\n      status: 'error',\n      sourceState,\n    } as WithSourceState<UseQueryResult<WithId<T>[], Error>>;\n  }\n\n  return { ...queryResult, sourceState } as WithSourceState<UseQueryResult<WithId<T>[], Error>>;\n}\n"]}
+{"version":3,"file":"use-firestore-collection.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-collection.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useEffect } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  query,\n  getDocs,\n  onSnapshot,\n  type DocumentData,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';\nimport { useSubscriptionStatus } from './subscription-status.js';\nimport type {\n  FirestoreCollectionOptions,\n  WithId,\n  WithSourceState,\n} from '../../firestore/types.js';\n\n/**\n * Fetch all documents from a Firestore collection with optional realtime updates.\n * Use this for small collections where you need all documents at once.\n * For large collections, use useFirestoreInfinite or useFirestorePaginated.\n * * @example\n * ```tsx\n * // Fetch all channels in an entity\n * const { data: channels } = useFirestoreCollection<Channel>({\n * collectionPath: `entities/${entityId}/channels`,\n * queryKey: ['channels', entityId],\n * constraints: [orderBy('createdAt', 'asc')],\n * });\n * * // With realtime updates\n * const { data: members } = useFirestoreCollection<Member>({\n * collectionPath: `entities/${entityId}/members`,\n * queryKey: ['members', entityId],\n * subscribe: true,\n * });\n * ```\n */\nexport function useFirestoreCollection<T extends DocumentData = DocumentData>({\n  collectionPath,\n  queryKey,\n  constraints = [],\n  enabled = true,\n  subscribe = false,\n  staleTime,\n  gcTime,\n  select,\n}: FirestoreCollectionOptions<T>): WithSourceState<UseQueryResult<WithId<T>[], Error>> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n\n  // STABILIZE DEPENDENCIES:\n  // We stringify these because [where('a', '==', 'b')] !== [where('a', '==', 'b')] in JS.\n  const constraintsMemo = JSON.stringify(constraints);\n  const queryKeyMemo = JSON.stringify(queryKey);\n\n  // Listener errors can't surface through useQuery (the queryFn is disabled while\n  // subscribed), so they're tracked per subscription identity and merged into the result.\n  const {\n    error: subscriptionError,\n    sourceState,\n    reset: resetStatus,\n    update: updateStatus,\n  } = useSubscriptionStatus(\n    JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe]),\n  );\n\n  useEffect(() => {\n    if (!subscribe || !enabled) return;\n\n    resetStatus();\n\n    // Bounded resubscribe: a transient `permission-denied` (e.g. a failed mid-session\n    // App Check token refresh) is retried on the RESUBSCRIBE_DELAYS_MS ladder before the\n    // error is surfaced. `attempt` resets on any healthy snapshot; `disposed`/timers are\n    // cleaned up on unmount so a pending retry never fires after teardown.\n    let currentUnsubscribe: (() => void) | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let attempt = 0;\n    let disposed = false;\n\n    const start = () => {\n      if (disposed) return;\n      const collectionRef = collection(db, collectionPath);\n      const q = constraints.length > 0\n        ? query(collectionRef, ...constraints)\n        : collectionRef;\n\n      currentUnsubscribe = onSnapshot(\n        q,\n        { includeMetadataChanges: true },\n        (snapshot) => {\n          attempt = 0;\n          updateStatus({ error: null });\n          const items = snapshot.docs.map((docSnap) => {\n            const rawData = docSnap.data();\n            const dataWithId = { id: docSnap.id, ...rawData };\n            const data = select ? select(dataWithId) : dataWithId;\n            return data as WithId<T>;\n          });\n          queryClient.setQueryData(queryKey, items);\n          const fromCache = snapshot.metadata?.fromCache ?? false;\n          updateStatus((prev) => ({ sourceState: fromCache ? (prev.sourceState === 'connecting' ? 'connecting' : 'offline') : 'live' }));\n        },\n        (error) => {\n          // Heal a transient permission-denied by resubscribing on the backoff ladder,\n          // keeping the last-known data visible. Only surface the error once the ladder\n          // is exhausted; any other error surfaces immediately, as before.\n          if (isPermissionDeniedError(error) && attempt < RESUBSCRIBE_DELAYS_MS.length) {\n            currentUnsubscribe?.();\n            currentUnsubscribe = null;\n            const delay = RESUBSCRIBE_DELAYS_MS[attempt];\n            attempt += 1;\n            updateStatus({ sourceState: 'connecting' });\n            retryTimer = setTimeout(start, delay);\n            return;\n          }\n          console.error('[useFirestoreCollection] Subscription error:', error);\n          updateStatus({ error, sourceState: 'error' });\n          queryClient.setQueryData(queryKey, undefined);\n        }\n      );\n    };\n\n    start();\n\n    return () => {\n      disposed = true;\n      if (retryTimer) clearTimeout(retryTimer);\n      currentUnsubscribe?.();\n    };\n    // queryKey & constraints are tracked via their stringified forms above; select is intentionally\n    // excluded so an inline caller function doesn't force a re-subscribe on every render.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [db, collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe, queryClient, resetStatus, updateStatus]);\n\n  const queryResult = useQuery({\n    queryKey,\n    queryFn: async (): Promise<WithId<T>[]> => {\n      const collectionRef = collection(db, collectionPath);\n      const q = constraints.length > 0\n        ? query(collectionRef, ...constraints)\n        : collectionRef;\n\n      const snapshot = await getDocs(q);\n      return snapshot.docs.map((docSnap) => {\n        const rawData = docSnap.data();\n        // Include id in data passed to select, so it can be renamed/transformed\n        const dataWithId = { id: docSnap.id, ...rawData };\n        const data = select ? select(dataWithId) : dataWithId;\n        return data as WithId<T>;\n      });\n    },\n    enabled: enabled && !subscribe,\n    staleTime: subscribe ? Infinity : staleTime,\n    gcTime,\n  });\n\n  // Merge a listener error into the result so subscribed consumers see a truthful\n  // isError/error/status instead of a forever-pending disabled query.\n  if (subscribe && subscriptionError) {\n    return {\n      ...queryResult,\n      data: undefined,\n      error: subscriptionError,\n      isError: true,\n      isLoadingError: true,\n      isSuccess: false,\n      isPending: false,\n      isLoading: false,\n      status: 'error',\n      sourceState,\n    } as WithSourceState<UseQueryResult<WithId<T>[], Error>>;\n  }\n\n  return { ...queryResult, sourceState } as WithSourceState<UseQueryResult<WithId<T>[], Error>>;\n}\n"]}

package/dist/react/firestore/use-firestore-doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-doc.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-doc.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGhF,OAAO,KAAK,EACV,mBAAmB,EAEnB,MAAM,EACN,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EACrE,OAAO,EACP,QAAQ,EACR,OAAc,EACd,SAAiB,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAwHnF"}
+{"version":3,"file":"use-firestore-doc.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-doc.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIhF,OAAO,KAAK,EACV,mBAAmB,EACnB,MAAM,EACN,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EACrE,OAAO,EACP,QAAQ,EACR,OAAc,EACd,SAAiB,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAyHnF"}

package/dist/react/firestore/use-firestore-doc.js

@@ -1,9 +1,10 @@
 'use client';
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { doc, getDoc, onSnapshot } from 'firebase/firestore';
 import { useFirestoreDb } from './context.js';
 import { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';
+import { useSubscriptionStatus } from './subscription-status.js';
 /**
  * Fetch a single Firestore document with optional realtime updates.
  * * @example
@@ -32,16 +33,13 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
     const queryClient = useQueryClient();
     const queryKeyMemo = JSON.stringify(queryKey);
     // Listener errors can't surface through useQuery (the queryFn is disabled while
-    // subscribed), so they're tracked here and merged into the returned result.
-    const [subscriptionError, setSubscriptionError] = useState(null);
-    // Metadata-derived source state — reset whenever the subscription identity changes.
-    const [sourceState, setSourceState] = useState('connecting');
+    // subscribed), so they're tracked per subscription identity and merged into the result.
+    const { error: subscriptionError, sourceState, reset: resetStatus, update: updateStatus, } = useSubscriptionStatus(JSON.stringify([docPath, queryKeyMemo, enabled, subscribe]));
     // Set up realtime subscription
     useEffect(() => {
         if (!subscribe || !enabled)
             return;
-        setSubscriptionError(null);
-        setSourceState('connecting');
+        resetStatus();
         // Bounded resubscribe: a transient `permission-denied` (e.g. a failed mid-session
         // App Check token refresh) is retried on the RESUBSCRIBE_DELAYS_MS ladder before the
         // error is surfaced. `attempt` resets on any healthy snapshot; `disposed`/timers are
@@ -56,7 +54,7 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
             const docRef = doc(db, docPath);
             currentUnsubscribe = onSnapshot(docRef, { includeMetadataChanges: true }, (snapshot) => {
                 attempt = 0;
-                setSubscriptionError(null);
+                updateStatus({ error: null });
                 if (snapshot.exists()) {
                     const rawData = snapshot.data();
                     // Include id in data passed to select, so it can be renamed/transformed
@@ -68,7 +66,7 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
                     queryClient.setQueryData(queryKey, null);
                 }
                 const fromCache = snapshot.metadata?.fromCache ?? false;
-                setSourceState((prev) => (fromCache ? (prev === 'connecting' ? 'connecting' : 'offline') : 'live'));
+                updateStatus((prev) => ({ sourceState: fromCache ? (prev.sourceState === 'connecting' ? 'connecting' : 'offline') : 'live' }));
             }, (error) => {
                 // Heal a transient permission-denied by resubscribing on the backoff ladder,
                 // keeping the last-known data visible. Only surface the error once the ladder
@@ -78,13 +76,12 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
                     currentUnsubscribe = null;
                     const delay = RESUBSCRIBE_DELAYS_MS[attempt];
                     attempt += 1;
-                    setSourceState('connecting');
+                    updateStatus({ sourceState: 'connecting' });
                     retryTimer = setTimeout(start, delay);
                     return;
                 }
                 console.error('[useFirestoreDoc] Subscription error:', error);
-                setSubscriptionError(error);
-                setSourceState('error');
+                updateStatus({ error, sourceState: 'error' });
                 queryClient.setQueryData(queryKey, undefined);
             });
         };
@@ -98,7 +95,7 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
         // Note: select intentionally excluded to prevent re-subscribing on every render if the caller
         // passes an inline function. queryKey is tracked via queryKeyMemo above.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [db, docPath, queryKeyMemo, enabled, subscribe, queryClient]);
+    }, [db, docPath, queryKeyMemo, enabled, subscribe, queryClient, resetStatus, updateStatus]);
     const query = useQuery({
         queryKey,
         queryFn: async () => {

package/dist/react/firestore/use-firestore-doc.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-doc.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-doc.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useEffect, useState } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport { doc, getDoc, onSnapshot, type DocumentData } from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';\nimport type {\n  FirestoreDocOptions,\n  FirestoreSourceState,\n  WithId,\n  WithSourceState,\n} from '../../firestore/types.js';\n\n/**\n * Fetch a single Firestore document with optional realtime updates.\n * * @example\n * ```tsx\n * // Simple fetch\n * const { data: user } = useFirestoreDoc<User>({\n * docPath: `users/${userId}`,\n * queryKey: ['user', userId],\n * });\n * * // With realtime updates\n * const { data: entity } = useFirestoreDoc<Entity>({\n * docPath: `entities/${entityId}`,\n * queryKey: ['entity', entityId],\n * subscribe: true,\n * });\n * * // Conditional fetch\n * const { data: profile } = useFirestoreDoc<Profile>({\n * docPath: `profiles/${userId}`,\n * queryKey: ['profile', userId],\n * enabled: !!userId,\n * });\n * ```\n */\nexport function useFirestoreDoc<T extends DocumentData = DocumentData>({\n  docPath,\n  queryKey,\n  enabled = true,\n  subscribe = false,\n  staleTime,\n  gcTime,\n  select,\n}: FirestoreDocOptions<T>): WithSourceState<UseQueryResult<WithId<T> | null, Error>> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n  const queryKeyMemo = JSON.stringify(queryKey);\n\n  // Listener errors can't surface through useQuery (the queryFn is disabled while\n  // subscribed), so they're tracked here and merged into the returned result.\n  const [subscriptionError, setSubscriptionError] = useState<Error | null>(null);\n  // Metadata-derived source state — reset whenever the subscription identity changes.\n  const [sourceState, setSourceState] = useState<FirestoreSourceState>('connecting');\n\n  // Set up realtime subscription\n  useEffect(() => {\n    if (!subscribe || !enabled) return;\n\n    setSubscriptionError(null);\n    setSourceState('connecting');\n\n    // Bounded resubscribe: a transient `permission-denied` (e.g. a failed mid-session\n    // App Check token refresh) is retried on the RESUBSCRIBE_DELAYS_MS ladder before the\n    // error is surfaced. `attempt` resets on any healthy snapshot; `disposed`/timers are\n    // cleaned up on unmount so a pending retry never fires after teardown.\n    let currentUnsubscribe: (() => void) | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let attempt = 0;\n    let disposed = false;\n\n    const start = () => {\n      if (disposed) return;\n      const docRef = doc(db, docPath);\n      currentUnsubscribe = onSnapshot(\n        docRef,\n        { includeMetadataChanges: true },\n        (snapshot) => {\n          attempt = 0;\n          setSubscriptionError(null);\n          if (snapshot.exists()) {\n            const rawData = snapshot.data();\n            // Include id in data passed to select, so it can be renamed/transformed\n            const dataWithId = { id: snapshot.id, ...rawData };\n            const data = select ? select(dataWithId) : dataWithId;\n            queryClient.setQueryData(queryKey, data as WithId<T>);\n          } else {\n            queryClient.setQueryData(queryKey, null);\n          }\n          const fromCache = snapshot.metadata?.fromCache ?? false;\n          setSourceState((prev) => (fromCache ? (prev === 'connecting' ? 'connecting' : 'offline') : 'live'));\n        },\n        (error) => {\n          // Heal a transient permission-denied by resubscribing on the backoff ladder,\n          // keeping the last-known data visible. Only surface the error once the ladder\n          // is exhausted; any other error surfaces immediately, as before.\n          if (isPermissionDeniedError(error) && attempt < RESUBSCRIBE_DELAYS_MS.length) {\n            currentUnsubscribe?.();\n            currentUnsubscribe = null;\n            const delay = RESUBSCRIBE_DELAYS_MS[attempt];\n            attempt += 1;\n            setSourceState('connecting');\n            retryTimer = setTimeout(start, delay);\n            return;\n          }\n          console.error('[useFirestoreDoc] Subscription error:', error);\n          setSubscriptionError(error);\n          setSourceState('error');\n          queryClient.setQueryData(queryKey, undefined);\n        }\n      );\n    };\n\n    start();\n\n    return () => {\n      disposed = true;\n      if (retryTimer) clearTimeout(retryTimer);\n      currentUnsubscribe?.();\n    };\n    // Note: select intentionally excluded to prevent re-subscribing on every render if the caller\n    // passes an inline function. queryKey is tracked via queryKeyMemo above.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [db, docPath, queryKeyMemo, enabled, subscribe, queryClient]);\n\n  const query = useQuery({\n    queryKey,\n    queryFn: async (): Promise<WithId<T> | null> => {\n      const docRef = doc(db, docPath);\n      const snapshot = await getDoc(docRef);\n\n      if (!snapshot.exists()) {\n        return null;\n      }\n\n      const rawData = snapshot.data();\n      // Include id in data passed to select, so it can be renamed/transformed\n      const dataWithId = { id: snapshot.id, ...rawData };\n      const data = select ? select(dataWithId) : dataWithId;\n      return data as WithId<T>;\n    },\n    enabled: enabled && !subscribe, // Don't fetch if subscribing (snapshot handles it)\n    staleTime: subscribe ? Infinity : staleTime, // Realtime data is always fresh\n    gcTime,\n  });\n\n  // Merge a listener error into the result so subscribed consumers see a truthful\n  // isError/error/status instead of a forever-pending disabled query.\n  if (subscribe && subscriptionError) {\n    return {\n      ...query,\n      data: undefined,\n      error: subscriptionError,\n      isError: true,\n      isLoadingError: true,\n      isSuccess: false,\n      isPending: false,\n      isLoading: false,\n      status: 'error',\n      sourceState,\n    } as WithSourceState<UseQueryResult<WithId<T> | null, Error>>;\n  }\n\n  return { ...query, sourceState } as WithSourceState<UseQueryResult<WithId<T> | null, Error>>;\n}\n"]}
+{"version":3,"file":"use-firestore-doc.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-doc.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useEffect } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport { doc, getDoc, onSnapshot, type DocumentData } from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';\nimport { useSubscriptionStatus } from './subscription-status.js';\nimport type {\n  FirestoreDocOptions,\n  WithId,\n  WithSourceState,\n} from '../../firestore/types.js';\n\n/**\n * Fetch a single Firestore document with optional realtime updates.\n * * @example\n * ```tsx\n * // Simple fetch\n * const { data: user } = useFirestoreDoc<User>({\n * docPath: `users/${userId}`,\n * queryKey: ['user', userId],\n * });\n * * // With realtime updates\n * const { data: entity } = useFirestoreDoc<Entity>({\n * docPath: `entities/${entityId}`,\n * queryKey: ['entity', entityId],\n * subscribe: true,\n * });\n * * // Conditional fetch\n * const { data: profile } = useFirestoreDoc<Profile>({\n * docPath: `profiles/${userId}`,\n * queryKey: ['profile', userId],\n * enabled: !!userId,\n * });\n * ```\n */\nexport function useFirestoreDoc<T extends DocumentData = DocumentData>({\n  docPath,\n  queryKey,\n  enabled = true,\n  subscribe = false,\n  staleTime,\n  gcTime,\n  select,\n}: FirestoreDocOptions<T>): WithSourceState<UseQueryResult<WithId<T> | null, Error>> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n  const queryKeyMemo = JSON.stringify(queryKey);\n\n  // Listener errors can't surface through useQuery (the queryFn is disabled while\n  // subscribed), so they're tracked per subscription identity and merged into the result.\n  const {\n    error: subscriptionError,\n    sourceState,\n    reset: resetStatus,\n    update: updateStatus,\n  } = useSubscriptionStatus(JSON.stringify([docPath, queryKeyMemo, enabled, subscribe]));\n\n  // Set up realtime subscription\n  useEffect(() => {\n    if (!subscribe || !enabled) return;\n\n    resetStatus();\n\n    // Bounded resubscribe: a transient `permission-denied` (e.g. a failed mid-session\n    // App Check token refresh) is retried on the RESUBSCRIBE_DELAYS_MS ladder before the\n    // error is surfaced. `attempt` resets on any healthy snapshot; `disposed`/timers are\n    // cleaned up on unmount so a pending retry never fires after teardown.\n    let currentUnsubscribe: (() => void) | null = null;\n    let retryTimer: ReturnType<typeof setTimeout> | null = null;\n    let attempt = 0;\n    let disposed = false;\n\n    const start = () => {\n      if (disposed) return;\n      const docRef = doc(db, docPath);\n      currentUnsubscribe = onSnapshot(\n        docRef,\n        { includeMetadataChanges: true },\n        (snapshot) => {\n          attempt = 0;\n          updateStatus({ error: null });\n          if (snapshot.exists()) {\n            const rawData = snapshot.data();\n            // Include id in data passed to select, so it can be renamed/transformed\n            const dataWithId = { id: snapshot.id, ...rawData };\n            const data = select ? select(dataWithId) : dataWithId;\n            queryClient.setQueryData(queryKey, data as WithId<T>);\n          } else {\n            queryClient.setQueryData(queryKey, null);\n          }\n          const fromCache = snapshot.metadata?.fromCache ?? false;\n          updateStatus((prev) => ({ sourceState: fromCache ? (prev.sourceState === 'connecting' ? 'connecting' : 'offline') : 'live' }));\n        },\n        (error) => {\n          // Heal a transient permission-denied by resubscribing on the backoff ladder,\n          // keeping the last-known data visible. Only surface the error once the ladder\n          // is exhausted; any other error surfaces immediately, as before.\n          if (isPermissionDeniedError(error) && attempt < RESUBSCRIBE_DELAYS_MS.length) {\n            currentUnsubscribe?.();\n            currentUnsubscribe = null;\n            const delay = RESUBSCRIBE_DELAYS_MS[attempt];\n            attempt += 1;\n            updateStatus({ sourceState: 'connecting' });\n            retryTimer = setTimeout(start, delay);\n            return;\n          }\n          console.error('[useFirestoreDoc] Subscription error:', error);\n          updateStatus({ error, sourceState: 'error' });\n          queryClient.setQueryData(queryKey, undefined);\n        }\n      );\n    };\n\n    start();\n\n    return () => {\n      disposed = true;\n      if (retryTimer) clearTimeout(retryTimer);\n      currentUnsubscribe?.();\n    };\n    // Note: select intentionally excluded to prevent re-subscribing on every render if the caller\n    // passes an inline function. queryKey is tracked via queryKeyMemo above.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [db, docPath, queryKeyMemo, enabled, subscribe, queryClient, resetStatus, updateStatus]);\n\n  const query = useQuery({\n    queryKey,\n    queryFn: async (): Promise<WithId<T> | null> => {\n      const docRef = doc(db, docPath);\n      const snapshot = await getDoc(docRef);\n\n      if (!snapshot.exists()) {\n        return null;\n      }\n\n      const rawData = snapshot.data();\n      // Include id in data passed to select, so it can be renamed/transformed\n      const dataWithId = { id: snapshot.id, ...rawData };\n      const data = select ? select(dataWithId) : dataWithId;\n      return data as WithId<T>;\n    },\n    enabled: enabled && !subscribe, // Don't fetch if subscribing (snapshot handles it)\n    staleTime: subscribe ? Infinity : staleTime, // Realtime data is always fresh\n    gcTime,\n  });\n\n  // Merge a listener error into the result so subscribed consumers see a truthful\n  // isError/error/status instead of a forever-pending disabled query.\n  if (subscribe && subscriptionError) {\n    return {\n      ...query,\n      data: undefined,\n      error: subscriptionError,\n      isError: true,\n      isLoadingError: true,\n      isSuccess: false,\n      isPending: false,\n      isLoading: false,\n      status: 'error',\n      sourceState,\n    } as WithSourceState<UseQueryResult<WithId<T> | null, Error>>;\n  }\n\n  return { ...query, sourceState } as WithSourceState<UseQueryResult<WithId<T> | null, Error>>;\n}\n"]}

package/dist/react/firestore/use-firestore-live-infinite.d.ts

@@ -1,27 +1,44 @@
 import { type DocumentData } from 'firebase/firestore';
-import type { FirestoreLiveInfiniteOptions } from '../../firestore/types.js';
+import type { FirestoreLiveInfiniteOptions, FirestoreSourceState } from '../../firestore/types.js';
 export interface FirestoreLiveInfiniteResult<T> {
-    /** Merged + deduped live-window and older items, sorted per `sort` (default asc). */
+    /** The current subscription identity's rows — live set plus loaded older pages, sorted per `sort`. */
     items: T[];
-    /** True until the live window's first snapshot arrives. */
+    /** True until the current identity's first snapshot arrives, unless its listener has failed. */
     isInitialLoading: boolean;
-    /** Load the next older page. */
+    /** Liveness of the current identity's listener; `connecting` from that identity's first render. */
+    sourceState: FirestoreSourceState;
+    /** The listener's failure for the current identity; `null` while connecting, live, or offline. */
+    error: Error | null;
+    /** Load the next older page. Never rejects — a failed read lands in `olderError`. */
     fetchOlder: () => Promise<void>;
-    /** Whether more older pages remain. */
+    /** Whether older rows exist that are not loaded yet (a one-doc look-ahead, never a full-page guess). */
     hasOlder: boolean;
-    /** Whether an older page is currently being fetched. */
+    /** Whether an older page is being read (including a `retry` of one). */
     isFetchingOlder: boolean;
+    /** The last older-page read failed; `null` once an older read succeeds. */
+    olderError: Error | null;
+    /** Re-run what failed: resubscribe a failed listener, re-read a failed older page. */
+    retry: () => void;
 }
 /**
- * A live newest-window plus cursor-bridged older pagination, merged into one
- * ordered list. The newest page is a realtime `onSnapshot` window (orderBy
- * descending, limited to `pageSize`); older pages load on demand via `getDocs`,
- * each seeded with `startAfter(previousOldestDoc)` — the first older page starts
- * after the live window's oldest document, so there is no gap and no re-read of
- * pages already in memory.
+ * A live list (newest rows realtime) with older rows paged in on demand, merged into
+ * one ordered list.
  *
- * Generic enough for any live feed (chat threads, live comments, activity
- * feeds). `db` comes from `<FirestoreProvider>`.
+ * Until the first server-confirmed snapshot that has rows, the listener reads the newest
+ * `pageSize` rows plus one look-ahead row. That snapshot fixes an anchor — the oldest row
+ * of the window — and from then on the listener covers anchor → newest with no limit, so
+ * it grows only with rows that arrive while the list is open, and every older page starts
+ * after the anchor. Nothing can fall between the live set and the older pages, however
+ * many rows arrive. Older pages carry the same one-row look-ahead, so `hasOlder` is false
+ * exactly when nothing older exists.
+ *
+ * Everything read is tagged to its subscription identity (path, key, ordering,
+ * constraints, page size, enabled): a new identity renders empty and connecting in its
+ * first render, and a retired identity's late callback or older page never lands.
+ *
+ * A `permission-denied` listener error resubscribes on the `RESUBSCRIBE_DELAYS_MS` ladder
+ * before surfacing; any other listener error surfaces at once. Rows already shown are
+ * kept beside the error. `db` comes from `<FirestoreProvider>`.
  */
 export declare function useFirestoreLiveInfinite<T = DocumentData & {
     id: string;

package/dist/react/firestore/use-firestore-live-infinite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-live-infinite.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-live-infinite.ts"],"names":[],"mappings":"AAIA,OAAO,EAQL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAI7E,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,qFAAqF;IACrF,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,2DAA2D;IAC3D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gCAAgC;IAChC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,eAAe,EAAE,OAAO,CAAC;CAC1B;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,EAC1E,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,WAAgB,EAChB,QAAQ,EAAE,iBAAsB,EAChC,OAAc,EACd,MAAM,EACN,YAAY,EACZ,IAAY,GACb,EAAE,4BAA4B,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC,CAAC,CAAC,CA6GlE"}
+{"version":3,"file":"use-firestore-live-infinite.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-live-infinite.ts"],"names":[],"mappings":"AAIA,OAAO,EASL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAInG,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,sGAAsG;IACtG,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,gGAAgG;IAChG,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mGAAmG;IACnG,WAAW,EAAE,oBAAoB,CAAC;IAClC,kGAAkG;IAClG,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,qFAAqF;IACrF,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,wGAAwG;IACxG,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,sFAAsF;IACtF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AA2BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,EAC1E,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,WAAgB,EAChB,QAAQ,EAAE,iBAAsB,EAChC,OAAc,EACd,MAAM,EACN,YAAY,EACZ,IAAY,GACb,EAAE,4BAA4B,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC,CAAC,CAAC,CA4PlE"}

package/dist/react/firestore/use-firestore-live-infinite.js

@@ -1,19 +1,40 @@
 'use client';
 import * as React from 'react';
 import { useInfiniteQuery } from '@tanstack/react-query';
-import { collection, query, orderBy, limit, startAfter, getDocs, onSnapshot, } from 'firebase/firestore';
+import { collection, query, orderBy, limit, startAfter, endAt, getDocs, onSnapshot, } from 'firebase/firestore';
 import { useFirestoreDb } from './context.js';
+import { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';
 const MAX_PAGE_SIZE = 100;
+function freshWindow(identity) {
+    return {
+        identity,
+        ready: false,
+        entries: [],
+        anchor: null,
+        olderExists: false,
+        sourceState: 'connecting',
+        error: null,
+    };
+}
 /**
- * A live newest-window plus cursor-bridged older pagination, merged into one
- * ordered list. The newest page is a realtime `onSnapshot` window (orderBy
- * descending, limited to `pageSize`); older pages load on demand via `getDocs`,
- * each seeded with `startAfter(previousOldestDoc)` — the first older page starts
- * after the live window's oldest document, so there is no gap and no re-read of
- * pages already in memory.
+ * A live list (newest rows realtime) with older rows paged in on demand, merged into
+ * one ordered list.
+ *
+ * Until the first server-confirmed snapshot that has rows, the listener reads the newest
+ * `pageSize` rows plus one look-ahead row. That snapshot fixes an anchor — the oldest row
+ * of the window — and from then on the listener covers anchor → newest with no limit, so
+ * it grows only with rows that arrive while the list is open, and every older page starts
+ * after the anchor. Nothing can fall between the live set and the older pages, however
+ * many rows arrive. Older pages carry the same one-row look-ahead, so `hasOlder` is false
+ * exactly when nothing older exists.
  *
- * Generic enough for any live feed (chat threads, live comments, activity
- * feeds). `db` comes from `<FirestoreProvider>`.
+ * Everything read is tagged to its subscription identity (path, key, ordering,
+ * constraints, page size, enabled): a new identity renders empty and connecting in its
+ * first render, and a retired identity's late callback or older page never lands.
+ *
+ * A `permission-denied` listener error resubscribes on the `RESUBSCRIBE_DELAYS_MS` ladder
+ * before surfacing; any other listener error surfaces at once. Rows already shown are
+ * kept beside the error. `db` comes from `<FirestoreProvider>`.
  */
 export function useFirestoreLiveInfinite({ collectionPath, queryKey, orderByField, constraints = [], pageSize: requestedPageSize = 20, enabled = true, select, getSortValue, sort = 'asc', }) {
     const db = useFirestoreDb();
@@ -32,77 +53,203 @@ export function useFirestoreLiveInfinite({ collectionPath, queryKey, orderByFiel
             : dataWithId[orderByField];
         return { docId: snap.id, sortValue, item };
     }, [orderByField]);
-    // Stable string deps for the subscription effect (values are captured via the
-    // queryKey, which the caller varies per collection/thread).
+    // Constraint objects are fresh every render; their serialized form is the identity.
     const queryKeyMemo = JSON.stringify(queryKey);
     const constraintsMemo = JSON.stringify(constraints);
-    const [windowState, setWindowState] = React.useState({ ready: false, entries: [], oldestDoc: null });
+    const identity = JSON.stringify([
+        collectionPath,
+        queryKeyMemo,
+        orderByField,
+        constraintsMemo,
+        pageSize,
+        enabled,
+    ]);
+    const [windowState, setWindowState] = React.useState(() => freshWindow(identity));
+    const windowRef = React.useRef(windowState);
+    windowRef.current = windowState;
+    const [retryNonce, setRetryNonce] = React.useState(0);
+    const current = windowState.identity === identity ? windowState : freshWindow(identity);
     React.useEffect(() => {
         if (!enabled) {
-            setWindowState({ ready: false, entries: [], oldestDoc: null });
+            // Retire the enabled identity's rows, so re-enabling starts afresh rather than resuming.
+            setWindowState(freshWindow(identity));
             return;
         }
-        const colRef = collection(db, collectionPath);
-        const q = query(colRef, ...constraints, orderBy(orderByField, 'desc'), limit(pageSize));
-        const unsub = onSnapshot(q, (snap) => {
-            const docs = snap.docs;
-            setWindowState({
-                ready: true,
-                entries: docs.map(toEntry),
-                oldestDoc: docs[docs.length - 1] ?? null,
+        // A retry of the same identity resumes from its anchor and keeps its rows.
+        const prior = windowRef.current;
+        const resumed = prior.identity === identity;
+        setWindowState((prev) => prev.identity === identity
+            ? { ...prev, error: null, sourceState: 'connecting' }
+            : freshWindow(identity));
+        let disposed = false;
+        let unsubscribe = null;
+        let retryTimer = null;
+        let attempt = 0;
+        let currentAnchor = resumed ? prior.anchor : null;
+        const update = (fn) => {
+            if (disposed)
+                return;
+            setWindowState((prev) => (prev.identity === identity ? fn(prev) : prev));
+        };
+        const listen = (anchor) => {
+            if (disposed)
+                return;
+            currentAnchor = anchor;
+            const colRef = collection(db, collectionPath);
+            const q = anchor
+                ? query(colRef, ...constraints, orderBy(orderByField, 'desc'), endAt(anchor))
+                : query(colRef, ...constraints, orderBy(orderByField, 'desc'), limit(pageSize + 1));
+            let serverConfirmed = false;
+            unsubscribe = onSnapshot(q, { includeMetadataChanges: true }, (snap) => {
+                if (disposed)
+                    return;
+                attempt = 0;
+                const docs = snap.docs;
+                const fromCache = snap.metadata?.fromCache ?? false;
+                const nextSource = (prev) => {
+                    if (!fromCache)
+                        return 'live';
+                    if (!serverConfirmed)
+                        return prev === 'error' ? 'connecting' : prev;
+                    return 'offline';
+                };
+                if (!fromCache)
+                    serverConfirmed = true;
+                if (anchor) {
+                    update((prev) => ({
+                        ...prev,
+                        ready: true,
+                        entries: docs.map(toEntry),
+                        sourceState: nextSource(prev.sourceState),
+                        error: null,
+                    }));
+                    return;
+                }
+                const windowDocs = docs.slice(0, pageSize);
+                if (fromCache || windowDocs.length === 0) {
+                    update((prev) => ({
+                        ...prev,
+                        ready: true,
+                        entries: windowDocs.map(toEntry),
+                        sourceState: nextSource(prev.sourceState),
+                        error: null,
+                    }));
+                    return;
+                }
+                const newAnchor = windowDocs[windowDocs.length - 1];
+                update((prev) => ({
+                    ...prev,
+                    ready: true,
+                    entries: windowDocs.map(toEntry),
+                    anchor: newAnchor,
+                    olderExists: docs.length > pageSize,
+                    sourceState: 'live',
+                    error: null,
+                }));
+                unsubscribe?.();
+                unsubscribe = null;
+                listen(newAnchor);
+            }, (error) => {
+                if (disposed)
+                    return;
+                unsubscribe?.();
+                unsubscribe = null;
+                if (isPermissionDeniedError(error) && attempt < RESUBSCRIBE_DELAYS_MS.length) {
+                    const delay = RESUBSCRIBE_DELAYS_MS[attempt];
+                    attempt += 1;
+                    update((prev) => ({ ...prev, sourceState: 'connecting' }));
+                    retryTimer = setTimeout(() => listen(currentAnchor), delay);
+                    return;
+                }
+                console.error('[useFirestoreLiveInfinite] Subscription error:', error);
+                update((prev) => ({ ...prev, sourceState: 'error', error }));
             });
-        });
-        return () => unsub();
-        // constraints captured via constraintsMemo; queryKey via queryKeyMemo; toEntry is stable.
+        };
+        listen(currentAnchor);
+        return () => {
+            disposed = true;
+            if (retryTimer)
+                clearTimeout(retryTimer);
+            unsubscribe?.();
+        };
+        // `identity` carries collectionPath, queryKey, orderByField, constraints, pageSize, and
+        // enabled; constraints are read from the render that produced it.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [db, collectionPath, orderByField, pageSize, enabled, queryKeyMemo, constraintsMemo, toEntry]);
+    }, [db, identity, retryNonce, toEntry]);
+    const anchor = enabled ? current.anchor : null;
+    const olderEnabled = anchor !== null && current.olderExists;
     const older = useInfiniteQuery({
-        queryKey: [...queryKey, 'older'],
-        enabled: enabled && windowState.ready,
+        queryKey: [...queryKey, 'older', identity, anchor?.id ?? null],
+        enabled: olderEnabled,
         initialPageParam: undefined,
         queryFn: async ({ pageParam }) => {
-            const cursor = pageParam ?? windowState.oldestDoc ?? undefined;
+            const cursor = pageParam ?? anchor;
             if (!cursor) {
-                return {
-                    entries: [],
-                    nextCursor: undefined,
-                };
+                return { entries: [], nextCursor: undefined };
             }
             const colRef = collection(db, collectionPath);
-            const q = query(colRef, ...constraints, orderBy(orderByField, 'desc'), startAfter(cursor), limit(pageSize));
+            const q = query(colRef, ...constraints, orderBy(orderByField, 'desc'), startAfter(cursor), limit(pageSize + 1));
             const snap = await getDocs(q);
             const docs = snap.docs;
+            const page = docs.slice(0, pageSize);
             return {
-                entries: docs.map(toEntry),
-                nextCursor: docs.length === pageSize ? docs[docs.length - 1] : undefined,
+                entries: page.map(toEntry),
+                nextCursor: docs.length > pageSize ? page[page.length - 1] : undefined,
             };
         },
         getNextPageParam: (last) => last.nextCursor,
     });
-    const { fetchNextPage } = older;
+    const { data: olderData, isFetching: olderFetching, isError: olderIsError, error: olderErr, hasNextPage: olderHasNext, fetchNextPage, refetch: refetchOlder, } = older;
+    const olderPages = olderEnabled ? olderData?.pages : undefined;
+    const hasOlder = olderEnabled && (olderPages ? Boolean(olderHasNext) : true);
+    const olderError = olderEnabled && olderIsError ? olderErr : null;
     const fetchOlder = React.useCallback(async () => {
-        await fetchNextPage();
-    }, [fetchNextPage]);
+        if (!olderEnabled || olderFetching)
+            return;
+        if (!olderPages) {
+            await refetchOlder();
+            return;
+        }
+        if (olderHasNext)
+            await fetchNextPage();
+    }, [olderEnabled, olderFetching, olderPages, olderHasNext, refetchOlder, fetchNextPage]);
+    const listenerFailed = enabled && current.error !== null;
+    const retry = React.useCallback(() => {
+        if (listenerFailed) {
+            setWindowState((prev) => prev.identity === identity ? { ...prev, error: null, sourceState: 'connecting' } : prev);
+            setRetryNonce((n) => n + 1);
+        }
+        if (olderError && !olderFetching) {
+            if (olderPages)
+                void fetchNextPage();
+            else
+                void refetchOlder();
+        }
+    }, [listenerFailed, identity, olderError, olderFetching, olderPages, fetchNextPage, refetchOlder]);
     const items = React.useMemo(() => {
         if (!enabled)
             return [];
-        const olderEntries = (older.data?.pages ?? []).flatMap((p) => p.entries);
-        // Window entries win on overlap (they are the freshest, live copies).
+        const olderEntries = (olderPages ?? []).flatMap((p) => p.entries);
+        // Live entries win on overlap (they are the freshest copies).
         const merged = new Map();
-        for (const entry of [...windowState.entries, ...olderEntries]) {
+        for (const entry of [...current.entries, ...olderEntries]) {
             if (!merged.has(entry.docId))
                 merged.set(entry.docId, entry);
         }
         const arr = Array.from(merged.values());
         arr.sort((a, b) => (sort === 'asc' ? a.sortValue - b.sortValue : b.sortValue - a.sortValue));
         return arr.map((e) => e.item);
-    }, [enabled, older.data, windowState.entries, sort]);
+    }, [enabled, olderPages, current.entries, sort]);
     return {
         items,
-        isInitialLoading: enabled ? !windowState.ready : false,
+        isInitialLoading: enabled ? !current.ready && current.error === null : false,
+        sourceState: current.sourceState,
+        error: enabled ? current.error : null,
         fetchOlder,
-        hasOlder: Boolean(older.hasNextPage),
-        isFetchingOlder: older.isFetchingNextPage,
+        hasOlder,
+        isFetchingOlder: olderEnabled && olderFetching,
+        olderError,
+        retry,
     };
 }
 //# sourceMappingURL=use-firestore-live-infinite.js.map