Rabbit Relay

A TypeScript-first RabbitMQ framework for building reliable publishers and consumers without hiding RabbitMQ.

Typed events · Publisher confirms · Retries and DLQs · RPC · Recovery · Graceful shutdown · OpenTelemetry

Listed in the official RabbitMQ JavaScript and Node ecosystem

Documentation · Examples · Issues · Discussions

npm install @bitspacerlabs/rabbit-relay

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

const broker = new RabbitMQBroker("orders-service", {
  publisherConfirms: true,
});

const orderCreated = event("orderCreated", "v1").of<{
  orderId: string;
  total: number;
}>();

const orders = await broker
  .queue("orders.created.q")
  .exchange("orders.events", {
    exchangeType: "topic",
    routingKey: "order.created",
  });

const api = orders.with({ orderCreated });

api.handle("orderCreated", async (_messageId, message) => {
  console.log("Processing order", message.data.orderId);
});

await api.consume({ prefetch: 20, concurrency: 5 });
await api.orderCreated({ orderId: "O-42", total: 99.5 });

Rabbit Relay uses at-least-once delivery semantics. Consumers must be idempotent because duplicates remain possible during retries, reconnects, and network failures. Read the delivery-semantics guide.

For publish-only producers that don't consume, use broker.exchange() to declare just the exchange (no queue, binding, or consumer):

const pub = await broker.exchange("orders.events", {
  exchangeType: "topic",
  publisherConfirms: true,
});
await pub.produce(orderCreated({ orderId: "O-42", total: 99.5 }));

Why Rabbit Relay?

amqplib provides the essential AMQP primitives for Node.js. Production services commonly need an application layer around those primitives for recovery, typed contracts, retry policies, shutdown coordination, topology ownership, and observability.

Rabbit Relay provides that layer while keeping RabbitMQ concepts explicit:

• Typed and versioned events with optional runtime validation
• Reliable publishing with publisher confirms, mandatory returns, backpressure, and message-size limits
• Predictable consumers with prefetch, concurrency, middleware, and deterministic acknowledgements
• Retries and dead-letter queues with immediate or delayed retry strategies and DLQ redrive
• Connection recovery that restores channels, topology, and consumers
• Graceful shutdown that drains active handlers before closing resources
• RPC with correlation IDs, reply queues, and timeouts
• Topology ownership modes for application-owned, infrastructure-owned, or plan-only workflows
• Operational visibility through health state, lifecycle events, and OpenTelemetry
• Native AMQP escape hatches when direct amqplib access is needed

Need	Recommended approach
A few simple publishes or consumers with full low-level control	Use amqplib directly
TypeScript-first messaging with reusable reliability conventions	Use Rabbit Relay
RabbitMQ Streams workloads	Use the RabbitMQ Streams client
A heavily configuration-driven enterprise messaging framework	Evaluate Rascal

Using an AI coding agent? Give it llms.txt for a curated documentation map. Repository agents should begin with AGENTS.md.

AI Coding Skills

Installable skills for AI coding agents that generate correct Rabbit Relay code:

npx skills add bitspacerlabs/rabbit-relay-skills

Includes skills for core API patterns, typed events, retries/DLQ, topology, RPC, and observability. Works with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenCode, and Gemini CLI. See rabbit-relay-skills for details.

Stability

Rabbit Relay is stable on the 1.x line and follows semantic versioning. The repository includes unit tests, live RabbitMQ integration tests, and packed-package ESM, CommonJS, and TypeScript smoke tests.

See CHANGELOG.md for release history.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

License

MIT © BitSpacer Labs