@tanstack/react-db 0.1.31 → 0.1.33

package/dist/cjs/index.cjs

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const useLiveQuery = require("./useLiveQuery.cjs");
+const useLiveInfiniteQuery = require("./useLiveInfiniteQuery.cjs");
 const db = require("@tanstack/db");
 exports.useLiveQuery = useLiveQuery.useLiveQuery;
+exports.useLiveInfiniteQuery = useLiveInfiniteQuery.useLiveInfiniteQuery;
 Object.defineProperty(exports, "createTransaction", {
   enumerable: true,
   get: () => db.createTransaction

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.cjs';
+export * from './useLiveInfiniteQuery.cjs';
 export * from '@tanstack/db';
 export type { Collection } from '@tanstack/db';
 export { createTransaction } from '@tanstack/db';

package/dist/cjs/useLiveInfiniteQuery.cjs

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const db = require("@tanstack/db");
+const useLiveQuery = require("./useLiveQuery.cjs");
+function isLiveQueryCollectionUtils(utils) {
+  return typeof utils.setWindow === `function`;
+}
+function useLiveInfiniteQuery(queryFnOrCollection, config, deps = []) {
+  const pageSize = config.pageSize || 20;
+  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 [loadedPageCount, setLoadedPageCount] = react.useState(1);
+  const [isFetchingNextPage, setIsFetchingNextPage] = react.useState(false);
+  const collectionRef = react.useRef(isCollection ? queryFnOrCollection : null);
+  const hasValidatedCollectionRef = react.useRef(false);
+  const depsKey = JSON.stringify(deps);
+  const prevDepsKeyRef = react.useRef(depsKey);
+  react.useEffect(() => {
+    let shouldReset = false;
+    if (isCollection) {
+      if (collectionRef.current !== queryFnOrCollection) {
+        collectionRef.current = queryFnOrCollection;
+        hasValidatedCollectionRef.current = false;
+        shouldReset = true;
+      }
+    } else {
+      if (prevDepsKeyRef.current !== depsKey) {
+        prevDepsKeyRef.current = depsKey;
+        shouldReset = true;
+      }
+    }
+    if (shouldReset) {
+      setLoadedPageCount(1);
+    }
+  }, [isCollection, queryFnOrCollection, depsKey]);
+  const queryResult = isCollection ? useLiveQuery.useLiveQuery(queryFnOrCollection) : useLiveQuery.useLiveQuery(
+    (q) => queryFnOrCollection(q).limit(pageSize).offset(0),
+    deps
+  );
+  react.useEffect(() => {
+    const utils = queryResult.collection.utils;
+    const expectedOffset = 0;
+    const expectedLimit = loadedPageCount * pageSize + 1;
+    if (!isLiveQueryCollectionUtils(utils)) {
+      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.`
+        );
+      }
+      return;
+    }
+    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 (!isCollection && !queryResult.isReady) return;
+    const result = utils.setWindow({
+      offset: expectedOffset,
+      limit: expectedLimit
+    });
+    if (result !== true) {
+      setIsFetchingNextPage(true);
+      result.then(() => {
+        setIsFetchingNextPage(false);
+      });
+    } else {
+      setIsFetchingNextPage(false);
+    }
+  }, [
+    isCollection,
+    queryResult.collection,
+    queryResult.isReady,
+    loadedPageCount,
+    pageSize
+  ]);
+  const { pages, pageParams, hasNextPage, flatData } = react.useMemo(() => {
+    const dataArray = Array.isArray(queryResult.data) ? queryResult.data : [];
+    const totalItemsRequested = loadedPageCount * pageSize;
+    const hasMore = dataArray.length > totalItemsRequested;
+    const pagesResult = [];
+    const pageParamsResult = [];
+    for (let i = 0; i < loadedPageCount; i++) {
+      const pageData = dataArray.slice(i * pageSize, (i + 1) * pageSize);
+      pagesResult.push(pageData);
+      pageParamsResult.push(initialPageParam + i);
+    }
+    const flatDataResult = dataArray.slice(
+      0,
+      totalItemsRequested
+    );
+    return {
+      pages: pagesResult,
+      pageParams: pageParamsResult,
+      hasNextPage: hasMore,
+      flatData: flatDataResult
+    };
+  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam]);
+  const fetchNextPage = react.useCallback(() => {
+    if (!hasNextPage || isFetchingNextPage) return;
+    setLoadedPageCount((prev) => prev + 1);
+  }, [hasNextPage, isFetchingNextPage]);
+  return {
+    ...queryResult,
+    data: flatData,
+    pages,
+    pageParams,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage
+  };
+}
+exports.useLiveInfiniteQuery = useLiveInfiniteQuery;
+//# sourceMappingURL=useLiveInfiniteQuery.cjs.map

package/dist/cjs/useLiveInfiniteQuery.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveInfiniteQuery.cjs","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\"\nimport { CollectionImpl } from \"@tanstack/db\"\nimport { useLiveQuery } from \"./useLiveQuery\"\nimport type {\n  Collection,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionUtils,\n  NonSingleResult,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\n/**\n * Type guard to check if utils object has setWindow method (LiveQueryCollectionUtils)\n */\nfunction isLiveQueryCollectionUtils(\n  utils: unknown\n): utils is LiveQueryCollectionUtils {\n  return typeof (utils as any).setWindow === `function`\n}\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  pageSize?: number\n  initialPageParam?: number\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}\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  // Track how many pages have been loaded\n  const [loadedPageCount, setLoadedPageCount] = useState(1)\n  const [isFetchingNextPage, setIsFetchingNextPage] = useState(false)\n\n  // Track collection instance and whether we've validated it (only for pre-created collections)\n  const collectionRef = useRef(isCollection ? queryFnOrCollection : null)\n  const hasValidatedCollectionRef = useRef(false)\n\n  // Track deps for query functions (stringify for comparison)\n  const depsKey = JSON.stringify(deps)\n  const prevDepsKeyRef = useRef(depsKey)\n\n  // Reset pagination when inputs change\n  useEffect(() => {\n    let shouldReset = false\n\n    if (isCollection) {\n      // Reset if collection instance changed\n      if (collectionRef.current !== queryFnOrCollection) {\n        collectionRef.current = queryFnOrCollection\n        hasValidatedCollectionRef.current = false\n        shouldReset = true\n      }\n    } else {\n      // Reset if deps changed (for query functions)\n      if (prevDepsKeyRef.current !== depsKey) {\n        prevDepsKeyRef.current = depsKey\n        shouldReset = true\n      }\n    }\n\n    if (shouldReset) {\n      setLoadedPageCount(1)\n    }\n  }, [isCollection, queryFnOrCollection, depsKey])\n\n  // Create a live query with initial limit and offset\n  // Either pass collection directly or wrap query function\n  const queryResult = isCollection\n    ? useLiveQuery(queryFnOrCollection)\n    : useLiveQuery(\n        (q) => queryFnOrCollection(q).limit(pageSize).offset(0),\n        deps\n      )\n\n  // Adjust window when pagination changes\n  useEffect(() => {\n    const utils = queryResult.collection.utils\n    const expectedOffset = 0\n    const expectedLimit = loadedPageCount * pageSize + 1 // +1 for peek ahead\n\n    // Check if collection has orderBy (required for setWindow)\n    if (!isLiveQueryCollectionUtils(utils)) {\n      // For pre-created collections, throw an error if no orderBy\n      if (isCollection) {\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      return\n    }\n\n    // For pre-created collections, validate window on first check\n    if (isCollection && !hasValidatedCollectionRef.current) {\n      const currentWindow = utils.getWindow()\n      if (\n        currentWindow &&\n        (currentWindow.offset !== expectedOffset ||\n          currentWindow.limit !== expectedLimit)\n      ) {\n        console.warn(\n          `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +\n            `but hook expects {offset: ${expectedOffset}, limit: ${expectedLimit}}. Adjusting window now.`\n        )\n      }\n      hasValidatedCollectionRef.current = true\n    }\n\n    // For query functions, wait until collection is ready\n    if (!isCollection && !queryResult.isReady) return\n\n    // Adjust the window\n    const result = utils.setWindow({\n      offset: expectedOffset,\n      limit: expectedLimit,\n    })\n\n    if (result !== true) {\n      setIsFetchingNextPage(true)\n      result.then(() => {\n        setIsFetchingNextPage(false)\n      })\n    } else {\n      setIsFetchingNextPage(false)\n    }\n  }, [\n    isCollection,\n    queryResult.collection,\n    queryResult.isReady,\n    loadedPageCount,\n    pageSize,\n  ])\n\n  // Split the data array into pages and determine if there's a next page\n  const { pages, pageParams, hasNextPage, flatData } = useMemo(() => {\n    const dataArray = (\n      Array.isArray(queryResult.data) ? queryResult.data : []\n    ) as InferResultType<TContext>\n    const totalItemsRequested = loadedPageCount * pageSize\n\n    // Check if we have more data than requested (the peek ahead item)\n    const hasMore = dataArray.length > totalItemsRequested\n\n    // Build pages array (without the peek ahead item)\n    const pagesResult: Array<Array<InferResultType<TContext>[number]>> = []\n    const pageParamsResult: Array<number> = []\n\n    for (let i = 0; i < loadedPageCount; i++) {\n      const pageData = dataArray.slice(i * pageSize, (i + 1) * pageSize)\n      pagesResult.push(pageData)\n      pageParamsResult.push(initialPageParam + i)\n    }\n\n    // Flatten the pages for the data return (without peek ahead item)\n    const flatDataResult = dataArray.slice(\n      0,\n      totalItemsRequested\n    ) as InferResultType<TContext>\n\n    return {\n      pages: pagesResult,\n      pageParams: pageParamsResult,\n      hasNextPage: hasMore,\n      flatData: flatDataResult,\n    }\n  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam])\n\n  // Fetch next page\n  const fetchNextPage = useCallback(() => {\n    if (!hasNextPage || isFetchingNextPage) return\n\n    setLoadedPageCount((prev) => prev + 1)\n  }, [hasNextPage, isFetchingNextPage])\n\n  return {\n    ...queryResult,\n    data: flatData,\n    pages,\n    pageParams,\n    fetchNextPage,\n    hasNextPage,\n    isFetchingNextPage,\n  } as UseLiveInfiniteQueryReturn<TContext>\n}\n"],"names":["CollectionImpl","useState","useRef","useEffect","useLiveQuery","useMemo","useCallback"],"mappings":"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"}

package/dist/cjs/useLiveInfiniteQuery.d.cts

@@ -0,0 +1,82 @@
+import { useLiveQuery } from './useLiveQuery.cjs';
+import { Collection, Context, InferResultType, InitialQueryBuilder, NonSingleResult, QueryBuilder } from '@tanstack/db';
+export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
+    pageSize?: number;
+    initialPageParam?: number;
+    getNextPageParam: (lastPage: Array<InferResultType<TContext>[number]>, allPages: Array<Array<InferResultType<TContext>[number]>>, lastPageParam: number, allPageParams: Array<number>) => number | undefined;
+};
+export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<ReturnType<typeof useLiveQuery<TContext>>, `data`> & {
+    data: InferResultType<TContext>;
+    pages: Array<Array<InferResultType<TContext>[number]>>;
+    pageParams: Array<number>;
+    fetchNextPage: () => void;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+};
+/**
+ * Create an infinite query using a query function with live updates
+ *
+ * Uses `utils.setWindow()` to dynamically adjust the limit/offset window
+ * without recreating the live query collection on each page change.
+ *
+ * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.
+ * @param config - Configuration including pageSize and getNextPageParam
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with pages, data, and pagination controls
+ *
+ * @example
+ * // Basic infinite query
+ * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   (q) => q
+ *     .from({ posts: postsCollection })
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc')
+ *     .select(({ posts }) => ({
+ *       id: posts.id,
+ *       title: posts.title
+ *     })),
+ *   {
+ *     pageSize: 20,
+ *     getNextPageParam: (lastPage, allPages) =>
+ *       lastPage.length === 20 ? allPages.length : undefined
+ *   }
+ * )
+ *
+ * @example
+ * // With dependencies
+ * const { pages, fetchNextPage } = useLiveInfiniteQuery(
+ *   (q) => q
+ *     .from({ posts: postsCollection })
+ *     .where(({ posts }) => eq(posts.category, category))
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc'),
+ *   {
+ *     pageSize: 10,
+ *     getNextPageParam: (lastPage) =>
+ *       lastPage.length === 10 ? lastPage.length : undefined
+ *   },
+ *   [category]
+ * )
+ *
+ * @example
+ * // Router loader pattern with pre-created collection
+ * // In loader:
+ * const postsQuery = createLiveQueryCollection({
+ *   query: (q) => q
+ *     .from({ posts: postsCollection })
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc')
+ *     .limit(20)
+ * })
+ * await postsQuery.preload()
+ * return { postsQuery }
+ *
+ * // In component:
+ * const { postsQuery } = useLoaderData()
+ * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   postsQuery,
+ *   {
+ *     pageSize: 20,
+ *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined
+ *   }
+ * )
+ */
+export declare function useLiveInfiniteQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult, config: UseLiveInfiniteQueryConfig<any>): UseLiveInfiniteQueryReturn<any>;
+export declare function useLiveInfiniteQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, config: UseLiveInfiniteQueryConfig<TContext>, deps?: Array<unknown>): UseLiveInfiniteQueryReturn<TContext>;

package/dist/esm/index.d.ts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.js';
+export * from './useLiveInfiniteQuery.js';
 export * from '@tanstack/db';
 export type { Collection } from '@tanstack/db';
 export { createTransaction } from '@tanstack/db';

package/dist/esm/index.js

@@ -1,8 +1,10 @@
 import { useLiveQuery } from "./useLiveQuery.js";
+import { useLiveInfiniteQuery } from "./useLiveInfiniteQuery.js";
 export * from "@tanstack/db";
 import { createTransaction } from "@tanstack/db";
 export {
   createTransaction,
+  useLiveInfiniteQuery,
   useLiveQuery
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/esm/useLiveInfiniteQuery.d.ts

@@ -0,0 +1,82 @@
+import { useLiveQuery } from './useLiveQuery.js';
+import { Collection, Context, InferResultType, InitialQueryBuilder, NonSingleResult, QueryBuilder } from '@tanstack/db';
+export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
+    pageSize?: number;
+    initialPageParam?: number;
+    getNextPageParam: (lastPage: Array<InferResultType<TContext>[number]>, allPages: Array<Array<InferResultType<TContext>[number]>>, lastPageParam: number, allPageParams: Array<number>) => number | undefined;
+};
+export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<ReturnType<typeof useLiveQuery<TContext>>, `data`> & {
+    data: InferResultType<TContext>;
+    pages: Array<Array<InferResultType<TContext>[number]>>;
+    pageParams: Array<number>;
+    fetchNextPage: () => void;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+};
+/**
+ * Create an infinite query using a query function with live updates
+ *
+ * Uses `utils.setWindow()` to dynamically adjust the limit/offset window
+ * without recreating the live query collection on each page change.
+ *
+ * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.
+ * @param config - Configuration including pageSize and getNextPageParam
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with pages, data, and pagination controls
+ *
+ * @example
+ * // Basic infinite query
+ * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   (q) => q
+ *     .from({ posts: postsCollection })
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc')
+ *     .select(({ posts }) => ({
+ *       id: posts.id,
+ *       title: posts.title
+ *     })),
+ *   {
+ *     pageSize: 20,
+ *     getNextPageParam: (lastPage, allPages) =>
+ *       lastPage.length === 20 ? allPages.length : undefined
+ *   }
+ * )
+ *
+ * @example
+ * // With dependencies
+ * const { pages, fetchNextPage } = useLiveInfiniteQuery(
+ *   (q) => q
+ *     .from({ posts: postsCollection })
+ *     .where(({ posts }) => eq(posts.category, category))
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc'),
+ *   {
+ *     pageSize: 10,
+ *     getNextPageParam: (lastPage) =>
+ *       lastPage.length === 10 ? lastPage.length : undefined
+ *   },
+ *   [category]
+ * )
+ *
+ * @example
+ * // Router loader pattern with pre-created collection
+ * // In loader:
+ * const postsQuery = createLiveQueryCollection({
+ *   query: (q) => q
+ *     .from({ posts: postsCollection })
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc')
+ *     .limit(20)
+ * })
+ * await postsQuery.preload()
+ * return { postsQuery }
+ *
+ * // In component:
+ * const { postsQuery } = useLoaderData()
+ * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   postsQuery,
+ *   {
+ *     pageSize: 20,
+ *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined
+ *   }
+ * )
+ */
+export declare function useLiveInfiniteQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult, config: UseLiveInfiniteQueryConfig<any>): UseLiveInfiniteQueryReturn<any>;
+export declare function useLiveInfiniteQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, config: UseLiveInfiniteQueryConfig<TContext>, deps?: Array<unknown>): UseLiveInfiniteQueryReturn<TContext>;

package/dist/esm/useLiveInfiniteQuery.js

@@ -0,0 +1,124 @@
+import { useState, useRef, useEffect, useMemo, useCallback } from "react";
+import { CollectionImpl } from "@tanstack/db";
+import { useLiveQuery } from "./useLiveQuery.js";
+function isLiveQueryCollectionUtils(utils) {
+  return typeof utils.setWindow === `function`;
+}
+function useLiveInfiniteQuery(queryFnOrCollection, config, deps = []) {
+  const pageSize = config.pageSize || 20;
+  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 [loadedPageCount, setLoadedPageCount] = useState(1);
+  const [isFetchingNextPage, setIsFetchingNextPage] = useState(false);
+  const collectionRef = useRef(isCollection ? queryFnOrCollection : null);
+  const hasValidatedCollectionRef = useRef(false);
+  const depsKey = JSON.stringify(deps);
+  const prevDepsKeyRef = useRef(depsKey);
+  useEffect(() => {
+    let shouldReset = false;
+    if (isCollection) {
+      if (collectionRef.current !== queryFnOrCollection) {
+        collectionRef.current = queryFnOrCollection;
+        hasValidatedCollectionRef.current = false;
+        shouldReset = true;
+      }
+    } else {
+      if (prevDepsKeyRef.current !== depsKey) {
+        prevDepsKeyRef.current = depsKey;
+        shouldReset = true;
+      }
+    }
+    if (shouldReset) {
+      setLoadedPageCount(1);
+    }
+  }, [isCollection, queryFnOrCollection, depsKey]);
+  const queryResult = isCollection ? useLiveQuery(queryFnOrCollection) : useLiveQuery(
+    (q) => queryFnOrCollection(q).limit(pageSize).offset(0),
+    deps
+  );
+  useEffect(() => {
+    const utils = queryResult.collection.utils;
+    const expectedOffset = 0;
+    const expectedLimit = loadedPageCount * pageSize + 1;
+    if (!isLiveQueryCollectionUtils(utils)) {
+      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.`
+        );
+      }
+      return;
+    }
+    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 (!isCollection && !queryResult.isReady) return;
+    const result = utils.setWindow({
+      offset: expectedOffset,
+      limit: expectedLimit
+    });
+    if (result !== true) {
+      setIsFetchingNextPage(true);
+      result.then(() => {
+        setIsFetchingNextPage(false);
+      });
+    } else {
+      setIsFetchingNextPage(false);
+    }
+  }, [
+    isCollection,
+    queryResult.collection,
+    queryResult.isReady,
+    loadedPageCount,
+    pageSize
+  ]);
+  const { pages, pageParams, hasNextPage, flatData } = useMemo(() => {
+    const dataArray = Array.isArray(queryResult.data) ? queryResult.data : [];
+    const totalItemsRequested = loadedPageCount * pageSize;
+    const hasMore = dataArray.length > totalItemsRequested;
+    const pagesResult = [];
+    const pageParamsResult = [];
+    for (let i = 0; i < loadedPageCount; i++) {
+      const pageData = dataArray.slice(i * pageSize, (i + 1) * pageSize);
+      pagesResult.push(pageData);
+      pageParamsResult.push(initialPageParam + i);
+    }
+    const flatDataResult = dataArray.slice(
+      0,
+      totalItemsRequested
+    );
+    return {
+      pages: pagesResult,
+      pageParams: pageParamsResult,
+      hasNextPage: hasMore,
+      flatData: flatDataResult
+    };
+  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam]);
+  const fetchNextPage = useCallback(() => {
+    if (!hasNextPage || isFetchingNextPage) return;
+    setLoadedPageCount((prev) => prev + 1);
+  }, [hasNextPage, isFetchingNextPage]);
+  return {
+    ...queryResult,
+    data: flatData,
+    pages,
+    pageParams,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage
+  };
+}
+export {
+  useLiveInfiniteQuery
+};
+//# sourceMappingURL=useLiveInfiniteQuery.js.map

package/dist/esm/useLiveInfiniteQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveInfiniteQuery.js","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\"\nimport { CollectionImpl } from \"@tanstack/db\"\nimport { useLiveQuery } from \"./useLiveQuery\"\nimport type {\n  Collection,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionUtils,\n  NonSingleResult,\n  QueryBuilder,\n} from \"@tanstack/db\"\n\n/**\n * Type guard to check if utils object has setWindow method (LiveQueryCollectionUtils)\n */\nfunction isLiveQueryCollectionUtils(\n  utils: unknown\n): utils is LiveQueryCollectionUtils {\n  return typeof (utils as any).setWindow === `function`\n}\n\nexport type UseLiveInfiniteQueryConfig<TContext extends Context> = {\n  pageSize?: number\n  initialPageParam?: number\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}\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  // Track how many pages have been loaded\n  const [loadedPageCount, setLoadedPageCount] = useState(1)\n  const [isFetchingNextPage, setIsFetchingNextPage] = useState(false)\n\n  // Track collection instance and whether we've validated it (only for pre-created collections)\n  const collectionRef = useRef(isCollection ? queryFnOrCollection : null)\n  const hasValidatedCollectionRef = useRef(false)\n\n  // Track deps for query functions (stringify for comparison)\n  const depsKey = JSON.stringify(deps)\n  const prevDepsKeyRef = useRef(depsKey)\n\n  // Reset pagination when inputs change\n  useEffect(() => {\n    let shouldReset = false\n\n    if (isCollection) {\n      // Reset if collection instance changed\n      if (collectionRef.current !== queryFnOrCollection) {\n        collectionRef.current = queryFnOrCollection\n        hasValidatedCollectionRef.current = false\n        shouldReset = true\n      }\n    } else {\n      // Reset if deps changed (for query functions)\n      if (prevDepsKeyRef.current !== depsKey) {\n        prevDepsKeyRef.current = depsKey\n        shouldReset = true\n      }\n    }\n\n    if (shouldReset) {\n      setLoadedPageCount(1)\n    }\n  }, [isCollection, queryFnOrCollection, depsKey])\n\n  // Create a live query with initial limit and offset\n  // Either pass collection directly or wrap query function\n  const queryResult = isCollection\n    ? useLiveQuery(queryFnOrCollection)\n    : useLiveQuery(\n        (q) => queryFnOrCollection(q).limit(pageSize).offset(0),\n        deps\n      )\n\n  // Adjust window when pagination changes\n  useEffect(() => {\n    const utils = queryResult.collection.utils\n    const expectedOffset = 0\n    const expectedLimit = loadedPageCount * pageSize + 1 // +1 for peek ahead\n\n    // Check if collection has orderBy (required for setWindow)\n    if (!isLiveQueryCollectionUtils(utils)) {\n      // For pre-created collections, throw an error if no orderBy\n      if (isCollection) {\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      return\n    }\n\n    // For pre-created collections, validate window on first check\n    if (isCollection && !hasValidatedCollectionRef.current) {\n      const currentWindow = utils.getWindow()\n      if (\n        currentWindow &&\n        (currentWindow.offset !== expectedOffset ||\n          currentWindow.limit !== expectedLimit)\n      ) {\n        console.warn(\n          `useLiveInfiniteQuery: Pre-created collection has window {offset: ${currentWindow.offset}, limit: ${currentWindow.limit}} ` +\n            `but hook expects {offset: ${expectedOffset}, limit: ${expectedLimit}}. Adjusting window now.`\n        )\n      }\n      hasValidatedCollectionRef.current = true\n    }\n\n    // For query functions, wait until collection is ready\n    if (!isCollection && !queryResult.isReady) return\n\n    // Adjust the window\n    const result = utils.setWindow({\n      offset: expectedOffset,\n      limit: expectedLimit,\n    })\n\n    if (result !== true) {\n      setIsFetchingNextPage(true)\n      result.then(() => {\n        setIsFetchingNextPage(false)\n      })\n    } else {\n      setIsFetchingNextPage(false)\n    }\n  }, [\n    isCollection,\n    queryResult.collection,\n    queryResult.isReady,\n    loadedPageCount,\n    pageSize,\n  ])\n\n  // Split the data array into pages and determine if there's a next page\n  const { pages, pageParams, hasNextPage, flatData } = useMemo(() => {\n    const dataArray = (\n      Array.isArray(queryResult.data) ? queryResult.data : []\n    ) as InferResultType<TContext>\n    const totalItemsRequested = loadedPageCount * pageSize\n\n    // Check if we have more data than requested (the peek ahead item)\n    const hasMore = dataArray.length > totalItemsRequested\n\n    // Build pages array (without the peek ahead item)\n    const pagesResult: Array<Array<InferResultType<TContext>[number]>> = []\n    const pageParamsResult: Array<number> = []\n\n    for (let i = 0; i < loadedPageCount; i++) {\n      const pageData = dataArray.slice(i * pageSize, (i + 1) * pageSize)\n      pagesResult.push(pageData)\n      pageParamsResult.push(initialPageParam + i)\n    }\n\n    // Flatten the pages for the data return (without peek ahead item)\n    const flatDataResult = dataArray.slice(\n      0,\n      totalItemsRequested\n    ) as InferResultType<TContext>\n\n    return {\n      pages: pagesResult,\n      pageParams: pageParamsResult,\n      hasNextPage: hasMore,\n      flatData: flatDataResult,\n    }\n  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam])\n\n  // Fetch next page\n  const fetchNextPage = useCallback(() => {\n    if (!hasNextPage || isFetchingNextPage) return\n\n    setLoadedPageCount((prev) => prev + 1)\n  }, [hasNextPage, isFetchingNextPage])\n\n  return {\n    ...queryResult,\n    data: flatData,\n    pages,\n    pageParams,\n    fetchNextPage,\n    hasNextPage,\n    isFetchingNextPage,\n  } as UseLiveInfiniteQueryReturn<TContext>\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/react-db",
   "description": "React integration for @tanstack/db",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "author": "Kyle Mathews",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@tanstack/db": "0.4.9"
+    "@tanstack/db": "0.4.11"
   },
   "devDependencies": {
     "@electric-sql/client": "1.0.14",

package/src/index.ts

@@ -1,5 +1,6 @@
 // Re-export all public APIs
 export * from "./useLiveQuery"
+export * from "./useLiveInfiniteQuery"
 
 // Re-export everything from @tanstack/db
 export * from "@tanstack/db"

package/src/useLiveInfiniteQuery.ts

@@ -0,0 +1,303 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { CollectionImpl } from "@tanstack/db"
+import { useLiveQuery } from "./useLiveQuery"
+import type {
+  Collection,
+  Context,
+  InferResultType,
+  InitialQueryBuilder,
+  LiveQueryCollectionUtils,
+  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`
+}
+
+export type UseLiveInfiniteQueryConfig<TContext extends Context> = {
+  pageSize?: number
+  initialPageParam?: number
+  getNextPageParam: (
+    lastPage: Array<InferResultType<TContext>[number]>,
+    allPages: Array<Array<InferResultType<TContext>[number]>>,
+    lastPageParam: number,
+    allPageParams: Array<number>
+  ) => number | undefined
+}
+
+export type UseLiveInfiniteQueryReturn<TContext extends Context> = Omit<
+  ReturnType<typeof useLiveQuery<TContext>>,
+  `data`
+> & {
+  data: InferResultType<TContext>
+  pages: Array<Array<InferResultType<TContext>[number]>>
+  pageParams: Array<number>
+  fetchNextPage: () => void
+  hasNextPage: boolean
+  isFetchingNextPage: boolean
+}
+
+/**
+ * Create an infinite query using a query function with live updates
+ *
+ * Uses `utils.setWindow()` to dynamically adjust the limit/offset window
+ * without recreating the live query collection on each page change.
+ *
+ * @param queryFn - Query function that defines what data to fetch. Must include `.orderBy()` for setWindow to work.
+ * @param config - Configuration including pageSize and getNextPageParam
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with pages, data, and pagination controls
+ *
+ * @example
+ * // Basic infinite query
+ * const { data, pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   (q) => q
+ *     .from({ posts: postsCollection })
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc')
+ *     .select(({ posts }) => ({
+ *       id: posts.id,
+ *       title: posts.title
+ *     })),
+ *   {
+ *     pageSize: 20,
+ *     getNextPageParam: (lastPage, allPages) =>
+ *       lastPage.length === 20 ? allPages.length : undefined
+ *   }
+ * )
+ *
+ * @example
+ * // With dependencies
+ * const { pages, fetchNextPage } = useLiveInfiniteQuery(
+ *   (q) => q
+ *     .from({ posts: postsCollection })
+ *     .where(({ posts }) => eq(posts.category, category))
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc'),
+ *   {
+ *     pageSize: 10,
+ *     getNextPageParam: (lastPage) =>
+ *       lastPage.length === 10 ? lastPage.length : undefined
+ *   },
+ *   [category]
+ * )
+ *
+ * @example
+ * // Router loader pattern with pre-created collection
+ * // In loader:
+ * const postsQuery = createLiveQueryCollection({
+ *   query: (q) => q
+ *     .from({ posts: postsCollection })
+ *     .orderBy(({ posts }) => posts.createdAt, 'desc')
+ *     .limit(20)
+ * })
+ * await postsQuery.preload()
+ * return { postsQuery }
+ *
+ * // In component:
+ * const { postsQuery } = useLoaderData()
+ * const { data, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   postsQuery,
+ *   {
+ *     pageSize: 20,
+ *     getNextPageParam: (lastPage) => lastPage.length === 20 ? lastPage.length : undefined
+ *   }
+ * )
+ */
+
+// Overload for pre-created collection (non-single result)
+export function useLiveInfiniteQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
+  config: UseLiveInfiniteQueryConfig<any>
+): UseLiveInfiniteQueryReturn<any>
+
+// Overload for query function
+export function useLiveInfiniteQuery<TContext extends Context>(
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
+  config: UseLiveInfiniteQueryConfig<TContext>,
+  deps?: Array<unknown>
+): UseLiveInfiniteQueryReturn<TContext>
+
+// Implementation
+export function useLiveInfiniteQuery<TContext extends Context>(
+  queryFnOrCollection: any,
+  config: UseLiveInfiniteQueryConfig<TContext>,
+  deps: Array<unknown> = []
+): UseLiveInfiniteQueryReturn<TContext> {
+  const pageSize = config.pageSize || 20
+  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)
+  const depsKey = JSON.stringify(deps)
+  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
+  const queryResult = isCollection
+    ? useLiveQuery(queryFnOrCollection)
+    : useLiveQuery(
+        (q) => queryFnOrCollection(q).limit(pageSize).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.`
+        )
+      }
+      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
+    }
+
+    // For query functions, wait until collection is ready
+    if (!isCollection && !queryResult.isReady) return
+
+    // Adjust the window
+    const result = utils.setWindow({
+      offset: expectedOffset,
+      limit: expectedLimit,
+    })
+
+    if (result !== true) {
+      setIsFetchingNextPage(true)
+      result.then(() => {
+        setIsFetchingNextPage(false)
+      })
+    } else {
+      setIsFetchingNextPage(false)
+    }
+  }, [
+    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)
+    }
+
+    // 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,
+    }
+  }, [queryResult.data, loadedPageCount, pageSize, initialPageParam])
+
+  // Fetch next page
+  const fetchNextPage = useCallback(() => {
+    if (!hasNextPage || isFetchingNextPage) return
+
+    setLoadedPageCount((prev) => prev + 1)
+  }, [hasNextPage, isFetchingNextPage])
+
+  return {
+    ...queryResult,
+    data: flatData,
+    pages,
+    pageParams,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+  } as UseLiveInfiniteQueryReturn<TContext>
+}