convex 1.45.0 → 1.47.0

package/src/cli/projectCreate.ts

@@ -64,7 +64,7 @@ async function runProjectCreate(
   logMessage(
     chalkStderr.gray(
       `Next, add a deployment with ` +
-        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev --type dev\` ` +
+        `\`npx convex deployment create ${team.slug}:${projectSlug}:dev/my-feature --type dev --select\` ` +
         `(pass \`--region us\` to choose a region).`,
     ),
   );

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.45.0";
+export const version = "1.47.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],

package/src/react/queries_observer.ts

@@ -1,15 +1,27 @@
 import { convexToJson, Value } from "../values/index.js";
 import { PaginatedWatch, Watch } from "./client.js";
 import { QueryJournal } from "../browser/sync/protocol.js";
-import { FunctionReference, getFunctionName } from "../server/api.js";
-import { RequestForQueries } from "./use_queries.js";
+import {
+  getFunctionName,
+  FunctionReference,
+  FunctionReference_future,
+} from "../server/api.js";
 import { PaginatedQueryResult } from "../browser/sync/pagination.js";
 import { SubscribeToPaginatedQueryOptions } from "../browser/sync/paginated_query_client.js";
 
 type Identifier = string;
 
+type RequestForQueriesCompat = Record<
+  Identifier,
+  {
+    query: FunctionReference<"query"> | FunctionReference_future<"query">;
+    args: Record<string, Value>;
+    paginationOptions?: SubscribeToPaginatedQueryOptions;
+  }
+>;
+
 type QueryInfo = {
-  query: FunctionReference<"query">;
+  query: FunctionReference<"query"> | FunctionReference_future<"query">;
   args: Record<string, Value>;
   watch: Watch<Value> | PaginatedWatch<Value>;
   unsubscribe: () => void;
@@ -18,7 +30,7 @@ type QueryInfo = {
 
 export interface CreateWatch {
   (
-    query: FunctionReference<"query">,
+    query: FunctionReference<"query"> | FunctionReference_future<"query">,
     args: Record<string, Value>,
     options: {
       journal?: QueryJournal;
@@ -44,16 +56,7 @@ export class QueriesObserver {
     this.listeners = new Set();
   }
 
-  setQueries(
-    newQueries: Record<
-      Identifier,
-      {
-        query: FunctionReference<"query">;
-        args: Record<string, Value>;
-        paginationOptions?: SubscribeToPaginatedQueryOptions;
-      }
-    >,
-  ) {
+  setQueries(newQueries: RequestForQueriesCompat) {
     // Add the new queries before unsubscribing from the old ones so that
     // the deduping in the `ConvexReactClient` can help if there are duplicates.
     for (const identifier of Object.keys(newQueries)) {
@@ -107,7 +110,7 @@ export class QueriesObserver {
   }
 
   getLocalResults(
-    queries: RequestForQueries,
+    queries: RequestForQueriesCompat,
   ): Record<
     Identifier,
     Value | undefined | Error | PaginatedQueryResult<Value>
@@ -173,7 +176,7 @@ export class QueriesObserver {
 
   private addQuery(
     identifier: Identifier,
-    query: FunctionReference<"query">,
+    query: FunctionReference<"query"> | FunctionReference_future<"query">,
     args: Record<string, Value>,
     {
       paginationOptions,

package/src/react/use_paginated_query2.ts

@@ -1,6 +1,10 @@
 import { useState } from "react";
 
-import { FunctionReference, getFunctionName } from "../server/api.js";
+import {
+  FunctionReference,
+  FunctionReturnType,
+  getFunctionName,
+} from "../server/api.js";
 import {
   PaginatedQueryReference,
   PaginatedQueryArgs,
@@ -255,7 +259,7 @@ export function usePaginatedQuery_experimental<
       throw new Error("Why is it missing?");
     }
     const internalResult = {
-      results: [] as Query["_returnType"]["page"],
+      results: [] as FunctionReturnType<Query>["page"],
       status: "LoadingFirstPage" as const,
       isLoading: true as const,
       loadMore: function skipNOP(_numItems: number) {
@@ -270,7 +274,7 @@ export function usePaginatedQuery_experimental<
     return internalResult as unknown as UsePaginatedQueryReturnType<Query>;
   }
   const result = resultsObject.paginatedQuery as
-    | PaginatedQueryResult<Query["_returnType"]["page"][number]>
+    | PaginatedQueryResult<FunctionReturnType<Query>["page"][number]>
     | Error;
 
   // TODO this is a weird mix of responsibilities:
@@ -279,7 +283,7 @@ export function usePaginatedQuery_experimental<
   // It comes back to why we'd ever get undefined when asking about a query; have we not yet called subscribe for it?
   if (result === undefined) {
     const internalResult = {
-      results: [] as Query["_returnType"]["page"],
+      results: [] as FunctionReturnType<Query>["page"],
       loadMore: () => false,
       isLoading: true as const,
       status: "LoadingFirstPage" as const,
@@ -313,7 +317,7 @@ export function usePaginatedQuery_experimental<
       );
       setState(createInitialState);
       const internalResult = {
-        results: [] as Query["_returnType"]["page"],
+        results: [] as FunctionReturnType<Query>["page"],
         loadMore: () => false,
         isLoading: true as const,
         status: "LoadingFirstPage" as const,
@@ -329,7 +333,7 @@ export function usePaginatedQuery_experimental<
         throw result;
       }
       const internalResult = {
-        results: [] as Query["_returnType"]["page"],
+        results: [] as FunctionReturnType<Query>["page"],
         loadMore: () => false,
         isLoading: false as const,
         status: "Error" as const,

package/src/react/use_queries.ts

@@ -4,7 +4,7 @@ import { useConvex } from "./client.js";
 import { CreateWatch, QueriesObserver } from "./queries_observer.js";
 import { useSubscription } from "./use_subscription.js";
 import { QueryJournal } from "../browser/index.js";
-import { FunctionReference } from "../server/api.js";
+import { FunctionReference, FunctionReference_future } from "../server/api.js";
 import { SubscribeToPaginatedQueryOptions } from "../browser/sync/paginated_query_client.js";
 
 /**
@@ -15,9 +15,10 @@ import { SubscribeToPaginatedQueryOptions } from "../browser/sync/paginated_quer
  * of queries without violating the rules of React hooks.
  *
  * This hook accepts an object whose keys are identifiers for each query and the
- * values are objects of `{ query: FunctionReference, args: Record<string, Value> }`. The
- * `query` is a FunctionReference for the Convex query function to load, and the `args` are
- * the arguments to that function.
+ * values are objects of
+ * `{ query: FunctionReference | FunctionReference_future, args: Record<string, Value> }`.
+ * The `query` is a reference to the Convex query function to load, and the
+ * `args` are the arguments to that function.
  *
  * The hook returns an object that maps each identifier to the result of the query,
  * `undefined` if the query is still loading, or an instance of `Error` if the query
@@ -59,7 +60,7 @@ import { SubscribeToPaginatedQueryOptions } from "../browser/sync/paginated_quer
  * @public
  */
 export function useQueries(
-  queries: RequestForQueries,
+  queries: RequestForQueriesCompat,
 ): Record<string, any | undefined | Error> {
   const convex = useConvex();
   if (convex === undefined) {
@@ -73,7 +74,7 @@ export function useQueries(
   }
   const createWatch = useMemo(() => {
     return (
-      query: FunctionReference<"query">,
+      query: FunctionReference<"query"> | FunctionReference_future<"query">,
       args: Record<string, Value>,
       {
         journal,
@@ -97,7 +98,7 @@ export function useQueries(
  * Internal version of `useQueries` that is exported for testing.
  */
 export function useQueriesHelper(
-  queries: RequestForQueries,
+  queries: RequestForQueriesCompat,
   createWatch: CreateWatch,
 ): Record<string, any | undefined | Error> {
   const [observer] = useState(() => new QueriesObserver(createWatch));
@@ -143,3 +144,18 @@ export type RequestForQueries = Record<
     paginationOptions?: SubscribeToPaginatedQueryOptions;
   }
 >;
+
+// The `queries` parameter of `useQueries`: `RequestForQueries` with `query`
+// also accepting a `FunctionReference_future`. The exported type stays a plain
+// reference so that code reading a `query` out of one gets a
+// `FunctionReference` it can forward anywhere. Module-local so that a
+// consumer's declaration file inlines it rather than importing it from a path
+// outside the package's public entry points.
+type RequestForQueriesCompat = Record<
+  string,
+  {
+    query: FunctionReference<"query"> | FunctionReference_future<"query">;
+    args: Record<string, Value>;
+    paginationOptions?: SubscribeToPaginatedQueryOptions;
+  }
+>;