|
| 1 | +/** |
| 2 | + * Single cron implementation for the trigger engine. |
| 3 | + * |
| 4 | + * Standard 5-field cron (minute hour dom month dow). This module is the one |
| 5 | + * place cron expressions are parsed, matched, and validated — the engine's |
| 6 | + * scheduler, the route-level validation, and anything Joe schedules must all |
| 7 | + * agree on edge cases, so they all import from here. |
| 8 | + */ |
| 9 | + |
| 10 | +function parseCronField(field: string, min: number, max: number): number[] { |
| 11 | + const values: number[] = [] |
| 12 | + for (const part of field.split(',')) { |
| 13 | + const stepMatch = part.match(/^(.+)\/(\d+)$/) |
| 14 | + const step = stepMatch ? parseInt(stepMatch[2], 10) : 1 |
| 15 | + // Defensive guard — `step <= 0` would make the loops below never advance |
| 16 | + // (or run backwards), pinning the scheduler. Any caller that reaches this |
| 17 | + // branch with a zero/negative step has bypassed isValidCron, so refuse loudly. |
| 18 | + if (!Number.isFinite(step) || step <= 0) { |
| 19 | + throw new Error(`Invalid cron step value: ${stepMatch?.[2]} (must be > 0)`) |
| 20 | + } |
| 21 | + const range = stepMatch ? stepMatch[1] : part |
| 22 | + |
| 23 | + if (range === '*') { |
| 24 | + for (let i = min; i <= max; i += step) values.push(i) |
| 25 | + } else if (range.includes('-')) { |
| 26 | + const [start, end] = range.split('-').map(Number) |
| 27 | + for (let i = start; i <= end; i += step) values.push(i) |
| 28 | + } else { |
| 29 | + values.push(parseInt(range, 10)) |
| 30 | + } |
| 31 | + } |
| 32 | + return values |
| 33 | +} |
| 34 | + |
| 35 | +export function cronMatchesDate(expression: string, date: Date): boolean { |
| 36 | + const parts = expression.trim().split(/\s+/) |
| 37 | + if (parts.length !== 5) return false |
| 38 | + |
| 39 | + try { |
| 40 | + const [minF, hourF, domF, monF, dowF] = parts |
| 41 | + const minute = parseCronField(minF, 0, 59) |
| 42 | + const hour = parseCronField(hourF, 0, 23) |
| 43 | + const dom = parseCronField(domF, 1, 31) |
| 44 | + const month = parseCronField(monF, 1, 12) |
| 45 | + const dow = parseCronField(dowF, 0, 6) |
| 46 | + |
| 47 | + return ( |
| 48 | + minute.includes(date.getMinutes()) && |
| 49 | + hour.includes(date.getHours()) && |
| 50 | + dom.includes(date.getDate()) && |
| 51 | + month.includes(date.getMonth() + 1) && |
| 52 | + dow.includes(date.getDay()) |
| 53 | + ) |
| 54 | + } catch { |
| 55 | + // Malformed expression (e.g. step 0). Treat as never-matching so a bad |
| 56 | + // legacy schedule cannot pin the scheduler in a tight loop. |
| 57 | + return false |
| 58 | + } |
| 59 | +} |
| 60 | + |
| 61 | +/** Compute the next matching minute for a cron expression after `after`. */ |
| 62 | +export function nextCronMatch(expression: string, after: Date): Date { |
| 63 | + const d = new Date(after) |
| 64 | + d.setSeconds(0, 0) |
| 65 | + d.setMinutes(d.getMinutes() + 1) |
| 66 | + // Search up to 366 days ahead |
| 67 | + for (let i = 0; i < 366 * 24 * 60; i++) { |
| 68 | + if (cronMatchesDate(expression, d)) return d |
| 69 | + d.setMinutes(d.getMinutes() + 1) |
| 70 | + } |
| 71 | + // Fallback: 24h from now |
| 72 | + return new Date(after.getTime() + 86400000) |
| 73 | +} |
| 74 | + |
| 75 | +/** Validate a 5-field cron expression. Returns true if the format is valid. */ |
| 76 | +export function isValidCron(expr: string): boolean { |
| 77 | + const parts = expr.trim().split(/\s+/) |
| 78 | + if (parts.length !== 5) return false |
| 79 | + const ranges = [ |
| 80 | + [0, 59], // minute |
| 81 | + [0, 23], // hour |
| 82 | + [1, 31], // day of month |
| 83 | + [1, 12], // month |
| 84 | + [0, 6], // day of week |
| 85 | + ] |
| 86 | + return parts.every((part, i) => { |
| 87 | + const [min, max] = ranges[i] |
| 88 | + return part.split(',').every(segment => { |
| 89 | + const stepMatch = segment.match(/^(.+)\/(\d+)$/) |
| 90 | + if (stepMatch) { |
| 91 | + const step = parseInt(stepMatch[2], 10) |
| 92 | + if (isNaN(step) || step < 1) return false |
| 93 | + } |
| 94 | + const range = stepMatch ? stepMatch[1] : segment |
| 95 | + if (range === '*') return true |
| 96 | + if (range.includes('-')) { |
| 97 | + const [a, b] = range.split('-').map(Number) |
| 98 | + return !isNaN(a) && !isNaN(b) && a >= min && b <= max && a <= b |
| 99 | + } |
| 100 | + const n = parseInt(range, 10) |
| 101 | + return !isNaN(n) && n >= min && n <= max |
| 102 | + }) |
| 103 | + }) |
| 104 | +} |
0 commit comments