convex 1.34.1 → 1.35.0

package/src/cli/lib/usage.ts

@@ -3,6 +3,7 @@ import { Context } from "../../bundler/context.js";
 import { logWarning } from "../../bundler/log.js";
 import { teamDashboardUrl } from "./dashboard.js";
 import { fetchTeamAndProject } from "./api.js";
+import { isAnonymousDeployment } from "./deployment.js";
 import { bigBrainAPI } from "./utils/utils.js";
 
 async function warn(
@@ -53,7 +54,8 @@ export async function usageStateWarning(
     auth === null ||
     auth.kind === "projectKey" ||
     auth.kind === "deploymentKey" ||
-    process.env.CONVEX_AGENT_MODE === "anonymous"
+    process.env.CONVEX_AGENT_MODE === "anonymous" ||
+    isAnonymousDeployment(targetDeployment)
   ) {
     return;
   }

package/src/cli/lib/utils/prompts.ts

@@ -30,12 +30,14 @@ export const promptString = async (
   options: {
     message: string;
     default?: string;
+    validate?: (value: string) => boolean | string | Promise<string | boolean>;
   },
 ): Promise<string> => {
   if (process.stdin.isTTY) {
     return input({
       message: options.message,
       ...(options.default !== undefined ? { default: options.default } : {}),
+      ...(options.validate !== undefined ? { validate: options.validate } : {}),
     }).catch(handlePromptError(ctx));
   } else {
     return ctx.crash({

package/src/cli/lib/utils/utils.test.ts

@@ -65,7 +65,7 @@ describe("bigBrainFetch", () => {
     const mockFetch = stubFetch();
     const ctx = makeContext(null);
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch("https://api.convex.dev/api/test", { method: "GET" });
 
     expect(mockFetch).toHaveBeenCalledOnce();
@@ -82,7 +82,7 @@ describe("bigBrainFetch", () => {
       accessToken: "test-token",
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch("https://api.convex.dev/api/test", { method: "GET" });
 
     expect(mockFetch).toHaveBeenCalledOnce();
@@ -99,7 +99,7 @@ describe("bigBrainFetch", () => {
       accessToken: "original-token",
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch("https://api.convex.dev/api/test", {
       method: "POST",
       headers: {
@@ -124,7 +124,7 @@ describe("bigBrainFetch", () => {
       headers: { "X-Custom-Header": "custom-value" },
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch(request, undefined);
 
     expect(mockFetch).toHaveBeenCalledOnce();
@@ -143,7 +143,7 @@ describe("bigBrainFetch", () => {
       headers: { "X-Custom-Header": "from-request" },
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch(request, {
       headers: { "X-Custom-Header": "from-options" },
     });
@@ -160,7 +160,7 @@ describe("bigBrainFetch", () => {
       method: "POST",
     });
 
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     await fetch(request);
 
     expect(mockFetch).toHaveBeenCalledOnce();

package/src/cli/lib/utils/utils.ts

@@ -1,3 +1,4 @@
+import { paths as PlatformDeploymentPaths } from "@convex-dev/platform/deploymentApi";
 import { paths as PlatformManagementPaths } from "@convex-dev/platform/managementApi";
 import { chalkStderr } from "chalk";
 import os from "os";
@@ -692,7 +693,7 @@ export function cacheDir() {
  *
  * This fetch() also has retries and throws if the response is not ok.
  */
-export async function bigBrainFetch(ctx: Context): Promise<typeof fetch> {
+export function bigBrainFetch(ctx: Context): typeof fetch {
   const authHeader = ctx.bigBrainAuth()?.header;
   const bigBrainHeaders: Record<string, string> = authHeader
     ? {
@@ -758,26 +759,25 @@ export async function bigBrainAPI<T = any>({
  *
  * Pass { throw: true } to throw ThrowingFetchErrors instead of exiting the process.
  */
-function typedBigBrainClientFactory<T>(baseUrl: string) {
+function typedApiClientFactory<T>(
+  baseUrl: string,
+  fetchBuilder: (ctx: Context) => typeof fetch,
+) {
   return (ctx: Context, options: { throw?: boolean } = {}) => {
     type Paths = T extends CliManagementPaths
       ? CliManagementPaths
       : T extends PlatformManagementPaths
         ? PlatformManagementPaths
-        : never;
-    const bigBrainClient = createClient<Paths>({
+        : T extends PlatformDeploymentPaths
+          ? PlatformDeploymentPaths
+          : never;
+    const client = createClient<Paths>({
       baseUrl,
-      fetch: async (
-        resource: Request,
-        options?: RequestInit,
-      ): Promise<Response> => {
-        const fetch = await bigBrainFetch(ctx);
-        return fetch(resource, options);
-      },
+      fetch: fetchBuilder(ctx),
     });
 
     // Wrap the client with error handling - go back to proxy since middleware doesn't catch parsing errors
-    return new Proxy(bigBrainClient, {
+    return new Proxy(client, {
       get(target, prop) {
         const originalMethod = target[prop as keyof typeof target];
 
@@ -810,13 +810,31 @@ function typedBigBrainClientFactory<T>(baseUrl: string) {
   };
 }
 
-export const typedBigBrainClient =
-  typedBigBrainClientFactory<CliManagementPaths>(BIG_BRAIN_URL);
+export const typedBigBrainClient = typedApiClientFactory<CliManagementPaths>(
+  BIG_BRAIN_URL,
+  bigBrainFetch,
+);
 export const typedPlatformClient =
-  typedBigBrainClientFactory<PlatformManagementPaths>(
+  typedApiClientFactory<PlatformManagementPaths>(
     PLATFORM_MANAGEMENT_API_URL,
+    bigBrainFetch,
   );
 
+export function typedDeploymentClient(
+  ctx: Context,
+  args: { deploymentUrl: string; adminKey: string },
+  options: { throw?: boolean } = {},
+) {
+  return typedApiClientFactory<PlatformDeploymentPaths>(
+    `${args.deploymentUrl}/api/v1`,
+    (ctx) =>
+      deploymentFetch(ctx, {
+        deploymentUrl: args.deploymentUrl,
+        adminKey: args.adminKey,
+      }),
+  )(ctx, options);
+}
+
 export async function bigBrainAPIMaybeThrows({
   ctx,
   method,
@@ -828,7 +846,7 @@ export async function bigBrainAPIMaybeThrows({
   path: string;
   data?: any;
 }): Promise<any> {
-  const fetch = await bigBrainFetch(ctx);
+  const fetch = bigBrainFetch(ctx);
   const dataString =
     data === undefined
       ? method === "POST"
@@ -894,19 +912,40 @@ export function waitUntilCalled(): [Promise<unknown>, () => void] {
   return [waitPromise, () => onCalled(null)];
 }
 
-// We can eventually switch to something like `filesize` for i18n and
-// more robust formatting, but let's keep our CLI bundle small for now.
+const BYTE_UNITS: [number, string][] = [
+  [1 << 30, "GiB"],
+  [1_000_000_000, "GB"],
+  [1 << 20, "MiB"],
+  [1_000_000, "MB"],
+  [1 << 10, "KiB"],
+  [1_000, "KB"],
+];
+
+/**
+ * Format a byte count into a human-friendly string.
+ *
+ * Picks the unit (binary or decimal) that divides most cleanly.
+ * Shows one decimal place only when it divides exactly (e.g. "4.1 MiB").
+ * Falls back to raw bytes when no unit divides cleanly.
+ */
 export function formatSize(n: number): string {
-  if (n < 1024) {
-    return `${n} B`;
+  if (n === 0) {
+    return "0 bytes";
   }
-  if (n < 1024 * 1024) {
-    return `${(n / 1024).toFixed(1)} KB`;
-  }
-  if (n < 1024 * 1024 * 1024) {
-    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  for (const [unitSize, unitName] of BYTE_UNITS) {
+    if (n < unitSize) {
+      continue;
+    }
+    if (n % unitSize === 0) {
+      return `${n / unitSize} ${unitName}`;
+    }
+    if ((n * 10) % unitSize === 0) {
+      const whole = Math.floor(n / unitSize);
+      const frac = Math.floor((n * 10) / unitSize) % 10;
+      return `${whole}.${frac} ${unitName}`;
+    }
   }
-  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+  return `${n} bytes`;
 }
 
 export function formatDuration(ms: number): string {
@@ -1236,7 +1275,7 @@ export function deploymentFetch(
     adminKey: string;
     onError?: (err: any) => void;
   },
-): typeof throwingFetch {
+): typeof fetch {
   const { deploymentUrl, adminKey, onError } = options;
   const onErrorWithAttempt = (err: any, attempt: number) => {
     onError?.(err);

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.34.1";
+export const version = "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;