@procedures/schedule 0.0.0-stage → 0.2.3

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+import type { PermittedEffects } from "@procedures/client";
+/** The time zone of a cron expression: the UTC time, or the local time of the host. */
+export type ScheduleTimeZone = "utc" | "local";
+/** The last run of a schedule. */
+export interface ScheduleRun {
+    /** The wall time of the start, in milliseconds since 1970. */
+    startedAt: number;
+    /** The time of the run, in milliseconds. */
+    durationMs: number;
+    outcome: "success" | "failure";
+    /** The error of a failure: its code, when it has one, and its message. */
+    error?: {
+        code?: string | undefined;
+        message: string;
+    } | undefined;
+}
+/** One stored schedule: a cron expression that starts a stored program with an input. */
+export interface Schedule {
+    /** The name of the schedule. */
+    id: string;
+    /** The cron expression: 5 fields, or a name such as `@daily`. */
+    cron: string;
+    /** The dotted key of the stored program: `reports.weekly`. */
+    program: string;
+    /** The input of the program. */
+    input?: unknown;
+    timeZone: ScheduleTimeZone;
+    /** When the schedule was added, in milliseconds since 1970. A schedule starts no run for a time before it. */
+    createdAt: number;
+    /**
+     * The capability of the caller that added the schedule, without its deadline. A run gets the
+     * capability of the host, narrowed by this one: a caller cannot start more than it can do.
+     */
+    capability?: {
+        clearance?: unknown;
+        effects?: PermittedEffects;
+    } | undefined;
+    lastRun?: ScheduleRun | undefined;
+    /** The number of runs. */
+    runs: number;
+    /** The number of runs that failed. */
+    failures: number;
+    /** The number of times that came while a run of the schedule was not finished: no second run started. */
+    skipped: number;
+}
+/** A schedule as the procedures give it: with its next time. */
+export interface ScheduleView extends Schedule {
+    /** The next time, as an ISO text in the time zone of the schedule, or null when the expression has no next time. */
+    nextRunAt: string | null;
+}
+export interface ScheduleAddInput {
+    /** The name of the schedule. The default is the key of the program. */
+    id?: string | undefined;
+    cron: string;
+    /** The dotted key of the stored program. */
+    program: string;
+    input?: unknown;
+    /** The time zone of the expression. The default is `local`. */
+    timeZone?: ScheduleTimeZone | undefined;
+    /** True: replace a schedule of the same name. The default is false: a second schedule of a name is an error. */
+    replace?: boolean | undefined;
+}
+export interface ScheduleAddOutput {
+    schedule: ScheduleView;
+}
+export interface ScheduleListInput {
+    /** Only the schedules of this program. */
+    program?: string | undefined;
+}
+export interface ScheduleListOutput {
+    /** The schedules, sorted by name. */
+    schedules: ScheduleView[];
+}
+export interface ScheduleRemoveInput {
+    id: string;
+}
+export interface ScheduleRemoveOutput {
+    /** True when the schedule existed. */
+    removed: boolean;
+}
+export interface ScheduleNextInput {
+    cron: string;
+    /** The number of times: 1 to 100. The default is 5. */
+    count?: number | undefined;
+    /** The times come after this time: an ISO text. The default is now. */
+    after?: string | undefined;
+    /** The time zone of the expression. The default is `local`. */
+    timeZone?: ScheduleTimeZone | undefined;
+}
+export interface ScheduleNextOutput {
+    /** The next times, as ISO texts in the time zone of the expression. Fewer than `count` when the expression has fewer times in the next 9 years. */
+    times: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,CAAC;AAE/C,kCAAkC;AAClC,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,0EAA0E;IAC1E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACpE;AAED,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,8GAA8G;IAC9G,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAAE,GAAG,SAAS,CAAC;IAC7E,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,oHAAoH;IACpH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAMD,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACxC,gHAAgH;IAChH,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,CAAC;CACxB;AAMD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAMD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,mJAAmJ;IACnJ,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,81 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/schedule",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.3",
+  "description": "A cron for stored programs: schedules as procedures, and a scheduler that a host starts, with an injectable clock and no overlapping runs.",
+  "keywords": [
+    "procedures",
+    "cron",
+    "schedule",
+    "scheduler",
+    "programs",
+    "jobs"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/schedule"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "devDependencies": {
+    "@mark1russell7/cue": "^1.0.0",
+    "@mark1russell7/service": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.3",
+    "@procedures/store": "0.2.3",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/cron.ts

@@ -0,0 +1,230 @@
+/**
+ * Cron expressions (roadmap R46): the parse and the next times.
+ *
+ * This package parses cron itself. The format is small, and a dependency for it gives a time
+ * zone database or a second format that this package does not need.
+ *
+ * - 5 fields: minute (0-59), hour (0-23), day of the month (1-31), month (1-12), day of the week
+ *   (0-7, with 0 and 7 for Sunday).
+ * - Each field: `*`, a number, a range `a-b`, a step `*` + `/n`, `a-b/n` or `a/n` (from `a` to the
+ *   end), and lists of these with commas.
+ * - The names of the months (`jan` to `dec`) and of the days (`sun` to `sat`), in each case.
+ * - The names `@yearly` (`@annually`), `@monthly`, `@weekly`, `@daily` (`@midnight`) and `@hourly`.
+ * - The days, as in Vixie cron: when the two day fields have a limit (they do not start with
+ *   `*`), a day matches when one of the two matches. Else the field with a limit decides.
+ *
+ * The times are in UTC or in the local time of the host. In local time, a time that the change
+ * to summer time skips does not run, and a time that the change back repeats can run two times.
+ */
+
+import { ScheduleError } from "./errors.js";
+import type { ScheduleTimeZone } from "./types.js";
+
+/** A parsed cron expression. */
+export interface CronExpression {
+  readonly source: string;
+  readonly minutes: ReadonlySet<number>;
+  readonly hours: ReadonlySet<number>;
+  readonly days: ReadonlySet<number>;
+  readonly months: ReadonlySet<number>;
+  /** The days of the week, 0 (Sunday) to 6. */
+  readonly weekdays: ReadonlySet<number>;
+  /** True when the field of the day of the month does not start with `*`. */
+  readonly dayLimited: boolean;
+  /** True when the field of the day of the week does not start with `*`. */
+  readonly weekdayLimited: boolean;
+}
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+
+interface FieldSpec {
+  readonly name: string;
+  readonly min: number;
+  readonly max: number;
+  /** The names of the values, from `first`. */
+  readonly names?: readonly string[];
+  readonly first?: number;
+}
+
+const FIELDS: readonly FieldSpec[] = [
+  { name: "minute", min: 0, max: 59 },
+  { name: "hour", min: 0, max: 23 },
+  { name: "day of the month", min: 1, max: 31 },
+  { name: "month", min: 1, max: 12, names: MONTHS, first: 1 },
+  { name: "day of the week", min: 0, max: 7, names: DAYS, first: 0 },
+];
+
+/** The names of the expressions that are one name. */
+export const CRON_NAMES: Readonly<Record<string, string>> = Object.freeze({
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+  "@monthly": "0 0 1 * *",
+  "@weekly": "0 0 * * 0",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly": "0 * * * *",
+});
+
+function fail(source: string, message: string): never {
+  throw new ScheduleError("BAD_CRON", `The cron expression ${JSON.stringify(source)} is not correct: ${message}`);
+}
+
+/** The value of one token of a field: a number or a name. */
+function valueOf(token: string, spec: FieldSpec, source: string): number {
+  if (/^\d+$/.test(token)) {
+    const value = Number(token);
+    if (value < spec.min || value > spec.max) fail(source, `${token} is out of the ${spec.name} range ${spec.min}-${spec.max}`);
+    return value;
+  }
+  const index = spec.names?.indexOf(token.toLowerCase()) ?? -1;
+  if (index < 0) fail(source, `${JSON.stringify(token)} is not a ${spec.name}`);
+  return index + (spec.first ?? 0);
+}
+
+/** The values of one field. */
+function parseField(text: string, spec: FieldSpec, source: string): Set<number> {
+  const values = new Set<number>();
+  for (const part of text.split(",")) {
+    if (part === "") fail(source, `the ${spec.name} field has an empty part`);
+    const pieces = part.split("/");
+    if (pieces.length > 2) fail(source, `${JSON.stringify(part)} has more than one step`);
+    const [range, stepText] = pieces as [string, string | undefined];
+    let step = 1;
+    if (stepText !== undefined) {
+      if (!/^\d+$/.test(stepText) || Number(stepText) < 1) fail(source, `the step ${JSON.stringify(stepText)} must be a whole number of 1 or more`);
+      step = Number(stepText);
+    }
+    let low: number;
+    let high: number;
+    if (range === "*") {
+      low = spec.min;
+      // The day of the week: * is 0-6, not 0-7
+      high = spec.names === DAYS ? 6 : spec.max;
+    } else if (range.includes("-")) {
+      const bounds = range.split("-");
+      if (bounds.length !== 2) fail(source, `${JSON.stringify(range)} is not a range`);
+      low = valueOf(bounds[0]!, spec, source);
+      high = valueOf(bounds[1]!, spec, source);
+      if (low > high) fail(source, `the range ${range} goes down`);
+    } else {
+      low = valueOf(range, spec, source);
+      high = stepText === undefined ? low : spec.max;
+    }
+    for (let value = low; value <= high; value += step) values.add(spec.names === DAYS && value === 7 ? 0 : value);
+  }
+  return values;
+}
+
+/** This function parses a cron expression. It throws a `BAD_CRON` error that tells the problem. */
+export function parseCron(text: string): CronExpression {
+  const source = text.trim();
+  const expanded = source.startsWith("@") ? CRON_NAMES[source.toLowerCase()] : source;
+  if (expanded === undefined) fail(source, `${source} is not a known name (${Object.keys(CRON_NAMES).join(", ")})`);
+  const fields = expanded.split(/\s+/).filter((field) => field !== "");
+  if (fields.length !== 5) fail(source, `it has ${fields.length} fields, and a cron expression has 5: minute, hour, day of the month, month, day of the week`);
+  const [minutes, hours, days, months, weekdays] = fields.map((field, index) => parseField(field, FIELDS[index]!, source)) as [Set<number>, Set<number>, Set<number>, Set<number>, Set<number>];
+  return {
+    source,
+    minutes,
+    hours,
+    days,
+    months,
+    weekdays,
+    dayLimited: !fields[2]!.startsWith("*"),
+    weekdayLimited: !fields[4]!.startsWith("*"),
+  };
+}
+
+/** The fields of a time in a time zone. */
+interface Fields {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  weekday: number;
+}
+
+/** The calendar of a time zone: the fields of a time, and the time of fields (which can overflow). */
+interface Calendar {
+  fields(time: number): Fields;
+  make(year: number, month: number, day: number, hour: number, minute: number): number;
+}
+
+const UTC: Calendar = {
+  fields(time) {
+    const date = new Date(time);
+    return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(), hour: date.getUTCHours(), minute: date.getUTCMinutes(), weekday: date.getUTCDay() };
+  },
+  make: (year, month, day, hour, minute) => Date.UTC(year, month - 1, day, hour, minute),
+};
+
+const LOCAL: Calendar = {
+  fields(time) {
+    const date = new Date(time);
+    return { year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(), hour: date.getHours(), minute: date.getMinutes(), weekday: date.getDay() };
+  },
+  make: (year, month, day, hour, minute) => new Date(year, month - 1, day, hour, minute).getTime(),
+};
+
+/** The years that a search covers: Feb 29 can be 8 years away (2096 to 2104). */
+const SEARCH_YEARS = 9;
+
+/** True when the day of the fields matches the two day fields. */
+function dayMatches(cron: CronExpression, fields: Fields): boolean {
+  const day = cron.days.has(fields.day);
+  const weekday = cron.weekdays.has(fields.weekday);
+  if (cron.dayLimited && cron.weekdayLimited) return day || weekday;
+  if (cron.dayLimited) return day;
+  if (cron.weekdayLimited) return weekday;
+  return true;
+}
+
+/**
+ * This function gives the first time of the expression after `after` (milliseconds since 1970),
+ * or undefined when the expression has no time in the next 9 years.
+ */
+export function nextTime(cron: CronExpression, after: number, timeZone: ScheduleTimeZone = "local"): number | undefined {
+  const calendar = timeZone === "utc" ? UTC : LOCAL;
+  let time = Math.floor(after / 60_000) * 60_000 + 60_000;
+  const lastYear = calendar.fields(after).year + SEARCH_YEARS;
+  for (let step = 0; step < 1_000_000; step++) {
+    const fields = calendar.fields(time);
+    if (fields.year > lastYear) return undefined;
+    let next: number;
+    if (!cron.months.has(fields.month)) next = calendar.make(fields.year, fields.month + 1, 1, 0, 0);
+    else if (!dayMatches(cron, fields)) next = calendar.make(fields.year, fields.month, fields.day + 1, 0, 0);
+    else if (!cron.hours.has(fields.hour)) next = calendar.make(fields.year, fields.month, fields.day, fields.hour + 1, 0);
+    else if (!cron.minutes.has(fields.minute)) next = time + 60_000;
+    else return time;
+    // A change of the clock can give a time that is not later: go one minute on
+    time = next > time ? next : time + 60_000;
+  }
+  return undefined;
+}
+
+/** This function gives the next `count` times of the expression after `after`. */
+export function nextTimes(cron: CronExpression, after: number, count: number, timeZone: ScheduleTimeZone = "local"): number[] {
+  const times: number[] = [];
+  let from = after;
+  while (times.length < count) {
+    const time = nextTime(cron, from, timeZone);
+    if (time === undefined) break;
+    times.push(time);
+    from = time;
+  }
+  return times;
+}
+
+const pad = (value: number, length = 2): string => String(value).padStart(length, "0");
+
+/** The ISO text of a time in a time zone: `2026-10-17T09:00:00Z`, or with the offset of the host: `2026-10-17T09:00:00+02:00`. */
+export function formatTime(time: number, timeZone: ScheduleTimeZone = "local"): string {
+  const date = new Date(time);
+  if (timeZone === "utc") return `${date.toISOString().slice(0, 19)}Z`;
+  const offset = -date.getTimezoneOffset();
+  const sign = offset >= 0 ? "+" : "-";
+  const zone = offset === 0 ? "Z" : `${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`;
+  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${zone}`;
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * The errors of the schedule procedures and of the scheduler.
+ */
+
+/** The reason of a `ScheduleError`. */
+export type ScheduleErrorCode =
+  /** The cron expression is not correct, or it has no time in the next 9 years. */
+  | "BAD_CRON"
+  /** A schedule of the name exists, and the input does not replace it. */
+  | "EXISTS"
+  /** No stored program has the key: not in the registry, not in the program store. */
+  | "NOT_FOUND"
+  /** The key names a procedure of code, not a stored program. */
+  | "NOT_A_PROGRAM"
+  /** The file of a `FileScheduleStore` is not correct. */
+  | "BAD_STORE";
+
+/** An error of the schedules. */
+export class ScheduleError extends Error {
+  override readonly name = "ScheduleError";
+  readonly code: ScheduleErrorCode;
+
+  constructor(code: ScheduleErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export { scheduleAdd, scheduleList, scheduleRemove, scheduleNext, viewOf } from "./procedures/schedule/index.js";
+// The cron expressions, the stores and the scheduler (roadmap R46)
+export { CRON_NAMES, formatTime, nextTime, nextTimes, parseCron, type CronExpression } from "./cron.js";
+export { ScheduleError, type ScheduleErrorCode } from "./errors.js";
+export { checkSchedule, defaultScheduleStore, FileScheduleStore, MemoryScheduleStore, type ScheduleStore } from "./store.js";
+export { DEFAULT_SCHEDULE_SETTINGS, findProgram, PROGRAM_KEY, type ScheduleSettings } from "./programs.js";
+export { DEFAULT_RUN_TIMEOUT_MS, Scheduler, type ScheduleRunEvent, type SchedulerOptions } from "./scheduler.js";