convex/src/server/scheduler.ts

Client for the Convex Cloud

import {
  ActionNames,
  GenericAPI,
  MutationNames,
  NamedAction,
  NamedMutation,
} from "../browser";

type SchedulableFunctionNames<API extends GenericAPI> =
  | ActionNames<API>
  | MutationNames<API>;

type NamedSchedulableFunction<
  API extends GenericAPI,
  Name extends SchedulableFunctionNames<API>
> = NamedMutation<API, Name> | NamedAction<API, Name>;

/**
 * An interface to schedule Convex functions. The scheduled functions are scheduled
 * and executed only if the function that is scheduling them completes successfully.
 *
 * You can schedule either mutations or actions. Mutations are guaranteed to execute
 * exactly once - they are automatically retried on transient errors and either execute
 * successfully or fail deterministically due to developer error in defining the
 * function. Actions execute at most once - they are not retried and might fail
 * due to transient errors.
 *
 * @public
 */
export interface Scheduler<API extends GenericAPI> {
  /**
   * Schedule a function to execute after a delay.
   *
   * @param delayMs - delay in milliseconds. Must be non-negative. If the delay
   * is zero, the scheduled function will be due to execute immediately after the
   * scheduling one completes.
   * @param name - the name of the function to schedule.
   * @param args - arguments to call the scheduled functions with.
   **/
  runAfter<Name extends SchedulableFunctionNames<API>>(
    delayMs: number,
    name: Name,
    ...args: Parameters<NamedSchedulableFunction<API, Name>>
  ): Promise<void>;

  /**
   * Schedule a function to execute at a given timestamp.
   *
   * @param timestamp - a Date or a timestamp (milliseconds since the epoch).
   * If the timestamp is in the past, the scheduled function will be due to
   * execute immediately after the scheduling one completes. The timestamp can't
   * be more than five years in the past or more than five years in the future.
   * @param name - the name of the function to schedule.
   * @param args - arguments to call the scheduled functions with.
   **/
  runAt<Name extends SchedulableFunctionNames<API>>(
    timestamp: number | Date,
    name: Name,
    ...args: Parameters<NamedSchedulableFunction<API, Name>>
  ): Promise<void>;
}