amqp-suite 0.1.0 → 0.1.2

package/README.md

@@ -1,114 +1,274 @@
 # 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)
+[![NPM version](https://img.shields.io/npm/v/amqp-suite?color=1447e6&style=flat-square)](https://www.npmjs.com/package/amqp-suite)
+[![MIT license](https://img.shields.io/badge/License-MIT-bridhtgreen?style=flat-square)](https://opensource.org/licenses/MIT)
+[![NPM downloads](https://img.shields.io/npm/dw/amqp-suite?color=bridhtgreen&style=flat-square)](https://www.npmjs.com/package/amqp-suite)
 [![stars](https://img.shields.io/github/stars/iamcarlosdaniel/amqp-suite)](https://github.com/iamcarlosdaniel/amqp-suite)
 
-![](docs/assets/repository_banner.png)
+![](https://raw.githubusercontent.com/iamcarlosdaniel/amqp-suite/main/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
+## 🔥 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.
+- **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
 
+### Package manager
+
+Using npm:
+
 ```bash
 npm install amqp-suite
 ```
 
+Using yarn:
+
+```bash
+yarn add amqp-suite
+```
+
+Using pnpm:
+
+```bash
+pnpm add amqp-suite
+```
+
+Using bun:
+
+```bash
+bun add amqp-suit
+```
+
+Once the package is installed, you can import the library using ES Modules:
+
+```javascript
+import { AmqpClient } from "amqp-suite";
+```
+
 ## Quick Start
 
 ### 1. Initialize and Connect
 
-Create an instance of the `AmqpClient` and establish a connection to the RabbitMQ broker.
+Create an instance of `AmqpClient` and establish a connection to your RabbitMQ broker. This prepares the client to publish and consume messages.
 
 ```javascript
 import { AmqpClient } from "amqp-suite";
 
-const amqpClient = new AmqpClient("amqp://localhost", "my_exchange");
+const amqpClient = new AmqpClient("amqp://localhost", "example-exchange");
 
-// Connect with optional retry config (retries, delay in ms)
-await amqpClient.connect(5, 2000);
+await amqpClient.connect();
 ```
 
 ### 2. Publish Messages
 
-The `publish` method ensures that the message is stringified and sent as a persistent buffer.
+The `publish` method automatically stringifies your message and sends it as a persistent buffer, ensuring it won’t be lost if the broker restarts.
 
 ```javascript
-const payload = {
-  id: 123,
-  event: "user_created",
-  timestamp: new Date(),
-};
-
-await amqpClient.publish("user.events.create", payload);
+await amqpClient.publish(
+  "example.events.hello_world", // Routing Key
+  {
+    message: "Hello World!",
+  },
+  {} // Options
+);
 ```
 
 ### 3. Consume Messages
 
-The `consume` method automatically asserts queues, binds them to the exchange, and handles acknowledgments (`ack`/`nack`).
+The `consume` method automatically creates queues, binds them to the exchange, and handles acknowledgments (`ack`/`nack`). You only need to provide the queue name and the function that will process incoming messages.
 
 ```javascript
 await amqpClient.consume(
-  "user_service_queue",
-  async (content, msg) => {
-    console.log("Received data:", content);
-    // Business logic here...
+  "example-queue", // Queue
+  (msg) => {
+    console.log("Received message:", msg);
+  },
+  {}, // Options
+  "example.events.hello_world" // Binding Key
+);
+```
+
+### Example Overview
+
+This diagram illustrates how a message is sent from the publisher, routed through the topic exchange, enqueued in the queue, and finally consumed by the consumer.
+
+![](https://raw.githubusercontent.com/iamcarlosdaniel/amqp-suite/main/docs/assets/example-architecture-diagram.svg)
+
+Here’s a full example that connects, publishes, consumes messages, and finally closes the connection.
+
+```javascript
+import { AmqpClient } from "amqp-suite";
+
+const amqpClient = new AmqpClient("amqp://localhost", "example-exchange");
+
+await amqpClient.connect();
+
+await amqpClient.publish(
+  "example.events.hello_world", // Routing Key
+  {
+    message: "Hello World!",
+  },
+  {} // Options
+);
+
+await amqpClient.consume(
+  "example-queue", // Queue
+  (msg) => {
+    console.log("Received message:", msg);
   },
-  { prefetch: 10 }, // Optional: defaults to 10
-  "user.events.*" // Binding key (Topic pattern)
+  {}, // Options
+  "example.events.hello_world" // Binding Key
 );
+
+await amqpClient.close();
 ```
 
+> **Note:** You can check the full example in [examples/hello-world](https://github.com/iamcarlosdaniel/amqp-suite/tree/main/examples/hello-world).
+
 ## 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.
+Creates a new instance of the AMQP client.
+
+The client uses a **durable topic exchange** to enable flexible message routing using routing patterns.
+
+#### Parameters
+
+- **`amqpUrl`** (`string`)
+  The AMQP connection URL.
+  Example: `amqp://user:pass@localhost:5672`
+
+- **`exchange`** (`string`)
+  The name of the **topic exchange** used for publishing and consuming messages.
+  The exchange is asserted as `durable`.
+
+---
 
 ### `.connect(retries = 5, delay = 5000)`
 
-Establishes the connection and creates the channel. If the connection drops, it will automatically attempt to reconnect.
+Establishes a connection to the AMQP broker and creates a channel.
+If the connection is lost unexpectedly, the client will automatically attempt to reconnect.
+
+#### Parameters
+
+- **`retries`** (`number`, optional)
+  Maximum number of reconnection attempts during the initial connection.
+  Default: `5`
+
+- **`delay`** (`number`, optional)
+  Delay in milliseconds between reconnection attempts.
+  Default: `5000`
 
-- **retries** (optional): Number of reconnection attempts (default: `5`).
-- **delay** (optional): Time interval (in milliseconds) between retries (default: `5000`).
+#### Behavior
+
+- Prevents multiple simultaneous connection attempts.
+- Automatically reconnects if the connection is closed by the broker.
+- Reconnection attempts triggered after a connection drop do **not** reuse the original retry counter.
+
+#### Returns
+
+- `Promise<void>`
+
+---
 
 ### `.publish(routingKey, message, options = {})`
 
-Publishes a message to the configured exchange with the given routing key.
+Publishes a message to the configured topic exchange using the specified routing key.
+
+Messages are automatically serialized to JSON and published as **persistent** by default.
+
+#### Parameters
+
+- **`routingKey`** (`string`)
+  The routing key used to route the message.
+  Example: `user.events.create`
+
+- **`message`** (`object`)
+  The message payload. It will be automatically serialized to JSON.
+
+- **`options`** (`object`, optional)
+  Additional publish options supported by `amqplib`.
+  These options are merged with `{ persistent: true }`.
+
+#### Behavior
 
-- **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`.
+- If the channel is not initialized, the client will attempt to connect automatically.
+- If the broker’s write buffer is full, the message may be temporarily buffered locally.
+
+#### Returns
+
+- `Promise<void>`
+
+---
 
 ### `.consume(queue, onMessage, options = {}, bindingKey = "#")`
 
-Consumes messages from the specified queue. The callback `onMessage` is executed when a message is received.
+Consumes messages from the specified queue and binds it to the exchange using the provided routing pattern.
+
+The `onMessage` callback is executed for each received message.
+
+#### Parameters
 
-- **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.
+- **`queue`** (`string`)
+  The name of the queue to consume messages from.
+  The queue is asserted as `durable`.
+
+- **`onMessage`** (`function`)
+  An asynchronous callback executed when a message is received.
 
   ```javascript
   async (content, rawMessage) => {
-    /* logic */
+    // message handling logic
   };
   ```
 
-- **options** (optional): Additional options like `prefetch` (default is 10).
-- **bindingKey** (optional): The routing pattern to bind the queue (default is `#`).
+  - `content`: Parsed JSON message payload.
+  - `rawMessage`: The original `ConsumeMessage` from `amqplib`.
+
+- **`options`** (`object`, optional)
+  Consumer configuration options.
+
+  - **`prefetch`** (`number`):
+    Limits the number of unacknowledged messages.
+    Default: `10`
+
+- **`bindingKey`** (`string`, optional)
+  The routing pattern used to bind the queue to the exchange.
+  Default: `#` (matches all routing keys).
+
+#### Behavior
+
+- Messages are acknowledged (`ack`) automatically after successful processing.
+- If an error is thrown while processing a message:
+
+  - The message is negatively acknowledged (`nack`)
+  - The message is **not requeued**, preventing infinite retry loops for malformed messages.
+
+#### Returns
+
+- `Promise<void>`
+
+---
 
 ### `.close()`
 
-Gracefully closes the channel and the connection.
+Gracefully closes the AMQP channel and connection.
+
+#### Behavior
+
+- Prevents automatic reconnection during shutdown.
+- Ensures resources are released cleanly.
+
+#### Returns
+
+- `Promise<void>`
 
 ## License
 

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "amqp-suite",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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"
+    "url": "https://iamcarlosdaniel.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iamcarlosdaniel/amqp-suite.git"
+  },
+  "homepage": "https://iamcarlosdaniel.com/projects/amqp-suite",
+  "bugs": {
+    "url": "https://github.com/iamcarlosdaniel/amqp-suite/issues/new"
   },
   "type": "module",
   "main": "src/index.js",
@@ -27,10 +35,10 @@
     "rabbitmq"
   ],
   "dependencies": {
-    "amqplib": "^0.10.9"
+    "amqplib": "0.10.9"
   },
   "devDependencies": {
-    "@vitest/ui": "^4.0.16",
-    "vitest": "^4.0.16"
+    "@vitest/ui": "4.0.16",
+    "vitest": "4.0.16"
   }
 }

package/src/{index.d.ts → amqp-client.d.ts}

@@ -1,4 +1,4 @@
-declare module "amqp-wrapper" {
+declare module "amqp-suite" {
   export class AmqpClient {
     constructor(amqpUrl: string, exchange: string);
     connect(retries?: number, delay?: number): Promise<void>;

package/src/amqp-client.js

@@ -23,6 +23,8 @@ class AmqpClient {
     this.channel = null;
     /** @type {boolean} State flag to prevent multiple simultaneous connection attempts. */
     this.isConnecting = false;
+    /** @type {boolean} State flag to indicate if the client is closing. */
+    this.isClosing = false;
   }
 
   /**
@@ -51,11 +53,14 @@ class AmqpClient {
       });
 
       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);
+
+        if (!this.isClosing) {
+          this.isConnecting = false;
+          console.warn(`AMQP connection lost. Retrying in ${delay}ms...`);
+          setTimeout(() => this.connect(), delay);
+        }
       });
 
       console.log("AMQP: Connection established successfully");
@@ -171,10 +176,12 @@ class AmqpClient {
    */
   async close() {
     try {
+      this.isClosing = true;
       await this.channel?.close();
       await this.connection?.close();
       console.log("AMQP: Connection closed cleanly.");
     } catch (err) {
+      this.isClosing = false;
       console.error("AMQP: Error during shutdown:", err);
     }
   }

package/src/index.js

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

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

@@ -1,33 +0,0 @@
-# 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/tests/amqp.test.js

@@ -1,172 +0,0 @@
-/**
- * @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

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