@zudojs/scheduler 1.1.0 → 1.1.2

package/README.md

@@ -2,6 +2,12 @@
 
 In-process scheduling for delayed, recurring and cron-driven jobs.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-scheduler](https://zudojs.oyinlola.site/docs/packages-scheduler) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-scheduler.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -151,6 +157,13 @@ for a recurring schedule whose process was blocked past its fire time.
 scheduler.every("1h", "hourly-rollup", { misfire: "catch-up" });
 ```
 
+A cron expression that can never fire (`0 0 30 2 *`, 30 February) is not a
+misfire: `cron()` throws `InvalidScheduleError` at registration.
+
+Schedules may be added before or after `start()`. One added to a running
+scheduler re-arms the timer immediately, so it fires on time even when it is
+due sooner than every existing schedule.
+
 ## Execution history
 
 The scheduler keeps the last 100 executions (`MAX_EXECUTION_HISTORY`), each a

package/dist/scheduler/scheduler.core.d.ts

@@ -11,6 +11,10 @@ import { PriorityQueue } from "./priorityQueue/schedulerPriorityQueue.core.js";
 export interface SchedulerErrorEvent {
     readonly scheduleId: string;
     readonly jobId: string;
+    /**
+     * The execution that failed. Empty when the failure happened before any
+     * execution could start — a schedule whose job is no longer registered.
+     */
     readonly executionId: string;
     readonly error: unknown;
 }
@@ -57,6 +61,16 @@ export declare class Scheduler {
      * to abort.
      */
     private readonly runningControllers;
+    /**
+     * In-flight controllers per schedule id.
+     *
+     * Indexed by id for the same reason {@link runningControllers} exists: a
+     * one-shot is retired at dispatch time, so `cancel()` arrives after its
+     * record has already been deleted and the record's own `running` set is
+     * unreachable. Without this, `handle.cancel()` aborted a recurring
+     * schedule's run and silently did nothing for a one-shot's.
+     */
+    private readonly runningByScheduleId;
     /** Executions in flight per job id, for the per-job concurrency ceiling. */
     private readonly runningByJob;
     /** Records with `pendingRuns > 0`, drained as executions finish. */
@@ -137,7 +151,13 @@ export declare class Scheduler {
      * misfire policy that says skip, discards them.
      */
     private retire;
-    /** Aborts every in-flight execution of one schedule. */
+    /**
+     * Aborts every in-flight execution of one schedule.
+     *
+     * Resolved through {@link runningByScheduleId} rather than the schedule
+     * map: a one-shot is retired as soon as it is dispatched, so its record is
+     * already gone while its execution is still running.
+     */
     private abortSchedule;
     /**
      * Internal tick method for processing due jobs.

package/dist/scheduler/scheduler.core.js

@@ -1,6 +1,6 @@
 import { ScheduleHandleImpl } from "./scheduleHandle/scheduleHandle.type.js";
 import { createSchedule } from "./schedule/schedule.type.js";
-import { SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobCancelledError, SchedulerJobTimeoutError, InvalidScheduleError, InvalidJobError, } from "./errors/scheduler.errors.js";
+import { SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobCancelledError, SchedulerJobNotFoundError, SchedulerJobTimeoutError, InvalidScheduleError, InvalidJobError, } from "./errors/scheduler.errors.js";
 import { DateTrigger, DelayTrigger, IntervalTrigger, CronTrigger, } from "./trigger/schedulerTrigger.core.js";
 import { SystemClock } from "./clock/schedulerClock.type.js";
 import { JobRegistry } from "./registry/jobRegistry.core.js";
@@ -46,6 +46,16 @@ export class Scheduler {
      * to abort.
      */
     runningControllers = new Set();
+    /**
+     * In-flight controllers per schedule id.
+     *
+     * Indexed by id for the same reason {@link runningControllers} exists: a
+     * one-shot is retired at dispatch time, so `cancel()` arrives after its
+     * record has already been deleted and the record's own `running` set is
+     * unreachable. Without this, `handle.cancel()` aborted a recurring
+     * schedule's run and silently did nothing for a one-shot's.
+     */
+    runningByScheduleId = new Map();
     /** Executions in flight per job id, for the per-job concurrency ceiling. */
     runningByJob = new Map();
     /** Records with `pendingRuns > 0`, drained as executions finish. */
@@ -211,6 +221,12 @@ export class Scheduler {
         const scheduleId = crypto.randomUUID();
         const now = this.clock.now();
         let nextRunAt = trigger.next(now);
+        if (nextRunAt === null && (type === "cron" || type === "interval")) {
+            // A recurring trigger with no next fire time is unsatisfiable (30
+            // February) — not a misfire. Running it "once now" fired a job at an
+            // arbitrary moment and then retired it silently.
+            throw new InvalidScheduleError(`Recurring trigger has no future fire time${expression === undefined ? "" : ` ("${expression}")`}.`, jobId);
+        }
         if (nextRunAt === null) {
             // The fire time has already passed. That is the misfire case, not an
             // error — `at(pastDate)` and a schedule restored after a restart both
@@ -235,6 +251,10 @@ export class Scheduler {
         };
         this.schedules.set(scheduleId, record);
         this.queue.enqueue(schedule);
+        // A schedule added after start() must re-arm the timer: it may be due
+        // sooner than whatever the timer is currently armed for (up to ~24.8
+        // days on an empty scheduler).
+        this.rearm();
         // The handle holds a reference to this scheduler, so pause, resume and
         // cancel actually reach the queue instead of mutating a detached copy.
         return new ScheduleHandleImpl(scheduleId, "active", {
@@ -250,6 +270,7 @@ export class Scheduler {
         const record = this.schedules.get(scheduleId);
         if (!record)
             return;
+        const previous = record.schedule.state;
         record.schedule = { ...record.schedule, state };
         if (state === "cancelled" || state === "completed") {
             // Held-back runs belong to a schedule that no longer exists.
@@ -259,6 +280,11 @@ export class Scheduler {
             this.queue.remove(scheduleId);
         }
         else if (state === "active") {
+            // Only a paused schedule resumes. `resume()` on a running one used to
+            // recompute its next fire time from now, so a supervisor calling it
+            // idempotently postponed the schedule indefinitely.
+            if (previous !== "paused")
+                return;
             // Resuming: recompute from now so a schedule paused across its fire time
             // does not immediately fire for every occurrence it missed.
             const now = this.clock.now();
@@ -309,12 +335,18 @@ export class Scheduler {
             this.retiredStates.delete(oldest);
         }
     }
-    /** Aborts every in-flight execution of one schedule. */
+    /**
+     * Aborts every in-flight execution of one schedule.
+     *
+     * Resolved through {@link runningByScheduleId} rather than the schedule
+     * map: a one-shot is retired as soon as it is dispatched, so its record is
+     * already gone while its execution is still running.
+     */
     abortSchedule(scheduleId) {
-        const record = this.schedules.get(scheduleId);
-        if (!record)
+        const controllers = this.runningByScheduleId.get(scheduleId);
+        if (!controllers)
             return;
-        for (const controller of record.running) {
+        for (const controller of [...controllers]) {
             controller.abort(new Error("Schedule cancelled"));
         }
     }
@@ -343,7 +375,11 @@ export class Scheduler {
                 break;
             }
             this.dispatch(record);
-            this.reschedule(record);
+            // `dispatch` retires the schedule when its job is no longer
+            // registered; rescheduling a retired record would put a dead entry
+            // back on the queue.
+            if (this.schedules.has(record.schedule.id))
+                this.reschedule(record);
         }
         this.rearm();
     }
@@ -394,8 +430,20 @@ export class Scheduler {
     /** Starts one execution of a schedule and tracks it. */
     dispatch(record) {
         const job = this.jobs.get(record.schedule.jobId);
-        if (!job)
+        if (!job) {
+            // The job was unregistered under a live schedule. Returning silently
+            // left the schedule re-arming its timer forever, dispatching nothing
+            // and reporting nothing, with `handle.state` still "active".
+            const error = new SchedulerJobNotFoundError(record.schedule.jobId);
+            this.retire(record, "cancelled", { dropPending: true });
+            this.reportError({
+                scheduleId: record.schedule.id,
+                jobId: record.schedule.jobId,
+                executionId: "",
+                error,
+            });
             return;
+        }
         // A schedule cancelled or paused while a run was held back must not fire.
         if (record.schedule.state === "cancelled" ||
             record.schedule.state === "paused") {
@@ -432,6 +480,12 @@ export class Scheduler {
         const controller = new AbortController();
         record.running.add(controller);
         this.runningControllers.add(controller);
+        let byScheduleId = this.runningByScheduleId.get(record.schedule.id);
+        if (!byScheduleId) {
+            byScheduleId = new Set();
+            this.runningByScheduleId.set(record.schedule.id, byScheduleId);
+        }
+        byScheduleId.add(controller);
         this.runningByJob.set(job.id, (this.runningByJob.get(job.id) ?? 0) + 1);
         const scheduleId = record.schedule.id;
         const scheduledAt = record.schedule.nextRunAt;
@@ -465,6 +519,12 @@ export class Scheduler {
             .finally(() => {
             record.running.delete(controller);
             this.runningControllers.delete(controller);
+            const live = this.runningByScheduleId.get(scheduleId);
+            if (live) {
+                live.delete(controller);
+                if (live.size === 0)
+                    this.runningByScheduleId.delete(scheduleId);
+            }
             this.inFlight.delete(execution);
             const remaining = (this.runningByJob.get(job.id) ?? 1) - 1;
             if (remaining <= 0)

package/dist/scheduler/trigger/cron.parser.js

@@ -88,6 +88,7 @@ function parseField(field, bounds, expression) {
         throw new CronParseError(`Cron field "${bounds.name}" is empty`, expression);
     }
     const values = new Set();
+    const isDayOfWeek = bounds.name === "dayOfWeek";
     for (const part of field.split(",")) {
         const [rangePart, stepPart] = part.split("/");
         if (stepPart !== undefined && !/^\d+$/.test(stepPart)) {
@@ -105,8 +106,16 @@ function parseField(field, bounds, expression) {
         }
         else if (rangePart.includes("-")) {
             const [from, to] = rangePart.split("-");
-            start = resolveValue(from ?? "", bounds, expression);
-            end = resolveValue(to ?? "", bounds, expression);
+            // Range endpoints keep their raw day-of-week spelling: normalising 7
+            // to 0 before the endpoints are compared turned "0-7" into Sunday
+            // alone and made "1-7" an inverted range.
+            start = resolveValue(from ?? "", bounds, expression, isDayOfWeek);
+            end = resolveValue(to ?? "", bounds, expression, isDayOfWeek);
+            // "mon-sun" names Monday through Sunday: the end is the week's last
+            // day, not its first. "sun-sat" is left alone — it already ascends.
+            if (isDayOfWeek && end === 0 && start > end) {
+                end = 7;
+            }
             if (start > end) {
                 throw new CronParseError(`Cron field "${bounds.name}" has an inverted range: "${rangePart}"`, expression);
             }
@@ -117,7 +126,8 @@ function parseField(field, bounds, expression) {
             end = stepPart === undefined ? start : bounds.max;
         }
         for (let v = start; v <= end; v += step) {
-            values.add(v);
+            // Both 0 and 7 are Sunday; the set only ever holds 0.
+            values.add(isDayOfWeek && v === 7 ? 0 : v);
         }
     }
     if (values.size === 0) {
@@ -125,13 +135,21 @@ function parseField(field, bounds, expression) {
     }
     return values;
 }
-/** Resolves a numeric or named field value, checking it against the bounds. */
-function resolveValue(raw, bounds, expression) {
+/**
+ * Resolves a numeric or named field value, checking it against the bounds.
+ *
+ * @param raw - The literal from the expression.
+ * @param bounds - The field being parsed.
+ * @param expression - The whole expression, for error reporting.
+ * @param rawDayOfWeek - Keeps day-of-week `7` as 7 and accepts it as a bound,
+ *   for a range endpoint that the caller expands and normalises itself.
+ */
+function resolveValue(raw, bounds, expression, rawDayOfWeek = false) {
     let value;
     if (/^\d+$/.test(raw)) {
         value = Number(raw);
         // Both 0 and 7 are Sunday in common cron dialects.
-        if (bounds.name === "dayOfWeek" && value === 7) {
+        if (bounds.name === "dayOfWeek" && value === 7 && !rawDayOfWeek) {
             value = 0;
         }
     }
@@ -144,7 +162,8 @@ function resolveValue(raw, bounds, expression) {
     else {
         throw new CronParseError(`Cron field "${bounds.name}" has an invalid value: "${raw}"`, expression);
     }
-    if (value < bounds.min || value > bounds.max) {
+    const max = rawDayOfWeek && bounds.name === "dayOfWeek" ? 7 : bounds.max;
+    if (value < bounds.min || value > max) {
         throw new CronParseError(`Cron field "${bounds.name}" value ${value} is outside ${bounds.min}-${bounds.max}`, expression);
     }
     return value;
@@ -172,7 +191,10 @@ export function nextCronDate(parsed, after, utc = false) {
     };
     // Start at the next whole minute after `after`, with seconds cleared.
     const candidate = new Date(after.getTime());
-    candidate.setSeconds(0, 0);
+    if (utc)
+        candidate.setUTCSeconds(0, 0);
+    else
+        candidate.setSeconds(0, 0);
     candidate.setTime(candidate.getTime() + 60_000);
     const limitYear = get.year(after) + MAX_SEARCH_YEARS;
     while (get.year(candidate) <= limitYear) {
@@ -185,7 +207,7 @@ export function nextCronDate(parsed, after, utc = false) {
             continue;
         }
         if (!parsed.hour.has(get.hour(candidate))) {
-            advanceHour(candidate);
+            advanceHour(candidate, utc);
             continue;
         }
         if (!parsed.minute.has(get.minute(candidate))) {
@@ -246,9 +268,18 @@ function advanceDay(candidate, utc) {
  * Moves to the top of the next hour.
  *
  * Uses wall-clock arithmetic rather than adding an hour of milliseconds, so a
- * DST transition does not skip or repeat an hour of scheduling.
+ * DST transition does not skip or repeat an hour of scheduling. In UTC mode
+ * the top of the hour is taken in UTC: a host on a half-hour offset
+ * (Asia/Kolkata) would otherwise land every skip on :30 UTC and never visit
+ * minutes 0-29 of a restricted hour.
  */
-function advanceHour(candidate) {
+function advanceHour(candidate, utc) {
+    if (utc) {
+        candidate.setUTCMinutes(0, 0, 0);
+        candidate.setTime(candidate.getTime() + 3_600_000);
+        candidate.setUTCMinutes(0, 0, 0);
+        return;
+    }
     candidate.setMinutes(0, 0, 0);
     candidate.setTime(candidate.getTime() + 3_600_000);
     candidate.setMinutes(0, 0, 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/scheduler",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Scheduled task and job infrastructure with cron-like scheduling, persistence, and worker management.",
   "license": "MIT",
   "author": {
@@ -27,9 +27,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/types": "1.0.0"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/types": "1.1.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",