@smitejs/jobs 2.0.0-SNAPSHOT

package/src/schedule.ts

@@ -0,0 +1,196 @@
+const MINUTE_MS = 60_000;
+const CRON_FIELDS = 5;
+const LOOK_AHEAD_MS = 366 * 24 * 60 * MINUTE_MS;
+
+/**
+ * A job run schedule: either a POSIX cron expression (minute hour day-of-month
+ * month day-of-week; `0` and `7` both mean Sunday) or a fixed interval in
+ * milliseconds.
+ *
+ * @group Types
+ */
+export type JobSchedule =
+  | { readonly kind: "cron"; readonly expression: string }
+  | { readonly kind: "interval"; readonly milliseconds: number };
+
+/**
+ * Builds a cron schedule from a 5-field POSIX expression. Every field accepts
+ * a bare value (`*`, `n`), a range (`a-b`), a range with a step (`a-b/n`), a
+ * wildcard with a step (for example `*` followed by `/n`), or a
+ * comma-separated list of any of those.
+ *
+ * @group Builders
+ * @example Schedule a job on a cron expression
+ */
+export const cron = (expression: string): JobSchedule => {
+  compileCron(expression);
+  return { kind: "cron", expression };
+};
+
+/**
+ * Builds a fixed-interval schedule from a duration in milliseconds.
+ *
+ * @group Builders
+ */
+export const interval = (milliseconds: number): JobSchedule => ({
+  kind: "interval",
+  milliseconds,
+});
+
+type Range = { readonly min: number; readonly max: number };
+
+/** Predicate deciding whether a single field value is allowed. */
+export type FieldMatcher = (value: number) => boolean;
+
+/** A compiled cron expression: five field matchers plus wildcard flags. */
+export interface CompiledCron {
+  readonly minute: FieldMatcher;
+  readonly hour: FieldMatcher;
+  readonly dayOfMonth: FieldMatcher;
+  readonly month: FieldMatcher;
+  readonly dayOfWeek: FieldMatcher;
+  readonly dayOfMonthIsStar: boolean;
+  readonly dayOfWeekIsStar: boolean;
+}
+
+const compileToken = (token: string, { min, max }: Range): FieldMatcher => {
+  const stepMatch = /^(.+?)\/(\d+)$/u.exec(token);
+  const step = stepMatch === null ? 1 : Number(stepMatch[2]);
+  const base = stepMatch === null ? token : (stepMatch[1] ?? "*");
+
+  let low: number;
+  let high: number;
+  if (base === "*") {
+    low = min;
+    high = max;
+  } else {
+    const range = /^(\d+)(?:-(\d+))?$/u.exec(base);
+    if (range === null) {
+      throw new Error(`Invalid cron token '${token}'.`);
+    }
+    low = Number(range[1]);
+    high = range[2] === undefined ? low : Number(range[2]);
+    if (low < min || high > max || low > high) {
+      throw new Error(`Cron token '${token}' is out of range [${min}–${max}].`);
+    }
+  }
+
+  return (value: number): boolean =>
+    value >= low && value <= high && (value - low) % step === 0;
+};
+
+const compileField = (field: string, range: Range): [FieldMatcher, boolean] => {
+  const tokens = field.split(",").map((token) => token.trim());
+  if (tokens.length === 0 || tokens.some((token) => token.length === 0)) {
+    throw new Error(`Empty cron field '${field}'.`);
+  }
+  const matchers = tokens.map((token) => compileToken(token, range));
+  return [
+    (value: number): boolean => matchers.some((matcher) => matcher(value)),
+    tokens.every((token) => token === "*"),
+  ];
+};
+
+/**
+ * Parses a 5-field POSIX cron expression into {@link CompiledCron}.
+ *
+ * @group Internals
+ */
+export function compileCron(expr: string): CompiledCron {
+  const fields = expr.trim().split(/\s+/u);
+  if (fields.length !== CRON_FIELDS) {
+    throw new Error(
+      `Cron expression '${expr}' must have exactly ${CRON_FIELDS} fields.`,
+    );
+  }
+  const [min, hour, dayOfMonth, month, dayOfWeek] = fields;
+  if (
+    min === undefined ||
+    hour === undefined ||
+    dayOfMonth === undefined ||
+    month === undefined ||
+    dayOfWeek === undefined
+  ) {
+    throw new Error(`Invalid cron expression '${expr}'.`);
+  }
+
+  const [minute] = compileField(min, { min: 0, max: 59 });
+  const [hourMatcher] = compileField(hour, { min: 0, max: 23 });
+  const [domMatcher, domStar] = compileField(dayOfMonth, { min: 1, max: 31 });
+  const [monthMatcher] = compileField(month, { min: 1, max: 12 });
+  const [dowMatcher, dowStar] = compileField(dayOfWeek, { min: 0, max: 7 });
+
+  return {
+    minute,
+    hour: hourMatcher,
+    dayOfMonth: domMatcher,
+    month: monthMatcher,
+    dayOfWeek: (value: number): boolean =>
+      dowMatcher(value) || (value === 0 && dowMatcher(7)),
+    dayOfMonthIsStar: domStar,
+    dayOfWeekIsStar: dowStar,
+  };
+}
+
+const dayAllows = (
+  dom: FieldMatcher,
+  dow: FieldMatcher,
+  domStar: boolean,
+  dowStar: boolean,
+  date: number,
+  weekday: number,
+): boolean => {
+  if (!domStar && !dowStar) {
+    return dom(date) || dow(weekday);
+  }
+  if (dowStar) {
+    return dom(date);
+  }
+  return dow(weekday);
+};
+
+/**
+ * Computes the next moment `schedule` fires at or after `from`. Cron fires on
+ * the first matching minute boundary; interval schedules fire `milliseconds`
+ * after `from`. Returns `null` when no cron fire is within the look-ahead
+ * horizon (one year).
+ *
+ * @group Executor
+ * @example Compute the next cron fire
+ */
+export function nextFire(schedule: JobSchedule, from: Date): Date | null {
+  if (schedule.kind === "interval") {
+    return new Date(from.getTime() + schedule.milliseconds);
+  }
+
+  const compiled = compileCron(schedule.expression);
+  const start = new Date(from);
+  start.setUTCSeconds(0, 0);
+  start.setUTCMinutes(start.getUTCMinutes() + 1);
+
+  const deadline = start.getTime() + LOOK_AHEAD_MS;
+  for (
+    let cursor = start;
+    cursor.getTime() <= deadline;
+    cursor = new Date(cursor.getTime() + MINUTE_MS)
+  ) {
+    const minuteMatch = compiled.minute(cursor.getUTCMinutes());
+    const hourMatch = compiled.hour(cursor.getUTCHours());
+    const monthMatch = compiled.month(cursor.getUTCMonth() + 1);
+    if (!minuteMatch || !hourMatch || !monthMatch) {
+      continue;
+    }
+    const dayMatch = dayAllows(
+      compiled.dayOfMonth,
+      compiled.dayOfWeek,
+      compiled.dayOfMonthIsStar,
+      compiled.dayOfWeekIsStar,
+      cursor.getUTCDate(),
+      cursor.getUTCDay(),
+    );
+    if (dayMatch) {
+      return cursor;
+    }
+  }
+  return null;
+}

package/src/scheduler.ts

@@ -0,0 +1,127 @@
+import { finalizeDescriptor } from "@smitejs/core";
+import type { AppDescriptor } from "@smitejs/core";
+import type { EmptySignal } from "@smitejs/handlers";
+import { fire } from "@smitejs/handlers";
+import { jobsOf } from "./collector.js";
+import type { CollectedJob } from "./collector.js";
+import { nextFire } from "./schedule.js";
+
+/** A timer id from `setTimeout` or `setInterval`. */
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+/**
+ * Options for {@link scheduler}.
+ *
+ * @group Executor
+ */
+export interface SchedulerOptions {
+  /** Invoked before each job runs, with the job id and fire time. */
+  readonly onRun?: (entry: {
+    readonly id: string;
+    readonly at: number;
+  }) => void;
+  /** Invoked when a job's run function throws or rejects. */
+  readonly onError?: (entry: {
+    readonly id: string;
+    readonly error: unknown;
+  }) => void;
+  /** Also arms the schedule clock when `start()` runs. */
+  readonly start?: boolean;
+}
+
+/**
+ * A runtime handle returned by {@link scheduler}: the collected jobs, plus
+ * `start` (fire everything once) and `tick`/`stop` to drive the fire clock.
+ *
+ * @group Executor
+ */
+export interface JobScheduler {
+  readonly jobs: readonly CollectedJob[];
+  /** Runs every job once immediately; with `{ start: true }` arms the clock. */
+  readonly start: () => Promise<void>;
+  /** Arms each job's cron/interval timer and returns a one-shot `stop`. */
+  readonly tick: () => () => void;
+  /** Clears every armed timer. */
+  readonly stop: () => void;
+}
+
+const signalOf = (job: { readonly id: string }): EmptySignal => fire(job.id);
+
+/**
+ * Turns an app into a runtime job scheduler. Walks the app's `jobs.job` IR
+ * tree via child refs — never the global registry — so it keeps working in
+ * production bundles where collect mode is folded out. `start()` fires every
+ * job once; `tick()` arms the cron/interval timers and returns a `stop` for
+ * shutdown; `{ start: true }` arms automatically. `onRun`/`onError` observe
+ * each fire.
+ *
+ * @group Executor
+ * @example Schedule an app's jobs
+ */
+export function scheduler(
+  app: AppDescriptor,
+  options: SchedulerOptions = {},
+): JobScheduler {
+  finalizeDescriptor(app);
+
+  const jobs = jobsOf(app);
+  const timers = new Set<TimerHandle>();
+
+  const runJob = async (job: CollectedJob): Promise<void> => {
+    options.onRun?.({ id: job.id, at: Date.now() });
+    try {
+      await Promise.resolve(job.run(signalOf(job)));
+    } catch (error) {
+      options.onError?.({ id: job.id, error });
+    }
+  };
+
+  const armJob = (job: CollectedJob): void => {
+    if (job.schedule.kind === "interval") {
+      const timer = setInterval(() => {
+        void runJob(job);
+      }, job.schedule.milliseconds);
+      timers.add(timer);
+      return;
+    }
+
+    const armNext = (): void => {
+      const next = nextFire(job.schedule, new Date());
+      if (next === null) return;
+      const timer = setTimeout(
+        () => {
+          timers.delete(timer);
+          void runJob(job);
+          armNext();
+        },
+        Math.max(0, next.getTime() - Date.now()),
+      );
+      timers.add(timer);
+    };
+    armNext();
+  };
+
+  const stop = (): void => {
+    for (const timer of timers) clearTimer(timer);
+    timers.clear();
+  };
+
+  return {
+    jobs,
+    start: async () => {
+      for (const job of jobs) {
+        await runJob(job);
+      }
+      if (options.start === true) {
+        for (const job of jobs) armJob(job);
+      }
+    },
+    tick: () => {
+      for (const job of jobs) armJob(job);
+      return stop;
+    },
+    stop,
+  };
+}
+
+const clearTimer = (timer: TimerHandle): void => clearInterval(timer);

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"],
+  "references": [{ "path": "../core" }, { "path": "../handlers" }]
+}