Add object-form useQuery overload with result state and throwOnError (#47801)

Adds an object-form overload to `useQuery` that accepts `{ query, args, throwOnError? }` and returns a `UseQueryResult<T>` discriminated union (`success | error | pending`).

- Renames `ConvexQueryOptions` → `QueryOptions`, moves `extendSubscriptionFor` off the shared type so the base is just `{ query, args }`.
- Adds `parseArgs` validation for object-form args.
- Includes type tests and runtime tests.

Stack: 1/6
GitOrigin-RevId: d7713b83577189447ae16e35add2dd1af0fe513c

Author: robelest

src/browser/index.ts

@@ -40,3 +40,6 @@ export type { QueryJournal } from "./sync/protocol.js";
 /** @internal */
 export type { UserIdentityAttributes } from "./sync/protocol.js";
 export type { FunctionResult } from "./sync/function_result.js";
+/** @internal */
+export { convexQueryOptions } from "./query_options.js";
+export type { QueryOptions } from "./query_options.js";

src/browser/query_options.test.ts

@@ -1,7 +1,6 @@
 import { test } from "vitest";
 import { makeFunctionReference } from "../server/index.js";
 import { EmptyObject } from "../server/registration.js";
-import { ConvexReactClient } from "../react/client.js";
 import { convexQueryOptions } from "./query_options.js";
 
 const apiQueryFuncWithArgs = makeFunctionReference<
@@ -42,11 +41,3 @@ test("convexQueryOptions", async () => {
     args: { name: "hey" },
   });
 });
-
-test("prewarmQuery types", async () => {
-  const client = {
-    prewarmQuery: () => {},
-  } as unknown as ConvexReactClient;
-
-  client.prewarmQuery({ query: apiQueryFuncWithArgs, args: { name: "hi" } });
-});

src/browser/query_options.ts

@@ -1,26 +1,47 @@
-/**
- * Query options are a potential new API for a variety of functions, but in particular a new overload of the React hook for queries.
- *
- * Inspired by https://tanstack.com/query/v5/docs/framework/react/guides/query-options
- */
+// Inspired by https://tanstack.com/query/v5/docs/framework/react/guides/query-options
 import type { FunctionArgs, FunctionReference } from "../server/api.js";
 
-// TODO if this type can encompass all use cases we can add not requiring args for queries
-// that don't take arguments. Goal would be that queryOptions allows leaving out args,
-// but queryOptions returns an object that always contains args. Helpers, "middleware,"
-// anything that intercepts these arguments
 /**
- * Query options.
+ * Options for a Convex query: the query function reference and its arguments.
+ *
+ * Used with the object-form overload of {@link useQuery}.
+ *
+ * @public
  */
-export type ConvexQueryOptions<Query extends FunctionReference<"query">> = {
+export type QueryOptions<Query extends FunctionReference<"query">> = {
+  /**
+   * The query function to run.
+   */
   query: Query;
+  /**
+   * The arguments to the query function.
+   */
   args: FunctionArgs<Query>;
-  extendSubscriptionFor?: number;
 };
 
-// This helper helps more once we have more inference happening.
+/**
+ * Creates a type-safe {@link QueryOptions} object for a Convex query.
+ *
+ * This is an identity function that exists to provide type inference — passing
+ * your query and args through this helper ensures TypeScript infers the correct
+ * `Query` type parameter, which enables precise return types on hooks like
+ * {@link useQuery}.
+ *
+ * ```typescript
+ * const opts = convexQueryOptions({
+ *   query: api.users.getById,
+ *   args: { id: userId },
+ * });
+ * // opts is typed as QueryOptions<typeof api.users.getById>
+ * client.prewarmQuery(opts);
+ * ```
+ *
+ * @param options - The query and its arguments.
+ * @returns The same object, typed as `QueryOptions<Query>`.
+ * @internal
+ */
 export function convexQueryOptions<Query extends FunctionReference<"query">>(
-  options: ConvexQueryOptions<Query>,
-): ConvexQueryOptions<Query> {
+  options: QueryOptions<Query>,
+): QueryOptions<Query> {
   return options;
 }

src/cli/codegen_templates/readme.ts

@@ -37,7 +37,20 @@ export const myQueryFunction = query({
 Using this query function in a React component looks like:
 
 \`\`\`ts
-const data = useQuery(api.myFunctions.myQueryFunction, { first: 10, second: "hello" });
+const state = useQuery({
+  query: api.myFunctions.myQueryFunction,
+  args: { first: 10, second: "hello" },
+});
+
+if (state.status === "pending") {
+  return <div>Loading...</div>;
+}
+
+if (state.status === "error") {
+  return <div>Error: {state.error.message}</div>;
+}
+
+const data = state.data;
 \`\`\`
 
 

src/react/client.test.tsx

@@ -5,6 +5,7 @@ import { test, expect, describe, vi } from "vitest";
 import ws from "ws";
 
 import { ConvexReactClient, createMutation, useQuery } from "./client.js";
+import { convexQueryOptions } from "../browser/query_options.js";
 import { ConvexProvider } from "./index.js";
 import React from "react";
 import { renderHook } from "@testing-library/react";
@@ -113,6 +114,46 @@ describe("useQuery", () => {
     expect(result.current).toStrictEqual(undefined);
   });
 
+  test("object form returns success result", () => {
+    const client = createClientWithQuery();
+    const wrapper = ({ children }: any) => (
+      <ConvexProvider client={client}>{children}</ConvexProvider>
+    );
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          query: anyApi.myQuery.default,
+          args: {},
+        }),
+      { wrapper },
+    );
+    expect(result.current).toStrictEqual({
+      data: "queryResult",
+      error: undefined,
+      status: "success",
+    });
+  });
+
+  test("object form returns pending when skipped", () => {
+    const client = createClientWithQuery();
+    const wrapper = ({ children }: any) => (
+      <ConvexProvider client={client}>{children}</ConvexProvider>
+    );
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          query: anyApi.myQuery.default,
+          args: "skip",
+        }),
+      { wrapper },
+    );
+    expect(result.current).toStrictEqual({
+      data: undefined,
+      error: undefined,
+      status: "pending",
+    });
+  });
+
   test("Optimistic update handlers can’t be async", () => {
     const client = testConvexReactClient();
     const mutation = createMutation(
@@ -192,3 +233,27 @@ describe("async query fetch", () => {
     expect(await queryResult).toStrictEqual("queryResult");
   });
 });
+
+describe("prewarmQuery types", () => {
+  test("accepts QueryOptions shape", () => {
+    const client = testConvexReactClient();
+    const opts = convexQueryOptions({
+      query: makeFunctionReference<"query", { name: string }, string>(
+        "myQuery",
+      ),
+      args: { name: "hi" },
+    });
+    client.prewarmQuery(opts);
+  });
+
+  test("accepts extendSubscriptionFor on prewarmQuery", () => {
+    const client = testConvexReactClient();
+    client.prewarmQuery({
+      query: makeFunctionReference<"query", { name: string }, string>(
+        "myQuery",
+      ),
+      args: { name: "hi" },
+      extendSubscriptionFor: 10_000,
+    });
+  });
+});

src/react/client.ts

@@ -32,7 +32,7 @@ import {
   instantiateNoopLogger,
   Logger,
 } from "../browser/logging.js";
-import { ConvexQueryOptions } from "../browser/query_options.js";
+import type { QueryOptions } from "../browser/query_options.js";
 import { LoadMoreOfPaginatedQuery } from "../browser/sync/pagination.js";
 import {
   PaginatedQueryClient,
@@ -537,9 +537,7 @@ export class ConvexReactClient {
    * an optional extendSubscriptionFor for how long to subscribe to the query.
    */
   prewarmQuery<Query extends FunctionReference<"query">>(
-    queryOptions: ConvexQueryOptions<Query> & {
-      extendSubscriptionFor?: number;
-    },
+    queryOptions: QueryOptions<Query> & { extendSubscriptionFor?: number },
   ) {
     const extendSubscriptionFor =
       queryOptions.extendSubscriptionFor ?? DEFAULT_EXTEND_SUBSCRIPTION_FOR;
@@ -801,6 +799,34 @@ export type OptionalRestArgsOrSkip<FuncRef extends FunctionReference<any>> =
     ? [args?: EmptyObject | "skip"]
     : [args: FuncRef["_args"] | "skip"];
 
+/**
+ * Result returned by object-form {@link useQuery}.
+ *
+ * @public
+ */
+export type UseQueryResult<QueryResult> =
+  | {
+      data: QueryResult;
+      error: undefined;
+      status: "success";
+    }
+  | {
+      data: undefined;
+      error: Error;
+      status: "error";
+    }
+  | {
+      data: undefined;
+      error: undefined;
+      status: "pending";
+    };
+
+type UseQueryOptions<Query extends FunctionReference<"query">> = {
+  query: Query;
+  args: FunctionArgs<Query> | "skip";
+  throwOnError?: boolean;
+};
+
 /**
  * Load a reactive query within a React component.
  *
@@ -847,20 +873,82 @@ export type OptionalRestArgsOrSkip<FuncRef extends FunctionReference<any>> =
 export function useQuery<Query extends FunctionReference<"query">>(
   query: Query,
   ...args: OptionalRestArgsOrSkip<Query>
-): Query["_returnType"] | undefined {
-  const skip = args[0] === "skip";
-  const argsObject = args[0] === "skip" ? {} : parseArgs(args[0]);
+): Query["_returnType"] | undefined;
+
+/**
+ * Load a reactive query within a React component using an options object.
+ *
+ * This is an alternative form of {@link useQuery} that accepts a single
+ * {@link UseQueryOptions} object instead of positional arguments.
+ * Errors are returned in the result object unless `throwOnError` is set.
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from "convex/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function TaskList() {
+ *   const state = useQuery({ query: api.tasks.list, args: { completed: false } });
+ *
+ *   if (state.status === "pending") return <div>Loading...</div>;
+ *   if (state.status === "error") return <div>Error: {state.error.message}</div>;
+ *   return state.data.map((task) => <div key={task._id}>{task.text}</div>);
+ * }
+ * ```
+ *
+ * @param options - Query options. Pass `args: "skip"` to disable the query.
+ * @returns the current query state as a {@link UseQueryResult} object.
+ *
+ * @see https://docs.convex.dev/client/react#fetching-data
+ * @public
+ */
+export function useQuery<Query extends FunctionReference<"query">>(
+  options: UseQueryOptions<Query>,
+): UseQueryResult<Query["_returnType"]>;
 
-  const queryReference =
-    typeof query === "string"
-      ? makeFunctionReference<"query", any, any>(query)
-      : query;
+export function useQuery<Query extends FunctionReference<"query">>(
+  queryOrOptions: Query | UseQueryOptions<Query>,
+  ...args: OptionalRestArgsOrSkip<Query>
+): Query["_returnType"] | undefined | UseQueryResult<Query["_returnType"]> {
+  const isObjectOptions =
+    typeof queryOrOptions === "object" &&
+    queryOrOptions !== null &&
+    "query" in queryOrOptions;
+  const throwOnError = isObjectOptions
+    ? (queryOrOptions.throwOnError ?? false)
+    : true;
+
+  let queryReference: Query | undefined;
+  let argsObject: Record<string, Value> = {};
+
+  if (isObjectOptions) {
+    const query = queryOrOptions.query;
+    queryReference =
+      typeof query === "string"
+        ? (makeFunctionReference<"query", any, any>(query) as Query)
+        : query;
+    if (queryOrOptions.args !== "skip") {
+      argsObject = parseArgs(queryOrOptions.args as Record<string, Value>);
+    }
+  } else {
+    const query = queryOrOptions;
+    queryReference =
+      typeof query === "string"
+        ? (makeFunctionReference<"query", any, any>(query) as Query)
+        : query;
+    argsObject = args[0] === "skip" ? {} : parseArgs(args[0] as Query["_args"]);
+  }
 
-  const queryName = getFunctionName(queryReference);
+  const queryName = queryReference
+    ? getFunctionName(queryReference)
+    : undefined;
+  const skip =
+    (isObjectOptions && queryOrOptions.args === "skip") ||
+    (!isObjectOptions && args[0] === "skip");
 
   const queries = useMemo(
     () =>
-      skip
+      skip || !queryReference
         ? ({} as RequestForQueries)
         : { query: { query: queryReference, args: argsObject } },
     // Stringify args so args that are semantically the same don't trigger a
@@ -871,6 +959,34 @@ export function useQuery<Query extends FunctionReference<"query">>(
 
   const results = useQueries(queries);
   const result = results["query"];
+
+  if (isObjectOptions) {
+    if (result instanceof Error) {
+      if (throwOnError) {
+        throw result;
+      }
+      return {
+        data: undefined,
+        error: result,
+        status: "error",
+      };
+    }
+
+    if (result === undefined) {
+      return {
+        data: undefined,
+        error: undefined,
+        status: "pending",
+      };
+    }
+
+    return {
+      data: result,
+      error: undefined,
+      status: "success",
+    };
+  }
+
   if (result instanceof Error) {
     throw result;
   }