@smitejs/jobs 2.0.0-SNAPSHOT

package/dist/scheduler.js

@@ -0,0 +1,79 @@
+import { finalizeDescriptor } from "@smitejs/core";
+import { fire } from "@smitejs/handlers";
+import { jobsOf } from "./collector.js";
+import { nextFire } from "./schedule.js";
+const signalOf = (job) => 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
+ * ```ts
+ * const handle = scheduler(app);
+ * const stop = handle.tick();
+ * ```
+ */
+export function scheduler(app, options = {}) {
+    finalizeDescriptor(app);
+    const jobs = jobsOf(app);
+    const timers = new Set();
+    const runJob = async (job) => {
+        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) => {
+        if (job.schedule.kind === "interval") {
+            const timer = setInterval(() => {
+                void runJob(job);
+            }, job.schedule.milliseconds);
+            timers.add(timer);
+            return;
+        }
+        const armNext = () => {
+            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 = () => {
+        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) => clearInterval(timer);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@smitejs/jobs",
+  "version": "2.0.0-SNAPSHOT",
+  "description": "Scheduled jobs for Smite: job descriptors with cron and interval schedules, a scheduler executor, and a collector.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/githiago-f/smite.git"
+  },
+  "homepage": "https://github.com/githiago-f/smite#readme",
+  "bugs": {
+    "url": "https://github.com/githiago-f/smite/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "!dist/**/*.test.*", "!dist/.tsbuildinfo"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@smitejs/core": "^2.0.0-SNAPSHOT",
+    "@smitejs/handlers": "^2.0.0-SNAPSHOT"
+  },
+  "sideEffects": false
+}

package/src/collector.ts

@@ -0,0 +1,44 @@
+import { childrenOf } from "@smitejs/core";
+import type { AppDescriptor, Descriptor } from "@smitejs/core";
+import type { EmptySignal } from "@smitejs/handlers";
+import type { JobSchedule } from "./schedule.js";
+
+/**
+ * A job as seen by artifact generators: its id, schedule, and the run function
+ * the scheduler invokes. `run` takes a zero-input signal.
+ *
+ * @group Collector
+ */
+export interface CollectedJob {
+  readonly id: string;
+  readonly schedule: JobSchedule;
+  readonly run: (signal: EmptySignal) => void | Promise<void>;
+}
+
+type JobNode = Descriptor<"jobs.job", { id: string; schedule: JobSchedule }>;
+type JobHandlerNode = Descriptor<
+  "jobs.handler",
+  { fn: (signal: EmptySignal) => void | Promise<void> }
+>;
+
+/**
+ * Walks an app's `jobs.job` children and returns the collected jobs with their
+ * schedules and run functions. Shared by artifact generators and the scheduler
+ * executor.
+ *
+ * @group Collector
+ * @example Collect an app's jobs
+ */
+export function jobsOf(app: AppDescriptor): readonly CollectedJob[] {
+  return childrenOf(app, "jobs.job").map((node) => {
+    const jobNode = node as JobNode;
+    const handler = childrenOf(node, "jobs.handler")[0] as
+      | JobHandlerNode
+      | undefined;
+    return {
+      id: jobNode.data.id,
+      schedule: jobNode.data.schedule,
+      run: handler?.data.fn ?? (() => undefined),
+    };
+  });
+}

package/src/docs.test.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { expandExamples } from "../../../scripts/inject-jsdoc-examples.mjs";
+import {
+  collectFiles,
+  collectTestSnippets,
+} from "../../../scripts/snippets.mjs";
+
+const packageName = "@smitejs/jobs";
+const rootDir = process.cwd();
+const srcDir = join(rootDir, "packages/jobs/src");
+
+const exampleReferences = async () => {
+  const { snippetIndex } = await collectTestSnippets({
+    packageName,
+    rootDir,
+    srcDir,
+  });
+  const files = await collectFiles(srcDir, (filePath) =>
+    filePath.endsWith(".ts"),
+  );
+  const references: Array<{ filePath: string; title: string }> = [];
+
+  for (const filePath of files) {
+    const source = await readFile(filePath, "utf8");
+    const exampleTag = /^(\s*\*[^\S\r\n]*)@example[^\S\r\n]+([^\r\n]+?)\s*$/gmu;
+    for (const match of source.matchAll(exampleTag)) {
+      references.push({ filePath, title: match[2]?.trim() ?? "" });
+    }
+  }
+
+  return { snippetIndex, references };
+};
+
+describe("documentation integrity", () => {
+  it("every @example resolves to a tested #section snippet", async () => {
+    const { snippetIndex, references } = await exampleReferences();
+    const missing = references
+      .filter(({ title }) => !snippetIndex.has(title.toLowerCase()))
+      .map(
+        ({ filePath, title }) =>
+          `- Missing tested snippet "${title}" in ${filePath}`,
+      );
+    expect(missing).toEqual([]);
+  });
+
+  it("renders each referenced snippet into a code block", async () => {
+    const { snippetIndex, snippets } = await collectTestSnippets({
+      packageName,
+      rootDir,
+      srcDir,
+    });
+    for (const snippet of snippets) {
+      const rendered = expandExamples(
+        ` * @example ${snippet.title}\n`,
+        snippetIndex,
+        packageName,
+        "synthetic.d.ts",
+      );
+      expect(rendered).toContain("```ts");
+      expect(rendered).toContain(snippet.code.split("\n")[0]);
+    }
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,176 @@
+import { childrenOf, clear, createApp, lookup } from "@smitejs/core";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  cron,
+  interval,
+  job,
+  jobs,
+  jobsOf,
+  nextFire,
+  scheduler,
+} from "./index.js";
+
+afterEach(() => clear());
+
+describe("schedules", () => {
+  it("computes a cron fire using a shared cron builder", () => {
+    // #section - Schedule a job on a cron expression
+    const everyFive = cron("5 * * * *");
+    // #endsection
+
+    expect(everyFive.kind).toBe("cron");
+    expect(
+      nextFire(everyFive, new Date("2026-01-01T00:00:00Z"))?.getTime(),
+    ).toBe(Date.UTC(2026, 0, 1, 0, 5, 0));
+  });
+
+  it("computes the first matching minute boundary", () => {
+    // #section - Compute the next cron fire
+    const workdayNine = cron("0 9-17 * * 1-5");
+    const monday = new Date("2026-01-05T00:00:00Z"); // 2026-01-05 is a Monday
+    const next = nextFire(workdayNine, monday);
+    // #endsection
+
+    expect(next?.getTime()).toBe(Date.UTC(2026, 0, 5, 9, 0, 0));
+  });
+
+  it("fires an interval at the offset", () => {
+    const everyTenSeconds = interval(10_000);
+    const fromAt = new Date("2026-01-01T00:00:00Z");
+    expect(nextFire(everyTenSeconds, fromAt)?.getTime()).toBe(
+      Date.UTC(2026, 0, 1, 0, 0, 10),
+    );
+  });
+
+  it("rejects malformed cron expressions", () => {
+    expect(() => cron("12 30")).toThrow(/fields/);
+    expect(() => cron("0 25 * * *")).toThrow(/out of range/);
+    expect(() => cron("bad * * * *")).toThrow(/Invalid/);
+  });
+});
+
+describe("job builders", () => {
+  it("schedules a job on a cron expression", () => {
+    // #section - Define a job
+    const app = createApp();
+    const descriptor = job(app, "nightly")
+      .cron("0 0 * * *")
+      .run(() => undefined);
+    // #endsection
+
+    expect(descriptor.__kind).toBe("jobs.job");
+    expect(descriptor.data.id).toBe("nightly");
+    expect(descriptor.data.schedule.kind).toBe("cron");
+    expect(childrenOf(app, "jobs.job").length).toBe(1);
+    const handlerNode = childrenOf(descriptor, "jobs.handler")[0];
+    expect(handlerNode).toBeDefined();
+    expect(lookup(descriptor.__key)).toBeDefined();
+  });
+
+  it("schedules a job on an interval", () => {
+    // #section - Schedule a job on an interval
+    const app = createApp();
+    const heartbeat = job(app, "heartbeat")
+      .every(5_000)
+      .run(() => undefined);
+    // #endsection
+    expect(heartbeat.data.schedule.kind).toBe("interval");
+  });
+
+  it("collects an app's jobs", () => {
+    const app = createApp();
+
+    // #section - Collect an app's jobs
+    job(app, "cleanup")
+      .every(60_000)
+      .run(() => undefined);
+    job(app, "report")
+      .cron("0 2 * * 1")
+      .run(() => undefined);
+    const collected = jobsOf(app);
+    // #endsection
+
+    expect(collected.map((entry) => entry.id).sort()).toEqual([
+      "cleanup",
+      "report",
+    ]);
+    expect(collected[0]?.schedule.kind).toBe("interval");
+  });
+
+  it("exposes a namespace bundle", () => {
+    // #section - Declare a jobs bundle
+    const jobsBundle = jobs;
+    // #endsection
+
+    expect(typeof jobsBundle.cron).toBe("function");
+    expect(typeof jobsBundle.interval).toBe("function");
+    expect(typeof jobsBundle.job).toBe("function");
+    expect(typeof jobsBundle.scheduler).toBe("function");
+    expect(typeof jobsBundle.jobsOf).toBe("function");
+  });
+});
+
+describe("scheduler executor", () => {
+  it("fires every job once on start", async () => {
+    const app = createApp();
+    const runs: Record<string, number> = {};
+    job(app, "a")
+      .cron("* * * * *")
+      .run(() => {
+        runs.a = (runs.a ?? 0) + 1;
+      });
+    job(app, "b")
+      .every(10)
+      .run(() => {
+        runs.b = (runs.b ?? 0) + 1;
+      });
+
+    const handle = scheduler(app);
+    expect(handle.jobs.map((entry) => entry.id).sort()).toEqual(["a", "b"]);
+    await handle.start();
+
+    expect(runs.a).toBe(1);
+    expect(runs.b).toBe(1);
+    handle.stop();
+  });
+
+  it("arms timers on tick and stops them", async () => {
+    const app = createApp();
+    const runs: number[] = [];
+    job(app, "ticker")
+      .every(5)
+      .run(() => {
+        runs.push(runs.length);
+      });
+
+    // #section - Schedule an app's jobs
+    const handle = scheduler(app);
+    const stop = handle.tick();
+    // #endsection
+
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    stop();
+
+    expect(runs.length).toBeGreaterThan(0);
+  });
+
+  it("surfaces onError for a failing job", async () => {
+    const app = createApp();
+    const errors: string[] = [];
+    job(app, "boom")
+      .every(10)
+      .run(() => {
+        throw new Error("bad");
+      });
+
+    const handle = scheduler(app, {
+      onError: ({ id, error }) => {
+        errors.push(`${id}:${String(error)}`);
+      },
+    });
+    await handle.start();
+    handle.stop();
+
+    expect(errors).toEqual(["boom:Error: bad"]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,36 @@
+export { cron, interval, nextFire } from "./schedule.js";
+export type { CompiledCron, FieldMatcher, JobSchedule } from "./schedule.js";
+
+export { job, runJob } from "./job.js";
+export type {
+  JobBuilder,
+  JobDescriptor,
+  JobHandler,
+  JobHandlerDescriptor,
+  JobRun,
+} from "./job.js";
+
+export { scheduler } from "./scheduler.js";
+export type { JobScheduler, SchedulerOptions } from "./scheduler.js";
+
+export { jobsOf } from "./collector.js";
+export type { CollectedJob } from "./collector.js";
+
+import { jobsOf } from "./collector.js";
+import { job } from "./job.js";
+import { cron, interval } from "./schedule.js";
+import { scheduler } from "./scheduler.js";
+
+/**
+ * The jobs namespace: one import for the whole scheduled-jobs app extensor.
+ *
+ * @group Surface
+ * @example Declare a jobs bundle
+ */
+export const jobs = {
+  cron,
+  interval,
+  job,
+  jobsOf,
+  scheduler,
+};

package/src/job.ts

@@ -0,0 +1,108 @@
+import { defineDescriptor, relate } from "@smitejs/core";
+import type { AppDescriptor, Descriptor } from "@smitejs/core";
+import type { EmptyHandler, EmptySignal } from "@smitejs/handlers";
+import { emptyHandler, fire } from "@smitejs/handlers";
+import { cron, interval } from "./schedule.js";
+import type { JobSchedule } from "./schedule.js";
+
+/**
+ * The zero-input function a job runs each time it fires.
+ *
+ * @group Types
+ */
+export type JobHandler = EmptyHandler;
+
+/**
+ * A `jobs.job` IR node: a named schedule and the handler edge that runs it.
+ *
+ * @group Internals
+ */
+export interface JobDescriptor
+  extends Descriptor<
+    "jobs.job",
+    { readonly id: string; readonly schedule: JobSchedule }
+  > {}
+
+/**
+ * A node wrapping the function a job runs.
+ *
+ * @group Internals
+ */
+export interface JobHandlerDescriptor
+  extends Descriptor<"jobs.handler", { readonly fn: JobHandler }> {}
+
+/**
+ * The terminal step of a {@link JobBuilder}: binds the run function to the
+ * schedule chosen and registers the job node under the app.
+ *
+ * @group Builders
+ */
+export interface JobRun {
+  /** Attaches the run function, relates the IR nodes, and returns the job. */
+  readonly run: (fn: JobHandler) => JobDescriptor;
+}
+
+/**
+ * A job builder: choose a cron or interval schedule from one shared
+ * `job(app, id)` piece, then bind a run function. Always a builder; returns the
+ * `jobs.job` descriptor after `run()`.
+ *
+ * @group Builders
+ * @example Define a job
+ */
+export interface JobBuilder {
+  /** Cron schedule from a 5-field POSIX expression. */
+  readonly cron: (expression: string) => JobRun;
+  /** Fixed-interval schedule in milliseconds. */
+  readonly every: (milliseconds: number) => JobRun;
+}
+
+/**
+ * Creates a job builder for an app. The common piece — `(app, id)` — yields two
+ * schedule builders (`cron()` / `every()`); pick one and `.run(fn)` attaches the
+ * `jobs.handler` child and relates the `jobs.job` node under the app.
+ *
+ * @group Builders
+ * @example Schedule a job on a cron expression
+ * @example Schedule a job on an interval
+ */
+export function job(app: AppDescriptor, id: string): JobBuilder {
+  const declare = (schedule: JobSchedule): JobRun => ({
+    run: (fn: JobHandler): JobDescriptor => {
+      const descriptor = defineDescriptor(
+        "jobs.job",
+        `${app.__key}:job:${id}`,
+        {
+          id,
+          schedule,
+        },
+      );
+      const handlerDescriptor = defineDescriptor(
+        "jobs.handler",
+        `${descriptor.__key}:handler`,
+        { fn: emptyHandler({ name: id }, fn) },
+      );
+      relate(descriptor, "jobs.handler", handlerDescriptor);
+      relate(app, "jobs.job", descriptor);
+      return descriptor;
+    },
+  });
+
+  const builder: JobBuilder = {
+    cron: (expression: string) => declare(cron(expression)),
+    every: (milliseconds: number) => declare(interval(milliseconds)),
+  };
+  return builder;
+}
+
+/**
+ * Fires a job's run function with a zero-input signal at the given (or
+ * current) instant.
+ *
+ * @group Executor
+ */
+export const runJob = (
+  descriptor: { readonly data: { readonly id: string } },
+  fn: (signal: EmptySignal) => void | Promise<void>,
+  at: number | Date = Date.now(),
+): Promise<void> => Promise.resolve(fn(fire(descriptor.data.id, at)));