@zerotal/scheduler 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @zerotal/scheduler
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Notes
+
+- Conforms to the Zerotal package conventions (provider in `src/provider/`, PascalCase config factory, `ZerotalError`-based errors, test coverage).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @zerotal/scheduler
+
+> Cron-style task scheduling with class-based schedules and a fluent facade.
+
+Run tasks on a cron-like cadence. Drop a `Schedule` subclass in `app/schedules/` for auto-registered, testable tasks, or use the `Scheduler` facade for quick inline definitions. Schedules run in the worker process (`bun zt worker`).
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/scheduler
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { SchedulerProvider } from "@zerotal/scheduler";
+```
+
+## Usage
+
+The recommended approach is class-based — extend `Schedule`, declare the cadence, and put the work in `handle()`. Every subclass under `app/schedules/` is discovered automatically:
+
+```ts
+import { Schedule } from "@zerotal/scheduler";
+import { Queue } from "@zerotal/queue";
+
+export class SendDailyReports extends Schedule {
+  cron = "0 8 * * *"; // every day at 08:00
+  withoutOverlapping = true;
+
+  async handle(): Promise<void> {
+    await Queue.dispatch(new SendReportsJob());
+  }
+}
+```
+
+Prefer the fluent frequency builder when it reads better — override `frequency()`:
+
+```ts
+import { Schedule, type SchedulerBuilder } from "@zerotal/scheduler";
+
+export class WarmCache extends Schedule {
+  override frequency(every: SchedulerBuilder) {
+    return every.everyFiveMinutes();
+  }
+  async handle(): Promise<void> {
+    await Cache.forget("posts:page:1");
+  }
+}
+```
+
+For one-liners, use the `Scheduler` facade — `job()` returns the `ScheduledTask` for fluent tuning:
+
+```ts
+import { Scheduler } from "@zerotal/scheduler";
+
+Scheduler.job("nightly-backup", () => runBackup())
+  .dailyAt("02:30")
+  .timezone("Africa/Johannesburg")
+  .withoutOverlapping({ expiresAfterMinutes: 30 })
+  .environments(["production"]);
+```
+
+In tests, `runNow()` executes the handler immediately, bypassing the cron/time guards:
+
+```ts
+const task = Scheduler.job("report", () => generateReport()).dailyAt("08:00");
+await task.runNow();
+expect(task.lastOk).toBe(true);
+```
+
+## Exports
+
+| Export                                                                        | Description                                                            |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `Scheduler`                                                                   | Fluent inline scheduling facade.                                       |
+| `Schedule`                                                                    | Base class for convention-based schedules in `app/schedules/`.         |
+| `SchedulerManager`, `SchedulerBuilder`                                        | The manager and the cadence builder.                                   |
+| `ScheduledTask`                                                               | A single registered task — introspection, `runNow()`, lifecycle hooks. |
+| `CronExpression`                                                              | Cron expression parser / next-run calculator.                          |
+| `schedulesConcern`, `registerSchedule`                                        | Convention loader hooks.                                               |
+| `SchedulerProvider`                                                           | Service provider — register in `bootstrap/providers.ts`.               |
+| `SchedulerConfig`, `SchedulerConfigShape`                                     | Config factory and its type.                                           |
+| `TaskCallback`, `TaskGuard`, `TaskHook`, `OutputMailer`, `OverlapLockOptions` | Supporting types.                                                      |
+
+## Documentation
+
+- [Scheduler](../../docs/scheduler.md)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zerotal/scheduler",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "stable",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Cron-style task scheduling for Zerotal with overlap locking and output capture.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "scheduler",
+    "cron"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/scheduler"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/scheduler#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/CronExpression.ts

@@ -0,0 +1,304 @@
+/**
+ * Cron expression utility — builder, validator, human-readable describer and
+ * next-run calculator. Supports standard 5-field cron (m h dom mon dow) and
+ * tolerates an optional leading seconds field (6-field) for validation.
+ *
+ * Field syntax: star, n, a-b, a-b with step, star with step, and
+ * comma-separated lists of any of those (e.g. `1,15,30` or `1-5`).
+ */
+export class CronExpression {
+  private fields: [string, string, string, string, string];
+
+  private static readonly RANGES: Record<number, [number, number]> = {
+    0: [0, 59],
+    1: [0, 23],
+    2: [1, 31],
+    3: [1, 12],
+    4: [0, 7],
+  };
+
+  private static readonly DOW = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+  ];
+  private static readonly MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+  ];
+
+  constructor(expression?: string) {
+    if (expression) {
+      const parts = expression.trim().split(/\s+/);
+      const five = parts.length === 6 ? parts.slice(1) : parts;
+      this.fields = [
+        five[0] ?? "*",
+        five[1] ?? "*",
+        five[2] ?? "*",
+        five[3] ?? "*",
+        five[4] ?? "*",
+      ];
+    } else {
+      this.fields = ["*", "*", "*", "*", "*"];
+    }
+  }
+
+  minute(v: number | string): this {
+    this.fields[0] = String(v);
+    return this;
+  }
+  hour(v: number | string): this {
+    this.fields[1] = String(v);
+    return this;
+  }
+  dayOfMonth(v: number | string): this {
+    this.fields[2] = String(v);
+    return this;
+  }
+  month(v: number | string): this {
+    this.fields[3] = String(v);
+    return this;
+  }
+  weekday(v: number | string): this {
+    this.fields[4] = String(v);
+    return this;
+  }
+
+  toString(): string {
+    return this.fields.join(" ");
+  }
+
+  /**
+   * Whether `value` satisfies one cron field.
+   *
+   * @param pattern - The field text (`*`, `5`, `1-5`, `* /3`, `1,15`, or a comma list).
+   * @param value - The value to test.
+   * @param min - The field's smallest legal value: 0 for minute, hour and day-of-week,
+   *   **1** for day-of-month and month. A `* /N` step counts from this, not from zero —
+   *   `0 0 * /7 * *` fires on the 1st, 8th, 15th…, and `0 0 * * /3 *` in January, April,
+   *   July and October. Anchoring at 0 regardless put the day-of-month step a day early
+   *   and the month step two months out.
+   */
+  private static _matchField(pattern: string, value: number, min = 0): boolean {
+    if (pattern === "*") return true;
+    for (const token of pattern.split(",")) {
+      let range = token;
+      let step = 1;
+      if (token.includes("/")) {
+        const [r, s] = token.split("/");
+        range = r || "*";
+        step = parseInt(s || "1", 10) || 1;
+      }
+      let start: number;
+      let end: number;
+      if (range === "*") {
+        start = -Infinity;
+        end = Infinity;
+      } else if (range.includes("-")) {
+        const [a, b] = range.split("-");
+        start = parseInt(a || "0", 10);
+        end = parseInt(b || "0", 10);
+      } else {
+        start = end = parseInt(range, 10);
+      }
+      if (Number.isNaN(start) || Number.isNaN(end)) continue;
+      if (value < start || value > end) continue;
+      const base = range === "*" ? min : start;
+      if ((value - base) % step === 0) return true;
+    }
+    return false;
+  }
+
+  matches(date: Date = new Date()): boolean {
+    const [mi, h, dom, mo, dow] = this.fields;
+    const day = date.getDay();
+    const dowMatch =
+      CronExpression._matchField(dow, day) || (day === 0 && CronExpression._matchField(dow, 7));
+    const domMatch = CronExpression._matchField(dom, date.getDate(), 1);
+
+    // vixie-cron day semantics: when BOTH day-of-month and day-of-week are
+    // restricted (neither is `*`), the day matches if EITHER matches (OR). When
+    // only one is restricted, the `*` side is trivially true, so the AND below
+    // reduces to the restricted one. This matches croner (the real firing path);
+    // the previous unconditional AND made matches()/nextRunAfter() disagree with
+    // actual firing for expressions like `0 0 1 * 1`.
+    const domRestricted = dom !== "*";
+    const dowRestricted = dow !== "*";
+    const dayMatch = domRestricted && dowRestricted ? domMatch || dowMatch : domMatch && dowMatch;
+
+    return (
+      CronExpression._matchField(mi, date.getMinutes()) &&
+      CronExpression._matchField(h, date.getHours()) &&
+      dayMatch &&
+      CronExpression._matchField(mo, date.getMonth() + 1, 1)
+    );
+  }
+
+  nextRun(from: Date = new Date()): Date | null {
+    return CronExpression.nextRunAfter(this.toString(), from);
+  }
+
+  static isValid(expression: string): boolean {
+    if (typeof expression !== "string") return false;
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5 && parts.length !== 6) return false;
+    const five = parts.length === 6 ? parts.slice(1) : parts;
+    for (let i = 0; i < 5; i++) {
+      if (!CronExpression._isValidField(five[i]!, CronExpression.RANGES[i]!)) return false;
+    }
+    return true;
+  }
+
+  private static _isValidField(field: string, [lo, hi]: [number, number]): boolean {
+    if (field === "*") return true;
+    for (const token of field.split(",")) {
+      if (token === "") return false;
+      let range = token;
+      if (token.includes("/")) {
+        const [r, s] = token.split("/");
+        const stepNum = Number(s);
+        if (!s || !Number.isInteger(stepNum) || stepNum < 1) return false;
+        range = r || "*";
+        if (range === "*") continue;
+      }
+      if (range.includes("-")) {
+        const [a, b] = range.split("-");
+        const an = Number(a);
+        const bn = Number(b);
+        if (!Number.isInteger(an) || !Number.isInteger(bn)) return false;
+        if (an < lo || bn > hi || an > bn) return false;
+      } else {
+        const n = Number(range);
+        if (!Number.isInteger(n) || n < lo || n > hi) return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * The first time at or after `from` that `expression` fires, or `null` when it never does
+   * within the search horizon.
+   *
+   * The scan steps by minute, but skips a whole day at a time once the day itself cannot
+   * match — a day-scoped expression like `0 0 29 2 *` would otherwise mean 533,000 minute
+   * probes to reach the next leap year, which is why a 370-day horizon reported "never
+   * runs" for a perfectly valid expression while burning ~320 ms of blocking CPU per call.
+   *
+   * @param expression - A 5- or 6-field cron expression.
+   * @param from - Search start; the result is strictly after this minute.
+   * @returns The next firing time, or `null` for an invalid expression or one with no
+   *   occurrence in the next {@link SEARCH_HORIZON_DAYS} days.
+   */
+  static nextRunAfter(expression: string, from: Date = new Date()): Date | null {
+    if (!CronExpression.isValid(expression)) return null;
+    const cron = new CronExpression(expression);
+    const cursor = new Date(from);
+    cursor.setSeconds(0, 0);
+    cursor.setMinutes(cursor.getMinutes() + 1);
+
+    const deadline = new Date(from);
+    deadline.setDate(deadline.getDate() + CronExpression.SEARCH_HORIZON_DAYS);
+
+    while (cursor <= deadline) {
+      if (cron._dayMatches(cursor)) {
+        if (cron.matches(cursor)) return new Date(cursor);
+        cursor.setMinutes(cursor.getMinutes() + 1);
+      } else {
+        // Nothing today can match — jump to 00:00 tomorrow rather than probing 1,440 minutes.
+        cursor.setDate(cursor.getDate() + 1);
+        cursor.setHours(0, 0, 0, 0);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * How far ahead {@link nextRunAfter} looks. Four years and change, so a Feb-29 expression
+   * resolves to the next leap day instead of reporting that it never runs.
+   */
+  static readonly SEARCH_HORIZON_DAYS = 366 * 4 + 1;
+
+  /** Whether the date part of `date` satisfies the day-of-month / month / day-of-week fields. */
+  private _dayMatches(date: Date): boolean {
+    const [, , dom, mo, dow] = this.fields;
+    if (!CronExpression._matchField(mo, date.getMonth() + 1, 1)) return false;
+
+    const day = date.getDay();
+    const dowMatch =
+      CronExpression._matchField(dow, day) || (day === 0 && CronExpression._matchField(dow, 7));
+    const domMatch = CronExpression._matchField(dom, date.getDate(), 1);
+    return dom !== "*" && dow !== "*" ? domMatch || dowMatch : domMatch && dowMatch;
+  }
+
+  static describe(expression: string): string {
+    if (!CronExpression.isValid(expression)) return "Invalid cron expression";
+    const parts = expression.trim().split(/\s+/);
+    const [mi, h, dom, mo, dow] = parts.length === 6 ? parts.slice(1) : parts;
+
+    if (mi === "*" && h === "*" && dom === "*" && mo === "*" && dow === "*") return "Every minute";
+    const stepMin = mi!.match(/^\*\/(\d+)$/);
+    if (stepMin && h === "*" && dom === "*" && mo === "*" && dow === "*")
+      return `Every ${stepMin[1]} minutes`;
+    if (mi === "0" && h === "*" && dom === "*" && mo === "*" && dow === "*") return "Every hour";
+
+    const segments: string[] = [];
+    if (/^\d+$/.test(mi!) && /^\d+$/.test(h!)) {
+      segments.push(`At ${CronExpression._formatTime(Number(h), Number(mi))}`);
+    } else {
+      if (mi !== "*") segments.push(`At minute ${mi}`);
+      if (h !== "*") segments.push(`past hour ${h}`);
+    }
+    if (dom !== "*") segments.push(`on day-of-month ${dom}`);
+    if (mo !== "*") segments.push(`in ${CronExpression._describeMonth(mo!)}`);
+    if (dow !== "*") segments.push(CronExpression._describeDow(dow!));
+    return segments.join(", ");
+  }
+
+  private static _formatTime(hour: number, minute: number): string {
+    const period = hour < 12 ? "AM" : "PM";
+    let hr = hour % 12;
+    if (hr === 0) hr = 12;
+    return `${String(hr).padStart(2, "0")}:${String(minute).padStart(2, "0")} ${period}`;
+  }
+
+  private static _dowName(n: number): string {
+    return CronExpression.DOW[n === 7 ? 0 : n] ?? String(n);
+  }
+
+  private static _describeDow(dow: string): string {
+    if (/^\d+$/.test(dow)) return CronExpression._dowName(Number(dow));
+    const range = dow.match(/^(\d+)-(\d+)$/);
+    if (range)
+      return `${CronExpression._dowName(Number(range[1]))} through ${CronExpression._dowName(Number(range[2]))}`;
+    if (dow.includes(",")) {
+      const names = dow.split(",").map((d) => CronExpression._dowName(Number(d)));
+      if (names.length === 2) return `${names[0]} and ${names[1]}`;
+      return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+    }
+    return `on ${dow}`;
+  }
+
+  private static _describeMonth(mo: string): string {
+    if (/^\d+$/.test(mo)) return CronExpression.MONTHS[Number(mo) - 1] ?? mo;
+    if (mo.includes(","))
+      return mo
+        .split(",")
+        .map((m) => CronExpression.MONTHS[Number(m) - 1] ?? m)
+        .join(", ");
+    return mo;
+  }
+}

package/src/Schedule.ts

@@ -0,0 +1,90 @@
+import type { OverlapLockOptions, ScheduledTask } from "./ScheduledTask.ts";
+import type { SchedulerBuilder } from "./SchedulerManager.ts";
+
+/**
+ * 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.
+ *
+ * @example
+ * 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());
+ *   }
+ * }
+ *
+ * @example  // fluent cadence instead of a raw cron string
+ * export class PruneTempFiles extends Schedule {
+ *   frequency(every) { return every.dailyAt("02:30"); }
+ *   async handle() { ... }
+ * }
+ */
+export abstract class Schedule {
+  /** The work performed on each run. Required. */
+  abstract handle(): void | Promise<void>;
+
+  /**
+   * Cron expression (5- or 6-field). Set this OR override {@link frequency}.
+   * Examples: `"* * * * *"` (every minute), `"0 8 * * 1"` (Mondays at 08:00).
+   */
+  cron?: string;
+
+  /**
+   * Build the cadence fluently using the scheduler's frequency helpers, instead of a raw
+   * cron string. Return the configured task.
+   *
+   * @example frequency(every) { return every.everyFiveMinutes(); }
+   */
+  frequency?(every: SchedulerBuilder): ScheduledTask;
+
+  /** Task name shown in `schedule:list` and logs. Defaults to the class name. */
+  name?: string;
+
+  /** IANA timezone the cron expression is evaluated in (default: system timezone). */
+  timezone?: string;
+
+  /**
+   * 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.
+   */
+  withoutOverlapping?: boolean | OverlapLockOptions;
+
+  /** Only run when `APP_ENV` is one of these values. */
+  environments?: string[];
+
+  /** Run the body without blocking the scheduler tick (fire-and-forget). */
+  inBackground?: boolean;
+
+  /** Only run between `["HH:MM", "HH:MM"]`. */
+  between?: [string, string];
+
+  /** Never run between `["HH:MM", "HH:MM"]`. */
+  unlessBetween?: [string, string];
+
+  /** Health-check pings (e.g. healthchecks.io). URLs are fetched at each lifecycle point. */
+  pingBefore?: string;
+  pingAfter?: string;
+  pingOnSuccess?: string;
+  pingOnFailure?: string;
+
+  /** Append captured console output to a file. */
+  appendOutputTo?: string;
+
+  /** Email captured console output (requires an output mailer to be configured). */
+  emailOutputTo?: string;
+
+  /** Dynamic guard — the task runs only when this resolves truthy. */
+  when?(): boolean | Promise<boolean>;
+
+  /** Dynamic guard — the task is skipped when this resolves truthy. */
+  skip?(): boolean | Promise<boolean>;
+}