rabbitmq-extension

A lightweight, strongly typed RabbitMQ client for Node.js and TypeScript built on top of amqplib.

Unlike many RabbitMQ frameworks, this library intentionally focuses only on transport responsibilities:

• Sending messages
• Consuming messages
• Header mapping
• Health checking
• Type-safe APIs

It does not implement:

• Retry policies
• Dead Letter Queue (DLQ)
• Validation
• Business processing
• Retry scheduling

Those concerns belong to a higher-level Message Processing library.

Examples:

• rabbitmq-sample: An example to consume message from rabbitmq.

Why Another RabbitMQ Library?

amqplib is an excellent low-level RabbitMQ client, but application code usually contains repetitive boilerplate:

• Buffer conversion
• JSON serialization
• Header mapping
• Generic types
• Health checks

This library removes that boilerplate while staying close to RabbitMQ.

Instead of becoming another messaging framework, it provides a thin, reusable abstraction over amqplib.

Features

• Strongly typed producer
• Strongly typed consumer
• Automatic header mapping
• JSON support
• Plain text support
• Health checker
• Connection timeout
• Minimal abstraction
• Built on top of amqplib

Installation

npm install rabbitmq-extension

or

npm install rabbitmq-extension amqplib

Design Philosophy

The goal is to keep the transport layer simple.

 Application

      ↓

RabbitMQ Library

      ↓

   amqplib

      ↓

RabbitMQ Server

The RabbitMQ library should only know about RabbitMQ.

Business concerns belong elsewhere.

Sender

Sending a message is straightforward.

const sender = new Sender<Order>(channel, "orders");

await sender.send(order);

Messages are automatically serialized before being published.

Consumer

Consumers receive typed objects.

const consumer = new Consumer<Order>(channel, "orders");

consumer.consume(async (order) => {
    console.log(order.id);
});

The library handles:

• reading the message
• JSON deserialization
• header conversion
• acknowledgement

Application code only processes the message.

JSON Messages

Enable JSON mode:

new Consumer<Order>(channel queue)

 RabbitMQ

    ↓

JSON String

    ↓

   Order

Plain Text Messages

JSON parsing can be disabled.

new Consumer<string>(channel, queue)

RabbitMQ

    ↓

 String

    ↓

Application

Message Headers

RabbitMQ headers are automatically converted into a simple string map.

Instead of handling different RabbitMQ header types,

MessagePropertyHeaders

applications receive

interface StringMap {
    [key: string]: string
}

Example:

sender.send(order, {
    correlationId: "12345",
    tenant: "company-a"
});

Consumer:

consumer.consume(async (order, headers) => {
    console.log(headers?.tenant);
});

Health Check

The library includes a lightweight RabbitMQ health checker.

const checker = new RabbitMQChecker(url);

await checker.check();

The checker attempts to establish a RabbitMQ connection within a configurable timeout.

Typical usage:

 Application

      ↓

   /health

      ↓

RabbitMQChecker

      ↓

  RabbitMQ

This integrates easily with Kubernetes readiness and liveness probes.

Connection Timeout

Connection attempts should never wait indefinitely.

The health checker supports configurable connection timeouts.

new RabbitMQChecker(url, 5000);

If RabbitMQ cannot be reached within the timeout, the connection fails immediately.

Logging

Optional logging callbacks are supported.

const consumer = new Consumer(channel, queue, logError, logInfo);

No logging framework is required.

Applications are free to integrate:

• Winston
• Pino
• Bunyan
• Custom loggers

Transport Responsibilities

This library intentionally focuses on RabbitMQ transport.

It provides:

• Connection
• Producer
• Consumer
• Serialization
• Header conversion
• Health checking

It intentionally does not provide:

• Retry policies
• Retry queues
• Validation
• Dead Letter Queue
• Business workflow

These responsibilities belong to the Message Processing library.

Architecture

Business Application

        │

        ▼

Message Processing

--------------------------

   Validation
      Retry
Dead Letter Queue
   Retry Count
     Logging

         │

         ▼

      RabbitMQ

--------------------------

     Sender
    Consumer
     Headers
  Health Check

        │

        ▼

     amqplib

        │

        ▼

  RabbitMQ Server

This separation keeps the RabbitMQ library small, reusable, and focused on transport concerns.

Why Separate Transport from Processing?

Retry logic is not specific to RabbitMQ.

For example, the same business workflow can be implemented using:

• RabbitMQ
• Kafka
• Amazon SQS
• Azure Service Bus
• Google Pub/Sub

By keeping transport and processing separate, business logic remains independent of the messaging technology.

Ecosystem

This library works naturally with the Message Processing library.

 RabbitMQ Server

        ↓

    amqplib

        ↓

rabbitmq-extension library

        ↓

Message Processing

        ↓

Business Services

The RabbitMQ library handles transport.

The Message Processing library handles:

• Validation
• Retry
• Retry queues
• Dead Letter Queue
• Error handling
• Logging

Together they provide a complete messaging solution while maintaining clear separation of responsibilities.

Design Goals

• Thin abstraction over amqplib
• Strong TypeScript typing
• Minimal API surface
• Transport-only responsibilities
• Easy integration with higher-level processing libraries
• No framework lock-in

License

MIT