@ttt-productions/query-core 0.14.22 → 0.14.24

package/dist/react/firestore/use-firestore-paginated.d.ts

@@ -2,10 +2,6 @@ import { type UseQueryResult } from '@tanstack/react-query';
 import { type DocumentData } from 'firebase/firestore';
 import type { WithId } from '../../firestore/types.js';
 import type { FirestorePaginatedOptions, PaginatedPage } from './types.js';
-/**
- * Return type for useFirestorePaginated hook. `data` is the displayed page's rows; the
- * page's cache entry (rows, cursor, has-more) lives at `paginatedPageKey(queryKey, page)`.
- */
 export type UseFirestorePaginatedResult<T> = Omit<UseQueryResult<PaginatedPage<WithId<T>>, Error>, 'data'> & {
     data: WithId<T>[] | undefined;
     page: number;
@@ -16,31 +12,5 @@ export type UseFirestorePaginatedResult<T> = Omit<UseQueryResult<PaginatedPage<W
     nextPage: () => void;
     prevPage: () => void;
 };
-/**
- * Page-based pagination for Firestore collections (Previous / Next, one page at a time).
- *
- * Each page is ONE cache entry at `[...queryKey, 'page', n]` holding its rows, its last
- * row as the next page's cursor, and whether a further page exists — read with a one-row
- * look-ahead, so `hasNextPage` is false exactly when nothing follows the displayed page.
- * Page n reads page n-1's cursor from the cache (loading the chain first if it is
- * missing) and records it as `after`. A displayed page whose `after` no longer matches
- * page n-1's cached cursor (page n-1 was re-read and its last row moved) is re-read before
- * it is shown, so every instance, remount, and refetch of a key agrees on where a page
- * starts. The page number belongs to the query identity (path, key, constraints, page
- * size): a new identity renders `initialPage` in its first render.
- *
- * `queryKey` must encode everything that changes the read — path, filters, ordering, and
- * page size — because the cache entries are shared by key.
- *
- * @example
- * ```tsx
- * const { data, page, nextPage, prevPage, hasNextPage, hasPrevPage } = useFirestorePaginated<Task>({
- *   collectionPath: 'tasks',
- *   queryKey: ['tasks', 'active', { pageSize: 10 }],
- *   constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],
- *   pageSize: 10,
- * });
- * ```
- */
 export declare function useFirestorePaginated<T extends DocumentData = DocumentData>({ collectionPath, queryKey, constraints, pageSize, initialPage, enabled, staleTime, gcTime, refetchInterval, select, }: FirestorePaginatedOptions<T>): UseFirestorePaginatedResult<T>;
 //# sourceMappingURL=use-firestore-paginated.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-paginated.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-paginated.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAML,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3E;;;GAGG;AACH,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI,IAAI,CAC/C,cAAc,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAC/C,MAAM,CACP,GAAG;IACF,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAC3E,cAAc,EACd,QAAQ,EACR,WAAgB,EAChB,QAA4B,EAC5B,WAAe,EACf,OAAc,EACd,SAAS,EACT,MAAM,EACN,eAAe,EACf,MAAM,GACP,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAsH/D"}
+{"version":3,"file":"use-firestore-paginated.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-paginated.ts"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAML,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3E,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI,IAAI,CAC/C,cAAc,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAC/C,MAAM,CACP,GAAG;IACF,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAC3E,cAAc,EACd,QAAQ,EACR,WAAgB,EAChB,QAA4B,EAC5B,WAAe,EACf,OAAc,EACd,SAAS,EACT,MAAM,EACN,eAAe,EACf,MAAM,GACP,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAiH/D"}

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

@@ -5,32 +5,6 @@ import { collection, query, getDocs, limit, startAfter, } from 'firebase/firesto
 import { useFirestoreDb } from './context.js';
 import { paginatedPageKey } from '../cache-helpers.js';
 const DEFAULT_PAGE_SIZE = 10;
-/**
- * Page-based pagination for Firestore collections (Previous / Next, one page at a time).
- *
- * Each page is ONE cache entry at `[...queryKey, 'page', n]` holding its rows, its last
- * row as the next page's cursor, and whether a further page exists — read with a one-row
- * look-ahead, so `hasNextPage` is false exactly when nothing follows the displayed page.
- * Page n reads page n-1's cursor from the cache (loading the chain first if it is
- * missing) and records it as `after`. A displayed page whose `after` no longer matches
- * page n-1's cached cursor (page n-1 was re-read and its last row moved) is re-read before
- * it is shown, so every instance, remount, and refetch of a key agrees on where a page
- * starts. The page number belongs to the query identity (path, key, constraints, page
- * size): a new identity renders `initialPage` in its first render.
- *
- * `queryKey` must encode everything that changes the read — path, filters, ordering, and
- * page size — because the cache entries are shared by key.
- *
- * @example
- * ```tsx
- * const { data, page, nextPage, prevPage, hasNextPage, hasPrevPage } = useFirestorePaginated<Task>({
- *   collectionPath: 'tasks',
- *   queryKey: ['tasks', 'active', { pageSize: 10 }],
- *   constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],
- *   pageSize: 10,
- * });
- * ```
- */
 export function useFirestorePaginated({ collectionPath, queryKey, constraints = [], pageSize = DEFAULT_PAGE_SIZE, initialPage = 1, enabled = true, staleTime, gcTime, refetchInterval, select, }) {
     const db = useFirestoreDb();
     const queryClient = useQueryClient();
@@ -68,8 +42,7 @@ export function useFirestorePaginated({ collectionPath, queryKey, constraints =
             after: cursor?.id ?? null,
         };
     }, 
-    // queryKey and constraints are captured through their serialized identity.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- queryKey and constraints are captured through their serialized identity
     [db, queryClient, identity, selectRef]);
     const queryResult = useQuery({
         queryKey: paginatedPageKey(queryKey, page),
@@ -79,9 +52,6 @@ export function useFirestorePaginated({ collectionPath, queryKey, constraints =
         gcTime,
         refetchInterval,
     });
-    // The page before the displayed one, observed from the cache only (never fetched here).
-    // When it is re-read and its last row moves, the displayed entry no longer starts where the
-    // chain says it must: it is re-read before it is shown as current.
     const previousPage = useQuery({
         queryKey: paginatedPageKey(queryKey, Math.max(1, page - 1)),
         queryFn: () => fetchPage(Math.max(1, page - 1)),
@@ -112,8 +82,7 @@ export function useFirestorePaginated({ collectionPath, queryKey, constraints =
             return;
         setPageState({ identity, page: next });
     }, 
-    // queryKey is captured through its serialized identity.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- queryKey is captured through its serialized identity
     [page, hasNextPage, identity, queryClient]);
     const nextPage = useCallback(() => setPage(page + 1), [page, setPage]);
     const prevPage = useCallback(() => setPage(page - 1), [page, setPage]);

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

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-paginated.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-paginated.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useState, useCallback, useEffect, useRef } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  query,\n  getDocs,\n  limit,\n  startAfter,\n  type DocumentData,\n  type DocumentSnapshot,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { paginatedPageKey } from '../cache-helpers.js';\nimport type { WithId } from '../../firestore/types.js';\nimport type { FirestorePaginatedOptions, PaginatedPage } from './types.js';\n\nconst DEFAULT_PAGE_SIZE = 10;\n\n/**\n * Return type for useFirestorePaginated hook. `data` is the displayed page's rows; the\n * page's cache entry (rows, cursor, has-more) lives at `paginatedPageKey(queryKey, page)`.\n */\nexport type UseFirestorePaginatedResult<T> = Omit<\n  UseQueryResult<PaginatedPage<WithId<T>>, Error>,\n  'data'\n> & {\n  data: WithId<T>[] | undefined;\n  page: number;\n  pageSize: number;\n  hasNextPage: boolean;\n  hasPrevPage: boolean;\n  setPage: (page: number) => void;\n  nextPage: () => void;\n  prevPage: () => void;\n};\n\n/**\n * Page-based pagination for Firestore collections (Previous / Next, one page at a time).\n *\n * Each page is ONE cache entry at `[...queryKey, 'page', n]` holding its rows, its last\n * row as the next page's cursor, and whether a further page exists — read with a one-row\n * look-ahead, so `hasNextPage` is false exactly when nothing follows the displayed page.\n * Page n reads page n-1's cursor from the cache (loading the chain first if it is\n * missing) and records it as `after`. A displayed page whose `after` no longer matches\n * page n-1's cached cursor (page n-1 was re-read and its last row moved) is re-read before\n * it is shown, so every instance, remount, and refetch of a key agrees on where a page\n * starts. The page number belongs to the query identity (path, key, constraints, page\n * size): a new identity renders `initialPage` in its first render.\n *\n * `queryKey` must encode everything that changes the read — path, filters, ordering, and\n * page size — because the cache entries are shared by key.\n *\n * @example\n * ```tsx\n * const { data, page, nextPage, prevPage, hasNextPage, hasPrevPage } = useFirestorePaginated<Task>({\n *   collectionPath: 'tasks',\n *   queryKey: ['tasks', 'active', { pageSize: 10 }],\n *   constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],\n *   pageSize: 10,\n * });\n * ```\n */\nexport function useFirestorePaginated<T extends DocumentData = DocumentData>({\n  collectionPath,\n  queryKey,\n  constraints = [],\n  pageSize = DEFAULT_PAGE_SIZE,\n  initialPage = 1,\n  enabled = true,\n  staleTime,\n  gcTime,\n  refetchInterval,\n  select,\n}: FirestorePaginatedOptions<T>): UseFirestorePaginatedResult<T> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n\n  const queryKeyMemo = JSON.stringify(queryKey);\n  const constraintsMemo = JSON.stringify(constraints);\n  const identity = JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, pageSize]);\n  const firstPage = Math.max(1, Math.floor(initialPage));\n\n  const [pageState, setPageState] = useState(() => ({ identity, page: firstPage }));\n  const page = pageState.identity === identity ? pageState.page : firstPage;\n\n  const selectRef = useRef(select);\n  selectRef.current = select;\n\n  const fetchPage = useCallback(\n    async (n: number): Promise<PaginatedPage<WithId<T>>> => {\n      let cursor: DocumentSnapshot | null = null;\n      if (n > 1) {\n        const previous = await queryClient.ensureQueryData<PaginatedPage<WithId<T>>>({\n          queryKey: paginatedPageKey(queryKey, n - 1),\n          queryFn: () => fetchPage(n - 1),\n        });\n        if (!previous.hasMore || !previous.cursor) {\n          return { items: [], cursor: null, hasMore: false, after: previous.cursor?.id ?? null };\n        }\n        cursor = previous.cursor;\n      }\n      const q = query(\n        collection(db, collectionPath),\n        ...constraints,\n        ...(cursor ? [startAfter(cursor)] : []),\n        limit(pageSize + 1),\n      );\n      const snapshot = await getDocs(q);\n      const pageDocs = snapshot.docs.slice(0, pageSize);\n      return {\n        items: pageDocs.map((docSnap) => {\n          const dataWithId = { id: docSnap.id, ...docSnap.data() };\n          const mapped = selectRef.current ? selectRef.current(dataWithId) : dataWithId;\n          return mapped as WithId<T>;\n        }),\n        cursor: pageDocs[pageDocs.length - 1] ?? null,\n        hasMore: snapshot.docs.length > pageSize,\n        after: cursor?.id ?? null,\n      };\n    },\n    // queryKey and constraints are captured through their serialized identity.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [db, queryClient, identity, selectRef],\n  );\n\n  const queryResult = useQuery({\n    queryKey: paginatedPageKey(queryKey, page),\n    queryFn: () => fetchPage(page),\n    enabled,\n    staleTime,\n    gcTime,\n    refetchInterval,\n  });\n\n  // The page before the displayed one, observed from the cache only (never fetched here).\n  // When it is re-read and its last row moves, the displayed entry no longer starts where the\n  // chain says it must: it is re-read before it is shown as current.\n  const previousPage = useQuery({\n    queryKey: paginatedPageKey(queryKey, Math.max(1, page - 1)),\n    queryFn: () => fetchPage(Math.max(1, page - 1)),\n    enabled: false,\n  });\n  const cachedEntry = queryResult.data;\n  const outOfChain =\n    page > 1 &&\n    cachedEntry !== undefined &&\n    (previousPage.data === undefined ||\n      cachedEntry.after !== (previousPage.data.cursor?.id ?? null));\n  const { refetch, isFetching } = queryResult;\n  useEffect(() => {\n    if (enabled && outOfChain && !isFetching) void refetch();\n  }, [enabled, outOfChain, isFetching, refetch]);\n\n  const entry = outOfChain ? undefined : cachedEntry;\n  const hasNextPage = Boolean(entry?.hasMore && entry.cursor);\n\n  const setPage = useCallback(\n    (target: number) => {\n      const next = Math.floor(target);\n      if (next < 1 || next === page) return;\n      if (next > page + 1) {\n        const before = queryClient.getQueryData<PaginatedPage<unknown>>(\n          paginatedPageKey(queryKey, next - 1),\n        );\n        if (!before?.hasMore) return;\n      }\n      if (next === page + 1 && !hasNextPage) return;\n      setPageState({ identity, page: next });\n    },\n    // queryKey is captured through its serialized identity.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [page, hasNextPage, identity, queryClient],\n  );\n\n  const nextPage = useCallback(() => setPage(page + 1), [page, setPage]);\n  const prevPage = useCallback(() => setPage(page - 1), [page, setPage]);\n\n  return {\n    ...queryResult,\n    ...(outOfChain\n      ? { isLoading: true, isPending: true, isSuccess: false, status: 'pending' as const }\n      : {}),\n    data: entry?.items,\n    page,\n    pageSize,\n    hasNextPage,\n    hasPrevPage: page > 1,\n    setPage,\n    nextPage,\n    prevPage,\n  } as UseFirestorePaginatedResult<T>;\n}\n"]}
+{"version":3,"file":"use-firestore-paginated.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-paginated.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useState, useCallback, useEffect, useRef } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  query,\n  getDocs,\n  limit,\n  startAfter,\n  type DocumentData,\n  type DocumentSnapshot,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { paginatedPageKey } from '../cache-helpers.js';\nimport type { WithId } from '../../firestore/types.js';\nimport type { FirestorePaginatedOptions, PaginatedPage } from './types.js';\n\nconst DEFAULT_PAGE_SIZE = 10;\n\nexport type UseFirestorePaginatedResult<T> = Omit<\n  UseQueryResult<PaginatedPage<WithId<T>>, Error>,\n  'data'\n> & {\n  data: WithId<T>[] | undefined;\n  page: number;\n  pageSize: number;\n  hasNextPage: boolean;\n  hasPrevPage: boolean;\n  setPage: (page: number) => void;\n  nextPage: () => void;\n  prevPage: () => void;\n};\n\nexport function useFirestorePaginated<T extends DocumentData = DocumentData>({\n  collectionPath,\n  queryKey,\n  constraints = [],\n  pageSize = DEFAULT_PAGE_SIZE,\n  initialPage = 1,\n  enabled = true,\n  staleTime,\n  gcTime,\n  refetchInterval,\n  select,\n}: FirestorePaginatedOptions<T>): UseFirestorePaginatedResult<T> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n\n  const queryKeyMemo = JSON.stringify(queryKey);\n  const constraintsMemo = JSON.stringify(constraints);\n  const identity = JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, pageSize]);\n  const firstPage = Math.max(1, Math.floor(initialPage));\n\n  const [pageState, setPageState] = useState(() => ({ identity, page: firstPage }));\n  const page = pageState.identity === identity ? pageState.page : firstPage;\n\n  const selectRef = useRef(select);\n  selectRef.current = select;\n\n  const fetchPage = useCallback(\n    async (n: number): Promise<PaginatedPage<WithId<T>>> => {\n      let cursor: DocumentSnapshot | null = null;\n      if (n > 1) {\n        const previous = await queryClient.ensureQueryData<PaginatedPage<WithId<T>>>({\n          queryKey: paginatedPageKey(queryKey, n - 1),\n          queryFn: () => fetchPage(n - 1),\n        });\n        if (!previous.hasMore || !previous.cursor) {\n          return { items: [], cursor: null, hasMore: false, after: previous.cursor?.id ?? null };\n        }\n        cursor = previous.cursor;\n      }\n      const q = query(\n        collection(db, collectionPath),\n        ...constraints,\n        ...(cursor ? [startAfter(cursor)] : []),\n        limit(pageSize + 1),\n      );\n      const snapshot = await getDocs(q);\n      const pageDocs = snapshot.docs.slice(0, pageSize);\n      return {\n        items: pageDocs.map((docSnap) => {\n          const dataWithId = { id: docSnap.id, ...docSnap.data() };\n          const mapped = selectRef.current ? selectRef.current(dataWithId) : dataWithId;\n          return mapped as WithId<T>;\n        }),\n        cursor: pageDocs[pageDocs.length - 1] ?? null,\n        hasMore: snapshot.docs.length > pageSize,\n        after: cursor?.id ?? null,\n      };\n    },\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- queryKey and constraints are captured through their serialized identity\n    [db, queryClient, identity, selectRef],\n  );\n\n  const queryResult = useQuery({\n    queryKey: paginatedPageKey(queryKey, page),\n    queryFn: () => fetchPage(page),\n    enabled,\n    staleTime,\n    gcTime,\n    refetchInterval,\n  });\n\n  const previousPage = useQuery({\n    queryKey: paginatedPageKey(queryKey, Math.max(1, page - 1)),\n    queryFn: () => fetchPage(Math.max(1, page - 1)),\n    enabled: false,\n  });\n  const cachedEntry = queryResult.data;\n  const outOfChain =\n    page > 1 &&\n    cachedEntry !== undefined &&\n    (previousPage.data === undefined ||\n      cachedEntry.after !== (previousPage.data.cursor?.id ?? null));\n  const { refetch, isFetching } = queryResult;\n  useEffect(() => {\n    if (enabled && outOfChain && !isFetching) void refetch();\n  }, [enabled, outOfChain, isFetching, refetch]);\n\n  const entry = outOfChain ? undefined : cachedEntry;\n  const hasNextPage = Boolean(entry?.hasMore && entry.cursor);\n\n  const setPage = useCallback(\n    (target: number) => {\n      const next = Math.floor(target);\n      if (next < 1 || next === page) return;\n      if (next > page + 1) {\n        const before = queryClient.getQueryData<PaginatedPage<unknown>>(\n          paginatedPageKey(queryKey, next - 1),\n        );\n        if (!before?.hasMore) return;\n      }\n      if (next === page + 1 && !hasNextPage) return;\n      setPageState({ identity, page: next });\n    },\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- queryKey is captured through its serialized identity\n    [page, hasNextPage, identity, queryClient],\n  );\n\n  const nextPage = useCallback(() => setPage(page + 1), [page, setPage]);\n  const prevPage = useCallback(() => setPage(page - 1), [page, setPage]);\n\n  return {\n    ...queryResult,\n    ...(outOfChain\n      ? { isLoading: true, isPending: true, isSuccess: false, status: 'pending' as const }\n      : {}),\n    data: entry?.items,\n    page,\n    pageSize,\n    hasNextPage,\n    hasPrevPage: page > 1,\n    setPage,\n    nextPage,\n    prevPage,\n  } as UseFirestorePaginatedResult<T>;\n}\n"]}

package/dist/react/firestore/useBatchFirestoreDocs.d.ts

@@ -1,150 +1,28 @@
 import type { Firestore } from 'firebase/firestore';
 import type { BatchFirestoreDocOutcome } from '../../firestore/types.js';
-/** Transport used to resolve an id in one-shot mode. */
 export type BatchFirestoreDocsTransport = 'batch' | 'get';
 export type BatchFirestoreDocsOptions = {
-    /**
-     * Firestore instance to use for queries
-     */
     db: Firestore;
-    /**
-     * Full collection path (e.g., 'publicUsers', 'entities/public')
-     */
     collectionPath: string;
-    /**
-     * Array of document IDs to fetch
-     */
     ids: string[];
-    /**
-     * Query key prefix for individual document cache entries
-     * Each document is cached as [queryKeyPrefix, docId]
-     * @example 'publicUser' -> ['publicUser', 'user123']
-     */
     queryKeyPrefix: string;
-    /**
-     * Time in milliseconds a PRESENT document stays fresh (default: 30 minutes).
-     * An absent document uses `absentStaleTime` instead.
-     */
     staleTime?: number;
-    /**
-     * Time in milliseconds to keep unused data in cache (default: 1 hour)
-     */
     gcTime?: number;
-    /**
-     * Whether queries should be enabled (default: true)
-     */
     enabled?: boolean;
-    /**
-     * Real-time mode (default: false). When true, each id is resolved via a shared,
-     * reference-counted `onSnapshot` listener instead of a one-shot read:
-     * - a missing doc caches `null` (negative caching) and resolves the instant it appears,
-     * - identity edits propagate live, and every browser tab stays consistent,
-     * - `staleTime` is irrelevant (listeners keep the cache fresh) and `refetch()` is a no-op.
-     * Initial read cost matches the one-shot path; listeners then stay open while mounted.
-     * Use for small, frequently-rendered, change-sensitive docs owned by the signed-in user.
-     */
     subscribe?: boolean;
-    /**
-     * One-shot transport (default: `'batch'`).
-     *
-     * - `'batch'` — ids enqueued in the same microtask are coalesced into
-     *   `where(documentId(), 'in', …)` queries of at most `FIRESTORE_IN_FILTER_LIMIT` (firebase-helpers) ids each. Fewest round-trips.
-     * - `'get'` — one `getDoc` per id, run concurrently. Required for a collection whose
-     *   Firestore rules gate reads on `resource.data`: an unconstrained id-list query is
-     *   denied WHOLESALE there, while per-document gets are evaluated per document, so one
-     *   unreadable id errors alone instead of failing every id with it. On such a collection
-     *   a get against a nonexistent doc is also denied, so "absent" and "hidden" are the same
-     *   client-visible signal — the id surfaces as that query's error, never as a null.
-     */
+    /** `'get'` is required where rules gate reads on `resource.data`: there an id-list query is denied wholesale. */
     transport?: BatchFirestoreDocsTransport;
-    /**
-     * Time in milliseconds an ABSENT (`null`) result stays fresh (default: 30 seconds).
-     * Deliberately much shorter than `staleTime`: a missing doc is usually a doc that has
-     * not been mirrored/created YET, and holding "missing" as fresh for the full staleTime
-     * is what leaves a row blank long after the doc appears.
-     */
     absentStaleTime?: number;
-    /**
-     * Backoff ladder (ms) for re-reading an id that resolved absent, one re-read per rung
-     * per absence episode (default: {@link ABSENT_RETRY_DELAYS_MS}). Pass `[]` to ask for no
-     * re-reads.
-     *
-     * The timer is per cache key, so many consumers of the same absent id still cost one
-     * re-read per rung — and consumers that disagree combine by UNION, never by mount order:
-     * the key polls if ANY mounted consumer wants polling, on the LONGEST ladder among them.
-     * `[]` therefore only silences re-reads that no other mounted consumer asked for. The
-     * effective ladder is recomputed on every mount and unmount; an episode already in
-     * progress continues on the new ladder's remaining rungs, or stops if it is now empty.
-     */
     absentRetryDelaysMs?: readonly number[];
 };
 export type BatchFirestoreDocsResult<T> = {
-    /**
-     * Map of docId -> document data.
-     * Only includes documents that exist AND are currently readable: an id whose query is in
-     * an error state is excluded, so a previously cached doc is never presented as readable
-     * after access to it fails.
-     */
     data: Record<string, T>;
-    /**
-     * True while any requested id has not resolved yet
-     */
     isLoading: boolean;
-    /**
-     * True if any requested id is in an error state
-     */
     isError: boolean;
-    /**
-     * First error across the requested ids, if any
-     */
     error: Error | null;
-    /**
-     * One entry per requested id (empty ids and duplicates dropped): `loading`, `present` with
-     * its data, `absent`, or `failed` with that id's own error. A multi-id consumer reads which
-     * ids are missing and which failed here — `data` / `isError` / `error` are the aggregate
-     * view and cannot tell them apart. The map, and each unchanged entry, keep their identity
-     * across renders.
-     */
     outcomes: Record<string, BatchFirestoreDocOutcome<T>>;
-    /**
-     * True while a read of an id whose last settled read failed is fetching or waiting for the
-     * network — a retry of a failure. A first load, and the absence ladder's re-read of an id that
-     * answered absent, never count. TanStack clears a never-answered id's error as its refetch
-     * starts, so this is the running flag a retry state (`useReadRetryState`) is built from.
-     */
     failedReadsRunning: boolean;
-    /**
-     * Refetch every requested id, cached ones included. A no-op in subscribe mode.
-     */
     refetch: () => Promise<void>;
 };
-/**
- * Resolve many document ids into individually observed, individually cached React Query
- * entries at `[queryKeyPrefix, id]`.
- *
- * There is exactly ONE data cache: the per-id entries. Each id owns a real query with a
- * real `queryFn`, so exact-key invalidation, `refetchQueries({ type: 'active' })`, and
- * `refetchOnMount` all work on a single id the way they work on any other query — and the
- * returned `data` is derived reactively from those query results, never read imperatively.
- *
- * A nonexistent document resolves to `null` (negative caching) and is excluded from `data`;
- * an absent id is then re-read on a bounded ladder (see `absentRetryDelaysMs`) so a doc
- * that appears shortly afterwards shows up without an invalidation.
- *
- * Each id's own answer — loading, present, absent, or failed with its own error — is in
- * `outcomes`; the aggregate fields cannot tell an absent id from a failed one.
- *
- * @example
- * ```typescript
- * const { data: users, isLoading } = useBatchFirestoreDocs<PublicUser>({
- *   db,
- *   collectionPath: 'publicUsers',
- *   ids: ['user1', 'user2', 'user3'],
- *   queryKeyPrefix: 'publicUser',
- *   staleTime: 30 * 60 * 1000,
- * });
- * // users = { user1: {...}, user2: {...}, user3: {...} }
- * ```
- */
 export declare function useBatchFirestoreDocs<T extends Record<string, any>>({ db, collectionPath, ids, queryKeyPrefix, staleTime, gcTime, enabled, subscribe, transport, absentStaleTime, absentRetryDelaysMs, }: BatchFirestoreDocsOptions): BatchFirestoreDocsResult<T>;
 //# sourceMappingURL=useBatchFirestoreDocs.d.ts.map

package/dist/react/firestore/useBatchFirestoreDocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBatchFirestoreDocs.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/useBatchFirestoreDocs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIpD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGzE,wDAAwD;AACxD,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,KAAK,CAAC;AAE1D,MAAM,MAAM,yBAAyB,GAAG;IACtC;;OAEG;IACH,EAAE,EAAE,SAAS,CAAC;IAEd;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,GAAG,EAAE,MAAM,EAAE,CAAC;IAEd;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;IAExC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI;IACxC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAExB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAyBF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnE,EAAE,EACF,cAAc,EACd,GAAG,EACH,cAAc,EACd,SAA0B,EAC1B,MAAuB,EACvB,OAAc,EACd,SAAiB,EACjB,SAAmB,EACnB,eAA2B,EAC3B,mBAA4C,GAC7C,EAAE,yBAAyB,GAAG,wBAAwB,CAAC,CAAC,CAAC,CA0MzD"}
+{"version":3,"file":"useBatchFirestoreDocs.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/useBatchFirestoreDocs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIpD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAIzE,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,KAAK,CAAC;AAE1D,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,SAAS,CAAC;IAEd,cAAc,EAAE,MAAM,CAAC;IAEvB,GAAG,EAAE,MAAM,EAAE,CAAC;IAEd,cAAc,EAAE,MAAM,CAAC;IAEvB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,iHAAiH;IACjH,SAAS,CAAC,EAAE,2BAA2B,CAAC;IAExC,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAExB,SAAS,EAAE,OAAO,CAAC;IAEnB,OAAO,EAAE,OAAO,CAAC;IAEjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtD,kBAAkB,EAAE,OAAO,CAAC;IAE5B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AA2CF,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnE,EAAE,EACF,cAAc,EACd,GAAG,EACH,cAAc,EACd,SAA0B,EAC1B,MAAuB,EACvB,OAAc,EACd,SAAiB,EACjB,SAAmB,EACnB,eAA2B,EAC3B,mBAA4C,GAC7C,EAAE,yBAAyB,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAiLzD"}

package/dist/react/firestore/useBatchFirestoreDocs.js

@@ -5,20 +5,31 @@ import { isListenerOwned, listenerErrorOf, subscribeDoc } from './doc-subscripti
 import { getDocLoader } from './batch-doc-loader.js';
 import { ABSENT_RETRY_DELAYS_MS, trackAbsentDoc } from './absence-scheduler.js';
 import { useReadRetryStates } from '../use-read-retry-state.js';
+import { isPermissionDeniedError } from './resubscribe.js';
 const LOADING_OUTCOME = { status: 'loading' };
 const IDLE_SOURCE = { error: null, isFetching: false, isLoading: false };
 const ABSENT_OUTCOME = { status: 'absent' };
 function sameOutcome(a, b) {
     if (a.status !== b.status)
         return false;
-    if (a.status === 'present')
-        return a.data === b.data;
+    if (a.status === 'present') {
+        const other = b;
+        return (a.data === other.data &&
+            a.failure?.error === other.failure?.error &&
+            a.failure?.retrying === other.failure?.retrying);
+    }
     if (a.status === 'failed') {
         const other = b;
         return a.error === other.error && a.retrying === other.retrying;
     }
     return true;
 }
+function failedOrHeld(value, error, retrying) {
+    if (value === null || value === undefined || isPermissionDeniedError(error)) {
+        return { status: 'failed', error, retrying };
+    }
+    return { status: 'present', data: value, failure: { error, retrying } };
+}
 function shallowRecordEqual(a, b) {
     const aKeys = Object.keys(a);
     if (aKeys.length !== Object.keys(b).length)
@@ -29,50 +40,15 @@ function shallowRecordEqual(a, b) {
     }
     return true;
 }
-/**
- * Resolve many document ids into individually observed, individually cached React Query
- * entries at `[queryKeyPrefix, id]`.
- *
- * There is exactly ONE data cache: the per-id entries. Each id owns a real query with a
- * real `queryFn`, so exact-key invalidation, `refetchQueries({ type: 'active' })`, and
- * `refetchOnMount` all work on a single id the way they work on any other query — and the
- * returned `data` is derived reactively from those query results, never read imperatively.
- *
- * A nonexistent document resolves to `null` (negative caching) and is excluded from `data`;
- * an absent id is then re-read on a bounded ladder (see `absentRetryDelaysMs`) so a doc
- * that appears shortly afterwards shows up without an invalidation.
- *
- * Each id's own answer — loading, present, absent, or failed with its own error — is in
- * `outcomes`; the aggregate fields cannot tell an absent id from a failed one.
- *
- * @example
- * ```typescript
- * const { data: users, isLoading } = useBatchFirestoreDocs<PublicUser>({
- *   db,
- *   collectionPath: 'publicUsers',
- *   ids: ['user1', 'user2', 'user3'],
- *   queryKeyPrefix: 'publicUser',
- *   staleTime: 30 * 60 * 1000,
- * });
- * // users = { user1: {...}, user2: {...}, user3: {...} }
- * ```
- */
 export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix, staleTime = 30 * 60 * 1000, gcTime = 60 * 60 * 1000, enabled = true, subscribe = false, transport = 'batch', absentStaleTime = 30 * 1000, absentRetryDelaysMs = ABSENT_RETRY_DELAYS_MS, }) {
     const queryClient = useQueryClient();
-    // Stabilize ids reference to prevent cascading re-renders
     const idsKey = JSON.stringify(ids);
-    // Deduplicate and filter out empty IDs
     const uniqueIds = useMemo(() => {
         const parsed = JSON.parse(idsKey);
         return Array.from(new Set(parsed.filter(Boolean)));
     }, [idsKey]);
-    // ── Real-time subscribe mode ──────────────────────────────────────────────
-    // Listener errors cannot surface through the per-id queries (they are disabled while
-    // subscribed), so they are tracked here, per id, and merged into the returned result.
     const [subscribeErrors, setSubscribeErrors] = useState({});
-    // Snapshot re-render trigger. The per-id query observers do notify on the listener's
-    // cache write, but only on React Query's batched microtask; bumping state in the
-    // snapshot callback keeps a landed snapshot visible in the SAME tick it arrives.
+    // Query observers notify on React Query's batched microtask; bumping state here shows a snapshot in the tick it lands.
     const [, setSnapshotVersion] = useState(0);
     const results = useQueries({
         queries: uniqueIds.map((id) => ({
@@ -82,10 +58,7 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
                 const loaded = transport === 'get'
                     ? await loader.loadOne(id, signal)
                     : await loader.loadBatched(id, signal);
-                // If a shared listener took ownership of this key while the read was in flight, the
-                // listener's value is the newer truth — `onSnapshot` will not re-emit until the doc
-                // changes, so returning the read result here would leave a stale value stuck. A listener
-                // that errored left only a `null` placeholder; its error is the answer, never an absence.
+                // `onSnapshot` does not re-emit until the document changes, so a read that lands after a listener took the key yields to it.
                 if (isListenerOwned(queryClient, queryKeyPrefix, id)) {
                     const listenerError = listenerErrorOf(queryClient, queryKeyPrefix, id);
                     if (listenerError)
@@ -97,9 +70,7 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
                 return loaded;
             },
             enabled: enabled && !subscribe,
-            // The consuming app's global default is `refetchOnMount: false`; these lookups opt
-            // back in so a remount re-reads a STALE id (refetch-on-mount never fires on a fresh
-            // one, so an all-cache-hit mount still costs nothing).
+            // Opts back into refetch-on-mount (the package default is off) so a remount re-reads a stale id.
             refetchOnMount: !subscribe,
             staleTime: subscribe
                 ? Infinity
@@ -133,9 +104,6 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
                 unsubscribe();
         };
     }, [uniqueIds, subscribe, enabled, collectionPath, queryKeyPrefix, queryClient, db]);
-    // Bounded re-read ladder for ids that resolved absent. Registration is per cache key, so
-    // overlapping consumers share one episode budget. The ladder is rebuilt from its own
-    // serialized form so an inline array literal cannot re-register (and reset it) every render.
     const absentDelaysKey = absentRetryDelaysMs.join(',');
     const absentDelays = useMemo(() => absentDelaysKey.split(',').filter(Boolean).map(Number), [absentDelaysKey]);
     useEffect(() => {
@@ -147,14 +115,10 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
                 release();
         };
     }, [uniqueIds, queryKeyPrefix, queryClient, absentDelays]);
-    // The maps are rebuilt every render; the committed refs below hand back the last
-    // COMMITTED objects while nothing changed, so consumers can depend on their identity. Only
-    // the effect writes the refs, so a concurrent render React discards can never leave them
-    // pointing at an uncommitted map.
+    // Only the effect writes these refs, so a concurrent render React discards never leaves them on an uncommitted map.
     const committedDataRef = useRef({});
     const committedOutcomesRef = useRef({});
-    // Each id's one-shot failure is held through its retry: TanStack clears a never-answered
-    // read's error as its refetch starts, which would turn the id's failure into `loading`.
+    // TanStack clears a never-answered read's error as its refetch starts, so the failure is held through the retry.
     const retryStates = useReadRetryStates(uniqueIds.map((id, index) => ({
         source: (results[index] ?? IDLE_SOURCE),
         queryKey: [queryKeyPrefix, id],
@@ -170,8 +134,6 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
         const id = uniqueIds[index];
         const result = results[index];
         let outcome = LOADING_OUTCOME;
-        // A one-shot reader of a key a failed shared listener owns sees that listener's `null`
-        // placeholder in the cache; the registry's error is what it stands for.
         const listenerError = (subscribe ? subscribeErrors[id] : undefined) ??
             listenerErrorOf(queryClient, queryKeyPrefix, id) ??
             undefined;
@@ -183,27 +145,28 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
         const retryState = retryStates[index];
         if (result?.isError)
             anyError ??= result.error;
+        const value = result?.data;
         if (retryState && retryState.error !== null) {
-            outcome = { status: 'failed', error: retryState.error, retrying: retryState.isRetrying };
+            outcome = failedOrHeld(value, retryState.error, retryState.isRetrying);
         }
         else if (result) {
             if (result.isLoading)
                 oneShotLoading = true;
-            const value = result.data;
             if (value === undefined)
                 anyUnresolved = true;
             if (listenerError) {
                 anyListenerError ??= listenerError;
-                outcome = { status: 'failed', error: listenerError, retrying: false };
+                outcome = failedOrHeld(value, listenerError, false);
             }
             else if (value === null) {
                 outcome = ABSENT_OUTCOME;
             }
             else if (value !== undefined) {
-                nextData[id] = value;
                 outcome = { status: 'present', data: value };
             }
         }
+        if (outcome.status === 'present')
+            nextData[id] = outcome.data;
         const committed = committedOutcomesRef.current[id];
         nextOutcomes[id] = committed && sameOutcome(committed, outcome) ? committed : outcome;
     }
@@ -218,14 +181,10 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
         committedOutcomesRef.current = outcomes;
     }, [data, outcomes]);
     const refetch = useCallback(async () => {
-        // Subscribe mode owns its freshness through the shared listeners — refetching would
-        // issue reads against disabled queries and race the listener's value.
         if (subscribe || !enabled)
             return;
         await Promise.all(uniqueIds.map((id) => queryClient.refetchQueries({ queryKey: [queryKeyPrefix, id], exact: true })));
     }, [uniqueIds, subscribe, enabled, queryClient, queryKeyPrefix]);
-    // In subscribe mode "loading" means a subscribed id has no cache entry yet (`null`
-    // counts as resolved-missing).
     const isLoading = subscribe ? enabled && anyUnresolved : oneShotLoading;
     return {
         data,

package/dist/react/firestore/useBatchFirestoreDocs.js.map

@@ -1 +1 @@
-{"version":3,"file":"useBatchFirestoreDocs.js","sourceRoot":"","sources":["../../../src/react/firestore/useBatchFirestoreDocs.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { useQueries, useQueryClient } from '@tanstack/react-query';\nimport type { Firestore } from 'firebase/firestore';\nimport { isListenerOwned, listenerErrorOf, subscribeDoc } from './doc-subscription-registry.js';\nimport { getDocLoader } from './batch-doc-loader.js';\nimport { ABSENT_RETRY_DELAYS_MS, trackAbsentDoc } from './absence-scheduler.js';\nimport type { BatchFirestoreDocOutcome } from '../../firestore/types.js';\nimport { useReadRetryStates, type ReadRetrySource } from '../use-read-retry-state.js';\n\n/** Transport used to resolve an id in one-shot mode. */\nexport type BatchFirestoreDocsTransport = 'batch' | 'get';\n\nexport type BatchFirestoreDocsOptions = {\n  /**\n   * Firestore instance to use for queries\n   */\n  db: Firestore;\n\n  /**\n   * Full collection path (e.g., 'publicUsers', 'entities/public')\n   */\n  collectionPath: string;\n\n  /**\n   * Array of document IDs to fetch\n   */\n  ids: string[];\n\n  /**\n   * Query key prefix for individual document cache entries\n   * Each document is cached as [queryKeyPrefix, docId]\n   * @example 'publicUser' -> ['publicUser', 'user123']\n   */\n  queryKeyPrefix: string;\n\n  /**\n   * Time in milliseconds a PRESENT document stays fresh (default: 30 minutes).\n   * An absent document uses `absentStaleTime` instead.\n   */\n  staleTime?: number;\n\n  /**\n   * Time in milliseconds to keep unused data in cache (default: 1 hour)\n   */\n  gcTime?: number;\n\n  /**\n   * Whether queries should be enabled (default: true)\n   */\n  enabled?: boolean;\n\n  /**\n   * Real-time mode (default: false). When true, each id is resolved via a shared,\n   * reference-counted `onSnapshot` listener instead of a one-shot read:\n   * - a missing doc caches `null` (negative caching) and resolves the instant it appears,\n   * - identity edits propagate live, and every browser tab stays consistent,\n   * - `staleTime` is irrelevant (listeners keep the cache fresh) and `refetch()` is a no-op.\n   * Initial read cost matches the one-shot path; listeners then stay open while mounted.\n   * Use for small, frequently-rendered, change-sensitive docs owned by the signed-in user.\n   */\n  subscribe?: boolean;\n\n  /**\n   * One-shot transport (default: `'batch'`).\n   *\n   * - `'batch'` — ids enqueued in the same microtask are coalesced into\n   *   `where(documentId(), 'in', …)` queries of at most `FIRESTORE_IN_FILTER_LIMIT` (firebase-helpers) ids each. Fewest round-trips.\n   * - `'get'` — one `getDoc` per id, run concurrently. Required for a collection whose\n   *   Firestore rules gate reads on `resource.data`: an unconstrained id-list query is\n   *   denied WHOLESALE there, while per-document gets are evaluated per document, so one\n   *   unreadable id errors alone instead of failing every id with it. On such a collection\n   *   a get against a nonexistent doc is also denied, so \"absent\" and \"hidden\" are the same\n   *   client-visible signal — the id surfaces as that query's error, never as a null.\n   */\n  transport?: BatchFirestoreDocsTransport;\n\n  /**\n   * Time in milliseconds an ABSENT (`null`) result stays fresh (default: 30 seconds).\n   * Deliberately much shorter than `staleTime`: a missing doc is usually a doc that has\n   * not been mirrored/created YET, and holding \"missing\" as fresh for the full staleTime\n   * is what leaves a row blank long after the doc appears.\n   */\n  absentStaleTime?: number;\n\n  /**\n   * Backoff ladder (ms) for re-reading an id that resolved absent, one re-read per rung\n   * per absence episode (default: {@link ABSENT_RETRY_DELAYS_MS}). Pass `[]` to ask for no\n   * re-reads.\n   *\n   * The timer is per cache key, so many consumers of the same absent id still cost one\n   * re-read per rung — and consumers that disagree combine by UNION, never by mount order:\n   * the key polls if ANY mounted consumer wants polling, on the LONGEST ladder among them.\n   * `[]` therefore only silences re-reads that no other mounted consumer asked for. The\n   * effective ladder is recomputed on every mount and unmount; an episode already in\n   * progress continues on the new ladder's remaining rungs, or stops if it is now empty.\n   */\n  absentRetryDelaysMs?: readonly number[];\n};\n\nexport type BatchFirestoreDocsResult<T> = {\n  /**\n   * Map of docId -> document data.\n   * Only includes documents that exist AND are currently readable: an id whose query is in\n   * an error state is excluded, so a previously cached doc is never presented as readable\n   * after access to it fails.\n   */\n  data: Record<string, T>;\n\n  /**\n   * True while any requested id has not resolved yet\n   */\n  isLoading: boolean;\n\n  /**\n   * True if any requested id is in an error state\n   */\n  isError: boolean;\n\n  /**\n   * First error across the requested ids, if any\n   */\n  error: Error | null;\n\n  /**\n   * One entry per requested id (empty ids and duplicates dropped): `loading`, `present` with\n   * its data, `absent`, or `failed` with that id's own error. A multi-id consumer reads which\n   * ids are missing and which failed here — `data` / `isError` / `error` are the aggregate\n   * view and cannot tell them apart. The map, and each unchanged entry, keep their identity\n   * across renders.\n   */\n  outcomes: Record<string, BatchFirestoreDocOutcome<T>>;\n\n  /**\n   * True while a read of an id whose last settled read failed is fetching or waiting for the\n   * network — a retry of a failure. A first load, and the absence ladder's re-read of an id that\n   * answered absent, never count. TanStack clears a never-answered id's error as its refetch\n   * starts, so this is the running flag a retry state (`useReadRetryState`) is built from.\n   */\n  failedReadsRunning: boolean;\n\n  /**\n   * Refetch every requested id, cached ones included. A no-op in subscribe mode.\n   */\n  refetch: () => Promise<void>;\n};\n\nconst LOADING_OUTCOME = { status: 'loading' } as const;\nconst IDLE_SOURCE: ReadRetrySource<Error> = { error: null, isFetching: false, isLoading: false };\nconst ABSENT_OUTCOME = { status: 'absent' } as const;\n\nfunction sameOutcome<T>(a: BatchFirestoreDocOutcome<T>, b: BatchFirestoreDocOutcome<T>): boolean {\n  if (a.status !== b.status) return false;\n  if (a.status === 'present') return a.data === (b as { data: T }).data;\n  if (a.status === 'failed') {\n    const other = b as { error: Error; retrying: boolean };\n    return a.error === other.error && a.retrying === other.retrying;\n  }\n  return true;\n}\n\nfunction shallowRecordEqual<T>(a: Record<string, T>, b: Record<string, T>): boolean {\n  const aKeys = Object.keys(a);\n  if (aKeys.length !== Object.keys(b).length) return false;\n  for (const key of aKeys) {\n    if (!Object.prototype.hasOwnProperty.call(b, key) || a[key] !== b[key]) return false;\n  }\n  return true;\n}\n\n/**\n * Resolve many document ids into individually observed, individually cached React Query\n * entries at `[queryKeyPrefix, id]`.\n *\n * There is exactly ONE data cache: the per-id entries. Each id owns a real query with a\n * real `queryFn`, so exact-key invalidation, `refetchQueries({ type: 'active' })`, and\n * `refetchOnMount` all work on a single id the way they work on any other query — and the\n * returned `data` is derived reactively from those query results, never read imperatively.\n *\n * A nonexistent document resolves to `null` (negative caching) and is excluded from `data`;\n * an absent id is then re-read on a bounded ladder (see `absentRetryDelaysMs`) so a doc\n * that appears shortly afterwards shows up without an invalidation.\n *\n * Each id's own answer — loading, present, absent, or failed with its own error — is in\n * `outcomes`; the aggregate fields cannot tell an absent id from a failed one.\n *\n * @example\n * ```typescript\n * const { data: users, isLoading } = useBatchFirestoreDocs<PublicUser>({\n *   db,\n *   collectionPath: 'publicUsers',\n *   ids: ['user1', 'user2', 'user3'],\n *   queryKeyPrefix: 'publicUser',\n *   staleTime: 30 * 60 * 1000,\n * });\n * // users = { user1: {...}, user2: {...}, user3: {...} }\n * ```\n */\nexport function useBatchFirestoreDocs<T extends Record<string, any>>({\n  db,\n  collectionPath,\n  ids,\n  queryKeyPrefix,\n  staleTime = 30 * 60 * 1000,\n  gcTime = 60 * 60 * 1000,\n  enabled = true,\n  subscribe = false,\n  transport = 'batch',\n  absentStaleTime = 30 * 1000,\n  absentRetryDelaysMs = ABSENT_RETRY_DELAYS_MS,\n}: BatchFirestoreDocsOptions): BatchFirestoreDocsResult<T> {\n  const queryClient = useQueryClient();\n\n  // Stabilize ids reference to prevent cascading re-renders\n  const idsKey = JSON.stringify(ids);\n\n  // Deduplicate and filter out empty IDs\n  const uniqueIds = useMemo(() => {\n    const parsed: string[] = JSON.parse(idsKey);\n    return Array.from(new Set(parsed.filter(Boolean)));\n  }, [idsKey]);\n\n  // ── Real-time subscribe mode ──────────────────────────────────────────────\n  // Listener errors cannot surface through the per-id queries (they are disabled while\n  // subscribed), so they are tracked here, per id, and merged into the returned result.\n  const [subscribeErrors, setSubscribeErrors] = useState<Record<string, Error>>({});\n  // Snapshot re-render trigger. The per-id query observers do notify on the listener's\n  // cache write, but only on React Query's batched microtask; bumping state in the\n  // snapshot callback keeps a landed snapshot visible in the SAME tick it arrives.\n  const [, setSnapshotVersion] = useState(0);\n\n  const results = useQueries({\n    queries: uniqueIds.map((id) => ({\n      queryKey: [queryKeyPrefix, id],\n      queryFn: async ({ signal }: { signal: AbortSignal }): Promise<T | null> => {\n        const loader = getDocLoader(queryClient, db, collectionPath);\n        const loaded =\n          transport === 'get'\n            ? await loader.loadOne(id, signal)\n            : await loader.loadBatched(id, signal);\n        // If a shared listener took ownership of this key while the read was in flight, the\n        // listener's value is the newer truth — `onSnapshot` will not re-emit until the doc\n        // changes, so returning the read result here would leave a stale value stuck. A listener\n        // that errored left only a `null` placeholder; its error is the answer, never an absence.\n        if (isListenerOwned(queryClient, queryKeyPrefix, id)) {\n          const listenerError = listenerErrorOf(queryClient, queryKeyPrefix, id);\n          if (listenerError) throw listenerError;\n          const owned = queryClient.getQueryData([queryKeyPrefix, id]);\n          if (owned !== undefined) return owned as T | null;\n        }\n        return loaded as T | null;\n      },\n      enabled: enabled && !subscribe,\n      // The consuming app's global default is `refetchOnMount: false`; these lookups opt\n      // back in so a remount re-reads a STALE id (refetch-on-mount never fires on a fresh\n      // one, so an all-cache-hit mount still costs nothing).\n      refetchOnMount: !subscribe,\n      staleTime: subscribe\n        ? Infinity\n        : (query: { state: { data: unknown } }) =>\n            query.state.data === null ? absentStaleTime : staleTime,\n      gcTime,\n    })),\n  });\n\n  useEffect(() => {\n    if (!subscribe || !enabled || uniqueIds.length === 0) return;\n    setSubscribeErrors({});\n    const unsubscribers = uniqueIds.map((id) =>\n      subscribeDoc({\n        queryClient,\n        db,\n        collectionPath,\n        queryKeyPrefix,\n        id,\n        onUpdate: () => {\n          setSubscribeErrors((errors) => {\n            if (!(id in errors)) return errors;\n            const { [id]: _cleared, ...rest } = errors;\n            return rest;\n          });\n          setSnapshotVersion((version) => version + 1);\n        },\n        onError: (error) =>\n          setSubscribeErrors((errors) =>\n            errors[id] === error ? errors : { ...errors, [id]: error },\n          ),\n      }),\n    );\n    return () => {\n      for (const unsubscribe of unsubscribers) unsubscribe();\n    };\n  }, [uniqueIds, subscribe, enabled, collectionPath, queryKeyPrefix, queryClient, db]);\n\n  // Bounded re-read ladder for ids that resolved absent. Registration is per cache key, so\n  // overlapping consumers share one episode budget. The ladder is rebuilt from its own\n  // serialized form so an inline array literal cannot re-register (and reset it) every render.\n  const absentDelaysKey = absentRetryDelaysMs.join(',');\n  const absentDelays = useMemo(\n    () => absentDelaysKey.split(',').filter(Boolean).map(Number),\n    [absentDelaysKey],\n  );\n\n  useEffect(() => {\n    if (uniqueIds.length === 0) return;\n    const releases = uniqueIds.map((id) =>\n      trackAbsentDoc({ queryClient, queryKey: [queryKeyPrefix, id], delays: absentDelays }),\n    );\n    return () => {\n      for (const release of releases) release();\n    };\n  }, [uniqueIds, queryKeyPrefix, queryClient, absentDelays]);\n\n  // The maps are rebuilt every render; the committed refs below hand back the last\n  // COMMITTED objects while nothing changed, so consumers can depend on their identity. Only\n  // the effect writes the refs, so a concurrent render React discards can never leave them\n  // pointing at an uncommitted map.\n  const committedDataRef = useRef<Record<string, T>>({});\n  const committedOutcomesRef = useRef<Record<string, BatchFirestoreDocOutcome<T>>>({});\n\n  // Each id's one-shot failure is held through its retry: TanStack clears a never-answered\n  // read's error as its refetch starts, which would turn the id's failure into `loading`.\n  const retryStates = useReadRetryStates(\n    uniqueIds.map((id, index) => ({\n      source: (results[index] ?? IDLE_SOURCE) as ReadRetrySource<Error>,\n      queryKey: [queryKeyPrefix, id],\n    })),\n  );\n\n  const nextData: Record<string, T> = {};\n  const nextOutcomes: Record<string, BatchFirestoreDocOutcome<T>> = {};\n  let anyError: Error | null = null;\n  let anyListenerError: Error | null = null;\n  let oneShotLoading = false;\n  let anyUnresolved = false;\n  let failedReadsRunning = false;\n\n  for (let index = 0; index < uniqueIds.length; index += 1) {\n    const id = uniqueIds[index];\n    const result = results[index];\n    let outcome: BatchFirestoreDocOutcome<T> = LOADING_OUTCOME;\n    // A one-shot reader of a key a failed shared listener owns sees that listener's `null`\n    // placeholder in the cache; the registry's error is what it stands for.\n    const listenerError =\n      (subscribe ? subscribeErrors[id] : undefined) ??\n      listenerErrorOf(queryClient, queryKeyPrefix, id) ??\n      undefined;\n    if (\n      result &&\n      (result.isFetching || result.isPaused) &&\n      result.errorUpdatedAt > result.dataUpdatedAt\n    ) {\n      failedReadsRunning = true;\n    }\n    const retryState = retryStates[index];\n    if (result?.isError) anyError ??= result.error as Error;\n    if (retryState && retryState.error !== null) {\n      outcome = { status: 'failed', error: retryState.error, retrying: retryState.isRetrying };\n    } else if (result) {\n      if (result.isLoading) oneShotLoading = true;\n      const value = result.data as T | null | undefined;\n      if (value === undefined) anyUnresolved = true;\n      if (listenerError) {\n        anyListenerError ??= listenerError;\n        outcome = { status: 'failed', error: listenerError, retrying: false };\n      } else if (value === null) {\n        outcome = ABSENT_OUTCOME;\n      } else if (value !== undefined) {\n        nextData[id] = value;\n        outcome = { status: 'present', data: value };\n      }\n    }\n    const committed = committedOutcomesRef.current[id];\n    nextOutcomes[id] = committed && sameOutcome(committed, outcome) ? committed : outcome;\n  }\n\n  const data = shallowRecordEqual(committedDataRef.current, nextData)\n    ? committedDataRef.current\n    : nextData;\n  const outcomes = shallowRecordEqual(committedOutcomesRef.current, nextOutcomes)\n    ? committedOutcomesRef.current\n    : nextOutcomes;\n\n  useEffect(() => {\n    committedDataRef.current = data;\n    committedOutcomesRef.current = outcomes;\n  }, [data, outcomes]);\n\n  const refetch = useCallback(async () => {\n    // Subscribe mode owns its freshness through the shared listeners — refetching would\n    // issue reads against disabled queries and race the listener's value.\n    if (subscribe || !enabled) return;\n    await Promise.all(\n      uniqueIds.map((id) =>\n        queryClient.refetchQueries({ queryKey: [queryKeyPrefix, id], exact: true }),\n      ),\n    );\n  }, [uniqueIds, subscribe, enabled, queryClient, queryKeyPrefix]);\n\n  // In subscribe mode \"loading\" means a subscribed id has no cache entry yet (`null`\n  // counts as resolved-missing).\n  const isLoading = subscribe ? enabled && anyUnresolved : oneShotLoading;\n\n  return {\n    data,\n    isLoading,\n    isError: anyError !== null || anyListenerError !== null,\n    error: anyError ?? anyListenerError,\n    outcomes,\n    failedReadsRunning,\n    refetch,\n  };\n}\n"]}
+{"version":3,"file":"useBatchFirestoreDocs.js","sourceRoot":"","sources":["../../../src/react/firestore/useBatchFirestoreDocs.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { useQueries, useQueryClient } from '@tanstack/react-query';\nimport type { Firestore } from 'firebase/firestore';\nimport { isListenerOwned, listenerErrorOf, subscribeDoc } from './doc-subscription-registry.js';\nimport { getDocLoader } from './batch-doc-loader.js';\nimport { ABSENT_RETRY_DELAYS_MS, trackAbsentDoc } from './absence-scheduler.js';\nimport type { BatchFirestoreDocOutcome } from '../../firestore/types.js';\nimport { useReadRetryStates, type ReadRetrySource } from '../use-read-retry-state.js';\nimport { isPermissionDeniedError } from './resubscribe.js';\n\nexport type BatchFirestoreDocsTransport = 'batch' | 'get';\n\nexport type BatchFirestoreDocsOptions = {\n  db: Firestore;\n\n  collectionPath: string;\n\n  ids: string[];\n\n  queryKeyPrefix: string;\n\n  staleTime?: number;\n\n  gcTime?: number;\n\n  enabled?: boolean;\n\n  subscribe?: boolean;\n\n  /** `'get'` is required where rules gate reads on `resource.data`: there an id-list query is denied wholesale. */\n  transport?: BatchFirestoreDocsTransport;\n\n  absentStaleTime?: number;\n\n  absentRetryDelaysMs?: readonly number[];\n};\n\nexport type BatchFirestoreDocsResult<T> = {\n  data: Record<string, T>;\n\n  isLoading: boolean;\n\n  isError: boolean;\n\n  error: Error | null;\n\n  outcomes: Record<string, BatchFirestoreDocOutcome<T>>;\n\n  failedReadsRunning: boolean;\n\n  refetch: () => Promise<void>;\n};\n\nconst LOADING_OUTCOME = { status: 'loading' } as const;\nconst IDLE_SOURCE: ReadRetrySource<Error> = { error: null, isFetching: false, isLoading: false };\nconst ABSENT_OUTCOME = { status: 'absent' } as const;\n\nfunction sameOutcome<T>(a: BatchFirestoreDocOutcome<T>, b: BatchFirestoreDocOutcome<T>): boolean {\n  if (a.status !== b.status) return false;\n  if (a.status === 'present') {\n    const other = b as { data: T; failure?: { error: Error; retrying: boolean } };\n    return (\n      a.data === other.data &&\n      a.failure?.error === other.failure?.error &&\n      a.failure?.retrying === other.failure?.retrying\n    );\n  }\n  if (a.status === 'failed') {\n    const other = b as { error: Error; retrying: boolean };\n    return a.error === other.error && a.retrying === other.retrying;\n  }\n  return true;\n}\n\nfunction failedOrHeld<T>(\n  value: T | null | undefined,\n  error: Error,\n  retrying: boolean,\n): BatchFirestoreDocOutcome<T> {\n  if (value === null || value === undefined || isPermissionDeniedError(error)) {\n    return { status: 'failed', error, retrying };\n  }\n  return { status: 'present', data: value, failure: { error, retrying } };\n}\n\nfunction shallowRecordEqual<T>(a: Record<string, T>, b: Record<string, T>): boolean {\n  const aKeys = Object.keys(a);\n  if (aKeys.length !== Object.keys(b).length) return false;\n  for (const key of aKeys) {\n    if (!Object.prototype.hasOwnProperty.call(b, key) || a[key] !== b[key]) return false;\n  }\n  return true;\n}\n\nexport function useBatchFirestoreDocs<T extends Record<string, any>>({\n  db,\n  collectionPath,\n  ids,\n  queryKeyPrefix,\n  staleTime = 30 * 60 * 1000,\n  gcTime = 60 * 60 * 1000,\n  enabled = true,\n  subscribe = false,\n  transport = 'batch',\n  absentStaleTime = 30 * 1000,\n  absentRetryDelaysMs = ABSENT_RETRY_DELAYS_MS,\n}: BatchFirestoreDocsOptions): BatchFirestoreDocsResult<T> {\n  const queryClient = useQueryClient();\n\n  const idsKey = JSON.stringify(ids);\n\n  const uniqueIds = useMemo(() => {\n    const parsed: string[] = JSON.parse(idsKey);\n    return Array.from(new Set(parsed.filter(Boolean)));\n  }, [idsKey]);\n\n  const [subscribeErrors, setSubscribeErrors] = useState<Record<string, Error>>({});\n  // Query observers notify on React Query's batched microtask; bumping state here shows a snapshot in the tick it lands.\n  const [, setSnapshotVersion] = useState(0);\n\n  const results = useQueries({\n    queries: uniqueIds.map((id) => ({\n      queryKey: [queryKeyPrefix, id],\n      queryFn: async ({ signal }: { signal: AbortSignal }): Promise<T | null> => {\n        const loader = getDocLoader(queryClient, db, collectionPath);\n        const loaded =\n          transport === 'get'\n            ? await loader.loadOne(id, signal)\n            : await loader.loadBatched(id, signal);\n        // `onSnapshot` does not re-emit until the document changes, so a read that lands after a listener took the key yields to it.\n        if (isListenerOwned(queryClient, queryKeyPrefix, id)) {\n          const listenerError = listenerErrorOf(queryClient, queryKeyPrefix, id);\n          if (listenerError) throw listenerError;\n          const owned = queryClient.getQueryData([queryKeyPrefix, id]);\n          if (owned !== undefined) return owned as T | null;\n        }\n        return loaded as T | null;\n      },\n      enabled: enabled && !subscribe,\n      // Opts back into refetch-on-mount (the package default is off) so a remount re-reads a stale id.\n      refetchOnMount: !subscribe,\n      staleTime: subscribe\n        ? Infinity\n        : (query: { state: { data: unknown } }) =>\n            query.state.data === null ? absentStaleTime : staleTime,\n      gcTime,\n    })),\n  });\n\n  useEffect(() => {\n    if (!subscribe || !enabled || uniqueIds.length === 0) return;\n    setSubscribeErrors({});\n    const unsubscribers = uniqueIds.map((id) =>\n      subscribeDoc({\n        queryClient,\n        db,\n        collectionPath,\n        queryKeyPrefix,\n        id,\n        onUpdate: () => {\n          setSubscribeErrors((errors) => {\n            if (!(id in errors)) return errors;\n            const { [id]: _cleared, ...rest } = errors;\n            return rest;\n          });\n          setSnapshotVersion((version) => version + 1);\n        },\n        onError: (error) =>\n          setSubscribeErrors((errors) =>\n            errors[id] === error ? errors : { ...errors, [id]: error },\n          ),\n      }),\n    );\n    return () => {\n      for (const unsubscribe of unsubscribers) unsubscribe();\n    };\n  }, [uniqueIds, subscribe, enabled, collectionPath, queryKeyPrefix, queryClient, db]);\n\n  const absentDelaysKey = absentRetryDelaysMs.join(',');\n  const absentDelays = useMemo(\n    () => absentDelaysKey.split(',').filter(Boolean).map(Number),\n    [absentDelaysKey],\n  );\n\n  useEffect(() => {\n    if (uniqueIds.length === 0) return;\n    const releases = uniqueIds.map((id) =>\n      trackAbsentDoc({ queryClient, queryKey: [queryKeyPrefix, id], delays: absentDelays }),\n    );\n    return () => {\n      for (const release of releases) release();\n    };\n  }, [uniqueIds, queryKeyPrefix, queryClient, absentDelays]);\n\n  // Only the effect writes these refs, so a concurrent render React discards never leaves them on an uncommitted map.\n  const committedDataRef = useRef<Record<string, T>>({});\n  const committedOutcomesRef = useRef<Record<string, BatchFirestoreDocOutcome<T>>>({});\n\n  // TanStack clears a never-answered read's error as its refetch starts, so the failure is held through the retry.\n  const retryStates = useReadRetryStates(\n    uniqueIds.map((id, index) => ({\n      source: (results[index] ?? IDLE_SOURCE) as ReadRetrySource<Error>,\n      queryKey: [queryKeyPrefix, id],\n    })),\n  );\n\n  const nextData: Record<string, T> = {};\n  const nextOutcomes: Record<string, BatchFirestoreDocOutcome<T>> = {};\n  let anyError: Error | null = null;\n  let anyListenerError: Error | null = null;\n  let oneShotLoading = false;\n  let anyUnresolved = false;\n  let failedReadsRunning = false;\n\n  for (let index = 0; index < uniqueIds.length; index += 1) {\n    const id = uniqueIds[index];\n    const result = results[index];\n    let outcome: BatchFirestoreDocOutcome<T> = LOADING_OUTCOME;\n    const listenerError =\n      (subscribe ? subscribeErrors[id] : undefined) ??\n      listenerErrorOf(queryClient, queryKeyPrefix, id) ??\n      undefined;\n    if (\n      result &&\n      (result.isFetching || result.isPaused) &&\n      result.errorUpdatedAt > result.dataUpdatedAt\n    ) {\n      failedReadsRunning = true;\n    }\n    const retryState = retryStates[index];\n    if (result?.isError) anyError ??= result.error as Error;\n    const value = result?.data as T | null | undefined;\n    if (retryState && retryState.error !== null) {\n      outcome = failedOrHeld(value, retryState.error, retryState.isRetrying);\n    } else if (result) {\n      if (result.isLoading) oneShotLoading = true;\n      if (value === undefined) anyUnresolved = true;\n      if (listenerError) {\n        anyListenerError ??= listenerError;\n        outcome = failedOrHeld(value, listenerError, false);\n      } else if (value === null) {\n        outcome = ABSENT_OUTCOME;\n      } else if (value !== undefined) {\n        outcome = { status: 'present', data: value };\n      }\n    }\n    if (outcome.status === 'present') nextData[id] = outcome.data;\n    const committed = committedOutcomesRef.current[id];\n    nextOutcomes[id] = committed && sameOutcome(committed, outcome) ? committed : outcome;\n  }\n\n  const data = shallowRecordEqual(committedDataRef.current, nextData)\n    ? committedDataRef.current\n    : nextData;\n  const outcomes = shallowRecordEqual(committedOutcomesRef.current, nextOutcomes)\n    ? committedOutcomesRef.current\n    : nextOutcomes;\n\n  useEffect(() => {\n    committedDataRef.current = data;\n    committedOutcomesRef.current = outcomes;\n  }, [data, outcomes]);\n\n  const refetch = useCallback(async () => {\n    if (subscribe || !enabled) return;\n    await Promise.all(\n      uniqueIds.map((id) =>\n        queryClient.refetchQueries({ queryKey: [queryKeyPrefix, id], exact: true }),\n      ),\n    );\n  }, [uniqueIds, subscribe, enabled, queryClient, queryKeyPrefix]);\n\n  const isLoading = subscribe ? enabled && anyUnresolved : oneShotLoading;\n\n  return {\n    data,\n    isLoading,\n    isError: anyError !== null || anyListenerError !== null,\n    error: anyError ?? anyListenerError,\n    outcomes,\n    failedReadsRunning,\n    refetch,\n  };\n}\n"]}