@tanstack/react-db 0.1.95 → 0.1.96

package/src/useLiveInfiniteQuery.ts

@@ -1,23 +1,39 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { CollectionImpl } from '@tanstack/db'
-import { useLiveQuery } from './useLiveQuery'
+import { useCallback, useRef, useSyncExternalStore } from 'react'
+import {
+  CollectionImpl,
+  createLiveQueryCollection,
+  createLiveQueryWindowController,
+  deepEquals,
+} from '@tanstack/db'
+// Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.
+import type { useLiveQuery } from './useLiveQuery'
 import type {
   Collection,
   Context,
   InferResultType,
   InitialQueryBuilder,
-  LiveQueryCollectionUtils,
+  LiveQueryWindowController,
   NonSingleResult,
   QueryBuilder,
 } from '@tanstack/db'
 
-/**
- * Type guard to check if utils object has setWindow method (LiveQueryCollectionUtils)
- */
-function isLiveQueryCollectionUtils(
-  utils: unknown,
-): utils is LiveQueryCollectionUtils {
-  return typeof (utils as any).setWindow === `function`
+// Live queries created here are cleaned up immediately (0 disables GC).
+const DEFAULT_GC_TIME_MS = 1
+
+type WindowedCollection = Collection<any, any, any> & {
+  utils: {
+    setWindow: (options: {
+      offset: number
+      limit: number
+    }) => true | Promise<void>
+  }
+}
+
+/** Type guard: does this collection expose `setWindow` (i.e. has an orderBy)? */
+function hasSetWindow(
+  collection: Collection<any, any, any>,
+): collection is WindowedCollection {
+  return typeof collection.utils?.setWindow === `function`
 }
 
 export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
@@ -46,8 +62,13 @@ export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<
   fetchNextPage: () => void
   hasNextPage: boolean
   isFetchingNextPage: boolean
+  error: unknown
 }
 
+type EnabledLiveQueryReturn<TContext extends Context> = ReturnType<
+  typeof useLiveQuery<TContext>
+>
+
 /**
  * Create an infinite query using a query function with live updates
  *
@@ -151,180 +172,135 @@ export function useLiveInfiniteQuery<TContext extends Context>(
     )
   }
 
-  // Track how many pages have been loaded
-  const [loadedPageCount, setLoadedPageCount] = useState(1)
-  const [isFetchingNextPage, setIsFetchingNextPage] = useState(false)
-
-  // Track collection instance and whether we've validated it (only for pre-created collections)
-  const collectionRef = useRef(isCollection ? queryFnOrCollection : null)
-  const hasValidatedCollectionRef = useRef(false)
-
-  // Track deps for query functions (stringify for comparison)
-  let depsKey: string
-  try {
-    depsKey = JSON.stringify(deps)
-  } catch {
-    throw new Error(
-      `useLiveInfiniteQuery: dependency array contains values that cannot be serialized (e.g. circular references). ` +
-        `Ensure all dependency values are JSON-serializable.`,
-    )
-  }
-  const prevDepsKeyRef = useRef(depsKey)
-
-  // Reset pagination when inputs change
-  useEffect(() => {
-    let shouldReset = false
-
+  const collectionRef = useRef<Collection<any, any, any> | null>(null)
+  const controllerRef = useRef<LiveQueryWindowController<any, any> | null>(null)
+  const configRef = useRef<unknown>(null)
+  const depsRef = useRef<Array<unknown> | null>(null)
+  const pageSizeRef = useRef(pageSize)
+  const initialPageParamRef = useRef(initialPageParam)
+  const validatedCollectionRef = useRef<unknown>(null)
+  const inputKind = isCollection ? `collection` : `query`
+  const inputKindRef = useRef<typeof inputKind | null>(null)
+  const previousInputKind = inputKindRef.current
+
+  const dependenciesChanged =
+    !isCollection &&
+    (depsRef.current === null ||
+      depsRef.current.length !== deps.length ||
+      depsRef.current.some((dep, index) => dep !== deps[index]))
+  const dependenciesStructurallyEqual =
+    !isCollection &&
+    depsRef.current !== null &&
+    deepEquals(depsRef.current, deps)
+  const needsNewCollection =
+    !collectionRef.current ||
+    inputKindRef.current !== inputKind ||
+    (isCollection && configRef.current !== queryFnOrCollection) ||
+    dependenciesChanged
+  const pageShapeChanged =
+    pageSizeRef.current !== pageSize ||
+    initialPageParamRef.current !== initialPageParam
+  const needsNewController =
+    !controllerRef.current || needsNewCollection || pageShapeChanged
+
+  if (needsNewCollection) {
+    inputKindRef.current = inputKind
     if (isCollection) {
-      // Reset if collection instance changed
-      if (collectionRef.current !== queryFnOrCollection) {
-        collectionRef.current = queryFnOrCollection
-        hasValidatedCollectionRef.current = false
-        shouldReset = true
-      }
-    } else {
-      // Reset if deps changed (for query functions)
-      if (prevDepsKeyRef.current !== depsKey) {
-        prevDepsKeyRef.current = depsKey
-        shouldReset = true
-      }
-    }
-
-    if (shouldReset) {
-      setLoadedPageCount(1)
-    }
-  }, [isCollection, queryFnOrCollection, depsKey])
-
-  // Create a live query with initial limit and offset
-  // Either pass collection directly or wrap query function
-  // Use pageSize + 1 for peek-ahead detection (to know if there are more pages)
-  const queryResult = isCollection
-    ? useLiveQuery(queryFnOrCollection)
-    : useLiveQuery(
-        (q) =>
-          queryFnOrCollection(q)
-            .limit(pageSize + 1)
-            .offset(0),
-        deps,
-      )
-
-  // Adjust window when pagination changes
-  useEffect(() => {
-    const utils = queryResult.collection.utils
-    const expectedOffset = 0
-    const expectedLimit = loadedPageCount * pageSize + 1 // +1 for peek ahead
-
-    // Check if collection has orderBy (required for setWindow)
-    if (!isLiveQueryCollectionUtils(utils)) {
-      // For pre-created collections, throw an error if no orderBy
-      if (isCollection) {
+      const collection = queryFnOrCollection as Collection<any, any, any>
+      if (!hasSetWindow(collection)) {
         throw new Error(
           `useLiveInfiniteQuery: Pre-created live query collection must have an orderBy clause for infinite pagination to work. ` +
             `Please add .orderBy() to your createLiveQueryCollection query.`,
         )
       }
-      return
-    }
-
-    // For pre-created collections, validate window on first check
-    if (isCollection && !hasValidatedCollectionRef.current) {
-      const currentWindow = utils.getWindow()
-      if (
-        currentWindow &&
-        (currentWindow.offset !== expectedOffset ||
-          currentWindow.limit !== expectedLimit)
-      ) {
-        console.warn(
-          `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +
-            `but hook expects {offset: ${expectedOffset}, limit: ${expectedLimit}}. Adjusting window now.`,
-        )
+      // Warn once per collection instance if its current window doesn't match
+      // the first page the hook is about to enforce.
+      if (validatedCollectionRef.current !== collection) {
+        validatedCollectionRef.current = collection
+        const currentWindow = collection.utils.getWindow?.()
+        if (
+          currentWindow &&
+          (currentWindow.offset !== 0 || currentWindow.limit !== pageSize + 1)
+        ) {
+          console.warn(
+            `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +
+              `but the hook expects {offset: 0, limit: ${pageSize + 1}}. Adjusting window now.`,
+          )
+        }
       }
-      hasValidatedCollectionRef.current = true
-    }
-
-    // For query functions, wait until collection is ready
-    if (!isCollection && !queryResult.isReady) return
-
-    // Adjust the window
-    let cancelled = false
-    const result = utils.setWindow({
-      offset: expectedOffset,
-      limit: expectedLimit,
-    })
-
-    if (result !== true) {
-      setIsFetchingNextPage(true)
-      result
-        .catch((error: unknown) => {
-          if (!cancelled)
-            console.error(`useLiveInfiniteQuery: setWindow failed:`, error)
-        })
-        .finally(() => {
-          if (!cancelled) setIsFetchingNextPage(false)
-        })
+      collectionRef.current = collection
+      configRef.current = queryFnOrCollection
     } else {
-      setIsFetchingNextPage(false)
-    }
-
-    return () => {
-      cancelled = true
-    }
-  }, [
-    isCollection,
-    queryResult.collection,
-    queryResult.isReady,
-    loadedPageCount,
-    pageSize,
-  ])
-
-  // Split the data array into pages and determine if there's a next page
-  const { pages, pageParams, hasNextPage, flatData } = useMemo(() => {
-    const dataArray = (
-      Array.isArray(queryResult.data) ? queryResult.data : []
-    ) as InferResultType<TContext>
-    const totalItemsRequested = loadedPageCount * pageSize
-
-    // Check if we have more data than requested (the peek ahead item)
-    const hasMore = dataArray.length > totalItemsRequested
-
-    // Build pages array (without the peek ahead item)
-    const pagesResult: Array<Array<InferResultType<TContext>[number]>> = []
-    const pageParamsResult: Array<number> = []
-
-    for (let i = 0; i < loadedPageCount; i++) {
-      const pageData = dataArray.slice(i * pageSize, (i + 1) * pageSize)
-      pagesResult.push(pageData)
-      pageParamsResult.push(initialPageParam + i)
+      // Wrap the query with the first page's peek-ahead window; the controller
+      // grows the limit from here via setWindow.
+      collectionRef.current = createLiveQueryCollection({
+        query: (q: InitialQueryBuilder) =>
+          queryFnOrCollection(q)
+            .limit(pageSize + 1)
+            .offset(0),
+        // Construction happens during render. Synchronization starts only when
+        // useSyncExternalStore commits the controller subscription.
+        startSync: false,
+        gcTime: DEFAULT_GC_TIME_MS,
+      })
+      depsRef.current = [...deps]
     }
+  }
 
-    // Flatten the pages for the data return (without peek ahead item)
-    const flatDataResult = dataArray.slice(
-      0,
-      totalItemsRequested,
-    ) as InferResultType<TContext>
+  if (needsNewController) {
+    const previousController = controllerRef.current
+    const canPreservePageCount =
+      previousController !== null &&
+      (!needsNewCollection ||
+        (previousInputKind === `query` && dependenciesStructurallyEqual))
+    const initialPageCount = canPreservePageCount
+      ? Math.max(1, previousController.getSnapshot().pages.length)
+      : 1
+    pageSizeRef.current = pageSize
+    initialPageParamRef.current = initialPageParam
+    controllerRef.current = createLiveQueryWindowController(
+      collectionRef.current,
+      {
+        pageSize,
+        initialPageParam,
+        initialPageCount,
+      },
+    )
+  }
+  const controller = controllerRef.current!
 
-    return {
-      pages: pagesResult,
-      pageParams: pageParamsResult,
-      hasNextPage: hasMore,
-      flatData: flatDataResult,
-    }
-  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam])
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => controller.subscribe(onStoreChange),
+    [controller],
+  )
+  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot)
 
-  // Fetch next page
   const fetchNextPage = useCallback(() => {
-    if (!hasNextPage || isFetchingNextPage) return
-
-    setLoadedPageCount((prev) => prev + 1)
-  }, [hasNextPage, isFetchingNextPage])
+    void controller.fetchNextPage().catch(() => {
+      // Pagination errors are exposed through the controller snapshot. The
+      // hook's void callback has no promise error channel, so consume it here.
+    })
+  }, [controller])
 
   return {
-    ...queryResult,
-    data: flatData,
-    pages,
-    pageParams,
+    data: snapshot.data as InferResultType<TContext>,
+    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],
+    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],
+    isLoading: snapshot.isLoading,
+    isReady: snapshot.isReady,
+    isIdle: snapshot.isIdle,
+    isError: snapshot.isError,
+    isCleanedUp: snapshot.isCleanedUp,
+    collection:
+      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],
+    isEnabled:
+      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],
+    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,
+    pageParams: snapshot.pageParams as Array<number>,
     fetchNextPage,
-    hasNextPage,
-    isFetchingNextPage,
-  } as UseLiveInfiniteQueryReturn<TContext>
+    hasNextPage: snapshot.hasNextPage,
+    isFetchingNextPage: snapshot.isFetchingNextPage,
+    error: snapshot.error,
+  }
 }

package/src/useLiveQuery.ts

@@ -2,9 +2,8 @@ import { useRef, useSyncExternalStore } from 'react'
 import {
   BaseQueryBuilder,
   createLiveQueryCollection,
-  getLiveQueryStatusFlags,
+  createLiveQueryObserver,
   isCollection,
-  isSingleResultCollection,
 } from '@tanstack/db'
 import type {
   Collection,
@@ -14,6 +13,7 @@ import type {
   InferResultType,
   InitialQueryBuilder,
   LiveQueryCollectionConfig,
+  LiveQueryObserver,
   NonSingleResult,
   QueryBuilder,
   SingleResult,
@@ -328,12 +328,10 @@ export function useLiveQuery(
   const depsRef = useRef<Array<unknown> | null>(null)
   const configRef = useRef<unknown>(null)
 
-  // Use refs to track version and memoized snapshot
-  const versionRef = useRef(0)
-  const snapshotRef = useRef<{
-    collection: Collection<object, string | number, {}> | null
-    version: number
-  } | null>(null)
+  // The shared observer owns subscription, the ready-race, and the snapshot.
+  const observerRef = useRef<LiveQueryObserver<object, string | number> | null>(
+    null,
+  )
 
   // Check if we need to create/recreate the collection
   const needsNewCollection =
@@ -413,143 +411,38 @@ export function useLiveQuery(
     }
   }
 
-  // Reset refs when collection changes
+  // 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) {
-    versionRef.current = 0
-    snapshotRef.current = null
+    // 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.
+    observerRef.current = createLiveQueryObserver(collectionRef.current, {
+      mode: `wholesale`,
+    })
   }
+  const observer = observerRef.current!
 
-  // Create stable subscribe function using ref
+  // Stable subscribe bound to the current observer; the observer owns the
+  // subscription, ready-race, and disposal.
   const subscribeRef = useRef<
     ((onStoreChange: () => void) => () => void) | null
   >(null)
   if (!subscribeRef.current || needsNewCollection) {
-    subscribeRef.current = (onStoreChange: () => void) => {
-      // If no collection, return a no-op unsubscribe function
-      if (!collectionRef.current) {
-        return () => {}
-      }
-
-      let unsubscribed = false
-
-      const subscription = collectionRef.current.subscribeChanges(() => {
-        // Drop late notifies that race with unsubscribe.
-        if (unsubscribed) return
-        // Bump version on any change; getSnapshot will rebuild next time
-        versionRef.current += 1
-        onStoreChange()
-      })
-      // Already-ready collections won't emit an initial change. Notify React
-      // ourselves, but defer to a microtask — calling onStoreChange synchronously
-      // here lands during the render-to-commit window and trips React's
-      // "state update on a component that hasn't mounted yet" warning.
-      if (collectionRef.current.status === `ready`) {
-        queueMicrotask(() => {
-          if (unsubscribed) return
-          versionRef.current += 1
-          onStoreChange()
-        })
-      }
-      return () => {
-        unsubscribed = true
-        subscription.unsubscribe()
-      }
-    }
-  }
-
-  // Create stable getSnapshot function using ref
-  const getSnapshotRef = useRef<
-    | (() => {
-        collection: Collection<object, string | number, {}> | null
-        version: number
-      })
-    | null
-  >(null)
-  if (!getSnapshotRef.current || needsNewCollection) {
-    getSnapshotRef.current = () => {
-      const currentVersion = versionRef.current
-      const currentCollection = collectionRef.current
-
-      // Recreate snapshot object only if version/collection changed
-      if (
-        !snapshotRef.current ||
-        snapshotRef.current.version !== currentVersion ||
-        snapshotRef.current.collection !== currentCollection
-      ) {
-        snapshotRef.current = {
-          collection: currentCollection,
-          version: currentVersion,
-        }
-      }
-
-      return snapshotRef.current
-    }
-  }
-
-  // Use useSyncExternalStore to subscribe to collection changes
-  const snapshot = useSyncExternalStore(
-    subscribeRef.current,
-    getSnapshotRef.current,
-  )
-
-  // Track last snapshot (from useSyncExternalStore) and the returned value separately
-  const returnedSnapshotRef = useRef<{
-    collection: Collection<object, string | number, {}> | null
-    version: number
-  } | null>(null)
-  // Keep implementation return loose to satisfy overload signatures
-  const returnedRef = useRef<any>(null)
-
-  // Rebuild returned object only when the snapshot changes (version or collection identity)
-  if (
-    !returnedSnapshotRef.current ||
-    returnedSnapshotRef.current.version !== snapshot.version ||
-    returnedSnapshotRef.current.collection !== snapshot.collection
-  ) {
-    // Handle null collection case (when callback returns undefined/null)
-    if (!snapshot.collection) {
-      returnedRef.current = {
-        state: undefined,
-        data: undefined,
-        collection: undefined,
-        status: `disabled`,
-        isLoading: false,
-        isReady: true,
-        isIdle: false,
-        isError: false,
-        isCleanedUp: false,
-        isEnabled: false,
-      }
-    } else {
-      // Capture a stable view of entries for this snapshot to avoid tearing
-      const entries = Array.from(snapshot.collection.entries())
-      const singleResult = isSingleResultCollection(snapshot.collection)
-      let stateCache: Map<string | number, unknown> | null = null
-      let dataCache: Array<unknown> | null = null
-
-      returnedRef.current = {
-        get state() {
-          if (!stateCache) {
-            stateCache = new Map(entries)
-          }
-          return stateCache
-        },
-        get data() {
-          if (!dataCache) {
-            dataCache = entries.map(([, value]) => value)
-          }
-          return singleResult ? dataCache[0] : dataCache
-        },
-        collection: snapshot.collection,
-        status: snapshot.collection.status,
-        ...getLiveQueryStatusFlags(snapshot.collection.status),
-        isEnabled: true,
-      }
-    }
-
-    // Remember the snapshot that produced this returned value
-    returnedSnapshotRef.current = snapshot
+    subscribeRef.current = (onStoreChange) =>
+      observer.subscribe(() => onStoreChange())
   }
 
-  return returnedRef.current!
+  // The observer returns a stable snapshot per revision, which is the return
+  // shape this hook exposes. Keep the return loose to satisfy the overloads.
+  return useSyncExternalStore(subscribeRef.current, () =>
+    observer.getSnapshot(),
+  ) as any
 }