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

useLiveQuery.ts

652 lines19.0 KB

1import {
2 batch,
3 createEffect,
4 createMemo,
5 createResource,
6 createSignal,
7 onCleanup,
8} from 'solid-js'
9import { ReactiveMap } from '@solid-primitives/map'
10import {
11 BaseQueryBuilder,
12 createLiveQueryObserver,
13 getPublicCollection,
14 isCollection,
15 isSingleResultCollection,
16 resolveLiveQueryValue,
17} from '@tanstack/db'
18import { createStore, reconcile } from 'solid-js/store'
19import type { Accessor } from 'solid-js'
20import type {
21 ChangeMessage,
22 Collection,
23 CollectionStatus,
24 Context,
25 GetResult,
26 InferResultType,
27 InitialQueryBuilder,
28 LiveQueryCollectionConfig,
29 LiveQueryObserver,
30 LiveQueryPersistedStatus,
31 NonSingleResult,
32 QueryBuilder,
33 SingleResult,
34} from '@tanstack/db'
35​
36const DEFAULT_GC_TIME_MS = 1
37​
38type InferConditionalResultType<TContext extends Context> =
39 TContext extends SingleResult
40 ? InferResultType<TContext> | []
41 : InferResultType<TContext>
42​
43/**
44 * Create a live query using a query function
45 * @param queryFn - Query function that defines what data to fetch
46 * @returns Accessor that returns data with Suspense support, with state and status information as properties
47 * @example
48 * // Basic query with object syntax
49 * const todosQuery = useLiveQuery((q) =>
50 * q.from({ todos: todosCollection })
51 * .where(({ todos }) => eq(todos.completed, false))
52 * .select(({ todos }) => ({ id: todos.id, text: todos.text }))
53 * )
54 *
55 * @example
56 * // With dependencies that trigger re-execution
57 * const todosQuery = useLiveQuery(
58 * (q) => q.from({ todos: todosCollection })
59 * .where(({ todos }) => gt(todos.priority, minPriority())),
60 * )
61 *
62 * @example
63 * // Join pattern
64 * const personIssues = useLiveQuery((q) =>
65 * q.from({ issues: issueCollection })
66 * .join({ persons: personCollection }, ({ issues, persons }) =>
67 * eq(issues.userId, persons.id)
68 * )
69 * .select(({ issues, persons }) => ({
70 * id: issues.id,
71 * title: issues.title,
72 * userName: persons.name
73 * }))
74 * )
75 *
76 * @example
77 * // Handle loading and error states
78 * const todosQuery = useLiveQuery((q) =>
79 * q.from({ todos: todoCollection })
80 * )
81 *
82 * return (
83 * <Switch>
84 * <Match when={todosQuery.isLoading}>
85 * <div>Loading...</div>
86 * </Match>
87 * <Match when={todosQuery.isError}>
88 * <div>Error: {todosQuery.status}</div>
89 * </Match>
90 * <Match when={todosQuery.isReady}>
91 * <For each={todosQuery()}>
92 * {(todo) => <li key={todo.id}>{todo.text}</li>}
93 * </For>
94 * </Match>
95 * </Switch>
96 * )
97 *
98 * @example
99 * // Use Suspense boundaries
100 * const todosQuery = useLiveQuery((q) =>
101 * q.from({ todos: todoCollection })
102 * )
103 *
104 * return (
105 * <Suspense fallback={<div>Loading...</div>}>
106 * <For each={todosQuery()}>
107 * {(todo) => <li key={todo.id}>{todo.text}</li>}
108 * </For>
109 * </Suspense>
110 * )
111 */
112// Overload 1: Accept query function that always returns QueryBuilder
113export function useLiveQuery<TContext extends Context>(
114 queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
115): Accessor<InferResultType<TContext>> & {
116 /**
117 * @deprecated use function result instead
118 * query.data -> query()
119 */
120 data: InferResultType<TContext>
121 state: ReactiveMap<string | number, GetResult<TContext>>
122 collection: Collection<GetResult<TContext>, string | number, {}>
123 status: CollectionStatus
124 isLoading: boolean
125 isReady: boolean
126 persistedStatus: LiveQueryPersistedStatus
127 isPersistedReady: boolean
128 persistedError: unknown | undefined
129 isIdle: boolean
130 isError: boolean
131 isCleanedUp: boolean
133​
134// Overload 1b: Accept query function that can return undefined/null
135export function useLiveQuery<TContext extends Context>(
136 queryFn: (
137 q: InitialQueryBuilder,
138 ) => QueryBuilder<TContext> | undefined | null,
139): Accessor<InferConditionalResultType<TContext>> & {
140 /**
141 * @deprecated use function result instead
142 * query.data -> query()
143 */
144 data: InferConditionalResultType<TContext>
145 state: ReactiveMap<string | number, GetResult<TContext>>
146 collection: Collection<GetResult<TContext>, string | number, {}> | null
147 status: CollectionStatus | `disabled`
148 isLoading: boolean
149 isReady: boolean
150 persistedStatus: LiveQueryPersistedStatus
151 isPersistedReady: boolean
152 persistedError: unknown | undefined
153 isIdle: boolean
154 isError: boolean
155 isCleanedUp: boolean
157​
158/**
159 * Create a live query using configuration object
160 * @param config - Configuration object with query and options
161 * @returns Accessor that returns data with Suspense support, with state and status information as properties
162 * @example
163 * // Basic config object usage
164 * const todosQuery = useLiveQuery(() => ({
165 * query: (q) => q.from({ todos: todosCollection }),
166 * gcTime: 60000
167 * }))
168 *
169 * @example
170 * // With query builder and options
171 * const queryBuilder = new Query()
172 * .from({ persons: collection })
173 * .where(({ persons }) => gt(persons.age, 30))
174 * .select(({ persons }) => ({ id: persons.id, name: persons.name }))
175 *
176 * const personsQuery = useLiveQuery(() => ({ query: queryBuilder }))
177 *
178 * @example
179 * // Handle all states uniformly
180 * const itemsQuery = useLiveQuery(() => ({
181 * query: (q) => q.from({ items: itemCollection })
182 * }))
183 *
184 * return (
185 * <Switch fallback={<div>{itemsQuery().length} items loaded</div>}>
186 * <Match when={itemsQuery.isLoading}>
187 * <div>Loading...</div>
188 * </Match>
189 * <Match when={itemsQuery.isError}>
190 * <div>Something went wrong</div>
191 * </Match>
192 * <Match when={!itemsQuery.isReady}>
193 * <div>Preparing...</div>
194 * </Match>
195 * </Switch>
196 * )
197 */
198// Overload 2: Accept config object
199export function useLiveQuery<TContext extends Context>(
200 config: Accessor<LiveQueryCollectionConfig<TContext>>,
201): Accessor<InferResultType<TContext>> & {
202 /**
203 * @deprecated use function result instead
204 * query.data -> query()
205 */
206 data: InferResultType<TContext>
207 state: ReactiveMap<string | number, GetResult<TContext>>
208 collection: Collection<GetResult<TContext>, string | number, {}>
209 status: CollectionStatus
210 isLoading: boolean
211 isReady: boolean
212 persistedStatus: LiveQueryPersistedStatus
213 isPersistedReady: boolean
214 persistedError: unknown | undefined
215 isIdle: boolean
216 isError: boolean
217 isCleanedUp: boolean
219​
220/**
221 * Subscribe to an existing live query collection
222 * @param liveQueryCollection - Pre-created live query collection to subscribe to
223 * @returns Accessor that returns data with Suspense support, with state and status information as properties
224 * @example
225 * // Using pre-created live query collection
226 * const myLiveQuery = createLiveQueryCollection((q) =>
227 * q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
228 * )
229 * const todosQuery = useLiveQuery(() => myLiveQuery)
230 *
231 * @example
232 * // Access collection methods directly
233 * const existingQuery = useLiveQuery(() => existingCollection)
234 *
235 * // Use collection for mutations
236 * const handleToggle = (id) => {
237 * existingQuery.collection.update(id, draft => { draft.completed = !draft.completed })
238 * }
239 *
240 * @example
241 * // Handle states consistently
242 * const sharedQuery = useLiveQuery(() => sharedCollection)
243 *
244 * return (
245 * <Switch fallback={<div><For each={sharedQuery()}>{(item) => <Item key={item.id} {...item} />}</For></div>}>
246 * <Match when={sharedQuery.isLoading}>
247 * <div>Loading...</div>
248 * </Match>
249 * <Match when={sharedQuery.isError}>
250 * <div>Error loading data</div>
251 * </Match>
252 * </Switch>
253 * )
254 */
255// Overload 3: Accept pre-created live query collection (non-single result)
256export function useLiveQuery<
257 TResult extends object,
258 TKey extends string | number,
259 TUtils extends Record<string, any>,
260>(
261 liveQueryCollection: Accessor<
262 Collection<TResult, TKey, TUtils> & NonSingleResult
263 >,
264): Accessor<Array<TResult>> & {
265 /**
266 * @deprecated use function result instead
267 * query.data -> query()
268 */
269 data: Array<TResult>
270 state: ReactiveMap<TKey, TResult>
271 collection: Collection<TResult, TKey, TUtils>
272 status: CollectionStatus
273 isLoading: boolean
274 isReady: boolean
275 persistedStatus: LiveQueryPersistedStatus
276 isPersistedReady: boolean
277 persistedError: unknown | undefined
278 isIdle: boolean
279 isError: boolean
280 isCleanedUp: boolean
282​
283// Overload 3b: Accept pre-created live query collection with singleResult: true
284export function useLiveQuery<
285 TResult extends object,
286 TKey extends string | number,
287 TUtils extends Record<string, any>,
288>(
289 liveQueryCollection: Accessor<
290 Collection<TResult, TKey, TUtils> & SingleResult
291 >,
292): Accessor<TResult | undefined> & {
293 /**
294 * @deprecated use function result instead
295 * query.data -> query()
296 */
297 data: TResult | undefined
298 state: ReactiveMap<TKey, TResult>
299 collection: Collection<TResult, TKey, TUtils> & SingleResult
300 status: CollectionStatus
301 isLoading: boolean
302 isReady: boolean
303 persistedStatus: LiveQueryPersistedStatus
304 isPersistedReady: boolean
305 persistedError: unknown | undefined
306 isIdle: boolean
307 isError: boolean
308 isCleanedUp: boolean
310​
311// Implementation - use function overloads to infer the actual collection type
312export function useLiveQuery(
313 configOrQueryOrCollection: (queryFn?: any) => any,
314) {
315 const collection = createMemo(
316 () => {
317 if (configOrQueryOrCollection.length === 1) {
318 // This is a query function - check if it returns null/undefined
319 const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder
320 const result = configOrQueryOrCollection(queryBuilder)
321​
322 if (result === undefined || result === null) {
323 // Disabled query - return null
324 return null
325 }
326​
327 return resolveLiveQueryValue(result, { gcTime: DEFAULT_GC_TIME_MS })
328 }
329​
330 const innerCollection = configOrQueryOrCollection()
331​
332 if (innerCollection === undefined || innerCollection === null) {
333 // Disabled query - return null
334 return null
335 }
336​
337 if (isCollection(innerCollection)) {
338 innerCollection.startSyncImmediate()
339 return innerCollection as Collection
340 }
341​
342 return resolveLiveQueryValue(innerCollection, {
343 gcTime: DEFAULT_GC_TIME_MS,
344 })
345 },
346 undefined,
347 { name: `TanstackDBCollectionMemo` },
348 )
349​
350 // Reactive state that gets updated granularly through change events
351 const state = new ReactiveMap<string | number, any>()
352​
353 // Keep the live Collection's result keys private while preserving one stable
354 // Solid store per logical row. A row's public $key can belong to an upstream
355 // Collection and is therefore not necessarily unique in this result.
356 const rowsByKey = new Map<
357 string | number,
358 { value: any; update: (value: any) => void }
359 >()
360 let rowsCollection: Collection<any, any, any> | undefined
361 const [data, setData] = createStore<Array<any>>([], {
362 name: `TanstackDBData`,
363 })
364​
365 // Track collection status reactively
366 const [status, setStatus] = createSignal(
367 collection() ? collection()!.status : (`disabled` as const),
368 {
369 name: `TanstackDBStatus`,
370 },
371 )
372 const [persistedStatus, setLocalStatus] =
373 createSignal<LiveQueryPersistedStatus>(`unavailable`)
374 const [persistedError, setLocalError] = createSignal<unknown>(undefined)
375​
376 // Helper to sync data array from collection in correct order
377 const syncDataFromCollection = (
378 currentCollection: Collection<any, any, any>,
379 ) => {
380 const nextRows: Array<any> = []
381 const retainedKeys = new Set<string | number>()
382​
383 for (const [key, value] of currentCollection.entries()) {
384 retainedKeys.add(key)
385​
386 const existing = rowsByKey.get(key)
387 if (existing) {
388 existing.update(value)
389 nextRows.push(existing.value)
390 } else {
391 const [row, setRow] = createStore(value)
392 rowsByKey.set(key, {
393 value: row,
394 update: (nextValue) => setRow(reconcile(nextValue, { key: null })),
395 })
396 nextRows.push(row)
397 }
398 }
399​
400 for (const key of rowsByKey.keys()) {
401 if (!retainedKeys.has(key)) rowsByKey.delete(key)
402 }
403​
404 setData((previous) => reconcile(nextRows, { key: null })(previous))
405 }
406​
407 // Generation guard for the resource's async continuations: Solid discards a
408 // superseded fetch's *return value*, but the writes below are side effects
409 // into hook-scoped state and would still run — resurrecting rows/status from
410 // a collection that has already been replaced.
411 let resourceGeneration = 0
412 let localWait:
413 | {
414 observer: LiveQueryObserver<any, any>
415 collection: Collection<any, any, any>
416 ready: boolean
417 }
418 | undefined
419 let subscribedCollection: Collection<any, any, any> | undefined
420 const releaseLocalWait = () => {
421 localWait?.observer.dispose()
422 localWait = undefined
423 }
424 onCleanup(() => {
425 resourceGeneration++
426 releaseLocalWait()
427 })
428​
429 const [getDataResource] = createResource(
430 () => ({ currentCollection: collection() }),
431 async ({ currentCollection }) => {
432 const generation = ++resourceGeneration
433 releaseLocalWait()
434 if (!currentCollection) {
435 return []
436 }
437 setStatus(currentCollection.status)
438 try {
439 const observer = createLiveQueryObserver(currentCollection)
440 localWait = {
441 observer,
442 collection: currentCollection,
443 ready: false,
444 }
445 try {
446 await observer.preloadForInitialRender()
447 } catch (error) {
448 if (generation === resourceGeneration) releaseLocalWait()
449 throw error
450 }
451 if (generation !== resourceGeneration) return data
452 localWait.ready = true
453 // `preloadForInitialRender` waits for readiness but does not itself
454 // retain the Collection after it settles. Hold one observer
455 // subscription across Solid's ready-before-commit Suspense gap.
456 observer.subscribe(() => {})
457 // Solid disposes a provisional effect only after the resource settles
458 // and Suspense re-evaluates the branch. Check on the next turn: a real
459 // commit still owns the Collection, while a suspended branch keeps the
460 // preload observer until its later commit or root cleanup.
461 setTimeout(() => {
462 if (
463 localWait?.observer === observer &&
464 subscribedCollection === currentCollection
465 ) {
466 releaseLocalWait()
467 }
468 }, 0)
469 } catch (error) {
470 if (generation !== resourceGeneration) return data
471 setStatus(`error`)
472 throw error
473 }
474 if (generation !== resourceGeneration) {
475 return data
476 }
477 // Initialize state with current collection data
478 batch(() => {
479 state.clear()
480 for (const [key, value] of currentCollection.entries()) {
481 state.set(key, value)
482 }
483 syncDataFromCollection(currentCollection)
484 setStatus(currentCollection.status)
485 })
486 return data
487 },
488 {
489 name: `TanstackDBData`,
490 deferStream: false,
491 initialValue: data,
492 },
493 )
494​
495 createEffect(() => {
496 const currentCollection = collection()
497 if (!currentCollection) {
498 setStatus(`disabled` as const)
499 setLocalStatus(`unavailable`)
500 setLocalError(undefined)
501 state.clear()
502 rowsByKey.clear()
503 rowsCollection = undefined
504 setData([])
505 return
506 }
507​
508 if (rowsCollection !== currentCollection) {
509 rowsByKey.clear()
510 rowsCollection = currentCollection
511 }
512​
513 // The shared observer owns subscription, the ready-race, and status; Solid
514 // materializes into its keyed ReactiveMap (granular) + reconciled store.
515 const observer = createLiveQueryObserver(currentCollection)
516 // Clear any keys carried over from a previous collection before the new
517 // observer re-seeds via `includeInitialState` (which only inserts current
518 // rows, never deletes stale ones). Without this, switching collections
519 // leaves the dropped keys in `state` until the async resource reconciles.
520 state.clear()
521 const unsubscribe = observer.subscribe(
522 (changes: Array<ChangeMessage<any>> | undefined) => {
523 batch(() => {
524 if (changes) {
525 for (const change of changes) {
526 switch (change.type) {
527 case `insert`:
528 case `update`:
529 state.set(change.key, change.value)
530 break
531 case `delete`:
532 state.delete(change.key)
533 break
534 }
535 }
536 } else {
537 // Cleanup and other status-only publications carry no row deltas.
538 // Rebuild the keyed view so it cannot diverge from ordered data.
539 state.clear()
540 for (const [key, value] of observer.getSnapshot().state ?? []) {
541 state.set(key, value)
542 }
543 }
544 syncDataFromCollection(currentCollection)
545 const snapshot = observer.getSnapshot()
546 setStatus(snapshot.status)
547 setLocalStatus(snapshot.persistedStatus)
548 setLocalError(snapshot.persistedError)
549 })
550 },
551 )
552 subscribedCollection = currentCollection
553 if (localWait?.ready && localWait.collection === currentCollection) {
554 releaseLocalWait()
555 }
556 // An already-ready empty collection produces no initial row batch. Bring
557 // ordered data and status in line synchronously instead of waiting for the
558 // resource continuation to correct the previous collection's rows.
559 batch(() => {
560 syncDataFromCollection(currentCollection)
561 const snapshot = observer.getSnapshot()
562 setStatus(snapshot.status)
563 setLocalStatus(snapshot.persistedStatus)
564 setLocalError(snapshot.persistedError)
565 })
566​
567 onCleanup(() => {
568 if (subscribedCollection === currentCollection) {
569 subscribedCollection = undefined
570 }
571 unsubscribe()
572 observer.dispose()
573 })
574 })
575​
576 // We have to remove getters from the resource function so we wrap it
577 function getData() {
578 const currentCollection = collection()
579 if (currentCollection) {
580 if (isSingleResultCollection(currentCollection)) {
581 // Force resource tracking so Suspense works
582 getDataResource()
583 return data[0]
584 }
585 }
586 return getDataResource()
587 }
588​
589 Object.defineProperties(getData, {
590 data: {
591 get() {
592 return getData()
593 },
594 },
595 status: {
596 get() {
597 return status()
598 },
599 },
600 collection: {
601 get() {
602 return getPublicCollection(collection())
603 },
604 },
605 state: {
606 get() {
607 return state
608 },
609 },
610 isLoading: {
611 get() {
612 return status() === `loading`
613 },
614 },
615 isReady: {
616 get() {
617 return status() === `ready` || status() === `disabled`
618 },
619 },
620 persistedStatus: {
621 get() {
622 return persistedStatus()
623 },
624 },
625 isPersistedReady: {
626 get() {
627 return persistedStatus() === `ready`
628 },
629 },
630 persistedError: {
631 get() {
632 return persistedError()
633 },
634 },
635 isIdle: {
636 get() {
637 return status() === `idle`
638 },
639 },
640 isError: {
641 get() {
642 return status() === `error`
643 },
644 },
645 isCleanedUp: {
646 get() {
647 return status() === `cleaned-up`
648 },
649 },
650 })
651 return getData