@lafken/queue 0.12.8 → 0.12.9

package/README.md

@@ -20,7 +20,7 @@ import { Queue, Standard, Payload, Param, Event } from '@lafken/queue/main';
 // 1. Define the message payload
 @Payload()
 export class OrderMessage {
-  @Param({ source: 'body', parse: true })
+  @Param({ source: 'attribute' })
   orderId: string;
 
   @Param({ source: 'body', parse: true })
@@ -31,8 +31,10 @@ export class OrderMessage {
 @Queue()
 export class OrderQueue {
   @Standard({ batchSize: 5, visibilityTimeout: 60 })
-  processOrder(@Event(OrderMessage) message: OrderMessage) {
-    console.log(`Processing order ${message.orderId}`);
+  processOrder(@Event(OrderMessage) messages: OrderMessage[]) {
+    for (const message of messages) {
+      console.log(`Processing order ${message.orderId}`);
+    }
   }
 }
 
@@ -50,7 +52,7 @@ createApp({
 });
 ```
 
-Each `@Standard` or `@Fifo` method becomes an independent Lambda function with its own SQS queue and event source mapping.
+Each `@Standard` or `@Fifo` method becomes an independent Lambda function with its own SQS queue and event source mapping. The handler always receives an **array** of mapped payload objects — one per SQS record in the batch.
 
 ## Features
 
@@ -82,8 +84,9 @@ Use the `@Standard` decorator to create a standard (non-FIFO) SQS queue consumer
   visibilityTimeout: 120,
   maxConcurrency: 5,
 })
-generateReport(@Event(ReportMessage) message: ReportMessage) {
+generateReport(@Event(ReportMessage) messages: ReportMessage[]) {
   // Process up to 10 messages per invocation
+  for (const message of messages) { ... }
 }
 ```
 
@@ -113,8 +116,9 @@ Use the `@Fifo` decorator for FIFO (First-In-First-Out) queues. FIFO queues guar
   contentBasedDeduplication: true,
   batchSize: 1,
 })
-processPayment(@Event(PaymentMessage) message: PaymentMessage) {
+processPayment(@Event(PaymentMessage) messages: PaymentMessage[]) {
   // Messages are processed in exact send order
+  for (const message of messages) { ... }
 }
 ```
 
@@ -136,31 +140,63 @@ import { Payload, Param } from '@lafken/queue/main';
 
 @Payload()
 export class TaskMessage {
-  @Param({ source: 'attribute', type: String })
+  @Param({ source: 'attribute' })
   correlationId: string;
 
-  @Param({ source: 'body', parse: true })
-  taskName: string;
+  @Param({ source: 'attribute', type: Number })
+  priority: number;
 
   @Param({ source: 'body', parse: true })
-  priority: number;
+  taskName: string;
 }
 ```
 
 #### @Param Options
 
-| Option   | Type                      | Default       | Description                                      |
-| -------- | ------------------------- | ------------- | ------------------------------------------------ |
-| `source` | `'attribute' \| 'body'`   | `'attribute'` | Where to extract the value from the SQS record   |
-| `parse`  | `boolean`                 | `false`       | JSON-parse the message body before extraction     |
-| `type`   | `String \| Number \| ...` | inferred      | Data type of the extracted value                  |
-| `name`   | `string`                  | property name | Override the field name used for extraction       |
+| Option   | Type                                       | Default       | Description                                              |
+| -------- | ------------------------------------------ | ------------- | -------------------------------------------------------- |
+| `source` | `'attribute' \| 'body' \| 'record'`        | `'attribute'` | Where to extract the value from the SQS record           |
+| `parse`  | `boolean`                                  | `false`       | JSON-parse the message body before extraction (`'body'` only) |
+| `type`   | `String \| Number \| ...`                  | inferred      | Data type of the extracted value                         |
+| `name`   | `string`                                   | property name | Override the source field name used for extraction       |
 
-- **`source: 'attribute'`** — reads from SQS message attributes (supports `String` and `Number` types)
-- **`source: 'body'`** — reads from the message body. Set `parse: true` to JSON-parse the body and extract a specific field
+- **`source: 'attribute'`** — reads from SQS message attributes (supports `String` and `Number` types).
+- **`source: 'body'`** — reads from the message body. Set `parse: true` to JSON-parse the body and extract a specific key by property name.
+- **`source: 'record'`** — reads a top-level SQS record field such as `messageId`, `receiptHandle`, `awsRegion`, etc. The `name` option accepts only valid `SQSRecordField` values and defaults to the property name.
 
-> [!NOTE]
-> Only one `@Param` with `source: 'body'` and `parse: false` (raw body) is allowed per handler.
+> [!IMPORTANT]
+> Only **one** `@Param` with `source: 'body'` is allowed per payload class.
+
+#### `source: 'record'` — SQS Record Fields
+
+Use `source: 'record'` to bind SQS envelope metadata (e.g. the message identifier or region) directly to a payload property. The available fields are:
+
+| Field            | Description                                         |
+| ---------------- | --------------------------------------------------- |
+| `messageId`      | Unique identifier assigned by SQS to the message   |
+| `receiptHandle`  | Token used to delete or extend message visibility   |
+| `md5OfBody`      | MD5 digest of the message body                      |
+| `eventSource`    | Always `"aws:sqs"`                                  |
+| `eventSourceARN` | ARN of the source SQS queue                         |
+| `awsRegion`      | AWS region where the queue resides                  |
+
+```typescript
+import { Payload, Param } from '@lafken/queue/main';
+
+@Payload()
+export class AuditMessage {
+  // property name matches record field → no 'name' needed
+  @Param({ source: 'record' })
+  messageId: string;
+
+  // alias: property 'region' extracts record.awsRegion
+  @Param({ source: 'record', name: 'awsRegion' })
+  region: string;
+
+  @Param({ source: 'attribute' })
+  userId: string;
+}
+```
 
 #### @Field Decorator
 
@@ -181,7 +217,7 @@ export class SimpleMessage {
 
 ### Consuming Messages
 
-Bind a typed payload to a handler method using the `@Event` parameter decorator. Pass the payload class so the framework can automatically extract and map fields from the SQS record at runtime:
+Bind a typed payload to a handler method using the `@Event` parameter decorator. Pass the payload class so the framework can automatically extract and map fields from every SQS record in the batch. The handler always receives an **array** of mapped objects:
 
 ```typescript
 import { Queue, Standard, Event } from '@lafken/queue/main';
@@ -189,8 +225,10 @@ import { Queue, Standard, Event } from '@lafken/queue/main';
 @Queue()
 export class AlertQueue {
   @Standard({ queueName: 'alerts', batchSize: 5 })
-  processAlert(@Event(AlertMessage) alert: AlertMessage) {
-    console.log(`Alert from ${alert.source}: ${alert.message}`);
+  processAlert(@Event(AlertMessage) alerts: AlertMessage[]) {
+    for (const alert of alerts) {
+      console.log(`Alert from ${alert.source}: ${alert.message}`);
+    }
   }
 }
 ```
@@ -224,7 +262,7 @@ await QueueService.sendMessage({
 | ------------------- | ---------------------------------- | -------------------------------------------------- |
 | `url`               | `string`                           | Full SQS queue URL                                 |
 | `body`              | `any`                              | Message body (automatically JSON-stringified)      |
-| `attributes`        | `Record<string, string \| number>` | SQS message attributes                            |
+| `attributes`        | `Record<string, string \| number>` | SQS message attributes                             |
 | `delay`             | `number`                           | Delay in seconds before the message becomes visible |
 | `groupId`           | `string`                           | Message group ID (FIFO queues only)                |
 | `deduplicationId`   | `string`                           | Deduplication ID (FIFO queues only)                |

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

@@ -31,12 +31,15 @@ export declare const Payload: (props?: import("@lafken/common").PayloadProps | u
  * Property decorator that maps a class field to a value extracted
  * from an SQS message.
  *
- * By default the value is read from a **message attribute** whose name
- * matches the property. Set `source: 'body'` to extract it from the
- * message body instead, and optionally enable `parse: true` to
- * JSON-parse the body before extraction.
+ * - `source: 'attribute'` (default) — reads a **message attribute** whose
+ *   name matches the property (or the `name` option).
+ * - `source: 'body'` — reads from the raw message body string; set
+ *   `parse: true` to JSON-parse it and pick the matching key.
+ * - `source: 'record'` — reads a top-level SQS record field such as
+ *   `messageId`, `receiptHandle`, `awsRegion`, etc. The `name` option
+ *   can override which record field is read.
  *
- * @param props - Optional extraction configuration (source, type, parse).
+ * @param props - Optional extraction configuration (source, type, parse, name).
  *
  * @example
  * ```ts
@@ -47,6 +50,12 @@ export declare const Payload: (props?: import("@lafken/common").PayloadProps | u
  *
  *   @Param({ source: 'body', parse: true })
  *   content: NotificationContent;
+ *
+ *   @Param({ source: 'record' })
+ *   messageId: string;
+ *
+ *   @Param({ source: 'record', name: 'messageId' })
+ *   sqsId: string;
  * }
  * ```
  */

package/lib/main/event/event.js

@@ -39,12 +39,15 @@ exports.Payload = (0, common_1.createPayloadDecorator)({
  * Property decorator that maps a class field to a value extracted
  * from an SQS message.
  *
- * By default the value is read from a **message attribute** whose name
- * matches the property. Set `source: 'body'` to extract it from the
- * message body instead, and optionally enable `parse: true` to
- * JSON-parse the body before extraction.
+ * - `source: 'attribute'` (default) — reads a **message attribute** whose
+ *   name matches the property (or the `name` option).
+ * - `source: 'body'` — reads from the raw message body string; set
+ *   `parse: true` to JSON-parse it and pick the matching key.
+ * - `source: 'record'` — reads a top-level SQS record field such as
+ *   `messageId`, `receiptHandle`, `awsRegion`, etc. The `name` option
+ *   can override which record field is read.
  *
- * @param props - Optional extraction configuration (source, type, parse).
+ * @param props - Optional extraction configuration (source, type, parse, name).
  *
  * @example
  * ```ts
@@ -55,6 +58,12 @@ exports.Payload = (0, common_1.createPayloadDecorator)({
  *
  *   @Param({ source: 'body', parse: true })
  *   content: NotificationContent;
+ *
+ *   @Param({ source: 'record' })
+ *   messageId: string;
+ *
+ *   @Param({ source: 'record', name: 'messageId' })
+ *   sqsId: string;
  * }
  * ```
  */

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

@@ -1,4 +1,9 @@
 import type { ArrayField, BooleanField, FieldProps, NumberField, ObjectField, StringField } from '@lafken/common';
+/**
+ * Top-level string fields available on every SQS record that can be
+ * extracted with `@Param({ source: 'record' })`.
+ */
+export type SQSRecordField = 'messageId' | 'receiptHandle' | 'md5OfBody' | 'eventSource' | 'eventSourceARN' | 'awsRegion';
 export interface ParamAttributeProps extends Omit<FieldProps, 'type'> {
     /**
      * Attribute source.
@@ -67,7 +72,30 @@ export interface ParamBodyParsedProps extends Omit<FieldProps, 'type'> {
      */
     type?: StringConstructor | Function | [Function];
 }
-export type ParamProps = ParamAttributeProps | ParamBodyUnparsedProps | ParamBodyParsedProps;
+export interface ParamRecordProps extends Omit<FieldProps, 'type' | 'name'> {
+    /**
+     * Record source.
+     *
+     * Extracts a top-level field directly from the raw SQS record object
+     * (e.g. `messageId`, `receiptHandle`, `awsRegion`).
+     */
+    source: 'record';
+    /**
+     * SQS record field name.
+     *
+     * Specifies which top-level property of the SQS record to extract.
+     * Defaults to the decorated property name when omitted.
+     */
+    name?: SQSRecordField;
+    /**
+     * Attribute type.
+     *
+     * All SQS record metadata fields are strings, so only `String`
+     * is accepted here.
+     */
+    type?: StringConstructor;
+}
+export type ParamProps = ParamAttributeProps | ParamBodyUnparsedProps | ParamBodyParsedProps | ParamRecordProps;
 export type Source = Exclude<ParamProps['source'], undefined>;
 interface QueueParamBase {
     source: Source;
@@ -85,5 +113,8 @@ export interface QueueObjectParam extends Omit<ObjectField, 'properties'>, Queue
 export interface QueueArrayParam extends Omit<ArrayField, 'items'>, QueueParamBase {
     items: QueueParamMetadata;
 }
-export type QueueParamMetadata = QueueStringParam | QueueNumberParam | QueueBooleanParam | QueueObjectParam | QueueArrayParam;
+export interface QueueRecordParam extends StringField, QueueParamBase {
+    source: 'record';
+}
+export type QueueParamMetadata = QueueStringParam | QueueNumberParam | QueueBooleanParam | QueueObjectParam | QueueArrayParam | QueueRecordParam;
 export {};

package/lib/main/queue/queue.js

@@ -42,6 +42,9 @@ const getValueFormBody = (param, record) => {
     }
     return JSON.parse(String(value))?.[param.name];
 };
+const getValueFromRecord = (param, record) => {
+    return record[param.name];
+};
 const argumentParser = {
     [common_1.LambdaArgumentTypes.event]: ({ event, methodName, target }) => {
         const queueEvent = event;
@@ -57,10 +60,15 @@ const argumentParser = {
                 continue;
             }
             for (const param of paramsByHandler.properties) {
-                attributes[param.destinationName] =
-                    param.source === 'attribute'
-                        ? getValueFromAttribute(param, record)
-                        : getValueFormBody(param, record);
+                if (param.source === 'attribute') {
+                    attributes[param.destinationName] = getValueFromAttribute(param, record);
+                }
+                else if (param.source === 'record') {
+                    attributes[param.destinationName] = getValueFromRecord(param, record);
+                }
+                else {
+                    attributes[param.destinationName] = getValueFormBody(param, record);
+                }
             }
             data.push(attributes);
         }

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

@@ -138,6 +138,10 @@ export interface ExternalQueueProps extends SourceMappingProps {
      *
      */
     queueName: string | ((props: GetResourceProps) => string);
+    /**
+     * Lambda configuration for processing messages from this queue.
+     */
+    lambda?: LambdaProps;
 }
 export interface InternalFifoProps extends InternalStandardProps {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/queue",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "private": false,
   "description": "Define SQS queues and consumers using TypeScript decorators - automatic infrastructure generation with Lafken",
   "keywords": [
@@ -54,7 +54,7 @@
   "dependencies": {
     "@aws-sdk/client-sqs": "^3.1045.0",
     "reflect-metadata": "^0.2.2",
-    "@lafken/resolver": "0.12.8"
+    "@lafken/resolver": "0.12.9"
   },
   "devDependencies": {
     "@cdktn/provider-aws": "^24.0.0",
@@ -68,13 +68,13 @@
     "typescript": "6.0.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.5",
-    "@lafken/common": "0.12.8"
+    "@lafken/common": "0.12.9"
   },
   "peerDependencies": {
     "@cdktn/provider-aws": ">=23.0.0",
     "cdktn": ">=0.22.0",
     "constructs": "^10.4.5",
-    "@lafken/common": "0.12.8"
+    "@lafken/common": "0.12.9"
   },
   "engines": {
     "node": ">=20.19"