rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

Install the package#

@rhythmjs/cron adds scheduled work to a Rhythm app. It is built on Bun.cron and nothing else: expressions are parsed and fired by Bun, which also guarantees that a job never overlaps itself. What the package adds is the Rhythm shape around that: named jobs, the same use() middleware and (ctx, next) handlers as RhythmRouter and RhythmWs, and a start and stop that follow the app's lifecycle.

@rhythmjs/rhythm is a peer dependency (0.0.24 or newer), and Bun 1.4 or newer is required.

Shell
bun add @rhythmjs/cron @rhythmjs/rhythm

A first app#

new RhythmCron<{ db: Db }>() declares the context the jobs need from the app. .cron(name, schedule, handler) adds a job, and .use(middleware) wraps every run of every job:

TypeScript
import { Rhythm, decorate } from "@rhythmjs/rhythm";
import { RhythmCron, startCron } from "@rhythmjs/cron";

const cron = new RhythmCron<{ db: Db }>({ tz: "UTC" })
  .use(async (ctx, next) => {
    const started = performance.now();
    await next();
    console.log(`${ctx.job.name} took ${Math.round(performance.now() - started)}ms`);
  })
  .cron("cleanup", "0 3 * * *", async (ctx) => {
    await ctx.db.deleteExpiredSessions();
  })
  .cron("report", { schedule: "30 9 * * MON-FRI", tz: "America/New_York" }, async (ctx) => {
    await sendReport(ctx.db);
  });

const app = new Rhythm().register(decorate(() => ({ db: openDb() }))).register(startCron(cron));

await app.callback()(); // jobs are scheduled
// await app.stop();    // and cancelled with the app

Each handler receives ctx: whatever the app supplied (here db) plus ctx.job, which says which job fired and when. The schedule syntax, time zones and handlers are covered in Schedules & handlers.

How it sits with Rhythm#

RhythmCron is a Pipeline, like the router and the WebSocket plugin, but it is not mounted per request: jobs have no request. Instead it is started once, at startup, through startCron:

TypeScript
app.register(startCron(cron));

startCron(cron) is a register callback. It starts every job with the app's startup context as their input and registers a cleanup that stops them, so app.stop() cancels the schedules. The jobs read that context when they fire, so dependencies added by later register() calls are visible to them. The app must provide the context the jobs declared ({ db: Db } above); a missing field is a compile error at startCron, not a surprise at 3 a.m.

Cron can live next to HTTP in one app. Register startCron(cron) for the schedules and mount the router for requests; a route can also trigger a job by hand with cron.run.

Where to go next#

Schedules & handlers#
Declaring jobs: expressions and nicknames, time zones, handlers and derive-style middleware, validation at registration, and names.
Lifecycle & errors#
Running them: startCron, start and stop, errors and onError, durability, replicas, and testing without waiting.
API reference#
Every export: RhythmCron, its options and methods, the context types, and startCron.

The package source and examples live in the cron repository.