convex 1.36.0 → 1.37.0

package/src/react/use_paginated_query.test.tsx

@@ -22,9 +22,9 @@ import type {
   PaginatedQueryArgs,
   PaginatedQueryItem,
   PaginatedQueryReference,
-  UsePaginatedQueryObjectReturnType,
   UsePaginatedQueryReturnType,
 } from "./use_paginated_query.js";
+import type { UsePaginatedQueryObjectReturnType } from "./use_paginated_query2.js";
 import {
   resetPaginationId,
   usePaginatedQuery,
@@ -76,7 +76,9 @@ describe.each([
     version: "client-based logic" as const,
   },
 ] as {
-  usePaginatedQuery: typeof usePaginatedQuery;
+  usePaginatedQuery:
+    | typeof usePaginatedQuery
+    | typeof usePaginatedQuery_experimental;
   resetPaginationId: typeof resetPaginationId;
   version: "hook-based logic" | "client-based logic";
 }[])(
@@ -161,67 +163,6 @@ describe.each([
       });
     }
 
-    test("Object options default to non-throwing error state", () => {
-      if (version === "client-based logic") {
-        return;
-      }
-      const convexClient = new ConvexReactClient(address);
-      resetPaginationId();
-      const wrapper = ({ children }: { children: React.ReactNode }) => (
-        <ConvexProvider client={convexClient}>{children}</ConvexProvider>
-      );
-
-      const { result } = renderHook(
-        () =>
-          usePaginatedQuery({
-            query: makeFunctionReference<"query">("myQuery"),
-            args: {},
-            initialNumItems: 10,
-          }),
-        { wrapper },
-      );
-
-      pushFirstPageError(convexClient, "boom-default");
-
-      if (result.current.status !== "error") {
-        throw new Error("Expected error status");
-      }
-      expect(result.current.error.message).toBe("boom-default");
-      expect(result.current.isLoading).toBe(false);
-      expect(result.current.canLoadMore).toBe(false);
-      expect(result.current.data).toEqual([]);
-    });
-
-    test("Object options throw when throwOnError is true", () => {
-      if (version === "client-based logic") {
-        return;
-      }
-      const convexClient = new ConvexReactClient(address);
-      resetPaginationId();
-      let lastError: Error | undefined;
-      const wrapper = ({ children }: { children: React.ReactNode }) => (
-        <ErrorBoundary onError={(e) => (lastError = e)}>
-          <ConvexProvider client={convexClient}>{children}</ConvexProvider>
-        </ErrorBoundary>
-      );
-
-      renderHook(
-        () =>
-          usePaginatedQuery({
-            query: makeFunctionReference<"query">("myQuery"),
-            args: {},
-            initialNumItems: 10,
-            throwOnError: true,
-          }),
-        { wrapper },
-      );
-
-      pushFirstPageError(convexClient, "boom-throw");
-
-      expect(lastError).toBeDefined();
-      expect(lastError?.message).toBe("boom-throw");
-    });
-
     test("Positional form continues throwing on errors", () => {
       if (version === "client-based logic") {
         return;
@@ -279,75 +220,6 @@ describe.each([
       });
     });
 
-    test("Returns nothing when object-form args are 'skip'", () => {
-      const convexClient = new ConvexReactClient(address);
-      // The experimental path subscribes through watchPaginatedQuery directly,
-      // while the original implementation still goes through watchQuery.
-      const subscriptionSpy =
-        version === "hook-based logic"
-          ? vi.spyOn(convexClient, "watchQuery")
-          : vi.spyOn(convexClient, "watchPaginatedQuery");
-      const wrapper = ({ children }: { children: React.ReactNode }) => (
-        <ConvexProvider client={convexClient}>{children}</ConvexProvider>
-      );
-
-      const { result } = renderHook(
-        () =>
-          usePaginatedQuery({
-            query: makeFunctionReference<"query">("myQuery"),
-            args: "skip",
-            initialNumItems: 10,
-          }),
-        { wrapper },
-      );
-
-      expect(subscriptionSpy.mock.calls).toEqual([]);
-      expect(result.current).toMatchObject({
-        isLoading: true,
-        data: undefined,
-        status: "pending",
-        canLoadMore: false,
-      });
-    });
-
-    test("Initially returns pending for object options", () => {
-      const convexClient = new ConvexReactClient(address);
-      const watchQuerySpy = vi.spyOn(convexClient, "watchQuery");
-      const wrapper = ({ children }: { children: React.ReactNode }) => (
-        <ConvexProvider client={convexClient}>{children}</ConvexProvider>
-      );
-
-      const { result } = renderHook(
-        () =>
-          usePaginatedQuery({
-            query: makeFunctionReference<"query">("myQuery"),
-            args: {},
-            initialNumItems: 10,
-          }),
-        { wrapper },
-      );
-
-      if (version === "hook-based logic") {
-        expect(watchQuerySpy.mock.calls[1]).toEqual([
-          makeFunctionReference("myQuery"),
-          {
-            paginationOpts: {
-              cursor: null,
-              id: expect.anything(),
-              numItems: 10,
-            },
-          },
-          { journal: undefined },
-        ]);
-      }
-      expect(result.current).toMatchObject({
-        isLoading: true,
-        data: undefined,
-        status: "pending",
-        canLoadMore: false,
-      });
-    });
-
     test("Initially returns LoadingFirstPage", () => {
       const convexClient = new ConvexReactClient(address);
       const watchQuerySpy = vi.spyOn(convexClient, "watchQuery");
@@ -1335,3 +1207,214 @@ describe.each([
     });
   },
 );
+
+describe("usePaginatedQuery_experimental object form", () => {
+  test("Returns nothing when object-form args are 'skip'", () => {
+    const convexClient = new ConvexReactClient(address);
+    const subscriptionSpy = vi.spyOn(convexClient, "watchPaginatedQuery");
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <ConvexProvider client={convexClient}>{children}</ConvexProvider>
+    );
+
+    const { result } = renderHook(
+      () =>
+        usePaginatedQuery_experimental({
+          query: makeFunctionReference<"query">("myQuery"),
+          args: "skip",
+          initialNumItems: 10,
+        }),
+      { wrapper },
+    );
+
+    expect(subscriptionSpy.mock.calls).toEqual([]);
+    expect(result.current).toMatchObject({
+      isLoading: true,
+      data: undefined,
+      status: "pending",
+      canLoadMore: false,
+    });
+  });
+
+  test("Initially returns pending for object options", () => {
+    const convexClient = new ConvexReactClient(address);
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <ConvexProvider client={convexClient}>{children}</ConvexProvider>
+    );
+
+    const { result } = renderHook(
+      () =>
+        usePaginatedQuery_experimental({
+          query: makeFunctionReference<"query">("myQuery"),
+          args: {},
+          initialNumItems: 10,
+        }),
+      { wrapper },
+    );
+
+    expect(result.current).toMatchObject({
+      isLoading: true,
+      data: undefined,
+      status: "pending",
+      canLoadMore: false,
+    });
+  });
+
+  describe("object form with data", () => {
+    let client: ConvexReactClient;
+    const query: FunctionReference<"query"> = makeFunctionReference("myQuery");
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <ConvexProvider client={client}>{children}</ConvexProvider>
+    );
+
+    const mockPage = (
+      opts: PaginationOptions,
+      retval: PaginationResult<unknown>,
+    ) => {
+      act(() => {
+        void client.mutation(
+          anyApi.myMutation.default,
+          {},
+          {
+            optimisticUpdate: (localStore) => {
+              localStore.setQuery(
+                anyApi.myQuery.default,
+                {
+                  paginationOpts: { ...opts, id: 1 },
+                },
+                retval,
+              );
+            },
+          },
+        );
+      });
+    };
+
+    beforeEach(() => {
+      client = new ConvexReactClient(address);
+      resetPaginatedId2();
+    });
+
+    test("returns success with data for a single exhausted page", () => {
+      const { result } = renderHook(
+        () =>
+          usePaginatedQuery_experimental({
+            query,
+            args: {},
+            initialNumItems: 5,
+          }),
+        { wrapper },
+      );
+
+      expect(result.current.status).toBe("pending");
+
+      mockPage(
+        { numItems: 5, cursor: null },
+        { page: ["a", "b", "c"], continueCursor: "end", isDone: true },
+      );
+
+      expect(result.current).toMatchObject({
+        status: "success",
+        data: ["a", "b", "c"],
+        canLoadMore: false,
+        isLoading: false,
+        error: undefined,
+      });
+    });
+
+    test("returns success with canLoadMore true when more pages exist", () => {
+      const { result } = renderHook(
+        () =>
+          usePaginatedQuery_experimental({
+            query,
+            args: {},
+            initialNumItems: 2,
+          }),
+        { wrapper },
+      );
+
+      mockPage(
+        { numItems: 2, cursor: null },
+        { page: ["item1", "item2"], continueCursor: "cur1", isDone: false },
+      );
+
+      expect(result.current).toMatchObject({
+        status: "success",
+        data: ["item1", "item2"],
+        canLoadMore: true,
+        isLoading: false,
+        error: undefined,
+      });
+    });
+
+    test("loadMore appends data and transitions to exhausted", () => {
+      const { result } = renderHook(
+        () =>
+          usePaginatedQuery_experimental({
+            query,
+            args: {},
+            initialNumItems: 1,
+          }),
+        { wrapper },
+      );
+
+      mockPage(
+        { numItems: 1, cursor: null },
+        { page: ["first"], continueCursor: "abc", isDone: false },
+      );
+
+      expect(result.current).toMatchObject({
+        status: "success",
+        data: ["first"],
+        canLoadMore: true,
+      });
+
+      mockPage(
+        { numItems: 2, cursor: "abc" },
+        { page: ["second"], continueCursor: "def", isDone: true },
+      );
+      act(() => {
+        result.current.loadMore(2);
+      });
+
+      expect(result.current).toMatchObject({
+        status: "success",
+        data: ["first", "second"],
+        canLoadMore: false,
+        isLoading: false,
+      });
+    });
+
+    test("page updates reflect in data", () => {
+      const { result } = renderHook(
+        () =>
+          usePaginatedQuery_experimental({
+            query,
+            args: {},
+            initialNumItems: 5,
+          }),
+        { wrapper },
+      );
+
+      mockPage(
+        { numItems: 5, cursor: null },
+        { page: ["old"], continueCursor: "c1", isDone: true },
+      );
+
+      expect(result.current).toMatchObject({
+        status: "success",
+        data: ["old"],
+      });
+
+      mockPage(
+        { numItems: 5, cursor: null },
+        { page: ["new1", "new2"], continueCursor: "c2", isDone: true },
+      );
+
+      expect(result.current).toMatchObject({
+        status: "success",
+        data: ["new1", "new2"],
+        canLoadMore: false,
+      });
+    });
+  });
+});

package/src/react/use_paginated_query.ts

@@ -35,23 +35,6 @@ export type PaginatedQueryReference = FunctionReference<
   PaginationResult<any>
 >;
 
-/**
- * Options for object-form {@link usePaginatedQuery}.
- *
- * @internal
- */
-export type UsePaginatedQueryOptions<Query extends PaginatedQueryReference> = {
-  query: Query;
-  args: PaginatedQueryArgs<Query> | "skip";
-  initialNumItems: number;
-  /**
-   * When `true` (default for positional form), errors are thrown and caught
-   * by an error boundary. When `false` (default for object form), errors are
-   * returned as `{ status: "Error", error: Error }` instead of being thrown.
-   */
-  throwOnError?: boolean;
-};
-
 // Incrementing integer for each page queried in the usePaginatedQuery hook.
 type QueryPageKey = number;
 
@@ -182,56 +165,18 @@ export function usePaginatedQuery<Query extends PaginatedQueryReference>(
   options: { initialNumItems: number },
 ): UsePaginatedQueryReturnType<Query>;
 
-/**
- * Load data reactively from a paginated query using an options object.
- *
- * @param options - Object-form options for the paginated query.
- * @returns An object with `data`, `status`, `canLoadMore`, `isLoading`,
- * `error`, and `loadMore`. `status` is `"pending"` while loading,
- * `"success"` when data is available, or `"error"` if the query threw.
- * `canLoadMore` is `true` only when idle and more pages exist.
- *
- * @internal
- */
-export function usePaginatedQuery<Query extends PaginatedQueryReference>(
-  options: UsePaginatedQueryOptions<Query>,
-): UsePaginatedQueryObjectReturnType<Query>;
-
 export function usePaginatedQuery<Query extends PaginatedQueryReference>(
-  queryOrOptions: Query | UsePaginatedQueryOptions<Query>,
-  args?: PaginatedQueryArgs<Query> | "skip",
-  options?: { initialNumItems: number },
-):
-  | UsePaginatedQueryReturnType<Query>
-  | UsePaginatedQueryObjectReturnType<Query> {
-  const isObjectOptions =
-    typeof queryOrOptions === "object" &&
-    queryOrOptions !== null &&
-    "query" in queryOrOptions;
-
-  const query = isObjectOptions ? queryOrOptions.query : queryOrOptions;
-  const queryArgs = isObjectOptions ? queryOrOptions.args : args;
-  const throwOnError = isObjectOptions
-    ? (queryOrOptions.throwOnError ?? false)
-    : true;
-  const initialOptions = isObjectOptions
-    ? { initialNumItems: queryOrOptions.initialNumItems }
-    : options;
-
+  query: Query,
+  args: PaginatedQueryArgs<Query> | "skip",
+  options: { initialNumItems: number },
+): UsePaginatedQueryReturnType<Query> {
   const { user: positionalResult } = usePaginatedQueryInternal(
     query,
-    queryArgs as PaginatedQueryArgs<Query> | "skip",
-    initialOptions as { initialNumItems: number },
-    throwOnError,
+    args,
+    options,
+    true,
   );
-
-  if (!isObjectOptions) {
-    return positionalResult as unknown as UsePaginatedQueryReturnType<Query>;
-  }
-
-  return reshapeToObjectForm(
-    positionalResult,
-  ) as unknown as UsePaginatedQueryObjectReturnType<Query>;
+  return positionalResult as unknown as UsePaginatedQueryReturnType<Query>;
 }
 
 /** @internal */
@@ -504,48 +449,6 @@ export function usePaginatedQueryInternal<
   };
 }
 
-/**
- * Reshape the internal TitleCase pagination result into the object-form
- * return type with lowercase `status`, `canLoadMore`, and `data`.
- */
-function reshapeToObjectForm<Item>(
-  internal: UsePaginatedQueryInternalResult<Item>,
-) {
-  const { results, loadMore } = internal;
-  if (internal.status === "Error" && "error" in internal) {
-    return {
-      data: results,
-      status: "error" as const,
-      canLoadMore: false as const,
-      isLoading: false as const,
-      error: internal.error,
-      loadMore,
-    };
-  }
-  if (
-    internal.status === "LoadingFirstPage" ||
-    internal.status === "LoadingMore"
-  ) {
-    return {
-      data: internal.status === "LoadingFirstPage" ? undefined : results,
-      status: "pending" as const,
-      canLoadMore: false as const,
-      isLoading: true as const,
-      error: undefined,
-      loadMore,
-    };
-  }
-  // CanLoadMore or Exhausted
-  return {
-    data: results,
-    status: "success" as const,
-    canLoadMore: internal.status === "CanLoadMore",
-    isLoading: false as const,
-    error: undefined,
-    loadMore,
-  };
-}
-
 let paginationId = 0;
 /**
  * Generate a new, unique ID for a pagination session.
@@ -669,43 +572,6 @@ export type PaginatedQueryItem<Query extends PaginatedQueryReference> =
 export type UsePaginatedQueryReturnType<Query extends PaginatedQueryReference> =
   UsePaginatedQueryResult<PaginatedQueryItem<Query>>;
 
-/**
- * Return type of the object-form {@link usePaginatedQuery} overload.
- *
- * Uses lowercase query status (`"pending" | "success" | "error"`) and a
- * `canLoadMore` boolean instead of the TitleCase pagination status strings
- * used by the positional form.
- *
- * @internal
- */
-export type UsePaginatedQueryObjectReturnType<
-  Query extends PaginatedQueryReference,
-> =
-  | {
-      data: PaginatedQueryItem<Query>[] | undefined;
-      status: "pending";
-      canLoadMore: false;
-      isLoading: true;
-      error: undefined;
-      loadMore: (numItems: number) => void;
-    }
-  | {
-      data: PaginatedQueryItem<Query>[];
-      status: "success";
-      canLoadMore: boolean;
-      isLoading: false;
-      error: undefined;
-      loadMore: (numItems: number) => void;
-    }
-  | {
-      data: PaginatedQueryItem<Query>[];
-      status: "error";
-      canLoadMore: false;
-      isLoading: false;
-      error: Error;
-      loadMore: (numItems: number) => void;
-    };
-
 /**
  * Optimistically update the values in a paginated list.
  *

package/src/react/use_paginated_query2.ts

@@ -4,9 +4,8 @@ import { FunctionReference, getFunctionName } from "../server/api.js";
 import {
   PaginatedQueryReference,
   PaginatedQueryArgs,
-  UsePaginatedQueryOptions,
+  PaginatedQueryItem,
   UsePaginatedQueryReturnType,
-  UsePaginatedQueryObjectReturnType,
 } from "./use_paginated_query.js";
 import { convexToJson, Value } from "../values/value.js";
 import { useQueries } from "./use_queries.js";
@@ -15,6 +14,66 @@ import { SubscribeToPaginatedQueryOptions } from "../browser/sync/paginated_quer
 import { ConvexError } from "../values/errors.js";
 import { useConvex } from "./client.js";
 
+/**
+ * Options for object-form {@link usePaginatedQuery_experimental}.
+ *
+ * @public
+ */
+export type UsePaginatedQueryOptions<
+  Query extends PaginatedQueryReference,
+  ThrowOnError extends boolean = false,
+> = {
+  query: Query;
+  args: PaginatedQueryArgs<Query> | "skip";
+  initialNumItems: number;
+  /**
+   * When `true` (default for positional form), errors are thrown and caught
+   * by an error boundary. When `false` (default for object form), errors are
+   * returned as `{ status: "Error", error: Error }` instead of being thrown.
+   */
+  throwOnError?: ThrowOnError;
+};
+
+/**
+ * Return type of the object-form {@link usePaginatedQuery_experimental} overload.
+ *
+ * Uses lowercase query status (`"pending" | "success" | "error"`) and a
+ * `canLoadMore` boolean instead of the TitleCase pagination status strings
+ * used by the positional form.
+ *
+ * @public
+ */
+export type UsePaginatedQueryObjectReturnType<
+  Query extends PaginatedQueryReference,
+  ThrowOnError extends boolean = false,
+> =
+  | {
+      data: PaginatedQueryItem<Query>[] | undefined;
+      status: "pending";
+      canLoadMore: false;
+      isLoading: true;
+      error: undefined;
+      loadMore: (numItems: number) => void;
+    }
+  | {
+      data: PaginatedQueryItem<Query>[];
+      status: "success";
+      canLoadMore: boolean;
+      isLoading: false;
+      error: undefined;
+      loadMore: (numItems: number) => void;
+    }
+  | (ThrowOnError extends true
+      ? never
+      : {
+          data: PaginatedQueryItem<Query>[];
+          status: "error";
+          canLoadMore: false;
+          isLoading: false;
+          error: Error;
+          loadMore: (numItems: number) => void;
+        });
+
 type UsePaginatedQueryState = {
   query: FunctionReference<"query">;
   args: Record<string, Value>;
@@ -83,12 +142,26 @@ export function usePaginatedQuery_experimental<
   options: { initialNumItems: number },
 ): UsePaginatedQueryReturnType<Query>;
 
-/** @internal */
+/**
+ * Experimental new usePaginatedQuery implementation that accepts an options object
+ * rather than positional arguments.
+ *
+ * @param options - A {@link UsePaginatedQueryOptions} object including `query` and `args`.
+ * @returns A {@link UsePaginatedQueryObjectReturnType} object with `data`, `status`,
+ * `canLoadMore`, `isLoading`, `error`, and `loadMore`. `status` is `"pending"` while
+ * loading, `"success"` when data is available, or `"error"` if the query threw.
+ * When `throwOnError` is `true`, the `"error"` status is excluded from the return
+ * type since errors will be thrown instead.
+ * `canLoadMore` is `true` only when idle and more pages exist.
+ *
+ * @public
+ */
 export function usePaginatedQuery_experimental<
   Query extends PaginatedQueryReference,
+  ThrowOnError extends boolean = false,
 >(
-  options: UsePaginatedQueryOptions<Query>,
-): UsePaginatedQueryObjectReturnType<Query>;
+  options: UsePaginatedQueryOptions<Query, ThrowOnError>,
+): UsePaginatedQueryObjectReturnType<Query, ThrowOnError>;
 
 export function usePaginatedQuery_experimental<
   Query extends PaginatedQueryReference,