Cron

import { Cron } from "cronbake";

const job = Cron.create({
  name: "report",
  cron: "@daily",
  callback: sendReport,
});

job.start();

Creating a job

Cron.create()

static create<T extends string = string>(
  options: CronOptions<T>,
  config?: { useCalculatedTimeouts?: boolean; pollingInterval?: number },
): ICron<T>

Creates a job, which is the same as new Cron(options, config). See CronOptions for the options. It throws if the name or expression is invalid, or the time zone is unknown. An invalid delay, maxHistory, priority or pollingInterval, or a callback that isn’t a function, logs a warning and the job is still created.

A job created this way has no baker behind it, so persist has no effect and a failure with no onError goes to its logger. The defaults for config are true and 1000.

Properties

Control

These don’t throw if the job’s state doesn’t allow the change. They do nothing instead. See Job lifecycle.

start()

start(): void

Schedules the job. Works from stopped or paused. With immediate: true it also arranges the first run. Throws if the schedule has no future date.

stop()

stop(): void

Cancels the schedule. A run in progress finishes.

pause()

pause(): void

Suspends a running job. A run in progress finishes.

resume()

resume(): void

Resumes a paused job from the next tick after the current time. Doesn’t trigger immediate.

destroy()

destroy(): void

Stops the job and fires onComplete. It doesn’t stop you from calling start() again afterwards, so don’t rely on this to retire a job you still hold a reference to.

Inspecting

getStatus()

getStatus(): Status

The job’s current state.

isRunning()

isRunning(): boolean

Whether the status is "running". This means the job is scheduled, not that its callback is executing right now.

nextExecution()

nextExecution(): Date

The next tick, or the current time if the job isn’t scheduled.

lastExecution()

lastExecution(): Date

The start of the most recent run. If the job has never run, this is the last time its schedule matched.

remaining()

remaining(): number

Milliseconds until the next tick, or 0 if the job isn’t scheduled.

time()

time(): number

The same as remaining().

getMetrics()

getMetrics(): JobMetrics

A copy of the job’s metrics.

getHistory()

getHistory(): ExecutionHistory[]

A copy of the job’s recent runs, newest first.

resetMetrics()

resetMetrics(): void

Clears the metrics and history.

Working with expressions

These don’t need a job. See Using expressions without a job for examples.

Cron.parse()

static parse(cron: string): CronTime

Returns the values each field matches, sorted and without duplicates. Accepts presets. Throws if the expression is invalid.

Cron.isValid()

static isValid(cron: string): boolean

Whether the expression parses. It doesn’t throw. A true result doesn’t guarantee the date exists, as 0 0 0 31 2 * shows.

Cron.getNext()

static getNext(cron: string, from?: Date, timezone?: string): Date

The first match after from, which defaults to now, on the clock of timezone, which defaults to the process’s time zone Next release. Throws if the expression is invalid, from is an invalid date, timezone is unknown, or nothing matches within 400 years.

Cron.getPrevious()

static getPrevious(cron: string, from?: Date, timezone?: string): Date

The last match before from, which defaults to now, on the clock of timezone, which defaults to the process’s time zone Next release. Throws in the same cases as getNext().