@nestjstools/messaging-amazon-sqs-extension 1.0.0 → 1.2.0

package/README.md

@@ -6,6 +6,13 @@
 
 A NestJS library for managing asynchronous and synchronous messages with support for buses, handlers, channels, and consumers. This library simplifies building scalable and decoupled applications by facilitating robust message handling pipelines while ensuring flexibility and reliability.
 
+---
+## Documentation
+
+https://nestjstools.gitbook.io/nestjstools-messaging-docs
+
+---
+
 ## Installation
 
 ```bash
@@ -97,9 +104,64 @@ export class CreateUserHandler implements IMessageHandler<CreateUser>{
   }
 }
 ```
+## 📨 Communicating Beyond a NestJS Application (Cross-Language Messaging)
+
+### To enable communication with a Handler from services written in other languages, follow these steps:
+
+1. **Publish a Message to the queue**
+
+2. **Include the Routing Key Header**
+   Your message **must** include a header attribute named `messagingRoutingKey`.
+   The value should correspond to the routing key defined in your NestJS message handler:
 
+   ```ts
+   @MessageHandler('my_app_command.create_user') // <-- Use this value as the routing key
+   ```
+
+3. **You're Done!**
+   Once the message is published with the correct routing key, it will be automatically routed to the appropriate handler within the NestJS application.
 ---
 
+## 🏷️ Sending Custom SQS Message Attributes
+
+In addition to the required `messagingRoutingKey` header, you can include **custom attributes** in your SQS messages to enrich the message with metadata such as request IDs, user types, or priority levels.
+
+### Example: Sending a Message with Attributes
+
+```ts
+const exampleAttributes = {
+  requestId: {
+    DataType: "String",
+    StringValue: "req-" + Math.random().toString(36).substring(2, 10),
+  },
+  timestamp: {
+    DataType: "Number",
+    StringValue: Date.now().toString(),
+  },
+  userType: {
+    DataType: "String",
+    StringValue: "admin",
+  },
+  priority: {
+    DataType: "Number",
+    StringValue: "1",
+  },
+};
+
+this.sqsMessageBus.dispatch(
+  new RoutingMessage(
+    new CreateUser('John FROM Sqs'),
+    'my_app_command.create_user',
+    new AmazonSqsMessageOptions(exampleAttributes)
+  )
+);
+```
+
+> ⚠️ Don't forget that `messagingRoutingKey` must still be present — it's used to route the message to the correct handler.
+
+---
+
+
 ### Key Features:
 
 * Amazon SQS Integration: Easily send and receive messages with Amazon SQS.

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './messaging-amazon-sqs-extension.module';
 export * from './channel/amazon-sqs.channel-config';
 export * from './message-bus/amazon-sqs-message.bus';
+export * from './message/amazon-sqs-message-options';

package/lib/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./messaging-amazon-sqs-extension.module"), exports);
 __exportStar(require("./channel/amazon-sqs.channel-config"), exports);
 __exportStar(require("./message-bus/amazon-sqs-message.bus"), exports);
+__exportStar(require("./message/amazon-sqs-message-options"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0EAAuD;AACvD,sEAAmD;AACnD,uEAAoD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0EAAuD;AACvD,sEAAmD;AACnD,uEAAoD;AACpD,uEAAoD"}

package/lib/message/amazon-sqs-message-options.d.ts

@@ -0,0 +1,8 @@
+import { MessageOptions } from '@nestjstools/messaging';
+import { MessageAttributeValue } from '@aws-sdk/client-sqs/dist-types/models/models_0';
+export declare class AmazonSqsMessageOptions implements MessageOptions {
+    readonly attributes: Record<string, MessageAttributeValue>;
+    readonly middlewares: any[];
+    readonly avoidErrorsWhenNotExistedHandler: boolean;
+    constructor(attributes?: Record<string, MessageAttributeValue>);
+}

package/lib/message/amazon-sqs-message-options.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmazonSqsMessageOptions = void 0;
+class AmazonSqsMessageOptions {
+    attributes;
+    middlewares = [];
+    avoidErrorsWhenNotExistedHandler = false;
+    constructor(attributes = {}) {
+        this.attributes = attributes;
+    }
+}
+exports.AmazonSqsMessageOptions = AmazonSqsMessageOptions;
+//# sourceMappingURL=amazon-sqs-message-options.js.map

package/lib/message/amazon-sqs-message-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amazon-sqs-message-options.js","sourceRoot":"","sources":["../../src/message/amazon-sqs-message-options.ts"],"names":[],"mappings":";;;AAGA,MAAa,uBAAuB;IAKhB;IAJF,WAAW,GAAU,EAAE,CAAC;IACxB,gCAAgC,GAAY,KAAK,CAAC;IAElE,YACkB,aAAoD,EAAE;QAAtD,eAAU,GAAV,UAAU,CAA4C;IAExE,CAAC;CACF;AARD,0DAQC"}

package/lib/message-bus/amazon-sqs-message.bus.js

@@ -13,21 +13,29 @@ exports.AmazonSqsMessageBus = void 0;
 const common_1 = require("@nestjs/common");
 const amazon_sqs_channel_1 = require("../channel/amazon-sqs.channel");
 const client_sqs_1 = require("@aws-sdk/client-sqs");
+const amazon_sqs_message_options_1 = require("../message/amazon-sqs-message-options");
 let AmazonSqsMessageBus = class AmazonSqsMessageBus {
     channel;
     constructor(channel) {
         this.channel = channel;
     }
     async dispatch(message) {
+        const messageOptions = message.messageOptions;
+        let attributes = {};
+        if (messageOptions !== undefined && !(messageOptions instanceof amazon_sqs_message_options_1.AmazonSqsMessageOptions)) {
+            throw new Error(`Message options must be a ${amazon_sqs_message_options_1.AmazonSqsMessageOptions.name} object`);
+        }
+        if (messageOptions instanceof amazon_sqs_message_options_1.AmazonSqsMessageOptions) {
+            attributes = messageOptions.attributes;
+        }
+        attributes.messagingRoutingKey = {
+            DataType: "String",
+            StringValue: message.messageRoutingKey,
+        };
         const command = new client_sqs_1.SendMessageCommand({
             QueueUrl: this.channel.config.queueUrl,
             MessageBody: JSON.stringify(message.message),
-            MessageAttributes: {
-                messagingRoutingKey: {
-                    DataType: "String",
-                    StringValue: message.messageRoutingKey,
-                },
-            }
+            MessageAttributes: attributes,
         });
         await this.channel.client.send(command);
     }

package/lib/message-bus/amazon-sqs-message.bus.js.map

@@ -1 +1 @@
-{"version":3,"file":"amazon-sqs-message.bus.js","sourceRoot":"","sources":["../../src/message-bus/amazon-sqs-message.bus.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,2CAA4C;AAC5C,sEAAiE;AACjE,oDAAyD;AAGlD,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAEX;IADnB,YACmB,OAAyB;QAAzB,YAAO,GAAP,OAAO,CAAkB;IAE5C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAuB;QACpC,MAAM,OAAO,GAAG,IAAI,+BAAkB,CAAC;YACrC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ;YACtC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC;YAC5C,iBAAiB,EAAE;gBACjB,mBAAmB,EAAE;oBACnB,QAAQ,EAAE,QAAQ;oBAClB,WAAW,EAAE,OAAO,CAAC,iBAAiB;iBACvC;aACF;SACF,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACzC,CAAC;CACF,CAAA;AAnBY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAGiB,qCAAgB;GAFjC,mBAAmB,CAmB/B"}
+{"version":3,"file":"amazon-sqs-message.bus.js","sourceRoot":"","sources":["../../src/message-bus/amazon-sqs-message.bus.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,2CAA4C;AAC5C,sEAAiE;AACjE,oDAAyD;AACzD,sFAAgF;AAIzE,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAEX;IADnB,YACmB,OAAyB;QAAzB,YAAO,GAAP,OAAO,CAAkB;IAE5C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAuB;QACpC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC9C,IAAI,UAAU,GAA0C,EAAE,CAAC;QAE3D,IAAI,cAAc,KAAK,SAAS,IAAI,CAAC,CAAC,cAAc,YAAY,oDAAuB,CAAC,EAAE,CAAC;YACzF,MAAM,IAAI,KAAK,CAAC,6BAA6B,oDAAuB,CAAC,IAAI,SAAS,CAAC,CAAC;QACtF,CAAC;QAED,IAAI,cAAc,YAAY,oDAAuB,EAAE,CAAC;YACtD,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC;QACzC,CAAC;QAED,UAAU,CAAC,mBAAmB,GAAG;YAC/B,QAAQ,EAAE,QAAQ;YAClB,WAAW,EAAE,OAAO,CAAC,iBAAiB;SACvC,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,+BAAkB,CAAC;YACrC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ;YACtC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC;YAC5C,iBAAiB,EAAE,UAAU;SAC9B,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACzC,CAAC;CACF,CAAA;AA/BY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAGiB,qCAAgB;GAFjC,mBAAmB,CA+B/B"}