convex/src/server/registration.ts

Client for the Convex Cloud

import {
  Auth,
  DatabaseReader,
  DatabaseWriter,
  StorageReader,
  StorageWriter,
} from ".";
import {
  ActionNames,
  GenericAPI,
  MutationNames,
  NamedAction,
  NamedMutation,
  NamedQuery,
  QueryNames,
} from "../browser";
import { GenericDataModel } from "./data_model.js";
import { Scheduler } from "./scheduler";

/**
 * A set of services for use within Convex mutation functions.
 *
 * The mutation context is passed as the first argument to any Convex mutation
 * function run on the server.
 *
 * If you're using code generation, use the `MutationCtx` type in
 * `convex/_generated/server.d.ts` which is typed for your data model.
 *
 * @public
 */
export type MutationCtx<
  DataModel extends GenericDataModel,
  API extends GenericAPI
> = {
  db: DatabaseWriter<DataModel>;
  auth: Auth;
  storage: StorageWriter;
  scheduler: Scheduler<API>;
};

/**
 * A set of services for use within Convex query functions.
 *
 * The query context is passed as the first argument to any Convex query
 * function run on the server.
 *
 * This differs from the {@link MutationCtx} because all of the services are
 * read-only.
 *
 * If you're using code generation, use the `QueryCtx` type in
 * `convex/_generated/server.d.ts` which is typed for your data model.
 *
 * @public
 */
export type QueryCtx<DataModel extends GenericDataModel> = {
  db: DatabaseReader<DataModel>;
  auth: Auth;
  storage: StorageReader;
};

/**
 * A set of services for use within Convex action.
 *
 * The context is passed as the first argument to any Convex action
 * run on the server.
 *
 * If you're using code generation, use the `ActionCtx` type in
 * `convex/_generated/server.d.ts` which is typed for your data model.
 *
 * @public
 */
export type ActionCtx<API extends GenericAPI> = {
  runQuery<Name extends QueryNames<API>>(
    name: Name,
    ...args: Parameters<NamedQuery<API, Name>>
  ): Promise<ReturnType<NamedQuery<API, Name>>>;

  runMutation<Name extends MutationNames<API>>(
    name: Name,
    ...args: Parameters<NamedMutation<API, Name>>
  ): Promise<ReturnType<NamedMutation<API, Name>>>;

  scheduler: Scheduler<API>;

  auth: Auth;
};

/**
 * A set of services for use within Convex HTTP endpoint.
 *
 * The context is passed as the first argument to any Convex HTTP
 * endpoint run on the server.
 *
 * If you're using code generation, use the `HttpEndpointCtx` type in
 * `convex/_generated/server.d.ts` which is typed for your data model.
 *
 * @public
 */
export type HttpEndpointCtx<API extends GenericAPI> = {
  runQuery<Name extends QueryNames<API>>(
    name: Name,
    ...args: Parameters<NamedQuery<API, Name>>
  ): Promise<ReturnType<NamedQuery<API, Name>>>;

  runMutation<Name extends MutationNames<API>>(
    name: Name,
    ...args: Parameters<NamedMutation<API, Name>>
  ): Promise<ReturnType<NamedMutation<API, Name>>>;

  runAction<Name extends ActionNames<API>>(
    name: Name,
    ...args: Parameters<NamedAction<API, Name>>
  ): Promise<ReturnType<NamedAction<API, Name>>>;

  auth: Auth;
};

/**
 * A mutation function that is part of this app's public API.
 *
 * You can create public mutations by wrapping your function in
 * {@link mutationGeneric} and exporting it.
 *
 * @public
 */
export type PublicMutation<
  DataModel extends GenericDataModel,
  API extends GenericAPI,
  Args extends any[],
  Output
> = {
  args: Args;
  output: Output;

  (ctx: MutationCtx<DataModel, API>, ...args: Args): Output;
  isMutation: true;
  isRegistered?: true;

  /** @internal */
  invokeMutation(argsStr: string): Promise<string>;
};

/**
 * A query function that is part of this app's public API.
 *
 * You can create public queries by wrapping your function in
 * {@link queryGeneric} and exporting it.
 *
 * @public
 */
export type PublicQuery<
  DataModel extends GenericDataModel,
  Args extends any[],
  Output
> = {
  args: Args;
  output: Output;

  (ctx: QueryCtx<DataModel>, ...args: Args): Output;
  isQuery: true;
  isRegistered?: true;

  /** @internal */
  invokeQuery(argsStr: string): Promise<string>;
};

/**
 * An action that is part of this app's public API.
 *
 * You can create public action by wrapping your function in
 * {@link actionGeneric} and exporting it.
 *
 * @public
 */
export type PublicAction<API extends GenericAPI, Args extends any[], Output> = {
  args: Args;
  output: Output;

  (ctx: ActionCtx<API>, ...args: Args): Output;
  isAction: true;
  isRegistered?: true;

  /** @internal */
  invokeAction(requestId: string, argsStr: string): Promise<string>;
};

/**
 * An HTTP endpoint that is part of this app's public API.
 *
 * You can create public HTTP endpoints by wrapping your function in
 * {@link httpEndpointGeneric} and exporting it.
 *
 * @public
 */
export type PublicHttpEndpoint<API extends GenericAPI> = {
  (ctx: HttpEndpointCtx<API>, request: Request): Response;
  isHttp: true;
  isRegistered?: true;

  /** @internal */
  invokeHttpEndpoint(argsStr: string): Promise<string>;
};

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link mutationGeneric} a type specific to your data model.
 * @public
 */
export type MutationBuilder<
  DataModel extends GenericDataModel,
  API extends GenericAPI
> = <Args extends any[], Output>(
  func: (ctx: MutationCtx<DataModel, API>, ...args: Args) => Output
) => PublicMutation<DataModel, API, Args, Output>;

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link queryGeneric} a type specific to your data model.
 * @public
 */
export type QueryBuilderForDataModel<DataModel extends GenericDataModel> = <
  Args extends any[],
  Output
>(
  func: (ctx: QueryCtx<DataModel>, ...args: Args) => Output
) => PublicQuery<DataModel, Args, Output>;

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link actionGeneric} a type specific to your data model.
 * @public
 */
export type ActionBuilderForAPI<API extends GenericAPI> = <
  Args extends any[],
  Output
>(
  func: (ctx: ActionCtx<API>, ...args: Args) => Output
) => PublicAction<API, Args, Output>;

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link httpEndpointGeneric} a type specific to your data model
 * and functions.
 * @public
 */
export type HttpEndpointBuilderForAPI<API extends GenericAPI> = (
  func: (ctx: HttpEndpointCtx<API>, request: Request) => Promise<Response>
) => PublicHttpEndpoint<API>;