Cron@rhythmjs/cron
Scheduled jobs
A pipeline of named jobs on Bun's own cron: Rhythm middleware around every run, started and stopped with the app, and no scheduler of our own.
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.
bun add @rhythmjs/cron @rhythmjs/rhythmA 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:
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 appEach 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:
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.use(middleware) runs around each job's handlers on every fire, with the same (ctx, next) shape as router middleware. Use it for timing, logging, tracing or locking. Extension middleware such as derive(...) widens the context the jobs see.
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,startandstop, errors andonError, durability, replicas, and testing without waiting. API reference#- Every export:
RhythmCron, its options and methods, the context types, andstartCron.
The package source and examples live in the cron repository.