@stonyx/cron 0.2.1-beta.14 → 0.2.1-beta.140

package/dist/run-log.js

@@ -0,0 +1,60 @@
+/**
+ * In-memory run log for job execution history.
+ * Stores recent execution results per job with auto-pruning.
+ */
+const DEFAULT_MAX_ENTRIES_PER_JOB = 100;
+export default class RunLog {
+    maxEntries;
+    entries;
+    constructor(maxEntriesPerJob = DEFAULT_MAX_ENTRIES_PER_JOB) {
+        this.maxEntries = maxEntriesPerJob;
+        this.entries = new Map();
+    }
+    /**
+     * Record a job execution result.
+     */
+    record(entry) {
+        const log = {
+            ts: Date.now(),
+            jobId: entry.jobId,
+            status: entry.status,
+            error: entry.error,
+            summary: entry.summary,
+            runAtMs: entry.runAtMs,
+            durationMs: entry.durationMs,
+            nextRunAtMs: entry.nextRunAtMs,
+        };
+        if (!this.entries.has(entry.jobId)) {
+            this.entries.set(entry.jobId, []);
+        }
+        const logs = this.entries.get(entry.jobId);
+        if (!logs)
+            return;
+        logs.push(log);
+        // Auto-prune
+        if (logs.length > this.maxEntries) {
+            logs.splice(0, logs.length - this.maxEntries);
+        }
+    }
+    /**
+     * Get run history for a job.
+     */
+    get(jobId, limit = 20) {
+        const logs = this.entries.get(jobId);
+        if (!logs)
+            return [];
+        return logs.slice(-limit).reverse();
+    }
+    /**
+     * Remove all entries for a job.
+     */
+    removeJob(jobId) {
+        this.entries.delete(jobId);
+    }
+    /**
+     * Clear all entries.
+     */
+    clear() {
+        this.entries.clear();
+    }
+}

package/dist/schedule.d.ts

@@ -0,0 +1,23 @@
+export interface AtSchedule {
+    kind: 'at';
+    at: string | number;
+}
+export interface EverySchedule {
+    kind: 'every';
+    everyMs: number;
+    anchorMs?: number;
+}
+export interface CronSchedule {
+    kind: 'cron';
+    expr: string;
+    tz?: string;
+}
+export type Schedule = AtSchedule | EverySchedule | CronSchedule;
+/**
+ * Compute the next run time for a schedule.
+ */
+export declare function computeNextRunAtMs(schedule: Schedule, nowMs: number): number | undefined;
+/**
+ * Validate a schedule definition.
+ */
+export declare function validateSchedule(schedule: Schedule): void;

package/dist/schedule.js

@@ -0,0 +1,65 @@
+/**
+ * Schedule types and next-run computation.
+ *
+ * Three schedule kinds:
+ *   - "at": One-shot at an absolute ISO-8601 timestamp
+ *   - "every": Recurring interval in milliseconds
+ *   - "cron": 5-field cron expression with optional timezone
+ */
+import { nextOccurrence, validateCronExpression } from './cron-parser.js';
+/**
+ * Compute the next run time for a schedule.
+ */
+export function computeNextRunAtMs(schedule, nowMs) {
+    if (schedule.kind === 'at') {
+        const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+        if (!Number.isFinite(atMs))
+            return undefined;
+        return atMs > nowMs ? atMs : undefined;
+    }
+    if (schedule.kind === 'every') {
+        const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+        const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+        if (nowMs < anchor)
+            return anchor;
+        const elapsed = nowMs - anchor;
+        const steps = Math.max(1, Math.floor((elapsed + everyMs - 1) / everyMs));
+        return anchor + steps * everyMs;
+    }
+    if (schedule.kind === 'cron') {
+        const tz = schedule.tz?.trim() || undefined;
+        // Round nowMs down to the current second to avoid sub-second drift
+        const nowSecondMs = Math.floor(nowMs / 1000) * 1000;
+        return nextOccurrence(schedule.expr.trim(), nowSecondMs, tz);
+    }
+    throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}
+/**
+ * Validate a schedule definition.
+ */
+export function validateSchedule(schedule) {
+    if (!schedule || typeof schedule !== 'object') {
+        throw new Error('Schedule must be an object');
+    }
+    if (schedule.kind === 'at') {
+        const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+        if (!Number.isFinite(atMs)) {
+            throw new Error(`Invalid "at" timestamp: "${schedule.at}"`);
+        }
+        return;
+    }
+    if (schedule.kind === 'every') {
+        if (typeof schedule.everyMs !== 'number' || schedule.everyMs < 1) {
+            throw new Error(`"every" schedule requires everyMs >= 1, got: ${schedule.everyMs}`);
+        }
+        return;
+    }
+    if (schedule.kind === 'cron') {
+        if (typeof schedule.expr !== 'string' || !schedule.expr.trim()) {
+            throw new Error('"cron" schedule requires a non-empty expr string');
+        }
+        validateCronExpression(schedule.expr.trim());
+        return;
+    }
+    throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}

package/dist/service.d.ts

@@ -0,0 +1,182 @@
+import MinHeap, { type HeapItem } from './min-heap.js';
+import { type Job, type JobPatch } from './job.js';
+import RunLog from './run-log.js';
+interface HeapEntry extends HeapItem {
+    key: string;
+}
+/**
+ * Why a `run()` did not invoke the callback. Exported so a consumer can write a
+ * total handler over it: the union is closed and narrowed (it was `string`
+ * before #34), so an exhaustive `switch` is now both possible and expected.
+ */
+export type SkipReason = 'not due' | 'already running' | 'removed';
+export interface JobDueResult {
+    status?: string;
+    error?: string;
+    summary?: string;
+}
+export interface ExecuteResult {
+    status: string;
+    error?: string;
+    summary?: string;
+    durationMs?: number;
+    deleted?: boolean;
+    /** Only set when `status` is `'skipped'`. */
+    reason?: SkipReason;
+}
+export interface ServiceStatus {
+    started: boolean;
+    jobCount: number;
+    nextWakeAtMs: number | undefined;
+}
+export interface ListOptions {
+    includeDisabled?: boolean;
+}
+export type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
+export default class CronService {
+    #private;
+    jobs: Map<string, Job>;
+    heap: MinHeap<HeapEntry>;
+    timer: ReturnType<typeof setTimeout> | null;
+    running: boolean;
+    runLog: RunLog;
+    started: boolean;
+    onJobDue: OnJobDueCallback | null;
+    constructor();
+    /**
+     * Start the service. Loads jobs from store (if any), arms timer. A no-op if
+     * already started.
+     *
+     * `initialJobs` crosses a serialization boundary — it is whatever the
+     * consumer's store handed back — so `Job[]` is a compile-time claim about
+     * runtime data. Three behaviours follow from that and are worth knowing
+     * before you call this, because all three are deliberate and two of them
+     * differ from a plain "load and arm":
+     *
+     * 1. WRITES TO `row.state`. A STALE claim (`state.runningAtMs` set by a
+     *    process that is gone) is released, because nothing else ever will —
+     *    there is no lease on the field (#35) — and left in place it is a job
+     *    that is dead forever while `status()` reports it healthy. A LIVE claim,
+     *    held by an invocation still running in this process, is left alone:
+     *    releasing it would let the timer start a second concurrent invocation of
+     *    a job that is already running.
+     *
+     * 2. THROWS on a row this class cannot use, rather than accepting it. A row
+     *    whose `state` is missing, or frozen (`structuredClone` + `Object.freeze`
+     *    is an ordinary defensive rehydration), throws out of `start()` where the
+     *    caller's own `await` can catch it. The alternative is a `TypeError` from
+     *    inside a bare timer callback later — an unhandled rejection, and
+     *    process-fatal under Node's default.
+     *
+     * 3. ARMS THE TIMER EVEN IF IT THROWS. The rows loaded before the throw are
+     *    registered and scheduled. Without this, a throw leaves `started: true`
+     *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
+     *    fires and `status()` still reports healthy.
+     *
+     * Which of the three you can observe depends on the CONTENT of the rows, not
+     * on whether they were deserialized — 1 fires only on a row that already
+     * carries a claim, and 2/3 only on a row this class cannot use. Hand it
+     * well-formed deserialized rows with no claim set and none of the three is
+     * observable. Hand it a deserialized row that DOES carry one and 1 and 2 are
+     * exactly what you get: measured, a stale `state.runningAtMs` of 1 comes back
+     * `undefined`, and a `structuredClone` + `Object.freeze` row makes `start()`
+     * throw `TypeError: Cannot assign to read only property 'runningAtMs'` with
+     * the timer still armed behind it. Hand it live `Job` objects this service is
+     * currently executing and only 1 is in play, by design — and on those it
+     * deliberately does nothing.
+     */
+    start(initialJobs?: Job[]): Promise<void>;
+    /**
+     * Stop the service. Clears timer.
+     */
+    stop(): void;
+    /**
+     * Get service status.
+     */
+    status(): ServiceStatus;
+    /**
+     * List jobs, optionally including disabled ones.
+     */
+    list(opts?: ListOptions): Job[];
+    /**
+     * Get a single job by ID.
+     */
+    get(id: string): Job | null;
+    /**
+     * Add a new job. Input is normalized for AI compatibility.
+     */
+    add(rawInput: Record<string, unknown>): Promise<Job>;
+    /**
+     * Update an existing job.
+     */
+    update(id: string, patch: JobPatch): Promise<Job>;
+    /**
+     * Remove a job.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Manually trigger a job.
+     *
+     * Returns `{ status: 'skipped', reason }` without invoking the callback when
+     * the job is not due (`mode: 'due'`), is already in flight
+     * (`'already running'`), or was removed before the claim landed
+     * (`'removed'`). Before the phase split, a forced run against an in-flight
+     * job launched a second concurrent invocation.
+     *
+     * THROWS (rather than returning a skip) when `id` is not a registered job:
+     * `Error("Job not found: <id>")`. A job that disappears between this lookup
+     * and the claim is the `'removed'` skip above, not a throw — the two differ
+     * only by the timing of a race, and the second is a legitimate outcome
+     * whereas the first is a caller error.
+     *
+     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
+     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
+     * across DIFFERENT jobs is deliberately unbounded — N concurrent `run()`
+     * calls produce N concurrent consumer callbacks. Before the phase split
+     * these serialized behind the module-global lock; that serialization was the
+     * bug rather than the feature (one hung callback wedged every other caller),
+     * so it is not restored here. The fan-out is caller-driven and the scheduler
+     * never produces it on its own. A per-invoke bound belongs above this layer;
+     * it is tracked on stonyx-cron#35 alongside the execution timeout.
+     *
+     * NOT FIXED HERE: the phase split fixes the LOCK wedge, not the TIMER. A
+     * callback that never settles still stops `onTimer`'s sequential loop
+     * forever — `running` stays true, every later tick early-returns and re-arms,
+     * and the hung job's batch siblings stay claimed and off-heap having never
+     * been invoked. CRUD still resolves and `status()` still reports
+     * `started: true`, so that failure is now silent where it used to be loud.
+     * Bounding the callback and releasing batch siblings is stonyx-cron#35. Do
+     * not read this method's doc as "the hang is fixed".
+     */
+    run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
+    /**
+     * Get run history for a job.
+     */
+    runs(id: string, limit?: number): ReturnType<RunLog['get']>;
+    armTimer(): void;
+    onTimer(): Promise<void>;
+    findDueJobs(nowMs: number): Job[];
+    /**
+     * Execute a job in three phases:
+     *
+     *   1. claim  (locked)   — take ownership of the job, detach it from the heap
+     *   2. invoke (UNLOCKED) — await the consumer callback
+     *   3. settle (locked)   — apply the result, log it, re-insert into the heap
+     *
+     * The critical section deliberately excludes phase 2. `onJobDue` is
+     * arbitrary, unbounded consumer code; awaiting it under the module-global
+     * lock is what wedged every subsequent `locked()` call (add/update/remove)
+     * when a callback never settled.
+     *
+     * `onTimer` performs the batch claim (`findDueJobs` + `markRunning`) for all
+     * due jobs under a single lock and then enters at phase 2 via
+     * `#executeClaimed`. That entry point is `#private` rather than a parameter
+     * on this method: as a published `alreadyClaimed` flag it would be a
+     * supported way to skip phase 1 entirely, defeating the claim guard and
+     * allowing concurrent `onJobDue` invocations for the same job.
+     */
+    executeJob(job: Job): Promise<ExecuteResult>;
+    removeFromHeap(id: string): void;
+    log(message: string): void;
+}
+export {};