convex-helpers 0.1.92 → 0.1.93

package/README.md

@@ -662,10 +662,15 @@ In addition to `getPage`, convex-helpers provides a function
   but does not subscribe the query to the end cursor automatically.
 
 The syntax and interface for `paginator` is so similar to `.paginate` that it is
-nearly a drop-in replacement and can even be used with `usePaginatedQuery`.
+nearly a drop-in replacement and can even be used with `usePaginatedQuery`[^1].
 This makes it more suitable for non-reactive pagination usecases,
 such as iterating data in a mutation. Note: it supports `withIndex` but not `filter`.
 
+[^1]:
+    Note: if you want gapless pagination, use the `usePaginatedQuery` hook in
+    `"convex-helpers/react"`, or if you're also using the cached query helpers, pass
+    `customPagination: true` for that version.
+
 For more information on reactive pagination and end cursors, see
 https://stack.convex.dev/fully-reactive-pagination
 and
@@ -722,11 +727,12 @@ and paginate the result.
   of documents, ordered by indexed fields.
 
 The cool thing about QueryStreams is you can make more QueryStreams from them,
-with operations equivalent to SQL's `UNION ALL`, `WHERE`, and
-`JOIN`. These operations preserve order, so the result
-is still a valid QueryStream. You can combine streams as much as you want, and
-finally treat it like a Convex query to get documents with `.first()`,
-`.collect()`, or `.paginate()`.
+with operations equivalent to SQL's `UNION ALL`, `WHERE`, and `JOIN`.
+These operations preserve order, so the result is still a valid QueryStream.
+You can combine streams as much as you want, and finally treat it like a
+Convex query to get documents with `.first()`, `.collect()`, or `.paginate()`.
+See [this Stack post](https://stack.convex.dev/translate-sql-into-convex-queries)
+for examples of translating SQL queries into Convex queries.
 
 For example, if you have a stream of "messages created by user1" and a stream
 of "messages created by user2", you can get a stream of
@@ -735,6 +741,9 @@ by creation time (or whatever the order is of the index you're using). You can
 then filter the merged stream to get a stream of "messages created by user1 or user2 that are unread". Then you
 can paginate the result.
 
+See [this Stack post](https://stack.convex.dev/merging-streams-of-convex-data)
+for more information.
+
 Concrete functions you can use:
 
 - `stream` constructs a stream using the same syntax as `DatabaseReader`.
@@ -746,9 +755,11 @@ Concrete functions you can use:
 - Once your stream is set up, you can get documents from it with the normal
   Convex query methods: `.first()`, `.collect()`, `.paginate()`, etc.
 
-Beware if using `.paginate()` with streams in reactive queries, as it has the
-same problems as [`paginator` and `getPage`](#manual-pagination): you need to
-pass in `endCursor` to prevent holes or overlaps between the pages.
+Note: if using `.paginate()` with streams in reactive queries, use the
+`usePaginatedQuery` hook from `"convex-helpers/react"`, or if you're also using
+the cached query helpers, pass `customPagination: true` for that version.
+It has the same behavior as [`paginator` and `getPage`](#manual-pagination) in
+that you need to pass in `endCursor` to prevent holes or overlaps between pages.
 
 ### Example 1: Paginate all messages by a fixed set of authors
 
@@ -920,19 +931,23 @@ server for some expiration period even after app `useQuery` hooks have all
 unmounted. This allows very fast reloading of unevicted values during
 navigation changes, view changes, etc.
 
+Note: unlike other forms of caching, subscription caching will mean strictly
+more bandwidth usage, because it will keep the subscription open even after
+the component unmounts. This is for optimizing the user experience, not database
+bandwidth.
+
 Related files:
 
 - [cache.ts](./react/cache.ts) re-exports things so you can import from a single convenient location.
 - [provider.tsx](./react/cache/provider.tsx) contains `ConvexQueryCacheProvider`,
   a configurable cache provider you put in your react app's root.
 - [hooks.ts](./react/cache/hooks.ts) contains cache-enabled drop-in
-  replacements for both `useQuery` and `useQueries` from `convex/react`.
+  replacements for `useQuery`, `usePaginatedQuery`, and `useQueries`.
 
 To use the cache, first make sure to put a `<ConvexQueryCacheProvider>`
 inside `<ConvexProvider>` in your react component tree:
 
-```jsx
-
+```tsx
 import { ConvexQueryCacheProvider } from "convex-helpers/react/cache";
 // For Next.js, import from "convex-helpers/react/cache/provider"; instead
 
@@ -966,7 +981,7 @@ This provider takes three optional props:
 Finally, you can utilize `useQuery` (and `useQueries`) just the same as
 their `convex/react` equivalents.
 
-```jsx
+```tsx
 import { useQuery } from "convex-helpers/react/cache";
 // For Next.js, import from "convex-helpers/react/cache/hooks"; instead
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convex-helpers",
-  "version": "0.1.92",
+  "version": "0.1.93",
   "description": "A collection of useful code to complement the official convex package.",
   "type": "module",
   "bin": {

package/react/cache/hooks.d.ts

@@ -105,13 +105,10 @@ export declare function useQuery<Query extends FunctionReference<"query">>(query
  * @param args - The arguments object for the query function, excluding
  * the `paginationOpts` property. That property is injected by this hook.
  * @param options - An object specifying the `initialNumItems` to be loaded in
- * the first page, and the `latestPageSize` to use.
- * @param options.latestPageSize controls how the latest page (the first page
- * until another page is loaded) size grows. With "fixed", the page size will
- * stay at the size specified by `initialNumItems` / `loadMore`. With "grow",
- * the page size will grow as new items are added within the range of the initial
- * page. Once multiple pages are loaded, all but the last page will grow, in
- * order to provide seamless pagination. See the docs for more details.
+ * the first page, and the `customPagination` to use.
+ * @param options.customPagination - Set this to true when you are using
+ * `stream` or `paginator` helpers on the server. This enables gapless
+ * pagination by connecting the pages explicitly when calling `loadMore`.
  * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
  * items, the status of the pagination, and a `loadMore` function.
  *
@@ -119,6 +116,9 @@ export declare function useQuery<Query extends FunctionReference<"query">>(query
  */
 export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: PaginatedQueryArgs<Query> | "skip", options: {
     initialNumItems: number;
-    latestPageSize?: "grow" | "fixed";
+    /**
+     * Set this to true if you are using the `stream` or `paginator` helpers.
+     */
+    customPagination?: boolean;
 }): UsePaginatedQueryReturnType<Query>;
 //# sourceMappingURL=hooks.d.ts.map

package/react/cache/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAInB,MAAM,eAAe,CAAC;AAkBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,GAAG,KAAK,CAAC,CAiCzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC/D,KAAK,EAAE,KAAK,EACZ,GAAG,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAC1C,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS,CAoBvC;AAoHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,uBAAuB,EACrE,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE;IACP,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC,GACA,2BAA2B,CAAC,KAAK,CAAC,CAqPpC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAInB,MAAM,eAAe,CAAC;AAkBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,GAAG,KAAK,CAAC,CAiCzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC/D,KAAK,EAAE,KAAK,EACZ,GAAG,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAC1C,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS,CAoBvC;AAoHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,uBAAuB,EACrE,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE;IACP,eAAe,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACA,2BAA2B,CAAC,KAAK,CAAC,CA2PpC"}

package/react/cache/hooks.js

@@ -234,13 +234,10 @@ const completeSplitQuery = (key) => (prevState) => {
  * @param args - The arguments object for the query function, excluding
  * the `paginationOpts` property. That property is injected by this hook.
  * @param options - An object specifying the `initialNumItems` to be loaded in
- * the first page, and the `latestPageSize` to use.
- * @param options.latestPageSize controls how the latest page (the first page
- * until another page is loaded) size grows. With "fixed", the page size will
- * stay at the size specified by `initialNumItems` / `loadMore`. With "grow",
- * the page size will grow as new items are added within the range of the initial
- * page. Once multiple pages are loaded, all but the last page will grow, in
- * order to provide seamless pagination. See the docs for more details.
+ * the first page, and the `customPagination` to use.
+ * @param options.customPagination - Set this to true when you are using
+ * `stream` or `paginator` helpers on the server. This enables gapless
+ * pagination by connecting the pages explicitly when calling `loadMore`.
  * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
  * items, the status of the pagination, and a `loadMore` function.
  *
@@ -296,10 +293,10 @@ export function usePaginatedQuery(query, args, options) {
     const [state, setState] = useState(createInitialState);
     // `currState` is the state that we'll render based on.
     let currState = state;
-    if (getFunctionName(query) !== getFunctionName(state.query) ||
+    if (skip !== state.skip ||
+        getFunctionName(query) !== getFunctionName(state.query) ||
         JSON.stringify(convexToJson(argsObject)) !==
-            JSON.stringify(convexToJson(state.args)) ||
-        skip !== state.skip) {
+            JSON.stringify(convexToJson(state.args))) {
         currState = createInitialState();
         setState(currState);
     }
@@ -346,8 +343,11 @@ export function usePaginatedQuery(query, args, options) {
             else if (currResult.splitCursor &&
                 (currResult.pageStatus === "SplitRecommended" ||
                     currResult.pageStatus === "SplitRequired" ||
-                    currResult.page.length > options.initialNumItems * 2)) {
-                // If a single page has more than double the expected number of items,
+                    (options.customPagination
+                        ? // For custom pagination, we eagerly split the page when it grows.
+                            currResult.page.length > options.initialNumItems
+                        : currResult.page.length > options.initialNumItems * 2))) {
+                // If a single page has more than 1.5x the expected number of items,
                 // or if the server requests a split, split the page into two.
                 setState(splitQuery(pageKey, currResult.splitCursor, currResult.continueCursor));
             }
@@ -411,7 +411,10 @@ export function usePaginatedQuery(query, args, options) {
                         const queries = { ...prevState.queries };
                         let ongoingSplits = prevState.ongoingSplits;
                         let pageKeys = prevState.pageKeys;
-                        if (options.latestPageSize !== "grow") {
+                        if (options.customPagination) {
+                            // Connect the current last page to the next page
+                            // by setting the endCursor of the last page to the continueCursor
+                            // of the next page.
                             const lastPageKey = prevState.pageKeys.at(-1);
                             const boundLastPageKey = nextPageKey;
                             queries[boundLastPageKey] = {
@@ -457,7 +460,7 @@ export function usePaginatedQuery(query, args, options) {
                 }
             },
         };
-    }, [maybeLastResult, currState.nextPageKey, options.latestPageSize]);
+    }, [maybeLastResult, currState.nextPageKey, options.customPagination]);
     return {
         results,
         ...statusObject,

package/react/cache/hooks.ts

@@ -314,13 +314,10 @@ const completeSplitQuery =
  * @param args - The arguments object for the query function, excluding
  * the `paginationOpts` property. That property is injected by this hook.
  * @param options - An object specifying the `initialNumItems` to be loaded in
- * the first page, and the `latestPageSize` to use.
- * @param options.latestPageSize controls how the latest page (the first page
- * until another page is loaded) size grows. With "fixed", the page size will
- * stay at the size specified by `initialNumItems` / `loadMore`. With "grow",
- * the page size will grow as new items are added within the range of the initial
- * page. Once multiple pages are loaded, all but the last page will grow, in
- * order to provide seamless pagination. See the docs for more details.
+ * the first page, and the `customPagination` to use.
+ * @param options.customPagination - Set this to true when you are using
+ * `stream` or `paginator` helpers on the server. This enables gapless
+ * pagination by connecting the pages explicitly when calling `loadMore`.
  * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
  * items, the status of the pagination, and a `loadMore` function.
  *
@@ -331,7 +328,10 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
   args: PaginatedQueryArgs<Query> | "skip",
   options: {
     initialNumItems: number;
-    latestPageSize?: "grow" | "fixed";
+    /**
+     * Set this to true if you are using the `stream` or `paginator` helpers.
+     */
+    customPagination?: boolean;
   },
 ): UsePaginatedQueryReturnType<Query> {
   if (
@@ -391,10 +391,10 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
   // `currState` is the state that we'll render based on.
   let currState = state;
   if (
+    skip !== state.skip ||
     getFunctionName(query) !== getFunctionName(state.query) ||
     JSON.stringify(convexToJson(argsObject as Value)) !==
-      JSON.stringify(convexToJson(state.args)) ||
-    skip !== state.skip
+      JSON.stringify(convexToJson(state.args))
   ) {
     currState = createInitialState();
     setState(currState);
@@ -455,9 +455,12 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
         currResult.splitCursor &&
         (currResult.pageStatus === "SplitRecommended" ||
           currResult.pageStatus === "SplitRequired" ||
-          currResult.page.length > options.initialNumItems * 2)
+          (options.customPagination
+            ? // For custom pagination, we eagerly split the page when it grows.
+              currResult.page.length > options.initialNumItems
+            : currResult.page.length > options.initialNumItems * 2))
       ) {
-        // If a single page has more than double the expected number of items,
+        // If a single page has more than 1.5x the expected number of items,
         // or if the server requests a split, split the page into two.
         setState(
           splitQuery(
@@ -527,7 +530,10 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
             const queries = { ...prevState.queries };
             let ongoingSplits = prevState.ongoingSplits;
             let pageKeys = prevState.pageKeys;
-            if (options.latestPageSize !== "grow") {
+            if (options.customPagination) {
+              // Connect the current last page to the next page
+              // by setting the endCursor of the last page to the continueCursor
+              // of the next page.
               const lastPageKey = prevState.pageKeys.at(-1)!;
               const boundLastPageKey = nextPageKey;
               queries[boundLastPageKey] = {
@@ -572,7 +578,7 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
         }
       },
     } as const;
-  }, [maybeLastResult, currState.nextPageKey, options.latestPageSize]);
+  }, [maybeLastResult, currState.nextPageKey, options.customPagination]);
 
   return {
     results,

package/react.d.ts

@@ -1,4 +1,4 @@
-import type { OptionalRestArgsOrSkip } from "convex/react";
+import type { OptionalRestArgsOrSkip, PaginatedQueryArgs, PaginatedQueryReference, UsePaginatedQueryReturnType } from "convex/react";
 import { useQueries } from "convex/react";
 import type { FunctionReference, FunctionReturnType } from "convex/server";
 /**
@@ -117,4 +117,29 @@ export declare function makeUseQueryWithStatus(useQueriesHook: typeof useQueries
     isPending: false;
     isError: true;
 };
+/**
+ * This is a clone of the `usePaginatedQuery` hook from `convex/react` made for
+ * use with the `stream` and `paginator` helpers, which don't automatically
+ * "grow" until you explicitly pass the `endCursor` arg.
+ *
+ * For these, we wait to set the end cursor until `loadMore` is called.
+ * So the first page will be a fixed size until the first call to `loadMore`,
+ * at which point the second page will start where the first page ended, and the
+ * first page will explicitly "pin" that end cursor. From then on, the last page
+ * will also be a fixed size until the next call to `loadMore`. This is less
+ * noticeable because typically the first page is the only page that grows.
+ *
+ * To use the cached query helpers, you can use those directly and pass
+ * `customPagination: true` in the options.
+ *
+ * Docs copied from {@link usePaginatedQueryOriginal} until `returns` block:
+ *
+ * @param query - a {@link server.FunctionReference} for the public query to run
+ * like `api.dir1.dir2.filename.func`.
+ * @param args - The arguments to the query function or the string "skip" if the
+ * query should not be loaded.
+ */
+export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: PaginatedQueryArgs<Query> | "skip", options: {
+    initialNumItems: number;
+}): UsePaginatedQueryReturnType<Query>;
 //# sourceMappingURL=react.d.ts.map

package/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["react.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAgC,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAK3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,QAAQ,GA0CM,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,SACxD,KAAK,gBACE,sBAAsB,CAAC,KAAK,CAAC,KAEzC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,AArEmD,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,OAAO,UAAU,IAC7C,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC/D,OAAO,KAAK,EACZ,GAAG,WAAW,sBAAsB,CAAC,KAAK,CAAC,KAEzC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,CAuDN"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["react.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAEL,UAAU,EAEX,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAInB,MAAM,eAAe,CAAC;AAOvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,QAAQ,GA0CM,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,SACxD,KAAK,gBACE,sBAAsB,CAAC,KAAK,CAAC,KAEzC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,AArEmD,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,OAAO,UAAU,IAC7C,KAAK,SAAS,iBAAiB,CAAC,OAAO,CAAC,EAC/D,OAAO,KAAK,EACZ,GAAG,WAAW,sBAAsB,CAAC,KAAK,CAAC,KAEzC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;CAChB,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,CAuDN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,uBAAuB,EACrE,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GACnC,2BAA2B,CAAC,KAAK,CAAC,CA6OpC"}

package/react.js

@@ -1,6 +1,8 @@
-import { useQueries, useQuery as useQueryOriginal } from "convex/react";
+import { ConvexError } from "convex/values";
+import { convexToJson } from "convex/values";
+import { useConvex, useQueries, useQuery as useQueryOriginal, } from "convex/react";
 import { getFunctionName } from "convex/server";
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 /**
  * Use in place of `useQuery` from "convex/react" to fetch data from a query
  * function but instead returns `{ status, data, error, isSuccess, isPending, isError}`.
@@ -131,3 +133,297 @@ export function makeUseQueryWithStatus(useQueriesHook) {
         };
     };
 }
+/**
+ * This is a clone of the `usePaginatedQuery` hook from `convex/react` made for
+ * use with the `stream` and `paginator` helpers, which don't automatically
+ * "grow" until you explicitly pass the `endCursor` arg.
+ *
+ * For these, we wait to set the end cursor until `loadMore` is called.
+ * So the first page will be a fixed size until the first call to `loadMore`,
+ * at which point the second page will start where the first page ended, and the
+ * first page will explicitly "pin" that end cursor. From then on, the last page
+ * will also be a fixed size until the next call to `loadMore`. This is less
+ * noticeable because typically the first page is the only page that grows.
+ *
+ * To use the cached query helpers, you can use those directly and pass
+ * `customPagination: true` in the options.
+ *
+ * Docs copied from {@link usePaginatedQueryOriginal} until `returns` block:
+ *
+ * @param query - a {@link server.FunctionReference} for the public query to run
+ * like `api.dir1.dir2.filename.func`.
+ * @param args - The arguments to the query function or the string "skip" if the
+ * query should not be loaded.
+ */
+export function usePaginatedQuery(query, args, options) {
+    if (typeof options?.initialNumItems !== "number" ||
+        options.initialNumItems <= 0) {
+        throw new Error(`\`options.initialNumItems\` must be a positive number. Received \`${options?.initialNumItems}\`.`);
+    }
+    const skip = args === "skip";
+    const argsObject = skip ? {} : args;
+    const queryName = getFunctionName(query);
+    const createInitialState = useMemo(() => {
+        return () => {
+            return {
+                query,
+                args: argsObject,
+                nextPageKey: 1,
+                pageKeys: skip ? [] : [0],
+                queries: skip
+                    ? {}
+                    : {
+                        0: {
+                            query,
+                            args: {
+                                ...argsObject,
+                                paginationOpts: {
+                                    numItems: options.initialNumItems,
+                                    cursor: null,
+                                },
+                            },
+                        },
+                    },
+                ongoingSplits: {},
+                skip,
+            };
+        };
+        // ESLint doesn't like that we're stringifying the args. We do this because
+        // we want to avoid rerendering if the args are a different
+        // object that serializes to the same result.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        JSON.stringify(convexToJson(argsObject)),
+        queryName,
+        options.initialNumItems,
+        skip,
+    ]);
+    const [state, setState] = useState(createInitialState);
+    // `currState` is the state that we'll render based on.
+    let currState = state;
+    if (skip !== state.skip ||
+        getFunctionName(query) !== getFunctionName(state.query) ||
+        JSON.stringify(convexToJson(argsObject)) !==
+            JSON.stringify(convexToJson(state.args))) {
+        currState = createInitialState();
+        setState(currState);
+    }
+    const convexClient = useConvex();
+    const logger = convexClient.logger;
+    const resultsObject = useQueries(currState.queries);
+    const [results, maybeLastResult] = useMemo(() => {
+        let currResult = undefined;
+        const allItems = [];
+        for (const pageKey of currState.pageKeys) {
+            currResult = resultsObject[pageKey];
+            if (currResult === undefined) {
+                break;
+            }
+            if (currResult instanceof Error) {
+                if (currResult.message.includes("InvalidCursor") ||
+                    (currResult instanceof ConvexError &&
+                        typeof currResult.data === "object" &&
+                        currResult.data?.isConvexSystemError === true &&
+                        currResult.data?.paginationError === "InvalidCursor")) {
+                    // - InvalidCursor: If the cursor is invalid, probably the paginated
+                    // database query was data-dependent and changed underneath us. The
+                    // cursor in the params or journal no longer matches the current
+                    // database query.
+                    // In all cases, we want to restart pagination to throw away all our
+                    // existing cursors.
+                    logger.warn("usePaginatedQuery hit error, resetting pagination state: " +
+                        currResult.message);
+                    setState(createInitialState);
+                    return [[], undefined];
+                }
+                else {
+                    throw currResult;
+                }
+            }
+            const ongoingSplit = currState.ongoingSplits[pageKey];
+            if (ongoingSplit !== undefined) {
+                if (resultsObject[ongoingSplit[0]] !== undefined &&
+                    resultsObject[ongoingSplit[1]] !== undefined) {
+                    // Both pages of the split have results now. Swap them in.
+                    setState(completeSplitQuery(pageKey));
+                }
+            }
+            else if (currResult.splitCursor &&
+                (currResult.pageStatus === "SplitRecommended" ||
+                    currResult.pageStatus === "SplitRequired" ||
+                    // For custom pagination, we eagerly split the page when it grows.
+                    currResult.page.length > options.initialNumItems)) {
+                setState(splitQuery(pageKey, currResult.splitCursor, currResult.continueCursor));
+            }
+            if (currResult.pageStatus === "SplitRequired") {
+                // If pageStatus is 'SplitRequired', it means the server was not able to
+                // fetch the full page. So we stop results before the incomplete
+                // page and return 'LoadingMore' while the page is splitting.
+                return [allItems, undefined];
+            }
+            allItems.push(...currResult.page);
+        }
+        return [allItems, currResult];
+    }, [
+        resultsObject,
+        currState.pageKeys,
+        currState.ongoingSplits,
+        options.initialNumItems,
+        createInitialState,
+        logger,
+    ]);
+    const statusObject = useMemo(() => {
+        if (maybeLastResult === undefined) {
+            if (currState.nextPageKey === 1) {
+                return {
+                    status: "LoadingFirstPage",
+                    isLoading: true,
+                    loadMore: (_numItems) => {
+                        // Intentional noop.
+                    },
+                };
+            }
+            else {
+                return {
+                    status: "LoadingMore",
+                    isLoading: true,
+                    loadMore: (_numItems) => {
+                        // Intentional noop.
+                    },
+                };
+            }
+        }
+        if (maybeLastResult.isDone) {
+            return {
+                status: "Exhausted",
+                isLoading: false,
+                loadMore: (_numItems) => {
+                    // Intentional noop.
+                },
+            };
+        }
+        const continueCursor = maybeLastResult.continueCursor;
+        let alreadyLoadingMore = false;
+        return {
+            status: "CanLoadMore",
+            isLoading: false,
+            loadMore: (numItems) => {
+                if (!alreadyLoadingMore) {
+                    alreadyLoadingMore = true;
+                    setState((prevState) => {
+                        let nextPageKey = prevState.nextPageKey;
+                        const queries = { ...prevState.queries };
+                        let ongoingSplits = prevState.ongoingSplits;
+                        // Connect the current last page to the next page
+                        // by setting the endCursor of the last page to the continueCursor
+                        // of the next page.
+                        const lastPageKey = prevState.pageKeys.at(-1);
+                        const boundLastPageKey = nextPageKey;
+                        queries[boundLastPageKey] = {
+                            query: prevState.query,
+                            args: {
+                                ...prevState.args,
+                                paginationOpts: {
+                                    ...queries[lastPageKey].args
+                                        .paginationOpts,
+                                    endCursor: continueCursor,
+                                },
+                            },
+                        };
+                        nextPageKey++;
+                        ongoingSplits = {
+                            ...ongoingSplits,
+                            [lastPageKey]: [boundLastPageKey, nextPageKey],
+                        };
+                        queries[nextPageKey] = {
+                            query: prevState.query,
+                            args: {
+                                ...prevState.args,
+                                paginationOpts: {
+                                    numItems,
+                                    cursor: continueCursor,
+                                },
+                            },
+                        };
+                        nextPageKey++;
+                        return {
+                            ...prevState,
+                            nextPageKey,
+                            queries,
+                            ongoingSplits,
+                        };
+                    });
+                }
+            },
+        };
+    }, [maybeLastResult, currState.nextPageKey]);
+    return {
+        results,
+        ...statusObject,
+    };
+}
+function splitQuery(key, splitCursor, continueCursor) {
+    return (prevState) => {
+        const queries = { ...prevState.queries };
+        const splitKey1 = prevState.nextPageKey;
+        const splitKey2 = prevState.nextPageKey + 1;
+        const nextPageKey = prevState.nextPageKey + 2;
+        queries[splitKey1] = {
+            query: prevState.query,
+            args: {
+                ...prevState.args,
+                paginationOpts: {
+                    ...prevState.queries[key].args.paginationOpts,
+                    endCursor: splitCursor,
+                },
+            },
+        };
+        queries[splitKey2] = {
+            query: prevState.query,
+            args: {
+                ...prevState.args,
+                paginationOpts: {
+                    ...prevState.queries[key].args.paginationOpts,
+                    cursor: splitCursor,
+                    endCursor: continueCursor,
+                },
+            },
+        };
+        const ongoingSplits = { ...prevState.ongoingSplits };
+        ongoingSplits[key] = [splitKey1, splitKey2];
+        return {
+            ...prevState,
+            nextPageKey,
+            queries,
+            ongoingSplits,
+        };
+    };
+}
+function completeSplitQuery(key) {
+    return (prevState) => {
+        const completedSplit = prevState.ongoingSplits[key];
+        if (completedSplit === undefined) {
+            return prevState;
+        }
+        const queries = { ...prevState.queries };
+        delete queries[key];
+        const ongoingSplits = { ...prevState.ongoingSplits };
+        delete ongoingSplits[key];
+        let pageKeys = prevState.pageKeys.slice();
+        const pageIndex = prevState.pageKeys.findIndex((v) => v === key);
+        if (pageIndex >= 0) {
+            pageKeys = [
+                ...prevState.pageKeys.slice(0, pageIndex),
+                ...completedSplit,
+                ...prevState.pageKeys.slice(pageIndex + 1),
+            ];
+        }
+        return {
+            ...prevState,
+            queries,
+            pageKeys,
+            ongoingSplits,
+        };
+    };
+}

package/react.ts

@@ -1,9 +1,28 @@
-import type { OptionalRestArgsOrSkip } from "convex/react";
-import { useQueries, useQuery as useQueryOriginal } from "convex/react";
-import type { FunctionReference, FunctionReturnType } from "convex/server";
+import type {
+  OptionalRestArgsOrSkip,
+  PaginatedQueryArgs,
+  PaginatedQueryReference,
+  UsePaginatedQueryReturnType,
+} from "convex/react";
+import { ConvexError } from "convex/values";
+import { convexToJson } from "convex/values";
+import {
+  useConvex,
+  useQueries,
+  useQuery as useQueryOriginal,
+} from "convex/react";
+import type {
+  FunctionReference,
+  FunctionReturnType,
+  PaginationOptions,
+  paginationOptsValidator,
+  PaginationResult,
+} from "convex/server";
+import type { Infer } from "convex/values";
 import { getFunctionName } from "convex/server";
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 import type { EmptyObject } from "./index.js";
+import type { Value } from "convex/values";
 
 /**
  * Use in place of `useQuery` from "convex/react" to fetch data from a query
@@ -163,3 +182,370 @@ export function makeUseQueryWithStatus(useQueriesHook: typeof useQueries) {
     };
   };
 }
+
+/**
+ * This is a clone of the `usePaginatedQuery` hook from `convex/react` made for
+ * use with the `stream` and `paginator` helpers, which don't automatically
+ * "grow" until you explicitly pass the `endCursor` arg.
+ *
+ * For these, we wait to set the end cursor until `loadMore` is called.
+ * So the first page will be a fixed size until the first call to `loadMore`,
+ * at which point the second page will start where the first page ended, and the
+ * first page will explicitly "pin" that end cursor. From then on, the last page
+ * will also be a fixed size until the next call to `loadMore`. This is less
+ * noticeable because typically the first page is the only page that grows.
+ *
+ * To use the cached query helpers, you can use those directly and pass
+ * `customPagination: true` in the options.
+ *
+ * Docs copied from {@link usePaginatedQueryOriginal} until `returns` block:
+ *
+ * @param query - a {@link server.FunctionReference} for the public query to run
+ * like `api.dir1.dir2.filename.func`.
+ * @param args - The arguments to the query function or the string "skip" if the
+ * query should not be loaded.
+ */
+export function usePaginatedQuery<Query extends PaginatedQueryReference>(
+  query: Query,
+  args: PaginatedQueryArgs<Query> | "skip",
+  options: { initialNumItems: number },
+): UsePaginatedQueryReturnType<Query> {
+  if (
+    typeof options?.initialNumItems !== "number" ||
+    options.initialNumItems <= 0
+  ) {
+    throw new Error(
+      `\`options.initialNumItems\` must be a positive number. Received \`${options?.initialNumItems}\`.`,
+    );
+  }
+  const skip = args === "skip";
+  const argsObject = skip ? {} : args;
+  const queryName = getFunctionName(query);
+  const createInitialState = useMemo(() => {
+    return () => {
+      return {
+        query,
+        args: argsObject as Record<string, Value>,
+        nextPageKey: 1,
+        pageKeys: skip ? [] : [0],
+        queries: skip
+          ? ({} as UsePaginatedQueryState["queries"])
+          : {
+              0: {
+                query,
+                args: {
+                  ...argsObject,
+                  paginationOpts: {
+                    numItems: options.initialNumItems,
+                    cursor: null,
+                  },
+                },
+              },
+            },
+        ongoingSplits: {},
+        skip,
+      };
+    };
+    // ESLint doesn't like that we're stringifying the args. We do this because
+    // we want to avoid rerendering if the args are a different
+    // object that serializes to the same result.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    JSON.stringify(convexToJson(argsObject as Value)),
+    queryName,
+    options.initialNumItems,
+    skip,
+  ]);
+
+  const [state, setState] =
+    useState<UsePaginatedQueryState>(createInitialState);
+
+  // `currState` is the state that we'll render based on.
+  let currState = state;
+  if (
+    skip !== state.skip ||
+    getFunctionName(query) !== getFunctionName(state.query) ||
+    JSON.stringify(convexToJson(argsObject as Value)) !==
+      JSON.stringify(convexToJson(state.args))
+  ) {
+    currState = createInitialState();
+    setState(currState);
+  }
+  const convexClient = useConvex();
+  const logger = convexClient.logger;
+
+  const resultsObject = useQueries(currState.queries);
+
+  const [results, maybeLastResult]: [
+    Value[],
+    undefined | PaginationResult<Value>,
+  ] = useMemo(() => {
+    let currResult: PaginationResult<Value> | undefined = undefined;
+
+    const allItems: Value[] = [];
+    for (const pageKey of currState.pageKeys) {
+      currResult = resultsObject[pageKey];
+      if (currResult === undefined) {
+        break;
+      }
+
+      if (currResult instanceof Error) {
+        if (
+          currResult.message.includes("InvalidCursor") ||
+          (currResult instanceof ConvexError &&
+            typeof currResult.data === "object" &&
+            currResult.data?.isConvexSystemError === true &&
+            currResult.data?.paginationError === "InvalidCursor")
+        ) {
+          // - InvalidCursor: If the cursor is invalid, probably the paginated
+          // database query was data-dependent and changed underneath us. The
+          // cursor in the params or journal no longer matches the current
+          // database query.
+
+          // In all cases, we want to restart pagination to throw away all our
+          // existing cursors.
+          logger.warn(
+            "usePaginatedQuery hit error, resetting pagination state: " +
+              currResult.message,
+          );
+          setState(createInitialState);
+          return [[], undefined];
+        } else {
+          throw currResult;
+        }
+      }
+      const ongoingSplit = currState.ongoingSplits[pageKey];
+      if (ongoingSplit !== undefined) {
+        if (
+          resultsObject[ongoingSplit[0]] !== undefined &&
+          resultsObject[ongoingSplit[1]] !== undefined
+        ) {
+          // Both pages of the split have results now. Swap them in.
+          setState(completeSplitQuery(pageKey));
+        }
+      } else if (
+        currResult.splitCursor &&
+        (currResult.pageStatus === "SplitRecommended" ||
+          currResult.pageStatus === "SplitRequired" ||
+          // For custom pagination, we eagerly split the page when it grows.
+          currResult.page.length > options.initialNumItems)
+      ) {
+        setState(
+          splitQuery(
+            pageKey,
+            currResult.splitCursor,
+            currResult.continueCursor,
+          ),
+        );
+      }
+      if (currResult.pageStatus === "SplitRequired") {
+        // If pageStatus is 'SplitRequired', it means the server was not able to
+        // fetch the full page. So we stop results before the incomplete
+        // page and return 'LoadingMore' while the page is splitting.
+        return [allItems, undefined];
+      }
+      allItems.push(...currResult.page);
+    }
+    return [allItems, currResult];
+  }, [
+    resultsObject,
+    currState.pageKeys,
+    currState.ongoingSplits,
+    options.initialNumItems,
+    createInitialState,
+    logger,
+  ]);
+
+  const statusObject = useMemo(() => {
+    if (maybeLastResult === undefined) {
+      if (currState.nextPageKey === 1) {
+        return {
+          status: "LoadingFirstPage",
+          isLoading: true,
+          loadMore: (_numItems: number) => {
+            // Intentional noop.
+          },
+        } as const;
+      } else {
+        return {
+          status: "LoadingMore",
+          isLoading: true,
+          loadMore: (_numItems: number) => {
+            // Intentional noop.
+          },
+        } as const;
+      }
+    }
+    if (maybeLastResult.isDone) {
+      return {
+        status: "Exhausted",
+        isLoading: false,
+        loadMore: (_numItems: number) => {
+          // Intentional noop.
+        },
+      } as const;
+    }
+    const continueCursor = maybeLastResult.continueCursor;
+    let alreadyLoadingMore = false;
+    return {
+      status: "CanLoadMore",
+      isLoading: false,
+      loadMore: (numItems: number) => {
+        if (!alreadyLoadingMore) {
+          alreadyLoadingMore = true;
+          setState((prevState) => {
+            let nextPageKey = prevState.nextPageKey;
+            const queries = { ...prevState.queries };
+            let ongoingSplits = prevState.ongoingSplits;
+            // Connect the current last page to the next page
+            // by setting the endCursor of the last page to the continueCursor
+            // of the next page.
+            const lastPageKey = prevState.pageKeys.at(-1)!;
+            const boundLastPageKey = nextPageKey;
+            queries[boundLastPageKey] = {
+              query: prevState.query,
+              args: {
+                ...prevState.args,
+                paginationOpts: {
+                  ...(queries[lastPageKey]!.args
+                    .paginationOpts as unknown as PaginationOptions),
+                  endCursor: continueCursor,
+                },
+              },
+            };
+            nextPageKey++;
+            ongoingSplits = {
+              ...ongoingSplits,
+              [lastPageKey]: [boundLastPageKey, nextPageKey],
+            };
+            queries[nextPageKey] = {
+              query: prevState.query,
+              args: {
+                ...prevState.args,
+                paginationOpts: {
+                  numItems,
+                  cursor: continueCursor,
+                },
+              },
+            };
+            nextPageKey++;
+            return {
+              ...prevState,
+              nextPageKey,
+              queries,
+              ongoingSplits,
+            };
+          });
+        }
+      },
+    } as const;
+  }, [maybeLastResult, currState.nextPageKey]);
+
+  return {
+    results,
+    ...statusObject,
+  };
+}
+
+/**
+ * A {@link server.FunctionReference} that is usable with {@link usePaginatedQuery}.
+ *
+ * This function reference must:
+ * - Refer to a public query
+ * - Have an argument named "paginationOpts" of type {@link server.PaginationOptions}
+ * - Have a return type of {@link server.PaginationResult}.
+ *
+ * @public
+ */
+
+// Incrementing integer for each page queried in the usePaginatedQuery hook.
+type QueryPageKey = number;
+
+type UsePaginatedQueryState = {
+  query: FunctionReference<"query">;
+  args: Record<string, Value>;
+  nextPageKey: QueryPageKey;
+  pageKeys: QueryPageKey[];
+  queries: Record<
+    QueryPageKey,
+    {
+      query: FunctionReference<"query">;
+      // Use the validator type as a test that it matches the args
+      // we generate.
+      args: { paginationOpts: Infer<typeof paginationOptsValidator> };
+    }
+  >;
+  ongoingSplits: Record<QueryPageKey, [QueryPageKey, QueryPageKey]>;
+  skip: boolean;
+};
+
+function splitQuery(
+  key: QueryPageKey,
+  splitCursor: string,
+  continueCursor: string,
+) {
+  return (prevState: UsePaginatedQueryState) => {
+    const queries = { ...prevState.queries };
+    const splitKey1 = prevState.nextPageKey;
+    const splitKey2 = prevState.nextPageKey + 1;
+    const nextPageKey = prevState.nextPageKey + 2;
+    queries[splitKey1] = {
+      query: prevState.query,
+      args: {
+        ...prevState.args,
+        paginationOpts: {
+          ...prevState.queries[key]!.args.paginationOpts,
+          endCursor: splitCursor,
+        },
+      },
+    };
+    queries[splitKey2] = {
+      query: prevState.query,
+      args: {
+        ...prevState.args,
+        paginationOpts: {
+          ...prevState.queries[key]!.args.paginationOpts,
+          cursor: splitCursor,
+          endCursor: continueCursor,
+        },
+      },
+    };
+    const ongoingSplits = { ...prevState.ongoingSplits };
+    ongoingSplits[key] = [splitKey1, splitKey2];
+    return {
+      ...prevState,
+      nextPageKey,
+      queries,
+      ongoingSplits,
+    };
+  };
+}
+
+function completeSplitQuery(key: QueryPageKey) {
+  return (prevState: UsePaginatedQueryState) => {
+    const completedSplit = prevState.ongoingSplits[key];
+    if (completedSplit === undefined) {
+      return prevState;
+    }
+    const queries = { ...prevState.queries };
+    delete queries[key];
+    const ongoingSplits = { ...prevState.ongoingSplits };
+    delete ongoingSplits[key];
+    let pageKeys = prevState.pageKeys.slice();
+    const pageIndex = prevState.pageKeys.findIndex((v) => v === key);
+    if (pageIndex >= 0) {
+      pageKeys = [
+        ...prevState.pageKeys.slice(0, pageIndex),
+        ...completedSplit,
+        ...prevState.pageKeys.slice(pageIndex + 1),
+      ];
+    }
+    return {
+      ...prevState,
+      queries,
+      pageKeys,
+      ongoingSplits,
+    };
+  };
+}

package/server/migrations.d.ts

@@ -115,8 +115,8 @@ export declare const migrationsTable: import("convex/server").TableDefinition<im
     workerId?: GenericId<"_scheduled_functions"> | undefined;
     latestEnd?: number | undefined;
     cursor: string | null;
-    name: string;
     isDone: boolean;
+    name: string;
     table: string;
     processed: number;
     latestStart: number;
@@ -129,7 +129,7 @@ export declare const migrationsTable: import("convex/server").TableDefinition<im
     processed: import("convex/values").VFloat64<number, "required">;
     latestStart: import("convex/values").VFloat64<number, "required">;
     latestEnd: import("convex/values").VFloat64<number | undefined, "optional">;
-}, "required", "cursor" | "name" | "isDone" | "table" | "workerId" | "processed" | "latestStart" | "latestEnd">, {
+}, "required", "cursor" | "isDone" | "name" | "table" | "workerId" | "processed" | "latestStart" | "latestEnd">, {
     name: ["name", "_creationTime"];
 }, {}, {}>;
 declare const migrationArgs: {
@@ -283,8 +283,8 @@ export declare function cancelMigration<DataModel extends GenericDataModel>(ctx:
     workerId?: GenericId<"_scheduled_functions"> | undefined;
     latestEnd?: number | undefined;
     cursor: string | null;
-    name: string;
     isDone: boolean;
+    name: string;
     table: string;
     processed: number;
     latestStart: number;
@@ -293,8 +293,8 @@ export declare function cancelMigration<DataModel extends GenericDataModel>(ctx:
     workerId?: GenericId<"_scheduled_functions"> | undefined;
     latestEnd?: number | undefined;
     cursor: string | null;
-    name: string;
     isDone: boolean;
+    name: string;
     table: string;
     processed: number;
     latestStart: number;

package/validators.d.ts

@@ -25,7 +25,7 @@ export declare const literals: <V extends string | number | boolean | bigint, T
  * @param x The validator to make nullable. As in, it can be the value or null.
  * @returns A new validator that can be the value or null.
  */
-export declare const nullable: <V extends Validator<any, "required", any>>(x: V) => VUnion<(V | import("convex/values").VNull<null, "required">)["type"], [import("convex/values").VNull<null, "required">, V], "required", (V | import("convex/values").VNull<null, "required">)["fieldPaths"]>;
+export declare const nullable: <V extends Validator<any, "required", any>>(x: V) => VUnion<(import("convex/values").VNull<null, "required"> | V)["type"], [import("convex/values").VNull<null, "required">, V], "required", (import("convex/values").VNull<null, "required"> | V)["fieldPaths"]>;
 /**
  * partial helps you define an object of optional validators more concisely.
  *