/** * Schedule expression helpers for the automation editor. * * The backend accepts two categorically different kinds of schedule and treats * them differently (see internal/automation/scheduler.go): * * - `@every ` is a pure interval. It is timezone-independent by * nature and its next firing depends on a server-side anchor, so it has no * wall-clock meaning the UI can predict. * - Everything else is a wall-clock cron evaluated in a timezone. An empty * timezone means UTC. * * This module converts between a stored expression and the structured shape the * schedule composer edits, and computes the next firing so the editor can show * the resolved instant instead of leaving it implicit. */ import { t } from "@/lib/i18n"; export type Frequency = | "every-5m" | "every-15m" | "every-30m" | "every-6h" | "hourly" | "daily" | "weekly" | "custom"; export type ScheduleSpec = { frequency: Frequency; /** Minute of the hour. Used by hourly, daily and weekly. */ minute: number; /** Hour of the day, 0-23. Used by daily and weekly. */ hour: number; /** Day of week, 0 = Sunday. Used by weekly. */ weekday: number; /** Verbatim expression. Authoritative when frequency is "custom". */ expression: string; }; const INTERVAL_EXPRESSIONS: Record = { "@every 5m": "every-5m", "@every 15m": "every-15m", "@every 30m": "every-30m", "@every 6h": "every-6h", }; const FREQUENCY_EXPRESSIONS: Partial> = { "every-5m": "@every 5m", "every-15m": "@every 15m", "every-30m": "@every 30m", "every-6h": "@every 6h", }; export const DEFAULT_SPEC: ScheduleSpec = { frequency: "daily", minute: 0, hour: 9, weekday: 1, expression: "0 9 * * *", }; /** * A schedule only carries a timezone when it is a wall-clock expression. This * mirrors the backend check that decides whether to bind a CRON_TZ prefix. */ export function usesTimezone(expression: string): boolean { const trimmed = expression.trim(); if (!trimmed) return false; return !trimmed.startsWith("@every"); } /** * Expand the named descriptors the backend accepts into 5-field form. * * The set has to match `cron.Descriptor` exactly (scheduler.go wires that * option into its parser). A descriptor missing here fails `toFields`, so a * schedule the backend runs happily falls back to the custom editor and the * structured controls never load for it. */ function expandDescriptor(expression: string): string | null { switch (expression) { case "@hourly": return "0 * * * *"; case "@daily": case "@midnight": return "0 0 * * *"; case "@weekly": return "0 0 * * 0"; case "@monthly": return "0 0 1 * *"; case "@yearly": case "@annually": return "0 0 1 1 *"; default: return null; } } type CronFields = { minute: string; hour: string; dom: string; month: string; dow: string }; function toFields(expression: string): CronFields | null { const parts = (expandDescriptor(expression) ?? expression).split(/\s+/); if (parts.length !== 5) return null; const [minute, hour, dom, month, dow] = parts; return { minute, hour, dom, month, dow }; } const PLAIN_NUMBER = /^\d+$/; /** * Only the exact shapes the composer itself produces map back onto structured * controls. Anything else stays custom, so a hand-written cron is never * silently rewritten into something narrower. */ function parseFields(fields: CronFields, expression: string): ScheduleSpec { const { minute, hour, dom, month, dow } = fields; const everyDay = dom === "*" && month === "*"; if (!PLAIN_NUMBER.test(minute) || !everyDay) { return { ...DEFAULT_SPEC, frequency: "custom", expression }; } if (hour === "*" && dow === "*") { return { ...DEFAULT_SPEC, frequency: "hourly", minute: Number(minute), expression }; } if (!PLAIN_NUMBER.test(hour)) { return { ...DEFAULT_SPEC, frequency: "custom", expression }; } const base = { ...DEFAULT_SPEC, minute: Number(minute), hour: Number(hour), expression }; if (dow === "*") return { ...base, frequency: "daily" }; if (PLAIN_NUMBER.test(dow)) { return { ...base, frequency: "weekly", weekday: Number(dow) % 7 }; } return { ...DEFAULT_SPEC, frequency: "custom", expression }; } export function parseExpression(expression: string): ScheduleSpec { const trimmed = expression.trim(); if (!trimmed) return { ...DEFAULT_SPEC }; const interval = INTERVAL_EXPRESSIONS[trimmed]; if (interval) return { ...DEFAULT_SPEC, frequency: interval, expression: trimmed }; const fields = toFields(trimmed); if (!fields) return { ...DEFAULT_SPEC, frequency: "custom", expression: trimmed }; return parseFields(fields, trimmed); } export function buildExpression(spec: ScheduleSpec): string { const interval = FREQUENCY_EXPRESSIONS[spec.frequency]; if (interval) return interval; switch (spec.frequency) { case "hourly": return `${spec.minute} * * * *`; case "daily": return `${spec.minute} ${spec.hour} * * *`; case "weekly": return `${spec.minute} ${spec.hour} * * ${spec.weekday}`; default: return spec.expression.trim(); } } /* ------------------------------------------------------------------------- * Cron field matching * ---------------------------------------------------------------------- */ type FieldRange = { from: number; to: number; step: number }; /** * Spelled month and weekday values, as the scheduler's parser accepts them. * * The editor validates "0 9 * * MON-FRI" as a schedule the backend will run, * so the preview has to be able to read it too. Parsing names as numbers * yielded NaN, which failed every day of the search and left the next-firing * line silently blank for an expression that fires perfectly well. */ const CRON_NAME_VALUES: Record = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12, sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, }; /** A cron field value: a number, or the name the scheduler accepts for it. */ function cronValue(text: string): number { const named = CRON_NAME_VALUES[text.trim().toLowerCase()]; return named === undefined ? Number(text) : named; } /** One comma-separated term: a star, a value, or a range, optionally stepped. */ function parseTerm(term: string, min: number, max: number): FieldRange | null { const [spec, stepText] = term.split("/"); const step = stepText === undefined ? 1 : Number(stepText); if (!Number.isFinite(step) || step < 1) return null; // "?" is the scheduler's alias for "*" in the two day fields. if (spec === "*" || spec === "" || spec === "?") return { from: min, to: max, step }; const [startText, endText] = spec.split("-"); const from = cronValue(startText); if (!Number.isFinite(from)) return null; if (endText !== undefined) { const to = cronValue(endText); return Number.isFinite(to) ? { from, to, step } : null; } // A bare number carrying a step means "from here onwards", e.g. 5/10. return { from, to: stepText === undefined ? from : max, step }; } function fieldMatches(field: string, value: number, min: number, max: number): boolean { return field.split(",").some((term) => { const range = parseTerm(term, min, max); if (!range) return false; if (value < range.from || value > range.to) return false; return (value - range.from) % range.step === 0; }); } /** * Whether a day field narrows the schedule at all. * * The wildcard spellings must be the same set `parseTerm` accepts, or the two * disagree about what a field means. `?` was the case that bit: `parseTerm` * reads it as the full range, but this read it as a restriction, so * `0 9 ? * MON` counted both day fields as restricted and took the OR branch — * where the `?` side matches every date — and the preview claimed 09:00 daily * instead of Mondays. */ function isRestricted(field: string): boolean { return !field.split(",").some((term) => { const spec = term.split("/")[0]; return spec === "*" || spec === "" || spec === "?"; }); } /** * Standard cron day rule, matching the backend: when day-of-month and * day-of-week are both restricted the schedule fires when EITHER matches; * otherwise both must match. */ function dayMatches(fields: CronFields, day: Date): boolean { if (!fieldMatches(fields.month, day.getUTCMonth() + 1, 1, 12)) return false; const domOk = fieldMatches(fields.dom, day.getUTCDate(), 1, 31); // Sunday is spelled 0 or 7; getUTCDay only ever says 0, so the 7 form has to // be offered explicitly or a schedule written that way never matches. const weekday = day.getUTCDay(); const dowOk = fieldMatches(fields.dow, weekday, 0, 7) || (weekday === 0 && fieldMatches(fields.dow, 7, 0, 7)); if (isRestricted(fields.dom) && isRestricted(fields.dow)) return domOk || dowOk; return domOk && dowOk; } /** Earliest matching time on a day, strictly after the given hour:minute. */ function firstTimeAfter( fields: CronFields, afterHour: number, afterMinute: number, ): { hour: number; minute: number } | null { for (let hour = 0; hour < 24; hour++) { if (!fieldMatches(fields.hour, hour, 0, 23)) continue; for (let minute = 0; minute < 60; minute++) { if (!fieldMatches(fields.minute, minute, 0, 59)) continue; if (hour < afterHour) continue; if (hour === afterHour && minute <= afterMinute) continue; return { hour, minute }; } } return null; } /* ------------------------------------------------------------------------- * Timezone arithmetic * ---------------------------------------------------------------------- */ type ZonedParts = { year: number; month: number; day: number; hour: number; minute: number }; function zonedParts(instant: Date, timeZone: string): ZonedParts { const parts = new Intl.DateTimeFormat("en-US", { timeZone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", }).formatToParts(instant); const read = (type: string) => Number(parts.find((part) => part.type === type)?.value ?? "0"); return { year: read("year"), month: read("month"), day: read("day"), hour: read("hour"), minute: read("minute"), }; } /** * Convert a wall-clock reading in `timeZone` back to the instant it names. * Two correction passes settle the offset, which is enough to land on the * right side of a DST transition. */ function wallClockToInstant(parts: ZonedParts, timeZone: string): Date { const target = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute); let instant = target; for (let pass = 0; pass < 2; pass++) { const seen = zonedParts(new Date(instant), timeZone); const seenAsUtc = Date.UTC(seen.year, seen.month - 1, seen.day, seen.hour, seen.minute); instant = target - (seenAsUtc - instant); } return new Date(instant); } /** * The next instant the expression fires, or null when that cannot be stated: * an `@every` interval (anchored server-side), an unparseable expression, or * nothing within a year. */ export function nextRun( expression: string, timeZone: string, from: Date = new Date(), ): Date | null { const trimmed = expression.trim(); if (!trimmed || trimmed.startsWith("@every")) return null; const fields = toFields(trimmed); if (!fields) return null; const zone = timeZone || "UTC"; let start: ZonedParts; try { start = zonedParts(from, zone); } catch { return null; } for (let offset = 0; offset <= 366; offset++) { const day = new Date(Date.UTC(start.year, start.month - 1, start.day + offset)); if (!dayMatches(fields, day)) continue; const today = offset === 0; const time = firstTimeAfter(fields, today ? start.hour : -1, today ? start.minute : -1); if (!time) continue; return wallClockToInstant( { year: day.getUTCFullYear(), month: day.getUTCMonth() + 1, day: day.getUTCDate(), ...time, }, zone, ); } return null; } /* ------------------------------------------------------------------------- * Presentation * ---------------------------------------------------------------------- */ export function browserTimeZone(): string { try { return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"; } catch { return "UTC"; } } export function timeZoneOptions(): string[] { const supported = (Intl as unknown as { supportedValuesOf?: (key: string) => string[] }) .supportedValuesOf; let zones: string[] = []; try { zones = supported?.("timeZone") ?? []; } catch { zones = []; } if (!zones.length) zones = [browserTimeZone()]; // Intl omits UTC from supportedValuesOf — 418 IANA zones, none of them "UTC" — // while an empty timezone means UTC everywhere else in this feature. Returning // that list unaltered let a schedule be moved off UTC with no way back to it. return ["UTC", ...zones].filter((zone, index, all) => all.indexOf(zone) === index); } /** * Short zone label for the preview line, e.g. "GMT+8". * * The zero offset is normalised because ICU does not agree with itself about * it: a full-ICU Node renders "GMT", the slimmer build in CI renders "GMT+0". * Leaving that through would make the label depend on which binary happened to * render it, and "GMT+0" is the worse of the two readings anyway — an offset of * zero is the one case where naming the offset adds nothing. */ export function timeZoneAbbreviation(timeZone: string, at: Date = new Date()): string { try { const parts = new Intl.DateTimeFormat("en-US", { timeZone, timeZoneName: "shortOffset", }).formatToParts(at); const label = parts.find((part) => part.type === "timeZoneName")?.value ?? timeZone; return /^GMT[+-]0+$/.test(label) ? "GMT" : label; } catch { return timeZone; } } // Catalog KEYS, not copy: this array is built once at module load, so resolving // it here would freeze the weekday names at the boot locale (docs/i18n.md, // "no module-scope t()"). `describeSchedule` resolves them per call instead. const WEEKDAY_KEYS = [ "common:weekdaySunday", "common:weekdayMonday", "common:weekdayTuesday", "common:weekdayWednesday", "common:weekdayThursday", "common:weekdayFriday", "common:weekdaySaturday", ]; const INTERVAL_LABEL_KEYS: Partial> = { "every-5m": "automations:scheduleIntervalEvery5Minutes", "every-15m": "automations:scheduleIntervalEvery15Minutes", "every-30m": "automations:scheduleIntervalEvery30Minutes", "every-6h": "automations:scheduleIntervalEvery6Hours", }; const pad = (value: number) => String(value).padStart(2, "0"); /** * One-line summary for lists. Always states the time and zone for a wall-clock * schedule — "Every day" alone is true but tells nobody when it runs. */ export function describeSchedule(expression: string, timeZone: string): string { const trimmed = expression.trim(); if (!trimmed) return t("automations:scheduleNone"); const spec = parseExpression(trimmed); const intervalKey = INTERVAL_LABEL_KEYS[spec.frequency]; if (intervalKey) return t(intervalKey); const zone = timeZone || "UTC"; const zoneLabel = timeZoneAbbreviation(zone); const at = `${pad(spec.hour)}:${pad(spec.minute)}`; switch (spec.frequency) { case "hourly": return t("automations:scheduleEveryHourAt", { minute: pad(spec.minute) }); case "daily": return t("automations:scheduleEveryDayAt", { time: at, zone: zoneLabel }); case "weekly": return t("automations:scheduleEveryWeekdayAt", { weekday: t(WEEKDAY_KEYS[spec.weekday]), time: at, zone: zoneLabel, }); default: return `${trimmed} · ${zoneLabel}`; } } export function formatInZone(instant: Date, timeZone: string): string { return new Intl.DateTimeFormat("en-GB", { timeZone, weekday: "short", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23", }).format(instant); }