@zudojs/scheduler 1.1.2 → 1.2.1

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

@@ -28,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.
@@ -50,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;
     /**
@@ -101,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.
      */
@@ -186,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, SchedulerJobNotFoundError, 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();
     /**
@@ -86,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() {
@@ -108,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) {
@@ -391,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.
@@ -500,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);
         })
@@ -576,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,18 +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;
@@ -117,7 +117,7 @@ function parseField(field, bounds, expression) {
                 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 {
@@ -131,7 +131,7 @@ function parseField(field, bounds, expression) {
         }
     }
     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;
 }
@@ -160,11 +160,11 @@ function resolveValue(raw, bounds, expression, rawDayOfWeek = false) {
         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}"`);
     }
     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);
+        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.2",
+  "version": "1.2.1",
   "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.2.0",
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/types": "1.1.1"
+    "@zudojs/errors": "1.3.1",
+    "@zudojs/constants": "1.1.3",
+    "@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"
   },