Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

13.5 KB
Raw Blame
/**
 * Cron expressions as the Rust backend reads them.
 *
 * Shared by every feature that lets someone build a repeating schedule —
 * routines and reminders both — so the two cannot drift on what `0 0 9 * * 2`
 * means. The backend parses these with the `cron` crate, which sets two
 * conventions worth stating up front:
 *
 * - Six fields, `sec min hour dayOfMonth month dayOfWeek`, not the conventional
 *   five. A seventh optional `year` field is accepted on read.
 * - Day-of-week is **1-based starting at Sunday**: 1=Sun through 7=Sat. This is
 *   not the JS `Date.getDay()` numbering, and mixing them up shifts every
 *   weekly schedule by a day.
 */

/**
 * How often a schedule repeats.
 *
 * No daily option: a weekly schedule with every day selected is the same
 * thing, and the pickers let you say it that way. One fewer frequency to
 * render, and no expression that only one picker can express.
 */
export type ScheduleFrequency = 'week' | 'month';

/** Time of day a schedule fires when none was chosen, as `HH:MM`. */
export const DEFAULT_TIME = '09:00';

// Day-of-week values match the `cron` crate convention:
//   1 = Sun, 2 = Mon, 3 = Tue, 4 = Wed, 5 = Thu, 6 = Fri, 7 = Sat
export const WEEKDAY_OPTIONS = [
  { value: '1', label: 'Sun', fullLabel: 'Sunday' },
  { value: '2', label: 'Mon', fullLabel: 'Monday' },
  { value: '3', label: 'Tue', fullLabel: 'Tuesday' },
  { value: '4', label: 'Wed', fullLabel: 'Wednesday' },
  { value: '5', label: 'Thu', fullLabel: 'Thursday' },
  { value: '6', label: 'Fri', fullLabel: 'Friday' },
  { value: '7', label: 'Sat', fullLabel: 'Saturday' },
];

const DOW_VALUES = WEEKDAY_OPTIONS.map((option) => option.value);

/** Monday to Friday, the default weekly selection. */
export const DEFAULT_WEEKDAYS = ['2', '3', '4', '5', '6'];

/** The parts of a cron expression a picker actually edits. */
export type CronParts = {
  frequency: ScheduleFrequency;
  /** `HH:MM`, 24-hour. */
  time: string;
  /** Day-of-week values in the cron crate's 1-7 numbering. Weekly only. */
  daysOfWeek: string[];
  /** 1-31. Monthly only. */
  dayOfMonth: string;
};

/** The IANA zone the browser is in, which is what a local time is relative to. */
export function getDefaultTimezone(): string {
  return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
}

/**
 * Whether `value` is a real `HH:MM` time, in range as well as in shape.
 *
 * The range check is the point: `buildCron` silently falls back to
 * {@link DEFAULT_TIME} for anything it cannot use, so a picker that accepted
 * `99:99` would report the schedule as valid, let it be saved, and store a
 * different time than the one on screen.
 */
export function isValidTime(value: string): boolean {
  const match = value.match(/^(\d{2}):(\d{2})$/);
  if (!match) return false;

  const [, hour, minute] = match;
  const h = Number(hour);
  const m = Number(minute);
  // Both bounds, though the digits-only pattern already rules out negatives.
  // A range check that only looks one way invites the next reader to widen the
  // pattern and not notice the other half was never there.
  return h >= 0 && h <= 23 && m >= 0 && m <= 59;
}

/**
 * Whether these parts describe a schedule that will be stored as shown.
 *
 * Every field {@link buildCron} would quietly substitute a fallback for, so a
 * picker can refuse to save rather than save something else. A weekly schedule
 * with no days selected builds an every-day cron, which is not what clearing
 * the last day is asking for.
 */
export function isValidCronParts(parts: CronParts): boolean {
  if (!isValidTime(parts.time)) return false;
  if (parts.frequency === 'week') {
    // Every value checked, not just the count: a stray day outside 1-7 would
    // build an expression the backend rejects, and "at least one selected" is
    // only the constraint the buttons happen to enforce today.
    return (
      parts.daysOfWeek.length > 0 &&
      parts.daysOfWeek.every((day) => DOW_VALUES.includes(day))
    );
  }
  const day = Number(parts.dayOfMonth);
  return Number.isInteger(day) && day >= 1 && day <= 31;
}

/** `HH:MM` from separate fields, falling back on anything out of range. */
function toTimeValue(hour: string, minute: string): string {
  const safeHour = Number(hour);
  const safeMinute = Number(minute);
  if (
    Number.isNaN(safeHour) ||
    Number.isNaN(safeMinute) ||
    safeHour < 0 ||
    safeHour > 23 ||
    safeMinute < 0 ||
    safeMinute > 59
  ) {
    return DEFAULT_TIME;
  }

  return `${String(safeHour).padStart(2, '0')}:${String(safeMinute).padStart(2, '0')}`;
}

/** `09:00` as the viewer's locale writes it, e.g. `9:00 AM`. */
export function formatTimeLabel(value: string): string {
  if (!isValidTime(value)) return value;
  const [hour, minute] = value.split(':').map(Number);
  const date = new Date(2026, 0, 1, hour, minute);
  return new Intl.DateTimeFormat(undefined, {
    hour: 'numeric',
    minute: '2-digit',
  }).format(date);
}

/** A day-of-week selection in words, collapsing the sets that have a name. */
function formatDayList(daysOfWeek: string[]): string {
  if (daysOfWeek.length === 0) return 'no days';
  const sorted = [...daysOfWeek].sort(
    (a, b) => DOW_VALUES.indexOf(a) - DOW_VALUES.indexOf(b)
  );
  if (sorted.length === 7) return 'every day';
  if (
    sorted.length === 5 &&
    sorted.every((d) => DEFAULT_WEEKDAYS.includes(d))
  ) {
    return 'weekdays';
  }
  if (sorted.length === 2 && sorted.includes('1') && sorted.includes('7')) {
    return 'weekends';
  }
  return sorted
    .map((d) => WEEKDAY_OPTIONS.find((opt) => opt.value === d)?.fullLabel)
    .filter(Boolean)
    .join(', ');
}

function nthSuffix(n: number): string {
  const tens = n % 100;
  if (tens >= 11 && tens <= 13) return 'th';
  switch (n % 10) {
    case 1:
      return 'st';
    case 2:
      return 'nd';
    case 3:
      return 'rd';
    default:
      return 'th';
  }
}

/**
 * A schedule in words, e.g. `weekdays at 9:00 AM`.
 *
 * Lower-case and un-punctuated so callers can drop it into their own sentence;
 * capitalize at the call site if it stands alone. `timezone` is appended in
 * parentheses when given, for surfaces where the zone is not obvious.
 */
export function describeCron(parts: CronParts, timezone?: string): string {
  const timeLabel = formatTimeLabel(parts.time);
  const zone = timezone ? ` (${timezone})` : '';

  if (parts.frequency === 'week') {
    return `${formatDayList(parts.daysOfWeek)} at ${timeLabel}${zone}`;
  }

  const day = Number(parts.dayOfMonth);
  if (Number.isInteger(day) && day >= 1 && day <= 31) {
    return `${day}${nthSuffix(day)} of each month at ${timeLabel}${zone}`;
  }
  return `each month at ${timeLabel}${zone}`;
}

/**
 * Expand a day-of-week field like `2,4,6` or `2-6` into single values.
 *
 * Returns `[]` when any part of the expression cannot be read, so the caller
 * falls back to defaults rather than silently dropping the days it understood.
 */
function expandDowExpression(expr: string): string[] {
  const parts = expr.split(',');
  const set = new Set<string>();
  for (const raw of parts) {
    const part = raw.trim();
    if (/^[1-7]$/.test(part)) {
      set.add(part);
      continue;
    }
    const range = part.match(/^([1-7])-([1-7])$/);
    if (range) {
      const [, lo, hi] = range;
      const loN = Number(lo);
      const hiN = Number(hi);
      if (loN <= hiN) {
        for (let n = loN; n <= hiN; n++) set.add(String(n));
        continue;
      }
    }
    return [];
  }
  return [...set].sort((a, b) => DOW_VALUES.indexOf(a) - DOW_VALUES.indexOf(b));
}

/** The parts a picker should start from, for anything unreadable. */
function fallbackParts(time: string = DEFAULT_TIME): CronParts {
  return {
    frequency: 'week',
    time,
    daysOfWeek: [...DEFAULT_WEEKDAYS],
    dayOfMonth: '1',
  };
}

/**
 * Read a cron expression back into the parts a picker edits.
 *
 * Lossy by design: this only recognizes the shapes {@link buildCron} produces,
 * and anything else falls back to a sane weekly default rather than throwing.
 * A schedule written by hand may therefore come back as something simpler than
 * what it says — the picker cannot represent it either way.
 *
 * `dayOfMonth: '*'` with `dayOfWeek: '*'` reads as `day`, the most specific
 * frequency that describes it. Callers that have no daily option should map it
 * to a weekly schedule with every day selected, which is the same expression.
 */
export function parseCron(cron: string): CronParts {
  return interpretCron(cron).parts;
}

/** Whether the shared recurrence controls can round-trip this expression. */
export function isCronRepresentable(cron: string): boolean {
  return interpretCron(cron).representable;
}

/**
 * A parse, plus whether the expression was one the pickers can actually say.
 *
 * The distinction matters to anything comparing two expressions: every
 * unrepresentable cron parses to the *same* fallback, so treating those parses
 * as canonical would make two genuinely different schedules look identical.
 */
type CronReading = { parts: CronParts; representable: boolean };

function unrepresentable(time?: string): CronReading {
  return { parts: fallbackParts(time), representable: false };
}

/**
 * Whether a cron field is a single plain number in range.
 *
 * Ranges (`9-17`), lists (`0,30`) and steps (`*&#47;15`) are all valid to the
 * backend and none of them are something the picker can show, so they are
 * rejected here rather than read as whichever number happens to parse first.
 */
function isPlainCronNumber(field: string, min: number, max: number): boolean {
  if (!/^\d+$/.test(field)) return false;
  const value = Number(field);
  return value >= min && value <= max;
}

function interpretCron(cron: string): CronReading {
  const fields = cron.trim().split(/\s+/);
  // Six fields (`sec min hour dom mon dow`), or seven with a trailing year.
  if (fields.length !== 6 && fields.length !== 7) return unrepresentable();

  const [second, minute, hour, dayOfMonth, month, dayOfWeek, year] = fields;
  const time = toTimeValue(hour, minute);

  // Every field the picker cannot express has to be reported, not just the
  // obvious ones. `toTimeValue` answers with the default for anything it cannot
  // read, so a range like `9-17` would otherwise pass as representable with the
  // hour silently reset to 09:00 — and `normalizeCron` would then rewrite a
  // real schedule into a different one, which is exactly what makes a genuine
  // edit compare equal and never get sent.
  if (!isPlainCronNumber(second, 0, 59)) return unrepresentable(time);
  if (!isPlainCronNumber(minute, 0, 59)) return unrepresentable(time);
  if (!isPlainCronNumber(hour, 0, 23)) return unrepresentable(time);

  // Seconds are the owner's — `30 0 9 * * *` means 09:00:30 — and the picker
  // only builds whole minutes, so anything else is not ours to rewrite.
  if (Number(second) !== 0) return unrepresentable(time);

  // A year constraint is a real part of the schedule and the picker has no way
  // to show it, so an expression carrying one is not ours to rewrite.
  if (year !== undefined && year !== '*') return unrepresentable(time);
  if (month !== '*') return unrepresentable(time);

  if (dayOfMonth === '*') {
    if (dayOfWeek === '*') {
      // Every day, said the way the picker says it.
      return {
        parts: {
          frequency: 'week',
          time,
          daysOfWeek: [...DOW_VALUES],
          dayOfMonth: '1',
        },
        representable: true,
      };
    }
    const days = expandDowExpression(dayOfWeek);
    if (days.length > 0) {
      return {
        parts: { frequency: 'week', time, daysOfWeek: days, dayOfMonth: '1' },
        representable: true,
      };
    }
    return unrepresentable(time);
  }

  // Monthly: a specific day-of-month with no day-of-week constraint.
  if (dayOfWeek === '*' && /^(?:[1-9]|[12]\d|3[01])$/.test(dayOfMonth)) {
    return {
      parts: {
        frequency: 'month',
        time,
        daysOfWeek: [...DEFAULT_WEEKDAYS],
        dayOfMonth,
      },
      representable: true,
    };
  }

  return unrepresentable(time);
}

/**
 * A cron expression in the one form the pickers write it.
 *
 * `0 0 9 * * *` and `0 0 9 * * 1,2,3,4,5,6,7` are the same schedule spelled two
 * ways, and which one you hold depends on what last wrote it. Callers comparing
 * two expressions for "did this change?" want them to agree, since a difference
 * that is only spelling still reads as an edit — and on a reminder an edit
 * resets state the owner cares about.
 *
 * Both spellings parse to the same parts, so rebuilding is the whole job.
 */
export function normalizeCron(cron: string): string {
  const { parts, representable } = interpretCron(cron);

  // Anything the pickers cannot express is returned untouched. Every such
  // expression parses to the same fallback, so normalizing them would make two
  // different schedules compare equal — and a comparison that says "unchanged"
  // about a real change silently discards the edit.
  return representable ? buildCron(parts) : cron;
}

/** Build the six-field expression the backend expects. */
export function buildCron(parts: CronParts): string {
  const [hour, minute] = (isValidTime(parts.time) ? parts.time : DEFAULT_TIME)
    .split(':')
    .map((value) => Number(value));

  if (parts.frequency === 'week') {
    const days = parts.daysOfWeek.length
      ? [...parts.daysOfWeek]
          .sort((a, b) => DOW_VALUES.indexOf(a) - DOW_VALUES.indexOf(b))
          .join(',')
      : '*';
    return `0 ${minute} ${hour} * * ${days}`;
  }

  const day = Number(parts.dayOfMonth);
  const safeDay = Number.isInteger(day) && day >= 1 && day <= 31 ? day : 1;
  return `0 ${minute} ${hour} ${safeDay} * *`;
}