@ttt-productions/query-core 0.14.13 → 0.14.15

package/dist/firestore/types.d.ts

@@ -32,6 +32,8 @@ export type WithSourceState<R> = R & {
  *   A failure is never reported as `absent`, and a document cached before the failure is
  *   not reported as `present`. What a failure means for a given collection (a rules denial
  *   that stands for "not there for this reader", say) is the consumer's to decide from `error`.
+ * - A failed id stays `failed` through a retry of it, with the failure it showed and `retrying`
+ *   true while the retry runs; an answer replaces it, a new failure replaces its `error`.
  */
 export type BatchFirestoreDocOutcome<T> = {
     status: 'loading';
@@ -43,6 +45,7 @@ export type BatchFirestoreDocOutcome<T> = {
 } | {
     status: 'failed';
     error: Error;
+    retrying: boolean;
 };
 /**
  * Extract document data with ID from a QueryDocumentSnapshot.

package/dist/firestore/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/E,yFAAyF;AACzF,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,WAAW,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAClC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1D;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,YAAY,EAC9C,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,MAAM,CAAC,CAAC,CAAC,CAEX;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,oBAAoB;IAClE,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,CAAC,CAAE,SAAQ,oBAAoB;IACzE,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,CAAE,SAAQ,oBAAoB;IACvE,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,CAAE,SAAQ,oBAAoB;IACxE,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B,CAAC,CAAC,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE;IAC7E,iFAAiF;IACjF,cAAc,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,CAAC,CAAC;IACpD,qHAAqH;IACrH,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACnB,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC;IACtC,gCAAgC;IAChC,UAAU,CAAC,EAAE;QACX,uCAAuC;QACvC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;QAC7B,oCAAoC;QACpC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;KAC7D,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,cAAc,CAAC,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC;IACtC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/firestore/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"AA8CA;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,IAA8B;IAE9B,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["import type {\n  DocumentData,\n  DocumentSnapshot,\n  QueryDocumentSnapshot,\n  QueryConstraint,\n} from 'firebase/firestore';\n\n/**\n * Document with ID included in the data object.\n */\nexport type WithId<T> = T & { id: string };\n\n/**\n * Metadata-derived liveness of a realtime subscription. Firestore serves cached\n * snapshots offline WITHOUT firing the error callback, so error-only detection\n * renders a stale cached empty result as \"live\". This four-state is derived from\n * `snapshot.metadata.fromCache` (server-confirmed vs cache) plus the listener\n * error callback:\n * - `connecting` — no server-confirmed snapshot yet (initial, or only cache-first data).\n * - `live` — at least one server-confirmed snapshot (`fromCache === false`).\n * - `offline` — only cached data after having been live (connectivity loss).\n * - `error` — the listener error callback fired (e.g. permission loss).\n *\n * Meaningful only for `subscribe: true`; a non-subscribed hook stays `connecting`.\n */\nexport type FirestoreSourceState = 'connecting' | 'live' | 'offline' | 'error';\n\n/** A query-hook result augmented with the metadata-derived subscription source state. */\nexport type WithSourceState<R> = R & { sourceState: FirestoreSourceState };\n\n/**\n * One requested id's answer from `useBatchFirestoreDocs`:\n * - `loading` — no answer yet (nothing cached for the id, or the hook is disabled).\n * - `present` — the document exists and is readable; `data` is it.\n * - `absent` — the read succeeded and the document does not exist.\n * - `failed` — the read (or, in subscribe mode, the listener) errored; `error` is the cause.\n *   A failure is never reported as `absent`, and a document cached before the failure is\n *   not reported as `present`. What a failure means for a given collection (a rules denial\n *   that stands for \"not there for this reader\", say) is the consumer's to decide from `error`.\n */\nexport type BatchFirestoreDocOutcome<T> =\n  | { status: 'loading' }\n  | { status: 'present'; data: T }\n  | { status: 'absent' }\n  | { status: 'failed'; error: Error };\n\n/**\n * Extract document data with ID from a QueryDocumentSnapshot.\n */\nexport function docWithId<T extends DocumentData>(\n  snap: QueryDocumentSnapshot<T>\n): WithId<T> {\n  return { id: snap.id, ...snap.data() };\n}\n\n/**\n * Base options shared across all Firestore hooks.\n */\nexport interface FirestoreBaseOptions {\n  /** React Query cache key */\n  queryKey: readonly unknown[];\n  /** Enable/disable the query */\n  enabled?: boolean;\n  /** Stale time override (ms) */\n  staleTime?: number;\n  /** Garbage collection time override (ms) */\n  gcTime?: number;\n}\n\n/**\n * Options for single document queries.\n */\nexport interface FirestoreDocOptions<T> extends FirestoreBaseOptions {\n  /** Full document path (e.g., 'users/abc123') */\n  docPath: string;\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to document data. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for collection queries.\n */\nexport interface FirestoreCollectionOptions<T> extends FirestoreBaseOptions {\n  /** Collection path (e.g., 'users' or 'entities/abc/members') */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy, etc.) */\n  constraints?: QueryConstraint[];\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for infinite scroll queries.\n */\nexport interface FirestoreInfiniteOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy - required for pagination) */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 20) */\n  pageSize?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for paginated queries with page numbers.\n */\nexport interface FirestorePaginatedOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 10) */\n  pageSize?: number;\n  /** Initial page number (default: 1) */\n  initialPage?: number;\n  /** Re-read the displayed page every `refetchInterval` ms while it is mounted (omit for none). */\n  refetchInterval?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for count() aggregation queries.\n */\nexport interface FirestoreCountOptions extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, etc.) applied before counting */\n  constraints?: QueryConstraint[];\n  /** Polling interval in ms (omit for no polling) */\n  refetchInterval?: number;\n}\n\n/**\n * Options for a live newest-window + cursor-bridged older-pages list\n * (e.g. chat messages, live comment threads, live activity feeds). The newest\n * page is a realtime onSnapshot window; older pages load on demand via getDocs,\n * seeded from the window's oldest document so there is no gap or re-read.\n */\nexport interface FirestoreLiveInfiniteOptions<T = DocumentData & { id: string }> {\n  /** Collection path (slash-joined for nested paths, e.g. 'chats/t1/messages'). */\n  collectionPath: string;\n  /** React Query cache key. The older-pages query is keyed under `[...queryKey, 'older']`. */\n  queryKey: readonly unknown[];\n  /** Field both the live window and older pages order by (descending under the hood). */\n  orderByField: string;\n  /** Equality/filter constraints. Do NOT pass orderBy/limit/startAfter — the hook adds those. */\n  constraints?: QueryConstraint[];\n  /** Items per page / live-window size (default 20, capped at 100). */\n  pageSize?: number;\n  /** When false, no listener is opened and no pages are fetched. */\n  enabled?: boolean;\n  /** Map each raw doc (id included) to the item shape. Default: identity (WithId). */\n  select?: (data: DocumentData & { id: string }) => T;\n  /** Output ordering of the merged list, by `orderByField` as Firestore orders it. Default 'asc' (oldest → newest). */\n  sort?: 'asc' | 'desc';\n}\n\n/**\n * Result page for infinite queries.\n */\nexport interface InfinitePage<T> {\n  items: WithId<T>[];\n  lastDoc: DocumentSnapshot | null;\n  size: number;\n}\n\n/**\n * One page's cache entry for `useFirestorePaginated`, stored at `[...queryKey, 'page', n]`:\n * the page's rows, its last row (the next page's cursor; `null` for an empty page), and\n * whether a further page exists (read with a one-row look-ahead), and the id of the row it\n * was read after (`null` for page 1), checked against the previous page's cursor.\n */\nexport interface PaginatedPage<T> {\n  items: T[];\n  cursor: DocumentSnapshot | null;\n  hasMore: boolean;\n  after: string | null;\n}\n\n/**\n * Mutation operation types for batch mutations.\n */\nexport type MutationOperation =\n  | { type: 'set'; docPath: string; data: DocumentData; merge?: boolean }\n  | { type: 'update'; docPath: string; data: DocumentData }\n  | { type: 'delete'; docPath: string };\n\n/**\n * Options for document mutations.\n */\nexport interface FirestoreMutationOptions<T> {\n  /** Document path for single-doc mutations */\n  docPath?: string;\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Enable optimistic updates */\n  optimistic?: {\n    /** Query key of the cache to update */\n    queryKey: readonly unknown[];\n    /** How to update the cached data */\n    updater: (oldData: T | undefined, newData: Partial<T>) => T;\n  };\n}\n\n/**\n * Options for batch mutations.\n */\nexport interface FirestoreBatchOptions {\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Max operations per batch (default: 450) */\n  batchSize?: number;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/firestore/types.ts"],"names":[],"mappings":"AAgDA;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,IAA8B;IAE9B,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["import type {\n  DocumentData,\n  DocumentSnapshot,\n  QueryDocumentSnapshot,\n  QueryConstraint,\n} from 'firebase/firestore';\n\n/**\n * Document with ID included in the data object.\n */\nexport type WithId<T> = T & { id: string };\n\n/**\n * Metadata-derived liveness of a realtime subscription. Firestore serves cached\n * snapshots offline WITHOUT firing the error callback, so error-only detection\n * renders a stale cached empty result as \"live\". This four-state is derived from\n * `snapshot.metadata.fromCache` (server-confirmed vs cache) plus the listener\n * error callback:\n * - `connecting` — no server-confirmed snapshot yet (initial, or only cache-first data).\n * - `live` — at least one server-confirmed snapshot (`fromCache === false`).\n * - `offline` — only cached data after having been live (connectivity loss).\n * - `error` — the listener error callback fired (e.g. permission loss).\n *\n * Meaningful only for `subscribe: true`; a non-subscribed hook stays `connecting`.\n */\nexport type FirestoreSourceState = 'connecting' | 'live' | 'offline' | 'error';\n\n/** A query-hook result augmented with the metadata-derived subscription source state. */\nexport type WithSourceState<R> = R & { sourceState: FirestoreSourceState };\n\n/**\n * One requested id's answer from `useBatchFirestoreDocs`:\n * - `loading` — no answer yet (nothing cached for the id, or the hook is disabled).\n * - `present` — the document exists and is readable; `data` is it.\n * - `absent` — the read succeeded and the document does not exist.\n * - `failed` — the read (or, in subscribe mode, the listener) errored; `error` is the cause.\n *   A failure is never reported as `absent`, and a document cached before the failure is\n *   not reported as `present`. What a failure means for a given collection (a rules denial\n *   that stands for \"not there for this reader\", say) is the consumer's to decide from `error`.\n * - A failed id stays `failed` through a retry of it, with the failure it showed and `retrying`\n *   true while the retry runs; an answer replaces it, a new failure replaces its `error`.\n */\nexport type BatchFirestoreDocOutcome<T> =\n  | { status: 'loading' }\n  | { status: 'present'; data: T }\n  | { status: 'absent' }\n  | { status: 'failed'; error: Error; retrying: boolean };\n\n/**\n * Extract document data with ID from a QueryDocumentSnapshot.\n */\nexport function docWithId<T extends DocumentData>(\n  snap: QueryDocumentSnapshot<T>\n): WithId<T> {\n  return { id: snap.id, ...snap.data() };\n}\n\n/**\n * Base options shared across all Firestore hooks.\n */\nexport interface FirestoreBaseOptions {\n  /** React Query cache key */\n  queryKey: readonly unknown[];\n  /** Enable/disable the query */\n  enabled?: boolean;\n  /** Stale time override (ms) */\n  staleTime?: number;\n  /** Garbage collection time override (ms) */\n  gcTime?: number;\n}\n\n/**\n * Options for single document queries.\n */\nexport interface FirestoreDocOptions<T> extends FirestoreBaseOptions {\n  /** Full document path (e.g., 'users/abc123') */\n  docPath: string;\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to document data. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for collection queries.\n */\nexport interface FirestoreCollectionOptions<T> extends FirestoreBaseOptions {\n  /** Collection path (e.g., 'users' or 'entities/abc/members') */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy, etc.) */\n  constraints?: QueryConstraint[];\n  /** Enable realtime updates via onSnapshot (default: false) */\n  subscribe?: boolean;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for infinite scroll queries.\n */\nexport interface FirestoreInfiniteOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, orderBy - required for pagination) */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 20) */\n  pageSize?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for paginated queries with page numbers.\n */\nexport interface FirestorePaginatedOptions<T> extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints */\n  constraints?: QueryConstraint[];\n  /** Number of items per page (default: 10) */\n  pageSize?: number;\n  /** Initial page number (default: 1) */\n  initialPage?: number;\n  /** Re-read the displayed page every `refetchInterval` ms while it is mounted (omit for none). */\n  refetchInterval?: number;\n  /** Transform function applied to each document. Receives data WITH id included. */\n  select?: (data: DocumentData & { id: string }) => T;\n}\n\n/**\n * Options for count() aggregation queries.\n */\nexport interface FirestoreCountOptions extends FirestoreBaseOptions {\n  /** Collection path */\n  collectionPath: string;\n  /** Firestore query constraints (where, etc.) applied before counting */\n  constraints?: QueryConstraint[];\n  /** Polling interval in ms (omit for no polling) */\n  refetchInterval?: number;\n}\n\n/**\n * Options for a live newest-window + cursor-bridged older-pages list\n * (e.g. chat messages, live comment threads, live activity feeds). The newest\n * page is a realtime onSnapshot window; older pages load on demand via getDocs,\n * seeded from the window's oldest document so there is no gap or re-read.\n */\nexport interface FirestoreLiveInfiniteOptions<T = DocumentData & { id: string }> {\n  /** Collection path (slash-joined for nested paths, e.g. 'chats/t1/messages'). */\n  collectionPath: string;\n  /** React Query cache key. The older-pages query is keyed under `[...queryKey, 'older']`. */\n  queryKey: readonly unknown[];\n  /** Field both the live window and older pages order by (descending under the hood). */\n  orderByField: string;\n  /** Equality/filter constraints. Do NOT pass orderBy/limit/startAfter — the hook adds those. */\n  constraints?: QueryConstraint[];\n  /** Items per page / live-window size (default 20, capped at 100). */\n  pageSize?: number;\n  /** When false, no listener is opened and no pages are fetched. */\n  enabled?: boolean;\n  /** Map each raw doc (id included) to the item shape. Default: identity (WithId). */\n  select?: (data: DocumentData & { id: string }) => T;\n  /** Output ordering of the merged list, by `orderByField` as Firestore orders it. Default 'asc' (oldest → newest). */\n  sort?: 'asc' | 'desc';\n}\n\n/**\n * Result page for infinite queries.\n */\nexport interface InfinitePage<T> {\n  items: WithId<T>[];\n  lastDoc: DocumentSnapshot | null;\n  size: number;\n}\n\n/**\n * One page's cache entry for `useFirestorePaginated`, stored at `[...queryKey, 'page', n]`:\n * the page's rows, its last row (the next page's cursor; `null` for an empty page), and\n * whether a further page exists (read with a one-row look-ahead), and the id of the row it\n * was read after (`null` for page 1), checked against the previous page's cursor.\n */\nexport interface PaginatedPage<T> {\n  items: T[];\n  cursor: DocumentSnapshot | null;\n  hasMore: boolean;\n  after: string | null;\n}\n\n/**\n * Mutation operation types for batch mutations.\n */\nexport type MutationOperation =\n  | { type: 'set'; docPath: string; data: DocumentData; merge?: boolean }\n  | { type: 'update'; docPath: string; data: DocumentData }\n  | { type: 'delete'; docPath: string };\n\n/**\n * Options for document mutations.\n */\nexport interface FirestoreMutationOptions<T> {\n  /** Document path for single-doc mutations */\n  docPath?: string;\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Enable optimistic updates */\n  optimistic?: {\n    /** Query key of the cache to update */\n    queryKey: readonly unknown[];\n    /** How to update the cached data */\n    updater: (oldData: T | undefined, newData: Partial<T>) => T;\n  };\n}\n\n/**\n * Options for batch mutations.\n */\nexport interface FirestoreBatchOptions {\n  /** Query keys to invalidate on success */\n  invalidateKeys?: readonly unknown[][];\n  /** Max operations per batch (default: 450) */\n  batchSize?: number;\n}\n"]}

package/dist/react/firestore/subscription-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscription-status.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAuC,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEtF,yHAAyH;AACzH,UAAU,cAAc;IACtB,gGAAgG;IAChG,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC;AAM9E;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM;;;;;;oBAc1C,WAAW,GAAG,CAAC,CAAC,IAAI,EAAE,kBAAkB,KAAK,WAAW,CAAC;mBAkBnC,OAAO;EAwBxC;AAED,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAQtE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,KAAK,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EACnC,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CA6F/C"}
+{"version":3,"file":"subscription-status.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAuC,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEtF,yHAAyH;AACzH,UAAU,cAAc;IACtB,gGAAgG;IAChG,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC;AAM9E;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM;;;;;;oBAc1C,WAAW,GAAG,CAAC,CAAC,IAAI,EAAE,kBAAkB,KAAK,WAAW,CAAC;mBAkBnC,OAAO;EAwBxC;AAED,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAQtE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,KAAK,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EACnC,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAwG/C"}

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

@@ -132,6 +132,18 @@ export function useSubscribedResult(query, subscribe, enabled, status) {
             refetch,
         };
     }
+    else if (active && query.isPending) {
+        // The listener has not delivered its first snapshot. The query underneath is disabled in
+        // subscribe mode, so it reports pending but not loading; the read IS loading, exactly like a
+        // one-shot read's first fetch — never an answered absence.
+        result = {
+            ...query,
+            isLoading: true,
+            isFetching: true,
+            fetchStatus: 'fetching',
+            refetch,
+        };
+    }
     else {
         result = { ...query, refetch };
     }

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":"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","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"]}
+{"version":3,"file":"subscription-status.js","sourceRoot":"","sources":["../../../src/react/firestore/subscription-status.ts"],"names":[],"mappings":"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","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 if (active && query.isPending) {\n    // The listener has not delivered its first snapshot. The query underneath is disabled in\n    // subscribe mode, so it reports pending but not loading; the read IS loading, exactly like a\n    // one-shot read's first fetch — never an answered absence.\n    result = {\n      ...query,\n      isLoading: true,\n      isFetching: true,\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/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;AAEzE,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;AAqBF;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAyLzD"}
+{"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,CAkMzD"}

package/dist/react/firestore/useBatchFirestoreDocs.js

@@ -4,15 +4,19 @@ import { useQueries, useQueryClient } from '@tanstack/react-query';
 import { isListenerOwned, listenerErrorOf, subscribeDoc } from './doc-subscription-registry.js';
 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';
 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 === 'failed')
-        return a.error === b.error;
+    if (a.status === 'failed') {
+        const other = b;
+        return a.error === other.error && a.retrying === other.retrying;
+    }
     return true;
 }
 function shallowRecordEqual(a, b) {
@@ -147,6 +151,12 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
     // pointing at 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`.
+    const retryStates = useReadRetryStates(uniqueIds.map((id, index) => ({
+        source: (results[index] ?? IDLE_SOURCE),
+        queryKey: [queryKeyPrefix, id],
+    })));
     const nextData = {};
     const nextOutcomes = {};
     let anyError = null;
@@ -166,10 +176,11 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
         if (result && (result.isFetching || result.isPaused) && result.errorUpdatedAt > result.dataUpdatedAt) {
             failedReadsRunning = true;
         }
-        if (result?.isError) {
-            const error = result.error;
-            anyError ??= error;
-            outcome = { status: 'failed', error };
+        const retryState = retryStates[index];
+        if (result?.isError)
+            anyError ??= result.error;
+        if (retryState && retryState.error !== null) {
+            outcome = { status: 'failed', error: retryState.error, retrying: retryState.isRetrying };
         }
         else if (result) {
             if (result.isLoading)
@@ -179,7 +190,7 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
                 anyUnresolved = true;
             if (listenerError) {
                 anyListenerError ??= listenerError;
-                outcome = { status: 'failed', error: listenerError };
+                outcome = { status: 'failed', error: listenerError, retrying: false };
             }
             else if (value === null) {
                 outcome = ABSENT_OUTCOME;

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';\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 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') return a.error === (b as { error: Error }).error;\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' ? await loader.loadOne(id, signal) : 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) => (errors[id] === error ? errors : { ...errors, [id]: error })),\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  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 (result && (result.isFetching || result.isPaused) && result.errorUpdatedAt > result.dataUpdatedAt) {\n      failedReadsRunning = true;\n    }\n    if (result?.isError) {\n      const error = result.error as Error;\n      anyError ??= error;\n      outcome = { status: 'failed', error };\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 };\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';\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' ? await loader.loadOne(id, signal) : 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) => (errors[id] === error ? errors : { ...errors, [id]: error })),\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 (result && (result.isFetching || result.isPaused) && result.errorUpdatedAt > result.dataUpdatedAt) {\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"]}

package/dist/react/index.d.ts

@@ -18,6 +18,6 @@ export { useBatchFirestoreDocs, } from './firestore/useBatchFirestoreDocs.js';
 export type { BatchFirestoreDocsOptions, BatchFirestoreDocsResult, BatchFirestoreDocsTransport, } from './firestore/useBatchFirestoreDocs.js';
 export { ABSENT_RETRY_DELAYS_MS } from './firestore/absence-scheduler.js';
 export { useFirestoreSearch } from './search/use-firestore-search.js';
-export { useReadRetryState } from './use-read-retry-state.js';
-export type { ReadRetrySource, ReadRetryState } from './use-read-retry-state.js';
+export { useReadRetryState, useReadRetryStates } from './use-read-retry-state.js';
+export type { ReadRetryEntry, ReadRetrySource, ReadRetryState } from './use-read-retry-state.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAGnE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGrE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC7G,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAC/E,YAAY,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AACtF,YAAY,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AAG9F,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAGhD,OAAO,EACL,qBAAqB,GACtB,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAG1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAGtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAGnE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGrE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC7G,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAC/E,YAAY,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AACtF,YAAY,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AAG9F,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAGhD,OAAO,EACL,qBAAqB,GACtB,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAG1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAGtE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/react/index.js

@@ -20,5 +20,5 @@ export { ABSENT_RETRY_DELAYS_MS } from './firestore/absence-scheduler.js';
 // Search Hook
 export { useFirestoreSearch } from './search/use-firestore-search.js';
 // Read retry state
-export { useReadRetryState } from './use-read-retry-state.js';
+export { useReadRetryState, useReadRetryStates } from './use-read-retry-state.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,qEAAqE;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,qBAAqB;AACrB,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG3E,wBAAwB;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AAEjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAE/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AAGtF,2BAA2B;AAC3B,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAEhD,uBAAuB;AACvB,OAAO,EACL,qBAAqB,GACtB,MAAM,sCAAsC,CAAC;AAM9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E,cAAc;AACd,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,mBAAmB;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC","sourcesContent":["\"use client\";\n\n// Query Client factory (client-only; requires @tanstack/react-query)\nexport { createQueryClient } from '../query-client.js';\nexport type { CreateQueryClientOptions } from '../query-client.js';\n\n// Provider\nexport { QueryProvider } from './provider.js';\nexport type { QueryProviderProps } from './provider.js';\n\n// Firestore Provider\nexport { FirestoreProvider, useFirestoreDb } from './firestore/context.js';\nexport type { FirestoreProviderProps } from './firestore/context.js';\n\n// Firestore Query Hooks\nexport { useFirestoreDoc } from './firestore/use-firestore-doc.js';\nexport { useFirestoreCollection } from './firestore/use-firestore-collection.js';\nexport type { FirestoreSourceState, WithSourceState, BatchFirestoreDocOutcome } from '../firestore/types.js';\nexport { useFirestoreInfinite } from './firestore/use-firestore-infinite.js';\nexport { useFirestorePaginated } from './firestore/use-firestore-paginated.js';\nexport type { UseFirestorePaginatedResult } from './firestore/use-firestore-paginated.js';\nexport { useFirestoreCount } from './firestore/use-firestore-count.js';\nexport { useFirestoreLiveInfinite } from './firestore/use-firestore-live-infinite.js';\nexport type { FirestoreLiveInfiniteResult } from './firestore/use-firestore-live-infinite.js';\n\n// Firestore Mutation Hooks\nexport {\n  useFirestoreSet,\n  useFirestoreUpdate,\n  useFirestoreDelete,\n  useFirestoreBatch,\n} from './firestore/use-firestore-mutations.js';\n\n// Batch Firestore Docs\nexport {\n  useBatchFirestoreDocs,\n} from './firestore/useBatchFirestoreDocs.js';\nexport type {\n  BatchFirestoreDocsOptions,\n  BatchFirestoreDocsResult,\n  BatchFirestoreDocsTransport,\n} from './firestore/useBatchFirestoreDocs.js';\nexport { ABSENT_RETRY_DELAYS_MS } from './firestore/absence-scheduler.js';\n\n// Search Hook\nexport { useFirestoreSearch } from './search/use-firestore-search.js';\n\n// Read retry state\nexport { useReadRetryState } from './use-read-retry-state.js';\nexport type { ReadRetrySource, ReadRetryState } from './use-read-retry-state.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,qEAAqE;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,qBAAqB;AACrB,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG3E,wBAAwB;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AAEjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAE/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AAGtF,2BAA2B;AAC3B,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAEhD,uBAAuB;AACvB,OAAO,EACL,qBAAqB,GACtB,MAAM,sCAAsC,CAAC;AAM9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E,cAAc;AACd,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,mBAAmB;AACnB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC","sourcesContent":["\"use client\";\n\n// Query Client factory (client-only; requires @tanstack/react-query)\nexport { createQueryClient } from '../query-client.js';\nexport type { CreateQueryClientOptions } from '../query-client.js';\n\n// Provider\nexport { QueryProvider } from './provider.js';\nexport type { QueryProviderProps } from './provider.js';\n\n// Firestore Provider\nexport { FirestoreProvider, useFirestoreDb } from './firestore/context.js';\nexport type { FirestoreProviderProps } from './firestore/context.js';\n\n// Firestore Query Hooks\nexport { useFirestoreDoc } from './firestore/use-firestore-doc.js';\nexport { useFirestoreCollection } from './firestore/use-firestore-collection.js';\nexport type { FirestoreSourceState, WithSourceState, BatchFirestoreDocOutcome } from '../firestore/types.js';\nexport { useFirestoreInfinite } from './firestore/use-firestore-infinite.js';\nexport { useFirestorePaginated } from './firestore/use-firestore-paginated.js';\nexport type { UseFirestorePaginatedResult } from './firestore/use-firestore-paginated.js';\nexport { useFirestoreCount } from './firestore/use-firestore-count.js';\nexport { useFirestoreLiveInfinite } from './firestore/use-firestore-live-infinite.js';\nexport type { FirestoreLiveInfiniteResult } from './firestore/use-firestore-live-infinite.js';\n\n// Firestore Mutation Hooks\nexport {\n  useFirestoreSet,\n  useFirestoreUpdate,\n  useFirestoreDelete,\n  useFirestoreBatch,\n} from './firestore/use-firestore-mutations.js';\n\n// Batch Firestore Docs\nexport {\n  useBatchFirestoreDocs,\n} from './firestore/useBatchFirestoreDocs.js';\nexport type {\n  BatchFirestoreDocsOptions,\n  BatchFirestoreDocsResult,\n  BatchFirestoreDocsTransport,\n} from './firestore/useBatchFirestoreDocs.js';\nexport { ABSENT_RETRY_DELAYS_MS } from './firestore/absence-scheduler.js';\n\n// Search Hook\nexport { useFirestoreSearch } from './search/use-firestore-search.js';\n\n// Read retry state\nexport { useReadRetryState, useReadRetryStates } from './use-read-retry-state.js';\nexport type { ReadRetryEntry, ReadRetrySource, ReadRetryState } from './use-read-retry-state.js';\n"]}

package/dist/react/use-read-retry-state.d.ts

@@ -16,6 +16,18 @@ export interface ReadRetryState<TError = Error> {
     /** The read has not answered yet and is not a retry of a failure. */
     isLoading: boolean;
 }
+/** One read a keyed retry state follows: its result and its identity. */
+export interface ReadRetryEntry<TError = Error> {
+    source: ReadRetrySource<TError>;
+    queryKey: QueryKey;
+}
+/**
+ * The failure and retry state of each of several reads, in entry order — the keyed form of
+ * `useReadRetryState` for a set whose size changes between renders (a `useQueries` list, a batch
+ * of per-id reads). Each read's failure is held under its own `queryKey`, so one read's retry
+ * never shows another's failure, and a read that leaves the set drops what it held.
+ */
+export declare function useReadRetryStates<TError = Error>(entries: readonly ReadRetryEntry<TError>[]): ReadRetryState<TError>[];
 /**
  * The failure and retry state of one read. TanStack Query clears the `error` of a query that never
  * succeeded and puts it back to `pending` the moment a refetch of it starts, so a retry state built

package/dist/react/use-read-retry-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-read-retry-state.d.ts","sourceRoot":"","sources":["../../src/react/use-read-retry-state.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE/D,oEAAoE;AACpE,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,KAAK;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,KAAK;IAC5C,2FAA2F;IAC3F,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;CACpB;AAoBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAG,KAAK,EAC9C,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,QAAQ,GACjB,cAAc,CAAC,MAAM,CAAC,CAqBxB"}
+{"version":3,"file":"use-read-retry-state.d.ts","sourceRoot":"","sources":["../../src/react/use-read-retry-state.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE/D,oEAAoE;AACpE,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,KAAK;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,KAAK;IAC5C,2FAA2F;IAC3F,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;CACpB;AAmBD,yEAAyE;AACzE,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,KAAK;IAC5C,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAsBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAG,KAAK,EAC/C,OAAO,EAAE,SAAS,cAAc,CAAC,MAAM,CAAC,EAAE,GACzC,cAAc,CAAC,MAAM,CAAC,EAAE,CAa1B;AAUD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAG,KAAK,EAC9C,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,QAAQ,GACjB,cAAc,CAAC,MAAM,CAAC,CAExB"}

package/dist/react/use-read-retry-state.js

@@ -15,6 +15,47 @@ function sameFailure(a, b) {
     const y = b;
     return x.name === y.name && x.message === y.message && x.code === y.code;
 }
+/** The failure a read holds next, given what it held: its live failure, or the held one while it runs. */
+function nextHeldFailure(held, source) {
+    const live = source.error ?? null;
+    if (live !== null)
+        return held !== undefined && sameFailure(held.error, live) ? held : { error: live };
+    const running = source.isFetching || source.isPaused === true;
+    return running ? held : undefined;
+}
+function toRetryState(source, held) {
+    const error = source.error ?? held?.error ?? null;
+    return {
+        error,
+        isRetrying: error !== null && (source.isFetching || source.isPaused === true),
+        isLoading: error === null && source.isLoading,
+    };
+}
+/**
+ * The failure and retry state of each of several reads, in entry order — the keyed form of
+ * `useReadRetryState` for a set whose size changes between renders (a `useQueries` list, a batch
+ * of per-id reads). Each read's failure is held under its own `queryKey`, so one read's retry
+ * never shows another's failure, and a read that leaves the set drops what it held.
+ */
+export function useReadRetryStates(entries) {
+    const [held, setHeld] = useState({});
+    const next = {};
+    const states = entries.map(({ source, queryKey }) => {
+        const identity = hashKey(queryKey);
+        const failure = nextHeldFailure(held[identity], source);
+        if (failure !== undefined)
+            next[identity] = failure;
+        return toRetryState(source, failure);
+    });
+    // Render-phase adjustment: the held failures follow the reads without an effect's extra render.
+    if (!sameHeld(held, next))
+        setHeld(next);
+    return states;
+}
+function sameHeld(a, b) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}
 /**
  * The failure and retry state of one read. TanStack Query clears the `error` of a query that never
  * succeeded and puts it back to `pending` the moment a refetch of it starts, so a retry state built
@@ -24,26 +65,6 @@ function sameFailure(a, b) {
  * meanwhile. The failure belongs to `queryKey`: a read under another key never shows it.
  */
 export function useReadRetryState(source, queryKey) {
-    const identity = hashKey(queryKey);
-    const live = source.error ?? null;
-    const running = source.isFetching || source.isPaused === true;
-    const [held, setHeld] = useState(null);
-    let next = held !== null && held.identity === identity ? held : null;
-    if (live !== null) {
-        if (next === null || !sameFailure(next.error, live))
-            next = { identity, error: live };
-    }
-    else if (!running) {
-        next = null;
-    }
-    // Render-phase adjustment: the held failure follows the read without an effect's extra render.
-    if (next !== held)
-        setHeld(next);
-    const error = live ?? next?.error ?? null;
-    return {
-        error,
-        isRetrying: error !== null && running,
-        isLoading: error === null && source.isLoading,
-    };
+    return useReadRetryStates([{ source, queryKey }])[0];
 }
 //# sourceMappingURL=use-read-retry-state.js.map

package/dist/react/use-read-retry-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-read-retry-state.js","sourceRoot":"","sources":["../../src/react/use-read-retry-state.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,OAAO,EAAiB,MAAM,uBAAuB,CAAC;AA0B/D;;;;GAIG;AACH,SAAS,WAAW,CAAC,CAAU,EAAE,CAAU;IACzC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC7F,MAAM,CAAC,GAAG,CAA0D,CAAC;IACrE,MAAM,CAAC,GAAG,CAA0D,CAAC;IACrE,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC;AAC3E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA+B,EAC/B,QAAkB;IAElB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC;IAClC,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC;IAC9D,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAA6B,IAAI,CAAC,CAAC;IAEnE,IAAI,IAAI,GAAG,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC;YAAE,IAAI,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxF,CAAC;SAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IACD,+FAA+F;IAC/F,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC;IAC1C,OAAO;QACL,KAAK;QACL,UAAU,EAAE,KAAK,KAAK,IAAI,IAAI,OAAO;QACrC,SAAS,EAAE,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,SAAS;KAC9C,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport { useState } from 'react';\nimport { hashKey, type QueryKey } from '@tanstack/react-query';\n\n/** The parts of a read's result the retry state is decided from. */\nexport interface ReadRetrySource<TError = Error> {\n  error: TError | null | undefined;\n  isFetching: boolean;\n  isLoading: boolean;\n  /** A fetch waiting for the network counts as still running. */\n  isPaused?: boolean;\n}\n\n/** A read's failure as its surface shows it, held on screen while a retry of it runs. */\nexport interface ReadRetryState<TError = Error> {\n  /** The read's failure: its current one, or the last one while a retry of it is running. */\n  error: TError | null;\n  /** A retry of the failed read is running. */\n  isRetrying: boolean;\n  /** The read has not answered yet and is not a retry of a failure. */\n  isLoading: boolean;\n}\n\ninterface HeldFailure<TError> {\n  identity: string;\n  error: TError;\n}\n\n/**\n * One failure is its name, message, and `code`, not its object: a composite source that builds its\n * error in render hands back a new object for the same failure every render, and holding each one\n * as new would set state on every render without end.\n */\nfunction sameFailure(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) return false;\n  const x = a as { name?: unknown; message?: unknown; code?: unknown };\n  const y = b as { name?: unknown; message?: unknown; code?: unknown };\n  return x.name === y.name && x.message === y.message && x.code === y.code;\n}\n\n/**\n * The failure and retry state of one read. TanStack Query clears the `error` of a query that never\n * succeeded and puts it back to `pending` the moment a refetch of it starts, so a retry state built\n * from `isFetching && error` is never true for a failed first read, and its failure panel turns into\n * a loading state under the retry the person pressed. This holds the read's last failure until the\n * retry settles — an answer clears it, a new failure replaces it — and reports the retry as running\n * meanwhile. The failure belongs to `queryKey`: a read under another key never shows it.\n */\nexport function useReadRetryState<TError = Error>(\n  source: ReadRetrySource<TError>,\n  queryKey: QueryKey,\n): ReadRetryState<TError> {\n  const identity = hashKey(queryKey);\n  const live = source.error ?? null;\n  const running = source.isFetching || source.isPaused === true;\n  const [held, setHeld] = useState<HeldFailure<TError> | null>(null);\n\n  let next = held !== null && held.identity === identity ? held : null;\n  if (live !== null) {\n    if (next === null || !sameFailure(next.error, live)) next = { identity, error: live };\n  } else if (!running) {\n    next = null;\n  }\n  // Render-phase adjustment: the held failure follows the read without an effect's extra render.\n  if (next !== held) setHeld(next);\n\n  const error = live ?? next?.error ?? null;\n  return {\n    error,\n    isRetrying: error !== null && running,\n    isLoading: error === null && source.isLoading,\n  };\n}\n"]}
+{"version":3,"file":"use-read-retry-state.js","sourceRoot":"","sources":["../../src/react/use-read-retry-state.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\nimport { useState } from 'react';\nimport { hashKey, type QueryKey } from '@tanstack/react-query';\n\n/** The parts of a read's result the retry state is decided from. */\nexport interface ReadRetrySource<TError = Error> {\n  error: TError | null | undefined;\n  isFetching: boolean;\n  isLoading: boolean;\n  /** A fetch waiting for the network counts as still running. */\n  isPaused?: boolean;\n}\n\n/** A read's failure as its surface shows it, held on screen while a retry of it runs. */\nexport interface ReadRetryState<TError = Error> {\n  /** The read's failure: its current one, or the last one while a retry of it is running. */\n  error: TError | null;\n  /** A retry of the failed read is running. */\n  isRetrying: boolean;\n  /** The read has not answered yet and is not a retry of a failure. */\n  isLoading: boolean;\n}\n\ninterface HeldFailure<TError> {\n  error: TError;\n}\n\n/**\n * One failure is its name, message, and `code`, not its object: a composite source that builds its\n * error in render hands back a new object for the same failure every render, and holding each one\n * as new would set state on every render without end.\n */\nfunction sameFailure(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) return false;\n  const x = a as { name?: unknown; message?: unknown; code?: unknown };\n  const y = b as { name?: unknown; message?: unknown; code?: unknown };\n  return x.name === y.name && x.message === y.message && x.code === y.code;\n}\n\n/** One read a keyed retry state follows: its result and its identity. */\nexport interface ReadRetryEntry<TError = Error> {\n  source: ReadRetrySource<TError>;\n  queryKey: QueryKey;\n}\n\n/** The failure a read holds next, given what it held: its live failure, or the held one while it runs. */\nfunction nextHeldFailure<TError>(\n  held: HeldFailure<TError> | undefined,\n  source: ReadRetrySource<TError>,\n): HeldFailure<TError> | undefined {\n  const live = source.error ?? null;\n  if (live !== null) return held !== undefined && sameFailure(held.error, live) ? held : { error: live };\n  const running = source.isFetching || source.isPaused === true;\n  return running ? held : undefined;\n}\n\nfunction toRetryState<TError>(source: ReadRetrySource<TError>, held: HeldFailure<TError> | undefined): ReadRetryState<TError> {\n  const error = source.error ?? held?.error ?? null;\n  return {\n    error,\n    isRetrying: error !== null && (source.isFetching || source.isPaused === true),\n    isLoading: error === null && source.isLoading,\n  };\n}\n\n/**\n * The failure and retry state of each of several reads, in entry order — the keyed form of\n * `useReadRetryState` for a set whose size changes between renders (a `useQueries` list, a batch\n * of per-id reads). Each read's failure is held under its own `queryKey`, so one read's retry\n * never shows another's failure, and a read that leaves the set drops what it held.\n */\nexport function useReadRetryStates<TError = Error>(\n  entries: readonly ReadRetryEntry<TError>[],\n): ReadRetryState<TError>[] {\n  const [held, setHeld] = useState<Readonly<Record<string, HeldFailure<TError>>>>({});\n\n  const next: Record<string, HeldFailure<TError>> = {};\n  const states = entries.map(({ source, queryKey }) => {\n    const identity = hashKey(queryKey);\n    const failure = nextHeldFailure(held[identity], source);\n    if (failure !== undefined) next[identity] = failure;\n    return toRetryState(source, failure);\n  });\n  // Render-phase adjustment: the held failures follow the reads without an effect's extra render.\n  if (!sameHeld(held, next)) setHeld(next);\n  return states;\n}\n\nfunction sameHeld<TError>(\n  a: Readonly<Record<string, HeldFailure<TError>>>,\n  b: Readonly<Record<string, HeldFailure<TError>>>,\n): boolean {\n  const keys = Object.keys(a);\n  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);\n}\n\n/**\n * The failure and retry state of one read. TanStack Query clears the `error` of a query that never\n * succeeded and puts it back to `pending` the moment a refetch of it starts, so a retry state built\n * from `isFetching && error` is never true for a failed first read, and its failure panel turns into\n * a loading state under the retry the person pressed. This holds the read's last failure until the\n * retry settles — an answer clears it, a new failure replaces it — and reports the retry as running\n * meanwhile. The failure belongs to `queryKey`: a read under another key never shows it.\n */\nexport function useReadRetryState<TError = Error>(\n  source: ReadRetrySource<TError>,\n  queryKey: QueryKey,\n): ReadRetryState<TError> {\n  return useReadRetryStates([{ source, queryKey }])[0]!;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/query-core",
-  "version": "0.14.13",
+  "version": "0.14.15",
   "description": "Shared TanStack Query (React Query) client defaults, query key helpers, and Firestore integration hooks for TTT Productions apps",
   "repository": {
     "type": "git",