Rabbit Relay

A type-safe RabbitMQ framework for Node.js (TypeScript), built on top of amqplib to simplify event-driven messaging, publishing, and consumption.

Docs · Examples · Issues · Discussions

---

Why Rabbit Relay?

amqplib is powerful, but it’s low-level. Rabbit Relay keeps “real RabbitMQ concepts” (exchanges, queues, routing keys), and adds:

• Type-safe events (typed payloads + versioning)
• Cleaner publish / consume APIs (less boilerplate)
• Explicit topology & ownership (no hidden abstractions)
• Reliable defaults (so every service doesn’t reinvent the same setup)

If you already use RabbitMQ and you want a better TypeScript developer experience, Rabbit Relay is for you.

---

Installation

npm i @bitspacerlabs/rabbit-relay

Tip: Rabbit Relay ships TypeScript-first and supports both ESM and CommonJS builds.

---

Quickstart (typed events)

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

const broker = new RabbitMQBroker("example.service");

// Create a publisher bound to your queue + exchange
const pub = await broker
  .queue("example.q")
  .exchange("example.exchange", { exchangeType: "topic" });

// Define typed events (name + version)
const send = event("send", "v1").of<{ message: string }>();

// Build a typed publish API.
// Calling api.send(...) creates the event and publishes it.
const api = pub.with({ send });
await api.send({ message: "hello world" });

Direct publish (produce)

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

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

const pub = await broker
  .queue("example.q")
  .exchange("example.direct", { exchangeType: "direct" });

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

await pub.produce(hello({ msg: "world" }));

Routing keys

By default, Rabbit Relay publishes using the event name as the routing key.

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

await pub.produce(
  hello({ msg: "world" })
); // routing key: "hello"

If you configure a concrete routingKey on the exchange, Rabbit Relay uses it when publishing:

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

For topic wildcard bindings such as # or demo.*, Rabbit Relay treats the value as a binding pattern and continues publishing by event name.

const pub = await broker
  .queue("plugins.q")
  .exchange("plugins.exchange", {
    exchangeType: "topic",
    routingKey: "demo.*",
  });

const ping = event("demo.ping", "v1").of<{ seq: number }>();

await pub.produce(
  ping({ seq: 1 })
); // routing key: "demo.ping"

You can always override the publish routing key explicitly:

await pub.publish(
  hello({ msg: "world" }),
  { routingKey: "custom.key" }
);

---

Examples

See runnable examples in:

• examples/ → https://github.com/bitspacerlabs/rabbit-relay/tree/main/examples

---

When to use Rabbit Relay

• You already use RabbitMQ
• You want type-safe events
• You prefer explicit topology and ownership
• You don’t want “magic” abstractions

---

Project status

Rabbit Relay is actively evolving. If something is unclear or missing, please open an issue (or start a discussion) with:

• what you’re trying to build
• the RabbitMQ pattern you’re using (pub/sub, work queue, RPC, etc.)
• a small code snippet

---

Contributing

Contributions are welcome

• Read: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md

If you want to help but don’t know where to start, check issues labeled good first issue.

---

License

MIT BitSpacer Labs