I just released Rabbit Relay 1.0.0, the first stable release of a TypeScript-first RabbitMQ framework for Node.js.

Rabbit Relay is built on top of amqplib.

The main idea is simple:

Keep RabbitMQ explicit, but make it safer and cleaner to use in TypeScript services.

It keeps real RabbitMQ concepts visible:

• exchanges
• queues
• bindings
• routing keys
• acknowledgements
• retries
• dead-letter queues
• publisher confirms
• topology ownership

It is not trying to turn RabbitMQ into magic function calls.

It is trying to make RabbitMQ easier to use correctly.

Why I built it

amqplib is powerful, but it is low-level.

In real services, teams often repeat the same boilerplate again and again:

• create connection
• create channel
• assert exchanges
• assert queues
• bind queues
• serialize messages
• publish messages
• consume messages
• ACK/NACK messages
• handle retries
• configure DLQs
• add correlation IDs
• add health checks
• decide who owns topology

That logic can become inconsistent across services.

Rabbit Relay is my attempt to make this layer consistent without hiding the RabbitMQ model.

A typed event

import { RabbitMQBroker, event } from "@bitspacerlabs/rabbit-relay";

type OrderCreated = {
  orderId: string;
  amount: number;
};

const orderCreated = event("order.created", "v1").of<OrderCreated>();

const broker = new RabbitMQBroker("orders.publisher");

const pub = await broker
  .queue("orders.publisher.q")
  .exchange("orders.ex", {
    exchangeType: "topic",
    publisherConfirms: true,
  });

await pub.produce(
  orderCreated({
    orderId: "o-1",
    amount: 42,
  })
);

await broker.close();

The RabbitMQ concepts are still visible:

orders.ex = exchange
orders.publisher.q = queue
topic = exchange type
publisherConfirms = wait for RabbitMQ broker acknowledgement

Rabbit Relay just gives this a cleaner TypeScript API.

Typed event contracts

Messaging systems often fail when message contracts become tribal knowledge.

But unless those contracts are visible in code, they are easy to break.

Rabbit Relay event factories make the event name, version, and payload type explicit:

const paymentProcessed = event("payment.processed", "v1").of<{
  orderId: string;
  transactionId: string;
  status: "paid";
}>();

Then publishing is type-checked:

await pub.produce(
  paymentProcessed({
    orderId: "o-1",
    transactionId: "txn-123",
    status: "paid",
  })
);

This does not replace schema validation or contract testing.

But it makes the common TypeScript workflow much safer.

A typed publish API

Rabbit Relay can also build a small typed publish API from event factories:

const send = event("send", "v1").of<{ message: string }>();

const api = pub.with({ send });

await api.send({
  message: "hello world",
});

The generated methods create the event and publish it.

So they are async publish methods and should be awaited.

Routing keys stay explicit

RabbitMQ topic routing is powerful, but easy to confuse.

In topic exchanges, values like order.* or # are usually binding patterns.

They are useful when binding a queue.

But they are usually not what you want to publish as the message routing key.

Rabbit Relay keeps this behavior explicit.

By default, Rabbit Relay publishes with the event name as the routing key:

const makeOrderCreated = event("order.created", "v1").of<OrderCreated>();

await pub.produce(
  makeOrderCreated({
    orderId: "o-1",
    amount: 42,
  })
); // routing key: "order.created"

If a concrete routing key is configured, Rabbit Relay can use it when publishing.

But if the configured routing key is a topic wildcard pattern like # or order.*, Rabbit Relay treats it as a binding pattern and continues publishing with the event name.

You can still override the publish routing key explicitly:

await pub.publish(eventEnvelope, {
  routingKey: "custom.key",
});

Consuming events

import { RabbitMQBroker, type EventEnvelope } from "@bitspacerlabs/rabbit-relay";

type OrderCreated = {
  orderId: string;
  amount: number;
};

const broker = new RabbitMQBroker("orders.consumer");

const sub = await broker
  .queue("orders.q")
  .exchange<{
    "order.created": EventEnvelope<OrderCreated>;
  }>("orders.ex", {
    exchangeType: "topic",
    routingKey: "order.*",
  });

sub.handle("order.created", async (_id, ev) => {
  console.log(ev.data.orderId);
});

await sub.consume({
  prefetch: 10,
  concurrency: 5,
});

The mental model stays the same:

producer -> exchange -> binding -> queue -> consumer

Production failure handling

The happy path is not enough.

Rabbit Relay supports:

• ACK on success
• NACK and requeue
• NACK and dead-letter
• bounded retry
• delayed retry
• DLQ redrive

Example:

await sub.consume({
  prefetch: 10,
  concurrency: 5,
  onError: "retry",
  retry: {
    attempts: 3,
    delayMs: 5000,
    then: "dead-letter",
  },
});

This avoids two dangerous patterns:

1. Losing failed messages silently.
2. Requeueing forever and creating an infinite failure loop.

Operations features

Rabbit Relay 1.0.0 also includes:

• lifecycle hooks
• health checks
• OpenTelemetry adapter
• topology planning
• topology validation
• DLQ redrive

For example:

const plan = broker.planTopology();

console.log(plan);

Topology validation can passively check existing RabbitMQ infrastructure without modifying it.

That is useful when infrastructure owns the RabbitMQ topology and applications should only validate that required exchanges and queues exist.

Why not hide RabbitMQ?

Some libraries try to make messaging look like normal function calls.

That can be nice at first, but it often hides important operational details.

RabbitMQ concepts matter:

• exchange type matters
• routing key matters
• queue durability matters
• prefetch matters
• ACK/NACK behavior matters
• DLQs matter
• publisher confirms matter
• topology ownership matters

Rabbit Relay is designed around the idea that developers should understand these concepts, not avoid them.

The library should reduce boilerplate, not remove the mental model.

Install

npm i @bitspacerlabs/rabbit-relay

GitHub: github.com/bitspacerlabs/rabbit-relay

Docs: bitspacerlabs.github.io/rabbit-relay

npm: @bitspacerlabs/rabbit-relay

Final thought

RabbitMQ is already powerful.

Rabbit Relay is not trying to replace it.

It is trying to make RabbitMQ easier to use correctly in Node.js and TypeScript services, while keeping the real messaging concepts visible.

That is the core idea:

Type-safe RabbitMQ for Node.js, without hiding RabbitMQ.