@zudojs/scheduler 1.1.1 → 1.2.0

package/README.md

@@ -41,6 +41,28 @@ scheduler.start();
 await scheduler.stop({ timeoutMs: 30_000 });
 ```
 
+## Starting and stopping
+
+A started scheduler keeps the Node.js process alive until `stop()`, so a
+script whose only work is a scheduler runs its jobs instead of exiting
+straight away. Pass `keepAlive: false` for a scheduler that should never hold
+the process open by itself (the behaviour before 1.2.0).
+
+`stop()` is idempotent: calling it on a scheduler that never started, or
+calling it twice, resolves instead of throwing `SchedulerStoppedError`.
+`stop({ drain: true })` lets running jobs finish instead of aborting them.
+
+For deterministic tests, pass your own clock. `Clock` is exported from the
+package root:
+
+```typescript
+import { Scheduler } from "@zudojs/scheduler";
+import type { Clock } from "@zudojs/scheduler";
+
+const clock: Clock = { now: () => new Date(0), nowMs: () => 0 };
+const scheduler = new Scheduler({ clock });
+```
+
 ## Scheduling
 
 Four entry points, each returning a `ScheduleHandle`:
@@ -104,6 +126,15 @@ A timeout raises `SchedulerJobTimeoutError` and **aborts the handler** via
 `ctx.signal`; anything else raises `SchedulerJobExecutionError` carrying the
 original error as `cause`.
 
+`ctx.attempt` is the attempt in progress, **1-based**: `1` on the first run,
+`2` on the first retry. `ctx.attemptNumber` is the same number under the name
+`@zudojs/queue` uses for its processor context, so both packages count
+attempts the same way.
+
+An invalid cron expression throws `CronParseError` with the expression quoted
+first and the reason after it:
+`Invalid cron expression "99 0 * * *": Cron field "minute" value 99 is outside 0-59.`
+
 ## Concurrency and overlap
 
 `maxConcurrency` (default 10) bounds executions in flight across all schedules;
@@ -176,6 +207,10 @@ scheduler.getExecutions("cleanup");
 //    duration, attempt, error? }]
 ```
 
+`attempt` is the attempt that settled the run — `3` for a run whose retry
+policy let it succeed on its third try — and, while the run is still going,
+the attempt currently in progress.
+
 ## Features
 
 - Delay, date, interval and cron triggers

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export { DateTrigger, DelayTrigger, IntervalTrigger, CronTrigger, } from "./sche
 export { parseCron, nextCronDate } from "./scheduler/trigger/index.js";
 export type { ParsedCron } from "./scheduler/trigger/index.js";
 export { SystemClock, createSystemClock } from "./scheduler/clock/index.js";
+export type { Clock } from "./scheduler/clock/index.js";
 export { JobRegistry } from "./scheduler/registry/index.js";
 export { JobExecutor, retryDelay } from "./scheduler/executor/index.js";
 export { PriorityQueue } from "./scheduler/priorityQueue/index.js";

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

@@ -17,9 +17,13 @@ export declare class JobExecutor {
      * @param attempt - The attempt number to start from (1-based).
      * @param signal - Signal that aborts the job and stops further retries.
      * @param data - Optional payload handed to the handler.
+     * @param hooks - `onAttempt` is told the 1-based number of each attempt as
+     *   it starts, so a caller can record the attempt that settled the run.
      * @returns The execution result.
      */
-    execute(job: JobDefinition, executionId: string, scheduledAt: Date, attempt: number, signal: AbortSignal, data?: unknown): Promise<JobExecutionResult>;
+    execute(job: JobDefinition, executionId: string, scheduledAt: Date, attempt: number, signal: AbortSignal, data?: unknown, hooks?: {
+        readonly onAttempt?: (attempt: number) => void;
+    }): Promise<JobExecutionResult>;
     /** Runs the handler once, under a timeout that also aborts it. */
     private runOnce;
     /** Maps a thrown value onto the scheduler's error taxonomy. */

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

@@ -20,9 +20,11 @@ export class JobExecutor {
      * @param attempt - The attempt number to start from (1-based).
      * @param signal - Signal that aborts the job and stops further retries.
      * @param data - Optional payload handed to the handler.
+     * @param hooks - `onAttempt` is told the 1-based number of each attempt as
+     *   it starts, so a caller can record the attempt that settled the run.
      * @returns The execution result.
      */
-    async execute(job, executionId, scheduledAt, attempt, signal, data) {
+    async execute(job, executionId, scheduledAt, attempt, signal, data, hooks) {
         const retry = job.options?.retry;
         const maxAttempts = Math.max(1, retry?.attempts ?? 1);
         let currentAttempt = attempt;
@@ -31,6 +33,7 @@ export class JobExecutor {
             if (signal.aborted) {
                 throw new SchedulerJobCancelledError("Job was cancelled via signal.", job.id);
             }
+            hooks?.onAttempt?.(currentAttempt);
             try {
                 await this.runOnce(job, executionId, scheduledAt, currentAttempt, signal, data);
                 return { success: true };

package/dist/scheduler/job/jobContext.type.d.ts

@@ -6,7 +6,16 @@ export interface JobContext<T = unknown> {
     readonly executionId: string;
     readonly scheduledAt: Date;
     readonly startedAt: Date;
+    /**
+     * The attempt in progress, 1-based: `1` on the first run, `2` on the first
+     * retry. Counts attempts within one execution, per the job's retry policy.
+     */
     readonly attempt: number;
+    /**
+     * Alias of {@link JobContext.attempt}, named as in `@zudojs/queue`, whose
+     * processor context carries the same 1-based `attemptNumber`.
+     */
+    readonly attemptNumber: number;
     readonly data: T;
     readonly signal: AbortSignal;
 }

package/dist/scheduler/job/jobContext.type.js

@@ -8,6 +8,7 @@ export function createJobContext(jobId, executionId, scheduledAt, startedAt, att
         scheduledAt,
         startedAt,
         attempt,
+        attemptNumber: attempt,
         data,
         signal,
     });

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;
 }
@@ -24,6 +28,12 @@ export interface SchedulerOptions {
     readonly maxConcurrency?: number;
     /** Called when a job execution fails. */
     readonly onError?: (event: SchedulerErrorEvent) => void;
+    /**
+     * Whether a started scheduler keeps the Node.js process alive until
+     * `stop()` (default: true). Pass `false` for a scheduler that should never
+     * by itself hold the process open.
+     */
+    readonly keepAlive?: boolean;
 }
 /**
  * Scheduler for time-based job execution.
@@ -46,6 +56,7 @@ export declare class Scheduler {
     private readonly schedules;
     private readonly maxConcurrency;
     private readonly onError;
+    private readonly keepAlive;
     /** Executions currently in flight, across all schedules. */
     private readonly inFlight;
     /**
@@ -57,6 +68,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. */
@@ -87,6 +108,9 @@ export declare class Scheduler {
     /**
      * Stops the scheduler, aborting in-flight jobs and waiting for them to settle.
      *
+     * Idempotent: on a scheduler that never started, or one already stopped, it
+     * only waits for any executions still settling.
+     *
      * @param options - `drain` waits for running jobs to finish instead of
      *   aborting them; `timeoutMs` bounds the wait either way.
      */
@@ -137,7 +161,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.
@@ -166,6 +196,8 @@ export declare class Scheduler {
     private drainPending;
     /** Records a started execution, evicting the oldest beyond the cap. */
     private beginExecution;
+    /** Records the attempt an execution is on, if it is still in the history. */
+    private recordAttempt;
     /** Completes the record for an execution, if it is still in the history. */
     private finishExecution;
     /**

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, 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";
@@ -35,6 +35,7 @@ export class Scheduler {
     schedules = new Map();
     maxConcurrency;
     onError;
+    keepAlive;
     /** Executions currently in flight, across all schedules. */
     inFlight = new Set();
     /**
@@ -46,6 +47,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. */
@@ -76,6 +87,7 @@ export class Scheduler {
         this.queue = opts.queue ?? new PriorityQueue();
         this.maxConcurrency = opts.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
         this.onError = opts.onError;
+        this.keepAlive = opts.keepAlive ?? true;
     }
     /** Whether the scheduler is currently running. */
     get isRunning() {
@@ -98,12 +110,16 @@ export class Scheduler {
     /**
      * Stops the scheduler, aborting in-flight jobs and waiting for them to settle.
      *
+     * Idempotent: on a scheduler that never started, or one already stopped, it
+     * only waits for any executions still settling.
+     *
      * @param options - `drain` waits for running jobs to finish instead of
      *   aborting them; `timeoutMs` bounds the wait either way.
      */
     async stop(options) {
         if (!this.running) {
-            throw new SchedulerStoppedError();
+            await this.settle(options?.timeoutMs);
+            return;
         }
         this.running = false;
         if (this.timer) {
@@ -260,6 +276,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.
@@ -269,6 +286,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();
@@ -319,12 +341,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"));
         }
     }
@@ -353,7 +381,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();
     }
@@ -365,8 +397,11 @@ export class Scheduler {
             clearTimeout(this.timer);
         const delay = this.calculateDelay();
         this.timer = setTimeout(() => this.tick(), delay);
-        if (this.timer.unref)
-            this.timer.unref();
+        // Referenced by default: a started scheduler is the process's reason to
+        // stay alive until stop(). An unreferenced timer let a script that only
+        // ran a scheduler exit 0 before anything fired.
+        if (!this.keepAlive)
+            this.timer.unref?.();
     }
     /**
      * Computes the next fire time and puts the schedule back on the queue.
@@ -404,8 +439,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") {
@@ -442,6 +489,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;
@@ -456,7 +509,7 @@ export class Scheduler {
             attempt: 1,
         });
         const execution = this.executor
-            .execute(job, executionId, scheduledAt, 1, controller.signal, record.options.data)
+            .execute(job, executionId, scheduledAt, 1, controller.signal, record.options.data, { onAttempt: (attempt) => this.recordAttempt(executionId, attempt) })
             .then(() => {
             this.finishExecution(executionId, "completed", startedAt);
         })
@@ -475,6 +528,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)
@@ -526,6 +585,16 @@ export class Scheduler {
             this.executionHistory.shift();
         }
     }
+    /** Records the attempt an execution is on, if it is still in the history. */
+    recordAttempt(executionId, attempt) {
+        const index = this.executionHistory.findIndex((entry) => entry.id === executionId);
+        if (index === -1)
+            return;
+        this.executionHistory[index] = {
+            ...this.executionHistory[index],
+            attempt,
+        };
+    }
     /** Completes the record for an execution, if it is still in the history. */
     finishExecution(executionId, status, startedAt, error) {
         const index = this.executionHistory.findIndex((entry) => entry.id === executionId);

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

@@ -64,12 +64,12 @@ const MAX_SEARCH_YEARS = 5;
 export function parseCron(expression) {
     const trimmed = expression.trim().toLowerCase();
     if (trimmed.length === 0) {
-        throw new CronParseError("Cron expression cannot be empty", expression);
+        throw new CronParseError(expression, "Cron expression cannot be empty");
     }
     const expanded = MACROS[trimmed] ?? trimmed;
     const fields = expanded.split(/\s+/);
     if (fields.length !== 5) {
-        throw new CronParseError(`Cron expression must have 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`, expression);
+        throw new CronParseError(expression, `Cron expression must have 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`);
     }
     const sets = FIELD_BOUNDS.map((bounds, index) => parseField(fields[index] ?? "", bounds, expression));
     return {
@@ -85,17 +85,18 @@ export function parseCron(expression) {
 /** Parses a single cron field into the set of values it permits. */
 function parseField(field, bounds, expression) {
     if (field.length === 0) {
-        throw new CronParseError(`Cron field "${bounds.name}" is empty`, expression);
+        throw new CronParseError(expression, `Cron field "${bounds.name}" is empty`);
     }
     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)) {
-            throw new CronParseError(`Cron field "${bounds.name}" has an invalid step: "${part}"`, expression);
+            throw new CronParseError(expression, `Cron field "${bounds.name}" has an invalid step: "${part}"`);
         }
         const step = stepPart === undefined ? 1 : Number(stepPart);
         if (step === 0) {
-            throw new CronParseError(`Cron field "${bounds.name}" has a zero step: "${part}"`, expression);
+            throw new CronParseError(expression, `Cron field "${bounds.name}" has a zero step: "${part}"`);
         }
         let start;
         let end;
@@ -105,10 +106,18 @@ 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);
+                throw new CronParseError(expression, `Cron field "${bounds.name}" has an inverted range: "${rangePart}"`);
             }
         }
         else {
@@ -117,21 +126,30 @@ 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) {
-        throw new CronParseError(`Cron field "${bounds.name}" matches no values: "${field}"`, expression);
+        throw new CronParseError(expression, `Cron field "${bounds.name}" matches no values: "${field}"`);
     }
     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;
         }
     }
@@ -142,10 +160,11 @@ function resolveValue(raw, bounds, expression) {
         value = DAY_NAMES[raw];
     }
     else {
-        throw new CronParseError(`Cron field "${bounds.name}" has an invalid value: "${raw}"`, expression);
+        throw new CronParseError(expression, `Cron field "${bounds.name}" has an invalid value: "${raw}"`);
     }
-    if (value < bounds.min || value > bounds.max) {
-        throw new CronParseError(`Cron field "${bounds.name}" value ${value} is outside ${bounds.min}-${bounds.max}`, expression);
+    const max = rawDayOfWeek && bounds.name === "dayOfWeek" ? 7 : bounds.max;
+    if (value < bounds.min || value > max) {
+        throw new CronParseError(expression, `Cron field "${bounds.name}" value ${value} is outside ${bounds.min}-${bounds.max}`);
     }
     return value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/scheduler",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Scheduled task and job infrastructure with cron-like scheduling, persistence, and worker management.",
   "license": "MIT",
   "author": {
@@ -27,13 +27,13 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/types": "1.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/types": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
     "cron",
     "jobs"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-scheduler",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },