convex 1.34.0 → 1.35.0

package/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,
+    });
+  });
+});

package/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;
   }

package/src/react/index.ts

@@ -53,7 +53,11 @@
  * import { api } from "../convex/_generated/api";
  *
  * function App() {
- *   const counter = useQuery(api.getCounter.default);
+ *   const counter = useQuery({
+ *     query: api.getCounter.default,
+ *     args: {},
+ *     throwOnError: true,
+ *   }).data;
  *   const increment = useMutation(api.incrementCounter.default);
  *   // Your component here!
  * }
@@ -78,6 +82,7 @@ export {
   type MutationOptions,
   type ConvexReactClientOptions,
   type OptionalRestArgsOrSkip,
+  type UseQueryResult,
   ConvexReactClient,
   useConvex,
   ConvexProvider,
@@ -86,3 +91,6 @@ export {
   useAction,
   useConvexConnectionState,
 } from "./client.js";
+/** @internal */
+export { convexQueryOptions } from "../browser/query_options.js";
+export type { QueryOptions } from "../browser/query_options.js";

package/src/react/use_query_object_options.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @vitest-environment custom-vitest-environment.ts
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { test, describe } from "vitest";
+import { anyApi } from "../server/api.js";
+
+import type { ApiFromModules, QueryBuilder } from "../server/index.js";
+import { useQuery as useQueryReal } from "./client.js";
+
+const useQuery = (() => {}) as unknown as typeof useQueryReal;
+const query: QueryBuilder<any, "public"> = (() => {}) as any;
+
+const module = {
+  noArgs: query(() => "result"),
+  args: query((_ctx, { _arg }: { _arg: string }) => "result"),
+};
+type API = ApiFromModules<{ module: typeof module }>;
+const api = anyApi as unknown as API;
+
+describe("useQuery object options", () => {
+  test("supports object options and skip sentinel", () => {
+    useQuery({
+      query: api.module.noArgs,
+      args: {},
+    });
+
+    useQuery({
+      query: api.module.args,
+      args: { _arg: "asdf" },
+    });
+
+    const _arg: string | undefined = undefined;
+    useQuery({
+      query: api.module.args,
+      args: _arg ? { _arg } : "skip",
+    });
+
+    useQuery({
+      query: api.module.args,
+      args: { _arg: "asdf" },
+    });
+
+    useQuery({
+      query: api.module.noArgs,
+      args: "skip",
+    });
+  });
+});

package/src/react/use_query_result.test.ts

@@ -0,0 +1,41 @@
+/**
+ * @vitest-environment custom-vitest-environment.ts
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { test, describe } from "vitest";
+import { anyApi } from "../server/api.js";
+
+import type { ApiFromModules, QueryBuilder } from "../server/index.js";
+import { useQuery as useQueryReal } from "./client.js";
+
+const useQuery = (() => {}) as unknown as typeof useQueryReal;
+const query: QueryBuilder<any, "public"> = (() => {}) as any;
+
+const module = {
+  noArgs: query(() => "result"),
+  args: query((_ctx, { _arg }: { _arg: string }) => "result"),
+};
+type API = ApiFromModules<{ module: typeof module }>;
+const api = anyApi as unknown as API;
+
+describe("useQuery object-form result types", () => {
+  test("supports object-form result usage", () => {
+    useQuery({
+      query: api.module.args,
+      args: { _arg: "asdf" },
+    });
+
+    useQuery({
+      query: api.module.args,
+      args: { _arg: "asdf" },
+      throwOnError: true,
+    });
+
+    const _arg: string | undefined = undefined;
+    useQuery({
+      query: api.module.args,
+      args: _arg ? { _arg } : "skip",
+    });
+  });
+});

package/src/react-clerk/ConvexProviderWithClerk.test.tsx

@@ -5,7 +5,7 @@ import { test } from "vitest";
 import React from "react";
 import { ConvexProviderWithClerk } from "./ConvexProviderWithClerk.js";
 import { ConvexReactClient } from "../react/index.js";
-import { useAuth } from "@clerk/clerk-react";
+import { useAuth } from "@clerk/react";
 
 test("Helpers are valid children", () => {
   const convex = new ConvexReactClient("https://localhost:3001");

package/src/react-clerk/ConvexProviderWithClerk.tsx

@@ -30,7 +30,7 @@ type UseAuth = () => {
  * authenticated with Clerk.
  *
  * It must be wrapped by a configured `ClerkProvider`, from
- * `@clerk/clerk-react`, `@clerk/clerk-expo`, `@clerk/nextjs` or
+ * `@clerk/react`, `@clerk/clerk-expo`, `@clerk/nextjs` or
  * another React-based Clerk client library and have the corresponding
  * `useAuth` hook passed in.
  *

package/src/server/api.ts

@@ -39,7 +39,11 @@ export type FunctionType = "query" | "mutation" | "action";
  * Function references can be used to invoke functions from the client. For
  * example, in React you can pass references to the {@link react.useQuery} hook:
  * ```js
- * const result = useQuery(api.myModule.myFunction);
+ * const result = useQuery({
+ *   query: api.myModule.myFunction,
+ *   args: {},
+ *   throwOnError: true,
+ * }).data;
  * ```
  *
  * @typeParam Type - The type of the function ("query", "mutation", or "action").

package/src/server/components/definition.ts

@@ -45,6 +45,9 @@ export type ComponentDefinitionAnalysis = {
 };
 export type AppDefinitionAnalysis = {
   definitionType: AppDefinitionType;
+  // Top-level field (not inside definitionType) to match Rust's
+  // SerializedComponentDefinitionMetadata.http_prefix field.
+  httpPrefix?: string;
   childComponents: ComponentInstantiation[];
   httpMounts: Record<string, HttpMount>;
   exports: ComponentExport;

package/src/server/components/index.ts

@@ -94,6 +94,7 @@ export type ComponentDefinition<Exports extends ComponentExports = any> = {
     definition: Definition,
     options?: {
       name?: string;
+      httpPrefix?: string;
     },
   ): InstalledComponent<Definition>;
 
@@ -128,6 +129,7 @@ export type AppDefinition = {
     definition: Definition,
     options?: {
       name?: string;
+      httpPrefix?: string;
     },
   ): InstalledComponent<Definition>;
 };
@@ -143,6 +145,7 @@ type CommonDefinitionData = {
     string,
     ImportedComponentDefinition,
     Record<string, any> | null,
+    string | undefined,
   ][];
   _exportTree: ExportTree;
 };
@@ -152,7 +155,9 @@ type ComponentDefinitionData = CommonDefinitionData & {
   _name: string;
   _onInitCallbacks: Record<string, (argsStr: string) => string>;
 };
-type AppDefinitionData = CommonDefinitionData;
+type AppDefinitionData = CommonDefinitionData & {
+  _httpPrefix?: string;
+};
 
 /**
  * Used to refer to an already-installed component.
@@ -204,6 +209,7 @@ function use<Definition extends ComponentDefinition<any>>(
   definition: Definition,
   options?: {
     name?: string;
+    httpPrefix?: string;
   },
 ): InstalledComponent<Definition> {
   // At runtime an imported component will have this shape.
@@ -232,7 +238,21 @@ function use<Definition extends ComponentDefinition<any>>(
     throw new Error("Component name cannot be empty.");
   }
 
-  this._childComponents.push([name, importedComponentDefinition, {}]);
+  const httpPrefix = options?.httpPrefix;
+  if (httpPrefix !== undefined) {
+    if (!httpPrefix.startsWith("/")) {
+      throw new Error(
+        `httpPrefix must start with "/". Received: "${httpPrefix}"`,
+      );
+    }
+  }
+
+  this._childComponents.push([
+    name,
+    importedComponentDefinition,
+    {},
+    httpPrefix,
+  ]);
   return new InstalledComponent(definition, name);
 }
 
@@ -255,10 +275,14 @@ function exportAppForAnalysis(
 ): AppDefinitionAnalysis {
   const definitionType = { type: "app" as const };
   const childComponents = serializeChildComponents(this._childComponents);
+  const httpMounts = buildHttpMounts(this._childComponents);
   return {
     definitionType,
+    ...(this._httpPrefix !== undefined
+      ? { httpPrefix: normalizeHttpPrefix(this._httpPrefix) }
+      : {}),
     childComponents: childComponents as any,
-    httpMounts: {},
+    httpMounts,
     exports: serializeExportTree(this._exportTree),
   };
 }
@@ -277,11 +301,35 @@ function serializeExportTree(tree: ExportTree): any {
   return { type: "branch", branch };
 }
 
+function normalizeHttpPrefix(prefix: string): string {
+  // Ensure the prefix ends with "/" as required by HttpMountPath in Rust.
+  return prefix.endsWith("/") ? prefix : prefix + "/";
+}
+
+function buildHttpMounts(
+  childComponents: [
+    string,
+    ImportedComponentDefinition,
+    Record<string, any> | null,
+    string | undefined,
+  ][],
+): Record<string, string> {
+  const httpMounts: Record<string, string> = {};
+  for (const [name, , , httpPrefix] of childComponents) {
+    if (httpPrefix !== undefined) {
+      const normalized = normalizeHttpPrefix(httpPrefix);
+      httpMounts[normalized] = `_reference/childComponent/${name}`;
+    }
+  }
+  return httpMounts;
+}
+
 function serializeChildComponents(
   childComponents: [
     string,
     ImportedComponentDefinition,
     Record<string, any> | null,
+    string | undefined,
   ][],
 ): {
   name: string;
@@ -289,6 +337,7 @@ function serializeChildComponents(
   args: [string, { type: "value"; value: string }][] | null;
 }[] {
   return childComponents.map(([name, definition, p]) => {
+    // Note: httpPrefix (4th element) is used separately in buildHttpMounts()
     let args: [string, { type: "value"; value: string }][] | null = null;
     if (p !== null) {
       args = [];
@@ -335,11 +384,12 @@ function exportComponentForAnalysis(
     args,
   };
   const childComponents = serializeChildComponents(this._childComponents);
+  const httpMounts = buildHttpMounts(this._childComponents);
   return {
     name: this._name,
     definitionType,
     childComponents: childComponents as any,
-    httpMounts: {},
+    httpMounts,
     exports: serializeExportTree(this._exportTree),
   };
 }
@@ -394,11 +444,18 @@ export function defineComponent<Exports extends ComponentExports = any>(
  * This is a feature of components, which are in beta.
  * This API is unstable and may change in subsequent releases.
  */
-export function defineApp(): AppDefinition {
+export function defineApp(options?: { httpPrefix?: string }): AppDefinition {
+  const httpPrefix = options?.httpPrefix;
+  if (httpPrefix !== undefined && !httpPrefix.startsWith("/")) {
+    throw new Error(
+      `httpPrefix must start with "/". Received: "${httpPrefix}"`,
+    );
+  }
   const ret: RuntimeAppDefinition = {
     _isRoot: true,
     _childComponents: [],
     _exportTree: {},
+    ...(httpPrefix !== undefined ? { _httpPrefix: httpPrefix } : {}),
 
     export: exportAppForAnalysis,
     use,

package/src/server/data_model.ts

@@ -1,4 +1,5 @@
 import { Value } from "../values/index.js";
+import type { SystemIndexes } from "./system_fields.js";
 
 // Document Types  /////////////////////////////////////////////////////////////
 
@@ -262,7 +263,7 @@ export type AnyDataModel = {
   [tableName: string]: {
     document: any;
     fieldPaths: GenericFieldPaths;
-    indexes: {};
+    indexes: SystemIndexes;
     searchIndexes: {};
     vectorIndexes: {};
   };

package/src/server/impl/meta_impl.ts

@@ -0,0 +1,74 @@
+import { jsonToConvex } from "../../values/index.js";
+import {
+  ActionMeta,
+  MutationMeta,
+  QueryMeta,
+  FunctionMetadata,
+  TransactionMetrics,
+} from "../meta.js";
+import { performAsyncSyscall } from "./syscall.js";
+
+async function getTransactionMetrics(): Promise<TransactionMetrics> {
+  let syscallJSON;
+  try {
+    syscallJSON = await performAsyncSyscall("1.0/getTransactionMetrics", {});
+  } catch (e: any) {
+    if (e.message?.includes("Unknown async operation")) {
+      throw new Error(
+        "getTransactionMetrics() can only be called from a query or mutation. " +
+          "It is not available in actions or outside of a Convex function.",
+      );
+    }
+    throw e;
+  }
+  return jsonToConvex(syscallJSON) as any;
+}
+
+async function getFunctionMetadata(): Promise<{
+  name: string;
+  componentPath: string;
+}> {
+  const { name, componentPath } = await performAsyncSyscall(
+    "1.0/getFunctionMetadata",
+    {},
+  );
+  return { name, componentPath };
+}
+
+export function setupQueryMeta(
+  visibility: FunctionMetadata["visibility"],
+): QueryMeta {
+  return {
+    getFunctionMetadata: async () => ({
+      ...(await getFunctionMetadata()),
+      type: "query",
+      visibility,
+    }),
+    getTransactionMetrics,
+  };
+}
+
+export function setupMutationMeta(
+  visibility: FunctionMetadata["visibility"],
+): MutationMeta {
+  return {
+    getFunctionMetadata: async () => ({
+      ...(await getFunctionMetadata()),
+      type: "mutation",
+      visibility,
+    }),
+    getTransactionMetrics,
+  };
+}
+
+export function setupActionMeta(
+  visibility: FunctionMetadata["visibility"],
+): ActionMeta {
+  return {
+    getFunctionMetadata: async () => ({
+      ...(await getFunctionMetadata()),
+      type: "action",
+      visibility,
+    }),
+  };
+}