@j13b/scheduler 0.0.0-stage → 0.1.1

package/dist/cjs/package.json

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

package/dist/cjs/port.d.ts

@@ -0,0 +1,15 @@
+import type { Alteration, ScheduleTemplate } from "./types.js";
+export interface SchedulerPort<TPayload extends {
+    type: string;
+}> {
+    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/port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/scheduler.d.ts

@@ -0,0 +1,23 @@
+import { type IEventBroadcast } from "@j13b/state";
+import type { SchedulerPort } from "./port.js";
+import type { ScheduleTemplate, ScheduledEvent, TimeSpan } from "./types.js";
+export declare class Scheduler<TPayload extends {
+    type: string;
+}> {
+    private readonly _port;
+    private readonly _changed;
+    constructor(port: SchedulerPort<TPayload>);
+    get changed(): IEventBroadcast<void>;
+    list(windowStart: number, windowEnd: number): Promise<ScheduledEvent<TPayload>[]>;
+    next(templateId: string, after: number): Promise<ScheduledEvent<TPayload> | null>;
+    nextDue(after: number, limit?: number): Promise<ScheduledEvent<TPayload>[]>;
+    add(template: ScheduleTemplate<TPayload>): Promise<void>;
+    update(delta: {
+        id: string;
+    } & Partial<Omit<ScheduleTemplate<TPayload>, "id">>): Promise<void>;
+    remove(id: string): Promise<void>;
+    reschedule(templateId: string, occurrenceKey: string, newStart: number, newTimeSpan?: TimeSpan, payloadOverride?: Partial<TPayload>): Promise<string>;
+    cancel(templateId: string, occurrenceKey: string): Promise<string>;
+    private _generateKeyed;
+    private _removeExistingAlteration;
+}

package/dist/cjs/scheduler.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+const state_1 = require("@j13b/state");
+const alterations_js_1 = require("./alterations.js");
+const anchored_js_1 = require("./generators/anchored.js");
+const days_of_month_js_1 = require("./generators/days_of_month.js");
+const days_of_week_js_1 = require("./generators/days_of_week.js");
+const days_of_year_js_1 = require("./generators/days_of_year.js");
+const instant_js_1 = require("./generators/instant.js");
+const local_date_time_js_1 = require("./generators/local_date_time.js");
+const months_of_year_js_1 = require("./generators/months_of_year.js");
+const weeks_of_month_js_1 = require("./generators/weeks_of_month.js");
+const yearly_js_1 = require("./generators/yearly.js");
+const occurrence_key_js_1 = require("./occurrence_key.js");
+const tz_js_1 = require("./tz.js");
+const validate_rule_js_1 = require("./validate_rule.js");
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Search horizon for next() / nextDue() before giving up. Five years covers
+// every realistic use; if you need longer, call list() with an explicit
+// window.
+const NEXT_SEARCH_HORIZON_MS = 5 * 365 * DAY_MS;
+class Scheduler {
+    _port;
+    // Fires after every successful write (add/update/remove/reschedule/cancel).
+    // The Dispatcher subscribes via .changed so a new event added during a
+    // sleep can interrupt the sleep and re-query nextDue().
+    _changed = new state_1.Event();
+    constructor(port) {
+        this._port = port;
+    }
+    get changed() {
+        return this._changed.broadcast;
+    }
+    // ─── Reads ──────────────────────────────────────────────────
+    // All occurrences whose [start, end) intersects [windowStart, windowEnd),
+    // sorted ascending by startTimestamp. Honors alterations.
+    async list(windowStart, windowEnd) {
+        if (windowEnd <= windowStart)
+            return [];
+        const [templates, alterations] = await Promise.all([
+            this._port.listTemplates(windowStart, windowEnd),
+            this._port.listAlterations(windowStart, windowEnd),
+        ]);
+        const out = [];
+        for (const tpl of templates) {
+            const keyed = this._generateKeyed(tpl, windowStart, windowEnd);
+            const events = (0, alterations_js_1.applyAlterations)(tpl.id, tpl.payload, keyed, alterations, tpl.timezone, windowStart, windowEnd);
+            out.push(...events);
+        }
+        out.sort((a, b) => a.startTimestamp - b.startTimestamp);
+        return out;
+    }
+    // Earliest occurrence of one template strictly after `after`. Returns null
+    // if no occurrence exists within NEXT_SEARCH_HORIZON_MS.
+    async next(templateId, after) {
+        const tpl = await this._port.getTemplate(templateId);
+        if (tpl == null)
+            return null;
+        // Expanding-window search. Doubles each iteration until horizon.
+        const horizonEnd = after + NEXT_SEARCH_HORIZON_MS;
+        let windowStart = after;
+        let windowSize = DAY_MS;
+        while (windowStart < horizonEnd) {
+            const windowEnd = Math.min(windowStart + windowSize, horizonEnd);
+            const alterations = await this._port.listAlterationsByTemplate(templateId);
+            const keyed = this._generateKeyed(tpl, windowStart, windowEnd);
+            const events = (0, alterations_js_1.applyAlterations)(tpl.id, tpl.payload, keyed, alterations, tpl.timezone, windowStart, windowEnd);
+            const firstAfter = events.find((e) => e.startTimestamp > after);
+            if (firstAfter != null)
+                return firstAfter;
+            windowStart = windowEnd;
+            windowSize = Math.min(windowSize * 2, 365 * DAY_MS);
+        }
+        return null;
+    }
+    // The next `limit` occurrences globally after `after`, sorted ascending.
+    // Defaults to 10. Searches in expanding windows like next().
+    async nextDue(after, limit = 10) {
+        if (limit <= 0)
+            return [];
+        const horizonEnd = after + NEXT_SEARCH_HORIZON_MS;
+        const out = [];
+        let windowStart = after;
+        let windowSize = DAY_MS;
+        while (windowStart < horizonEnd && out.length < limit) {
+            const windowEnd = Math.min(windowStart + windowSize, horizonEnd);
+            const events = await this.list(windowStart, windowEnd);
+            for (const e of events) {
+                if (e.startTimestamp > after) {
+                    out.push(e);
+                    if (out.length >= limit)
+                        break;
+                }
+            }
+            windowStart = windowEnd;
+            windowSize = Math.min(windowSize * 2, 365 * DAY_MS);
+        }
+        return out;
+    }
+    // ─── Writes ─────────────────────────────────────────────────
+    async add(template) {
+        (0, validate_rule_js_1.validateRule)(template.rule);
+        _validateTimezone(template.timezone);
+        _validateDisambiguation(template.disambiguation);
+        const normalized = {
+            ...template,
+            rule: _normalizeRule(template.rule),
+        };
+        await this._port.addTemplate(normalized);
+        this._changed.notify();
+    }
+    // Partial update. Caller supplies any subset of the template fields plus
+    // the id. If the rule changes (kind or any field), all alterations for
+    // this template are wiped — same policy as activity-board, made explicit.
+    async update(delta) {
+        const existing = await this._port.getTemplate(delta.id);
+        if (existing == null)
+            throw new Error(`No template with id ${delta.id}`);
+        const merged = {
+            ...existing,
+            ...delta,
+            id: delta.id,
+        };
+        (0, validate_rule_js_1.validateRule)(merged.rule);
+        _validateTimezone(merged.timezone);
+        _validateDisambiguation(merged.disambiguation);
+        const updated = {
+            ...merged,
+            rule: _normalizeRule(merged.rule),
+        };
+        const ruleChanged = !_rulesEqual(existing.rule, updated.rule);
+        await this._port.updateTemplate(updated);
+        if (ruleChanged) {
+            await this._port.removeAlterationsForTemplate(updated.id);
+        }
+        this._changed.notify();
+    }
+    async remove(id) {
+        await this._port.removeAlterationsForTemplate(id);
+        await this._port.removeTemplate(id);
+        this._changed.notify();
+    }
+    // Adds or replaces a reschedule alteration for the given occurrence.
+    // Caller is responsible for providing a valid occurrenceKey (typically
+    // taken from a prior list() result). If `newTimeSpan` is omitted, the
+    // rescheduled occurrence inherits the original's UTC duration (i.e. moves
+    // in time but keeps the same length).
+    async reschedule(templateId, occurrenceKey, newStart, newTimeSpan, payloadOverride) {
+        if (newTimeSpan != null)
+            (0, validate_rule_js_1.validateTimeSpan)(newTimeSpan);
+        const id = `alt-${templateId}-${occurrenceKey}-${Date.now()}`;
+        await this._removeExistingAlteration(templateId, occurrenceKey);
+        const alt = {
+            id,
+            templateId,
+            occurrenceKey,
+            kind: "reschedule",
+            startTimestamp: newStart,
+            timeSpan: newTimeSpan,
+            payloadOverride,
+        };
+        await this._port.addAlteration(alt);
+        this._changed.notify();
+        return id;
+    }
+    async cancel(templateId, occurrenceKey) {
+        const id = `alt-${templateId}-${occurrenceKey}-${Date.now()}`;
+        await this._removeExistingAlteration(templateId, occurrenceKey);
+        const alt = {
+            id,
+            templateId,
+            occurrenceKey,
+            kind: "cancel",
+        };
+        await this._port.addAlteration(alt);
+        this._changed.notify();
+        return id;
+    }
+    // ─── Internals ──────────────────────────────────────────────
+    _generateKeyed(tpl, windowStart, windowEnd) {
+        const tz = tpl.timezone;
+        const dis = tpl.disambiguation ?? "compatible";
+        let occurrences;
+        switch (tpl.rule.kind) {
+            case "instant":
+                // Absolute start — no wall-clock ambiguity, disambiguation N/A.
+                occurrences = (0, instant_js_1.generateInstant)(tpl.rule, tz, windowStart, windowEnd);
+                break;
+            case "localDateTime":
+                occurrences = (0, local_date_time_js_1.generateLocalDateTime)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            case "anchored":
+                // Absolute stepping — no wall-clock ambiguity, disambiguation N/A.
+                occurrences = (0, anchored_js_1.generateAnchored)(tpl.rule, tz, windowStart, windowEnd);
+                break;
+            case "daysOfWeek":
+                occurrences = (0, days_of_week_js_1.generateDaysOfWeek)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            case "weeksOfMonth":
+                occurrences = (0, weeks_of_month_js_1.generateWeeksOfMonth)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            case "monthsOfYear":
+                occurrences = (0, months_of_year_js_1.generateMonthsOfYear)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            case "yearly":
+                occurrences = (0, yearly_js_1.generateYearly)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            case "daysOfMonth":
+                occurrences = (0, days_of_month_js_1.generateDaysOfMonth)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            case "daysOfYear":
+                occurrences = (0, days_of_year_js_1.generateDaysOfYear)(tpl.rule, tz, windowStart, windowEnd, dis);
+                break;
+            default: {
+                // Exhaustiveness guard — adding a new kind without handling it here
+                // is a compile error.
+                const _exhaustive = tpl.rule;
+                throw new Error(`Unknown rule kind: ${JSON.stringify(_exhaustive)}`);
+            }
+        }
+        return (0, occurrence_key_js_1.assignOccurrenceKeys)(occurrences, tz);
+    }
+    async _removeExistingAlteration(templateId, occurrenceKey) {
+        const existing = await this._port.listAlterationsByTemplate(templateId);
+        for (const alt of existing) {
+            if (alt.occurrenceKey === occurrenceKey) {
+                await this._port.removeAlteration(alt.id);
+            }
+        }
+    }
+}
+exports.Scheduler = Scheduler;
+// ─── Validation ───────────────────────────────────────────────
+// Returns a copy of `rule` with timeSpan defaulted when omitted, so
+// generators don't have to handle undefined repeatedly.
+function _normalizeRule(rule) {
+    if (rule.timeSpan != null)
+        return rule;
+    return { ...rule, timeSpan: { type: "duration", ms: 1 } };
+}
+function _validateTimezone(tz) {
+    if (typeof tz !== "string" || tz.length === 0) {
+        throw new Error("ScheduleTemplate.timezone is required (use 'UTC' for zone-free scheduling)");
+    }
+    if (!(0, tz_js_1.isValidTimeZone)(tz)) {
+        throw new Error(`Unknown timezone '${tz}' (expected an IANA zone name or 'UTC')`);
+    }
+}
+const _DISAMBIGUATIONS = [
+    "compatible",
+    "earlier",
+    "later",
+    "reject",
+    "skip",
+];
+function _validateDisambiguation(d) {
+    if (d == null)
+        return;
+    if (!_DISAMBIGUATIONS.includes(d)) {
+        throw new Error(`Unknown disambiguation '${d}' (expected one of ${_DISAMBIGUATIONS.join(", ")})`);
+    }
+}
+function _rulesEqual(a, b) {
+    return JSON.stringify(_canonicalize(a)) === JSON.stringify(_canonicalize(b));
+}
+function _canonicalize(rule) {
+    // Sort + dedup any array selectors so reorderings or duplicates don't
+    // false-flag a rule change (which would wipe alterations).
+    if (rule.kind === "daysOfWeek") {
+        return { ...rule, days: [...new Set(rule.days)].sort((a, b) => a - b) };
+    }
+    if (rule.kind === "weeksOfMonth") {
+        return {
+            ...rule,
+            days: [...new Set(rule.days)].sort((a, b) => a - b),
+            weeks: [...new Set(rule.weeks)].sort((a, b) => a - b),
+        };
+    }
+    if (rule.kind === "monthsOfYear") {
+        return {
+            ...rule,
+            months: [...new Set(rule.months)].sort((a, b) => a - b),
+            weeks: [...new Set(rule.weeks)].sort((a, b) => a - b),
+            days: [...new Set(rule.days)].sort((a, b) => a - b),
+        };
+    }
+    if (rule.kind === "daysOfMonth") {
+        return {
+            ...rule,
+            months: [...new Set(rule.months)].sort((a, b) => a - b),
+            daysOfMonth: [...new Set(rule.daysOfMonth)].sort((a, b) => a - b),
+        };
+    }
+    if (rule.kind === "daysOfYear") {
+        return {
+            ...rule,
+            daysOfYear: [...new Set(rule.daysOfYear)].sort((a, b) => a - b),
+        };
+    }
+    return rule;
+}

package/dist/cjs/types.d.ts

@@ -0,0 +1,149 @@
+export declare enum Day {
+    Sunday = 0,
+    Monday = 1,
+    Tuesday = 2,
+    Wednesday = 3,
+    Thursday = 4,
+    Friday = 5,
+    Saturday = 6
+}
+export declare enum Month {
+    January = 0,
+    February = 1,
+    March = 2,
+    April = 3,
+    May = 4,
+    June = 5,
+    July = 6,
+    August = 7,
+    September = 8,
+    October = 9,
+    November = 10,
+    December = 11
+}
+export type TimeSpan = {
+    type: "duration";
+    ms: number;
+} | {
+    type: "hourSpan";
+    hours: number;
+};
+export type RecurrenceRule = InstantRule | LocalDateTimeRule | AnchoredRule | DaysOfWeekRule | WeeksOfMonthRule | MonthsOfYearRule | YearlyRule | DaysOfMonthRule | DaysOfYearRule;
+export interface InstantRule {
+    kind: "instant";
+    startOn: number;
+    timeSpan?: TimeSpan;
+}
+export interface LocalDateTimeRule {
+    kind: "localDateTime";
+    year: number;
+    month: Month;
+    day: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+}
+export interface AnchoredRule {
+    kind: "anchored";
+    anchorDate: number;
+    intervalMs: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export interface DaysOfWeekRule {
+    kind: "daysOfWeek";
+    days: Day[];
+    weekInterval: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export interface WeeksOfMonthRule {
+    kind: "weeksOfMonth";
+    days: Day[];
+    weeks: number[];
+    monthInterval: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export interface MonthsOfYearRule {
+    kind: "monthsOfYear";
+    months: Month[];
+    weeks: number[];
+    days: Day[];
+    yearInterval: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export interface YearlyRule {
+    kind: "yearly";
+    month: Month;
+    day: number;
+    yearInterval: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export interface DaysOfMonthRule {
+    kind: "daysOfMonth";
+    months: Month[];
+    daysOfMonth: number[];
+    yearInterval: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export interface DaysOfYearRule {
+    kind: "daysOfYear";
+    daysOfYear: number[];
+    yearInterval: number;
+    timeOfDay: number;
+    timeSpan?: TimeSpan;
+    seriesStart: number;
+    seriesEnd: number | null;
+    count?: number | null;
+}
+export type Disambiguation = "compatible" | "earlier" | "later" | "reject" | "skip";
+export interface ScheduleTemplate<TPayload extends {
+    type: string;
+}> {
+    id: string;
+    rule: RecurrenceRule;
+    timezone: string;
+    disambiguation?: Disambiguation;
+    payload: TPayload;
+}
+export interface Alteration<TPayload extends {
+    type: string;
+}> {
+    id: string;
+    templateId: string;
+    occurrenceKey: string;
+    kind: "reschedule" | "cancel";
+    startTimestamp?: number;
+    timeSpan?: TimeSpan;
+    payloadOverride?: Partial<TPayload>;
+}
+export interface ScheduledEvent<TPayload extends {
+    type: string;
+}> {
+    templateId: string;
+    occurrenceKey: string;
+    startTimestamp: number;
+    endTimestamp: number;
+    payload: TPayload;
+    alterationId?: string;
+}

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;