@tanstack/react-db 0.5.12 → 1.0.0-rc.1.1

package/src/useLiveQuery.ts

@@ -4,22 +4,25 @@ import { useRef, useSyncExternalStore } from 'react'
 import {
   UnhashableQueryIRError,
   createLiveQueryObserver,
+  createLiveQuerySourceIdClaims,
   deepEquals,
-  getPreparedLiveQueryIdentity,
+  getLiveQueryKey,
+  getSourceObjectToken,
   getStableValueHash,
+  identifyLiveQuery,
   isCollection,
   prepareLiveQueryValue,
+  rejectLiveQueryInput,
+  releaseDeferredOnReclaim,
   resolveLiveQueryValue,
+  resumeDeferredLiveQueryCollections,
 } from '@tanstack/db'
 import { useOptionalDbClient } from './DbProvider'
 import { setLiveQueryResultInfo } from './live-query-internals'
 import { shouldWarnInDevelopment } from './development'
 import {
-  claimSourceIds,
-  createSourceIdBindings,
   getPreparedSources,
-  getSourceObjectToken,
-  resumeSyncStarts,
+  getUnboundDescriptorReporter,
 } from './source-id-bindings'
 import type {
   Collection,
@@ -31,9 +34,13 @@ import type {
   InferResultType,
   InitialQueryBuilder,
   LiveQueryCollectionConfig,
+  LiveQueryIdentityScope,
+  LiveQueryKey,
   LiveQueryObserver,
-  LiveQueryPersistedStatus,
+  LiveQuerySourceIdClaims,
+  LiveQueryStatusFlags,
   NonSingleResult,
+  PooledLiveQueries,
   QueryBuilder,
   SingleResult,
 } from '@tanstack/db'
@@ -45,9 +52,7 @@ const DEFAULT_SUSPENSE_GC_TIME_MS = 5000
 const DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS = 16
 const DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD = 10
 const DERIVED_IDENTITY_TOTAL_WARN_MS = 50
-const warnedDepsCallsites = new Set<string>()
 const warnedDerivedIdentityCallsites = new Set<string>()
-const warnedUnhashableIdentityCallsites = new Set<string>()
 const unpreparedQueryValue = Symbol(`unpreparedQueryValue`)
 
 type SuspenseCollection = Collection<object, string | number, {}>
@@ -106,7 +111,7 @@ export type DerivedIdentityProfiler = {
 }
 
 export type UseLiveQueryStatus = CollectionStatus | `disabled`
-export type LiveQueryKey = ReadonlyArray<unknown>
+export type { LiveQueryKey }
 type UseLiveQueryConfigOptions<TContext extends Context> = Omit<
   LiveQueryCollectionConfig<TContext>,
   `query`
@@ -119,6 +124,11 @@ type UseLiveQueryConfigOptions<TContext extends Context> = Omit<
   queryKey?: LiveQueryKey
   /** Override the nearest DbProvider for this query. */
   client?: DbClient
+  /**
+   * Pass `pooledLiveQueries` to share one partition among equality-filtered
+   * queries of one shape. Suspense and DbClient queries never pool.
+   */
+  pool?: PooledLiveQueries
 }
 
 type ConfiguredQueryBuilder<TContext extends Context> = Extract<
@@ -139,27 +149,6 @@ export type ConditionalUseLiveQueryConfig<TContext extends Context> =
         ) => ConfiguredQueryBuilder<TContext> | undefined | null)
   }
 
-export function warnDeprecatedDepsArray(
-  hookName: `useLiveQuery` | `useLiveInfiniteQuery` = `useLiveQuery`,
-): void {
-  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_DEPRECATION_WARNINGS`)) {
-    return
-  }
-
-  const callsite = getWarningCallsite(4)
-  if (warnedDepsCallsites.has(callsite)) {
-    return
-  }
-  warnedDepsCallsites.add(callsite)
-  const replacement =
-    hookName === `useLiveQuery`
-      ? `useLiveQuery({ query })`
-      : `useLiveInfiniteQuery(query, { queryKey })`
-  console.warn(
-    `[${hookName}] The dependency-array form is deprecated and will be removed in 1.0. Use ${replacement} instead. Provide queryKey only for functional/opaque queries or to avoid deriving identity from structured query IR on render.`,
-  )
-}
-
 function getCurrentTime(): number {
   return typeof performance !== `undefined` &&
     typeof performance.now === `function`
@@ -187,7 +176,10 @@ function warnDerivedIdentityHotPath(
 ): void {
   if (
     profiler.warned ||
-    !shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)
+    !(
+      shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`) &&
+      process.env.NODE_ENV !== `production`
+    )
   ) {
     return
   }
@@ -221,14 +213,6 @@ function warnDerivedIdentityHotPath(
   )
 }
 
-function getExplicitQueryKey(value: unknown): LiveQueryKey | undefined {
-  return value &&
-    typeof value === `object` &&
-    Array.isArray((value as { queryKey?: unknown }).queryKey)
-    ? (value as { queryKey: LiveQueryKey }).queryKey
-    : undefined
-}
-
 function getExplicitDbClient(value: unknown): DbClient | undefined {
   return value &&
     typeof value === `object` &&
@@ -246,43 +230,52 @@ export function prepareQueryValue(
   return prepareLiveQueryValue(value, dbClient, deferredCollections)
 }
 
-type DerivedQueryPreparation =
-  | {
-      status: `hashable`
-      value: unknown
-      identityDeps: Array<unknown>
-    }
-  | {
-      status: `unhashable`
-      value: unknown
-      error: UnhashableQueryIRError
-    }
+type DerivedQueryPreparation = {
+  value: unknown
+  identityDeps: Array<unknown>
+}
+
+/** How a hook checks a prepared query whose identity it compares. */
+export function getIdentityScope(
+  claims: LiveQuerySourceIdClaims,
+  dbClient: DbClient | undefined,
+  hookName: string,
+): LiveQueryIdentityScope {
+  return {
+    claims,
+    client: dbClient,
+    bindingName: hookName,
+    onUnboundDescriptor: getUnboundDescriptorReporter(dbClient, hookName),
+  }
+}
 
+/**
+ * Prepare a query without `queryKey`, derive its identity, and claim its
+ * source Collection IDs. A query whose IR has no stable identity throws
+ * `UnhashableQueryIRError`. The hook's render boundary releases the sync
+ * starts a rejected render deferred.
+ */
 export function prepareDerivedQuery(
   value: unknown,
-  dbClient: DbClient | undefined,
   profiler: DerivedIdentityProfiler,
+  scope: LiveQueryIdentityScope,
   deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>,
 ): DerivedQueryPreparation {
-  const shouldProfile = shouldWarnInDevelopment(
-    `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`,
-  )
+  const shouldProfile =
+    shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`) &&
+    process.env.NODE_ENV !== `production`
   const start = shouldProfile ? getCurrentTime() : 0
-  const preparedValue = prepareQueryValue(value, dbClient, deferredCollections)
+  const preparedValue = prepareQueryValue(
+    value,
+    scope.client,
+    deferredCollections,
+  )
 
   try {
-    const identity = getPreparedLiveQueryIdentity(preparedValue)
     return {
-      status: `hashable`,
       value: preparedValue,
-      identityDeps: [`derived`, identity],
-    }
-  } catch (error) {
-    if (error instanceof UnhashableQueryIRError) {
-      return { status: `unhashable`, value: preparedValue, error }
+      identityDeps: [`derived`, identifyLiveQuery(preparedValue, scope)],
     }
-
-    throw error
   } finally {
     if (shouldProfile) {
       const durationMs = getCurrentTime() - start
@@ -294,30 +287,9 @@ export function prepareDerivedQuery(
   }
 }
 
-export function warnUnhashableDerivedIdentity(
-  error: UnhashableQueryIRError,
-): void {
-  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {
-    return
-  }
-
-  const callsite = getWarningCallsite(4)
-  if (warnedUnhashableIdentityCallsites.has(callsite)) {
-    return
-  }
-  warnedUnhashableIdentityCallsites.add(callsite)
-
-  console.warn(
-    `[useLiveQuery] This query cannot derive a stable identity because ${error.reason} at ${error.path}. ` +
-      `It will keep the legacy mount-stable behavior for now. Add queryKey: [...] to make captured values reactive. ` +
-      `Unhashable queries without queryKey will throw in 1.0.`,
-  )
-}
-
 /**
  * Create a live query using a query function.
  * @param queryFn - Query function that defines what data to fetch
- * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
  * @returns Object with reactive data, state, and status information
  * @example
  * // Prefer config object syntax
@@ -370,12 +342,12 @@ export function warnUnhashableDerivedIdentity(
  *
  * @example
  * // Handle loading and error states
- * const { data, isLoading, isError, status } = useLiveQuery({
+ * const { data, isLoading, isLoadingError, status } = useLiveQuery({
  *   query: (q) => q.from({ todos: todoCollection })
  * })
  *
  * if (isLoading) return <div>Loading...</div>
- * if (isError) return <div>Error: {status}</div>
+ * if (isLoadingError) return <div>Error: {status}</div>
  *
  * return (
  *   <ul>
@@ -386,66 +358,39 @@ export function warnUnhashableDerivedIdentity(
 // Overload 1: Accept query function that always returns QueryBuilder
 export function useLiveQuery<TContext extends Context>(
   queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
-  deps?: Array<unknown>,
 ): {
   state: Map<string | number, GetResult<TContext>>
   data: InferResultType<TContext>
   collection: Collection<GetResult<TContext>, string | number, {}>
   status: CollectionStatus // Can't be disabled if always returns QueryBuilder
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: true // Always true if always returns QueryBuilder
-}
+} & LiveQueryStatusFlags
 
 // Overload 2: Accept query function that can return undefined/null
 export function useLiveQuery<TContext extends Context>(
   queryFn: (
     q: InitialQueryBuilder,
   ) => QueryBuilder<TContext> | undefined | null,
-  deps?: Array<unknown>,
 ): {
   state: Map<string | number, GetResult<TContext>> | undefined
   data: InferResultType<TContext> | undefined
   collection: Collection<GetResult<TContext>, string | number, {}> | undefined
   status: UseLiveQueryStatus
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: boolean
-}
+} & LiveQueryStatusFlags
 
 // Overload 3: Accept query function that can return LiveQueryCollectionConfig
 export function useLiveQuery<TContext extends Context>(
   queryFn: (
     q: InitialQueryBuilder,
   ) => LiveQueryCollectionConfig<TContext> | undefined | null,
-  deps?: Array<unknown>,
 ): {
   state: Map<string | number, GetResult<TContext>> | undefined
   data: InferResultType<TContext> | undefined
   collection: Collection<GetResult<TContext>, string | number, {}> | undefined
   status: UseLiveQueryStatus
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: boolean
-}
+} & LiveQueryStatusFlags
 
 // Overload 4: Accept query function that can return Collection
 export function useLiveQuery<
@@ -456,22 +401,13 @@ export function useLiveQuery<
   queryFn: (
     q: InitialQueryBuilder,
   ) => Collection<TResult, TKey, TUtils> | undefined | null,
-  deps?: Array<unknown>,
 ): {
   state: Map<TKey, TResult> | undefined
   data: Array<TResult> | undefined
   collection: Collection<TResult, TKey, TUtils> | undefined
   status: UseLiveQueryStatus
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: boolean
-}
+} & LiveQueryStatusFlags
 
 // Overload 5: Accept query function that can return all types
 export function useLiveQuery<
@@ -488,7 +424,6 @@ export function useLiveQuery<
     | Collection<TResult, TKey, TUtils>
     | undefined
     | null,
-  deps?: Array<unknown>,
 ): {
   state:
     Map<string | number, GetResult<TContext>> | Map<TKey, TResult> | undefined
@@ -498,21 +433,12 @@ export function useLiveQuery<
     | Collection<TResult, TKey, TUtils>
     | undefined
   status: UseLiveQueryStatus
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: boolean
-}
+} & LiveQueryStatusFlags
 
 /**
  * Create a live query using configuration object
  * @param config - Configuration object with query and options
- * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
  * @returns Object with reactive data, state, and status information
  * @example
  * // Basic config object usage
@@ -534,12 +460,12 @@ export function useLiveQuery<
  *
  * @example
  * // Handle all states uniformly
- * const { data, isLoading, isReady, isError } = useLiveQuery({
+ * const { data, isLoading, isReady, isLoadingError } = useLiveQuery({
  *   query: (q) => q.from({ items: itemCollection })
  * })
  *
  * if (isLoading) return <div>Loading...</div>
- * if (isError) return <div>Something went wrong</div>
+ * if (isLoadingError) return <div>Something went wrong</div>
  * if (!isReady) return <div>Preparing...</div>
  *
  * return <div>{data.length} items loaded</div>
@@ -552,16 +478,8 @@ export function useLiveQuery<TContext extends Context>(
   data: InferResultType<TContext>
   collection: Collection<GetResult<TContext>, string | number, {}>
   status: CollectionStatus // Can't be disabled when query always returns a builder
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: true // Always true when query always returns a builder
-}
+} & LiveQueryStatusFlags
 
 // Overload 7: Accept config object with a query that can return undefined/null
 export function useLiveQuery<TContext extends Context>(
@@ -571,56 +489,8 @@ export function useLiveQuery<TContext extends Context>(
   data: InferResultType<TContext> | undefined
   collection: Collection<GetResult<TContext>, string | number, {}> | undefined
   status: UseLiveQueryStatus
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
-  isEnabled: boolean
-}
-
-// Overload 8: Accept config object with legacy deps
-export function useLiveQuery<TContext extends Context>(
-  config: LiveQueryCollectionConfig<TContext>,
-  deps?: Array<unknown>,
-): {
-  state: Map<string | number, GetResult<TContext>>
-  data: InferResultType<TContext>
-  collection: Collection<GetResult<TContext>, string | number, {}>
-  status: CollectionStatus // Can't be disabled when query always returns a builder
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
-  isEnabled: true // Always true when query always returns a builder
-}
-
-// Overload 9: Accept config object with legacy deps and a query that can return undefined/null
-export function useLiveQuery<TContext extends Context>(
-  config: ConditionalUseLiveQueryConfig<TContext>,
-  deps: Array<unknown>,
-): {
-  state: Map<string | number, GetResult<TContext>> | undefined
-  data: InferResultType<TContext> | undefined
-  collection: Collection<GetResult<TContext>, string | number, {}> | undefined
-  status: UseLiveQueryStatus
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: boolean
-}
+} & LiveQueryStatusFlags
 
 /**
  * Subscribe to an existing live query collection
@@ -644,10 +514,10 @@ export function useLiveQuery<TContext extends Context>(
  *
  * @example
  * // Handle states consistently
- * const { data, isLoading, isError } = useLiveQuery(sharedCollection)
+ * const { data, isLoading, isLoadingError } = useLiveQuery(sharedCollection)
  *
  * if (isLoading) return <div>Loading...</div>
- * if (isError) return <div>Error loading data</div>
+ * if (isLoadingError) return <div>Error loading data</div>
  *
  * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
  */
@@ -663,16 +533,8 @@ export function useLiveQuery<
   data: Array<TResult>
   collection: Collection<TResult, TKey, TUtils>
   status: CollectionStatus // Can't be disabled for pre-created live query collections
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: true // Always true for pre-created live query collections
-}
+} & LiveQueryStatusFlags
 
 // Overload 10: Accept pre-created live query collection with singleResult: true
 export function useLiveQuery<
@@ -686,31 +548,17 @@ export function useLiveQuery<
   data: TResult | undefined
   collection: Collection<TResult, TKey, TUtils> & SingleResult
   status: CollectionStatus // Can't be disabled for pre-created live query collections
-  isLoading: boolean
-  isReady: boolean
-  persistedStatus: LiveQueryPersistedStatus
-  isPersistedReady: boolean
-  persistedError: unknown | undefined
-  isIdle: boolean
-  isError: boolean
-  isCleanedUp: boolean
   isEnabled: true // Always true for pre-created live query collections
-}
+} & LiveQueryStatusFlags
 
 // Implementation - use function overloads to infer the actual collection type
-export function useLiveQuery(
-  configOrQueryOrCollection: any,
-  deps?: Array<unknown>,
-) {
-  return useLiveQueryImpl(configOrQueryOrCollection, deps)
+export function useLiveQuery(configOrQueryOrCollection: any) {
+  return useLiveQueryImpl(configOrQueryOrCollection)
 }
 
 /** @internal Shared implementation for the Suspense wrapper. */
-export function useLiveQueryForSuspense(
-  configOrQueryOrCollection: any,
-  deps: Array<unknown> | undefined,
-) {
-  return useLiveQueryImpl(configOrQueryOrCollection, deps, true)
+export function useLiveQueryForSuspense(configOrQueryOrCollection: any) {
+  return useLiveQueryImpl(configOrQueryOrCollection, true)
 }
 
 // What one hook instance keeps across renders. It lives in a single ref
@@ -718,10 +566,9 @@ export function useLiveQueryForSuspense(
 function createHookInstance(dbClient: DbClient | undefined) {
   return {
     collection: null as Collection<object, string | number, {}> | null,
-    deps: null as Array<unknown> | null,
+    identityDeps: null as Array<unknown> | null,
     config: null as unknown,
     client: dbClient,
-    legacyUnhashableIdentity: [`legacy-unhashable`] as Array<unknown>,
     derivedIdentityProfiler: {
       renderCount: 0,
       totalMs: 0,
@@ -731,7 +578,8 @@ function createHookInstance(dbClient: DbClient | undefined) {
     deferredCollections: new Set<
       CollectionImpl<any, string | number, any, any, any>
     >(),
-    sourceIds: createSourceIdBindings(),
+    sourceIds: createLiveQuerySourceIdClaims(),
+    cancelReclaimRelease: undefined as (() => void) | undefined,
     observer: null as LiveQueryObserver<object, string | number> | null,
     queryHash: undefined as string | undefined,
     suspenseKey: undefined as string | undefined,
@@ -740,193 +588,147 @@ function createHookInstance(dbClient: DbClient | undefined) {
   }
 }
 
-function useLiveQueryImpl(
-  configOrQueryOrCollection: any,
-  deps: Array<unknown> | undefined,
-  forSuspense = false,
-) {
+function useLiveQueryImpl(configOrQueryOrCollection: any, forSuspense = false) {
   const contextDbClient = useOptionalDbClient()
   // Check if it's already a collection
   const inputIsCollection = isCollection(configOrQueryOrCollection)
   const dbClient = inputIsCollection
     ? contextDbClient
     : (getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient)
-  const resolvedDeps = deps ?? []
 
   const instanceRef = useRef<ReturnType<typeof createHookInstance> | null>(null)
   const instance = (instanceRef.current ??= createHookInstance(dbClient))
-  const resumeDeferredCollections = () =>
-    resumeSyncStarts(instance.deferredCollections)
-
-  const queryKey = !inputIsCollection
-    ? getExplicitQueryKey(configOrQueryOrCollection)
-    : undefined
-  let preparedQueryValue: unknown | typeof unpreparedQueryValue =
-    unpreparedQueryValue
-  let identityDeps: ReadonlyArray<unknown>
-  let streamIdentity: unknown = undefined
-  let identityError: UnhashableQueryIRError | undefined
+  // A commit releases the starts itself, so it drops the reclaim listener.
+  const resumeDeferredCollections = () => {
+    instance.cancelReclaimRelease?.()
+    instance.cancelReclaimRelease = undefined
+    resumeDeferredLiveQueryCollections(instance.deferredCollections)
+  }
 
-  if (queryKey) {
-    identityDeps = queryKey
-    streamIdentity = [`queryKey`, queryKey]
-  } else if (deps !== undefined) {
-    identityDeps = resolvedDeps
-    // Deps decide reuse. Only hydration and Suspense read the query hash; the
-    // development warning about unhashable queries still derives it.
-    if (
-      dbClient ||
-      forSuspense ||
-      shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)
-    )
-      try {
-        preparedQueryValue = prepareQueryValue(
-          configOrQueryOrCollection,
-          dbClient,
-          instance.deferredCollections,
-        )
-        streamIdentity = [
-          `deps`,
-          resolvedDeps,
-          getPreparedLiveQueryIdentity(preparedQueryValue),
-        ]
-      } catch (error) {
-        if (!(error instanceof UnhashableQueryIRError)) throw error
-        warnUnhashableDerivedIdentity(error)
-        identityError = error
-      }
-  } else if (inputIsCollection) {
-    identityDeps = []
-    streamIdentity = [`collection`, configOrQueryOrCollection.id]
-  } else {
-    const preparation = prepareDerivedQuery(
-      configOrQueryOrCollection,
-      dbClient,
-      instance.derivedIdentityProfiler,
-      instance.deferredCollections,
-    )
-    preparedQueryValue = preparation.value
-    if (preparation.status === `hashable`) {
+  // The render boundary: a render that throws anywhere after preparation
+  // never commits, so it releases the sync starts it deferred here.
+  try {
+    const queryKey = !inputIsCollection
+      ? getLiveQueryKey(configOrQueryOrCollection)
+      : undefined
+    let preparedQueryValue: unknown | typeof unpreparedQueryValue =
+      unpreparedQueryValue
+    let identityDeps: ReadonlyArray<unknown>
+    let streamIdentity: unknown = undefined
+    let identityError: UnhashableQueryIRError | undefined
+
+    if (queryKey) {
+      identityDeps = queryKey
+      streamIdentity = [`queryKey`, queryKey]
+    } else if (inputIsCollection) {
+      identityDeps = []
+      streamIdentity = [`collection`, configOrQueryOrCollection.id]
+    } else {
+      const preparation = prepareDerivedQuery(
+        configOrQueryOrCollection,
+        instance.derivedIdentityProfiler,
+        getIdentityScope(instance.sourceIds, dbClient, `useLiveQuery`),
+        instance.deferredCollections,
+      )
+      preparedQueryValue = preparation.value
       identityDeps = preparation.identityDeps
       streamIdentity = preparation.identityDeps
-    } else {
-      warnUnhashableDerivedIdentity(preparation.error)
-      identityDeps = instance.legacyUnhashableIdentity
-      identityError = preparation.error
     }
-  }
 
-  let queryHash: string | undefined
-  if (streamIdentity !== undefined) {
-    try {
-      queryHash = getStableValueHash(streamIdentity, `queryKey`)
-    } catch (error) {
-      if (error instanceof UnhashableQueryIRError) {
-        if (queryKey !== undefined) throw error
-        identityError = error
-      } else {
-        throw error
+    let queryHash: string | undefined
+    if (streamIdentity !== undefined) {
+      try {
+        queryHash = getStableValueHash(streamIdentity, `queryKey`)
+      } catch (error) {
+        if (error instanceof UnhashableQueryIRError) {
+          if (queryKey !== undefined) throw error
+          identityError = error
+        } else {
+          throw error
+        }
       }
     }
-  }
-
-  if (deps !== undefined) {
-    warnDeprecatedDepsArray()
-  }
-
-  if (
-    queryKey === undefined &&
-    deps === undefined &&
-    preparedQueryValue !== unpreparedQueryValue
-  ) {
-    claimSourceIds(
-      instance.sourceIds,
-      preparedQueryValue,
-      dbClient,
-      `useLiveQuery`,
-      resumeDeferredCollections,
-    )
-  }
 
-  const canReuseSuspenseKey =
-    forSuspense &&
-    !inputIsCollection &&
-    queryHash !== undefined &&
-    instance.collection !== null &&
-    instance.client === dbClient &&
-    instance.queryHash === queryHash &&
-    instance.suspenseKey !== undefined
+    const canReuseSuspenseKey =
+      forSuspense &&
+      !inputIsCollection &&
+      queryHash !== undefined &&
+      instance.collection !== null &&
+      instance.client === dbClient &&
+      instance.queryHash === queryHash &&
+      instance.suspenseKey !== undefined
 
-  if (
-    forSuspense &&
-    !inputIsCollection &&
-    queryHash &&
-    !canReuseSuspenseKey &&
-    preparedQueryValue === unpreparedQueryValue
-  ) {
-    preparedQueryValue = prepareQueryValue(
-      configOrQueryOrCollection,
-      dbClient,
-      instance.deferredCollections,
-    )
-  }
-
-  const suspenseKey =
-    queryHash && forSuspense && !inputIsCollection
-      ? canReuseSuspenseKey
-        ? instance.suspenseKey
-        : getSourceQualifiedSuspenseKey(preparedQueryValue, queryHash, dbClient)
-      : queryHash
+    if (
+      forSuspense &&
+      !inputIsCollection &&
+      queryHash &&
+      !canReuseSuspenseKey &&
+      preparedQueryValue === unpreparedQueryValue
+    ) {
+      preparedQueryValue = prepareQueryValue(
+        configOrQueryOrCollection,
+        dbClient,
+        instance.deferredCollections,
+      )
+    }
 
-  const suspenseCollections =
-    forSuspense && !inputIsCollection && suspenseKey
-      ? getSuspenseCollections(dbClient)
+    const suspenseKey =
+      queryHash && forSuspense && !inputIsCollection
+        ? canReuseSuspenseKey
+          ? instance.suspenseKey
+          : getSourceQualifiedSuspenseKey(
+              preparedQueryValue,
+              queryHash,
+              dbClient,
+            )
+        : queryHash
+
+    const suspenseCollections =
+      forSuspense && !inputIsCollection && suspenseKey
+        ? getSuspenseCollections(dbClient)
+        : undefined
+    const suspenseEntry = suspenseKey
+      ? suspenseCollections?.get(suspenseKey)
       : undefined
-  const suspenseEntry = suspenseKey
-    ? suspenseCollections?.get(suspenseKey)
-    : undefined
-  const suspenseCollection = suspenseEntry?.collection
-
-  const identityChanged =
-    instance.deps === null ||
-    (deps !== undefined
-      ? instance.deps.length !== identityDeps.length ||
-        instance.deps.some((dep, index) => dep !== identityDeps[index])
-      : !deepEquals(instance.deps, identityDeps))
-
-  // Check if we need to create/recreate the collection
-  const needsNewCollection =
-    !instance.collection ||
-    (inputIsCollection && instance.config !== configOrQueryOrCollection) ||
-    (!inputIsCollection && (instance.client !== dbClient || identityChanged))
-
-  if (needsNewCollection) {
-    if (inputIsCollection) {
-      // Warn when passing a collection directly with on-demand sync mode
-      // In on-demand mode, data is only loaded when queries with predicates request it
-      // Passing the collection directly doesn't provide any predicates, so no data loads
-      const syncMode = (
-        configOrQueryOrCollection as { config?: { syncMode?: string } }
-      ).config?.syncMode
-      if (
-        syncMode === `on-demand` &&
-        shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)
-      ) {
-        console.warn(
-          `[useLiveQuery] Warning: Passing a collection with syncMode "on-demand" directly to useLiveQuery ` +
-            `will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.\n\n` +
-            `Instead, use a query builder function:\n` +
-            `  const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })\n\n` +
-            `Or switch to syncMode "eager" if you want all data to sync automatically.`,
-        )
-      }
-      // It's already a collection, ensure sync is started for React hooks
-      configOrQueryOrCollection.startSyncImmediate()
-      instance.collection = configOrQueryOrCollection
-      instance.config = configOrQueryOrCollection
-    } else {
-      if (suspenseCollection) {
-        instance.collection = suspenseCollection
+    const suspenseCollection = suspenseEntry?.collection
+
+    const identityChanged =
+      instance.identityDeps === null ||
+      !deepEquals(instance.identityDeps, identityDeps)
+
+    // Check if we need to create/recreate the collection
+    const needsNewCollection =
+      !instance.collection ||
+      (inputIsCollection && instance.config !== configOrQueryOrCollection) ||
+      (!inputIsCollection && (instance.client !== dbClient || identityChanged))
+
+    if (needsNewCollection) {
+      if (inputIsCollection) {
+        // Warn when passing a collection directly with on-demand sync mode
+        // In on-demand mode, data is only loaded when queries with predicates request it
+        // Passing the collection directly doesn't provide any predicates, so no data loads
+        const syncMode = (
+          configOrQueryOrCollection as { config?: { syncMode?: string } }
+        ).config?.syncMode
+        if (
+          syncMode === `on-demand` &&
+          shouldWarnInDevelopment(
+            `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`,
+          ) &&
+          process.env.NODE_ENV !== `production`
+        ) {
+          console.warn(
+            `[useLiveQuery] Warning: Passing a collection with syncMode "on-demand" directly to useLiveQuery ` +
+              `will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.\n\n` +
+              `Instead, use a query builder function:\n` +
+              `  const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })\n\n` +
+              `Or switch to syncMode "eager" if you want all data to sync automatically.`,
+          )
+        }
+        // It's already a collection, ensure sync is started for React hooks
+        configOrQueryOrCollection.startSyncImmediate()
+        instance.collection = configOrQueryOrCollection
+        instance.config = configOrQueryOrCollection
       } else {
         if (preparedQueryValue === unpreparedQueryValue) {
           preparedQueryValue = prepareQueryValue(
@@ -935,117 +737,149 @@ function useLiveQueryImpl(
             instance.deferredCollections,
           )
         }
-        if (!dbClient) {
-          getPreparedSources(preparedQueryValue, dbClient, `useLiveQuery`)
-        }
-        instance.collection = resolveLiveQueryValue(preparedQueryValue, {
-          gcTime: forSuspense
-            ? DEFAULT_SUSPENSE_GC_TIME_MS
-            : DEFAULT_GC_TIME_MS,
-          // Hydration and Suspense key the live-query Collection by identity.
-          pool: !forSuspense && !dbClient,
-          // Without a DbClient, Suspense starts it through a preload below.
-          startSync: !forSuspense || dbClient !== undefined,
-        }) as SuspenseCollection | null
-        if (suspenseCollections && suspenseKey && instance.collection) {
-          const collection = instance.collection
-          const removeCleanupListener = collection.on(`status:cleaned-up`, () =>
-            releaseSuspenseCollection(
-              suspenseCollections,
-              suspenseKey,
-              collection,
-            ),
-          )
-          const removeErrorListener = collection.on(`status:error`, () => {
-            // Keep the failed collection through React's immediate retry so
-            // the hook can throw its actual load error to an ErrorBoundary.
-            // Retire it afterward so a later boundary reset starts fresh.
-            setTimeout(
+
+        if (suspenseCollection) {
+          instance.collection = suspenseCollection
+        } else {
+          // A keyed query claims nothing, so it reports an unbound descriptor
+          // here; the other forms reported it when they claimed.
+          if (!dbClient && queryKey !== undefined) {
+            getPreparedSources(preparedQueryValue, dbClient, `useLiveQuery`)
+          }
+          instance.collection = resolveLiveQueryValue(preparedQueryValue, {
+            gcTime: forSuspense
+              ? DEFAULT_SUSPENSE_GC_TIME_MS
+              : DEFAULT_GC_TIME_MS,
+            // Hydration and Suspense key the live-query Collection by identity,
+            // so they never pool, even when the config passes a pool.
+            pool: forSuspense || dbClient ? false : undefined,
+            // Without a DbClient, Suspense starts it through a preload below.
+            startSync: !forSuspense || dbClient !== undefined,
+          }) as SuspenseCollection | null
+          // A render that never commits releases its deferred sync starts
+          // when garbage collection reclaims the live query it built. A
+          // Collection the callback returned is not this render's to reclaim.
+          if (instance.collection && !isCollection(preparedQueryValue)) {
+            instance.cancelReclaimRelease?.()
+            instance.cancelReclaimRelease = releaseDeferredOnReclaim(
+              instance.collection,
+              instance.deferredCollections,
+            )
+          }
+          if (suspenseCollections && suspenseKey && instance.collection) {
+            const collection = instance.collection
+            const removeCleanupListener = collection.on(
+              `status:cleaned-up`,
               () =>
                 releaseSuspenseCollection(
                   suspenseCollections,
                   suspenseKey,
                   collection,
                 ),
-              0,
             )
-          })
-          const entry: SuspenseCollectionEntry = {
-            collection,
-            removeStatusListeners: () => {
-              removeCleanupListener()
-              removeErrorListener()
-            },
+            // Keep a failed or crashed collection through React's immediate
+            // retry so the hook can throw its actual error to an ErrorBoundary.
+            // Retire it afterward so a later boundary reset starts fresh.
+            const retireAfterRetry = () =>
+              setTimeout(
+                () =>
+                  releaseSuspenseCollection(
+                    suspenseCollections,
+                    suspenseKey,
+                    collection,
+                  ),
+                0,
+              )
+            const removeErrorListener = collection.on(
+              `status:error`,
+              retireAfterRetry,
+            )
+            const removeCrashListener = collection.on(
+              `status:crashed`,
+              retireAfterRetry,
+            )
+            const entry: SuspenseCollectionEntry = {
+              collection,
+              removeStatusListeners: () => {
+                removeCleanupListener()
+                removeErrorListener()
+                removeCrashListener()
+              },
+            }
+            suspenseCollections.set(suspenseKey, entry)
           }
-          suspenseCollections.set(suspenseKey, entry)
         }
+        instance.config = configOrQueryOrCollection
+        instance.identityDeps = [...identityDeps]
       }
-      instance.config = configOrQueryOrCollection
-      instance.deps = [...identityDeps]
+      instance.client = dbClient
+      instance.queryHash = queryHash
+      instance.suspenseKey = suspenseKey
+      instance.identityError = identityError
     }
-    instance.client = dbClient
-    instance.queryHash = queryHash
-    instance.suspenseKey = suspenseKey
-    instance.identityError = identityError
-  }
 
-  // Recreate the observer when the underlying collection changes. The observer
-  // is not disposed explicitly here or on unmount: `useSyncExternalStore`
-  // unsubscribes it when the subscribe changes or the component unmounts, which
-  // detaches the collection subscription; the observer is then GC'd. (An unmount
-  // effect that disposed it would misfire under StrictMode/offscreen effect
-  // replay, leaving a disposed observer in the ref.)
-  if (needsNewCollection) {
-    // Defer the initial notify: useSyncExternalStore must not be notified
-    // synchronously during subscribe.
-    // Wholesale mode: React re-reads getSnapshot() on notify, keeps the
-    // hook's pre-observer loading policy, and — because wholesale delivers
-    // nothing synchronously during subscribe — never notifies
-    // useSyncExternalStore inside its own subscribe call.
-    instance.observer = createLiveQueryObserver(instance.collection, {
-      mode: `wholesale`,
-      client: dbClient,
-      queryHash: instance.queryHash,
-      onPreload: resumeDeferredCollections,
-    })
-  }
-  const observer = instance.observer!
-  // A Suspense render asks for its data. Preloading starts the sync run, so a
-  // source that already holds the rows makes it ready before the snapshot is
-  // read instead of suspending once. useLiveSuspenseQuery surfaces failures.
-  // A DbClient defers source starts past render and owns its streamed query.
-  if (
-    forSuspense &&
-    !dbClient &&
-    (instance.collection?.status === `idle` ||
-      instance.collection?.status === `cleaned-up`)
-  ) {
-    observer.preloadForInitialRender().catch(() => {})
-  }
+    // Recreate the observer when the underlying collection changes. The observer
+    // is not disposed explicitly here or on unmount: `useSyncExternalStore`
+    // unsubscribes it when the subscribe changes or the component unmounts, which
+    // detaches the collection subscription; the observer is then GC'd. (An unmount
+    // effect that disposed it would misfire under StrictMode/offscreen effect
+    // replay, leaving a disposed observer in the ref.)
+    if (needsNewCollection) {
+      // Defer the initial notify: useSyncExternalStore must not be notified
+      // synchronously during subscribe.
+      // Wholesale mode: React re-reads getSnapshot() on notify, keeps the
+      // hook's pre-observer loading policy, and — because wholesale delivers
+      // nothing synchronously during subscribe — never notifies
+      // useSyncExternalStore inside its own subscribe call.
+      instance.observer = createLiveQueryObserver(instance.collection, {
+        mode: `wholesale`,
+        client: dbClient,
+        queryHash: instance.queryHash,
+        onPreload: resumeDeferredCollections,
+        suspendUntilReady: forSuspense,
+      })
+    }
+    const observer = instance.observer!
+    // A Suspense render asks for its data. Preloading starts the sync run, so a
+    // source that already holds the rows makes it ready before the snapshot is
+    // read instead of suspending once. useLiveSuspenseQuery surfaces failures.
+    // A DbClient defers source starts past render and owns its streamed query.
+    if (
+      forSuspense &&
+      !dbClient &&
+      (instance.collection?.status === `idle` ||
+        instance.collection?.status === `cleaned-up`)
+    ) {
+      observer.preload().catch(() => {})
+    }
 
-  // Stable subscribe bound to the current observer; the observer owns the
-  // subscription, ready-race, and disposal.
-  if (!instance.subscribe || needsNewCollection) {
-    instance.subscribe = (onStoreChange: () => void) => {
-      const unsubscribe = observer.subscribe(onStoreChange)
-      resumeDeferredCollections()
-      return unsubscribe
+    // Stable subscribe bound to the current observer; the observer owns the
+    // subscription, ready-race, and disposal.
+    if (!instance.subscribe || needsNewCollection) {
+      instance.subscribe = (onStoreChange: () => void) => {
+        const unsubscribe = observer.subscribe(onStoreChange)
+        resumeDeferredCollections()
+        return unsubscribe
+      }
     }
-  }
 
-  const returned = useSyncExternalStore(
-    instance.subscribe,
-    () => observer.getSnapshot(),
-    () => observer.getServerSnapshot(),
-  )
-  // Only useLiveSuspenseQuery reads this, and it costs a define per render.
-  if (forSuspense) {
-    setLiveQueryResultInfo(returned, {
-      client: dbClient,
-      queryHash: instance.queryHash,
-      identityError: instance.identityError,
-      observer,
-    })
+    const returned = useSyncExternalStore(
+      instance.subscribe,
+      () => observer.getSnapshot(),
+      () => observer.getServerSnapshot(forSuspense),
+    )
+    // Only useLiveSuspenseQuery reads this, and it costs a define per render.
+    if (forSuspense) {
+      setLiveQueryResultInfo(returned, {
+        client: dbClient,
+        queryHash: instance.queryHash,
+        identityError: instance.identityError,
+        observer,
+        deferredCollections: instance.deferredCollections,
+      })
+    }
+    return returned as any
+  } catch (error) {
+    return rejectLiveQueryInput(instance.deferredCollections, error)
   }
-  return returned as any
 }