Cron: add scheduler, wakeups, and run history

src/cron/schedule.ts

@@ -0,0 +1,29 @@
+import { Cron } from "croner";
+import type { CronSchedule } from "./types.js";
+
+export function computeNextRunAtMs(
+  schedule: CronSchedule,
+  nowMs: number,
+): number | undefined {
+  if (schedule.kind === "at") {
+    return schedule.atMs > nowMs ? schedule.atMs : undefined;
+  }
+
+  if (schedule.kind === "every") {
+    const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+    const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+    if (nowMs <= anchor) return anchor;
+    const elapsed = nowMs - anchor;
+    const steps = Math.floor((elapsed + everyMs - 1) / everyMs);
+    return anchor + steps * everyMs;
+  }
+
+  const expr = schedule.expr.trim();
+  if (!expr) return undefined;
+  const cron = new Cron(expr, {
+    timezone: schedule.tz?.trim() || undefined,
+    catch: false,
+  });
+  const next = cron.nextRun(new Date(nowMs));
+  return next ? next.getTime() : undefined;
+}