convex 1.45.0-alpha.0 → 1.46.0

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;
+  }
+>;

package/src/server/api.ts

@@ -42,6 +42,9 @@ export type FunctionType = "query" | "mutation" | "action";
  * const result = useQuery(api.myModule.myFunction);
  * ```
  *
+ * If you want to accept a `FunctionReference` as a callback argument, prefer
+ * typing the callback parameter as {@link FunctionReference_future}.
+ *
  * @typeParam Type - The type of the function ("query", "mutation", or "action").
  * @typeParam Visibility - The visibility of the function ("public" or "internal").
  * @typeParam Args - The arguments to this function. This is an object mapping
@@ -58,9 +61,179 @@ export type FunctionReference<
 > = {
   _type: Type;
   _visibility: Visibility;
+  /**
+   * To read the arguments for a `FunctionReference`, prefer
+   * {@link FunctionArgs}.
+   *
+   * This slot will be removed in a future version.
+   *
+   * @deprecated
+   */
   _args: Args;
+  /**
+   * To read the return type of a `FunctionReference`, prefer
+   * {@link FunctionReturnType}.
+   *
+   * This slot will be removed in a future version.
+   *
+   * @deprecated
+   */
   _returnType: ReturnType;
   _componentPath: ComponentPath;
+  /**
+   * To read the arguments or return type of a `FunctionReference`, prefer
+   * {@link FunctionArgs} and {@link FunctionReturnType}.
+   */
+  // This phantom slot exists so that a `FunctionReference` can be checked
+  // against a `FunctionReference_future`. It changes nothing about how two
+  // `FunctionReference`s compare with each other.
+  //
+  // The slot models the function itself: it puts `Args` in a contravariant
+  // position and `ReturnType` in a covariant one, so the slot alone is enough
+  // to compare a reference the way TypeScript compares two functions.
+  //
+  // In that comparison the `keys` parameter has an important role. It carries
+  // the keys of `Args`, so that checking a `FunctionReference` against a
+  // `FunctionReference_future` also checks that every key the consumer passes
+  // is a key the function declares. TypeScript treats a surplus property as
+  // harmless, but a Convex argument validator rejects it, so this is what
+  // makes the comparison match the runtime. See `FunctionReferenceArgKeys`.
+  _fn?(args: Args, keys: FunctionReferenceArgKeys<Args>): ReturnType;
+};
+
+/**
+ * The keys of a reference's arguments.
+ *
+ * `0 extends 1 & Args` holds only when `Args` is `any`. That maps to `any`
+ * rather than `keyof any` so that an untyped reference neither imposes nor
+ * fails the key check in either direction. Arguments with an index signature,
+ * such as `EmptyObject` and `DefaultFunctionArgs`, map to `string`, which
+ * accepts every key and leaves the decision to the first parameter.
+ */
+type ArgKeys<Args> = 0 extends 1 & Args ? any : keyof Args;
+
+/**
+ * The second parameter of `FunctionReference._fn`.
+ *
+ * Wrapping the keys in a function of a function puts them two parameters deep,
+ * so comparing this parameter contravariantly checks that every key the
+ * consumer passes is one the function declares. That is the check a Convex
+ * argument validator performs and an ordinary function-type comparison skips.
+ *
+ * The union with {@link UncheckedArgKeys} is what keeps two
+ * `FunctionReference`s comparing as they did before this slot existed. Every
+ * `FunctionReferenceArgKeys` is assignable to `UncheckedArgKeys`, so between
+ * two `FunctionReference`s the keys always relate and only `_args` decides.
+ * {@link FunctionReference_futureArgKeys} is not assignable to it, so a
+ * `FunctionReference` compared against a `FunctionReference_future` has to
+ * satisfy the real check.
+ */
+type FunctionReferenceArgKeys<Args> = 0 extends 1 & Args
+  ? any
+  : ((keys: (key: ArgKeys<Args>) => void) => void) | UncheckedArgKeys;
+
+/**
+ * A keys parameter that every {@link FunctionReferenceArgKeys} is assignable
+ * to, and that no {@link FunctionReference_futureArgKeys} is: `unknown` for
+ * the second parameter accepts the former's missing parameter and rejects the
+ * latter's `never`.
+ */
+type UncheckedArgKeys = (keys: never, unchecked?: unknown) => void;
+
+/**
+ * The second parameter of `FunctionReference_future._fn`. The same shape as
+ * {@link FunctionReferenceArgKeys} plus a `guard` parameter that keeps it out
+ * of {@link UncheckedArgKeys}.
+ */
+type FunctionReference_futureArgKeys<Args> = 0 extends 1 & Args
+  ? any
+  : (keys: (key: ArgKeys<Args>) => void, guard?: never) => void;
+
+/**
+ * A reference to a Convex function whose arguments are checked closer to the
+ * way Convex checks them at runtime.
+ *
+ * Use this instead of {@link FunctionReference} when you accept someone else's
+ * Convex function as a callback and know which arguments you will pass it.
+ *
+ * A plain `FunctionReference` gets a couple things backwards: it accepts a
+ * function requiring arguments you never pass, and rejects a function
+ * accepting broader values than you pass. An ordinary TypeScript function type
+ * doesn't map perfectly either: it treats a surplus argument as harmless,
+ * where a Convex validator rejects it.
+ *
+ * This type melds regular TypeScript function reference behavior with top
+ * level checking of arguments to prevent surplus arguments from hitting
+ * runtime validation errors. The caveat: a surplus key inside a nested object,
+ * an array element, or one arm of a union passes the type check and fails the
+ * validator at runtime.
+ *
+ * ```ts
+ * import { FunctionReference_future } from "convex/server";
+ *
+ * declare function onComplete(
+ *   fn: FunctionReference_future<
+ *     "mutation",
+ *     "internal",
+ *     { taskId: string; force: boolean },
+ *     null
+ *   >,
+ * ): void;
+ *
+ * // Takes exactly `{ taskId: string; force: boolean }`.
+ * onComplete(internal.tasks.finish);
+ * // Takes `{ taskId: string | number; force?: boolean }`: calling it is safe.
+ * onComplete(internal.tasks.finishLoosely);
+ * // Requires a `reason` argument that `onComplete` never passes.
+ * onComplete(internal.tasks.finishWithReason);
+ * //          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ rejected
+ * // Takes only `{ taskId: string }`: its validator would reject `force`.
+ * onComplete(internal.tasks.finishById);
+ * //          ~~~~~~~~~~~~~~~~~~~~~~~~ rejected
+ * ```
+ *
+ * A value of this type is usable with `ctx.runMutation`,
+ * `ctx.scheduler.runAfter`, `createFunctionHandle`, and everything else in
+ * this package that takes a reference, all of which accept either kind.
+ *
+ * It is *not* assignable to a plain `FunctionReference`. Code that wants to
+ * accept both kinds should take
+ * `FunctionReference<...> | FunctionReference_future<...>` and read arguments
+ * and return types through {@link FunctionArgs} and {@link FunctionReturnType}.
+ *
+ * Argument checking here relies on `strictFunctionTypes` (implied by `strict`)
+ * and is skipped for projects that disable it. Everything else about the
+ * reference is compared exactly as `FunctionReference` compares it.
+ *
+ * @typeParam Type - The type of the function ("query", "mutation", or "action").
+ * @typeParam Visibility - The visibility of the function ("public" or "internal").
+ * @typeParam Args - The arguments the consumer of the reference will pass.
+ * @typeParam ReturnType - The return type of this function.
+ * @public
+ */
+export type FunctionReference_future<
+  Type extends FunctionType,
+  Visibility extends FunctionVisibility = "public",
+  Args extends DefaultFunctionArgs = any,
+  ReturnType = any,
+  ComponentPath = string | undefined,
+> = {
+  _type: Type;
+  _visibility: Visibility;
+  _componentPath: ComponentPath;
+  // Declared as a *property* rather than a method: TypeScript compares method
+  // parameters bivariantly and would not check anything. The explicit
+  // `| undefined` is needed because an optional method on the source side
+  // (`FunctionReference._fn`) carries a real `undefined` in its type, which
+  // `exactOptionalPropertyTypes` would otherwise reject.
+  //
+  // Both parameters are compared contravariantly: the first checks that the
+  // consumer's arguments satisfy the function's, the second that the consumer
+  // passes no key the function does not declare. See
+  // `FunctionReference_futureArgKeys`.
+  _fn?:
+    | ((args: Args, keys: FunctionReference_futureArgKeys<Args>) => ReturnType)
+    | undefined;
 };
 
 /**
@@ -76,7 +249,9 @@ export type FunctionReference<
  * @public
  */
 export function getFunctionName(
-  functionReference: AnyFunctionReference,
+  functionReference:
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
 ): string {
   const address = getFunctionAddress(functionReference);
 
@@ -431,13 +606,33 @@ export type PartialApi<API> = {
 export const anyApi: AnyApi = createApi() as any;
 
 /**
- * Given a {@link FunctionReference}, get the return type of the function.
+ * Given a {@link FunctionReference} or {@link FunctionReference_future}, get
+ * the arguments of the function.
  *
  * This is represented as an object mapping argument names to values.
+ *
  * @public
  */
-export type FunctionArgs<FuncRef extends AnyFunctionReference> =
-  FuncRef["_args"];
+export type FunctionArgs<
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
+> = ExtractSignature<FuncRef>["args"];
+
+// The arguments and return type a reference declares. A `FunctionReference`
+// declares them in `_args` and `_returnType`, a `FunctionReference_future`
+// only in its `_fn` slot. Reading the named slots first also covers a
+// reference typed by an older copy of this package, which has no `_fn`.
+type ExtractSignature<FuncRef> = FuncRef extends {
+  _args: infer Args;
+  _returnType: infer R;
+}
+  ? { args: Args; returnType: R }
+  : FuncRef extends {
+        _fn?: ((args: infer Args, keys: never) => infer R) | undefined;
+      }
+    ? { args: Args; returnType: R }
+    : { args: any; returnType: any };
 
 /**
  * A tuple type of the (maybe optional) arguments to `FuncRef`.
@@ -447,10 +642,14 @@ export type FunctionArgs<FuncRef extends AnyFunctionReference> =
  *
  * @public
  */
-export type OptionalRestArgs<FuncRef extends AnyFunctionReference> =
-  FuncRef["_args"] extends EmptyObject
+export type OptionalRestArgs<
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
+> =
+  FunctionArgs<FuncRef> extends EmptyObject
     ? [args?: EmptyObject]
-    : [args: FuncRef["_args"]];
+    : [args: FunctionArgs<FuncRef>];
 
 /**
  * A tuple type of the (maybe optional) arguments to `FuncRef`, followed by an options
@@ -462,19 +661,26 @@ export type OptionalRestArgs<FuncRef extends AnyFunctionReference> =
  * @public
  */
 export type ArgsAndOptions<
-  FuncRef extends AnyFunctionReference,
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
   Options,
-> = FuncRef["_args"] extends EmptyObject
-  ? [args?: EmptyObject, options?: Options]
-  : [args: FuncRef["_args"], options?: Options];
+> =
+  FunctionArgs<FuncRef> extends EmptyObject
+    ? [args?: EmptyObject, options?: Options]
+    : [args: FunctionArgs<FuncRef>, options?: Options];
 
 /**
- * Given a {@link FunctionReference}, get the return type of the function.
+ * Given a {@link FunctionReference} or {@link FunctionReference_future}, get
+ * the return type of the function.
  *
  * @public
  */
-export type FunctionReturnType<FuncRef extends AnyFunctionReference> =
-  FuncRef["_returnType"];
+export type FunctionReturnType<
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
+> = ExtractSignature<FuncRef>["returnType"];
 
 type UndefinedToNull<T> = T extends void ? null : T;
 

package/src/server/components/index.ts

@@ -3,6 +3,7 @@ import { version } from "../../index.js";
 import {
   AnyFunctionReference,
   FunctionReference,
+  FunctionReference_future,
   FunctionType,
 } from "../api.js";
 import { performAsyncSyscall } from "../impl/syscall.js";
@@ -66,12 +67,9 @@ export async function createFunctionHandle<
   Args extends DefaultFunctionArgs,
   ReturnType,
 >(
-  functionReference: FunctionReference<
-    Type,
-    "public" | "internal",
-    Args,
-    ReturnType
-  >,
+  functionReference:
+    | FunctionReference<Type, "public" | "internal", Args, ReturnType>
+    | FunctionReference_future<Type, "public" | "internal", Args, ReturnType>,
 ): Promise<FunctionHandle<Type, Args, ReturnType>> {
   const address = getFunctionAddress(functionReference);
   return await performAsyncSyscall("1.0/createFunctionHandle", {