@tanstack/react-db 0.1.95 → 0.2.0

package/src/useLiveInfiniteQuery.ts

@@ -1,24 +1,30 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { CollectionImpl } from '@tanstack/db'
-import { useLiveQuery } from './useLiveQuery'
+import { useCallback, useRef, useSyncExternalStore } from 'react'
+import {
+  assertLiveQueryWindowManyResult,
+  compareLiveQueryWindowDependencies,
+  createLiveQueryCollection,
+  createLiveQueryWindowController,
+  fetchNextLiveQueryWindowPage,
+  getLiveQueryWindowCollectionWarning,
+  getLiveQueryWindowInputKind,
+  normalizeLiveQueryWindowPageSize,
+  resolveLiveQueryWindowInput,
+  shouldPreserveLiveQueryWindowPageCount,
+} 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
 
 export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
   pageSize?: number
@@ -43,9 +49,26 @@ export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<
   data: InferResultType<TContext>
   pages: Array<Array<InferResultType<TContext>[number]>>
   pageParams: Array<number>
-  fetchNextPage: () => void
+  fetchNextPage: () => Promise<void>
   hasNextPage: boolean
   isFetchingNextPage: boolean
+  error: unknown
+}
+
+type EnabledLiveQueryReturn<TContext extends Context> = ReturnType<
+  typeof useLiveQuery<TContext>
+>
+
+type InfiniteQueryRenderState = {
+  inputKind: `collection` | `query`
+  inputCollection: Collection<any, any, any> | null
+  dependencies: Array<unknown> | null
+  pageSize: number
+  initialPageParam: number
+  collection: Collection<any, any, any>
+  controller: LiveQueryWindowController<any, any>
+  warning: string | null
+  warned: boolean
 }
 
 /**
@@ -137,194 +160,139 @@ export function useLiveInfiniteQuery<TContext extends Context>(
   config: UseLiveInfiniteQueryConfig<TContext>,
   deps: Array<unknown> = [],
 ): UseLiveInfiniteQueryReturn<TContext> {
-  const pageSize = config.pageSize || 20
+  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)
   const initialPageParam = config.initialPageParam ?? 0
 
-  // Detect if input is a collection or query function
-  const isCollection = queryFnOrCollection instanceof CollectionImpl
-
-  // Validate input type
-  if (!isCollection && typeof queryFnOrCollection !== `function`) {
-    throw new Error(
-      `useLiveInfiniteQuery: First argument must be either a pre-created live query collection (CollectionImpl) ` +
-        `or a query function. Received: ${typeof queryFnOrCollection}`,
-    )
-  }
-
-  // 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
-
-    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) {
-        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.`,
-        )
+  const inputIsCollection =
+    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`
+
+  const committedRef = useRef<InfiniteQueryRenderState | null>(null)
+  const committed = committedRef.current
+  const inputKind = inputIsCollection ? `collection` : `query`
+
+  const dependencyComparison = compareLiveQueryWindowDependencies(
+    committed?.dependencies,
+    deps,
+  )
+  const dependenciesChanged = !inputIsCollection && dependencyComparison.changed
+  const dependenciesStructurallyEqual =
+    !inputIsCollection && dependencyComparison.structurallyEqual
+  const needsNewCollection =
+    committed === null ||
+    committed.inputKind !== inputKind ||
+    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||
+    dependenciesChanged
+  const pageShapeChanged =
+    committed === null ||
+    committed.pageSize !== pageSize ||
+    committed.initialPageParam !== initialPageParam
+  const needsNewController =
+    committed === null || needsNewCollection || pageShapeChanged
+
+  let renderState = committed
+  if (needsNewController) {
+    let collection = committed?.collection
+    let warning: string | null = null
+
+    if (needsNewCollection) {
+      const input = resolveLiveQueryWindowInput<TContext>(queryFnOrCollection)
+      if (input.kind === `collection`) {
+        collection = input.collection
+      } else {
+        // Wrap the query with the first page's peek-ahead window; the controller
+        // grows the limit from here via setWindow.
+        collection = createLiveQueryCollection({
+          query: input.query.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,
+        })
       }
-      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.`,
-        )
-      }
-      hasValidatedCollectionRef.current = true
+    if (!collection) {
+      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)
     }
 
-    // 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)
-        })
+    if (inputIsCollection) {
+      warning =
+        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null
     } 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)
+      assertLiveQueryWindowManyResult(collection)
     }
 
-    // Flatten the pages for the data return (without peek ahead item)
-    const flatDataResult = dataArray.slice(
-      0,
-      totalItemsRequested,
-    ) as InferResultType<TContext>
-
-    return {
-      pages: pagesResult,
-      pageParams: pageParamsResult,
-      hasNextPage: hasMore,
-      flatData: flatDataResult,
+    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({
+      hasPreviousController: committed !== null,
+      previousInputKind: committed?.inputKind,
+      inputKind,
+      sameCollection:
+        inputIsCollection && committed?.inputCollection === collection,
+      dependenciesChanged,
+      dependenciesStructurallyEqual,
+      pageShapeChanged,
+    })
+    const previousPageCount = committed
+      ? Math.max(1, committed.controller.getSnapshot().pages.length)
+      : 1
+    const initialPageCount = canPreservePageCount ? previousPageCount : 1
+    renderState = {
+      inputKind,
+      inputCollection: inputIsCollection ? collection : null,
+      dependencies: inputIsCollection ? null : [...deps],
+      pageSize,
+      initialPageParam,
+      collection,
+      controller: createLiveQueryWindowController(collection, {
+        pageSize,
+        initialPageParam,
+        initialPageCount,
+      }),
+      warning,
+      warned: false,
     }
-  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam])
-
-  // Fetch next page
-  const fetchNextPage = useCallback(() => {
-    if (!hasNextPage || isFetchingNextPage) return
-
-    setLoadedPageCount((prev) => prev + 1)
-  }, [hasNextPage, isFetchingNextPage])
+  }
+  const currentRenderState = renderState!
+  const controller = currentRenderState.controller
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const unsubscribe = controller.subscribe(onStoreChange)
+      committedRef.current = currentRenderState
+      if (currentRenderState.warning && !currentRenderState.warned) {
+        currentRenderState.warned = true
+        console.warn(currentRenderState.warning)
+      }
+      return unsubscribe
+    },
+    [controller, currentRenderState],
+  )
+  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot)
+
+  const fetchNextPage = useCallback(
+    () => fetchNextLiveQueryWindowPage(controller),
+    [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
 }