@alzulejos/laranja-core 0.2.4

package/dist/schedule.js

@@ -0,0 +1,140 @@
+/**
+ * Schedule representation. laranja stores schedules in a PROVIDER-NEUTRAL
+ * structured form so the back half can lower them to whatever the target cloud
+ * expects (AWS EventBridge `rate(...)`/`cron(...)`, GCP/Cloudflare Unix cron,
+ * Azure NCRONTAB, …). The front half never bakes in a provider string.
+ *
+ * `rate` ("every N units") is portable across every provider. `cron` carries a
+ * raw expression tagged with its dialect — an explicit escape hatch (only "aws"
+ * exists today; new dialects land with their providers).
+ *
+ * The builders are pure, which lets the static scanner constant-fold calls like
+ * `@Cron(rate(5, "minutes"))` at scan time without executing user code.
+ */
+import cronstrue from "cronstrue";
+function toSingular(unit) {
+    return unit.replace(/s$/, "");
+}
+/**
+ * Builds a neutral "every N units" schedule.
+ *
+ * @example rate(5, "minutes") // { kind: "rate", value: 5, unit: "minute" }
+ * @example rate(1, "hour")    // { kind: "rate", value: 1, unit: "hour" }
+ */
+export function rate(value, unit) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`rate(): value must be a positive integer, got ${value}`);
+    }
+    return { kind: "rate", value, unit: toSingular(unit) };
+}
+/**
+ * Shorthand for `rate(1, unit)`.
+ * @example every("day") // { kind: "rate", value: 1, unit: "day" }
+ */
+export function every(unit) {
+    return rate(1, unit);
+}
+const RATE_STRING_RE = /^rate\((\d+)\s+(minute|minutes|hour|hours|day|days)\)$/;
+const CRON_STRING_RE = /^cron\((.+)\)$/;
+/**
+ * Parse a raw AWS schedule STRING (`"rate(5 minutes)"` / `"cron(0 12 * * ? *)"`)
+ * into the neutral structured form. Returns undefined for anything that isn't a
+ * valid AWS expression (e.g. a 5-field Unix cron string), so callers can raise a
+ * clear error. (Other dialects' string parsing arrives with their providers.)
+ */
+export function parseScheduleString(s) {
+    const trimmed = s.trim();
+    const r = RATE_STRING_RE.exec(trimmed);
+    if (r) {
+        const value = Number(r[1]);
+        if (value < 1)
+            return undefined;
+        return { kind: "rate", value, unit: toSingular(r[2]) };
+    }
+    const c = CRON_STRING_RE.exec(trimmed);
+    if (c)
+        return { kind: "cron", expression: c[1], dialect: "aws" };
+    return undefined;
+}
+/** Throws a clear, located error if `s` isn't a valid schedule. */
+export function assertSchedule(s, where) {
+    if (s.kind === "rate") {
+        if (!Number.isInteger(s.value) || s.value < 1) {
+            throw new Error(`Invalid schedule at ${where}: rate value must be a positive integer, got ${s.value}.`);
+        }
+        return;
+    }
+    // Only the "aws" cron dialect exists today; others land with their providers.
+    if (s.dialect !== "aws") {
+        throw new Error(`Invalid schedule at ${where}: unknown cron dialect "${s.dialect}".`);
+    }
+    if (!s.expression.trim()) {
+        throw new Error(`Invalid schedule at ${where}: empty cron expression.`);
+    }
+}
+/**
+ * Remap one AWS day-of-week field back to standard Unix numbering. AWS uses 1-7
+ * with 1=Sunday; cronstrue (like Unix cron) uses 0-6 with 0=Sunday — so numeric
+ * tokens shift down by one. Only the value/range segment is remapped; a trailing
+ * `/step` is a count, not a day, and passes through. Names (MON..SUN) pass through.
+ * Mirrors the inverse of `translateDow` in nest-schedule.ts.
+ */
+function awsDowToStandard(field) {
+    if (field === "*" || field === "?")
+        return "*";
+    return field
+        .split(",")
+        .map((part) => part
+        .split("/")
+        .map((seg, i) => i === 0
+        ? seg
+            .split("-")
+            .map((t) => {
+            const n = Number(t);
+            return /^\d+$/.test(t) && n >= 1 && n <= 7 ? String(n - 1) : t;
+        })
+            .join("-")
+        : seg)
+        .join("/"))
+        .join(",");
+}
+/**
+ * Convert laranja's stored AWS EventBridge cron (`min hour dom month dow [year]`,
+ * with `?` placeholders and AWS day-of-week numbering) into a standard 5-field
+ * Unix expression (`*` placeholders, 0=Sunday) that cronstrue understands. The
+ * inverse of the lowering `nestCronToSchedule` performs. Returns the input
+ * untouched for anything that isn't 5- or 6-field, so the caller can fall back.
+ */
+function awsCronToStandard(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5 && parts.length !== 6)
+        return expr;
+    const [minute, hour, dom, month, dow] = parts; // parts[5] (year) is dropped
+    return [minute, hour, dom === "?" ? "*" : dom, month, awsDowToStandard(dow)].join(" ");
+}
+/**
+ * Human-readable description of a Schedule — the single source of truth for how a
+ * schedule is shown to a user (the CLI `plan` table and the dashboard both call
+ * this, so the wording never drifts). `rate` renders structurally; `cron` is
+ * normalized from our AWS dialect to standard Unix cron and handed to cronstrue.
+ * Anything cronstrue can't parse falls back to the raw expression, so we never
+ * show a misleading label.
+ *
+ * @example describeSchedule({ kind: "rate", value: 5, unit: "minute" }) // "Every 5 minutes"
+ * @example describeSchedule({ kind: "cron", expression: "* * * * ? *", dialect: "aws" }) // "Every minute"
+ */
+export function describeSchedule(schedule) {
+    if (schedule.kind === "rate") {
+        return schedule.value === 1
+            ? `Every ${schedule.unit}`
+            : `Every ${schedule.value} ${schedule.unit}s`;
+    }
+    const standard = awsCronToStandard(schedule.expression);
+    try {
+        return cronstrue.toString(standard, { throwExceptionOnParseError: true, verbose: false });
+    }
+    catch {
+        return schedule.expression;
+    }
+}
+//# sourceMappingURL=schedule.js.map

package/dist/schedule.js.map

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

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@alzulejos/laranja-core",
+  "version": "0.2.4",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "cronstrue": "^3.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}