Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

useLiveInfiniteQuery.ts

330 lines10.4 KB

1import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
2import { CollectionImpl } from '@tanstack/db'
3import { useLiveQuery } from './useLiveQuery'
4import type {
5 Collection,
6 Context,
7 InferResultType,
8 InitialQueryBuilder,
9 LiveQueryCollectionUtils,
10 NonSingleResult,
11 QueryBuilder,
12} from '@tanstack/db'
13​
14/**
15 * Type guard to check if utils object has setWindow method (LiveQueryCollectionUtils)
16 */
17function isLiveQueryCollectionUtils(
18 utils: unknown,
19): utils is LiveQueryCollectionUtils {
20 return typeof (utils as any).setWindow === `function`
22​
23export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
24 pageSize?: number
25 initialPageParam?: number
26 /**
27 * @deprecated This callback is not used by the current implementation.
28 * Pagination is determined internally via a peek-ahead strategy.
29 * Provided for API compatibility with TanStack Query conventions.
30 */
31 getNextPageParam?: (
32 lastPage: Array<InferResultType<TContext>[number]>,
33 allPages: Array<Array<InferResultType<TContext>[number]>>,
34 lastPageParam: number,
35 allPageParams: Array<number>,
36 ) => number | undefined
38​
39export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<
40 ReturnType<typeof useLiveQuery<TContext>>,
41 `data`
42> & {
43 data: InferResultType<TContext>
44 pages: Array<Array<InferResultType<TContext>[number]>>
45 pageParams: Array<number>
46 fetchNextPage: () => void
47 hasNextPage: boolean
48 isFetchingNextPage: boolean
50​
51/**
52 * Create an infinite query using a query function with live updates
53 *
54 * Uses `utils.setWindow()` to dynamically adjust the limit/offset window
55 * without recreating the live query collection on each page change.
56 *
57 * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.
58 * @param config - Configuration including pageSize and getNextPageParam
59 * @param deps - Array of dependencies that trigger query re-execution when changed
60 * @returns Object with pages, data, and pagination controls
61 *
62 * @example
63 * // Basic infinite query
64 * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
65 * (q) => q
66 * .from({ posts: postsCollection })
67 * .orderBy(({ posts }) => posts.createdAt, 'desc')
68 * .select(({ posts }) => ({
69 * id: posts.id,
70 * title: posts.title
71 * })),
72 * {
73 * pageSize: 20,
74 * getNextPageParam: (lastPage, allPages) =>
75 * lastPage.length === 20 ? allPages.length : undefined
76 * }
77 * )
78 *
79 * @example
80 * // With dependencies
81 * const { pages, fetchNextPage } = useLiveInfiniteQuery(
82 * (q) => q
83 * .from({ posts: postsCollection })
84 * .where(({ posts }) => eq(posts.category, category))
85 * .orderBy(({ posts }) => posts.createdAt, 'desc'),
86 * {
87 * pageSize: 10,
88 * getNextPageParam: (lastPage) =>
89 * lastPage.length === 10 ? lastPage.length : undefined
90 * },
91 * [category]
92 * )
93 *
94 * @example
95 * // Router loader pattern with pre-created collection
96 * // In loader:
97 * const postsQuery = createLiveQueryCollection({
98 * query: (q) => q
99 * .from({ posts: postsCollection })
100 * .orderBy(({ posts }) => posts.createdAt, 'desc')
101 * .limit(20)
102 * })
103 * await postsQuery.preload()
104 * return { postsQuery }
105 *
106 * // In component:
107 * const { postsQuery } = useLoaderData()
108 * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
109 * postsQuery,
110 * {
111 * pageSize: 20,
112 * getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined
113 * }
114 * )
115 */
116​
117// Overload for pre-created collection (non-single result)
118export function useLiveInfiniteQuery<
119 TResult extends object,
120 TKey extends string | number,
121 TUtils extends Record<string, any>,
122>(
123 liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
124 config: UseLiveInfiniteQueryConfig<any>,
125): UseLiveInfiniteQueryReturn<any>
126​
127// Overload for query function
128export function useLiveInfiniteQuery<TContext extends Context>(
129 queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
130 config: UseLiveInfiniteQueryConfig<TContext>,
131 deps?: Array<unknown>,
132): UseLiveInfiniteQueryReturn<TContext>
133​
134// Implementation
135export function useLiveInfiniteQuery<TContext extends Context>(
136 queryFnOrCollection: any,
137 config: UseLiveInfiniteQueryConfig<TContext>,
138 deps: Array<unknown> = [],
139): UseLiveInfiniteQueryReturn<TContext> {
140 const pageSize = config.pageSize || 20
141 const initialPageParam = config.initialPageParam ?? 0
142​
143 // Detect if input is a collection or query function
144 const isCollection = queryFnOrCollection instanceof CollectionImpl
145​
146 // Validate input type
147 if (!isCollection && typeof queryFnOrCollection !== `function`) {
148 throw new Error(
149 `useLiveInfiniteQuery: First argument must be either a pre-created live query collection (CollectionImpl) ` +
150 `or a query function. Received: ${typeof queryFnOrCollection}`,
151 )
152 }
153​
154 // Track how many pages have been loaded
155 const [loadedPageCount, setLoadedPageCount] = useState(1)
156 const [isFetchingNextPage, setIsFetchingNextPage] = useState(false)
157​
158 // Track collection instance and whether we've validated it (only for pre-created collections)
159 const collectionRef = useRef(isCollection ? queryFnOrCollection : null)
160 const hasValidatedCollectionRef = useRef(false)
161​
162 // Track deps for query functions (stringify for comparison)
163 let depsKey: string
164 try {
165 depsKey = JSON.stringify(deps)
166 } catch {
167 throw new Error(
168 `useLiveInfiniteQuery: dependency array contains values that cannot be serialized (e.g. circular references). ` +
169 `Ensure all dependency values are JSON-serializable.`,
170 )
171 }
172 const prevDepsKeyRef = useRef(depsKey)
173​
174 // Reset pagination when inputs change
175 useEffect(() => {
176 let shouldReset = false
177​
178 if (isCollection) {
179 // Reset if collection instance changed
180 if (collectionRef.current !== queryFnOrCollection) {
181 collectionRef.current = queryFnOrCollection
182 hasValidatedCollectionRef.current = false
183 shouldReset = true
184 }
185 } else {
186 // Reset if deps changed (for query functions)
187 if (prevDepsKeyRef.current !== depsKey) {
188 prevDepsKeyRef.current = depsKey
189 shouldReset = true
190 }
191 }
192​
193 if (shouldReset) {
194 setLoadedPageCount(1)
195 }
196 }, [isCollection, queryFnOrCollection, depsKey])
197​
198 // Create a live query with initial limit and offset
199 // Either pass collection directly or wrap query function
200 // Use pageSize + 1 for peek-ahead detection (to know if there are more pages)
201 const queryResult = isCollection
202 ? useLiveQuery(queryFnOrCollection)
203 : useLiveQuery(
204 (q) =>
205 queryFnOrCollection(q)
206 .limit(pageSize + 1)
207 .offset(0),
208 deps,
209 )
210​
211 // Adjust window when pagination changes
212 useEffect(() => {
213 const utils = queryResult.collection.utils
214 const expectedOffset = 0
215 const expectedLimit = loadedPageCount * pageSize + 1 // +1 for peek ahead
216​
217 // Check if collection has orderBy (required for setWindow)
218 if (!isLiveQueryCollectionUtils(utils)) {
219 // For pre-created collections, throw an error if no orderBy
220 if (isCollection) {
221 throw new Error(
222 `useLiveInfiniteQuery: Pre-created live query collection must have an orderBy clause for infinite pagination to work. ` +
223 `Please add .orderBy() to your createLiveQueryCollection query.`,
224 )
225 }
226 return
227 }
228​
229 // For pre-created collections, validate window on first check
230 if (isCollection && !hasValidatedCollectionRef.current) {
231 const currentWindow = utils.getWindow()
232 if (
233 currentWindow &&
234 (currentWindow.offset !== expectedOffset ||
235 currentWindow.limit !== expectedLimit)
236 ) {
237 console.warn(
238 `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +
239 `but hook expects {offset: ${expectedOffset}, limit: ${expectedLimit}}. Adjusting window now.`,
240 )
241 }
242 hasValidatedCollectionRef.current = true
243 }
244​
245 // For query functions, wait until collection is ready
246 if (!isCollection && !queryResult.isReady) return
247​
248 // Adjust the window
249 let cancelled = false
250 const result = utils.setWindow({
251 offset: expectedOffset,
252 limit: expectedLimit,
253 })
254​
255 if (result !== true) {
256 setIsFetchingNextPage(true)
257 result
258 .catch((error: unknown) => {
259 if (!cancelled)
260 console.error(`useLiveInfiniteQuery: setWindow failed:`, error)
261 })
262 .finally(() => {
263 if (!cancelled) setIsFetchingNextPage(false)
264 })
265 } else {
266 setIsFetchingNextPage(false)
267 }
268​
269 return () => {
270 cancelled = true
271 }
272 }, [
273 isCollection,
274 queryResult.collection,
275 queryResult.isReady,
276 loadedPageCount,
277 pageSize,
278 ])
279​
280 // Split the data array into pages and determine if there's a next page
281 const { pages, pageParams, hasNextPage, flatData } = useMemo(() => {
282 const dataArray = (
283 Array.isArray(queryResult.data) ? queryResult.data : []
284 ) as InferResultType<TContext>
285 const totalItemsRequested = loadedPageCount * pageSize
286​
287 // Check if we have more data than requested (the peek ahead item)
288 const hasMore = dataArray.length > totalItemsRequested
289​
290 // Build pages array (without the peek ahead item)
291 const pagesResult: Array<Array<InferResultType<TContext>[number]>> = []
292 const pageParamsResult: Array<number> = []
293​
294 for (let i = 0; i < loadedPageCount; i++) {
295 const pageData = dataArray.slice(i * pageSize, (i + 1) * pageSize)
296 pagesResult.push(pageData)
297 pageParamsResult.push(initialPageParam + i)
298 }
299​
300 // Flatten the pages for the data return (without peek ahead item)
301 const flatDataResult = dataArray.slice(
302 0,
303 totalItemsRequested,
304 ) as InferResultType<TContext>
305​
306 return {
307 pages: pagesResult,
308 pageParams: pageParamsResult,
309 hasNextPage: hasMore,
310 flatData: flatDataResult,
311 }
312 }, [queryResult.data, loadedPageCount, pageSize, initialPageParam])
313​
314 // Fetch next page
315 const fetchNextPage = useCallback(() => {
316 if (!hasNextPage || isFetchingNextPage) return
317​
318 setLoadedPageCount((prev) => prev + 1)
319 }, [hasNextPage, isFetchingNextPage])
320​
321 return {
322 ...queryResult,
323 data: flatData,
324 pages,
325 pageParams,
326 fetchNextPage,
327 hasNextPage,
328 isFetchingNextPage,
329 } as UseLiveInfiniteQueryReturn<TContext>