convex 1.36.1 → 1.37.0

package/src/cli/lib/generatedFunctionLogsApi.ts

@@ -35,6 +35,7 @@ export interface components {
             usageStats: components["schemas"]["UsageStatsJson"];
             /** Format: double */
             userExecutionTime?: number | null;
+            willRetry: boolean;
         } | {
             componentPath?: string | null;
             executionId: string;

package/src/cli/lib/usage.ts

@@ -1,10 +1,10 @@
 import { chalkStderr } from "chalk";
 import { Context } from "../../bundler/context.js";
-import { logWarning } from "../../bundler/log.js";
+import { logVerbose, 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";
+import { bigBrainAPIMaybeThrows } from "./utils/utils.js";
 
 async function warn(
   ctx: Context,
@@ -19,7 +19,7 @@ async function warn(
 }
 
 async function teamUsageState(ctx: Context, teamId: number) {
-  const { usageState } = (await bigBrainAPI({
+  const { usageState } = (await bigBrainAPIMaybeThrows({
     ctx,
     method: "GET",
     path: "dashboard/teams/" + teamId + "/usage/team_usage_state",
@@ -31,7 +31,7 @@ async function teamUsageState(ctx: Context, teamId: number) {
 }
 
 async function teamSpendingLimitsState(ctx: Context, teamId: number) {
-  const response = (await bigBrainAPI({
+  const response = (await bigBrainAPIMaybeThrows({
     ctx,
     method: "GET",
     path: "dashboard/teams/" + teamId + "/get_spending_limits",
@@ -59,12 +59,22 @@ export async function usageStateWarning(
   ) {
     return;
   }
+
   const { teamId, team } = await fetchTeamAndProject(ctx, targetDeployment);
 
-  const [usageState, spendingLimitsState] = await Promise.all([
-    teamUsageState(ctx, teamId),
-    teamSpendingLimitsState(ctx, teamId),
-  ]);
+  let usageState: Awaited<ReturnType<typeof teamUsageState>>;
+  let spendingLimitsState: Awaited<ReturnType<typeof teamSpendingLimitsState>>;
+  try {
+    [usageState, spendingLimitsState] = await Promise.all([
+      teamUsageState(ctx, teamId),
+      teamSpendingLimitsState(ctx, teamId),
+    ]);
+  } catch (err) {
+    // Non-fatal: usage warnings are advisory, so don't block `convex dev`
+    // if these endpoints error.
+    logVerbose("Skipping usage state warning:", err);
+    return;
+  }
   if (spendingLimitsState === "Disabled") {
     await warn(ctx, {
       title:

package/src/cli/lib/workos/environmentApi.test.ts

@@ -0,0 +1,107 @@
+import { test, expect, describe, beforeEach, vi } from "vitest";
+import { Context } from "../../../bundler/context.js";
+import { createCORSOrigin, createRedirectURI } from "./environmentApi.js";
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+const ctx: Context = {
+  crash: vi.fn(async (args: { printedMessage: string | null }) => {
+    throw new Error(args.printedMessage ?? "crash");
+  }),
+} as unknown as Context;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("createRedirectURI", () => {
+  test("returns modified: true on a successful response", async () => {
+    mockFetch.mockResolvedValue(new Response(null, { status: 201 }));
+    await expect(
+      createRedirectURI(ctx, "key", "http://localhost:5173"),
+    ).resolves.toEqual({ modified: true });
+  });
+
+  test("returns modified: false when the URI already exists", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(
+        `{"message":"Redirect URI 'http://localhost:5173' already exists.","error":"Unprocessable Entity"}`,
+        { status: 422 },
+      ),
+    );
+    await expect(
+      createRedirectURI(ctx, "key", "http://localhost:5173"),
+    ).resolves.toEqual({ modified: false });
+    expect(ctx.crash).not.toHaveBeenCalled();
+  });
+
+  test("crashes with the body for a non-duplicate 422", async () => {
+    const body = `{"message":"Redirect URI 'test' is invalid.","error":"Unprocessable Entity"}`;
+    mockFetch.mockResolvedValue(new Response(body, { status: 422 }));
+    await expect(createRedirectURI(ctx, "key", "test")).rejects.toThrow(
+      `Failed to create redirect URI: 422 ${body}`,
+    );
+    expect(ctx.crash).toHaveBeenCalledWith(
+      expect.objectContaining({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: `Failed to create redirect URI: 422 ${body}`,
+      }),
+    );
+  });
+
+  test("crashes with the body for non-422 errors", async () => {
+    const body = `{"message":"Unauthorized"}`;
+    mockFetch.mockResolvedValue(new Response(body, { status: 401 }));
+    await expect(createRedirectURI(ctx, "key", "http://x")).rejects.toThrow(
+      `Failed to create redirect URI: 401 ${body}`,
+    );
+  });
+});
+
+describe("createCORSOrigin", () => {
+  test("returns modified: true on a successful response", async () => {
+    mockFetch.mockResolvedValue(new Response(null, { status: 201 }));
+    await expect(
+      createCORSOrigin(ctx, "key", "http://localhost:5173"),
+    ).resolves.toEqual({ modified: true });
+  });
+
+  test("returns modified: false on duplicate_cors_origin", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(`{"code":"duplicate_cors_origin","message":"..."}`, {
+        status: 409,
+      }),
+    );
+    await expect(
+      createCORSOrigin(ctx, "key", "http://localhost:5173"),
+    ).resolves.toEqual({ modified: false });
+    expect(ctx.crash).not.toHaveBeenCalled();
+  });
+
+  test("returns modified: false when the origin already exists", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(`{"message":"CORS origin already exists."}`, {
+        status: 409,
+      }),
+    );
+    await expect(
+      createCORSOrigin(ctx, "key", "http://localhost:5173"),
+    ).resolves.toEqual({ modified: false });
+    expect(ctx.crash).not.toHaveBeenCalled();
+  });
+
+  test("crashes with the body for a non-duplicate 409", async () => {
+    const body = `{"message":"Some other conflict."}`;
+    mockFetch.mockResolvedValue(new Response(body, { status: 409 }));
+    await expect(createCORSOrigin(ctx, "key", "http://x")).rejects.toThrow(
+      `Failed to create CORS origin: 409 ${body}`,
+    );
+    expect(ctx.crash).toHaveBeenCalledWith(
+      expect.objectContaining({
+        printedMessage: `Failed to create CORS origin: 409 ${body}`,
+      }),
+    );
+  });
+});

package/src/cli/lib/workos/environmentApi.ts

@@ -35,15 +35,11 @@ export async function createRedirectURI(
   );
 
   if (!response.ok) {
-    if (response.status === 422) {
-      const errorText = await response.text();
-      if (errorText.includes("already exists")) {
-        // This redirect URI already exists.
-        return { modified: false };
-      }
-    }
-
     const errorText = await response.text();
+    if (response.status === 422 && errorText.includes("already exists")) {
+      // This redirect URI already exists.
+      return { modified: false };
+    }
     return await ctx.crash({
       exitCode: 1,
       errorType: "fatal",
@@ -109,18 +105,15 @@ export async function createCORSOrigin(
   );
 
   if (!response.ok) {
-    if (response.status === 409) {
-      const errorText = await response.text();
-      if (
-        errorText.includes("duplicate_cors_origin") ||
-        errorText.includes("already exists")
-      ) {
-        // This CORS origin already exists.
-        return { modified: false };
-      }
-    }
-
     const errorText = await response.text();
+    if (
+      response.status === 409 &&
+      (errorText.includes("duplicate_cors_origin") ||
+        errorText.includes("already exists"))
+    ) {
+      // This CORS origin already exists.
+      return { modified: false };
+    }
     return await ctx.crash({
       exitCode: 1,
       errorType: "fatal",

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.36.1";
+export const version = "1.37.0";

package/src/react/client.test.tsx

@@ -4,7 +4,12 @@
 import { test, expect, describe, vi } from "vitest";
 import ws from "ws";
 
-import { ConvexReactClient, createMutation, useQuery } from "./client.js";
+import {
+  ConvexReactClient,
+  createMutation,
+  useQuery,
+  useQuery_experimental,
+} from "./client.js";
 import { convexQueryOptions } from "../browser/query_options.js";
 import { ConvexProvider } from "./index.js";
 import React from "react";
@@ -114,14 +119,14 @@ describe("useQuery", () => {
     expect(result.current).toStrictEqual(undefined);
   });
 
-  test("object form returns success result", () => {
+  test("useQuery_experimental object form returns success result", () => {
     const client = createClientWithQuery();
     const wrapper = ({ children }: any) => (
       <ConvexProvider client={client}>{children}</ConvexProvider>
     );
     const { result } = renderHook(
       () =>
-        useQuery({
+        useQuery_experimental({
           query: anyApi.myQuery.default,
           args: {},
         }),
@@ -129,27 +134,24 @@ describe("useQuery", () => {
     );
     expect(result.current).toStrictEqual({
       data: "queryResult",
-      error: undefined,
       status: "success",
     });
   });
 
-  test("object form returns pending when skipped", () => {
+  test("useQuery_experimental object form returns pending when skipped", () => {
     const client = createClientWithQuery();
     const wrapper = ({ children }: any) => (
       <ConvexProvider client={client}>{children}</ConvexProvider>
     );
     const { result } = renderHook(
       () =>
-        useQuery({
+        useQuery_experimental({
           query: anyApi.myQuery.default,
           args: "skip",
         }),
       { wrapper },
     );
     expect(result.current).toStrictEqual({
-      data: undefined,
-      error: undefined,
       status: "pending",
     });
   });

package/src/react/client.ts

@@ -800,31 +800,22 @@ export type OptionalRestArgsOrSkip<FuncRef extends FunctionReference<any>> =
     : [args: FuncRef["_args"] | "skip"];
 
 /**
- * Result returned by object-form {@link useQuery}.
+ * Result returned by object-form {@link useQuery_experimental}.
  *
- * @internal
+ * @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">> = {
+export type UseQueryResult<QueryResult, ThrowOnError extends boolean = false> =
+  | { status: "pending" }
+  | { status: "success"; data: QueryResult }
+  | (ThrowOnError extends true ? never : { status: "error"; error: Error });
+
+type UseQueryOptions<
+  Query extends FunctionReference<"query">,
+  ThrowOnError extends boolean,
+> = {
   query: Query;
   args: FunctionArgs<Query> | "skip";
-  throwOnError?: boolean;
+  throwOnError?: ThrowOnError;
 };
 
 /**
@@ -873,18 +864,50 @@ type UseQueryOptions<Query extends FunctionReference<"query">> = {
 export function useQuery<Query extends FunctionReference<"query">>(
   query: Query,
   ...args: OptionalRestArgsOrSkip<Query>
-): Query["_returnType"] | undefined;
+): Query["_returnType"] | undefined {
+  const skip = args[0] === "skip";
+  const argsObject = args[0] === "skip" ? {} : parseArgs(args[0]);
+  const queryReference =
+    typeof query === "string"
+      ? makeFunctionReference<"query", any, any>(query)
+      : query;
+
+  const queryName = getFunctionName(queryReference);
+
+  const queries = useMemo(
+    () =>
+      skip
+        ? ({} as RequestForQueries)
+        : { query: { query: queryReference, args: argsObject } },
+    // Stringify args so args that are semantically the same don't trigger a
+    // rerender. Saves developers from adding `useMemo` on every args usage.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(convexToJson(argsObject)), queryName, skip],
+  );
+
+  const results = useQueries(queries);
+  const result = results["query"];
+
+  if (result instanceof Error) {
+    throw result;
+  }
+  return result;
+}
 
 /**
  * Load a reactive query within a React component using an options object.
  *
- * This is an alternative form of {@link useQuery} that accepts a single
+ * This is an experimental 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.
+ *
+ * Consumers are expected to check the returned object `status` field to
+ * make proper use of the result. If an error occurs, it will be present
+ * in the result object unless `throwOnError` is `true`, in which case
+ * the error will be thrown instead.
  *
  * @example
  * ```tsx
- * import { useQuery } from "convex/react";
+ * import { useQuery_experimental as useQuery } from "convex/react";
  * import { api } from "../convex/_generated/api";
  *
  * function TaskList() {
@@ -900,55 +923,35 @@ export function useQuery<Query extends FunctionReference<"query">>(
  * @returns the current query state as a {@link UseQueryResult} object.
  *
  * @see https://docs.convex.dev/client/react#fetching-data
- * @internal
+ * @public
  */
-export function useQuery<Query extends FunctionReference<"query">>(
-  options: UseQueryOptions<Query>,
-): UseQueryResult<Query["_returnType"]>;
-
-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 = queryReference
-    ? getFunctionName(queryReference)
-    : undefined;
-  const skip =
-    (isObjectOptions && queryOrOptions.args === "skip") ||
-    (!isObjectOptions && args[0] === "skip");
-
+export function useQuery_experimental<
+  Query extends FunctionReference<"query">,
+  ThrowOnError extends boolean = false,
+>(
+  options: UseQueryOptions<Query, ThrowOnError>,
+): UseQueryResult<Query["_returnType"], ThrowOnError>;
+
+export function useQuery_experimental<
+  Query extends FunctionReference<"query">,
+  ThrowOnError extends boolean = false,
+>(
+  options: UseQueryOptions<Query, ThrowOnError>,
+): UseQueryResult<Query["_returnType"], false> {
+  const throwOnError = options.throwOnError ?? false;
+  const queryReference =
+    typeof options.query === "string"
+      ? (makeFunctionReference<"query", any, any>(options.query) as Query)
+      : options.query;
+  const skip = options.args === "skip";
+  const argsObject = !skip
+    ? parseArgs(options.args as Record<string, Value>)
+    : {};
+
+  const queryName = getFunctionName(queryReference);
   const queries = useMemo(
     () =>
-      skip || !queryReference
+      skip
         ? ({} as RequestForQueries)
         : { query: { query: queryReference, args: argsObject } },
     // Stringify args so args that are semantically the same don't trigger a
@@ -960,37 +963,26 @@ 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",
-      };
+  if (result instanceof Error) {
+    if (throwOnError) {
+      throw result;
     }
-
     return {
-      data: result,
-      error: undefined,
-      status: "success",
+      error: result,
+      status: "error",
     };
   }
 
-  if (result instanceof Error) {
-    throw result;
+  if (result === undefined) {
+    return {
+      status: "pending",
+    };
   }
-  return result;
+
+  return {
+    data: result,
+    status: "success",
+  };
 }
 
 /**

package/src/react/index.ts

@@ -61,7 +61,11 @@
  * @module
  */
 export * from "./use_paginated_query.js";
-export { usePaginatedQuery_experimental } from "./use_paginated_query2.js";
+export {
+  usePaginatedQuery_experimental,
+  type UsePaginatedQueryOptions,
+  type UsePaginatedQueryObjectReturnType,
+} from "./use_paginated_query2.js";
 export { usePaginatedQuery } from "./use_paginated_query.js";
 export { useQueries, type RequestForQueries } from "./use_queries.js";
 export type { AuthTokenFetcher } from "../browser/sync/client.js";
@@ -82,6 +86,7 @@ export {
   useConvex,
   ConvexProvider,
   useQuery,
+  useQuery_experimental,
   useMutation,
   useAction,
   useConvexConnectionState,