@daloyjs/core 0.36.0 → 0.37.0

package/dist/scheduler.d.ts

@@ -0,0 +1,315 @@
+/**
+ * In-process scheduled tasks (cron) for DaloyJS.
+ *
+ * A queue-agnostic schedule primitive — the in-process counterpart to an
+ * external job queue. Where a queue answers *“run this work somewhere,
+ * eventually”*, the {@link Scheduler} answers *“run this work in
+ * this process, on this clock”* — the three things a production
+ * in-process scheduler needs:
+ *
+ * - **Flexible schedules.** Fixed intervals (`intervalMs`) or 5-field cron
+ *   expressions (`cron`, with `@hourly`/`@daily`/… aliases and an optional
+ *   IANA `timeZone`), parsed once into a fast matcher with no backtracking
+ *   regex.
+ * - **Single-flight guarantees.** A task never overlaps itself: if a tick
+ *   fires while the previous run is still in progress, the tick is *skipped*
+ *   (and counted), so a slow task can never pile up unbounded concurrent runs.
+ * - **Graceful-shutdown integration.** {@link Scheduler.stop} clears every
+ *   timer and waits for in-flight runs to settle (up to a deadline, then
+ *   aborts their {@link AbortSignal}), so it slots cleanly into the app's
+ *   `onClose` drain. Timers are `unref`'d, so a scheduler never keeps an
+ *   otherwise-idle process alive on its own.
+ *
+ * Everything is built on Web-standard primitives (`AbortController`,
+ * `Intl.DateTimeFormat` for timezone wall-clock math, `setTimeout`), so it
+ * runs unchanged on Node, Bun, Deno, Cloudflare Workers, and Vercel Edge, with
+ * zero runtime dependencies. Pair it with {@link App.cron} for an app-managed
+ * scheduler whose lifecycle is tied to graceful shutdown, or drive a
+ * {@link Scheduler} directly.
+ *
+ * @example
+ * ```ts
+ * const scheduler = new Scheduler();
+ * scheduler.define({ name: "cleanup", cron: "0 * * * *" }, async ({ signal }) => {
+ *   await purgeExpiredSessions({ signal });
+ * });
+ * scheduler.start();
+ * // ... later, during shutdown:
+ * await scheduler.stop(5_000);
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+/**
+ * Thrown when a cron expression cannot be parsed, or describes a time that can
+ * never occur (for example `0 0 30 2 *` — the 30th of February).
+ *
+ * @since 0.37.0
+ */
+export declare class CronParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * A minimal structured logger, structurally compatible with the DaloyJS
+ * application logger. Only the levels the scheduler emits are required.
+ *
+ * @since 0.37.0
+ */
+export interface SchedulerLogger {
+    debug(obj: object | string, msg?: string): void;
+    info(obj: object | string, msg?: string): void;
+    warn(obj: object | string, msg?: string): void;
+    error(obj: object | string, msg?: string): void;
+}
+/**
+ * Pluggable timer primitives, injectable for deterministic testing. The
+ * default uses `setTimeout`/`clearTimeout` and `unref`s the handle so a
+ * pending tick never keeps an idle process alive.
+ *
+ * @since 0.37.0
+ */
+export interface TimerFns {
+    /** Schedule `callback` to run after `delayMs`, returning an opaque handle. */
+    set(callback: () => void, delayMs: number): unknown;
+    /** Cancel a previously scheduled timer by its handle. */
+    clear(handle: unknown): void;
+}
+/**
+ * Context handed to a task handler on each run.
+ *
+ * @since 0.37.0
+ */
+export interface TaskRunContext {
+    /** The task's unique name. */
+    readonly name: string;
+    /** The wall-clock time the run was scheduled for. */
+    readonly scheduledFor: Date;
+    /** Monotonically increasing run number for this task (1-based). */
+    readonly runCount: number;
+    /**
+     * Aborted when the per-run `timeoutMs` elapses, or when {@link Scheduler.stop}
+     * runs out of grace time. Well-behaved handlers should forward it to any
+     * I/O they perform so shutdown stays prompt.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * A handler invoked on each scheduled run.
+ *
+ * @since 0.37.0
+ */
+export type TaskHandler = (ctx: TaskRunContext) => void | Promise<void>;
+/**
+ * Information passed to a task's `onError` callback.
+ *
+ * @since 0.37.0
+ */
+export interface TaskErrorInfo {
+    /** The task's unique name. */
+    readonly name: string;
+    /** The run number that failed (1-based). */
+    readonly runCount: number;
+    /** `true` when the failure was the per-run timeout aborting the handler. */
+    readonly timedOut: boolean;
+}
+/**
+ * Definition of a single scheduled task. Exactly one of {@link intervalMs} or
+ * {@link cron} must be provided.
+ *
+ * @since 0.37.0
+ */
+export interface TaskDefinition {
+    /** Unique, non-empty task name. Used in logs and {@link Scheduler.getState}. */
+    name: string;
+    /**
+     * Fixed delay, in milliseconds, between the **start** of consecutive runs
+     * (fixed-rate cadence). Must be a positive integer. If a run outlasts the
+     * interval, the next tick is skipped (single-flight) rather than overlapping.
+     * Mutually exclusive with {@link cron}.
+     */
+    intervalMs?: number;
+    /**
+     * A 5-field cron expression (`minute hour day-of-month month day-of-week`)
+     * or a named alias (`@yearly`/`@annually`, `@monthly`, `@weekly`, `@daily`/
+     * `@midnight`, `@hourly`). Mutually exclusive with {@link intervalMs}.
+     */
+    cron?: string;
+    /**
+     * IANA timezone (e.g. `"America/New_York"`) the cron expression is evaluated
+     * in. Defaults to UTC. Ignored for interval schedules.
+     */
+    timeZone?: string;
+    /**
+     * Run the task once immediately when the scheduler starts, in addition to
+     * its normal schedule. Defaults to `false`.
+     */
+    runOnStart?: boolean;
+    /**
+     * Abort the run's {@link TaskRunContext.signal} after this many milliseconds.
+     * `0` (the default) disables the per-run timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Invoked when a run throws or times out. Errors are always logged; this
+     * hook is for custom handling (alerting, metrics). Exceptions thrown here
+     * are swallowed.
+     */
+    onError?: (error: unknown, info: TaskErrorInfo) => void;
+}
+/**
+ * Options for constructing a {@link Scheduler}.
+ *
+ * @since 0.37.0
+ */
+export interface SchedulerOptions {
+    /** Structured logger for scheduler lifecycle and task events. */
+    logger?: SchedulerLogger;
+    /** Injectable clock (milliseconds since epoch). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable timer primitives. Defaults to `unref`'d `setTimeout`. */
+    timers?: TimerFns;
+}
+/**
+ * A point-in-time snapshot of a task's execution statistics.
+ *
+ * @since 0.37.0
+ */
+export interface TaskState {
+    /** The task's unique name. */
+    readonly name: string;
+    /** Whether a run is currently in progress. */
+    readonly running: boolean;
+    /** Total completed runs (successful or failed). */
+    readonly runs: number;
+    /** Total failed runs (threw or timed out). */
+    readonly failures: number;
+    /** Ticks skipped because the previous run was still in progress. */
+    readonly skipped: number;
+    /** Epoch ms the most recent run started, or `undefined` if never run. */
+    readonly lastRunAt: number | undefined;
+    /** Wall-clock duration of the most recent completed run, in ms. */
+    readonly lastDurationMs: number | undefined;
+    /** The most recent run error, or `undefined`. */
+    readonly lastError: unknown;
+    /** Epoch ms the next run is scheduled for, or `undefined` if stopped. */
+    readonly nextRunAt: number | undefined;
+}
+/**
+ * A cron expression compiled into per-field membership sets. Each set lists
+ * the allowed numeric values for that field.
+ *
+ * @since 0.37.0
+ */
+export interface CronFields {
+    /** Allowed minutes (0–59). */
+    readonly minute: ReadonlySet<number>;
+    /** Allowed hours (0–23). */
+    readonly hour: ReadonlySet<number>;
+    /** Allowed days of month (1–31). */
+    readonly dayOfMonth: ReadonlySet<number>;
+    /** Allowed months (1–12). */
+    readonly month: ReadonlySet<number>;
+    /** Allowed days of week (0–6, Sunday = 0). */
+    readonly dayOfWeek: ReadonlySet<number>;
+    /** `true` when day-of-month was restricted (not `*`). */
+    readonly domRestricted: boolean;
+    /** `true` when day-of-week was restricted (not `*`). */
+    readonly dowRestricted: boolean;
+}
+/**
+ * Parse a 5-field cron expression (or a named alias) into a {@link CronFields}
+ * matcher.
+ *
+ * Supported syntax per field: `*`, lists (`1,2,3`), ranges (`1-5`), steps
+ * (`*\/5`, `1-10/2`), and case-insensitive month (`JAN`–`DEC`) / day
+ * (`SUN`–`SAT`) names. Day-of-week accepts both `0` and `7` for Sunday.
+ *
+ * @param expression - A cron expression or alias.
+ * @returns The compiled field sets.
+ * @throws {@link CronParseError} if the expression is malformed.
+ * @since 0.37.0
+ */
+export declare function parseCron(expression: string): CronFields;
+/**
+ * Compute the next instant (strictly after `after`) that a cron expression
+ * matches, evaluated in `timeZone` (UTC by default).
+ *
+ * @param expression - A compiled {@link CronFields} or a raw cron expression.
+ * @param after - The instant to search after. Defaults to now.
+ * @param timeZone - IANA timezone the expression is evaluated in.
+ * @returns The next matching `Date`.
+ * @throws {@link CronParseError} if no match occurs within five years
+ *   (an unsatisfiable expression).
+ * @since 0.37.0
+ */
+export declare function nextCronRun(expression: string | CronFields, after?: Date, timeZone?: string): Date;
+/**
+ * An in-process task scheduler with cron / interval schedules, single-flight
+ * overlap protection, and graceful shutdown. See the module overview for the
+ * design rationale.
+ *
+ * @since 0.37.0
+ */
+export declare class Scheduler {
+    #private;
+    constructor(options?: SchedulerOptions);
+    /** `true` once {@link start} has been called and {@link stop} has not. */
+    get running(): boolean;
+    /** The number of registered tasks. */
+    get size(): number;
+    /**
+     * Register a task. May be called before or after {@link start}; tasks added
+     * after start are scheduled immediately.
+     *
+     * @param def - The task definition. Exactly one of `intervalMs` / `cron`.
+     * @param handler - The function to run on each tick.
+     * @returns This scheduler, for chaining.
+     * @throws {RangeError} on invalid options (bad name, both/neither schedule,
+     *   non-positive interval, negative timeout, duplicate name).
+     * @throws {@link CronParseError} if a `cron` expression is malformed.
+     */
+    define(def: TaskDefinition, handler: TaskHandler): this;
+    /**
+     * Start the scheduler. Idempotent: a second call is a no-op. Each task is
+     * armed for its next run (or run immediately when `runOnStart` is set).
+     *
+     * @returns This scheduler, for chaining.
+     */
+    start(): this;
+    /**
+     * Stop the scheduler gracefully. Clears every pending timer so no new runs
+     * start, then waits up to `graceMs` for in-flight runs to finish; any run
+     * still going when the grace period elapses has its {@link AbortSignal}
+     * aborted. Idempotent.
+     *
+     * @param graceMs - Milliseconds to wait for in-flight runs. Defaults to 5000.
+     * @returns A promise that resolves once all runs have settled (or been
+     *   aborted and settled).
+     */
+    stop(graceMs?: number): Promise<void>;
+    /**
+     * Trigger a task immediately, out of band, respecting the single-flight
+     * guarantee (a manual run is skipped if the task is already running). The
+     * task's normal schedule is unaffected.
+     *
+     * @param name - The task name.
+     * @returns A promise that resolves when the manual run settles, with `true`
+     *   if it ran or `false` if it was skipped because a run was in progress.
+     * @throws {RangeError} if no task with that name exists.
+     */
+    runNow(name: string): Promise<boolean>;
+    /**
+     * Read a snapshot of a task's execution statistics.
+     *
+     * @param name - The task name.
+     * @returns The {@link TaskState}, or `undefined` if no such task exists.
+     */
+    getState(name: string): TaskState | undefined;
+    /**
+     * List execution-statistics snapshots for every registered task.
+     *
+     * @returns A snapshot array in definition order.
+     */
+    list(): readonly TaskState[];
+}