@tanstack/react-db 0.2.0 → 0.3.0

package/src/live-query-internals.ts

@@ -0,0 +1,36 @@
+import type {
+  DbClient,
+  LiveQueryObserver,
+  UnhashableQueryIRError,
+} from '@tanstack/db'
+
+const liveQueryResultInfo = Symbol(`liveQueryResultInfo`)
+
+export type LiveQueryResultInfo = {
+  client: DbClient | undefined
+  queryHash: string | undefined
+  identityError: UnhashableQueryIRError | undefined
+  observer: LiveQueryObserver<object, string | number>
+}
+
+type ResultWithInfo = {
+  [liveQueryResultInfo]?: LiveQueryResultInfo
+}
+
+export function setLiveQueryResultInfo(
+  result: object,
+  info: LiveQueryResultInfo,
+): void {
+  Object.defineProperty(result, liveQueryResultInfo, {
+    configurable: true,
+    value: info,
+  })
+}
+
+export function getLiveQueryResultInfo(result: object): LiveQueryResultInfo {
+  const info = (result as ResultWithInfo)[liveQueryResultInfo]
+  if (!info) {
+    throw new Error(`Missing internal live query result information.`)
+  }
+  return info
+}

package/src/useLiveInfiniteQuery.ts

@@ -1,3 +1,5 @@
+'use client'
+
 import { useCallback, useRef, useSyncExternalStore } from 'react'
 import {
   assertLiveQueryWindowManyResult,
@@ -11,11 +13,23 @@ import {
   resolveLiveQueryWindowInput,
   shouldPreserveLiveQueryWindowPageCount,
 } from '@tanstack/db'
-// Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.
-import type { useLiveQuery } from './useLiveQuery'
+import { useOptionalDbClient } from './DbProvider'
+import {
+  prepareDerivedQuery,
+  prepareQueryValue,
+  warnDeprecatedDepsArray,
+  warnUnhashableDerivedIdentity,
+} from './useLiveQuery'
+import type {
+  DerivedIdentityProfiler,
+  LiveQueryKey,
+  useLiveQuery,
+} from './useLiveQuery'
 import type {
   Collection,
+  CollectionImpl as CollectionImplType,
   Context,
+  DbClient,
   InferResultType,
   InitialQueryBuilder,
   LiveQueryWindowController,
@@ -25,8 +39,17 @@ import type {
 
 // Live queries created here are cleaned up immediately (0 disables GC).
 const DEFAULT_GC_TIME_MS = 1
+const unpreparedQueryValue = Symbol(`unpreparedQueryValue`)
 
 export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
+  /**
+   * Explicit identity for queries that contain opaque functional variants or
+   * are hot enough that deriving identity from structured IR is too expensive.
+   * Structured queries should omit this so DB can derive identity directly.
+   */
+  queryKey?: LiveQueryKey
+  /** Override the nearest DbProvider for this query. */
+  client?: DbClient
   pageSize?: number
   initialPageParam?: number
   /**
@@ -62,6 +85,9 @@ type EnabledLiveQueryReturn<TContext extends Context> = ReturnType<
 type InfiniteQueryRenderState = {
   inputKind: `collection` | `query`
   inputCollection: Collection<any, any, any> | null
+  inputQuery: unknown
+  client: DbClient | undefined
+  identityMode: `collection` | `queryKey` | `legacyDeps` | `derived`
   dependencies: Array<unknown> | null
   pageSize: number
   initialPageParam: number
@@ -69,72 +95,21 @@ type InfiniteQueryRenderState = {
   controller: LiveQueryWindowController<any, any>
   warning: string | null
   warned: boolean
+  deferredCollections: Set<
+    CollectionImplType<any, string | number, any, any, any>
+  >
 }
 
 /**
- * Create an infinite query using a query function with live updates
+ * Create an infinite query using a query function with live updates.
  *
  * Uses `utils.setWindow()` to dynamically adjust the limit/offset window
  * without recreating the live query collection on each page change.
  *
  * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.
  * @param config - Configuration including pageSize and getNextPageParam
- * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
  * @returns Object with pages, data, and pagination controls
- *
- * @example
- * // Basic infinite query
- * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
- *   (q) => q
- *     .from({ posts: postsCollection })
- *     .orderBy(({ posts }) => posts.createdAt, 'desc')
- *     .select(({ posts }) => ({
- *       id: posts.id,
- *       title: posts.title
- *     })),
- *   {
- *     pageSize: 20,
- *     getNextPageParam: (lastPage, allPages) =>
- *       lastPage.length === 20 ? allPages.length : undefined
- *   }
- * )
- *
- * @example
- * // With dependencies
- * const { pages, fetchNextPage } = useLiveInfiniteQuery(
- *   (q) => q
- *     .from({ posts: postsCollection })
- *     .where(({ posts }) => eq(posts.category, category))
- *     .orderBy(({ posts }) => posts.createdAt, 'desc'),
- *   {
- *     pageSize: 10,
- *     getNextPageParam: (lastPage) =>
- *       lastPage.length === 10 ? lastPage.length : undefined
- *   },
- *   [category]
- * )
- *
- * @example
- * // Router loader pattern with pre-created collection
- * // In loader:
- * const postsQuery = createLiveQueryCollection({
- *   query: (q) => q
- *     .from({ posts: postsCollection })
- *     .orderBy(({ posts }) => posts.createdAt, 'desc')
- *     .limit(20)
- * })
- * await postsQuery.preload()
- * return { postsQuery }
- *
- * // In component:
- * const { postsQuery } = useLoaderData()
- * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
- *   postsQuery,
- *   {
- *     pageSize: 20,
- *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined
- *   }
- * )
  */
 
 // Overload for pre-created collection (non-single result)
@@ -158,10 +133,12 @@ export function useLiveInfiniteQuery<TContext extends Context>(
 export function useLiveInfiniteQuery<TContext extends Context>(
   queryFnOrCollection: any,
   config: UseLiveInfiniteQueryConfig<TContext>,
-  deps: Array<unknown> = [],
+  deps?: Array<unknown>,
 ): UseLiveInfiniteQueryReturn<TContext> {
   const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)
   const initialPageParam = config.initialPageParam ?? 0
+  const contextDbClient = useOptionalDbClient()
+  const dbClient = config.client ?? contextDbClient
 
   const inputIsCollection =
     getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`
@@ -169,14 +146,72 @@ export function useLiveInfiniteQuery<TContext extends Context>(
   const committedRef = useRef<InfiniteQueryRenderState | null>(null)
   const committed = committedRef.current
   const inputKind = inputIsCollection ? `collection` : `query`
+  const derivedIdentityProfilerRef = useRef<DerivedIdentityProfiler>({
+    renderCount: 0,
+    totalMs: 0,
+    maxMs: 0,
+    warned: false,
+  })
+  const legacyUnhashableIdentityRef = useRef<Array<unknown>>([
+    `legacy-unhashable`,
+  ])
+  const deferredCollections = new Set<
+    CollectionImplType<any, string | number, any, any, any>
+  >()
 
+  let preparedQueryValue: unknown | typeof unpreparedQueryValue =
+    unpreparedQueryValue
+  let identityDeps: ReadonlyArray<unknown> = []
+  let identityMode: InfiniteQueryRenderState[`identityMode`] = `collection`
+
+  if (!inputIsCollection) {
+    if (config.queryKey !== undefined) {
+      identityMode = `queryKey`
+      identityDeps = config.queryKey
+    } else if (deps !== undefined) {
+      identityMode = `legacyDeps`
+      identityDeps = deps
+      warnDeprecatedDepsArray(`useLiveInfiniteQuery`)
+    } else if (
+      committed?.identityMode === `derived` &&
+      committed.inputQuery === queryFnOrCollection &&
+      committed.client === dbClient
+    ) {
+      identityMode = `derived`
+      identityDeps = committed.dependencies ?? []
+    } else {
+      identityMode = `derived`
+      const preparation = prepareDerivedQuery(
+        queryFnOrCollection,
+        dbClient,
+        derivedIdentityProfilerRef.current,
+        deferredCollections,
+      )
+      preparedQueryValue = preparation.value
+      if (preparation.status === `hashable`) {
+        identityDeps = preparation.identityDeps
+      } else {
+        warnUnhashableDerivedIdentity(preparation.error)
+        identityDeps = legacyUnhashableIdentityRef.current
+      }
+    }
+  }
+
+  const usesLegacyDeps =
+    !inputIsCollection && config.queryKey === undefined && deps !== undefined
   const dependencyComparison = compareLiveQueryWindowDependencies(
     committed?.dependencies,
-    deps,
+    identityDeps,
   )
-  const dependenciesChanged = !inputIsCollection && dependencyComparison.changed
+  const sameClient = committed?.client === dbClient
+  const dependenciesChanged =
+    !inputIsCollection &&
+    (!sameClient ||
+      (usesLegacyDeps
+        ? dependencyComparison.changed
+        : !dependencyComparison.structurallyEqual))
   const dependenciesStructurallyEqual =
-    !inputIsCollection && dependencyComparison.structurallyEqual
+    usesLegacyDeps && sameClient && dependencyComparison.structurallyEqual
   const needsNewCollection =
     committed === null ||
     committed.inputKind !== inputKind ||
@@ -195,7 +230,18 @@ export function useLiveInfiniteQuery<TContext extends Context>(
     let warning: string | null = null
 
     if (needsNewCollection) {
-      const input = resolveLiveQueryWindowInput<TContext>(queryFnOrCollection)
+      let inputValue = queryFnOrCollection
+      if (!inputIsCollection) {
+        if (preparedQueryValue === unpreparedQueryValue) {
+          preparedQueryValue = prepareQueryValue(
+            queryFnOrCollection,
+            dbClient,
+            deferredCollections,
+          )
+        }
+        inputValue = () => preparedQueryValue
+      }
+      const input = resolveLiveQueryWindowInput<TContext>(inputValue)
       if (input.kind === `collection`) {
         collection = input.collection
       } else {
@@ -239,7 +285,10 @@ export function useLiveInfiniteQuery<TContext extends Context>(
     renderState = {
       inputKind,
       inputCollection: inputIsCollection ? collection : null,
-      dependencies: inputIsCollection ? null : [...deps],
+      inputQuery: inputIsCollection ? null : queryFnOrCollection,
+      client: dbClient,
+      identityMode,
+      dependencies: inputIsCollection ? null : [...identityDeps],
       pageSize,
       initialPageParam,
       collection,
@@ -250,6 +299,7 @@ export function useLiveInfiniteQuery<TContext extends Context>(
       }),
       warning,
       warned: false,
+      deferredCollections,
     }
   }
   const currentRenderState = renderState!
@@ -263,12 +313,16 @@ export function useLiveInfiniteQuery<TContext extends Context>(
         currentRenderState.warned = true
         console.warn(currentRenderState.warning)
       }
+      for (const collection of currentRenderState.deferredCollections) {
+        collection._resumeSyncStart()
+      }
+      currentRenderState.deferredCollections.clear()
       return unsubscribe
     },
     [controller, currentRenderState],
   )
   const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])
-  const snapshot = useSyncExternalStore(subscribe, getSnapshot)
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 
   const fetchNextPage = useCallback(
     () => fetchNextLiveQueryWindowPage(controller),