@nestjs/workflows 0.0.1

package/dist/core/scheduling/schedule-spec.js

@@ -0,0 +1,233 @@
+import { parseDuration } from '../time/duration.js';
+import { canonical } from '../utils/canonical.util.js';
+import { cronOccurrences, parseCron } from './cron.util.js';
+import { parseRRule, rruleCounts, rruleOccurrences } from './rrule.util.js';
+import { assertTimeZone } from './time-zone.util.js';
+const MISSED = ['skip', 'once', 'all'];
+const OVERLAP = ['skip', 'allow', 'cancel-previous', 'buffer-one'];
+const MAX_COUNT = 10_000;
+const MAX_PREVIEW = 1_000;
+/** Schedule ids, like workflow names, can't hold the `@` that separates them from the time in an occurrence's run id. */
+const SCHEDULE_ID = /^[\w.:-]+$/;
+/**
+ * Checks a schedule's options and returns its spec: validated, times in milliseconds, defaults applied (`tz: 'UTC'`,
+ * `missed: 'skip'`, `overlap: 'skip'`). Throws a `TypeError` that starts with `owner` for anything invalid, with the
+ * reason (`0 0 30 2 *` never matches: February has no 30th). Fields it doesn't know are left out: a package adds its
+ * own to the spec.
+ *
+ * ```ts
+ * const spec = parseSchedule({ cron: '0 0 8 * * MON', tz: 'Europe/Warsaw', missed: 'once' }, 'Schedule "weekly-digest"');
+ * ```
+ */
+export function parseSchedule(options, owner = 'Schedule') {
+    if (options === null || typeof options !== 'object') {
+        throw new TypeError(`${owner}: expected an object with cron, every or rrule, got ${JSON.stringify(options)}.`);
+    }
+    const kinds = ['cron', 'every', 'rrule'].filter((kind) => options[kind] !== undefined);
+    if (kinds.length !== 1) {
+        throw new TypeError(`${owner}: give exactly one of cron, every and rrule${kinds.length ? `, not ${kinds.join(' and ')}` : ''}.`);
+    }
+    const tz = options.tz ?? 'UTC';
+    assertTimeZone(tz, owner);
+    const startAt = instant(owner, 'startAt', options.startAt);
+    const endAt = instant(owner, 'endAt', options.endAt);
+    if (startAt !== null && endAt !== null && endAt <= startAt) {
+        throw new TypeError(`${owner}: endAt (${new Date(endAt).toISOString()}) must be after startAt (${new Date(startAt).toISOString()}).`);
+    }
+    const timing = {};
+    if (options.cron !== undefined) {
+        if (typeof options.cron !== 'string') {
+            throw new TypeError(`${owner}: cron must be a string, such as '0 8 * * MON'.`);
+        }
+        compiledCron(options.cron);
+        timing.cron = options.cron;
+    }
+    else if (options.every !== undefined) {
+        let every;
+        try {
+            every = parseDuration(options.every);
+        }
+        catch (error) {
+            throw new TypeError(`${owner}: ${error.message}`);
+        }
+        if (every < 1_000) {
+            throw new TypeError(`${owner}: every (${JSON.stringify(options.every)}) must be at least a second.`);
+        }
+        if (options.tz !== undefined) {
+            throw new TypeError(`${owner}: every repeats a fixed interval from startAt (default: the Unix epoch), whatever the time zone; tz doesn't apply. ` +
+                "For a time of day in a time zone, use cron: '0 0 * * *' with tz.");
+        }
+        timing.every = every;
+    }
+    else {
+        if (typeof options.rrule !== 'string') {
+            throw new TypeError(`${owner}: rrule must be a string, such as 'FREQ=WEEKLY;BYDAY=MO;BYHOUR=8'.`);
+        }
+        const rule = compiledRRule(options.rrule);
+        if (rruleCounts(rule) && startAt === null) {
+            throw new TypeError(`${owner}: an rrule with COUNT counts from startAt: give one (or use limit).`);
+        }
+        // COUNT is counted from DTSTART at every computation of the next occurrence: `limit` counts as it goes.
+        if ((rule.count ?? 0) > MAX_COUNT) {
+            throw new TypeError(`${owner}: an rrule's COUNT (${rule.count}) can be at most ${MAX_COUNT}. For more, use limit.`);
+        }
+        timing.rrule = options.rrule;
+    }
+    const limit = options.limit ?? null;
+    if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1)) {
+        throw new TypeError(`${owner}: invalid limit ${JSON.stringify(limit)}. Use a positive integer.`);
+    }
+    const missed = options.missed ?? 'skip';
+    if (!MISSED.includes(missed)) {
+        throw new TypeError(`${owner}: invalid missed ${JSON.stringify(missed)}. Use 'skip', 'once' or 'all'.`);
+    }
+    const overlap = options.overlap ?? 'skip';
+    if (!OVERLAP.includes(overlap)) {
+        throw new TypeError(`${owner}: invalid overlap ${JSON.stringify(overlap)}. Use 'skip', 'allow', 'cancel-previous' or 'buffer-one'.`);
+    }
+    if (missed === 'all' && overlap !== 'allow') {
+        throw new TypeError(`${owner}: missed: 'all' starts every missed occurrence at once, so it needs overlap: 'allow'. ` + "For one catch-up run, use missed: 'once'.");
+    }
+    return { ...timing, tz, startAt, endAt, limit, missed, overlap };
+}
+/**
+ * The times (epoch milliseconds, ascending) of a schedule's next occurrences strictly after `from` (default: now),
+ * at most `count` (default 10, at most 1,000) and at most what its `limit` leaves after `runs` occurrences: a
+ * schedule's preview. No I/O. Throws a `TypeError` that starts with `owner` for an invalid `count` or `from`.
+ *
+ * ```ts
+ * nextOccurrences(parseSchedule({ cron: '0 9 * * MON-FRI', tz: 'America/New_York' }), { from: Date.UTC(2026, 0, 1), count: 2 });
+ * // [Date.UTC(2026, 0, 1, 14), Date.UTC(2026, 0, 2, 14)]: 09:00 EST on Thursday and Friday
+ * ```
+ */
+export function nextOccurrences(spec, options = {}, owner = 'nextOccurrences()') {
+    const count = options.count ?? 10;
+    if (!Number.isSafeInteger(count) || count < 1 || count > MAX_PREVIEW) {
+        throw new TypeError(`${owner}: count (${count}) must be an integer from 1 to ${MAX_PREVIEW}.`);
+    }
+    const from = options.from === undefined ? Date.now() : options.from instanceof Date ? options.from.getTime() : options.from;
+    if (typeof from !== 'number' || !Number.isFinite(from)) {
+        throw new TypeError(`${owner}: invalid from ${String(options.from)}. Pass a valid Date or a timestamp in milliseconds.`);
+    }
+    const left = spec.limit === null ? Infinity : spec.limit - (options.runs ?? 0);
+    const times = [];
+    for (const at of occurrences(spec, from)) {
+        if (times.length >= Math.min(count, left)) {
+            break;
+        }
+        times.push(at);
+    }
+    return times;
+}
+/**
+ * The id of the run an occurrence starts: `<schedule id>@<ISO time of the occurrence>`, such as
+ * `weekly-digest@2026-01-05T07:00:00.000Z`, the same wherever and however often it is started, so a second start of
+ * an occurrence (by a worker that took over) finds the first.
+ *
+ * ```ts
+ * occurrenceId('weekly-digest', Date.UTC(2026, 0, 5, 7)); // 'weekly-digest@2026-01-05T07:00:00.000Z'
+ * ```
+ */
+export function occurrenceId(schedule, at) {
+    return `${schedule}@${new Date(at).toISOString()}`;
+}
+/**
+ * Throws a `TypeError` unless `id` can be a schedule's id: letters, digits, `.`, `:`, `_` and `-` (never the `@` of
+ * an occurrence's run id). `owner`, when given, is named in the message.
+ *
+ * ```ts
+ * assertScheduleId(id, 'queue "emails"'); // Invalid schedule id "weekly digest" of queue "emails". ...
+ * ```
+ */
+export function assertScheduleId(id, owner) {
+    if (typeof id !== 'string' || !SCHEDULE_ID.test(id)) {
+        throw new TypeError(`Invalid schedule id ${JSON.stringify(id)}${owner === undefined ? '' : ` of ${owner}`}. Use letters, digits, ".", ":", "_" or "-".`);
+    }
+}
+/** Whether two specs have the same occurrences (their policies aside). */
+export function sameTiming(a, b) {
+    const timing = ({ cron, every, rrule, tz, startAt, endAt }) => canonical({ cron, every, rrule, tz, startAt, endAt });
+    return timing(a) === timing(b);
+}
+/** The spec's occurrences strictly after `after`, ascending, within `startAt` and `endAt` (not counting `limit`). */
+export function* occurrences(spec, after) {
+    const from = spec.startAt === null ? after : Math.max(after, spec.startAt - 1);
+    let times;
+    if (spec.cron !== undefined) {
+        times = cronOccurrences(compiledCron(spec.cron), from, spec.tz);
+    }
+    else if (spec.rrule !== undefined) {
+        times = rruleOccurrences(compiledRRule(spec.rrule), spec.startAt, spec.tz, from);
+    }
+    else {
+        times = everyOccurrences(spec.every, spec.startAt ?? 0, from);
+    }
+    for (const at of times) {
+        if (spec.endAt !== null && at > spec.endAt) {
+            return;
+        }
+        yield at;
+    }
+}
+/** The first occurrence strictly after `after`, or `null`. */
+export function nextOccurrence(spec, after) {
+    for (const at of occurrences(spec, after)) {
+        return at;
+    }
+    return null;
+}
+/**
+ * The latest `count` occurrences in `[from, to]`, ascending. Looks back from `to` in growing windows, so a
+ * schedule that fell far behind costs as much as the occurrences it returns, not all it missed.
+ */
+export function latestOccurrences(spec, from, to, count) {
+    for (let window = 60_000;; window *= 16) {
+        const start = Math.max(from, to - window);
+        const found = [];
+        for (const at of occurrences(spec, start - 1)) {
+            if (at > to) {
+                break;
+            }
+            found.push(at);
+            if (found.length > count) {
+                found.shift();
+            }
+        }
+        if (found.length === count || start === from) {
+            return found;
+        }
+    }
+}
+function* everyOccurrences(every, anchor, after) {
+    let at = after < anchor ? anchor : anchor + (Math.floor((after - anchor) / every) + 1) * every;
+    for (;;) {
+        yield at;
+        at += every;
+    }
+}
+function instant(owner, name, value) {
+    if (value === undefined) {
+        return null;
+    }
+    const ms = value instanceof Date ? value.getTime() : value;
+    if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+        throw new TypeError(`${owner}: invalid ${name} ${String(value)}. Pass a valid Date or a timestamp in milliseconds.`);
+    }
+    return ms;
+}
+const crons = new Map();
+const rrules = new Map();
+function compiledCron(expression) {
+    let cron = crons.get(expression);
+    if (!cron) {
+        crons.set(expression, (cron = parseCron(expression)));
+    }
+    return cron;
+}
+function compiledRRule(rule) {
+    let compiled = rrules.get(rule);
+    if (!compiled) {
+        rrules.set(rule, (compiled = parseRRule(rule)));
+    }
+    return compiled;
+}

package/dist/core/scheduling/scheduler.d.ts

@@ -0,0 +1,134 @@
+import type { ScheduleSpec } from '../interfaces/schedule.interface.js';
+import type { ScheduleRecord, ScheduleSave, ScheduleStore } from '../interfaces/schedule-store.interface.js';
+import type { ScheduleProduction, SchedulerOptions } from '../interfaces/scheduler-options.interface.js';
+/**
+ * A schedule's fields, as `Scheduler.save()`'s change returns them: what `ScheduleStore.saveSchedule()` takes, without
+ * the condition.
+ *
+ * ```ts
+ * await scheduler.save(id, (current): ScheduleFields | null =>
+ *   current?.declared ? null : scheduler.changed(current, { target: 'emails', declared: false, spec, payload }),
+ * );
+ * ```
+ */
+export type ScheduleFields = Omit<ScheduleSave, 'id' | 'expectRevision' | 'now'>;
+/**
+ * The engine of schedules, over a `ScheduleStore`: it starts each occurrence's run exactly once however many workers
+ * produce them, and keeps the schedules the code declares in step with it, also through rolling deploys. A package
+ * plugs in its runs (`fire`, `running`, `cancel`) and calls `produce()` from its worker's loop.
+ *
+ * - **One run per occurrence.** A production leases the due schedules (`claimSchedules`), records its decisions in
+ *   each (the starts it will make, the runs to cancel) before making them, then clears them and hands the schedule
+ *   back. A worker that dies or loses the lease in between leaves them to the next, which makes them again: a run's
+ *   id, `occurrenceId(schedule, at)`, makes the second start a no-op. `runs`, what `limit` counts, is exact.
+ * - **missed** and **overlap** as `ScheduleOptions` say; a start the store refuses is retried, backing off from a
+ *   second to a minute, ten times in all, while the schedule's other starts go ahead.
+ * - **Declared schedules follow the code.** At startup (`synced()`) and every minute (from `produce()`), a process
+ *   saves the schedules its code declares, confirms them, and takes over one declared otherwise, unless a newer version
+ *   of the code declared it and a process of that code still confirms it. It deletes a declared schedule its code
+ *   doesn't declare once no process confirmed it for five minutes: the code that declares it is gone.
+ *
+ * ```ts
+ * const scheduler = new Scheduler({ store, targets, declared, fire, running, cancel, clock });
+ * await scheduler.synced(); // at startup
+ * const worker = new LeasedWorker({ ..., produce: async () => (await scheduler.produce(owner, leaseMs)).started });
+ * ```
+ */
+export declare class Scheduler<S extends ScheduleSpec = ScheduleSpec> {
+    private readonly options;
+    /** The store, as it holds the schedules: payloads undecoded. */
+    readonly store: ScheduleStore;
+    private readonly encoded;
+    private readonly clock;
+    private readonly logger;
+    private readonly labels;
+    private syncing?;
+    /** When `produce()` next reconciles the declared schedules with the code (the clock's time). */
+    private reconcileAt;
+    private readonly warned;
+    constructor(options: SchedulerOptions<S>);
+    /** The declared schedules, reconciled with the code once per process (again after a failure). Call it at startup. */
+    synced(): Promise<void>;
+    /**
+     * Leases the due schedules of this process's targets and starts their occurrences' runs; every minute it reconciles
+     * the declared schedules first. Call it from the worker's loop (`LeasedWorker`'s `produce`), with its owner and
+     * lease duration.
+     */
+    produce(owner: string, leaseMs: number): Promise<ScheduleProduction>;
+    /**
+     * Applies `change` to the stored schedule until it lands: a write conditional on the revision it read. `change`
+     * returns the new fields, or `null` to leave it. Resolves to the schedule as stored (`null`: none). With `replacing`,
+     * a schedule whose payload no codec can read any more is read as it is stored, so the new payload replaces it; with
+     * `asStored`, it is read and saved as the store holds it, its payload untouched (a pause needs no codec).
+     */
+    save(id: string, change: (current: ScheduleRecord | null) => ScheduleFields | null, options?: {
+        replacing?: boolean;
+        asStored?: boolean;
+    }): Promise<ScheduleRecord | null>;
+    /**
+     * A schedule's fields after a change of what it is: a new one starts with its first occurrence after now; one whose
+     * timing is unchanged keeps its progress; one whose timing changed starts over from now (keeping its runs and the
+     * starts in flight, dropping an occurrence buffered with the old timing) and takes the lease from a worker that
+     * computed with the old timing. Its pause carries over.
+     */
+    changed(current: ScheduleRecord | null, next: {
+        target: string;
+        declared: boolean;
+        spec: S;
+        payload: unknown;
+    }): ScheduleFields;
+    /**
+     * Pauses the schedule at once: it takes the lease, so a worker deciding its occurrences at that moment starts only
+     * what it had already decided, and nothing else starts until `resume()`. Resolves to it as stored, or `null` for an
+     * unknown id.
+     */
+    pause(id: string): Promise<ScheduleRecord | null>;
+    /**
+     * Resumes the schedule from its first occurrence after now: those due while it was paused are passed over, whatever
+     * `missed` says. Resolves to it as stored, or `null` for an unknown id.
+     */
+    resume(id: string): Promise<ScheduleRecord | null>;
+    /** The schedule with its payload decoded, or `null` for an unknown id. Throws when no codec can read its payload. */
+    read(id: string): Promise<ScheduleRecord | null>;
+    /** A schedule as stored, with its payload decoded; `null` (logged once) when no codec can read it any more. */
+    readable(record: ScheduleRecord): Promise<ScheduleRecord>;
+    /**
+     * Where a stored schedule is: when its next occurrence is due (`null` while paused, or once it ended), how many it
+     * started (what `limit` counts), and the occurrence buffered for `overlap: 'buffer-one'`.
+     */
+    progress(record: ScheduleRecord): {
+        nextAt: number | null;
+        runs: number;
+        bufferedAt: number | null;
+    };
+    /**
+     * Reconciles the declared schedules with this process's code: at startup, then about once a minute (from the
+     * productions). Safe in a rolling deploy, where processes of other code run beside it:
+     *
+     * - A schedule its code declares is saved when it is missing, and confirmed (`confirmedAt`) when its last
+     *   confirmation is a minute old. One declared differently is replaced at startup, unless a newer version of the
+     *   code declared it and a process of that code still confirms it; later, only once no process confirms it (the code
+     *   that declared it is gone), or when an older version declared it.
+     * - A declared schedule its code doesn't declare is left while a process confirms it, since the code of a running
+     *   process declares it, and deleted once none has for five minutes, whatever its target: otherwise the schedules of
+     *   a target that no code has any more would stay forever. The processes whose code declares one save it again as
+     *   they start, so after its processes were gone for longer, it starts over: from its next occurrence, unpaused, its
+     *   runs counted from zero.
+     */
+    private reconcile;
+    private declaredChange;
+    /**
+     * A schedule to save with a new payload (the code's, or an upsert's): one with a payload no codec can read any more
+     * (a dropped key) is read as it is stored, its payload marked unreadable, so the new payload can replace it.
+     */
+    private readReplacing;
+    /**
+     * Deletes a declared schedule this process's code doesn't declare, once no process whose code declares it has
+     * confirmed it for five minutes; again if it was written meanwhile, unless that write confirmed it.
+     */
+    private remove;
+    /** Every declared schedule as stored, a page at a time. */
+    private allDeclared;
+    private declared;
+    private produceOne;
+}