@greatwait/contracts 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/naming.d.ts

@@ -0,0 +1,45 @@
+import { type Recurrence } from "./scheduling.js";
+/** "60s", "5m", "2h", "1d" when the interval is a whole one; seconds otherwise. */
+export declare function compactInterval(seconds: number): string;
+/**
+ * A cron expression in a few words — "2pm MTW", "9am daily", "2:30pm
+ * weekdays" — or the expression itself when it is not a plain time on some
+ * days of the week. A name should never claim a reading it cannot make.
+ */
+export declare function cronWords(expression: string): string;
+/** The host of a URL, without a leading "www." — or the text if it is not one. */
+export declare function targetDomain(url: string): string;
+/**
+ * The name a schedule gets when nobody types one: its type, period and
+ * target domain in a sentence.
+ *
+ * | Recurrence                | Endpoint                | Name                        |
+ * | ------------------------- | ----------------------- | --------------------------- |
+ * | every 60 seconds          | https://flowxo.com/x    | Every 60s → flowxo.com      |
+ * | cron `0 14 * * 1-3`       | https://example.com/y   | 2pm MTW → example.com       |
+ * | once, at an instant       | https://example.com/y   | Once 2026-09-05 14:33 UTC → example.com |
+ * | every 5 minutes, no endpoint | —                    | Every 5m (timer)            |
+ */
+export declare function generatedScheduleName(recurrence: Recurrence | {
+    readonly at: string;
+    readonly kind: "at";
+}, endpointUrl: string | undefined): string;
+/**
+ * The period half of a generated name on its own — "Every 1h", "2pm MTW",
+ * "Once 2026-09-05 14:33 UTC". What a row is called when whoever writes it
+ * knows the recurrence and nothing about where it delivers: the migration
+ * that backfilled the column, and a repository handed no name.
+ */
+export declare function periodWords(recurrence: Recurrence | {
+    readonly at: string;
+    readonly kind: "at";
+}): string;
+/**
+ * The name an endpoint gets when nobody types one: its whole URL.
+ *
+ * "For endpoints, let's use the whole URL as the name, and require the names
+ * to be unique. Two endpoints can only have the same URL if they are
+ * explicitely named." The whole address, not the domain — an endpoint appears
+ * in a dropdown, and two receivers on one host are two entries.
+ */
+export declare function generatedEndpointName(url: string): string;

package/dist/naming.js

@@ -0,0 +1,159 @@
+import { SCHEDULE_NAME_MAX_LENGTH } from "./scheduling.js";
+/**
+ * The names a schedule and an endpoint get when nobody types one (W4-14,
+ * FXO-2255).
+ *
+ * "The optional names should be defaulted on save for schedule and endpoint -
+ * for schedule, the type, period, and target domain in a sentance, something
+ * like 'Every 60s -> flowxo.com' or '2pm MTW -> example.com' (for CRON for
+ * instance)". And: "For endpoints, let's use the whole URL as the name".
+ *
+ * **A stored value, not a rendering trick.** The service writes the generated
+ * name into the row on save, and the person edits it like any other name
+ * afterwards; nothing recomputes it when the recurrence changes. So this
+ * module is used at the moment of creation and nowhere else on the read
+ * path — the dashboard shows it only as a preview of what the save will
+ * write.
+ */
+const DAY_INITIALS = ["Su", "M", "T", "W", "Th", "F", "Sa"];
+/** "60s", "5m", "2h", "1d" when the interval is a whole one; seconds otherwise. */
+export function compactInterval(seconds) {
+    if (seconds % 86_400 === 0)
+        return `${String(seconds / 86_400)}d`;
+    if (seconds % 3_600 === 0)
+        return `${String(seconds / 3_600)}h`;
+    if (seconds % 60 === 0)
+        return `${String(seconds / 60)}m`;
+    return `${String(seconds)}s`;
+}
+/** "2pm", "2:30pm", "9am", "12am"; undefined when the field is not one plain time. */
+function clockWords(minute, hour) {
+    if (!/^\d{1,2}$/u.test(minute) || !/^\d{1,2}$/u.test(hour))
+        return undefined;
+    const h = Number(hour);
+    const m = Number(minute);
+    if (h > 23 || m > 59)
+        return undefined;
+    const twelve = h % 12 === 0 ? 12 : h % 12;
+    const suffix = h < 12 ? "am" : "pm";
+    return m === 0
+        ? `${String(twelve)}${suffix}`
+        : `${String(twelve)}:${String(m).padStart(2, "0")}${suffix}`;
+}
+/** "daily", "weekdays", "weekends", or initials like "MTW"; undefined if unreadable. */
+function daysWords(field) {
+    if (field === "*" || field === "?")
+        return "daily";
+    const days = new Set();
+    for (const part of field.split(",")) {
+        const range = /^(\d)(?:-(\d))?$/u.exec(part);
+        if (range === null)
+            return undefined;
+        const from = Number(range[1]);
+        const to = range[2] === undefined ? from : Number(range[2]);
+        if (from > 7 || to > 7 || from > to)
+            return undefined;
+        for (let day = from; day <= to; day += 1)
+            days.add(day % 7);
+    }
+    if (days.size === 0)
+        return undefined;
+    const ordered = [1, 2, 3, 4, 5, 6, 0].filter((day) => days.has(day));
+    if (ordered.length === 7)
+        return "daily";
+    if (ordered.length === 5 && ordered.every((day) => day >= 1 && day <= 5)) {
+        return "weekdays";
+    }
+    if (ordered.length === 2 && days.has(0) && days.has(6))
+        return "weekends";
+    return ordered.map((day) => DAY_INITIALS[day]).join("");
+}
+/**
+ * A cron expression in a few words — "2pm MTW", "9am daily", "2:30pm
+ * weekdays" — or the expression itself when it is not a plain time on some
+ * days of the week. A name should never claim a reading it cannot make.
+ */
+export function cronWords(expression) {
+    const fields = expression.trim().split(/\s+/u);
+    if (fields.length !== 5)
+        return `cron ${expression.trim()}`;
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+    const clock = clockWords(minute, hour);
+    const days = daysWords(dayOfWeek);
+    if (clock === undefined ||
+        days === undefined ||
+        dayOfMonth !== "*" ||
+        month !== "*") {
+        return `cron ${expression.trim()}`;
+    }
+    return `${clock} ${days}`;
+}
+/** The host of a URL, without a leading "www." — or the text if it is not one. */
+export function targetDomain(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./u, "");
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * The name a schedule gets when nobody types one: its type, period and
+ * target domain in a sentence.
+ *
+ * | Recurrence                | Endpoint                | Name                        |
+ * | ------------------------- | ----------------------- | --------------------------- |
+ * | every 60 seconds          | https://flowxo.com/x    | Every 60s → flowxo.com      |
+ * | cron `0 14 * * 1-3`       | https://example.com/y   | 2pm MTW → example.com       |
+ * | once, at an instant       | https://example.com/y   | Once 2026-09-05 14:33 UTC → example.com |
+ * | every 5 minutes, no endpoint | —                    | Every 5m (timer)            |
+ */
+export function generatedScheduleName(recurrence, endpointUrl) {
+    const period = periodWords(recurrence);
+    return boundedName(endpointUrl === undefined
+        ? `${period} (timer)`
+        : `${period} → ${targetDomain(endpointUrl)}`);
+}
+/**
+ * The period half of a generated name on its own — "Every 1h", "2pm MTW",
+ * "Once 2026-09-05 14:33 UTC". What a row is called when whoever writes it
+ * knows the recurrence and nothing about where it delivers: the migration
+ * that backfilled the column, and a repository handed no name.
+ */
+export function periodWords(recurrence) {
+    return boundedName(recurrence.kind === "every"
+        ? `Every ${compactInterval(recurrence.everySeconds)}`
+        : recurrence.kind === "cron"
+            ? cronWords(recurrence.cron)
+            : `Once ${"at" in recurrence ? instantWords(recurrence.at) : ""}`.trim());
+}
+/**
+ * Cut to what the contract admits. A hostname may run to 253 characters and
+ * a cron expression to whatever somebody typed; a generated name longer than
+ * the schema's bound would be refused by the row's own check, or written and
+ * then rejected on every read.
+ */
+function boundedName(name) {
+    return name.length <= SCHEDULE_NAME_MAX_LENGTH
+        ? name
+        : `${name.slice(0, SCHEDULE_NAME_MAX_LENGTH - 1)}…`;
+}
+/** "2026-09-05 14:33 UTC" — the service has no reader's clock at save time. */
+function instantWords(iso) {
+    const ms = Date.parse(iso);
+    if (Number.isNaN(ms))
+        return iso;
+    const date = new Date(ms).toISOString();
+    return `${date.slice(0, 10)} ${date.slice(11, 16)} UTC`;
+}
+/**
+ * The name an endpoint gets when nobody types one: its whole URL.
+ *
+ * "For endpoints, let's use the whole URL as the name, and require the names
+ * to be unique. Two endpoints can only have the same URL if they are
+ * explicitely named." The whole address, not the domain — an endpoint appears
+ * in a dropdown, and two receivers on one host are two entries.
+ */
+export function generatedEndpointName(url) {
+    return url;
+}