Open History to see the last commit
1'use client'
2
3import { useCallback, useRef, useSyncExternalStore } from 'react'
4import {
5 assertLiveQueryWindowManyResult,
6 compareLiveQueryWindowDependencies,
7 createLiveQueryCollection,
8 createLiveQueryWindowController,
9 fetchNextLiveQueryWindowPage,
10 getLiveQueryWindowCollectionWarning,
11 getLiveQueryWindowInputKind,
12 liveQueryWindowMatches,
13 normalizeLiveQueryWindowPageSize,
14 resolveLiveQueryWindowInput,
15 shouldPreserveLiveQueryWindowPageCount,
16} from '@tanstack/db'
17import { useOptionalDbClient } from './DbProvider'
18import {
19 claimSourceIds,
20 createSourceIdBindings,
21 resumeSyncStarts,
22} from './source-id-bindings'
23import {
24 prepareDerivedQuery,
25 prepareQueryValue,
26 warnDeprecatedDepsArray,
27 warnUnhashableDerivedIdentity,
28} from './useLiveQuery'
29import type { SourceIdBindings } from './source-id-bindings'
30import type {
31 DerivedIdentityProfiler,
32 LiveQueryKey,
33 useLiveQuery,
34} from './useLiveQuery'
35import type {
36 Collection,
37 CollectionImpl as CollectionImplType,
38 CollectionStatus,
39 Context,
40 DbClient,
41 InferResultType,
42 InitialQueryBuilder,
43 LiveQueryPersistedStatus,
44 LiveQueryWindowController,
45 NonSingleResult,
46 QueryBuilder,
47} from '@tanstack/db'
48
49// Live queries created here are cleaned up immediately (0 disables GC).
50const DEFAULT_GC_TIME_MS = 1
51const unpreparedQueryValue = Symbol(`unpreparedQueryValue`)
52
53// Keep the generic parameter for existing typed config wrappers.
54export type UseLiveInfiniteQueryConfig<_TContext extends Context> = {
55 /**
56 * Explicit identity for queries that contain opaque functional variants or
57 * are hot enough that deriving identity from structured IR is too expensive.
58 * Structured queries should omit this so DB can derive identity directly.
59 */
60 queryKey?: LiveQueryKey
61 /** Override the nearest DbProvider for this query. */
62 client?: DbClient
63 pageSize?: number
64 /** First result-page label, not a server cursor or remote offset. */
65 initialPageParam?: number
66}
67
68export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<
69 ReturnType<typeof useLiveQuery<TContext>>,
70 `data`
71> & {
72 data: InferResultType<TContext>
73 pages: Array<Array<InferResultType<TContext>[number]>>
74 pageParams: Array<number>
75 fetchNextPage: () => Promise<void>
76 hasNextPage: boolean
77 isFetchingNextPage: boolean
78 error: unknown
79}
80
81export type UseLiveInfiniteQueryReturnWithCollection<
82 TResult extends object,
83 TKey extends string | number,
84 TUtils extends Record<string, any>,
85> = {
86 data: Array<TResult>
87 state: Map<TKey, TResult>
88 collection: Collection<TResult, TKey, TUtils> & NonSingleResult
89 status: CollectionStatus
90 isLoading: boolean
91 isReady: boolean
92 persistedStatus: LiveQueryPersistedStatus
93 isPersistedReady: boolean
94 persistedError: unknown | undefined
95 isIdle: boolean
96 isError: boolean
97 isCleanedUp: boolean
98 isEnabled: true
99 pages: Array<Array<TResult>>
100 pageParams: Array<number>
101 fetchNextPage: () => Promise<void>
102 hasNextPage: boolean
103 isFetchingNextPage: boolean
104 error: unknown
105}
106
107type EnabledLiveQueryReturn<TContext extends Context> = ReturnType<
108 typeof useLiveQuery<TContext>
109>
110
111type InfiniteQueryRenderState = {
112 inputKind: `collection` | `query`
113 inputCollection: Collection<any, any, any> | null
114 inputQuery: unknown
115 client: DbClient | undefined
116 identityMode: `collection` | `queryKey` | `legacyDeps` | `derived`
117 dependencies: Array<unknown> | null
118 pageSize: number
119 initialPageParam: number
120 collection: Collection<any, any, any>
121 controller: LiveQueryWindowController<any, any>
122 warning: string | null
123 warned: boolean
124 deferredCollections: Set<
125 CollectionImplType<any, string | number, any, any, any>
126 >
127}
128
129type RenderedWindowCollection = {
130 client: DbClient | undefined
131 dependencies: Array<unknown>
132 collection: Collection<any, any, any>
133 deferredCollections: Set<
134 CollectionImplType<any, string | number, any, any, any>
135 >
136}
137
138/**
139 * Whether a recorded query identity matches the current one. Legacy deps
140 * compare by reference. Derived identities and query keys compare by structure.
141 */
142function queryIdentityMatches(
143 comparison: { changed: boolean; structurallyEqual: boolean },
144 sameClient: boolean,
145 usesLegacyDeps: boolean,
146): boolean {
147 return (
148 sameClient &&
149 (usesLegacyDeps ? !comparison.changed : comparison.structurallyEqual)
150 )
151}
152
153/**
154 * Create an infinite query using a query function with live updates.
155 *
156 * Uses `utils.setWindow()` to dynamically adjust the limit/offset window
157 * without recreating the live query collection on each page change.
158 *
159 * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.
160 * @param config - Configuration including pageSize and an optional initial page label
161 * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
162 * @returns Object with pages, data, and pagination controls
163 */
164
165// Overload for pre-created collection (non-single result)
166export function useLiveInfiniteQuery<
167 TResult extends object,
168 TKey extends string | number,
169 TUtils extends Record<string, any>,
170>(
171 liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
172 config: UseLiveInfiniteQueryConfig<any>,
173): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>
174
175// Overload for query function
176export function useLiveInfiniteQuery<TContext extends Context>(
177 queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
178 config: UseLiveInfiniteQueryConfig<TContext>,
179 deps?: Array<unknown>,
180): UseLiveInfiniteQueryReturn<TContext>
181
182// Implementation
183export function useLiveInfiniteQuery<TContext extends Context>(
184 queryFnOrCollection: any,
185 config: UseLiveInfiniteQueryConfig<TContext>,
186 deps?: Array<unknown>,
187): UseLiveInfiniteQueryReturn<TContext> {
188 if (`getNextPageParam` in config) {
189 throw new Error(
190 `getNextPageParam is not supported by useLiveInfiniteQuery. Use an on-demand collection and fulfill meta.loadSubsetOptions in queryFn for server pagination.`,
191 )
192 }
193 const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)
194 const initialPageParam = config.initialPageParam ?? 0
195 const contextDbClient = useOptionalDbClient()
196 const dbClient = config.client ?? contextDbClient
197
198 const inputIsCollection =
199 getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`
200
201 const committedRef = useRef<InfiniteQueryRenderState | null>(null)
202 const committed = committedRef.current
203 // Like useLiveQuery's instance memo, keep the window collection built by the
204 // latest render. A second render before commit, such as a StrictMode double
205 // render, reuses it instead of starting another one. Only the collection is
206 // kept. Each render still builds its own controller and page count from the
207 // committed state, which an uncommitted render never changes.
208 const renderedCollectionRef = useRef<RenderedWindowCollection | null>(null)
209 const sourceIdsRef = useRef<SourceIdBindings | null>(null)
210 const inputKind = inputIsCollection ? `collection` : `query`
211 const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({
212 renderCount: 0,
213 totalMs: 0,
214 maxMs: 0,
215 warned: false,
216 })
217 const legacyUnhashableIdentityRef = useRef<Array<unknown>>([
218 `legacy-unhashable`,
219 ])
220 const deferredCollections = new Set<
221 CollectionImplType<any, string | number, any, any, any>
222 >()
223
224 let preparedQueryValue: unknown | typeof unpreparedQueryValue =
225 unpreparedQueryValue
226 let identityDeps: ReadonlyArray<unknown> = []
227 let identityMode: InfiniteQueryRenderState[`identityMode`] = `collection`
228
229 if (!inputIsCollection) {
230 if (config.queryKey !== undefined) {
231 identityMode = `queryKey`
232 identityDeps = config.queryKey
233 } else if (deps !== undefined) {
234 identityMode = `legacyDeps`
235 identityDeps = deps
236 warnDeprecatedDepsArray(`useLiveInfiniteQuery`)
237 } else if (
238 committed?.identityMode === `derived` &&
239 committed.inputQuery === queryFnOrCollection &&
240 committed.client === dbClient
241 ) {
242 identityMode = `derived`
243 identityDeps = committed.dependencies ?? []
244 } else {
245 identityMode = `derived`
246 const preparation = prepareDerivedQuery(
247 queryFnOrCollection,
248 dbClient,
249 derivedIdentityProfilerRef.current,
250 deferredCollections,
251 )
252 preparedQueryValue = preparation.value
253 claimSourceIds(
254 (sourceIdsRef.current ??= createSourceIdBindings()),
255 preparation.value,
256 dbClient,
257 `useLiveInfiniteQuery`,
258 () => resumeSyncStarts(deferredCollections),
259 )
260 if (preparation.status === `hashable`) {
261 identityDeps = preparation.identityDeps
262 } else {
263 warnUnhashableDerivedIdentity(preparation.error)
264 identityDeps = legacyUnhashableIdentityRef.current
265 }
266 }
267 }
268
269 const usesLegacyDeps =
270 !inputIsCollection && config.queryKey === undefined && deps !== undefined
271 const dependencyComparison = compareLiveQueryWindowDependencies(
272 committed?.dependencies,
273 identityDeps,
274 )
275 const sameClient = committed?.client === dbClient
276 const dependenciesChanged =
277 !inputIsCollection &&
278 !queryIdentityMatches(dependencyComparison, sameClient, usesLegacyDeps)
279 const dependenciesStructurallyEqual =
280 usesLegacyDeps && sameClient && dependencyComparison.structurallyEqual
281 const needsNewCollection =
282 committed === null ||
283 committed.inputKind !== inputKind ||
284 (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||
285 dependenciesChanged
286 const pageShapeChanged =
287 committed === null ||
288 committed.pageSize !== pageSize ||
289 committed.initialPageParam !== initialPageParam
290 const needsNewController =
291 committed === null || needsNewCollection || pageShapeChanged
292
293 let renderState = committed
294 if (needsNewController) {
295 let collection = committed?.collection
296 let warning: string | null = null
297 let startInRender = false
298 let suppliedCollection = false
299 let createdCollection = false
300
301 const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({
302 hasPreviousController: committed !== null,
303 previousInputKind: committed?.inputKind,
304 inputKind,
305 sameCollection:
306 inputIsCollection && committed?.inputCollection === queryFnOrCollection,
307 dependenciesChanged,
308 dependenciesStructurallyEqual,
309 pageShapeChanged,
310 })
311 const previousPageCount = committed
312 ? Math.max(1, committed.controller.getSnapshot().pages.length)
313 : 1
314 const initialPageCount = canPreservePageCount ? previousPageCount : 1
315 // The peek-ahead window for every retained page.
316 const requiredLimit = initialPageCount * pageSize + 1
317
318 if (needsNewCollection) {
319 let inputValue = queryFnOrCollection
320 if (!inputIsCollection) {
321 if (preparedQueryValue === unpreparedQueryValue) {
322 preparedQueryValue = prepareQueryValue(
323 queryFnOrCollection,
324 dbClient,
325 deferredCollections,
326 )
327 }
328 inputValue = () => preparedQueryValue
329 }
330 const rendered = renderedCollectionRef.current
331 if (
332 !inputIsCollection &&
333 rendered !== null &&
334 queryIdentityMatches(
335 compareLiveQueryWindowDependencies(
336 rendered.dependencies,
337 identityDeps,
338 ),
339 rendered.client === dbClient,
340 usesLegacyDeps,
341 ) &&
342 rendered.collection.status !== `cleaned-up` &&
343 rendered.collection.status !== `error` &&
344 liveQueryWindowMatches(rendered.collection, requiredLimit)
345 ) {
346 // An earlier render built this collection and nothing has committed
347 // since. Its window is exactly the retained pages, so its first
348 // rows are correct. Sources it deferred still resume at commit. A
349 // collection in terminal error, such as after its source restarted,
350 // cannot serve the query again, so a new one replaces it.
351 collection = rendered.collection
352 for (const deferred of rendered.deferredCollections) {
353 deferredCollections.add(deferred)
354 }
355 } else {
356 const input = resolveLiveQueryWindowInput<TContext>(inputValue)
357 if (input.kind === `collection`) {
358 collection = input.collection
359 suppliedCollection = true
360 // A supplied collection is never reused, so release the last one.
361 renderedCollectionRef.current = null
362 } else {
363 // Wrap the query with the peek-ahead window for every retained page,
364 // so a collection that starts syncing now never publishes fewer rows
365 // than the controller's pages. The controller grows the limit via
366 // setWindow.
367 collection = createLiveQueryCollection({
368 query: input.query.limit(requiredLimit).offset(0),
369 gcTime: DEFAULT_GC_TIME_MS,
370 })
371 startInRender = true
372 createdCollection = true
373 }
374 }
375 }
376
377 if (!collection) {
378 throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)
379 }
380
381 if (inputIsCollection) {
382 warning =
383 getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null
384 } else {
385 assertLiveQueryWindowManyResult(collection)
386 }
387 // Like useLiveQuery, start sync during render once the input is valid. A
388 // render reads only rows the sources already hold, such as a preloaded
389 // collection's, and sends no request until the subscription commits. GC
390 // reclaims a render that never commits. A supplied window that the
391 // controller must still adjust waits for the subscription.
392 if (suppliedCollection) {
393 startInRender = liveQueryWindowMatches(collection, requiredLimit)
394 }
395 if (startInRender) collection.startSyncImmediate()
396 // Keep a created collection for the next render only once it validated and
397 // started, so a retry after a startup error builds a new one and throws.
398 if (createdCollection) {
399 renderedCollectionRef.current = {
400 client: dbClient,
401 dependencies: [...identityDeps],
402 collection,
403 deferredCollections,
404 }
405 }
406
407 renderState = {
408 inputKind,
409 inputCollection: inputIsCollection ? collection : null,
410 inputQuery: inputIsCollection ? null : queryFnOrCollection,
411 client: dbClient,
412 identityMode,
413 dependencies: inputIsCollection ? null : [...identityDeps],
414 pageSize,
415 initialPageParam,
416 collection,
417 controller: createLiveQueryWindowController(collection, {
418 pageSize,
419 initialPageParam,
420 initialPageCount,
421 }),
422 warning,
423 warned: false,
424 deferredCollections,
425 }
426 }
427 const currentRenderState = renderState!
428 const controller = currentRenderState.controller
429
430 const subscribe = useCallback(
431 (onStoreChange: () => void) => {
432 const unsubscribe = controller.subscribe(onStoreChange)
433 committedRef.current = currentRenderState
434 if (currentRenderState.warning && !currentRenderState.warned) {
435 currentRenderState.warned = true
436 console.warn(currentRenderState.warning)
437 }
438 resumeSyncStarts(currentRenderState.deferredCollections)
439 return unsubscribe
440 },
441 [controller, currentRenderState],
442 )
443 const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])
444 const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
445
446 const fetchNextPage = useCallback(
447 () => fetchNextLiveQueryWindowPage(controller),
448 [controller],
449 )
450
451 return {
452 data: snapshot.data as InferResultType<TContext>,
453 get state() {
454 return snapshot.state as EnabledLiveQueryReturn<TContext>[`state`]
455 },
456 status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],
457 isLoading: snapshot.isLoading,
458 isReady: snapshot.isReady,
459 persistedStatus: snapshot.persistedStatus,
460 isPersistedReady: snapshot.isPersistedReady,
461 persistedError: snapshot.persistedError,
462 isIdle: snapshot.isIdle,
463 isError: snapshot.isError,
464 isCleanedUp: snapshot.isCleanedUp,
465 collection:
466 snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],
467 isEnabled: snapshot.isEnabled,
468 pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,
469 pageParams: snapshot.pageParams as Array<number>,
470 fetchNextPage,
471 hasNextPage: snapshot.hasNextPage,
472 isFetchingNextPage: snapshot.isFetchingNextPage,
473 error: snapshot.error,
474 }
475}