Documentation / zerotal / scheduler / Schedule

Abstract Class: Schedule

Defined in: packages/scheduler/src/Schedule.ts:30

Base class for convention-based scheduled tasks. Drop a subclass in app/schedules/ and it is auto-registered at boot (worker + console environments) by the scheduler's convention loader.

Define the cadence with either cron or the fluent frequency() method, put the work in handle(), and tune behaviour with the declarative settings below.

Examples

import { Schedule } from "@zerotal/scheduler";

export class SendDailyReports extends Schedule {
  cron = "0 8 * * *";          // every day at 08:00
  timezone = "Africa/Johannesburg";
  withoutOverlapping = true;

  async handle(): Promise<void> {
    await Queue.dispatch(new SendReportsJob());
  }
}

// fluent cadence instead of a raw cron string
export class PruneTempFiles extends Schedule {
  frequency(every) { return every.dailyAt("02:30"); }
  async handle() { ... }
}

Constructors

Constructor

new Schedule(): Schedule

Returns

Schedule

Properties

cron?

optional cron?: string

Defined in: packages/scheduler/src/Schedule.ts:38

Cron expression (5- or 6-field). Set this OR override frequency. Examples: "* * * * *" (every minute), "0 8 * * 1" (Mondays at 08:00).

name?

optional name?: string

Defined in: packages/scheduler/src/Schedule.ts:49

Task name shown in schedule:list and logs. Defaults to the class name.

timezone?

optional timezone?: string

Defined in: packages/scheduler/src/Schedule.ts:52

IANA timezone the cron expression is evaluated in (default: system timezone).

withoutOverlapping?

optional withoutOverlapping?: boolean | OverlapLockOptions

Defined in: packages/scheduler/src/Schedule.ts:59

Prevent overlapping runs. true skips a tick while a previous run is still active and, when a lock driver is configured, also takes a cross-process lock. Pass { crossProcess: false } to guard within this process only.

environments?

optional environments?: string[]

Defined in: packages/scheduler/src/Schedule.ts:62

Only run when APP_ENV is one of these values.

inBackground?

optional inBackground?: boolean

Defined in: packages/scheduler/src/Schedule.ts:65

Run the body without blocking the scheduler tick (fire-and-forget).

between?

optional between?: [string, string]

Defined in: packages/scheduler/src/Schedule.ts:68

Only run between ["HH:MM", "HH:MM"].

unlessBetween?

optional unlessBetween?: [string, string]

Defined in: packages/scheduler/src/Schedule.ts:71

Never run between ["HH:MM", "HH:MM"].

pingBefore?

optional pingBefore?: string

Defined in: packages/scheduler/src/Schedule.ts:74

Health-check pings (e.g. healthchecks.io). URLs are fetched at each lifecycle point.

pingAfter?

optional pingAfter?: string

Defined in: packages/scheduler/src/Schedule.ts:75

pingOnSuccess?

optional pingOnSuccess?: string

Defined in: packages/scheduler/src/Schedule.ts:76

pingOnFailure?

optional pingOnFailure?: string

Defined in: packages/scheduler/src/Schedule.ts:77

appendOutputTo?

optional appendOutputTo?: string

Defined in: packages/scheduler/src/Schedule.ts:80

Append captured console output to a file.

emailOutputTo?

optional emailOutputTo?: string

Defined in: packages/scheduler/src/Schedule.ts:83

Email captured console output (requires an output mailer to be configured).

Methods

handle()

abstract handle(): void | Promise<void>

Defined in: packages/scheduler/src/Schedule.ts:32

The work performed on each run. Required.

Returns

void | Promise<void>

frequency()?

optional frequency(every): ScheduledTask

Defined in: packages/scheduler/src/Schedule.ts:46

Build the cadence fluently using the scheduler's frequency helpers, instead of a raw cron string. Return the configured task.

Parameters

every

SchedulerBuilder

Returns

ScheduledTask

Example

frequency(every) { return every.everyFiveMinutes(); }

when()?

optional when(): boolean | Promise<boolean>

Defined in: packages/scheduler/src/Schedule.ts:86

Dynamic guard — the task runs only when this resolves truthy.

Returns

boolean | Promise<boolean>

skip()?

optional skip(): boolean | Promise<boolean>

Defined in: packages/scheduler/src/Schedule.ts:89

Dynamic guard — the task is skipped when this resolves truthy.

Returns

boolean | Promise<boolean>