@j13b/scheduler 0.0.0-stage → 0.1.1

package/src/__tests__/tz.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "vitest";
+import { Day } from "../types.js";
+import {
+  addDaysInTz,
+  addMonthsInTz,
+  dayOfWeekInTz,
+  monthLength,
+  utcToWallParts,
+  wallTimeToUtc,
+} from "../tz.js";
+
+// Reference moments:
+//   2025-03-09 09:00 UTC = 2025-03-09 02:00 MST = 03:00 MDT (the gap)
+//   2025-11-02 08:00 UTC = 2025-11-02 02:00 MDT = 01:00 MST (the overlap)
+//   America/Denver: -07:00 in MDT, -06:00 in MST. Wait — opposite. MST is
+//   standard (-07), MDT is daylight (-06). Spring forward = MST→MDT (lose
+//   an hour). Fall back = MDT→MST (gain an hour).
+
+describe("tz — UTC pass-through", () => {
+  test("utcToWallParts treats UTC as itself", () => {
+    const w = utcToWallParts(Date.UTC(2026, 4, 11, 14, 30, 45, 250), "UTC");
+    expect(w).toEqual({
+      year: 2026,
+      month: 4,
+      day: 11,
+      hour: 14,
+      minute: 30,
+      second: 45,
+      ms: 250,
+      dayOfWeek: Day.Monday,
+    });
+  });
+
+  test("wallTimeToUtc in UTC = Date.UTC", () => {
+    const expected = Date.UTC(2026, 4, 11, 14, 30, 45, 250);
+    const msOfDay = 14 * 3_600_000 + 30 * 60_000 + 45 * 1000 + 250;
+    expect(wallTimeToUtc(2026, 4, 11, msOfDay, "UTC")).toBe(expected);
+  });
+});
+
+describe("tz — IANA round-trips", () => {
+  test("New York: 9am wall = 14:00 UTC in winter (EST)", () => {
+    const utc = wallTimeToUtc(2026, 0, 15, 9 * 3_600_000, "America/New_York");
+    expect(new Date(utc).toISOString()).toBe("2026-01-15T14:00:00.000Z");
+  });
+
+  test("New York: 9am wall = 13:00 UTC in summer (EDT)", () => {
+    const utc = wallTimeToUtc(2026, 6, 15, 9 * 3_600_000, "America/New_York");
+    expect(new Date(utc).toISOString()).toBe("2026-07-15T13:00:00.000Z");
+  });
+
+  test("Tokyo: 9am wall = 00:00 UTC year-round (no DST)", () => {
+    const winter = wallTimeToUtc(2026, 0, 15, 9 * 3_600_000, "Asia/Tokyo");
+    const summer = wallTimeToUtc(2026, 6, 15, 9 * 3_600_000, "Asia/Tokyo");
+    expect(new Date(winter).toISOString()).toBe("2026-01-15T00:00:00.000Z");
+    expect(new Date(summer).toISOString()).toBe("2026-07-15T00:00:00.000Z");
+  });
+
+  test("Round-trip: utcToWallParts → wallTimeToUtc preserves the instant", () => {
+    const original = Date.UTC(2025, 5, 15, 18, 42, 17);
+    const w = utcToWallParts(original, "Europe/London");
+    const msOfDay = w.hour * 3_600_000 + w.minute * 60_000 + w.second * 1000;
+    expect(wallTimeToUtc(w.year, w.month, w.day, msOfDay, "Europe/London")).toBe(original);
+  });
+});
+
+describe("tz — DST boundaries", () => {
+  // Spring forward: 2025-03-09, America/Denver. Clock jumps 02:00 MST → 03:00 MDT.
+  // 02:30 wall is "non-existent". We resolve to the EARLIER instant — i.e.
+  // treat the wall fields with the pre-transition (MST, -07) offset. So
+  // 02:30 → 09:30 UTC (since pre-transition Denver is UTC-7).
+  // Wait: actually pre-transition offset is MST (-7), so 02:30 MST → 09:30 UTC.
+  // The IMPLEMENTATION returns 08:30 UTC, which corresponds to 02:30 in the
+  // pre-jump timeline interpreted as if it were ALREADY MDT (-6). Hmm.
+  //
+  // What's actually happening: the algorithm reads the offset at the
+  // post-correction guess (which lands AFTER the jump), so it uses MDT (-6).
+  // 02:30 wall - (-6h) = 08:30 UTC. So we resolve to the EARLIER UTC instant
+  // by using the POST-transition (smaller magnitude) offset. This is the
+  // Luxon / date-fns-tz default for spring-forward.
+  // Default disambiguation is now "compatible": a spring-forward gap moves
+  // FORWARD to the later instant. 02:30 (nonexistent) → 09:30 UTC (i.e. the
+  // clock jumps to 03:30 MDT). "earlier" recovers the old 08:30 UTC behavior.
+  test("spring forward gap: default (compatible) resolves to the later instant", () => {
+    const utc = wallTimeToUtc(2025, 2, 9, 2 * 3_600_000 + 30 * 60_000, "America/Denver");
+    expect(new Date(utc).toISOString()).toBe("2025-03-09T09:30:00.000Z");
+  });
+
+  test("spring forward gap: disambiguation policies pick gap direction", () => {
+    const wall = 2 * 3_600_000 + 30 * 60_000;
+    const earlier = wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "earlier");
+    const later = wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "later");
+    const compatible = wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "compatible");
+    expect(new Date(earlier).toISOString()).toBe("2025-03-09T08:30:00.000Z");
+    expect(new Date(later).toISOString()).toBe("2025-03-09T09:30:00.000Z");
+    expect(compatible).toBe(later);
+    expect(() => wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "reject")).toThrow(/gap/);
+  });
+
+  // Fall back: 2025-11-02, America/Denver. Clock falls 02:00 MDT → 01:00 MST.
+  // 01:30 wall is ambiguous. We resolve to the EARLIER instant: 07:30 UTC
+  // (the first occurrence, while still on MDT), not 08:30 UTC.
+  test("fall back ambiguous wall time resolves to earlier instant (compatible default)", () => {
+    const utc = wallTimeToUtc(2025, 10, 2, 1 * 3_600_000 + 30 * 60_000, "America/Denver");
+    expect(new Date(utc).toISOString()).toBe("2025-11-02T07:30:00.000Z");
+  });
+
+  test("fall back overlap: disambiguation policies pick which occurrence", () => {
+    const wall = 1 * 3_600_000 + 30 * 60_000;
+    const earlier = wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "earlier");
+    const later = wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "later");
+    expect(new Date(earlier).toISOString()).toBe("2025-11-02T07:30:00.000Z");
+    expect(new Date(later).toISOString()).toBe("2025-11-02T08:30:00.000Z");
+    // "compatible" picks the earlier occurrence for an overlap.
+    expect(wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "compatible")).toBe(earlier);
+    expect(() => wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "reject")).toThrow(/overlap/);
+  });
+
+  // Same wall-clock time, two different UTCs across spring forward.
+  test("9am Denver wall is 16:00 UTC before, 15:00 UTC after spring forward", () => {
+    const before = wallTimeToUtc(2025, 2, 8, 9 * 3_600_000, "America/Denver"); // Sat
+    const after = wallTimeToUtc(2025, 2, 10, 9 * 3_600_000, "America/Denver"); // Mon
+    expect(new Date(before).toISOString()).toBe("2025-03-08T16:00:00.000Z");
+    expect(new Date(after).toISOString()).toBe("2025-03-10T15:00:00.000Z");
+  });
+});
+
+describe("tz — addDaysInTz", () => {
+  test("adding 1 day across spring forward keeps wall time stable", () => {
+    // 2025-03-08 09:00 Denver
+    const start = wallTimeToUtc(2025, 2, 8, 9 * 3_600_000, "America/Denver");
+    const next = addDaysInTz(start, 1, "America/Denver");
+    const w = utcToWallParts(next, "America/Denver");
+    expect({ year: w.year, month: w.month, day: w.day, hour: w.hour }).toEqual({
+      year: 2025,
+      month: 2,
+      day: 9,
+      hour: 9,
+    });
+    // The actual elapsed UTC ms is 23 hours, not 24.
+    expect(next - start).toBe(23 * 3_600_000);
+  });
+
+  test("adding 1 day across fall back keeps wall time stable", () => {
+    const start = wallTimeToUtc(2025, 10, 1, 9 * 3_600_000, "America/Denver");
+    const next = addDaysInTz(start, 1, "America/Denver");
+    const w = utcToWallParts(next, "America/Denver");
+    expect({ year: w.year, month: w.month, day: w.day, hour: w.hour }).toEqual({
+      year: 2025,
+      month: 10,
+      day: 2,
+      hour: 9,
+    });
+    // 25-hour day.
+    expect(next - start).toBe(25 * 3_600_000);
+  });
+
+  test("adding negative days works", () => {
+    const start = wallTimeToUtc(2026, 4, 11, 12 * 3_600_000, "UTC");
+    const before = addDaysInTz(start, -10, "UTC");
+    expect(new Date(before).toISOString()).toBe("2026-05-01T12:00:00.000Z");
+  });
+});
+
+describe("tz — addMonthsInTz", () => {
+  test("adds months in wall sense", () => {
+    const start = wallTimeToUtc(2026, 0, 31, 12 * 3_600_000, "UTC"); // Jan 31
+    const next = addMonthsInTz(start, 1, "UTC"); // Feb 31 → Mar 3 (JS rolls over)
+    const w = utcToWallParts(next, "UTC");
+    expect({ year: w.year, month: w.month, day: w.day }).toEqual({
+      year: 2026,
+      month: 2, // March (JS rolls Feb 31 → Mar 3)
+      day: 3,
+    });
+  });
+});
+
+describe("tz — dayOfWeekInTz", () => {
+  test("crosses date boundary correctly in non-UTC tz", () => {
+    // 2026-05-11 23:00 UTC = 2026-05-11 16:00 PDT (Monday in LA, Monday in UTC)
+    const utc = Date.UTC(2026, 4, 11, 23, 0, 0);
+    expect(dayOfWeekInTz(utc, "UTC")).toBe(Day.Monday);
+    expect(dayOfWeekInTz(utc, "America/Los_Angeles")).toBe(Day.Monday);
+  });
+
+  test("date boundary case: 04:00 UTC Tuesday is still Monday in LA", () => {
+    // 2026-05-12 04:00 UTC = 2026-05-11 21:00 PDT
+    const utc = Date.UTC(2026, 4, 12, 4, 0, 0);
+    expect(dayOfWeekInTz(utc, "UTC")).toBe(Day.Tuesday);
+    expect(dayOfWeekInTz(utc, "America/Los_Angeles")).toBe(Day.Monday);
+  });
+});
+
+describe("tz — monthLength", () => {
+  test("returns civil month length", () => {
+    expect(monthLength(2024, 1)).toBe(29); // Feb 2024 (leap)
+    expect(monthLength(2025, 1)).toBe(28); // Feb 2025
+    expect(monthLength(2026, 0)).toBe(31); // Jan
+    expect(monthLength(2026, 3)).toBe(30); // Apr
+  });
+});

package/src/__tests__/validate_rule.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "vitest";
+import { InMemorySchedulerPort } from "../in_memory_port.js";
+import { Scheduler } from "../scheduler.js";
+import type { RecurrenceRule } from "../types.js";
+import { RULE_KINDS, validateRule, validateTimeSpan } from "../validate_rule.js";
+
+const START = Date.UTC(2026, 0, 1);
+const SEVEN_AM = 7 * 60 * 60 * 1000;
+
+// A rule as it arrives from JSON: anything at all.
+const loose = (rule: unknown): RecurrenceRule => rule as RecurrenceRule;
+
+const VALID: RecurrenceRule[] = [
+  { kind: "instant", startOn: START },
+  { kind: "localDateTime", year: 2026, month: 0, day: 1, timeOfDay: SEVEN_AM },
+  { kind: "anchored", anchorDate: START, intervalMs: 1000, seriesStart: START, seriesEnd: null },
+  {
+    kind: "daysOfWeek",
+    days: [1],
+    weekInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+  {
+    kind: "weeksOfMonth",
+    days: [0],
+    weeks: [1, 3],
+    monthInterval: 1,
+    timeOfDay: SEVEN_AM,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+  {
+    kind: "monthsOfYear",
+    months: [10],
+    weeks: [4],
+    days: [4],
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+    count: 3,
+  },
+  {
+    kind: "yearly",
+    month: 6,
+    day: 4,
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+  {
+    kind: "daysOfMonth",
+    months: [0, 1],
+    daysOfMonth: [1, 15],
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: START + 1,
+    timeSpan: { type: "duration", ms: 60_000 },
+  },
+  {
+    kind: "daysOfYear",
+    daysOfYear: [1, 366],
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+];
+
+describe("validateRule accepts", () => {
+  test.each(VALID.map((r) => [r.kind, r] as const))("a whole %s rule", (_kind, rule) => {
+    expect(() => validateRule(rule)).not.toThrow();
+  });
+
+  test("every kind is covered here", () => {
+    expect(VALID.map((r) => r.kind).sort()).toEqual([...RULE_KINDS].sort());
+  });
+});
+
+// The rules an LLM sent for "the 1st and 3rd Sunday at 7am". Before, each one
+// crashed inside the scheduler ("Cannot read properties of undefined", "Invalid
+// time value"); now each names what is wrong.
+describe("validateRule names the field that is wrong", () => {
+  test("a field the kind does not have", () => {
+    expect(() =>
+      validateRule(loose({ kind: "weeksOfMonth", weeks: [1, 3], weekdays: [0] }))
+    ).toThrow(
+      'WeeksOfMonthRule has no field "weekdays" (its fields are: days, weeks, monthInterval'
+    );
+  });
+
+  test("a required field that is missing, with the form it expects", () => {
+    expect(() => validateRule(loose({ kind: "weeksOfMonth", weeks: [1, 3], days: [0] }))).toThrow(
+      "WeeksOfMonthRule.monthInterval is required: a whole number >= 1 (1 = every month)"
+    );
+    expect(() =>
+      validateRule(loose({ kind: "weeksOfMonth", weeks: [1, 3], days: [0], monthInterval: 1 }))
+    ).toThrow("WeeksOfMonthRule.timeOfDay is required: ms after local midnight");
+    expect(() =>
+      validateRule(
+        loose({
+          kind: "weeksOfMonth",
+          weeks: [1, 3],
+          days: [0],
+          monthInterval: 1,
+          timeOfDay: SEVEN_AM,
+        })
+      )
+    ).toThrow("WeeksOfMonthRule.seriesStart is required: a UTC timestamp in ms");
+    expect(() =>
+      validateRule(
+        loose({
+          kind: "weeksOfMonth",
+          weeks: [1, 3],
+          days: [0],
+          monthInterval: 1,
+          timeOfDay: SEVEN_AM,
+          seriesStart: START,
+        })
+      )
+    ).toThrow("WeeksOfMonthRule.seriesEnd is required: a UTC timestamp in ms or null (no end)");
+  });
+
+  test("a wrong type or value", () => {
+    const base = VALID[4] as unknown as Record<string, unknown>;
+
+    expect(() => validateRule(loose({ ...base, days: [] }))).toThrow(
+      "WeeksOfMonthRule.days must be a non-empty array"
+    );
+    expect(() => validateRule(loose({ ...base, days: 0 }))).toThrow(
+      "WeeksOfMonthRule.days must be a non-empty array"
+    );
+    expect(() => validateRule(loose({ ...base, days: [7] }))).toThrow("7 is out of range");
+    expect(() => validateRule(loose({ ...base, weeks: [0] }))).toThrow("0 is out of range");
+    expect(() => validateRule(loose({ ...base, timeOfDay: "07:00" }))).toThrow(
+      "WeeksOfMonthRule.timeOfDay must be ms after local midnight"
+    );
+    expect(() => validateRule(loose({ ...base, seriesStart: "2026-01-01" }))).toThrow(
+      "seriesStart must be a UTC timestamp"
+    );
+    expect(() => validateRule(loose({ ...base, count: -1 }))).toThrow(
+      "count must be a whole number >= 0 or null"
+    );
+    expect(() => validateRule(loose({ ...base, seriesEnd: START }))).toThrow(
+      "seriesEnd must be > seriesStart"
+    );
+  });
+
+  test("an unknown kind, or no rule at all", () => {
+    expect(() => validateRule(loose({ kind: "monthly" }))).toThrow(
+      'Unknown rule kind "monthly" (expected one of instant,'
+    );
+    expect(() => validateRule(loose(null))).toThrow('A rule must be an object with a "kind"');
+  });
+});
+
+describe("validateTimeSpan", () => {
+  test("accepts nothing, a duration, or an hour span", () => {
+    expect(() => validateTimeSpan(undefined)).not.toThrow();
+    expect(() => validateTimeSpan({ type: "duration", ms: 1 })).not.toThrow();
+    expect(() => validateTimeSpan({ type: "hourSpan", hours: 1.5 })).not.toThrow();
+  });
+
+  test("rejects anything else with the forms it takes", () => {
+    expect(() => validateTimeSpan({ ms: 5 })).toThrow('timeSpan must be { "type": "duration"');
+    expect(() => validateTimeSpan({ type: "duration", ms: 0 })).toThrow("timeSpan.ms must be >= 1");
+  });
+});
+
+describe("the scheduler refuses a malformed rule before storing it", () => {
+  test("add throws the field message and stores nothing", async () => {
+    const port = new InMemorySchedulerPort<{ type: "event" }>();
+    const scheduler = new Scheduler(port);
+
+    await expect(
+      scheduler.add({
+        id: "t1",
+        rule: loose({ kind: "weeksOfMonth", weeks: [1, 3], weekdays: [0] }),
+        timezone: "UTC",
+        payload: { type: "event" },
+      })
+    ).rejects.toThrow('has no field "weekdays"');
+
+    expect(await port.getTemplate("t1")).toBeNull();
+  });
+});

package/src/__tests__/weeks_of_month.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from "vitest";
+import { generateWeeksOfMonth } from "../generators/weeks_of_month.js";
+import { Day, type WeeksOfMonthRule } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateWeeksOfMonth", () => {
+  test("2nd Tuesday of every month for a quarter", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Tuesday],
+      weeks: [2],
+      monthInterval: 1,
+      timeOfDay: 14 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 3, 1));
+    // 2nd Tuesdays: Jan 13, Feb 10, Mar 10
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-13T14:00:00.000Z",
+      "2026-02-10T14:00:00.000Z",
+      "2026-03-10T14:00:00.000Z",
+    ]);
+  });
+
+  test("last Friday of every month", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Friday],
+      weeks: [-1],
+      monthInterval: 1,
+      timeOfDay: 17 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 3, 1));
+    // Last Fridays: Jan 30, Feb 27, Mar 27
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-30T17:00:00.000Z",
+      "2026-02-27T17:00:00.000Z",
+      "2026-03-27T17:00:00.000Z",
+    ]);
+  });
+
+  test("5th Friday: emits only in months that have one", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Friday],
+      weeks: [5],
+      monthInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    // 2026: months with a 5th Friday are Jan (30), May (29), Jul (31), Oct (30).
+    // Wait — let me recompute: 5th Friday means the month has 5 Fridays.
+    // Jan 2026 Fridays: 2,9,16,23,30 → 5 Fridays, 5th = 30
+    // May 2026 Fridays: 1,8,15,22,29 → 5 Fridays, 5th = 29
+    // Jul 2026 Fridays: 3,10,17,24,31 → 5 Fridays, 5th = 31
+    // Oct 2026 Fridays: 2,9,16,23,30 → 5 Fridays, 5th = 30
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-30T00:00:00.000Z",
+      "2026-05-29T00:00:00.000Z",
+      "2026-07-31T00:00:00.000Z",
+      "2026-10-30T00:00:00.000Z",
+    ]);
+  });
+
+  test("every other month: skips months correctly", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Wednesday],
+      weeks: [1],
+      monthInterval: 2,
+      timeOfDay: 12 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 6, 1));
+    // 1st Wed of Jan/Mar/May 2026 = Jan 7, Mar 4, May 6
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-07T12:00:00.000Z",
+      "2026-03-04T12:00:00.000Z",
+      "2026-05-06T12:00:00.000Z",
+    ]);
+  });
+
+  test("throws on week = 0", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [0],
+      monthInterval: 1,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateWeeksOfMonth(rule, "UTC", 0, 1000)).toThrow(/week/);
+  });
+
+  test("throws on monthInterval = 0", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [1],
+      monthInterval: 0,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateWeeksOfMonth(rule, "UTC", 0, 1000)).toThrow(/monthInterval/);
+  });
+
+  test("first AND last week: Mon/Wed/Fri on weeks [1, -1] of every month", () => {
+    // The user's original use case.
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday, Day.Wednesday, Day.Friday],
+      weeks: [1, -1],
+      monthInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 1, 1));
+    // Jan 2026 starts Thursday. Days of week:
+    //   Thu Jan 1, Fri Jan 2 (1st Fri), Sat Jan 3, Sun Jan 4,
+    //   Mon Jan 5 (1st Mon), Tue Jan 6, Wed Jan 7 (1st Wed), ...
+    // Last week of Jan 2026:
+    //   Mon Jan 26 (last Mon), Wed Jan 28 (last Wed), Fri Jan 30 (last Fri).
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-02T09:00:00.000Z", // 1st Fri
+      "2026-01-05T09:00:00.000Z", // 1st Mon
+      "2026-01-07T09:00:00.000Z", // 1st Wed
+      "2026-01-26T09:00:00.000Z", // last Mon
+      "2026-01-28T09:00:00.000Z", // last Wed
+      "2026-01-30T09:00:00.000Z", // last Fri
+    ]);
+  });
+
+  test("multiple positive weeks: 1st, 3rd, 5th Tuesday", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Tuesday],
+      weeks: [1, 3, 5],
+      monthInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 5, 1),
+      seriesEnd: null,
+    };
+    // June 2026 Tuesdays: 2, 9, 16, 23, 30 → 1st=2, 3rd=16, 5th=30
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 5, 1), Date.UTC(2026, 6, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-06-02T00:00:00.000Z",
+      "2026-06-16T00:00:00.000Z",
+      "2026-06-30T00:00:00.000Z",
+    ]);
+  });
+
+  test("duplicate weeks are deduped (no double-emit)", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [1, 1, 1],
+      monthInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 1, 1));
+    expect(out).toHaveLength(1); // 1st Monday of Jan 2026 = Jan 5
+  });
+
+  test("throws on empty weeks", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [],
+      monthInterval: 1,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateWeeksOfMonth(rule, "UTC", 0, 1000)).toThrow(/weeks/);
+  });
+});

package/src/__tests__/yearly.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import { generateYearly } from "../generators/yearly.js";
+import { Month, type YearlyRule } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateYearly", () => {
+  test("every June 11", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.June,
+      day: 11,
+      yearInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-06-11T09:00:00.000Z",
+      "2025-06-11T09:00:00.000Z",
+      "2026-06-11T09:00:00.000Z",
+    ]);
+  });
+
+  test("every other Jan 1", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.January,
+      day: 1,
+      yearInterval: 2,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2030, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-01-01T00:00:00.000Z",
+      "2026-01-01T00:00:00.000Z",
+      "2028-01-01T00:00:00.000Z",
+    ]);
+  });
+
+  test("Feb 29 falls back to Feb 28 in non-leap years", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.February,
+      day: 29,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-02-29T00:00:00.000Z", // leap
+      "2025-02-28T00:00:00.000Z", // fallback
+      "2026-02-28T00:00:00.000Z", // fallback
+    ]);
+  });
+
+  test("count caps emissions", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.July,
+      day: 4,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+      count: 2,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2030, 0, 1));
+    expect(out).toHaveLength(2);
+  });
+
+  test("throws on month out of range", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: 12 as Month,
+      day: 1,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateYearly(rule, "UTC", 0, 1000)).toThrow(/month/);
+  });
+
+  test("throws on day < 1 or > 31", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.January,
+      day: 32,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateYearly(rule, "UTC", 0, 1000)).toThrow(/day/);
+  });
+});