rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

class RhythmCron#

TypeScript
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.

new RhythmCron(options?)#
Creates an instance. See options.
use(middleware)#
Adds middleware that wraps every run of every job, in registration order, with (ctx, next). Extension middleware (derive, ...) widens the context for later use() calls and every job.
cron(name, schedule, ...handlers)#
Registers a job and returns the instance. Throws a TypeError for 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#
CronJobInfo for every registered job, in registration order.
running#
true while jobs are scheduled.
start(input?)#
Schedules every job with Bun.cron, using input as 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 input is omitted. Resolves with the run's context; errors reject instead of going to onError. Throws a RangeError for an unknown name.
[Symbol.dispose]()#
Same as stop(), so using works.
callback()#
Calls start(input) and resolves with the input, so the instance can be used wherever a Mountable is expected. Prefer startCron.

Options#

TypeScript
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: name labels failure messages; type defaults to "cron".

Types#

TypeScript
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 jobs reports for each job. tz is the job's resolved zone, undefined for the system's.
CronContext<T>#
The app's context T plus job: the job's info and firedAt, 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#

TypeScript
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.