@ttt-productions/query-core 0.14.5 → 0.14.7

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

@@ -1,122 +1,132 @@
 'use client';
-import { useState, useCallback, useMemo } from 'react';
+import { useState, useCallback, useEffect, useRef } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { collection, query, getDocs, limit, startAfter, } from 'firebase/firestore';
 import { useFirestoreDb } from './context.js';
+import { paginatedPageKey } from '../../cache-helpers.js';
 const DEFAULT_PAGE_SIZE = 10;
-const MAX_CACHED_CURSORS = 20;
 /**
- * Page-based pagination for Firestore collections.
- * Supports navigating to specific pages (1, 2, 3...) rather than infinite scroll.
- * * @example
+ * Page-based pagination for Firestore collections (Previous / Next, one page at a time).
+ *
+ * Each page is ONE cache entry at `[...queryKey, 'page', n]` holding its rows, its last
+ * row as the next page's cursor, and whether a further page exists — read with a one-row
+ * look-ahead, so `hasNextPage` is false exactly when nothing follows the displayed page.
+ * Page n reads page n-1's cursor from the cache (loading the chain first if it is
+ * missing) and records it as `after`. A displayed page whose `after` no longer matches
+ * page n-1's cached cursor (page n-1 was re-read and its last row moved) is re-read before
+ * it is shown, so every instance, remount, and refetch of a key agrees on where a page
+ * starts. The page number belongs to the query identity (path, key, constraints, page
+ * size): a new identity renders `initialPage` in its first render.
+ *
+ * `queryKey` must encode everything that changes the read — path, filters, ordering, and
+ * page size — because the cache entries are shared by key.
+ *
+ * @example
  * ```tsx
- * const {
- * data,
- * page,
- * setPage,
- * hasNextPage,
- * hasPrevPage,
- * isLoading,
- * } = useFirestorePaginated<Task>({
- * collectionPath: 'tasks',
- * queryKey: ['tasks', 'list'],
- * constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],
- * pageSize: 10,
+ * const { data, page, nextPage, prevPage, hasNextPage, hasPrevPage } = useFirestorePaginated<Task>({
+ *   collectionPath: 'tasks',
+ *   queryKey: ['tasks', 'active', { pageSize: 10 }],
+ *   constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],
+ *   pageSize: 10,
  * });
- * * // Render pagination controls
- * <button onClick={() => setPage(page - 1)} disabled={!hasPrevPage}>Previous</button>
- * <span>Page {page}</span>
- * <button onClick={() => setPage(page + 1)} disabled={!hasNextPage}>Next</button>
  * ```
  */
-export function useFirestorePaginated({ collectionPath, queryKey, constraints = [], pageSize = DEFAULT_PAGE_SIZE, initialPage = 1, enabled = true, staleTime, gcTime, select, }) {
+export function useFirestorePaginated({ collectionPath, queryKey, constraints = [], pageSize = DEFAULT_PAGE_SIZE, initialPage = 1, enabled = true, staleTime, gcTime, refetchInterval, select, }) {
     const db = useFirestoreDb();
     const queryClient = useQueryClient();
-    const [page, setPageInternal] = useState(initialPage);
-    const [cursors, setCursors] = useState(new Map());
-    const [hasMore, setHasMore] = useState(true);
-    // Create a stable query key that includes the page
-    const pageQueryKey = useMemo(() => [...queryKey, 'page', page], [queryKey, page]);
-    const queryResult = useQuery({
-        queryKey: pageQueryKey,
-        queryFn: async () => {
-            const collectionRef = collection(db, collectionPath);
-            // Get cursor for current page (if not page 1)
-            const cursor = page > 1 ? cursors.get(page - 1) : undefined;
-            // Build query
-            const queryConstraints = [
-                ...constraints,
-                ...(cursor ? [startAfter(cursor)] : []),
-                limit(pageSize),
-            ];
-            const q = query(collectionRef, ...queryConstraints);
-            const snapshot = await getDocs(q);
-            // Store the last doc as cursor for next page
-            if (snapshot.docs.length > 0) {
-                const lastDoc = snapshot.docs[snapshot.docs.length - 1];
-                setCursors((prev) => {
-                    const next = new Map(prev);
-                    next.set(page, lastDoc);
-                    // Prune old cursors if too many (prevent memory leaks)
-                    if (next.size > MAX_CACHED_CURSORS) {
-                        const sorted = Array.from(next.keys()).sort((a, b) => a - b);
-                        const toDelete = sorted.slice(0, sorted.length - MAX_CACHED_CURSORS);
-                        toDelete.forEach((k) => next.delete(k));
-                    }
-                    return next;
-                });
-            }
-            // Determine if there are more pages
-            setHasMore(snapshot.docs.length === pageSize);
-            return snapshot.docs.map((docSnap) => {
-                const rawData = docSnap.data();
-                // Include id in data passed to select, so it can be renamed/transformed
-                const dataWithId = { id: docSnap.id, ...rawData };
-                const data = select ? select(dataWithId) : dataWithId;
-                return data;
+    const queryKeyMemo = JSON.stringify(queryKey);
+    const constraintsMemo = JSON.stringify(constraints);
+    const identity = JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, pageSize]);
+    const firstPage = Math.max(1, Math.floor(initialPage));
+    const [pageState, setPageState] = useState(() => ({ identity, page: firstPage }));
+    const page = pageState.identity === identity ? pageState.page : firstPage;
+    const selectRef = useRef(select);
+    selectRef.current = select;
+    const fetchPage = useCallback(async (n) => {
+        let cursor = null;
+        if (n > 1) {
+            const previous = await queryClient.ensureQueryData({
+                queryKey: paginatedPageKey(queryKey, n - 1),
+                queryFn: () => fetchPage(n - 1),
             });
-        },
+            if (!previous.hasMore || !previous.cursor) {
+                return { items: [], cursor: null, hasMore: false, after: previous.cursor?.id ?? null };
+            }
+            cursor = previous.cursor;
+        }
+        const q = query(collection(db, collectionPath), ...constraints, ...(cursor ? [startAfter(cursor)] : []), limit(pageSize + 1));
+        const snapshot = await getDocs(q);
+        const pageDocs = snapshot.docs.slice(0, pageSize);
+        return {
+            items: pageDocs.map((docSnap) => {
+                const dataWithId = { id: docSnap.id, ...docSnap.data() };
+                const mapped = selectRef.current ? selectRef.current(dataWithId) : dataWithId;
+                return mapped;
+            }),
+            cursor: pageDocs[pageDocs.length - 1] ?? null,
+            hasMore: snapshot.docs.length > pageSize,
+            after: cursor?.id ?? null,
+        };
+    }, 
+    // queryKey and constraints are captured through their serialized identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [db, queryClient, identity, selectRef]);
+    const queryResult = useQuery({
+        queryKey: paginatedPageKey(queryKey, page),
+        queryFn: () => fetchPage(page),
         enabled,
         staleTime,
         gcTime,
+        refetchInterval,
     });
-    const setPage = useCallback((newPage) => {
-        if (newPage < 1)
-            return;
-        // Can only go forward one page at a time if cursor doesn't exist
-        if (newPage > page + 1 && !cursors.has(newPage - 1)) {
-            console.warn('[useFirestorePaginated] Cannot skip pages. Navigate sequentially.');
+    // The page before the displayed one, observed from the cache only (never fetched here).
+    // When it is re-read and its last row moves, the displayed entry no longer starts where the
+    // chain says it must: it is re-read before it is shown as current.
+    const previousPage = useQuery({
+        queryKey: paginatedPageKey(queryKey, Math.max(1, page - 1)),
+        queryFn: () => fetchPage(Math.max(1, page - 1)),
+        enabled: false,
+    });
+    const cachedEntry = queryResult.data;
+    const outOfChain = page > 1 &&
+        cachedEntry !== undefined &&
+        (previousPage.data === undefined || cachedEntry.after !== (previousPage.data.cursor?.id ?? null));
+    const { refetch, isFetching } = queryResult;
+    useEffect(() => {
+        if (enabled && outOfChain && !isFetching)
+            void refetch();
+    }, [enabled, outOfChain, isFetching, refetch]);
+    const entry = outOfChain ? undefined : cachedEntry;
+    const hasNextPage = Boolean(entry?.hasMore && entry.cursor);
+    const setPage = useCallback((target) => {
+        const next = Math.floor(target);
+        if (next < 1 || next === page)
             return;
+        if (next > page + 1) {
+            const before = queryClient.getQueryData(paginatedPageKey(queryKey, next - 1));
+            if (!before?.hasMore)
+                return;
         }
-        setPageInternal(newPage);
-    }, [page, cursors]);
-    const nextPage = useCallback(() => {
-        if (hasMore)
-            setPage(page + 1);
-    }, [page, hasMore, setPage]);
-    const prevPage = useCallback(() => {
-        if (page > 1)
-            setPage(page - 1);
-    }, [page, setPage]);
-    const resetToFirstPage = useCallback(() => {
-        setCursors(new Map());
-        setPageInternal(1);
-        setHasMore(true);
-        // Invalidate all cached pages
-        queryClient.invalidateQueries({ queryKey, exact: false });
-    }, [queryClient, queryKey]);
+        if (next === page + 1 && !hasNextPage)
+            return;
+        setPageState({ identity, page: next });
+    }, 
+    // queryKey is captured through its serialized identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [page, hasNextPage, identity, queryClient]);
+    const nextPage = useCallback(() => setPage(page + 1), [page, setPage]);
+    const prevPage = useCallback(() => setPage(page - 1), [page, setPage]);
     return {
         ...queryResult,
-        // Pagination state
+        ...(outOfChain ? { isLoading: true, isPending: true, isSuccess: false, status: 'pending' } : {}),
+        data: entry?.items,
         page,
         pageSize,
-        hasNextPage: hasMore,
+        hasNextPage,
         hasPrevPage: page > 1,
-        // Navigation functions
         setPage,
         nextPage,
         prevPage,
-        resetToFirstPage,
     };
 }
 //# sourceMappingURL=use-firestore-paginated.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-paginated.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-paginated.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useState, useCallback, useMemo } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  query,\n  getDocs,\n  limit,\n  startAfter,\n  type DocumentData,\n  type DocumentSnapshot,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport type { FirestorePaginatedOptions, WithId } from '../../firestore/types.js';\n\nconst DEFAULT_PAGE_SIZE = 10;\nconst MAX_CACHED_CURSORS = 20;\n\n/**\n * Return type for useFirestorePaginated hook\n */\nexport type UseFirestorePaginatedResult<T> = UseQueryResult<WithId<T>[], Error> & {\n  page: number;\n  pageSize: number;\n  hasNextPage: boolean;\n  hasPrevPage: boolean;\n  setPage: (page: number) => void;\n  nextPage: () => void;\n  prevPage: () => void;\n  resetToFirstPage: () => void;\n};\n\n/**\n * Page-based pagination for Firestore collections.\n * Supports navigating to specific pages (1, 2, 3...) rather than infinite scroll.\n * * @example\n * ```tsx\n * const {\n * data,\n * page,\n * setPage,\n * hasNextPage,\n * hasPrevPage,\n * isLoading,\n * } = useFirestorePaginated<Task>({\n * collectionPath: 'tasks',\n * queryKey: ['tasks', 'list'],\n * constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],\n * pageSize: 10,\n * });\n * * // Render pagination controls\n * <button onClick={() => setPage(page - 1)} disabled={!hasPrevPage}>Previous</button>\n * <span>Page {page}</span>\n * <button onClick={() => setPage(page + 1)} disabled={!hasNextPage}>Next</button>\n * ```\n */\nexport function useFirestorePaginated<T extends DocumentData = DocumentData>({\n  collectionPath,\n  queryKey,\n  constraints = [],\n  pageSize = DEFAULT_PAGE_SIZE,\n  initialPage = 1,\n  enabled = true,\n  staleTime,\n  gcTime,\n  select,\n}: FirestorePaginatedOptions<T>): UseFirestorePaginatedResult<T> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n\n  const [page, setPageInternal] = useState(initialPage);\n  const [cursors, setCursors] = useState<Map<number, DocumentSnapshot>>(new Map());\n  const [hasMore, setHasMore] = useState(true);\n\n  // Create a stable query key that includes the page\n  const pageQueryKey = useMemo(\n    () => [...queryKey, 'page', page],\n    [queryKey, page]\n  );\n\n  const queryResult = useQuery({\n    queryKey: pageQueryKey,\n    queryFn: async (): Promise<WithId<T>[]> => {\n      const collectionRef = collection(db, collectionPath);\n\n      // Get cursor for current page (if not page 1)\n      const cursor = page > 1 ? cursors.get(page - 1) : undefined;\n\n      // Build query\n      const queryConstraints = [\n        ...constraints,\n        ...(cursor ? [startAfter(cursor)] : []),\n        limit(pageSize),\n      ];\n\n      const q = query(collectionRef, ...queryConstraints);\n      const snapshot = await getDocs(q);\n\n      // Store the last doc as cursor for next page\n      if (snapshot.docs.length > 0) {\n        const lastDoc = snapshot.docs[snapshot.docs.length - 1];\n        setCursors((prev) => {\n          const next = new Map(prev);\n          next.set(page, lastDoc);\n\n          // Prune old cursors if too many (prevent memory leaks)\n          if (next.size > MAX_CACHED_CURSORS) {\n            const sorted = Array.from(next.keys()).sort((a, b) => a - b);\n            const toDelete = sorted.slice(0, sorted.length - MAX_CACHED_CURSORS);\n            toDelete.forEach((k) => next.delete(k));\n          }\n\n          return next;\n        });\n      }\n\n      // Determine if there are more pages\n      setHasMore(snapshot.docs.length === pageSize);\n\n      return snapshot.docs.map((docSnap) => {\n        const rawData = docSnap.data();\n        // Include id in data passed to select, so it can be renamed/transformed\n        const dataWithId = { id: docSnap.id, ...rawData };\n        const data = select ? select(dataWithId) : dataWithId;\n        return data as WithId<T>;\n      });\n    },\n    enabled,\n    staleTime,\n    gcTime,\n  });\n\n  const setPage = useCallback((newPage: number) => {\n    if (newPage < 1) return;\n\n    // Can only go forward one page at a time if cursor doesn't exist\n    if (newPage > page + 1 && !cursors.has(newPage - 1)) {\n      console.warn('[useFirestorePaginated] Cannot skip pages. Navigate sequentially.');\n      return;\n    }\n\n    setPageInternal(newPage);\n  }, [page, cursors]);\n\n  const nextPage = useCallback(() => {\n    if (hasMore) setPage(page + 1);\n  }, [page, hasMore, setPage]);\n\n  const prevPage = useCallback(() => {\n    if (page > 1) setPage(page - 1);\n  }, [page, setPage]);\n\n  const resetToFirstPage = useCallback(() => {\n    setCursors(new Map());\n    setPageInternal(1);\n    setHasMore(true);\n    // Invalidate all cached pages\n    queryClient.invalidateQueries({ queryKey, exact: false });\n  }, [queryClient, queryKey]);\n\n  return {\n    ...queryResult,\n    // Pagination state\n    page,\n    pageSize,\n    hasNextPage: hasMore,\n    hasPrevPage: page > 1,\n    // Navigation functions\n    setPage,\n    nextPage,\n    prevPage,\n    resetToFirstPage,\n  };\n}\n"]}
+{"version":3,"file":"use-firestore-paginated.js","sourceRoot":"","sources":["../../../src/react/firestore/use-firestore-paginated.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useState, useCallback, useEffect, useRef } from 'react';\nimport { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';\nimport {\n  collection,\n  query,\n  getDocs,\n  limit,\n  startAfter,\n  type DocumentData,\n  type DocumentSnapshot,\n} from 'firebase/firestore';\nimport { useFirestoreDb } from './context.js';\nimport { paginatedPageKey } from '../../cache-helpers.js';\nimport type { FirestorePaginatedOptions, PaginatedPage, WithId } from '../../firestore/types.js';\n\nconst DEFAULT_PAGE_SIZE = 10;\n\n/**\n * Return type for useFirestorePaginated hook. `data` is the displayed page's rows; the\n * page's cache entry (rows, cursor, has-more) lives at `paginatedPageKey(queryKey, page)`.\n */\nexport type UseFirestorePaginatedResult<T> = Omit<UseQueryResult<PaginatedPage<WithId<T>>, Error>, 'data'> & {\n  data: WithId<T>[] | undefined;\n  page: number;\n  pageSize: number;\n  hasNextPage: boolean;\n  hasPrevPage: boolean;\n  setPage: (page: number) => void;\n  nextPage: () => void;\n  prevPage: () => void;\n};\n\n/**\n * Page-based pagination for Firestore collections (Previous / Next, one page at a time).\n *\n * Each page is ONE cache entry at `[...queryKey, 'page', n]` holding its rows, its last\n * row as the next page's cursor, and whether a further page exists — read with a one-row\n * look-ahead, so `hasNextPage` is false exactly when nothing follows the displayed page.\n * Page n reads page n-1's cursor from the cache (loading the chain first if it is\n * missing) and records it as `after`. A displayed page whose `after` no longer matches\n * page n-1's cached cursor (page n-1 was re-read and its last row moved) is re-read before\n * it is shown, so every instance, remount, and refetch of a key agrees on where a page\n * starts. The page number belongs to the query identity (path, key, constraints, page\n * size): a new identity renders `initialPage` in its first render.\n *\n * `queryKey` must encode everything that changes the read — path, filters, ordering, and\n * page size — because the cache entries are shared by key.\n *\n * @example\n * ```tsx\n * const { data, page, nextPage, prevPage, hasNextPage, hasPrevPage } = useFirestorePaginated<Task>({\n *   collectionPath: 'tasks',\n *   queryKey: ['tasks', 'active', { pageSize: 10 }],\n *   constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')],\n *   pageSize: 10,\n * });\n * ```\n */\nexport function useFirestorePaginated<T extends DocumentData = DocumentData>({\n  collectionPath,\n  queryKey,\n  constraints = [],\n  pageSize = DEFAULT_PAGE_SIZE,\n  initialPage = 1,\n  enabled = true,\n  staleTime,\n  gcTime,\n  refetchInterval,\n  select,\n}: FirestorePaginatedOptions<T>): UseFirestorePaginatedResult<T> {\n  const db = useFirestoreDb();\n  const queryClient = useQueryClient();\n\n  const queryKeyMemo = JSON.stringify(queryKey);\n  const constraintsMemo = JSON.stringify(constraints);\n  const identity = JSON.stringify([collectionPath, queryKeyMemo, constraintsMemo, pageSize]);\n  const firstPage = Math.max(1, Math.floor(initialPage));\n\n  const [pageState, setPageState] = useState(() => ({ identity, page: firstPage }));\n  const page = pageState.identity === identity ? pageState.page : firstPage;\n\n  const selectRef = useRef(select);\n  selectRef.current = select;\n\n  const fetchPage = useCallback(\n    async (n: number): Promise<PaginatedPage<WithId<T>>> => {\n      let cursor: DocumentSnapshot | null = null;\n      if (n > 1) {\n        const previous = await queryClient.ensureQueryData<PaginatedPage<WithId<T>>>({\n          queryKey: paginatedPageKey(queryKey, n - 1),\n          queryFn: () => fetchPage(n - 1),\n        });\n        if (!previous.hasMore || !previous.cursor) {\n          return { items: [], cursor: null, hasMore: false, after: previous.cursor?.id ?? null };\n        }\n        cursor = previous.cursor;\n      }\n      const q = query(\n        collection(db, collectionPath),\n        ...constraints,\n        ...(cursor ? [startAfter(cursor)] : []),\n        limit(pageSize + 1),\n      );\n      const snapshot = await getDocs(q);\n      const pageDocs = snapshot.docs.slice(0, pageSize);\n      return {\n        items: pageDocs.map((docSnap) => {\n          const dataWithId = { id: docSnap.id, ...docSnap.data() };\n          const mapped = selectRef.current ? selectRef.current(dataWithId) : dataWithId;\n          return mapped as WithId<T>;\n        }),\n        cursor: pageDocs[pageDocs.length - 1] ?? null,\n        hasMore: snapshot.docs.length > pageSize,\n        after: cursor?.id ?? null,\n      };\n    },\n    // queryKey and constraints are captured through their serialized identity.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [db, queryClient, identity, selectRef],\n  );\n\n  const queryResult = useQuery({\n    queryKey: paginatedPageKey(queryKey, page),\n    queryFn: () => fetchPage(page),\n    enabled,\n    staleTime,\n    gcTime,\n    refetchInterval,\n  });\n\n  // The page before the displayed one, observed from the cache only (never fetched here).\n  // When it is re-read and its last row moves, the displayed entry no longer starts where the\n  // chain says it must: it is re-read before it is shown as current.\n  const previousPage = useQuery({\n    queryKey: paginatedPageKey(queryKey, Math.max(1, page - 1)),\n    queryFn: () => fetchPage(Math.max(1, page - 1)),\n    enabled: false,\n  });\n  const cachedEntry = queryResult.data;\n  const outOfChain =\n    page > 1 &&\n    cachedEntry !== undefined &&\n    (previousPage.data === undefined || cachedEntry.after !== (previousPage.data.cursor?.id ?? null));\n  const { refetch, isFetching } = queryResult;\n  useEffect(() => {\n    if (enabled && outOfChain && !isFetching) void refetch();\n  }, [enabled, outOfChain, isFetching, refetch]);\n\n  const entry = outOfChain ? undefined : cachedEntry;\n  const hasNextPage = Boolean(entry?.hasMore && entry.cursor);\n\n  const setPage = useCallback(\n    (target: number) => {\n      const next = Math.floor(target);\n      if (next < 1 || next === page) return;\n      if (next > page + 1) {\n        const before = queryClient.getQueryData<PaginatedPage<unknown>>(\n          paginatedPageKey(queryKey, next - 1),\n        );\n        if (!before?.hasMore) return;\n      }\n      if (next === page + 1 && !hasNextPage) return;\n      setPageState({ identity, page: next });\n    },\n    // queryKey is captured through its serialized identity.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [page, hasNextPage, identity, queryClient],\n  );\n\n  const nextPage = useCallback(() => setPage(page + 1), [page, setPage]);\n  const prevPage = useCallback(() => setPage(page - 1), [page, setPage]);\n\n  return {\n    ...queryResult,\n    ...(outOfChain ? { isLoading: true, isPending: true, isSuccess: false, status: 'pending' as const } : {}),\n    data: entry?.items,\n    page,\n    pageSize,\n    hasNextPage,\n    hasPrevPage: page > 1,\n    setPage,\n    nextPage,\n    prevPage,\n  } as UseFirestorePaginatedResult<T>;\n}\n"]}

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

@@ -9,7 +9,9 @@ import type { WithId } from '../../firestore/types.js';
  * Features:
  * - Debounced input (default 300ms)
  * - Case-insensitive search
- * - Minimum 3 character requirement
+ * - Searches only a text `isSearchableText` accepts (`FIRESTORE_SEARCH_MIN_LENGTH`, trimmed)
+ * - No answer while the debounce lags the typed text: `data` is undefined and `isLoading` is true
+ *   (idle instead when the typed text is too short or the search is disabled)
  * - Prefix matching with '\uf8ff' suffix
  * - Configurable result limit
  *

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

@@ -1 +1 @@
-{"version":3,"file":"use-firestore-search.d.ts","sourceRoot":"","sources":["../../../src/react/search/use-firestore-search.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAOL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAMvD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EACxE,cAAc,EACd,WAAW,EACX,SAAS,EACT,KAAqB,EACrB,OAAc,EACd,MAAM,EACN,UAAgC,EAChC,SAA8B,EAC9B,eAAoB,GACrB,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAiDhE"}
+{"version":3,"file":"use-firestore-search.d.ts","sourceRoot":"","sources":["../../../src/react/search/use-firestore-search.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAOL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAOvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EACxE,cAAc,EACd,WAAW,EACX,SAAS,EACT,KAAqB,EACrB,OAAc,EACd,MAAM,EACN,UAAgC,EAChC,SAA8B,EAC9B,eAAoB,GACrB,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAwDhE"}

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

@@ -4,6 +4,7 @@ import { useQuery } from '@tanstack/react-query';
 import { collection, getDocs, query, where, orderBy, limit as firestoreLimit, } from 'firebase/firestore';
 import { useFirestoreDb } from '../firestore/context.js';
 import { keys } from '../../keys.js';
+import { isSearchableText, normalizeSearchText } from '../../search/rule.js';
 const DEFAULT_LIMIT = 5;
 const DEFAULT_DEBOUNCE_MS = 300;
 const DEFAULT_STALE_TIME = 60 * 1000; // 1 minute
@@ -14,7 +15,9 @@ const DEFAULT_STALE_TIME = 60 * 1000; // 1 minute
  * Features:
  * - Debounced input (default 300ms)
  * - Case-insensitive search
- * - Minimum 3 character requirement
+ * - Searches only a text `isSearchableText` accepts (`FIRESTORE_SEARCH_MIN_LENGTH`, trimmed)
+ * - No answer while the debounce lags the typed text: `data` is undefined and `isLoading` is true
+ *   (idle instead when the typed text is too short or the search is disabled)
  * - Prefix matching with '\uf8ff' suffix
  * - Configurable result limit
  *
@@ -44,10 +47,9 @@ export function useFirestoreSearch({ collectionPath, searchField, queryText, lim
         }, debounceMs);
         return () => clearTimeout(timer);
     }, [queryText, debounceMs]);
-    // Normalize query text
-    const normalizedQuery = debouncedQuery.toLowerCase().trim();
-    const shouldSearch = normalizedQuery.length >= 3 && enabled;
-    return useQuery({
+    const normalizedQuery = normalizeSearchText(debouncedQuery);
+    const shouldSearch = enabled && isSearchableText(debouncedQuery);
+    const searchQuery = useQuery({
         queryKey: keys.custom('search', collectionPath, searchField, normalizedQuery, JSON.stringify(equalityFilters)),
         queryFn: async () => {
             if (!shouldSearch) {
@@ -75,5 +77,48 @@ export function useFirestoreSearch({ collectionPath, searchField, queryText, lim
         enabled: shouldSearch,
         staleTime,
     });
+    // Until the debounce catches up, the query's key holds an earlier text, so its result (or its
+    // absence) is not an answer for the text typed now (FRONTEND-206): report no answer instead —
+    // still searching when the typed text will be searched, idle when it will not.
+    const typedQuery = normalizeSearchText(queryText);
+    if (typedQuery === normalizedQuery)
+        return searchQuery;
+    const willSearch = enabled && isSearchableText(queryText);
+    return withoutAnswer(searchQuery, willSearch);
+}
+/**
+ * The query result with every answer field replaced. The other fields stay getters onto the
+ * original result: TanStack tracks which fields a component reads to decide when it re-renders,
+ * and reading them all here (a spread) would opt every consumer out of that.
+ */
+function withoutAnswer(result, searching) {
+    const answerFields = {
+        data: undefined,
+        error: null,
+        isError: false,
+        isLoadingError: false,
+        isRefetchError: false,
+        isSuccess: false,
+        isPending: true,
+        isPlaceholderData: false,
+        isFetched: false,
+        isFetchedAfterMount: false,
+        isRefetching: false,
+        isLoading: searching,
+        isFetching: searching,
+        status: 'pending',
+        fetchStatus: searching ? 'fetching' : 'idle',
+        dataUpdatedAt: 0,
+        errorUpdatedAt: 0,
+    };
+    const view = {};
+    for (const key of Object.keys(result)) {
+        Object.defineProperty(view, key, {
+            enumerable: true,
+            configurable: true,
+            get: key in answerFields ? () => answerFields[key] : () => result[key],
+        });
+    }
+    return view;
 }
 //# sourceMappingURL=use-firestore-search.js.map

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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","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"]}
+{"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';\nimport { isSearchableText, normalizeSearchText } from '../../search/rule.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 * - Searches only a text `isSearchableText` accepts (`FIRESTORE_SEARCH_MIN_LENGTH`, trimmed)\n * - No answer while the debounce lags the typed text: `data` is undefined and `isLoading` is true\n *   (idle instead when the typed text is too short or the search is disabled)\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  const normalizedQuery = normalizeSearchText(debouncedQuery);\n  const shouldSearch = enabled && isSearchableText(debouncedQuery);\n\n  const searchQuery = 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  // Until the debounce catches up, the query's key holds an earlier text, so its result (or its\n  // absence) is not an answer for the text typed now (FRONTEND-206): report no answer instead —\n  // still searching when the typed text will be searched, idle when it will not.\n  const typedQuery = normalizeSearchText(queryText);\n  if (typedQuery === normalizedQuery) return searchQuery;\n  const willSearch = enabled && isSearchableText(queryText);\n  return withoutAnswer(searchQuery, willSearch);\n}\n\n/**\n * The query result with every answer field replaced. The other fields stay getters onto the\n * original result: TanStack tracks which fields a component reads to decide when it re-renders,\n * and reading them all here (a spread) would opt every consumer out of that.\n */\nfunction withoutAnswer<R extends UseQueryResult<unknown, Error>>(result: R, searching: boolean): R {\n  const answerFields: Record<string, unknown> = {\n    data: undefined,\n    error: null,\n    isError: false,\n    isLoadingError: false,\n    isRefetchError: false,\n    isSuccess: false,\n    isPending: true,\n    isPlaceholderData: false,\n    isFetched: false,\n    isFetchedAfterMount: false,\n    isRefetching: false,\n    isLoading: searching,\n    isFetching: searching,\n    status: 'pending',\n    fetchStatus: searching ? 'fetching' : 'idle',\n    dataUpdatedAt: 0,\n    errorUpdatedAt: 0,\n  };\n  const view = {} as R;\n  for (const key of Object.keys(result)) {\n    Object.defineProperty(view, key, {\n      enumerable: true,\n      configurable: true,\n      get: key in answerFields ? () => answerFields[key] : () => result[key as keyof R],\n    });\n  }\n  return view;\n}\n\n"]}

package/dist/search/rule.d.ts

@@ -0,0 +1,10 @@
+/** The fewest characters, counted on the normalized text, that `useFirestoreSearch` searches. */
+export declare const FIRESTORE_SEARCH_MIN_LENGTH = 3;
+/**
+ * The text `useFirestoreSearch` reads for a typed text: lowercased, surrounding whitespace dropped.
+ * Two typed texts with the same normalized text are the same search.
+ */
+export declare function normalizeSearchText(text: string): string;
+/** Whether `useFirestoreSearch` searches this typed text (its normalized length reaches the minimum). */
+export declare function isSearchableText(text: string): boolean;
+//# sourceMappingURL=rule.d.ts.map

package/dist/search/rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.d.ts","sourceRoot":"","sources":["../../src/search/rule.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/search/rule.js

@@ -0,0 +1,14 @@
+/** The fewest characters, counted on the normalized text, that `useFirestoreSearch` searches. */
+export const FIRESTORE_SEARCH_MIN_LENGTH = 3;
+/**
+ * The text `useFirestoreSearch` reads for a typed text: lowercased, surrounding whitespace dropped.
+ * Two typed texts with the same normalized text are the same search.
+ */
+export function normalizeSearchText(text) {
+    return text.toLowerCase().trim();
+}
+/** Whether `useFirestoreSearch` searches this typed text (its normalized length reaches the minimum). */
+export function isSearchableText(text) {
+    return normalizeSearchText(text).length >= FIRESTORE_SEARCH_MIN_LENGTH;
+}
+//# sourceMappingURL=rule.js.map

package/dist/search/rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.js","sourceRoot":"","sources":["../../src/search/rule.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,2BAA2B,CAAC;AACzE,CAAC","sourcesContent":["/** The fewest characters, counted on the normalized text, that `useFirestoreSearch` searches. */\nexport const FIRESTORE_SEARCH_MIN_LENGTH = 3;\n\n/**\n * The text `useFirestoreSearch` reads for a typed text: lowercased, surrounding whitespace dropped.\n * Two typed texts with the same normalized text are the same search.\n */\nexport function normalizeSearchText(text: string): string {\n  return text.toLowerCase().trim();\n}\n\n/** Whether `useFirestoreSearch` searches this typed text (its normalized length reaches the minimum). */\nexport function isSearchableText(text: string): boolean {\n  return normalizeSearchText(text).length >= FIRESTORE_SEARCH_MIN_LENGTH;\n}\n"]}

package/package.json

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