Cron@rhythmjs/cron
API reference
Every export of @rhythmjs/cron: RhythmCron, startCron, and the types around them.
On this page
class RhythmCron#
import { RhythmCron } from "@rhythmjs/cron";
class RhythmCron<I extends object = {}, D extends object = {}> extends Pipeline<CronContext<I & D>> {
constructor(options?: RhythmCronOptions);
use(middleware: Middleware | ExtensionMiddleware): this | RhythmCron<I, D & U>;
cron(name: string, schedule: CronSchedule, ...handlers: CronHandler<I & D>[]): this;
readonly jobs: readonly CronJobInfo[];
readonly running: boolean;
start(input?: I): this;
stop(): this;
run(name: string, input?: I): Promise<CronContext<I & D>>;
next(name: string, from?: Date | number): Date | null;
[Symbol.dispose](): void;
}RhythmCron is a Pipeline from @rhythmjs/rhythm. I is the context the jobs need from the app and D what its middleware derived; the input argument is required when I has required fields.
use(middleware)#- Adds middleware that wraps every run of every job, in registration order, with
(ctx, next). Extension middleware (derive, ...) widens the context for lateruse()calls and every job. cron(name, schedule, ...handlers)#- Registers a job and returns the instance. Throws a
TypeErrorfor a duplicate name, an invalid expression or time zone, or a schedule that never fires. The first handler may be extension middleware that widens the context for the rest. jobs#CronJobInfofor every registered job, in registration order.running#truewhile jobs are scheduled.start(input?)#- Schedules every job with
Bun.cron, usinginputas the context of each run. No-op if already running. stop()#- Cancels every scheduled job. The instance can be started again.
run(name, input?)#- Runs a job's pipeline now: the instance's middleware, then the handlers. Uses the started input when
inputis omitted. Resolves with the run's context; errors reject instead of going toonError. Throws aRangeErrorfor an unknown name. next(name, from?)#- The next fire time after
from(default now) in the job's time zone, ornullif it never fires. Throws aRangeErrorfor an unknown name. [Symbol.dispose]()#- Same as
stop(), sousingworks. callback()#- Calls
start(input)and resolves with the input, so the instance can be used wherever aMountableis expected. PreferstartCron.
Options#
interface RhythmCronOptions extends PipelineOptions {
tz?: string;
onError?(error: unknown, ctx: CronContext<any>): void;
unref?: boolean;
}tz#- IANA time zone for every schedule that does not set its own. Default: the system's.
onError(error, ctx)#- Called when a scheduled run fails. Default:
console.error('cron job "name" failed', error). The job stays scheduled. unref#- Let the process exit while jobs are scheduled. Default
false. name, type#- Pipeline options:
namelabels failure messages;typedefaults to"cron".
Types#
interface CronJobInfo {
readonly name: string;
readonly schedule: string;
readonly tz: string | undefined;
}
type CronContext<T extends object> = T & {
readonly job: CronJobInfo & { readonly firedAt: Date };
};
type CronSchedule = Bun.CronWithAutocomplete | { schedule: Bun.CronWithAutocomplete; tz?: string };
type CronHandler<T extends object> = (ctx: CronContext<T>, next: Next) => unknown | Promise<unknown>;CronJobInfo#- What
jobsreports for each job.tzis the job's resolved zone, undefined for the system's. CronContext<T>#- The app's context
Tplusjob: the job's info andfiredAt, the time of this run. CronSchedule#- A 5-field expression or nickname, or an object giving that job its own
tz. CronHandler<T>#- A job handler,
(ctx, next).CronHandlers<T>is a non-empty tuple of them.
startCron#
import { startCron } from "@rhythmjs/cron";
function startCron<I extends object, T extends object>(cron: RhythmCron<I, any>): RegisterCallback<T>;Returns a register callback for app.register(startCron(cron)). It starts the jobs with the app's startup context and registers a cleanup that stops them on app.stop(). The startup context T must satisfy I, otherwise the call is a compile error.