@lafken/schedule 0.6.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aníbal Emilio Jorquera Cornejo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @lafken/schedule
+
+`@lafken/schedule` simplifies the creation and management of Amazon EventBridge scheduled rules (Cron jobs) and their integration with AWS Lambda. It provides decorators to define scheduled tasks using standard cron expressions or structured time objects.
+
+## Installation
+
+```bash
+npm install @lafken/schedule
+```
+
+## Configuration
+
+Add the `ScheduleResolver` from the `@lafken/schedule/resolver` library to your application configuration.
+
+```typescript
+import { ScheduleResolver } from '@lafken/schedule/resolver';
+
+createApp({
+  name: 'awesome-app',
+  resolvers: [
+    new ScheduleResolver(),
+  ],
+  ...
+});
+
+// ...
+
+@Schedule()
+class GreetingSchedule {
+  // ...
+}
+
+const greetingModule = createModule({
+  name: 'greeting',
+  resources: [
+    GreetingSchedule
+  ]
+});
+
+```
+
+## Features
+
+### Defining a Schedule Resource
+
+Use the `@Schedule` decorator to define a class that contains scheduled tasks.
+
+```typescript
+import { Schedule, Cron } from '@lafken/schedule';
+
+@Schedule()
+export class DataSyncService {
+  // ... cron handlers
+}
+```
+
+### Defining Cron Tasks
+
+Use the `@Cron` decorator to define a method as a scheduled task. You can configure the schedule using a standard cron string or a structured object.
+
+#### Using Cron Strings
+
+You can use standard AWS cron expressions: `cron(Minutes Hours Day-of-month Month Day-of-week Year)`.
+
+```typescript
+@Cron({
+  schedule: 'cron(0 12 * * ? *)', // Run every day at 12:00 UTC
+})
+dailySync() {
+  console.log('Running daily sync...');
+}
+```
+
+#### Using Structured Schedule Objects
+
+You can also define the schedule using a readable object format.
+
+```typescript
+@Cron({
+  schedule: {
+    minute: '0',
+    hour: '8',
+    weekDay: 'MON-FRI',
+  },
+})
+weekdayStart() {
+  console.log('Starting weekday operations...');
+}
+```

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './main';
+export * from './resolver';

package/lib/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./main"), exports);
+__exportStar(require("./resolver"), exports);

package/lib/main/index.d.ts

@@ -0,0 +1 @@
+export * from './schedule';

package/lib/main/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schedule"), exports);

package/lib/main/schedule/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schedule';
+export * from './schedule.types';

package/lib/main/schedule/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schedule"), exports);
+__exportStar(require("./schedule.types"), exports);

package/lib/main/schedule/schedule.d.ts

@@ -0,0 +1,4 @@
+import type { EventCronProps } from './schedule.types';
+export declare const RESOURCE_TYPE: "CRON";
+export declare const Schedule: (props?: import("@lafken/common").ResourceProps | undefined) => (constructor: Function) => void;
+export declare const Cron: (props: EventCronProps) => (target: any, methodName: string, descriptor: PropertyDescriptor) => any;

package/lib/main/schedule/schedule.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cron = exports.Schedule = exports.RESOURCE_TYPE = void 0;
+const common_1 = require("@lafken/common");
+exports.RESOURCE_TYPE = 'CRON';
+exports.Schedule = (0, common_1.createResourceDecorator)({
+    type: exports.RESOURCE_TYPE,
+    callerFileIndex: 5,
+});
+const Cron = (props) => (0, common_1.createLambdaDecorator)({
+    getLambdaMetadata: (props, methodName) => ({
+        ...props,
+        name: methodName,
+    }),
+})(props);
+exports.Cron = Cron;

package/lib/main/schedule/schedule.types.d.ts

@@ -0,0 +1,42 @@
+import type { LambdaMetadata } from '@lafken/common';
+type ScheduleExpressions = number | '*' | '?' | (string & {});
+export interface ScheduleTime {
+    day?: ScheduleExpressions;
+    hour?: ScheduleExpressions;
+    minute?: ScheduleExpressions;
+    month?: ScheduleExpressions;
+    weekDay?: ScheduleExpressions;
+    year?: ScheduleExpressions;
+}
+export interface EventCronProps {
+    /**
+     * Maximum event age.
+     *
+     * Specifies the maximum age of an event that can be sent to the rule's targets.
+     * Events older than this duration will be discarded.
+     */
+    maxEventAge?: number;
+    /**
+     * Retry attempts for failed events.
+     *
+     * Specifies the maximum number of times EventBridge will retry sending
+     * an event to the target if the initial attempt fails.
+     */
+    retryAttempts?: number;
+    /**
+     * Schedule for the EventBridge rule.
+     *
+     * Defines when the rule should trigger, either using a cron expression
+     * or a structured schedule object. This allows for time-based Lambda invocation
+     *
+     * You can provide:
+     * - A cron string in the standard AWS format: `cron(* * * * * *)`
+     * - A `ScheduleTime` object to specify individual fields:
+     *   - `minute`, `hour`, `day`, `month`, `weekDay`, `year`
+     *   - Each field can be a number, '*', '?', a range `${number}-${number}`
+     */
+    schedule: string | ScheduleTime;
+}
+export interface EventCronMetadata extends LambdaMetadata, EventCronProps {
+}
+export {};

package/lib/main/schedule/schedule.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/resolver/cron/cron.d.ts

@@ -0,0 +1,16 @@
+import { CloudwatchEventRule } from '@cdktf/provider-aws/lib/cloudwatch-event-rule';
+import { type AppModule } from '@lafken/resolver';
+import type { CronProps } from './cron.types';
+declare const Cron_base: (new (...args: any[]) => {
+    isGlobal(module: import("@lafken/common").ModuleGlobalReferenceNames | (string & {}), id: string): void;
+    isDependent(resolveDependency: () => void): void;
+    readonly node: import("constructs").Node;
+    toString(): string;
+}) & typeof CloudwatchEventRule;
+export declare class Cron extends Cron_base {
+    private props;
+    constructor(scope: AppModule, id: string, props: CronProps);
+    addEventTarget(id: string): void;
+    private static buildScheduleExpression;
+}
+export {};

package/lib/resolver/cron/cron.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cron = void 0;
+const cloudwatch_event_rule_1 = require("@cdktf/provider-aws/lib/cloudwatch-event-rule");
+const cloudwatch_event_target_1 = require("@cdktf/provider-aws/lib/cloudwatch-event-target");
+const resolver_1 = require("@lafken/resolver");
+class Cron extends resolver_1.lafkenResource.make(cloudwatch_event_rule_1.CloudwatchEventRule) {
+    props;
+    constructor(scope, id, props) {
+        const { handler } = props;
+        super(scope, `${handler.name}-cron`, {
+            name: handler.name,
+            scheduleExpression: Cron.buildScheduleExpression(handler.schedule),
+        });
+        this.props = props;
+        this.isGlobal(scope.id, id);
+        this.addEventTarget(id);
+    }
+    addEventTarget(id) {
+        const { handler, resourceMetadata } = this.props;
+        const lambdaHandler = new resolver_1.LambdaHandler(this, `${handler.name}-${resourceMetadata.name}`, {
+            ...handler,
+            originalName: resourceMetadata.originalName,
+            filename: resourceMetadata.filename,
+            foldername: resourceMetadata.foldername,
+            suffix: 'event',
+            principal: 'events.amazonaws.com',
+        });
+        new cloudwatch_event_target_1.CloudwatchEventTarget(this, `${id}-event-target`, {
+            rule: this.name,
+            arn: lambdaHandler.arn,
+            retryPolicy: {
+                maximumRetryAttempts: handler.retryAttempts,
+                maximumEventAgeInSeconds: handler.maxEventAge,
+            },
+        });
+    }
+    static buildScheduleExpression(schedule) {
+        if (typeof schedule === 'string') {
+            return `cron(${schedule})`;
+        }
+        const { minute = '*', hour = '*', day = '*', month = '*', year = '*', weekDay = '*', } = schedule;
+        let dayValue;
+        let weekDayValue;
+        if (day && day !== '*' && day !== '?') {
+            dayValue = day.toString();
+            weekDayValue = '?';
+        }
+        else if (weekDay && weekDay !== '*' && weekDay !== '?') {
+            dayValue = '?';
+            weekDayValue = weekDay.toString();
+        }
+        else {
+            dayValue = day?.toString() ?? '*';
+            weekDayValue = '?';
+        }
+        return `cron(${minute} ${hour} ${dayValue} ${month} ${weekDayValue} ${year})`;
+    }
+}
+exports.Cron = Cron;

package/lib/resolver/cron/cron.types.d.ts

@@ -0,0 +1,6 @@
+import type { ResourceMetadata } from '@lafken/common';
+import type { EventCronMetadata } from '../../main';
+export interface CronProps {
+    resourceMetadata: ResourceMetadata;
+    handler: EventCronMetadata;
+}

package/lib/resolver/cron/cron.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/resolver/index.d.ts

@@ -0,0 +1 @@
+export * from './resolver';

package/lib/resolver/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./resolver"), exports);

package/lib/resolver/resolver.d.ts

@@ -0,0 +1,6 @@
+import { type ClassResource } from '@lafken/common';
+import { type AppModule, type ResolverType } from '@lafken/resolver';
+export declare class ScheduleResolver implements ResolverType {
+    type: "CRON";
+    create(module: AppModule, resource: ClassResource): void;
+}

package/lib/resolver/resolver.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleResolver = void 0;
+const common_1 = require("@lafken/common");
+const resolver_1 = require("@lafken/resolver");
+const main_1 = require("../main");
+const cron_1 = require("./cron/cron");
+class ScheduleResolver {
+    type = main_1.RESOURCE_TYPE;
+    create(module, resource) {
+        const metadata = (0, common_1.getResourceMetadata)(resource);
+        const handlers = (0, common_1.getResourceHandlerMetadata)(resource);
+        resolver_1.lambdaAssets.initializeMetadata({
+            foldername: metadata.foldername,
+            filename: metadata.filename,
+            minify: metadata.minify,
+            className: metadata.originalName,
+            methods: handlers.map((handler) => handler.name),
+        });
+        for (const handler of handlers) {
+            const id = `${handler.name}-${metadata.name}`;
+            new cron_1.Cron(module, id, {
+                handler,
+                resourceMetadata: metadata,
+            });
+        }
+    }
+}
+exports.ScheduleResolver = ScheduleResolver;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lafken/schedule",
+  "version": "0.6.0",
+  "private": false,
+  "license": "MIT",
+  "exports": {
+    "./main": {
+      "import": "./lib/main/index.js",
+      "types": "./lib/main/index.d.ts",
+      "require": "./lib/main/index.js"
+    },
+    "./resolver": {
+      "import": "./lib/resolver/index.js",
+      "types": "./lib/resolver/index.d.ts",
+      "require": "./lib/resolver/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "main": [
+        "./lib/main/index.d.ts"
+      ],
+      "resolver": [
+        "./lib/resolver/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@cdktf/provider-aws": "21.22.0",
+    "cdktf": "0.21.0",
+    "constructs": "10.4.4",
+    "reflect-metadata": "0.2.2",
+    "@lafken/common": "0.6.0",
+    "@lafken/resolver": "0.6.0"
+  },
+  "devDependencies": {
+    "@jest/types": "^30.2.0",
+    "@types/jest": "30.0.0",
+    "jest": "30.2.0",
+    "ts-jest": "29.4.6",
+    "ts-node": "10.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc -p ./tsconfig.build.json",
+    "clean": "rm -rf ./lib",
+    "dev": "tsc -w",
+    "test": "jest",
+    "test:coverage": "jest --coverage"
+  }
+}