@zudojs/scheduler 1.1.0 → 1.1.1

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.js

@@ -211,6 +211,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 +241,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", {

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

@@ -172,7 +172,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 +188,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 +249,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.1",
   "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.1.0",
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/types": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",