@procedures/schedule 0.0.0-stage → 0.3.0

package/dist/procedures/schedule/index.js

@@ -0,0 +1,5 @@
+export { scheduleAdd, viewOf } from "./add.js";
+export { scheduleList } from "./list.js";
+export { scheduleRemove } from "./remove.js";
+export { scheduleNext } from "./next.js";
+//# sourceMappingURL=index.js.map

package/dist/procedures/schedule/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/procedures/schedule/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/procedures/schedule/list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * schedule.list procedure
+ *
+ * The schedules, sorted by name, with the next time, the last run and the counts of each.
+ */
+import { type ScheduleSettings } from "../../programs.js";
+import type { ScheduleListInput, ScheduleListOutput } from "../../types.js";
+/**
+ * The schedules, with the next time and the last run of each
+ */
+export declare function scheduleList(input: ScheduleListInput, settings?: ScheduleSettings): Promise<ScheduleListOutput>;
+//# sourceMappingURL=list.d.ts.map

package/dist/procedures/schedule/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/procedures/schedule/list.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAG5E;;GAEG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,GAAE,gBAA4C,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAMhJ"}

package/dist/procedures/schedule/list.js

@@ -0,0 +1,18 @@
+/**
+ * schedule.list procedure
+ *
+ * The schedules, sorted by name, with the next time, the last run and the counts of each.
+ */
+import { DEFAULT_SCHEDULE_SETTINGS } from "../../programs.js";
+import { viewOf } from "./add.js";
+/**
+ * The schedules, with the next time and the last run of each
+ */
+export async function scheduleList(input, settings = DEFAULT_SCHEDULE_SETTINGS) {
+    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)),
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/procedures/schedule/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/procedures/schedule/list.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,yBAAyB,EAAyB,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAwB,EAAE,QAAQ,GAAqB,yBAAyB;IACjH,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;KACtJ,CAAC;AACJ,CAAC"}

package/dist/procedures/schedule/next.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { type ScheduleSettings } from "../../programs.js";
+import type { ScheduleNextInput, ScheduleNextOutput } from "../../types.js";
+/**
+ * The next times of a cron expression
+ */
+export declare function scheduleNext(input: ScheduleNextInput, settings?: Pick<ScheduleSettings, "now">): Promise<ScheduleNextOutput>;
+//# sourceMappingURL=next.d.ts.map

package/dist/procedures/schedule/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../../src/procedures/schedule/next.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE5E;;GAEG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,GAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAA6B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAS7J"}

package/dist/procedures/schedule/next.js

@@ -0,0 +1,24 @@
+/**
+ * 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 } from "../../programs.js";
+/**
+ * The next times of a cron expression
+ */
+export async function scheduleNext(input, settings = DEFAULT_SCHEDULE_SETTINGS) {
+    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)) };
+}
+//# sourceMappingURL=next.js.map

package/dist/procedures/schedule/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../../../src/procedures/schedule/next.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAyB,MAAM,mBAAmB,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAwB,EAAE,QAAQ,GAAkC,yBAAyB;IAC9H,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAC;IAC3C,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC;IAC3B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,aAAa,CAAC,UAAU,EAAE,kCAAkC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChI,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;AACjH,CAAC"}

package/dist/procedures/schedule/remove.d.ts

@@ -0,0 +1,12 @@
+/**
+ * schedule.remove procedure
+ *
+ * Remove a schedule. A run that started before stays until its end, and its record goes nowhere.
+ */
+import { type ScheduleSettings } from "../../programs.js";
+import type { ScheduleRemoveInput, ScheduleRemoveOutput } from "../../types.js";
+/**
+ * Remove a schedule
+ */
+export declare function scheduleRemove(input: ScheduleRemoveInput, settings?: ScheduleSettings): Promise<ScheduleRemoveOutput>;
+//# sourceMappingURL=remove.d.ts.map

package/dist/procedures/schedule/remove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove.d.ts","sourceRoot":"","sources":["../../../src/procedures/schedule/remove.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEhF;;GAEG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,EAAE,QAAQ,GAAE,gBAA4C,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAEtJ"}

package/dist/procedures/schedule/remove.js

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

package/dist/procedures/schedule/remove.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove.js","sourceRoot":"","sources":["../../../src/procedures/schedule/remove.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,yBAAyB,EAAyB,MAAM,mBAAmB,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAA0B,EAAE,QAAQ,GAAqB,yBAAyB;IACrH,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AAC5D,CAAC"}

package/dist/programs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 { type ProcedureRegistryLike } from "@procedures/client";
+import { 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 declare const DEFAULT_SCHEDULE_SETTINGS: ScheduleSettings;
+/** The form of the key of a program: segments without spaces, joined with dots. */
+export declare const PROGRAM_KEY: RegExp;
+/**
+ * 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 declare function findProgram(registry: ProcedureRegistryLike, key: string): Promise<"registry" | "store">;
+//# sourceMappingURL=programs.d.ts.map

package/dist/programs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"programs.d.ts","sourceRoot":"","sources":["../src/programs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA+B,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAG7F,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtE,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,EAAE,gBAAwF,CAAC;AAEjI,mFAAmF;AACnF,eAAO,MAAM,WAAW,EAAE,MAAgC,CAAC;AAE3D;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,CAW7G"}

package/dist/programs.js

@@ -0,0 +1,34 @@
+/**
+ * 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 } from "@procedures/client";
+import { getProgramStore } from "@procedures/store";
+import { ScheduleError } from "./errors.js";
+import { defaultScheduleStore } from "./store.js";
+/** The settings of the default module: `defaultScheduleStore` and `Date.now`. */
+export const DEFAULT_SCHEDULE_SETTINGS = 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 = /^[^.\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, key) {
+    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`);
+}
+//# sourceMappingURL=programs.js.map

package/dist/programs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"programs.js","sourceRoot":"","sources":["../src/programs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAA8B,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAsB,MAAM,YAAY,CAAC;AAStE,iFAAiF;AACjF,MAAM,CAAC,MAAM,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAEjI,mFAAmF;AACnF,MAAM,CAAC,MAAM,WAAW,GAAW,uBAAuB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAA+B,EAAE,GAAW;IAC5E,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,GAAG,GAAG,8HAA8H,CAAC,CAAC;QACjL,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,MAAM,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACtF,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,iCAAiC,GAAG,0DAA0D,CAAC,CAAC;AACvI,CAAC"}

package/dist/register.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Importing this file registers the procedures of @procedures/schedule in the global registry:
+ * `import "@procedures/schedule/register"`. The package root registers nothing.
+ */
+export * from "./module.js";
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,cAAc,aAAa,CAAC"}

package/dist/register.js

@@ -0,0 +1,8 @@
+/**
+ * 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();
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,cAAc,aAAa,CAAC;AAE5B,0BAA0B,EAAE,CAAC"}

package/dist/scheduler.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The scheduler: a host starts it, and it starts the stored programs of the schedules at their
+ * times (roadmap R46).
+ *
+ * - It wakes at each minute (the unit of cron), reads the schedules of its store, and starts each
+ *   schedule whose time came. A schedule that a procedure adds or removes counts at the next minute.
+ * - A run goes through the registry, with the capability of the host narrowed by the capability
+ *   of the caller that added the schedule. The expose rule, the call rule, the interceptors and
+ *   the resources of the host policy apply too.
+ * - A schedule has at most one run at a time. A time that comes during a run does not start a
+ *   second run: the store counts it as skipped.
+ * - The store records the last run of each schedule: its start, its time and its outcome.
+ * - A run that passes `runTimeoutMs` gets the abort of its signal and the outcome `TIMEOUT`. The
+ *   schedule stays busy until the handler ends: a handler that does not stop blocks only its own
+ *   schedule.
+ * - The scheduler does not run the times that it missed while it was stopped. Times that it
+ *   missed during a run or a slow minute give one run, not one for each time.
+ * - The timers use an injectable `Clock` (`after` and `now`), and the calendar uses an injectable
+ *   wall clock (`now`, default `Date.now`). A test gives `fakeClock` of `@mark1russell7/service/testing`.
+ */
+import { type Capability, type Clock, type HostPolicy, type ProcedureRegistry } from "@procedures/client";
+import { type ScheduleStore } from "./store.js";
+/** The default time limit of a run: 10 minutes. */
+export declare const DEFAULT_RUN_TIMEOUT_MS = 600000;
+/** What a host gets after each run and each skipped time. */
+export interface ScheduleRunEvent {
+    readonly id: string;
+    readonly program: string;
+    readonly outcome: "success" | "failure" | "skipped";
+    /** The wall time of the start, in milliseconds since 1970. */
+    readonly startedAt: number;
+    readonly durationMs: number;
+    readonly error?: {
+        readonly code?: string | undefined;
+        readonly message: string;
+    } | undefined;
+}
+/** The options of a `Scheduler`. */
+export interface SchedulerOptions {
+    /** The registry of the programs. The default is the global registry. */
+    readonly registry?: ProcedureRegistry | undefined;
+    /** The store of the schedules: the store of the module of the procedures. The default is `defaultScheduleStore`. */
+    readonly store?: ScheduleStore | undefined;
+    /** The capability of the host for each run. The default is the capability of `policy`, else no limits. */
+    readonly capability?: Capability | undefined;
+    /** The policy of the host: its expose rule, call rule, interceptors, clearance order, resources and capability. */
+    readonly policy?: HostPolicy | undefined;
+    /** The clock of the timers and of the durations. The default is `realClock`. */
+    readonly clock?: Clock | undefined;
+    /** The wall time, in milliseconds since 1970. The default is `Date.now`. */
+    readonly now?: (() => number) | undefined;
+    /** The time limit of a run, in milliseconds. 0: no limit. The default is 10 minutes. */
+    readonly runTimeoutMs?: number | undefined;
+    /** This function gets each run and each skipped time. */
+    readonly onRun?: ((event: ScheduleRunEvent) => void) | undefined;
+    /** This function gets an error of the scheduler itself: a store that cannot be read, for example. */
+    readonly onError?: ((error: unknown) => void) | undefined;
+}
+/** A scheduler of the stored programs. See the comment of the file. */
+export declare class Scheduler {
+    private readonly registry;
+    private readonly store;
+    private readonly clock;
+    private readonly now;
+    private readonly runTimeoutMs;
+    private readonly options;
+    private readonly due;
+    private readonly runs;
+    private startedAt;
+    private cancel;
+    private ticking;
+    constructor(options?: SchedulerOptions);
+    /** True after `start()` and before `stop()`. */
+    get started(): boolean;
+    /** The names of the schedules with a run that has not ended. */
+    get active(): string[];
+    /** This method starts the scheduler: the first times come after now. It gives the end of the first examination. */
+    start(): Promise<void>;
+    /** This method stops the timer, aborts the runs, and gives the end of the runs. */
+    stop(): Promise<void>;
+    /** This method gives the end of the examination in progress and of the runs in progress. */
+    settled(): Promise<void>;
+    /**
+     * This method examines the schedules now and starts each one whose time came. It does not wait
+     * for the runs. A second call during an examination gives the same examination.
+     */
+    tick(): Promise<void>;
+    /** This method starts one run of a schedule now, unless it has a run in progress. It gives the event of the run. */
+    runNow(id: string): Promise<ScheduleRunEvent>;
+    private examine;
+    /** This method arms the timer for the next minute, or for an earlier time that is due. */
+    private arm;
+    /** This method gives an event to `onRun`. An error of `onRun` goes to `onError`, not to the scheduler. */
+    private report;
+    /** This method records a time that came during a run of the same schedule. */
+    private skip;
+    /** This method starts a run, unless the schedule has one. It gives false for a schedule with a run. */
+    private launch;
+    /** One run: the program through the registry, then its record. */
+    private run;
+    /** The options of an invocation: the policy of the host, a capability and the signal of the run. */
+    private invokeOptions;
+    /** The program of a schedule through the registry, after a load from the program store when the registry does not have it. */
+    private invoke;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAWL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,UAAU,EAEf,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAGtE,mDAAmD;AACnD,eAAO,MAAM,sBAAsB,SAAU,CAAC;AAE9C,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACpD,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CAC/F;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAClD,oHAAoH;IACpH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7C,mHAAmH;IACnH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACjE,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC3D;AA0BD,uEAAuE;AACvE,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8E;IACnG,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAA4B;IAE3C,YAAY,OAAO,GAAE,gBAAqB,EAQzC;IAED,gDAAgD;IAChD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gEAAgE;IAChE,IAAI,MAAM,IAAI,MAAM,EAAE,CAErB;IAED,mHAAmH;IAC7G,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3B;IAED,mFAAmF;IAC7E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1B;IAED,4FAA4F;IACtF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAG7B;IAED;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAMpB;IAED,oHAAoH;IAC9G,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAMlD;YAEa,OAAO;IA6BrB,0FAA0F;IAC1F,OAAO,CAAC,GAAG;IAYX,0GAA0G;IAC1G,OAAO,CAAC,MAAM;IAQd,8EAA8E;IAC9E,OAAO,CAAC,IAAI;IASZ,uGAAuG;IACvG,OAAO,CAAC,MAAM;IAYd,kEAAkE;YACpD,GAAG;IAqCjB,oGAAoG;IACpG,OAAO,CAAC,aAAa;IAcrB,8HAA8H;YAChH,MAAM;CAoBrB"}

package/dist/scheduler.js

@@ -0,0 +1,274 @@
+/**
+ * The scheduler: a host starts it, and it starts the stored programs of the schedules at their
+ * times (roadmap R46).
+ *
+ * - It wakes at each minute (the unit of cron), reads the schedules of its store, and starts each
+ *   schedule whose time came. A schedule that a procedure adds or removes counts at the next minute.
+ * - A run goes through the registry, with the capability of the host narrowed by the capability
+ *   of the caller that added the schedule. The expose rule, the call rule, the interceptors and
+ *   the resources of the host policy apply too.
+ * - A schedule has at most one run at a time. A time that comes during a run does not start a
+ *   second run: the store counts it as skipped.
+ * - The store records the last run of each schedule: its start, its time and its outcome.
+ * - A run that passes `runTimeoutMs` gets the abort of its signal and the outcome `TIMEOUT`. The
+ *   schedule stays busy until the handler ends: a handler that does not stop blocks only its own
+ *   schedule.
+ * - The scheduler does not run the times that it missed while it was stopped. Times that it
+ *   missed during a run or a slow minute give one run, not one for each time.
+ * - The timers use an injectable `Clock` (`after` and `now`), and the calendar uses an injectable
+ *   wall clock (`now`, default `Date.now`). A test gives `fakeClock` of `@mark1russell7/service/testing`.
+ */
+import { InvocationError, PROCEDURE_REGISTRY, invokePath, invokeProcedure, isRuntimeDefined, keyToPath, narrowCapability, outputValue, realClock, } from "@procedures/client";
+import { nextTime, parseCron } from "./cron.js";
+import { ScheduleError } from "./errors.js";
+import { findProgram } from "./programs.js";
+import { defaultScheduleStore } from "./store.js";
+/** The default time limit of a run: 10 minutes. */
+export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+const versionOf = (schedule) => `${schedule.createdAt}|${schedule.cron}|${schedule.timeZone}`;
+/** The code and the message of an error. */
+function errorInfo(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error?.code;
+    return typeof code === "string" ? { code, message } : { message };
+}
+/** The next time of a schedule after a time, or undefined for an expression that is not correct. */
+function nextOf(schedule, after) {
+    try {
+        return nextTime(parseCron(schedule.cron), after, schedule.timeZone);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A scheduler of the stored programs. See the comment of the file. */
+export class Scheduler {
+    registry;
+    store;
+    clock;
+    now;
+    runTimeoutMs;
+    options;
+    due = new Map();
+    runs = new Map();
+    startedAt;
+    cancel;
+    ticking;
+    constructor(options = {}) {
+        this.options = options;
+        this.registry = options.registry ?? PROCEDURE_REGISTRY;
+        this.store = options.store ?? defaultScheduleStore;
+        this.clock = options.clock ?? realClock;
+        this.now = options.now ?? (() => Date.now());
+        this.runTimeoutMs = options.runTimeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+        if (!(this.runTimeoutMs >= 0))
+            throw new TypeError("Scheduler: runTimeoutMs must be 0 or more");
+    }
+    /** True after `start()` and before `stop()`. */
+    get started() {
+        return this.startedAt !== undefined;
+    }
+    /** The names of the schedules with a run that has not ended. */
+    get active() {
+        return [...this.runs.keys()].sort();
+    }
+    /** This method starts the scheduler: the first times come after now. It gives the end of the first examination. */
+    async start() {
+        if (this.startedAt !== undefined)
+            return;
+        this.startedAt = this.now();
+        await this.tick();
+    }
+    /** This method stops the timer, aborts the runs, and gives the end of the runs. */
+    async stop() {
+        this.startedAt = undefined;
+        this.cancel?.();
+        this.cancel = undefined;
+        this.due.clear();
+        for (const run of this.runs.values())
+            run.controller.abort(new Error("The scheduler stopped"));
+        await this.settled();
+    }
+    /** This method gives the end of the examination in progress and of the runs in progress. */
+    async settled() {
+        await this.ticking;
+        await Promise.all([...this.runs.values()].map((run) => run.promise));
+    }
+    /**
+     * This method examines the schedules now and starts each one whose time came. It does not wait
+     * for the runs. A second call during an examination gives the same examination.
+     */
+    tick() {
+        this.ticking ??= this.examine().finally(() => {
+            this.ticking = undefined;
+            this.arm();
+        });
+        return this.ticking;
+    }
+    /** This method starts one run of a schedule now, unless it has a run in progress. It gives the event of the run. */
+    async runNow(id) {
+        const schedule = await this.store.get(id);
+        if (schedule === undefined)
+            throw new ScheduleError("NOT_FOUND", `No schedule is named ${id}`);
+        return new Promise((resolve) => {
+            if (!this.launch(schedule, this.now(), resolve))
+                resolve(this.skip(schedule, this.now()));
+        });
+    }
+    async examine() {
+        if (this.startedAt === undefined)
+            return;
+        const now = this.now();
+        let schedules;
+        try {
+            schedules = await this.store.list();
+        }
+        catch (error) {
+            this.options.onError?.(error);
+            return;
+        }
+        const ids = new Set(schedules.map((schedule) => schedule.id));
+        for (const id of this.due.keys())
+            if (!ids.has(id))
+                this.due.delete(id);
+        for (const schedule of schedules) {
+            // A stop during the read of the store starts nothing
+            if (this.startedAt === undefined)
+                return;
+            const version = versionOf(schedule);
+            let due = this.due.get(schedule.id);
+            if (due === undefined || due.version !== version) {
+                // A new or a changed schedule: its first time is after it was added, and after the start
+                due = { version, at: nextOf(schedule, Math.max(schedule.createdAt, this.startedAt) - 1) };
+                this.due.set(schedule.id, due);
+            }
+            if (due.at === undefined || due.at > now)
+                continue;
+            // The times that passed give one run: the next time comes after now
+            due.at = nextOf(schedule, now);
+            if (!this.launch(schedule, now))
+                void this.skip(schedule, now);
+        }
+    }
+    /** This method arms the timer for the next minute, or for an earlier time that is due. */
+    arm() {
+        if (this.startedAt === undefined)
+            return;
+        this.cancel?.();
+        const now = this.now();
+        let wake = Math.floor(now / 60_000) * 60_000 + 60_000;
+        for (const due of this.due.values())
+            if (due.at !== undefined && due.at < wake)
+                wake = due.at;
+        this.cancel = this.clock.after(Math.max(0, wake - now), () => {
+            this.cancel = undefined;
+            void this.tick();
+        });
+    }
+    /** This method gives an event to `onRun`. An error of `onRun` goes to `onError`, not to the scheduler. */
+    report(event) {
+        try {
+            this.options.onRun?.(event);
+        }
+        catch (error) {
+            this.options.onError?.(error);
+        }
+    }
+    /** This method records a time that came during a run of the same schedule. */
+    skip(schedule, now) {
+        const event = { id: schedule.id, program: schedule.program, outcome: "skipped", startedAt: now, durationMs: 0 };
+        void this.store
+            .update(schedule.id, (current) => (current.createdAt === schedule.createdAt ? { ...current, skipped: current.skipped + 1 } : undefined))
+            .catch((error) => this.options.onError?.(error));
+        this.report(event);
+        return event;
+    }
+    /** This method starts a run, unless the schedule has one. It gives false for a schedule with a run. */
+    launch(schedule, startedAt, done) {
+        if (this.runs.has(schedule.id))
+            return false;
+        const controller = new AbortController();
+        const promise = this.run(schedule, startedAt, controller).then((event) => {
+            this.runs.delete(schedule.id);
+            this.report(event);
+            done?.(event);
+        });
+        this.runs.set(schedule.id, { promise, controller });
+        return true;
+    }
+    /** One run: the program through the registry, then its record. */
+    async run(schedule, startedAt, controller) {
+        const start = this.clock.now();
+        let timedOut = false;
+        const stopTimer = this.runTimeoutMs > 0
+            ? this.clock.after(this.runTimeoutMs, () => {
+                timedOut = true;
+                controller.abort(new Error(`The run of ${schedule.id} passed its time limit of ${this.runTimeoutMs} ms`));
+            })
+            : undefined;
+        let error;
+        try {
+            await this.invoke(schedule, controller.signal);
+        }
+        catch (caught) {
+            error = errorInfo(caught);
+        }
+        finally {
+            stopTimer?.();
+        }
+        if (timedOut)
+            error = { code: "TIMEOUT", message: `The run passed its time limit of ${this.runTimeoutMs} ms${error ? `: ${error.message}` : ""}` };
+        const run = {
+            startedAt,
+            durationMs: Math.max(0, this.clock.now() - start),
+            outcome: error === undefined ? "success" : "failure",
+            ...(error !== undefined ? { error } : {}),
+        };
+        try {
+            await this.store.update(schedule.id, (current) => current.createdAt === schedule.createdAt
+                ? { ...current, lastRun: run, runs: current.runs + 1, failures: current.failures + (error === undefined ? 0 : 1) }
+                : undefined);
+        }
+        catch (caught) {
+            this.options.onError?.(caught);
+        }
+        return { id: schedule.id, program: schedule.program, outcome: run.outcome, startedAt, durationMs: run.durationMs, ...(error !== undefined ? { error } : {}) };
+    }
+    /** The options of an invocation: the policy of the host, a capability and the signal of the run. */
+    invokeOptions(capability, signal) {
+        const policy = this.options.policy;
+        return {
+            registry: this.registry,
+            signal,
+            ...(capability !== undefined ? { capability } : {}),
+            ...(policy?.expose ? { expose: policy.expose } : {}),
+            ...(policy?.strictCalls ? { strictCalls: true } : {}),
+            ...(policy && policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
+            ...(policy?.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),
+            ...(policy?.resources ? { resources: policy.resources } : {}),
+        };
+    }
+    /** The program of a schedule through the registry, after a load from the program store when the registry does not have it. */
+    async invoke(schedule, signal) {
+        const path = keyToPath(schedule.program);
+        const host = this.options.capability ?? this.options.policy?.capabilityOf?.();
+        if ((await findProgram(this.registry, schedule.program)) === "store") {
+            // The load defines the program: a step of the host, with the capability of the host
+            await outputValue(await invokePath(["procedure", "load"], { path }, this.invokeOptions(host, signal)), ["procedure", "load"]);
+        }
+        const procedure = this.registry.get(path);
+        if (procedure === undefined || !isRuntimeDefined(procedure)) {
+            throw new ScheduleError("NOT_FOUND", `The program ${schedule.program} is not in the registry after its load`);
+        }
+        const capability = schedule.capability === undefined ? host : narrowCapability(host, schedule.capability, this.options.policy?.clearanceOrder);
+        if (signal.aborted)
+            throw new InvocationError("ABORTED", `The run of ${schedule.id} was aborted before its start`, path);
+        const output = await invokeProcedure(procedure, schedule.input ?? {}, this.invokeOptions(capability, signal));
+        if (output.kind === "stream") {
+            for await (const _item of output.items) {
+                // A program that gives a stream runs to its end
+            }
+        }
+    }
+}
+//# sourceMappingURL=scheduler.js.map