@zudojs/scheduler 0.1.0 → 1.0.0

package/dist/scheduler/scheduler.core.js

@@ -1,14 +1,31 @@
 import { ScheduleHandleImpl } from "./scheduleHandle/scheduleHandle.type.js";
-import { SchedulerError, SchedulerNotStartedError, SchedulerAlreadyStartedError, SchedulerStoppedError, InvalidScheduleError, InvalidJobError, } from "./errors/scheduler.errors.js";
+import { createSchedule } from "./schedule/schedule.type.js";
+import { SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobCancelledError, 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";
 import { JobExecutor } from "./executor/jobExecutor.core.js";
 import { PriorityQueue } from "./priorityQueue/schedulerPriorityQueue.core.js";
 import { parseDuration } from "./duration/duration.parser.js";
-import { MAX_SCHEDULES, MAX_TIMER_DELAY, } from "./constants/schedulerConstants.core.js";
+import { MAX_SCHEDULES, MAX_TIMER_DELAY, MAX_EXECUTION_HISTORY, DEFAULT_MAX_CONCURRENCY, DEFAULT_MISFIRE_POLICY, DEFAULT_OVERLAP_POLICY, } from "./constants/schedulerConstants.core.js";
+/**
+ * Ceiling on fire times held back by `overlap: "queue"` or a job concurrency
+ * limit. Without one, a schedule whose job never keeps up would grow an
+ * unbounded backlog of runs nobody wants any more.
+ */
+const MAX_PENDING_RUNS = 1024;
 /**
  * Scheduler for time-based job execution.
+ *
+ * @example
+ * ```ts
+ * const scheduler = new Scheduler({ onError: (e) => log.error(e) });
+ * scheduler.define({ id: "cleanup", name: "Cleanup", handler: run });
+ * scheduler.every("5m", "cleanup");
+ * scheduler.start();
+ * // …later
+ * await scheduler.stop();
+ * ```
  */
 export class Scheduler {
     jobs;
@@ -16,13 +33,51 @@ export class Scheduler {
     queue;
     clock;
     schedules = new Map();
+    maxConcurrency;
+    onError;
+    /** Executions currently in flight, across all schedules. */
+    inFlight = new Set();
+    /**
+     * Abort controllers for every in-flight execution.
+     *
+     * Tracked here as well as on the schedule record: a one-shot schedule is
+     * retired as soon as it is dispatched, so by the time `stop()` runs its
+     * record is already gone and a per-record set alone would have nothing left
+     * to abort.
+     */
+    runningControllers = new Set();
+    /** Executions in flight per job id, for the per-job concurrency ceiling. */
+    runningByJob = new Map();
+    /** Records with `pendingRuns > 0`, drained as executions finish. */
+    pending = new Set();
+    /** Bounded ring of execution records, newest last. */
+    executionHistory = [];
     running = false;
     timer;
-    constructor(jobs, executor, queue, clock) {
-        this.jobs = jobs ?? new JobRegistry();
-        this.executor = executor ?? new JobExecutor(clock ?? new SystemClock());
-        this.queue = queue ?? new PriorityQueue();
-        this.clock = clock ?? new SystemClock();
+    /**
+     * @param options - Scheduler options, or a {@link JobRegistry} for the
+     *   positional form kept for backwards compatibility.
+     */
+    constructor(options, executor, queue, clock) {
+        const opts = options instanceof JobRegistry
+            ? { jobs: options, executor, queue, clock }
+            : (options ?? {});
+        // Resolve the clock once and share it. Building a second SystemClock for
+        // the executor meant a custom clock reached only one of the two.
+        this.clock = opts.clock ?? new SystemClock();
+        this.jobs = opts.jobs ?? new JobRegistry();
+        this.executor = opts.executor ?? new JobExecutor(this.clock);
+        this.queue = opts.queue ?? new PriorityQueue();
+        this.maxConcurrency = opts.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+        this.onError = opts.onError;
+    }
+    /** Whether the scheduler is currently running. */
+    get isRunning() {
+        return this.running;
+    }
+    /** Number of live schedules. */
+    get scheduleCount() {
+        return this.schedules.size;
     }
     /**
      * Starts the scheduler.
@@ -35,9 +90,12 @@ export class Scheduler {
         this.tick();
     }
     /**
-     * Stops the scheduler.
+     * Stops the scheduler, aborting in-flight jobs and waiting for them to settle.
+     *
+     * @param options - `drain` waits for running jobs to finish instead of
+     *   aborting them; `timeoutMs` bounds the wait either way.
      */
-    stop() {
+    async stop(options) {
         if (!this.running) {
             throw new SchedulerStoppedError();
         }
@@ -46,66 +104,170 @@ export class Scheduler {
             clearTimeout(this.timer);
             this.timer = undefined;
         }
+        if (options?.drain !== true) {
+            // Abort every in-flight execution. Previously the AbortController was
+            // created and immediately discarded, so nothing could ever be cancelled.
+            for (const controller of this.runningControllers) {
+                controller.abort(new Error("Scheduler stopped"));
+            }
+            // Runs held back by overlap or a concurrency ceiling are discarded with
+            // them; keeping them would fire on a later start for a time long past.
+            for (const record of this.pending)
+                record.pendingRuns = 0;
+            this.pending.clear();
+        }
+        await this.settle(options?.timeoutMs);
+    }
+    /** Waits for in-flight executions to finish, up to an optional timeout. */
+    async settle(timeoutMs) {
+        if (this.inFlight.size === 0)
+            return;
+        const all = Promise.allSettled([...this.inFlight]).then(() => undefined);
+        if (timeoutMs === undefined) {
+            await all;
+            return;
+        }
+        await Promise.race([
+            all,
+            new Promise((resolve) => {
+                const timer = setTimeout(resolve, timeoutMs);
+                if (timer.unref)
+                    timer.unref();
+            }),
+        ]);
     }
     /**
      * Defines a new job.
      */
     define(job) {
+        if (typeof job?.id !== "string" || job.id.trim().length === 0) {
+            throw new InvalidJobError("Job definition requires a non-empty string id.", String(job?.id));
+        }
+        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);
+        }
         this.jobs.register(job);
     }
     /**
      * Schedules a job to run once after a delay.
      */
-    after(delay, jobId) {
+    after(delay, jobId, options) {
         const delayMs = parseDuration(delay);
-        const trigger = new DelayTrigger(delayMs);
-        return this.scheduleJob(jobId, trigger, "delay");
+        return this.scheduleJob(jobId, new DelayTrigger(delayMs), "delay", options);
     }
     /**
      * Schedules a job to run at a specific date.
      */
-    at(date, jobId) {
-        const trigger = new DateTrigger(date);
-        return this.scheduleJob(jobId, trigger, "once");
+    at(date, jobId, options) {
+        return this.scheduleJob(jobId, new DateTrigger(date), "once", options);
     }
     /**
      * Schedules a job to run at a fixed interval.
      */
-    every(interval, jobId) {
+    every(interval, jobId, options) {
         const intervalMs = parseDuration(interval);
-        const trigger = new IntervalTrigger(intervalMs);
-        return this.scheduleJob(jobId, trigger, "interval");
+        return this.scheduleJob(jobId, new IntervalTrigger(intervalMs), "interval", options);
     }
     /**
      * Schedules a job using a cron expression.
      */
-    cron(expression, jobId) {
-        const trigger = new CronTrigger(expression);
-        return this.scheduleJob(jobId, trigger, "cron", { expression });
+    cron(expression, jobId, options) {
+        const trigger = new CronTrigger(expression, options?.timezone);
+        return this.scheduleJob(jobId, trigger, "cron", options, expression);
+    }
+    /** Returns a snapshot of a schedule, or undefined. */
+    getSchedule(scheduleId) {
+        return this.schedules.get(scheduleId)?.schedule;
+    }
+    /** Returns snapshots of every live schedule. */
+    listSchedules() {
+        return [...this.schedules.values()].map((record) => record.schedule);
     }
     /**
      * Schedules a job with a trigger.
      */
-    scheduleJob(jobId, trigger, type, options) {
+    scheduleJob(jobId, trigger, type, options, expression) {
         if (!this.jobs.has(jobId)) {
             throw new InvalidJobError(`Job "${jobId}" is not registered.`, jobId);
         }
+        if (this.schedules.size >= MAX_SCHEDULES) {
+            throw new InvalidScheduleError(`Maximum number of schedules (${MAX_SCHEDULES}) exceeded.`, jobId);
+        }
         const scheduleId = crypto.randomUUID();
-        const nextRunAt = trigger.next(this.clock.now());
+        const now = this.clock.now();
+        let nextRunAt = trigger.next(now);
         if (nextRunAt === null) {
-            throw new InvalidScheduleError("Trigger returned null for next run.", scheduleId);
-        }
-        const schedule = {
-            id: scheduleId,
-            jobId,
-            type,
-            expression: options?.expression,
-            nextRunAt,
-            state: "active",
+            // The fire time has already passed. That is the misfire case, not an
+            // error — `at(pastDate)` and a schedule restored after a restart both
+            // land here.
+            const misfire = options?.misfire ?? DEFAULT_MISFIRE_POLICY;
+            if (misfire === "skip") {
+                throw new InvalidScheduleError("Trigger has no future fire time and the misfire policy is 'skip'.", scheduleId);
+            }
+            // "run-once" and "catch-up" both start by running immediately.
+            nextRunAt = now;
+        }
+        if (Number.isNaN(nextRunAt.getTime())) {
+            throw new InvalidScheduleError("Trigger produced an invalid date.", scheduleId);
+        }
+        const schedule = createSchedule(scheduleId, jobId, type, nextRunAt, options ?? {}, expression);
+        const record = {
+            schedule,
+            trigger,
+            options: options ?? {},
+            running: new Set(),
+            pendingRuns: 0,
         };
-        this.schedules.set(scheduleId, schedule);
+        this.schedules.set(scheduleId, record);
         this.queue.enqueue(schedule);
-        return new ScheduleHandleImpl(scheduleId, "active");
+        // 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,
+            getNextRun: () => this.schedules.get(scheduleId)?.schedule.nextRunAt,
+            abortRunning: () => this.abortSchedule(scheduleId),
+        });
+    }
+    /** Applies a state change to a live schedule. */
+    setScheduleState(scheduleId, state) {
+        const record = this.schedules.get(scheduleId);
+        if (!record)
+            return;
+        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);
+        }
+        else if (state === "paused") {
+            this.queue.remove(scheduleId);
+        }
+        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();
+            }
+        }
+    }
+    /** Aborts every in-flight execution of one schedule. */
+    abortSchedule(scheduleId) {
+        const record = this.schedules.get(scheduleId);
+        if (!record)
+            return;
+        for (const controller of record.running) {
+            controller.abort(new Error("Schedule cancelled"));
+        }
     }
     /**
      * Internal tick method for processing due jobs.
@@ -121,13 +283,231 @@ export class Scheduler {
                 break;
             }
             this.queue.dequeue();
-            if (schedule.state !== "active") {
+            const record = this.schedules.get(schedule.id);
+            if (!record || record.schedule.state !== "active") {
                 continue;
             }
-            this.executeSchedule(schedule);
+            // Concurrency ceiling: without one, N due schedules start N executions
+            // at once. Anything over the ceiling is left for the next tick.
+            if (this.inFlight.size >= this.maxConcurrency) {
+                this.queue.enqueue(record.schedule);
+                break;
+            }
+            this.dispatch(record);
+            this.reschedule(record);
         }
+        this.rearm();
+    }
+    /** (Re)arms the tick timer for the next due schedule. */
+    rearm() {
+        if (!this.running)
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
         const delay = this.calculateDelay();
         this.timer = setTimeout(() => this.tick(), delay);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    /**
+     * Computes the next fire time and puts the schedule back on the queue.
+     *
+     * Nothing did this before, so `every()` and `cron()` fired exactly once and
+     * then sat in the map forever.
+     */
+    reschedule(record) {
+        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);
+            return;
+        }
+        // "catch-up" advances from the fire time that just ran, so a schedule
+        // that fell behind replays each missed occurrence instead of silently
+        // skipping to the next future one. Every other policy resumes from now.
+        const misfire = record.options.misfire ?? DEFAULT_MISFIRE_POLICY;
+        const now = this.clock.now();
+        const from = misfire === "catch-up" ? record.schedule.nextRunAt : now;
+        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);
+            return;
+        }
+        record.schedule = {
+            ...record.schedule,
+            nextRunAt: next,
+            lastRunAt: now,
+        };
+        this.queue.enqueue(record.schedule);
+    }
+    /** Starts one execution of a schedule and tracks it. */
+    dispatch(record) {
+        const job = this.jobs.get(record.schedule.jobId);
+        if (!job)
+            return;
+        // A schedule cancelled or paused while a run was held back must not fire.
+        if (record.schedule.state === "cancelled" ||
+            record.schedule.state === "paused") {
+            return;
+        }
+        // A schedule's own policy wins over the job's default.
+        const overlap = record.options.overlap ?? job.options?.overlap ?? DEFAULT_OVERLAP_POLICY;
+        if (record.running.size > 0) {
+            if (overlap === "skip")
+                return;
+            if (overlap === "queue") {
+                // Hold the fire time rather than dropping it; it is dispatched when
+                // the running execution finishes. "queue" used to fall through to
+                // "allow" and start a concurrent run.
+                this.defer(record);
+                return;
+            }
+            if (overlap === "replace") {
+                for (const controller of record.running) {
+                    controller.abort(new Error("Superseded by a newer execution"));
+                }
+            }
+        }
+        // Per-job concurrency ceiling. `JobOptions.concurrency` was accepted and
+        // read by nothing, so a job declaring `concurrency: 1` still ran as many
+        // executions at once as it had due schedules.
+        const concurrency = job.options?.concurrency;
+        if (concurrency !== undefined &&
+            (this.runningByJob.get(job.id) ?? 0) >= Math.max(1, concurrency)) {
+            this.defer(record);
+            return;
+        }
+        const executionId = crypto.randomUUID();
+        const controller = new AbortController();
+        record.running.add(controller);
+        this.runningControllers.add(controller);
+        this.runningByJob.set(job.id, (this.runningByJob.get(job.id) ?? 0) + 1);
+        const scheduleId = record.schedule.id;
+        const scheduledAt = record.schedule.nextRunAt;
+        const startedAt = this.clock.now();
+        this.beginExecution({
+            id: executionId,
+            jobId: job.id,
+            scheduleId,
+            status: "running",
+            scheduledAt,
+            startedAt,
+            attempt: 1,
+        });
+        const execution = this.executor
+            .execute(job, executionId, scheduledAt, 1, controller.signal, record.options.data)
+            .then(() => {
+            this.finishExecution(executionId, "completed", startedAt);
+        })
+            .catch((error) => {
+            this.finishExecution(executionId, statusFor(error), startedAt, error);
+            // A failure used to vanish into an empty catch block with a "retry
+            // logic would go here" comment. Retries now live in the executor, and
+            // whatever survives them is reported.
+            this.reportError({
+                scheduleId,
+                jobId: job.id,
+                executionId,
+                error,
+            });
+        })
+            .finally(() => {
+            record.running.delete(controller);
+            this.runningControllers.delete(controller);
+            this.inFlight.delete(execution);
+            const remaining = (this.runningByJob.get(job.id) ?? 1) - 1;
+            if (remaining <= 0)
+                this.runningByJob.delete(job.id);
+            else
+                this.runningByJob.set(job.id, remaining);
+            this.drainPending();
+        });
+        this.inFlight.add(execution);
+    }
+    /** Holds a fire time back until capacity frees up. */
+    defer(record) {
+        if (record.pendingRuns >= MAX_PENDING_RUNS)
+            return;
+        record.pendingRuns += 1;
+        this.pending.add(record);
+    }
+    /**
+     * Dispatches held-back runs that can now proceed.
+     *
+     * A record that is still blocked re-defers itself, which shows up as its
+     * counter returning to where it started; that is the loop's exit condition,
+     * so a blocked record cannot spin.
+     */
+    drainPending() {
+        if (!this.running || this.pending.size === 0)
+            return;
+        for (const record of [...this.pending]) {
+            while (record.pendingRuns > 0) {
+                if (this.inFlight.size >= this.maxConcurrency)
+                    return;
+                const before = record.pendingRuns;
+                record.pendingRuns -= 1;
+                this.dispatch(record);
+                if (record.pendingRuns >= before)
+                    break;
+            }
+            if (record.pendingRuns === 0)
+                this.pending.delete(record);
+        }
+    }
+    /** Records a started execution, evicting the oldest beyond the cap. */
+    beginExecution(execution) {
+        this.executionHistory.push(execution);
+        while (this.executionHistory.length > MAX_EXECUTION_HISTORY) {
+            this.executionHistory.shift();
+        }
+    }
+    /** 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);
+        if (index === -1)
+            return;
+        const completedAt = this.clock.now();
+        this.executionHistory[index] = {
+            ...this.executionHistory[index],
+            status,
+            completedAt,
+            duration: completedAt.getTime() - startedAt.getTime(),
+            ...(error === undefined ? {} : { error }),
+        };
+    }
+    /**
+     * Returns the recorded executions, oldest first.
+     *
+     * At most {@link MAX_EXECUTION_HISTORY} are kept. `JobExecution` and that
+     * constant were both exported from the beginning and nothing produced or
+     * read either.
+     *
+     * @param jobId - Restrict to one job's executions.
+     */
+    getExecutions(jobId) {
+        const all = [...this.executionHistory];
+        return jobId === undefined
+            ? all
+            : all.filter((execution) => execution.jobId === jobId);
+    }
+    /** Hands an execution failure to the error listener. */
+    reportError(event) {
+        if (!this.onError)
+            return;
+        try {
+            this.onError(event);
+        }
+        catch {
+            // A throwing error listener must not take the scheduler down with it.
+        }
     }
     /**
      * Calculates the delay until the next tick.
@@ -143,22 +523,13 @@ export class Scheduler {
         const delay = next.nextRunAt.getTime() - this.clock.nowMs();
         return Math.max(0, Math.min(delay, MAX_TIMER_DELAY));
     }
-    /**
-     * Executes a schedule.
-     */
-    async executeSchedule(schedule) {
-        const job = this.jobs.get(schedule.jobId);
-        if (!job) {
-            return;
-        }
-        const executionId = crypto.randomUUID();
-        const signal = new AbortController().signal;
-        try {
-            await this.executor.execute(job, executionId, schedule.nextRunAt, 1, signal);
-        }
-        catch (error) {
-            // Job execution failed - retry logic would go here
-        }
-    }
+}
+/** Maps a failed execution onto the job state that describes it. */
+function statusFor(error) {
+    if (error instanceof SchedulerJobTimeoutError)
+        return "timed_out";
+    if (error instanceof SchedulerJobCancelledError)
+        return "cancelled";
+    return "failed";
 }
 //# sourceMappingURL=scheduler.core.js.map

package/dist/scheduler/trigger/cron.parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @zudojs/scheduler/trigger/cron
+ *
+ * Standard five-field cron expression parsing and next-fire computation.
+ *
+ * Fields, in order: minute, hour, day-of-month, month, day-of-week.
+ * Each supports `*`, a value, a `a-b` range, a `a-b/n` or `*\/n` step, and a
+ * comma-separated list of any of those. Month and day-of-week also accept the
+ * usual three-letter names. A leading `@yearly`-style macro is expanded first.
+ */
+/** A parsed cron expression: the permitted values for each field. */
+export interface ParsedCron {
+    readonly minute: ReadonlySet<number>;
+    readonly hour: ReadonlySet<number>;
+    readonly dayOfMonth: ReadonlySet<number>;
+    readonly month: ReadonlySet<number>;
+    readonly dayOfWeek: ReadonlySet<number>;
+    /** True when day-of-month was `*`, which changes how the two day fields combine. */
+    readonly dayOfMonthUnrestricted: boolean;
+    /** True when day-of-week was `*`. */
+    readonly dayOfWeekUnrestricted: boolean;
+}
+/**
+ * Parses a cron expression into the set of values each field permits.
+ *
+ * @param expression - A five-field cron expression or a supported macro.
+ * @returns The parsed expression.
+ * @throws {CronParseError} when the expression is not valid.
+ */
+export declare function parseCron(expression: string): ParsedCron;
+/**
+ * Computes the next time a parsed cron expression fires, strictly after `after`.
+ *
+ * Search is minute-by-minute with whole-field skips, bounded by
+ * {@link MAX_SEARCH_YEARS} so an unsatisfiable expression (30 February) fails
+ * rather than looping.
+ *
+ * @param parsed - The parsed expression.
+ * @param after - The instant to search forward from (exclusive).
+ * @param utc - Interpret the fields in UTC rather than local time.
+ * @returns The next fire time, or null when none exists within the horizon.
+ */
+export declare function nextCronDate(parsed: ParsedCron, after: Date, utc?: boolean): Date | null;
+//# sourceMappingURL=cron.parser.d.ts.map