Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

14.0 KB
Raw Blame
// 5-field cron parser + IANA-timezone-aware nextRun + cronToHuman.
// Zero npm dependencies (uses Intl.DateTimeFormat for tz wall-clock conversion).
//
// Field order: minute hour dayOfMonth month dayOfWeek
// Supports: '*', 'N', 'N-M', 'N-M/S', '*/S', 'N,M,O' (combination), dayOfWeek 7=Sun.
// Vixie-cron day matching: when both DOM and DOW are restricted, OR; else only the restricted one.

export type CronField = readonly number[];

export interface ParsedCron {
  minute: CronField; // 0-59
  hour: CronField; // 0-23
  dayOfMonth: CronField; // 1-31
  month: CronField; // 1-12
  dayOfWeek: CronField; // 0-6 (Sun=0)
  domRestricted: boolean;
  dowRestricted: boolean;
  expr: string;
}

interface FieldRange {
  min: number;
  max: number;
}

const RANGES: Record<keyof Pick<ParsedCron, 'minute' | 'hour' | 'dayOfMonth' | 'month' | 'dayOfWeek'>, FieldRange> = {
  minute: { min: 0, max: 59 },
  hour: { min: 0, max: 23 },
  dayOfMonth: { min: 1, max: 31 },
  month: { min: 1, max: 12 },
  dayOfWeek: { min: 0, max: 6 },
};

export function parseCron(expr: string): ParsedCron {
  const trimmed = expr.trim();
  const parts = trimmed.split(/\s+/);
  if (parts.length !== 5) {
    throw new Error(`Invalid cron expression (need 5 fields): ${expr}`);
  }
  const [mi, h, dom, mo, dow] = parts;
  const dowField = parseField(dow, RANGES.dayOfWeek, /* allowDowSeven */ true);
  return {
    minute: parseField(mi, RANGES.minute),
    hour: parseField(h, RANGES.hour),
    dayOfMonth: parseField(dom, RANGES.dayOfMonth),
    month: parseField(mo, RANGES.month),
    dayOfWeek: dowField,
    domRestricted: dom !== '*',
    dowRestricted: dow !== '*',
    expr: trimmed,
  };
}

function parseField(token: string, range: FieldRange, allowDowSeven = false): number[] {
  const out = new Set<number>();
  const effectiveMax = allowDowSeven ? 7 : range.max;
  for (const part of token.split(',')) {
    if (part.length === 0) {
      throw new Error(`Empty cron field segment in "${token}"`);
    }
    const stepSegments = part.split('/');
    if (stepSegments.length > 2) {
      throw new Error(`Invalid step syntax in "${part}"`);
    }
    const [rangePart, stepPart] = stepSegments;
    let step = 1;
    if (stepPart !== undefined) {
      step = parseDecimalInteger(stepPart);
      if (!Number.isInteger(step) || step <= 0) {
        throw new Error(`Invalid step "${stepPart}" in "${part}"`);
      }
    }
    let lo: number;
    let hi: number;
    if (rangePart === '*') {
      lo = range.min;
      hi = range.max;
    } else if (rangePart.includes('-')) {
      const rangeSegments = rangePart.split('-');
      if (rangeSegments.length !== 2) {
        throw new Error(`Invalid range "${rangePart}" in "${part}"`);
      }
      const [aStr, bStr] = rangeSegments;
      lo = parseDecimalInteger(aStr);
      hi = parseDecimalInteger(bStr);
      if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo > hi) {
        throw new Error(`Invalid range "${rangePart}" in "${part}"`);
      }
    } else {
      const v = parseDecimalInteger(rangePart);
      if (!Number.isInteger(v)) {
        throw new Error(`Invalid value "${rangePart}" in "${part}"`);
      }
      lo = v;
      // "N/S" expands as "N,N+S,N+2S,...,max"
      hi = stepPart !== undefined ? effectiveMax : v;
    }
    if (lo < range.min || hi > effectiveMax) {
      throw new Error(`Field "${part}" out of range [${range.min}, ${effectiveMax}]`);
    }
    for (let v = lo; v <= hi; v += step) {
      const normalized = allowDowSeven && v === 7 ? 0 : v;
      out.add(normalized);
    }
  }
  return [...out].sort((a, b) => a - b);
}

function parseDecimalInteger(value: string): number {
  return /^\d+$/.test(value) ? Number(value) : Number.NaN;
}

// ---------- timezone helpers ----------

const FORMATTER_CACHE = new Map<string, Intl.DateTimeFormat>();

function getFormatter(tz: string): Intl.DateTimeFormat {
  let f = FORMATTER_CACHE.get(tz);
  if (!f) {
    f = new Intl.DateTimeFormat('en-US', {
      timeZone: tz,
      year: 'numeric',
      month: 'numeric',
      day: 'numeric',
      hour: 'numeric',
      minute: 'numeric',
      second: 'numeric',
      weekday: 'short',
      hour12: false,
    });
    FORMATTER_CACHE.set(tz, f);
  }
  return f;
}

export interface WallClock {
  y: number;
  mo: number;
  d: number;
  h: number;
  mi: number;
  s: number;
  dow: number;
}

const DOW_MAP: Record<string, number> = {
  Sun: 0,
  Mon: 1,
  Tue: 2,
  Wed: 3,
  Thu: 4,
  Fri: 5,
  Sat: 6,
};

// Exported so siblings (monthlyClamp) can build wall-clock-aware logic without
// duplicating the Intl.DateTimeFormat plumbing. Not part of the public package API.
export function wallClock(epochMs: number, tz: string): WallClock {
  const parts = getFormatter(tz).formatToParts(epochMs);
  const map: Record<string, string> = {};
  for (const p of parts) {
    if (p.type !== 'literal') {
      map[p.type] = p.value;
    }
  }
  let h = parseInt(map.hour, 10);
  if (h === 24) h = 0; // some impls return "24" for midnight
  return {
    y: parseInt(map.year, 10),
    mo: parseInt(map.month, 10),
    d: parseInt(map.day, 10),
    h,
    mi: parseInt(map.minute, 10),
    s: parseInt(map.second, 10),
    dow: DOW_MAP[map.weekday] ?? 0,
  };
}

// ms-offset between wall-clock-as-UTC and the actual epoch (positive = tz ahead of UTC)
function tzOffsetMs(epochMs: number, tz: string): number {
  const w = wallClock(epochMs, tz);
  const wallAsUtc = Date.UTC(w.y, w.mo - 1, w.d, w.h, w.mi, w.s);
  const epochSec = Math.floor(epochMs / 1000) * 1000;
  return wallAsUtc - epochSec;
}

// Whether the epoch instant reads exactly (y,mo,d,h,mi) on the wall clock in tz.
function wallClockEquals(
  epochMs: number,
  y: number,
  mo: number,
  d: number,
  h: number,
  mi: number,
  tz: string,
): boolean {
  const w = wallClock(epochMs, tz);
  return w.y === y && w.mo === mo && w.d === d && w.h === h && w.mi === mi;
}

// Convert wall-clock (y,mo,d,h,mi) in tz back to epoch ms.
//
// DST edges:
//  - Overlap (fall-back, wall time occurs twice): resolves to the LATER
//    occurrence. nextRun/nextMonthlyFire compare candidates against a strictly
//    increasing "from" instant; the earlier occurrence can lie in the past when
//    `from` is already inside the repeated hour, which made the scheduler
//    re-fire a finished schedule every tick until the wall clock left the
//    repeated hour.
//  - Gap (spring-forward, wall time never occurs): returns the instant the wall
//    clock reads the requested time plus the gap size (the post-transition
//    interpretation). Returning the pre-transition side made nextRun re-derive
//    the missing slot forever and exhaust MAX_ITERATIONS (~4.4s of blocking
//    Intl calls), quarantining the schedule and stalling the host tick loop.
// Exported for sibling use (see wallClock comment above).
export function fromWallClock(y: number, mo: number, d: number, h: number, mi: number, tz: string): number {
  const guess = Date.UTC(y, mo - 1, d, h, mi, 0);
  const off1 = tzOffsetMs(guess, tz);
  const candidate = guess - off1;
  const off2 = tzOffsetMs(candidate, tz);
  if (off2 === off1) {
    // Offsets agree, but a fall-back transition within the next hour can make
    // this wall time occur a second time; prefer that later occurrence.
    const offAfter = tzOffsetMs(candidate + 3600_000, tz);
    if (offAfter !== off1) {
      const later = guess - offAfter;
      if (wallClockEquals(later, y, mo, d, h, mi, tz)) return later;
    }
    return candidate;
  }
  const corrected = guess - off2;
  if (wallClockEquals(corrected, y, mo, d, h, mi, tz)) return corrected;
  // Nonexistent wall time: spring-forward gaps shrink the day, so the offset
  // that applies after the jump is the larger one — clamping there guarantees
  // the returned instant is at/after the transition, letting walkers exit the
  // gap instead of re-entering it.
  return guess - Math.min(off1, off2);
}

// ---------- nextRun ----------

const MAX_ITERATIONS = 366 * 24 * 60; // safety cap; smart walk converges much faster

export function nextRun(expr: string, fromMs: number, tz: string): number {
  const cron = parseCron(expr);
  // Snap to next minute boundary (cron resolution is 1 min)
  const startMs = Math.floor(fromMs / 60_000) * 60_000 + 60_000;
  let cur = startMs;

  for (let i = 0; i < MAX_ITERATIONS; i++) {
    const w = wallClock(cur, tz);

    if (!cron.month.includes(w.mo)) {
      const next = nextOrWrap(cron.month, w.mo);
      const wrapsYear = next <= w.mo;
      cur = fromWallClock(wrapsYear ? w.y + 1 : w.y, next, 1, 0, 0, tz);
      continue;
    }

    if (!matchesDay(cron, w)) {
      // Advance to start-of-next-day in tz
      const sod = fromWallClock(w.y, w.mo, w.d, 0, 0, tz);
      const nextDay = sod + 26 * 3600 * 1000; // +26h ensures we cross any DST gap
      const w2 = wallClock(nextDay, tz);
      cur = fromWallClock(w2.y, w2.mo, w2.d, 0, 0, tz);
      continue;
    }

    if (!cron.hour.includes(w.h)) {
      const next = nextOrWrap(cron.hour, w.h);
      if (next > w.h) {
        cur = fromWallClock(w.y, w.mo, w.d, next, 0, tz);
      } else {
        // wrap into next day
        const sod = fromWallClock(w.y, w.mo, w.d, 0, 0, tz);
        const nextDay = sod + 26 * 3600 * 1000;
        const w2 = wallClock(nextDay, tz);
        cur = fromWallClock(w2.y, w2.mo, w2.d, next, 0, tz);
      }
      continue;
    }

    if (!cron.minute.includes(w.mi)) {
      const next = nextOrWrap(cron.minute, w.mi);
      if (next > w.mi) {
        cur = fromWallClock(w.y, w.mo, w.d, w.h, next, tz);
      } else {
        // A sub-hour fall-back can leave us in the same wall-clock hour after
        // the UTC +1h hop below. Try every cron minute in the current wall
        // hour only for this wrap case: fromWallClock resolves an overlap to
        // its later occurrence, so a minute that wrapped numerically (for
        // example 01:45 after 01:50) can still be future in the repeated
        // segment. Gap conversion is accepted only when it round-trips to the
        // requested wall minute; otherwise the same clamped instant would be
        // selected on every iteration.
        const sameHourCandidates = cron.minute
          .map((minute) => fromWallClock(w.y, w.mo, w.d, w.h, minute, tz))
          .filter(
            (candidate, index) =>
              candidate > fromMs &&
              wallClockEquals(candidate, w.y, w.mo, w.d, w.h, cron.minute[index], tz),
          );
        if (sameHourCandidates.length > 0) {
          cur = Math.min(...sameHourCandidates);
          continue;
        }

        // Wrap into the next distinct wall-clock hour. A plain +1h UTC hop
        // can remain inside a repeated hour after a 30-minute fall-back, so
        // advance by at most four hourly probes until the wall hour changes.
        // The bound covers the DST transitions supported by this walker while
        // preventing an unbounded search inside a malformed schedule.
        const nextHourStart = fromWallClock(w.y, w.mo, w.d, w.h, 0, tz) + 3600_000;
        let probe = nextHourStart;
        let w2 = wallClock(probe, tz);
        for (let step = 0; step < 4 && sameWallHour(w2, w); step++) {
          probe += 3600_000;
          w2 = wallClock(probe, tz);
        }
        cur = fromWallClock(w2.y, w2.mo, w2.d, w2.h, next, tz);
      }
      continue;
    }

    return cur;
  }
  throw new Error(`Could not find next run within iteration limit for "${expr}"`);
}

function matchesDay(cron: ParsedCron, w: WallClock): boolean {
  const domMatch = cron.dayOfMonth.includes(w.d);
  const dowMatch = cron.dayOfWeek.includes(w.dow);
  if (cron.domRestricted && cron.dowRestricted) return domMatch || dowMatch;
  if (cron.domRestricted) return domMatch;
  if (cron.dowRestricted) return dowMatch;
  return true;
}

function nextOrWrap(list: CronField, current: number): number {
  for (const x of list) if (x > current) return x;
  return list[0];
}

function sameWallHour(a: WallClock, b: WallClock): boolean {
  return a.y === b.y && a.mo === b.mo && a.d === b.d && a.h === b.h;
}

// ---------- cronToHuman ----------
//
// English-only by design. Phase 6 (renderer UI) wraps this with an i18n layer
// (`apps/desktop/src/renderer/features/scheduler/lib/cronToHuman.ts`) that key-maps
// these strings to localized output. Do not add locale switches here — keep this
// pure and stable so the engine remains zero-dep.

const DOW_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

export function cronToHuman(expr: string): string {
  let cron: ParsedCron;
  try {
    cron = parseCron(expr);
  } catch {
    return expr;
  }
  const trimmed = expr.trim();

  // Common patterns
  switch (trimmed) {
    case '* * * * *':
      return 'Every minute';
    case '*/5 * * * *':
      return 'Every 5 minutes';
    case '*/10 * * * *':
      return 'Every 10 minutes';
    case '*/15 * * * *':
      return 'Every 15 minutes';
    case '*/30 * * * *':
      return 'Every 30 minutes';
    case '0 * * * *':
      return 'Every hour';
  }

  const parts: string[] = [];
  const minStar = cron.minute.length === 60;
  const hourStar = cron.hour.length === 24;

  if (cron.minute.length === 1 && cron.hour.length === 1) {
    parts.push(`At ${pad2(cron.hour[0])}:${pad2(cron.minute[0])}`);
  } else if (!minStar || !hourStar) {
    if (cron.minute.length === 1) {
      parts.push(`At minute ${cron.minute[0]} of hour ${formatList(cron.hour)}`);
    } else {
      parts.push(`At minute ${formatList(cron.minute)} of hour ${formatList(cron.hour)}`);
    }
  }

  if (cron.dowRestricted) {
    parts.push(`on ${cron.dayOfWeek.map((d) => DOW_NAMES[d]).join(',')}`);
  }
  if (cron.domRestricted) {
    parts.push(`on day-of-month ${formatList(cron.dayOfMonth)}`);
  }
  if (cron.month.length !== 12) {
    parts.push(`in ${cron.month.map((m) => MONTH_NAMES[m - 1]).join(',')}`);
  }

  return parts.length === 0 ? 'Every minute' : parts.join(' ');
}

function pad2(n: number): string {
  return n.toString().padStart(2, '0');
}

function formatList(list: CronField): string {
  if (list.length <= 4) return list.join(',');
  return `${list[0]},...,${list[list.length - 1]}`;
}