@j13b/scheduler 0.0.0-stage → 0.1.0

package/dist/cjs/types.js

@@ -0,0 +1,58 @@
+"use strict";
+// All types are plain data — safe to JSON-serialize and store in a JSON column.
+// Generated occurrences carry a TPayload so consumers can attach whatever
+// domain data they need (cron action, calendar event body, etc.).
+//
+// ─── DST gotchas for wall-clock rules ───────────────────────────────────────
+//
+// daysOfWeek / weekOfMonth / yearly rules use wall-clock fields (timeOfDay,
+// day-of-week, month/day) interpreted in the template's `timezone`. In a tz
+// that observes DST, two edge cases exist:
+//
+// 1. Spring-forward gap. On the spring-forward day, an hour is SKIPPED — in
+//    America/Denver, 02:00 MST jumps to 03:00 MDT, so wall times 02:00–02:59
+//    don't exist that day. If `timeOfDay` lands in this gap, we resolve to
+//    the post-transition offset (the default in Luxon and date-fns-tz),
+//    which means the event fires at a *different* wall-clock time than you
+//    asked for — typically one hour earlier in real time. RECOMMENDATION:
+//    don't pick `timeOfDay` between 02:00 and 02:59 in DST-observing zones.
+//    03:00 is always safe.
+//
+// 2. TimeSpan spanning the gap. The TimeSpan type has two flavors:
+//    `{type:"duration",ms}` — exact UTC milliseconds, no DST adjustment.
+//      An 8h duration shift starting 23:00 spring-forward eve runs for
+//      exactly 8h real time; the worker's wall display reads "9 hours
+//      elapsed" because clocks jumped. Payroll-correct.
+//    `{type:"hourSpan",hours}` — wall-clock hours, flexes with DST.
+//      An 8h hourSpan shift starting 23:00 spring-forward eve ends at
+//      07:00 next wall day regardless; real elapsed time is 7 actual
+//      hours. Calendar-display correct.
+//    Both are valid; pick based on whether you care about real elapsed
+//    time or wall-clock display.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Month = exports.Day = void 0;
+var Day;
+(function (Day) {
+    Day[Day["Sunday"] = 0] = "Sunday";
+    Day[Day["Monday"] = 1] = "Monday";
+    Day[Day["Tuesday"] = 2] = "Tuesday";
+    Day[Day["Wednesday"] = 3] = "Wednesday";
+    Day[Day["Thursday"] = 4] = "Thursday";
+    Day[Day["Friday"] = 5] = "Friday";
+    Day[Day["Saturday"] = 6] = "Saturday";
+})(Day || (exports.Day = Day = {}));
+var Month;
+(function (Month) {
+    Month[Month["January"] = 0] = "January";
+    Month[Month["February"] = 1] = "February";
+    Month[Month["March"] = 2] = "March";
+    Month[Month["April"] = 3] = "April";
+    Month[Month["May"] = 4] = "May";
+    Month[Month["June"] = 5] = "June";
+    Month[Month["July"] = 6] = "July";
+    Month[Month["August"] = 7] = "August";
+    Month[Month["September"] = 8] = "September";
+    Month[Month["October"] = 9] = "October";
+    Month[Month["November"] = 10] = "November";
+    Month[Month["December"] = 11] = "December";
+})(Month || (exports.Month = Month = {}));

package/dist/cjs/tz.d.ts

@@ -0,0 +1,22 @@
+import type { Day, Disambiguation, TimeSpan } from "./types.js";
+export interface WallParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    ms: number;
+    dayOfWeek: Day;
+}
+export declare function isValidTimeZone(tz: string): boolean;
+export declare function utcToWallParts(utcEpochMs: number, tz?: string): WallParts;
+export declare function isNonexistentWallTime(year: number, month: number, day: number, msOfDay: number, tz: string | undefined): boolean;
+export declare function wallTimeToUtc(year: number, month: number, // 0-indexed
+day: number, msOfDay: number, // 0..86_399_999, ms since wall-clock midnight
+tz?: string, disambiguation?: Disambiguation): number;
+export declare function dayOfWeekInTz(utcEpochMs: number, tz?: string): Day;
+export declare function addDaysInTz(utcEpochMs: number, days: number, tz?: string): number;
+export declare function addMonthsInTz(utcEpochMs: number, months: number, tz?: string): number;
+export declare function monthLength(year: number, month: number): number;
+export declare function computeSpanEnd(startUtc: number, span: TimeSpan | undefined, tz: string | undefined): number;

package/dist/cjs/tz.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidTimeZone = isValidTimeZone;
+exports.utcToWallParts = utcToWallParts;
+exports.isNonexistentWallTime = isNonexistentWallTime;
+exports.wallTimeToUtc = wallTimeToUtc;
+exports.dayOfWeekInTz = dayOfWeekInTz;
+exports.addDaysInTz = addDaysInTz;
+exports.addMonthsInTz = addMonthsInTz;
+exports.monthLength = monthLength;
+exports.computeSpanEnd = computeSpanEnd;
+const DAY_MS = 86_400_000;
+const _formatterCache = new Map();
+function _formatter(tz) {
+    let f = _formatterCache.get(tz);
+    if (f == null) {
+        f = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+        });
+        _formatterCache.set(tz, f);
+    }
+    return f;
+}
+// Is `tz` an IANA zone name (or "UTC") the runtime recognizes? Constructing an
+// Intl.DateTimeFormat with an unknown zone throws RangeError; we probe for that.
+function isValidTimeZone(tz) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz }).format();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function utcToWallParts(utcEpochMs, tz = "UTC") {
+    if (tz === "UTC") {
+        const d = new Date(utcEpochMs);
+        return {
+            year: d.getUTCFullYear(),
+            month: d.getUTCMonth(),
+            day: d.getUTCDate(),
+            hour: d.getUTCHours(),
+            minute: d.getUTCMinutes(),
+            second: d.getUTCSeconds(),
+            ms: d.getUTCMilliseconds(),
+            dayOfWeek: d.getUTCDay(),
+        };
+    }
+    const parts = _formatter(tz).formatToParts(new Date(utcEpochMs));
+    const get = (type) => {
+        const p = parts.find((x) => x.type === type);
+        if (p == null)
+            throw new Error(`Missing date-time part '${type}' for tz '${tz}'`);
+        return Number(p.value);
+    };
+    let hour = get("hour");
+    if (hour === 24)
+        hour = 0; // some Node versions report midnight as "24"
+    const year = get("year");
+    const month = get("month") - 1;
+    const day = get("day");
+    // Day-of-week derived from the wall date via UTC math (the math itself
+    // is tz-independent — Date.UTC just gives us a zero-anchored instant).
+    const dayOfWeek = new Date(Date.UTC(year, month, day)).getUTCDay();
+    // Intl doesn't give us ms — preserve the original ms from utcEpochMs.
+    // Sub-second precision is the same in any tz, since offsets are minute-
+    // aligned (or, for a few historical zones, second-aligned).
+    const ms = ((utcEpochMs % 1000) + 1000) % 1000;
+    return {
+        year,
+        month,
+        day,
+        hour,
+        minute: get("minute"),
+        second: get("second"),
+        ms,
+        dayOfWeek,
+    };
+}
+// Offset from UTC to local wall time at the given UTC instant, in ms.
+// Positive for zones east of UTC. (wallAsUtc - utcInstant)
+function _offsetMsAt(utcEpochMs, tz) {
+    if (tz === "UTC")
+        return 0;
+    const w = utcToWallParts(utcEpochMs, tz);
+    const wallAsUtc = Date.UTC(w.year, w.month, w.day, w.hour, w.minute, w.second) + w.ms;
+    return wallAsUtc - utcEpochMs;
+}
+// The instants that a wall time could map to in `tz`, plus the bracketing
+// offsets. `valid` has length 1 normally, 0 in a spring-forward gap, or 2 in a
+// fall-back overlap (sorted ascending).
+function _possibleInstants(localUtc, tz) {
+    const offBefore = _offsetMsAt(localUtc - DAY_MS, tz);
+    const offAfter = _offsetMsAt(localUtc + DAY_MS, tz);
+    const valid = [];
+    const offsets = offBefore === offAfter ? [offBefore] : [offBefore, offAfter];
+    for (const off of offsets) {
+        const epoch = localUtc - off;
+        // Keep this candidate only if it reads back as the wall time we asked for
+        // (a gap's candidates won't; an overlap's both will).
+        const w = utcToWallParts(epoch, tz);
+        const back = Date.UTC(w.year, w.month, w.day, w.hour, w.minute, w.second) + w.ms;
+        if (back === localUtc && !valid.includes(epoch))
+            valid.push(epoch);
+    }
+    valid.sort((a, b) => a - b);
+    return { valid, offBefore, offAfter };
+}
+// Is this wall time nonexistent (in a spring-forward gap) in `tz`? Used by the
+// "skip" disambiguation to drop occurrences whose wall time doesn't exist.
+function isNonexistentWallTime(year, month, day, msOfDay, tz) {
+    if (tz == null || tz === "UTC")
+        return false;
+    const localUtc = Date.UTC(year, month, day) + msOfDay;
+    return _possibleInstants(localUtc, tz).valid.length === 0;
+}
+function wallTimeToUtc(year, month, // 0-indexed
+day, msOfDay, // 0..86_399_999, ms since wall-clock midnight
+tz = "UTC", disambiguation = "compatible") {
+    if (tz === "UTC") {
+        return Date.UTC(year, month, day) + msOfDay;
+    }
+    const localUtc = Date.UTC(year, month, day) + msOfDay;
+    const { valid, offBefore, offAfter } = _possibleInstants(localUtc, tz);
+    if (valid.length === 1)
+        return valid[0];
+    if (valid.length === 2) {
+        // Fall-back overlap. compatible/earlier/skip → earlier; later → later.
+        if (disambiguation === "reject") {
+            throw new Error(`Ambiguous wall time ${new Date(localUtc).toISOString().slice(0, 19)} in '${tz}' (fall-back overlap) with disambiguation "reject"`);
+        }
+        return disambiguation === "later" ? valid[1] : valid[0];
+    }
+    // Spring-forward gap (valid.length === 0). earlier → the earlier instant
+    // (post-transition offset); compatible/later/skip → the later instant.
+    // ("skip" only reaches here defensively — callers pre-check via
+    // isNonexistentWallTime; we resolve it like "compatible".)
+    if (disambiguation === "reject") {
+        throw new Error(`Nonexistent wall time ${new Date(localUtc).toISOString().slice(0, 19)} in '${tz}' (spring-forward gap) with disambiguation "reject"`);
+    }
+    return disambiguation === "earlier" ? localUtc - offAfter : localUtc - offBefore;
+}
+function dayOfWeekInTz(utcEpochMs, tz = "UTC") {
+    return utcToWallParts(utcEpochMs, tz).dayOfWeek;
+}
+// Add N calendar days in the wall-clock sense — important across DST
+// boundaries, where one civil day is 23 or 25 hours, not 24.
+function addDaysInTz(utcEpochMs, days, tz = "UTC") {
+    const w = utcToWallParts(utcEpochMs, tz);
+    return wallTimeToUtc(w.year, w.month, w.day + days, _hmsToMs(w), tz);
+}
+function addMonthsInTz(utcEpochMs, months, tz = "UTC") {
+    const w = utcToWallParts(utcEpochMs, tz);
+    return wallTimeToUtc(w.year, w.month + months, w.day, _hmsToMs(w), tz);
+}
+// Civil-calendar month length — tz-independent.
+function monthLength(year, month) {
+    // Date.UTC(y, m+1, 0) gives the last day of month `m` (0-indexed).
+    return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+// Returns endTimestamp for an occurrence given its start and a TimeSpan.
+//
+// For `duration`: pure UTC ms addition. The wall clock may show ±1h different
+// elapsed time on DST nights, but real elapsed time is exactly `ms`.
+//
+// For `hourSpan`: add hours in wall-clock space (handles midnight crossing
+// and DST flex). On a tz-less template, hourSpan collapses to hours*3_600_000
+// since there's no wall clock to flex against.
+//
+// When span is undefined, defaults to 1ms (so the half-open intersection
+// emits cron-fire occurrences correctly).
+function computeSpanEnd(startUtc, span, tz) {
+    if (span == null)
+        return startUtc + 1;
+    if (span.type === "duration")
+        return startUtc + span.ms;
+    // hourSpan
+    if (tz == null) {
+        // No tz → treat hours as a fixed real-time interval.
+        return startUtc + span.hours * 3_600_000;
+    }
+    const w = utcToWallParts(startUtc, tz);
+    const totalMs = _hmsToMs(w) + span.hours * 3_600_000;
+    const daysAhead = Math.floor(totalMs / 86_400_000);
+    const endMsInDay = totalMs - daysAhead * 86_400_000;
+    return wallTimeToUtc(w.year, w.month, w.day + daysAhead, endMsInDay, tz);
+}
+function _hmsToMs(w) {
+    return w.hour * 3_600_000 + w.minute * 60_000 + w.second * 1000 + w.ms;
+}

package/dist/dispatcher.d.ts

@@ -0,0 +1,39 @@
+import { DispatcherStore } from './dispatcher_store.js';
+import { Scheduler } from './scheduler.js';
+import { ScheduledEvent } from './types.js';
+export interface DispatcherConfig<TPayload extends {
+    type: string;
+}> {
+    scheduler: Scheduler<TPayload>;
+    fire: (event: ScheduledEvent<TPayload>) => Promise<void> | void;
+    store?: DispatcherStore;
+    onError?: (err: unknown, event?: ScheduledEvent<TPayload>) => void;
+    idleTimeoutMs?: number;
+    now?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+}
+export declare class Dispatcher<TPayload extends {
+    type: string;
+}> {
+    private readonly _scheduler;
+    private readonly _fire;
+    private readonly _store;
+    private readonly _onError;
+    private readonly _idleTimeoutMs;
+    private readonly _now;
+    private readonly _setTimeout;
+    private readonly _clearTimeout;
+    private _running;
+    private _wakeResolve;
+    private _changeSubscription;
+    constructor(config: DispatcherConfig<TPayload>);
+    start(): Promise<void>;
+    stop(): void;
+    private _loop;
+    private _findNextTarget;
+    private _tick;
+    private _sleepUntil;
+    private _wake;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../src/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAA2B,MAAM,uBAAuB,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOjD,MAAM,WAAW,gBAAgB,CAAC,QAAQ,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IACjE,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAI/B,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEhE,KAAK,CAAC,EAAE,eAAe,CAAC;IAExB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEnE,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AASD,qBAAa,UAAU,CAAC,QAAQ,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4D;IAClF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2D;IACpF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAE1D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,mBAAmB,CAAyC;gBAExD,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAexC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,IAAI,IAAI,IAAI;YAYE,KAAK;YAYL,eAAe;YAiBf,KAAK;YAgCL,WAAW;IAuBzB,OAAO,CAAC,KAAK;CAGd"}

package/dist/dispatcher.js

@@ -0,0 +1,111 @@
+import { InMemoryDispatcherStore } from "./dispatcher_store.js";
+// src/dispatcher.ts
+var DEFAULT_IDLE_TIMEOUT_MS = 36e5;
+var Dispatcher = class {
+	_scheduler;
+	_fire;
+	_store;
+	_onError;
+	_idleTimeoutMs;
+	_now;
+	_setTimeout;
+	_clearTimeout;
+	_running = false;
+	_wakeResolve = null;
+	_changeSubscription = null;
+	constructor(config) {
+		this._scheduler = config.scheduler;
+		this._fire = config.fire;
+		this._store = config.store ?? new InMemoryDispatcherStore();
+		this._onError = config.onError ?? defaultOnError;
+		this._idleTimeoutMs = config.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+		this._now = config.now ?? Date.now;
+		this._setTimeout = config.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+		this._clearTimeout = config.clearTimeout ?? ((h) => globalThis.clearTimeout(h));
+	}
+	async start() {
+		if (this._running) return;
+		this._running = true;
+		this._changeSubscription = this._scheduler.changed.subscribe(() => this._wake());
+		await this._tick();
+		if (this._running) this._loop();
+	}
+	stop() {
+		if (!this._running) return;
+		this._running = false;
+		if (this._changeSubscription != null) {
+			this._changeSubscription.unsubscribe();
+			this._changeSubscription = null;
+		}
+		this._wake();
+	}
+	async _loop() {
+		while (this._running) {
+			const target = await this._findNextTarget();
+			if (!this._running) return;
+			await this._sleepUntil(target);
+			if (!this._running) return;
+			await this._tick();
+		}
+	}
+	async _findNextTarget() {
+		try {
+			const next = (await this._scheduler.nextDue(this._now(), 1))[0];
+			return next != null ? next.startTimestamp : this._now() + this._idleTimeoutMs;
+		} catch (err) {
+			this._onError(err);
+			return this._now() + this._idleTimeoutMs;
+		}
+	}
+	async _tick() {
+		const cursor = await this._store.loadCursor() ?? this._now();
+		const windowEnd = this._now() + 1;
+		if (windowEnd <= cursor) return;
+		let events;
+		try {
+			events = await this._scheduler.list(cursor, windowEnd);
+		} catch (err) {
+			this._onError(err);
+			return;
+		}
+		for (const event of events) {
+			if (!this._running) return;
+			try {
+				await this._fire(event);
+			} catch (err) {
+				this._onError(err, event);
+			}
+		}
+		await this._store.saveCursor(windowEnd);
+	}
+	async _sleepUntil(targetMs) {
+		const remaining = targetMs - this._now();
+		if (remaining <= 0) return;
+		await new Promise((resolve) => {
+			let done = false;
+			const timer = this._setTimeout(() => {
+				if (done) return;
+				done = true;
+				this._wakeResolve = null;
+				resolve();
+			}, remaining);
+			this._wakeResolve = () => {
+				if (done) return;
+				done = true;
+				this._clearTimeout(timer);
+				this._wakeResolve = null;
+				resolve();
+			};
+		});
+	}
+	_wake() {
+		if (this._wakeResolve != null) this._wakeResolve();
+	}
+};
+function defaultOnError(err, event) {
+	if (event != null) console.error(`[Dispatcher] fire failed for ${event.templateId}/${event.occurrenceKey}:`, err);
+	else console.error("[Dispatcher] error:", err);
+}
+export { Dispatcher };
+
+//# sourceMappingURL=dispatcher.js.map

package/dist/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","names":[],"sources":["../src/dispatcher.ts"],"sourcesContent":["import type { IEventSubscription } from \"@j13b/state\";\nimport { type DispatcherStore, InMemoryDispatcherStore } from \"./dispatcher_store.js\";\nimport type { Scheduler } from \"./scheduler.js\";\nimport type { ScheduledEvent } from \"./types.js\";\n\n// Default safety-net wait when nothing is scheduled. The Scheduler.changed\n// event normally wakes us as soon as something gets added, so this is just\n// a backstop in case a notification is missed.\nconst DEFAULT_IDLE_TIMEOUT_MS = 60 * 60 * 1000;\n\nexport interface DispatcherConfig<TPayload extends { type: string }> {\n  scheduler: Scheduler<TPayload>;\n  // Called for each due event in cursor → now order. Errors thrown from here\n  // are passed to onError; the cursor advances regardless (cron-style: a\n  // permanently-failing fire shouldn't block the queue forever).\n  fire: (event: ScheduledEvent<TPayload>) => Promise<void> | void;\n  // Persists the cursor across restarts. Defaults to in-memory (no recovery).\n  store?: DispatcherStore;\n  // Called when fire() throws or list() fails. Defaults to console.error.\n  onError?: (err: unknown, event?: ScheduledEvent<TPayload>) => void;\n  // Backstop wait when no event is scheduled. Default 1 hour. Lower for tests.\n  idleTimeoutMs?: number;\n  // Clock injection (Date.now) and timer injection (setTimeout/clearTimeout).\n  // Defaults to wall clock. Inject for deterministic tests.\n  now?: () => number;\n  setTimeout?: (fn: () => void, ms: number) => unknown;\n  clearTimeout?: (handle: unknown) => void;\n}\n\n// Drives a Scheduler in real time. The loop:\n//   1. Catch up: list(cursor, now) → fire each → advance cursor → save.\n//   2. Find next: nextDue(now, 1) → wait until its startTimestamp.\n//   3. Wait may end early via Scheduler.changed (a write happened) or stop().\n// Catch-up handles crashes AND in-process adds we missed. The change event\n// handles in-process adds while we're sleeping — the dispatcher wakes\n// immediately and re-queries instead of firing the stale \"next\" event late.\nexport class Dispatcher<TPayload extends { type: string }> {\n  private readonly _scheduler: Scheduler<TPayload>;\n  private readonly _fire: (event: ScheduledEvent<TPayload>) => Promise<void> | void;\n  private readonly _store: DispatcherStore;\n  private readonly _onError: (err: unknown, event?: ScheduledEvent<TPayload>) => void;\n  private readonly _idleTimeoutMs: number;\n  private readonly _now: () => number;\n  private readonly _setTimeout: (fn: () => void, ms: number) => unknown;\n  private readonly _clearTimeout: (handle: unknown) => void;\n\n  private _running = false;\n  private _wakeResolve: (() => void) | null = null;\n  private _changeSubscription: IEventSubscription<void> | null = null;\n\n  constructor(config: DispatcherConfig<TPayload>) {\n    this._scheduler = config.scheduler;\n    this._fire = config.fire;\n    this._store = config.store ?? new InMemoryDispatcherStore();\n    this._onError = config.onError ?? defaultOnError;\n    this._idleTimeoutMs = config.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;\n    this._now = config.now ?? Date.now;\n    this._setTimeout = config.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms));\n    this._clearTimeout =\n      config.clearTimeout ?? ((h) => globalThis.clearTimeout(h as ReturnType<typeof setTimeout>));\n  }\n\n  // Starts the loop. Resolves after the first catch-up pass completes (so\n  // tests can await an initial sync). The loop keeps running in the\n  // background until stop() is called.\n  async start(): Promise<void> {\n    if (this._running) return;\n    this._running = true;\n    this._changeSubscription = this._scheduler.changed.subscribe(() => this._wake());\n    // First iteration in foreground so callers can await initial catch-up.\n    await this._tick();\n    if (this._running) void this._loop();\n  }\n\n  // Halts the loop. Any in-flight fire() completes; subsequent fires are\n  // skipped. The Scheduler subscription is removed.\n  stop(): void {\n    if (!this._running) return;\n    this._running = false;\n    if (this._changeSubscription != null) {\n      this._changeSubscription.unsubscribe();\n      this._changeSubscription = null;\n    }\n    this._wake();\n  }\n\n  // ─── Internals ──────────────────────────────────────────────\n\n  private async _loop(): Promise<void> {\n    while (this._running) {\n      const target = await this._findNextTarget();\n      if (!this._running) return;\n      await this._sleepUntil(target);\n      if (!this._running) return;\n      await this._tick();\n    }\n  }\n\n  // Returns the epoch-ms instant the dispatcher should next wake. Either\n  // the next due event's startTimestamp, or now + idleTimeoutMs.\n  private async _findNextTarget(): Promise<number> {\n    try {\n      const upcoming = await this._scheduler.nextDue(this._now(), 1);\n      const next = upcoming[0];\n      return next != null ? next.startTimestamp : this._now() + this._idleTimeoutMs;\n    } catch (err) {\n      this._onError(err);\n      return this._now() + this._idleTimeoutMs;\n    }\n  }\n\n  // Catch-up pass: fire everything with start in [cursor, now]. We use\n  // `now + 1` as the half-open windowEnd so an event scheduled exactly at\n  // the wake instant is included (the wake from setTimeout lands on the\n  // event's startTimestamp, and we don't want to miss it). Advancing the\n  // cursor to `now + 1` likewise avoids re-listing the same event on the\n  // next tick.\n  private async _tick(): Promise<void> {\n    const cursor = (await this._store.loadCursor()) ?? this._now();\n    const now = this._now();\n    const windowEnd = now + 1;\n    if (windowEnd <= cursor) {\n      // Cursor is already at or past `now + 1` — happens on the very first\n      // tick when we just-saved-and-rewoke. Nothing to do.\n      return;\n    }\n\n    let events: ScheduledEvent<TPayload>[];\n    try {\n      events = await this._scheduler.list(cursor, windowEnd);\n    } catch (err) {\n      this._onError(err);\n      // Don't advance cursor on a list failure — try again next tick.\n      return;\n    }\n\n    for (const event of events) {\n      if (!this._running) return;\n      try {\n        await this._fire(event);\n      } catch (err) {\n        this._onError(err, event);\n      }\n    }\n    await this._store.saveCursor(windowEnd);\n  }\n\n  // Sleeps until either the target epoch-ms instant, or wake() is called\n  // (via Scheduler.changed or stop()). No-op if target is already past.\n  private async _sleepUntil(targetMs: number): Promise<void> {\n    const remaining = targetMs - this._now();\n    if (remaining <= 0) return;\n    await new Promise<void>((resolve) => {\n      let done = false;\n      const timer = this._setTimeout(() => {\n        if (done) return;\n        done = true;\n        this._wakeResolve = null;\n        resolve();\n      }, remaining);\n      this._wakeResolve = () => {\n        if (done) return;\n        done = true;\n        this._clearTimeout(timer);\n        this._wakeResolve = null;\n        resolve();\n      };\n    });\n  }\n\n  // Resolves any in-flight _sleepUntil. Called by stop() and by the\n  // Scheduler.changed subscription.\n  private _wake(): void {\n    if (this._wakeResolve != null) this._wakeResolve();\n  }\n}\n\nfunction defaultOnError(err: unknown, event?: ScheduledEvent<{ type: string }>): void {\n  if (event != null) {\n    console.error(`[Dispatcher] fire failed for ${event.templateId}/${event.occurrenceKey}:`, err);\n  } else {\n    console.error(\"[Dispatcher] error:\", err);\n  }\n}\n"],"mappings":";;AAQA,IAAM,0BAA0B;AA4BhC,IAAa,aAAb,MAA2D;CACzD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA,WAAmB;CACnB,eAA4C;CAC5C,sBAA+D;CAE/D,YAAY,QAAoC;EAC9C,KAAK,aAAa,OAAO;EACzB,KAAK,QAAQ,OAAO;EACpB,KAAK,SAAS,OAAO,SAAS,IAAI,wBAAwB;EAC1D,KAAK,WAAW,OAAO,WAAW;EAClC,KAAK,iBAAiB,OAAO,iBAAiB;EAC9C,KAAK,OAAO,OAAO,OAAO,KAAK;EAC/B,KAAK,cAAc,OAAO,gBAAgB,IAAI,OAAO,WAAW,WAAW,IAAI,EAAE;EACjF,KAAK,gBACH,OAAO,kBAAkB,MAAM,WAAW,aAAa,CAAkC;CAC7F;CAKA,MAAM,QAAuB;EAC3B,IAAI,KAAK,UAAU;EACnB,KAAK,WAAW;EAChB,KAAK,sBAAsB,KAAK,WAAW,QAAQ,gBAAgB,KAAK,MAAM,CAAC;EAE/E,MAAM,KAAK,MAAM;EACjB,IAAI,KAAK,UAAU,KAAU,MAAM;CACrC;CAIA,OAAa;EACX,IAAI,CAAC,KAAK,UAAU;EACpB,KAAK,WAAW;EAChB,IAAI,KAAK,uBAAuB,MAAM;GACpC,KAAK,oBAAoB,YAAY;GACrC,KAAK,sBAAsB;EAC7B;EACA,KAAK,MAAM;CACb;CAIA,MAAc,QAAuB;EACnC,OAAO,KAAK,UAAU;GACpB,MAAM,SAAS,MAAM,KAAK,gBAAgB;GAC1C,IAAI,CAAC,KAAK,UAAU;GACpB,MAAM,KAAK,YAAY,MAAM;GAC7B,IAAI,CAAC,KAAK,UAAU;GACpB,MAAM,KAAK,MAAM;EACnB;CACF;CAIA,MAAc,kBAAmC;EAC/C,IAAI;GAEF,MAAM,QAAO,MADU,KAAK,WAAW,QAAQ,KAAK,KAAK,GAAG,CAAC,EAAA,CACvC;GACtB,OAAO,QAAQ,OAAO,KAAK,iBAAiB,KAAK,KAAK,IAAI,KAAK;EACjE,SAAS,KAAK;GACZ,KAAK,SAAS,GAAG;GACjB,OAAO,KAAK,KAAK,IAAI,KAAK;EAC5B;CACF;CAQA,MAAc,QAAuB;EACnC,MAAM,SAAU,MAAM,KAAK,OAAO,WAAW,KAAM,KAAK,KAAK;EAE7D,MAAM,YADM,KAAK,KACC,IAAM;EACxB,IAAI,aAAa,QAGf;EAGF,IAAI;EACJ,IAAI;GACF,SAAS,MAAM,KAAK,WAAW,KAAK,QAAQ,SAAS;EACvD,SAAS,KAAK;GACZ,KAAK,SAAS,GAAG;GAEjB;EACF;EAEA,KAAK,MAAM,SAAS,QAAQ;GAC1B,IAAI,CAAC,KAAK,UAAU;GACpB,IAAI;IACF,MAAM,KAAK,MAAM,KAAK;GACxB,SAAS,KAAK;IACZ,KAAK,SAAS,KAAK,KAAK;GAC1B;EACF;EACA,MAAM,KAAK,OAAO,WAAW,SAAS;CACxC;CAIA,MAAc,YAAY,UAAiC;EACzD,MAAM,YAAY,WAAW,KAAK,KAAK;EACvC,IAAI,aAAa,GAAG;EACpB,MAAM,IAAI,SAAe,YAAY;GACnC,IAAI,OAAO;GACX,MAAM,QAAQ,KAAK,kBAAkB;IACnC,IAAI,MAAM;IACV,OAAO;IACP,KAAK,eAAe;IACpB,QAAQ;GACV,GAAG,SAAS;GACZ,KAAK,qBAAqB;IACxB,IAAI,MAAM;IACV,OAAO;IACP,KAAK,cAAc,KAAK;IACxB,KAAK,eAAe;IACpB,QAAQ;GACV;EACF,CAAC;CACH;CAIA,QAAsB;EACpB,IAAI,KAAK,gBAAgB,MAAM,KAAK,aAAa;CACnD;AACF;AAEA,SAAS,eAAe,KAAc,OAAgD;CACpF,IAAI,SAAS,MACX,QAAQ,MAAM,gCAAgC,MAAM,WAAW,GAAG,MAAM,cAAc,IAAI,GAAG;MAE7F,QAAQ,MAAM,uBAAuB,GAAG;AAE5C"}

package/dist/dispatcher_store.d.ts

@@ -0,0 +1,10 @@
+export interface DispatcherStore {
+    loadCursor(): Promise<number | null>;
+    saveCursor(cursor: number): Promise<void>;
+}
+export declare class InMemoryDispatcherStore implements DispatcherStore {
+    private _cursor;
+    loadCursor(): Promise<number | null>;
+    saveCursor(cursor: number): Promise<void>;
+}
+//# sourceMappingURL=dispatcher_store.d.ts.map

package/dist/dispatcher_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher_store.d.ts","sourceRoot":"","sources":["../src/dispatcher_store.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAID,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,OAAO,CAAuB;IAEhC,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIpC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}

package/dist/dispatcher_store.js

@@ -0,0 +1,13 @@
+// src/dispatcher_store.ts
+var InMemoryDispatcherStore = class {
+	_cursor = null;
+	async loadCursor() {
+		return this._cursor;
+	}
+	async saveCursor(cursor) {
+		this._cursor = cursor;
+	}
+};
+export { InMemoryDispatcherStore };
+
+//# sourceMappingURL=dispatcher_store.js.map

package/dist/dispatcher_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher_store.js","names":[],"sources":["../src/dispatcher_store.ts"],"sourcesContent":["// Persistence for the Dispatcher's tick cursor. The cursor is a single\n// epoch-ms value: the last instant for which the Dispatcher has fired all\n// due events. On restart, the Dispatcher catches up by listing events in\n// [cursor, now) and firing them — so a process crash followed by restart\n// won't lose events that were due during downtime.\n//\n// Same shape as ChatStore / MemoryStore in the agent module — implement\n// against whatever backend you want.\nexport interface DispatcherStore {\n  loadCursor(): Promise<number | null>;\n  saveCursor(cursor: number): Promise<void>;\n}\n\n// Reference in-memory implementation. Useful for tests and short-lived\n// processes that don't need crash recovery.\nexport class InMemoryDispatcherStore implements DispatcherStore {\n  private _cursor: number | null = null;\n\n  async loadCursor(): Promise<number | null> {\n    return this._cursor;\n  }\n\n  async saveCursor(cursor: number): Promise<void> {\n    this._cursor = cursor;\n  }\n}\n"],"mappings":";AAeA,IAAa,0BAAb,MAAgE;CAC9D,UAAiC;CAEjC,MAAM,aAAqC;EACzC,OAAO,KAAK;CACd;CAEA,MAAM,WAAW,QAA+B;EAC9C,KAAK,UAAU;CACjB;AACF"}

package/dist/generators/anchored.d.ts

@@ -0,0 +1,4 @@
+import { AnchoredRule } from '../types.js';
+import { Occurrence } from './types.js';
+export declare function generateAnchored(rule: AnchoredRule, tz: string | undefined, windowStart: number, windowEnd: number): Occurrence[];
+//# sourceMappingURL=anchored.d.ts.map

package/dist/generators/anchored.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchored.d.ts","sourceRoot":"","sources":["../../src/generators/anchored.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAEL,KAAK,UAAU,EAGhB,MAAM,YAAY,CAAC;AAKpB,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,EAClB,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,UAAU,EAAE,CAmDd"}

package/dist/generators/anchored.js

@@ -0,0 +1,42 @@
+import { computeSpanEnd } from "../tz.js";
+import { TooManyOccurrencesError, intersects } from "./types.js";
+// src/generators/anchored.ts
+function generateAnchored(rule, tz, windowStart, windowEnd) {
+	if (rule.intervalMs <= 0) throw new Error(`AnchoredRule.intervalMs must be > 0 (got ${rule.intervalMs})`);
+	if (rule.count != null && rule.count < 0) throw new Error(`AnchoredRule.count must be >= 0 (got ${rule.count})`);
+	const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+	const effectiveEnd = Math.min(windowEnd, seriesEnd);
+	const effectiveStart = Math.max(windowStart, rule.seriesStart);
+	if (effectiveStart >= effectiveEnd) return [];
+	let index;
+	let occurrenceStart;
+	if (rule.count != null) {
+		index = 0;
+		occurrenceStart = rule.anchorDate;
+	} else if (effectiveStart <= rule.anchorDate) {
+		index = 0;
+		occurrenceStart = rule.anchorDate;
+	} else {
+		const stepsAhead = Math.ceil((effectiveStart - rule.anchorDate) / rule.intervalMs);
+		index = stepsAhead;
+		occurrenceStart = rule.anchorDate + stepsAhead * rule.intervalMs;
+	}
+	const out = [];
+	while (occurrenceStart < effectiveEnd) {
+		if (rule.count != null && index >= rule.count) break;
+		const occEnd = computeSpanEnd(occurrenceStart, rule.timeSpan, tz);
+		if (intersects(occurrenceStart, occEnd, windowStart, windowEnd) && occurrenceStart >= rule.seriesStart) {
+			out.push({
+				startTimestamp: occurrenceStart,
+				endTimestamp: occEnd
+			});
+			if (out.length > 1e4) throw new TooManyOccurrencesError("anchored");
+		}
+		index++;
+		occurrenceStart += rule.intervalMs;
+	}
+	return out;
+}
+export { generateAnchored };
+
+//# sourceMappingURL=anchored.js.map

package/dist/generators/anchored.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchored.js","names":[],"sources":["../../src/generators/anchored.ts"],"sourcesContent":["import type { AnchoredRule } from \"../types.js\";\nimport { computeSpanEnd } from \"../tz.js\";\nimport {\n  MAX_OCCURRENCES_PER_GENERATE,\n  type Occurrence,\n  TooManyOccurrencesError,\n  intersects,\n} from \"./types.js\";\n\n// Anchored is tz-independent for STEPPING (every occurrence is exactly\n// intervalMs ms from the anchor), but tz can still affect the end-of-\n// occurrence when hourSpan is used. seriesStart/seriesEnd bound in UTC.\nexport function generateAnchored(\n  rule: AnchoredRule,\n  tz: string | undefined,\n  windowStart: number,\n  windowEnd: number\n): Occurrence[] {\n  if (rule.intervalMs <= 0) {\n    throw new Error(`AnchoredRule.intervalMs must be > 0 (got ${rule.intervalMs})`);\n  }\n  if (rule.count != null && rule.count < 0) {\n    throw new Error(`AnchoredRule.count must be >= 0 (got ${rule.count})`);\n  }\n\n  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;\n  const effectiveEnd = Math.min(windowEnd, seriesEnd);\n  const effectiveStart = Math.max(windowStart, rule.seriesStart);\n\n  if (effectiveStart >= effectiveEnd) return [];\n\n  // If `count` is set we must start counting from the anchor; otherwise we\n  // can fast-forward to the window start.\n  let index: number;\n  let occurrenceStart: number;\n  if (rule.count != null) {\n    index = 0;\n    occurrenceStart = rule.anchorDate;\n  } else {\n    if (effectiveStart <= rule.anchorDate) {\n      index = 0;\n      occurrenceStart = rule.anchorDate;\n    } else {\n      // First occurrence at or after effectiveStart.\n      const stepsAhead = Math.ceil((effectiveStart - rule.anchorDate) / rule.intervalMs);\n      index = stepsAhead;\n      occurrenceStart = rule.anchorDate + stepsAhead * rule.intervalMs;\n    }\n  }\n\n  const out: Occurrence[] = [];\n  while (occurrenceStart < effectiveEnd) {\n    if (rule.count != null && index >= rule.count) break;\n\n    const occEnd = computeSpanEnd(occurrenceStart, rule.timeSpan, tz);\n    if (\n      intersects(occurrenceStart, occEnd, windowStart, windowEnd) &&\n      occurrenceStart >= rule.seriesStart\n    ) {\n      out.push({ startTimestamp: occurrenceStart, endTimestamp: occEnd });\n      if (out.length > MAX_OCCURRENCES_PER_GENERATE) {\n        throw new TooManyOccurrencesError(\"anchored\");\n      }\n    }\n    index++;\n    occurrenceStart += rule.intervalMs;\n  }\n  return out;\n}\n"],"mappings":";;;AAYA,SAAgB,iBACd,MACA,IACA,aACA,WACc;CACd,IAAI,KAAK,cAAc,GACrB,MAAM,IAAI,MAAM,4CAA4C,KAAK,WAAW,EAAE;CAEhF,IAAI,KAAK,SAAS,QAAQ,KAAK,QAAQ,GACrC,MAAM,IAAI,MAAM,wCAAwC,KAAK,MAAM,EAAE;CAGvE,MAAM,YAAY,KAAK,aAAa,OAAO;CAC3C,MAAM,eAAe,KAAK,IAAI,WAAW,SAAS;CAClD,MAAM,iBAAiB,KAAK,IAAI,aAAa,KAAK,WAAW;CAE7D,IAAI,kBAAkB,cAAc,OAAO,CAAC;CAI5C,IAAI;CACJ,IAAI;CACJ,IAAI,KAAK,SAAS,MAAM;EACtB,QAAQ;EACR,kBAAkB,KAAK;CACzB,OACE,IAAI,kBAAkB,KAAK,YAAY;EACrC,QAAQ;EACR,kBAAkB,KAAK;CACzB,OAAO;EAEL,MAAM,aAAa,KAAK,MAAM,iBAAiB,KAAK,cAAc,KAAK,UAAU;EACjF,QAAQ;EACR,kBAAkB,KAAK,aAAa,aAAa,KAAK;CACxD;CAGF,MAAM,MAAoB,CAAC;CAC3B,OAAO,kBAAkB,cAAc;EACrC,IAAI,KAAK,SAAS,QAAQ,SAAS,KAAK,OAAO;EAE/C,MAAM,SAAS,eAAe,iBAAiB,KAAK,UAAU,EAAE;EAChE,IACE,WAAW,iBAAiB,QAAQ,aAAa,SAAS,KAC1D,mBAAmB,KAAK,aACxB;GACA,IAAI,KAAK;IAAE,gBAAgB;IAAiB,cAAc;GAAO,CAAC;GAClE,IAAI,IAAI,SAAA,KACN,MAAM,IAAI,wBAAwB,UAAU;EAEhD;EACA;EACA,mBAAmB,KAAK;CAC1B;CACA,OAAO;AACT"}

package/dist/generators/days_of_month.d.ts

@@ -0,0 +1,4 @@
+import { DaysOfMonthRule, Disambiguation } from '../types.js';
+import { Occurrence } from './types.js';
+export declare function generateDaysOfMonth(rule: DaysOfMonthRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];
+//# sourceMappingURL=days_of_month.d.ts.map

package/dist/generators/days_of_month.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"days_of_month.d.ts","sourceRoot":"","sources":["../../src/generators/days_of_month.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQnE,OAAO,EAEL,KAAK,UAAU,EAGhB,MAAM,YAAY,CAAC;AAIpB,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,cAA6B,GAC5C,UAAU,EAAE,CA4Ed"}

package/dist/generators/days_of_month.js

@@ -0,0 +1,53 @@
+import { computeSpanEnd, isNonexistentWallTime, monthLength, utcToWallParts, wallTimeToUtc } from "../tz.js";
+import { TooManyOccurrencesError, intersects } from "./types.js";
+// src/generators/days_of_month.ts
+function generateDaysOfMonth(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+	if (rule.yearInterval <= 0) throw new Error(`DaysOfMonthRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+	if (rule.months.length === 0) throw new Error("DaysOfMonthRule.months must be non-empty");
+	for (const m of rule.months) if (m < 0 || m > 11) throw new Error(`DaysOfMonthRule.months entries must be in 0..11 (got ${m})`);
+	if (rule.daysOfMonth.length === 0) throw new Error("DaysOfMonthRule.daysOfMonth must be non-empty");
+	for (const d of rule.daysOfMonth) if (d < 1 || d > 31) throw new Error(`DaysOfMonthRule.daysOfMonth entries must be in 1..31 (got ${d})`);
+	if (rule.count != null && rule.count < 0) throw new Error(`DaysOfMonthRule.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 daysOfMonth = [...new Set(rule.daysOfMonth)].sort((a, b) => a - b);
+	const startYear = utcToWallParts(rule.seriesStart, tz).year;
+	const endYear = 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 month of months) {
+			const len = monthLength(year, month);
+			const clampedDays = [...new Set(daysOfMonth.map((d) => Math.min(d, len)))];
+			for (const day of clampedDays) {
+				if (disambiguation === "skip" && isNonexistentWallTime(year, month, day, rule.timeOfDay, tz)) continue;
+				const occStart = wallTimeToUtc(year, month, day, rule.timeOfDay, tz, disambiguation);
+				const occEnd = 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 (intersects(occStart, occEnd, windowStart, windowEnd)) {
+					yearEmits.push({
+						startTimestamp: occStart,
+						endTimestamp: occEnd
+					});
+					if (out.length + yearEmits.length > 1e4) throw new TooManyOccurrencesError("daysOfMonth");
+				}
+			}
+		}
+		yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+		out.push(...yearEmits);
+	}
+	return out;
+}
+export { generateDaysOfMonth };
+
+//# sourceMappingURL=days_of_month.js.map

package/dist/generators/days_of_month.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"days_of_month.js","names":[],"sources":["../../src/generators/days_of_month.ts"],"sourcesContent":["import type { DaysOfMonthRule, Disambiguation } from \"../types.js\";\nimport {\n  computeSpanEnd,\n  isNonexistentWallTime,\n  monthLength,\n  utcToWallParts,\n  wallTimeToUtc,\n} from \"../tz.js\";\nimport {\n  MAX_OCCURRENCES_PER_GENERATE,\n  type Occurrence,\n  TooManyOccurrencesError,\n  intersects,\n} from \"./types.js\";\n\n// Numerical date-based recurrence: months × daysOfMonth. Days clamp per\n// month (day 31 in April → Apr 30, day 29 in Feb non-leap → Feb 28).\nexport function generateDaysOfMonth(\n  rule: DaysOfMonthRule,\n  tz: string | undefined,\n  windowStart: number,\n  windowEnd: number,\n  disambiguation: Disambiguation = \"compatible\"\n): Occurrence[] {\n  if (rule.yearInterval <= 0) {\n    throw new Error(`DaysOfMonthRule.yearInterval must be > 0 (got ${rule.yearInterval})`);\n  }\n  if (rule.months.length === 0) {\n    throw new Error(\"DaysOfMonthRule.months must be non-empty\");\n  }\n  for (const m of rule.months) {\n    if (m < 0 || m > 11) {\n      throw new Error(`DaysOfMonthRule.months entries must be in 0..11 (got ${m})`);\n    }\n  }\n  if (rule.daysOfMonth.length === 0) {\n    throw new Error(\"DaysOfMonthRule.daysOfMonth must be non-empty\");\n  }\n  for (const d of rule.daysOfMonth) {\n    if (d < 1 || d > 31) {\n      throw new Error(`DaysOfMonthRule.daysOfMonth entries must be in 1..31 (got ${d})`);\n    }\n  }\n  if (rule.count != null && rule.count < 0) {\n    throw new Error(`DaysOfMonthRule.count must be >= 0 (got ${rule.count})`);\n  }\n\n  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;\n  const effectiveEnd = Math.min(windowEnd, seriesEnd);\n  if (rule.seriesStart >= effectiveEnd) return [];\n\n  const months = [...new Set(rule.months)].sort((a, b) => a - b);\n  const daysOfMonth = [...new Set(rule.daysOfMonth)].sort((a, b) => a - b);\n\n  const startYear = utcToWallParts(rule.seriesStart, tz).year;\n  const endYear = utcToWallParts(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;\n\n  const out: Occurrence[] = [];\n  let count = 0;\n\n  for (let year = startYear; year <= endYear; year += rule.yearInterval) {\n    const yearEmits: Occurrence[] = [];\n\n    for (const month of months) {\n      const len = monthLength(year, month);\n      // Dedup clamped days so day-31 + day-30 in April don't both emit Apr 30.\n      const clampedDays = [...new Set(daysOfMonth.map((d) => Math.min(d, len)))];\n      for (const day of clampedDays) {\n        if (\n          disambiguation === \"skip\" &&\n          isNonexistentWallTime(year, month, day, rule.timeOfDay, tz)\n        ) {\n          continue;\n        }\n        const occStart = wallTimeToUtc(year, month, day, rule.timeOfDay, tz, disambiguation);\n        const occEnd = computeSpanEnd(occStart, rule.timeSpan, tz);\n\n        if (occStart < rule.seriesStart) continue;\n        if (occStart >= seriesEnd) continue;\n\n        if (rule.count != null && count >= rule.count) {\n          yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);\n          out.push(...yearEmits);\n          return out;\n        }\n        count++;\n\n        if (intersects(occStart, occEnd, windowStart, windowEnd)) {\n          yearEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });\n          if (out.length + yearEmits.length > MAX_OCCURRENCES_PER_GENERATE) {\n            throw new TooManyOccurrencesError(\"daysOfMonth\");\n          }\n        }\n      }\n    }\n    yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);\n    out.push(...yearEmits);\n  }\n  return out;\n}\n"],"mappings":";;;AAiBA,SAAgB,oBACd,MACA,IACA,aACA,WACA,iBAAiC,cACnB;CACd,IAAI,KAAK,gBAAgB,GACvB,MAAM,IAAI,MAAM,iDAAiD,KAAK,aAAa,EAAE;CAEvF,IAAI,KAAK,OAAO,WAAW,GACzB,MAAM,IAAI,MAAM,0CAA0C;CAE5D,KAAK,MAAM,KAAK,KAAK,QACnB,IAAI,IAAI,KAAK,IAAI,IACf,MAAM,IAAI,MAAM,wDAAwD,EAAE,EAAE;CAGhF,IAAI,KAAK,YAAY,WAAW,GAC9B,MAAM,IAAI,MAAM,+CAA+C;CAEjE,KAAK,MAAM,KAAK,KAAK,aACnB,IAAI,IAAI,KAAK,IAAI,IACf,MAAM,IAAI,MAAM,6DAA6D,EAAE,EAAE;CAGrF,IAAI,KAAK,SAAS,QAAQ,KAAK,QAAQ,GACrC,MAAM,IAAI,MAAM,2CAA2C,KAAK,MAAM,EAAE;CAG1E,MAAM,YAAY,KAAK,aAAa,OAAO;CAC3C,MAAM,eAAe,KAAK,IAAI,WAAW,SAAS;CAClD,IAAI,KAAK,eAAe,cAAc,OAAO,CAAC;CAE9C,MAAM,SAAS,CAAC,GAAG,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC;CAC7D,MAAM,cAAc,CAAC,GAAG,IAAI,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC;CAEvE,MAAM,YAAY,eAAe,KAAK,aAAa,EAAE,CAAC,CAAC;CACvD,MAAM,UAAU,eAAe,KAAK,IAAI,cAAc,OAAO,gBAAgB,GAAG,EAAE,CAAC,CAAC;CAEpF,MAAM,MAAoB,CAAC;CAC3B,IAAI,QAAQ;CAEZ,KAAK,IAAI,OAAO,WAAW,QAAQ,SAAS,QAAQ,KAAK,cAAc;EACrE,MAAM,YAA0B,CAAC;EAEjC,KAAK,MAAM,SAAS,QAAQ;GAC1B,MAAM,MAAM,YAAY,MAAM,KAAK;GAEnC,MAAM,cAAc,CAAC,GAAG,IAAI,IAAI,YAAY,KAAK,MAAM,KAAK,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;GACzE,KAAK,MAAM,OAAO,aAAa;IAC7B,IACE,mBAAmB,UACnB,sBAAsB,MAAM,OAAO,KAAK,KAAK,WAAW,EAAE,GAE1D;IAEF,MAAM,WAAW,cAAc,MAAM,OAAO,KAAK,KAAK,WAAW,IAAI,cAAc;IACnF,MAAM,SAAS,eAAe,UAAU,KAAK,UAAU,EAAE;IAEzD,IAAI,WAAW,KAAK,aAAa;IACjC,IAAI,YAAY,WAAW;IAE3B,IAAI,KAAK,SAAS,QAAQ,SAAS,KAAK,OAAO;KAC7C,UAAU,MAAM,GAAG,MAAM,EAAE,iBAAiB,EAAE,cAAc;KAC5D,IAAI,KAAK,GAAG,SAAS;KACrB,OAAO;IACT;IACA;IAEA,IAAI,WAAW,UAAU,QAAQ,aAAa,SAAS,GAAG;KACxD,UAAU,KAAK;MAAE,gBAAgB;MAAU,cAAc;KAAO,CAAC;KACjE,IAAI,IAAI,SAAS,UAAU,SAAA,KACzB,MAAM,IAAI,wBAAwB,aAAa;IAEnD;GACF;EACF;EACA,UAAU,MAAM,GAAG,MAAM,EAAE,iBAAiB,EAAE,cAAc;EAC5D,IAAI,KAAK,GAAG,SAAS;CACvB;CACA,OAAO;AACT"}

package/dist/generators/days_of_week.d.ts

@@ -0,0 +1,6 @@
+import { DaysOfWeekRule, Disambiguation } from '../types.js';
+import { dayOfWeekInTz } from '../tz.js';
+import { Occurrence } from './types.js';
+export declare function generateDaysOfWeek(rule: DaysOfWeekRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];
+export { dayOfWeekInTz };
+//# sourceMappingURL=days_of_week.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"days_of_week.d.ts","sourceRoot":"","sources":["../../src/generators/days_of_week.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAGL,aAAa,EAId,MAAM,UAAU,CAAC;AAClB,OAAO,EAEL,KAAK,UAAU,EAGhB,MAAM,YAAY,CAAC;AAKpB,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,cAAc,EACpB,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,cAA6B,GAC5C,UAAU,EAAE,CAwEd;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC"}