@zudojs/scheduler 0.1.0 → 1.0.0

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

@@ -1,8 +1,10 @@
 import { createJobContext } from "../job/jobContext.type.js";
-import { SchedulerJobExecutionError, SchedulerJobCancelledError, } from "../errors/scheduler.errors.js";
-import { DEFAULT_JOB_TIMEOUT } from "../constants/schedulerConstants.core.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";
+/** Marker attached to the rejection a timeout produces, carrying its budget. */
+const TIMEOUT = Symbol("scheduler.timeout");
 /**
- * Executes a job with timeout support.
+ * Executes a job with timeout, cancellation and retry support.
  */
 export class JobExecutor {
     clock;
@@ -10,41 +12,162 @@ export class JobExecutor {
         this.clock = clock;
     }
     /**
-     * Executes a job.
+     * Executes a job, retrying according to its retry policy.
+     *
+     * @param job - The job definition.
+     * @param executionId - Identifier for this execution.
+     * @param scheduledAt - The time the job was scheduled to run.
+     * @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.
+     * @returns The execution result.
      */
-    async execute(job, executionId, scheduledAt, attempt, signal) {
-        const timeout = job.options?.timeout ?? DEFAULT_JOB_TIMEOUT;
-        const context = createJobContext(job.id, executionId, scheduledAt, this.clock.now(), attempt, undefined, signal);
-        try {
-            await this.withTimeout(() => Promise.resolve(job.handler(context)), timeout, signal);
-            return { success: true };
-        }
-        catch (error) {
+    async execute(job, executionId, scheduledAt, attempt, signal, data) {
+        const retry = job.options?.retry;
+        const maxAttempts = Math.max(1, retry?.attempts ?? 1);
+        let currentAttempt = attempt;
+        let lastError;
+        for (let i = 0; i < maxAttempts; i++, currentAttempt++) {
             if (signal.aborted) {
                 throw new SchedulerJobCancelledError("Job was cancelled via signal.", job.id);
             }
-            throw new SchedulerJobExecutionError(error instanceof Error ? error.message : "Unknown job execution error.", job.id);
+            try {
+                await this.runOnce(job, executionId, scheduledAt, currentAttempt, signal, data);
+                return { success: true };
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    throw new SchedulerJobCancelledError("Job was cancelled via signal.", job.id);
+                }
+                lastError = this.classify(error, job.id);
+                // Last attempt, or nothing to retry with.
+                if (i === maxAttempts - 1)
+                    break;
+                const delay = retryDelay(retry, currentAttempt);
+                if (delay > 0) {
+                    await sleep(delay, signal);
+                }
+            }
+        }
+        throw (lastError ??
+            new SchedulerJobExecutionError("Unknown job execution error.", job.id));
+    }
+    /** 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 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.
+        const controller = new AbortController();
+        const onParentAbort = () => controller.abort(signal.reason);
+        if (signal.aborted) {
+            controller.abort(signal.reason);
         }
+        else {
+            signal.addEventListener("abort", onParentAbort, { once: true });
+        }
+        const context = createJobContext(job.id, executionId, scheduledAt, this.clock.now(), attempt, data, controller.signal);
+        try {
+            await this.withTimeout(() => Promise.resolve(job.handler(context)), timeout, controller);
+        }
+        finally {
+            signal.removeEventListener("abort", onParentAbort);
+        }
+    }
+    /** Maps a thrown value onto the scheduler's error taxonomy. */
+    classify(error, jobId) {
+        const budget = typeof error === "object" && error !== null
+            ? error[TIMEOUT]
+            : undefined;
+        if (typeof budget === "number") {
+            // SchedulerJobTimeoutError builds its own message from the budget.
+            return new SchedulerJobTimeoutError(budget, jobId);
+        }
+        if (error instanceof SchedulerJobCancelledError) {
+            return error;
+        }
+        // Carry the original error rather than flattening it to a message string,
+        // which used to discard the stack and any nested cause. The published
+        // error class takes no options bag, so the cause is attached directly.
+        const wrapped = new SchedulerJobExecutionError(error instanceof Error ? error.message : "Unknown job execution error.", jobId);
+        Object.defineProperty(wrapped, "cause", {
+            value: error,
+            writable: true,
+            enumerable: false,
+            configurable: true,
+        });
+        return wrapped;
     }
     /**
-     * Wraps a promise with a timeout using AbortSignal.
+     * Wraps an operation with a timeout that aborts it.
      */
-    async withTimeout(operation, timeout, signal) {
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                reject(new Error(`Job timed out after ${timeout}ms.`));
-            }, timeout);
-            Promise.resolve()
-                .then(() => Promise.resolve(operation()))
-                .then((result) => {
-                clearTimeout(timer);
-                resolve(result);
-            })
-                .catch((error) => {
-                clearTimeout(timer);
+    async withTimeout(operation, timeout, controller) {
+        let timer;
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                const error = new Error(`Job timed out after ${timeout}ms.`);
+                error[TIMEOUT] = timeout;
+                // Abort first so a handler that observes its signal can wind down.
+                controller.abort(error);
                 reject(error);
-            });
+            }, timeout);
+            if (timer.unref)
+                timer.unref();
         });
+        try {
+            return await Promise.race([operation(), timeoutPromise]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
     }
 }
+/**
+ * Computes the delay before the next retry attempt.
+ *
+ * `RetryPolicy` has carried strategy, delay, maxDelay and jitter since the
+ * package was written; none of it was ever applied.
+ */
+export function retryDelay(policy, attempt) {
+    if (!policy)
+        return 0;
+    const base = policy.delay ?? DEFAULT_RETRY_DELAY;
+    const attempts = Math.min(attempt, DEFAULT_MAX_RETRIES * 4);
+    let delay;
+    switch (policy.strategy) {
+        case "linear":
+            delay = base * attempts;
+            break;
+        case "exponential":
+            delay = base * Math.pow(2, Math.max(0, attempts - 1));
+            break;
+        case "fixed":
+        default:
+            delay = base;
+            break;
+    }
+    if (policy.maxDelay !== undefined) {
+        delay = Math.min(delay, policy.maxDelay);
+    }
+    if (policy.jitter) {
+        // Full jitter: spreads a thundering herd of retries across the window.
+        delay = Math.random() * delay;
+    }
+    return Math.max(0, Math.round(delay));
+}
+/** Sleeps, resolving early if the signal aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(finish, ms);
+        if (timer.unref)
+            timer.unref();
+        function finish() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        }
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
 //# sourceMappingURL=jobExecutor.core.js.map

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

@@ -3,9 +3,20 @@ import type { OverlapPolicy } from "../types/schedulerTypes.core.js";
  * Options for a scheduled job.
  */
 export interface JobOptions {
+    /** Per-execution timeout in ms. Default: 30 000. */
     readonly timeout?: number;
+    /** Retry policy applied to a failing execution. */
     readonly retry?: RetryPolicy;
+    /**
+     * Maximum executions of this job in flight at once, across every schedule
+     * that fires it. A fire time arriving at the ceiling is held and dispatched
+     * as soon as an execution finishes.
+     */
     readonly concurrency?: number;
+    /**
+     * Default overlap policy for every schedule of this job.
+     * `ScheduleOptions.overlap` overrides it.
+     */
     readonly overlap?: OverlapPolicy;
 }
 /**

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

@@ -2,6 +2,10 @@ import type { Schedule } from "../schedule/schedule.type.js";
 /**
  * Priority queue using a min heap for scheduling.
  *
+ * Ordered by fire time, with `ScheduleOptions.priority` breaking ties: a
+ * higher priority runs first among schedules due at the same instant. That
+ * option used to be documented as "reserved" and read by nothing at all.
+ *
  * Provides O(log n) insertion and removal, and O(1) peek.
  */
 export declare class PriorityQueue {
@@ -22,6 +26,8 @@ export declare class PriorityQueue {
      * Removes a schedule by ID.
      */
     remove(id: string): boolean;
+    /** Returns true when a schedule with the given id is queued. */
+    has(id: string): boolean;
     /**
      * Returns the number of schedules in the queue.
      */
@@ -34,6 +40,12 @@ export declare class PriorityQueue {
      * Clears all schedules from the queue.
      */
     clear(): void;
+    /**
+     * Orders two schedules: earlier fire time first, then higher priority.
+     *
+     * @returns A negative number when `a` should run before `b`.
+     */
+    private compare;
     /**
      * Bubble up an element to maintain heap property.
      */

package/dist/scheduler/priorityQueue/schedulerPriorityQueue.core.js

@@ -1,6 +1,10 @@
 /**
  * Priority queue using a min heap for scheduling.
  *
+ * Ordered by fire time, with `ScheduleOptions.priority` breaking ties: a
+ * higher priority runs first among schedules due at the same instant. That
+ * option used to be documented as "reserved" and read by nothing at all.
+ *
  * Provides O(log n) insertion and removal, and O(1) peek.
  */
 export class PriorityQueue {
@@ -9,6 +13,13 @@ export class PriorityQueue {
      * Inserts a schedule into the priority queue.
      */
     enqueue(schedule) {
+        const time = schedule.nextRunAt?.getTime();
+        if (typeof time !== "number" || Number.isNaN(time)) {
+            // Every heap comparison against NaN is false, so an invalid date never
+            // sinks: it parks itself at the head of the queue and blocks everything
+            // genuinely due behind it.
+            throw new RangeError(`Cannot enqueue schedule "${schedule.id}": nextRunAt is not a valid date`);
+        }
         this.heap.push(schedule);
         this.bubbleUp(this.heap.length - 1);
     }
@@ -47,11 +58,18 @@ export class PriorityQueue {
         const last = this.heap.pop();
         if (index < this.heap.length && last !== undefined) {
             this.heap[index] = last;
+            // Bubble first; if it moved, the element now at `index` is an ancestor
+            // of that subtree and cannot sink, so sinking is a no-op. If it did not
+            // move, sinking is the correction that is needed.
             this.bubbleUp(index);
             this.sinkDown(index);
         }
         return true;
     }
+    /** Returns true when a schedule with the given id is queued. */
+    has(id) {
+        return this.heap.some((schedule) => schedule.id === id);
+    }
     /**
      * Returns the number of schedules in the queue.
      */
@@ -70,6 +88,17 @@ export class PriorityQueue {
     clear() {
         this.heap.length = 0;
     }
+    /**
+     * Orders two schedules: earlier fire time first, then higher priority.
+     *
+     * @returns A negative number when `a` should run before `b`.
+     */
+    compare(a, b) {
+        const byTime = a.nextRunAt.getTime() - b.nextRunAt.getTime();
+        if (byTime !== 0)
+            return byTime;
+        return (b.options?.priority ?? 0) - (a.options?.priority ?? 0);
+    }
     /**
      * Bubble up an element to maintain heap property.
      */
@@ -78,7 +107,7 @@ export class PriorityQueue {
             const parentIndex = Math.floor((index - 1) / 2);
             const parent = this.heap[parentIndex];
             const current = this.heap[index];
-            if (current.nextRunAt.getTime() < parent.nextRunAt.getTime()) {
+            if (this.compare(current, parent) < 0) {
                 [this.heap[parentIndex], this.heap[index]] = [current, parent];
                 index = parentIndex;
             }
@@ -96,13 +125,11 @@ export class PriorityQueue {
             const left = 2 * index + 1;
             const right = 2 * index + 2;
             if (left < this.heap.length &&
-                this.heap[left].nextRunAt.getTime() <
-                    this.heap[smallest].nextRunAt.getTime()) {
+                this.compare(this.heap[left], this.heap[smallest]) < 0) {
                 smallest = left;
             }
             if (right < this.heap.length &&
-                this.heap[right].nextRunAt.getTime() <
-                    this.heap[smallest].nextRunAt.getTime()) {
+                this.compare(this.heap[right], this.heap[smallest]) < 0) {
                 smallest = right;
             }
             if (smallest !== index) {

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

@@ -12,6 +12,14 @@ export declare class JobRegistry {
      * Retrieves a job definition by ID.
      */
     get(id: string): JobDefinition | undefined;
+    /**
+     * Retrieves a job definition by ID, throwing when it is not registered.
+     *
+     * @param id - The job identifier.
+     * @returns The job definition.
+     * @throws {SchedulerJobNotFoundError} when no job is registered under `id`.
+     */
+    getOrThrow(id: string): JobDefinition;
     /**
      * Determines whether a job is registered.
      */

package/dist/scheduler/registry/jobRegistry.core.js

@@ -24,6 +24,20 @@ export class JobRegistry {
     get(id) {
         return this.jobs.get(id);
     }
+    /**
+     * Retrieves a job definition by ID, throwing when it is not registered.
+     *
+     * @param id - The job identifier.
+     * @returns The job definition.
+     * @throws {SchedulerJobNotFoundError} when no job is registered under `id`.
+     */
+    getOrThrow(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new SchedulerJobNotFoundError(id);
+        }
+        return job;
+    }
     /**
      * Determines whether a job is registered.
      */

package/dist/scheduler/schedule/schedule.type.d.ts

@@ -1,5 +1,6 @@
 import type { ScheduleOptions } from "./scheduleOptions.type.js";
-import type { ScheduleState } from "../types/schedulerTypes.core.js";
+import type { ScheduleState, ScheduleType } from "../types/schedulerTypes.core.js";
+export type { ScheduleType };
 /**
  * Schedule definition.
  */
@@ -13,12 +14,16 @@ export interface Schedule {
     readonly state: ScheduleState;
     readonly options?: ScheduleOptions;
 }
-/**
- * Type of schedule.
- */
-export type ScheduleType = "once" | "delay" | "interval" | "cron";
 /**
  * Creates a schedule.
+ *
+ * @param id - Schedule identifier.
+ * @param jobId - The job this schedule fires.
+ * @param type - The kind of schedule.
+ * @param nextRunAt - The first fire time.
+ * @param options - Schedule options.
+ * @param expression - The cron expression, for cron schedules.
+ * @returns A frozen, active schedule.
  */
-export declare function createSchedule(id: string, jobId: string, type: ScheduleType, nextRunAt: Date, options?: ScheduleOptions): Schedule;
+export declare function createSchedule(id: string, jobId: string, type: ScheduleType, nextRunAt: Date, options?: ScheduleOptions, expression?: string): Schedule;
 //# sourceMappingURL=schedule.type.d.ts.map

package/dist/scheduler/schedule/schedule.type.js

@@ -1,7 +1,15 @@
 /**
  * Creates a schedule.
+ *
+ * @param id - Schedule identifier.
+ * @param jobId - The job this schedule fires.
+ * @param type - The kind of schedule.
+ * @param nextRunAt - The first fire time.
+ * @param options - Schedule options.
+ * @param expression - The cron expression, for cron schedules.
+ * @returns A frozen, active schedule.
  */
-export function createSchedule(id, jobId, type, nextRunAt, options = {}) {
+export function createSchedule(id, jobId, type, nextRunAt, options = {}, expression) {
     return Object.freeze({
         id,
         jobId,
@@ -9,6 +17,7 @@ export function createSchedule(id, jobId, type, nextRunAt, options = {}) {
         nextRunAt,
         state: "active",
         options: Object.freeze(options),
+        ...(expression === undefined ? {} : { expression }),
     });
 }
 //# sourceMappingURL=schedule.type.js.map

package/dist/scheduler/schedule/scheduleOptions.type.d.ts

@@ -1,10 +1,33 @@
-import type { MisfirePolicy } from "../types/schedulerTypes.core.js";
+import type { MisfirePolicy, OverlapPolicy } from "../types/schedulerTypes.core.js";
 /**
  * Options for a schedule.
  */
 export interface ScheduleOptions {
+    /** IANA timezone name. Only "UTC" is currently honoured by CronTrigger. */
     readonly timezone?: string;
+    /**
+     * How to handle a fire time that has already passed (default: "run-once").
+     *
+     * `"skip"` refuses the schedule, `"run-once"` fires once immediately and
+     * then resumes from now, and `"catch-up"` replays every occurrence that was
+     * missed, one per tick, until the schedule has caught up with the clock.
+     */
     readonly misfire?: MisfirePolicy;
+    /**
+     * How to handle a fire time arriving while a previous run is still going.
+     *
+     * `"allow"` (default) starts it anyway, `"skip"` drops it, `"queue"` holds
+     * it until the running execution finishes, and `"replace"` aborts the
+     * running execution. Overrides `JobOptions.overlap` for this schedule.
+     */
+    readonly overlap?: OverlapPolicy;
+    /**
+     * Relative priority, breaking ties between schedules due at the same
+     * instant. Higher runs first; the default is 0. It does not let a schedule
+     * jump ahead of one that is due earlier.
+     */
     readonly priority?: number;
+    /** Payload handed to the job handler as `context.data`. */
+    readonly data?: unknown;
 }
 //# sourceMappingURL=scheduleOptions.type.d.ts.map

package/dist/scheduler/scheduleHandle/index.d.ts

@@ -1,3 +1,4 @@
 export type { ScheduleHandle } from "./scheduleHandle.type.js";
 export { ScheduleHandleImpl } from "./scheduleHandle.type.js";
+export type { ScheduleHandleBinding } from "./scheduleHandle.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scheduler/scheduleHandle/scheduleHandle.type.d.ts

@@ -10,14 +10,37 @@ export interface ScheduleHandle {
     cancel(): Promise<void>;
     nextRun(): Date | undefined;
 }
+/**
+ * The scheduler operations a handle needs to act on its schedule.
+ *
+ * Without these the handle is a detached object: `cancel()` sets a local field
+ * and the job still runs.
+ */
+export interface ScheduleHandleBinding {
+    /** Applies a state transition to the live schedule. */
+    setState(state: ScheduleState): void;
+    /** Reads the live schedule's state, or undefined once it is gone. */
+    getState(): ScheduleState | undefined;
+    /** Reads the live schedule's next fire time. */
+    getNextRun(): Date | undefined;
+    /** Aborts any execution of this schedule that is currently in flight. */
+    abortRunning(): void;
+}
 /**
  * Implementation of ScheduleHandle.
+ *
+ * Bound to its scheduler, so pause, resume and cancel reach the queue. An
+ * unbound handle (the two-argument form) still tracks state locally, which
+ * keeps it usable in tests that do not involve a scheduler.
  */
 export declare class ScheduleHandleImpl implements ScheduleHandle {
     readonly id: string;
-    state: ScheduleState;
-    private cancelled;
-    constructor(id: string, state: ScheduleState);
+    private _state;
+    private readonly binding;
+    constructor(id: string, state: ScheduleState, binding?: ScheduleHandleBinding);
+    /** The schedule's current state, read from the scheduler when bound. */
+    get state(): ScheduleState;
+    set state(next: ScheduleState);
     pause(): Promise<void>;
     resume(): Promise<void>;
     cancel(): Promise<void>;

package/dist/scheduler/scheduleHandle/scheduleHandle.type.js

@@ -1,13 +1,26 @@
 /**
  * Implementation of ScheduleHandle.
+ *
+ * Bound to its scheduler, so pause, resume and cancel reach the queue. An
+ * unbound handle (the two-argument form) still tracks state locally, which
+ * keeps it usable in tests that do not involve a scheduler.
  */
 export class ScheduleHandleImpl {
     id;
-    state;
-    cancelled = false;
-    constructor(id, state) {
+    _state;
+    binding;
+    constructor(id, state, binding) {
         this.id = id;
-        this.state = state;
+        this._state = state;
+        this.binding = binding;
+    }
+    /** The schedule's current state, read from the scheduler when bound. */
+    get state() {
+        return this.binding?.getState() ?? this._state;
+    }
+    set state(next) {
+        this._state = next;
+        this.binding?.setState(next);
     }
     pause() {
         this.state = "paused";
@@ -18,12 +31,15 @@ export class ScheduleHandleImpl {
         return Promise.resolve();
     }
     cancel() {
-        this.cancelled = true;
-        this.state = "cancelled";
+        // Abort first: a job already running should stop, not just be removed from
+        // future scheduling.
+        this.binding?.abortRunning();
+        this._state = "cancelled";
+        this.binding?.setState("cancelled");
         return Promise.resolve();
     }
     nextRun() {
-        return undefined;
+        return this.binding?.getNextRun();
     }
 }
 //# sourceMappingURL=scheduleHandle.type.js.map