![\"Rabbit](\"assets/rabbit-relay.svg\")
\n\n \n
\n A TypeScript-first RabbitMQ framework for building reliable publishers and consumers without hiding RabbitMQ.\n
\n\n\n Typed events · Publisher confirms · Retries and DLQs · RPC · Recovery · Graceful shutdown · OpenTelemetry\n
\n\n\n \n Listed in the official RabbitMQ JavaScript and Node ecosystem\n \n
\n\n\n \n ![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/bitspacerlabs/rabbit-relay/ci.yml?branch=main&label=CI\")
![\"npm](\"https://img.shields.io/npm/v/@bitspacerlabs/rabbit-relay\")
![\"npm](\"https://img.shields.io/npm/dm/@bitspacerlabs/rabbit-relay\")
![\"GitHub](\"https://img.shields.io/github/stars/bitspacerlabs/rabbit-relay?style=flat\")
![\"license\"](\"https://img.shields.io/github/license/bitspacerlabs/rabbit-relay\")
\n Documentation\n ·\n Examples\n ·\n Issues\n ·\n Discussions\n
\n\n```bash\nnpm install @bitspacerlabs/rabbit-relay\n```\n\n```ts\nimport { RabbitMQBroker, event } from \"@bitspacerlabs/rabbit-relay\";\n\nconst broker = new RabbitMQBroker(\"orders-service\", {\n publisherConfirms: true,\n});\n\nconst orderCreated = event(\"orderCreated\", \"v1\").of<{\n orderId: string;\n total: number;\n}>();\n\nconst orders = await broker\n .queue(\"orders.created.q\")\n .exchange(\"orders.events\", {\n exchangeType: \"topic\",\n routingKey: \"order.created\",\n });\n\nconst api = orders.with({ orderCreated });\n\napi.handle(\"orderCreated\", async (_messageId, message) => {\n console.log(\"Processing order\", message.data.orderId);\n});\n\nawait api.consume({ prefetch: 20, concurrency: 5 });\nawait api.orderCreated({ orderId: \"O-42\", total: 99.5 });\n```\n\n> 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](https://bitspacerlabs.github.io/rabbit-relay/docs/delivery-semantics).\n\nFor **publish-only producers** that don't consume, use `broker.exchange()` to declare just the exchange (no queue, binding, or consumer):\n\n```ts\nconst pub = await broker.exchange(\"orders.events\", {\n exchangeType: \"topic\",\n publisherConfirms: true,\n});\nawait pub.produce(orderCreated({ orderId: \"O-42\", total: 99.5 }));\n```\n\n## Why Rabbit Relay?\n\n[`amqplib`](https://github.com/amqp-node/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.\n\nRabbit Relay provides that layer while keeping RabbitMQ concepts explicit:\n\n- **Typed and versioned events** with optional runtime validation\n- **Reliable publishing** with publisher confirms, mandatory returns, backpressure, and message-size limits\n- **Predictable consumers** with prefetch, concurrency, middleware, and deterministic acknowledgements\n- **Retries and dead-letter queues** with immediate or delayed retry strategies and DLQ redrive\n- **Connection recovery** that restores channels, topology, and consumers\n- **Graceful shutdown** that drains active handlers before closing resources\n- **RPC** with correlation IDs, reply queues, and timeouts\n- **Topology ownership modes** for application-owned, infrastructure-owned, or plan-only workflows\n- **Operational visibility** through health state, lifecycle events, and OpenTelemetry\n- **Native AMQP escape hatches** when direct `amqplib` access is needed\n\n| Need | Recommended approach |\n|---|---|\n| A few simple publishes or consumers with full low-level control | Use `amqplib` directly |\n| TypeScript-first messaging with reusable reliability conventions | Use Rabbit Relay |\n| RabbitMQ Streams workloads | Use the RabbitMQ Streams client |\n| A heavily configuration-driven enterprise messaging framework | Evaluate Rascal |\n\n> Using an AI coding agent? Give it [`llms.txt`](llms.txt) for a curated documentation map. Repository agents should begin with [`AGENTS.md`](AGENTS.md).\n\n## AI Coding Skills\n\nInstallable skills for AI coding agents that generate correct Rabbit Relay code:\n\n```bash\nnpx skills add bitspacerlabs/rabbit-relay-skills\n```\n\nIncludes 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`](https://github.com/bitspacerlabs/rabbit-relay-skills) for details.\n\n## Stability\n\nRabbit 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.\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for release history.\n\n## Contributing\n\nContributions are welcome. Read [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and [`SECURITY.md`](SECURITY.md).\n\n## License\n\nMIT © BitSpacer Labs\n","readmeFilename":"README.md"}