Open History to see the last commit
1'use client'
2
3import { useRef } from 'react'
4import { useLiveQueryForSuspense } from './useLiveQuery'
5import { getLiveQueryResultInfo } from './live-query-internals'
6import type { UseLiveQueryConfig } from './useLiveQuery'
7import type {
8 Collection,
9 Context,
10 DbClient,
11 GetResult,
12 InferResultType,
13 InitialQueryBuilder,
14 LiveQueryCollectionConfig,
15 NonSingleResult,
16 QueryBuilder,
17 SingleResult,
18} from '@tanstack/db'
19
20// React can discard a render that suspends, including its refs. Keep the
21// initial-render failure across retries, scoped by client because streamed
22// preloads of the same collection can fail independently.
23const initialRenderErrors = new WeakMap<
24 Collection<any, any, any>,
25 {
26 byClient: WeakMap<DbClient, { error: unknown; clientQuery?: object }>
27 unscoped?: { error: unknown; clientQuery?: object }
28 }
29>()
30
31function clearInitialRenderError(
32 collection: Collection<any, any, any>,
33 client: DbClient | undefined,
34) {
35 const entry = initialRenderErrors.get(collection)
36 if (!entry) return
37 if (client) entry.byClient.delete(client)
38 else delete entry.unscoped
39}
40
41function rememberInitialRenderError(
42 collection: Collection<any, any, any>,
43 client: DbClient | undefined,
44 error: unknown,
45 clientQuery?: object,
46) {
47 if (collection.status === `cleaned-up`) return
48 let entry = initialRenderErrors.get(collection)
49 if (!entry) {
50 entry = { byClient: new WeakMap() }
51 collection.once(`status:cleaned-up`, () => {
52 initialRenderErrors.delete(collection)
53 })
54 initialRenderErrors.set(collection, entry)
55 }
56 if (client) entry.byClient.set(client, { error, clientQuery })
57 else entry.unscoped = { error }
58}
59
60/**
61 * Create a live query with React Suspense support
62 * @param queryFn - Query function that defines what data to fetch
63 * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
64 * @returns Object with reactive data and state - data is guaranteed to be defined
65 * @throws Promise when data is loading (caught by Suspense boundary)
66 * @throws Error when collection fails (caught by Error boundary)
67 * @example
68 * // Basic usage with Suspense
69 * function TodoList() {
70 * const { data } = useLiveSuspenseQuery({
71 * query: (q) =>
72 * q.from({ todos: todosCollection })
73 * .where(({ todos }) => eq(todos.completed, false))
74 * .select(({ todos }) => ({ id: todos.id, text: todos.text }))
75 * })
76 *
77 * return (
78 * <ul>
79 * {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
80 * </ul>
81 * )
82 * }
83 *
84 * function App() {
85 * return (
86 * <Suspense fallback={<div>Loading...</div>}>
87 * <TodoList />
88 * </Suspense>
89 * )
90 * }
91 *
92 * @example
93 * // Single result query
94 * const { data } = useLiveSuspenseQuery(
95 * (q) => q.from({ todos: todosCollection })
96 * .where(({ todos }) => eq(todos.id, 1))
97 * .findOne()
98 * )
99 * // data is guaranteed to be the single item (or undefined if not found)
100 *
101 * @example
102 * // Structured captured values are included in derived query identity and trigger re-suspension
103 * const { data } = useLiveSuspenseQuery({
104 * query: (q) => q.from({ todos: todosCollection })
105 * .where(({ todos }) => gt(todos.priority, minPriority)),
106 * })
107 *
108 * @example
109 * // With Error boundary
110 * function App() {
111 * return (
112 * <ErrorBoundary fallback={<div>Error loading data</div>}>
113 * <Suspense fallback={<div>Loading...</div>}>
114 * <TodoList />
115 * </Suspense>
116 * </ErrorBoundary>
117 * )
118 * }
119 *
120 * @remarks
121 * **Important:** This hook does NOT support disabled queries (returning undefined/null).
122 * Following TanStack Query's useSuspenseQuery design, the query callback must always
123 * return a valid query, collection, or config object.
124 *
125 * ❌ **This will cause a type error:**
126 * ```ts
127 * useLiveSuspenseQuery(
128 * (q) => userId ? q.from({ users }) : undefined // ❌ Error!
129 * )
130 * ```
131 *
132 * ✅ **Use conditional rendering instead:**
133 * ```ts
134 * function Profile({ userId }: { userId: string }) {
135 * const { data } = useLiveSuspenseQuery({
136 * query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
137 * })
138 * return <div>{data.name}</div>
139 * }
140 *
141 * // In parent component:
142 * {userId ? <Profile userId={userId} /> : <div>No user</div>}
143 * ```
144 *
145 * ✅ **For optional inputs, conditionally render a component with complete query inputs:**
146 * ```ts
147 * {userId ? <Profile userId={userId} /> : <div>No user</div>}
148 * ```
149 */
150// Overload 1: Accept query function that always returns QueryBuilder
151export function useLiveSuspenseQuery<TContext extends Context>(
152 queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
153 deps?: Array<unknown>,
154): {
155 state: Map<string | number, GetResult<TContext>>
156 data: InferResultType<TContext>
157 collection: Collection<GetResult<TContext>, string | number, {}>
158}
159
160// Overload 2: Accept config object
161export function useLiveSuspenseQuery<TContext extends Context>(
162 config: UseLiveQueryConfig<TContext>,
163): {
164 state: Map<string | number, GetResult<TContext>>
165 data: InferResultType<TContext>
166 collection: Collection<GetResult<TContext>, string | number, {}>
167}
168
169// Overload 3: Accept legacy config object
170export function useLiveSuspenseQuery<TContext extends Context>(
171 config: LiveQueryCollectionConfig<TContext>,
172 deps?: Array<unknown>,
173): {
174 state: Map<string | number, GetResult<TContext>>
175 data: InferResultType<TContext>
176 collection: Collection<GetResult<TContext>, string | number, {}>
177}
178
179// Overload 4: Accept pre-created live query collection
180export function useLiveSuspenseQuery<
181 TResult extends object,
182 TKey extends string | number,
183 TUtils extends Record<string, any>,
184>(
185 liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
186): {
187 state: Map<TKey, TResult>
188 data: Array<TResult>
189 collection: Collection<TResult, TKey, TUtils>
190}
191
192// Overload 5: Accept pre-created live query collection with singleResult: true
193export function useLiveSuspenseQuery<
194 TResult extends object,
195 TKey extends string | number,
196 TUtils extends Record<string, any>,
197>(
198 liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,
199): {
200 state: Map<TKey, TResult>
201 data: TResult | undefined
202 collection: Collection<TResult, TKey, TUtils> & SingleResult
203}
204
205// Implementation - uses useLiveQuery internally and adds Suspense logic
206export function useLiveSuspenseQuery(
207 configOrQueryOrCollection: any,
208 deps?: Array<unknown>,
209) {
210 const promiseRef = useRef<Promise<void> | null>(null)
211 const collectionRef = useRef<Collection<any, any, any> | null>(null)
212 const hasBeenReadyRef = useRef(false)
213
214 // Use useLiveQuery to handle collection management and reactivity
215 const result =
216 deps === undefined
217 ? useLiveQueryForSuspense(configOrQueryOrCollection, undefined)
218 : useLiveQueryForSuspense(configOrQueryOrCollection, deps)
219
220 if (!result.isEnabled) {
221 // Suspense queries cannot be disabled - this matches TanStack Query's useSuspenseQuery behavior
222 throw new Error(
223 `useLiveSuspenseQuery does not support disabled queries (callback returned undefined/null). ` +
224 `The Suspense pattern requires data to always be defined (T, not T | undefined). ` +
225 `Solutions: ` +
226 `1) Use conditional rendering - don't render the component until the condition is met. ` +
227 `2) Use useLiveQuery instead, which supports disabled queries with the 'isEnabled' flag.`,
228 )
229 }
230
231 const queryInfo = getLiveQueryResultInfo(result)
232
233 // Reset promise and ready state when query identity changes
234 if (collectionRef.current !== result.collection) {
235 promiseRef.current = null
236 collectionRef.current = result.collection
237 hasBeenReadyRef.current = false
238 }
239
240 // SUSPENSE LOGIC: Throw promise or error based on collection status
241
242 const collectionStatus = result.collection.status
243
244 // Track when we reach ready state
245 if (result.isReady || queryInfo.observer.isInitialRenderReady()) {
246 hasBeenReadyRef.current = true
247 promiseRef.current = null
248 clearInitialRenderError(result.collection, queryInfo.client)
249 }
250
251 const observerError = queryInfo.observer.getError()
252 // A client request can reject with undefined, which getError() cannot
253 // distinguish from no error. The request status preserves that distinction.
254 const clientQuery =
255 queryInfo.client && queryInfo.queryHash
256 ? queryInfo.client._getLiveQuery(queryInfo.queryHash)
257 : undefined
258 // A configured persisted restore may still satisfy this render after the
259 // client query fails. Let the observer classify that failure below.
260 if (
261 !hasBeenReadyRef.current &&
262 (result.persistedStatus === `unavailable` ||
263 result.persistedStatus === `error`) &&
264 (observerError !== undefined || clientQuery?.status === `error`)
265 ) {
266 promiseRef.current = null
267 throw observerError === undefined ? clientQuery?.error : observerError
268 }
269
270 const errorEntry = initialRenderErrors.get(result.collection)
271 const initialRenderError = queryInfo.client
272 ? errorEntry?.byClient.get(queryInfo.client)
273 : errorEntry?.unscoped
274 // A replacement client query must not inherit the prior request's error.
275 if (
276 initialRenderError?.clientQuery !== undefined &&
277 initialRenderError.clientQuery !== clientQuery
278 ) {
279 clearInitialRenderError(result.collection, queryInfo.client)
280 } else if (initialRenderError && !hasBeenReadyRef.current) {
281 promiseRef.current = null
282 throw initialRenderError.error
283 }
284
285 // Only throw errors during initial load (before first ready)
286 // After success, errors surface as stale data (matches TanStack Query behavior)
287 if (
288 collectionStatus === `error` &&
289 !hasBeenReadyRef.current &&
290 (result.persistedStatus === `unavailable` ||
291 result.persistedStatus === `error`)
292 ) {
293 promiseRef.current = null
294 // TODO: Once collections hold a reference to their last error object (#671),
295 // we should rethrow that actual error instead of creating a generic message
296 throw new Error(`Collection "${result.collection.id}" failed to load`)
297 }
298
299 if (
300 !hasBeenReadyRef.current &&
301 (result.isLoading ||
302 result.isIdle ||
303 result.isError ||
304 (collectionStatus === `error` &&
305 result.persistedStatus !== `unavailable`))
306 ) {
307 if (queryInfo.client?._isSsrStreamingEnabled() && !queryInfo.queryHash) {
308 const reason = queryInfo.identityError
309 ? `${queryInfo.identityError.reason} at ${queryInfo.identityError.path}`
310 : `the query has no stable identity`
311 throw new Error(
312 `Cannot stream this live query during SSR because ${reason}. Provide an explicit serializable queryKey.`,
313 )
314 }
315 // Create or reuse promise for current collection
316 if (!promiseRef.current) {
317 const collection = result.collection
318 const client = queryInfo.client
319 const queryHash = queryInfo.queryHash
320 let active = true
321 const stopWatchingCleanup = collection.once(`status:cleaned-up`, () => {
322 active = false
323 })
324 let preload: Promise<void>
325 try {
326 preload = queryInfo.observer.preloadForInitialRender()
327 } catch (error) {
328 stopWatchingCleanup()
329 throw error
330 }
331 const preloadClientQuery =
332 client && queryHash ? client._getLiveQuery(queryHash) : undefined
333 promiseRef.current = preload
334 .catch((error: unknown) => {
335 const latestClientQuery =
336 client && queryHash ? client._getLiveQuery(queryHash) : undefined
337 if (active && latestClientQuery === preloadClientQuery)
338 rememberInitialRenderError(
339 collection,
340 client,
341 error,
342 preloadClientQuery,
343 )
344 throw error
345 })
346 .finally(stopWatchingCleanup)
347 }
348 // React Suspense catches this promise and retries after preload settles.
349 throw promiseRef.current
350 }
351
352 // Return data without status/loading flags (handled by Suspense/ErrorBoundary)
353 // If error after success, return last known good state (stale data)
354 return {
355 state: result.state,
356 data: result.data,
357 collection: result.collection,
358 }
359}