attempt at implementing a kind of time-zone resiliant cron

ts/time/cron.ts

@@ -0,0 +1,54 @@
+import { minute } from "#root/ts/time/time.js";
+
+export interface Cancel {
+	(): void
+}
+
+
+const tick = 1 * minute;
+
+/**
+ * Schedules a function to be called when a month begins.
+ * This function recalculates the next execution time every minute to stay accurate,
+ * especially if the user changes time zones.
+ * @param fn - The function to execute at the start of the month.
+ * @param month - Optional. Specific month (0-11) when the function should be called.
+ * @returns A {@link Cancel} function to cancel the scheduled execution.
+ */
+export function onMonth(fn: () => unknown, month?: number): Cancel {
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+    const schedule = () => {
+        const now = new Date();
+        const currentMonth = now.getMonth();
+        const currentYear = now.getFullYear();
+
+        const nextMonthStart = month !== undefined
+            ? new Date(currentYear + (currentMonth >= month ? 1 : 0), month, 1)
+            : new Date(currentYear, currentMonth + 1, 1);
+
+        const delay = nextMonthStart.getTime() - now.getTime();
+
+        if (delay <= tick) {
+            if (intervalId) {
+                clearInterval(intervalId);
+                intervalId = null;
+            }
+            if (timeoutId) clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => {
+                fn();
+                schedule();
+            }, delay);
+        } else if (!intervalId) {
+            intervalId = setInterval(schedule, tick);
+        }
+    };
+
+    schedule();
+
+    return () => {
+        if (intervalId) clearInterval(intervalId);
+        if (timeoutId) clearTimeout(timeoutId);
+    };
+}

ts/time/schedule.ts

@@ -0,0 +1,48 @@
+import { minute } from "#root/ts/time/time.js";
+
+
+interface Cancel {
+	(): void
+}
+
+/**
+ * Calls a function as close to the given Date as possible.
+ *
+ * For resiliance against time-zone shifts, this function re-calculates
+ * the target time every minute, so if the target time ends up suddenly
+ * happening very soon or even in the past, the function will still fire
+ * correctly.
+ *
+ * Returns {@link Cancel}.
+ */
+export function schedule(fn: () => unknown, next: (now: Date) => Date, tick: number = 1 * minute): Cancel {
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+    const schedule = () => {
+        const now = new Date();
+
+        const delay = (+next(now)) - (+now)
+
+        if (delay <= tick) {
+            if (intervalId) {
+                clearInterval(intervalId);
+                intervalId = null;
+            }
+            if (timeoutId) clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => {
+                fn();
+                schedule();
+            }, delay);
+        } else if (!intervalId) {
+            intervalId = setInterval(schedule, tick);
+        }
+    };
+
+    schedule();
+
+    return () => {
+        if (intervalId) clearInterval(intervalId);
+        if (timeoutId) clearTimeout(timeoutId);
+    };
+}

ts/time/time.ts

@@ -0,0 +1,6 @@
+export const millisecond = 1;
+export const second = 60 * millisecond;
+export const minute = 60 * second;
+export const hour = 60 * second;
+export const day = 24 * hour;
+export const week = 7 * day;