@nestjs/workflows 0.0.1

package/dist/core/retries/retry.js

@@ -0,0 +1,107 @@
+import { parseDuration } from '../time/duration.js';
+/** The family's default: 3 attempts, 1s doubling up to 5m, no jitter. */
+const DEFAULT_RETRY = {
+    attempts: 3,
+    backoff: { delay: 1_000, factor: 2, maxDelay: 300_000, jitter: 'none' },
+};
+const DEFAULT_BACKOFF = DEFAULT_RETRY.backoff;
+/**
+ * Checks `retry` (a count, `false` or `RetrySettings`) and resolves it over `base`, field by field: `undefined` is
+ * `base`, `false` one attempt, a number the attempts. `base` defaults to the family's default: 3 attempts, 1s doubling
+ * up to 5m, no jitter. Throws a `TypeError` for invalid settings, so they fail where they are given rather than at the
+ * first retry.
+ *
+ * ```ts
+ * const defaults = resolveRetry(moduleOptions.retry);
+ * const policy = resolveRetry(jobOptions.retry, defaults);
+ * ```
+ */
+export function resolveRetry(retry, base = DEFAULT_RETRY) {
+    if (retry === undefined) {
+        return base;
+    }
+    if (retry === false) {
+        return { ...base, attempts: 1 };
+    }
+    if (typeof retry === 'number') {
+        return { ...base, attempts: attempts(retry) };
+    }
+    const { backoff } = retry;
+    return {
+        attempts: retry.attempts === undefined ? base.attempts : attempts(retry.attempts),
+        backoff: typeof backoff === 'function'
+            ? (attempt, error) => parseDuration(backoff(attempt, error))
+            : backoff
+                ? resolveBackoff(backoff, typeof base.backoff === 'function' ? DEFAULT_BACKOFF : base.backoff)
+                : base.backoff,
+        retryIf: retry.retryIf ?? base.retryIf,
+    };
+}
+/**
+ * The wait (ms) after the failed `attempt` (1-based): `delay * factor^(attempt - 1)`, capped at `maxDelay`, then
+ * randomized by `jitter` (`'full'`: from 0 to the wait, `'equal'`: from half of it to all of it). `random` returns a
+ * number in `[0, 1)`, as `Math.random()` (the default) does.
+ *
+ * ```ts
+ * backoffDelay({ delay: 1_000, factor: 2, maxDelay: 60_000, jitter: 'none' }, 4); // 8_000
+ * ```
+ */
+export function backoffDelay(backoff, attempt, random = Math.random) {
+    const wait = Math.min(backoff.maxDelay, backoff.delay * backoff.factor ** (attempt - 1));
+    switch (backoff.jitter) {
+        case 'full':
+            return Math.floor(random() * wait);
+        case 'equal':
+            return Math.floor(wait / 2 + random() * (wait / 2));
+        default:
+            return wait;
+    }
+}
+/**
+ * Whether, and when, to retry after `attempt` (1-based) failed with `error`: not once the policy's attempts are
+ * spent, nor when `retryIf` returns false; otherwise after the backoff's wait. A `retryIf` or backoff function that
+ * throws gives up, with what it threw. Errors that must never be retried (a `NonRetryableStepError`) are the caller's
+ * to check first.
+ *
+ * ```ts
+ * const next = nextRetry(resolveRetry({ attempts: 3 }), 1, new Error('ECONNRESET'));
+ * // { retry: true, delay: 1_000 }
+ * ```
+ */
+export function nextRetry(policy, attempt, error) {
+    if (attempt >= policy.attempts) {
+        return { retry: false, reason: 'exhausted' };
+    }
+    try {
+        if (!(policy.retryIf?.(error, attempt) ?? true)) {
+            return { retry: false, reason: 'refused' };
+        }
+        const { backoff } = policy;
+        return { retry: true, delay: typeof backoff === 'function' ? backoff(attempt, error) : backoffDelay(backoff, attempt) };
+    }
+    catch (thrown) {
+        return { retry: false, reason: 'threw', error: thrown };
+    }
+}
+function resolveBackoff(backoff, base) {
+    const factor = backoff.factor ?? base.factor;
+    if (!(factor > 0)) {
+        throw new TypeError(`Invalid backoff factor ${factor}. Use a positive number (1 = constant).`);
+    }
+    const jitter = backoff.jitter ?? base.jitter;
+    if (!['full', 'equal', 'none'].includes(jitter)) {
+        throw new TypeError(`Invalid backoff jitter "${jitter}". Use "full", "equal" or "none".`);
+    }
+    return {
+        delay: backoff.delay === undefined ? base.delay : parseDuration(backoff.delay),
+        factor,
+        maxDelay: backoff.maxDelay === undefined ? base.maxDelay : parseDuration(backoff.maxDelay),
+        jitter,
+    };
+}
+function attempts(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new TypeError(`Invalid retry attempts ${value}. Use a whole number of attempts, including the first.`);
+    }
+    return Math.max(1, value);
+}

package/dist/core/scheduling/cron.util.d.ts

@@ -0,0 +1,52 @@
+/** `n#k` in the day-of-week field: the `nth` (1-5) `weekday` (0-6, Sunday is 0) of the month. */
+export interface CronNthWeekday {
+    readonly weekday: number;
+    readonly nth: number;
+}
+/** A parsed cron expression: the values each field allows, ascending. */
+export interface CronExpression {
+    /** The expression as given. */
+    readonly source: string;
+    readonly seconds: readonly number[];
+    readonly minutes: readonly number[];
+    readonly hours: readonly number[];
+    /** 1-31; `L` is `lastDayOfMonth`. */
+    readonly daysOfMonth: readonly number[];
+    readonly lastDayOfMonth: boolean;
+    /** 1-12. */
+    readonly months: readonly number[];
+    /** 0-6, Sunday is 0 (7 is read as 0). */
+    readonly daysOfWeek: readonly number[];
+    /** `nL`: the last such weekday of the month. */
+    readonly lastWeekdays: readonly number[];
+    readonly nthWeekdays: readonly CronNthWeekday[];
+    /** Whether the day-of-month text starts with something other than `*` or `?` (Vixie cron's DOM_STAR, negated). */
+    readonly dayOfMonthRestricted: boolean;
+    /** Whether the day-of-week text starts with something other than `*` or `?` (Vixie cron's DOW_STAR, negated). */
+    readonly dayOfWeekRestricted: boolean;
+}
+/**
+ * Parses 5 fields (minute hour day-of-month month day-of-week) or 6 (second first), whitespace-separated, or a
+ * nickname (`@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight`, `@hourly`). A field is a list
+ * (`a,b-c,*\/n`) of `*` or `?` (any), values, ranges `a-b` and steps `*\/n`, `a-b/n` and `a/n` (a to the field's
+ * maximum). Months take JAN-DEC and days of the week SUN-SAT (any case, in ranges too); days of the week are 0-7,
+ * where 0 and 7 are Sunday. The day of the month also takes `L` (its last day), the day of the week `nL` (the last
+ * weekday n of the month, `5L` the last Friday) and `n#k` (the k-th weekday n, k 1-5, `1#1` the first Monday).
+ *
+ * Days match as in Vixie cron and cronie: when both day fields are restricted, a day that matches either one runs;
+ * otherwise a day must match both. A field whose text starts with `*` or `?` is not restricted, even with a step
+ * (Vixie's DOM_STAR and DOW_STAR), so `0 0 *\/2 * 1` runs on odd days of the month that are Mondays, while
+ * `0 0 1,15 * 1` runs on the 1st, the 15th and every Monday.
+ *
+ * Throws a TypeError for a malformed expression and for one that never matches (February 30).
+ */
+export declare function parseCron(expression: string): CronExpression;
+/**
+ * The first occurrence strictly after instant `after`, in `tz`; null if none within 50 years. An occurrence is a
+ * wall time in `tz` that matches every field, to the second, mapped to an instant as `fromWallTime` does: on the day
+ * clocks go forward a skipped 02:30 runs at 03:30 (once, even when 03:30 matches too); on the day they go back a
+ * repeated 02:30 runs once, the first time (so an every-minute cron skips the repeated hour's second pass).
+ */
+export declare function nextCron(cron: CronExpression, after: number, tz: string): number | null;
+/** Occurrences strictly after `after`, ascending, strictly increasing (no duplicate instants), in `tz`. */
+export declare function cronOccurrences(cron: CronExpression, after: number, tz: string): Generator<number>;

package/dist/core/scheduling/cron.util.js

@@ -0,0 +1,262 @@
+import { fromWallTime, recentClockChange, toWallTime } from './time-zone.util.js';
+const SECOND = 1_000;
+const DAY = 86_400_000;
+const HORIZON_YEARS = 50;
+// Any fixed wall time does: a cron that matches at all does so within 50 years of it (February 29 within 8 years,
+// the fifth Monday of February within 40, as 2100 isn't a leap year).
+const REFERENCE = Date.UTC(2000, 0, 1);
+const MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const LONGEST_MONTHS = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const NICKNAMES = {
+    '@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 * * * *',
+};
+const SECONDS = { min: 0, max: 59, accepts: 'seconds are 0-59' };
+const MINUTES = { min: 0, max: 59, accepts: 'minutes are 0-59' };
+const HOURS = { min: 0, max: 23, accepts: 'hours are 0-23' };
+const DAYS_OF_MONTH = { min: 1, max: 31, accepts: 'days of the month are 1-31 or L (the last day)' };
+const MONTHS = {
+    min: 1,
+    max: 12,
+    names: ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'],
+    accepts: 'months are 1-12 or JAN-DEC',
+};
+const DAYS_OF_WEEK = {
+    min: 0,
+    max: 7,
+    names: ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'],
+    accepts: 'days of the week are 0-7 (0 and 7 are Sunday) or SUN-SAT, nL (5L is the last Friday) or n#k (1#1 is the first Monday)',
+};
+/**
+ * Parses 5 fields (minute hour day-of-month month day-of-week) or 6 (second first), whitespace-separated, or a
+ * nickname (`@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight`, `@hourly`). A field is a list
+ * (`a,b-c,*\/n`) of `*` or `?` (any), values, ranges `a-b` and steps `*\/n`, `a-b/n` and `a/n` (a to the field's
+ * maximum). Months take JAN-DEC and days of the week SUN-SAT (any case, in ranges too); days of the week are 0-7,
+ * where 0 and 7 are Sunday. The day of the month also takes `L` (its last day), the day of the week `nL` (the last
+ * weekday n of the month, `5L` the last Friday) and `n#k` (the k-th weekday n, k 1-5, `1#1` the first Monday).
+ *
+ * Days match as in Vixie cron and cronie: when both day fields are restricted, a day that matches either one runs;
+ * otherwise a day must match both. A field whose text starts with `*` or `?` is not restricted, even with a step
+ * (Vixie's DOM_STAR and DOW_STAR), so `0 0 *\/2 * 1` runs on odd days of the month that are Mondays, while
+ * `0 0 1,15 * 1` runs on the 1st, the 15th and every Monday.
+ *
+ * Throws a TypeError for a malformed expression and for one that never matches (February 30).
+ */
+export function parseCron(expression) {
+    if (typeof expression !== 'string') {
+        throw new TypeError(`Invalid cron expression ${JSON.stringify(expression)}. Use a string, such as "0 9 * * MON-FRI".`);
+    }
+    const trimmed = expression.trim();
+    const text = trimmed.startsWith('@') ? NICKNAMES[trimmed.toLowerCase()] : trimmed;
+    if (text === undefined) {
+        throw new TypeError(`Invalid cron expression "${expression}": use @yearly, @annually, @monthly, @weekly, @daily, @midnight or @hourly, or 5 or 6 fields.`);
+    }
+    const fields = text === '' ? [] : text.split(/\s+/);
+    if (fields.length !== 5 && fields.length !== 6) {
+        throw new TypeError(`Invalid cron expression "${expression}": use 5 fields (minute hour day-of-month month day-of-week) or 6 (second first), not ${fields.length}.`);
+    }
+    const [second, minute, hour, dayOfMonth, month, dayOfWeek] = fields.length === 6 ? fields : ['0', ...fields];
+    const failIn = (field) => (reason) => {
+        throw new TypeError(`Invalid cron field "${field}" in "${expression}": ${reason}.`);
+    };
+    const cron = {
+        source: expression,
+        seconds: parseList(second, SECONDS, failIn(second)),
+        minutes: parseList(minute, MINUTES, failIn(minute)),
+        hours: parseList(hour, HOURS, failIn(hour)),
+        ...parseDaysOfMonth(dayOfMonth, failIn(dayOfMonth)),
+        months: parseList(month, MONTHS, failIn(month)),
+        ...parseDaysOfWeek(dayOfWeek, failIn(dayOfWeek)),
+        dayOfMonthRestricted: !/^[*?]/.test(dayOfMonth),
+        dayOfWeekRestricted: !/^[*?]/.test(dayOfWeek),
+    };
+    if (nextMatch(cron, REFERENCE, addYears(REFERENCE, HORIZON_YEARS)) === null) {
+        throw new TypeError(`Invalid cron expression "${expression}": it never matches${neverReason(cron)}.`);
+    }
+    return cron;
+}
+/**
+ * The first occurrence strictly after instant `after`, in `tz`; null if none within 50 years. An occurrence is a
+ * wall time in `tz` that matches every field, to the second, mapped to an instant as `fromWallTime` does: on the day
+ * clocks go forward a skipped 02:30 runs at 03:30 (once, even when 03:30 matches too); on the day they go back a
+ * repeated 02:30 runs once, the first time (so an every-minute cron skips the repeated hour's second pass).
+ */
+export function nextCron(cron, after, tz) {
+    // Right after clocks went forward, a skipped wall time that lands later is still ahead, though its wall time is
+    // before `after`'s: search from as far back as they jumped.
+    const from = Math.floor((toWallTime(after, tz) - Math.max(0, recentClockChange(after, tz))) / SECOND) * SECOND + SECOND;
+    let until = addYears(from, HORIZON_YEARS);
+    let next = null;
+    for (let wall = nextMatch(cron, from, until); wall !== null; wall = nextMatch(cron, wall + SECOND, until)) {
+        const instant = fromWallTime(wall, tz);
+        if (instant > after && (next === null || instant < next)) {
+            next = instant;
+            // A wall time in a gap lands the gap's length later, so a match between it and where it landed comes first
+            // (with a 30-minute gap, 02:10 lands at 02:40, after 02:35).
+            until = toWallTime(instant, tz) - SECOND;
+        }
+    }
+    return next;
+}
+/** Occurrences strictly after `after`, ascending, strictly increasing (no duplicate instants), in `tz`. */
+export function* cronOccurrences(cron, after, tz) {
+    for (let next = nextCron(cron, after, tz); next !== null; next = nextCron(cron, next, tz)) {
+        yield next;
+    }
+}
+/** The first wall time at or after `from` (a whole second) that every field allows, or null past `until`. */
+function nextMatch(cron, from, until) {
+    let wall = from;
+    // A field that doesn't allow its value moves to its next allowed one, resetting the fields below; when none is
+    // left, it moves the field above instead.
+    while (wall <= until) {
+        const date = new Date(wall);
+        const year = date.getUTCFullYear();
+        const month = date.getUTCMonth() + 1;
+        const day = date.getUTCDate();
+        const hour = date.getUTCHours();
+        const minute = date.getUTCMinutes();
+        const second = date.getUTCSeconds();
+        const nextMonth = following(cron.months, month);
+        if (nextMonth !== month) {
+            wall = nextMonth === undefined ? Date.UTC(year + 1, cron.months[0] - 1, 1) : Date.UTC(year, nextMonth - 1, 1);
+            continue;
+        }
+        if (!dayMatches(cron, year, month, day, date.getUTCDay())) {
+            wall = Date.UTC(year, month - 1, day + 1);
+            continue;
+        }
+        const nextHour = following(cron.hours, hour);
+        if (nextHour !== hour) {
+            wall = nextHour === undefined ? Date.UTC(year, month - 1, day + 1) : Date.UTC(year, month - 1, day, nextHour);
+            continue;
+        }
+        const nextMinute = following(cron.minutes, minute);
+        if (nextMinute !== minute) {
+            wall = nextMinute === undefined ? Date.UTC(year, month - 1, day, hour + 1) : Date.UTC(year, month - 1, day, hour, nextMinute);
+            continue;
+        }
+        const nextSecond = following(cron.seconds, second);
+        if (nextSecond !== second) {
+            wall =
+                nextSecond === undefined ? Date.UTC(year, month - 1, day, hour, minute + 1) : Date.UTC(year, month - 1, day, hour, minute, nextSecond);
+            continue;
+        }
+        return wall;
+    }
+    return null;
+}
+function dayMatches(cron, year, month, day, weekday) {
+    const length = daysIn(year, month);
+    const byMonthDay = cron.daysOfMonth.includes(day) || (cron.lastDayOfMonth && day === length);
+    const byWeekday = cron.daysOfWeek.includes(weekday) ||
+        (cron.lastWeekdays.includes(weekday) && day + 7 > length) ||
+        cron.nthWeekdays.some((nth) => nth.weekday === weekday && Math.ceil(day / 7) === nth.nth);
+    return cron.dayOfMonthRestricted && cron.dayOfWeekRestricted ? byMonthDay || byWeekday : byMonthDay && byWeekday;
+}
+function parseDaysOfMonth(text, fail) {
+    const items = text.split(',');
+    const lastDayOfMonth = items.some((item) => item.toUpperCase() === 'L');
+    const rest = items.filter((item) => item.toUpperCase() !== 'L');
+    return { daysOfMonth: rest.length > 0 ? parseList(rest.join(','), DAYS_OF_MONTH, fail) : [], lastDayOfMonth };
+}
+function parseDaysOfWeek(text, fail) {
+    const lastWeekdays = new Set();
+    const nthWeekdays = [];
+    const rest = [];
+    for (const item of text.split(',')) {
+        const last = /^(\w+)L$/i.exec(item);
+        const nth = /^(\w+)#(.*)$/.exec(item);
+        if (last) {
+            lastWeekdays.add(parseValue(last[1], DAYS_OF_WEEK, fail) % 7);
+        }
+        else if (nth) {
+            if (!/^[1-5]$/.test(nth[2])) {
+                fail(`k in n#k is 1-5 (1#1 is the first Monday of the month)`);
+            }
+            nthWeekdays.push({ weekday: parseValue(nth[1], DAYS_OF_WEEK, fail) % 7, nth: Number(nth[2]) });
+        }
+        else {
+            rest.push(item);
+        }
+    }
+    const daysOfWeek = rest.length > 0 ? parseList(rest.join(','), DAYS_OF_WEEK, fail).map((day) => day % 7) : [];
+    return { daysOfWeek: [...new Set(daysOfWeek)].sort((a, b) => a - b), lastWeekdays: [...lastWeekdays].sort((a, b) => a - b), nthWeekdays };
+}
+/** The values a list of `*`, `?`, values, ranges and steps allows, ascending. */
+function parseList(text, field, fail) {
+    const values = new Set();
+    for (const item of text.split(',')) {
+        if (item === '') {
+            fail('a list item is empty');
+        }
+        const match = /^(?:([*?])|([^-/]+)(?:-([^-/]+))?)(?:\/(.*))?$/.exec(item);
+        if (!match) {
+            fail(field.accepts);
+        }
+        const [, any, low, high, step] = match;
+        if (step !== undefined && !/^\d+$/.test(step)) {
+            fail('a step is a whole number, such as */15');
+        }
+        const by = step === undefined ? 1 : Number(step);
+        if (by === 0) {
+            fail('a step of 0 never moves; use a positive one, such as */15');
+        }
+        const from = any ? field.min : parseValue(low, field, fail);
+        const to = any ? field.max : high !== undefined ? parseValue(high, field, fail) : step !== undefined ? field.max : from;
+        if (from > to) {
+            fail(`the range ${low}-${high} is reversed; put the lower bound first`);
+        }
+        for (let value = from; value <= to; value += by) {
+            values.add(value);
+        }
+    }
+    return [...values].sort((a, b) => a - b);
+}
+function parseValue(text, field, fail) {
+    const named = field.names?.indexOf(text.toUpperCase()) ?? -1;
+    if (named >= 0) {
+        return field.min + named;
+    }
+    if (!/^\d+$/.test(text) || Number(text) < field.min || Number(text) > field.max) {
+        fail(field.accepts);
+    }
+    return Number(text);
+}
+/** Why a cron never matches, when it's because every day of the month it allows is past the end of its months. */
+function neverReason(cron) {
+    const [first] = cron.daysOfMonth;
+    if (cron.lastDayOfMonth || first === undefined || cron.months.some((month) => LONGEST_MONTHS[month - 1] >= first)) {
+        return '';
+    }
+    const months = cron.months.map((month) => MONTH_NAMES[month - 1]);
+    return ` (${join(months, 'and')} ${months.length === 1 ? 'has' : 'have'} no ${join(cron.daysOfMonth.map(ordinal), 'or')})`;
+}
+function following(values, from) {
+    for (const value of values) {
+        if (value >= from) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function daysIn(year, month) {
+    return (Date.UTC(year, month, 1) - Date.UTC(year, month - 1, 1)) / DAY;
+}
+function addYears(wall, years) {
+    const date = new Date(wall);
+    date.setUTCFullYear(date.getUTCFullYear() + years);
+    return date.getTime();
+}
+function ordinal(n) {
+    const suffix = n % 100 >= 11 && n % 100 <= 13 ? 'th' : (['th', 'st', 'nd', 'rd'][n % 10] ?? 'th');
+    return `${n}${suffix}`;
+}
+function join(items, conjunction) {
+    return items.length === 1 ? items[0] : `${items.slice(0, -1).join(', ')} ${conjunction} ${items[items.length - 1]}`;
+}

package/dist/core/scheduling/encoded-schedule.store.d.ts

@@ -0,0 +1,26 @@
+import type { LoggerService } from '@nestjs/common';
+import { type PayloadCodecs } from '../codecs/payload-codecs.js';
+import type { PayloadContext } from '../interfaces/payload-codec.interface.js';
+import type { ScheduleClaimRequest, ScheduleQuery, ScheduleRecord, ScheduleSave, ScheduleStore, ScheduleWrite } from '../interfaces/schedule-store.interface.js';
+/**
+ * @internal A `ScheduleStore` as the `Scheduler` sees it: payloads encoded on the way in and decoded on the way out,
+ * so the store sees only what the codec returns. A claimed schedule no codec can read any more is left out of the
+ * claim (logged) and handed back, due when its lease would have ended, and read once the codec is back.
+ */
+export declare class EncodedScheduleStore implements ScheduleStore {
+    readonly inner: ScheduleStore;
+    private readonly codecs;
+    private readonly context;
+    private readonly logger;
+    constructor(inner: ScheduleStore, codecs: PayloadCodecs, context: (schedule: string) => PayloadContext, logger: Pick<LoggerService, 'error'>);
+    /** Whether a codec encodes what is written. */
+    get encodes(): boolean;
+    saveSchedule(save: ScheduleSave): Promise<ScheduleRecord | null>;
+    getSchedule(id: string): Promise<ScheduleRecord | null>;
+    listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
+    deleteSchedule(id: string, revision?: number): Promise<boolean>;
+    claimSchedules(request: ScheduleClaimRequest): Promise<ScheduleRecord[]>;
+    writeSchedule(id: string, token: string, write: ScheduleWrite): Promise<boolean>;
+    /** A schedule as stored, with its payload decoded. Throws if no listed codec can decode it. */
+    decode(record: ScheduleRecord): Promise<ScheduleRecord>;
+}

package/dist/core/scheduling/encoded-schedule.store.js

@@ -0,0 +1,54 @@
+import { isEncodedPayload } from '../codecs/payload-codecs.js';
+/**
+ * @internal A `ScheduleStore` as the `Scheduler` sees it: payloads encoded on the way in and decoded on the way out,
+ * so the store sees only what the codec returns. A claimed schedule no codec can read any more is left out of the
+ * claim (logged) and handed back, due when its lease would have ended, and read once the codec is back.
+ */
+export class EncodedScheduleStore {
+    constructor(inner, codecs, context, logger) {
+        this.inner = inner;
+        this.codecs = codecs;
+        this.context = context;
+        this.logger = logger;
+    }
+    /** Whether a codec encodes what is written. */
+    get encodes() {
+        return this.codecs.encodes;
+    }
+    async saveSchedule(save) {
+        const payload = await this.codecs.encode(save.payload, this.context(save.id));
+        const saved = await this.inner.saveSchedule({ ...save, payload });
+        return saved && this.decode(saved);
+    }
+    async getSchedule(id) {
+        const record = await this.inner.getSchedule(id);
+        return record && this.decode(record);
+    }
+    async listSchedules(query) {
+        return Promise.all((await this.inner.listSchedules(query)).map((record) => this.decode(record)));
+    }
+    deleteSchedule(id, revision) {
+        return this.inner.deleteSchedule(id, revision);
+    }
+    async claimSchedules(request) {
+        const decoded = [];
+        for (const record of await this.inner.claimSchedules(request)) {
+            try {
+                decoded.push(await this.decode(record));
+            }
+            catch (error) {
+                this.logger.error(`Schedule "${record.id}" can't be read, so it isn't run; it is claimed again later. ${error.message}`);
+                // Handed back untouched, due when its lease would have ended; at worst its lease expires, as if its worker died.
+                await this.inner.writeSchedule(record.id, request.token, { now: request.now, state: record.state, wakeAt: request.leaseUntil, release: true }).catch(() => undefined);
+            }
+        }
+        return decoded;
+    }
+    writeSchedule(id, token, write) {
+        return this.inner.writeSchedule(id, token, write);
+    }
+    /** A schedule as stored, with its payload decoded. Throws if no listed codec can decode it. */
+    async decode(record) {
+        return isEncodedPayload(record.payload) ? { ...record, payload: await this.codecs.decode(record.payload, this.context(record.id)) } : record;
+    }
+}

package/dist/core/scheduling/in-memory-schedule.store.d.ts

@@ -0,0 +1,20 @@
+import type { ScheduleClaimRequest, ScheduleQuery, ScheduleRecord, ScheduleSave, ScheduleStore, ScheduleWrite } from '../interfaces/schedule-store.interface.js';
+/**
+ * A `ScheduleStore` in this process's memory: for tests, and for a package's in-memory store (the in-memory workflow
+ * store keeps its schedules in one). Every method does its work before its first `await`, so calls never interleave,
+ * which makes claims, fenced writes and conditional saves atomic without locks. Values are copied on the way in and
+ * out, as a database would.
+ *
+ * ```ts
+ * const scheduler = new Scheduler({ store: new InMemoryScheduleStore(), ... });
+ * ```
+ */
+export declare class InMemoryScheduleStore implements ScheduleStore {
+    private readonly schedules;
+    saveSchedule(save: ScheduleSave): Promise<ScheduleRecord | null>;
+    getSchedule(id: string): Promise<ScheduleRecord | null>;
+    listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
+    deleteSchedule(id: string, revision?: number): Promise<boolean>;
+    claimSchedules(request: ScheduleClaimRequest): Promise<ScheduleRecord[]>;
+    writeSchedule(id: string, token: string, write: ScheduleWrite): Promise<boolean>;
+}

package/dist/core/scheduling/in-memory-schedule.store.js

@@ -0,0 +1,90 @@
+/**
+ * A `ScheduleStore` in this process's memory: for tests, and for a package's in-memory store (the in-memory workflow
+ * store keeps its schedules in one). Every method does its work before its first `await`, so calls never interleave,
+ * which makes claims, fenced writes and conditional saves atomic without locks. Values are copied on the way in and
+ * out, as a database would.
+ *
+ * ```ts
+ * const scheduler = new Scheduler({ store: new InMemoryScheduleStore(), ... });
+ * ```
+ */
+export class InMemoryScheduleStore {
+    constructor() {
+        this.schedules = new Map();
+    }
+    async saveSchedule(save) {
+        const existing = this.schedules.get(save.id);
+        if (save.expectRevision === null ? existing !== undefined : existing?.record.revision !== save.expectRevision) {
+            return null;
+        }
+        const { expectRevision: _expect, releaseLease, now, ...fields } = save;
+        const record = {
+            ...copy(fields),
+            revision: (existing?.record.revision ?? 0) + 1,
+            leaseOwner: existing?.record.leaseOwner ?? null,
+            leaseUntil: releaseLease ? null : (existing?.record.leaseUntil ?? null),
+            createdAt: existing?.record.createdAt ?? now,
+            updatedAt: now,
+        };
+        this.schedules.set(save.id, { record, leaseToken: releaseLease ? null : (existing?.leaseToken ?? null) });
+        return copy(record);
+    }
+    async getSchedule(id) {
+        const schedule = this.schedules.get(id);
+        return schedule ? copy(schedule.record) : null;
+    }
+    async listSchedules(query) {
+        return [...this.schedules.values()]
+            .map((schedule) => schedule.record)
+            .filter((record) => (query.target === undefined || record.target === query.target) && (query.declared === undefined || record.declared === query.declared))
+            .sort((a, b) => compare(a.id, b.id))
+            .slice(query.offset, query.offset + query.limit)
+            .map(copy);
+    }
+    async deleteSchedule(id, revision) {
+        const schedule = this.schedules.get(id);
+        if (!schedule || (revision !== undefined && schedule.record.revision !== revision)) {
+            return false;
+        }
+        return this.schedules.delete(id);
+    }
+    async claimSchedules(request) {
+        const targets = new Set(request.targets);
+        const due = [...this.schedules.values()]
+            .filter(({ record }) => !record.paused &&
+            record.wakeAt !== null &&
+            record.wakeAt <= request.now &&
+            (record.leaseUntil === null || record.leaseUntil < request.now) &&
+            targets.has(record.target))
+            .sort((a, b) => a.record.wakeAt - b.record.wakeAt || compare(a.record.id, b.record.id))
+            .slice(0, request.limit);
+        for (const schedule of due) {
+            schedule.leaseToken = request.token;
+            schedule.record.leaseOwner = request.owner;
+            schedule.record.leaseUntil = request.leaseUntil;
+        }
+        return due.map((schedule) => copy(schedule.record));
+    }
+    async writeSchedule(id, token, write) {
+        const schedule = this.schedules.get(id);
+        if (!schedule || schedule.leaseToken === null || schedule.leaseToken !== token) {
+            return false;
+        }
+        const { record } = schedule;
+        record.state = copy(write.state);
+        record.wakeAt = write.wakeAt;
+        record.revision++;
+        record.updatedAt = write.now;
+        if (write.release) {
+            schedule.leaseToken = null;
+            record.leaseUntil = null;
+        }
+        return true;
+    }
+}
+function copy(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

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

@@ -0,0 +1,3 @@
+export * from './in-memory-schedule.store.js';
+export * from './schedule-spec.js';
+export * from './scheduler.js';

package/dist/core/scheduling/index.js

@@ -0,0 +1,3 @@
+export * from './in-memory-schedule.store.js';
+export * from './schedule-spec.js';
+export * from './scheduler.js';