import { FunctionReference, OptionalRestArgs } from "../server/api.js";
import { Id } from "../values/value.js";
/**
* A {@link FunctionReference} that can be scheduled to run in the future.
*
* Schedulable functions are mutations and actions that are public or internal.
*
* @public
*/
export type SchedulableFunctionReference = FunctionReference<
"mutation" | "action",
"public" | "internal"
>;
/**
* An interface to schedule Convex functions to run in the future.
*
* Available as `ctx.scheduler` in mutations and actions.
*
* **Execution guarantees:**
* - **Scheduled mutations** are guaranteed to execute **exactly once**. They
* are automatically retried on transient errors.
* - **Scheduled actions** execute **at most once**. They are not retried and
* may fail due to transient errors.
*
* Consider using an `internalMutation` or `internalAction` to ensure that
* scheduled functions cannot be called directly from a client.
*
* @example
* ```typescript
* import { mutation } from "./_generated/server";
* import { internal } from "./_generated/api";
* import { v } from "convex/values";
*
* export const createOrder = mutation({
* args: { items: v.array(v.string()) },
* returns: v.null(),
* handler: async (ctx, args) => {
* const orderId = await ctx.db.insert("orders", { items: args.items });
*
* // Run immediately after this mutation commits:
* await ctx.scheduler.runAfter(0, internal.emails.sendConfirmation, {
* orderId,
* });
*
* // Run cleanup in 7 days:
* await ctx.scheduler.runAfter(
* 7 * 24 * 60 * 60 * 1000,
* internal.orders.archiveOrder,
* { orderId },
* );
*
* return null;
* },
* });
* ```
*
* @see https://docs.convex.dev/scheduling/scheduled-functions
* @public
*/
export interface Scheduler {
/**
* Schedule a function to execute after a delay.
*
* @example
* ```typescript
* // Schedule to run as soon as possible (if this is a mutation it would be after this mutation commits):
* await ctx.scheduler.runAfter(0, internal.tasks.process, { taskId });
*
* // Run after 5 seconds:
* await ctx.scheduler.runAfter(5000, internal.tasks.process, { taskId });
*
* // Run after 1 hour:
* await ctx.scheduler.runAfter(60 * 60 * 1000, internal.cleanup.run, {});
* ```
*
* @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 functionReference - A {@link FunctionReference} for the function
* to schedule.
* @param args - Arguments to call the scheduled functions with.
* @returns The ID of the scheduled function in the `_scheduled_functions`
* system table. Use this to cancel it later if needed.
**/
runAfter<FuncRef extends SchedulableFunctionReference>(
delayMs: number,
functionReference: FuncRef,
...args: OptionalRestArgs<FuncRef>
): Promise<Id<"_scheduled_functions">>;
/**
* Schedule a function to execute at a specific time.
*
* @example
* ```typescript
* // Run at a specific Date:
* await ctx.scheduler.runAt(
* new Date("2030-01-01T00:00:00Z"),
* internal.events.triggerNewYear,
* {},
* );
*
* // Run at a timestamp (milliseconds since epoch):
* await ctx.scheduler.runAt(Date.now() + 60000, internal.tasks.process, { taskId });
* ```
*
* @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 functionReference - A {@link FunctionReference} for the function
* to schedule.
* @param args - Arguments to call the scheduled functions with.
* @returns The ID of the scheduled function in the `_scheduled_functions`
* system table.
**/
runAt<FuncRef extends SchedulableFunctionReference>(
timestamp: number | Date,
functionReference: FuncRef,
...args: OptionalRestArgs<FuncRef>
): Promise<Id<"_scheduled_functions">>;
/**
* Cancel a previously scheduled function.
*
* For scheduled **actions**: if the action has not started, it will
* not run. If it is already in progress, it will continue running but any
* new functions it tries to schedule will be canceled.
* If it had already completed, canceling will throw an error.
* For scheduled **mutations**: the mutation will either show up as
* "pending", "completed", or "failed", but never "inProgress".
* Canceling a mutation will atomically cancel it entirely or fail to cancel
* if it has committed. It is a transaction that will either run to
* completion and commit or fully roll back.
*
* @example
* ```typescript
* // Cancel a scheduled function:
* await ctx.scheduler.cancel(scheduledFunctionId);
* ```
*
* @param id - The ID of the scheduled function to cancel (returned by
* `runAfter` or `runAt`).
*/
cancel(id: Id<"_scheduled_functions">): Promise<void>;
}
