@j13b/scheduler 0.0.0-stage → 0.1.0

package/src/__tests__/days_of_month.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "vitest";
+import { generateDaysOfMonth } from "../generators/days_of_month.js";
+import { type DaysOfMonthRule, Month } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateDaysOfMonth", () => {
+  test("15th of Jan and Mar, every other year", () => {
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [Month.January, Month.March],
+      daysOfMonth: [15],
+      yearInterval: 2,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfMonth(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2029, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-01-15T09:00:00.000Z",
+      "2024-03-15T09:00:00.000Z",
+      "2026-01-15T09:00:00.000Z",
+      "2026-03-15T09:00:00.000Z",
+      "2028-01-15T09:00:00.000Z",
+      "2028-03-15T09:00:00.000Z",
+    ]);
+  });
+
+  test("payroll: 1st and 15th of every month", () => {
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [
+        Month.January,
+        Month.February,
+        Month.March,
+        Month.April,
+        Month.May,
+        Month.June,
+        Month.July,
+        Month.August,
+        Month.September,
+        Month.October,
+        Month.November,
+        Month.December,
+      ],
+      daysOfMonth: [1, 15],
+      yearInterval: 1,
+      timeOfDay: 6 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out).toHaveLength(24); // 12 months × 2 days
+    expect(new Date(out[0].startTimestamp).toISOString()).toBe("2026-01-01T06:00:00.000Z");
+    expect(new Date(out[1].startTimestamp).toISOString()).toBe("2026-01-15T06:00:00.000Z");
+    expect(new Date(out[23].startTimestamp).toISOString()).toBe("2026-12-15T06:00:00.000Z");
+  });
+
+  test("quarterly tax dates", () => {
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [Month.January, Month.April, Month.July, Month.September],
+      daysOfMonth: [15],
+      yearInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-15T09:00:00.000Z",
+      "2026-04-15T09:00:00.000Z",
+      "2026-07-15T09:00:00.000Z",
+      "2026-09-15T09:00:00.000Z",
+    ]);
+  });
+
+  test("day 31 clamps to last day of shorter months", () => {
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [Month.January, Month.April],
+      daysOfMonth: [31],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-31T00:00:00.000Z", // Jan has 31
+      "2026-04-30T00:00:00.000Z", // Apr clamps to 30
+    ]);
+  });
+
+  test("day 30 + day 31 in April: dedup after clamp", () => {
+    // Both clamp to Apr 30 — should only emit once.
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [Month.April],
+      daysOfMonth: [30, 31],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out).toHaveLength(1);
+    expect(new Date(out[0].startTimestamp).toISOString()).toBe("2026-04-30T00:00:00.000Z");
+  });
+
+  test("count caps emissions across months × days", () => {
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [Month.January, Month.July],
+      daysOfMonth: [1, 15],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+      count: 3,
+    };
+    const out = generateDaysOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out).toHaveLength(3);
+  });
+
+  test("throws on empty months / daysOfMonth", () => {
+    const base = {
+      kind: "daysOfMonth" as const,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR } as const,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() =>
+      generateDaysOfMonth({ ...base, months: [], daysOfMonth: [1] }, "UTC", 0, 1000)
+    ).toThrow(/months/);
+    expect(() =>
+      generateDaysOfMonth({ ...base, months: [Month.January], daysOfMonth: [] }, "UTC", 0, 1000)
+    ).toThrow(/daysOfMonth/);
+  });
+
+  test("throws on day out of range", () => {
+    const rule: DaysOfMonthRule = {
+      kind: "daysOfMonth",
+      months: [Month.January],
+      daysOfMonth: [32],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateDaysOfMonth(rule, "UTC", 0, 1000)).toThrow(/daysOfMonth/);
+  });
+});

package/src/__tests__/days_of_week.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "vitest";
+import { generateDaysOfWeek } from "../generators/days_of_week.js";
+import { Day, type DaysOfWeekRule } from "../types.js";
+import { utcToWallParts } from "../tz.js";
+
+const HOUR = 3_600_000;
+
+describe("generateDaysOfWeek", () => {
+  test("Mon/Wed/Fri at 9am UTC over a week", () => {
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [Day.Monday, Day.Wednesday, Day.Friday],
+      weekInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 4, 4), // Mon May 4 2026
+      seriesEnd: null,
+    };
+    const out = generateDaysOfWeek(rule, "UTC", Date.UTC(2026, 4, 4), Date.UTC(2026, 4, 11));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-05-04T09:00:00.000Z", // Mon
+      "2026-05-06T09:00:00.000Z", // Wed
+      "2026-05-08T09:00:00.000Z", // Fri
+    ]);
+  });
+
+  test("every other week: skips weeks correctly", () => {
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [Day.Tuesday],
+      weekInterval: 2,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 4, 5), // Tue May 5 2026
+      seriesEnd: null,
+    };
+    const out = generateDaysOfWeek(rule, "UTC", Date.UTC(2026, 4, 1), Date.UTC(2026, 5, 1));
+    // Every other Tuesday starting May 5: 5, 19. (Jun 2 is outside window.)
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-05-05T00:00:00.000Z",
+      "2026-05-19T00:00:00.000Z",
+    ]);
+  });
+
+  test("count caps total emissions across weeks", () => {
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [Day.Monday, Day.Wednesday, Day.Friday],
+      weekInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 4, 4),
+      seriesEnd: null,
+      count: 5,
+    };
+    const out = generateDaysOfWeek(rule, "UTC", Date.UTC(2026, 4, 4), Date.UTC(2026, 5, 30));
+    expect(out).toHaveLength(5);
+    // Mon, Wed, Fri (week 1) + Mon, Wed (week 2) = 5
+    expect(new Date(out[4].startTimestamp).toISOString()).toBe("2026-05-13T09:00:00.000Z");
+  });
+
+  test("9am Monday in Denver stays at 9am wall across DST forward", () => {
+    // Spring forward Sun 2025-03-09. The Mondays around it: Mar 2, Mar 9 (no
+    // wait, Mar 9 is Sunday). Mar 2 (Mon, MST) and Mar 9 (Sun) — the next
+    // Monday is Mar 9? No: Mar 9 is Sun, Mar 10 is Mon. Use those.
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [Day.Monday],
+      weekInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2025, 2, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfWeek(
+      rule,
+      "America/Denver",
+      Date.UTC(2025, 2, 1),
+      Date.UTC(2025, 2, 17)
+    );
+    // Mar 3 (MST), Mar 10 (MDT), and Mar 17 — but window ends at Mar 17 00:00
+    // UTC. At 9am Denver on Mar 17 = 15:00 UTC, which is past 17 00:00 UTC.
+    // So we expect: Mar 3, Mar 10.
+    expect(out.length).toBeGreaterThanOrEqual(2);
+    const isos = out.map((o) => new Date(o.startTimestamp).toISOString());
+    expect(isos[0]).toBe("2025-03-03T16:00:00.000Z"); // 9am MST = 16 UTC
+    expect(isos[1]).toBe("2025-03-10T15:00:00.000Z"); // 9am MDT = 15 UTC
+
+    // And the wall-time hour in Denver is 9 for both:
+    expect(utcToWallParts(out[0].startTimestamp, "America/Denver").hour).toBe(9);
+    expect(utcToWallParts(out[1].startTimestamp, "America/Denver").hour).toBe(9);
+  });
+
+  test("excludes occurrences before seriesStart", () => {
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [Day.Sunday, Day.Monday, Day.Tuesday],
+      weekInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 4, 5), // Tue May 5
+      seriesEnd: null,
+    };
+    // Window starts before seriesStart. Should emit Tue May 5 only (Sun May 3
+    // and Mon May 4 are before seriesStart).
+    const out = generateDaysOfWeek(rule, "UTC", Date.UTC(2026, 4, 1), Date.UTC(2026, 4, 6));
+    expect(out).toHaveLength(1);
+    expect(new Date(out[0].startTimestamp).toISOString()).toBe("2026-05-05T00:00:00.000Z");
+  });
+
+  test("throws on weekInterval = 0", () => {
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [Day.Monday],
+      weekInterval: 0,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateDaysOfWeek(rule, "UTC", 0, 1000)).toThrow(/weekInterval/);
+  });
+
+  test("throws on empty days", () => {
+    const rule: DaysOfWeekRule = {
+      kind: "daysOfWeek",
+      days: [],
+      weekInterval: 1,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateDaysOfWeek(rule, "UTC", 0, 1000)).toThrow(/non-empty/);
+  });
+});

package/src/__tests__/days_of_year.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from "vitest";
+import { generateDaysOfYear } from "../generators/days_of_year.js";
+import type { DaysOfYearRule } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateDaysOfYear", () => {
+  test("50th and 70th day of every year", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [50, 70],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    // 2026 (non-leap): day 50 = Feb 19, day 70 = Mar 11
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-02-19T00:00:00.000Z",
+      "2026-03-11T00:00:00.000Z",
+    ]);
+  });
+
+  test("day 60 differs between leap and non-leap years", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [60],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    // 2024 (leap): day 60 = Feb 29. 2025/2026 (non-leap): day 60 = Mar 1.
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-02-29T00:00:00.000Z",
+      "2025-03-01T00:00:00.000Z",
+      "2026-03-01T00:00:00.000Z",
+    ]);
+  });
+
+  test("day 366 only emits in leap years (skipped in non-leap)", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [366],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2029, 0, 1));
+    // Only 2024 and 2028 are leap years in this range.
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-12-31T00:00:00.000Z",
+      "2028-12-31T00:00:00.000Z",
+    ]);
+  });
+
+  test("day 1 (Jan 1) every year", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [1],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-01-01T00:00:00.000Z",
+      "2025-01-01T00:00:00.000Z",
+      "2026-01-01T00:00:00.000Z",
+    ]);
+  });
+
+  test("day 365 (last day of non-leap year)", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [365],
+      yearInterval: 1,
+      timeOfDay: 23 * HOUR + 59 * 60_000,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    // 2024 leap: day 365 = Dec 30. 2025/2026 non-leap: day 365 = Dec 31.
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-12-30T23:59:00.000Z",
+      "2025-12-31T23:59:00.000Z",
+      "2026-12-31T23:59:00.000Z",
+    ]);
+  });
+
+  test("yearInterval = 4 with day 366 emits each leap year", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [366],
+      yearInterval: 4,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2033, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-12-31T00:00:00.000Z",
+      "2028-12-31T00:00:00.000Z",
+      "2032-12-31T00:00:00.000Z",
+    ]);
+  });
+
+  test("count caps emissions", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [50, 70, 100],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+      count: 4,
+    };
+    const out = generateDaysOfYear(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2029, 0, 1));
+    expect(out).toHaveLength(4);
+  });
+
+  test("throws on empty daysOfYear", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateDaysOfYear(rule, "UTC", 0, 1000)).toThrow(/daysOfYear/);
+  });
+
+  test("throws on day out of range (1..366)", () => {
+    const rule: DaysOfYearRule = {
+      kind: "daysOfYear",
+      daysOfYear: [367],
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateDaysOfYear(rule, "UTC", 0, 1000)).toThrow(/daysOfYear/);
+  });
+});