@stonyx/cron 0.2.1-beta.9 → 0.2.1-beta.90

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,125 @@
+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;
+}
+interface JobDueResult {
+    status?: string;
+    error?: string;
+    summary?: string;
+}
+interface ExecuteResult {
+    status: string;
+    error?: string;
+    summary?: string;
+    durationMs?: number;
+    deleted?: boolean;
+    /** Only set when `status` is `'skipped'`. */
+    reason?: 'not due' | 'already running' | 'removed';
+}
+interface ServiceStatus {
+    started: boolean;
+    jobCount: number;
+    nextWakeAtMs: number | undefined;
+}
+interface ListOptions {
+    includeDisabled?: boolean;
+}
+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.
+     */
+    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; refusing it is AC4 of #34.
+     *
+     * 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, not the feature (one hung callback wedged every other caller), so it
+     * is not being restored here. The fan-out is caller-driven: it is bounded by
+     * how many times the consumer chooses to call `run()`, exactly like any other
+     * async API, and the scheduler never produces it on its own. A consumer that
+     * exposes `run()` over HTTP or a CLI owns that bound the same way it owns
+     * request concurrency for every other handler. A per-invoke bound inside the
+     * service is tracked separately (#35).
+     */
+    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, then enters at phase 2 via `#executeClaimed`.
+     * That entry point is a `#private` method rather than a parameter on this
+     * one: as a published `alreadyClaimed` boolean it was a supported way for a
+     * consumer to skip phase 1 entirely, which defeats the claim guard AC4 asks
+     * for and allows concurrent `onJobDue` invocations for the same job.
+     */
+    executeJob(job: Job): Promise<ExecuteResult>;
+    removeFromHeap(id: string): void;
+    log(message: string): void;
+}
+export {};