@zudojs/scheduler 1.0.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/duration/duration.parser.js

@@ -38,7 +38,10 @@ export function parseDuration(duration) {
         throw new InvalidDurationError(duration);
     }
     // Each component is digits followed by a unit. `ms` is matched before `m`.
-    const pattern = /(\d+)(ms|s|m|h|d|w)/gy;
+    // Sticky, not global: a failed component ends the loop instead of rescanning
+    // from the next offset, so a long digit run cannot be re-matched per offset.
+    // (`g` alongside `y` was redundant — sticky already wins for `exec`.)
+    const pattern = /(\d+)(ms|s|m|h|d|w)/y; // codeql[js/polynomial-redos]
     let total = 0;
     let matched = 0;
     let match;

package/dist/scheduler/executor/jobExecutor.core.js

@@ -1,6 +1,6 @@
 import { createJobContext } from "../job/jobContext.type.js";
 import { SchedulerJobExecutionError, SchedulerJobCancelledError, SchedulerJobTimeoutError, } from "../errors/scheduler.errors.js";
-import { DEFAULT_JOB_TIMEOUT, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_DELAY, } from "../constants/schedulerConstants.core.js";
+import { DEFAULT_JOB_TIMEOUT, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_DELAY, MAX_TIMER_DELAY, } from "../constants/schedulerConstants.core.js";
 /** Marker attached to the rejection a timeout produces, carrying its budget. */
 const TIMEOUT = Symbol("scheduler.timeout");
 /**
@@ -54,7 +54,10 @@ export class JobExecutor {
     }
     /** Runs the handler once, under a timeout that also aborts it. */
     async runOnce(job, executionId, scheduledAt, attempt, signal, data) {
-        const timeout = job.options?.timeout ?? DEFAULT_JOB_TIMEOUT;
+        // A job registered straight into a `JobRegistry` skips `define()`'s
+        // validation; clamp so an oversized budget waits, rather than being
+        // silently reduced to 1ms by the timer subsystem.
+        const timeout = Math.min(job.options?.timeout ?? DEFAULT_JOB_TIMEOUT, MAX_TIMER_DELAY);
         // A dedicated controller per attempt, chained to the caller's signal, so a
         // timeout actually aborts the handler instead of only rejecting the
         // wrapper while the work carries on.

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

@@ -63,6 +63,12 @@ export declare class Scheduler {
     private readonly pending;
     /** Bounded ring of execution records, newest last. */
     private readonly executionHistory;
+    /**
+     * Final state of schedules that have been retired, so a handle to a
+     * one-shot that already fired reports "completed" instead of the "active"
+     * it was created with. Bounded to {@link MAX_SCHEDULES} entries.
+     */
+    private readonly retiredStates;
     private running;
     private timer?;
     /**
@@ -122,6 +128,15 @@ export declare class Scheduler {
     private scheduleJob;
     /** Applies a state change to a live schedule. */
     private setScheduleState;
+    /**
+     * Drops a schedule that will never fire again, remembering why.
+     *
+     * Runs already held back by `overlap: "queue"` or a concurrency ceiling
+     * are kept by default: they are fire times that have arrived, and a
+     * one-shot retired at dispatch still owes them. Only a cancel, or a
+     * misfire policy that says skip, discards them.
+     */
+    private retire;
     /** Aborts every in-flight execution of one schedule. */
     private abortSchedule;
     /**

package/dist/scheduler/scheduler.core.js

@@ -52,6 +52,12 @@ export class Scheduler {
     pending = new Set();
     /** Bounded ring of execution records, newest last. */
     executionHistory = [];
+    /**
+     * Final state of schedules that have been retired, so a handle to a
+     * one-shot that already fired reports "completed" instead of the "active"
+     * it was created with. Bounded to {@link MAX_SCHEDULES} entries.
+     */
+    retiredStates = new Map();
     running = false;
     timer;
     /**
@@ -146,8 +152,14 @@ export class Scheduler {
         if (typeof job.handler !== "function") {
             throw new InvalidJobError(`Job "${job.id}" requires a handler function.`, job.id);
         }
-        if (job.options?.timeout !== undefined && job.options.timeout <= 0) {
-            throw new InvalidJobError(`Job "${job.id}" timeout must be positive, got ${job.options.timeout}.`, job.id);
+        if (job.options?.timeout !== undefined &&
+            (!Number.isFinite(job.options.timeout) ||
+                job.options.timeout <= 0 ||
+                job.options.timeout > MAX_TIMER_DELAY)) {
+            // `Infinity` and anything past the 32-bit timer ceiling are clamped
+            // by Node to 1ms, so a job declared with "no timeout" was failing on
+            // its first millisecond.
+            throw new InvalidJobError(`Job "${job.id}" timeout must be a positive number no greater than ${MAX_TIMER_DELAY}ms, got ${job.options.timeout}.`, job.id);
         }
         this.jobs.register(job);
     }
@@ -199,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
@@ -223,11 +241,16 @@ 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", {
             setState: (state) => this.setScheduleState(scheduleId, state),
-            getState: () => this.schedules.get(scheduleId)?.schedule.state,
+            getState: () => this.schedules.get(scheduleId)?.schedule.state ??
+                this.retiredStates.get(scheduleId),
             getNextRun: () => this.schedules.get(scheduleId)?.schedule.nextRunAt,
             abortRunning: () => this.abortSchedule(scheduleId),
         });
@@ -240,10 +263,7 @@ export class Scheduler {
         record.schedule = { ...record.schedule, state };
         if (state === "cancelled" || state === "completed") {
             // Held-back runs belong to a schedule that no longer exists.
-            record.pendingRuns = 0;
-            this.pending.delete(record);
-            this.queue.remove(scheduleId);
-            this.schedules.delete(scheduleId);
+            this.retire(record, state, { dropPending: true });
         }
         else if (state === "paused") {
             this.queue.remove(scheduleId);
@@ -251,13 +271,52 @@ export class Scheduler {
         else if (state === "active") {
             // Resuming: recompute from now so a schedule paused across its fire time
             // does not immediately fire for every occurrence it missed.
-            const next = record.trigger.next(this.clock.now());
-            if (next && !Number.isNaN(next.getTime())) {
-                record.schedule = { ...record.schedule, nextRunAt: next };
-                this.queue.remove(scheduleId);
-                this.queue.enqueue(record.schedule);
-                this.rearm();
+            const now = this.clock.now();
+            let next = record.trigger.next(now);
+            if (next === null) {
+                // The fire time passed while paused. A one-shot used to stay "active"
+                // here with nothing ever able to dispatch it; apply the misfire
+                // policy exactly as `scheduleJob` does for a fire time already past.
+                const misfire = record.options.misfire ?? DEFAULT_MISFIRE_POLICY;
+                const isRecurring = record.schedule.type === "interval" ||
+                    record.schedule.type === "cron";
+                if (misfire === "skip" || isRecurring) {
+                    // Nothing left to fire: retire it rather than leaking an entry.
+                    this.retire(record, "completed", { dropPending: true });
+                    return;
+                }
+                next = now;
             }
+            if (Number.isNaN(next.getTime()))
+                return;
+            record.schedule = { ...record.schedule, nextRunAt: next };
+            this.queue.remove(scheduleId);
+            this.queue.enqueue(record.schedule);
+            this.rearm();
+        }
+    }
+    /**
+     * Drops a schedule that will never fire again, remembering why.
+     *
+     * Runs already held back by `overlap: "queue"` or a concurrency ceiling
+     * are kept by default: they are fire times that have arrived, and a
+     * one-shot retired at dispatch still owes them. Only a cancel, or a
+     * misfire policy that says skip, discards them.
+     */
+    retire(record, state, options) {
+        record.schedule = { ...record.schedule, state };
+        if (options?.dropPending === true) {
+            record.pendingRuns = 0;
+            this.pending.delete(record);
+        }
+        this.queue.remove(record.schedule.id);
+        this.schedules.delete(record.schedule.id);
+        this.retiredStates.set(record.schedule.id, state);
+        while (this.retiredStates.size > MAX_SCHEDULES) {
+            const oldest = this.retiredStates.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.retiredStates.delete(oldest);
         }
     }
     /** Aborts every in-flight execution of one schedule. */
@@ -319,12 +378,8 @@ export class Scheduler {
         const isRecurring = record.schedule.type === "interval" || record.schedule.type === "cron";
         if (!isRecurring) {
             // One-shot: retire it rather than leaking the entry.
-            record.schedule = {
-                ...record.schedule,
-                state: "completed",
-                lastRunAt: this.clock.now(),
-            };
-            this.schedules.delete(record.schedule.id);
+            record.schedule = { ...record.schedule, lastRunAt: this.clock.now() };
+            this.retire(record, "completed");
             return;
         }
         // "catch-up" advances from the fire time that just ran, so a schedule
@@ -336,8 +391,7 @@ export class Scheduler {
         const next = record.trigger.next(from);
         if (!next || Number.isNaN(next.getTime())) {
             // A trigger with no further fire time is finished.
-            record.schedule = { ...record.schedule, state: "completed" };
-            this.schedules.delete(record.schedule.id);
+            this.retire(record, "completed");
             return;
         }
         record.schedule = {
@@ -428,6 +482,9 @@ export class Scheduler {
             else
                 this.runningByJob.set(job.id, remaining);
             this.drainPending();
+            // Capacity freed: a schedule held back by the ceiling is waiting for
+            // exactly this moment, and no timer is armed for it.
+            this.rearm();
         });
         this.inFlight.add(execution);
     }
@@ -516,6 +573,13 @@ export class Scheduler {
         if (this.queue.isEmpty) {
             return MAX_TIMER_DELAY;
         }
+        // At the ceiling a due schedule cannot be dispatched, and arming a
+        // zero-delay timer for it spun the event loop — about a tick per
+        // millisecond — until an execution finished. The finishing execution
+        // re-arms the timer, so waiting here loses nothing.
+        if (this.inFlight.size >= this.maxConcurrency) {
+            return MAX_TIMER_DELAY;
+        }
         const next = this.queue.peek();
         if (!next) {
             return MAX_TIMER_DELAY;

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,8 +1,12 @@
 {
   "name": "@zudojs/scheduler",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Scheduled task and job infrastructure with cron-like scheduling, persistence, and worker management.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,9 +27,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0",
-    "@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",