@pristine-ts/local-scheduling 4.0.2

package/dist/types/errors/invalid-cron-expression.error.d.ts

@@ -0,0 +1,20 @@
+import { BadRequestError } from "@pristine-ts/common";
+/**
+ * Thrown when a cron expression cannot be parsed or is semantically invalid.
+ *
+ * It extends {@link BadRequestError} so that, if it propagates to an HTTP boundary (for
+ * example a controller that validates a user-submitted schedule), the framework's HTTP
+ * responder surfaces it as a **400 Bad Request** automatically. The `message` is written
+ * to be safe and precise enough to return verbatim to the caller, and the offending
+ * `expression` (plus optional field context) is carried in the error `details` bag.
+ */
+export declare class InvalidCronExpressionError extends BadRequestError {
+    readonly expression: string;
+    readonly field?: string | undefined;
+    /**
+     * @param message A precise, caller-safe description of what is wrong with the expression.
+     * @param expression The raw cron expression that failed to parse.
+     * @param field The name of the offending field (e.g. `"minute"`), when known.
+     */
+    constructor(message: string, expression: string, field?: string | undefined);
+}

package/dist/types/errors/schedule-already-exists.error.d.ts

@@ -0,0 +1,15 @@
+import { ConflictError } from "@pristine-ts/common";
+/**
+ * Thrown by `schedule(id, ...)` when the id is already registered. Registration is
+ * intentionally not idempotent so that a duplicate id — almost always a bug in the
+ * consumer's bootstrap — surfaces loudly instead of silently double-arming a timer. To
+ * replace an existing schedule, call `unschedule(id)` first, or `reschedule(id, ...)` to
+ * only change its expression.
+ *
+ * It extends {@link ConflictError} so it surfaces as a **409 Conflict** if it reaches an
+ * HTTP boundary.
+ */
+export declare class ScheduleAlreadyExistsError extends ConflictError {
+    readonly id: string;
+    constructor(id: string);
+}

package/dist/types/errors/schedule-not-found.error.d.ts

@@ -0,0 +1,12 @@
+import { NotFoundError } from "@pristine-ts/common";
+/**
+ * Thrown when an operation references a schedule id that is not registered (for example
+ * `reschedule(id, ...)` or `getNextExecutionDate(id)` on an unknown id).
+ *
+ * It extends {@link NotFoundError} so it surfaces as a **404 Not Found** if it reaches an
+ * HTTP boundary — convenient when a controller mutates schedules by id.
+ */
+export declare class ScheduleNotFoundError extends NotFoundError {
+    readonly id: string;
+    constructor(id: string);
+}

package/dist/types/interfaces/interfaces.d.ts

@@ -0,0 +1,5 @@
+export * from "./local-scheduler.interface";
+export * from "./schedulable.interface";
+export * from "./schedule.interface";
+export * from "./schedule-descriptor.interface";
+export * from "./schedule-options.interface";

package/dist/types/interfaces/local-scheduler.interface.d.ts

@@ -0,0 +1,57 @@
+import { ScheduleInterface } from "./schedule.interface";
+import { ScheduledTaskFunction } from "../types/scheduled-task-function.type";
+import { ScheduleOptions } from "./schedule-options.interface";
+import { ScheduleDescriptor } from "./schedule-descriptor.interface";
+/**
+ * The contract implemented by {@link LocalSchedulerManager}. Depend on this interface (via the
+ * `"LocalSchedulerInterface"` injection token) when you want the scheduler mockable.
+ *
+ * Schedules come from two places that share one id space: statically-tagged
+ * {@link SchedulableInterface} tasks (auto-registered on `start()`), and the dynamic methods
+ * below — ordinary runtime state, typically loaded from a database at bootstrap and mutated by
+ * HTTP controllers. Schedules may be registered before `start()`; they arm when it is called.
+ */
+export interface LocalSchedulerInterface {
+    /** Whether the scheduler is currently started (armed). */
+    readonly isStarted: boolean;
+    /**
+     * Registers a task under `id`, run on `schedule` — a {@link ScheduleInterface} (e.g. a
+     * {@link CronSchedule} or {@link DateSchedule}) or a cron string as shorthand for a
+     * {@link CronSchedule}. If the scheduler is already started, the schedule arms immediately;
+     * otherwise it arms on `start()`.
+     * @throws {ScheduleAlreadyExistsError} if `id` is already registered.
+     * @throws {InvalidCronExpressionError} if `schedule` is an invalid cron string.
+     */
+    schedule(id: string, schedule: ScheduleInterface | string, task: ScheduledTaskFunction, options?: ScheduleOptions): void;
+    /**
+     * Removes the schedule registered under `id`, cancelling its timer. An in-flight invocation
+     * is left to finish.
+     * @returns `true` if a schedule was removed, `false` if none existed.
+     */
+    unschedule(id: string): boolean;
+    /**
+     * Replaces the schedule of an existing registration, re-arming it (options and task are
+     * preserved). Accepts a {@link ScheduleInterface} or a cron string.
+     * @throws {ScheduleNotFoundError} if `id` is not registered.
+     * @throws {InvalidCronExpressionError} if `schedule` is an invalid cron string.
+     */
+    reschedule(id: string, schedule: ScheduleInterface | string): void;
+    /** Whether a schedule is registered under `id`. */
+    has(id: string): boolean;
+    /** Returns a snapshot of every registered schedule. */
+    list(): ScheduleDescriptor[];
+    /**
+     * Returns the next armed execution date for `id` (or, if the scheduler is stopped, computes
+     * it from now).
+     * @throws {ScheduleNotFoundError} if `id` is not registered.
+     */
+    getNextExecutionDate(id: string): Date | undefined;
+    /** Arms every registered schedule. Idempotent — calling it while started is a no-op. */
+    start(): void;
+    /**
+     * Cancels every schedule's timer synchronously (no further fires occur after `stop()`
+     * returns) and resolves once any in-flight task invocations have settled, so it can be
+     * awaited for a graceful shutdown.
+     */
+    stop(): Promise<void>;
+}

package/dist/types/interfaces/schedulable.interface.d.ts

@@ -0,0 +1,43 @@
+import { ScheduledTaskInterface } from "@pristine-ts/scheduling";
+import { ScheduleInterface } from "./schedule.interface";
+/**
+ * A {@link ScheduledTaskInterface} that additionally declares *when* it should run, so a
+ * scheduler driver can execute it automatically.
+ *
+ * A scheduled task is just work — `run()` — and, by design in `@pristine-ts/scheduling`,
+ * something external decides when it runs (AWS EventBridge, an HTTP trigger, a manual call).
+ * Implementing `SchedulableInterface` is how a task carries its own schedule so an in-process
+ * driver ({@link LocalSchedulerManager}) can own the clock and run it with no external
+ * trigger. Keeping this a separate interface — rather than adding a schedule to every
+ * scheduled task — makes it explicit that a driver must be present to honour the schedule.
+ *
+ * Tag the implementing class with `@tag(ServiceDefinitionTagEnum.Schedulable)` (and `@injectable()`); the local
+ * scheduler injects every tagged class and, on `start()`, arms one timer per schedule the
+ * task returns.
+ *
+ * ```ts
+ * @tag(ServiceDefinitionTagEnum.Schedulable)
+ * @injectable()
+ * export class NightlyCleanupTask implements SchedulableInterface {
+ *   constructor(@inject("MyConfig") private readonly config: MyConfig) {}
+ *
+ *   getSchedules(): ScheduleInterface[] {
+ *     return [new CronSchedule(this.config.cleanupCron)];
+ *   }
+ *
+ *   async run(eventId?: string): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export interface SchedulableInterface extends ScheduledTaskInterface {
+    /**
+     * The schedule(s) on which this task runs. Called once when the scheduler starts, so the
+     * task may compute them from injected dependencies. Return more than one to run the same
+     * task on several schedules (for example a recurring cron plus a one-off date), mixing
+     * schedule kinds freely. Any error thrown here isolates this task — it is logged and does
+     * not prevent other tasks, or the scheduler, from starting.
+     */
+    getSchedules(): ScheduleInterface[];
+}

package/dist/types/interfaces/schedule-descriptor.interface.d.ts

@@ -0,0 +1,22 @@
+import { ScheduleInterface } from "./schedule.interface";
+/**
+ * A read-only snapshot of a registered schedule, returned by `LocalSchedulerManager.list()`.
+ * Useful for building a "next runs" view or an admin listing of active schedules.
+ */
+export interface ScheduleDescriptor {
+    /** The id the schedule is registered under. */
+    id: string;
+    /**
+     * The schedule that determines when the task runs — a {@link CronSchedule},
+     * {@link DateSchedule}, or any other {@link ScheduleInterface}. Its `toString()` gives a
+     * human-readable form.
+     */
+    schedule: ScheduleInterface;
+    /** Whether an invocation of this schedule is currently in-flight. */
+    isRunning: boolean;
+    /**
+     * The next armed execution date, or `undefined` when the scheduler is stopped or the
+     * schedule has no further occurrence.
+     */
+    nextExecutionDate?: Date;
+}

package/dist/types/interfaces/schedule-options.interface.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-schedule policy options. Every field is optional and defaults to a conservative,
+ * safe behaviour, so `schedule(id, expression, task)` with no options is the common case.
+ *
+ * The type is intentionally an open interface so that future options (for example an IANA
+ * `timezone`) can be added without breaking existing call sites.
+ */
+export interface ScheduleOptions {
+    /**
+     * What to do when an occurrence fires while the previous invocation of the same schedule
+     * is still running.
+     *
+     * - `false` (default): **skip** the overlapping occurrence (a warning is logged) and wait
+     *   for the next one. A schedule therefore never runs concurrently with itself.
+     * - `true`: run the new invocation anyway, concurrently with the in-flight one.
+     */
+    allowOverlap?: boolean;
+    /**
+     * What to do when an occurrence is missed because the process could not fire on time
+     * (for example the host slept or the event loop stalled past the occurrence).
+     *
+     * - `false` (default): **skip** the missed occurrence and arm for the next future one.
+     * - `true`: fire **at most one** catch-up invocation on wake, then resume the normal
+     *   schedule. Multiple missed occurrences still collapse into a single catch-up.
+     */
+    catchUp?: boolean;
+    /**
+     * How late (in milliseconds) a fire may be before it is considered a *missed* occurrence
+     * rather than normal jitter. A fire later than this past its scheduled time is subject to
+     * the {@link catchUp} policy; a fire within this tolerance always runs.
+     *
+     * Defaults to `5000` (5 seconds) — comfortably above event-loop jitter, far below any
+     * real sleep. Lower it for sub-minute schedules that must be punctual; raise it on a
+     * heavily loaded host to avoid skipping merely-jittery fires.
+     */
+    missedExecutionThresholdInMilliseconds?: number;
+}

package/dist/types/interfaces/schedule-state.interface.d.ts

@@ -0,0 +1,24 @@
+import { ScheduleInterface } from "./schedule.interface";
+import { ScheduledTaskFunction } from "../types/scheduled-task-function.type";
+/**
+ * The fully-resolved internal state of one registered schedule, held by
+ * `LocalSchedulerManager`. This is an implementation detail — it is intentionally **not**
+ * re-exported from the module's public barrel; {@link ScheduleDescriptor} is the public,
+ * read-only view of a schedule.
+ */
+export interface ScheduleState {
+    id: string;
+    schedule: ScheduleInterface;
+    task: ScheduledTaskFunction;
+    allowOverlap: boolean;
+    catchUp: boolean;
+    missedExecutionThresholdInMilliseconds: number;
+    /** The currently-armed timer handle, if any. */
+    timeout?: ReturnType<typeof setTimeout>;
+    /** The epoch (ms) of the occurrence the timer is currently working towards. */
+    armedTargetEpoch?: number;
+    /** The next armed execution date (mirror of {@link ScheduleState.armedTargetEpoch} as a `Date`). */
+    nextExecutionDate?: Date;
+    /** Whether an invocation of this schedule is currently in-flight. */
+    running: boolean;
+}

package/dist/types/interfaces/schedule.interface.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A schedule tells the scheduler *when* a task should next run. It is deliberately
+ * polymorphic: a {@link CronSchedule} recurs on a cron expression, a {@link DateSchedule}
+ * fires once at a fixed instant, and future schedule kinds (a fixed interval, calendar
+ * rules, ...) can implement the same contract without any change to the scheduler.
+ *
+ * The scheduler drives a schedule purely through {@link getNextExecutionDate}: it asks for
+ * the next occurrence, arms a timer for it, and — after firing — asks again. A schedule that
+ * returns `undefined` has no further occurrence and is left unarmed (a one-shot that has
+ * already fired, or a cron that never matches).
+ */
+export interface ScheduleInterface {
+    /**
+     * The next occurrence strictly after `from`, or `undefined` if this schedule has no
+     * further occurrence.
+     */
+    getNextExecutionDate(from: Date): Date | undefined;
+    /** A short, human-readable description of the schedule, used in logs and `list()`. */
+    toString(): string;
+}

package/dist/types/local-scheduling.module.d.ts

@@ -0,0 +1,30 @@
+import { ModuleInterface } from "@pristine-ts/common";
+export * from "./builders/builders";
+export * from "./enums/enums";
+export * from "./errors/errors";
+export * from "./interfaces/interfaces";
+export * from "./managers/managers";
+export * from "./models/models";
+export * from "./schedules/schedules";
+export * from "./servers/servers";
+export * from "./types/types";
+export * from "./local-scheduling.module.keyname";
+/**
+ * The local-scheduling module. Import it into your application module to make
+ * {@link LocalSchedulerManager} injectable and to have every {@link SchedulableInterface} you
+ * tag with `@tag(ServiceDefinitionTagEnum.Schedulable)` auto-registered when the scheduler
+ * starts.
+ *
+ * You do not have to start the scheduler yourself: {@link LocalSchedulerRuntimeServer} is
+ * tagged as a {@link RuntimeServerInterface}, so `pristine start` starts it (and stops it on
+ * shutdown, via `onShutdown` below) alongside the HTTP/gRPC servers. Resolve
+ * {@link LocalSchedulerManager} directly only when you need the dynamic API (adding schedules
+ * from a database, mutating them from controllers).
+ *
+ * It builds on `@pristine-ts/scheduling` — a {@link SchedulableInterface} is a
+ * {@link ScheduledTaskInterface} that also declares its schedule — and is otherwise
+ * platform-neutral: it depends only on core, logging, and scheduling, and registers no event
+ * mappers or handlers. It coexists with `@pristine-ts/aws-scheduling` and the other scheduling
+ * drivers — none of them interfere with the others.
+ */
+export declare const LocalSchedulingModule: ModuleInterface;

package/dist/types/local-scheduling.module.keyname.d.ts

@@ -0,0 +1 @@
+export declare const LocalSchedulingModuleKeyname: string;

package/dist/types/managers/local-scheduler.manager.d.ts

@@ -0,0 +1,110 @@
+import { LogHandlerInterface } from "@pristine-ts/logging";
+import { LocalSchedulerInterface } from "../interfaces/local-scheduler.interface";
+import { SchedulableInterface } from "../interfaces/schedulable.interface";
+import { ScheduleInterface } from "../interfaces/schedule.interface";
+import { ScheduleOptions } from "../interfaces/schedule-options.interface";
+import { ScheduleDescriptor } from "../interfaces/schedule-descriptor.interface";
+import { ScheduledTaskFunction } from "../types/scheduled-task-function.type";
+/**
+ * In-process scheduler driver for long-running Pristine applications (an always-up server, a
+ * worker). Unlike {@link SchedulerManager} from `@pristine-ts/scheduling` — which runs tagged
+ * tasks when an external trigger (e.g. AWS EventBridge) fires — this manager owns the clock
+ * itself and runs each task on its own {@link ScheduleInterface} (cron, one-off date, ...)
+ * from inside the Node process.
+ *
+ * It offers two registration paths that share one id space and one set of timers:
+ *
+ * - **Dynamic** — schedules registered, replaced, and removed at runtime by id, which suits a
+ *   consumer that loads user-defined schedules from a database and mutates them from HTTP
+ *   controllers.
+ * - **Static** — any class tagged {@link ServiceDefinitionTagEnum.Schedulable} that implements
+ *   {@link SchedulableInterface} is discovered via `@injectAll` and **auto-registered on
+ *   `start()`** from the schedules it declares.
+ *
+ * **Timer strategy:** each schedule owns a single chained `setTimeout` armed for its next
+ * occurrence, re-armed after every fire. The delay is always recomputed from the current time
+ * (never accumulated), so the schedule does not drift; delays beyond the `setTimeout` maximum
+ * are chunked. See {@link ScheduleOptions} for the overlap and missed-fire policies.
+ *
+ * It is tagged `"LocalSchedulerInterface"` and module-scoped to the local-scheduling module,
+ * so it can be injected either by class or by interface token. It is a `@singleton()`: there
+ * is exactly one instance per process, so the code that starts it at bootstrap and the HTTP
+ * controllers that mutate schedules at runtime all share the same set of timers.
+ */
+export declare class LocalSchedulerManager implements LocalSchedulerInterface {
+    private readonly logHandler;
+    private readonly schedulables;
+    /**
+     * The largest delay a single `setTimeout` can represent: 2^31 - 1 milliseconds (~24.8
+     * days). Longer waits are chunked into successive timeouts.
+     */
+    private static readonly MAX_TIMEOUT_DELAY;
+    /** Default value for {@link ScheduleOptions.missedExecutionThresholdInMilliseconds}. */
+    private static readonly DEFAULT_MISSED_EXECUTION_THRESHOLD_MS;
+    private readonly states;
+    /** Every task invocation that has been started and not yet settled — awaited by `stop()`. */
+    private readonly inFlightInvocations;
+    private started;
+    /**
+     * @param logHandler The log handler used to report skips, task errors, and lifecycle.
+     * @param schedulables Every class tagged {@link ServiceDefinitionTagEnum.Schedulable}. Injected optionally, so the
+     *   collection is simply empty when none is tagged. They are registered on `start()`.
+     *   Defaults to `[]` so the manager can also be constructed directly (e.g. in tests)
+     *   without wiring the collection.
+     */
+    constructor(logHandler: LogHandlerInterface, schedulables?: SchedulableInterface[]);
+    get isStarted(): boolean;
+    schedule(id: string, schedule: ScheduleInterface | string, task: ScheduledTaskFunction, options?: ScheduleOptions): void;
+    unschedule(id: string): boolean;
+    reschedule(id: string, schedule: ScheduleInterface | string): void;
+    has(id: string): boolean;
+    list(): ScheduleDescriptor[];
+    getNextExecutionDate(id: string): Date | undefined;
+    start(): void;
+    stop(): Promise<void>;
+    /**
+     * Registers each statically-tagged {@link SchedulableInterface} from the schedules it
+     * declares. Called once by `start()`. Each task's registration id derives from its class
+     * name (suffixed with the schedule index when a task declares more than one schedule). A
+     * task whose id is already registered (a collision with a dynamic schedule, or a repeat call
+     * after stop→start) is skipped, and a task whose `getSchedules()` throws is logged and
+     * skipped — neither prevents the others, or the scheduler, from starting.
+     */
+    private registerSchedulables;
+    private resolveSchedule;
+    /**
+     * Computes the next occurrence from now and arms the timer for it. Any existing timer is
+     * cleared first.
+     */
+    private arm;
+    /**
+     * Computes the next occurrence strictly after `baseEpoch` and arms the timer for it. If the
+     * schedule has no upcoming occurrence, it is left unarmed (a one-shot that already fired, or
+     * a cron that never matches).
+     */
+    private armFrom;
+    /**
+     * Arms a `setTimeout` for the currently-armed target, chunked so it never exceeds the
+     * platform maximum. Re-computing the delay from `Date.now()` on each (re-)arm keeps the
+     * schedule drift-free.
+     */
+    private setChunkedTimeout;
+    /**
+     * Fires when a (possibly chunked) timeout elapses. If the real target is still in the future
+     * — because the delay was chunked — it re-arms for the remaining time; otherwise it fires
+     * the occurrence.
+     */
+    private onTimer;
+    /**
+     * Decides whether the occurrence at `target` should run (applying the missed-fire and
+     * overlap policies), re-arms for the next occurrence, and executes the task if warranted.
+     */
+    private fire;
+    /**
+     * Runs the task, isolating any error so it can never break the scheduling loop, and tracks
+     * the invocation so `stop()` can await it. The task receives an `eventId` correlating logs
+     * to this specific occurrence.
+     */
+    private execute;
+    private clearTimer;
+}

package/dist/types/managers/managers.d.ts

@@ -0,0 +1 @@
+export * from "./local-scheduler.manager";

package/dist/types/models/cron-expression.model.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A parsed, validated standard cron expression, and the engine that computes its upcoming
+ * execution dates.
+ *
+ * **Supported syntax** (standard 5-field cron, plus an optional leading seconds field):
+ *
+ * ```
+ * ┌───────────── second (0-59)          (optional 6th field; omit for classic 5-field cron)
+ * │ ┌─────────── minute (0-59)
+ * │ │ ┌───────── hour (0-23)
+ * │ │ │ ┌─────── day-of-month (1-31)
+ * │ │ │ │ ┌───── month (1-12 or JAN-DEC)
+ * │ │ │ │ │ ┌─── day-of-week (0-7 or SUN-SAT; 0 and 7 are both Sunday)
+ * │ │ │ │ │ │
+ * * * * * * *
+ * ```
+ *
+ * Each field accepts `*`, single values, ranges (`a-b`), lists (`a,b,c`), and steps
+ * (`* / n`, `a-b/n`, `a/n` meaning "from a to the maximum, every n"). Month and day-of-week
+ * values may be given as case-insensitive names. Ranges must be ascending; wrap-around
+ * ranges such as `FRI-SUN` are not supported — express them as a list (`FRI,SAT,SUN`).
+ *
+ * **Day-of-month / day-of-week OR rule:** when *both* the day-of-month and day-of-week
+ * fields are restricted (neither is `*`), the expression matches when *either* field
+ * matches — the classic Vixie-cron behaviour. For example `30 4 1,15 * 5` runs at 04:30 on
+ * the 1st and 15th of the month **and** every Friday. When at least one of the two is `*`,
+ * the fields combine with AND (the `*` one matching everything). A field is considered
+ * "restricted" whenever its text is not exactly `*` — so a starred field carrying a step
+ * (every-N) still counts as restricted.
+ *
+ * **Time semantics:** all computations use the host's **system local time** (via the
+ * standard `Date`). Across a spring-forward DST transition, a local time that does not
+ * exist is skipped; across a fall-back transition, a repeated local time fires once. A
+ * future revision may accept an IANA timezone without changing this class's method
+ * signatures (a timezone would be supplied as an additional, optional constructor option).
+ */
+export declare class CronExpression {
+    /**
+     * Case-insensitive month names accepted in the month field, mapped to their `1-12` value.
+     */
+    private static readonly MONTH_NAMES;
+    /**
+     * Case-insensitive day-of-week names accepted in the day-of-week field, mapped to their
+     * `0-6` value where `0` is Sunday (the classic cron convention).
+     */
+    private static readonly DAY_OF_WEEK_NAMES;
+    /**
+     * The upper bound (in years past the `from` date) of the forward scan performed when
+     * computing the next execution. Eight years is the largest gap between two consecutive
+     * occurrences of Feb 29 (e.g. 2096 → 2104, because 2100 is not a leap year), so any
+     * expression that ever matches is guaranteed to match within this window. An expression
+     * that does not match within it is treated as never-matching (e.g. `0 0 30 2 *`).
+     */
+    private static readonly MAX_SCAN_YEARS;
+    /**
+     * A hard iteration ceiling on the forward scan, as a defensive backstop against an
+     * unforeseen non-advancing state. The scan advances by at least one calendar field per
+     * iteration and is really bounded by {@link CronExpression.MAX_SCAN_YEARS}; this ceiling
+     * only ever trips on a bug, never on legitimate input.
+     */
+    private static readonly MAX_SCAN_ITERATIONS;
+    /** The normalized expression (trimmed, single-spaced). */
+    readonly expression: string;
+    /** Whether this expression carries a leading seconds field (6-field form). */
+    readonly hasSecondsField: boolean;
+    private readonly seconds;
+    private readonly minutes;
+    private readonly hours;
+    private readonly daysOfMonth;
+    private readonly months;
+    private readonly daysOfWeek;
+    private readonly dayOfMonthRestricted;
+    private readonly dayOfWeekRestricted;
+    /**
+     * Parses and validates the expression.
+     * @param expression A 5-field (or 6-field, seconds-leading) standard cron expression.
+     * @throws {InvalidCronExpressionError} if the expression is malformed or out of range.
+     *   The error carries an HTTP 400 status and a precise message.
+     */
+    constructor(expression: string);
+    /**
+     * Returns whether an expression is valid without throwing — convenient for create-time
+     * validation of user input where a boolean is more ergonomic than a try/catch.
+     */
+    static isValid(expression: string): boolean;
+    /**
+     * Computes the next execution strictly after `from`.
+     * @param from The reference instant. Defaults to now.
+     * @returns The next matching `Date`, or `undefined` if the expression has no occurrence
+     *   within the {@link CronExpression.MAX_SCAN_YEARS} scan window (i.e. it never matches,
+     *   such as `0 0 30 2 *`).
+     */
+    getNextExecutionDate(from?: Date): Date | undefined;
+    /**
+     * Computes up to `count` successive execution dates starting strictly after `from`.
+     * Returns fewer than `count` (possibly zero) entries only if the expression stops
+     * matching within the scan window.
+     */
+    getNextExecutionDates(from: Date, count: number): Date[];
+    /** Returns the normalized expression. */
+    toString(): string;
+    /**
+     * Applies the day-of-month / day-of-week OR rule for a candidate date.
+     */
+    private matchesDay;
+    /**
+     * Parses the day-of-week field, which is special-cased for the `0-7` range where both
+     * `0` and `7` mean Sunday. Values are parsed against `0-7` and then `7` is normalized to
+     * `0` so the resulting set aligns with `Date.getDay()`.
+     */
+    private parseDayOfWeek;
+    /**
+     * Parses a single cron field into the set of numeric values it allows.
+     */
+    private parseField;
+    /**
+     * Parses one atomic token (a number or a name) and validates it is within range.
+     */
+    private parseValue;
+}

package/dist/types/models/models.d.ts

@@ -0,0 +1 @@
+export * from "./cron-expression.model";

package/dist/types/schedules/cron.schedule.d.ts

@@ -0,0 +1,22 @@
+import { ScheduleInterface } from "../interfaces/schedule.interface";
+import { CronExpression } from "../models/cron-expression.model";
+/**
+ * A recurring {@link ScheduleInterface} backed by a standard cron expression. Construct it
+ * from a cron string (parsed and validated immediately, throwing an
+ * {@link InvalidCronExpressionError} on bad input) or from an already-built
+ * {@link CronExpression}.
+ *
+ * ```ts
+ * new CronSchedule("0 3 * * *");        // 03:00 every day
+ * new CronSchedule("0/15 9-17 * * 1-5"); // every 15 minutes, 09:00-17:00, Mon-Fri
+ * ```
+ */
+export declare class CronSchedule implements ScheduleInterface {
+    /** The parsed cron expression backing this schedule. */
+    readonly cronExpression: CronExpression;
+    constructor(cronExpression: string | CronExpression);
+    getNextExecutionDate(from: Date): Date | undefined;
+    /** Up to `count` successive occurrences after `from`. */
+    getNextExecutionDates(from: Date, count: number): Date[];
+    toString(): string;
+}

package/dist/types/schedules/date.schedule.d.ts

@@ -0,0 +1,17 @@
+import { ScheduleInterface } from "../interfaces/schedule.interface";
+/**
+ * A one-shot {@link ScheduleInterface} that fires a single time at a fixed instant. Once that
+ * instant has passed, {@link getNextExecutionDate} returns `undefined`, so the scheduler
+ * fires it once and then leaves it unarmed — it remains listed, with no next execution date.
+ *
+ * ```ts
+ * new DateSchedule(new Date("2026-12-31T23:59:00"));
+ * ```
+ */
+export declare class DateSchedule implements ScheduleInterface {
+    /** The single instant at which this schedule fires. */
+    readonly date: Date;
+    constructor(date: Date);
+    getNextExecutionDate(from: Date): Date | undefined;
+    toString(): string;
+}

package/dist/types/schedules/schedules.d.ts

@@ -0,0 +1,2 @@
+export * from "./cron.schedule";
+export * from "./date.schedule";

package/dist/types/servers/local-scheduler.runtime-server.d.ts

@@ -0,0 +1,24 @@
+import { RuntimeServerInterface } from "@pristine-ts/core";
+import { LogHandlerInterface } from "@pristine-ts/logging";
+import { LocalSchedulerInterface } from "../interfaces/local-scheduler.interface";
+/**
+ * Adapts {@link LocalSchedulerManager} to the `pristine start` lifecycle so tagged tasks run
+ * with no manual bootstrap.
+ *
+ * It is tagged {@link ServiceDefinitionTagEnum.RuntimeServer}, so `pristine start` resolves it
+ * alongside the HTTP/gRPC servers and calls `start()` — which registers every tagged
+ * {@link SchedulableInterface} and arms its timers. Graceful shutdown is wired via the
+ * module's `onShutdown`, which calls `stop()` to cancel timers and drain in-flight tasks.
+ *
+ * A scheduler has no socket, so the `--port` / `--address` overrides `pristine start`
+ * propagates are ignored.
+ */
+export declare class LocalSchedulerRuntimeServer implements RuntimeServerInterface {
+    private readonly scheduler;
+    private readonly logHandler;
+    /** Stable label for `pristine start` log lines and diagnostics. */
+    readonly name: string;
+    constructor(scheduler: LocalSchedulerInterface, logHandler: LogHandlerInterface);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/types/servers/servers.d.ts

@@ -0,0 +1 @@
+export * from "./local-scheduler.runtime-server";

package/dist/types/types/scheduled-task-function.type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The function a dynamically-registered schedule runs on each fire.
+ *
+ * It receives the `eventId` the scheduler generates for the occurrence (correlating logs to
+ * a specific fire), mirroring {@link ScheduledTaskInterface.run}. The argument is optional to
+ * consume: a plain `() => Promise<void>` (or a synchronous `() => void`) is assignable to
+ * this type, so the common case stays terse. A returned promise is awaited, which is what
+ * lets the overlap policy detect a still-running invocation.
+ */
+export type ScheduledTaskFunction = (eventId?: string) => void | Promise<void>;

package/dist/types/types/types.d.ts

@@ -0,0 +1 @@
+export * from "./scheduled-task-function.type";