@j13b/scheduler 0.0.0-stage → 0.1.0

package/src/__tests__/dispatcher.test.ts

@@ -0,0 +1,317 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { Dispatcher } from "../dispatcher.js";
+import { InMemoryDispatcherStore } from "../dispatcher_store.js";
+import { InMemorySchedulerPort } from "../in_memory_port.js";
+import { Scheduler } from "../scheduler.js";
+import type { ScheduledEvent } from "../types.js";
+
+interface CronPayload {
+  type: "cron";
+  command: string;
+}
+
+const HOUR = 3_600_000;
+const T0_DATE = new Date(2026, 4, 11, 0, 0, 0);
+
+// Each test captures a single T0 (the test's "logical now") and derives
+// everything from it — cursor seeds, event startOns, expectation timestamps.
+// This removes any implicit dependency on Date.now() being frozen by fake
+// timers between calls. If you ever remove vi.useFakeTimers() or someone
+// changes the harness, the tests still mean the same thing.
+function makeFakes() {
+  const port = new InMemorySchedulerPort<CronPayload>();
+  const scheduler = new Scheduler(port);
+  const fired: ScheduledEvent<CronPayload>[] = [];
+  const errors: { err: unknown; event?: ScheduledEvent<CronPayload> }[] = [];
+  const store = new InMemoryDispatcherStore();
+  const T0 = T0_DATE.getTime();
+  return { port, scheduler, fired, errors, store, T0 };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(T0_DATE);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("Dispatcher — catch-up on start", () => {
+  test("fires all events between cursor and now on first tick", async () => {
+    const { scheduler, fired, store, T0 } = makeFakes();
+    // Pre-seed the cursor at T0.
+    await store.saveCursor(T0);
+
+    // Add three events at known offsets from T0.
+    await scheduler.add({
+      id: "e1",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 1 * HOUR },
+      payload: { type: "cron", command: "1" },
+    });
+    await scheduler.add({
+      id: "e2",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 2 * HOUR },
+      payload: { type: "cron", command: "2" },
+    });
+    await scheduler.add({
+      id: "e3",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 5 * HOUR },
+      payload: { type: "cron", command: "3" },
+    });
+
+    // Simulate downtime: jump the wall clock to T0 + 3h, past the first two.
+    vi.setSystemTime(new Date(T0 + 3 * HOUR));
+
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (event) => {
+        fired.push(event);
+      },
+      store,
+    });
+    await dispatcher.start();
+    dispatcher.stop();
+
+    expect(fired.map((e) => e.payload.command)).toEqual(["1", "2"]);
+  });
+
+  test("first run with no cursor seeds it to now (no backfill)", async () => {
+    const { scheduler, fired, store, T0 } = makeFakes();
+    // Event 1 hour before T0 — would fire if cursor were earlier than T0.
+    await scheduler.add({
+      id: "past",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 - HOUR },
+      payload: { type: "cron", command: "past" },
+    });
+
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        fired.push(e);
+      },
+      store,
+    });
+    await dispatcher.start();
+    dispatcher.stop();
+
+    // Cursor was null → seeded to T0 → past event not in [T0, T0+1) range.
+    expect(fired).toHaveLength(0);
+    // Cursor advances to `now + 1` (windowEnd convention) so events at
+    // exactly `now` would be picked up but not re-emitted on the next tick.
+    expect(await store.loadCursor()).toBe(T0 + 1);
+  });
+});
+
+describe("Dispatcher — live firing", () => {
+  test("fires an event when its time arrives", async () => {
+    const { scheduler, fired, store, T0 } = makeFakes();
+    await store.saveCursor(T0);
+
+    await scheduler.add({
+      id: "soon",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + HOUR },
+      payload: { type: "cron", command: "ping" },
+    });
+
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        fired.push(e);
+      },
+      store,
+    });
+    await dispatcher.start();
+
+    // Advance to just past the event.
+    await vi.advanceTimersByTimeAsync(HOUR + 100);
+    dispatcher.stop();
+
+    expect(fired.map((e) => e.payload.command)).toEqual(["ping"]);
+  });
+});
+
+describe("Dispatcher — wake on add (the race)", () => {
+  test("adding an event during sleep wakes the dispatcher and fires it on time", async () => {
+    const { scheduler, fired, store, T0 } = makeFakes();
+    await store.saveCursor(T0);
+
+    // Initial event 5 hours out from T0.
+    await scheduler.add({
+      id: "later",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 5 * HOUR },
+      payload: { type: "cron", command: "later" },
+    });
+
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        fired.push(e);
+      },
+      store,
+    });
+    await dispatcher.start();
+
+    // 30 minutes pass — dispatcher is sleeping until T0 + 5h.
+    await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
+    expect(fired).toHaveLength(0);
+
+    // A new event gets added at T0 + 1h — before "later". Scheduler.changed
+    // notifies; dispatcher wakes from its sleep and re-queries nextDue.
+    await scheduler.add({
+      id: "sooner",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 1 * HOUR },
+      payload: { type: "cron", command: "sooner" },
+    });
+    // Let microtasks settle (the wake is sync but the loop is async).
+    await vi.advanceTimersByTimeAsync(0);
+
+    // Advance past "sooner"'s firing time (T0 + 1h, currently at T0 + 30m).
+    await vi.advanceTimersByTimeAsync(40 * 60 * 1000); // total +1h10m
+    expect(fired.map((e) => e.payload.command)).toContain("sooner");
+    expect(fired).toHaveLength(1); // only sooner so far
+
+    // Continue past "later" (T0 + 5h).
+    await vi.advanceTimersByTimeAsync(5 * HOUR);
+    dispatcher.stop();
+
+    expect(fired.map((e) => e.payload.command)).toEqual(["sooner", "later"]);
+  });
+});
+
+describe("Dispatcher — failure handling", () => {
+  test("fire throwing: logged via onError, cursor still advances", async () => {
+    const { scheduler, fired, errors, store, T0 } = makeFakes();
+    await store.saveCursor(T0);
+
+    await scheduler.add({
+      id: "bad",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + HOUR },
+      payload: { type: "cron", command: "boom" },
+    });
+    await scheduler.add({
+      id: "good",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 2 * HOUR },
+      payload: { type: "cron", command: "ok" },
+    });
+
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        if (e.payload.command === "boom") throw new Error("kaboom");
+        fired.push(e);
+      },
+      store,
+      onError: (err, event) => {
+        errors.push({ err, event });
+      },
+    });
+    await dispatcher.start();
+
+    await vi.advanceTimersByTimeAsync(3 * HOUR);
+    dispatcher.stop();
+
+    expect(errors).toHaveLength(1);
+    expect((errors[0].err as Error).message).toBe("kaboom");
+    expect(errors[0].event?.payload.command).toBe("boom");
+    // The "good" event still fires after the failure.
+    expect(fired.map((e) => e.payload.command)).toEqual(["ok"]);
+  });
+});
+
+describe("Dispatcher — stop()", () => {
+  test("stop prevents further firing", async () => {
+    const { scheduler, fired, store, T0 } = makeFakes();
+    await store.saveCursor(T0);
+
+    await scheduler.add({
+      id: "a",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + HOUR },
+      payload: { type: "cron", command: "a" },
+    });
+    await scheduler.add({
+      id: "b",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + 2 * HOUR },
+      payload: { type: "cron", command: "b" },
+    });
+
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        fired.push(e);
+      },
+      store,
+    });
+    await dispatcher.start();
+
+    await vi.advanceTimersByTimeAsync(HOUR + 100);
+    dispatcher.stop();
+    await vi.advanceTimersByTimeAsync(10 * HOUR);
+
+    expect(fired.map((e) => e.payload.command)).toEqual(["a"]);
+  });
+
+  test("stop is idempotent", async () => {
+    const { scheduler, store, T0 } = makeFakes();
+    await store.saveCursor(T0);
+    const dispatcher = new Dispatcher({
+      scheduler,
+      fire: async () => {},
+      store,
+    });
+    await dispatcher.start();
+    dispatcher.stop();
+    expect(() => dispatcher.stop()).not.toThrow();
+  });
+});
+
+describe("Dispatcher — cursor persistence", () => {
+  test("cursor survives stop/start, preventing re-fire", async () => {
+    const { scheduler, fired, store, T0 } = makeFakes();
+    await store.saveCursor(T0);
+
+    await scheduler.add({
+      id: "e1",
+      timezone: "UTC",
+      rule: { kind: "instant", startOn: T0 + HOUR },
+      payload: { type: "cron", command: "1" },
+    });
+
+    let dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        fired.push(e);
+      },
+      store,
+    });
+    await dispatcher.start();
+    await vi.advanceTimersByTimeAsync(HOUR + 100);
+    dispatcher.stop();
+    expect(fired).toHaveLength(1);
+
+    // Restart — cursor is now past the event, so it shouldn't re-fire.
+    dispatcher = new Dispatcher({
+      scheduler,
+      fire: async (e) => {
+        fired.push(e);
+      },
+      store,
+    });
+    await dispatcher.start();
+    await vi.advanceTimersByTimeAsync(5 * HOUR);
+    dispatcher.stop();
+
+    expect(fired).toHaveLength(1);
+  });
+});

package/src/__tests__/instant.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { generateInstant } from "../generators/instant.js";
+import type { InstantRule } from "../types.js";
+
+describe("generateInstant", () => {
+  const rule: InstantRule = {
+    kind: "instant",
+    startOn: Date.UTC(2026, 4, 11, 14, 0, 0),
+    timeSpan: { type: "duration", ms: 60 * 60_000 },
+  };
+
+  test("emits if event intersects window", () => {
+    const out = generateInstant(rule, undefined, Date.UTC(2026, 4, 11), Date.UTC(2026, 4, 12));
+    expect(out).toHaveLength(1);
+    expect(out[0]).toEqual({
+      startTimestamp: rule.startOn,
+      endTimestamp: rule.startOn + 60 * 60_000,
+    });
+  });
+
+  test("emits if window is entirely inside event duration", () => {
+    const out = generateInstant(
+      rule,
+      undefined,
+      rule.startOn + 10 * 60_000,
+      rule.startOn + 20 * 60_000
+    );
+    expect(out).toHaveLength(1);
+  });
+
+  test("does not emit when window is fully before", () => {
+    const out = generateInstant(rule, undefined, Date.UTC(2026, 4, 1), Date.UTC(2026, 4, 10));
+    expect(out).toHaveLength(0);
+  });
+
+  test("does not emit when window is fully after", () => {
+    const out = generateInstant(rule, undefined, Date.UTC(2026, 4, 20), Date.UTC(2026, 4, 25));
+    expect(out).toHaveLength(0);
+  });
+
+  test("does not emit when window is exactly the end (half-open)", () => {
+    const out = generateInstant(
+      rule,
+      undefined,
+      rule.startOn + 60 * 60_000,
+      rule.startOn + 60 * 60_000 + 1000
+    );
+    expect(out).toHaveLength(0);
+  });
+});

package/src/__tests__/local_date_time.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "vitest";
+import { generateLocalDateTime } from "../generators/local_date_time.js";
+import type { LocalDateTimeRule } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateLocalDateTime", () => {
+  test("resolves wall-clock fields through the template tz", () => {
+    // May 11 2026 09:00 in Denver is MDT (UTC-6) → 15:00 UTC.
+    const rule: LocalDateTimeRule = {
+      kind: "localDateTime",
+      year: 2026,
+      month: 4, // May
+      day: 11,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+    };
+    const out = generateLocalDateTime(
+      rule,
+      "America/Denver",
+      Date.UTC(2026, 4, 1),
+      Date.UTC(2026, 4, 30)
+    );
+    expect(out).toHaveLength(1);
+    expect(out[0].startTimestamp).toBe(Date.UTC(2026, 4, 11, 15));
+    expect(out[0].endTimestamp).toBe(Date.UTC(2026, 4, 11, 16));
+  });
+
+  test("with no tz, wall-clock fields are interpreted as UTC", () => {
+    const rule: LocalDateTimeRule = {
+      kind: "localDateTime",
+      year: 2026,
+      month: 4,
+      day: 11,
+      timeOfDay: 9 * HOUR,
+    };
+    const out = generateLocalDateTime(rule, undefined, Date.UTC(2026, 4, 1), Date.UTC(2026, 4, 30));
+    expect(out).toHaveLength(1);
+    expect(out[0].startTimestamp).toBe(Date.UTC(2026, 4, 11, 9));
+  });
+
+  test("clamps day to month length (Feb 30 → Feb 28 in a non-leap year)", () => {
+    const rule: LocalDateTimeRule = {
+      kind: "localDateTime",
+      year: 2026, // non-leap
+      month: 1, // Feb
+      day: 30,
+      timeOfDay: 0,
+    };
+    const out = generateLocalDateTime(rule, undefined, Date.UTC(2026, 1, 1), Date.UTC(2026, 2, 1));
+    expect(out).toHaveLength(1);
+    expect(out[0].startTimestamp).toBe(Date.UTC(2026, 1, 28));
+  });
+
+  test("hourSpan flexes across spring-forward (8 wall-hours = 7 real hours)", () => {
+    // Mar 7 2026 23:00 Denver (MST, UTC-7) → 06:00 UTC Mar 8.
+    // +8 wall hours lands at 07:00 wall Mar 8, now MDT (UTC-6) → 13:00 UTC.
+    // Real elapsed: 7h, because the clock jumped 02:00 → 03:00 overnight.
+    const rule: LocalDateTimeRule = {
+      kind: "localDateTime",
+      year: 2026,
+      month: 2, // March
+      day: 7,
+      timeOfDay: 23 * HOUR,
+      timeSpan: { type: "hourSpan", hours: 8 },
+    };
+    const out = generateLocalDateTime(
+      rule,
+      "America/Denver",
+      Date.UTC(2026, 2, 1),
+      Date.UTC(2026, 2, 31)
+    );
+    expect(out).toHaveLength(1);
+    expect(out[0].startTimestamp).toBe(Date.UTC(2026, 2, 8, 6));
+    expect(out[0].endTimestamp).toBe(Date.UTC(2026, 2, 8, 13));
+    expect(out[0].endTimestamp - out[0].startTimestamp).toBe(7 * HOUR);
+  });
+
+  describe("spring-forward gap on the start (02:30 Mar 8 2026 Denver — nonexistent)", () => {
+    // The clock skips 02:00 → 03:00, so 02:30 doesn't exist that day.
+    const rule: LocalDateTimeRule = {
+      kind: "localDateTime",
+      year: 2026,
+      month: 2, // March
+      day: 8,
+      timeOfDay: 2 * HOUR + 30 * 60_000,
+    };
+    const gen = (dis?: Parameters<typeof generateLocalDateTime>[4]) =>
+      generateLocalDateTime(
+        rule,
+        "America/Denver",
+        Date.UTC(2026, 2, 1),
+        Date.UTC(2026, 2, 31),
+        dis
+      );
+
+    test("default (compatible) moves forward to the later instant", () => {
+      const out = gen();
+      expect(out).toHaveLength(1);
+      expect(new Date(out[0].startTimestamp).toISOString()).toBe("2026-03-08T09:30:00.000Z");
+    });
+
+    test("earlier resolves to the earlier instant", () => {
+      const out = gen("earlier");
+      expect(new Date(out[0].startTimestamp).toISOString()).toBe("2026-03-08T08:30:00.000Z");
+    });
+
+    test("skip drops the nonexistent occurrence", () => {
+      expect(gen("skip")).toHaveLength(0);
+    });
+
+    test("reject throws", () => {
+      expect(() => gen("reject")).toThrow(/gap/);
+    });
+  });
+
+  test("does not emit when the occurrence is outside the window", () => {
+    const rule: LocalDateTimeRule = {
+      kind: "localDateTime",
+      year: 2026,
+      month: 4,
+      day: 11,
+      timeOfDay: 9 * HOUR,
+    };
+    const out = generateLocalDateTime(rule, undefined, Date.UTC(2026, 5, 1), Date.UTC(2026, 5, 30));
+    expect(out).toHaveLength(0);
+  });
+
+  test("throws on out-of-range month", () => {
+    const rule = {
+      kind: "localDateTime",
+      year: 2026,
+      month: 12,
+      day: 1,
+      timeOfDay: 0,
+    } as unknown as LocalDateTimeRule;
+    expect(() => generateLocalDateTime(rule, undefined, 0, Date.UTC(2030, 0, 1))).toThrow();
+  });
+});