@ttt-productions/query-core 0.14.21 → 0.14.23

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

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

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

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

package/dist/react/firestore/useBatchFirestoreDocs.js

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

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

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

package/dist/react/index.d.ts

@@ -1,12 +1,11 @@
-export { createQueryClient } from '../query-client.js';
-export type { CreateQueryClientOptions } from '../query-client.js';
+export { createQueryClient } from './query-client.js';
+export type { CreateQueryClientOptions } from './query-client.js';
 export { QueryProvider } from './provider.js';
 export type { QueryProviderProps } from './provider.js';
 export { FirestoreProvider, useFirestoreDb } from './firestore/context.js';
 export type { FirestoreProviderProps } from './firestore/context.js';
 export { useFirestoreDoc } from './firestore/use-firestore-doc.js';
 export { useFirestoreCollection } from './firestore/use-firestore-collection.js';
-export type { FirestoreSourceState, WithSourceState, BatchFirestoreDocOutcome } from '../firestore/types.js';
 export { useFirestoreInfinite } from './firestore/use-firestore-infinite.js';
 export { useFirestorePaginated } from './firestore/use-firestore-paginated.js';
 export type { UseFirestorePaginatedResult } from './firestore/use-firestore-paginated.js';
@@ -14,10 +13,20 @@ export { useFirestoreCount } from './firestore/use-firestore-count.js';
 export { useFirestoreLiveInfinite } from './firestore/use-firestore-live-infinite.js';
 export type { FirestoreLiveInfiniteResult } from './firestore/use-firestore-live-infinite.js';
 export { useFirestoreSet, useFirestoreUpdate, useFirestoreDelete, useFirestoreBatch, } from './firestore/use-firestore-mutations.js';
-export { useBatchFirestoreDocs, } from './firestore/useBatchFirestoreDocs.js';
+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 { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, placeRowInPages, } from './cache-helpers.js';
+export type { PagedRows } from './cache-helpers.js';
+export { createDomainEventInvalidator } from './domain-events/create-domain-event-invalidator.js';
+export { exact, prefix, predicate, serializeInvalidation, applyInvalidations, } from './domain-events/cache-invalidation.js';
+export type { DomainEventInvalidator, DomainEventInvalidationRegistry, } from './domain-events/create-domain-event-invalidator.js';
+export type { CacheAction, CacheInvalidation, RefetchType, } from './domain-events/cache-invalidation.js';
+export { docWithId } from './firestore/types.js';
+export type { FirestoreDocOptions, FirestoreCollectionOptions, FirestoreInfiniteOptions, FirestorePaginatedOptions, FirestoreCountOptions, FirestoreLiveInfiniteOptions, InfinitePage, PaginatedPage, MutationOperation, } from './firestore/types.js';
+export { flattenInfiniteData, getInfiniteDataCount } from './firestore/infinite-helpers.js';
+export type { FirestoreSearchOptions } from './search/types.js';
 export { useReadRetryState, useReadRetryStates } from './use-read-retry-state.js';
 export type { ReadRetryEntry, ReadRetrySource, ReadRetryState } from './use-read-retry-state.js';
 export { usePendingMutationVariables, pendingMutationVariables, usePendingMutationTargets, hasPendingMutation, duplicateSubmissionError, useDuplicateGuardedMutation, } from './pending-mutations.js';

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,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIjG,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,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;AAE9F,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,4BAA4B,EAAE,MAAM,oDAAoD,CAAC;AAClG,OAAO,EACL,KAAK,EACL,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,oDAAoD,CAAC;AAC5D,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,WAAW,GACZ,MAAM,uCAAuC,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,4BAA4B,EAC5B,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5F,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEjG,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC"}

package/dist/react/index.js

@@ -1,27 +1,22 @@
-"use client";
-// Query Client factory (client-only; requires @tanstack/react-query)
-export { createQueryClient } from '../query-client.js';
-// Provider
+'use client';
+export { createQueryClient } from './query-client.js';
 export { QueryProvider } from './provider.js';
-// Firestore Provider
 export { FirestoreProvider, useFirestoreDb } from './firestore/context.js';
-// Firestore Query Hooks
 export { useFirestoreDoc } from './firestore/use-firestore-doc.js';
 export { useFirestoreCollection } from './firestore/use-firestore-collection.js';
 export { useFirestoreInfinite } from './firestore/use-firestore-infinite.js';
 export { useFirestorePaginated } from './firestore/use-firestore-paginated.js';
 export { useFirestoreCount } from './firestore/use-firestore-count.js';
 export { useFirestoreLiveInfinite } from './firestore/use-firestore-live-infinite.js';
-// Firestore Mutation Hooks
 export { useFirestoreSet, useFirestoreUpdate, useFirestoreDelete, useFirestoreBatch, } from './firestore/use-firestore-mutations.js';
-// Batch Firestore Docs
-export { useBatchFirestoreDocs, } from './firestore/useBatchFirestoreDocs.js';
+export { useBatchFirestoreDocs } from './firestore/useBatchFirestoreDocs.js';
 export { ABSENT_RETRY_DELAYS_MS } from './firestore/absence-scheduler.js';
-// Search Hook
 export { useFirestoreSearch } from './search/use-firestore-search.js';
-// Read retry state
+export { invalidateByPrefix, removeByPrefix, updateQueryData, paginatedPageKey, mapPaginatedItems, prependToFirstPaginatedPage, placeRowInPages, } from './cache-helpers.js';
+export { createDomainEventInvalidator } from './domain-events/create-domain-event-invalidator.js';
+export { exact, prefix, predicate, serializeInvalidation, applyInvalidations, } from './domain-events/cache-invalidation.js';
+export { docWithId } from './firestore/types.js';
+export { flattenInfiniteData, getInfiniteDataCount } from './firestore/infinite-helpers.js';
 export { useReadRetryState, useReadRetryStates } from './use-read-retry-state.js';
-// Authoritative pending for interactive mutations: in-flight state and duplicate guards read from
-// the shared MutationCache under the app's stable mutation keys.
 export { usePendingMutationVariables, pendingMutationVariables, usePendingMutationTargets, hasPendingMutation, duplicateSubmissionError, useDuplicateGuardedMutation, } from './pending-mutations.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,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGlF,kGAAkG;AAClG,iEAAiE;AACjE,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,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\n// Authoritative pending for interactive mutations: in-flight state and duplicate guards read from\n// the shared MutationCache under the app's stable mutation keys.\nexport {\n  usePendingMutationVariables,\n  pendingMutationVariables,\n  usePendingMutationTargets,\n  hasPendingMutation,\n  duplicateSubmissionError,\n  useDuplicateGuardedMutation,\n} from './pending-mutations.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,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,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAM7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,oDAAoD,CAAC;AAClG,OAAO,EACL,KAAK,EACL,MAAM,EACN,SAAS,EACT,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uCAAuC,CAAC;AAW/C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAYjD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAG5F,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGlF,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC","sourcesContent":["'use client';\n\nexport { createQueryClient } from './query-client.js';\nexport type { CreateQueryClientOptions } from './query-client.js';\n\nexport { QueryProvider } from './provider.js';\nexport type { QueryProviderProps } from './provider.js';\n\nexport { FirestoreProvider, useFirestoreDb } from './firestore/context.js';\nexport type { FirestoreProviderProps } from './firestore/context.js';\n\nexport { useFirestoreDoc } from './firestore/use-firestore-doc.js';\nexport { useFirestoreCollection } from './firestore/use-firestore-collection.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\nexport {\n  useFirestoreSet,\n  useFirestoreUpdate,\n  useFirestoreDelete,\n  useFirestoreBatch,\n} from './firestore/use-firestore-mutations.js';\n\nexport { useBatchFirestoreDocs } 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\nexport { useFirestoreSearch } from './search/use-firestore-search.js';\n\nexport {\n  invalidateByPrefix,\n  removeByPrefix,\n  updateQueryData,\n  paginatedPageKey,\n  mapPaginatedItems,\n  prependToFirstPaginatedPage,\n  placeRowInPages,\n} from './cache-helpers.js';\nexport type { PagedRows } from './cache-helpers.js';\n\nexport { createDomainEventInvalidator } from './domain-events/create-domain-event-invalidator.js';\nexport {\n  exact,\n  prefix,\n  predicate,\n  serializeInvalidation,\n  applyInvalidations,\n} from './domain-events/cache-invalidation.js';\nexport type {\n  DomainEventInvalidator,\n  DomainEventInvalidationRegistry,\n} from './domain-events/create-domain-event-invalidator.js';\nexport type {\n  CacheAction,\n  CacheInvalidation,\n  RefetchType,\n} from './domain-events/cache-invalidation.js';\n\nexport { docWithId } from './firestore/types.js';\nexport type {\n  FirestoreDocOptions,\n  FirestoreCollectionOptions,\n  FirestoreInfiniteOptions,\n  FirestorePaginatedOptions,\n  FirestoreCountOptions,\n  FirestoreLiveInfiniteOptions,\n  InfinitePage,\n  PaginatedPage,\n  MutationOperation,\n} from './firestore/types.js';\nexport { flattenInfiniteData, getInfiniteDataCount } from './firestore/infinite-helpers.js';\nexport type { FirestoreSearchOptions } from './search/types.js';\n\nexport { useReadRetryState, useReadRetryStates } from './use-read-retry-state.js';\nexport type { ReadRetryEntry, ReadRetrySource, ReadRetryState } from './use-read-retry-state.js';\n\nexport {\n  usePendingMutationVariables,\n  pendingMutationVariables,\n  usePendingMutationTargets,\n  hasPendingMutation,\n  duplicateSubmissionError,\n  useDuplicateGuardedMutation,\n} from './pending-mutations.js';\n"]}

package/dist/react/pending-mutations.d.ts

@@ -1,29 +1,9 @@
-import { type MutationKey, type QueryClient, type UseMutationResult } from "@tanstack/react-query";
-/** The variables of every pending mutation under `mutationKey` (prefix-matched), live. */
+import { type MutationKey, type QueryClient, type UseMutationResult } from '@tanstack/react-query';
 export declare function usePendingMutationVariables<V>(mutationKey: MutationKey): ReadonlyArray<V | undefined>;
-/** The variables of every pending mutation under `mutationKey`, read once — for a duplicate guard. */
 export declare function pendingMutationVariables<V>(queryClient: QueryClient, mutationKey: MutationKey): Array<V | undefined>;
-/**
- * The targets of every pending mutation under `mutationKey`, live — for a list whose rows each
- * ask "is mine pending?" through one hook call. `targetOf` names a variables' target, or returns
- * nothing for variables without one.
- */
 export declare function usePendingMutationTargets<V>(mutationKey: MutationKey, targetOf: (variables: V) => string | null | undefined): ReadonlySet<string>;
-/**
- * True when a mutation under `mutationKey` is pending — any one, or with `matches`, one whose
- * variables are for the same target.
- */
 export declare function hasPendingMutation<V>(queryClient: QueryClient, mutationKey: MutationKey, matches?: (variables: V) => boolean): boolean;
-/**
- * The rejection a guarded `mutateAsync` throws for a duplicate submission: an `AbortError`, the
- * shape a caller already treats as "nothing happened" rather than a failure to report.
- */
 export declare function duplicateSubmissionError(what: string): Error;
-/**
- * Wrap a keyed mutation's `mutate` / `mutateAsync` in the cache-consulting duplicate guard:
- * `mutate` drops a duplicate silently, and `mutateAsync` rejects it with
- * {@link duplicateSubmissionError}. `isDuplicate` must have a stable identity (declare it at module
- * level) so the guarded callbacks keep theirs.
- */
+/** `isDuplicate` must have a stable identity (declare it at module level) so the guarded callbacks keep theirs. */
 export declare function useDuplicateGuardedMutation<TData, TError, TVariables, TContext>(mutation: UseMutationResult<TData, TError, TVariables, TContext>, isDuplicate: (queryClient: QueryClient, variables: TVariables) => boolean, what: string): UseMutationResult<TData, TError, TVariables, TContext>;
 //# sourceMappingURL=pending-mutations.d.ts.map

package/dist/react/pending-mutations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending-mutations.d.ts","sourceRoot":"","sources":["../../src/react/pending-mutations.ts"],"names":[],"mappings":"AAeA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,0FAA0F;AAC1F,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,GAAG,aAAa,CAAC,CAAC,GAAG,SAAS,CAAC,CAKrG;AAED,sGAAsG;AACtG,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,WAAW,GACvB,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,CAKtB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GACpD,WAAW,CAAC,MAAM,CAAC,CAQrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,WAAW,EACxB,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO,GAClC,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAC7E,QAAQ,EAAE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,EAChE,WAAW,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,KAAK,OAAO,EACzE,IAAI,EAAE,MAAM,GACX,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAkBxD"}
+{"version":3,"file":"pending-mutations.d.ts","sourceRoot":"","sources":["../../src/react/pending-mutations.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,wBAAgB,2BAA2B,CAAC,CAAC,EAC3C,WAAW,EAAE,WAAW,GACvB,aAAa,CAAC,CAAC,GAAG,SAAS,CAAC,CAK9B;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,WAAW,GACvB,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,CAKtB;AAED,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GACpD,WAAW,CAAC,MAAM,CAAC,CAQrB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,WAAW,EACxB,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO,GAClC,OAAO,CAIT;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED,mHAAmH;AACnH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAC7E,QAAQ,EAAE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,EAChE,WAAW,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,KAAK,OAAO,EACzE,IAAI,EAAE,MAAM,GACX,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAuBxD"}