@lafken/event 0.6.4 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @lafken/event
 
-`@lafken/event` helps you create listeners for EventBridge events and trigger Lambda functions to process those events. It provides decorators that simplify configuring event listeners—whether for custom events or built-in sources like S3 and DynamoDB.
+Listen and react to Amazon EventBridge events using TypeScript decorators. `@lafken/event` lets you define event rules with pattern-based filtering and automatically connects them to Lambda functions. Supports custom events, S3 notifications, and DynamoDB stream events.
 
 ## Installation
 
@@ -8,88 +8,104 @@
 npm install @lafken/event
 ```
 
-## Configuration
+## Getting Started
 
-Add the EventRuleResolver from the @lafken/event/resolver library.
-In its configuration, you can define one or more event buses. If no event bus is provided, the default EventBridge bus will be used for communication.
+Define an event rule class with `@EventRule`, add `@Rule` methods with event patterns, and register everything through `EventRuleResolver`:
 
 ```typescript
-import { ApiResolver } from '@lafken/event/resolver';
+import { createApp, createModule } from '@lafken/main';
+import { EventRuleResolver } from '@lafken/event/resolver';
+import { EventRule, Rule, Event } from '@lafken/event/main';
 
+// 1. Define event handlers
+@EventRule()
+export class OrderEvents {
+  @Rule({
+    pattern: {
+      source: 'orders',
+      detailType: ['order.created'],
+    },
+  })
+  onOrderCreated(@Event() event: any) {
+    console.log('New order:', event);
+  }
+}
+
+// 2. Register in a module
+const orderModule = createModule({
+  name: 'order',
+  resources: [OrderEvents],
+});
+
+// 3. Add the resolver to the app
 createApp({
-  name: 'awesome-app',
-  resolvers: [
-    new EventRuleResolver({
-      busName: 'awesome-event-bus',
-      extend: ({ eventBus }) => {
-        // ... extend the event bus
-      },
-    }),
-  ],
-  ...
+  name: 'my-app',
+  resolvers: [new EventRuleResolver({ busName: 'my-event-bus' })],
+  modules: [orderModule],
 });
 ```
 
-This setup allows you to customize how events are routed and processed within your application.
+Each `@Rule` method becomes an independent Lambda function triggered by matching EventBridge events. The event payload is automatically passed through `$.detail`.
+
+## Features
+
+### Event Rule Class
 
-Next, you need to configure the module by importing the class resources decorated with the @EventRule decorator. These classes must contain methods decorated with @Rule, which will create the event listener and attach the corresponding Lambda function for execution.
+Use the `@EventRule` decorator to group related event handlers in a single class:
 
 ```typescript
-@EventRule({
-  minify: false,
-})
-export class GreetingEvent {
+import { EventRule, Rule, Event } from '@lafken/event/main';
+
+@EventRule()
+export class InventoryEvents {
   @Rule({
-    bus: 'awesome-event-bus',
     pattern: {
-      source: 'simple-source',
+      source: 'inventory',
+      detailType: ['stock.updated'],
     },
   })
-  simpleEvent(@Event() e: any) {
-    // ...
-  }
-}
+  onStockUpdate(@Event() event: any) { }
 
-const greetingModule = createModule({
-  name: 'greeting',
-  resources: [
-    GreetingEvent
-  ]
-});
+  @Rule({
+    pattern: {
+      source: 'inventory',
+      detailType: ['stock.depleted'],
+    },
+  })
+  onStockDepleted(@Event() event: any) { }
+}
 ```
 
-## Features
+### Custom Events
 
-### Receiving and Filtering Events
-The @Rule decorator allows you to define an event pattern by specifying the event source and applying filters on detail and detailType.
+Define rules that match custom events by specifying `source`, `detailType`, and `detail` filters:
 
 ```typescript
 @Rule({
   pattern: {
-    source: 'simple-source',
+    source: 'payments',
+    detailType: ['payment.completed', 'payment.refunded'],
     detail: {
-      name: ['foo', 'bar'],
+      currency: ['USD', 'EUR'],
     },
-    detailType: ['CREATE', 'UPDATE'],
   },
 })
-// ...
+onPaymentEvent(@Event() event: any) {
+  // Triggered only for USD or EUR payments
+}
 ```
 
-### Receiving Events
-To access the payload sent by an event, you must use the @Event decorator. This decorator automatically maps the event’s inputPath to $.detail, allowing you to receive the event data directly as a parameter.
+#### Pattern Fields
 
-```typescript
-@Rule(/* ... */)
-sayHelloFromEvent(@Event() event: any) {
-  console.log('simple source', event);
-}
-```
-### S3 integrations
-Event rules also support integration with Amazon S3 through EventBridge-enabled bucket notifications.
-When this integration is enabled, S3 events are delivered to EventBridge, allowing fine-grained filtering based on event metadata such as the bucket name, object key, and event type.
+| Field        | Type       | Description                                          |
+| ------------ | ---------- | ---------------------------------------------------- |
+| `source`     | `string`   | Event source identifier (required)                   |
+| `detailType` | `string[]` | Event type names to match                            |
+| `detail`     | `object`   | Attribute-level filtering on the event payload       |
 
-To enable S3 integration within an event rule, set the integration property to 's3' and define a pattern that matches the desired S3 event structure.
+### S3 Integration
+
+Listen for S3 bucket notifications delivered through EventBridge. Set `integration: 's3'` and define a pattern matching the S3 event structure:
 
 ```typescript
 @Rule({
@@ -98,65 +114,175 @@ To enable S3 integration within an event rule, set the integration property to '
     detailType: ['Object Created'],
     detail: {
       bucket: {
-        name: ['lafken-example-documents'],
+        name: ['uploads-bucket'],
       },
       object: {
-        key: [
-          {
-            prefix: 'test.json',
-          },
-        ],
+        key: [{ prefix: 'images/' }],
       },
     },
   },
 })
-s3(@Event() event: any) {
-  // Handler logic
+onImageUploaded(@Event() event: any) {
+  // Triggered when a new object is created under images/
 }
 ```
 
-### Dynamo Integration
-Event rules can also consume and process events emitted by Amazon DynamoDB Streams.
-To use this integration, you must first enable DynamoDB Streams on the target table. Once enabled, DynamoDB will emit change records (INSERT, MODIFY, REMOVE), which can be routed through EventBridge and processed by your rule.
+#### S3 Pattern Options
+
+| Field                 | Type                               | Description                                  |
+| --------------------- | ---------------------------------- | -------------------------------------------- |
+| `detailType`          | `S3DetailType[]`                   | `'Object Created'` or `'Object Deleted'`     |
+| `detail.bucket.name`  | `string[]`                         | Bucket names to match                        |
+| `detail.object.key`   | `(string \| S3ObjectKey)[]`        | Object keys or prefix/suffix patterns        |
 
-After the stream is configured, you can define a rule with the integration: 'dynamodb' option and provide a pattern to filter the specific DynamoDB events you want to handle.
+Object key filters support `prefix` and `suffix` matching:
+
+```typescript
+detail: {
+  object: {
+    key: [
+      { prefix: 'uploads/' },
+      { suffix: '.pdf' },
+      'exact-filename.txt',
+    ],
+  },
+}
+```
+
+### DynamoDB Integration
+
+Consume events from DynamoDB Streams routed through EventBridge. The target table must have streams enabled (see `@lafken/dynamo` stream configuration). Set `integration: 'dynamodb'` and use `source` to specify the table name:
 
 ```typescript
 @Rule({
   integration: 'dynamodb',
   pattern: {
-    source: 'clients',
+    source: 'customers',
     detail: {
       eventName: ['INSERT', 'MODIFY'],
-      keys: {
-        email: {
-          prefix: 'awesome',
-        },
+      newImage: {
+        status: ['active'],
       },
     },
   },
 })
-dynamo(@Event() e: any) {
-  // ...
+onCustomerChange(@Event() event: any) {
+  // Triggered on INSERT or MODIFY where status is 'active'
+}
+```
+
+#### DynamoDB Pattern Options
+
+| Field              | Type                                    | Description                                   |
+| ------------------ | --------------------------------------- | --------------------------------------------- |
+| `source`           | `string`                                | DynamoDB table name                           |
+| `detail.eventName` | `('INSERT' \| 'MODIFY' \| 'REMOVE')[]` | Stream event types to match                   |
+| `detail.keys`      | `DynamoAttributeFilters`                | Filter by primary key values                  |
+| `detail.newImage`  | `DynamoAttributeFilters`                | Filter by new item attributes (after change)  |
+| `detail.oldImage`  | `DynamoAttributeFilters`                | Filter by old item attributes (before change) |
+
+Attribute filters support EventBridge content-based filtering patterns:
+
+```typescript
+detail: {
+  keys: {
+    email: ['user@example.com'],
+    age: [{ numeric: ['>', 18] }],
+  },
+  newImage: {
+    name: [{ prefix: 'A' }],
+    role: [{ 'anything-but': 'admin' }],
+  },
+}
+```
+
+#### Available Filter Patterns
+
+| Pattern               | Example                                   | Description                        |
+| --------------------- | ----------------------------------------- | ---------------------------------- |
+| Exact match           | `'value'`                                 | Matches exact string or number     |
+| `prefix`              | `{ prefix: 'usr_' }`                     | Starts with                        |
+| `suffix`              | `{ suffix: '.com' }`                     | Ends with                          |
+| `anything-but`        | `{ 'anything-but': 'admin' }`            | Matches everything except          |
+| `numeric`             | `{ numeric: ['>', 100] }`                | Numeric comparison                 |
+| `numeric` (range)     | `{ numeric: ['>=', 0, '<', 100] }`       | Numeric range                      |
+| `exists`              | `{ exists: true }`                        | Field exists or does not exist     |
+| `equals-ignore-case`  | `{ 'equals-ignore-case': 'active' }`     | Case-insensitive string match      |
+
+### Receiving Events
+
+Use the `@Event` parameter decorator to inject the EventBridge event payload into a handler method. The payload is automatically extracted from `$.detail`:
+
+```typescript
+@Rule({
+  pattern: {
+    source: 'notifications',
+    detailType: ['notification.sent'],
+  },
+})
+onNotification(@Event() event: any) {
+  // event contains the detail object, not the full EventBridge envelope
+  console.log(event.recipientId, event.channel);
 }
 ```
 
-### Event bus
+### Event Buses
 
-It is possible to configure multiple Event Buses when initializing the EventRuleResolver. Each event bus can then be referenced from individual rules by specifying its name in the bus property of the @Rule decorator.
+Configure one or more custom event buses when initializing `EventRuleResolver`. Each `@Rule` can target a specific bus via the `bus` option. If omitted, the default EventBridge bus is used:
 
-If no event bus is explicitly configured for a rule, the default EventBridge bus will be used automatically.
+```typescript
+import { EventRuleResolver } from '@lafken/event/resolver';
 
+createApp({
+  name: 'my-app',
+  resolvers: [
+    new EventRuleResolver(
+      {
+        busName: 'orders-bus',
+        extend: ({ eventBus, scope }) => {
+          // Apply additional CDKTN configuration
+        },
+      },
+      {
+        busName: 'notifications-bus',
+      }
+    ),
+  ],
+});
+```
+
+Reference a specific bus from a rule:
 
 ```typescript
-//...
-new EventRuleResolver({
-  busName: 'awesome-event-bus',
-  extend: ({ eventBus }) => {
-    // ... extend the event bus
+@Rule({
+  bus: 'orders-bus',
+  pattern: {
+    source: 'checkout',
+    detailType: ['checkout.completed'],
   },
-}, {
-  busName: 'another-event-bus'
-}),
-// ...
+})
+onCheckout(@Event() event: any) { }
 ```
+
+### Retry Policy
+
+Configure how EventBridge handles failed target invocations using `retryAttempts` and `maxEventAge`:
+
+```typescript
+@Rule({
+  retryAttempts: 3,
+  maxEventAge: 7200,
+  pattern: {
+    source: 'billing',
+    detailType: ['invoice.generated'],
+  },
+})
+onInvoice(@Event() event: any) {
+  // Retries up to 3 times, discards events older than 2 hours
+}
+```
+
+| Option          | Type     | Description                                                |
+| --------------- | -------- | ---------------------------------------------------------- |
+| `retryAttempts` | `number` | Maximum retry attempts if the target invocation fails      |
+| `maxEventAge`   | `number` | Maximum event age in seconds before the event is discarded |

package/lib/main/event/event.d.ts

@@ -1 +1,19 @@
+/**
+ * Parameter decorator that injects the raw EventBridge event into a
+ * handler method argument.
+ *
+ * Use it on a parameter of an `@EventHandler` method so the framework
+ * passes the incoming EventBridge event payload at runtime.
+ *
+ * @example
+ * ```ts
+ * @EventRule({})
+ * export class OrderEvents {
+ *   @EventHandler({ source: 'orders', detailType: 'order.created' })
+ *   onOrderCreated(@Event() event: any) {
+ *     // event contains the full EventBridge event payload
+ *   }
+ * }
+ * ```
+ */
 export declare const Event: () => (target: any, methodName: string, _number: number) => void;

package/lib/main/event/event.js

@@ -2,6 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Event = void 0;
 const common_1 = require("@lafken/common");
+/**
+ * Parameter decorator that injects the raw EventBridge event into a
+ * handler method argument.
+ *
+ * Use it on a parameter of an `@EventHandler` method so the framework
+ * passes the incoming EventBridge event payload at runtime.
+ *
+ * @example
+ * ```ts
+ * @EventRule({})
+ * export class OrderEvents {
+ *   @EventHandler({ source: 'orders', detailType: 'order.created' })
+ *   onOrderCreated(@Event() event: any) {
+ *     // event contains the full EventBridge event payload
+ *   }
+ * }
+ * ```
+ */
 const Event = () => (target, methodName, _number) => {
     (0, common_1.reflectArgumentMethod)(target, methodName, common_1.LambdaArgumentTypes.event);
 };

package/lib/main/rule/rule.d.ts

@@ -1,4 +1,50 @@
 import type { EventRuleProps } from './rule.types';
 export declare const RESOURCE_TYPE: "EVENT";
+/**
+ * Class decorator that registers a class as an EventBridge rule resource.
+ *
+ * The decorated class groups one or more `@Rule` handler methods that
+ * react to events published on an EventBridge bus. Each handler inside
+ * the class defines its own event pattern and integration.
+ *
+ * @param props - Optional resource configuration (e.g. a custom `name`).
+ *
+ * @example
+ * ```ts
+ * @EventRule()
+ * export class OrderEvents {
+ *   @Rule({ pattern: { source: 'orders', detailType: ['order.created'] } })
+ *   onCreated(@Event() event) { }
+ * }
+ * ```
+ */
 export declare const EventRule: (props?: import("@lafken/common").ResourceProps | undefined) => (constructor: Function) => void;
+/**
+ * Method decorator that registers a handler for a specific EventBridge
+ * rule pattern.
+ *
+ * The decorated method becomes a Lambda function that is invoked when
+ * an event matching the configured pattern is published on the
+ * EventBridge bus. Supports default custom events, S3 events, and
+ * DynamoDB stream events through the `integration` option.
+ *
+ * @param props - Rule configuration including the event pattern, optional
+ *                integration source, retry attempts, max event age, and bus name.
+ *
+ * @example
+ * ```ts
+ * // Custom event
+ * @Rule({
+ *   pattern: { source: 'payments', detailType: ['payment.completed'] },
+ * })
+ * onPayment(@Event() event) { }
+ *
+ * // S3 integration
+ * @Rule({
+ *   integration: 's3',
+ *   pattern: { detailType: ['Object Created'], detail: { bucket: { name: ['uploads'] } } },
+ * })
+ * onUpload(@Event() event) { }
+ * ```
+ */
 export declare const Rule: (props: EventRuleProps) => (target: any, methodName: string, descriptor: PropertyDescriptor) => any;

package/lib/main/rule/rule.js

@@ -3,10 +3,56 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rule = exports.EventRule = exports.RESOURCE_TYPE = void 0;
 const common_1 = require("@lafken/common");
 exports.RESOURCE_TYPE = 'EVENT';
+/**
+ * Class decorator that registers a class as an EventBridge rule resource.
+ *
+ * The decorated class groups one or more `@Rule` handler methods that
+ * react to events published on an EventBridge bus. Each handler inside
+ * the class defines its own event pattern and integration.
+ *
+ * @param props - Optional resource configuration (e.g. a custom `name`).
+ *
+ * @example
+ * ```ts
+ * @EventRule()
+ * export class OrderEvents {
+ *   @Rule({ pattern: { source: 'orders', detailType: ['order.created'] } })
+ *   onCreated(@Event() event) { }
+ * }
+ * ```
+ */
 exports.EventRule = (0, common_1.createResourceDecorator)({
     type: exports.RESOURCE_TYPE,
     callerFileIndex: 5,
 });
+/**
+ * Method decorator that registers a handler for a specific EventBridge
+ * rule pattern.
+ *
+ * The decorated method becomes a Lambda function that is invoked when
+ * an event matching the configured pattern is published on the
+ * EventBridge bus. Supports default custom events, S3 events, and
+ * DynamoDB stream events through the `integration` option.
+ *
+ * @param props - Rule configuration including the event pattern, optional
+ *                integration source, retry attempts, max event age, and bus name.
+ *
+ * @example
+ * ```ts
+ * // Custom event
+ * @Rule({
+ *   pattern: { source: 'payments', detailType: ['payment.completed'] },
+ * })
+ * onPayment(@Event() event) { }
+ *
+ * // S3 integration
+ * @Rule({
+ *   integration: 's3',
+ *   pattern: { detailType: ['Object Created'], detail: { bucket: { name: ['uploads'] } } },
+ * })
+ * onUpload(@Event() event) { }
+ * ```
+ */
 const Rule = (props) => (0, common_1.createLambdaDecorator)({
     getLambdaMetadata: (props, methodName) => ({
         ...props,

package/lib/resolver/resolver.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventRuleResolver = void 0;
-const cloudwatch_event_bus_1 = require("@cdktf/provider-aws/lib/cloudwatch-event-bus");
-const data_aws_cloudwatch_event_bus_1 = require("@cdktf/provider-aws/lib/data-aws-cloudwatch-event-bus");
+const cloudwatch_event_bus_1 = require("@cdktn/provider-aws/lib/cloudwatch-event-bus");
+const data_aws_cloudwatch_event_bus_1 = require("@cdktn/provider-aws/lib/data-aws-cloudwatch-event-bus");
 const common_1 = require("@lafken/common");
 const resolver_1 = require("@lafken/resolver");
 const main_1 = require("../main");

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

@@ -1,4 +1,4 @@
-import type { CloudwatchEventBus } from '@cdktf/provider-aws/lib/cloudwatch-event-bus';
+import type { CloudwatchEventBus } from '@cdktn/provider-aws/lib/cloudwatch-event-bus';
 import type { EventBusNames } from '@lafken/common';
 import type { AppStack } from '@lafken/resolver';
 interface ExtendProps {

package/lib/resolver/rule/rule.d.ts

@@ -1,4 +1,4 @@
-import { CloudwatchEventRule } from '@cdktf/provider-aws/lib/cloudwatch-event-rule';
+import { CloudwatchEventRule } from '@cdktn/provider-aws/lib/cloudwatch-event-rule';
 import { type AppModule } from '@lafken/resolver';
 import type { RuleProps } from './rule.types';
 declare const Rule_base: (new (...args: any[]) => {

package/lib/resolver/rule/rule.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rule = 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 cloudwatch_event_rule_1 = require("@cdktn/provider-aws/lib/cloudwatch-event-rule");
+const cloudwatch_event_target_1 = require("@cdktn/provider-aws/lib/cloudwatch-event-target");
 const resolver_1 = require("@lafken/resolver");
-const cdktf_1 = require("cdktf");
+const cdktn_1 = require("cdktn");
 class Rule extends resolver_1.lafkenResource.make(cloudwatch_event_rule_1.CloudwatchEventRule) {
     props;
     constructor(scope, id, props) {
@@ -12,7 +12,7 @@ class Rule extends resolver_1.lafkenResource.make(cloudwatch_event_rule_1.Cloudw
         super(scope, `${id}-rule`, {
             name: id,
             eventBusName: bus.name,
-            eventPattern: cdktf_1.Fn.jsonencode(Rule.getEvent(handler)),
+            eventPattern: cdktn_1.Fn.jsonencode(Rule.getEvent(handler)),
         });
         this.props = props;
         this.isGlobal(scope.id, id);

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

@@ -1,4 +1,4 @@
-import type { CloudwatchEventBus } from '@cdktf/provider-aws/lib/cloudwatch-event-bus';
+import type { CloudwatchEventBus } from '@cdktn/provider-aws/lib/cloudwatch-event-bus';
 import type { ResourceMetadata } from '@lafken/common';
 import type { EventRuleMetadata } from '../../main';
 export interface RuleProps {

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@lafken/event",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "private": false,
-  "description": "Create EventBridge event listeners in TypeScript with Lambda integration",
+  "description": "Define EventBridge event listeners using TypeScript decorators - serverless event-driven infrastructure",
   "keywords": [
     "aws",
     "eventbridge",
     "event",
+    "event-driven",
     "serverless",
+    "typescript",
+    "decorators",
     "lafken"
   ],
+  "homepage": "https://github.com/Hero64/lafken#readme",
+  "bugs": "https://github.com/Hero64/lafken/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hero64/lafken",
+    "directory": "packages/event"
+  },
   "license": "MIT",
+  "author": "Aníbal Jorquera",
   "exports": {
     "./main": {
       "import": "./lib/main/index.js",
@@ -37,28 +48,38 @@
     "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.4",
-    "@lafken/resolver": "0.6.4"
+    "reflect-metadata": "^0.2.2",
+    "@lafken/resolver": "0.8.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"
+    "@cdktn/provider-aws": "^23.0.0",
+    "@swc/core": "^1.15.11",
+    "@swc/helpers": "^0.5.18",
+    "@vitest/runner": "^4.0.18",
+    "cdktn": "^0.22.0",
+    "cdktn-vitest": "^1.0.0",
+    "constructs": "^10.4.5",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.0.18",
+    "@lafken/common": "0.8.0"
+  },
+  "peerDependencies": {
+    "@cdktn/provider-aws": "^23.0.0",
+    "@lafken/common": "^0.7.0",
+    "cdktn": "^0.22.0",
+    "constructs": "^10.4.5"
+  },
+  "engines": {
+    "node": ">=20.19"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "pnpm clean && tsc -p ./tsconfig.build.json",
+    "check-types": "tsc --noEmit -p ./tsconfig.build.json",
     "clean": "rm -rf ./lib",
     "dev": "tsc -w",
-    "test": "jest",
-    "test:coverage": "jest --coverage"
+    "test": "vitest"
   }
 }