@zerotal/scheduler 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,53 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-08-30
+
+### Fixed
+
+- **A task with a `timezone` no longer takes the whole scheduler down.** The code
+  passed croner's options form — `Bun.cron(schedule, { run, timezone })` — on the
+  belief that Bun accepted it at runtime and only the types disagreed. It does not:
+  it throws, and it throws during _registration_, so the worker died on boot and
+  restart-looped. One task with a timezone stopped **every** task in the app,
+  including the ones that release inventory holds and chase deposits. Setting a
+  timezone is the obvious thing to do for a business that operates in one country and
+  is not on UTC, which is most of them.
+
+  Zerotal evaluates the zone itself now. A zoned task registers a minute tick and runs
+  on the ticks where its expression matches the wall clock in its own zone — minute
+  granularity being the finest `Bun.cron` accepts anyway, so nothing is given up, and
+  comparing against the zone's local time rather than an offset computed once is what
+  keeps it right across a daylight-saving change. `nextRunAt()` reads the same zone,
+  so `schedule:list` and the monitor agree with when the task will actually run.
+
+  The test that covered this asserted the broken behaviour against a mock that
+  accepted anything. It now runs against the real `Bun.cron`.
+
+- **A task that cannot register takes only itself out.** Registration throws for
+  exactly the reasons that are one task's problem — an expression the runtime
+  rejects, a zone it does not know — and letting one propagate meant a typo in one
+  schedule stopped every schedule in the app, from a crash loop that named none of
+  them. The others start now, and the log names the one that did not.
+
+### Changed
+
+- **`scheduler.timezone` does something.** It was documented as informational and read
+  by nothing. It is now the zone every schedule is evaluated in unless the task sets
+  its own — one line instead of a `.timezone()` on every task. Its default changed
+  from the literal `"UTC"` to **the system zone**, so an app that never set the key
+  keeps doing exactly what it did; only an app that explicitly asked for a zone gets
+  a change, which is the change it asked for.
+
+### Added
+
+- `UnknownTimeZoneError` (and the `SchedulerError` base it extends) — raised at
+  registration and naming the task, rather than a `RangeError` thrown once a minute
+  from inside a cron tick with nothing to say which schedule it came from.
+- `wallClockIn`, `isValidTimeZone`, `CronExpression.matchesIn` and
+  `CronExpression.nextRunAfterIn` — the zone arithmetic the scheduler now uses,
+  exported because an app doing its own time-window logic needs the same answers.
+
 ## [1.9.0] — 2026-08-29
 
 ### Documented

package/api-surface.md

@@ -10,10 +10,12 @@ class CronExpression = {
   static describe: (expression: string) => string
   static isValid: (expression: string) => boolean
   static nextRunAfter: (expression: string, from?: Date) => Date | null
+  static nextRunAfterIn: (expression: string, from: Date, timeZone: string) => Date | null
   static readonly SEARCH_HORIZON_DAYS: number
   dayOfMonth: (v: number | string) => CronExpression
   hour: (v: number | string) => CronExpression
   matches: (date?: Date) => boolean
+  matchesIn: (date: Date, timeZone: string) => boolean
   minute: (v: number | string) => CronExpression
   month: (v: number | string) => CronExpression
   nextRun: (from?: Date) => Date | null
@@ -121,6 +123,13 @@ class SchedulerBuilder = {
   yearlyOn: (month?: number, dayOfMonth?: number, time?: string) => ScheduledTask
 }
 
+class SchedulerError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): SchedulerError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
 class SchedulerManager = {
   new (): SchedulerManager
   add: (name: string, cronExpression: string, callback: TaskCallback) => ScheduledTask
@@ -172,14 +181,25 @@ class TaskSkipped = {
   readonly reason: 'lock' | 'window' | 'env' | 'when' | 'skip' | 'overlap'
 }
 
+class UnknownTimeZoneError = {
+  new (task: string, timezone: string): UnknownTimeZoneError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
 const Scheduler = SchedulerManager
 
+function isValidTimeZone = (timeZone: string) => boolean
+
 function SchedulerConfig = (options?: Partial<SchedulerConfigShape>) => SchedulerConfigShape
 
+function wallClockIn = (date: Date, timeZone: string) => Date
+
 interface OverlapLockOptions = {
-  crossProcess?: boolean
-  expiresAfterMinutes?: number
-  refresh?: boolean
+  crossProcess?: boolean | undefined
+  expiresAfterMinutes?: number | undefined
+  refresh?: boolean | undefined
 }
 
 interface RunLogConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/scheduler",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0"
+    "@zerotal/core": "1.11.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/CronExpression.ts

@@ -6,6 +6,73 @@
  * 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`).
  */
+/**
+ * The same instant, shifted so a `Date`'s **local** getters read `timeZone`'s wall
+ * clock.
+ *
+ * Cron is a wall-clock spec: `0 3 * * *` means three in the morning where the
+ * business is, not three UTC. Every matcher below reads `getHours()`,
+ * `getMinutes()` and friends, which answer in the *process's* zone — so evaluating
+ * a schedule in another zone is a question of which Date you hand them.
+ *
+ * The returned Date is a lie about the instant and true about the clock face: its
+ * epoch value is wrong by the zone offset, and it is only ever passed to the field
+ * matchers, never returned to a caller or compared against a real time.
+ *
+ * @param date - The instant to read.
+ * @param timeZone - An IANA zone name, e.g. `"Africa/Johannesburg"`.
+ * @returns A Date whose local fields are that zone's wall clock at `date`.
+ * @throws {@link RangeError} When `timeZone` is not a zone this runtime knows.
+ */
+export function wallClockIn(date: Date, timeZone: string): Date {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  }).formatToParts(date);
+
+  const field = (type: string): number => {
+    const found = parts.find((p) => p.type === type);
+    return found ? Number(found.value) : 0;
+  };
+
+  return new Date(
+    field("year"),
+    field("month") - 1,
+    field("day"),
+    field("hour"),
+    field("minute"),
+    field("second"),
+    0,
+  );
+}
+
+/**
+ * Whether this runtime knows `timeZone`.
+ *
+ * Worth checking separately from using it: a typo in a schedule's zone would
+ * otherwise surface as a `RangeError` thrown once a minute from inside a cron
+ * tick, with nothing naming the task it came from.
+ *
+ * @param timeZone - An IANA zone name.
+ */
+export function isValidTimeZone(timeZone: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Minutes in a day, for the day-skip in the next-run scans. */
+const MINUTES_PER_DAY = 24 * 60;
+
 export class CronExpression {
   private fields: [string, string, string, string, string];
 
@@ -148,6 +215,17 @@ export class CronExpression {
     );
   }
 
+  /**
+   * Whether the expression matches `date` **as read in `timeZone`**.
+   *
+   * @param date - The instant to test.
+   * @param timeZone - An IANA zone name the expression is written against.
+   * @throws {@link RangeError} When `timeZone` is not a zone this runtime knows.
+   */
+  matchesIn(date: Date, timeZone: string): boolean {
+    return this.matches(wallClockIn(date, timeZone));
+  }
+
   nextRun(from: Date = new Date()): Date | null {
     return CronExpression.nextRunAfter(this.toString(), from);
   }
@@ -226,6 +304,50 @@ export class CronExpression {
     return null;
   }
 
+  /**
+   * The first instant at or after `from` that `expression` fires, reading the clock
+   * in `timeZone`.
+   *
+   * The returned Date is a real instant, not a shifted one — the shifting happens
+   * inside the scan, where the expression is compared against the zone's wall clock
+   * a minute at a time. That is what keeps it right across a DST change: nothing
+   * here computes an offset once and adds it.
+   *
+   * @param expression - A 5- or 6-field cron expression.
+   * @param from - Search start; the result is strictly after this minute.
+   * @param timeZone - An IANA zone name the expression is written against.
+   * @returns The next firing instant, or `null` for an invalid expression, an unknown
+   *   zone, or no occurrence within {@link SEARCH_HORIZON_DAYS}.
+   */
+  static nextRunAfterIn(expression: string, from: Date, timeZone: string): Date | null {
+    if (!CronExpression.isValid(expression)) return null;
+    if (!isValidTimeZone(timeZone)) 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) {
+      const local = wallClockIn(cursor, timeZone);
+      if (cron._dayMatches(local)) {
+        if (cron.matches(local)) return new Date(cursor);
+        cursor.setMinutes(cursor.getMinutes() + 1);
+      } else {
+        // Nothing on this local day can match — jump to the zone's next midnight
+        // rather than probing 1,440 minutes. Zone offsets are whole minutes, so
+        // this lands on it exactly; a DST change costs an hour of extra probes and
+        // nothing else.
+        const elapsed = local.getHours() * 60 + local.getMinutes();
+        cursor.setMinutes(cursor.getMinutes() + (MINUTES_PER_DAY - elapsed));
+      }
+    }
+    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.

package/src/ScheduledTask.ts

@@ -1,11 +1,22 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { FrameworkEvents } from "@zerotal/core";
+import { config, FrameworkEvents } from "@zerotal/core";
 import { deployEnv } from "@zerotal/core";
 import { TaskRan, TaskFailed, TaskSkipped } from "./events.ts";
 import type { LockManager, ManagedLock } from "@zerotal/core/lock";
-import { CronExpression } from "./CronExpression.ts";
+import { CronExpression, isValidTimeZone } from "./CronExpression.ts";
+import { UnknownTimeZoneError } from "./errors.ts";
 import { frameworkLog } from "@zerotal/core/logger";
 
+/**
+ * The tick a timezoned task rides on.
+ *
+ * `Bun.cron` evaluates a schedule in the system zone and offers no way to change
+ * that, so a task with its own zone registers this instead and does the matching
+ * itself. Minute granularity is not a compromise: five fields is all `Bun.cron`
+ * accepts, so a minute is the finest a Zerotal schedule can express anyway.
+ */
+const EVERY_MINUTE = "* * * * *";
+
 // ── Output capture (shared, reference-counted) ────────────────────────────────
 // A single `console.log` patch is installed while ANY task is capturing, and the
 // captured output is routed to the running task's own buffer via AsyncLocalStorage.
@@ -47,7 +58,7 @@ export interface OverlapLockOptions {
    * Take a cross-process lock (via the configured lock driver) in addition to the
    * in-process guard. Default: `true`. Set `false` to guard within this process only.
    */
-  crossProcess?: boolean;
+  crossProcess?: boolean | undefined;
 
   /**
    * **How long after a crash before another host may take the task over**, in
@@ -64,7 +75,7 @@ export interface OverlapLockOptions {
    * want a crash to be *slower* to recover from, which is rarely what anyone
    * wants.
    */
-  expiresAfterMinutes?: number;
+  expiresAfterMinutes?: number | undefined;
 
   /**
    * Heartbeat the lock for as long as the task runs. Default: `true`.
@@ -73,7 +84,7 @@ export interface OverlapLockOptions {
    * inside {@link expiresAfterMinutes} or lose its lock — and where you must
    * therefore size that value for the worst case.
    */
-  refresh?: boolean;
+  refresh?: boolean | undefined;
 }
 
 export class ScheduledTask {
@@ -134,6 +145,14 @@ export class ScheduledTask {
     this._callback = callback;
   }
 
+  /**
+   * Evaluate this task's schedule in `tz` rather than the server's zone.
+   *
+   * @param tz - An IANA zone name, e.g. `"Africa/Johannesburg"`.
+   * @throws {@link UnknownTimeZoneError} At {@link start}, when the runtime does not
+   *   know the zone — named there rather than here so a schedule declared as data
+   *   fails where the failure can name the task.
+   */
   timezone(tz: string): this {
     this._timezone = tz;
     return this;
@@ -250,9 +269,18 @@ export class ScheduledTask {
   get lastDurationMs(): number | undefined {
     return this._lastDurationMs;
   }
-  /** Next scheduled fire time from `from` (null if the expression never matches). */
+  /**
+   * Next scheduled fire time from `from` (null if the expression never matches).
+   *
+   * Read in the task's own timezone when it has one, so `schedule:list` and the
+   * monitor agree with when the task will actually run rather than with when the
+   * same expression would fire in the server's zone.
+   */
   nextRunAt(from: Date = new Date()): Date | null {
-    return new CronExpression(this._schedule).nextRun(from);
+    const timezone = this._effectiveTimezone();
+    return timezone
+      ? CronExpression.nextRunAfterIn(this._schedule, from, timezone)
+      : new CronExpression(this._schedule).nextRun(from);
   }
   /** Run the task body immediately, bypassing schedule/time-window guards. */
   async runNow(): Promise<void> {
@@ -497,19 +525,57 @@ export class ScheduledTask {
     };
   }
 
+  /**
+   * The zone this task's schedule is read in: its own, else `scheduler.timezone`.
+   *
+   * `undefined` when that resolves to the zone the process is already in, because
+   * `Bun.cron` evaluates a schedule in the system zone and its own tick is both
+   * cheaper and better tested than a minute tick with a match on top.
+   *
+   * @returns The zone to evaluate in, or `undefined` to let `Bun.cron` do it.
+   */
+  private _effectiveTimezone(): string | undefined {
+    const timezone = this._timezone ?? config.safe("scheduler.timezone", "");
+    if (!timezone) return undefined;
+    return timezone === Intl.DateTimeFormat().resolvedOptions().timeZone ? undefined : timezone;
+  }
+
   start(): void {
     if (this._handle) return;
     const handler = this._buildHandler();
-    // Bun.cron supports croner's options form `(schedule, { run, timezone })` at
-    // runtime, but @types/bun only types the `(schedule, handler)` overload — cast
-    // when passing a timezone.
-    const cronWithOptions = Bun.cron as unknown as (
-      schedule: string,
-      options: { run: () => void | Promise<void>; timezone: string },
-    ) => { stop(): void };
-    this._handle = this._timezone
-      ? cronWithOptions(this._schedule, { run: handler, timezone: this._timezone })
-      : Bun.cron(this._schedule, handler);
+    const timezone = this._effectiveTimezone();
+
+    if (!timezone) {
+      this._handle = Bun.cron(this._schedule, handler);
+      return;
+    }
+
+    if (!isValidTimeZone(timezone)) {
+      throw new UnknownTimeZoneError(this._name, timezone);
+    }
+
+    // `Bun.cron` takes `(schedule, handler)` and nothing else. The croner options
+    // form — `(schedule, { run, timezone })` — throws, and it throws during
+    // *registration*, so one task with a timezone took every other task in the app
+    // with it and the worker restart-looped. Setting a timezone is the obvious
+    // thing to do for a business that operates in one country and is not on UTC,
+    // which is most of them.
+    //
+    // So the schedule is evaluated here rather than by Bun. Bun ticks once a
+    // minute — the finest granularity it has, so nothing is given up — and the task
+    // runs on the ticks where the expression matches the wall clock in its own
+    // zone. Comparing against the zone's local time rather than an offset computed
+    // at registration is also what keeps it right across a DST change.
+    //
+    // A wall clock that skips an hour skips the schedules inside it, and one that
+    // repeats an hour runs them twice. That is what every cron does, and the
+    // alternative — inventing a firing time the clock never showed — is worse.
+    const expression = new CronExpression(this._schedule);
+
+    this._handle = Bun.cron(EVERY_MINUTE, async () => {
+      if (!expression.matchesIn(new Date(), timezone)) return;
+      await handler();
+    });
   }
 
   stop(): void {

package/src/SchedulerManager.ts

@@ -24,10 +24,28 @@ export class SchedulerManager {
     return new SchedulerBuilder(this, name, callback);
   }
 
+  /**
+   * Register every task with the runtime's cron.
+   *
+   * A task that cannot be registered takes itself out and nothing else. Registration
+   * throws for exactly the reasons that are one task's problem — an expression the
+   * runtime rejects, a timezone it does not know — and letting one of them propagate
+   * meant the worker died during boot and restart-looped, so a typo in one schedule
+   * stopped every schedule in the app. Which ones those are is not a thing you can
+   * see from a crash loop.
+   */
   start(): void {
     this._started = true;
     for (const task of this._tasks.values()) {
-      task.start();
+      try {
+        task.start();
+      } catch (err) {
+        frameworkLog("scheduler").error(
+          `Task "${task.name}" did not register and will not run: ${(err as Error).message ?? String(err)}`,
+          { task: task.name, schedule: task.schedule },
+        );
+        continue;
+      }
       frameworkLog("scheduler").info(`Started "${task.name}" — ${task.schedule}`);
     }
   }

package/src/config.ts

@@ -2,8 +2,15 @@ import { deepMerge } from "@zerotal/core";
 import { DEFAULT_RUN_LOG_KEEP, DEFAULT_RUN_LOG_PATH } from "./runLog.ts";
 
 export interface SchedulerConfigShape {
-  /** Timezone for cron expressions. Informational only - Bun.cron uses
-   *  the system timezone. Default: 'UTC' */
+  /**
+   * IANA timezone every schedule's cron expression is read in, unless the task
+   * sets its own with `.timezone(tz)`.
+   *
+   * Defaults to the system zone, so an app that does not set this keeps whatever
+   * its server does. Setting it is the usual case for a business that operates in
+   * one country and is not on UTC — one line instead of a `.timezone()` on every
+   * task.
+   */
   timezone: string;
   /** Durable run history — read with `schedule:runs` (see runLog.ts). */
   runLog: {
@@ -17,7 +24,10 @@ export interface SchedulerConfigShape {
 }
 
 const defaults: SchedulerConfigShape = {
-  timezone: "UTC",
+  // The system zone rather than a hardcoded "UTC": the default has to be what the
+  // app already does, or turning this key from decoration into behaviour would have
+  // moved every schedule in every app that never set it.
+  timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
   runLog: {
     path: DEFAULT_RUN_LOG_PATH,
     keep: DEFAULT_RUN_LOG_KEEP,

package/src/errors.ts

@@ -0,0 +1,32 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for all @zerotal/scheduler errors. */
+export class SchedulerError extends ZerotalError {
+  constructor(
+    message: string,
+    code = "E_SCHEDULER",
+    status = 500,
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, status, context);
+  }
+}
+
+/**
+ * Thrown when a task declares a timezone this runtime does not know.
+ *
+ * Raised at registration rather than at the first tick, because a `RangeError`
+ * thrown once a minute from inside a cron callback names the formatter and not the
+ * task — and a typo'd zone would otherwise be a task that silently never runs.
+ */
+export class UnknownTimeZoneError extends SchedulerError {
+  constructor(task: string, timezone: string) {
+    super(
+      `[Zerotal Scheduler] Task "${task}" declares timezone "${timezone}", which this runtime ` +
+        `does not know. Use an IANA name, e.g. "Africa/Johannesburg" or "UTC".`,
+      "E_SCHEDULER_UNKNOWN_TIMEZONE",
+      500,
+      { task, timezone },
+    );
+  }
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export { SchedulerManager, SchedulerBuilder } from "./SchedulerManager.ts";
 export { ScheduledTask } from "./ScheduledTask.ts";
-export { CronExpression } from "./CronExpression.ts";
+export { CronExpression, wallClockIn, isValidTimeZone } from "./CronExpression.ts";
+export { SchedulerError, UnknownTimeZoneError } from "./errors.ts";
 export { SchedulerProvider } from "./provider/SchedulerProvider.ts";
 
 // Convention-based scheduling: extend Schedule, drop it in app/schedules/.