Scheduling

The Scheduler service schedules Confect functions to run in the future. It wraps Convex’s scheduler with Effect-native types: delays use Duration and timestamps use DateTime. Both runAfter() and runAt() accept a ref to a mutation or action and an optional args object matching the ref’s args schema. They return an ID from the _scheduled_functions system table. Pass this ID to cancel() to cancel the scheduled function.

Run after a delay

import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import refs from "./confect/_generated/refs";
import { Scheduler } from "./confect/_generated/services";

Effect.gen(function* () {
  const scheduler = yield* Scheduler;

  yield* scheduler.runAfter(Duration.minutes(5), refs.internal.messages.send, {
    text: "Hello",
  });
});

Run at a specific time

Effect.gen(function* () {
  const scheduler = yield* Scheduler;

  const dateTime = yield* DateTime.make("2030-01-01T00:00:00Z");

  yield* scheduler.runAt(dateTime, refs.internal.messages.send, {
    text: "Happy new year",
  });
});

Cancel a scheduled function

Call scheduler.cancel(id) to cancel a previously scheduled function. It returns an Effect<void> and is available wherever the Scheduler service is provided, including mutations and actions.

Effect.gen(function* () {
  const scheduler = yield* Scheduler;

  const scheduledFunctionId = yield* scheduler.runAfter(
    Duration.minutes(5),
    refs.internal.messages.send,
    { text: "Hello" },
  );

  yield* scheduler.cancel(scheduledFunctionId);
});

Cancellation follows Convex’s semantics: a pending function will not run. An action that has already started continues running, but any new functions it schedules are canceled. A mutation is canceled atomically or cannot be canceled if it has already committed. Convex cancellation errors surface as Effect defects, matching runAfter and runAt. For the full scheduling APIs, see the Effect Duration documentation, the Effect DateTime documentation, and the Convex scheduling documentation.

Getting Started

Concepts

Server

Clients

Guides

Run after a delay

Run at a specific time

Cancel a scheduled function

​Run after a delay

​Run at a specific time

​Cancel a scheduled function

Run after a delay

Run at a specific time

Cancel a scheduled function