Cron

Durable recurring schedules using standard cron expressions.

Cron jobs run on a recurring schedule using standard 5-field UTC cron expressions. Schedules are durable — they persist in the database and survive restarts.

Defining a Cron Job

import { cron } from "@chimpbase/runtime";

const dailyReport = cron(
  "reports.daily",
  "0 9 * * *",       // Every day at 09:00 UTC
  async (ctx, invocation) => {
    ctx.log.info("generating daily report", {
      fireAt: invocation.fireAt,
    });
    // ... generate report
  },
);

Cron Expression Format

Standard 5-field UTC cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
│ │ │ │ │
* * * * *

Examples:

ExpressionSchedule
*/15 * * * *Every 15 minutes
0 * * * *Every hour
0 9 * * *Daily at 09:00 UTC
0 0 * * 1Every Monday at midnight
0 0 1 * *First day of every month

Invocation Context

The cron handler receives a ChimpbaseCronInvocation object:

interface ChimpbaseCronInvocation {
  fireAt: string;      // ISO timestamp of the scheduled fire time
  fireAtMs: number;    // Unix milliseconds of the fire time
  name: string;        // Cron job name
  schedule: string;    // Cron expression
}

Backlog Behavior

After downtime, the runtime resumes from the current slot instead of replaying every missed interval. This means missed cron executions are skipped, which is the right default for most use cases (rollups, snapshots, cleanup jobs).

Using Decorators

import { Cron } from "@chimpbase/runtime";

class ReportsModule {
  @Cron("reports.daily", "0 9 * * *")
  async generateDailyReport(ctx, invocation) {
    // ...
  }
}
Workers
Durable background job execution with retries and dead-letter queues.
Workflows
Long-running stateful processes that survive restarts, time delays, and external signals.