@j13b/scheduler 0.0.0-stage → 0.1.0

package/src/generators/months_of_year.ts

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

package/src/generators/types.ts

@@ -0,0 +1,26 @@
+// Generators emit raw start/end pairs sorted ascending by startTimestamp.
+// Stable per-occurrence keys are assigned downstream (occurrence_key.ts) so
+// keys can be derived consistently across rule kinds.
+export interface Occurrence {
+  startTimestamp: number;
+  endTimestamp: number;
+}
+
+// Hard ceiling per generate() call. A misconfigured rule (e.g. 1ms anchored
+// interval over a year-long window) would otherwise produce billions of
+// occurrences; we'd rather throw a clear error than blow heap.
+export const MAX_OCCURRENCES_PER_GENERATE = 10_000;
+
+export class TooManyOccurrencesError extends Error {
+  constructor(kind: string) {
+    super(
+      `Generator '${kind}' would emit more than ${MAX_OCCURRENCES_PER_GENERATE} occurrences for the requested window. Narrow the window, increase the interval, or set 'count' on the rule.`
+    );
+    this.name = "TooManyOccurrencesError";
+  }
+}
+
+// Half-open intersection: [startA, endA) overlaps [startB, endB)?
+export function intersects(startA: number, endA: number, startB: number, endB: number): boolean {
+  return Math.max(startA, startB) < Math.min(endA, endB);
+}

package/src/generators/weeks_of_month.ts

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

package/src/generators/yearly.ts

@@ -0,0 +1,73 @@
+import type { Disambiguation, YearlyRule } from "../types.js";
+import {
+  computeSpanEnd,
+  isNonexistentWallTime,
+  monthLength,
+  utcToWallParts,
+  wallTimeToUtc,
+} from "../tz.js";
+import {
+  MAX_OCCURRENCES_PER_GENERATE,
+  type Occurrence,
+  TooManyOccurrencesError,
+  intersects,
+} from "./types.js";
+
+// Simple yearly recurrence: a single month + day. Day clamps to month
+// length (Feb 29 → Feb 28 in non-leap years, Apr 31 → Apr 30, etc.).
+export function generateYearly(
+  rule: YearlyRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number,
+  disambiguation: Disambiguation = "compatible"
+): Occurrence[] {
+  if (rule.yearInterval <= 0) {
+    throw new Error(`YearlyRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+  }
+  if (rule.month < 0 || rule.month > 11) {
+    throw new Error(`YearlyRule.month must be in 0..11 (got ${rule.month})`);
+  }
+  if (rule.day < 1 || rule.day > 31) {
+    throw new Error(`YearlyRule.day must be in 1..31 (got ${rule.day})`);
+  }
+  if (rule.count != null && rule.count < 0) {
+    throw new Error(`YearlyRule.count must be >= 0 (got ${rule.count})`);
+  }
+
+  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+  const effectiveEnd = Math.min(windowEnd, seriesEnd);
+  if (rule.seriesStart >= effectiveEnd) return [];
+
+  const startYear = utcToWallParts(rule.seriesStart, tz).year;
+  const endYear = utcToWallParts(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;
+
+  const out: Occurrence[] = [];
+  let count = 0;
+
+  for (let year = startYear; year <= endYear; year += rule.yearInterval) {
+    const day = Math.min(rule.day, monthLength(year, rule.month));
+    if (
+      disambiguation === "skip" &&
+      isNonexistentWallTime(year, rule.month, day, rule.timeOfDay, tz)
+    ) {
+      continue;
+    }
+    const occStart = wallTimeToUtc(year, rule.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) break;
+    count++;
+
+    if (intersects(occStart, occEnd, windowStart, windowEnd)) {
+      out.push({ startTimestamp: occStart, endTimestamp: occEnd });
+      if (out.length > MAX_OCCURRENCES_PER_GENERATE) {
+        throw new TooManyOccurrencesError("yearly");
+      }
+    }
+  }
+  return out;
+}

package/src/in_memory_port.ts

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

package/src/index.ts

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

package/src/occurrence_key.ts

@@ -0,0 +1,42 @@
+import type { Occurrence } from "./generators/types.js";
+import { utcToWallParts } from "./tz.js";
+
+// A key identifies a specific occurrence within a template's series. It must
+// be:
+//   - Stable across small rule edits (e.g. tweaking timeOfDay)
+//   - Unique within a single generate() call's output for one template
+//
+// Format: `YYYY-MM-DD` (in the template's tz), with `#N` suffix when multiple
+// occurrences land on the same calendar day. Index is 0-based by emission
+// order within that day.
+//
+// Trade-off: changing timeOfDay across the date boundary moves an event to
+// a different day, which orphans alterations on it. We accept that as the
+// cost of human-readable, edit-tolerant keys. Same goes for timezone changes.
+
+export interface KeyedOccurrence extends Occurrence {
+  occurrenceKey: string;
+}
+
+export function assignOccurrenceKeys(
+  occurrences: readonly Occurrence[],
+  tz: string | undefined
+): KeyedOccurrence[] {
+  const counts = new Map<string, number>();
+  return occurrences.map((occ) => {
+    const w = utcToWallParts(occ.startTimestamp, tz);
+    const date = `${_pad4(w.year)}-${_pad2(w.month + 1)}-${_pad2(w.day)}`;
+    const idx = counts.get(date) ?? 0;
+    counts.set(date, idx + 1);
+    const occurrenceKey = idx === 0 ? date : `${date}#${idx}`;
+    return { ...occ, occurrenceKey };
+  });
+}
+
+function _pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+function _pad4(n: number): string {
+  return n < 10 ? `000${n}` : n < 100 ? `00${n}` : n < 1000 ? `0${n}` : String(n);
+}

package/src/port.ts

@@ -0,0 +1,31 @@
+import type { Alteration, ScheduleTemplate } from "./types.js";
+
+// Storage adapter for the Scheduler. The Scheduler is pure logic over this
+// port; consumers implement it against whatever backing store they want
+// (in-memory, SQL JSON column, KV, etc.).
+//
+// Range queries (start/end) MUST return any template/alteration that could
+// produce or affect an occurrence in the window — including templates whose
+// seriesStart is before `start` but whose recurrence still emits inside it.
+// The simplest correct implementation returns all templates and lets the
+// scheduler filter. Smarter ports may pre-filter on seriesStart/seriesEnd.
+export interface SchedulerPort<TPayload extends { type: string }> {
+  // Templates whose recurrence may emit occurrences intersecting [start, end).
+  listTemplates(start: number, end: number): Promise<ScheduleTemplate<TPayload>[]>;
+  getTemplate(id: string): Promise<ScheduleTemplate<TPayload> | null>;
+  addTemplate(template: ScheduleTemplate<TPayload>): Promise<void>;
+  // Replaces the entire stored template. The Scheduler validates before calling.
+  updateTemplate(template: ScheduleTemplate<TPayload>): Promise<void>;
+  removeTemplate(id: string): Promise<void>;
+
+  // Alterations affecting occurrences in [start, end).
+  listAlterations(start: number, end: number): Promise<Alteration<TPayload>[]>;
+  // All alterations for a template (used when wiping on rule changes).
+  listAlterationsByTemplate(templateId: string): Promise<Alteration<TPayload>[]>;
+  addAlteration(alteration: Alteration<TPayload>): Promise<void>;
+  removeAlteration(id: string): Promise<void>;
+  // Bulk delete used by the Scheduler when a template's rule changes
+  // (existing alterations are no longer meaningful — same policy as
+  // activity-board, just made explicit).
+  removeAlterationsForTemplate(templateId: string): Promise<void>;
+}