@cronvello/sdk 0.1.4 → 0.2.0

package/dist/dev.d.ts

@@ -0,0 +1,318 @@
+/**
+ * The **local engine** — Cronvello running entirely on your machine, with no account, no cloud, and
+ * no network. It is the piece that turns `@cronvello/sdk` from a thin client into a real cron tool:
+ * give it your jobs and it computes each one's next fire time, runs the handler when it's due, and
+ * enforces the production policies (overlap protection, per-run timeout, retry with backoff) locally
+ * — exactly the guarantees the cloud gives you, on your laptop.
+ *
+ * Everything is driven through an injectable {@link EngineClock}, so the whole scheduler is
+ * deterministic under test (a virtual clock can fast-forward days in microseconds) and uses the real
+ * `setTimeout`/`Date.now` in production. The engine never touches the network.
+ */
+/** The outcome of a single execution (which may have spanned several attempts). */
+type RunStatus = "success" | "error" | "timed_out" | "skipped";
+/** One job the engine should schedule. Derived from a `defineCronvello` registry, but standalone. */
+interface EngineJob {
+    /** Stable registry key. */
+    key: string;
+    /** Cron expression (5- or 6-field, macros). `@reboot` fires once when the engine starts. */
+    schedule: string;
+    /** IANA timezone the schedule is read in. */
+    timeZone: string;
+    /** Abort a run that exceeds this many ms (the handler's `ctx.signal` aborts). 0/undefined = no limit. */
+    timeoutMs?: number;
+    /** Retries after the first failed attempt (default 0). */
+    maxRetries?: number;
+    /** Allow a fire while a previous run of the same job is still in flight (default false). */
+    allowConcurrentRuns?: boolean;
+    /** Optional human description (shown in the dev table). */
+    description?: string;
+}
+/** A completed execution recorded in the in-memory history ring buffer. */
+interface RunRecord {
+    key: string;
+    source: "local";
+    /** Epoch ms when the execution began. */
+    startedAt: number;
+    /** Epoch ms when it settled. */
+    finishedAt: number;
+    durationMs: number;
+    status: RunStatus;
+    /** How many attempts were made (1 + retries that ran). */
+    attempts: number;
+    /** Error message for a failed/timed-out run. */
+    error?: string;
+    /** The handler's return value for a successful run. */
+    result?: unknown;
+}
+/** Lifecycle events the engine emits — the CLI renders them as a live feed. */
+type EngineEvent = {
+    type: "engine-start";
+    jobs: number;
+    at: number;
+} | {
+    type: "engine-stop";
+    at: number;
+} | {
+    type: "scheduled";
+    key: string;
+    at: number;
+} | {
+    type: "fire";
+    key: string;
+    attempt: number;
+    at: number;
+} | {
+    type: "success";
+    key: string;
+    durationMs: number;
+    attempts: number;
+    result: unknown;
+    at: number;
+} | {
+    type: "error";
+    key: string;
+    durationMs: number;
+    attempt: number;
+    willRetry: boolean;
+    error: string;
+    at: number;
+} | {
+    type: "timeout";
+    key: string;
+    durationMs: number;
+    attempt: number;
+    willRetry: boolean;
+    at: number;
+} | {
+    type: "retry";
+    key: string;
+    attempt: number;
+    delayMs: number;
+    at: number;
+} | {
+    type: "skipped";
+    key: string;
+    reason: "overlap";
+    at: number;
+};
+/** A snapshot of one job's scheduling state, for the dev table. */
+interface JobSnapshot {
+    key: string;
+    schedule: string;
+    timeZone: string;
+    description?: string;
+    /** Next fire time, or null for `@reboot` / unschedulable jobs. */
+    nextFire: Date | null;
+    /** True while a run of this job is in flight. */
+    running: boolean;
+}
+/**
+ * The timer/clock seam. Production wires this to the global `setTimeout`/`Date.now`; tests inject a
+ * virtual clock so scheduling is fully deterministic.
+ */
+interface EngineClock {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/** Runs a job's handler in-process (with lifecycle hooks). `signal` aborts on timeout. */
+type EngineRunner = (key: string, signal: AbortSignal) => Promise<unknown>;
+interface LocalEngineOptions {
+    /** Timer source. Defaults to the real `setTimeout`/`Date.now`. */
+    clock?: EngineClock;
+    /** Receives every lifecycle event (for live rendering / metrics). */
+    onEvent?: (event: EngineEvent) => void;
+    /** Cap on the in-memory run history (default 100). Oldest records drop first. */
+    historyLimit?: number;
+    /** Backoff before retry attempt N (1-based: N=1 is the delay before the 2nd attempt). */
+    backoff?: (attempt: number) => number;
+    /** Install SIGINT/SIGTERM handlers that stop the engine cleanly (default false). */
+    installSignalHandlers?: boolean;
+}
+/**
+ * Construct a local engine. Call {@link LocalEngine.start} to begin the loop and
+ * {@link LocalEngine.stop} for a clean shutdown.
+ */
+declare function createLocalEngine(jobs: EngineJob[], runner: EngineRunner, options?: LocalEngineOptions): LocalEngine;
+declare class LocalEngine {
+    private readonly clock;
+    /** Every event listener. The constructor's `onEvent` is registered as one of them. */
+    private readonly listeners;
+    /** Run after the engine has drained, e.g. to close a dashboard server. */
+    private readonly closeHooks;
+    private readonly historyLimit;
+    private readonly backoff;
+    private readonly runner;
+    private readonly states;
+    private readonly history;
+    private readonly inFlight;
+    private started;
+    private stopped;
+    private signalCleanup;
+    constructor(jobs: EngineJob[], runner: EngineRunner, options?: LocalEngineOptions);
+    /**
+     * Subscribe to every lifecycle event (in addition to the constructor's `onEvent`). Returns an
+     * unsubscribe function. Used by the local dashboard to fan events out to many SSE clients without
+     * disturbing the scheduler. A listener that throws is isolated — it can't break the loop.
+     */
+    subscribe(listener: (event: EngineEvent) => void): () => void;
+    /**
+     * Register a hook to run once, after {@link stop} has drained in-flight runs — e.g. to close a
+     * dashboard server so `engine.stop()` tears everything down together. Hooks are awaited.
+     */
+    onStop(hook: () => void | Promise<void>): this;
+    /** Deliver an event to every listener, isolating each so one bad listener can't stall the loop. */
+    private emit;
+    /** Begin scheduling. Idempotent — a second call is a no-op. */
+    start(): this;
+    /**
+     * Stop scheduling and wait for in-flight runs to settle. After this resolves no further handlers
+     * will start. Safe to call from a signal handler.
+     */
+    stop(): Promise<void>;
+    /** The run history, newest first (a copy — safe to keep). */
+    runs(): RunRecord[];
+    /** History entries for one job, newest first. */
+    runsFor(key: string): RunRecord[];
+    /** Current scheduling state of every job, for the dev table. */
+    snapshot(): JobSnapshot[];
+    /** The jobs this engine manages (read-only view). */
+    jobs(): readonly EngineJob[];
+    /** Number of runs currently in flight. */
+    get activeRuns(): number;
+    private scheduleNext;
+    private onDue;
+    /**
+     * Run a job once, right now, by key — the local equivalent of "run now" in the cloud. Goes through
+     * the exact same execution path as a scheduled fire (overlap protection, timeout, retry/backoff,
+     * history + events), so a manual run shows up in the feed just like any other. Resolves with the
+     * resulting {@link RunRecord}. Throws for an unknown key or after the engine has stopped.
+     */
+    trigger(key: string): Promise<RunRecord>;
+    /**
+     * The run history as newline-delimited JSON (NDJSON), oldest run first — one record per line, the
+     * natural shape for piping to a file or another tool. No trailing newline.
+     */
+    toNdjson(): string;
+    /** Start an execution and track it so {@link stop} can await it. Resolves with the run's record. */
+    private launch;
+    private execute;
+    /** A single attempt: run the handler, racing it against the per-job timeout. */
+    private runOnce;
+    private sleep;
+    private record;
+    private installSignalHandlers;
+}
+
+/**
+ * Cron schedule arithmetic for the local engine — next-occurrence, preview, and an upcoming-window
+ * planner, all timezone-aware (IANA / DST) and **zero-dependency**.
+ *
+ * The cloud SDK only needs to *validate* a cron string (see `cron.ts`), because the server owns the
+ * scheduler. The local engine has to actually *fire* jobs, so it needs the next time an expression
+ * matches. This module is that calculator.
+ *
+ * How the timezone math works without a date library:
+ *   • A cron expression matches against **wall-clock** fields (the time a person reads off a clock in
+ *     the job's timezone), so the search is done on naive calendar fields and only converted to a
+ *     real epoch once a full match is found.
+ *   • To convert a wall-clock time in a zone to an absolute epoch we use the runtime's own IANA
+ *     database via `Intl.DateTimeFormat`: format a guess into the zone, measure the offset it
+ *     implies, and correct once. This is the standard offset-probe technique and it handles DST
+ *     transitions (a daily job at 04:00 stays at 04:00 local; the gap to the previous fire is 23h or
+ *     25h across the spring/autumn switch).
+ *
+ * Supported syntax mirrors `validateCron`: 5-field crontab, an optional leading seconds field
+ * (6 fields), the `@macros`, month/weekday names, and `*` / ranges / lists / steps. Day-of-month and
+ * day-of-week combine with Vixie cron's OR semantics when both are restricted.
+ */
+/** A cron expression compiled into the set of values each field matches. */
+interface ParsedCron {
+    /** Allowed seconds. For a 5-field expression this is `{0}`. */
+    seconds: Set<number>;
+    minutes: Set<number>;
+    hours: Set<number>;
+    daysOfMonth: Set<number>;
+    months: Set<number>;
+    /** Allowed weekdays, 0 = Sunday … 6 = Saturday (7 is folded to 0). */
+    daysOfWeek: Set<number>;
+    /** True when the day-of-month field was anything other than `*`/`?`. */
+    domRestricted: boolean;
+    /** True when the day-of-week field was anything other than `*`/`?`. */
+    dowRestricted: boolean;
+    /** True for `@reboot`, which has no scheduled next time (the engine fires it once at start). */
+    reboot: boolean;
+}
+/** Parse a cron expression into matchable value-sets. Throws on a malformed expression. */
+declare function parseCron(expr: string): ParsedCron;
+interface NextOccurrenceOptions {
+    /** Search strictly after this instant (epoch ms or Date). Defaults to now. */
+    from?: Date | number;
+    /** IANA timezone the expression is read in. Defaults to "UTC". */
+    timeZone?: string;
+}
+/**
+ * The next instant the expression fires, strictly after `from`, in the given timezone — or `null`
+ * when nothing matches within {@link SEARCH_HORIZON_YEARS} (e.g. Feb-30). Throws for `@reboot`.
+ */
+declare function nextOccurrence(expr: string | ParsedCron, opts?: NextOccurrenceOptions): Date | null;
+interface PreviewOptions {
+    /** Start the preview after this instant. Defaults to now. */
+    from?: Date | number;
+    /** IANA timezone. Defaults to the runtime's local zone. */
+    timeZone?: string;
+    /** How many fire times to return (default 5, capped at 100). */
+    count?: number;
+}
+/** The next N times an expression fires — the engine of `cronvello preview`. */
+declare function previewSchedule(expr: string, opts?: PreviewOptions): Date[];
+interface UpcomingJob {
+    key: string;
+    schedule: string;
+    timeZone: string;
+}
+interface UpcomingFire {
+    key: string;
+    time: Date;
+    schedule: string;
+    timeZone: string;
+}
+interface UpcomingOptions {
+    /** Window start (defaults to now). */
+    from?: Date | number;
+    /** Window length in ms (defaults to 1 hour). */
+    withinMs?: number;
+    /** Cap per job so a per-second schedule can't flood the plan (default 50). */
+    maxPerJob?: number;
+}
+/**
+ * Every fire across a set of jobs within the next window, merged and sorted by time — what powers
+ * `cronvello dev --dry-run`. Jobs whose schedule can't be parsed are skipped (a dev concern surfaced
+ * elsewhere); `@reboot` jobs are skipped because they have no scheduled time.
+ */
+declare function upcomingFires(jobs: UpcomingJob[], opts?: UpcomingOptions): UpcomingFire[];
+/** The runtime's local IANA zone, falling back to UTC if it can't be resolved. */
+declare function localTimeZone(): string;
+
+interface DashboardOptions {
+    /** Port to listen on. Default `4747`. Use `0` to let the OS pick a free port (handy in tests). */
+    port?: number;
+    /** Host/interface to bind. Default `127.0.0.1` — keep it loopback; this is not a public server. */
+    host?: string;
+}
+interface DashboardHandle {
+    /** The local URL the dashboard is reachable at, e.g. `http://127.0.0.1:4747`. */
+    url: string;
+    /** The actual port bound (resolved even when `port: 0` was requested). */
+    port: number;
+    /** Stop the server and drop every live SSE connection. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Start the dashboard server for an engine. Resolves once it is listening; rejects with a clear
+ * message if the port is already in use. Bind defaults to loopback.
+ */
+declare function startDashboard(engine: LocalEngine, options?: DashboardOptions): Promise<DashboardHandle>;
+
+export { type DashboardHandle, type DashboardOptions, type EngineClock, type EngineEvent, type EngineJob, type EngineRunner, type JobSnapshot, LocalEngine, type LocalEngineOptions, type NextOccurrenceOptions, type ParsedCron, type PreviewOptions, type RunRecord, type RunStatus, type UpcomingFire, type UpcomingJob, type UpcomingOptions, createLocalEngine, localTimeZone, nextOccurrence, parseCron, previewSchedule, startDashboard, upcomingFires };