amqp-suite 0.1.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:run
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carlos Daniel
+
+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,115 @@
+# amqp-suite
+
+[![NPM version](https://img.shields.io/npm/v/amqp-suite)](https://www.npmjs.com/package/amqp-suite)
+[![NPM downloads](https://img.shields.io/npm/dw/amqp-suite.svg)](https://www.npmjs.com/package/amqp-suite)
+[![MIT license](https://img.shields.io/badge/License-MIT-bridhtgreen)](https://opensource.org/licenses/MIT)
+[![stars](https://img.shields.io/github/stars/iamcarlosdaniel/amqp-suite)](https://github.com/iamcarlosdaniel/amqp-suite)
+
+![](docs/assets/repository_banner.png)
+
+`amqp-suite` is a simple and efficient AMQP (Advanced Message Queuing Protocol) client wrapper for Node.js that handles connection management, message publishing, and consuming messages from queues with a topic exchange. This package abstracts complex connection handling and simplifies AMQP usage in applications by providing easy-to-use methods for connecting, publishing, consuming, and gracefully shutting down the connection.
+
+## Features
+
+- Automatic Reconnection: Built-in retry logic for connection failures and drops.
+- Simplified Pub/Sub: Designed for 'topic' exchanges to allow flexible routing.
+- Structured Messaging: Automatic JSON serialization and deserialization.
+- Error Handling: Graceful handling of malformed messages and channel crashes.
+- Flow Control: Integrated prefetch support to prevent consumer saturation.
+
+## Installation
+
+```bash
+npm install amqp-suite
+```
+
+## Quick Start
+
+### 1. Initialize and Connect
+
+Create an instance of the `AmqpClient` and establish a connection to the RabbitMQ broker.
+
+```javascript
+import { AmqpClient } from "amqp-suite";
+
+const amqpClient = new AmqpClient("amqp://localhost", "my_exchange");
+
+// Connect with optional retry config (retries, delay in ms)
+await amqpClient.connect(5, 2000);
+```
+
+### 2. Publish Messages
+
+The `publish` method ensures that the message is stringified and sent as a persistent buffer.
+
+```javascript
+const payload = {
+  id: 123,
+  event: "user_created",
+  timestamp: new Date(),
+};
+
+await amqpClient.publish("user.events.create", payload);
+```
+
+### 3. Consume Messages
+
+The `consume` method automatically asserts queues, binds them to the exchange, and handles acknowledgments (`ack`/`nack`).
+
+```javascript
+await amqpClient.consume(
+  "user_service_queue",
+  async (content, msg) => {
+    console.log("Received data:", content);
+    // Business logic here...
+  },
+  { prefetch: 10 }, // Optional: defaults to 10
+  "user.events.*" // Binding key (Topic pattern)
+);
+```
+
+## API Reference
+
+### `new AmqpClient(amqpUrl, exchange)`
+
+- **amqpUrl**: The connection string (e.g., `amqp://user:pass@localhost:5672`).
+- **exchange**: The name of the topic exchange to use.
+
+### `.connect(retries = 5, delay = 5000)`
+
+Establishes the connection and creates the channel. If the connection drops, it will automatically attempt to reconnect.
+
+- **retries** (optional): Number of reconnection attempts (default: `5`).
+- **delay** (optional): Time interval (in milliseconds) between retries (default: `5000`).
+
+### `.publish(routingKey, message, options = {})`
+
+Publishes a message to the configured exchange with the given routing key.
+
+- **routingKey**: The routing key used to route the message (e.g., `'user.events.create'`).
+- **message**: The message payload, which will be stringified into JSON.
+- **options** (optional): Additional publish options from `amqplib`.
+
+### `.consume(queue, onMessage, options = {}, bindingKey = "#")`
+
+Consumes messages from the specified queue. The callback `onMessage` is executed when a message is received.
+
+- **queue**: The name of the queue to consume messages from.
+- **onMessage**: An async callback function that will be called with the message content and the original message.
+
+  ```javascript
+  async (content, rawMessage) => {
+    /* logic */
+  };
+  ```
+
+- **options** (optional): Additional options like `prefetch` (default is 10).
+- **bindingKey** (optional): The routing pattern to bind the queue (default is `#`).
+
+### `.close()`
+
+Gracefully closes the channel and the connection.
+
+## License
+
+This project is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "amqp-suite",
+  "version": "0.1.0",
+  "description": "A simple wrapper for AMQP 0-9-1 messaging.",
+  "license": "MIT",
+  "author": {
+    "name": "Carlos Daniel Menchaca Arauz",
+    "email": "contact@iamcarlosdaniel.com",
+    "url": "http://iamcarlosdaniel.com"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run"
+  },
+  "keywords": [
+    "amqp",
+    "exchange",
+    "pubsub",
+    "publisher",
+    "consumer",
+    "rabbitmq"
+  ],
+  "dependencies": {
+    "amqplib": "^0.10.9"
+  },
+  "devDependencies": {
+    "@vitest/ui": "^4.0.16",
+    "vitest": "^4.0.16"
+  }
+}

package/src/amqp-client.js

@@ -0,0 +1,183 @@
+import amqp from "amqplib";
+
+/**
+ * @fileoverview
+ * AMQP Service Class to manage AMQP communication.
+ * Handles automatic connection, channel management, and structured
+ * pub/sub patterns using 'topic' exchanges.
+ */
+class AmqpClient {
+  /**
+   * Creates an instance of the AMQP helper.
+   * @param {string} amqpUrl - The connection string (e.g., 'amqp://localhost').
+   * @param {string} exchange - The name of the exchange to be used.
+   */
+  constructor(amqpUrl, exchange) {
+    /** @type {string} */
+    this.amqpUrl = amqpUrl;
+    /** @type {string} */
+    this.exchange = exchange;
+    /** @type {import('amqplib').Connection|null} */
+    this.connection = null;
+    /** @type {import('amqplib').Channel|null} */
+    this.channel = null;
+    /** @type {boolean} State flag to prevent multiple simultaneous connection attempts. */
+    this.isConnecting = false;
+  }
+
+  /**
+   * Establishes a connection to the AMQP broker and sets up the infrastructure.
+   * Implements a recursive retry logic in case of connection failure or drops.
+   * @param {number} [retries=5] - Maximum number of reconnection attempts.
+   * @param {number} [delay=5000] - Time interval in milliseconds between retries.
+   * @returns {Promise<void>}
+   * @throws {Error} Throws an error if all retry attempts fail.
+   */
+  async connect(retries = 5, delay = 5000) {
+    if (this.isConnecting) return;
+    this.isConnecting = true;
+
+    try {
+      this.connection = await amqp.connect(this.amqpUrl);
+      this.channel = await this.connection.createChannel();
+
+      // Infrastructure initial setup: Using 'topic' for flexible routing
+      await this.channel.assertExchange(this.exchange, "topic", {
+        durable: true,
+      });
+
+      this.connection.on("error", (err) => {
+        console.error("AMQP Connection Error:", err);
+      });
+
+      this.connection.on("close", () => {
+        this.isConnecting = false;
+        this.connection = null;
+        this.channel = null;
+        console.warn(`AMQP connection lost. Retrying in ${delay}ms...`);
+        setTimeout(() => this.connect(), delay);
+      });
+
+      console.log("AMQP: Connection established successfully");
+      this.isConnecting = false;
+    } catch (error) {
+      this.isConnecting = false;
+      if (retries > 0) {
+        console.error(
+          `AMQP: Connection failed. Retries left: ${retries}. Retrying in ${delay}ms...`
+        );
+        setTimeout(() => this.connect(retries - 1, delay), delay);
+      } else {
+        console.error(
+          "AMQP: Critical failure. Could not connect after maximum attempts."
+        );
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Publishes a message to the configured exchange.
+   * @param {string} routingKey - The routing key used to direct the message.
+   * @param {Object} message - The message payload (will be stringified to JSON).
+   * @param {import('amqplib').Options.Publish} [options={}] - Additional publish options.
+   * @returns {Promise<void>}
+   */
+  async publish(routingKey, message, options = {}) {
+    if (!this.channel) {
+      console.log("AMQP: Channel not initialized. Attempting to connect...");
+      await this.connect();
+    }
+
+    try {
+      const published = this.channel.publish(
+        this.exchange,
+        routingKey,
+        Buffer.from(JSON.stringify(message)),
+        { persistent: true, ...options }
+      );
+
+      if (published) {
+        console.log(`AMQP: Message published to [${routingKey}]`);
+      } else {
+        console.warn(
+          "AMQP: Message was buffered locally. Check broker capacity or channel drain."
+        );
+      }
+    } catch (err) {
+      console.error("AMQP: Failed to publish message:", err);
+      throw err;
+    }
+  }
+
+  /**
+   * Consumes messages from a specific queue.
+   * @param {string} queue - The name of the queue to consume from.
+   * @param {function(Object, import('amqplib').ConsumeMessage): Promise<void>} onMessage -
+   * Callback executed when a message is received.
+   * @param {Object} [options={}] - Additional queue and prefetch options.
+   * @param {string} [bindingKey="#"] - The binding pattern to link the queue to the exchange.
+   * @returns {Promise<void>}
+   */
+  async consume(queue, onMessage, options = {}, bindingKey = "#") {
+    if (!this.channel) {
+      console.log("AMQP: Channel not initialized. Attempting to connect...");
+      await this.connect();
+    }
+
+    try {
+      const { prefetch = 10, ...queueOptions } = options;
+
+      // Ensure the queue exists and is durable by default
+      await this.channel.assertQueue(queue, { durable: true, ...queueOptions });
+      await this.channel.bindQueue(queue, this.exchange, bindingKey);
+
+      // Limit unacknowledged messages to avoid overwhelming the consumer
+      await this.channel.prefetch(prefetch);
+
+      await this.channel.consume(
+        queue,
+        async (msg) => {
+          if (msg !== null) {
+            try {
+              const content = JSON.parse(msg.content.toString());
+              await onMessage(content, msg);
+              this.channel.ack(msg);
+            } catch (err) {
+              console.error(
+                `AMQP: Error processing message on queue [${queue}]:`,
+                err.message
+              );
+              // nack(message, requeue: false) to prevent infinite loops on malformed messages
+              this.channel.nack(msg, false, false);
+            }
+          }
+        },
+        { noAck: false }
+      );
+
+      console.log(
+        `AMQP: Consumer started for queue [${queue}] with binding [${bindingKey}]`
+      );
+    } catch (err) {
+      console.error("AMQP: Failed to initialize consumer:", err);
+      throw err;
+    }
+  }
+
+  /**
+   * Gracefully closes the AMQP channel and connection.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    try {
+      await this.channel?.close();
+      await this.connection?.close();
+      console.log("AMQP: Connection closed cleanly.");
+    } catch (err) {
+      console.error("AMQP: Error during shutdown:", err);
+    }
+  }
+}
+
+export { AmqpClient };

package/src/index.d.ts

@@ -0,0 +1,14 @@
+declare module "amqp-wrapper" {
+  export class AmqpClient {
+    constructor(amqpUrl: string, exchange: string);
+    connect(retries?: number, delay?: number): Promise<void>;
+    publish(routingKey: string, message: any, options?: any): Promise<void>;
+    consume(
+      queue: string,
+      onMessage: (content: any, msg: any) => Promise<void>,
+      options?: any,
+      bindingKey?: string
+    ): Promise<void>;
+    close(): Promise<void>;
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+import { AmqpClient } from "./amqp-client";
+
+export { AmqpClient };

package/tests/amqp.test.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Unit tests for the AMQP class using Vitest and amqplib mocks.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import amqp from "amqplib";
+import { AmqpClient } from "amqp-suite";
+
+vi.mock("amqplib");
+
+/**
+ * Test suite for AMQP integration and message handling.
+ */
+describe("AMQP Class", () => {
+  /** @type {AmqpClient} */
+  let amqpInstance;
+
+  /** @type {string} */
+  const mockUrl = "amqp://localhost";
+
+  /** @type {string} */
+  const mockExchange = "test_exchange";
+
+  /**
+   * Mocked AMQP Channel object with Vitest spy functions.
+   * @type {Object}
+   */
+  const mockChannel = {
+    assertExchange: vi.fn().mockResolvedValue(undefined),
+    assertQueue: vi.fn().mockResolvedValue({}),
+    bindQueue: vi.fn().mockResolvedValue(undefined),
+    prefetch: vi.fn().mockResolvedValue(undefined),
+    publish: vi.fn().mockReturnValue(true),
+    consume: vi.fn().mockResolvedValue({ consumerTag: "abc" }),
+    ack: vi.fn(),
+    nack: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+
+  /**
+   * Mocked AMQP Connection object.
+   * @type {Object}
+   */
+  const mockConnection = {
+    createChannel: vi.fn().mockResolvedValue(mockChannel),
+    on: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+
+  /**
+   * Setup hook to reset mocks and re-initialize the AMQP instance before each test.
+   */
+  beforeEach(() => {
+    vi.clearAllMocks();
+    amqpInstance = new AmqpClient(mockUrl, mockExchange);
+    amqp.connect.mockResolvedValue(mockConnection);
+  });
+
+  /**
+   * Test case: Constructor property assignment.
+   */
+  it("should correctly initialize values in the constructor", () => {
+    expect(amqpInstance.amqpUrl).toBe(mockUrl);
+    expect(amqpInstance.exchange).toBe(mockExchange);
+  });
+
+  /**
+   * Test case: Connection workflow and exchange assertion.
+   */
+  it("should connect and create a channel successfully", async () => {
+    await amqpInstance.connect();
+
+    expect(amqp.connect).toHaveBeenCalledWith(mockUrl);
+    expect(mockConnection.createChannel).toHaveBeenCalled();
+    expect(mockChannel.assertExchange).toHaveBeenCalledWith(
+      mockExchange,
+      "topic",
+      { durable: true }
+    );
+    expect(amqpInstance.connection).not.toBeNull();
+  });
+
+  /**
+   * Test case: Message publishing logic and buffer conversion.
+   */
+  it("should publish a message correctly", async () => {
+    await amqpInstance.connect();
+    const routingKey = "user.created";
+    const message = { id: 1, name: "Test" };
+
+    await amqpInstance.publish(routingKey, message);
+
+    expect(mockChannel.publish).toHaveBeenCalledWith(
+      mockExchange,
+      routingKey,
+      expect.any(Buffer),
+      expect.objectContaining({ persistent: true })
+    );
+  });
+
+  /**
+   * Test case: Consumer setup and successful message processing.
+   */
+  it("should setup consumer and acknowledge messages on success", async () => {
+    await amqpInstance.connect();
+    const queueName = "test_queue";
+    const bindingKey = "test.key";
+    const mockPayload = { data: "hello world" };
+    const mockOnMessage = vi.fn().mockResolvedValue(undefined);
+
+    await amqpInstance.consume(
+      queueName,
+      mockOnMessage,
+      { prefetch: 5 },
+      bindingKey
+    );
+
+    expect(mockChannel.assertQueue).toHaveBeenCalledWith(
+      queueName,
+      expect.objectContaining({ durable: true })
+    );
+    expect(mockChannel.bindQueue).toHaveBeenCalledWith(
+      queueName,
+      mockExchange,
+      bindingKey
+    );
+    expect(mockChannel.prefetch).toHaveBeenCalledWith(5);
+
+    const consumerCallback = mockChannel.consume.mock.calls[0][1];
+    const fakeMsg = {
+      content: Buffer.from(JSON.stringify(mockPayload)),
+    };
+
+    await consumerCallback(fakeMsg);
+
+    expect(mockOnMessage).toHaveBeenCalledWith(mockPayload, fakeMsg);
+    expect(mockChannel.ack).toHaveBeenCalledWith(fakeMsg);
+  });
+
+  /**
+   * Test case: Consumer error handling (nack).
+   */
+  it("should nack messages if the processing fails", async () => {
+    await amqpInstance.connect();
+    const mockOnMessage = vi
+      .fn()
+      .mockRejectedValue(new Error("Processing failed"));
+
+    await amqpInstance.consume("error_queue", mockOnMessage);
+
+    const consumerCallback = mockChannel.consume.mock.calls[0][1];
+    const fakeMsg = {
+      content: Buffer.from(JSON.stringify({ some: "data" })),
+    };
+
+    await consumerCallback(fakeMsg);
+
+    expect(mockChannel.nack).toHaveBeenCalledWith(fakeMsg, false, false);
+    expect(mockChannel.ack).not.toHaveBeenCalled();
+  });
+
+  /**
+   * Test case: Graceful shutdown of channel and connection.
+   */
+  it("should close the connection cleanly", async () => {
+    await amqpInstance.connect();
+    await amqpInstance.close();
+
+    expect(mockChannel.close).toHaveBeenCalled();
+    expect(mockConnection.close).toHaveBeenCalled();
+  });
+});

package/vitest.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true, // Permite usar 'describe', 'it', 'expect' sin importarlos
+    environment: "node",
+  },
+});