convex-helpers 0.1.90 → 0.1.91

package/package.json

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

package/react/cache/hooks.d.ts

@@ -1,4 +1,4 @@
-import type { OptionalRestArgsOrSkip, RequestForQueries } from "convex/react";
+import type { OptionalRestArgsOrSkip, PaginatedQueryArgs, PaginatedQueryReference, RequestForQueries, UsePaginatedQueryReturnType } from "convex/react";
 import type { FunctionReference, FunctionReturnType } from "convex/server";
 /**
  * Load a variable number of reactive Convex queries, utilizing
@@ -70,4 +70,60 @@ export declare function useQueries(queries: RequestForQueries): Record<string, a
  * @public
  */
 export declare function useQuery<Query extends FunctionReference<"query">>(query: Query, ...queryArgs: OptionalRestArgsOrSkip<Query>): FunctionReturnType<Query> | undefined;
+/**
+ * Load data reactively from a paginated query to a create a growing list.
+ *
+ * This can be used to power "infinite scroll" UIs.
+ *
+ * This hook must be used with public query references that match
+ * {@link PaginatedQueryReference}.
+ *
+ * `usePaginatedQuery` concatenates all the pages of results into a single list
+ * and manages the continuation cursors when requesting more items.
+ *
+ * Example usage:
+ * ```typescript
+ * const { results, status, isLoading, loadMore } = usePaginatedQuery(
+ *   api.messages.list,
+ *   { channel: "#general" },
+ *   { initialNumItems: 5 }
+ * );
+ * ```
+ *
+ * If the query reference or arguments change, the pagination state will be reset
+ * to the first page. Similarly, if any of the pages result in an InvalidCursor
+ * error or an error associated with too much data, the pagination state will also
+ * reset to the first page.
+ *
+ * To learn more about pagination, see [Paginated Queries](https://docs.convex.dev/database/pagination).
+ *
+ * @param query - A FunctionReference to the public query function to run.
+ * @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 `endCursorBehavior` to use.
+ * @param options.endCursorBehavior` controls how the `endCursor` is set on the
+ * last loaded page. The current behavior is to have the first request for a page
+ * "pin" the end of the page to the `endCursor` returned in the first request.
+ * This shows up as your first request growing as new items are added within
+ * the range of the initial page. This is tracked via a QueryJournal, which is
+ * not shared between clients and can have unexpected behavior, so we will be
+ * deprecating this behavior in favor of the new option `setOnLoadMore`.
+ * For `setOnLoadMore`, the `endCursor` is not inferred from the first request,
+ * instead the first call to `loadMore` will explicitly set the `endCursor` to
+ * the `continueCursor` of the last page. In the future this will not use the
+ * QueryJournal and will become the default behavior, resulting in the first
+ * page staying at the same size as `initialNumItems` until you call `loadMore`.
+ * Note: setting the `endCursor` on the request will re-request that page with
+ * the new argument, causing an effectively duplicate request per `loadMore`.
+ *
+ * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
+ * items, the status of the pagination, and a `loadMore` function.
+ *
+ * @public
+ */
+export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: PaginatedQueryArgs<Query> | "skip", options: {
+    initialNumItems: number;
+    endCursorBehavior?: "setOnLoadMore" | "legacyQueryJournal";
+}): 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,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAavB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;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,iBAAiB,CAAC,EAAE,eAAe,GAAG,oBAAoB,CAAC;CAC5D,GACA,2BAA2B,CAAC,KAAK,CAAC,CAqPpC"}

package/react/cache/hooks.js

@@ -1,8 +1,8 @@
-import { ConvexProvider, useQueries as useQueriesCore } from "convex/react";
+import { ConvexProvider, useConvex, useQueries as useQueriesCore, } from "convex/react";
 import { getFunctionName } from "convex/server";
-import { useContext, useEffect, useMemo } from "react";
+import { useContext, useEffect, useMemo, useState } from "react";
 import { ConvexQueryCacheContext } from "./provider.js";
-import { convexToJson } from "convex/values";
+import { ConvexError, convexToJson, } from "convex/values";
 const uuid = typeof crypto !== "undefined" && crypto.randomUUID
     ? crypto.randomUUID.bind(crypto)
     : () => Math.random().toString(36).substring(2) +
@@ -134,3 +134,337 @@ function createQueryKey(query, args) {
     const queryKey = JSON.stringify(key);
     return queryKey;
 }
+// NOTE!: We use the same ID so it's always cached, but it can mean a split is
+// required off the bat if it's an old stale query result.
+function nextPaginationId() {
+    return 0;
+}
+const splitQuery = (key, splitCursor, continueCursor) => (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,
+    };
+};
+const completeSplitQuery = (key) => (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,
+    };
+};
+/**
+ * Load data reactively from a paginated query to a create a growing list.
+ *
+ * This can be used to power "infinite scroll" UIs.
+ *
+ * This hook must be used with public query references that match
+ * {@link PaginatedQueryReference}.
+ *
+ * `usePaginatedQuery` concatenates all the pages of results into a single list
+ * and manages the continuation cursors when requesting more items.
+ *
+ * Example usage:
+ * ```typescript
+ * const { results, status, isLoading, loadMore } = usePaginatedQuery(
+ *   api.messages.list,
+ *   { channel: "#general" },
+ *   { initialNumItems: 5 }
+ * );
+ * ```
+ *
+ * If the query reference or arguments change, the pagination state will be reset
+ * to the first page. Similarly, if any of the pages result in an InvalidCursor
+ * error or an error associated with too much data, the pagination state will also
+ * reset to the first page.
+ *
+ * To learn more about pagination, see [Paginated Queries](https://docs.convex.dev/database/pagination).
+ *
+ * @param query - A FunctionReference to the public query function to run.
+ * @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 `endCursorBehavior` to use.
+ * @param options.endCursorBehavior` controls how the `endCursor` is set on the
+ * last loaded page. The current behavior is to have the first request for a page
+ * "pin" the end of the page to the `endCursor` returned in the first request.
+ * This shows up as your first request growing as new items are added within
+ * the range of the initial page. This is tracked via a QueryJournal, which is
+ * not shared between clients and can have unexpected behavior, so we will be
+ * deprecating this behavior in favor of the new option `setOnLoadMore`.
+ * For `setOnLoadMore`, the `endCursor` is not inferred from the first request,
+ * instead the first call to `loadMore` will explicitly set the `endCursor` to
+ * the `continueCursor` of the last page. In the future this will not use the
+ * QueryJournal and will become the default behavior, resulting in the first
+ * page staying at the same size as `initialNumItems` until you call `loadMore`.
+ * Note: setting the `endCursor` on the request will re-request that page with
+ * the new argument, causing an effectively duplicate request per `loadMore`.
+ *
+ * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
+ * items, the status of the pagination, and a `loadMore` function.
+ *
+ * @public
+ */
+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 () => {
+            const id = nextPaginationId();
+            return {
+                query,
+                args: argsObject,
+                id,
+                nextPageKey: 1,
+                pageKeys: skip ? [] : [0],
+                queries: skip
+                    ? {}
+                    : {
+                        0: {
+                            query,
+                            args: {
+                                ...argsObject,
+                                paginationOpts: {
+                                    numItems: options.initialNumItems,
+                                    cursor: null,
+                                    id,
+                                },
+                            },
+                        },
+                    },
+                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 (getFunctionName(query) !== getFunctionName(state.query) ||
+        JSON.stringify(convexToJson(argsObject)) !==
+            JSON.stringify(convexToJson(state.args)) ||
+        skip !== state.skip) {
+        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" ||
+                    currResult.page.length > options.initialNumItems * 2)) {
+                // If a single page has more than double the expected number of items,
+                // or if the server requests a split, split the page into two.
+                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;
+                        let pageKeys = prevState.pageKeys;
+                        if (options.endCursorBehavior === "setOnLoadMore") {
+                            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],
+                            };
+                        }
+                        else {
+                            pageKeys = [...prevState.pageKeys, nextPageKey];
+                        }
+                        queries[nextPageKey] = {
+                            query: prevState.query,
+                            args: {
+                                ...prevState.args,
+                                paginationOpts: {
+                                    numItems,
+                                    cursor: continueCursor,
+                                    id: prevState.id,
+                                },
+                            },
+                        };
+                        nextPageKey++;
+                        return {
+                            ...prevState,
+                            pageKeys,
+                            nextPageKey,
+                            queries,
+                            ongoingSplits,
+                        };
+                    });
+                }
+            },
+        };
+    }, [maybeLastResult, currState.nextPageKey, options.endCursorBehavior]);
+    return {
+        results,
+        ...statusObject,
+    };
+}

package/react/cache/hooks.ts

@@ -1,14 +1,32 @@
-import type { OptionalRestArgsOrSkip, RequestForQueries } from "convex/react";
-import { ConvexProvider, useQueries as useQueriesCore } from "convex/react";
+import type {
+  OptionalRestArgsOrSkip,
+  PaginatedQueryArgs,
+  PaginatedQueryReference,
+  RequestForQueries,
+  UsePaginatedQueryReturnType,
+} from "convex/react";
+import {
+  ConvexProvider,
+  useConvex,
+  useQueries as useQueriesCore,
+} from "convex/react";
 import type {
   FunctionArgs,
   FunctionReference,
   FunctionReturnType,
+  PaginationOptions,
+  paginationOptsValidator,
+  PaginationResult,
 } from "convex/server";
 import { getFunctionName } from "convex/server";
-import { useContext, useEffect, useMemo } from "react";
+import { useContext, useEffect, useMemo, useState } from "react";
 import { ConvexQueryCacheContext } from "./provider.js";
-import { convexToJson } from "convex/values";
+import {
+  ConvexError,
+  convexToJson,
+  type Infer,
+  type Value,
+} from "convex/values";
 
 const uuid =
   typeof crypto !== "undefined" && crypto.randomUUID
@@ -162,3 +180,407 @@ function createQueryKey<Query extends FunctionReference<"query">>(
   const queryKey = JSON.stringify(key);
   return queryKey;
 }
+
+// NOTE!: We use the same ID so it's always cached, but it can mean a split is
+// required off the bat if it's an old stale query result.
+function nextPaginationId(): number {
+  return 0;
+}
+
+/**
+ * NOTE: The below is copied verbatim from the convex package, using the cached
+ * useQueries implementation.
+ */
+
+// Incrementing integer for each page queried in the usePaginatedQuery hook.
+type QueryPageKey = number;
+
+type UsePaginatedQueryState = {
+  query: FunctionReference<"query">;
+  args: Record<string, Value>;
+  id: number;
+  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;
+};
+
+const splitQuery =
+  (key: QueryPageKey, splitCursor: string, continueCursor: string) =>
+  (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,
+    };
+  };
+
+const completeSplitQuery =
+  (key: QueryPageKey) => (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,
+    };
+  };
+
+/**
+ * Load data reactively from a paginated query to a create a growing list.
+ *
+ * This can be used to power "infinite scroll" UIs.
+ *
+ * This hook must be used with public query references that match
+ * {@link PaginatedQueryReference}.
+ *
+ * `usePaginatedQuery` concatenates all the pages of results into a single list
+ * and manages the continuation cursors when requesting more items.
+ *
+ * Example usage:
+ * ```typescript
+ * const { results, status, isLoading, loadMore } = usePaginatedQuery(
+ *   api.messages.list,
+ *   { channel: "#general" },
+ *   { initialNumItems: 5 }
+ * );
+ * ```
+ *
+ * If the query reference or arguments change, the pagination state will be reset
+ * to the first page. Similarly, if any of the pages result in an InvalidCursor
+ * error or an error associated with too much data, the pagination state will also
+ * reset to the first page.
+ *
+ * To learn more about pagination, see [Paginated Queries](https://docs.convex.dev/database/pagination).
+ *
+ * @param query - A FunctionReference to the public query function to run.
+ * @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 `endCursorBehavior` to use.
+ * @param options.endCursorBehavior` controls how the `endCursor` is set on the
+ * last loaded page. The current behavior is to have the first request for a page
+ * "pin" the end of the page to the `endCursor` returned in the first request.
+ * This shows up as your first request growing as new items are added within
+ * the range of the initial page. This is tracked via a QueryJournal, which is
+ * not shared between clients and can have unexpected behavior, so we will be
+ * deprecating this behavior in favor of the new option `setOnLoadMore`.
+ * For `setOnLoadMore`, the `endCursor` is not inferred from the first request,
+ * instead the first call to `loadMore` will explicitly set the `endCursor` to
+ * the `continueCursor` of the last page. In the future this will not use the
+ * QueryJournal and will become the default behavior, resulting in the first
+ * page staying at the same size as `initialNumItems` until you call `loadMore`.
+ * Note: setting the `endCursor` on the request will re-request that page with
+ * the new argument, causing an effectively duplicate request per `loadMore`.
+ *
+ * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
+ * items, the status of the pagination, and a `loadMore` function.
+ *
+ * @public
+ */
+export function usePaginatedQuery<Query extends PaginatedQueryReference>(
+  query: Query,
+  args: PaginatedQueryArgs<Query> | "skip",
+  options: {
+    initialNumItems: number;
+    endCursorBehavior?: "setOnLoadMore" | "legacyQueryJournal";
+  },
+): 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 () => {
+      const id = nextPaginationId();
+      return {
+        query,
+        args: argsObject as Record<string, Value>,
+        id,
+        nextPageKey: 1,
+        pageKeys: skip ? [] : [0],
+        queries: skip
+          ? ({} as UsePaginatedQueryState["queries"])
+          : {
+              0: {
+                query,
+                args: {
+                  ...argsObject,
+                  paginationOpts: {
+                    numItems: options.initialNumItems,
+                    cursor: null,
+                    id,
+                  },
+                },
+              },
+            },
+        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 (
+    getFunctionName(query) !== getFunctionName(state.query) ||
+    JSON.stringify(convexToJson(argsObject as Value)) !==
+      JSON.stringify(convexToJson(state.args)) ||
+    skip !== state.skip
+  ) {
+    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" ||
+          currResult.page.length > options.initialNumItems * 2)
+      ) {
+        // If a single page has more than double the expected number of items,
+        // or if the server requests a split, split the page into two.
+        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;
+            let pageKeys = prevState.pageKeys;
+            if (options.endCursorBehavior === "setOnLoadMore") {
+              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],
+              };
+            } else {
+              pageKeys = [...prevState.pageKeys, nextPageKey];
+            }
+            queries[nextPageKey] = {
+              query: prevState.query,
+              args: {
+                ...prevState.args,
+                paginationOpts: {
+                  numItems,
+                  cursor: continueCursor,
+                  id: prevState.id,
+                },
+              },
+            };
+            nextPageKey++;
+            return {
+              ...prevState,
+              pageKeys,
+              nextPageKey,
+              queries,
+              ongoingSplits,
+            };
+          });
+        }
+      },
+    } as const;
+  }, [maybeLastResult, currState.nextPageKey, options.endCursorBehavior]);
+
+  return {
+    results,
+    ...statusObject,
+  };
+}

package/react/cache.d.ts

@@ -1,3 +1,3 @@
 export { ConvexQueryCacheProvider } from "./cache/provider.js";
-export { useQuery, useQueries } from "./cache/hooks.js";
+export { useQuery, useQueries, usePaginatedQuery } from "./cache/hooks.js";
 //# sourceMappingURL=cache.d.ts.map

package/react/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/react/cache.js

@@ -1,2 +1,2 @@
 export { ConvexQueryCacheProvider } from "./cache/provider.js";
-export { useQuery, useQueries } from "./cache/hooks.js";
+export { useQuery, useQueries, usePaginatedQuery } from "./cache/hooks.js";

package/react/cache.ts

@@ -1,2 +1,2 @@
 export { ConvexQueryCacheProvider } from "./cache/provider.js";
-export { useQuery, useQueries } from "./cache/hooks.js";
+export { useQuery, useQueries, usePaginatedQuery } from "./cache/hooks.js";

package/server/migrations.d.ts

@@ -116,8 +116,8 @@ export declare const migrationsTable: import("convex/server").TableDefinition<im
     latestEnd?: number | undefined;
     cursor: string | null;
     name: string;
-    table: string;
     isDone: boolean;
+    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" | "table" | "isDone" | "workerId" | "processed" | "latestStart" | "latestEnd">, {
+}, "required", "cursor" | "name" | "isDone" | "table" | "workerId" | "processed" | "latestStart" | "latestEnd">, {
     name: ["name", "_creationTime"];
 }, {}, {}>;
 declare const migrationArgs: {
@@ -284,8 +284,8 @@ export declare function cancelMigration<DataModel extends GenericDataModel>(ctx:
     latestEnd?: number | undefined;
     cursor: string | null;
     name: string;
-    table: string;
     isDone: boolean;
+    table: string;
     processed: number;
     latestStart: number;
 } | {
@@ -294,8 +294,8 @@ export declare function cancelMigration<DataModel extends GenericDataModel>(ctx:
     latestEnd?: number | undefined;
     cursor: string | null;
     name: string;
-    table: string;
     isDone: boolean;
+    table: string;
     processed: number;
     latestStart: number;
 }>;

package/server/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["stream.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["stream.ts"],"names":[],"mappings":"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"}

package/server/stream.js

@@ -22,7 +22,9 @@ function makeExclusive(boundType) {
  * 2. q.eq("f1", 1).gt("f2", 2).lt("f2", 3)
  * 3. q.eq("f1", 1).eq("f2", 3).lte("f3", 2)
  */
-function splitRange(indexFields, startBound, endBound, startBoundType, endBoundType) {
+function splitRange(indexFields, 
+// For descending queries, the resulting queries are reversed.
+order, startBound, endBound, startBoundType, endBoundType) {
     // Three parts to the split:
     // 1. reduce down from startBound to common prefix
     // 2. range with common prefix
@@ -79,7 +81,11 @@ function splitRange(indexFields, startBound, endBound, startBoundType, endBoundT
         middleRange.push([startBoundType, indexFields[0], startValue]);
         middleRange.push([endBoundType, indexFields[0], endValue]);
     }
-    return [...startRanges, middleRange, ...endRanges];
+    const ranges = [...startRanges, middleRange, ...endRanges];
+    if (order === "desc") {
+        ranges.reverse();
+    }
+    return ranges;
 }
 function rangeToQuery(range) {
     return (q) => {
@@ -226,6 +232,18 @@ class QueryStream {
         throw new Error("Cannot call .filter on query stream. use .filterWith instead.");
     }
     async paginate(opts) {
+        if (opts.numItems === 0) {
+            if (opts.cursor === null) {
+                throw new Error(".paginate called with cursor of null and 0 for numItems. " +
+                    "This is not supported, as null is not a valid continueCursor. " +
+                    "Advice: avoid calling paginate entirely in these cases.");
+            }
+            return {
+                page: [],
+                isDone: false,
+                continueCursor: opts.cursor,
+            };
+        }
         const order = this.getOrder();
         let newStartKey = {
             key: [],
@@ -242,7 +260,7 @@ class QueryStream {
             inclusive: true,
         };
         const maxRowsToRead = opts.maximumRowsRead;
-        const softMaxRowsToRead = maxRowsToRead ? (3 * maxRowsToRead) / 4 : 1000;
+        const softMaxRowsToRead = opts.numItems + 1;
         let maxRows = opts.numItems;
         if (opts.endCursor) {
             newEndKey = {
@@ -545,14 +563,11 @@ export class OrderedStreamQuery extends StreamableQuery {
  */
 export function streamIndexRange(db, schema, table, index, bounds, order) {
     const indexFields = getIndexFields(table, index, schema);
-    const splitBounds = splitRange(indexFields, bounds.lowerBound, bounds.upperBound, bounds.lowerBoundInclusive ? "gte" : "gt", bounds.upperBoundInclusive ? "lte" : "lt");
-    const subQueries = [];
-    for (const splitBound of splitBounds) {
-        subQueries.push(stream(db, schema)
-            .query(table)
-            .withIndex(index, rangeToQuery(splitBound))
-            .order(order));
-    }
+    const splitBounds = splitRange(indexFields, order, bounds.lowerBound, bounds.upperBound, bounds.lowerBoundInclusive ? "gte" : "gt", bounds.upperBoundInclusive ? "lte" : "lt");
+    const subQueries = splitBounds.map((splitBound) => stream(db, schema)
+        .query(table)
+        .withIndex(index, rangeToQuery(splitBound))
+        .order(order));
     return new ConcatStreams(...subQueries);
 }
 class ReflectIndexRange {

package/server/stream.ts

@@ -52,6 +52,8 @@ type Bound = ["gt" | "lt" | "gte" | "lte" | "eq", string, Value];
  */
 function splitRange(
   indexFields: string[],
+  // For descending queries, the resulting queries are reversed.
+  order: "asc" | "desc",
   startBound: IndexKey,
   endBound: IndexKey,
   startBoundType: "gt" | "lt" | "gte" | "lte",
@@ -116,7 +118,11 @@ function splitRange(
     middleRange.push([startBoundType, indexFields[0]!, startValue]);
     middleRange.push([endBoundType, indexFields[0]!, endValue]);
   }
-  return [...startRanges, middleRange, ...endRanges];
+  const ranges = [...startRanges, middleRange, ...endRanges];
+  if (order === "desc") {
+    ranges.reverse();
+  }
+  return ranges;
 }
 
 function rangeToQuery(range: Bound[]) {
@@ -321,6 +327,20 @@ abstract class QueryStream<T extends GenericStreamItem>
       maximumRowsRead?: number;
     },
   ): Promise<PaginationResult<T>> {
+    if (opts.numItems === 0) {
+      if (opts.cursor === null) {
+        throw new Error(
+          ".paginate called with cursor of null and 0 for numItems. " +
+            "This is not supported, as null is not a valid continueCursor. " +
+            "Advice: avoid calling paginate entirely in these cases.",
+        );
+      }
+      return {
+        page: [],
+        isDone: false,
+        continueCursor: opts.cursor,
+      };
+    }
     const order = this.getOrder();
     let newStartKey = {
       key: [] as IndexKey,
@@ -337,7 +357,7 @@ abstract class QueryStream<T extends GenericStreamItem>
       inclusive: true,
     };
     const maxRowsToRead = opts.maximumRowsRead;
-    const softMaxRowsToRead = maxRowsToRead ? (3 * maxRowsToRead) / 4 : 1000;
+    const softMaxRowsToRead = opts.numItems + 1;
     let maxRows: number | undefined = opts.numItems;
     if (opts.endCursor) {
       newEndKey = {
@@ -821,20 +841,18 @@ export function streamIndexRange<
   const indexFields = getIndexFields(table, index, schema);
   const splitBounds = splitRange(
     indexFields,
+    order,
     bounds.lowerBound,
     bounds.upperBound,
     bounds.lowerBoundInclusive ? "gte" : "gt",
     bounds.upperBoundInclusive ? "lte" : "lt",
   );
-  const subQueries: OrderedStreamQuery<Schema, T, IndexName>[] = [];
-  for (const splitBound of splitBounds) {
-    subQueries.push(
-      stream(db, schema)
-        .query(table)
-        .withIndex(index, rangeToQuery(splitBound))
-        .order(order),
-    );
-  }
+  const subQueries = splitBounds.map((splitBound) =>
+    stream(db, schema)
+      .query(table)
+      .withIndex(index, rangeToQuery(splitBound))
+      .order(order),
+  );
   return new ConcatStreams(...subQueries);
 }