@tanstack/react-db 0.1.96 → 0.2.0

package/dist/cjs/useLiveInfiniteQuery.cjs

@@ -3,90 +3,95 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const react = require("react");
 const db = require("@tanstack/db");
 const DEFAULT_GC_TIME_MS = 1;
-function hasSetWindow(collection) {
-  return typeof collection.utils?.setWindow === `function`;
-}
 function useLiveInfiniteQuery(queryFnOrCollection, config, deps = []) {
-  const pageSize = config.pageSize || 20;
+  const pageSize = db.normalizeLiveQueryWindowPageSize(config.pageSize);
   const initialPageParam = config.initialPageParam ?? 0;
-  const isCollection = queryFnOrCollection instanceof db.CollectionImpl;
-  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}`
-    );
-  }
-  const collectionRef = react.useRef(null);
-  const controllerRef = react.useRef(null);
-  const configRef = react.useRef(null);
-  const depsRef = react.useRef(null);
-  const pageSizeRef = react.useRef(pageSize);
-  const initialPageParamRef = react.useRef(initialPageParam);
-  const validatedCollectionRef = react.useRef(null);
-  const inputKind = isCollection ? `collection` : `query`;
-  const inputKindRef = react.useRef(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 && db.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) {
-      const collection = queryFnOrCollection;
-      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.`
-        );
-      }
-      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.`
-          );
-        }
+  const inputIsCollection = db.getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`;
+  const committedRef = react.useRef(null);
+  const committed = committedRef.current;
+  const inputKind = inputIsCollection ? `collection` : `query`;
+  const dependencyComparison = db.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 = null;
+    if (needsNewCollection) {
+      const input = db.resolveLiveQueryWindowInput(queryFnOrCollection);
+      if (input.kind === `collection`) {
+        collection = input.collection;
+      } else {
+        collection = db.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
+        });
       }
-      collectionRef.current = collection;
-      configRef.current = queryFnOrCollection;
+    }
+    if (!collection) {
+      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`);
+    }
+    if (inputIsCollection) {
+      warning = db.getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null;
     } else {
-      collectionRef.current = db.createLiveQueryCollection({
-        query: (q) => 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];
+      db.assertLiveQueryWindowManyResult(collection);
     }
-  }
-  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 = db.createLiveQueryWindowController(
-      collectionRef.current,
-      {
+    const canPreservePageCount = db.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: db.createLiveQueryWindowController(collection, {
         pageSize,
         initialPageParam,
         initialPageCount
-      }
-    );
+      }),
+      warning,
+      warned: false
+    };
   }
-  const controller = controllerRef.current;
+  const currentRenderState = renderState;
+  const controller = currentRenderState.controller;
   const subscribe = react.useCallback(
-    (onStoreChange) => controller.subscribe(onStoreChange),
-    [controller]
+    (onStoreChange) => {
+      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 = react.useCallback(() => controller.getSnapshot(), [controller]);
   const snapshot = react.useSyncExternalStore(subscribe, getSnapshot);
-  const fetchNextPage = react.useCallback(() => {
-    void controller.fetchNextPage().catch(() => {
-    });
-  }, [controller]);
+  const fetchNextPage = react.useCallback(
+    () => db.fetchNextLiveQueryWindowPage(controller),
+    [controller]
+  );
   return {
     data: snapshot.data,
     state: snapshot.state,

package/dist/cjs/useLiveInfiniteQuery.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveInfiniteQuery.cjs","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  CollectionImpl,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  deepEquals,\n} from '@tanstack/db'\n// Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.\nimport type { useLiveQuery } from './useLiveQuery'\nimport type {\n  Collection,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\n\ntype WindowedCollection = Collection<any, any, any> & {\n  utils: {\n    setWindow: (options: {\n      offset: number\n      limit: number\n    }) => true | Promise<void>\n  }\n}\n\n/** Type guard: does this collection expose `setWindow` (i.e. has an orderBy)? */\nfunction hasSetWindow(\n  collection: Collection<any, any, any>,\n): collection is WindowedCollection {\n  return typeof collection.utils?.setWindow === `function`\n}\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => void\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\n/**\n * Create an infinite query using a query function with live updates\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n *\n * @example\n * // Basic infinite query\n * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .select(({ posts }) => ({\n *       id: posts.id,\n *       title: posts.title\n *     })),\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage, allPages) =>\n *       lastPage.length === 20 ? allPages.length : undefined\n *   }\n * )\n *\n * @example\n * // With dependencies\n * const { pages, fetchNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .where(({ posts }) => eq(posts.category, category))\n *     .orderBy(({ posts }) => posts.createdAt, 'desc'),\n *   {\n *     pageSize: 10,\n *     getNextPageParam: (lastPage) =>\n *       lastPage.length === 10 ? lastPage.length : undefined\n *   },\n *   [category]\n * )\n *\n * @example\n * // Router loader pattern with pre-created collection\n * // In loader:\n * const postsQuery = createLiveQueryCollection({\n *   query: (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .limit(20)\n * })\n * await postsQuery.preload()\n * return { postsQuery }\n *\n * // In component:\n * const { postsQuery } = useLoaderData()\n * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   postsQuery,\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined\n *   }\n * )\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps: Array<unknown> = [],\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = config.pageSize || 20\n  const initialPageParam = config.initialPageParam ?? 0\n\n  // Detect if input is a collection or query function\n  const isCollection = queryFnOrCollection instanceof CollectionImpl\n\n  // Validate input type\n  if (!isCollection && typeof queryFnOrCollection !== `function`) {\n    throw new Error(\n      `useLiveInfiniteQuery: First argument must be either a pre-created live query collection (CollectionImpl) ` +\n        `or a query function. Received: ${typeof queryFnOrCollection}`,\n    )\n  }\n\n  const collectionRef = useRef<Collection<any, any, any> | null>(null)\n  const controllerRef = useRef<LiveQueryWindowController<any, any> | null>(null)\n  const configRef = useRef<unknown>(null)\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const pageSizeRef = useRef(pageSize)\n  const initialPageParamRef = useRef(initialPageParam)\n  const validatedCollectionRef = useRef<unknown>(null)\n  const inputKind = isCollection ? `collection` : `query`\n  const inputKindRef = useRef<typeof inputKind | null>(null)\n  const previousInputKind = inputKindRef.current\n\n  const dependenciesChanged =\n    !isCollection &&\n    (depsRef.current === null ||\n      depsRef.current.length !== deps.length ||\n      depsRef.current.some((dep, index) => dep !== deps[index]))\n  const dependenciesStructurallyEqual =\n    !isCollection &&\n    depsRef.current !== null &&\n    deepEquals(depsRef.current, deps)\n  const needsNewCollection =\n    !collectionRef.current ||\n    inputKindRef.current !== inputKind ||\n    (isCollection && configRef.current !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    pageSizeRef.current !== pageSize ||\n    initialPageParamRef.current !== initialPageParam\n  const needsNewController =\n    !controllerRef.current || needsNewCollection || pageShapeChanged\n\n  if (needsNewCollection) {\n    inputKindRef.current = inputKind\n    if (isCollection) {\n      const collection = queryFnOrCollection as Collection<any, any, any>\n      if (!hasSetWindow(collection)) {\n        throw new Error(\n          `useLiveInfiniteQuery: Pre-created live query collection must have an orderBy clause for infinite pagination to work. ` +\n            `Please add .orderBy() to your createLiveQueryCollection query.`,\n        )\n      }\n      // Warn once per collection instance if its current window doesn't match\n      // the first page the hook is about to enforce.\n      if (validatedCollectionRef.current !== collection) {\n        validatedCollectionRef.current = collection\n        const currentWindow = collection.utils.getWindow?.()\n        if (\n          currentWindow &&\n          (currentWindow.offset !== 0 || currentWindow.limit !== pageSize + 1)\n        ) {\n          console.warn(\n            `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +\n              `but the hook expects {offset: 0, limit: ${pageSize + 1}}. Adjusting window now.`,\n          )\n        }\n      }\n      collectionRef.current = collection\n      configRef.current = queryFnOrCollection\n    } else {\n      // Wrap the query with the first page's peek-ahead window; the controller\n      // grows the limit from here via setWindow.\n      collectionRef.current = createLiveQueryCollection({\n        query: (q: InitialQueryBuilder) =>\n          queryFnOrCollection(q)\n            .limit(pageSize + 1)\n            .offset(0),\n        // Construction happens during render. Synchronization starts only when\n        // useSyncExternalStore commits the controller subscription.\n        startSync: false,\n        gcTime: DEFAULT_GC_TIME_MS,\n      })\n      depsRef.current = [...deps]\n    }\n  }\n\n  if (needsNewController) {\n    const previousController = controllerRef.current\n    const canPreservePageCount =\n      previousController !== null &&\n      (!needsNewCollection ||\n        (previousInputKind === `query` && dependenciesStructurallyEqual))\n    const initialPageCount = canPreservePageCount\n      ? Math.max(1, previousController.getSnapshot().pages.length)\n      : 1\n    pageSizeRef.current = pageSize\n    initialPageParamRef.current = initialPageParam\n    controllerRef.current = createLiveQueryWindowController(\n      collectionRef.current,\n      {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      },\n    )\n  }\n  const controller = controllerRef.current!\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => controller.subscribe(onStoreChange),\n    [controller],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot)\n\n  const fetchNextPage = useCallback(() => {\n    void controller.fetchNextPage().catch(() => {\n      // Pagination errors are exposed through the controller snapshot. The\n      // hook's void callback has no promise error channel, so consume it here.\n    })\n  }, [controller])\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":["CollectionImpl","useRef","deepEquals","createLiveQueryCollection","createLiveQueryWindowController","useCallback","useSyncExternalStore"],"mappings":"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"}
+{"version":3,"file":"useLiveInfiniteQuery.cjs","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  assertLiveQueryWindowManyResult,\n  compareLiveQueryWindowDependencies,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryWindowCollectionWarning,\n  getLiveQueryWindowInputKind,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\n// Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.\nimport type { useLiveQuery } from './useLiveQuery'\nimport type {\n  Collection,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\ntype InfiniteQueryRenderState = {\n  inputKind: `collection` | `query`\n  inputCollection: Collection<any, any, any> | null\n  dependencies: Array<unknown> | null\n  pageSize: number\n  initialPageParam: number\n  collection: Collection<any, any, any>\n  controller: LiveQueryWindowController<any, any>\n  warning: string | null\n  warned: boolean\n}\n\n/**\n * Create an infinite query using a query function with live updates\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n *\n * @example\n * // Basic infinite query\n * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .select(({ posts }) => ({\n *       id: posts.id,\n *       title: posts.title\n *     })),\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage, allPages) =>\n *       lastPage.length === 20 ? allPages.length : undefined\n *   }\n * )\n *\n * @example\n * // With dependencies\n * const { pages, fetchNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .where(({ posts }) => eq(posts.category, category))\n *     .orderBy(({ posts }) => posts.createdAt, 'desc'),\n *   {\n *     pageSize: 10,\n *     getNextPageParam: (lastPage) =>\n *       lastPage.length === 10 ? lastPage.length : undefined\n *   },\n *   [category]\n * )\n *\n * @example\n * // Router loader pattern with pre-created collection\n * // In loader:\n * const postsQuery = createLiveQueryCollection({\n *   query: (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .limit(20)\n * })\n * await postsQuery.preload()\n * return { postsQuery }\n *\n * // In component:\n * const { postsQuery } = useLoaderData()\n * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   postsQuery,\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined\n *   }\n * )\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps: Array<unknown> = [],\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)\n  const initialPageParam = config.initialPageParam ?? 0\n\n  const inputIsCollection =\n    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`\n\n  const committedRef = useRef<InfiniteQueryRenderState | null>(null)\n  const committed = committedRef.current\n  const inputKind = inputIsCollection ? `collection` : `query`\n\n  const dependencyComparison = compareLiveQueryWindowDependencies(\n    committed?.dependencies,\n    deps,\n  )\n  const dependenciesChanged = !inputIsCollection && dependencyComparison.changed\n  const dependenciesStructurallyEqual =\n    !inputIsCollection && dependencyComparison.structurallyEqual\n  const needsNewCollection =\n    committed === null ||\n    committed.inputKind !== inputKind ||\n    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    committed === null ||\n    committed.pageSize !== pageSize ||\n    committed.initialPageParam !== initialPageParam\n  const needsNewController =\n    committed === null || needsNewCollection || pageShapeChanged\n\n  let renderState = committed\n  if (needsNewController) {\n    let collection = committed?.collection\n    let warning: string | null = null\n\n    if (needsNewCollection) {\n      const input = resolveLiveQueryWindowInput<TContext>(queryFnOrCollection)\n      if (input.kind === `collection`) {\n        collection = input.collection\n      } else {\n        // Wrap the query with the first page's peek-ahead window; the controller\n        // grows the limit from here via setWindow.\n        collection = createLiveQueryCollection({\n          query: input.query.limit(pageSize + 1).offset(0),\n          // Construction happens during render. Synchronization starts only when\n          // useSyncExternalStore commits the controller subscription.\n          startSync: false,\n          gcTime: DEFAULT_GC_TIME_MS,\n        })\n      }\n    }\n\n    if (!collection) {\n      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)\n    }\n\n    if (inputIsCollection) {\n      warning =\n        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null\n    } else {\n      assertLiveQueryWindowManyResult(collection)\n    }\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === collection,\n      dependenciesChanged,\n      dependenciesStructurallyEqual,\n      pageShapeChanged,\n    })\n    const previousPageCount = committed\n      ? Math.max(1, committed.controller.getSnapshot().pages.length)\n      : 1\n    const initialPageCount = canPreservePageCount ? previousPageCount : 1\n    renderState = {\n      inputKind,\n      inputCollection: inputIsCollection ? collection : null,\n      dependencies: inputIsCollection ? null : [...deps],\n      pageSize,\n      initialPageParam,\n      collection,\n      controller: createLiveQueryWindowController(collection, {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      }),\n      warning,\n      warned: false,\n    }\n  }\n  const currentRenderState = renderState!\n  const controller = currentRenderState.controller\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const unsubscribe = controller.subscribe(onStoreChange)\n      committedRef.current = currentRenderState\n      if (currentRenderState.warning && !currentRenderState.warned) {\n        currentRenderState.warned = true\n        console.warn(currentRenderState.warning)\n      }\n      return unsubscribe\n    },\n    [controller, currentRenderState],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot)\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":["normalizeLiveQueryWindowPageSize","getLiveQueryWindowInputKind","useRef","compareLiveQueryWindowDependencies","resolveLiveQueryWindowInput","createLiveQueryCollection","getLiveQueryWindowCollectionWarning","assertLiveQueryWindowManyResult","shouldPreserveLiveQueryWindowPageCount","createLiveQueryWindowController","useCallback","useSyncExternalStore","fetchNextLiveQueryWindowPage"],"mappings":"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"}

package/dist/cjs/useLiveInfiniteQuery.d.cts

@@ -14,7 +14,7 @@ export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<ReturnTy
     data: InferResultType<TContext>;
     pages: Array<Array<InferResultType<TContext>[number]>>;
     pageParams: Array<number>;
-    fetchNextPage: () => void;
+    fetchNextPage: () => Promise<void>;
     hasNextPage: boolean;
     isFetchingNextPage: boolean;
     error: unknown;

package/dist/esm/useLiveInfiniteQuery.d.ts

@@ -14,7 +14,7 @@ export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<ReturnTy
     data: InferResultType<TContext>;
     pages: Array<Array<InferResultType<TContext>[number]>>;
     pageParams: Array<number>;
-    fetchNextPage: () => void;
+    fetchNextPage: () => Promise<void>;
     hasNextPage: boolean;
     isFetchingNextPage: boolean;
     error: unknown;

package/dist/esm/useLiveInfiniteQuery.js

@@ -1,90 +1,95 @@
 import { useRef, useCallback, useSyncExternalStore } from "react";
-import { deepEquals, createLiveQueryCollection, createLiveQueryWindowController, CollectionImpl } from "@tanstack/db";
+import { normalizeLiveQueryWindowPageSize, getLiveQueryWindowInputKind, compareLiveQueryWindowDependencies, resolveLiveQueryWindowInput, createLiveQueryCollection, getLiveQueryWindowCollectionWarning, assertLiveQueryWindowManyResult, shouldPreserveLiveQueryWindowPageCount, createLiveQueryWindowController, fetchNextLiveQueryWindowPage } from "@tanstack/db";
 const DEFAULT_GC_TIME_MS = 1;
-function hasSetWindow(collection) {
-  return typeof collection.utils?.setWindow === `function`;
-}
 function useLiveInfiniteQuery(queryFnOrCollection, config, deps = []) {
-  const pageSize = config.pageSize || 20;
+  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize);
   const initialPageParam = config.initialPageParam ?? 0;
-  const isCollection = queryFnOrCollection instanceof CollectionImpl;
-  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}`
-    );
-  }
-  const collectionRef = useRef(null);
-  const controllerRef = useRef(null);
-  const configRef = useRef(null);
-  const depsRef = useRef(null);
-  const pageSizeRef = useRef(pageSize);
-  const initialPageParamRef = useRef(initialPageParam);
-  const validatedCollectionRef = useRef(null);
-  const inputKind = isCollection ? `collection` : `query`;
-  const inputKindRef = useRef(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) {
-      const collection = queryFnOrCollection;
-      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.`
-        );
-      }
-      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.`
-          );
-        }
+  const inputIsCollection = getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`;
+  const committedRef = useRef(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 = null;
+    if (needsNewCollection) {
+      const input = resolveLiveQueryWindowInput(queryFnOrCollection);
+      if (input.kind === `collection`) {
+        collection = input.collection;
+      } else {
+        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
+        });
       }
-      collectionRef.current = collection;
-      configRef.current = queryFnOrCollection;
+    }
+    if (!collection) {
+      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`);
+    }
+    if (inputIsCollection) {
+      warning = getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null;
     } else {
-      collectionRef.current = createLiveQueryCollection({
-        query: (q) => 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];
+      assertLiveQueryWindowManyResult(collection);
     }
-  }
-  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,
-      {
+    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
+    };
   }
-  const controller = controllerRef.current;
+  const currentRenderState = renderState;
+  const controller = currentRenderState.controller;
   const subscribe = useCallback(
-    (onStoreChange) => controller.subscribe(onStoreChange),
-    [controller]
+    (onStoreChange) => {
+      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(() => {
-    void controller.fetchNextPage().catch(() => {
-    });
-  }, [controller]);
+  const fetchNextPage = useCallback(
+    () => fetchNextLiveQueryWindowPage(controller),
+    [controller]
+  );
   return {
     data: snapshot.data,
     state: snapshot.state,

package/dist/esm/useLiveInfiniteQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveInfiniteQuery.js","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  CollectionImpl,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  deepEquals,\n} from '@tanstack/db'\n// Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.\nimport type { useLiveQuery } from './useLiveQuery'\nimport type {\n  Collection,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\n\ntype WindowedCollection = Collection<any, any, any> & {\n  utils: {\n    setWindow: (options: {\n      offset: number\n      limit: number\n    }) => true | Promise<void>\n  }\n}\n\n/** Type guard: does this collection expose `setWindow` (i.e. has an orderBy)? */\nfunction hasSetWindow(\n  collection: Collection<any, any, any>,\n): collection is WindowedCollection {\n  return typeof collection.utils?.setWindow === `function`\n}\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => void\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\n/**\n * Create an infinite query using a query function with live updates\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n *\n * @example\n * // Basic infinite query\n * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .select(({ posts }) => ({\n *       id: posts.id,\n *       title: posts.title\n *     })),\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage, allPages) =>\n *       lastPage.length === 20 ? allPages.length : undefined\n *   }\n * )\n *\n * @example\n * // With dependencies\n * const { pages, fetchNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .where(({ posts }) => eq(posts.category, category))\n *     .orderBy(({ posts }) => posts.createdAt, 'desc'),\n *   {\n *     pageSize: 10,\n *     getNextPageParam: (lastPage) =>\n *       lastPage.length === 10 ? lastPage.length : undefined\n *   },\n *   [category]\n * )\n *\n * @example\n * // Router loader pattern with pre-created collection\n * // In loader:\n * const postsQuery = createLiveQueryCollection({\n *   query: (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .limit(20)\n * })\n * await postsQuery.preload()\n * return { postsQuery }\n *\n * // In component:\n * const { postsQuery } = useLoaderData()\n * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   postsQuery,\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined\n *   }\n * )\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps: Array<unknown> = [],\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = config.pageSize || 20\n  const initialPageParam = config.initialPageParam ?? 0\n\n  // Detect if input is a collection or query function\n  const isCollection = queryFnOrCollection instanceof CollectionImpl\n\n  // Validate input type\n  if (!isCollection && typeof queryFnOrCollection !== `function`) {\n    throw new Error(\n      `useLiveInfiniteQuery: First argument must be either a pre-created live query collection (CollectionImpl) ` +\n        `or a query function. Received: ${typeof queryFnOrCollection}`,\n    )\n  }\n\n  const collectionRef = useRef<Collection<any, any, any> | null>(null)\n  const controllerRef = useRef<LiveQueryWindowController<any, any> | null>(null)\n  const configRef = useRef<unknown>(null)\n  const depsRef = useRef<Array<unknown> | null>(null)\n  const pageSizeRef = useRef(pageSize)\n  const initialPageParamRef = useRef(initialPageParam)\n  const validatedCollectionRef = useRef<unknown>(null)\n  const inputKind = isCollection ? `collection` : `query`\n  const inputKindRef = useRef<typeof inputKind | null>(null)\n  const previousInputKind = inputKindRef.current\n\n  const dependenciesChanged =\n    !isCollection &&\n    (depsRef.current === null ||\n      depsRef.current.length !== deps.length ||\n      depsRef.current.some((dep, index) => dep !== deps[index]))\n  const dependenciesStructurallyEqual =\n    !isCollection &&\n    depsRef.current !== null &&\n    deepEquals(depsRef.current, deps)\n  const needsNewCollection =\n    !collectionRef.current ||\n    inputKindRef.current !== inputKind ||\n    (isCollection && configRef.current !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    pageSizeRef.current !== pageSize ||\n    initialPageParamRef.current !== initialPageParam\n  const needsNewController =\n    !controllerRef.current || needsNewCollection || pageShapeChanged\n\n  if (needsNewCollection) {\n    inputKindRef.current = inputKind\n    if (isCollection) {\n      const collection = queryFnOrCollection as Collection<any, any, any>\n      if (!hasSetWindow(collection)) {\n        throw new Error(\n          `useLiveInfiniteQuery: Pre-created live query collection must have an orderBy clause for infinite pagination to work. ` +\n            `Please add .orderBy() to your createLiveQueryCollection query.`,\n        )\n      }\n      // Warn once per collection instance if its current window doesn't match\n      // the first page the hook is about to enforce.\n      if (validatedCollectionRef.current !== collection) {\n        validatedCollectionRef.current = collection\n        const currentWindow = collection.utils.getWindow?.()\n        if (\n          currentWindow &&\n          (currentWindow.offset !== 0 || currentWindow.limit !== pageSize + 1)\n        ) {\n          console.warn(\n            `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +\n              `but the hook expects {offset: 0, limit: ${pageSize + 1}}. Adjusting window now.`,\n          )\n        }\n      }\n      collectionRef.current = collection\n      configRef.current = queryFnOrCollection\n    } else {\n      // Wrap the query with the first page's peek-ahead window; the controller\n      // grows the limit from here via setWindow.\n      collectionRef.current = createLiveQueryCollection({\n        query: (q: InitialQueryBuilder) =>\n          queryFnOrCollection(q)\n            .limit(pageSize + 1)\n            .offset(0),\n        // Construction happens during render. Synchronization starts only when\n        // useSyncExternalStore commits the controller subscription.\n        startSync: false,\n        gcTime: DEFAULT_GC_TIME_MS,\n      })\n      depsRef.current = [...deps]\n    }\n  }\n\n  if (needsNewController) {\n    const previousController = controllerRef.current\n    const canPreservePageCount =\n      previousController !== null &&\n      (!needsNewCollection ||\n        (previousInputKind === `query` && dependenciesStructurallyEqual))\n    const initialPageCount = canPreservePageCount\n      ? Math.max(1, previousController.getSnapshot().pages.length)\n      : 1\n    pageSizeRef.current = pageSize\n    initialPageParamRef.current = initialPageParam\n    controllerRef.current = createLiveQueryWindowController(\n      collectionRef.current,\n      {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      },\n    )\n  }\n  const controller = controllerRef.current!\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => controller.subscribe(onStoreChange),\n    [controller],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot)\n\n  const fetchNextPage = useCallback(() => {\n    void controller.fetchNextPage().catch(() => {\n      // Pagination errors are exposed through the controller snapshot. The\n      // hook's void callback has no promise error channel, so consume it here.\n    })\n  }, [controller])\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useLiveInfiniteQuery.js","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useRef, useSyncExternalStore } from 'react'\nimport {\n  assertLiveQueryWindowManyResult,\n  compareLiveQueryWindowDependencies,\n  createLiveQueryCollection,\n  createLiveQueryWindowController,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryWindowCollectionWarning,\n  getLiveQueryWindowInputKind,\n  normalizeLiveQueryWindowPageSize,\n  resolveLiveQueryWindowInput,\n  shouldPreserveLiveQueryWindowPageCount,\n} from '@tanstack/db'\n// Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.\nimport type { useLiveQuery } from './useLiveQuery'\nimport type {\n  Collection,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryWindowController,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\n\n// Live queries created here are cleaned up immediately (0 disables GC).\nconst DEFAULT_GC_TIME_MS = 1\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  pageSize?: number\n  initialPageParam?: number\n  /**\n   * @deprecated This callback is not used by the current implementation.\n   * Pagination is determined internally via a peek-ahead strategy.\n   * Provided for API compatibility with TanStack Query conventions.\n   */\n  getNextPageParam?: (\n    lastPage: Array<InferResultType<TContext>[number]>,\n    allPages: Array<Array<InferResultType<TContext>[number]>>,\n    lastPageParam: number,\n    allPageParams: Array<number>,\n  ) => number | undefined\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<\n  ReturnType<typeof useLiveQuery<TContext>>,\n  `data`\n> & {\n  data: InferResultType<TContext>\n  pages: Array<Array<InferResultType<TContext>[number]>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n  error: unknown\n}\n\ntype EnabledLiveQueryReturn<TContext extends Context> = ReturnType<\n  typeof useLiveQuery<TContext>\n>\n\ntype InfiniteQueryRenderState = {\n  inputKind: `collection` | `query`\n  inputCollection: Collection<any, any, any> | null\n  dependencies: Array<unknown> | null\n  pageSize: number\n  initialPageParam: number\n  collection: Collection<any, any, any>\n  controller: LiveQueryWindowController<any, any>\n  warning: string | null\n  warned: boolean\n}\n\n/**\n * Create an infinite query using a query function with live updates\n *\n * Uses `utils.setWindow()` to dynamically adjust the limit/offset window\n * without recreating the live query collection on each page change.\n *\n * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.\n * @param config - Configuration including pageSize and getNextPageParam\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with pages, data, and pagination controls\n *\n * @example\n * // Basic infinite query\n * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .select(({ posts }) => ({\n *       id: posts.id,\n *       title: posts.title\n *     })),\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage, allPages) =>\n *       lastPage.length === 20 ? allPages.length : undefined\n *   }\n * )\n *\n * @example\n * // With dependencies\n * const { pages, fetchNextPage } = useLiveInfiniteQuery(\n *   (q) => q\n *     .from({ posts: postsCollection })\n *     .where(({ posts }) => eq(posts.category, category))\n *     .orderBy(({ posts }) => posts.createdAt, 'desc'),\n *   {\n *     pageSize: 10,\n *     getNextPageParam: (lastPage) =>\n *       lastPage.length === 10 ? lastPage.length : undefined\n *   },\n *   [category]\n * )\n *\n * @example\n * // Router loader pattern with pre-created collection\n * // In loader:\n * const postsQuery = createLiveQueryCollection({\n *   query: (q) => q\n *     .from({ posts: postsCollection })\n *     .orderBy(({ posts }) => posts.createdAt, 'desc')\n *     .limit(20)\n * })\n * await postsQuery.preload()\n * return { postsQuery }\n *\n * // In component:\n * const { postsQuery } = useLoaderData()\n * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   postsQuery,\n *   {\n *     pageSize: 20,\n *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined\n *   }\n * )\n */\n\n// Overload for pre-created collection (non-single result)\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any>\n\n// Overload for query function\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps?: Array<unknown>,\n): UseLiveInfiniteQueryReturn<TContext>\n\n// Implementation\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFnOrCollection: any,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n  deps: Array<unknown> = [],\n): UseLiveInfiniteQueryReturn<TContext> {\n  const pageSize = normalizeLiveQueryWindowPageSize(config.pageSize)\n  const initialPageParam = config.initialPageParam ?? 0\n\n  const inputIsCollection =\n    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`\n\n  const committedRef = useRef<InfiniteQueryRenderState | null>(null)\n  const committed = committedRef.current\n  const inputKind = inputIsCollection ? `collection` : `query`\n\n  const dependencyComparison = compareLiveQueryWindowDependencies(\n    committed?.dependencies,\n    deps,\n  )\n  const dependenciesChanged = !inputIsCollection && dependencyComparison.changed\n  const dependenciesStructurallyEqual =\n    !inputIsCollection && dependencyComparison.structurallyEqual\n  const needsNewCollection =\n    committed === null ||\n    committed.inputKind !== inputKind ||\n    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||\n    dependenciesChanged\n  const pageShapeChanged =\n    committed === null ||\n    committed.pageSize !== pageSize ||\n    committed.initialPageParam !== initialPageParam\n  const needsNewController =\n    committed === null || needsNewCollection || pageShapeChanged\n\n  let renderState = committed\n  if (needsNewController) {\n    let collection = committed?.collection\n    let warning: string | null = null\n\n    if (needsNewCollection) {\n      const input = resolveLiveQueryWindowInput<TContext>(queryFnOrCollection)\n      if (input.kind === `collection`) {\n        collection = input.collection\n      } else {\n        // Wrap the query with the first page's peek-ahead window; the controller\n        // grows the limit from here via setWindow.\n        collection = createLiveQueryCollection({\n          query: input.query.limit(pageSize + 1).offset(0),\n          // Construction happens during render. Synchronization starts only when\n          // useSyncExternalStore commits the controller subscription.\n          startSync: false,\n          gcTime: DEFAULT_GC_TIME_MS,\n        })\n      }\n    }\n\n    if (!collection) {\n      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)\n    }\n\n    if (inputIsCollection) {\n      warning =\n        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null\n    } else {\n      assertLiveQueryWindowManyResult(collection)\n    }\n\n    const canPreservePageCount = shouldPreserveLiveQueryWindowPageCount({\n      hasPreviousController: committed !== null,\n      previousInputKind: committed?.inputKind,\n      inputKind,\n      sameCollection:\n        inputIsCollection && committed?.inputCollection === collection,\n      dependenciesChanged,\n      dependenciesStructurallyEqual,\n      pageShapeChanged,\n    })\n    const previousPageCount = committed\n      ? Math.max(1, committed.controller.getSnapshot().pages.length)\n      : 1\n    const initialPageCount = canPreservePageCount ? previousPageCount : 1\n    renderState = {\n      inputKind,\n      inputCollection: inputIsCollection ? collection : null,\n      dependencies: inputIsCollection ? null : [...deps],\n      pageSize,\n      initialPageParam,\n      collection,\n      controller: createLiveQueryWindowController(collection, {\n        pageSize,\n        initialPageParam,\n        initialPageCount,\n      }),\n      warning,\n      warned: false,\n    }\n  }\n  const currentRenderState = renderState!\n  const controller = currentRenderState.controller\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const unsubscribe = controller.subscribe(onStoreChange)\n      committedRef.current = currentRenderState\n      if (currentRenderState.warning && !currentRenderState.warned) {\n        currentRenderState.warned = true\n        console.warn(currentRenderState.warning)\n      }\n      return unsubscribe\n    },\n    [controller, currentRenderState],\n  )\n  const getSnapshot = useCallback(() => controller.getSnapshot(), [controller])\n  const snapshot = useSyncExternalStore(subscribe, getSnapshot)\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data as InferResultType<TContext>,\n    state: snapshot.state as EnabledLiveQueryReturn<TContext>[`state`],\n    status: snapshot.status as EnabledLiveQueryReturn<TContext>[`status`],\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isError: snapshot.isError,\n    isCleanedUp: snapshot.isCleanedUp,\n    collection:\n      snapshot.collection as EnabledLiveQueryReturn<TContext>[`collection`],\n    isEnabled:\n      snapshot.isEnabled as EnabledLiveQueryReturn<TContext>[`isEnabled`],\n    pages: snapshot.pages as Array<Array<InferResultType<TContext>[number]>>,\n    pageParams: snapshot.pageParams as Array<number>,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    error: snapshot.error,\n  }\n}\n"],"names":[],"mappings":";;AA0BA,MAAM,qBAAqB;AAmIpB,SAAS,qBACd,qBACA,QACA,OAAuB,CAAA,GACe;AACtC,QAAM,WAAW,iCAAiC,OAAO,QAAQ;AACjE,QAAM,mBAAmB,OAAO,oBAAoB;AAEpD,QAAM,oBACJ,4BAA4B,mBAAmB,MAAM;AAEvD,QAAM,eAAe,OAAwC,IAAI;AACjE,QAAM,YAAY,aAAa;AAC/B,QAAM,YAAY,oBAAoB,eAAe;AAErD,QAAM,uBAAuB;AAAA,IAC3B,WAAW;AAAA,IACX;AAAA,EAAA;AAEF,QAAM,sBAAsB,CAAC,qBAAqB,qBAAqB;AACvE,QAAM,gCACJ,CAAC,qBAAqB,qBAAqB;AAC7C,QAAM,qBACJ,cAAc,QACd,UAAU,cAAc,aACvB,qBAAqB,UAAU,oBAAoB,uBACpD;AACF,QAAM,mBACJ,cAAc,QACd,UAAU,aAAa,YACvB,UAAU,qBAAqB;AACjC,QAAM,qBACJ,cAAc,QAAQ,sBAAsB;AAE9C,MAAI,cAAc;AAClB,MAAI,oBAAoB;AACtB,QAAI,aAAa,WAAW;AAC5B,QAAI,UAAyB;AAE7B,QAAI,oBAAoB;AACtB,YAAM,QAAQ,4BAAsC,mBAAmB;AACvE,UAAI,MAAM,SAAS,cAAc;AAC/B,qBAAa,MAAM;AAAA,MACrB,OAAO;AAGL,qBAAa,0BAA0B;AAAA,UACrC,OAAO,MAAM,MAAM,MAAM,WAAW,CAAC,EAAE,OAAO,CAAC;AAAA;AAAA;AAAA,UAG/C,WAAW;AAAA,UACX,QAAQ;AAAA,QAAA,CACT;AAAA,MACH;AAAA,IACF;AAEA,QAAI,CAAC,YAAY;AACf,YAAM,IAAI,MAAM,sDAAsD;AAAA,IACxE;AAEA,QAAI,mBAAmB;AACrB,gBACE,oCAAoC,YAAY,WAAW,CAAC,KAAK;AAAA,IACrE,OAAO;AACL,sCAAgC,UAAU;AAAA,IAC5C;AAEA,UAAM,uBAAuB,uCAAuC;AAAA,MAClE,uBAAuB,cAAc;AAAA,MACrC,mBAAmB,WAAW;AAAA,MAC9B;AAAA,MACA,gBACE,qBAAqB,WAAW,oBAAoB;AAAA,MACtD;AAAA,MACA;AAAA,MACA;AAAA,IAAA,CACD;AACD,UAAM,oBAAoB,YACtB,KAAK,IAAI,GAAG,UAAU,WAAW,YAAA,EAAc,MAAM,MAAM,IAC3D;AACJ,UAAM,mBAAmB,uBAAuB,oBAAoB;AACpE,kBAAc;AAAA,MACZ;AAAA,MACA,iBAAiB,oBAAoB,aAAa;AAAA,MAClD,cAAc,oBAAoB,OAAO,CAAC,GAAG,IAAI;AAAA,MACjD;AAAA,MACA;AAAA,MACA;AAAA,MACA,YAAY,gCAAgC,YAAY;AAAA,QACtD;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,MACD;AAAA,MACA,QAAQ;AAAA,IAAA;AAAA,EAEZ;AACA,QAAM,qBAAqB;AAC3B,QAAM,aAAa,mBAAmB;AAEtC,QAAM,YAAY;AAAA,IAChB,CAAC,kBAA8B;AAC7B,YAAM,cAAc,WAAW,UAAU,aAAa;AACtD,mBAAa,UAAU;AACvB,UAAI,mBAAmB,WAAW,CAAC,mBAAmB,QAAQ;AAC5D,2BAAmB,SAAS;AAC5B,gBAAQ,KAAK,mBAAmB,OAAO;AAAA,MACzC;AACA,aAAO;AAAA,IACT;AAAA,IACA,CAAC,YAAY,kBAAkB;AAAA,EAAA;AAEjC,QAAM,cAAc,YAAY,MAAM,WAAW,eAAe,CAAC,UAAU,CAAC;AAC5E,QAAM,WAAW,qBAAqB,WAAW,WAAW;AAE5D,QAAM,gBAAgB;AAAA,IACpB,MAAM,6BAA6B,UAAU;AAAA,IAC7C,CAAC,UAAU;AAAA,EAAA;AAGb,SAAO;AAAA,IACL,MAAM,SAAS;AAAA,IACf,OAAO,SAAS;AAAA,IAChB,QAAQ,SAAS;AAAA,IACjB,WAAW,SAAS;AAAA,IACpB,SAAS,SAAS;AAAA,IAClB,QAAQ,SAAS;AAAA,IACjB,SAAS,SAAS;AAAA,IAClB,aAAa,SAAS;AAAA,IACtB,YACE,SAAS;AAAA,IACX,WACE,SAAS;AAAA,IACX,OAAO,SAAS;AAAA,IAChB,YAAY,SAAS;AAAA,IACrB;AAAA,IACA,aAAa,SAAS;AAAA,IACtB,oBAAoB,SAAS;AAAA,IAC7B,OAAO,SAAS;AAAA,EAAA;AAEpB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-db",
-  "version": "0.1.96",
+  "version": "0.2.0",
   "description": "React integration for @tanstack/db",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@tanstack/db": "0.7.0"
+    "@tanstack/db": "0.7.1"
   },
   "peerDependencies": {
     "react": ">=16.8.0"

package/src/useLiveInfiniteQuery.ts

@@ -1,9 +1,15 @@
 import { useCallback, useRef, useSyncExternalStore } from 'react'
 import {
-  CollectionImpl,
+  assertLiveQueryWindowManyResult,
+  compareLiveQueryWindowDependencies,
   createLiveQueryCollection,
   createLiveQueryWindowController,
-  deepEquals,
+  fetchNextLiveQueryWindowPage,
+  getLiveQueryWindowCollectionWarning,
+  getLiveQueryWindowInputKind,
+  normalizeLiveQueryWindowPageSize,
+  resolveLiveQueryWindowInput,
+  shouldPreserveLiveQueryWindowPageCount,
 } from '@tanstack/db'
 // Type-only: used in `ReturnType<typeof useLiveQuery>` in UseLiveInfiniteQueryReturn.
 import type { useLiveQuery } from './useLiveQuery'
@@ -20,22 +26,6 @@ import type {
 // 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> = {
   pageSize?: number
   initialPageParam?: number
@@ -59,7 +49,7 @@ 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
@@ -69,6 +59,18 @@ 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
+}
+
 /**
  * Create an infinite query using a query function with live updates
  *
@@ -158,130 +160,120 @@ 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
+  const inputIsCollection =
+    getLiveQueryWindowInputKind(queryFnOrCollection) === `collection`
 
-  // 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}`,
-    )
-  }
-
-  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 committedRef = useRef<InfiniteQueryRenderState | null>(null)
+  const committed = committedRef.current
+  const inputKind = inputIsCollection ? `collection` : `query`
 
-  const dependenciesChanged =
-    !isCollection &&
-    (depsRef.current === null ||
-      depsRef.current.length !== deps.length ||
-      depsRef.current.some((dep, index) => dep !== deps[index]))
+  const dependencyComparison = compareLiveQueryWindowDependencies(
+    committed?.dependencies,
+    deps,
+  )
+  const dependenciesChanged = !inputIsCollection && dependencyComparison.changed
   const dependenciesStructurallyEqual =
-    !isCollection &&
-    depsRef.current !== null &&
-    deepEquals(depsRef.current, deps)
+    !inputIsCollection && dependencyComparison.structurallyEqual
   const needsNewCollection =
-    !collectionRef.current ||
-    inputKindRef.current !== inputKind ||
-    (isCollection && configRef.current !== queryFnOrCollection) ||
+    committed === null ||
+    committed.inputKind !== inputKind ||
+    (inputIsCollection && committed.inputCollection !== queryFnOrCollection) ||
     dependenciesChanged
   const pageShapeChanged =
-    pageSizeRef.current !== pageSize ||
-    initialPageParamRef.current !== initialPageParam
+    committed === null ||
+    committed.pageSize !== pageSize ||
+    committed.initialPageParam !== initialPageParam
   const needsNewController =
-    !controllerRef.current || needsNewCollection || pageShapeChanged
+    committed === null || needsNewCollection || pageShapeChanged
 
-  if (needsNewCollection) {
-    inputKindRef.current = inputKind
-    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.`,
-        )
-      }
-      // 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.`,
-          )
-        }
+  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,
+        })
       }
-      collectionRef.current = collection
-      configRef.current = queryFnOrCollection
+    }
+
+    if (!collection) {
+      throw new Error(`useLiveInfiniteQuery: Failed to create a collection.`)
+    }
+
+    if (inputIsCollection) {
+      warning =
+        getLiveQueryWindowCollectionWarning(collection, pageSize + 1) ?? null
     } else {
-      // 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]
+      assertLiveQueryWindowManyResult(collection)
     }
-  }
 
-  if (needsNewController) {
-    const previousController = controllerRef.current
-    const canPreservePageCount =
-      previousController !== null &&
-      (!needsNewCollection ||
-        (previousInputKind === `query` && dependenciesStructurallyEqual))
-    const initialPageCount = canPreservePageCount
-      ? Math.max(1, previousController.getSnapshot().pages.length)
+    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
-    pageSizeRef.current = pageSize
-    initialPageParamRef.current = initialPageParam
-    controllerRef.current = createLiveQueryWindowController(
-      collectionRef.current,
-      {
+    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,
+    }
   }
-  const controller = controllerRef.current!
+  const currentRenderState = renderState!
+  const controller = currentRenderState.controller
 
   const subscribe = useCallback(
-    (onStoreChange: () => void) => controller.subscribe(onStoreChange),
-    [controller],
+    (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(() => {
-    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])
+  const fetchNextPage = useCallback(
+    () => fetchNextLiveQueryWindowPage(controller),
+    [controller],
+  )
 
   return {
     data: snapshot.data as InferResultType<TContext>,