Fix native Convex pagination in infinite queries

.changeset/calm-pages-wait.md

@@ -0,0 +1,8 @@
+---
+"kitcn": patch
+---
+
+## Patches
+
+- Fix cRPC infinite queries backed by native Convex pagination loading pages
+  before `fetchNextPage()` is called.

fixtures/next-auth/package.json

@@ -9,7 +9,7 @@
     "convex": "1.38.0",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.26.0",
     "next": "16.2.6",
     "next-themes": "^0.4.6",
     "react": "19.2.4",

fixtures/next/package.json

@@ -8,7 +8,7 @@
     "convex": "1.38.0",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.26.0",
     "next": "16.2.6",
     "next-themes": "^0.4.6",
     "react": "19.2.4",

fixtures/start-auth/package.json

@@ -17,7 +17,7 @@
     "convex": "1.38.0",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.26.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

fixtures/start/package.json

@@ -16,7 +16,7 @@
     "convex": "1.38.0",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.26.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

fixtures/vite-auth/package.json

@@ -11,7 +11,7 @@
     "convex": "1.38.0",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.26.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

fixtures/vite/package.json

@@ -10,7 +10,7 @@
     "convex": "1.38.0",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.26.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

packages/kitcn/src/internal/pagination.ts

@@ -0,0 +1,14 @@
+import type { PaginationResult } from 'convex/server';
+
+type SplitPaginationResult<T> = PaginationResult<T> & {
+  splitCursor: string;
+};
+
+export const shouldSplitPaginationPage = <T>(
+  page: PaginationResult<T>,
+  initialNumItems?: number
+): page is SplitPaginationResult<T> =>
+  Boolean(page.splitCursor) &&
+  (page.pageStatus === 'SplitRecommended' ||
+    page.pageStatus === 'SplitRequired' ||
+    (initialNumItems !== undefined && page.page.length > initialNumItems * 2));

packages/kitcn/src/react/use-infinite-query.test.tsx

@@ -174,6 +174,87 @@ describe('useInfiniteQuery', () => {
     expect((firstCall.queries[0] as any).enabled).toBe(true);
   });
 
+  test('does not split a native Convex page solely because it has a split cursor', () => {
+    const queryClient = new QueryClient();
+    const wrapper = makeWrapper(queryClient);
+    const firstPage = {
+      page: [{ _id: 'post-1' }, { _id: 'post-2' }, { _id: 'post-3' }],
+      isDone: false,
+      continueCursor: 'cursor-3',
+      splitCursor: 'cursor-2',
+    };
+    const secondPage = {
+      page: [{ _id: 'post-4' }, { _id: 'post-5' }, { _id: 'post-6' }],
+      isDone: true,
+      continueCursor: 'cursor-6',
+    };
+
+    useQueriesSpy.mockImplementation((arg: UseQueriesArg) => {
+      useQueriesCalls.push(arg);
+      return (arg as any).combine(
+        [firstPage, secondPage]
+          .slice(0, arg.queries.length)
+          .map((data, index) => ({
+            data,
+            dataUpdatedAt: index + 1,
+            isError: false,
+            isFetching: false,
+            isLoading: false,
+            isPlaceholderData: false,
+          }))
+      );
+    });
+
+    const options = createOptions({ limit: 3 });
+    const { result } = renderHook(() => useInfiniteQuery(options), { wrapper });
+
+    expect(result.current.data).toEqual(firstPage.page);
+    expect(result.current.hasNextPage).toBe(true);
+    expect(useQueriesCalls.at(-1)?.queries).toHaveLength(1);
+
+    act(() => {
+      result.current.fetchNextPage();
+    });
+
+    expect(result.current.data).toEqual([
+      ...firstPage.page,
+      ...secondPage.page,
+    ]);
+    expect(result.current.hasNextPage).toBe(false);
+    expect(useQueriesCalls.at(-1)?.queries).toHaveLength(2);
+  });
+
+  test('splits a page when Convex recommends it', () => {
+    const queryClient = new QueryClient();
+    const wrapper = makeWrapper(queryClient);
+    const firstPage = {
+      page: [{ _id: 'post-1' }, { _id: 'post-2' }, { _id: 'post-3' }],
+      isDone: false,
+      continueCursor: 'cursor-3',
+      splitCursor: 'cursor-2',
+      pageStatus: 'SplitRecommended',
+    };
+
+    useQueriesSpy.mockImplementation((arg: UseQueriesArg) => {
+      useQueriesCalls.push(arg);
+      return (arg as any).combine([
+        {
+          data: firstPage,
+          dataUpdatedAt: 1,
+          isError: false,
+          isFetching: false,
+          isLoading: false,
+          isPlaceholderData: false,
+        },
+      ]);
+    });
+
+    const options = createOptions({ limit: 3 });
+    renderHook(() => useInfiniteQuery(options), { wrapper });
+
+    expect(useQueriesCalls.at(-1)?.queries).toHaveLength(2);
+  });
+
   test('fetchNextPage adds a new page query with continueCursor and limit', () => {
     const queryClient = new QueryClient();
     const wrapper = makeWrapper(queryClient);

packages/kitcn/src/react/use-infinite-query.ts

@@ -23,6 +23,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { CRPCClientError, isCRPCClientError } from '../crpc/error';
 import { convexQuery } from '../crpc/query-options';
 import { type ExtractPaginatedItem, FUNC_REF_SYMBOL } from '../crpc/types';
+import { shouldSplitPaginationPage } from '../internal/pagination';
 import type { DistributiveOmit } from '../internal/types';
 import { useAuthValue, useSafeConvexAuth } from './auth-store';
 import { useMeta } from './context';
@@ -134,13 +135,6 @@ type PageState = {
   endCursor?: string | null; // For page splitting - the cursor where this page ends
 };
 
-// Page splitting: when a page gets too large, Convex may return splitCursor
-// - SplitRecommended: page is large, should split on next render
-// - SplitRequired: page MUST be split (too large to return)
-type PageResultWithSplit<T> = PaginationResult<T> & {
-  splitCursor?: string | null;
-};
-
 /** Build a unique key for recovery attempt detection */
 const buildRecoveryKey = (
   pageKeys: number[],
@@ -507,7 +501,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
       const allItems: PaginatedQueryItem<Query>[] = [];
       const pages: PaginatedQueryItem<Query>[][] = [];
       const seenIds = new Set<string>();
-      let lastPage: PageResultWithSplit<PaginatedQueryItem<Query>> | undefined;
+      let lastPage: PaginationResult<PaginatedQueryItem<Query>> | undefined;
       let paginationStatus: PaginationStatus = 'LoadingFirstPage';
 
       for (let i = 0; i < results.length; i++) {
@@ -516,7 +510,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
           paginationStatus = i === 0 ? 'LoadingFirstPage' : 'LoadingMore';
           break;
         }
-        const page = pageQuery.data as PageResultWithSplit<
+        const page = pageQuery.data as PaginationResult<
           PaginatedQueryItem<Query>
         >;
         lastPage = page;
@@ -577,25 +571,29 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
     state,
   });
 
-  // Handle page splitting - when a page returns splitCursor, we need to split it
+  // Split when Convex requests it or a reactive page outgrows its target size.
   useEffect(() => {
     for (let i = 0; i < combined._rawResults.length; i++) {
       const pageQuery = combined._rawResults[i];
       if (pageQuery.data) {
-        const page = pageQuery.data as PageResultWithSplit<
+        const page = pageQuery.data as PaginationResult<
           PaginatedQueryItem<Query>
         >;
         const pageKey = state.pageKeys[i];
         const pageState = state.queries[pageKey];
 
         // Check if this page needs splitting and we haven't already split it
-        if (page.splitCursor && pageState && !pageState.endCursor) {
+        if (
+          shouldSplitPaginationPage(page, limit) &&
+          pageState &&
+          !pageState.endCursor
+        ) {
           setState((prev) => {
             const currentPageState = prev.queries[pageKey];
             if (!currentPageState || currentPageState.endCursor) return prev;
 
             const newKey = prev.nextPageKey;
-            const splitCursor = page.splitCursor!; // Checked above: page.splitCursor is truthy
+            const splitCursor = page.splitCursor;
             const splitPageArgs = {
               ...argsObject,
               cursor: splitCursor,
@@ -635,6 +633,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
     state.pageKeys,
     state.queries,
     argsObject,
+    limit,
     setState,
   ]);
 

packages/kitcn/src/solid/use-infinite-query.ts

@@ -20,6 +20,7 @@ import { createEffect, createMemo, createSignal, on } from 'solid-js';
 import { CRPCClientError, isCRPCClientError } from '../crpc/error';
 import { convexQuery } from '../crpc/query-options';
 import { type ExtractPaginatedItem, FUNC_REF_SYMBOL } from '../crpc/types';
+import { shouldSplitPaginationPage } from '../internal/pagination';
 import type { DistributiveOmit } from '../internal/types';
 import { useMeta } from './auth';
 import { useAuthValue, useSafeConvexAuth } from './auth-store';
@@ -139,13 +140,6 @@ type PageState = {
   endCursor?: string | null; // For page splitting - the cursor where this page ends
 };
 
-// Page splitting: when a page gets too large, Convex may return splitCursor
-// - SplitRecommended: page is large, should split on next render
-// - SplitRequired: page MUST be split (too large to return)
-type PageResultWithSplit<T> = PaginationResult<T> & {
-  splitCursor?: string | null;
-};
-
 /** Build a unique key for recovery attempt detection */
 const buildRecoveryKey = (
   pageKeys: number[],
@@ -500,7 +494,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
       const allItems: PaginatedQueryItem<Query>[] = [];
       const pages: PaginatedQueryItem<Query>[][] = [];
       const seenIds = new Set<string>();
-      let lastPage: PageResultWithSplit<PaginatedQueryItem<Query>> | undefined;
+      let lastPage: PaginationResult<PaginatedQueryItem<Query>> | undefined;
       let paginationStatus: PaginationStatus = 'LoadingFirstPage';
 
       for (let i = 0; i < results.length; i++) {
@@ -509,7 +503,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
           paginationStatus = i === 0 ? 'LoadingFirstPage' : 'LoadingMore';
           break;
         }
-        const page = pageQuery.data as PageResultWithSplit<
+        const page = pageQuery.data as PaginationResult<
           PaginatedQueryItem<Query>
         >;
         lastPage = page;
@@ -558,7 +552,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
   })) as {
     data: PaginatedQueryItem<Query>[];
     dataUpdatedAt: number;
-    lastPage: PageResultWithSplit<PaginatedQueryItem<Query>> | undefined;
+    lastPage: PaginationResult<PaginatedQueryItem<Query>> | undefined;
     pages: PaginatedQueryItem<Query>[][];
     status: PaginationStatus;
     error: Error | null;
@@ -581,7 +575,7 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
     state,
   });
 
-  // Handle page splitting - when a page returns splitCursor, we need to split it
+  // Split when Convex requests it or a reactive page outgrows its target size.
   createEffect(
     on(
       [
@@ -594,21 +588,25 @@ const useInfiniteQueryInternal = <Query extends PaginatedQueryReference>(
         for (let i = 0; i < combined._rawResults.length; i++) {
           const pageQuery = combined._rawResults[i];
           if (pageQuery.data) {
-            const page = pageQuery.data as PageResultWithSplit<
+            const page = pageQuery.data as PaginationResult<
               PaginatedQueryItem<Query>
             >;
             const pageKey = state().pageKeys[i];
             const pageState = state().queries[pageKey];
 
             // Check if this page needs splitting and we haven't already split it
-            if (page.splitCursor && pageState && !pageState.endCursor) {
+            if (
+              shouldSplitPaginationPage(page, limit) &&
+              pageState &&
+              !pageState.endCursor
+            ) {
               setState((prev) => {
                 const currentPageState = prev.queries[pageKey];
                 if (!currentPageState || currentPageState.endCursor)
                   return prev;
 
                 const newKey = prev.nextPageKey;
-                const splitCursor = page.splitCursor!;
+                const splitCursor = page.splitCursor;
                 const splitPageArgs = {
                   ...argsObject(),
                   cursor: splitCursor,

packages/kitcn/src/solid/use-infinite-query.vitest.tsx

@@ -201,6 +201,41 @@ describe('useInfiniteQuery', () => {
     expect((firstCall.queries[0] as any).enabled).toBe(true);
   });
 
+  test('does not split a native Convex page solely because it has a split cursor', () => {
+    const queryClient = new QueryClient();
+    const wrapper = makeWrapper(queryClient);
+    const firstPage = {
+      page: [{ _id: 'post-1' }, { _id: 'post-2' }, { _id: 'post-3' }],
+      isDone: false,
+      continueCursor: 'cursor-3',
+      splitCursor: 'cursor-2',
+    };
+    let capturedAccessor: (() => UseQueriesArg) | null = null;
+
+    mockUseQueries.mockImplementation((accessor: any) => {
+      capturedAccessor = accessor;
+      const arg = typeof accessor === 'function' ? accessor() : accessor;
+      useQueriesCalls.push(arg);
+      return arg.combine([
+        {
+          data: firstPage,
+          dataUpdatedAt: 1,
+          isError: false,
+          isFetching: false,
+          isLoading: false,
+          isPlaceholderData: false,
+        },
+      ]);
+    });
+
+    const options = createOptions({ limit: 3 });
+    const { result } = renderHook(() => useInfiniteQuery(options), { wrapper });
+
+    expect(result.data).toEqual(firstPage.page);
+    expect(result.hasNextPage).toBe(true);
+    expect(capturedAccessor!().queries).toHaveLength(1);
+  });
+
   test('fetchNextPage adds a new page query with continueCursor and limit', () => {
     const queryClient = new QueryClient();
     const wrapper = makeWrapper(queryClient);

tooling/scenario-fixtures/create-convex-nextjs-shadcn/components/ui/button.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 import { Slot } from '@radix-ui/react-slot';
 import { cva, type VariantProps } from 'class-variance-authority';
 import * as React from 'react';