@ttt-productions/query-core 0.14.5 → 0.14.6

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/package.json

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