@bitspacerlabs/rabbit-relay 0.5.2 → 0.6.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,101 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: sohaibqasem
+
+---
+
+# Bug Report – Rabbit Relay
+
+## Summary
+A clear and concise description of what the bug is.
+
+---
+
+## Rabbit Relay Version
+- **Package:** `@bitspacerlabs/rabbit-relay`
+- **Version:** `x.y.z`
+
+---
+
+## RabbitMQ Environment
+- **RabbitMQ Version:** `x.y.z`
+- **Deployment:** Local / Docker / Cloud
+- **Clustered:** Yes / No
+
+---
+
+## Node.js Environment
+- **Node.js Version:** `vXX`
+- **Package Manager:** npm / pnpm / yarn
+- **OS:** Linux / macOS / Windows
+
+---
+
+## What Happened?
+Describe what actually happened.
+
+---
+
+## Expected Behavior
+Describe what you expected to happen.
+
+---
+
+## Steps to Reproduce
+1. Configure broker with minimal setup
+2. Publish an event
+3. Start a consumer
+4. Observe the behavior
+
+---
+
+## Actual Output / Logs
+```text
+Paste logs or error messages here
+```
+
+---
+
+## Example Code (Minimal Repro)
+```ts
+// Paste a minimal reproducible example here
+```
+
+---
+
+## Message / Event Details
+- **Exchange:**  
+- **Routing Key:**  
+- **Queue:**  
+- **Event Name:**  
+- **Persistent:** Yes / No  
+- **Confirm Channel:** Yes / No  
+- **Deduplication Enabled:** Yes / No  
+
+---
+
+## Does This Happen Consistently?
+- Always  
+- Sometimes  
+- Only under load  
+- Only after reconnect  
+
+---
+
+## Screenshots / Diagrams (Optional)
+Broker topology or RabbitMQ Management UI screenshots if available.
+
+---
+
+## Additional Context
+Add any other context that might help diagnose the problem (retries, reconnects, dead letters, load, etc.).
+
+---
+
+## Checklist
+- [ ] I am using the latest Rabbit Relay version
+- [ ] I checked existing issues
+- [ ] I provided a minimal reproducible example

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+@sohaibqasem.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing to Rabbit Relay 🐇⚡
+
+First of all, thank you for taking the time to contribute!  
+**Rabbit Relay** is an open-source project built with the goal of making RabbitMQ usage in Node.js **reliable, type-safe, and developer-friendly**.  
+Contributions of all kinds are welcome 💙
+
+---
+
+## Project Philosophy
+
+Rabbit Relay is built around a few core principles:
+
+- **Type safety first** (TypeScript-driven APIs)
+- **Reliability over magic**
+- **Explicit, predictable behavior**
+- **Minimal runtime dependencies**
+- **Production-ready by default**
+
+Every contribution should aim to support these goals.
+
+---
+
+## Ways to Contribute
+
+You can contribute in many ways, including:
+
+- Reporting bugs  
+- Proposing or implementing new features  
+- Adding tests or improving coverage  
+- Improving documentation or examples  
+- Refactoring or improving internal code quality  
+- Suggesting design or API improvements  
+
+If you’re unsure where to start, check existing issues or open a discussion.
+
+---
+
+## 🐞 Reporting Bugs
+
+Before opening a new issue:
+
+1. Search existing issues to avoid duplicates  
+2. Make sure you're using the latest version  
+3. Provide as much detail as possible  
+
+Please include:
+
+- Rabbit Relay version  
+- Node.js version  
+- RabbitMQ version  
+- Minimal reproducible example (if possible)  
+- Expected behavior vs actual behavior  
+- Error logs or stack traces  
+
+---
+
+## ✨ Feature Requests
+
+Feature requests are welcome!
+
+Please describe:
+
+- The problem you're trying to solve  
+- Why existing solutions are insufficient  
+- How the feature fits Rabbit Relay’s philosophy  
+- Proposed API shape (TypeScript examples encouraged)  
+
+Large changes should be discussed before implementation.
+
+---
+
+## 🛠 Development Setup
+
+### Prerequisites
+
+- Node.js (LTS recommended)
+- npm or pnpm
+- A running RabbitMQ instance (Docker is fine)
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Build the package
+
+```bash
+npm run build
+```
+
+## Code Style & Conventions
+
+- TypeScript only  
+- Avoid `any` unless absolutely necessary  
+- Prefer explicit types for public APIs  
+- Avoid breaking changes unless discussed  
+- Keep functions small and focused  
+
+---
+
+## Pull Request Process
+
+1. Fork the repository  
+2. Create a feature branch  
+3. Commit with clear messages  
+4. Open a Pull Request  
+5. Be ready to iterate based on feedback  
+
+---
+
+## 🚦 Breaking Changes
+
+Breaking changes require:
+
+- Clear justification  
+- Migration guidance  
+- Explicit mention in PR title and description  
+
+---
+
+## 🤝 Code of Conduct
+
+Be respectful, inclusive, and constructive.  
+Harassment or toxic behavior will not be tolerated.
+
+---
+
+## 💙 Community & Vision
+
+Rabbit Relay is part of **Bitspacer Labs**, focused on open-source tooling and developer communities.
+
+Everyone is welcome to contribute.
+
+---
+
+## ⭐ Support the Project
+
+If you find Rabbit Relay useful:
+
+- ⭐ Star the repository  
+- 📣 Share it  
+- 💬 Provide feedback  
+
+Thank you for contributing

package/README.md

@@ -1,73 +1,101 @@
+<!--
+NOTE:
+- Package: @bitspacerlabs/rabbit-relay
+- Repo: https://github.com/bitspacerlabs/rabbit-relay
+-->
+
+<p align="center">
+  <img src="assets/rabbit-relay.svg" alt="Rabbit Relay" width="220" />
+</p>
+
+<h1 align="center">Rabbit Relay</h1>
+
 <p align="center">
-  <img src="assets/logo.svg" alt="Rabbit Relay" width="260">
+  A <b>type-safe</b> RabbitMQ framework for Node.js (TypeScript), built on top of <b>amqplib</b> to simplify
+  event-driven messaging, publishing, and consumption.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/rabbit-relay">
-    <img src="https://img.shields.io/npm/v/@bitspacerlabs/rabbit-relay.svg?style=flat-square" alt="NPM Version">
+  <a href="https://www.npmjs.com/package/@bitspacerlabs/rabbit-relay">
+    <img alt="npm version" src="https://img.shields.io/npm/v/@bitspacerlabs/rabbit-relay">
   </a>
-  <a href="https://github.com/bitspacerlabs/rabbit-relay">
-    <img src="https://img.shields.io/github/stars/@bitspacerlabs/rabbit-relay.svg?style=flat-square" alt="GitHub Stars">
+  <a href="https://www.npmjs.com/package/@bitspacerlabs/rabbit-relay">
+    <img alt="npm downloads" src="https://img.shields.io/npm/dm/@bitspacerlabs/rabbit-relay">
   </a>
-  <a href="https://github.com/bitspacerlabs/rabbit-relay/issues">
-    <img src="https://img.shields.io/github/issues/@bitspacerlabs/rabbit-relay.svg?style=flat-square" alt="Issues">
+  <a href="https://github.com/bitspacerlabs/rabbit-relay/stargazers">
+    <img alt="GitHub stars" src="https://img.shields.io/github/stars/bitspacerlabs/rabbit-relay?style=flat">
   </a>
-  <a href="https://opensource.org/licenses/MIT">
-    <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License">
+  <a href="LICENSE">
+    <img alt="license" src="https://img.shields.io/github/license/bitspacerlabs/rabbit-relay">
   </a>
 </p>
 
----
-
-## Rabbit Relay
-
-**Rabbit Relay** is a type-safe RabbitMQ framework for Node.js.
-
-It helps you publish and consume events using real RabbitMQ concepts, with TypeScript types and reliable defaults.
+<p align="center">
+  <a href="https://bitspacerlabs.github.io/rabbit-relay/">Docs</a>
+  ·
+  <a href="https://github.com/bitspacerlabs/rabbit-relay/tree/main/examples">Examples</a>
+  ·
+  <a href="https://github.com/bitspacerlabs/rabbit-relay/issues">Issues</a>
+  ·
+  <a href="https://github.com/bitspacerlabs/rabbit-relay/discussions">Discussions</a>
+</p>
 
 ---
 
-## Start Here
+## Why Rabbit Relay?
+
+**amqplib is powerful, but it’s low-level.** Rabbit Relay keeps “real RabbitMQ concepts” (exchanges, queues, routing keys),
+and adds:
 
-**Documentation & Guides**  
-https://bitspacerlabs.github.io/rabbit-relay/
+- **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
 
 ```bash
-npm install @bitspacerlabs/rabbit-relay
+npm i @bitspacerlabs/rabbit-relay
 ```
 
+> Tip: Rabbit Relay ships TypeScript-first and supports both ESM and CommonJS builds.
+
 ---
 
-## Minimal Examples
+## Quickstart (typed events)
 
 ```ts
-import { RabbitMQBroker, event } from "rabbit-relay";
+import { RabbitMQBroker, event } from "@bitspacerlabs/rabbit-relay";
 
 const broker = new RabbitMQBroker("example.service");
 
-const pub = await broker.queue("example.q").exchange("example.exchange", { exchangeType: "topic" });
+// 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 API and publish
 const api = pub.with({ send });
-
 await api.send({ message: "hello world" });
 ```
 
----
-
+### Direct publish (produce)
 
 ```ts
-import { RabbitMQBroker, event } from "rabbit-relay";
+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 pub = await broker
+  .queue("example.q")
+  .exchange("example.direct", { exchangeType: "direct" });
 
 const hello = event("hello", "v1").of<{ msg: string }>();
 
@@ -76,15 +104,43 @@ await pub.produce(hello({ msg: "world" }));
 
 ---
 
-## When to Use Rabbit Relay
+## 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 hidden abstractions
+- 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`](CONTRIBUTING.md)
+- Code of Conduct: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+
+If you want to help but don’t know where to start, check issues labeled **good first issue**.
 
 ---
 
 ## License
 
-MIT © BitSpacerLabs
+MIT © BitSpacer Labs

package/SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+## Supported Versions
+soon
+
+## Reporting a Vulnerability
+
+If you have a security issue to report, please contact us at [bitspacerlabs](bitspacerlabs/rabbit-relay).

package/dist/cjs/backpressure.d.ts

@@ -0,0 +1,4 @@
+import { Channel, Options } from "amqplib";
+export declare const waitForDrain: (ch: Channel) => Promise<void>;
+export declare const publishWithBackpressure: (ch: Channel, exchange: string, routingKey: string, content: Buffer, options?: Options.Publish) => Promise<void>;
+export declare const maybeWaitForConfirms: (ch: Channel) => Promise<void>;

package/dist/cjs/backpressure.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeWaitForConfirms = exports.publishWithBackpressure = exports.waitForDrain = void 0;
+const waitForDrain = (ch) => new Promise((resolve) => {
+    const anyCh = ch;
+    if (typeof anyCh.once === "function")
+        anyCh.once("drain", resolve);
+    else
+        resolve(); // if not supported, resolve immediately
+});
+exports.waitForDrain = waitForDrain;
+const publishWithBackpressure = async (ch, exchange, routingKey, content, options) => {
+    const ok = ch.publish(exchange, routingKey, content, options);
+    if (!ok) {
+        console.warn(`[amqp] publish backpressure: waiting for 'drain' (exchange=${exchange}, key=${routingKey}, size=${content.length})`);
+        const t0 = Date.now();
+        await (0, exports.waitForDrain)(ch);
+        const dt = Date.now() - t0;
+        if (dt >= 1) {
+            console.warn(`[amqp] drain resolved after ${dt}ms (exchange=${exchange}, key=${routingKey})`);
+        }
+    }
+};
+exports.publishWithBackpressure = publishWithBackpressure;
+const maybeWaitForConfirms = async (ch) => {
+    const anyCh = ch;
+    if (typeof anyCh.waitForConfirms === "function") {
+        await anyCh.waitForConfirms();
+    }
+};
+exports.maybeWaitForConfirms = maybeWaitForConfirms;

package/dist/cjs/consumer.d.ts

@@ -0,0 +1,19 @@
+import { Channel } from "amqplib";
+import { EventEnvelope } from "./eventFactories";
+import { ConsumeOptions } from "./types";
+export type HandlerMap = Map<string, (id: string | number, event: EventEnvelope) => Promise<unknown>>;
+export declare function createConsumer(params: {
+    queueName: string;
+    handlers: HandlerMap;
+}): {
+    startConsume: (getChannel: () => Promise<Channel>, opts?: ConsumeOptions) => Promise<{
+        stop: () => Promise<void>;
+    }>;
+    resumeOnReconnect: (ch: Channel) => Promise<void>;
+    getState: () => {
+        isConsuming: boolean;
+        prefetchCount: number;
+        concurrency: number;
+        onError: "ack" | "requeue" | "dead-letter";
+    };
+};