convex 1.45.0 → 1.47.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -204,7 +204,7 @@
     "@babel/types": "^7.27.1",
     "@clerk/react": "^6.4.3",
     "@commander-js/extra-typings": "^14.0.0",
-    "@convex-dev/platform": "0.1.10",
+    "@convex-dev/platform": "0.1.11",
     "@eslint/compat": "~2.0.0",
     "@eslint/eslintrc": "^3",
     "@eslint/js": "~9.39.0",
@@ -222,13 +222,13 @@
     "@types/babel__code-frame": "^7.0.6",
     "@types/deep-equal": "1.0.4",
     "@types/node": "^18.17.0",
-    "@types/react": "^18.0.0",
-    "@types/react-dom": "^18.0.0",
+    "@types/react": "^19.2.4",
+    "@types/react-dom": "^19.2.3",
     "@types/semver": "^7.3.13",
     "@types/serve-handler": "~6.1.4",
     "@types/ws": "^8.5.13",
     "@vitest/eslint-plugin": "~1.6.0",
-    "adm-zip": "^0.6.0",
+    "adm-zip": "^0.6.1",
     "bufferutil": "^4.0.7",
     "chalk": "5",
     "chokidar": "3.6.0",
@@ -258,8 +258,8 @@
     "openapi-typescript-helpers": "~0.1.0",
     "openid-client": "^5.3.1",
     "ora": "^9.0.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "semver": "^7.6.0",
     "serve-handler": "~6.1.6",
     "shx": "~0.4.0",
@@ -269,7 +269,7 @@
     "typedoc": "^0.24.6",
     "typescript": "~5.0.3",
     "typescript-eslint": "~8.57.0",
-    "undici": "7.29.0",
+    "undici": "7.29.1",
     "vitest": "^4.1.0",
     "wait-for-expect": "~4.0.0",
     "zod": "^3.24.0",
@@ -280,7 +280,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "npm run generateApiSpec && python3 scripts/build.py 2>&1",
+    "build": "npm run generateApiSpec && uv run --script scripts/build.py 2>&1",
     "bundle-server": "node scripts/bundle-server.mjs",
     "clean": "shx rm -rf dist tmpDist*",
     "lint": "eslint . --cache",

package/schemas/convex.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "description": "Configuration schema for Convex project settings.\n\nDocumentation: https://docs.convex.dev/production/project-configuration#convexjson",
+  "description": "Configuration schema for Convex project settings.\n\nDocumentation: https://docs.convex.dev/config/convex.json",
   "type": "object",
   "definitions": {
     "authKitConfigureSettings": {
@@ -123,7 +123,7 @@
         },
         "nodeVersion": {
           "type": "string",
-          "description": "The Node.js version to use for Node.js actions. The currently supported values are '20', '22', and '24'.\n\nDocumentation: https://docs.convex.dev/production/project-configuration#configuring-the-nodejs-version",
+          "description": "The Node.js version to use for Node.js actions. The currently supported values are '20', '22', and '24'.\n\nDocumentation: https://docs.convex.dev/config/convex.json#configuring-the-nodejs-version",
           "default": "20"
         }
       }
@@ -135,7 +135,7 @@
     },
     "functions": {
       "type": "string",
-      "description": "Path to the directory containing Convex functions. You can customize this to use a different location than the default 'convex/' directory.\n\nDocumentation: https://docs.convex.dev/production/project-configuration#changing-the-convex-folder-name-or-location",
+      "description": "Path to the directory containing Convex functions. You can customize this to use a different location than the default 'convex/' directory.\n\nDocumentation: https://docs.convex.dev/config/convex.json#changing-the-convex-folder-name-or-location",
       "default": "convex/"
     },
     "codegen": {
@@ -155,12 +155,12 @@
         },
         "staticApi": {
           "type": "boolean",
-          "description": "When true, generates static `api.d.ts` files, which improves autocomplete and incremental typechecking performance in large codebases.\n\nDocumentation: https://docs.convex.dev/production/project-configuration#using-static-code-generation-beta",
+          "description": "When true, generates static `api.d.ts` files, which improves autocomplete and incremental typechecking performance in large codebases.\n\nDocumentation: https://docs.convex.dev/config/convex.json#using-static-code-generation-beta",
           "default": false
         },
         "staticDataModel": {
           "type": "boolean",
-          "description": "When true, generates static `dataModel.d.ts` files, which improves autocomplete and incremental typechecking performance in large codebases.\n\nDocumentation: https://docs.convex.dev/production/project-configuration#using-static-code-generation-beta",
+          "description": "When true, generates static `dataModel.d.ts` files, which improves autocomplete and incremental typechecking performance in large codebases.\n\nDocumentation: https://docs.convex.dev/config/convex.json#using-static-code-generation-beta",
           "default": false
         }
       }

package/src/browser/http_client.ts

@@ -1,8 +1,9 @@
 import {
-  FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
   getFunctionName,
+  FunctionReference,
+  FunctionReference_future,
 } from "../server/api.js";
 import { parseArgs, validateDeploymentUrl } from "../common/index.js";
 import { version } from "../index.js";
@@ -68,7 +69,9 @@ export class ConvexHttpClient {
   private fetch?: typeof globalThis.fetch | undefined;
   private logger: Logger;
   private mutationQueue: Array<{
-    mutation: FunctionReference<"mutation">;
+    mutation:
+      | FunctionReference<"mutation">
+      | FunctionReference_future<"mutation">;
     args: FunctionArgs<any>;
     resolve: (value: any) => void;
     reject: (error: any) => void;
@@ -223,7 +226,11 @@ export class ConvexHttpClient {
    *
    * @deprecated This API is experimental: it may change or disappear.
    */
-  async consistentQuery<Query extends FunctionReference<"query">>(
+  async consistentQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     ...args: OptionalRestArgs<Query>
   ): Promise<FunctionReturnType<Query>> {
@@ -267,7 +274,11 @@ export class ConvexHttpClient {
    * the arguments will be `{}`.
    * @returns A promise of the query's result.
    */
-  async query<Query extends FunctionReference<"query">>(
+  async query<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     ...args: OptionalRestArgs<Query>
   ): Promise<FunctionReturnType<Query>> {
@@ -275,7 +286,11 @@ export class ConvexHttpClient {
     return await this.queryInner(query, queryArgs, {});
   }
 
-  private async queryInner<Query extends FunctionReference<"query">>(
+  private async queryInner<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     queryArgs: FunctionArgs<Query>,
     options: { timestampPromise?: Promise<string> },
@@ -339,7 +354,11 @@ export class ConvexHttpClient {
     }
   }
 
-  private async mutationInner<Mutation extends FunctionReference<"mutation">>(
+  private async mutationInner<
+    Mutation extends
+      | FunctionReference<"mutation">
+      | FunctionReference_future<"mutation">,
+  >(
     mutation: Mutation,
     mutationArgs: FunctionArgs<Mutation>,
   ): Promise<FunctionReturnType<Mutation>> {
@@ -408,7 +427,11 @@ export class ConvexHttpClient {
     this.isProcessingQueue = false;
   }
 
-  private enqueueMutation<Mutation extends FunctionReference<"mutation">>(
+  private enqueueMutation<
+    Mutation extends
+      | FunctionReference<"mutation">
+      | FunctionReference_future<"mutation">,
+  >(
     mutation: Mutation,
     args: FunctionArgs<Mutation>,
   ): Promise<FunctionReturnType<Mutation>> {
@@ -427,7 +450,11 @@ export class ConvexHttpClient {
    * @param options - An optional object containing
    * @returns A promise of the mutation's result.
    */
-  async mutation<Mutation extends FunctionReference<"mutation">>(
+  async mutation<
+    Mutation extends
+      | FunctionReference<"mutation">
+      | FunctionReference_future<"mutation">,
+  >(
     mutation: Mutation,
     ...args: ArgsAndOptions<Mutation, HttpMutationOptions>
   ): Promise<FunctionReturnType<Mutation>> {
@@ -450,7 +477,11 @@ export class ConvexHttpClient {
    * the arguments will be `{}`.
    * @returns A promise of the action's result.
    */
-  async action<Action extends FunctionReference<"action">>(
+  async action<
+    Action extends
+      | FunctionReference<"action">
+      | FunctionReference_future<"action">,
+  >(
     action: Action,
     ...args: OptionalRestArgs<Action>
   ): Promise<FunctionReturnType<Action>> {
@@ -513,7 +544,9 @@ export class ConvexHttpClient {
    * @internal
    */
   async function<
-    AnyFunction extends FunctionReference<"query" | "mutation" | "action">,
+    AnyFunction extends
+      | FunctionReference<"query" | "mutation" | "action">
+      | FunctionReference_future<"query" | "mutation" | "action">,
   >(
     anyFunction: AnyFunction | string,
     componentPath?: string,

package/src/browser/query_options.ts

@@ -1,5 +1,9 @@
 // Inspired by https://tanstack.com/query/v5/docs/framework/react/guides/query-options
-import type { FunctionArgs, FunctionReference } from "../server/api.js";
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReference_future,
+} from "../server/api.js";
 
 /**
  * Options for a Convex query: the query function reference and its arguments.
@@ -8,7 +12,9 @@ import type { FunctionArgs, FunctionReference } from "../server/api.js";
  *
  * @public
  */
-export type QueryOptions<Query extends FunctionReference<"query">> = {
+export type QueryOptions<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+> = {
   /**
    * The query function to run.
    */
@@ -40,8 +46,8 @@ export type QueryOptions<Query extends FunctionReference<"query">> = {
  * @returns The same object, typed as `QueryOptions<Query>`.
  * @internal
  */
-export function convexQueryOptions<Query extends FunctionReference<"query">>(
-  options: QueryOptions<Query>,
-): QueryOptions<Query> {
+export function convexQueryOptions<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+>(options: QueryOptions<Query>): QueryOptions<Query> {
   return options;
 }

package/src/browser/simple_client.ts

@@ -1,9 +1,10 @@
 import { validateDeploymentUrl } from "../common/index.js";
 import {
   FunctionArgs,
-  FunctionReference,
   FunctionReturnType,
   PaginationResult,
+  FunctionReference,
+  FunctionReference_future,
 } from "../server/index.js";
 import { getFunctionName } from "../server/api.js";
 import { AuthTokenFetcher } from "./sync/authentication_manager.js";
@@ -184,14 +185,18 @@ export class ConvexClient {
    *
    * @return an {@link Unsubscribe} function to stop calling the onUpdate function.
    */
-  onUpdate<Query extends FunctionReference<"query">>(
+  onUpdate<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     args: FunctionArgs<Query>,
     callback: (result: FunctionReturnType<Query>) => unknown,
     onError?: (e: Error) => unknown,
-  ): Unsubscribe<Query["_returnType"]> {
+  ): Unsubscribe<FunctionReturnType<Query>> {
     if (this.disabled) {
-      return this.createDisabledUnsubscribe<Query["_returnType"]>();
+      return this.createDisabledUnsubscribe<FunctionReturnType<Query>>();
     }
 
     // BaseConvexClient takes care of deduplicating queries subscriptions...
@@ -227,7 +232,7 @@ export class ConvexClient {
     }
 
     const unsubscribeProps: RemoveCallSignature<
-      Unsubscribe<Query["_returnType"]>
+      Unsubscribe<FunctionReturnType<Query>>
     > = {
       unsubscribe: () => {
         if (this.closed) {
@@ -241,7 +246,7 @@ export class ConvexClient {
       getQueryLogs: () => this.client.localQueryLogs(queryToken),
     };
     const ret = unsubscribeProps.unsubscribe as Unsubscribe<
-      Query["_returnType"]
+      FunctionReturnType<Query>
     >;
     Object.assign(ret, unsubscribeProps);
     return ret;
@@ -262,7 +267,11 @@ export class ConvexClient {
    *
    * @return an {@link Unsubscribe} function to stop calling the callback.
    */
-  onPaginatedUpdate_experimental<Query extends FunctionReference<"query">>(
+  onPaginatedUpdate_experimental<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     args: FunctionArgs<Query>,
     options: { initialNumItems: number },
@@ -487,7 +496,11 @@ export class ConvexClient {
    * @param options - A {@link MutationOptions} options object for the mutation.
    * @returns A promise of the mutation's result.
    */
-  async mutation<Mutation extends FunctionReference<"mutation">>(
+  async mutation<
+    Mutation extends
+      | FunctionReference<"mutation">
+      | FunctionReference_future<"mutation">,
+  >(
     mutation: Mutation,
     args: FunctionArgs<Mutation>,
     options?: MutationOptions,
@@ -504,7 +517,11 @@ export class ConvexClient {
    * @param args - An arguments object for the action.
    * @returns A promise of the action's result.
    */
-  async action<Action extends FunctionReference<"action">>(
+  async action<
+    Action extends
+      | FunctionReference<"action">
+      | FunctionReference_future<"action">,
+  >(
     action: Action,
     args: FunctionArgs<Action>,
   ): Promise<Awaited<FunctionReturnType<Action>>> {
@@ -520,13 +537,17 @@ export class ConvexClient {
    * @param args - An arguments object for the query.
    * @returns A promise of the query's result.
    */
-  async query<Query extends FunctionReference<"query">>(
+  async query<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
-    args: Query["_args"],
-  ): Promise<Awaited<Query["_returnType"]>> {
+    args: FunctionArgs<Query>,
+  ): Promise<Awaited<FunctionReturnType<Query>>> {
     if (this.disabled) throw new Error("ConvexClient is disabled");
     const value = this.client.localQueryResult(getFunctionName(query), args) as
-      | Awaited<Query["_returnType"]>
+      | Awaited<FunctionReturnType<Query>>
       | undefined;
     if (value !== undefined) return Promise.resolve(value);
 
@@ -583,7 +604,7 @@ type QueryInfo = {
   queryToken: QueryToken | PaginatedQueryToken;
   hasEverRun: boolean;
   // query, args and paginationOptions are just here for debugging, the queryToken is authoritative
-  query: FunctionReference<"query">;
+  query: FunctionReference<"query"> | FunctionReference_future<"query">;
   args: any;
   paginationOptions: { initialNumItems: number; id: number } | undefined;
 };

package/src/browser/sync/optimistic_updates.ts

@@ -1,9 +1,10 @@
 import { Value } from "../../values/index.js";
 import {
   FunctionArgs,
-  FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
+  FunctionReference,
+  FunctionReference_future,
 } from "../../server/api.js";
 
 /**
@@ -25,7 +26,11 @@ export interface OptimisticLocalStore {
    * @returns The query result or `undefined` if the query is not currently
    * in the client.
    */
-  getQuery<Query extends FunctionReference<"query">>(
+  getQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     ...args: OptionalRestArgs<Query>
   ): undefined | FunctionReturnType<Query>;
@@ -46,7 +51,11 @@ export interface OptimisticLocalStore {
    *   - `args` - The arguments object for the query.
    *   - `value` The query result or `undefined` if the query is loading.
    */
-  getAllQueries<Query extends FunctionReference<"query">>(
+  getAllQueries<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
   ): {
     args: FunctionArgs<Query>;
@@ -66,7 +75,11 @@ export interface OptimisticLocalStore {
    * @param value - The new value to set the query to or `undefined` to remove
    * it from the client.
    */
-  setQuery<Query extends FunctionReference<"query">>(
+  setQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     args: FunctionArgs<Query>,
     value: undefined | FunctionReturnType<Query>,

package/src/browser/sync/optimistic_updates_impl.ts

@@ -1,9 +1,10 @@
 import {
   FunctionArgs,
-  FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
   getFunctionName,
+  FunctionReference,
+  FunctionReference_future,
 } from "../../server/api.js";
 import { parseArgs } from "../../common/index.js";
 import { Value } from "../../values/index.js";
@@ -40,7 +41,11 @@ class OptimisticLocalStoreImpl implements OptimisticLocalStore {
     this.modifiedQueries = [];
   }
 
-  getQuery<Query extends FunctionReference<"query">>(
+  getQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     ...args: OptionalRestArgs<Query>
   ): undefined | FunctionReturnType<Query> {
@@ -55,7 +60,11 @@ class OptimisticLocalStoreImpl implements OptimisticLocalStore {
     return OptimisticLocalStoreImpl.queryValue(queryResult.result);
   }
 
-  getAllQueries<Query extends FunctionReference<"query">>(
+  getAllQueries<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
   ): {
     args: FunctionArgs<Query>;
@@ -77,7 +86,11 @@ class OptimisticLocalStoreImpl implements OptimisticLocalStore {
     return queriesWithName;
   }
 
-  setQuery<QueryReference extends FunctionReference<"query">>(
+  setQuery<
+    QueryReference extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     queryReference: QueryReference,
     args: FunctionArgs<QueryReference>,
     value: undefined | FunctionReturnType<QueryReference>,

package/src/bundler/index.ts

@@ -205,6 +205,7 @@ export async function bundle({
   modules: Bundle[];
   externalDependencies: Map<string, string>;
   bundledModuleNames: Set<string>;
+  metafile: esbuild.Metafile | null;
 }> {
   const availableExternalPackages = await computeExternalPackages(
     ctx,
@@ -264,6 +265,7 @@ export async function bundle({
       result.externalModuleNames,
     ),
     bundledModuleNames: result.bundledModuleNames,
+    metafile: result.metafile ?? null,
   };
 }
 
@@ -321,10 +323,13 @@ export async function bundleSchema(
     platform: "browser",
     extraConditions,
   });
-  return result.modules;
+  return { modules: result.modules, metafile: result.metafile };
 }
 
-export async function bundleAuthConfig(ctx: Context, dir: string) {
+export async function bundleAuthConfig(
+  ctx: Context,
+  dir: string,
+): Promise<{ modules: Bundle[]; metafile: esbuild.Metafile | null }> {
   const authConfigPath = path.resolve(dir, "auth.config.js");
   const authConfigTsPath = path.resolve(dir, "auth.config.ts");
   if (ctx.fs.exists(authConfigPath) && ctx.fs.exists(authConfigTsPath)) {
@@ -343,7 +348,7 @@ export async function bundleAuthConfig(ctx: Context, dir: string) {
         `Found no auth config file at ${authConfigTsPath} or ${authConfigPath} so there are no configured auth providers`,
       ),
     );
-    return [];
+    return { modules: [], metafile: null };
   }
   logVerbose(chalkStderr.yellow(`Bundling auth config found at ${chosenPath}`));
   const result = await bundle({
@@ -355,7 +360,7 @@ export async function bundleAuthConfig(ctx: Context, dir: string) {
     // The auth config must be one module
     splitting: false,
   });
-  return result.modules;
+  return { modules: result.modules, metafile: result.metafile };
 }
 
 export async function doesImportConvexHttpRouter(source: string) {

package/src/cli/codegen.ts

@@ -67,7 +67,6 @@ export const codegen = new Command("codegen")
       liveComponentSources: !!options.liveComponentSources,
       debugNodeApis: false,
       systemUdfs: !!options.systemUdfs,
-      largeIndexDeletionCheck: "no verification" as const, // `codegen` is a read-only operation
       codegenOnlyThisComponent: options.componentDir,
     };
 

package/src/cli/configure.ts

@@ -122,17 +122,22 @@ export async function deploymentCredentialsOrConfigure(
     chosenConfiguration,
     cmdOptions,
   );
-  const { convexSiteUrl: siteUrl } = await fetchDeploymentCanonicalUrls(ctx, {
-    adminKey: selectedDeployment.adminKey,
-    deploymentUrl: selectedDeployment.url,
-  });
+  const { convexCloudUrl, convexSiteUrl: siteUrl } =
+    await fetchDeploymentCanonicalUrls(ctx, {
+      adminKey: selectedDeployment.adminKey,
+      deploymentUrl: selectedDeployment.url,
+    });
+  const applicationUrl = deploymentUrlForApplicationEnv(
+    selectedDeployment,
+    convexCloudUrl,
+  );
 
   if (selectedDeployment.deploymentFields !== null) {
     // Set the `CONVEX_DEPLOYMENT` env var + the `CONVEX_URL` env var
     await updateEnvAndConfigForDeploymentSelection(
       ctx,
       {
-        url: selectedDeployment.url,
+        url: applicationUrl,
         siteUrl,
         deploymentName: selectedDeployment.deploymentFields.deploymentName,
         teamSlug: selectedDeployment.deploymentFields.teamSlug,
@@ -160,6 +165,21 @@ export async function deploymentCredentialsOrConfigure(
   };
 }
 
+export function deploymentUrlForApplicationEnv(
+  selectedDeployment: {
+    url: string;
+    deploymentFields: { deploymentType: DeploymentType } | null;
+  },
+  canonicalCloudUrl: string,
+): string {
+  const deploymentType = selectedDeployment.deploymentFields?.deploymentType;
+  return deploymentType !== undefined &&
+    deploymentType !== "local" &&
+    deploymentType !== "anonymous"
+    ? canonicalCloudUrl
+    : selectedDeployment.url;
+}
+
 export async function _deploymentCredentialsOrConfigure(
   ctx: Context,
   deploymentSelection: DeploymentSelection,
@@ -608,14 +628,14 @@ async function selectExistingProject(
   devDeployment: "cloud" | "local";
 }> {
   const {
-    team: { slug: teamSlug },
+    team: { id: teamId, slug: teamSlug },
     chosen,
   } = await validateOrSelectTeam(ctx, config.team, "Team:");
 
   const projectSlug = await validateOrSelectProject(
     ctx,
     config.project,
-    teamSlug,
+    teamId,
     "Configure project",
     "Project:",
   );