@ttt-productions/query-core 0.14.7 → 0.14.9

package/dist/react/firestore/subscription-status.js

@@ -1,20 +1,24 @@
 'use client';
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+function freshStatus(identity) {
+    return { identity, error: null, sourceState: 'connecting', restart: null, restarts: 0 };
+}
 /**
  * A realtime listener's source state and error, tagged to the subscription identity that
  * produced them. A new identity reads `connecting` with no error from its first render;
  * writes made for a retired identity are dropped once the new identity's listener has
  * started (it calls `reset`).
+ *
+ * `restart()` clears the error and bumps `restarts`; the listener effect re-opens on the bump,
+ * and its first snapshot or next surfaced error ends the restart (`settled` in the patch).
  */
 export function useSubscriptionStatus(identity) {
-    const [status, setStatus] = useState(() => ({
-        identity,
-        error: null,
-        sourceState: 'connecting',
-    }));
-    const current = status.identity === identity ? status : { identity, error: null, sourceState: 'connecting' };
+    const [status, setStatus] = useState(() => freshStatus(identity));
+    const current = status.identity === identity ? status : freshStatus(identity);
     const reset = useCallback(() => {
-        setStatus({ identity, error: null, sourceState: 'connecting' });
+        setStatus((prev) => prev.identity === identity
+            ? { ...prev, error: null, sourceState: 'connecting' }
+            : freshStatus(identity));
     }, [identity]);
     const update = useCallback((patch) => {
         setStatus((prev) => {
@@ -24,6 +28,138 @@ export function useSubscriptionStatus(identity) {
             return { ...prev, ...next };
         });
     }, [identity]);
-    return { error: current.error, sourceState: current.sourceState, reset, update };
+    // The identity the hook renders now. A `restart` captured under an earlier identity must not
+    // touch the current one's status, or every write the current listener makes would be dropped.
+    const renderedIdentity = useRef(identity);
+    useEffect(() => {
+        renderedIdentity.current = identity;
+    }, [identity]);
+    /** Re-opens the listener; false (and nothing changes) when this identity is no longer rendered. */
+    const restart = useCallback(() => {
+        if (renderedIdentity.current !== identity)
+            return false;
+        setStatus((prev) => {
+            const base = prev.identity === identity ? prev : freshStatus(identity);
+            return {
+                ...base,
+                error: null,
+                sourceState: 'connecting',
+                restart: { fromError: base.error !== null || base.restart?.fromError === true },
+                restarts: base.restarts + 1,
+            };
+        });
+        return true;
+    }, [identity]);
+    return {
+        error: current.error,
+        sourceState: current.sourceState,
+        pendingRestart: current.restart,
+        restarts: current.restarts,
+        reset,
+        update,
+        restart,
+    };
+}
+/**
+ * The subscribed hooks' result: the query's own result, with the listener's error and source
+ * state merged in. In subscribe mode `refetch()` re-opens the listener (clearing its error, with a
+ * fresh resubscribe ladder) and resolves once the re-opened listener delivers its first snapshot or
+ * surfaces its next error; until then the result reports fetching. A restart after a failure shows
+ * no data until that snapshot: the failed listener's last rows are not presented as current.
+ */
+export function useSubscribedResult(query, subscribe, enabled, status) {
+    const { error, sourceState, pendingRestart, restart } = status;
+    const waiters = useRef([]);
+    const latest = useRef(query);
+    const mounted = useRef(true);
+    const active = subscribe && enabled;
+    const refetch = useCallback((options) => {
+        // An unmounted hook, or a refetch captured under an identity the hook has left, re-opens
+        // nothing: it settles at once rather than waiting on a listener that will never report.
+        if (!active || !mounted.current)
+            return Promise.resolve(latest.current);
+        return new Promise((resolve, reject) => {
+            if (!restart()) {
+                resolve(latest.current);
+                return;
+            }
+            waiters.current.push({ resolve, reject, throwOnError: options?.throwOnError === true });
+        });
+    }, [active, restart]);
+    let result;
+    if (!subscribe) {
+        result = query;
+    }
+    else if (error) {
+        result = {
+            ...query,
+            data: undefined,
+            error,
+            isError: true,
+            isLoadingError: true,
+            isSuccess: false,
+            isPending: false,
+            isLoading: false,
+            status: 'error',
+            refetch,
+        };
+    }
+    else if (pendingRestart?.fromError) {
+        result = {
+            ...query,
+            data: undefined,
+            error: null,
+            isError: false,
+            isLoadingError: false,
+            isRefetchError: false,
+            isSuccess: false,
+            isPending: true,
+            isLoading: true,
+            isFetching: true,
+            isRefetching: false,
+            status: 'pending',
+            fetchStatus: 'fetching',
+            refetch,
+        };
+    }
+    else if (pendingRestart) {
+        result = {
+            ...query,
+            isFetching: true,
+            isLoading: query.isPending,
+            isRefetching: !query.isPending,
+            fetchStatus: 'fetching',
+            refetch,
+        };
+    }
+    else {
+        result = { ...query, refetch };
+    }
+    const restartOpen = pendingRestart !== null;
+    useEffect(() => {
+        latest.current = result;
+        if (restartOpen || waiters.current.length === 0)
+            return;
+        const settled = waiters.current;
+        waiters.current = [];
+        for (const waiter of settled) {
+            if (waiter.throwOnError && result.error)
+                waiter.reject(result.error);
+            else
+                waiter.resolve(result);
+        }
+    });
+    // A refetch still open when the hook unmounts resolves with the last result instead of hanging.
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            const settled = waiters.current;
+            waiters.current = [];
+            for (const waiter of settled)
+                waiter.resolve(latest.current);
+        };
+    }, []);
+    return { ...result, sourceState };
 }
 //# sourceMappingURL=subscription-status.js.map

package/dist/react/firestore/subscription-status.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscription-status.js","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAW9C;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAqB,GAAG,EAAE,CAAC,CAAC;QAC9D,QAAQ;QACR,KAAK,EAAE,IAAI;QACX,WAAW,EAAE,YAAY;KAC1B,CAAC,CAAC,CAAC;IAEJ,MAAM,OAAO,GACX,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;IAE/F,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,CAAC;IAClE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,KAAgE,EAAE,EAAE;QACnE,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YACjB,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACnF,CAAC","sourcesContent":["'use client';\n\nimport { useCallback, useState } from 'react';\nimport type { FirestoreSourceState } from '../../firestore/types.js';\n\ninterface SubscriptionStatus {\n  identity: string;\n  error: Error | null;\n  sourceState: FirestoreSourceState;\n}\n\ntype StatusPatch = Partial<Omit<SubscriptionStatus, 'identity'>>;\n\n/**\n * A realtime listener's source state and error, tagged to the subscription identity that\n * produced them. A new identity reads `connecting` with no error from its first render;\n * writes made for a retired identity are dropped once the new identity's listener has\n * started (it calls `reset`).\n */\nexport function useSubscriptionStatus(identity: string) {\n  const [status, setStatus] = useState<SubscriptionStatus>(() => ({\n    identity,\n    error: null,\n    sourceState: 'connecting',\n  }));\n\n  const current: SubscriptionStatus =\n    status.identity === identity ? status : { identity, error: null, sourceState: 'connecting' };\n\n  const reset = useCallback(() => {\n    setStatus({ identity, error: null, sourceState: 'connecting' });\n  }, [identity]);\n\n  const update = useCallback(\n    (patch: StatusPatch | ((prev: SubscriptionStatus) => StatusPatch)) => {\n      setStatus((prev) => {\n        if (prev.identity !== identity) return prev;\n        const next = typeof patch === 'function' ? patch(prev) : patch;\n        return { ...prev, ...next };\n      });\n    },\n    [identity],\n  );\n\n  return { error: current.error, sourceState: current.sourceState, reset, update };\n}\n"]}
+{"version":3,"file":"subscription-status.js","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAqBjE,SAAS,WAAW,CAAC,QAAgB;IACnC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAqB,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtF,MAAM,OAAO,GAAuB,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAElG,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CACjB,IAAI,CAAC,QAAQ,KAAK,QAAQ;YACxB,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE;YACrD,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAC1B,CAAC;IACJ,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,KAAgE,EAAE,EAAE;QACnE,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YACjB,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,6FAA6F;IAC7F,8FAA8F;IAC9F,MAAM,gBAAgB,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,SAAS,CAAC,GAAG,EAAE;QACb,gBAAgB,CAAC,OAAO,GAAG,QAAQ,CAAC;IACtC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,mGAAmG;IACnG,MAAM,OAAO,GAAG,WAAW,CAAC,GAAY,EAAE;QACxC,IAAI,gBAAgB,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACxD,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YACjB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YACvE,OAAO;gBACL,GAAG,IAAI;gBACP,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,YAAY;gBACzB,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,EAAE;gBAC/E,QAAQ,EAAE,IAAI,CAAC,QAAQ,GAAG,CAAC;aAC5B,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,cAAc,EAAE,OAAO,CAAC,OAAO;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK;QACL,MAAM;QACN,OAAO;KACR,CAAC;AACJ,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAmC,EACnC,SAAkB,EAClB,OAAgB,EAChB,MAA6B;IAE7B,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAyB,EAAE,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,KAA0C,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,SAAS,IAAI,OAAO,CAAC;IAEpC,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,OAAwB,EAA8C,EAAE;QACvE,yFAAyF;QACzF,wFAAwF;QACxF,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACxB,OAAO;YACT,CAAC;YACD,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,MAAM,EAAE,OAAO,CAAC,CAClB,CAAC;IAEF,IAAI,MAAoC,CAAC;IACzC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,GAAG,KAAK,CAAC;IACjB,CAAC;SAAM,IAAI,KAAK,EAAE,CAAC;QACjB,MAAM,GAAG;YACP,GAAG,KAAK;YACR,IAAI,EAAE,SAAS;YACf,KAAK;YACL,OAAO,EAAE,IAAI;YACb,cAAc,EAAE,IAAI;YACpB,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,OAAO;YACf,OAAO;SACwB,CAAC;IACpC,CAAC;SAAM,IAAI,cAAc,EAAE,SAAS,EAAE,CAAC;QACrC,MAAM,GAAG;YACP,GAAG,KAAK;YACR,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,KAAK;YACd,cAAc,EAAE,KAAK;YACrB,cAAc,EAAE,KAAK;YACrB,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,IAAI;YACf,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,UAAU;YACvB,OAAO;SACwB,CAAC;IACpC,CAAC;SAAM,IAAI,cAAc,EAAE,CAAC;QAC1B,MAAM,GAAG;YACP,GAAG,KAAK;YACR,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,YAAY,EAAE,CAAC,KAAK,CAAC,SAAS;YAC9B,WAAW,EAAE,UAAU;YACvB,OAAO;SACwB,CAAC;IACpC,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAkC,CAAC;IACjE,CAAC;IAED,MAAM,WAAW,GAAG,cAAc,KAAK,IAAI,CAAC;IAC5C,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,CAAC,OAAO,GAAG,MAA2C,CAAC;QAC7D,IAAI,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACxD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,OAAO,CAAC,OAAO,GAAG,EAAE,CAAC;QACrB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK;gBAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;;gBAChE,MAAM,CAAC,OAAO,CAAC,MAA2C,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,gGAAgG;IAChG,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;YACxB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;YAChC,OAAO,CAAC,OAAO,GAAG,EAAE,CAAC;YACrB,KAAK,MAAM,MAAM,IAAI,OAAO;gBAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/D,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,GAAG,MAAM,EAAE,WAAW,EAAmD,CAAC;AACrF,CAAC","sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\nimport type { QueryObserverResult, RefetchOptions, UseQueryResult } from '@tanstack/react-query';\nimport type { FirestoreSourceState, WithSourceState } from '../../firestore/types.js';\n\n/** A restart a subscribed result's `refetch()` asked for, open until the listener's first snapshot or its next error. */\ninterface PendingRestart {\n  /** The listener had failed: its last data is not shown as current while the restart is open. */\n  fromError: boolean;\n}\n\ninterface SubscriptionStatus {\n  identity: string;\n  error: Error | null;\n  sourceState: FirestoreSourceState;\n  restart: PendingRestart | null;\n  /** Bumped by every restart; the listener effect depends on it, so a bump re-opens the listener. */\n  restarts: number;\n}\n\ntype StatusPatch = Partial<Omit<SubscriptionStatus, 'identity' | 'restarts'>>;\n\nfunction freshStatus(identity: string): SubscriptionStatus {\n  return { identity, error: null, sourceState: 'connecting', restart: null, restarts: 0 };\n}\n\n/**\n * A realtime listener's source state and error, tagged to the subscription identity that\n * produced them. A new identity reads `connecting` with no error from its first render;\n * writes made for a retired identity are dropped once the new identity's listener has\n * started (it calls `reset`).\n *\n * `restart()` clears the error and bumps `restarts`; the listener effect re-opens on the bump,\n * and its first snapshot or next surfaced error ends the restart (`settled` in the patch).\n */\nexport function useSubscriptionStatus(identity: string) {\n  const [status, setStatus] = useState<SubscriptionStatus>(() => freshStatus(identity));\n\n  const current: SubscriptionStatus = status.identity === identity ? status : freshStatus(identity);\n\n  const reset = useCallback(() => {\n    setStatus((prev) =>\n      prev.identity === identity\n        ? { ...prev, error: null, sourceState: 'connecting' }\n        : freshStatus(identity),\n    );\n  }, [identity]);\n\n  const update = useCallback(\n    (patch: StatusPatch | ((prev: SubscriptionStatus) => StatusPatch)) => {\n      setStatus((prev) => {\n        if (prev.identity !== identity) return prev;\n        const next = typeof patch === 'function' ? patch(prev) : patch;\n        return { ...prev, ...next };\n      });\n    },\n    [identity],\n  );\n\n  // The identity the hook renders now. A `restart` captured under an earlier identity must not\n  // touch the current one's status, or every write the current listener makes would be dropped.\n  const renderedIdentity = useRef(identity);\n  useEffect(() => {\n    renderedIdentity.current = identity;\n  }, [identity]);\n\n  /** Re-opens the listener; false (and nothing changes) when this identity is no longer rendered. */\n  const restart = useCallback((): boolean => {\n    if (renderedIdentity.current !== identity) return false;\n    setStatus((prev) => {\n      const base = prev.identity === identity ? prev : freshStatus(identity);\n      return {\n        ...base,\n        error: null,\n        sourceState: 'connecting',\n        restart: { fromError: base.error !== null || base.restart?.fromError === true },\n        restarts: base.restarts + 1,\n      };\n    });\n    return true;\n  }, [identity]);\n\n  return {\n    error: current.error,\n    sourceState: current.sourceState,\n    pendingRestart: current.restart,\n    restarts: current.restarts,\n    reset,\n    update,\n    restart,\n  };\n}\n\ntype SubscriptionStatusApi = ReturnType<typeof useSubscriptionStatus>;\n\ninterface RefetchWaiter<TData> {\n  resolve: (result: QueryObserverResult<TData, Error>) => void;\n  reject: (error: Error) => void;\n  throwOnError: boolean;\n}\n\n/**\n * The subscribed hooks' result: the query's own result, with the listener's error and source\n * state merged in. In subscribe mode `refetch()` re-opens the listener (clearing its error, with a\n * fresh resubscribe ladder) and resolves once the re-opened listener delivers its first snapshot or\n * surfaces its next error; until then the result reports fetching. A restart after a failure shows\n * no data until that snapshot: the failed listener's last rows are not presented as current.\n */\nexport function useSubscribedResult<TData>(\n  query: UseQueryResult<TData, Error>,\n  subscribe: boolean,\n  enabled: boolean,\n  status: SubscriptionStatusApi,\n): WithSourceState<UseQueryResult<TData, Error>> {\n  const { error, sourceState, pendingRestart, restart } = status;\n  const waiters = useRef<RefetchWaiter<TData>[]>([]);\n  const latest = useRef(query as QueryObserverResult<TData, Error>);\n  const mounted = useRef(true);\n  const active = subscribe && enabled;\n\n  const refetch = useCallback(\n    (options?: RefetchOptions): Promise<QueryObserverResult<TData, Error>> => {\n      // An unmounted hook, or a refetch captured under an identity the hook has left, re-opens\n      // nothing: it settles at once rather than waiting on a listener that will never report.\n      if (!active || !mounted.current) return Promise.resolve(latest.current);\n      return new Promise((resolve, reject) => {\n        if (!restart()) {\n          resolve(latest.current);\n          return;\n        }\n        waiters.current.push({ resolve, reject, throwOnError: options?.throwOnError === true });\n      });\n    },\n    [active, restart],\n  );\n\n  let result: UseQueryResult<TData, Error>;\n  if (!subscribe) {\n    result = query;\n  } else if (error) {\n    result = {\n      ...query,\n      data: undefined,\n      error,\n      isError: true,\n      isLoadingError: true,\n      isSuccess: false,\n      isPending: false,\n      isLoading: false,\n      status: 'error',\n      refetch,\n    } as UseQueryResult<TData, Error>;\n  } else if (pendingRestart?.fromError) {\n    result = {\n      ...query,\n      data: undefined,\n      error: null,\n      isError: false,\n      isLoadingError: false,\n      isRefetchError: false,\n      isSuccess: false,\n      isPending: true,\n      isLoading: true,\n      isFetching: true,\n      isRefetching: false,\n      status: 'pending',\n      fetchStatus: 'fetching',\n      refetch,\n    } as UseQueryResult<TData, Error>;\n  } else if (pendingRestart) {\n    result = {\n      ...query,\n      isFetching: true,\n      isLoading: query.isPending,\n      isRefetching: !query.isPending,\n      fetchStatus: 'fetching',\n      refetch,\n    } as UseQueryResult<TData, Error>;\n  } else {\n    result = { ...query, refetch } as UseQueryResult<TData, Error>;\n  }\n\n  const restartOpen = pendingRestart !== null;\n  useEffect(() => {\n    latest.current = result as QueryObserverResult<TData, Error>;\n    if (restartOpen || waiters.current.length === 0) return;\n    const settled = waiters.current;\n    waiters.current = [];\n    for (const waiter of settled) {\n      if (waiter.throwOnError && result.error) waiter.reject(result.error);\n      else waiter.resolve(result as QueryObserverResult<TData, Error>);\n    }\n  });\n\n  // A refetch still open when the hook unmounts resolves with the last result instead of hanging.\n  useEffect(() => {\n    mounted.current = true;\n    return () => {\n      mounted.current = false;\n      const settled = waiters.current;\n      waiters.current = [];\n      for (const waiter of settled) waiter.resolve(latest.current);\n    };\n  }, []);\n\n  return { ...result, sourceState } as WithSourceState<UseQueryResult<TData, Error>>;\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-collection.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-collection.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EACV,0BAA0B,EAC1B,MAAM,EACN,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAC5E,cAAc,EACd,QAAQ,EACR,WAAgB,EAChB,OAAc,EACd,SAAiB,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAiIrF"}
+{"version":3,"file":"use-firestore-collection.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-collection.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EACV,0BAA0B,EAC1B,MAAM,EACN,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAC5E,cAAc,EACd,QAAQ,EACR,WAAgB,EAChB,OAAc,EACd,SAAiB,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACP,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CA6GrF"}

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

@@ -2,9 +2,9 @@
 import { useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { collection, query, getDocs, onSnapshot, } from 'firebase/firestore';
-import { useFirestoreDb } from './context.js';
+import { useFirestoreDb, useListenerErrorReporter } from './context.js';
 import { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';
-import { useSubscriptionStatus } from './subscription-status.js';
+import { useSubscribedResult, useSubscriptionStatus } from './subscription-status.js';
 /**
  * Fetch all documents from a Firestore collection with optional realtime updates.
  * Use this for small collections where you need all documents at once.
@@ -28,13 +28,15 @@ import { useSubscriptionStatus } from './subscription-status.js';
 export function useFirestoreCollection({ collectionPath, queryKey, constraints = [], enabled = true, subscribe = false, staleTime, gcTime, select, }) {
     const db = useFirestoreDb();
     const queryClient = useQueryClient();
+    const reportListenerError = useListenerErrorReporter();
     // STABILIZE DEPENDENCIES:
     // We stringify these because [where('a', '==', 'b')] !== [where('a', '==', 'b')] in JS.
     const constraintsMemo = JSON.stringify(constraints);
     const queryKeyMemo = JSON.stringify(queryKey);
     // Listener errors can't surface through useQuery (the queryFn is disabled while
     // subscribed), so they're tracked per subscription identity and merged into the result.
-    const { error: subscriptionError, sourceState, reset: resetStatus, update: updateStatus, } = useSubscriptionStatus(JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe]));
+    const subscription = useSubscriptionStatus(JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe]));
+    const { reset: resetStatus, update: updateStatus, restarts } = subscription;
     useEffect(() => {
         if (!subscribe || !enabled)
             return;
@@ -56,7 +58,7 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
                 : collectionRef;
             currentUnsubscribe = onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
                 attempt = 0;
-                updateStatus({ error: null });
+                updateStatus({ error: null, restart: null });
                 const items = snapshot.docs.map((docSnap) => {
                     const rawData = docSnap.data();
                     const dataWithId = { id: docSnap.id, ...rawData };
@@ -79,9 +81,9 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
                     retryTimer = setTimeout(start, delay);
                     return;
                 }
-                console.error('[useFirestoreCollection] Subscription error:', error);
-                updateStatus({ error, sourceState: 'error' });
+                updateStatus({ error, sourceState: 'error', restart: null });
                 queryClient.setQueryData(queryKey, undefined);
+                reportListenerError(error, { hook: 'useFirestoreCollection', queryKey, path: collectionPath });
             });
         };
         start();
@@ -94,7 +96,7 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
         // queryKey & constraints are tracked via their stringified forms above; select is intentionally
         // excluded so an inline caller function doesn't force a re-subscribe on every render.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [db, collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe, queryClient, resetStatus, updateStatus]);
+    }, [db, collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe, restarts, queryClient, resetStatus, updateStatus, reportListenerError]);
     const queryResult = useQuery({
         queryKey,
         queryFn: async () => {
@@ -115,22 +117,6 @@ export function useFirestoreCollection({ collectionPath, queryKey, constraints =
         staleTime: subscribe ? Infinity : staleTime,
         gcTime,
     });
-    // Merge a listener error into the result so subscribed consumers see a truthful
-    // isError/error/status instead of a forever-pending disabled query.
-    if (subscribe && subscriptionError) {
-        return {
-            ...queryResult,
-            data: undefined,
-            error: subscriptionError,
-            isError: true,
-            isLoadingError: true,
-            isSuccess: false,
-            isPending: false,
-            isLoading: false,
-            status: 'error',
-            sourceState,
-        };
-    }
-    return { ...queryResult, sourceState };
+    return useSubscribedResult(queryResult, subscribe, enabled, subscription);
 }
 //# sourceMappingURL=use-firestore-collection.js.map

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":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AACtF,OAAO,EACL,UAAU,EACV,KAAK,EACL,OAAO,EACP,UAAU,GAEX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAOjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CAAwC,EAC5E,cAAc,EACd,QAAQ,EACR,WAAW,GAAG,EAAE,EAChB,OAAO,GAAG,IAAI,EACd,SAAS,GAAG,KAAK,EACjB,SAAS,EACT,MAAM,EACN,MAAM,GACwB;IAC9B,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IAErC,0BAA0B;IAC1B,wFAAwF;IACxF,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE9C,gFAAgF;IAChF,wFAAwF;IACxF,MAAM,EACJ,KAAK,EAAE,iBAAiB,EACxB,WAAW,EACX,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,YAAY,GACrB,GAAG,qBAAqB,CACvB,IAAI,CAAC,SAAS,CAAC,CAAC,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CACpF,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,SAAS,IAAI,CAAC,OAAO;YAAE,OAAO;QAEnC,WAAW,EAAE,CAAC;QAEd,kFAAkF;QAClF,qFAAqF;QACrF,qFAAqF;QACrF,uEAAuE;QACvE,IAAI,kBAAkB,GAAwB,IAAI,CAAC;QACnD,IAAI,UAAU,GAAyC,IAAI,CAAC;QAC5D,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,IAAI,QAAQ;gBAAE,OAAO;YACrB,MAAM,aAAa,GAAG,UAAU,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;YACrD,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC;gBAC9B,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC;gBACtC,CAAC,CAAC,aAAa,CAAC;YAElB,kBAAkB,GAAG,UAAU,CAC7B,CAAC,EACD,EAAE,sBAAsB,EAAE,IAAI,EAAE,EAChC,CAAC,QAAQ,EAAE,EAAE;gBACX,OAAO,GAAG,CAAC,CAAC;gBACZ,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;oBAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;oBAC/B,MAAM,UAAU,GAAG,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;oBAClD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;oBACtD,OAAO,IAAiB,CAAC;gBAC3B,CAAC,CAAC,CAAC;gBACH,WAAW,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAC1C,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,EAAE,SAAS,IAAI,KAAK,CAAC;gBACxD,YAAY,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACjI,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;gBACR,6EAA6E;gBAC7E,8EAA8E;gBAC9E,iEAAiE;gBACjE,IAAI,uBAAuB,CAAC,KAAK,CAAC,IAAI,OAAO,GAAG,qBAAqB,CAAC,MAAM,EAAE,CAAC;oBAC7E,kBAAkB,EAAE,EAAE,CAAC;oBACvB,kBAAkB,GAAG,IAAI,CAAC;oBAC1B,MAAM,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;oBAC7C,OAAO,IAAI,CAAC,CAAC;oBACb,YAAY,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,CAAC;oBAC5C,UAAU,GAAG,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;oBACtC,OAAO;gBACT,CAAC;gBACD,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,KAAK,CAAC,CAAC;gBACrE,YAAY,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC9C,WAAW,CAAC,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAChD,CAAC,CACF,CAAC;QACJ,CAAC,CAAC;QAEF,KAAK,EAAE,CAAC;QAER,OAAO,GAAG,EAAE;YACV,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,UAAU;gBAAE,YAAY,CAAC,UAAU,CAAC,CAAC;YACzC,kBAAkB,EAAE,EAAE,CAAC;QACzB,CAAC,CAAC;QACF,gGAAgG;QAChG,sFAAsF;QACtF,uDAAuD;IACzD,CAAC,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IAEpH,MAAM,WAAW,GAAG,QAAQ,CAAC;QAC3B,QAAQ;QACR,OAAO,EAAE,KAAK,IAA0B,EAAE;YACxC,MAAM,aAAa,GAAG,UAAU,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;YACrD,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC;gBAC9B,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC;gBACtC,CAAC,CAAC,aAAa,CAAC;YAElB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;YAClC,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;gBACnC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;gBAC/B,wEAAwE;gBACxE,MAAM,UAAU,GAAG,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;gBAClD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;gBACtD,OAAO,IAAiB,CAAC;YAC3B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,OAAO,IAAI,CAAC,SAAS;QAC9B,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QAC3C,MAAM;KACP,CAAC,CAAC;IAEH,gFAAgF;IAChF,oEAAoE;IACpE,IAAI,SAAS,IAAI,iBAAiB,EAAE,CAAC;QACnC,OAAO;YACL,GAAG,WAAW;YACd,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,iBAAiB;YACxB,OAAO,EAAE,IAAI;YACb,cAAc,EAAE,IAAI;YACpB,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,KAAK;YAChB,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,OAAO;YACf,WAAW;SAC2C,CAAC;IAC3D,CAAC;IAED,OAAO,EAAE,GAAG,WAAW,EAAE,WAAW,EAAyD,CAAC;AAChG,CAAC","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"]}
+{"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, useListenerErrorReporter } from './context.js';\nimport { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';\nimport { useSubscribedResult, 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  const reportListenerError = useListenerErrorReporter();\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 subscription = useSubscriptionStatus(\n    JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, enabled, subscribe]),\n  );\n  const { reset: resetStatus, update: updateStatus, restarts } = subscription;\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, restart: 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          updateStatus({ error, sourceState: 'error', restart: null });\n          queryClient.setQueryData(queryKey, undefined);\n          reportListenerError(error, { hook: 'useFirestoreCollection', queryKey, path: collectionPath });\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, restarts, queryClient, resetStatus, updateStatus, reportListenerError]);\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  return useSubscribedResult(queryResult, subscribe, enabled, subscription);\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;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"}
+{"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,CAqGnF"}

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

@@ -2,9 +2,9 @@
 import { useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { doc, getDoc, onSnapshot } from 'firebase/firestore';
-import { useFirestoreDb } from './context.js';
+import { useFirestoreDb, useListenerErrorReporter } from './context.js';
 import { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';
-import { useSubscriptionStatus } from './subscription-status.js';
+import { useSubscribedResult, useSubscriptionStatus } from './subscription-status.js';
 /**
  * Fetch a single Firestore document with optional realtime updates.
  * * @example
@@ -31,10 +31,12 @@ import { useSubscriptionStatus } from './subscription-status.js';
 export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe = false, staleTime, gcTime, select, }) {
     const db = useFirestoreDb();
     const queryClient = useQueryClient();
+    const reportListenerError = useListenerErrorReporter();
     const queryKeyMemo = JSON.stringify(queryKey);
     // Listener errors can't surface through useQuery (the queryFn is disabled while
     // 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]));
+    const subscription = useSubscriptionStatus(JSON.stringify([docPath, queryKeyMemo, enabled, subscribe]));
+    const { reset: resetStatus, update: updateStatus, restarts } = subscription;
     // Set up realtime subscription
     useEffect(() => {
         if (!subscribe || !enabled)
@@ -54,7 +56,7 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
             const docRef = doc(db, docPath);
             currentUnsubscribe = onSnapshot(docRef, { includeMetadataChanges: true }, (snapshot) => {
                 attempt = 0;
-                updateStatus({ error: null });
+                updateStatus({ error: null, restart: null });
                 if (snapshot.exists()) {
                     const rawData = snapshot.data();
                     // Include id in data passed to select, so it can be renamed/transformed
@@ -80,9 +82,9 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
                     retryTimer = setTimeout(start, delay);
                     return;
                 }
-                console.error('[useFirestoreDoc] Subscription error:', error);
-                updateStatus({ error, sourceState: 'error' });
+                updateStatus({ error, sourceState: 'error', restart: null });
                 queryClient.setQueryData(queryKey, undefined);
+                reportListenerError(error, { hook: 'useFirestoreDoc', queryKey, path: docPath });
             });
         };
         start();
@@ -95,7 +97,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, resetStatus, updateStatus]);
+    }, [db, docPath, queryKeyMemo, enabled, subscribe, restarts, queryClient, resetStatus, updateStatus, reportListenerError]);
     const query = useQuery({
         queryKey,
         queryFn: async () => {
@@ -114,22 +116,6 @@ export function useFirestoreDoc({ docPath, queryKey, enabled = true, subscribe =
         staleTime: subscribe ? Infinity : staleTime, // Realtime data is always fresh
         gcTime,
     });
-    // Merge a listener error into the result so subscribed consumers see a truthful
-    // isError/error/status instead of a forever-pending disabled query.
-    if (subscribe && subscriptionError) {
-        return {
-            ...query,
-            data: undefined,
-            error: subscriptionError,
-            isError: true,
-            isLoadingError: true,
-            isSuccess: false,
-            isPending: false,
-            isLoading: false,
-            status: 'error',
-            sourceState,
-        };
-    }
-    return { ...query, sourceState };
+    return useSubscribedResult(query, subscribe, enabled, subscription);
 }
 //# sourceMappingURL=use-firestore-doc.js.map

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 } 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"]}
+{"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, useListenerErrorReporter } from './context.js';\nimport { RESUBSCRIBE_DELAYS_MS, isPermissionDeniedError } from './resubscribe.js';\nimport { useSubscribedResult, 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 reportListenerError = useListenerErrorReporter();\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 subscription = useSubscriptionStatus(JSON.stringify([docPath, queryKeyMemo, enabled, subscribe]));\n  const { reset: resetStatus, update: updateStatus, restarts } = subscription;\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, restart: 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          updateStatus({ error, sourceState: 'error', restart: null });\n          queryClient.setQueryData(queryKey, undefined);\n          reportListenerError(error, { hook: 'useFirestoreDoc', queryKey, path: docPath });\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, restarts, queryClient, resetStatus, updateStatus, reportListenerError]);\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  return useSubscribedResult(query, subscribe, enabled, subscription);\n}\n"]}

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

@@ -1,7 +1,7 @@
 import { type DocumentData } from 'firebase/firestore';
 import type { FirestoreLiveInfiniteOptions, FirestoreSourceState } from '../../firestore/types.js';
 export interface FirestoreLiveInfiniteResult<T> {
-    /** The current subscription identity's rows — live set plus loaded older pages, sorted per `sort`. */
+    /** The current subscription identity's rows — live set plus loaded older pages, ordered per `sort`. */
     items: T[];
     /** True until the current identity's first snapshot arrives, unless its listener has failed. */
     isInitialLoading: boolean;
@@ -9,7 +9,7 @@ export interface FirestoreLiveInfiniteResult<T> {
     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`. */
+    /** Load the next older page; nothing older is read until this is called. Never rejects — a failed read lands in `olderError`. */
     fetchOlder: () => Promise<void>;
     /** Whether older rows exist that are not loaded yet (a one-doc look-ahead, never a full-page guess). */
     hasOlder: boolean;
@@ -21,7 +21,7 @@ export interface FirestoreLiveInfiniteResult<T> {
     retry: () => void;
 }
 /**
- * A live list (newest rows realtime) with older rows paged in on demand, merged into
+ * A live list (newest rows realtime) with older rows paged in on request, merged into
  * one ordered list.
  *
  * Until the first server-confirmed snapshot that has rows, the listener reads the newest
@@ -30,7 +30,10 @@ export interface FirestoreLiveInfiniteResult<T> {
  * 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.
+ * exactly when nothing older exists. No older page is read until `fetchOlder` asks for one.
+ *
+ * Both reads arrive newest first and meet at the anchor, so the merged list is their
+ * concatenation: a snapshot never re-sorts the rows already loaded.
  *
  * Everything read is tagged to its subscription identity (path, key, ordering,
  * constraints, page size, enabled): a new identity renders empty and connecting in its
@@ -42,5 +45,5 @@ export interface FirestoreLiveInfiniteResult<T> {
  */
 export declare function useFirestoreLiveInfinite<T = DocumentData & {
     id: string;
-}>({ collectionPath, queryKey, orderByField, constraints, pageSize: requestedPageSize, enabled, select, getSortValue, sort, }: FirestoreLiveInfiniteOptions<T>): FirestoreLiveInfiniteResult<T>;
+}>({ collectionPath, queryKey, orderByField, constraints, pageSize: requestedPageSize, enabled, select, sort, staleTime, gcTime, }: FirestoreLiveInfiniteOptions<T>): FirestoreLiveInfiniteResult<T>;
 //# sourceMappingURL=use-firestore-live-infinite.d.ts.map

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,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"}
+{"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,uGAAuG;IACvG,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,iIAAiI;IACjI,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,IAAY,EACZ,SAAS,EACT,MAAM,GACP,EAAE,4BAA4B,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAwPlE"}