@zudojs/scheduler 0.0.1 → 1.0.0

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

@@ -1,11 +1,42 @@
+import type { JobExecution } from "./types/schedulerTypes.core.js";
 import type { JobDefinition } from "./job/jobDefinition.type.js";
+import type { Schedule } from "./schedule/schedule.type.js";
+import type { ScheduleOptions } from "./schedule/scheduleOptions.type.js";
 import type { ScheduleHandle } from "./scheduleHandle/scheduleHandle.type.js";
 import type { Clock } 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";
+/** Details reported to an error listener when a job fails. */
+export interface SchedulerErrorEvent {
+    readonly scheduleId: string;
+    readonly jobId: string;
+    readonly executionId: string;
+    readonly error: unknown;
+}
+/** Options accepted by {@link Scheduler}. */
+export interface SchedulerOptions {
+    readonly jobs?: JobRegistry;
+    readonly executor?: JobExecutor;
+    readonly queue?: PriorityQueue;
+    readonly clock?: Clock;
+    /** Maximum job executions in flight at once (default: 10). */
+    readonly maxConcurrency?: number;
+    /** Called when a job execution fails. */
+    readonly onError?: (event: SchedulerErrorEvent) => void;
+}
 /**
  * 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 declare class Scheduler {
     private readonly jobs;
@@ -13,17 +44,52 @@ export declare class Scheduler {
     private readonly queue;
     private readonly clock;
     private readonly schedules;
+    private readonly maxConcurrency;
+    private readonly onError;
+    /** Executions currently in flight, across all schedules. */
+    private readonly inFlight;
+    /**
+     * 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.
+     */
+    private readonly runningControllers;
+    /** Executions in flight per job id, for the per-job concurrency ceiling. */
+    private readonly runningByJob;
+    /** Records with `pendingRuns > 0`, drained as executions finish. */
+    private readonly pending;
+    /** Bounded ring of execution records, newest last. */
+    private readonly executionHistory;
     private running;
     private timer?;
-    constructor(jobs?: JobRegistry, executor?: JobExecutor, queue?: PriorityQueue, clock?: Clock);
+    /**
+     * @param options - Scheduler options, or a {@link JobRegistry} for the
+     *   positional form kept for backwards compatibility.
+     */
+    constructor(options?: SchedulerOptions | JobRegistry, executor?: JobExecutor, queue?: PriorityQueue, clock?: Clock);
+    /** Whether the scheduler is currently running. */
+    get isRunning(): boolean;
+    /** Number of live schedules. */
+    get scheduleCount(): number;
     /**
      * Starts the scheduler.
      */
     start(): void;
     /**
-     * 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(): void;
+    stop(options?: {
+        readonly drain?: boolean;
+        readonly timeoutMs?: number;
+    }): Promise<void>;
+    /** Waits for in-flight executions to finish, up to an optional timeout. */
+    private settle;
     /**
      * Defines a new job.
      */
@@ -31,34 +97,77 @@ export declare class Scheduler {
     /**
      * Schedules a job to run once after a delay.
      */
-    after(delay: string, jobId: string): ScheduleHandle;
+    after(delay: string, jobId: string, options?: ScheduleOptions): ScheduleHandle;
     /**
      * Schedules a job to run at a specific date.
      */
-    at(date: Date, jobId: string): ScheduleHandle;
+    at(date: Date, jobId: string, options?: ScheduleOptions): ScheduleHandle;
     /**
      * Schedules a job to run at a fixed interval.
      */
-    every(interval: string, jobId: string): ScheduleHandle;
+    every(interval: string, jobId: string, options?: ScheduleOptions): ScheduleHandle;
     /**
      * Schedules a job using a cron expression.
      */
-    cron(expression: string, jobId: string): ScheduleHandle;
+    cron(expression: string, jobId: string, options?: ScheduleOptions & {
+        readonly timezone?: string;
+    }): ScheduleHandle;
+    /** Returns a snapshot of a schedule, or undefined. */
+    getSchedule(scheduleId: string): Schedule | undefined;
+    /** Returns snapshots of every live schedule. */
+    listSchedules(): readonly Schedule[];
     /**
      * Schedules a job with a trigger.
      */
     private scheduleJob;
+    /** Applies a state change to a live schedule. */
+    private setScheduleState;
+    /** Aborts every in-flight execution of one schedule. */
+    private abortSchedule;
     /**
      * Internal tick method for processing due jobs.
      */
     private tick;
+    /** (Re)arms the tick timer for the next due schedule. */
+    private rearm;
     /**
-     * Calculates the delay until the next tick.
+     * 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.
      */
-    private calculateDelay;
+    private reschedule;
+    /** Starts one execution of a schedule and tracks it. */
+    private dispatch;
+    /** Holds a fire time back until capacity frees up. */
+    private defer;
+    /**
+     * 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.
+     */
+    private drainPending;
+    /** Records a started execution, evicting the oldest beyond the cap. */
+    private beginExecution;
+    /** Completes the record for an execution, if it is still in the history. */
+    private finishExecution;
     /**
-     * Executes a schedule.
+     * 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.
      */
-    private executeSchedule;
+    getExecutions(jobId?: string): readonly JobExecution[];
+    /** Hands an execution failure to the error listener. */
+    private reportError;
+    /**
+     * Calculates the delay until the next tick.
+     */
+    private calculateDelay;
 }
 //# sourceMappingURL=scheduler.core.d.ts.map