convex 1.45.0 → 1.46.0

package/src/cli/lib/localDeployment/run.ts

@@ -13,10 +13,28 @@ import detect from "detect-port";
 import { LOCAL_BACKEND_SENTRY_DSN } from "../utils/sentry.js";
 import { createHash } from "crypto";
 import { LocalDeploymentError } from "./errors.js";
-import { LOCAL_BACKEND_INSTANCE_SECRET } from "./utils.js";
+import { LOCAL_BACKEND_INSTANCE_SECRET, releaseDate } from "./utils.js";
 import { DeploymentType, DetailedDeploymentCredentials } from "../api.js";
+import { productionProvisionHost, provisionHost } from "../config.js";
 
 const DEFAULT_STARTUP_TIMEOUT_SECS = 30;
+const FIRST_CONTROL_PLANE_AUTH_BACKEND_VERSION =
+  "precompiled-2026-09-15-4e9b83a";
+
+export function _backendSupportsControlPlaneAuth(version: string): boolean {
+  if (version === FIRST_CONTROL_PLANE_AUTH_BACKEND_VERSION) {
+    return true;
+  }
+  const backendDate = releaseDate(version);
+  const firstSupportedDate = releaseDate(
+    FIRST_CONTROL_PLANE_AUTH_BACKEND_VERSION,
+  );
+  return (
+    backendDate !== null &&
+    firstSupportedDate !== null &&
+    backendDate > firstSupportedDate
+  );
+}
 
 async function parseStartupTimeoutSecs(ctx: Context): Promise<number> {
   const raw = process.env.CONVEX_LOCAL_BACKEND_STARTUP_TIMEOUT_SECS;
@@ -44,6 +62,7 @@ export async function runLocalBackend(
     deploymentKind: LocalDeploymentKind;
     deploymentName: string;
     binaryPath: string;
+    backendVersion: string;
     instanceSecret: string;
     isLatestVersion: boolean;
   },
@@ -128,7 +147,29 @@ export async function runLocalBackend(
       errForSentry: new LocalDeploymentError(message),
     });
   }
-  const commandStr = `${args.binaryPath} ${commandArgs.join(" ")}`;
+  const supportsControlPlane = _backendSupportsControlPlaneAuth(
+    args.backendVersion,
+  );
+  if (supportsControlPlane && provisionHost !== productionProvisionHost) {
+    commandArgs.push("--control-plane-url", provisionHost);
+  }
+  const auth = ctx.bigBrainAuth();
+  if (
+    supportsControlPlane &&
+    args.deploymentKind === "local" &&
+    auth?.kind === "accessToken"
+  ) {
+    commandArgs.push("--control-plane-access-token", auth.accessToken);
+  }
+  const displayArgs = commandArgs.map((arg, index) =>
+    index > 0 &&
+    ["--instance-secret", "--control-plane-access-token"].includes(
+      commandArgs[index - 1],
+    )
+      ? "[REDACTED]"
+      : arg,
+  );
+  const commandStr = `${args.binaryPath} ${displayArgs.join(" ")}`;
   logVerbose(`Starting local backend: \`${commandStr}\``);
   const p = child_process
     .spawn(args.binaryPath, commandArgs, {
@@ -428,6 +469,7 @@ async function startEphemeralLocalBackend(
 
   const { cleanupHandle } = await runLocalBackend(ctx, {
     binaryPath,
+    backendVersion: config.backendVersion,
     ports: config.ports,
     deploymentKind,
     deploymentName: args.deploymentName,

package/src/cli/lib/localDeployment/upgrade.ts

@@ -10,6 +10,7 @@ import {
   saveDeploymentConfig,
 } from "./filePaths.js";
 import { runLocalBackend } from "./run.js";
+import { releaseDate } from "./utils.js";
 import { promptYesNo } from "../utils/prompts.js";
 import { ensureBackendBinaryDownloaded } from "./download.js";
 import {
@@ -66,6 +67,7 @@ export async function handlePotentialUpgradeAndStart(
     );
     const { cleanupHandle } = await runLocalBackend(ctx, {
       binaryPath: args.newBinaryPath,
+      backendVersion: args.newVersion,
       deploymentKind: args.deploymentKind,
       deploymentName: args.deploymentName,
       ports: args.ports,
@@ -99,6 +101,7 @@ export async function handlePotentialUpgradeAndStart(
     });
     const { cleanupHandle } = await runLocalBackend(ctx, {
       binaryPath: oldBinaryPath,
+      backendVersion: args.oldVersion,
       ports: args.ports,
       deploymentKind: args.deploymentKind,
       deploymentName: args.deploymentName,
@@ -155,6 +158,7 @@ async function handleUpgrade(
   logVerbose(`Running backend on new version ${args.newVersion}`);
   const { cleanupHandle } = await runLocalBackend(ctx, {
     binaryPath: args.newBinaryPath,
+    backendVersion: args.newVersion,
     ports: args.ports,
     deploymentKind: args.deploymentKind,
     deploymentName: args.deploymentName,
@@ -182,9 +186,3 @@ export function _isDowngrade(oldVersion: string, newVersion: string): boolean {
   const newDate = releaseDate(newVersion);
   return oldDate !== null && newDate !== null && newDate < oldDate;
 }
-
-// Backend releases are tagged `precompiled-YYYY-MM-DD-<commit>`, so the dates
-// sort lexicographically.
-function releaseDate(version: string): string | null {
-  return /^precompiled-(\d{4}-\d{2}-\d{2})-/.exec(version)?.[1] ?? null;
-}

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

@@ -92,3 +92,9 @@ export function printLocalDeploymentWelcomeMessage() {
 
 export const LOCAL_BACKEND_INSTANCE_SECRET =
   "4361726e697461732c206c69746572616c6c79206d65616e696e6720226c6974";
+
+// Backend releases are tagged `precompiled-YYYY-MM-DD-<commit>`, so the dates
+// sort lexicographically.
+export function releaseDate(version: string): string | null {
+  return /^precompiled-(\d{4}-\d{2}-\d{2})-/.exec(version)?.[1] ?? null;
+}

package/src/cli/lib/run.ts

@@ -535,6 +535,7 @@ export async function pushToDeployment(
       liveComponentSources: args.liveComponentSources,
       pushAllModules: false,
       largeIndexDeletionCheck: "no verification", // `convex run` can’t push to prod
+      warnOnSlowSchemaValidation: true,
       message: null,
     },
     {

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

@@ -972,40 +972,28 @@ export function waitUntilCalled(): [Promise<unknown>, () => void] {
   return [waitPromise, () => onCalled(null)];
 }
 
-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"],
-];
+const BYTE_UNITS = ["bytes", "KiB", "MiB", "GiB", "TiB", "PiB"];
 
 /**
- * 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.
+ * Format a byte count into a human-friendly string, rounded to one decimal
+ * place (dropped when it would be ".0"), e.g. "4.1 MiB" or "128 MiB".
  */
 export function formatSize(n: number): string {
-  if (n === 0) {
-    return "0 bytes";
+  let value = n;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unitIndex++;
   }
-  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}`;
-    }
+  // Rounding to one decimal place can itself reach the next unit's
+  // boundary (e.g. 1023.999 KiB -> "1024.0 KiB" instead of "1.0 MiB").
+  const roundedValue = Number(value.toFixed(1));
+  if (roundedValue >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unitIndex++;
   }
-  return `${n} bytes`;
+  const formatted = value.toFixed(1).replace(/\.0$/, "");
+  return `${formatted} ${BYTE_UNITS[unitIndex]}`;
 }
 
 export function formatDuration(ms: number): string {
@@ -1195,12 +1183,12 @@ export function spawnAsync(
 
 const IDEMPOTENT_METHODS = ["GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE"];
 
-function retryDelay(
+// immediate, 1s delay, 2s delay, 4s delay, etc.
+export function retryDelay(
   attempt: number,
   _error: Error | null,
   _response: Response | null,
 ): number {
-  // immediate, 1s delay, 2s delay, 4s delay, etc.
   const delay = attempt === 0 ? 1 : 2 ** (attempt - 1) * 1000;
   const randomSum = delay * 0.2 * Math.random();
   return delay + randomSum;
@@ -1209,8 +1197,13 @@ function retryDelay(
 function deploymentFetchRetryOn(
   onError?: (err: any, attempt: number) => void,
   method?: string,
+  maxRetries: number = MAX_RETRIES,
+  shouldRetryOverride?: (
+    error: Error | null,
+    response: Response | null,
+  ) => boolean,
 ) {
-  const shouldRetry = function (
+  const defaultShouldRetry = function (
     _attempt: number,
     error: Error | null,
     response: Response | null,
@@ -1266,6 +1259,21 @@ function deploymentFetchRetryOn(
     return { kind: "stop" };
   };
 
+  const shouldRetry = shouldRetryOverride
+    ? function (
+        _attempt: number,
+        error: Error | null,
+        response: Response | null,
+      ): { kind: "retry"; error: any } | { kind: "stop" } {
+        return shouldRetryOverride(error, response)
+          ? {
+              kind: "retry",
+              error:
+                error ?? `Received response with status ${response?.status}`,
+            }
+          : { kind: "stop" };
+      }
+    : defaultShouldRetry;
   return function (
     attempt: number,
     error: Error | null,
@@ -1275,7 +1283,7 @@ function deploymentFetchRetryOn(
     if (result.kind === "retry") {
       onError?.(result.error, attempt);
     }
-    if (attempt >= MAX_RETRIES) {
+    if (attempt >= maxRetries) {
       // Stop retrying if we've exhausted all retries, but do this after we've
       // called `onError` so that the caller can still log the error.
       return false;
@@ -1334,15 +1342,30 @@ export function deploymentFetch(
     deploymentUrl: string;
     adminKey: string;
     onError?: (err: any) => void;
+    // Defaults to MAX_RETRIES. Lower this for best-effort requests (e.g.
+    // advisory checks) where a slow retry loop against an unsupported or
+    // unhealthy endpoint shouldn't hold up the surrounding command.
+    maxRetries?: number | undefined;
+    // Replaces the default retry policy (which is tuned for pushes: network
+    // errors, 404s on fresh deployments, retries of idempotent methods).
+    // Return true to retry the request. Backoff and retry logging are
+    // shared either way.
+    shouldRetry?: (error: Error | null, response: Response | null) => boolean;
   },
 ): typeof fetch {
-  const { deploymentUrl, adminKey, onError } = options;
+  const {
+    deploymentUrl,
+    adminKey,
+    onError,
+    maxRetries = MAX_RETRIES,
+    shouldRetry,
+  } = options;
   const onErrorWithAttempt = (err: any, attempt: number) => {
     onError?.(err);
     if (attempt >= RETRY_LOG_THRESHOLD) {
       logMessage(
         chalkStderr.gray(
-          `Retrying request (attempt ${attempt}/${MAX_RETRIES})...`,
+          `Retrying request (attempt ${attempt}/${maxRetries})...`,
         ),
       );
     }
@@ -1367,7 +1390,12 @@ export function deploymentFetch(
     }
     const func = throwingFetch(url, {
       retryDelay,
-      retryOn: deploymentFetchRetryOn(onErrorWithAttempt, options?.method),
+      retryOn: deploymentFetchRetryOn(
+        onErrorWithAttempt,
+        options?.method,
+        maxRetries,
+        shouldRetry,
+      ),
       ...options,
       headers,
     });

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.45.0";
+export const version = "1.46.0";

package/src/nextjs/index.ts

@@ -48,9 +48,10 @@ import { validateDeploymentUrl } from "../common/index.js";
 import { Preloaded } from "../react/index.js";
 import {
   ArgsAndOptions,
-  FunctionReference,
   FunctionReturnType,
   getFunctionName,
+  FunctionReference,
+  FunctionReference_future,
 } from "../server/index.js";
 import { convexToJson, jsonToConvex } from "../values/index.js";
 
@@ -98,7 +99,9 @@ export type NextjsOptions = {
  * @param options -  A {@link NextjsOptions} options object for the query.
  * @returns A promise of the `Preloaded` payload.
  */
-export async function preloadQuery<Query extends FunctionReference<"query">>(
+export async function preloadQuery<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+>(
   query: Query,
   ...args: ArgsAndOptions<Query, NextjsOptions>
 ): Promise<Preloaded<Query>> {
@@ -117,9 +120,9 @@ export async function preloadQuery<Query extends FunctionReference<"query">>(
  * @param preloaded - The `Preloaded` payload returned by {@link preloadQuery}.
  * @returns The query result.
  */
-export function preloadedQueryResult<Query extends FunctionReference<"query">>(
-  preloaded: Preloaded<Query>,
-): FunctionReturnType<Query> {
+export function preloadedQueryResult<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+>(preloaded: Preloaded<Query>): FunctionReturnType<Query> {
   return jsonToConvex(preloaded._valueJSON);
 }
 
@@ -133,7 +136,9 @@ export function preloadedQueryResult<Query extends FunctionReference<"query">>(
  * @param options -  A {@link NextjsOptions} options object for the query.
  * @returns A promise of the query's result.
  */
-export async function fetchQuery<Query extends FunctionReference<"query">>(
+export async function fetchQuery<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+>(
   query: Query,
   ...args: ArgsAndOptions<Query, NextjsOptions>
 ): Promise<FunctionReturnType<Query>> {
@@ -153,7 +158,9 @@ export async function fetchQuery<Query extends FunctionReference<"query">>(
  * @returns A promise of the mutation's result.
  */
 export async function fetchMutation<
-  Mutation extends FunctionReference<"mutation">,
+  Mutation extends
+    | FunctionReference<"mutation">
+    | FunctionReference_future<"mutation">,
 >(
   mutation: Mutation,
   ...args: ArgsAndOptions<Mutation, NextjsOptions>
@@ -173,7 +180,11 @@ export async function fetchMutation<
  * @param options -  A {@link NextjsOptions} options object for the action.
  * @returns A promise of the action's result.
  */
-export async function fetchAction<Action extends FunctionReference<"action">>(
+export async function fetchAction<
+  Action extends
+    | FunctionReference<"action">
+    | FunctionReference_future<"action">,
+>(
   action: Action,
   ...args: ArgsAndOptions<Action, NextjsOptions>
 ): Promise<FunctionReturnType<Action>> {

package/src/react/client.ts

@@ -21,11 +21,12 @@ import { parseArgs } from "../common/index.js";
 import {
   ArgsAndOptions,
   FunctionArgs,
-  FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
   getFunctionName,
   makeFunctionReference,
+  FunctionReference,
+  FunctionReference_future,
 } from "../server/api.js";
 import { EmptyObject } from "../server/registration.js";
 import {
@@ -55,7 +56,11 @@ if (typeof React === "undefined") {
  *
  * @public
  */
-export interface ReactMutation<Mutation extends FunctionReference<"mutation">> {
+export interface ReactMutation<
+  Mutation extends
+    | FunctionReference<"mutation">
+    | FunctionReference_future<"mutation">,
+> {
   /**
    * Execute the mutation on the server, returning a `Promise` of its return value.
    *
@@ -95,7 +100,9 @@ export interface ReactMutation<Mutation extends FunctionReference<"mutation">> {
 
 // Exported only for testing.
 export function createMutation(
-  mutationReference: FunctionReference<"mutation">,
+  mutationReference:
+    | FunctionReference<"mutation">
+    | FunctionReference_future<"mutation">,
   client: ConvexReactClient,
   update?: OptimisticUpdate<any>,
 ): ReactMutation<any> {
@@ -126,7 +133,11 @@ export function createMutation(
  *
  * @public
  */
-export interface ReactAction<Action extends FunctionReference<"action">> {
+export interface ReactAction<
+  Action extends
+    | FunctionReference<"action">
+    | FunctionReference_future<"action">,
+> {
   /**
    * Execute the function on the server, returning a `Promise` of its return value.
    *
@@ -138,7 +149,9 @@ export interface ReactAction<Action extends FunctionReference<"action">> {
 }
 
 function createAction(
-  actionReference: FunctionReference<"action">,
+  actionReference:
+    | FunctionReference<"action">
+    | FunctionReference_future<"action">,
   client: ConvexReactClient,
 ): ReactAction<any> {
   return function (args?: Record<string, Value>): Promise<unknown> {
@@ -481,7 +494,11 @@ export class ConvexReactClient {
    *
    * @returns The {@link Watch} object.
    */
-  watchQuery<Query extends FunctionReference<"query">>(
+  watchQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     ...argsAndOptions: ArgsAndOptions<Query, WatchQueryOptions>
   ): Watch<FunctionReturnType<Query>> {
@@ -557,9 +574,11 @@ export class ConvexReactClient {
    * @param queryOptions - A query (function reference from an api object) and its args, plus
    * an optional extendSubscriptionFor for how long to subscribe to the query.
    */
-  prewarmQuery<Query extends FunctionReference<"query">>(
-    queryOptions: QueryOptions<Query> & { extendSubscriptionFor?: number },
-  ) {
+  prewarmQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(queryOptions: QueryOptions<Query> & { extendSubscriptionFor?: number }) {
     const extendSubscriptionFor =
       queryOptions.extendSubscriptionFor ?? DEFAULT_EXTEND_SUBSCRIPTION_FOR;
     const watch = this.watchQuery(queryOptions.query, queryOptions.args || {});
@@ -584,9 +603,13 @@ export class ConvexReactClient {
    *
    * @internal
    */
-  watchPaginatedQuery<Query extends FunctionReference<"query">>(
+  watchPaginatedQuery<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
-    args: Query["_args"],
+    args: FunctionArgs<Query>,
     options: WatchPaginatedQueryOptions,
   ): PaginatedWatch<FunctionReturnType<Query>> {
     const name = getFunctionName(query);
@@ -634,7 +657,11 @@ export class ConvexReactClient {
    * @param options - A {@link MutationOptions} options object for the mutation.
    * @returns A promise of the mutation's result.
    */
-  mutation<Mutation extends FunctionReference<"mutation">>(
+  mutation<
+    Mutation extends
+      | FunctionReference<"mutation">
+      | FunctionReference_future<"mutation">,
+  >(
     mutation: Mutation,
     ...argsAndOptions: ArgsAndOptions<
       Mutation,
@@ -655,7 +682,11 @@ export class ConvexReactClient {
    * the arguments will be `{}`.
    * @returns A promise of the action's result.
    */
-  action<Action extends FunctionReference<"action">>(
+  action<
+    Action extends
+      | FunctionReference<"action">
+      | FunctionReference_future<"action">,
+  >(
     action: Action,
     ...args: OptionalRestArgs<Action>
   ): Promise<FunctionReturnType<Action>> {
@@ -675,7 +706,11 @@ export class ConvexReactClient {
    * the arguments will be `{}`.
    * @returns A promise of the query's result.
    */
-  query<Query extends FunctionReference<"query">>(
+  query<
+    Query extends
+      | FunctionReference<"query">
+      | FunctionReference_future<"query">,
+  >(
     query: Query,
     ...args: OptionalRestArgs<Query>
   ): Promise<FunctionReturnType<Query>> {
@@ -815,10 +850,12 @@ export const ConvexProvider: React.FC<{
   );
 };
 
-export type OptionalRestArgsOrSkip<FuncRef extends FunctionReference<any>> =
-  FuncRef["_args"] extends EmptyObject
+export type OptionalRestArgsOrSkip<
+  FuncRef extends FunctionReference<any> | FunctionReference_future<any>,
+> =
+  FunctionArgs<FuncRef> extends EmptyObject
     ? [args?: EmptyObject | "skip"]
-    : [args: FuncRef["_args"] | "skip"];
+    : [args: FunctionArgs<FuncRef> | "skip"];
 
 /**
  * Result returned by object-form {@link useQuery_experimental}.
@@ -831,7 +868,7 @@ export type UseQueryResult<QueryResult, ThrowOnError extends boolean = false> =
   | (ThrowOnError extends true ? never : { status: "error"; error: Error });
 
 type UseQueryOptions<
-  Query extends FunctionReference<"query">,
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
   ThrowOnError extends boolean,
 > = {
   query: Query;
@@ -882,10 +919,12 @@ type UseQueryOptions<
  * @see https://docs.convex.dev/client/react#fetching-data
  * @public
  */
-export function useQuery<Query extends FunctionReference<"query">>(
+export function useQuery<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+>(
   query: Query,
   ...args: OptionalRestArgsOrSkip<Query>
-): Query["_returnType"] | undefined {
+): FunctionReturnType<Query> | undefined {
   const skip = args[0] === "skip";
   const argsObject = args[0] === "skip" ? {} : parseArgs(args[0]);
   const queryReference =
@@ -947,18 +986,18 @@ export function useQuery<Query extends FunctionReference<"query">>(
  * @public
  */
 export function useQuery_experimental<
-  Query extends FunctionReference<"query">,
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
   ThrowOnError extends boolean = false,
 >(
   options: UseQueryOptions<Query, ThrowOnError>,
-): UseQueryResult<Query["_returnType"], ThrowOnError>;
+): UseQueryResult<FunctionReturnType<Query>, ThrowOnError>;
 
 export function useQuery_experimental<
-  Query extends FunctionReference<"query">,
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
   ThrowOnError extends boolean = false,
 >(
   options: UseQueryOptions<Query, ThrowOnError>,
-): UseQueryResult<Query["_returnType"], false> {
+): UseQueryResult<FunctionReturnType<Query>, false> {
   const throwOnError = options.throwOnError ?? false;
   const queryReference =
     typeof options.query === "string"
@@ -1042,9 +1081,11 @@ export function useQuery_experimental<
  * @see https://docs.convex.dev/client/react#editing-data
  * @public
  */
-export function useMutation<Mutation extends FunctionReference<"mutation">>(
-  mutation: Mutation,
-): ReactMutation<Mutation> {
+export function useMutation<
+  Mutation extends
+    | FunctionReference<"mutation">
+    | FunctionReference_future<"mutation">,
+>(mutation: Mutation): ReactMutation<Mutation> {
   const mutationReference =
     typeof mutation === "string"
       ? makeFunctionReference<"mutation", any, any>(mutation)
@@ -1111,9 +1152,11 @@ export function useMutation<Mutation extends FunctionReference<"mutation">>(
  * @see https://docs.convex.dev/functions/actions#calling-actions-from-clients
  * @public
  */
-export function useAction<Action extends FunctionReference<"action">>(
-  action: Action,
-): ReactAction<Action> {
+export function useAction<
+  Action extends
+    | FunctionReference<"action">
+    | FunctionReference_future<"action">,
+>(action: Action): ReactAction<Action> {
   const convex = useContext(ConvexContext);
   const actionReference =
     typeof action === "string"

package/src/react/hydration.tsx

@@ -1,6 +1,12 @@
 import { useMemo } from "react";
 import { useQuery } from "../react/client.js";
-import { FunctionReference, makeFunctionReference } from "../server/api.js";
+import {
+  FunctionArgs,
+  FunctionReturnType,
+  makeFunctionReference,
+  FunctionReference,
+  FunctionReference_future,
+} from "../server/api.js";
 import { jsonToConvex } from "../values/index.js";
 
 /**
@@ -9,7 +15,9 @@ import { jsonToConvex } from "../values/index.js";
  *
  * @public
  */
-export type Preloaded<Query extends FunctionReference<"query">> = {
+export type Preloaded<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+> = {
   __type: Query;
   _name: string;
   _argsJSON: string;
@@ -31,13 +39,13 @@ export type Preloaded<Query extends FunctionReference<"query">> = {
  *
  * @public
  */
-export function usePreloadedQuery<Query extends FunctionReference<"query">>(
-  preloadedQuery: Preloaded<Query>,
-): Query["_returnType"] {
+export function usePreloadedQuery<
+  Query extends FunctionReference<"query"> | FunctionReference_future<"query">,
+>(preloadedQuery: Preloaded<Query>): FunctionReturnType<Query> {
   const args = useMemo(
     () => jsonToConvex(preloadedQuery._argsJSON),
     [preloadedQuery._argsJSON],
-  ) as Query["_args"];
+  ) as FunctionArgs<Query>;
   const preloadedResult = useMemo(
     () => jsonToConvex(preloadedQuery._valueJSON),
     [preloadedQuery._valueJSON],