@connextar/house 0.10.0 → 0.11.0

package/dist/jobs/windows.js

@@ -0,0 +1,130 @@
+/**
+ * Run windows: which window a moment falls in, or none.
+ *
+ * A window is a function from "now" to a key, or `null` when the job is not due
+ * at all. The key is what the ledger's unique index is on, together with the
+ * job, so **one run per job per key** is the whole of idempotency: a second tick
+ * in the same window finds the key taken and does nothing.
+ *
+ * Both apps wrote this as two functions — `attempt(now)` and `windowKey(now)` —
+ * which could disagree. One function cannot.
+ *
+ * The helpers carry one lesson each:
+ *
+ * - **A day is a day somewhere.** AltEd keyed its tracker job on the UTC date
+ *   while the job took "yesterday" from the UK calendar; in summer a tick after
+ *   23:00 UTC and the next at 00:00 UTC fell in different windows but the same
+ *   UK day, so that day's misses were sent twice and the next day's never. Every
+ *   calendar helper takes the `timeZone` the job's own idea of a day comes from.
+ * - **Not before a civil hour.** `from` keeps a morning email out of midnight —
+ *   AltEd's weekly digest waits for 07:00 "so nobody's phone lights up".
+ * - **A missed start is caught up, not lost.** Quickie's monthly report ran only
+ *   on the 1st, so a day of failed ticks on the 1st lost the month. `weekly` and
+ *   `monthly` stay open from their start to the end of their period (after
+ *   `from` each day), and the key keeps it to one run.
+ *
+ * Keys match what both apps already store (`2026-09-30`, `2026-09-30T14`,
+ * `2026-09-30Q2`, `month:2026-09`), so moving a job onto a helper does not run
+ * it a second time in the window it moves in.
+ */
+const WEEKDAYS = { Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6, Sun: 7 };
+const formatters = new Map();
+function zoned(now, timeZone) {
+    let format = formatters.get(timeZone);
+    if (!format) {
+        format = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            hourCycle: "h23",
+            weekday: "short",
+        });
+        formatters.set(timeZone, format);
+    }
+    const parts = Object.fromEntries(format.formatToParts(now).map((part) => [part.type, part.value]));
+    return {
+        year: Number(parts.year),
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hour: Number(parts.hour),
+        weekday: WEEKDAYS[parts.weekday ?? ""] ?? 1,
+    };
+}
+const pad = (value, width = 2) => String(value).padStart(width, "0");
+/** `YYYY-MM-DD` for a calendar date, moved by whole days without touching a clock. */
+function dateKey(year, month, day, plusDays = 0) {
+    const date = new Date(Date.UTC(year, month - 1, day + plusDays));
+    return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}
+function checkHour(from) {
+    if (!Number.isInteger(from) || from < 0 || from > 23)
+        throw new RangeError(`"from" must be an hour, 0–23 (got ${from}).`);
+}
+/** Once an hour. Key `2026-09-30T14` (UTC) — Quickie's hourly key. */
+export function hourly() {
+    return (now) => `${now.toISOString().slice(0, 13)}`;
+}
+/**
+ * Once every `hours` hours, in blocks from UTC midnight. Key `2026-09-30Q2` —
+ * with 6, exactly Quickie's four-a-day bank feed key.
+ */
+export function everyHours(hours) {
+    if (!Number.isInteger(hours) || hours < 1 || 24 % hours !== 0) {
+        throw new RangeError(`everyHours takes a whole number of hours that divides the day (got ${hours}).`);
+    }
+    return (now) => `${now.toISOString().slice(0, 10)}Q${Math.floor(now.getUTCHours() / hours)}`;
+}
+/** Once a day, from `from` o'clock to midnight in `timeZone`. Key `2026-09-30`, the date there. */
+export function daily(options = {}) {
+    const { from = 0, timeZone = "UTC" } = options;
+    checkHour(from);
+    return (now) => {
+        const at = zoned(now, timeZone);
+        return at.hour >= from ? dateKey(at.year, at.month, at.day) : null;
+    };
+}
+/**
+ * Once a week, opening on `weekday` (1 = Monday) at `from` and staying open —
+ * from `from` each day — until the next one opens. Key `week:2026-09-28`, the
+ * date it opened.
+ */
+export function weekly(options = {}) {
+    const { weekday = 1, from = 0, timeZone = "UTC" } = options;
+    checkHour(from);
+    if (!Number.isInteger(weekday) || weekday < 1 || weekday > 7) {
+        throw new RangeError(`weekday is 1 (Monday) to 7 (Sunday) (got ${weekday}).`);
+    }
+    return (now) => {
+        const at = zoned(now, timeZone);
+        if (at.hour < from)
+            return null;
+        const since = (at.weekday - weekday + 7) % 7;
+        return `week:${dateKey(at.year, at.month, at.day, -since)}`;
+    };
+}
+/**
+ * Once a month, opening on `day` at `from` and staying open — from `from` each
+ * day — to the month's end. Key `month:2026-09` — Quickie's monthly key.
+ * `day` is 1–28, so the window opens in February too.
+ */
+export function monthly(options = {}) {
+    const { day = 1, from = 0, timeZone = "UTC" } = options;
+    checkHour(from);
+    if (!Number.isInteger(day) || day < 1 || day > 28)
+        throw new RangeError(`day is 1–28 (got ${day}).`);
+    return (now) => {
+        const at = zoned(now, timeZone);
+        if (at.day < day || at.hour < from)
+            return null;
+        return `month:${pad(at.year, 4)}-${pad(at.month)}`;
+    };
+}
+/** The prefix every Run now key starts with, in both apps' existing rows and in this module's. */
+export const MANUAL_KEY_PREFIX = "manual:";
+/** Whether a stored window key was a Run now rather than the schedule. */
+export function isManualKey(windowKey) {
+    return windowKey.startsWith(MANUAL_KEY_PREFIX);
+}
+//# sourceMappingURL=windows.js.map

package/dist/jobs/windows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.js","sourceRoot":"","sources":["../../src/jobs/windows.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {
@@ -62,6 +62,14 @@
       "types": "./dist/grid/index.d.ts",
       "default": "./dist/grid/index.js"
     },
+    "./jobs": {
+      "types": "./dist/jobs/index.d.ts",
+      "default": "./dist/jobs/index.js"
+    },
+    "./jobs/react": {
+      "types": "./dist/jobs/react-index.d.ts",
+      "default": "./dist/jobs/react-index.js"
+    },
     "./web-search": {
       "types": "./dist/web-search/index.d.ts",
       "default": "./dist/web-search/index.js"