Cron

Task scheduling using cron expressions, backed by node-cron.

Usage

import { Cron } from "@io-oidis-localhost/Io/Oidis/Localhost/Utils/Cron.js";

const cron : Cron = Cron.getSingleton();

API Reference

AddTask

Registers and schedules a recurring task. Accepts either a name string or a full ICronTaskDescriptor options object. If the task name matches a key in cron.scheduler in the project configuration, that cron expression is used automatically.

public AddTask($task : () => Promise<void> | void, $name : string) : void
public AddTask($task : () => Promise<void> | void, $options? : ICronTaskDescriptor) : void

• $task — the function to execute on each tick.
• $name / $options — name string or descriptor with name, cronTime, timezone, allowOverlap, and skipTolerance.
• Default cronTime if not configured: "* * * * *" (every minute).
• Tasks are started immediately unless master stop is active.

cron.AddTask(async () => {
    // runs every hour
}, { name: "MyTask", cronTime: "0 * * * *" });

Overlap guard and skip tolerance

By default a task never runs concurrently with itself: a tick that fires while the previous execution is still in flight is skipped and counted. Set allowOverlap: true to disable the guard.

Every skip is logged. skipTolerance (default 0) is the number of consecutive skipped ticks logged as Info; the next skip above the tolerance is logged as Warning (reported to Sentry). The streak resets whenever an execution starts, so occasional overlaps of a long-running task stay quiet while a stuck task is still reported.

cron.AddTask(async () => {
    // runs every minute, a single pass may take up to 4 minutes
}, { name: "Collector", cronTime: "* * * * *", skipTolerance: 4 });

ListTasks reports the counters per task: skipped (total), consecutiveSkipped (current streak), lastSkippedAt, skipTolerance, plus runs, lastRunAt, lastDurationMs, and inFlight.

MasterStop

Activates or deactivates all registered tasks at once. Triggers the OnStateChange handler when the state changes.

public async MasterStop($active : boolean) : Promise<boolean>

• $active = true — stops all active tasks (emergency stop).
• $active = false — restarts all previously active tasks.

ListTasks

Returns the list of all registered tasks with their cron expression, name, timezone, and run/skip statistics.

public ListTasks() : ICronTaskDescriptor[]

StartTask

Starts a previously stopped task by its internal ID or name. Pass $instant = true to also execute the task immediately.

public StartTask($idOrName : string, $instant : boolean = false) : boolean

StopTask

Stops a running task by its internal ID or name without removing it from the register.

public StopTask($idOrName : string) : boolean

RemoveTask

Stops and permanently removes a task from the register by its internal ID or name.

public RemoveTask($idOrName : string) : boolean

OnStateChange

Registers a handler called whenever the master stop state changes.

public OnStateChange($handler : ($state : boolean) => Promise<void>) : void

Configuration

Cron is configured via cron in the project configuration (ICronConfig):

"cron": {
    "enabled": true,
    "timezone": "Europe/Prague",
    "scheduler": {
        "MyTask": "0 * * * *",
        "DailyCleanup": "0 0 * * *"
    }
}

• enabled — if false, master stop is active by default and tasks do not start automatically.
• timezone — IANA timezone applied to all tasks that do not specify their own.
• scheduler — map of task name to cron expression; used only when AddTask does not provide its own cronTime.

Remote Control via CronConnector

CronConnector exposes the Cron API as @Extern() methods for remote invocation:

Method	Description
MasterStop($active)	Async master stop toggle
ListTasks()	List all tasks
StartTask($idOrName, $instant)	Start a task
StopTask($idOrName)	Stop a task

---

See also: Utilities Overview | Localhost Overview | Events