Function useLiveSuspenseQuery

packages/react-db/src/useLiveSuspenseQuery.ts:155–223

(
  configOrQueryOrCollection: any,
  deps: Array<unknown> = [],
)

// Implementation - uses useLiveQuery internally and adds Suspense logic
export function useLiveSuspenseQuery(
  configOrQueryOrCollection: any,
  deps: Array<unknown> = [],
) {
  const promiseRef = useRef<Promise<void> | null>(null)
  const collectionRef = useRef<Collection<any, any, any> | null>(null)
  const hasBeenReadyRef = useRef(false)

  // Use useLiveQuery to handle collection management and reactivity
  const result = useLiveQuery(configOrQueryOrCollection, deps)

  // Reset promise and ready state when collection changes (deps changed)
  if (collectionRef.current !== result.collection) {
    promiseRef.current = null
    collectionRef.current = result.collection
    hasBeenReadyRef.current = false
  }

  // SUSPENSE LOGIC: Throw promise or error based on collection status
  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
  if (!result.isEnabled) {
    // Suspense queries cannot be disabled - this matches TanStack Query's useSuspenseQuery behavior
    throw new Error(
      `useLiveSuspenseQuery does not support disabled queries (callback returned undefined/null). ` +
        `The Suspense pattern requires data to always be defined (T, not T | undefined). ` +
        `Solutions: ` +
        `1) Use conditional rendering - don't render the component until the condition is met. ` +
        `2) Use useLiveQuery instead, which supports disabled queries with the 'isEnabled' flag.`,
    )
  }

  // It’s not recommended to suspend a render based on a store value returned by useSyncExternalStore.
  // result.status is the snapshot from syncExternalStore. We read the fresh status from the collection reference instead.
  const collectionStatus = result.collection.status

  // Track when we reach ready state
  if (collectionStatus === `ready`) {
    hasBeenReadyRef.current = true
    promiseRef.current = null
  }

  // Only throw errors during initial load (before first ready)
  // After success, errors surface as stale data (matches TanStack Query behavior)
  if (collectionStatus === `error` && !hasBeenReadyRef.current) {
    promiseRef.current = null
    // TODO: Once collections hold a reference to their last error object (#671),
    // we should rethrow that actual error instead of creating a generic message
    throw new Error(`Collection "${result.collection.id}" failed to load`)
  }

  if (collectionStatus === `loading` || collectionStatus === `idle`) {
    // Create or reuse promise for current collection
    if (!promiseRef.current) {
      promiseRef.current = result.collection.preload()
    }
    // THROW PROMISE - React Suspense catches this (React 18+ required)
    // Note: We don't check React version here. In React <18, this will be caught
    // by an Error Boundary, which provides a reasonable failure mode.