@stonyx/cron 0.2.1-beta.6 → 0.2.1-beta.61

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.

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,21 @@
+import MinHeap, { type HeapItem } from './min-heap.js';
+interface CronJob extends HeapItem {
+    callback: () => void | Promise<void>;
+    interval: string;
+    key: string;
+}
+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>;
+    register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
+    unregister(key: string): void;
+    setNextTrigger(job: CronJob): void;
+    log(text: string, key?: string | null): void;
+}
+export {};

package/dist/main.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { getTimestamp } from '@stonyx/utils/date';
+import MinHeap from './min-heap.js';
+export default class Cron {
+    static instance;
+    jobs = {};
+    heap = new MinHeap();
+    timer = null;
+    constructor() {
+        if (Cron.instance)
+            return Cron.instance;
+        Cron.instance = this;
+    }
+    async init() {
+        // Self-register so log.cron works even when @stonyx/cron is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = '#888', logMethod = 'cron' } = config.cron ?? {};
+        log.defineType(logMethod, logColor);
+    }
+    scheduleNextRun() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        const { heap } = this;
+        if (heap.isEmpty())
+            return;
+        const nextJob = heap.peek();
+        if (!nextJob)
+            return;
+        const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
+        this.timer = setTimeout(() => this.runDueJobs(), delay);
+    }
+    async runDueJobs() {
+        const now = getTimestamp();
+        const { heap } = this;
+        while (!heap.isEmpty()) {
+            const next = heap.peek();
+            if (!next || next.nextTrigger > now)
+                break;
+            const job = heap.pop();
+            if (config.debug)
+                this.log('job has been triggered', job.key);
+            try {
+                await job.callback();
+            }
+            catch (err) {
+                log.error(`Cron job "${job.key}" failed:`, err);
+            }
+            this.setNextTrigger(job);
+            heap.push(job);
+        }
+        this.scheduleNextRun();
+    }
+    register(key, callback, interval, runOnInit = false) {
+        const job = { callback, interval, key, nextTrigger: 0 };
+        this.jobs[key] = job;
+        this.setNextTrigger(job);
+        this.heap.push(job);
+        if (config.debug) {
+            this.log(`job has been registered with interval: ${interval}`, key);
+        }
+        if (runOnInit) {
+            try {
+                callback();
+            }
+            catch (err) {
+                log.error(`Cron job "${key}" failed on init:`, err);
+            }
+        }
+        this.scheduleNextRun();
+    }
+    unregister(key) {
+        const { heap, jobs } = this;
+        const job = jobs[key];
+        if (!job)
+            return;
+        delete jobs[key];
+        heap.remove(job);
+        if (config.debug)
+            this.log('job has been unregistered', key);
+        this.scheduleNextRun();
+    }
+    setNextTrigger(job) {
+        job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
+    }
+    log(text, key = null) {
+        if (!config.cron?.log)
+            return;
+        const tag = key ? `Cron::${key}` : `Cron`;
+        log.cron(`${tag} - ${text}:`);
+    }
+}

package/dist/min-heap.d.ts

@@ -0,0 +1,13 @@
+export interface HeapItem {
+    nextTrigger: number;
+}
+export default class MinHeap<T extends HeapItem> {
+    items: T[];
+    push(job: T): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    bubbleUp(): void;
+    bubbleDown(): void;
+    remove(job: T): void;
+    isEmpty(): boolean;
+}