@j13b/scheduler 0.0.0-stage → 0.1.0

package/dist/cjs/generators/days_of_week.d.ts

@@ -0,0 +1,5 @@
+import type { DaysOfWeekRule, Disambiguation } from "../types.js";
+import { dayOfWeekInTz } from "../tz.js";
+import { type Occurrence } from "./types.js";
+export declare function generateDaysOfWeek(rule: DaysOfWeekRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];
+export { dayOfWeekInTz };

package/dist/cjs/generators/days_of_week.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dayOfWeekInTz = void 0;
+exports.generateDaysOfWeek = generateDaysOfWeek;
+const tz_js_1 = require("../tz.js");
+Object.defineProperty(exports, "dayOfWeekInTz", { enumerable: true, get: function () { return tz_js_1.dayOfWeekInTz; } });
+const types_js_1 = require("./types.js");
+// Iterate week-by-week (in wall time, in tz) starting from seriesStart's
+// week. For each scheduled week, emit the occurrences that fall on the
+// rule's days.
+function generateDaysOfWeek(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    if (rule.weekInterval <= 0) {
+        throw new Error(`DaysOfWeekRule.weekInterval must be > 0 (got ${rule.weekInterval})`);
+    }
+    if (rule.days.length === 0) {
+        throw new Error("DaysOfWeekRule.days must be non-empty");
+    }
+    if (rule.count != null && rule.count < 0) {
+        throw new Error(`DaysOfWeekRule.count must be >= 0 (got ${rule.count})`);
+    }
+    const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+    const effectiveEnd = Math.min(windowEnd, seriesEnd);
+    if (rule.seriesStart >= effectiveEnd)
+        return [];
+    // Sort days for deterministic emit order within a week.
+    const days = [...rule.days].sort((a, b) => a - b);
+    // Anchor: snap seriesStart to the start of its week (Sunday) in tz.
+    const seriesStartParts = (0, tz_js_1.utcToWallParts)(rule.seriesStart, tz);
+    const daysSinceSunday = seriesStartParts.dayOfWeek;
+    const weekAnchor = (0, tz_js_1.wallTimeToUtc)(seriesStartParts.year, seriesStartParts.month, seriesStartParts.day - daysSinceSunday, 0, tz);
+    const out = [];
+    let count = 0;
+    // Step by `weekInterval` weeks at a time. Use addDaysInTz to handle DST
+    // correctly (a week is 7 calendar days, not 7*86400000 ms).
+    let weekStart = weekAnchor;
+    while (weekStart < effectiveEnd) {
+        for (const dow of days) {
+            // Compute the day-of-week within this week in tz wall time.
+            const dayUtc = (0, tz_js_1.addDaysInTz)(weekStart, dow, tz);
+            const dayParts = (0, tz_js_1.utcToWallParts)(dayUtc, tz);
+            if (disambiguation === "skip" &&
+                (0, tz_js_1.isNonexistentWallTime)(dayParts.year, dayParts.month, dayParts.day, rule.timeOfDay, tz)) {
+                continue;
+            }
+            const occStart = (0, tz_js_1.wallTimeToUtc)(dayParts.year, dayParts.month, dayParts.day, rule.timeOfDay, tz, disambiguation);
+            const occEnd = (0, tz_js_1.computeSpanEnd)(occStart, rule.timeSpan, tz);
+            // Must be on/after seriesStart and before seriesEnd.
+            if (occStart < rule.seriesStart)
+                continue;
+            if (occStart >= seriesEnd)
+                continue;
+            if (rule.count != null && count >= rule.count)
+                return out;
+            count++;
+            if ((0, types_js_1.intersects)(occStart, occEnd, windowStart, windowEnd)) {
+                out.push({ startTimestamp: occStart, endTimestamp: occEnd });
+                if (out.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                    throw new types_js_1.TooManyOccurrencesError("daysOfWeek");
+                }
+            }
+        }
+        weekStart = (0, tz_js_1.addDaysInTz)(weekStart, 7 * rule.weekInterval, tz);
+    }
+    return out;
+}

package/dist/cjs/generators/days_of_year.d.ts

@@ -0,0 +1,3 @@
+import type { DaysOfYearRule, Disambiguation } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateDaysOfYear(rule: DaysOfYearRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];

package/dist/cjs/generators/days_of_year.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDaysOfYear = generateDaysOfYear;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./types.js");
+// Day-of-year recurrence. Day 1 = Jan 1. Day 366 only exists in leap
+// years and is SKIPPED in non-leap years (no clamp — "366th day" means
+// literally that).
+function generateDaysOfYear(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    if (rule.yearInterval <= 0) {
+        throw new Error(`DaysOfYearRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+    }
+    if (rule.daysOfYear.length === 0) {
+        throw new Error("DaysOfYearRule.daysOfYear must be non-empty");
+    }
+    for (const d of rule.daysOfYear) {
+        if (d < 1 || d > 366) {
+            throw new Error(`DaysOfYearRule.daysOfYear entries must be in 1..366 (got ${d})`);
+        }
+    }
+    if (rule.count != null && rule.count < 0) {
+        throw new Error(`DaysOfYearRule.count must be >= 0 (got ${rule.count})`);
+    }
+    const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+    const effectiveEnd = Math.min(windowEnd, seriesEnd);
+    if (rule.seriesStart >= effectiveEnd)
+        return [];
+    const days = [...new Set(rule.daysOfYear)].sort((a, b) => a - b);
+    const startYear = (0, tz_js_1.utcToWallParts)(rule.seriesStart, tz).year;
+    const endYear = (0, tz_js_1.utcToWallParts)(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;
+    const out = [];
+    let count = 0;
+    for (let year = startYear; year <= endYear; year += rule.yearInterval) {
+        const yearEmits = [];
+        for (const dayOfYear of days) {
+            // Date.UTC(year, 0, N) treats N as "Nth day from Jan 1". If N is 366
+            // in a non-leap year it rolls into year+1; detect and skip.
+            const probe = new Date(Date.UTC(year, 0, dayOfYear));
+            if (probe.getUTCFullYear() !== year)
+                continue; // day 366 in non-leap year
+            const month = probe.getUTCMonth();
+            const day = probe.getUTCDate();
+            if (disambiguation === "skip" &&
+                (0, tz_js_1.isNonexistentWallTime)(year, month, day, rule.timeOfDay, tz)) {
+                continue;
+            }
+            const occStart = (0, tz_js_1.wallTimeToUtc)(year, month, day, rule.timeOfDay, tz, disambiguation);
+            const occEnd = (0, tz_js_1.computeSpanEnd)(occStart, rule.timeSpan, tz);
+            if (occStart < rule.seriesStart)
+                continue;
+            if (occStart >= seriesEnd)
+                continue;
+            if (rule.count != null && count >= rule.count) {
+                yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+                out.push(...yearEmits);
+                return out;
+            }
+            count++;
+            if ((0, types_js_1.intersects)(occStart, occEnd, windowStart, windowEnd)) {
+                yearEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });
+                if (out.length + yearEmits.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                    throw new types_js_1.TooManyOccurrencesError("daysOfYear");
+                }
+            }
+        }
+        yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+        out.push(...yearEmits);
+    }
+    return out;
+}

package/dist/cjs/generators/instant.d.ts

@@ -0,0 +1,3 @@
+import type { InstantRule } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateInstant(rule: InstantRule, tz: string | undefined, windowStart: number, windowEnd: number): Occurrence[];

package/dist/cjs/generators/instant.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateInstant = generateInstant;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./types.js");
+// A single occurrence at an absolute UTC instant. The template timezone does
+// not affect the start (the instant is already a fixed point on the timeline);
+// it only flexes an hourSpan end, via computeSpanEnd.
+function generateInstant(rule, tz, windowStart, windowEnd) {
+    const start = rule.startOn;
+    const end = (0, tz_js_1.computeSpanEnd)(start, rule.timeSpan, tz);
+    if (!(0, types_js_1.intersects)(start, end, windowStart, windowEnd))
+        return [];
+    return [{ startTimestamp: start, endTimestamp: end }];
+}

package/dist/cjs/generators/local_date_time.d.ts

@@ -0,0 +1,3 @@
+import type { Disambiguation, LocalDateTimeRule } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateLocalDateTime(rule: LocalDateTimeRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];

package/dist/cjs/generators/local_date_time.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLocalDateTime = generateLocalDateTime;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./types.js");
+// A single occurrence expressed in wall-clock terms, resolved through the
+// template timezone (DST-aware). `day` clamps to the month length. When tz is
+// undefined the wall-clock fields are interpreted as UTC. A spring-forward gap
+// or fall-back overlap on the start is resolved per `disambiguation` (see
+// tz.ts) — "skip" drops the occurrence entirely if its wall time doesn't exist.
+function generateLocalDateTime(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    if (!Number.isInteger(rule.year)) {
+        throw new Error(`LocalDateTimeRule.year must be an integer (got ${rule.year})`);
+    }
+    if (rule.month < 0 || rule.month > 11) {
+        throw new Error(`LocalDateTimeRule.month must be in 0..11 (got ${rule.month})`);
+    }
+    if (rule.day < 1 || rule.day > 31) {
+        throw new Error(`LocalDateTimeRule.day must be in 1..31 (got ${rule.day})`);
+    }
+    const day = Math.min(rule.day, (0, tz_js_1.monthLength)(rule.year, rule.month));
+    if (disambiguation === "skip" &&
+        (0, tz_js_1.isNonexistentWallTime)(rule.year, rule.month, day, rule.timeOfDay, tz)) {
+        return [];
+    }
+    const start = (0, tz_js_1.wallTimeToUtc)(rule.year, rule.month, day, rule.timeOfDay, tz, disambiguation);
+    const end = (0, tz_js_1.computeSpanEnd)(start, rule.timeSpan, tz);
+    if (!(0, types_js_1.intersects)(start, end, windowStart, windowEnd))
+        return [];
+    return [{ startTimestamp: start, endTimestamp: end }];
+}

package/dist/cjs/generators/months_of_year.d.ts

@@ -0,0 +1,3 @@
+import type { Disambiguation, MonthsOfYearRule } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateMonthsOfYear(rule: MonthsOfYearRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];

package/dist/cjs/generators/months_of_year.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMonthsOfYear = generateMonthsOfYear;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./types.js");
+// Positional yearly recurrence — top of the positional cascade.
+// (months × weeks-of-month × weekdays, with yearInterval as cadence.)
+//
+// For each year in cadence, walk the selected months; in each month, find
+// the Nth weekday matches (e.g. "2nd Tuesday") for each (week, day) pair.
+// If a position doesn't exist that month (e.g. 5th Sunday in a 4-Sunday
+// month), silently skip — same policy as WeeksOfMonthRule.
+function generateMonthsOfYear(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    if (rule.yearInterval <= 0) {
+        throw new Error(`MonthsOfYearRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+    }
+    if (rule.months.length === 0) {
+        throw new Error("MonthsOfYearRule.months must be non-empty");
+    }
+    for (const m of rule.months) {
+        if (m < 0 || m > 11) {
+            throw new Error(`MonthsOfYearRule.months entries must be in 0..11 (got ${m})`);
+        }
+    }
+    if (rule.weeks.length === 0) {
+        throw new Error("MonthsOfYearRule.weeks must be non-empty");
+    }
+    for (const w of rule.weeks) {
+        if (w === 0 || w < -5 || w > 5) {
+            throw new Error(`MonthsOfYearRule.weeks entries must be in [-5..-1] or [1..5] (got ${w})`);
+        }
+    }
+    if (rule.days.length === 0) {
+        throw new Error("MonthsOfYearRule.days must be non-empty");
+    }
+    if (rule.count != null && rule.count < 0) {
+        throw new Error(`MonthsOfYearRule.count must be >= 0 (got ${rule.count})`);
+    }
+    const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+    const effectiveEnd = Math.min(windowEnd, seriesEnd);
+    if (rule.seriesStart >= effectiveEnd)
+        return [];
+    const months = [...new Set(rule.months)].sort((a, b) => a - b);
+    const weeks = [...new Set(rule.weeks)];
+    const weekdays = [...new Set(rule.days)].sort((a, b) => a - b);
+    // Anchor at the start of seriesStart's year (in tz), but actually anchor
+    // at its first selected month within that year. We iterate year-by-year.
+    const seriesStartParts = (0, tz_js_1.utcToWallParts)(rule.seriesStart, tz);
+    let yearAnchor = (0, tz_js_1.wallTimeToUtc)(seriesStartParts.year, 0, 1, 0, tz);
+    const out = [];
+    let count = 0;
+    while (yearAnchor < effectiveEnd) {
+        const yp = (0, tz_js_1.utcToWallParts)(yearAnchor, tz);
+        const yearEmits = [];
+        for (const month of months) {
+            for (const week of weeks) {
+                for (const dow of weekdays) {
+                    const targetDay = _nthWeekdayOfMonth(yp.year, month, dow, week);
+                    if (targetDay == null)
+                        continue; // Nth doesn't exist this month
+                    if (disambiguation === "skip" &&
+                        (0, tz_js_1.isNonexistentWallTime)(yp.year, month, targetDay, rule.timeOfDay, tz)) {
+                        continue;
+                    }
+                    const occStart = (0, tz_js_1.wallTimeToUtc)(yp.year, month, targetDay, rule.timeOfDay, tz, disambiguation);
+                    const occEnd = (0, tz_js_1.computeSpanEnd)(occStart, rule.timeSpan, tz);
+                    if (occStart < rule.seriesStart)
+                        continue;
+                    if (occStart >= seriesEnd)
+                        continue;
+                    if (rule.count != null && count >= rule.count) {
+                        yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+                        out.push(...yearEmits);
+                        return out;
+                    }
+                    count++;
+                    if ((0, types_js_1.intersects)(occStart, occEnd, windowStart, windowEnd)) {
+                        yearEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });
+                        if (out.length + yearEmits.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                            throw new types_js_1.TooManyOccurrencesError("monthsOfYear");
+                        }
+                    }
+                }
+            }
+        }
+        yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+        out.push(...yearEmits);
+        // Step yearInterval years. Use addMonthsInTz(12) so leap-year wall-clock
+        // arithmetic is correct (it isn't strictly necessary at year granularity,
+        // but matches the rest of the codebase).
+        yearAnchor = (0, tz_js_1.addMonthsInTz)(yearAnchor, 12 * rule.yearInterval, tz);
+    }
+    return out;
+}
+// Same helper as WeeksOfMonth uses. Returns day-of-month (1..31) for the
+// Nth occurrence of `dow` in the given month, or null if it doesn't exist.
+function _nthWeekdayOfMonth(year, month, dow, n) {
+    const len = (0, tz_js_1.monthLength)(year, month);
+    if (n > 0) {
+        const firstDow = new Date(Date.UTC(year, month, 1)).getUTCDay();
+        const offset = (dow - firstDow + 7) % 7;
+        const day = 1 + offset + (n - 1) * 7;
+        return day <= len ? day : null;
+    }
+    const lastDow = new Date(Date.UTC(year, month, len)).getUTCDay();
+    const offset = (lastDow - dow + 7) % 7;
+    const day = len - offset + (n + 1) * 7;
+    return day >= 1 ? day : null;
+}

package/dist/cjs/generators/types.d.ts

@@ -0,0 +1,9 @@
+export interface Occurrence {
+    startTimestamp: number;
+    endTimestamp: number;
+}
+export declare const MAX_OCCURRENCES_PER_GENERATE = 10000;
+export declare class TooManyOccurrencesError extends Error {
+    constructor(kind: string);
+}
+export declare function intersects(startA: number, endA: number, startB: number, endB: number): boolean;

package/dist/cjs/generators/types.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TooManyOccurrencesError = exports.MAX_OCCURRENCES_PER_GENERATE = void 0;
+exports.intersects = intersects;
+// Hard ceiling per generate() call. A misconfigured rule (e.g. 1ms anchored
+// interval over a year-long window) would otherwise produce billions of
+// occurrences; we'd rather throw a clear error than blow heap.
+exports.MAX_OCCURRENCES_PER_GENERATE = 10_000;
+class TooManyOccurrencesError extends Error {
+    constructor(kind) {
+        super(`Generator '${kind}' would emit more than ${exports.MAX_OCCURRENCES_PER_GENERATE} occurrences for the requested window. Narrow the window, increase the interval, or set 'count' on the rule.`);
+        this.name = "TooManyOccurrencesError";
+    }
+}
+exports.TooManyOccurrencesError = TooManyOccurrencesError;
+// Half-open intersection: [startA, endA) overlaps [startB, endB)?
+function intersects(startA, endA, startB, endB) {
+    return Math.max(startA, startB) < Math.min(endA, endB);
+}

package/dist/cjs/generators/weeks_of_month.d.ts

@@ -0,0 +1,3 @@
+import type { Disambiguation, WeeksOfMonthRule } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateWeeksOfMonth(rule: WeeksOfMonthRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];

package/dist/cjs/generators/weeks_of_month.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateWeeksOfMonth = generateWeeksOfMonth;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./types.js");
+// "Nth Tuesday of every month", "last Friday of every other month", etc.
+// Iterate month-by-month at monthInterval cadence; for each repeatable day,
+// resolve the target wall date.
+function generateWeeksOfMonth(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    if (rule.monthInterval <= 0) {
+        throw new Error(`WeeksOfMonthRule.monthInterval must be > 0 (got ${rule.monthInterval})`);
+    }
+    if (rule.weeks.length === 0) {
+        throw new Error("WeeksOfMonthRule.weeks must be non-empty");
+    }
+    for (const w of rule.weeks) {
+        if (w === 0 || w < -5 || w > 5) {
+            throw new Error(`WeeksOfMonthRule.weeks entries must be in [-5..-1] or [1..5] (got ${w})`);
+        }
+    }
+    if (rule.days.length === 0) {
+        throw new Error("WeeksOfMonthRule.days must be non-empty");
+    }
+    if (rule.count != null && rule.count < 0) {
+        throw new Error(`WeeksOfMonthRule.count must be >= 0 (got ${rule.count})`);
+    }
+    const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+    const effectiveEnd = Math.min(windowEnd, seriesEnd);
+    if (rule.seriesStart >= effectiveEnd)
+        return [];
+    const days = [...rule.days].sort((a, b) => a - b);
+    // Dedup `weeks` so a duplicated entry doesn't double-emit. Don't sort —
+    // we sort the per-month emits at the end of each month iteration anyway.
+    const weeks = [...new Set(rule.weeks)];
+    // Anchor at seriesStart's month (in tz).
+    const seriesStartParts = (0, tz_js_1.utcToWallParts)(rule.seriesStart, tz);
+    let monthAnchor = (0, tz_js_1.wallTimeToUtc)(seriesStartParts.year, seriesStartParts.month, 1, 0, tz);
+    const out = [];
+    let count = 0;
+    while (monthAnchor < effectiveEnd) {
+        const mp = (0, tz_js_1.utcToWallParts)(monthAnchor, tz);
+        const monthEmits = [];
+        for (const week of weeks) {
+            for (const dow of days) {
+                const targetDay = _nthWeekdayOfMonth(mp.year, mp.month, dow, week);
+                if (targetDay == null)
+                    continue; // e.g. 5th Friday in a 4-Friday month
+                if (disambiguation === "skip" &&
+                    (0, tz_js_1.isNonexistentWallTime)(mp.year, mp.month, targetDay, rule.timeOfDay, tz)) {
+                    continue;
+                }
+                const occStart = (0, tz_js_1.wallTimeToUtc)(mp.year, mp.month, targetDay, rule.timeOfDay, tz, disambiguation);
+                const occEnd = (0, tz_js_1.computeSpanEnd)(occStart, rule.timeSpan, tz);
+                if (occStart < rule.seriesStart)
+                    continue;
+                if (occStart >= seriesEnd)
+                    continue;
+                if (rule.count != null && count >= rule.count) {
+                    // Sort and emit what we collected this month before returning.
+                    monthEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+                    out.push(...monthEmits);
+                    return out;
+                }
+                count++;
+                if ((0, types_js_1.intersects)(occStart, occEnd, windowStart, windowEnd)) {
+                    monthEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });
+                    if (out.length + monthEmits.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                        throw new types_js_1.TooManyOccurrencesError("weeksOfMonth");
+                    }
+                }
+            }
+        }
+        // Sort within-month emits before appending. With multiple weeks (and
+        // negative weeks mixed with positive), per-week iteration order doesn't
+        // produce ascending startTimestamps.
+        monthEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+        out.push(...monthEmits);
+        monthAnchor = (0, tz_js_1.addMonthsInTz)(monthAnchor, rule.monthInterval, tz);
+    }
+    return out;
+}
+// Returns the day-of-month (1..31) for the Nth weekday of the given month,
+// or null if it doesn't exist (e.g. asking for the 5th Tuesday of a 4-Tuesday
+// month). Negative N counts from the end: -1 = last, -2 = second-to-last.
+function _nthWeekdayOfMonth(year, month, dow, n) {
+    const len = (0, tz_js_1.monthLength)(year, month);
+    if (n > 0) {
+        // Find the first occurrence of `dow` in the month, then step by 7s.
+        const firstDow = new Date(Date.UTC(year, month, 1)).getUTCDay();
+        const offset = (dow - firstDow + 7) % 7;
+        const day = 1 + offset + (n - 1) * 7;
+        return day <= len ? day : null;
+    }
+    // n < 0: count from end of month.
+    const lastDow = new Date(Date.UTC(year, month, len)).getUTCDay();
+    const offset = (lastDow - dow + 7) % 7;
+    const day = len - offset + (n + 1) * 7;
+    return day >= 1 ? day : null;
+}

package/dist/cjs/generators/yearly.d.ts

@@ -0,0 +1,3 @@
+import type { Disambiguation, YearlyRule } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateYearly(rule: YearlyRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];

package/dist/cjs/generators/yearly.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateYearly = generateYearly;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./types.js");
+// Simple yearly recurrence: a single month + day. Day clamps to month
+// length (Feb 29 → Feb 28 in non-leap years, Apr 31 → Apr 30, etc.).
+function generateYearly(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    if (rule.yearInterval <= 0) {
+        throw new Error(`YearlyRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+    }
+    if (rule.month < 0 || rule.month > 11) {
+        throw new Error(`YearlyRule.month must be in 0..11 (got ${rule.month})`);
+    }
+    if (rule.day < 1 || rule.day > 31) {
+        throw new Error(`YearlyRule.day must be in 1..31 (got ${rule.day})`);
+    }
+    if (rule.count != null && rule.count < 0) {
+        throw new Error(`YearlyRule.count must be >= 0 (got ${rule.count})`);
+    }
+    const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+    const effectiveEnd = Math.min(windowEnd, seriesEnd);
+    if (rule.seriesStart >= effectiveEnd)
+        return [];
+    const startYear = (0, tz_js_1.utcToWallParts)(rule.seriesStart, tz).year;
+    const endYear = (0, tz_js_1.utcToWallParts)(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;
+    const out = [];
+    let count = 0;
+    for (let year = startYear; year <= endYear; year += rule.yearInterval) {
+        const day = Math.min(rule.day, (0, tz_js_1.monthLength)(year, rule.month));
+        if (disambiguation === "skip" &&
+            (0, tz_js_1.isNonexistentWallTime)(year, rule.month, day, rule.timeOfDay, tz)) {
+            continue;
+        }
+        const occStart = (0, tz_js_1.wallTimeToUtc)(year, rule.month, day, rule.timeOfDay, tz, disambiguation);
+        const occEnd = (0, tz_js_1.computeSpanEnd)(occStart, rule.timeSpan, tz);
+        if (occStart < rule.seriesStart)
+            continue;
+        if (occStart >= seriesEnd)
+            continue;
+        if (rule.count != null && count >= rule.count)
+            break;
+        count++;
+        if ((0, types_js_1.intersects)(occStart, occEnd, windowStart, windowEnd)) {
+            out.push({ startTimestamp: occStart, endTimestamp: occEnd });
+            if (out.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                throw new types_js_1.TooManyOccurrencesError("yearly");
+            }
+        }
+    }
+    return out;
+}

package/dist/cjs/in_memory_port.d.ts

@@ -0,0 +1,18 @@
+import type { SchedulerPort } from "./port.js";
+import type { Alteration, ScheduleTemplate } from "./types.js";
+export declare class InMemorySchedulerPort<TPayload extends {
+    type: string;
+}> implements SchedulerPort<TPayload> {
+    private _templates;
+    private _alterations;
+    listTemplates(_start: number, _end: number): Promise<ScheduleTemplate<TPayload>[]>;
+    getTemplate(id: string): Promise<ScheduleTemplate<TPayload> | null>;
+    addTemplate(template: ScheduleTemplate<TPayload>): Promise<void>;
+    updateTemplate(template: ScheduleTemplate<TPayload>): Promise<void>;
+    removeTemplate(id: string): Promise<void>;
+    listAlterations(_start: number, _end: number): Promise<Alteration<TPayload>[]>;
+    listAlterationsByTemplate(templateId: string): Promise<Alteration<TPayload>[]>;
+    addAlteration(alteration: Alteration<TPayload>): Promise<void>;
+    removeAlteration(id: string): Promise<void>;
+    removeAlterationsForTemplate(templateId: string): Promise<void>;
+}

package/dist/cjs/in_memory_port.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemorySchedulerPort = void 0;
+// Reference port. Stores templates and alterations in plain Maps. Returns
+// deep-cloned copies so callers can't mutate internal state.
+//
+// Range queries return everything and let the Scheduler filter — correct,
+// but O(n) per query. A real backend would index on seriesStart/seriesEnd.
+class InMemorySchedulerPort {
+    _templates = new Map();
+    _alterations = new Map();
+    async listTemplates(_start, _end) {
+        return [...this._templates.values()].map(clone);
+    }
+    async getTemplate(id) {
+        const t = this._templates.get(id);
+        return t == null ? null : clone(t);
+    }
+    async addTemplate(template) {
+        if (this._templates.has(template.id)) {
+            throw new Error(`Template already exists: ${template.id}`);
+        }
+        this._templates.set(template.id, clone(template));
+    }
+    async updateTemplate(template) {
+        if (!this._templates.has(template.id)) {
+            throw new Error(`No template with id ${template.id}`);
+        }
+        this._templates.set(template.id, clone(template));
+    }
+    async removeTemplate(id) {
+        this._templates.delete(id);
+    }
+    async listAlterations(_start, _end) {
+        return [...this._alterations.values()].map(clone);
+    }
+    async listAlterationsByTemplate(templateId) {
+        return [...this._alterations.values()].filter((a) => a.templateId === templateId).map(clone);
+    }
+    async addAlteration(alteration) {
+        if (this._alterations.has(alteration.id)) {
+            throw new Error(`Alteration already exists: ${alteration.id}`);
+        }
+        this._alterations.set(alteration.id, clone(alteration));
+    }
+    async removeAlteration(id) {
+        this._alterations.delete(id);
+    }
+    async removeAlterationsForTemplate(templateId) {
+        for (const [id, a] of this._alterations) {
+            if (a.templateId === templateId)
+                this._alterations.delete(id);
+        }
+    }
+}
+exports.InMemorySchedulerPort = InMemorySchedulerPort;
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export { Scheduler } from "./scheduler.js";
+export { InMemorySchedulerPort } from "./in_memory_port.js";
+export type { SchedulerPort } from "./port.js";
+export { Dispatcher, type DispatcherConfig } from "./dispatcher.js";
+export { type DispatcherStore, InMemoryDispatcherStore } from "./dispatcher_store.js";
+export { Day, Month, type RecurrenceRule, type InstantRule, type LocalDateTimeRule, type AnchoredRule, type DaysOfWeekRule, type WeeksOfMonthRule, type MonthsOfYearRule, type YearlyRule, type DaysOfMonthRule, type DaysOfYearRule, type ScheduleTemplate, type Alteration, type ScheduledEvent, type TimeSpan, type Disambiguation, } from "./types.js";

package/dist/cjs/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Month = exports.Day = exports.InMemoryDispatcherStore = exports.Dispatcher = exports.InMemorySchedulerPort = exports.Scheduler = void 0;
+var scheduler_js_1 = require("./scheduler.js");
+Object.defineProperty(exports, "Scheduler", { enumerable: true, get: function () { return scheduler_js_1.Scheduler; } });
+var in_memory_port_js_1 = require("./in_memory_port.js");
+Object.defineProperty(exports, "InMemorySchedulerPort", { enumerable: true, get: function () { return in_memory_port_js_1.InMemorySchedulerPort; } });
+var dispatcher_js_1 = require("./dispatcher.js");
+Object.defineProperty(exports, "Dispatcher", { enumerable: true, get: function () { return dispatcher_js_1.Dispatcher; } });
+var dispatcher_store_js_1 = require("./dispatcher_store.js");
+Object.defineProperty(exports, "InMemoryDispatcherStore", { enumerable: true, get: function () { return dispatcher_store_js_1.InMemoryDispatcherStore; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "Day", { enumerable: true, get: function () { return types_js_1.Day; } });
+Object.defineProperty(exports, "Month", { enumerable: true, get: function () { return types_js_1.Month; } });

package/dist/cjs/occurrence_key.d.ts

@@ -0,0 +1,5 @@
+import type { Occurrence } from "./generators/types.js";
+export interface KeyedOccurrence extends Occurrence {
+    occurrenceKey: string;
+}
+export declare function assignOccurrenceKeys(occurrences: readonly Occurrence[], tz: string | undefined): KeyedOccurrence[];

package/dist/cjs/occurrence_key.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignOccurrenceKeys = assignOccurrenceKeys;
+const tz_js_1 = require("./tz.js");
+function assignOccurrenceKeys(occurrences, tz) {
+    const counts = new Map();
+    return occurrences.map((occ) => {
+        const w = (0, tz_js_1.utcToWallParts)(occ.startTimestamp, tz);
+        const date = `${_pad4(w.year)}-${_pad2(w.month + 1)}-${_pad2(w.day)}`;
+        const idx = counts.get(date) ?? 0;
+        counts.set(date, idx + 1);
+        const occurrenceKey = idx === 0 ? date : `${date}#${idx}`;
+        return { ...occ, occurrenceKey };
+    });
+}
+function _pad2(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+function _pad4(n) {
+    return n < 10 ? `000${n}` : n < 100 ? `00${n}` : n < 1000 ? `0${n}` : String(n);
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}