reqon-dsl 0.2.0

package/src/scheduler/cron-parser.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseCronExpression,
+  getNextCronRun,
+  intervalToMs,
+  getNextRunTime,
+  shouldRunNow,
+} from './cron-parser.js';
+import type { ScheduleDefinition, IntervalSchedule } from '../ast/nodes.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: IntervalSchedule = { value: 30, unit: 'seconds' };
+    expect(intervalToMs(interval)).toBe(30_000);
+  });
+
+  it('should convert minutes to ms', () => {
+    const interval: IntervalSchedule = { value: 5, unit: 'minutes' };
+    expect(intervalToMs(interval)).toBe(5 * 60 * 1000);
+  });
+
+  it('should convert hours to ms', () => {
+    const interval: IntervalSchedule = { value: 6, unit: 'hours' };
+    expect(intervalToMs(interval)).toBe(6 * 60 * 60 * 1000);
+  });
+
+  it('should convert days to ms', () => {
+    const interval: IntervalSchedule = { value: 1, unit: 'days' };
+    expect(intervalToMs(interval)).toBe(24 * 60 * 60 * 1000);
+  });
+
+  it('should convert weeks to ms', () => {
+    const interval: IntervalSchedule = { 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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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: ScheduleDefinition = {
+      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/src/scheduler/cron-parser.ts

@@ -0,0 +1,236 @@
+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 function parseCronExpression(expression: string): CronSchedule {
+  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
+  };
+}
+
+interface CronSchedule {
+  minute: number[];
+  hour: number[];
+  dayOfMonth: number[];
+  month: number[];
+  dayOfWeek: number[];
+}
+
+function parseField(field: string, min: number, max: number): number[] {
+  const values: Set<number> = 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: CronSchedule, after: Date = new Date()): 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: IntervalSchedule): number {
+  const multipliers: Record<IntervalSchedule['unit'], number> = {
+    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: ScheduleDefinition, after: Date = new Date()): Date | null {
+  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: ScheduleDefinition,
+  lastRun: Date | undefined,
+  checkIntervalMs: number = 1000
+): boolean {
+  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/src/scheduler/index.ts

@@ -0,0 +1,10 @@
+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';