@namzu/sdk 44.3.0 → 45.1.0

package/dist/schedules/cron.js

@@ -0,0 +1,167 @@
+/**
+ * Five-field cron, parsed into sets.
+ *
+ * Minute, hour, day of month, month, day of week. Lists, ranges, steps and
+ * three-letter names; `0` and `7` are both Sunday. Vixie semantics for the
+ * two day fields: when BOTH are restricted a day matches if EITHER does, which
+ * is what every cron and every existing crontab assumes.
+ *
+ * Refused, each by name: `L`, `W`, `#`, `?`, a sixth (seconds) field and
+ * `@reboot`. A refused token is a better answer than a job that silently
+ * means something the operator did not write.
+ */
+import { ScheduleValidationError } from './errors.js';
+const MACROS = {
+    '@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 MONTH_NAMES = [
+    'jan',
+    'feb',
+    'mar',
+    'apr',
+    'may',
+    'jun',
+    'jul',
+    'aug',
+    'sep',
+    'oct',
+    'nov',
+    'dec',
+];
+const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const FIELDS = [
+    { label: 'minute', min: 0, max: 59 },
+    { label: 'hour', min: 0, max: 23 },
+    { label: 'day of month', min: 1, max: 31 },
+    { label: 'month', min: 1, max: 12, names: MONTH_NAMES, nameBase: 1 },
+    { label: 'day of week', min: 0, max: 7, names: DAY_NAMES, nameBase: 0 },
+];
+function parseValue(raw, field) {
+    const lower = raw.toLowerCase();
+    if (field.names) {
+        const at = field.names.indexOf(lower);
+        if (at >= 0)
+            return at + (field.nameBase ?? 0);
+    }
+    if (!/^\d+$/.test(raw)) {
+        throw new ScheduleValidationError(`${field.label}: "${raw}" is not a number or a name`, raw);
+    }
+    const n = Number(raw);
+    if (n < field.min || n > field.max) {
+        throw new ScheduleValidationError(`${field.label}: ${n} is outside ${field.min}-${field.max}`, raw);
+    }
+    return n;
+}
+function parseField(text, field) {
+    if (text === '')
+        throw new ScheduleValidationError(`${field.label}: empty field`, text);
+    const values = new Set();
+    for (const part of text.split(',')) {
+        if (part === '')
+            throw new ScheduleValidationError(`${field.label}: empty list entry`, text);
+        // Names (`jul`, `wed`) are removed first: they carry the letters the
+        // refused `L` and `W` are spelled with.
+        const withoutNames = part.replace(/[a-z]{3}/gi, (word) => field.names?.includes(word.toLowerCase()) ? '' : word);
+        for (const refused of ['L', 'W', '#', '?']) {
+            if (withoutNames.toUpperCase().includes(refused)) {
+                throw new ScheduleValidationError(`${field.label}: "${refused}" is not supported (in "${part}")`, refused);
+            }
+        }
+        const [rangeText = '', stepText, extra] = part.split('/');
+        if (extra !== undefined) {
+            throw new ScheduleValidationError(`${field.label}: "${part}" has more than one step`, part);
+        }
+        let step = 1;
+        if (stepText !== undefined) {
+            if (!/^\d+$/.test(stepText) || Number(stepText) === 0) {
+                throw new ScheduleValidationError(`${field.label}: step "${stepText}" must be a whole number above 0`, part);
+            }
+            step = Number(stepText);
+        }
+        let lo;
+        let hi;
+        if (rangeText === '*') {
+            lo = field.min;
+            hi = field.label === 'day of week' ? 6 : field.max;
+        }
+        else if (rangeText.includes('-')) {
+            const [a = '', b = '', more] = rangeText.split('-');
+            if (more !== undefined) {
+                throw new ScheduleValidationError(`${field.label}: "${rangeText}" is not a range`, part);
+            }
+            lo = parseValue(a, field);
+            hi = parseValue(b, field);
+            if (hi < lo) {
+                throw new ScheduleValidationError(`${field.label}: range "${rangeText}" runs backwards`, rangeText);
+            }
+        }
+        else {
+            lo = parseValue(rangeText, field);
+            // `5/15` means "from 5, every 15", as in Vixie cron.
+            hi = stepText !== undefined ? (field.label === 'day of week' ? 6 : field.max) : lo;
+        }
+        for (let v = lo; v <= hi; v += step)
+            values.add(v);
+    }
+    return [...values].sort((a, b) => a - b);
+}
+/**
+ * Parse a five-field expression or a macro. Throws
+ * {@link ScheduleValidationError} naming the offending token.
+ */
+export function parseCronExpression(input) {
+    const trimmed = input.trim();
+    if (trimmed === '')
+        throw new ScheduleValidationError('empty cron expression', '');
+    let text = trimmed;
+    if (trimmed.startsWith('@')) {
+        const macro = MACROS[trimmed.toLowerCase()];
+        if (!macro) {
+            throw new ScheduleValidationError(`"${trimmed}" is not a supported macro`, trimmed);
+        }
+        text = macro;
+    }
+    const fields = text.split(/\s+/);
+    if (fields.length === 6) {
+        throw new ScheduleValidationError('six fields: a seconds field is not supported; use five fields (minute hour day month weekday)', fields[0]);
+    }
+    if (fields.length !== 5) {
+        throw new ScheduleValidationError(`expected five fields (minute hour day month weekday), got ${fields.length}`, text);
+    }
+    const [mi = '', ho = '', dom = '', mon = '', dow = ''] = fields;
+    const minutes = parseField(mi, FIELDS[0]);
+    const hours = parseField(ho, FIELDS[1]);
+    const daysOfMonth = parseField(dom, FIELDS[2]);
+    const months = parseField(mon, FIELDS[3]);
+    const weekdays = parseField(dow, FIELDS[4]);
+    const normalizedWeekdays = [...new Set(weekdays.map((d) => (d === 7 ? 0 : d)))].sort((a, b) => a - b);
+    const fixedTime = !/[*/]/.test(mi) && !/[*/]/.test(ho);
+    return {
+        source: fields.join(' '),
+        minutes,
+        hours,
+        daysOfMonth,
+        months,
+        daysOfWeek: normalizedWeekdays,
+        domRestricted: !dom.startsWith('*'),
+        dowRestricted: !dow.startsWith('*'),
+        fixedTime,
+    };
+}
+/** Whether the civil date matches the day fields (Vixie OR rule). */
+export function cronMatchesDay(expr, month, day, weekday) {
+    if (!expr.months.includes(month))
+        return false;
+    const domMatch = expr.daysOfMonth.includes(day);
+    const dowMatch = expr.daysOfWeek.includes(weekday);
+    if (expr.domRestricted && expr.dowRestricted)
+        return domMatch || dowMatch;
+    return domMatch && dowMatch;
+}
+//# sourceMappingURL=cron.js.map

package/dist/schedules/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../../src/schedules/cron.ts"],"names":[],"mappings":"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"}

package/dist/schedules/describe.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A schedule in words, for a confirmation screen or a listing.
+ *
+ * Covers the common shapes exactly and falls back to the expression itself
+ * for anything else, rather than paraphrasing it wrongly.
+ */
+import type { ScheduleSpec } from './types.js';
+export interface DescribeScheduleOptions {
+    /** Zone an `at` or `every` anchor is shown in. Default UTC. */
+    readonly tz?: string;
+}
+/** The schedule in words: `at 03:00 every day (Europe/Istanbul)`. */
+export declare function describeSchedule(spec: ScheduleSpec, options?: DescribeScheduleOptions): string;
+//# sourceMappingURL=describe.d.ts.map

package/dist/schedules/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/schedules/describe.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,YAAY,CAAA;AAoB9D,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CACpB;AAqFD,qEAAqE;AACrE,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,uBAA4B,GACnC,MAAM,CAiBR"}

package/dist/schedules/describe.js

@@ -0,0 +1,133 @@
+/**
+ * A schedule in words, for a confirmation screen or a listing.
+ *
+ * Covers the common shapes exactly and falls back to the expression itself
+ * for anything else, rather than paraphrasing it wrongly.
+ */
+import { parseCronExpression } from './cron.js';
+import { formatWall } from './tz.js';
+const MINUTE = 60_000;
+const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+function pad(n) {
+    return String(n).padStart(2, '0');
+}
+function plural(n, unit) {
+    return `${n} ${unit}${n === 1 ? '' : 's'}`;
+}
+function describeInterval(ms) {
+    if (ms % (7 * 24 * 60 * MINUTE) === 0) {
+        const w = ms / (7 * 24 * 60 * MINUTE);
+        return w === 1 ? 'every week' : `every ${plural(w, 'week')}`;
+    }
+    if (ms % (24 * 60 * MINUTE) === 0) {
+        const d = ms / (24 * 60 * MINUTE);
+        return d === 1 ? 'every 24 hours' : `every ${plural(d, 'day')}`;
+    }
+    if (ms % (60 * MINUTE) === 0) {
+        const h = ms / (60 * MINUTE);
+        return h === 1 ? 'every hour' : `every ${plural(h, 'hour')}`;
+    }
+    const m = ms / MINUTE;
+    return m === 1 ? 'every minute' : `every ${plural(m, 'minute')}`;
+}
+/** `1,2,3,5` → `1–3, 5`. */
+function ranges(values, name) {
+    const out = [];
+    let i = 0;
+    while (i < values.length) {
+        let j = i;
+        while (j + 1 < values.length && values[j + 1] === values[j] + 1)
+            j++;
+        const a = values[i];
+        const b = values[j];
+        if (j - i >= 2)
+            out.push(`${name(a)} through ${name(b)}`);
+        else
+            for (let k = i; k <= j; k++)
+                out.push(name(values[k]));
+        i = j + 1;
+    }
+    return out.join(', ');
+}
+function isFull(values, min, max) {
+    return values.length === max - min + 1;
+}
+function describeDays(e) {
+    const allDom = !e.domRestricted;
+    const allDow = !e.dowRestricted;
+    const allMonths = isFull(e.months, 1, 12);
+    let days;
+    if (allDom && allDow)
+        days = 'every day';
+    else if (allDom)
+        days = `on ${ranges(e.daysOfWeek, (d) => DAY_NAMES[d] ?? String(d))}`;
+    else if (allDow)
+        days = `on day ${ranges(e.daysOfMonth, String)} of the month`;
+    else
+        days = `on day ${ranges(e.daysOfMonth, String)} of the month and on ${ranges(e.daysOfWeek, (d) => DAY_NAMES[d] ?? String(d))}`;
+    if (!allMonths)
+        days += ` in ${ranges(e.months, (m) => MONTH_NAMES[m - 1] ?? String(m))}`;
+    return days;
+}
+function describeTimes(e, source) {
+    const [mi = '', ho = ''] = source.split(' ');
+    const allMinutes = isFull(e.minutes, 0, 59);
+    const allHours = isFull(e.hours, 0, 23);
+    if (allMinutes && allHours)
+        return 'every minute';
+    const stepMinute = /^\*\/(\d+)$/.exec(mi);
+    if (stepMinute && allHours)
+        return `every ${plural(Number(stepMinute[1]), 'minute')}`;
+    if (allHours && e.minutes.length <= 4) {
+        return e.minutes.length === 1 && e.minutes[0] === 0
+            ? 'every hour, on the hour'
+            : `every hour at minute ${e.minutes.join(', ')}`;
+    }
+    const stepHour = /^\*\/(\d+)$/.exec(ho);
+    if (stepHour && e.minutes.length === 1) {
+        return `every ${plural(Number(stepHour[1]), 'hour')} at minute ${e.minutes[0]}`;
+    }
+    if (e.hours.length * e.minutes.length <= 6) {
+        const times = [];
+        for (const h of e.hours)
+            for (const m of e.minutes)
+                times.push(`${pad(h)}:${pad(m)}`);
+        return `at ${times.join(', ')}`;
+    }
+    return `at minute ${ranges(e.minutes, String)} of hour ${ranges(e.hours, String)}`;
+}
+/** The schedule in words: `at 03:00 every day (Europe/Istanbul)`. */
+export function describeSchedule(spec, options = {}) {
+    const tz = options.tz ?? 'UTC';
+    switch (spec.kind) {
+        case 'at':
+            return `once at ${formatWall(Date.parse(spec.at), tz)} (${tz})`;
+        case 'every':
+            return describeInterval(spec.everyMs);
+        case 'cron': {
+            let e;
+            try {
+                e = parseCronExpression(spec.expr);
+            }
+            catch {
+                return `cron "${spec.expr}" (${spec.tz})`;
+            }
+            return `${describeTimes(e, e.source)} ${describeDays(e)} (${spec.tz})`;
+        }
+    }
+}
+//# sourceMappingURL=describe.js.map

package/dist/schedules/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/schedules/describe.ts"],"names":[],"mappings":"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"}

package/dist/schedules/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A schedule, cron expression or time zone that cannot be used.
+ *
+ * `token` names the piece of the input that was refused, so a caller can
+ * point at it instead of repeating the whole expression back.
+ */
+export declare class ScheduleValidationError extends Error {
+    readonly token: string | undefined;
+    constructor(message: string, token?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/schedules/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/schedules/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAK3C"}

package/dist/schedules/errors.js

@@ -0,0 +1,15 @@
+/**
+ * A schedule, cron expression or time zone that cannot be used.
+ *
+ * `token` names the piece of the input that was refused, so a caller can
+ * point at it instead of repeating the whole expression back.
+ */
+export class ScheduleValidationError extends Error {
+    token;
+    constructor(message, token) {
+        super(message);
+        this.name = 'ScheduleValidationError';
+        this.token = token;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/schedules/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/schedules/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACxC,KAAK,CAAoB;IAElC,YAAY,OAAe,EAAE,KAAc;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;CACD"}

package/dist/schedules/evaluate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What to do about one job now: fire, skip, record a miss, or nothing.
+ *
+ * Pure: no clock, no I/O. The host passes the instant, the state it kept and
+ * whether an occurrence was already claimed, and applies the decision itself
+ * (append history, claim, dispatch). Evaluating the same `(state, now)` twice
+ * gives the same answer, so a host that lost its in-memory queue rebuilds it
+ * by evaluating again; an already-claimed key is never fired twice.
+ *
+ * Rules, in order:
+ *
+ * 1. Occurrences due are those in `(lastEvaluatedAt, now]`, counted with a
+ *    cap and never enumerated. A new job counts from its creation. A changed
+ *    revision counts from the change, so editing `0 3 * * *` into `0 4 * * *`
+ *    does not invent catch-ups for 04:00s that never belonged to the job.
+ * 2. `lastEvaluatedAt` never moves backwards: after a backward clock jump
+ *    nothing is due until the wall clock passes it again.
+ * 3. A job that is not active produces skip records only (paused and
+ *    awaiting-confirmation are collapsed per evaluation). A one-shot whose
+ *    time passed while inactive is expired.
+ * 4. The latest due occurrence fires on time (`scheduled`, or `late` once
+ *    more than five seconds late) within the late grace; within the catch-up
+ *    window it fires once as `catch-up` and everything earlier is one
+ *    `missed` record; older than the window, nothing fires.
+ * 5. An unfinished run of the same job skips what came due meanwhile.
+ * 6. A provider quota hold skips what comes due before the hold ends.
+ */
+import type { ScheduleDecision, ScheduleEvaluationInput } from './types.js';
+/** Default catch-up window: seven days. */
+export declare const SCHEDULE_CATCH_UP_WINDOW_MS: number;
+/** Default grace for a fire to still count as on time: two minutes. */
+export declare const SCHEDULE_LATE_GRACE_MS = 120000;
+/** Evaluate one job at `now`. */
+export declare function evaluateJob(input: ScheduleEvaluationInput): ScheduleDecision;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/schedules/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/schedules/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EAGvB,MAAM,YAAY,CAAA;AAEnB,2CAA2C;AAC3C,eAAO,MAAM,2BAA2B,QAA0B,CAAA;AAClE,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,SAAU,CAAA;AAe7C,iCAAiC;AACjC,wBAAgB,WAAW,CAAC,KAAK,EAAE,uBAAuB,GAAG,gBAAgB,CA0H5E"}

package/dist/schedules/evaluate.js

@@ -0,0 +1,158 @@
+/**
+ * What to do about one job now: fire, skip, record a miss, or nothing.
+ *
+ * Pure: no clock, no I/O. The host passes the instant, the state it kept and
+ * whether an occurrence was already claimed, and applies the decision itself
+ * (append history, claim, dispatch). Evaluating the same `(state, now)` twice
+ * gives the same answer, so a host that lost its in-memory queue rebuilds it
+ * by evaluating again; an already-claimed key is never fired twice.
+ *
+ * Rules, in order:
+ *
+ * 1. Occurrences due are those in `(lastEvaluatedAt, now]`, counted with a
+ *    cap and never enumerated. A new job counts from its creation. A changed
+ *    revision counts from the change, so editing `0 3 * * *` into `0 4 * * *`
+ *    does not invent catch-ups for 04:00s that never belonged to the job.
+ * 2. `lastEvaluatedAt` never moves backwards: after a backward clock jump
+ *    nothing is due until the wall clock passes it again.
+ * 3. A job that is not active produces skip records only (paused and
+ *    awaiting-confirmation are collapsed per evaluation). A one-shot whose
+ *    time passed while inactive is expired.
+ * 4. The latest due occurrence fires on time (`scheduled`, or `late` once
+ *    more than five seconds late) within the late grace; within the catch-up
+ *    window it fires once as `catch-up` and everything earlier is one
+ *    `missed` record; older than the window, nothing fires.
+ * 5. An unfinished run of the same job skips what came due meanwhile.
+ * 6. A provider quota hold skips what comes due before the hold ends.
+ */
+import { countOccurrences, nextFireTime, previousFireTime } from './next-fire.js';
+/** Default catch-up window: seven days. */
+export const SCHEDULE_CATCH_UP_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Default grace for a fire to still count as on time: two minutes. */
+export const SCHEDULE_LATE_GRACE_MS = 120_000;
+/** A fire later than this is reported `late` rather than `scheduled`. */
+const LATE_THRESHOLD_MS = 5_000;
+function missedReason(input, firstMissed) {
+    const gap = input.daemon.observedGap;
+    if (gap && firstMissed.getTime() >= gap.from.getTime()) {
+        if (gap.kind === 'asleep')
+            return 'machine-asleep';
+        if (gap.kind === 'clock-forward')
+            return 'clock-jumped-forward';
+    }
+    return 'daemon-not-running';
+}
+/** Evaluate one job at `now`. */
+export function evaluateJob(input) {
+    const { job, state, now } = input;
+    const nowMs = now.getTime();
+    const lateGrace = input.lateGraceMs ?? SCHEDULE_LATE_GRACE_MS;
+    const windowMs = job.catchUp?.windowMs ?? SCHEDULE_CATCH_UP_WINDOW_MS;
+    let baseMs = Date.parse(state.lastEvaluatedAt ?? job.createdAt);
+    if (!Number.isFinite(baseMs))
+        baseMs = Date.parse(job.createdAt);
+    if (state.jobRevision !== undefined && state.jobRevision !== job.revision) {
+        baseMs = Math.max(baseMs, Date.parse(job.updatedAt));
+    }
+    const nextState = (evaluatedMs) => {
+        const next = nextFireTime(job.spec, new Date(evaluatedMs));
+        return {
+            lastEvaluatedAt: new Date(evaluatedMs),
+            ...(next ? { nextFireAt: next } : {}),
+            jobRevision: job.revision,
+        };
+    };
+    if (job.state === 'completed' || job.state === 'expired') {
+        return {
+            skip: [],
+            nextState: { lastEvaluatedAt: new Date(Math.max(baseMs, nowMs)), jobRevision: job.revision },
+        };
+    }
+    // Rule 2: a clock that went backwards decides nothing new.
+    if (nowMs <= baseMs)
+        return { skip: [], nextState: nextState(baseMs) };
+    const due = countOccurrences(job.spec, new Date(baseMs), now);
+    if (due.count === 0 || !due.latest) {
+        if (job.spec.kind === 'at' && Date.parse(job.spec.at) <= baseMs && job.state !== 'active') {
+            return { skip: [], jobTransition: 'expired', nextState: nextState(nowMs) };
+        }
+        return { skip: [], nextState: nextState(nowMs) };
+    }
+    const latest = due.latest;
+    const collapsed = (reason) => [
+        { scheduledFor: latest, reason, count: due.count },
+    ];
+    if (job.state === 'paused' || job.state === 'pending-confirmation') {
+        const reason = job.state === 'paused' ? 'paused' : 'awaiting-confirmation';
+        return {
+            skip: collapsed(reason),
+            ...(job.spec.kind === 'at' ? { jobTransition: 'expired' } : {}),
+            nextState: nextState(nowMs),
+        };
+    }
+    const hold = state.quotaHoldUntil ? Date.parse(state.quotaHoldUntil) : Number.NaN;
+    if (Number.isFinite(hold) && hold > nowMs) {
+        return { skip: collapsed('quota-hold'), nextState: nextState(nowMs) };
+    }
+    if (state.activeRun) {
+        return {
+            skip: collapsed(state.activeRun.status === 'awaiting-approval'
+                ? 'previous-run-awaiting-approval'
+                : 'previous-run-active'),
+            nextState: nextState(nowMs),
+        };
+    }
+    const key = String(latest.getTime());
+    const lateBy = nowMs - latest.getTime();
+    const earlier = due.count - 1;
+    const missedBefore = () => {
+        if (earlier <= 0 || !due.first)
+            return undefined;
+        // The occurrence just before the fired one.
+        const to = previousFireTime(job.spec, new Date(latest.getTime() - 1)) ?? due.first;
+        return {
+            from: due.first,
+            to,
+            count: earlier,
+            capped: due.capped,
+            reason: missedReason(input, due.first),
+        };
+    };
+    const transition = job.spec.kind === 'at' ? { jobTransition: 'completed' } : {};
+    if (input.isClaimed?.(key)) {
+        // Somebody already started it; nothing to fire, nothing missed.
+        return { skip: [], ...transition, nextState: nextState(nowMs) };
+    }
+    if (lateBy <= lateGrace || lateBy <= windowMs) {
+        const trigger = lateBy <= lateGrace ? (lateBy > LATE_THRESHOLD_MS ? 'late' : 'scheduled') : 'catch-up';
+        const missed = missedBefore();
+        return {
+            fire: { key, scheduledFor: latest, trigger },
+            skip: [],
+            ...(missed ? { missed } : {}),
+            ...transition,
+            nextState: nextState(nowMs),
+        };
+    }
+    // Everything due is older than the window.
+    const first = due.first ?? latest;
+    return {
+        skip: [
+            {
+                scheduledFor: latest,
+                reason: job.spec.kind === 'at' ? 'one-shot-expired' : 'beyond-catch-up-window',
+                count: 1,
+            },
+        ],
+        missed: {
+            from: first,
+            to: latest,
+            count: due.count,
+            capped: due.capped,
+            reason: missedReason(input, first),
+        },
+        ...(job.spec.kind === 'at' ? { jobTransition: 'expired' } : {}),
+        nextState: nextState(nowMs),
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/schedules/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/schedules/evaluate.ts"],"names":[],"mappings":"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"}

package/dist/schedules/index.d.ts

@@ -0,0 +1,11 @@
+export { parseCronExpression } from './cron.js';
+export { describeSchedule } from './describe.js';
+export type { DescribeScheduleOptions } from './describe.js';
+export { ScheduleValidationError } from './errors.js';
+export { SCHEDULE_CATCH_UP_WINDOW_MS, SCHEDULE_LATE_GRACE_MS, evaluateJob, } from './evaluate.js';
+export { countOccurrences, nextFireTime, previousFireTime, } from './next-fire.js';
+export { parseDuration, parseScheduleSpec, upcomingFireTimes } from './spec.js';
+export type { ParseScheduleOptions } from './spec.js';
+export { hostTimeZone, validateTimeZone } from './tz.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/schedules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schedules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EACN,2BAA2B,EAC3B,sBAAsB,EACtB,WAAW,GACX,MAAM,eAAe,CAAA;AACtB,OAAO,EACN,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GAChB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC/E,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AACxD,mBAAmB,YAAY,CAAA"}

package/dist/schedules/index.js

@@ -0,0 +1,8 @@
+export { parseCronExpression } from './cron.js';
+export { describeSchedule } from './describe.js';
+export { ScheduleValidationError } from './errors.js';
+export { SCHEDULE_CATCH_UP_WINDOW_MS, SCHEDULE_LATE_GRACE_MS, evaluateJob, } from './evaluate.js';
+export { countOccurrences, nextFireTime, previousFireTime, } from './next-fire.js';
+export { parseDuration, parseScheduleSpec, upcomingFireTimes } from './spec.js';
+export { hostTimeZone, validateTimeZone } from './tz.js';
+//# sourceMappingURL=index.js.map

package/dist/schedules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schedules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EACN,2BAA2B,EAC3B,sBAAsB,EACtB,WAAW,GACX,MAAM,eAAe,CAAA;AACtB,OAAO,EACN,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GAChB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAE/E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA"}