reqon-dsl 0.2.0

package/dist/scheduler/cron-parser.d.ts

@@ -0,0 +1,32 @@
+import type { ScheduleDefinition, IntervalSchedule } from '../ast/nodes.js';
+/**
+ * Parse a cron expression and calculate the next run time
+ *
+ * Cron format: "minute hour day-of-month month day-of-week"
+ * Supports: numbers, ranges (1-5), steps (*​/5), lists (1,3,5), and wildcards (*)
+ */
+export declare function parseCronExpression(expression: string): CronSchedule;
+interface CronSchedule {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+}
+/**
+ * Calculate the next run time for a cron schedule
+ */
+export declare function getNextCronRun(schedule: CronSchedule, after?: Date): Date;
+/**
+ * Convert interval schedule to milliseconds
+ */
+export declare function intervalToMs(interval: IntervalSchedule): number;
+/**
+ * Calculate next run time based on schedule definition
+ */
+export declare function getNextRunTime(schedule: ScheduleDefinition, after?: Date): Date | null;
+/**
+ * Check if a schedule should run now (within the check interval)
+ */
+export declare function shouldRunNow(schedule: ScheduleDefinition, lastRun: Date | undefined, checkIntervalMs?: number): boolean;
+export {};

package/dist/scheduler/cron-parser.js

@@ -0,0 +1,198 @@
+/**
+ * Parse a cron expression and calculate the next run time
+ *
+ * Cron format: "minute hour day-of-month month day-of-week"
+ * Supports: numbers, ranges (1-5), steps (*​/5), lists (1,3,5), and wildcards (*)
+ */
+export function parseCronExpression(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`Invalid cron expression: expected 5 fields, got ${parts.length}`);
+    }
+    return {
+        minute: parseField(parts[0], 0, 59),
+        hour: parseField(parts[1], 0, 23),
+        dayOfMonth: parseField(parts[2], 1, 31),
+        month: parseField(parts[3], 1, 12),
+        dayOfWeek: parseField(parts[4], 0, 6), // 0 = Sunday
+    };
+}
+function parseField(field, min, max) {
+    const values = new Set();
+    for (const part of field.split(',')) {
+        if (part === '*') {
+            // All values
+            for (let i = min; i <= max; i++) {
+                values.add(i);
+            }
+        }
+        else if (part.includes('/')) {
+            // Step values (e.g., */5 or 1-10/2)
+            const [range, stepStr] = part.split('/');
+            const step = parseInt(stepStr, 10);
+            let start = min;
+            let end = max;
+            if (range !== '*') {
+                if (range.includes('-')) {
+                    const [rangeStart, rangeEnd] = range.split('-').map((n) => parseInt(n, 10));
+                    start = rangeStart;
+                    end = rangeEnd;
+                }
+                else {
+                    start = parseInt(range, 10);
+                }
+            }
+            for (let i = start; i <= end; i += step) {
+                values.add(i);
+            }
+        }
+        else if (part.includes('-')) {
+            // Range (e.g., 1-5)
+            const [start, end] = part.split('-').map((n) => parseInt(n, 10));
+            for (let i = start; i <= end; i++) {
+                values.add(i);
+            }
+        }
+        else {
+            // Single value
+            values.add(parseInt(part, 10));
+        }
+    }
+    // Validate all values are in range
+    for (const value of values) {
+        if (value < min || value > max) {
+            throw new Error(`Cron field value ${value} out of range [${min}, ${max}]`);
+        }
+    }
+    return Array.from(values).sort((a, b) => a - b);
+}
+/**
+ * Calculate the next run time for a cron schedule
+ */
+export function getNextCronRun(schedule, after = new Date()) {
+    const next = new Date(after);
+    next.setSeconds(0, 0);
+    next.setMinutes(next.getMinutes() + 1); // Start from next minute
+    // Try up to 4 years to find a match
+    const maxIterations = 4 * 366 * 24 * 60;
+    for (let i = 0; i < maxIterations; i++) {
+        // Check month
+        if (!schedule.month.includes(next.getMonth() + 1)) {
+            // Move to first day of next matching month
+            next.setMonth(next.getMonth() + 1);
+            next.setDate(1);
+            next.setHours(0, 0, 0, 0);
+            continue;
+        }
+        // Check day of month
+        if (!schedule.dayOfMonth.includes(next.getDate())) {
+            next.setDate(next.getDate() + 1);
+            next.setHours(0, 0, 0, 0);
+            continue;
+        }
+        // Check day of week
+        if (!schedule.dayOfWeek.includes(next.getDay())) {
+            next.setDate(next.getDate() + 1);
+            next.setHours(0, 0, 0, 0);
+            continue;
+        }
+        // Check hour
+        if (!schedule.hour.includes(next.getHours())) {
+            next.setHours(next.getHours() + 1);
+            next.setMinutes(0, 0, 0);
+            continue;
+        }
+        // Check minute
+        if (!schedule.minute.includes(next.getMinutes())) {
+            next.setMinutes(next.getMinutes() + 1);
+            continue;
+        }
+        // Found a match!
+        return next;
+    }
+    throw new Error('Could not find next cron run time within 4 years');
+}
+/**
+ * Convert interval schedule to milliseconds
+ */
+export function intervalToMs(interval) {
+    const multipliers = {
+        seconds: 1000,
+        minutes: 60 * 1000,
+        hours: 60 * 60 * 1000,
+        days: 24 * 60 * 60 * 1000,
+        weeks: 7 * 24 * 60 * 60 * 1000,
+    };
+    return interval.value * multipliers[interval.unit];
+}
+/**
+ * Calculate next run time based on schedule definition
+ */
+export function getNextRunTime(schedule, after = new Date()) {
+    switch (schedule.scheduleType) {
+        case 'interval': {
+            if (!schedule.interval) {
+                throw new Error('Interval schedule missing interval configuration');
+            }
+            const intervalMs = intervalToMs(schedule.interval);
+            return new Date(after.getTime() + intervalMs);
+        }
+        case 'cron': {
+            if (!schedule.cronExpression) {
+                throw new Error('Cron schedule missing cron expression');
+            }
+            const cronSchedule = parseCronExpression(schedule.cronExpression);
+            return getNextCronRun(cronSchedule, after);
+        }
+        case 'once': {
+            if (!schedule.runAt) {
+                throw new Error('One-time schedule missing runAt datetime');
+            }
+            const runAt = new Date(schedule.runAt);
+            // If the scheduled time is in the past, return null (job should not run)
+            if (runAt <= after) {
+                return null;
+            }
+            return runAt;
+        }
+        default:
+            throw new Error(`Unknown schedule type: ${schedule.scheduleType}`);
+    }
+}
+/**
+ * Check if a schedule should run now (within the check interval)
+ */
+export function shouldRunNow(schedule, lastRun, checkIntervalMs = 1000) {
+    const now = new Date();
+    switch (schedule.scheduleType) {
+        case 'interval': {
+            if (!lastRun)
+                return true; // Never run before, run now
+            if (!schedule.interval)
+                return false;
+            const intervalMs = intervalToMs(schedule.interval);
+            const elapsed = now.getTime() - lastRun.getTime();
+            return elapsed >= intervalMs;
+        }
+        case 'cron': {
+            if (!schedule.cronExpression)
+                return false;
+            const cronSchedule = parseCronExpression(schedule.cronExpression);
+            const nextRun = getNextCronRun(cronSchedule, lastRun ?? new Date(0));
+            // Check if we're within the check interval of the next run time
+            const diff = Math.abs(now.getTime() - nextRun.getTime());
+            return diff <= checkIntervalMs;
+        }
+        case 'once': {
+            if (!schedule.runAt)
+                return false;
+            if (lastRun)
+                return false; // Already ran
+            const runAt = new Date(schedule.runAt);
+            const diff = Math.abs(now.getTime() - runAt.getTime());
+            return diff <= checkIntervalMs;
+        }
+        default:
+            return false;
+    }
+}

package/dist/scheduler/cron-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scheduler/cron-parser.test.js

@@ -0,0 +1,188 @@
+import { describe, it, expect } from 'vitest';
+import { parseCronExpression, getNextCronRun, intervalToMs, getNextRunTime, shouldRunNow, } from './cron-parser.js';
+describe('parseCronExpression', () => {
+    it('should parse simple cron expressions', () => {
+        const schedule = parseCronExpression('0 * * * *');
+        expect(schedule.minute).toEqual([0]);
+        expect(schedule.hour).toHaveLength(24); // All hours
+        expect(schedule.dayOfMonth).toHaveLength(31);
+        expect(schedule.month).toHaveLength(12);
+        expect(schedule.dayOfWeek).toHaveLength(7);
+    });
+    it('should parse specific values', () => {
+        const schedule = parseCronExpression('30 9 15 6 1');
+        expect(schedule.minute).toEqual([30]);
+        expect(schedule.hour).toEqual([9]);
+        expect(schedule.dayOfMonth).toEqual([15]);
+        expect(schedule.month).toEqual([6]);
+        expect(schedule.dayOfWeek).toEqual([1]);
+    });
+    it('should parse ranges', () => {
+        const schedule = parseCronExpression('0-5 9-17 * * 1-5');
+        expect(schedule.minute).toEqual([0, 1, 2, 3, 4, 5]);
+        expect(schedule.hour).toEqual([9, 10, 11, 12, 13, 14, 15, 16, 17]);
+        expect(schedule.dayOfWeek).toEqual([1, 2, 3, 4, 5]);
+    });
+    it('should parse step values', () => {
+        const schedule = parseCronExpression('*/15 */6 * * *');
+        expect(schedule.minute).toEqual([0, 15, 30, 45]);
+        expect(schedule.hour).toEqual([0, 6, 12, 18]);
+    });
+    it('should parse lists', () => {
+        const schedule = parseCronExpression('0,30 9,12,18 * * *');
+        expect(schedule.minute).toEqual([0, 30]);
+        expect(schedule.hour).toEqual([9, 12, 18]);
+    });
+    it('should parse combined expressions', () => {
+        const schedule = parseCronExpression('0 9-17/2 * * 1-5');
+        expect(schedule.minute).toEqual([0]);
+        expect(schedule.hour).toEqual([9, 11, 13, 15, 17]);
+        expect(schedule.dayOfWeek).toEqual([1, 2, 3, 4, 5]);
+    });
+    it('should throw on invalid cron expression', () => {
+        expect(() => parseCronExpression('0 * *')).toThrow('expected 5 fields');
+    });
+    it('should throw on out of range values', () => {
+        expect(() => parseCronExpression('60 * * * *')).toThrow('out of range');
+        expect(() => parseCronExpression('* 25 * * *')).toThrow('out of range');
+    });
+});
+describe('getNextCronRun', () => {
+    it('should calculate next run for every minute', () => {
+        const schedule = parseCronExpression('* * * * *');
+        const now = new Date('2025-01-20T10:30:00Z');
+        const next = getNextCronRun(schedule, now);
+        expect(next.getMinutes()).toBe(31);
+        expect(next.getHours()).toBe(10);
+    });
+    it('should calculate next run for specific time', () => {
+        const schedule = parseCronExpression('0 9 * * *');
+        const now = new Date('2025-01-20T10:30:00Z');
+        const next = getNextCronRun(schedule, now);
+        // Should be 9:00 the next day
+        expect(next.getMinutes()).toBe(0);
+        expect(next.getHours()).toBe(9);
+        expect(next.getDate()).toBe(21);
+    });
+    it('should handle hourly schedules', () => {
+        const schedule = parseCronExpression('0 * * * *');
+        const now = new Date('2025-01-20T10:30:00Z');
+        const next = getNextCronRun(schedule, now);
+        expect(next.getMinutes()).toBe(0);
+        expect(next.getHours()).toBe(11);
+    });
+    it('should handle day of week constraints', () => {
+        const schedule = parseCronExpression('0 9 * * 1'); // Monday only
+        const now = new Date('2025-01-20T10:30:00Z'); // This is a Monday
+        const next = getNextCronRun(schedule, now);
+        // Should be next Monday at 9:00
+        expect(next.getDay()).toBe(1); // Monday
+        expect(next.getHours()).toBe(9);
+        expect(next.getMinutes()).toBe(0);
+    });
+});
+describe('intervalToMs', () => {
+    it('should convert seconds to ms', () => {
+        const interval = { value: 30, unit: 'seconds' };
+        expect(intervalToMs(interval)).toBe(30_000);
+    });
+    it('should convert minutes to ms', () => {
+        const interval = { value: 5, unit: 'minutes' };
+        expect(intervalToMs(interval)).toBe(5 * 60 * 1000);
+    });
+    it('should convert hours to ms', () => {
+        const interval = { value: 6, unit: 'hours' };
+        expect(intervalToMs(interval)).toBe(6 * 60 * 60 * 1000);
+    });
+    it('should convert days to ms', () => {
+        const interval = { value: 1, unit: 'days' };
+        expect(intervalToMs(interval)).toBe(24 * 60 * 60 * 1000);
+    });
+    it('should convert weeks to ms', () => {
+        const interval = { value: 1, unit: 'weeks' };
+        expect(intervalToMs(interval)).toBe(7 * 24 * 60 * 60 * 1000);
+    });
+});
+describe('getNextRunTime', () => {
+    it('should calculate next run for interval schedule', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'interval',
+            interval: { value: 6, unit: 'hours' },
+        };
+        const now = new Date('2025-01-20T10:00:00Z');
+        const next = getNextRunTime(schedule, now);
+        expect(next).not.toBeNull();
+        expect(next.getTime()).toBe(now.getTime() + 6 * 60 * 60 * 1000);
+    });
+    it('should calculate next run for cron schedule', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'cron',
+            cronExpression: '0 */6 * * *',
+        };
+        const now = new Date('2025-01-20T10:30:00Z');
+        const next = getNextRunTime(schedule, now);
+        expect(next).not.toBeNull();
+        expect(next.getMinutes()).toBe(0);
+        expect(next.getHours()).toBe(12); // Next 6-hour mark
+    });
+    it('should calculate next run for one-time schedule', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'once',
+            runAt: '2025-01-25T15:00:00Z',
+        };
+        const now = new Date('2025-01-20T10:00:00Z');
+        const next = getNextRunTime(schedule, now);
+        expect(next).not.toBeNull();
+        expect(next.toISOString()).toBe('2025-01-25T15:00:00.000Z');
+    });
+    it('should return null for past one-time schedule', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'once',
+            runAt: '2025-01-15T15:00:00Z',
+        };
+        const now = new Date('2025-01-20T10:00:00Z');
+        const next = getNextRunTime(schedule, now);
+        expect(next).toBeNull();
+    });
+});
+describe('shouldRunNow', () => {
+    it('should return true for interval schedule that is due', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'interval',
+            interval: { value: 1, unit: 'hours' },
+        };
+        const lastRun = new Date(Date.now() - 61 * 60 * 1000); // 61 minutes ago
+        expect(shouldRunNow(schedule, lastRun)).toBe(true);
+    });
+    it('should return false for interval schedule not yet due', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'interval',
+            interval: { value: 1, unit: 'hours' },
+        };
+        const lastRun = new Date(Date.now() - 30 * 60 * 1000); // 30 minutes ago
+        expect(shouldRunNow(schedule, lastRun)).toBe(false);
+    });
+    it('should return true for first run of interval schedule', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'interval',
+            interval: { value: 1, unit: 'hours' },
+        };
+        expect(shouldRunNow(schedule, undefined)).toBe(true);
+    });
+    it('should return false for one-time schedule that already ran', () => {
+        const schedule = {
+            type: 'ScheduleDefinition',
+            scheduleType: 'once',
+            runAt: '2025-01-15T15:00:00Z',
+        };
+        const lastRun = new Date('2025-01-15T15:00:00Z');
+        expect(shouldRunNow(schedule, lastRun)).toBe(false);
+    });
+});

package/dist/scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export { Scheduler } from './scheduler.js';
+export { parseCronExpression, getNextRunTime, intervalToMs, shouldRunNow } from './cron-parser.js';
+export type { ScheduledJob, SchedulerState, ScheduleEvent, SchedulerCallbacks, SchedulerConfig, ScheduledMission, } from './types.js';

package/dist/scheduler/index.js

@@ -0,0 +1,2 @@
+export { Scheduler } from './scheduler.js';
+export { parseCronExpression, getNextRunTime, intervalToMs, shouldRunNow } from './cron-parser.js';

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,81 @@
+import type { ReqonProgram, MissionDefinition } from '../ast/nodes.js';
+import type { ExecutorConfig, ExecutionResult } from '../interpreter/executor.js';
+import type { ScheduledJob, SchedulerConfig } from './types.js';
+/**
+ * Scheduler for running missions on a schedule
+ */
+export declare class Scheduler {
+    private config;
+    private missions;
+    private state;
+    private running;
+    private checkTimer;
+    private retryTimers;
+    private executorConfig;
+    constructor(config?: SchedulerConfig, executorConfig?: ExecutorConfig);
+    /**
+     * Register a mission for scheduling
+     */
+    register(mission: MissionDefinition, filePath: string): void;
+    /**
+     * Register all scheduled missions from a program
+     */
+    registerProgram(program: ReqonProgram, filePath: string): void;
+    /**
+     * Start the scheduler
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the scheduler
+     */
+    stop(): Promise<void>;
+    /**
+     * Check all jobs and run any that are due
+     */
+    private checkAndRun;
+    /**
+     * Run a scheduled job
+     */
+    private runJob;
+    /**
+     * Handle job failure with optional retry
+     */
+    private handleFailure;
+    /**
+     * Enable a job
+     */
+    enable(missionName: string): void;
+    /**
+     * Disable a job
+     */
+    disable(missionName: string): void;
+    /**
+     * Get job status
+     */
+    getJob(missionName: string): ScheduledJob | undefined;
+    /**
+     * Get all jobs
+     */
+    getJobs(): ScheduledJob[];
+    /**
+     * Trigger a job to run immediately
+     */
+    trigger(missionName: string): Promise<ExecutionResult | null>;
+    /**
+     * Load state from disk
+     */
+    private loadState;
+    /**
+     * Save state to disk
+     */
+    private saveState;
+    /**
+     * Emit a schedule event
+     */
+    private emitEvent;
+    /**
+     * Format schedule for display
+     */
+    private formatSchedule;
+    private log;
+}