Open History to see the last commit
1import { computed, shallowRef, toValue, watchEffect } from 'vue'
2import {
3 assertLiveQueryWindowManyResult,
4 compareLiveQueryWindowDependencies,
5 createLiveQueryCollection,
6 createLiveQueryWindowController,
7 fetchNextLiveQueryWindowPage,
8 getLiveQueryWindowCollectionWarning,
9 normalizeLiveQueryWindowPageSize,
10 resolveLiveQueryWindowInput,
11 shouldPreserveLiveQueryWindowPageCount,
12} from '@tanstack/db'
13import type {
14 Collection,
15 CollectionStatus,
16 Context,
17 GetResult,
18 InferResultType,
19 InitialQueryBuilder,
20 NonSingleResult,
21 QueryBuilder,
22 UtilsRecord,
23} from '@tanstack/db'
24import type { ComputedRef, MaybeRefOrGetter } from 'vue'
25
26const DEFAULT_GC_TIME_MS = 1
27
28type InternalCollection = Collection<object, string | number, UtilsRecord>
29
30type PreviousController = {
31 getSnapshot: () => { pages: ReadonlyArray<ReadonlyArray<unknown>> }
32}
33
34type InfiniteQueryOptions = {
35 pageSize?: number
36 initialPageParam?: number
37}
38
39export type LiveInfiniteQueryConfig<TRow> = InfiniteQueryOptions & {
40 /**
41 * @deprecated Pagination uses the shared controller's peek-ahead strategy.
42 * This remains for compatibility with TanStack Query conventions.
43 */
44 getNextPageParam?: (
45 lastPage: Array<TRow>,
46 allPages: Array<Array<TRow>>,
47 lastPageParam: number,
48 allPageParams: Array<number>,
49 ) => number | undefined
50}
51
52export type UseLiveInfiniteQueryConfig<
53 TContext extends Context & NonSingleResult,
54> = LiveInfiniteQueryConfig<InferResultType<TContext>[number]>
55
56export interface UseLiveInfiniteQueryReturn<
57 TContext extends Context & NonSingleResult,
58> {
59 state: ComputedRef<Map<string | number, GetResult<TContext>>>
60 data: ComputedRef<InferResultType<TContext>>
61 collection: ComputedRef<
62 Collection<GetResult<TContext>, string | number, UtilsRecord>
63 >
64 status: ComputedRef<CollectionStatus>
65 isLoading: ComputedRef<boolean>
66 isReady: ComputedRef<boolean>
67 isIdle: ComputedRef<boolean>
68 isError: ComputedRef<boolean>
69 isCleanedUp: ComputedRef<boolean>
70 pages: ComputedRef<Array<Array<InferResultType<TContext>[number]>>>
71 pageParams: ComputedRef<Array<number>>
72 fetchNextPage: () => Promise<void>
73 hasNextPage: ComputedRef<boolean>
74 isFetchingNextPage: ComputedRef<boolean>
75 error: ComputedRef<unknown>
76}
77
78export interface UseLiveInfiniteQueryReturnWithCollection<
79 TResult extends object,
80 TKey extends string | number,
81 TUtils extends UtilsRecord,
82> {
83 state: ComputedRef<Map<TKey, TResult>>
84 data: ComputedRef<Array<TResult>>
85 collection: ComputedRef<Collection<TResult, TKey, TUtils>>
86 status: ComputedRef<CollectionStatus>
87 isLoading: ComputedRef<boolean>
88 isReady: ComputedRef<boolean>
89 isIdle: ComputedRef<boolean>
90 isError: ComputedRef<boolean>
91 isCleanedUp: ComputedRef<boolean>
92 pages: ComputedRef<Array<Array<TResult>>>
93 pageParams: ComputedRef<Array<number>>
94 fetchNextPage: () => Promise<void>
95 hasNextPage: ComputedRef<boolean>
96 isFetchingNextPage: ComputedRef<boolean>
97 error: ComputedRef<unknown>
98}
99
100/**
101 * Create a Vue-native reactive view over the shared live-query window
102 * controller. The query must include an `orderBy` clause.
103 */
104export function useLiveInfiniteQuery<
105 TResult extends object,
106 TKey extends string | number,
107 TUtils extends UtilsRecord,
108>(
109 liveQueryCollection: MaybeRefOrGetter<
110 Collection<TResult, TKey, TUtils> & NonSingleResult
111 >,
112 config: LiveInfiniteQueryConfig<TResult>,
113): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>
114
115export function useLiveInfiniteQuery<
116 TContext extends Context & NonSingleResult,
117>(
118 queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
119 config: UseLiveInfiniteQueryConfig<TContext>,
120 deps?: Array<MaybeRefOrGetter<unknown>>,
121): UseLiveInfiniteQueryReturn<TContext>
122
123export function useLiveInfiniteQuery<
124 TContext extends Context & NonSingleResult,
125>(
126 queryFnOrCollection: unknown,
127 config: InfiniteQueryOptions,
128 deps: Array<MaybeRefOrGetter<unknown>> = [],
129): UseLiveInfiniteQueryReturn<TContext> {
130 let validatedCollection: InternalCollection | null = null
131 let previousController: PreviousController | null = null
132 let previousInput: ReturnType<
133 typeof resolveLiveQueryWindowInput<TContext>
134 > | null = null
135 let previousDependencies: Array<unknown> | null = null
136 let previousPageSize: number | null = null
137 let previousInitialPageParam: number | null = null
138
139 const controller = computed(() => {
140 const dependencies = deps.map((dependency) => toValue(dependency))
141
142 const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)
143 const initialPageParam = config.initialPageParam ?? 0
144 const unwrappedInput =
145 typeof queryFnOrCollection === `function`
146 ? queryFnOrCollection
147 : toValue(queryFnOrCollection)
148 const input = resolveLiveQueryWindowInput<TContext>(unwrappedInput)
149 const dependencyComparison = compareLiveQueryWindowDependencies(
150 previousDependencies,
151 dependencies,
152 )
153 const dependenciesChanged = dependencyComparison.changed
154 const dependenciesStructurallyEqual = dependencyComparison.structurallyEqual
155 const pageShapeChanged =
156 previousPageSize !== pageSize ||
157 previousInitialPageParam !== initialPageParam
158 const sameCollection =
159 input.kind === `collection` &&
160 previousInput?.kind === `collection` &&
161 previousInput.collection === input.collection
162 const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({
163 hasPreviousController: previousController !== null,
164 previousInputKind: previousInput?.kind,
165 inputKind: input.kind,
166 sameCollection,
167 dependenciesChanged,
168 dependenciesStructurallyEqual,
169 pageShapeChanged,
170 })
171 const previousPageCount = previousController
172 ? Math.max(1, previousController.getSnapshot().pages.length)
173 : 1
174 const initialPageCount = canPreservePageCount ? previousPageCount : 1
175
176 previousInput = input
177 previousDependencies = [...dependencies]
178 previousPageSize = pageSize
179 previousInitialPageParam = initialPageParam
180
181 if (input.kind === `collection`) {
182 const collection = input.collection
183 const warning = getLiveQueryWindowCollectionWarning(
184 collection,
185 pageSize + 1,
186 )
187
188 if (validatedCollection !== collection) {
189 validatedCollection = collection
190 if (warning) console.warn(warning)
191 }
192
193 const currentController = createLiveQueryWindowController(collection, {
194 pageSize,
195 initialPageParam,
196 initialPageCount,
197 })
198 previousController = currentController
199 return currentController
200 }
201
202 const collection = createLiveQueryCollection({
203 query: input.query.limit(pageSize + 1).offset(0),
204 startSync: false,
205 gcTime: DEFAULT_GC_TIME_MS,
206 })
207 assertLiveQueryWindowManyResult(collection)
208 const currentController = createLiveQueryWindowController(collection, {
209 pageSize,
210 initialPageParam,
211 initialPageCount,
212 })
213 previousController = currentController
214 return currentController
215 })
216
217 const snapshot = shallowRef(controller.value.getSnapshot())
218
219 watchEffect(
220 (onInvalidate) => {
221 const currentController = controller.value
222 const updateSnapshot = () => {
223 snapshot.value = currentController.getSnapshot()
224 }
225
226 updateSnapshot()
227 const unsubscribe = currentController.subscribe(updateSnapshot)
228 updateSnapshot()
229
230 onInvalidate(() => {
231 unsubscribe()
232 currentController.dispose()
233 })
234 },
235 { flush: `sync` },
236 )
237
238 return {
239 state: computed(
240 () => snapshot.value.state as Map<string | number, GetResult<TContext>>,
241 ),
242 data: computed(() => snapshot.value.data as InferResultType<TContext>),
243 collection: computed(
244 () =>
245 snapshot.value.collection as Collection<
246 GetResult<TContext>,
247 string | number,
248 UtilsRecord
249 >,
250 ),
251 status: computed(() => snapshot.value.status as CollectionStatus),
252 isLoading: computed(() => snapshot.value.isLoading),
253 isReady: computed(() => snapshot.value.isReady),
254 isIdle: computed(() => snapshot.value.isIdle),
255 isError: computed(() => snapshot.value.isError),
256 isCleanedUp: computed(() => snapshot.value.isCleanedUp),
257 pages: computed(
258 () =>
259 snapshot.value.pages as Array<Array<InferResultType<TContext>[number]>>,
260 ),
261 pageParams: computed(() => snapshot.value.pageParams as Array<number>),
262 fetchNextPage: () => fetchNextLiveQueryWindowPage(controller.value),
263 hasNextPage: computed(() => snapshot.value.hasNextPage),
264 isFetchingNextPage: computed(() => snapshot.value.isFetchingNextPage),
265 error: computed(() => snapshot.value.error),
266 }
267}