@j13b/scheduler 0.0.0-stage → 0.1.1

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/cjs/validate_rule.d.ts

@@ -0,0 +1,4 @@
+import type { RecurrenceRule, TimeSpan } from "./types.js";
+export declare const RULE_KINDS: RecurrenceRule["kind"][];
+export declare function validateRule(rule: RecurrenceRule): void;
+export declare function validateTimeSpan(span: unknown): asserts span is TimeSpan | undefined;

package/dist/cjs/validate_rule.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULE_KINDS = void 0;
+exports.validateRule = validateRule;
+exports.validateTimeSpan = validateTimeSpan;
+// ─── Rule validation ──────────────────────────────────────────
+//
+// A rule often comes from outside the type system: JSON in a database, a
+// request body, or an LLM tool call. So validation checks the WHOLE shape —
+// every required field present, of the right type, in range, and no fields
+// the kind does not have — and throws an Error that names the field and the
+// form it expects. A bad rule never reaches a generator, where it would crash
+// with "Cannot read properties of undefined" or "Invalid time value".
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAYS_HINT = "Day numbers 0..6 (0=Sunday, 1=Monday … 6=Saturday)";
+const MONTHS_HINT = "Month numbers 0..11 (0=January … 11=December)";
+const WEEKS_HINT = "week-of-month numbers 1..5 (1=first) or -1..-5 (-1=last)";
+const TIME_OF_DAY_HINT = "ms after local midnight, 0..86_399_999 (7:00 = 25_200_000)";
+const TIMESTAMP_HINT = "a UTC timestamp in ms";
+// The common series fields every repeating kind has.
+const SERIES = {
+    timeSpan: { required: false, check: (v) => validateTimeSpan(v) },
+    seriesStart: { required: true, check: timestamp },
+    seriesEnd: { required: true, check: nullable(timestamp, "null (no end)") },
+    count: {
+        required: false,
+        check: nullable(int(0, Number.MAX_SAFE_INTEGER, "a whole number >= 0"), "null"),
+    },
+};
+const TIME_OF_DAY = { required: true, check: int(0, DAY_MS - 1, TIME_OF_DAY_HINT) };
+const KINDS = {
+    instant: {
+        name: "InstantRule",
+        fields: {
+            startOn: { required: true, check: timestamp },
+            timeSpan: { required: false, check: (v) => validateTimeSpan(v) },
+        },
+    },
+    localDateTime: {
+        name: "LocalDateTimeRule",
+        fields: {
+            year: { required: true, check: int(1, 9999, "a year such as 2026") },
+            month: { required: true, check: int(0, 11, MONTHS_HINT) },
+            day: { required: true, check: int(1, 31, "a day of the month 1..31") },
+            timeOfDay: TIME_OF_DAY,
+            timeSpan: { required: false, check: (v) => validateTimeSpan(v) },
+        },
+    },
+    anchored: {
+        name: "AnchoredRule",
+        fields: {
+            anchorDate: { required: true, check: timestamp },
+            intervalMs: { required: true, check: positive("an interval in ms > 0") },
+            ...SERIES,
+        },
+    },
+    daysOfWeek: {
+        name: "DaysOfWeekRule",
+        fields: {
+            days: { required: true, check: intList(0, 6, DAYS_HINT) },
+            weekInterval: {
+                required: true,
+                check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every week)"),
+            },
+            timeOfDay: TIME_OF_DAY,
+            ...SERIES,
+        },
+    },
+    weeksOfMonth: {
+        name: "WeeksOfMonthRule",
+        fields: {
+            days: { required: true, check: intList(0, 6, DAYS_HINT) },
+            weeks: { required: true, check: weekList },
+            monthInterval: {
+                required: true,
+                check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every month)"),
+            },
+            timeOfDay: TIME_OF_DAY,
+            ...SERIES,
+        },
+    },
+    monthsOfYear: {
+        name: "MonthsOfYearRule",
+        fields: {
+            months: { required: true, check: intList(0, 11, MONTHS_HINT) },
+            weeks: { required: true, check: weekList },
+            days: { required: true, check: intList(0, 6, DAYS_HINT) },
+            yearInterval: {
+                required: true,
+                check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+            },
+            timeOfDay: TIME_OF_DAY,
+            ...SERIES,
+        },
+    },
+    yearly: {
+        name: "YearlyRule",
+        fields: {
+            month: { required: true, check: int(0, 11, MONTHS_HINT) },
+            day: { required: true, check: int(1, 31, "a day of the month 1..31") },
+            yearInterval: {
+                required: true,
+                check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+            },
+            timeOfDay: TIME_OF_DAY,
+            ...SERIES,
+        },
+    },
+    daysOfMonth: {
+        name: "DaysOfMonthRule",
+        fields: {
+            months: { required: true, check: intList(0, 11, MONTHS_HINT) },
+            daysOfMonth: { required: true, check: intList(1, 31, "days of the month 1..31") },
+            yearInterval: {
+                required: true,
+                check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+            },
+            timeOfDay: TIME_OF_DAY,
+            ...SERIES,
+        },
+    },
+    daysOfYear: {
+        name: "DaysOfYearRule",
+        fields: {
+            daysOfYear: { required: true, check: intList(1, 366, "days of the year 1..366") },
+            yearInterval: {
+                required: true,
+                check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+            },
+            timeOfDay: TIME_OF_DAY,
+            ...SERIES,
+        },
+    },
+};
+// The rule kinds, in the order the types declare them.
+exports.RULE_KINDS = Object.keys(KINDS);
+// Throws when `rule` is not a valid RecurrenceRule. The message names the
+// first wrong field and the form it expects.
+function validateRule(rule) {
+    const raw = rule;
+    if (typeof raw !== "object" || raw == null || Array.isArray(raw)) {
+        throw new Error(`A rule must be an object with a "kind" (one of ${exports.RULE_KINDS.join(", ")})`);
+    }
+    const obj = raw;
+    const kind = KINDS[obj.kind];
+    if (kind == null) {
+        throw new Error(`Unknown rule kind ${JSON.stringify(obj.kind)} (expected one of ${exports.RULE_KINDS.join(", ")})`);
+    }
+    const known = Object.keys(kind.fields);
+    for (const key of Object.keys(obj)) {
+        if (key !== "kind" && !known.includes(key)) {
+            throw new Error(`${kind.name} has no field "${key}" (its fields are: ${known.join(", ")})`);
+        }
+    }
+    for (const [field, spec] of Object.entries(kind.fields)) {
+        const label = `${kind.name}.${field}`;
+        if (obj[field] === undefined) {
+            if (spec.required)
+                throw new Error(`${label} is required: ${describe(spec, label)}`);
+            continue;
+        }
+        spec.check(obj[field], label);
+    }
+    const seriesStart = obj.seriesStart;
+    const seriesEnd = obj.seriesEnd;
+    if (seriesStart != null && seriesEnd != null && seriesEnd <= seriesStart) {
+        throw new Error(`${kind.name}.seriesEnd must be > seriesStart`);
+    }
+}
+// Throws when `span` is not a TimeSpan. Undefined is valid (the rule's
+// default span applies).
+function validateTimeSpan(span) {
+    if (span === undefined)
+        return;
+    const form = '{ "type": "duration", "ms": <ms >= 1> } or { "type": "hourSpan", "hours": <hours > 0> }';
+    if (typeof span !== "object" || span == null) {
+        throw new Error(`timeSpan must be ${form}`);
+    }
+    const s = span;
+    if (s.type === "duration") {
+        if (typeof s.ms !== "number" || !Number.isFinite(s.ms) || s.ms < 1) {
+            throw new Error(`timeSpan.ms must be >= 1 if supplied (got ${String(s.ms)})`);
+        }
+        return;
+    }
+    if (s.type === "hourSpan") {
+        if (typeof s.hours !== "number" || !Number.isFinite(s.hours) || s.hours <= 0) {
+            throw new Error(`timeSpan.hours must be > 0 (got ${String(s.hours)})`);
+        }
+        return;
+    }
+    throw new Error(`timeSpan must be ${form} (got type ${JSON.stringify(s.type)})`);
+}
+// ─── Field checks ─────────────────────────────────────────────
+// What the field should hold, for "is required" messages: each check is
+// called on undefined and its message reused.
+function describe(spec, label) {
+    try {
+        spec.check(undefined, label);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const at = msg.indexOf(" must be ");
+        if (at >= 0)
+            return msg.slice(at + " must be ".length).replace(/ \(got [^)]*\)$/, "");
+    }
+    return "see the rule's type";
+}
+function show(v) {
+    return v === undefined ? "nothing" : JSON.stringify(v);
+}
+function isInt(v) {
+    return typeof v === "number" && Number.isInteger(v);
+}
+function int(min, max, hint) {
+    return (v, field) => {
+        if (!isInt(v) || v < min || v > max)
+            throw new Error(`${field} must be ${hint} (got ${show(v)})`);
+    };
+}
+function positive(hint) {
+    return (v, field) => {
+        if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) {
+            throw new Error(`${field} must be ${hint} (got ${show(v)})`);
+        }
+    };
+}
+function timestamp(v, field) {
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new Error(`${field} must be ${TIMESTAMP_HINT} (got ${show(v)})`);
+    }
+}
+function nullable(check, nullHint) {
+    return (v, field) => {
+        if (v === null)
+            return;
+        try {
+            check(v, field);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(msg.replace(/ \(got /, ` or ${nullHint} (got `));
+        }
+    };
+}
+function intList(min, max, hint) {
+    return (v, field) => {
+        const form = `a non-empty array of ${hint}`;
+        if (!Array.isArray(v) || v.length === 0)
+            throw new Error(`${field} must be ${form} (got ${show(v)})`);
+        for (const x of v) {
+            if (!isInt(x) || x < min || x > max) {
+                throw new Error(`${field} must be ${form} (got ${show(v)}; ${show(x)} is out of range)`);
+            }
+        }
+    };
+}
+function weekList(v, field) {
+    const form = `a non-empty array of ${WEEKS_HINT}`;
+    if (!Array.isArray(v) || v.length === 0)
+        throw new Error(`${field} must be ${form} (got ${show(v)})`);
+    for (const w of v) {
+        if (!isInt(w) || w === 0 || w < -5 || w > 5) {
+            throw new Error(`${field} must be ${form} (got ${show(v)}; ${show(w)} is out of range)`);
+        }
+    }
+}

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":"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"}

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