@alzulejos/laranja-core 0.2.4

package/dist/ir.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The Infra IR is the serializable boundary between the front half of the tool
+ * (scanning user source) and the back half (generating + deploying CDK).
+ *
+ * Everything downstream depends only on this shape — never on ts-morph nodes or
+ * the user's source tree. This is what lets us later move CDK synth server-side
+ * (free tier) vs. local eject (paid) without touching the scanner.
+ */
+import type { Schedule } from "./schedule.js";
+export type Framework = "express" | "nest";
+/**
+ * Target cloud. Only "aws" is implemented today; the rest are planned. The field
+ * lives in the IR so server-side synth can dispatch to the right back-half and
+ * configs written today stay forward-compatible.
+ */
+export type CloudProvider = "aws" | "azure" | "gcp" | "cloudflare";
+/**
+ * Runtime config shared by every function-backed resource — the HTTP proxy and
+ * each cron/queue consumer all become a function, so they all carry this.
+ *
+ * Sourced from the config's global `compute` defaults, overridden per-resource by
+ * `resources[id]`; the scanner merges the two and attaches the result here. Each
+ * field maps to a real knob on AWS Lambda, GCP Cloud Functions, and Azure
+ * Functions — except the two flagged AWS-honest, which a future provider union
+ * rejects on non-AWS targets rather than fake-abstracting.
+ */
+export interface ComputeConfig {
+    /** Memory in MB. */
+    memory?: number;
+    /** Max wall-clock seconds per invocation. */
+    timeout?: number;
+    /** Cap on simultaneous executions (AWS reserved concurrency / GCP maxInstances). */
+    maxConcurrency?: number;
+    /** CPU architecture. AWS-honest. */
+    architecture?: "x86_64" | "arm64";
+    /** Log retention in days. AWS-honest (CloudWatch log group). */
+    logRetention?: number;
+}
+/** A point in the user's source, for diagnostics / visibility. e.g. "src/jobs.ts:12" */
+export type SourceLocation = string;
+/** A decorated method on a class: `class Jobs { @Cron() method() {} }`. */
+export interface MethodTarget {
+    style: "method";
+    /** Project-relative path to the file declaring the class. */
+    file: string;
+    /** Class the method lives on. */
+    className: string;
+    /** Method name to invoke. */
+    method: string;
+    /** Source location for diagnostics. */
+    source: SourceLocation;
+}
+/** An exported function registered via `cron(...)` / `queue(...)`. */
+export interface FunctionTarget {
+    style: "function";
+    /** Project-relative path to the file declaring the function. */
+    file: string;
+    /** Exported name of the handler function to import. */
+    exportName: string;
+    /** Source location for diagnostics. */
+    source: SourceLocation;
+}
+/**
+ * Reference to the user code that becomes an isolated Lambda. Either a method on
+ * a class (decorator style) or a standalone exported function (marker style).
+ */
+export type HandlerRef = MethodTarget | FunctionTarget;
+/** The natural handler name: method name (class style) or export name (function style). */
+export declare function handlerName(ref: HandlerRef): string;
+/** The id a handler gets when the user doesn't set an explicit one. */
+export declare function defaultHandlerId(ref: HandlerRef): string;
+/** Lambda label: the natural handler name, unless the user set a custom id. */
+export declare function handlerLabel(item: HandlerRef & {
+    id: string;
+}): string;
+/** A discovered HTTP route. In v1 all routes are served by ONE proxy Lambda; */
+/** routes are captured for visibility / validation / future per-route IAM. */
+export interface HttpRoute {
+    method: string;
+    path: string;
+    source: SourceLocation;
+}
+export interface HttpIR {
+    /** Project-relative module that exports the framework app (the proxy target). */
+    handlerEntry: string;
+    /** Named export of the app within `handlerEntry` (e.g. "app" or "default"). */
+    appExport: string;
+    routes: HttpRoute[];
+    /** Resolved compute config for the proxy function (keyed as "http" in `resources`). */
+    compute?: ComputeConfig;
+}
+/**
+ * A `workers(SomeModule)` marker — and, post‑consolidation, the ONE worker Lambda
+ * for that module. All of a module's method‑style `@Cron`/`@Queue` handlers run in
+ * this single function: it boots a standalone DI context
+ * (`NestFactory.createApplicationContext(module)`) once, and its generated shim
+ * routes each invocation (EventBridge → cron by id, SQS → queue by ARN) to the
+ * right provider method. Absent for Express (no DI) and workers‑free projects.
+ *
+ * A project may declare several — one per disjoint DI root (e.g. a queues module
+ * and a crons module) — so each worker Lambda boots only the graph it needs and
+ * pays a smaller cold start. Each method‑style cron/queue names its module via
+ * `workersId`; that is the function it belongs to.
+ */
+export interface WorkersIR {
+    /** Stable id — the module's class name; what handlers point `workersId` at, and
+     *  the asset/function key for this worker Lambda. */
+    id: string;
+    /** Project-relative module that exports `workers(SomeModule)`. */
+    handlerEntry: string;
+    /** Named export within that module (e.g. "default" or "jobs"). */
+    appExport: string;
+    /** Compute for this shared worker function — resolved from `resources[<module>]`
+     *  merged over the global `compute` default. Shared by every hosted handler. */
+    compute?: ComputeConfig;
+}
+/** @Cron(...) / cron(...) -> scheduled trigger -> its own Lambda. */
+export type CronIR = HandlerRef & {
+    /** Stable logical id, used for the CDK construct + function name. */
+    id: string;
+    /** Provider-neutral schedule; the back half lowers it to the target's syntax. */
+    schedule: Schedule;
+    /** IANA timezone for the schedule (needs EventBridge Scheduler, not Rules). */
+    timezone?: string;
+    /** Async-invoke retry attempts (AWS allows 0–2). */
+    retryAttempts?: number;
+    /** Max age (seconds) of an event before async retries are abandoned. */
+    maxEventAge?: number;
+    /** Dead-letter failed async invokes to another declared queue, referenced by id. */
+    dlq?: {
+        queue: string;
+    };
+    /** Resolved compute config for this cron's function. */
+    compute?: ComputeConfig;
+    /** Method-style Nest crons only: id of the WorkersIR DI root that owns this provider. */
+    workersId?: string;
+};
+/** @Queue({ name }) / queue(...) -> SQS queue -> its own consumer Lambda. */
+export type QueueIR = HandlerRef & {
+    id: string;
+    /** Queue name. A ".fifo" suffix or fifo:true marks a FIFO queue. */
+    name: string;
+    batchSize?: number;
+    fifo?: boolean;
+    /** FIFO content-based dedup (FIFO-only). Defaults to true for FIFO when unset. */
+    contentBasedDedup?: boolean;
+    /** Seconds a message stays hidden while being processed (AWS requires >= timeout). */
+    visibilityTimeout?: number;
+    /** Seconds to wait gathering a fuller batch before invoking the consumer. */
+    maxBatchingWindow?: number;
+    /** Report per-message failures so only failed items are retried, not the batch. */
+    reportBatchItemFailures?: boolean;
+    /** Seconds an undelivered message is retained on the source queue. */
+    messageRetention?: number;
+    /** Dead-letter after N failed receives to another declared queue, referenced by id. */
+    dlq?: {
+        maxReceiveCount: number;
+        queue: string;
+    };
+    /** Resolved compute config for this queue's consumer function. */
+    compute?: ComputeConfig;
+    /** Method-style Nest queues only: id of the WorkersIR DI root that owns this provider. */
+    workersId?: string;
+};
+export interface InfraIR {
+    app: {
+        name: string;
+        framework: Framework;
+        /** Target cloud. Defaults to "aws". */
+        provider: CloudProvider;
+        /** Deployment stage; part of resource names. */
+        stage: string;
+        /**
+         * Emit a per-app-stage monitoring dashboard. Provider-neutral; the back half
+         * maps it to its own primitives (CloudWatch dashboard on AWS). Defaults to true.
+         */
+        monitoring: boolean;
+        /** Project-relative app entry (same as http.handlerEntry). Absent for workers-only apps. */
+        entry?: string;
+    };
+    /** Absent when there's no `http()` marker — a workers-only deployment. */
+    http?: HttpIR;
+    /**
+     * Nest DI roots for class-based workers; absent for Express / function-only apps.
+     * One entry per `workers()` marker — a project can run disjoint DI graphs so each
+     * worker Lambda boots only its own module (smaller cold starts). Method-style
+     * crons/queues bind to a root via `workersId`.
+     */
+    workers?: WorkersIR[];
+    crons: CronIR[];
+    queues: QueueIR[];
+    /**
+     * Static env from config, injected into every Lambda as literal name->value.
+     * Crosses the wire to the server as-is. Secrets handling comes later.
+     */
+    env: Record<string, string>;
+    /**
+     * Env var NAMES discovered from `env("NAME")` calls in user code (names only,
+     * never values). The client resolves each from `process.env` at deploy time
+     * and injects it into every Lambda — so values stay on the developer's machine
+     * (and out of the IR, the wire, and the server). Sorted + de-duplicated.
+     */
+    envKeys: string[];
+}

package/dist/ir.js

@@ -0,0 +1,21 @@
+/**
+ * The Infra IR is the serializable boundary between the front half of the tool
+ * (scanning user source) and the back half (generating + deploying CDK).
+ *
+ * Everything downstream depends only on this shape — never on ts-morph nodes or
+ * the user's source tree. This is what lets us later move CDK synth server-side
+ * (free tier) vs. local eject (paid) without touching the scanner.
+ */
+/** The natural handler name: method name (class style) or export name (function style). */
+export function handlerName(ref) {
+    return ref.style === "function" ? ref.exportName : ref.method;
+}
+/** The id a handler gets when the user doesn't set an explicit one. */
+export function defaultHandlerId(ref) {
+    return ref.style === "function" ? ref.exportName : `${ref.className}-${ref.method}`;
+}
+/** Lambda label: the natural handler name, unless the user set a custom id. */
+export function handlerLabel(item) {
+    return item.id === defaultHandlerId(item) ? handlerName(item) : item.id;
+}
+//# sourceMappingURL=ir.js.map

package/dist/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../src/ir.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqEH,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAC,GAAe;IACzC,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;AAChE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,gBAAgB,CAAC,GAAe;IAC9C,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;AACtF,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,IAAiC;IAC5D,OAAO,IAAI,CAAC,EAAE,KAAK,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1E,CAAC"}

package/dist/nest-schedule.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `@nestjs/schedule` compatibility. A Nest user should be able to swap the
+ * `@Cron` import from `@nestjs/schedule` to laranja and keep their existing
+ * schedules — so we accept node-cron expressions (and the `CronExpression` enum)
+ * and translate them into laranja's neutral `Schedule` here, in the front half.
+ *
+ * We lower to an AWS EventBridge `cron(...)` expression (the only dialect the back
+ * half understands today). node-cron and EventBridge cron differ in real ways —
+ * sub-minute granularity, day-of-week numbering, and the mutually-exclusive
+ * day-of-month/day-of-week rule (EventBridge requires exactly one of them to be
+ * `?`). So this both TRANSLATES what maps and REJECTS, loudly and with a source
+ * location, what EventBridge physically cannot honor. We never silently round a
+ * schedule to a different cadence — a job the user thinks runs every 30s must not
+ * quietly become every minute.
+ */
+import { type Schedule } from "./schedule.js";
+/**
+ * Mirror of `@nestjs/schedule`'s `CronExpression` enum (values copied verbatim),
+ * re-exported so users who `import { CronExpression }` can point it at laranja and
+ * keep compiling. The scanner resolves `CronExpression.MEMBER` to its string value
+ * through this same object, so the two stay in lockstep by construction.
+ */
+export declare enum CronExpression {
+    EVERY_SECOND = "* * * * * *",
+    EVERY_5_SECONDS = "*/5 * * * * *",
+    EVERY_10_SECONDS = "*/10 * * * * *",
+    EVERY_30_SECONDS = "*/30 * * * * *",
+    EVERY_MINUTE = "*/1 * * * *",
+    EVERY_5_MINUTES = "0 */5 * * * *",
+    EVERY_10_MINUTES = "0 */10 * * * *",
+    EVERY_30_MINUTES = "0 */30 * * * *",
+    EVERY_HOUR = "0 0-23/1 * * *",
+    EVERY_2_HOURS = "0 0-23/2 * * *",
+    EVERY_3_HOURS = "0 0-23/3 * * *",
+    EVERY_4_HOURS = "0 0-23/4 * * *",
+    EVERY_5_HOURS = "0 0-23/5 * * *",
+    EVERY_6_HOURS = "0 0-23/6 * * *",
+    EVERY_7_HOURS = "0 0-23/7 * * *",
+    EVERY_8_HOURS = "0 0-23/8 * * *",
+    EVERY_9_HOURS = "0 0-23/9 * * *",
+    EVERY_10_HOURS = "0 0-23/10 * * *",
+    EVERY_11_HOURS = "0 0-23/11 * * *",
+    EVERY_12_HOURS = "0 0-23/12 * * *",
+    EVERY_DAY_AT_1AM = "0 01 * * *",
+    EVERY_DAY_AT_2AM = "0 02 * * *",
+    EVERY_DAY_AT_3AM = "0 03 * * *",
+    EVERY_DAY_AT_4AM = "0 04 * * *",
+    EVERY_DAY_AT_5AM = "0 05 * * *",
+    EVERY_DAY_AT_6AM = "0 06 * * *",
+    EVERY_DAY_AT_7AM = "0 07 * * *",
+    EVERY_DAY_AT_8AM = "0 08 * * *",
+    EVERY_DAY_AT_9AM = "0 09 * * *",
+    EVERY_DAY_AT_10AM = "0 10 * * *",
+    EVERY_DAY_AT_11AM = "0 11 * * *",
+    EVERY_DAY_AT_NOON = "0 12 * * *",
+    EVERY_DAY_AT_1PM = "0 13 * * *",
+    EVERY_DAY_AT_2PM = "0 14 * * *",
+    EVERY_DAY_AT_3PM = "0 15 * * *",
+    EVERY_DAY_AT_4PM = "0 16 * * *",
+    EVERY_DAY_AT_5PM = "0 17 * * *",
+    EVERY_DAY_AT_6PM = "0 18 * * *",
+    EVERY_DAY_AT_7PM = "0 19 * * *",
+    EVERY_DAY_AT_8PM = "0 20 * * *",
+    EVERY_DAY_AT_9PM = "0 21 * * *",
+    EVERY_DAY_AT_10PM = "0 22 * * *",
+    EVERY_DAY_AT_11PM = "0 23 * * *",
+    EVERY_DAY_AT_MIDNIGHT = "0 0 * * *",
+    EVERY_WEEK = "0 0 * * 0",
+    EVERY_WEEKDAY = "0 0 * * 1-5",
+    EVERY_WEEKEND = "0 0 * * 6,0",
+    EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT = "0 0 1 * *",
+    EVERY_1ST_DAY_OF_MONTH_AT_NOON = "0 12 1 * *",
+    EVERY_2ND_HOUR = "0 */2 * * *",
+    EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM = "0 1-23/2 * * *",
+    EVERY_2ND_MONTH = "0 0 1 */2 *",
+    EVERY_QUARTER = "0 0 1 */3 *",
+    EVERY_6_MONTHS = "0 0 1 */6 *",
+    EVERY_YEAR = "0 0 1 1 *",
+    EVERY_30_MINUTES_BETWEEN_9AM_AND_5PM = "0 */30 9-17 * * *",
+    EVERY_30_MINUTES_BETWEEN_9AM_AND_6PM = "0 */30 9-18 * * *",
+    EVERY_30_MINUTES_BETWEEN_10AM_AND_7PM = "0 */30 10-19 * * *",
+    MONDAY_TO_FRIDAY_AT_1AM = "0 0 01 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_2AM = "0 0 02 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_3AM = "0 0 03 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_4AM = "0 0 04 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_5AM = "0 0 05 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_6AM = "0 0 06 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_7AM = "0 0 07 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_8AM = "0 0 08 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_9AM = "0 0 09 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_09_30AM = "0 30 09 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_10AM = "0 0 10 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_11AM = "0 0 11 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_11_30AM = "0 30 11 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_12PM = "0 0 12 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_1PM = "0 0 13 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_2PM = "0 0 14 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_3PM = "0 0 15 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_4PM = "0 0 16 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_5PM = "0 0 17 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_6PM = "0 0 18 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_7PM = "0 0 19 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_8PM = "0 0 20 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_9PM = "0 0 21 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_10PM = "0 0 22 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_11PM = "0 0 23 * * 1-5"
+}
+/** Every enum string keyed by member name — used by the scanner to fold `CronExpression.X`. */
+export declare const CRON_EXPRESSION_VALUES: Record<string, string>;
+/**
+ * Translate a node-cron expression (5-field `min hour dom month dow`, or 6-field
+ * with a leading seconds column) into a neutral AWS-dialect cron `Schedule`.
+ * Throws a clear, located error for anything EventBridge can't express.
+ *
+ * NOTE on the seconds column: EventBridge has a 1-minute floor, so the only
+ * seconds value we accept is `0` ("at the top of the minute"), which we drop.
+ * Any other seconds value is a sub-minute or second-offset schedule and is
+ * rejected rather than approximated.
+ */
+export declare function nestCronToSchedule(expr: string, where: string): Schedule;
+/**
+ * Translate `@Interval(ms)` into a neutral rate `Schedule`. Unlike `@Cron`,
+ * `@Interval` genuinely means "every N milliseconds", which maps to EventBridge's
+ * clock-independent `rate(...)`. EventBridge's floor is one minute, so the
+ * interval must be a whole number of minutes.
+ */
+export declare function intervalToSchedule(ms: number, where: string): Schedule;

package/dist/nest-schedule.js

@@ -0,0 +1,222 @@
+/**
+ * `@nestjs/schedule` compatibility. A Nest user should be able to swap the
+ * `@Cron` import from `@nestjs/schedule` to laranja and keep their existing
+ * schedules — so we accept node-cron expressions (and the `CronExpression` enum)
+ * and translate them into laranja's neutral `Schedule` here, in the front half.
+ *
+ * We lower to an AWS EventBridge `cron(...)` expression (the only dialect the back
+ * half understands today). node-cron and EventBridge cron differ in real ways —
+ * sub-minute granularity, day-of-week numbering, and the mutually-exclusive
+ * day-of-month/day-of-week rule (EventBridge requires exactly one of them to be
+ * `?`). So this both TRANSLATES what maps and REJECTS, loudly and with a source
+ * location, what EventBridge physically cannot honor. We never silently round a
+ * schedule to a different cadence — a job the user thinks runs every 30s must not
+ * quietly become every minute.
+ */
+import { rate } from "./schedule.js";
+/**
+ * Mirror of `@nestjs/schedule`'s `CronExpression` enum (values copied verbatim),
+ * re-exported so users who `import { CronExpression }` can point it at laranja and
+ * keep compiling. The scanner resolves `CronExpression.MEMBER` to its string value
+ * through this same object, so the two stay in lockstep by construction.
+ */
+export var CronExpression;
+(function (CronExpression) {
+    CronExpression["EVERY_SECOND"] = "* * * * * *";
+    CronExpression["EVERY_5_SECONDS"] = "*/5 * * * * *";
+    CronExpression["EVERY_10_SECONDS"] = "*/10 * * * * *";
+    CronExpression["EVERY_30_SECONDS"] = "*/30 * * * * *";
+    CronExpression["EVERY_MINUTE"] = "*/1 * * * *";
+    CronExpression["EVERY_5_MINUTES"] = "0 */5 * * * *";
+    CronExpression["EVERY_10_MINUTES"] = "0 */10 * * * *";
+    CronExpression["EVERY_30_MINUTES"] = "0 */30 * * * *";
+    CronExpression["EVERY_HOUR"] = "0 0-23/1 * * *";
+    CronExpression["EVERY_2_HOURS"] = "0 0-23/2 * * *";
+    CronExpression["EVERY_3_HOURS"] = "0 0-23/3 * * *";
+    CronExpression["EVERY_4_HOURS"] = "0 0-23/4 * * *";
+    CronExpression["EVERY_5_HOURS"] = "0 0-23/5 * * *";
+    CronExpression["EVERY_6_HOURS"] = "0 0-23/6 * * *";
+    CronExpression["EVERY_7_HOURS"] = "0 0-23/7 * * *";
+    CronExpression["EVERY_8_HOURS"] = "0 0-23/8 * * *";
+    CronExpression["EVERY_9_HOURS"] = "0 0-23/9 * * *";
+    CronExpression["EVERY_10_HOURS"] = "0 0-23/10 * * *";
+    CronExpression["EVERY_11_HOURS"] = "0 0-23/11 * * *";
+    CronExpression["EVERY_12_HOURS"] = "0 0-23/12 * * *";
+    CronExpression["EVERY_DAY_AT_1AM"] = "0 01 * * *";
+    CronExpression["EVERY_DAY_AT_2AM"] = "0 02 * * *";
+    CronExpression["EVERY_DAY_AT_3AM"] = "0 03 * * *";
+    CronExpression["EVERY_DAY_AT_4AM"] = "0 04 * * *";
+    CronExpression["EVERY_DAY_AT_5AM"] = "0 05 * * *";
+    CronExpression["EVERY_DAY_AT_6AM"] = "0 06 * * *";
+    CronExpression["EVERY_DAY_AT_7AM"] = "0 07 * * *";
+    CronExpression["EVERY_DAY_AT_8AM"] = "0 08 * * *";
+    CronExpression["EVERY_DAY_AT_9AM"] = "0 09 * * *";
+    CronExpression["EVERY_DAY_AT_10AM"] = "0 10 * * *";
+    CronExpression["EVERY_DAY_AT_11AM"] = "0 11 * * *";
+    CronExpression["EVERY_DAY_AT_NOON"] = "0 12 * * *";
+    CronExpression["EVERY_DAY_AT_1PM"] = "0 13 * * *";
+    CronExpression["EVERY_DAY_AT_2PM"] = "0 14 * * *";
+    CronExpression["EVERY_DAY_AT_3PM"] = "0 15 * * *";
+    CronExpression["EVERY_DAY_AT_4PM"] = "0 16 * * *";
+    CronExpression["EVERY_DAY_AT_5PM"] = "0 17 * * *";
+    CronExpression["EVERY_DAY_AT_6PM"] = "0 18 * * *";
+    CronExpression["EVERY_DAY_AT_7PM"] = "0 19 * * *";
+    CronExpression["EVERY_DAY_AT_8PM"] = "0 20 * * *";
+    CronExpression["EVERY_DAY_AT_9PM"] = "0 21 * * *";
+    CronExpression["EVERY_DAY_AT_10PM"] = "0 22 * * *";
+    CronExpression["EVERY_DAY_AT_11PM"] = "0 23 * * *";
+    CronExpression["EVERY_DAY_AT_MIDNIGHT"] = "0 0 * * *";
+    CronExpression["EVERY_WEEK"] = "0 0 * * 0";
+    CronExpression["EVERY_WEEKDAY"] = "0 0 * * 1-5";
+    CronExpression["EVERY_WEEKEND"] = "0 0 * * 6,0";
+    CronExpression["EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT"] = "0 0 1 * *";
+    CronExpression["EVERY_1ST_DAY_OF_MONTH_AT_NOON"] = "0 12 1 * *";
+    CronExpression["EVERY_2ND_HOUR"] = "0 */2 * * *";
+    CronExpression["EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM"] = "0 1-23/2 * * *";
+    CronExpression["EVERY_2ND_MONTH"] = "0 0 1 */2 *";
+    CronExpression["EVERY_QUARTER"] = "0 0 1 */3 *";
+    CronExpression["EVERY_6_MONTHS"] = "0 0 1 */6 *";
+    CronExpression["EVERY_YEAR"] = "0 0 1 1 *";
+    CronExpression["EVERY_30_MINUTES_BETWEEN_9AM_AND_5PM"] = "0 */30 9-17 * * *";
+    CronExpression["EVERY_30_MINUTES_BETWEEN_9AM_AND_6PM"] = "0 */30 9-18 * * *";
+    CronExpression["EVERY_30_MINUTES_BETWEEN_10AM_AND_7PM"] = "0 */30 10-19 * * *";
+    CronExpression["MONDAY_TO_FRIDAY_AT_1AM"] = "0 0 01 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_2AM"] = "0 0 02 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_3AM"] = "0 0 03 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_4AM"] = "0 0 04 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_5AM"] = "0 0 05 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_6AM"] = "0 0 06 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_7AM"] = "0 0 07 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_8AM"] = "0 0 08 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_9AM"] = "0 0 09 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_09_30AM"] = "0 30 09 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_10AM"] = "0 0 10 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_11AM"] = "0 0 11 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_11_30AM"] = "0 30 11 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_12PM"] = "0 0 12 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_1PM"] = "0 0 13 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_2PM"] = "0 0 14 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_3PM"] = "0 0 15 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_4PM"] = "0 0 16 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_5PM"] = "0 0 17 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_6PM"] = "0 0 18 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_7PM"] = "0 0 19 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_8PM"] = "0 0 20 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_9PM"] = "0 0 21 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_10PM"] = "0 0 22 * * 1-5";
+    CronExpression["MONDAY_TO_FRIDAY_AT_11PM"] = "0 0 23 * * 1-5";
+})(CronExpression || (CronExpression = {}));
+/** Every enum string keyed by member name — used by the scanner to fold `CronExpression.X`. */
+export const CRON_EXPRESSION_VALUES = Object.fromEntries(Object.entries(CronExpression).filter(([, v]) => typeof v === "string"));
+/**
+ * Strip leading zeros from every numeric token in a field (`09` -> `9`, `01-05`
+ * -> `1-5`). The Nest enum zero-pads hours and days, which EventBridge's parser
+ * rejects. Non-numeric tokens (`*`, `?`, `,`, `-`, `/`, names) are left intact.
+ */
+function stripZeros(field) {
+    return field.replace(/\d+/g, (d) => String(parseInt(d, 10)));
+}
+/**
+ * Collapse a full-domain range-step (`0-23/2`) or full range (`0-59`) to the `*`
+ * form EventBridge prefers, and drop a redundant `/1` step. Leaves anything else
+ * (explicit values, lists, partial ranges) untouched. Assumes zeros already stripped.
+ */
+function normalizeField(field, min, max) {
+    const full = new RegExp(`^${min}-${max}(?:/(\\d+))?$`);
+    const m = full.exec(field);
+    if (m)
+        return m[1] && m[1] !== "1" ? `*/${m[1]}` : "*";
+    const starStep = /^\*\/1$/.exec(field);
+    if (starStep)
+        return "*";
+    return field;
+}
+/** Translate one numeric day-of-week token from Unix (0-7, 0/7=Sun) to AWS (1-7, 1=Sun). */
+function translateDowNumber(token) {
+    if (!/^\d+$/.test(token))
+        return token; // names (MON..SUN) pass through — AWS accepts them
+    const n = Number(token);
+    if (n < 0 || n > 7)
+        return token; // out of range: let AWS reject it with its own message
+    return String((n % 7) + 1);
+}
+/** Apply the Unix→AWS day-of-week remap across ranges (`1-5`) and lists (`6,0`). */
+function translateDow(field) {
+    if (field === "*" || field === "?")
+        return field;
+    return field
+        .split(",")
+        .map((part) => part
+        .split("/")
+        .map((seg, i) => 
+    // Only the value/range segment is remapped; a trailing `/step` is numeric, left as-is.
+    i === 0 ? seg.split("-").map(translateDowNumber).join("-") : seg)
+        .join("/"))
+        .join(",");
+}
+const SPECIFIED = (v) => v !== "*" && v !== "?";
+/**
+ * Translate a node-cron expression (5-field `min hour dom month dow`, or 6-field
+ * with a leading seconds column) into a neutral AWS-dialect cron `Schedule`.
+ * Throws a clear, located error for anything EventBridge can't express.
+ *
+ * NOTE on the seconds column: EventBridge has a 1-minute floor, so the only
+ * seconds value we accept is `0` ("at the top of the minute"), which we drop.
+ * Any other seconds value is a sub-minute or second-offset schedule and is
+ * rejected rather than approximated.
+ */
+export function nestCronToSchedule(expr, where) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5 && parts.length !== 6) {
+        throw new Error(`schedule at ${where}: "${expr}" is not a 5- or 6-field cron expression.`);
+    }
+    let fields = parts;
+    if (parts.length === 6) {
+        const seconds = parts[0];
+        if (seconds !== "0") {
+            throw new Error(`schedule at ${where}: "${expr}" uses a sub-minute seconds field ("${seconds}"). ` +
+                `EventBridge has a 1-minute minimum granularity, so only a seconds value of "0" is supported.`);
+        }
+        fields = parts.slice(1);
+    }
+    let dayOfMonth = stripZeros(fields[2]);
+    const month = stripZeros(fields[3]);
+    let dayOfWeek = translateDow(fields[4]);
+    const minute = normalizeField(stripZeros(fields[0]), 0, 59);
+    const hour = normalizeField(stripZeros(fields[1]), 0, 23);
+    // EventBridge forbids specifying BOTH day-of-month and day-of-week; exactly one
+    // must be `?`. Unix cron allows `* * `, so we pick the `?` for whichever side the
+    // user didn't constrain — and reject the genuinely-ambiguous "both constrained".
+    const domSpec = SPECIFIED(dayOfMonth);
+    const dowSpec = SPECIFIED(dayOfWeek);
+    if (domSpec && dowSpec) {
+        throw new Error(`schedule at ${where}: "${expr}" constrains both day-of-month and day-of-week. ` +
+            `EventBridge cron can't AND them — set one of the two to "*".`);
+    }
+    if (dowSpec)
+        dayOfMonth = "?";
+    else
+        dayOfWeek = "?";
+    return {
+        kind: "cron",
+        expression: `${minute} ${hour} ${dayOfMonth} ${month} ${dayOfWeek} *`,
+        dialect: "aws",
+    };
+}
+/**
+ * Translate `@Interval(ms)` into a neutral rate `Schedule`. Unlike `@Cron`,
+ * `@Interval` genuinely means "every N milliseconds", which maps to EventBridge's
+ * clock-independent `rate(...)`. EventBridge's floor is one minute, so the
+ * interval must be a whole number of minutes.
+ */
+export function intervalToSchedule(ms, where) {
+    if (!Number.isInteger(ms) || ms <= 0) {
+        throw new Error(`@Interval at ${where}: interval must be a positive integer of milliseconds, got ${ms}.`);
+    }
+    if (ms % 60000 !== 0) {
+        throw new Error(`@Interval at ${where}: ${ms}ms is not a whole number of minutes. ` +
+            `EventBridge has a 1-minute minimum granularity, so intervals must be multiples of 60000ms.`);
+    }
+    return rate(ms / 60000, "minutes");
+}
+//# sourceMappingURL=nest-schedule.js.map

package/dist/nest-schedule.js.map

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

package/dist/schedule.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+/** Units accepted by the `rate()` builder (singular or plural, for ergonomics). */
+export type RateUnit = "minute" | "minutes" | "hour" | "hours" | "day" | "days";
+/** Canonical singular unit stored in the IR. */
+export type ScheduleUnit = "minute" | "hour" | "day";
+/** Provider-neutral schedule stored in the IR. */
+export type Schedule = {
+    kind: "rate";
+    value: number;
+    unit: ScheduleUnit;
+} | {
+    kind: "cron";
+    expression: string;
+    dialect: "aws";
+};
+/** Anything accepted where a schedule is expected: structured, or a raw string. */
+export type ScheduleInput = Schedule | string;
+/**
+ * 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 declare function rate(value: number, unit: RateUnit): Schedule;
+/**
+ * Shorthand for `rate(1, unit)`.
+ * @example every("day") // { kind: "rate", value: 1, unit: "day" }
+ */
+export declare function every(unit: ScheduleUnit): Schedule;
+/**
+ * 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 declare function parseScheduleString(s: string): Schedule | undefined;
+/** Throws a clear, located error if `s` isn't a valid schedule. */
+export declare function assertSchedule(s: Schedule, where: string): void;
+/**
+ * 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 declare function describeSchedule(schedule: Schedule): string;