@procedures/schedule 0.0.0-stage → 0.2.3

package/src/module.ts

@@ -0,0 +1,227 @@
+/**
+ * The procedures of @procedures/schedule as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/schedule
+ *
+ * `scheduleModule` keeps the schedules in `defaultScheduleStore` (memory). `createScheduleModule()`
+ * gives the same procedures with the store of the host, for example a `FileScheduleStore`. The
+ * host gives the same store to its `Scheduler` (roadmap R46).
+ */
+
+import { z } from "zod";
+import {
+  defineModule,
+  registerModules,
+  PROCEDURE_REGISTRY,
+  createProcedure,
+  zodAdapter,
+  type AnyProcedure,
+  type Effects,
+  type ProcedureContext,
+  type ProcedureModule,
+  type ProcedureRegistry,
+} from "@procedures/client";
+import { scheduleAdd } from "./procedures/schedule/add.js";
+import { scheduleList } from "./procedures/schedule/list.js";
+import { scheduleRemove } from "./procedures/schedule/remove.js";
+import { scheduleNext } from "./procedures/schedule/next.js";
+import { DEFAULT_SCHEDULE_SETTINGS, PROGRAM_KEY, type ScheduleSettings } from "./programs.js";
+import type { ScheduleStore } from "./store.js";
+import type {
+  Schedule,
+  ScheduleAddInput,
+  ScheduleAddOutput,
+  ScheduleListInput,
+  ScheduleListOutput,
+  ScheduleNextInput,
+  ScheduleNextOutput,
+  ScheduleRemoveInput,
+  ScheduleRemoveOutput,
+} from "./types.js";
+
+// =============================================================================
+// Schemas
+// =============================================================================
+
+const cron = z.string().min(1).max(200).describe("The cron expression: 5 fields (minute hour day month weekday), or @hourly, @daily, @weekly, @monthly, @yearly");
+const timeZone = z.enum(["utc", "local"]).describe("The time zone of the expression (default local)");
+const scheduleId = z
+  .string()
+  .regex(/^[A-Za-z0-9._:-]{1,200}$/, "Letters, digits, and . _ : -")
+  .describe("The name of the schedule");
+const programKey = z.string().max(500).regex(PROGRAM_KEY, "A dotted key: reports.weekly").describe("The dotted key of the stored program");
+
+const run = z.object({
+  startedAt: z.number().describe("The start, in milliseconds since 1970"),
+  durationMs: z.number(),
+  outcome: z.enum(["success", "failure"]),
+  error: z.object({ code: z.string().optional(), message: z.string() }).optional(),
+});
+
+const view = z.object({
+  id: z.string(),
+  cron: z.string(),
+  program: z.string(),
+  input: z.unknown().optional(),
+  timeZone: z.enum(["utc", "local"]),
+  createdAt: z.number().describe("When the schedule was added, in milliseconds since 1970"),
+  capability: z
+    .custom<NonNullable<Schedule["capability"]>>((value) => value !== null && typeof value === "object")
+    .optional()
+    .describe("The capability of the caller that added it: its clearance and its permitted effects"),
+  lastRun: run.optional().describe("The last run"),
+  runs: z.number().int(),
+  failures: z.number().int(),
+  skipped: z.number().int().describe("The times that came during a run: no second run started"),
+  nextRunAt: z.string().nullable().describe("The next time as an ISO text, or null"),
+});
+
+const ScheduleAddInputSchema = z.object({
+  id: scheduleId.optional().describe("The name of the schedule (default: the key of the program)"),
+  cron,
+  program: programKey,
+  input: z.unknown().optional().describe("The input of the program"),
+  timeZone: timeZone.optional(),
+  replace: z.boolean().optional().describe("True: replace a schedule of the same name (default false)"),
+});
+
+const ScheduleAddOutputSchema = z.object({ schedule: view });
+
+const ScheduleListInputSchema = z.object({ program: programKey.optional().describe("Only the schedules of this program") });
+
+const ScheduleListOutputSchema = z.object({ schedules: z.array(view).describe("The schedules, sorted by name") });
+
+const ScheduleRemoveInputSchema = z.object({ id: scheduleId });
+
+const ScheduleRemoveOutputSchema = z.object({ removed: z.boolean().describe("True when the schedule existed") });
+
+const ScheduleNextInputSchema = z.object({
+  cron,
+  count: z.number().int().min(1).max(100).optional().describe("The number of times, 1 to 100 (default 5)"),
+  after: z.string().max(100).optional().describe("The times come after this ISO time (default now)"),
+  timeZone: timeZone.optional(),
+});
+
+const ScheduleNextOutputSchema = z.object({ times: z.array(z.string()).describe("The next times as ISO texts") });
+
+// =============================================================================
+// Procedures
+// =============================================================================
+
+/** `schedule.add`: it reads the registry and the program store, and writes the schedules (a store can be a file). */
+const ADDS: Effects = Object.freeze({ reads: Object.freeze(["fs", "programs", "registry", "schedules"]), writes: Object.freeze(["fs", "schedules"]) });
+/** `schedule.list`: it reads the schedules. */
+const LISTS: Effects = Object.freeze({ reads: Object.freeze(["fs", "schedules"]), writes: Object.freeze([]) });
+/** `schedule.remove`: it deletes a schedule. A second call changes nothing more. */
+const REMOVES: Effects = Object.freeze({ reads: Object.freeze(["fs", "schedules"]), writes: Object.freeze(["fs", "schedules"]), destructive: true, idempotent: true });
+/** `schedule.next`: its output comes from its input and the time. */
+const PURE: Effects = Object.freeze({ reads: Object.freeze([]), writes: Object.freeze([]) });
+
+/** The four procedures, with handlers that use the settings. */
+function scheduleProcedures(settings: ScheduleSettings): AnyProcedure[] {
+  const scheduleAddProcedure = createProcedure()
+    .path(["schedule", "add"])
+    .input(zodAdapter<ScheduleAddInput>(ScheduleAddInputSchema))
+    .output(zodAdapter<ScheduleAddOutput>(ScheduleAddOutputSchema))
+    .meta({
+      description: "Add a schedule: a cron expression that starts a stored program with an input",
+      tags: ["schedule", "cron", "programs"],
+      args: ["cron", "program"],
+      shorts: { timeZone: "z" },
+      output: "json",
+      effects: ADDS,
+    })
+    .handler(async (input: ScheduleAddInput, ctx: ProcedureContext): Promise<ScheduleAddOutput> => scheduleAdd(input, ctx, settings))
+    .build();
+
+  const scheduleListProcedure = createProcedure()
+    .path(["schedule", "list"])
+    .input(zodAdapter<ScheduleListInput>(ScheduleListInputSchema))
+    .output(zodAdapter<ScheduleListOutput>(ScheduleListOutputSchema))
+    .meta({
+      description: "The schedules, with the next time and the last run of each",
+      tags: ["schedule", "cron"],
+      args: [],
+      shorts: {},
+      output: "json",
+      effects: LISTS,
+    })
+    .handler(async (input: ScheduleListInput): Promise<ScheduleListOutput> => scheduleList(input, settings))
+    .build();
+
+  const scheduleRemoveProcedure = createProcedure()
+    .path(["schedule", "remove"])
+    .input(zodAdapter<ScheduleRemoveInput>(ScheduleRemoveInputSchema))
+    .output(zodAdapter<ScheduleRemoveOutput>(ScheduleRemoveOutputSchema))
+    .meta({
+      description: "Remove a schedule",
+      tags: ["schedule", "cron"],
+      args: ["id"],
+      shorts: {},
+      output: "json",
+      effects: REMOVES,
+    })
+    .handler(async (input: ScheduleRemoveInput): Promise<ScheduleRemoveOutput> => scheduleRemove(input, settings))
+    .build();
+
+  const scheduleNextProcedure = createProcedure()
+    .path(["schedule", "next"])
+    .input(zodAdapter<ScheduleNextInput>(ScheduleNextInputSchema))
+    .output(zodAdapter<ScheduleNextOutput>(ScheduleNextOutputSchema))
+    .meta({
+      description: "The next times of a cron expression",
+      tags: ["schedule", "cron"],
+      args: ["cron"],
+      shorts: { count: "n", timeZone: "z" },
+      output: "json",
+      effects: PURE,
+    })
+    .handler(async (input: ScheduleNextInput): Promise<ScheduleNextOutput> => scheduleNext(input, settings))
+    .build();
+
+  return [scheduleAddProcedure, scheduleListProcedure, scheduleRemoveProcedure, scheduleNextProcedure];
+}
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data, on
+ * `defaultScheduleStore`. Importing this file registers nothing.
+ */
+export const scheduleModule: ProcedureModule = defineModule("@procedures/schedule", scheduleProcedures(DEFAULT_SCHEDULE_SETTINGS));
+
+export default scheduleModule;
+
+/** The options of `createScheduleModule()`. */
+export interface ScheduleModuleOptions {
+  /** The store of the schedules. The default is `defaultScheduleStore` (memory). */
+  readonly store?: ScheduleStore | undefined;
+  /** The wall time, in milliseconds since 1970. The default is `Date.now`. A test gives the time of its fake clock. */
+  readonly now?: (() => number) | undefined;
+}
+
+/**
+ * This function gives the module of this package with the store of the host. Without options, it
+ * gives `scheduleModule`. A host gives it to `createRegistry()` before its bundles, so it
+ * replaces the `scheduleModule` that a bundle requires (the first module of a name counts).
+ *
+ * ```ts
+ * const store = new FileScheduleStore("schedules.json");
+ * const registry = createRegistry(createScheduleModule({ store }), storeModule);
+ * await new Scheduler({ registry, store, policy }).start();
+ * ```
+ */
+export function createScheduleModule(options: ScheduleModuleOptions = {}): ProcedureModule {
+  if (Object.values(options).every((value) => value === undefined)) return scheduleModule;
+  const settings: ScheduleSettings = {
+    store: options.store ?? DEFAULT_SCHEDULE_SETTINGS.store,
+    now: options.now ?? DEFAULT_SCHEDULE_SETTINGS.now,
+  };
+  return defineModule("@procedures/schedule", scheduleProcedures(settings));
+}
+
+/**
+ * This function registers the procedures of @procedures/schedule in a registry. The default is the
+ * global registry. The options are the options of `createScheduleModule()`.
+ */
+export function registerScheduleProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY, options: ScheduleModuleOptions = {}): void {
+  registerModules(registry, [createScheduleModule(options)]);
+}

package/src/procedures/schedule/add.ts

@@ -0,0 +1,66 @@
+/**
+ * schedule.add procedure
+ *
+ * Add a schedule: a cron expression that starts a stored program with an input. The procedure
+ * examines the expression and the program, and keeps the capability of the caller: a run gets
+ * the capability of the host, narrowed by it.
+ */
+
+import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client";
+import { formatTime, nextTime, parseCron } from "../../cron.js";
+import { ScheduleError } from "../../errors.js";
+import { DEFAULT_SCHEDULE_SETTINGS, findProgram, type ScheduleSettings } from "../../programs.js";
+import type { Schedule, ScheduleAddInput, ScheduleAddOutput, ScheduleView } from "../../types.js";
+
+/** The view of a schedule: with its next time after `now`. */
+export function viewOf(schedule: Schedule, now: number): ScheduleView {
+  let next: number | undefined;
+  try {
+    next = nextTime(parseCron(schedule.cron), now, schedule.timeZone);
+  } catch {
+    next = undefined;
+  }
+  return { ...schedule, nextRunAt: next === undefined ? null : formatTime(next, schedule.timeZone) };
+}
+
+/** The capability of the caller to keep: its clearance and its permitted effects, without its deadline. */
+function callerCapability(ctx: Pick<ProcedureContext, "capability"> | undefined): Schedule["capability"] {
+  const capability = ctx?.capability;
+  if (capability === undefined) return undefined;
+  const kept: NonNullable<Schedule["capability"]> = {};
+  if (capability.clearance !== undefined) kept.clearance = capability.clearance;
+  if (capability.effects !== undefined) kept.effects = capability.effects;
+  return Object.keys(kept).length > 0 ? kept : undefined;
+}
+
+/**
+ * Add a schedule: a cron expression that starts a stored program with an input
+ */
+export async function scheduleAdd(input: ScheduleAddInput, ctx?: Pick<ProcedureContext, "capability" | "registry">, settings: ScheduleSettings = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleAddOutput> {
+  const now = settings.now();
+  const timeZone = input.timeZone ?? "local";
+  const cron = parseCron(input.cron);
+  if (nextTime(cron, now, timeZone) === undefined) {
+    throw new ScheduleError("BAD_CRON", `The cron expression ${JSON.stringify(input.cron)} has no time in the next 9 years`);
+  }
+  await findProgram(ctx?.registry ?? PROCEDURE_REGISTRY, input.program);
+  const id = input.id ?? input.program;
+  const capability = callerCapability(ctx);
+  const schedule: Schedule = {
+    id,
+    cron: cron.source,
+    program: input.program,
+    ...(input.input !== undefined ? { input: input.input } : {}),
+    timeZone,
+    createdAt: now,
+    ...(capability !== undefined ? { capability } : {}),
+    runs: 0,
+    failures: 0,
+    skipped: 0,
+  };
+  if (input.replace !== true && (await settings.store.get(id)) !== undefined) {
+    throw new ScheduleError("EXISTS", `A schedule named ${id} exists: give replace: true, or another id`);
+  }
+  await settings.store.put(schedule);
+  return { schedule: viewOf(schedule, now) };
+}

package/src/procedures/schedule/index.ts

@@ -0,0 +1,4 @@
+export { scheduleAdd, viewOf } from "./add.js";
+export { scheduleList } from "./list.js";
+export { scheduleRemove } from "./remove.js";
+export { scheduleNext } from "./next.js";

package/src/procedures/schedule/list.ts

@@ -0,0 +1,20 @@
+/**
+ * schedule.list procedure
+ *
+ * The schedules, sorted by name, with the next time, the last run and the counts of each.
+ */
+
+import { DEFAULT_SCHEDULE_SETTINGS, type ScheduleSettings } from "../../programs.js";
+import type { ScheduleListInput, ScheduleListOutput } from "../../types.js";
+import { viewOf } from "./add.js";
+
+/**
+ * The schedules, with the next time and the last run of each
+ */
+export async function scheduleList(input: ScheduleListInput, settings: ScheduleSettings = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleListOutput> {
+  const now = settings.now();
+  const schedules = await settings.store.list();
+  return {
+    schedules: schedules.filter((schedule) => input.program === undefined || schedule.program === input.program).map((schedule) => viewOf(schedule, now)),
+  };
+}

package/src/procedures/schedule/next.ts

@@ -0,0 +1,25 @@
+/**
+ * schedule.next procedure
+ *
+ * The next times of a cron expression. It reads no store: the output comes from the input and
+ * from the time.
+ */
+
+import { formatTime, nextTimes, parseCron } from "../../cron.js";
+import { ScheduleError } from "../../errors.js";
+import { DEFAULT_SCHEDULE_SETTINGS, type ScheduleSettings } from "../../programs.js";
+import type { ScheduleNextInput, ScheduleNextOutput } from "../../types.js";
+
+/**
+ * The next times of a cron expression
+ */
+export async function scheduleNext(input: ScheduleNextInput, settings: Pick<ScheduleSettings, "now"> = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleNextOutput> {
+  const timeZone = input.timeZone ?? "local";
+  const cron = parseCron(input.cron);
+  let after = settings.now();
+  if (input.after !== undefined) {
+    after = Date.parse(input.after);
+    if (Number.isNaN(after)) throw new ScheduleError("BAD_CRON", `after must be an ISO time, not ${JSON.stringify(input.after)}`);
+  }
+  return { times: nextTimes(cron, after, input.count ?? 5, timeZone).map((time) => formatTime(time, timeZone)) };
+}

package/src/procedures/schedule/remove.ts

@@ -0,0 +1,15 @@
+/**
+ * schedule.remove procedure
+ *
+ * Remove a schedule. A run that started before stays until its end, and its record goes nowhere.
+ */
+
+import { DEFAULT_SCHEDULE_SETTINGS, type ScheduleSettings } from "../../programs.js";
+import type { ScheduleRemoveInput, ScheduleRemoveOutput } from "../../types.js";
+
+/**
+ * Remove a schedule
+ */
+export async function scheduleRemove(input: ScheduleRemoveInput, settings: ScheduleSettings = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleRemoveOutput> {
+  return { removed: await settings.store.delete(input.id) };
+}

package/src/programs.ts

@@ -0,0 +1,43 @@
+/**
+ * The stored programs that a schedule starts, and the settings of the procedures.
+ *
+ * A schedule names a stored program: a procedure that `procedure.define` made, or a program of
+ * the program store of the registry (`@procedures/store`). A procedure of code is not a program:
+ * a schedule cannot start `shell.run` directly.
+ */
+
+import { isRuntimeDefined, keyToPath, type ProcedureRegistryLike } from "@procedures/client";
+import { getProgramStore } from "@procedures/store";
+import { ScheduleError } from "./errors.js";
+import { defaultScheduleStore, type ScheduleStore } from "./store.js";
+
+/** What the procedures of a module use: the store and the wall clock. */
+export interface ScheduleSettings {
+  readonly store: ScheduleStore;
+  /** The wall time, in milliseconds since 1970. */
+  readonly now: () => number;
+}
+
+/** The settings of the default module: `defaultScheduleStore` and `Date.now`. */
+export const DEFAULT_SCHEDULE_SETTINGS: ScheduleSettings = Object.freeze({ store: defaultScheduleStore, now: () => Date.now() });
+
+/** The form of the key of a program: segments without spaces, joined with dots. */
+export const PROGRAM_KEY: RegExp = /^[^.\s]+(\.[^.\s]+)*$/;
+
+/**
+ * This function tells where the stored program of a key is: in the registry (a procedure that
+ * `procedure.define` made), or only in the program store of the registry. It throws
+ * `NOT_A_PROGRAM` for a procedure of code and `NOT_FOUND` for no program.
+ */
+export async function findProgram(registry: ProcedureRegistryLike, key: string): Promise<"registry" | "store"> {
+  const procedure = registry.get(keyToPath(key));
+  if (procedure !== undefined) {
+    if (!isRuntimeDefined(procedure)) {
+      throw new ScheduleError("NOT_A_PROGRAM", `${key} is a procedure of code, not a stored program. A schedule starts only a program of procedure.define or of the program store.`);
+    }
+    return "registry";
+  }
+  const programs = getProgramStore(registry);
+  if (programs !== undefined && (await programs.get(key)) !== undefined) return "store";
+  throw new ScheduleError("NOT_FOUND", `No stored program has the key ${key}: it is not in the registry and not in its program store`);
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/schedule in the global registry:
+ * `import "@procedures/schedule/register"`. The package root registers nothing.
+ */
+
+import { registerScheduleProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerScheduleProcedures();