@ttt-productions/query-core 0.14.0 → 0.14.2

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

@@ -1,4 +1,6 @@
-import { type Firestore } from 'firebase/firestore';
+import type { Firestore } from 'firebase/firestore';
+/** Transport used to resolve an id in one-shot mode. */
+export type BatchFirestoreDocsTransport = 'batch' | 'get';
 export type BatchFirestoreDocsOptions = {
     /**
      * Firestore instance to use for queries
@@ -14,12 +16,13 @@ export type BatchFirestoreDocsOptions = {
     ids: string[];
     /**
      * Query key prefix for individual document cache entries
-     * Each document will be cached as [queryKeyPrefix, docId]
+     * Each document is cached as [queryKeyPrefix, docId]
      * @example 'publicUser' -> ['publicUser', 'user123']
      */
     queryKeyPrefix: string;
     /**
-     * Time in milliseconds to consider data fresh (default: 30 minutes)
+     * Time in milliseconds a PRESENT document stays fresh (default: 30 minutes).
+     * An absent document uses `absentStaleTime` instead.
      */
     staleTime?: number;
     /**
@@ -32,46 +35,85 @@ export type BatchFirestoreDocsOptions = {
     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 `getDocs` batch:
+     * 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).
-     * Initial read cost matches the batch path; listeners then stay open while mounted.
-     * Use for small, frequently-rendered, change-sensitive identity docs (e.g. publicUsers).
+     * - `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 30 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.
+     */
+    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 in Firestore
+     * 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 if any batch queries are still loading
+     * True while any requested id has not resolved yet
      */
     isLoading: boolean;
     /**
-     * True if any batch queries have errored
+     * True if any requested id is in an error state
      */
     isError: boolean;
     /**
-     * First error from batch queries, if any
+     * First error across the requested ids, if any
      */
     error: Error | null;
     /**
-     * Refetch all documents (even cached ones)
+     * Refetch every requested id, cached ones included. A no-op in subscribe mode.
      */
     refetch: () => Promise<void>;
 };
 /**
- * Efficiently batch fetch Firestore documents with individual caching
+ * 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.
  *
- * Features:
- * - Each document is cached individually for maximum reuse
- * - Only fetches documents that are missing or stale
- * - Respects Firestore's 30-item limit for 'in' queries
- * - Returns combined result as Record<docId, data>
+ * 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.
  *
  * @example
  * ```typescript
@@ -80,10 +122,10 @@ export type BatchFirestoreDocsResult<T> = {
  *   collectionPath: 'publicUsers',
  *   ids: ['user1', 'user2', 'user3'],
  *   queryKeyPrefix: 'publicUser',
- *   staleTime: 30 * 60 * 1000, // 30 minutes
+ *   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, }: BatchFirestoreDocsOptions): BatchFirestoreDocsResult<T>;
+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,EAAiD,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAKnG,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;;OAEG;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;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI;IACxC;;;OAGG;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;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;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,GAClB,EAAE,yBAAyB,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAmKzD"}
+{"version":3,"file":"useBatchFirestoreDocs.d.ts","sourceRoot":"","sources":["../../../src/react/firestore/useBatchFirestoreDocs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAKpD,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;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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,CA4IzD"}

package/dist/react/firestore/useBatchFirestoreDocs.js

@@ -1,17 +1,31 @@
 'use client';
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useQueries, useQueryClient } from '@tanstack/react-query';
-import { collection, getDocs, query, where, documentId } from 'firebase/firestore';
-import { subscribeDoc } from './doc-subscription-registry.js';
-const FIRESTORE_IN_LIMIT = 30;
+import { isListenerOwned, subscribeDoc } from './doc-subscription-registry.js';
+import { getDocLoader } from './batch-doc-loader.js';
+import { ABSENT_RETRY_DELAYS_MS, trackAbsentDoc } from './absence-scheduler.js';
+function shallowRecordEqual(a, b) {
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    for (const key of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(b, key) || a[key] !== b[key])
+            return false;
+    }
+    return true;
+}
 /**
- * Efficiently batch fetch Firestore documents with individual caching
+ * 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.
  *
- * Features:
- * - Each document is cached individually for maximum reuse
- * - Only fetches documents that are missing or stale
- * - Respects Firestore's 30-item limit for 'in' queries
- * - Returns combined result as Record<docId, data>
+ * 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.
  *
  * @example
  * ```typescript
@@ -20,12 +34,12 @@ const FIRESTORE_IN_LIMIT = 30;
  *   collectionPath: 'publicUsers',
  *   ids: ['user1', 'user2', 'user3'],
  *   queryKeyPrefix: 'publicUser',
- *   staleTime: 30 * 60 * 1000, // 30 minutes
+ *   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, }) {
+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);
@@ -35,9 +49,40 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
         return Array.from(new Set(parsed.filter(Boolean)));
     }, [idsKey]);
     // ── Real-time subscribe mode ──────────────────────────────────────────────
-    // Re-render trigger; bumped whenever a subscribed doc's snapshot lands.
-    const [snapshotVersion, setSnapshotVersion] = useState(0);
+    // Listener errors cannot surface through the per-id queries (they are disabled while
+    // subscribed), so they are tracked here and merged into the returned result.
     const [subscribeError, setSubscribeError] = useState(null);
+    // 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.
+    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.
+                if (isListenerOwned(queryClient, queryKeyPrefix, id)) {
+                    const owned = queryClient.getQueryData([queryKeyPrefix, id]);
+                    if (owned !== undefined)
+                        return owned;
+                }
+                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).
+            refetchOnMount: !subscribe,
+            staleTime: subscribe
+                ? Infinity
+                : (query) => query.state.data === null ? absentStaleTime : staleTime,
+            gcTime,
+        })),
+    });
     useEffect(() => {
         if (!subscribe || !enabled || uniqueIds.length === 0)
             return;
@@ -48,110 +93,73 @@ export function useBatchFirestoreDocs({ db, collectionPath, ids, queryKeyPrefix,
             collectionPath,
             queryKeyPrefix,
             id,
-            onUpdate: () => setSnapshotVersion((v) => v + 1),
+            onUpdate: () => setSnapshotVersion((version) => version + 1),
             onError: (error) => setSubscribeError(error),
         }));
         return () => {
             for (const unsubscribe of unsubscribers)
                 unsubscribe();
         };
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- idsKey stands in for uniqueIds
-    }, [idsKey, subscribe, enabled, collectionPath, queryKeyPrefix, queryClient, db]);
-    // Separate IDs into cached/fresh vs needs-fetch (one-shot path only)
-    const { fetchIds } = useMemo(() => {
-        if (!enabled || subscribe) {
-            return { fetchIds: [] };
-        }
-        const needsFetch = [];
-        for (const id of uniqueIds) {
-            const queryKey = [queryKeyPrefix, id];
-            const state = queryClient.getQueryState(queryKey);
-            // Check if data exists and is still fresh. `null` counts as data — it marks a
-            // known-absent doc (negative caching) and must not be re-fetched while fresh.
-            const hasResolvedData = state !== undefined && state.data !== undefined;
-            if (!(hasResolvedData && state.dataUpdatedAt && Date.now() - state.dataUpdatedAt < staleTime)) {
-                needsFetch.push(id);
-            }
-        }
-        return { fetchIds: needsFetch };
-    }, [uniqueIds, queryKeyPrefix, queryClient, staleTime, enabled, subscribe]);
-    // Batch the fetchIds into groups of 30
-    const batches = useMemo(() => {
-        const result = [];
-        for (let i = 0; i < fetchIds.length; i += FIRESTORE_IN_LIMIT) {
-            result.push(fetchIds.slice(i, i + FIRESTORE_IN_LIMIT));
-        }
-        return result;
-    }, [fetchIds]);
-    // Fetch each batch and populate individual cache entries
-    const batchQueries = useQueries({
-        queries: batches.map((batch, batchIndex) => ({
-            queryKey: [queryKeyPrefix, 'batch', batchIndex, ...[...batch].sort()],
-            queryFn: async () => {
-                if (batch.length === 0)
-                    return [];
-                const q = query(collection(db, collectionPath), where(documentId(), 'in', batch));
-                const snapshot = await getDocs(q);
-                const docs = [];
-                const returnedIds = new Set();
-                // Process each document and update individual cache entries
-                snapshot.forEach((doc) => {
-                    const data = { id: doc.id, ...doc.data() };
-                    docs.push(data);
-                    returnedIds.add(doc.id);
-                    // Populate individual cache entry
-                    queryClient.setQueryData([queryKeyPrefix, doc.id], data, { updatedAt: Date.now() });
-                });
-                // Negative-cache requested ids that came back missing so they aren't
-                // re-fetched on every render while fresh (mirrors the subscribe path).
-                for (const id of batch) {
-                    if (!returnedIds.has(id)) {
-                        queryClient.setQueryData([queryKeyPrefix, id], null, { updatedAt: Date.now() });
-                    }
-                }
-                return docs;
-            },
-            staleTime,
-            gcTime,
-            enabled: enabled && batch.length > 0,
-        })),
-    });
-    // Combine results (one-shot batch path)
-    const batchIsLoading = batchQueries.some(q => q.isLoading);
-    const batchIsError = batchQueries.some(q => q.isError);
-    const batchError = batchQueries.find(q => q.error)?.error || null;
-    // Trigger re-derivation when batch fetches complete
-    const batchSettledCount = batchQueries.filter(q => q.isSuccess || q.isError).length;
-    const batchUpdateTimestamp = batchQueries.reduce((sum, q) => sum + (q.dataUpdatedAt ?? 0), 0);
-    const data = useMemo(() => {
-        const combined = {};
-        // Always read all IDs from individual cache entries. Both paths populate these via
-        // setQueryData (batch queryFn, or the subscribe listener); we never read batch results
-        // directly, so IDs can't fall through the cached/fetched split. A `null` entry means a
-        // doc is known-absent (negative caching, both paths) and is correctly excluded here.
-        for (const id of uniqueIds) {
-            const cached = queryClient.getQueryData([queryKeyPrefix, id]);
-            if (cached) {
-                combined[id] = cached;
-            }
+    }, [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(() => {
+        if (uniqueIds.length === 0)
+            return;
+        const releases = uniqueIds.map((id) => trackAbsentDoc({ queryClient, queryKey: [queryKeyPrefix, id], delays: absentDelays }));
+        return () => {
+            for (const release of releases)
+                release();
+        };
+    }, [uniqueIds, queryKeyPrefix, queryClient, absentDelays]);
+    const nextData = {};
+    let anyError = null;
+    let oneShotLoading = false;
+    let anyUnresolved = false;
+    for (let index = 0; index < uniqueIds.length; index += 1) {
+        const result = results[index];
+        if (!result)
+            continue;
+        if (result.isError) {
+            anyError ??= result.error ?? null;
+            continue;
         }
-        return combined;
-        // batchSettledCount/batchUpdateTimestamp/snapshotVersion are intentional re-derivation triggers:
-        // the cache is read imperatively via getQueryData (non-reactive), so these counters force a
-        // recompute when a batch fetch settles or a subscribed doc updates.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [uniqueIds, queryKeyPrefix, queryClient, batchSettledCount, batchUpdateTimestamp, snapshotVersion]);
-    // In subscribe mode the batch queries are inert; "loading" means a subscribed id has not
-    // received its first snapshot yet (no cache entry — `null` counts as resolved-missing).
-    const subscribeIsLoading = subscribe && enabled && uniqueIds.some((id) => queryClient.getQueryData([queryKeyPrefix, id]) === undefined);
-    const refetch = async () => {
-        await Promise.all(batchQueries.map(q => q.refetch()));
-    };
+        if (result.isLoading)
+            oneShotLoading = true;
+        const value = result.data;
+        if (value === undefined)
+            anyUnresolved = true;
+        else if (value)
+            nextData[uniqueIds[index]] = value;
+    }
+    // The map is rebuilt every render; keep the last COMMITTED object while it is unchanged so
+    // consumers can safely depend on `data`'s identity. Only the effect writes the ref, so a
+    // concurrent render React discards can never leave it pointing at an uncommitted map.
+    const committedDataRef = useRef(nextData);
+    const data = shallowRecordEqual(committedDataRef.current, nextData)
+        ? committedDataRef.current
+        : nextData;
+    useEffect(() => {
+        committedDataRef.current = data;
+    }, [data]);
+    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,
-        isLoading: batchIsLoading || subscribeIsLoading,
-        isError: batchIsError || subscribeError !== null,
-        error: batchError ?? subscribeError,
+        isLoading,
+        isError: anyError !== null || subscribeError !== null,
+        error: anyError ?? subscribeError,
         refetch,
     };
 }

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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"}
+{"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, subscribeDoc } from './doc-subscription-registry.js';\nimport { getDocLoader } from './batch-doc-loader.js';\nimport { ABSENT_RETRY_DELAYS_MS, trackAbsentDoc } from './absence-scheduler.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 30 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   * Refetch every requested id, cached ones included. A no-op in subscribe mode.\n   */\n  refetch: () => Promise<void>;\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 * @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 and merged into the returned result.\n  const [subscribeError, setSubscribeError] = useState<Error | null>(null);\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.\n        if (isListenerOwned(queryClient, queryKeyPrefix, id)) {\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    setSubscribeError(null);\n    const unsubscribers = uniqueIds.map((id) =>\n      subscribeDoc({\n        queryClient,\n        db,\n        collectionPath,\n        queryKeyPrefix,\n        id,\n        onUpdate: () => setSnapshotVersion((version) => version + 1),\n        onError: (error) => setSubscribeError(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  const nextData: Record<string, T> = {};\n  let anyError: Error | null = null;\n  let oneShotLoading = false;\n  let anyUnresolved = false;\n\n  for (let index = 0; index < uniqueIds.length; index += 1) {\n    const result = results[index];\n    if (!result) continue;\n    if (result.isError) {\n      anyError ??= (result.error as Error | null) ?? null;\n      continue;\n    }\n    if (result.isLoading) oneShotLoading = true;\n    const value = result.data as T | null | undefined;\n    if (value === undefined) anyUnresolved = true;\n    else if (value) nextData[uniqueIds[index]] = value;\n  }\n\n  // The map is rebuilt every render; keep the last COMMITTED object while it is unchanged so\n  // consumers can safely depend on `data`'s identity. Only the effect writes the ref, so a\n  // concurrent render React discards can never leave it pointing at an uncommitted map.\n  const committedDataRef = useRef<Record<string, T>>(nextData);\n  const data = shallowRecordEqual(committedDataRef.current, nextData)\n    ? committedDataRef.current\n    : nextData;\n\n  useEffect(() => {\n    committedDataRef.current = data;\n  }, [data]);\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 || subscribeError !== null,\n    error: anyError ?? subscribeError,\n    refetch,\n  };\n}\n"]}

package/dist/react/index.d.ts

@@ -15,6 +15,7 @@ export { useFirestoreLiveInfinite } from './firestore/use-firestore-live-infinit
 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 type { BatchFirestoreDocsOptions, BatchFirestoreDocsResult, } 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';
 //# 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,MAAM,uBAAuB,CAAC;AACnF,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,GACzB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,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,MAAM,uBAAuB,CAAC;AACnF,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"}

package/dist/react/index.js

@@ -16,6 +16,7 @@ export { useFirestoreLiveInfinite } from './firestore/use-firestore-live-infinit
 export { useFirestoreSet, useFirestoreUpdate, useFirestoreDelete, useFirestoreBatch, } from './firestore/use-firestore-mutations.js';
 // Batch Firestore Docs
 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';
 //# 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,cAAc;AACd,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC"}
+{"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","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 } 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"]}

package/dist/react/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/react/provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAiC,MAAM,oBAAoB,CAAC;AAOtF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAsB;IAC3E,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC;IACxE,OAAO,KAAC,mBAAmB,IAAC,MAAM,EAAE,MAAM,YAAG,QAAQ,GAAuB,CAAC;AAC/E,CAAC"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/react/provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAiC,MAAM,oBAAoB,CAAC;AAOtF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAsB;IAC3E,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC;IACxE,OAAO,KAAC,mBAAmB,IAAC,MAAM,EAAE,MAAM,YAAG,QAAQ,GAAuB,CAAC;AAC/E,CAAC","sourcesContent":["'use client';\n\nimport React from 'react';\nimport { QueryClientProvider } from '@tanstack/react-query';\nimport { createQueryClient, type CreateQueryClientOptions } from '../query-client.js';\n\nexport type QueryProviderProps = React.PropsWithChildren<{\n  /** Optional overrides applied when the client is first created. */\n  clientOptions?: CreateQueryClientOptions;\n}>;\n\n/**\n * Client component wrapper for Next.js / React apps.\n * Creates a single QueryClient per browser session.\n */\nexport function QueryProvider({ children, clientOptions }: QueryProviderProps) {\n  const [client] = React.useState(() => createQueryClient(clientOptions));\n  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-search.js","sourceRoot":"","sources":["../../../src/react/search/use-firestore-search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-firestore-search.js","sourceRoot":"","sources":["../../../src/react/search/use-firestore-search.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useState, useEffect } from 'react';\nimport { useQuery, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  getDocs,\n  query,\n  where,\n  orderBy,\n  limit as firestoreLimit,\n  type DocumentData,\n  type QueryConstraint,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from '../firestore/context.js';\nimport { keys } from '../../keys.js';\nimport type { FirestoreSearchOptions } from '../../search/types.js';\nimport type { WithId } from '../../firestore/types.js';\n\nconst DEFAULT_LIMIT = 5;\nconst DEFAULT_DEBOUNCE_MS = 300;\nconst DEFAULT_STALE_TIME = 60 * 1000; // 1 minute\n\n/**\n * Generic Firestore search hook with debouncing and case-insensitive prefix matching.\n * Automatically normalizes search text to lowercase and uses Firestore range queries.\n *\n * Features:\n * - Debounced input (default 300ms)\n * - Case-insensitive search\n * - Minimum 3 character requirement\n * - Prefix matching with '\\uf8ff' suffix\n * - Configurable result limit\n *\n * @example\n * ```typescript\n * const { data, isLoading } = useFirestoreSearch<UserProfile>({\n *   collectionPath: 'userProfiles',\n *   searchField: 'username',\n *   queryText: searchValue,\n * });\n *\n * const { data } = useFirestoreSearch<Team>({\n *   collectionPath: 'teams',\n *   searchField: 'name_lowercase',\n *   queryText: searchValue,\n *   limit: 10,\n * });\n * ```\n */\nexport function useFirestoreSearch<T extends DocumentData = DocumentData>({\n  collectionPath,\n  searchField,\n  queryText,\n  limit = DEFAULT_LIMIT,\n  enabled = true,\n  select,\n  debounceMs = DEFAULT_DEBOUNCE_MS,\n  staleTime = DEFAULT_STALE_TIME,\n  equalityFilters = [],\n}: FirestoreSearchOptions<T>): UseQueryResult<WithId<T>[], Error> {\n  const db = useFirestoreDb();\n  const [debouncedQuery, setDebouncedQuery] = useState(queryText);\n\n  // Debounce the search query\n  useEffect(() => {\n    const timer = setTimeout(() => {\n      setDebouncedQuery(queryText);\n    }, debounceMs);\n\n    return () => clearTimeout(timer);\n  }, [queryText, debounceMs]);\n\n  // Normalize query text\n  const normalizedQuery = debouncedQuery.toLowerCase().trim();\n  const shouldSearch = normalizedQuery.length >= 3 && enabled;\n\n  return useQuery({\n    queryKey: keys.custom('search', collectionPath, searchField, normalizedQuery, JSON.stringify(equalityFilters)),\n    queryFn: async (): Promise<WithId<T>[]> => {\n      if (!shouldSearch) {\n        return [];\n      }\n\n      const collectionRef = collection(db, collectionPath);\n\n      // Build range query for prefix matching\n      // Using '\\uf8ff' as upper bound creates a range that matches all strings starting with the query\n      const constraints: QueryConstraint[] = [\n        ...equalityFilters.map((f) => where(f.field, '==', f.value)),\n        where(searchField, '>=', normalizedQuery),\n        where(searchField, '<=', normalizedQuery + '\\uf8ff'),\n        orderBy(searchField, 'asc'),\n        firestoreLimit(limit),\n      ];\n\n      const q = query(collectionRef, ...constraints);\n      const snapshot = await getDocs(q);\n\n      return snapshot.docs.map((docSnap) => {\n        const rawData = docSnap.data();\n        const dataWithId = { id: docSnap.id, ...rawData };\n        const data = select ? select(dataWithId) : dataWithId;\n        return data as WithId<T>;\n      });\n    },\n    enabled: shouldSearch,\n    staleTime,\n  });\n}\n"]}

package/dist/search/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/search/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/search/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { DocumentData } from 'firebase/firestore';\n\n/**\n * Equality filter applied before the prefix range in a Firestore search.\n * Each becomes a `where(field, '==', value)` constraint, ordered ahead of the\n * search field. The composite index must list these equality fields (ASC)\n * before the search field (ASC).\n */\nexport interface SearchEqualityFilter {\n  field: string;\n  value: unknown;\n}\n\n/**\n * Configuration for a Firestore search query\n */\nexport interface FirestoreSearchConfig {\n  /** Firestore collection path to search */\n  collectionPath: string;\n  /** Field name to search on (must be indexed and lowercase) */\n  searchField: string;\n  /** Maximum number of results to return */\n  limit: number;\n  /** Optional equality filters applied before the prefix range. */\n  equalityFilters?: SearchEqualityFilter[];\n}\n\n/**\n * Options for useFirestoreSearch hook\n */\nexport interface FirestoreSearchOptions<T extends DocumentData = DocumentData> {\n  /** Firestore collection path to search */\n  collectionPath: string;\n  /** Field name to search on (must be indexed and lowercase) */\n  searchField: string;\n  /** Search query text */\n  queryText: string;\n  /** Maximum number of results (default: 5) */\n  limit?: number;\n  /** Enable/disable the search (default: true) */\n  enabled?: boolean;\n  /** Transform function to convert raw Firestore data to typed result */\n  select?: (data: DocumentData & { id: string }) => T;\n  /** Debounce delay in milliseconds (default: 300) */\n  debounceMs?: number;\n  /** React Query stale time (default: 60000ms) */\n  staleTime?: number;\n  /** Optional equality filters applied before the prefix range. */\n  equalityFilters?: SearchEqualityFilter[];\n}\n"]}

package/package.json

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