@zudojs/scheduler 1.0.0 → 1.1.0

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);
     }
@@ -227,7 +239,8 @@ export class Scheduler {
         // 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 +253,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 +261,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 +368,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 +381,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 +472,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 +563,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/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/scheduler",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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,8 +27,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0",
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1",
     "@zudojs/types": "1.0.0"
   },
   "devDependencies": {