@zerotal/scheduler 1.0.0

package/src/conventions.ts

@@ -0,0 +1,81 @@
+import type { ConcernDescriptor } from "@zerotal/core";
+import { Schedule } from "./Schedule.ts";
+import type { SchedulerManager } from "./SchedulerManager.ts";
+import type { ScheduledTask } from "./ScheduledTask.ts";
+import { frameworkLog } from "@zerotal/core/logger";
+
+function isScheduleClass(v: unknown): v is new () => Schedule {
+  return (
+    typeof v === "function" &&
+    v !== Schedule &&
+    (v as { prototype?: unknown }).prototype instanceof Schedule
+  );
+}
+
+/**
+ * Register one Schedule instance with the scheduler manager, translating its declarative
+ * settings into a configured ScheduledTask. Exported for testing.
+ */
+export function registerSchedule(
+  manager: SchedulerManager,
+  schedule: Schedule,
+  fallbackName: string,
+): ScheduledTask | undefined {
+  const name = schedule.name ?? fallbackName;
+  const builder = manager.job(name, () => schedule.handle());
+
+  let task: ScheduledTask;
+  if (typeof schedule.frequency === "function") {
+    task = schedule.frequency(builder);
+  } else if (schedule.cron) {
+    task = builder.cron(schedule.cron);
+  } else {
+    frameworkLog("scheduler").warn(`Schedule "${name}" defines no cron or frequency(); skipped`);
+    return undefined;
+  }
+
+  if (schedule.timezone) task.timezone(schedule.timezone);
+  if (schedule.withoutOverlapping) {
+    task.withoutOverlapping(
+      typeof schedule.withoutOverlapping === "object" ? schedule.withoutOverlapping : undefined,
+    );
+  }
+  if (schedule.environments) task.environments(schedule.environments);
+  if (schedule.inBackground) task.runInBackground();
+  if (schedule.between) task.between(schedule.between[0], schedule.between[1]);
+  if (schedule.unlessBetween)
+    task.unlessBetween(schedule.unlessBetween[0], schedule.unlessBetween[1]);
+  if (schedule.pingBefore) task.pingBefore(schedule.pingBefore);
+  if (schedule.pingAfter) task.pingAfter(schedule.pingAfter);
+  if (schedule.pingOnSuccess) task.pingOnSuccess(schedule.pingOnSuccess);
+  if (schedule.pingOnFailure) task.pingOnFailure(schedule.pingOnFailure);
+  if (schedule.appendOutputTo) task.appendOutputTo(schedule.appendOutputTo);
+  if (schedule.emailOutputTo) task.emailOutputTo(schedule.emailOutputTo);
+  if (typeof schedule.when === "function") task.when(() => schedule.when!());
+  if (typeof schedule.skip === "function") task.skip(() => schedule.skip!());
+
+  return task;
+}
+
+/**
+ * `app/schedules/` convention. Every `Schedule` subclass is instantiated and registered with the
+ * scheduler. Runs in worker (to execute) and console (so `schedule:list` can enumerate them);
+ * never in `web`, so HTTP instances don't run cron. Contributed by `SchedulerProvider`.
+ */
+export const schedulesConcern: ConcernDescriptor = {
+  name: "schedules",
+  order: 55,
+  dir: "app/schedules",
+  envs: ["worker", "console"],
+  register(mod, ctx) {
+    const manager = ctx.resolve<SchedulerManager>("scheduler");
+    if (!manager) {
+      frameworkLog("scheduler").warn('app/schedules: "scheduler" binding not available; skipped');
+      return;
+    }
+    for (const exported of Object.values(mod)) {
+      if (!isScheduleClass(exported)) continue;
+      registerSchedule(manager, new exported(), exported.name);
+    }
+  },
+};

package/src/events.ts

@@ -0,0 +1,41 @@
+/**
+ * The scheduler package's framework events, emitted on core's {@link FrameworkEvents}
+ * bus. Observability packages subscribe to them by kind (their class name).
+ */
+
+/**
+ * Emitted after a scheduled task finishes running.
+ * @category Scheduler
+ */
+export class TaskRan {
+  constructor(
+    readonly name: string,
+    readonly durationMs: number,
+    readonly ok: boolean,
+  ) {}
+}
+
+/**
+ * Emitted when a scheduled task throws during execution.
+ * @category Scheduler
+ */
+export class TaskFailed {
+  constructor(
+    readonly name: string,
+    readonly durationMs: number,
+    readonly error: string,
+  ) {}
+}
+
+/**
+ * Emitted when a scheduled task is skipped before running; `reason` records
+ * which guard skipped it (env, time window, `when()` condition, explicit skip,
+ * overlap prevention, or a held lock).
+ * @category Scheduler
+ */
+export class TaskSkipped {
+  constructor(
+    readonly name: string,
+    readonly reason: "env" | "window" | "when" | "skip" | "overlap" | "lock",
+  ) {}
+}

package/src/facades/Scheduler.ts

@@ -0,0 +1,11 @@
+import { createFacade } from "@zerotal/core";
+
+/**
+ * Static accessor for the scheduler manager. Use for fluent, inline schedule definitions
+ * (e.g. inside a provider). For convention-based schedules, extend the `Schedule` base class
+ * and place the file in `app/schedules/`.
+ *
+ * @example
+ * Scheduler.job("cleanup", () => purgeTempFiles()).dailyAt("02:00");
+ */
+export const Scheduler = createFacade("scheduler");

package/src/global.d.ts

@@ -0,0 +1,30 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// ── Bun globals ───────────────────────────────────────────────────────────
+// Bun extends Request with native route params (e.g. /users/:id → { id: '42' })
+interface Request {
+  readonly params?: Record<string, string>;
+}
+
+// ── SQLInstance: callable tagged-template + DB methods ────────────────────
+interface SQLInstance {
+  <T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}
+
+// ── RedisInstance: minimal Bun.redis surface ──────────────────────────────
+interface RedisInstance {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  set(key: string, value: string, options: { ex: number }): Promise<void>;
+  del(...keys: string[]): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  keys(pattern: string): Promise<string[]>;
+  flushdb(): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { SchedulerManager, SchedulerBuilder } from "./SchedulerManager.ts";
+export { ScheduledTask } from "./ScheduledTask.ts";
+export { CronExpression } from "./CronExpression.ts";
+export { SchedulerProvider } from "./provider/SchedulerProvider.ts";
+
+// Convention-based scheduling: extend Schedule, drop it in app/schedules/.
+export { Schedule } from "./Schedule.ts";
+export { schedulesConcern, registerSchedule } from "./conventions.ts";
+
+// Fluent inline scheduling facade (renamed from the former `Schedule` facade).
+export { Scheduler } from "./facades/Scheduler.ts";
+
+export type {
+  TaskCallback,
+  TaskGuard,
+  TaskHook,
+  OutputMailer,
+  OverlapLockOptions,
+} from "./ScheduledTask.ts";
+
+// Config factory
+export { SchedulerConfig } from "./config.ts";
+export type { SchedulerConfigShape } from "./config.ts";
+
+// Framework instrumentation events (emitted on the core FrameworkEvents bus)
+export { TaskRan, TaskFailed, TaskSkipped } from "./events.ts";

package/src/monitor.ts

@@ -0,0 +1,140 @@
+/**
+ * Scheduler → monitor panel contribution.
+ *
+ * A cron task that silently stopped firing is one of the harder failures to
+ * notice: nothing errors, work just stops happening. Every task already tracks
+ * when it last ran, whether it succeeded, how long it took and when it is due
+ * next — this puts that in front of an operator.
+ *
+ * The panel's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, exactly as the observer bridges in
+ * `observability.ts` are: the scheduler depends on `@zerotal/monitor` not at
+ * all, and an app running tasks without the panel pulls in nothing extra.
+ */
+import type { Application } from "@zerotal/core";
+import type { SchedulerManager } from "./SchedulerManager.ts";
+
+type Row = Record<string, unknown>;
+type Tone = "default" | "good" | "warn" | "bad";
+
+/** The slice of the monitor panel's contribution surface this module uses. */
+interface MonitorPanelSink {
+  enabled(id: string): boolean;
+  section(section: {
+    id: string;
+    label: string;
+    group?: string;
+    sort?: number;
+    resolve(range: string): {
+      stats?: Array<{
+        label: string;
+        value: string | number;
+        detail?: string;
+        tone?: Tone;
+        percent?: number;
+      }>;
+      tables?: Array<{
+        title: string;
+        columns: Array<{
+          key: string;
+          label: string;
+          align?: "start" | "end";
+          mono?: boolean;
+          format?: (value: unknown, row: Row) => string;
+          tone?: (value: unknown, row: Row) => Tone | null;
+        }>;
+        rows: Row[];
+        empty?: string;
+      }>;
+    };
+  }): void;
+}
+
+function formatWhen(value: unknown): string {
+  if (value === null || value === undefined) return "—";
+  const date = value instanceof Date ? value : new Date(String(value));
+  return Number.isNaN(date.getTime()) ? "—" : date.toLocaleString();
+}
+
+function formatDuration(value: unknown): string {
+  if (typeof value !== "number") return "—";
+  return value < 1000 ? `${Math.round(value)} ms` : `${(value / 1000).toFixed(1)} s`;
+}
+
+/**
+ * Contribute the scheduled-tasks section to the monitor panel, when one is
+ * installed. Call from `SchedulerProvider.onBooting()`.
+ */
+export function installSchedulerMonitor(app: Application): void {
+  const panel = app.container.tryMake("monitor.panel" as never) as MonitorPanelSink | undefined;
+  if (!panel?.enabled("scheduler")) return;
+
+  panel.section({
+    id: "scheduler",
+    label: "Scheduled tasks",
+    group: "Infrastructure",
+    // The manager is resolved at render time rather than captured here: tasks
+    // can be registered after boot, and the panel re-reads on every refresh.
+    // Going through the container rather than the facade also keeps this
+    // callable outside a booted app, which is what makes it testable.
+    resolve: () => {
+      const scheduler = app.container.tryMake("scheduler") as SchedulerManager | null;
+      const tasks = scheduler ? [...scheduler.tasks.values()] : [];
+      const failing = tasks.filter((t) => t.lastOk === false);
+      const neverRun = tasks.filter((t) => t.lastRunAt === undefined);
+
+      return {
+        stats: [
+          { label: "Tasks", value: tasks.length },
+          {
+            label: "Running now",
+            value: tasks.filter((t) => t.isRunning).length,
+          },
+          {
+            label: "Failing",
+            value: failing.length,
+            tone: failing.length > 0 ? "bad" : "good",
+            ...(failing.length > 0 ? { detail: failing.map((t) => t.name).join(", ") } : {}),
+          },
+          {
+            label: "Never run",
+            value: neverRun.length,
+            tone: neverRun.length > 0 ? "warn" : "default",
+          },
+        ],
+        tables: [
+          {
+            title: "Tasks",
+            empty: "No tasks are scheduled.",
+            columns: [
+              { key: "name", label: "Task" },
+              { key: "schedule", label: "Cron", mono: true },
+              {
+                key: "status",
+                label: "Last result",
+                tone: (v) => (v === "Failed" ? "bad" : v === "OK" ? "good" : null),
+              },
+              { key: "lastRunAt", label: "Last run", format: formatWhen },
+              { key: "durationMs", label: "Duration", align: "end", format: formatDuration },
+              { key: "nextRunAt", label: "Next run", format: formatWhen },
+            ],
+            rows: tasks.map((t) => ({
+              name: t.name,
+              schedule: t.schedule,
+              status: t.isRunning
+                ? "Running"
+                : t.lastOk === undefined
+                  ? "Never run"
+                  : t.lastOk
+                    ? "OK"
+                    : "Failed",
+              lastRunAt: t.lastRunAt ?? null,
+              durationMs: t.lastDurationMs ?? null,
+              nextRunAt: t.nextRunAt(),
+            })),
+          },
+        ],
+      };
+    },
+  });
+}

package/src/observability.ts

@@ -0,0 +1,124 @@
+/**
+ * Scheduler → observer bridges. The scheduler emits its own `TaskRan` / `TaskFailed`
+ * / `TaskSkipped` framework events on the core `FrameworkEvents` bus; this module
+ * forwards them to whichever observer packages are installed.
+ *
+ * Each observer's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, so the scheduler depends on none of
+ * the observer packages — installing or removing an observer requires no change here.
+ */
+import { FrameworkEvents } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { TaskRan, TaskFailed, TaskSkipped } from "./events.ts";
+
+/** The subset of the telemetry tracer this bridge calls (bound as `telemetry`). */
+interface TelemetrySink {
+  recordCompleted(
+    name: string,
+    durationMs: number,
+    options?: {
+      kind?: "internal" | "server" | "client" | "producer" | "consumer";
+      attributes?: Record<string, string | number | boolean>;
+      status?: "ok" | "error";
+      errorMessage?: string;
+    },
+  ): unknown;
+}
+
+/** The subset of the monitor store this bridge calls (bound as `monitor.store`). */
+interface MonitorSink {
+  recordEvent(e: {
+    kind: string;
+    label: string;
+    status?: "ok" | "warn" | "bad" | "info";
+    route?: string | null;
+    data?: Record<string, unknown>;
+  }): void;
+}
+
+/** The subset of the logger this bridge calls (bound as `log`). */
+interface LogSink {
+  info(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>, error?: unknown): void;
+}
+
+/**
+ * Subscribe the scheduler's events to every installed observer. Returns a disposer
+ * that removes every subscription; call it from the scheduler provider's `onStopping()`.
+ */
+export function installSchedulerObservability(app: Application): () => void {
+  const unsubs: Array<() => void> = [];
+
+  const tracer = app.container.tryMake("telemetry" as never) as TelemetrySink | undefined;
+  if (tracer) {
+    unsubs.push(
+      FrameworkEvents.on(TaskRan, (e) => {
+        void tracer.recordCompleted("schedule.task", e.durationMs, {
+          attributes: { "task.name": e.name },
+          status: e.ok ? "ok" : "error",
+        });
+      }),
+      FrameworkEvents.on(TaskFailed, (e) => {
+        void tracer.recordCompleted("schedule.task", e.durationMs, {
+          attributes: { "task.name": e.name },
+          status: "error",
+          errorMessage: e.error,
+        });
+      }),
+    );
+  }
+
+  const store = app.container.tryMake("monitor.store" as never) as MonitorSink | undefined;
+  if (store) {
+    unsubs.push(
+      FrameworkEvents.on(TaskRan, (e) =>
+        store.recordEvent({
+          kind: "task",
+          label: e.name,
+          status: e.ok ? "ok" : "bad",
+          route: null,
+          data: { ms: e.durationMs },
+        }),
+      ),
+      FrameworkEvents.on(TaskFailed, (e) =>
+        store.recordEvent({
+          kind: "task",
+          label: e.name,
+          status: "bad",
+          route: null,
+          data: { ms: e.durationMs, detail: e.error },
+        }),
+      ),
+      FrameworkEvents.on(TaskSkipped, (e) =>
+        store.recordEvent({
+          kind: "task",
+          label: e.name,
+          status: "info",
+          route: null,
+          data: { detail: e.reason },
+        }),
+      ),
+    );
+  }
+
+  const log = app.container.tryMake("log" as never) as LogSink | undefined;
+  if (log) {
+    unsubs.push(
+      FrameworkEvents.on(TaskRan, (e) => {
+        if (e.ok) log.info("Scheduled task ran", { name: e.name, durationMs: e.durationMs });
+        else log.error("Scheduled task failed", { name: e.name, durationMs: e.durationMs });
+      }),
+      FrameworkEvents.on(TaskFailed, (e) =>
+        log.error(
+          "Scheduled task threw",
+          { name: e.name, durationMs: e.durationMs },
+          new Error(e.error),
+        ),
+      ),
+    );
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/provider/SchedulerProvider.ts

@@ -0,0 +1,65 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { LockManager } from "@zerotal/core/lock";
+import { SchedulerManager } from "../SchedulerManager.ts";
+import { ScheduledTask } from "../ScheduledTask.ts";
+import { schedulesConcern } from "../conventions.ts";
+import { installSchedulerObservability } from "../observability.ts";
+import { installSchedulerMonitor } from "../monitor.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    scheduler: SchedulerManager;
+  }
+}
+
+export class SchedulerProvider extends ServiceProvider {
+  static override provides = ["scheduler"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker"];
+
+  private _disposeObservability: (() => void) | undefined = undefined;
+
+  override onRegister(): void {
+    // Convention-based auto-discovery of app/schedules. (Optional-chained so bare-container
+    // unit tests with a minimal app stub don't need to stub registerConcern.)
+    this.app.registerConcern?.(schedulesConcern);
+
+    this.app.container.singleton("scheduler", () => new SchedulerManager());
+  }
+
+  override async onBooting(): Promise<void> {
+    await this.app.container.make("scheduler");
+
+    // Offer the scheduled-tasks section to the monitor panel, if one is
+    // installed. The panel reads its section registry when it renders, so
+    // contributing during the booting phase is early enough.
+    installSchedulerMonitor(this.app);
+  }
+
+  override async onBooted(): Promise<void> {
+    this._disposeObservability = installSchedulerObservability(this.app);
+
+    // Wire the distributed lock for cross-process withoutOverlapping. Falls back to
+    // the in-process guard when no LockProvider is registered.
+    ScheduledTask.lockManager = (this.app.container.tryMake("lock") as LockManager | null) ?? null;
+
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+    runner.registerLazy("schedule:list", () =>
+      import("../commands/ScheduleListCommand.ts").then((m) => m.ScheduleListCommand),
+    );
+  }
+
+  override async onStarted(): Promise<void> {
+    const scheduler = this.app.container.makeSync("scheduler") as SchedulerManager;
+    scheduler.start();
+  }
+
+  override async onStopped(): Promise<void> {
+    this._disposeObservability?.();
+    this._disposeObservability = undefined;
+
+    const scheduler = this.app.container.tryMake("scheduler") as SchedulerManager | undefined;
+    scheduler?.stop();
+  }
+}