@stonyx/cron 0.2.1-alpha.2 → 0.2.1-alpha.20

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-cron/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-cron/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/cron.svg)](https://www.npmjs.com/package/@stonyx/cron)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # stonyx-cron
 
 A small, lightweight cron/job scheduling utility for asynchronous jobs. Designed to schedule, run, and automatically re-schedule jobs at precise intervals with optional debug logging.
@@ -31,6 +35,14 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 |  `register`  | `key: string, callback: Function, interval: number, runOnInit?: boolean` | Register a new job with a given interval in seconds. If `runOnInit` is true, the job runs immediately upon registration. |
 | `unregister` |                               `key: string`                              | Remove a previously registered job.                                                                                      |
 
+> **Callback semantics.** Callbacks are invoked fire-and-forget: `Cron` never waits for one to settle, and reschedules a job *before* invoking it. Two *different* jobs that fall due on the same tick may therefore overlap.
+>
+> A job that is still running when it next falls due is skipped — and **keeps** being skipped until that invocation settles. One warning is logged per stuck run (not per tick), including how long the invocation has been running. `Cron` provides no timeout by design, so **bounding your own callback is your responsibility**: a promise that never settles means that job never runs again for the lifetime of the process. Other jobs are unaffected.
+>
+> Synchronous throws and asynchronous rejections are both caught and reported through `log.error`, with the error's stack interpolated into the message. Neither can stop the scheduler.
+>
+> `interval` is **whole seconds, as a string**. `register` throws a `TypeError` on a value it cannot parse — in particular, this class does not accept cron expressions; use `CronService` (`@stonyx/cron/service`) for those. Values below `1` are clamped to `1` second with a warning.
+
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
 ## Configuration

package/dist/cron-parser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 5-field cron expression parser with next-occurrence computation.
+ * No external dependencies - built for stonyx-cron.
+ *
+ * Fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6)
+ * Supports: wildcards(*), ranges(1-5), steps(* /5), lists(1,3,5), names(jan-dec, sun-sat)
+ */
+export interface ParsedCronExpression {
+    minutes: number[];
+    hours: number[];
+    daysOfMonth: number[];
+    months: number[];
+    daysOfWeek: number[];
+}
+/**
+ * Parse a single cron field into a sorted array of allowed values.
+ */
+export declare function parseField(field: string, fieldIndex: number): number[];
+/**
+ * Parse a 5-field cron expression into field arrays.
+ */
+export declare function parseCronExpression(expr: string): ParsedCronExpression;
+/**
+ * Compute the next occurrence of a cron expression after a given timestamp.
+ */
+export declare function nextOccurrence(expr: string, afterMs: number, tz?: string): number | undefined;
+/**
+ * Validate a cron expression without computing next occurrence.
+ */
+export declare function validateCronExpression(expr: string): void;

package/dist/cron-parser.js

@@ -0,0 +1,200 @@
+/**
+ * 5-field cron expression parser with next-occurrence computation.
+ * No external dependencies - built for stonyx-cron.
+ *
+ * Fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6)
+ * Supports: wildcards(*), ranges(1-5), steps(* /5), lists(1,3,5), names(jan-dec, sun-sat)
+ */
+const MONTH_NAMES = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
+const DAY_NAMES = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+const FIELD_RANGES = [
+    { min: 0, max: 59 }, // minute
+    { min: 0, max: 23 }, // hour
+    { min: 1, max: 31 }, // day of month
+    { min: 1, max: 12 }, // month
+    { min: 0, max: 6 }, // day of week
+];
+/**
+ * Parse a single cron field into a sorted array of allowed values.
+ */
+export function parseField(field, fieldIndex) {
+    const { min, max } = FIELD_RANGES[fieldIndex];
+    const names = fieldIndex === 3 ? MONTH_NAMES : fieldIndex === 4 ? DAY_NAMES : null;
+    const resolveToken = (token) => {
+        if (names) {
+            const lower = token.toLowerCase();
+            if (lower in names)
+                return names[lower];
+        }
+        const n = Number(token);
+        if (!Number.isInteger(n))
+            throw new Error(`Invalid cron value: "${token}" in field ${fieldIndex}`);
+        // Normalize day-of-week 7 -> 0 (both mean Sunday)
+        if (fieldIndex === 4 && n === 7)
+            return 0;
+        return n;
+    };
+    const results = new Set();
+    for (const part of field.split(',')) {
+        const trimmed = part.trim();
+        const [rangeStr, stepStr] = trimmed.split('/');
+        const step = stepStr !== undefined ? Number(stepStr) : 1;
+        if (!Number.isInteger(step) || step < 1) {
+            throw new Error(`Invalid step "${stepStr}" in cron field ${fieldIndex}`);
+        }
+        let start, end;
+        if (rangeStr === '*') {
+            start = min;
+            end = max;
+        }
+        else if (rangeStr.includes('-')) {
+            const [lo, hi] = rangeStr.split('-');
+            start = resolveToken(lo);
+            end = resolveToken(hi);
+        }
+        else {
+            start = resolveToken(rangeStr);
+            end = stepStr !== undefined ? max : start;
+        }
+        if (start < min || start > max || end < min || end > max) {
+            throw new Error(`Value out of range [${min}-${max}] in cron field ${fieldIndex}: "${trimmed}"`);
+        }
+        for (let v = start; v <= end; v += step) {
+            results.add(v);
+        }
+    }
+    return [...results].sort((a, b) => a - b);
+}
+/**
+ * Parse a 5-field cron expression into field arrays.
+ */
+export function parseCronExpression(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Cron expression must have exactly 5 fields, got ${fields.length}: "${expr}"`);
+    }
+    return {
+        minutes: parseField(fields[0], 0),
+        hours: parseField(fields[1], 1),
+        daysOfMonth: parseField(fields[2], 2),
+        months: parseField(fields[3], 3),
+        daysOfWeek: parseField(fields[4], 4),
+    };
+}
+/**
+ * Get the number of days in a given month/year.
+ */
+function daysInMonth(_year, month) {
+    return new Date(_year, month, 0).getDate();
+}
+/**
+ * Check if a day-of-month + day-of-week pair matches the parsed expression.
+ */
+function dayMatches(parsed, domWild, dowWild, dayOfMonth, dayOfWeek) {
+    const domMatch = parsed.daysOfMonth.includes(dayOfMonth);
+    const dowMatch = parsed.daysOfWeek.includes(dayOfWeek);
+    if (domWild && dowWild)
+        return true;
+    if (domWild)
+        return dowMatch;
+    if (dowWild)
+        return domMatch;
+    return domMatch || dowMatch; // Both restricted -> OR
+}
+/**
+ * Compute the next occurrence of a cron expression after a given timestamp.
+ */
+export function nextOccurrence(expr, afterMs, tz) {
+    const parsed = parseCronExpression(expr);
+    const exprFields = expr.trim().split(/\s+/);
+    const domWild = exprFields[2] === '*';
+    const dowWild = exprFields[4] === '*';
+    // Start from the next whole minute after afterMs
+    const startDate = new Date(afterMs);
+    startDate.setSeconds(0, 0);
+    startDate.setMinutes(startDate.getMinutes() + 1);
+    // Convert to target timezone for field matching
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz || undefined,
+        year: 'numeric', month: 'numeric', day: 'numeric',
+        hour: 'numeric', minute: 'numeric', hour12: false,
+        weekday: 'short',
+    });
+    const dayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+    // Parse formatted date parts in the target timezone
+    function getLocalParts(date) {
+        const parts = {};
+        for (const { type, value } of formatter.formatToParts(date)) {
+            parts[type] = value;
+        }
+        const hourStr = parts.hour ?? '0';
+        return {
+            year: Number(parts.year ?? '0'),
+            month: Number(parts.month ?? '0'),
+            day: Number(parts.day ?? '0'),
+            hour: Number(hourStr === '24' ? '0' : hourStr),
+            minute: Number(parts.minute ?? '0'),
+            weekday: dayMap[parts.weekday] ?? 0,
+        };
+    }
+    // Search limit: 4 years of minutes
+    const maxMs = afterMs + 4 * 365.25 * 24 * 60 * 60 * 1000;
+    const candidate = new Date(startDate);
+    while (candidate.getTime() <= maxMs) {
+        const p = getLocalParts(candidate);
+        // Check month
+        if (!parsed.months.includes(p.month)) {
+            const nextMonth = parsed.months.find(m => m > p.month);
+            if (nextMonth) {
+                advanceToMonth(candidate, p.year, nextMonth);
+            }
+            else {
+                advanceToMonth(candidate, p.year + 1, parsed.months[0]);
+            }
+            continue;
+        }
+        // Check day (dom + dow)
+        if (!dayMatches(parsed, domWild, dowWild, p.day, p.weekday)) {
+            candidate.setMinutes(candidate.getMinutes() + (24 * 60 - p.hour * 60 - p.minute));
+            continue;
+        }
+        // Check hour
+        if (!parsed.hours.includes(p.hour)) {
+            const nextHour = parsed.hours.find(h => h > p.hour);
+            if (nextHour) {
+                candidate.setMinutes(candidate.getMinutes() + ((nextHour - p.hour) * 60 - p.minute));
+            }
+            else {
+                candidate.setMinutes(candidate.getMinutes() + ((24 - p.hour) * 60 - p.minute));
+            }
+            continue;
+        }
+        // Check minute
+        if (!parsed.minutes.includes(p.minute)) {
+            const nextMin = parsed.minutes.find(m => m > p.minute);
+            if (nextMin) {
+                candidate.setMinutes(candidate.getMinutes() + (nextMin - p.minute));
+            }
+            else {
+                candidate.setMinutes(candidate.getMinutes() + (60 - p.minute));
+            }
+            continue;
+        }
+        // All fields match
+        return candidate.getTime();
+    }
+    return undefined;
+}
+/**
+ * Advance a Date to the start of a specific month in a specific year.
+ */
+function advanceToMonth(current, year, month) {
+    current.setFullYear(year, month - 1, 1);
+    current.setHours(0, 0, 0, 0);
+}
+/**
+ * Validate a cron expression without computing next occurrence.
+ */
+export function validateCronExpression(expr) {
+    parseCronExpression(expr);
+}

package/dist/job.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Job data model and state machine for the advanced scheduling system.
+ */
+import { type Schedule } from './schedule.js';
+export interface JobState {
+    nextRunAtMs: number | undefined;
+    runningAtMs: number | undefined;
+    lastRunAtMs: number | undefined;
+    lastStatus: 'ok' | 'error' | 'skipped' | undefined;
+    lastError: string | undefined;
+    lastDurationMs: number | undefined;
+    consecutiveErrors: number;
+    scheduleErrorCount: number;
+}
+export interface Job {
+    id: string;
+    name: string;
+    description: string | undefined;
+    enabled: boolean;
+    deleteAfterRun: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: Schedule;
+    sessionTarget: string;
+    wakeMode: string;
+    payload: Record<string, unknown>;
+    delivery: Record<string, unknown> | undefined;
+    state: JobState;
+}
+export interface JobInput {
+    name: string;
+    schedule: Schedule;
+    payload: Record<string, unknown>;
+    description?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    sessionTarget?: string;
+    wakeMode?: string;
+    delivery?: Record<string, unknown>;
+}
+export interface JobPatch {
+    name?: string;
+    description?: string;
+    schedule?: Schedule;
+    payload?: Record<string, unknown>;
+    delivery?: Record<string, unknown> | null;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    sessionTarget?: string;
+    wakeMode?: string;
+}
+export declare function errorBackoffMs(consecutiveErrors: number): number;
+/**
+ * Create a new job object from input.
+ */
+export declare function createJob(input: JobInput): Job;
+/**
+ * Apply an update patch to a job.
+ */
+export declare function updateJob(job: Job, patch: JobPatch): Job;
+/**
+ * Mark a job as started (running).
+ */
+export declare function markRunning(job: Job): void;
+/**
+ * Apply the result of a job execution.
+ */
+export declare function applyResult(job: Job, status: 'ok' | 'error' | 'skipped', error?: string, durationMs?: number): void;
+/**
+ * Check if a job is due to run.
+ */
+export declare function isDue(job: Job, nowMs: number): boolean;

package/dist/job.js

@@ -0,0 +1,172 @@
+/**
+ * Job data model and state machine for the advanced scheduling system.
+ */
+import { computeNextRunAtMs, validateSchedule } from './schedule.js';
+/**
+ * Error backoff table (milliseconds).
+ * Applied after consecutive errors to prevent hammering.
+ */
+const ERROR_BACKOFF_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
+export function errorBackoffMs(consecutiveErrors) {
+    if (consecutiveErrors < 1)
+        return 0;
+    return ERROR_BACKOFF_MS[Math.min(consecutiveErrors - 1, ERROR_BACKOFF_MS.length - 1)];
+}
+/**
+ * Create a new job object from input.
+ */
+export function createJob(input) {
+    validateSchedule(input.schedule);
+    const nowMs = Date.now();
+    const enabled = input.enabled !== false;
+    const deleteAfterRun = input.deleteAfterRun ?? (input.schedule.kind === 'at');
+    const job = {
+        id: crypto.randomUUID(),
+        name: input.name,
+        description: input.description || undefined,
+        enabled,
+        deleteAfterRun,
+        createdAtMs: nowMs,
+        updatedAtMs: nowMs,
+        schedule: { ...input.schedule },
+        sessionTarget: input.sessionTarget || 'isolated',
+        wakeMode: input.wakeMode || 'now',
+        payload: { ...input.payload },
+        delivery: input.delivery ? { ...input.delivery } : undefined,
+        state: {
+            nextRunAtMs: undefined,
+            runningAtMs: undefined,
+            lastRunAtMs: undefined,
+            lastStatus: undefined,
+            lastError: undefined,
+            lastDurationMs: undefined,
+            consecutiveErrors: 0,
+            scheduleErrorCount: 0,
+        },
+    };
+    // Compute initial next run
+    if (enabled) {
+        try {
+            job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+        }
+        catch {
+            job.state.scheduleErrorCount = 1;
+        }
+    }
+    return job;
+}
+/**
+ * Apply an update patch to a job.
+ */
+export function updateJob(job, patch) {
+    const nowMs = Date.now();
+    if (patch.name !== undefined)
+        job.name = patch.name;
+    if (patch.description !== undefined)
+        job.description = patch.description || undefined;
+    if (patch.deleteAfterRun !== undefined)
+        job.deleteAfterRun = patch.deleteAfterRun;
+    if (patch.sessionTarget !== undefined)
+        job.sessionTarget = patch.sessionTarget;
+    if (patch.wakeMode !== undefined)
+        job.wakeMode = patch.wakeMode;
+    if (patch.payload !== undefined)
+        job.payload = { ...patch.payload };
+    if (patch.delivery !== undefined)
+        job.delivery = patch.delivery ? { ...patch.delivery } : undefined;
+    if (patch.schedule !== undefined) {
+        validateSchedule(patch.schedule);
+        job.schedule = { ...patch.schedule };
+        job.state.scheduleErrorCount = 0;
+        // Recompute next run
+        if (job.enabled) {
+            try {
+                job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+            }
+            catch {
+                job.state.scheduleErrorCount = 1;
+            }
+        }
+    }
+    if (patch.enabled !== undefined) {
+        job.enabled = patch.enabled;
+        if (job.enabled && !job.state.nextRunAtMs) {
+            try {
+                job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+            }
+            catch {
+                job.state.scheduleErrorCount++;
+            }
+        }
+        if (!job.enabled) {
+            job.state.nextRunAtMs = undefined;
+        }
+    }
+    job.updatedAtMs = nowMs;
+    return job;
+}
+/**
+ * Mark a job as started (running).
+ */
+export function markRunning(job) {
+    job.state.runningAtMs = Date.now();
+}
+/**
+ * Apply the result of a job execution.
+ */
+export function applyResult(job, status, error, durationMs) {
+    const nowMs = Date.now();
+    job.state.lastRunAtMs = job.state.runningAtMs || nowMs;
+    job.state.runningAtMs = undefined;
+    job.state.lastStatus = status;
+    job.state.lastError = status === 'error' ? error : undefined;
+    job.state.lastDurationMs = durationMs;
+    if (status === 'error') {
+        job.state.consecutiveErrors = (job.state.consecutiveErrors || 0) + 1;
+    }
+    else {
+        job.state.consecutiveErrors = 0;
+    }
+    // One-shot jobs: disable after any terminal status
+    if (job.schedule.kind === 'at') {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+        return;
+    }
+    // Recurring jobs: compute next run with backoff
+    if (job.enabled) {
+        try {
+            const normalNext = computeNextRunAtMs(job.schedule, nowMs);
+            if (normalNext === undefined) {
+                job.enabled = false;
+                job.state.nextRunAtMs = undefined;
+                return;
+            }
+            if (status === 'error' && job.state.consecutiveErrors > 0) {
+                const backoff = errorBackoffMs(job.state.consecutiveErrors);
+                job.state.nextRunAtMs = Math.max(normalNext, nowMs + backoff);
+            }
+            else {
+                job.state.nextRunAtMs = normalNext;
+            }
+            job.state.scheduleErrorCount = 0;
+        }
+        catch {
+            job.state.scheduleErrorCount = (job.state.scheduleErrorCount || 0) + 1;
+            // Auto-disable after 3 consecutive schedule computation errors
+            if (job.state.scheduleErrorCount >= 3) {
+                job.enabled = false;
+                job.state.nextRunAtMs = undefined;
+            }
+        }
+    }
+}
+/**
+ * Check if a job is due to run.
+ */
+export function isDue(job, nowMs) {
+    return job.enabled
+        && !job.state.runningAtMs
+        && job.state.nextRunAtMs !== undefined
+        && job.state.nextRunAtMs <= nowMs;
+}

package/dist/locked.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Async locking mechanism to serialize state mutations.
+ * Prevents concurrent operations from corrupting job state.
+ */
+/**
+ * Execute a function with exclusive access to cron state.
+ * Operations queue behind each other - no concurrent mutations.
+ */
+export declare function locked<T>(fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Reset the lock chain. Only for testing.
+ */
+export declare function resetLock(): void;

package/dist/locked.js

@@ -0,0 +1,27 @@
+/**
+ * Async locking mechanism to serialize state mutations.
+ * Prevents concurrent operations from corrupting job state.
+ */
+let chain = Promise.resolve();
+/**
+ * Execute a function with exclusive access to cron state.
+ * Operations queue behind each other - no concurrent mutations.
+ */
+export async function locked(fn) {
+    let resolve;
+    const prev = chain;
+    chain = new Promise(r => { resolve = r; });
+    await prev;
+    try {
+        return await fn();
+    }
+    finally {
+        resolve();
+    }
+}
+/**
+ * Reset the lock chain. Only for testing.
+ */
+export function resetLock() {
+    chain = Promise.resolve();
+}

package/dist/main.d.ts

@@ -0,0 +1,61 @@
+import MinHeap, { type HeapItem } from './min-heap.js';
+interface CronJob extends HeapItem {
+    callback: () => void | Promise<void>;
+    interval: string;
+    key: string;
+    /**
+     * Timestamp (ms) at which the current invocation started; `undefined` when the
+     * job is idle. Mirrors `job.state.runningAtMs` in the service tier
+     * (`src/job.ts` `markRunning`/`applyResult`/`isDue`).
+     */
+    runningAtMs?: number;
+    /**
+     * True once a skip has been reported for the *current* invocation. Bounds the
+     * still-running warning to one line per stuck run instead of one per tick.
+     */
+    skipReported?: boolean;
+}
+export default class Cron {
+    static instance: Cron | null;
+    jobs: Record<string, CronJob>;
+    heap: MinHeap<CronJob>;
+    timer: ReturnType<typeof setTimeout> | null;
+    constructor();
+    init(): Promise<void>;
+    scheduleNextRun(): void;
+    runDueJobs(): Promise<void>;
+    /**
+     * The one safe way this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections alike, and skips the invocation entirely when the job's previous
+     * invocation has not settled yet (fire-and-forget would otherwise let a slow
+     * job stack invocations on itself).
+     */
+    safeInvoke(job: CronJob, runOnInit?: boolean): void;
+    /**
+     * Report a scheduler-level message without ever letting the logger's own
+     * failure reach the caller.
+     *
+     * `@stonyx/logs` convenience methods return a promise and write to disk
+     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
+     * log volume that promise rejects; an unobserved rejection raised from inside
+     * the handler that exists to prevent unhandled rejections would re-create
+     * exactly the defect this class was fixed for (measured: exit code 1).
+     */
+    report(level: 'error' | 'warn', message: string): void;
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job: CronJob): void;
+    register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
+    unregister(key: string): void;
+    /**
+     * Parse a job interval (whole seconds, as a string) into a positive integer.
+     *
+     * Returns `null` when the value cannot be parsed at all, so callers can choose
+     * between failing fast (`register`) and falling back (`setNextTrigger`).
+     */
+    parseInterval(interval: string): number | null;
+    setNextTrigger(job: CronJob): void;
+    log(text: string, key?: string | null): void;
+}
+export {};