# relaybus

> relaybus is a reliable, storage-agnostic event bus for NestJS and Node.js: a transactional outbox with per-handler retries, leases, dead letters and ordering keys for PostgreSQL and MongoDB, with Kafka and RabbitMQ transports.

relaybus stores every event in the same database transaction as your business data (the transactional outbox pattern), then delivers it to each handler and broker with independent retries, leases and dead letters. Packages: @relaybus/core, @relaybus/nestjs, @relaybus/postgres, @relaybus/mongodb, @relaybus/kafka, @relaybus/rabbitmq, @relaybus/testing, @relaybus/eslint-plugin, @relaybus/otel. Requires Node.js 22.12 or newer; NestJS 11 or 12 for the NestJS module.

## Start here

- [Getting started](https://berkcansavur.github.io/relaybus/getting-started.md): Add a reliable transactional outbox event bus to a NestJS and PostgreSQL service in five minutes.
- [Guarantees](https://berkcansavur.github.io/relaybus/guarantees.md): Exactly what relaybus guarantees (atomic publish, at-least-once delivery, per-key ordering, fencing) and what it does not.

## Concepts

- [Transactional outbox](https://berkcansavur.github.io/relaybus/concepts/outbox.md): How the transactional outbox pattern avoids dual writes, and how relaybus implements it with deliveries per handler.
- [Deliveries](https://berkcansavur.github.io/relaybus/concepts/deliveries.md): A delivery is one event for one handler or route, with its own status, attempts and retry schedule.
- [Leases and fencing](https://berkcansavur.github.io/relaybus/concepts/leases.md): How competing workers claim deliveries with leases and why a stalled worker cannot overwrite the worker that took over.
- [Retries and backoff](https://berkcansavur.github.io/relaybus/concepts/retries.md): Capped exponential backoff with full jitter, timeouts and non-retryable errors in relaybus.
- [Ordering keys](https://berkcansavur.github.io/relaybus/concepts/ordering-keys.md): Per-key ordering in commit order: how the sequence is assigned and what it does and does not promise.
- [Compile-time safety with event catalogs](https://berkcansavur.github.io/relaybus/concepts/event-catalogs.md): Group events in a catalog so the TypeScript compiler rejects a missing handler, a wrong payload or an event published to the wrong catalog, and a boot check catches the rest.
- [Dead letters](https://berkcansavur.github.io/relaybus/concepts/dead-letters.md): What happens to events that exhaust their retries, and how to inspect and requeue them.
- [Observability](https://berkcansavur.github.io/relaybus/concepts/observability.md): OpenTelemetry metrics and traces for relaybus: the metrics, one trace across services, a collector and Prometheus setup, and alerts on backlog age and dead letters.
- [Error codes](https://berkcansavur.github.io/relaybus/concepts/error-codes.md): The stable, machine-readable code of every relaybus error, stored with dead letters and reported to observers.

## Packages

- [All packages](https://berkcansavur.github.io/relaybus/packages/index.md): The nine @relaybus packages: core, nestjs, postgres, mongodb, kafka, rabbitmq, testing, eslint-plugin and otel.
- [@relaybus/core](https://berkcansavur.github.io/relaybus/packages/core.md): Reliable event bus for Node.js: a transactional outbox with per-handler deliveries, retries with jitter, dead letters and per-key ordering on top of your own database.
- [@relaybus/nestjs](https://berkcansavur.github.io/relaybus/packages/nestjs.md): NestJS event bus module for relaybus: @RelayBusConsumer handlers on a transactional outbox, with retries, dead letters and graceful shutdown, so events are never lost between your database and your handlers.
- [@relaybus/postgres](https://berkcansavur.github.io/relaybus/packages/postgres.md): PostgreSQL event store for relaybus: a transactional outbox written in your own transaction (pg, Prisma, TypeORM, Drizzle, Knex, Kysely) with SKIP LOCKED leasing and per-key ordering.
- [@relaybus/mongodb](https://berkcansavur.github.io/relaybus/packages/mongodb.md): MongoDB event store for relaybus: a transactional outbox on multi-document transactions (driver or Mongoose sessions) with atomic leasing and per-key ordering.
- [@relaybus/kafka](https://berkcansavur.github.io/relaybus/packages/kafka.md): Kafka transport for relaybus: forwards committed outbox events to Kafka topics (CloudEvents binding) and consumes them with an idempotent inbox, so events are not lost between database and Kafka.
- [@relaybus/rabbitmq](https://berkcansavur.github.io/relaybus/packages/rabbitmq.md): RabbitMQ transport for relaybus: publisher-confirmed publishing from the transactional outbox and acknowledged, idempotent consumption with retry queues and dead-letter queues.
- [@relaybus/testing](https://berkcansavur.github.io/relaybus/packages/testing.md): Testing utilities for relaybus: the EventStore contract suite, a FakeClock and an in-memory transport for deterministic tests of retries, delays and dead letters, and a codec contract that runs under Vitest, Jest or any other test framework.
- [@relaybus/eslint-plugin](https://berkcansavur.github.io/relaybus/packages/eslint-plugin.md): ESLint rules for relaybus: no calls to other services inside a transaction, and no publish outside a transaction, so outbox transactions stay short and events stay atomic with your writes.
- [@relaybus/otel](https://berkcansavur.github.io/relaybus/packages/otel.md): OpenTelemetry for relaybus: messaging metrics after the semantic conventions, outbox backlog gauges, and one trace from publish in one service to the handler in another, with W3C trace context in event headers.

## Recipes

- [Transactions in NestJS](https://berkcansavur.github.io/relaybus/recipes/transactions-in-nestjs.md): Run NestJS service methods in an outbox transaction with @RelayBusTransaction(), share it with repositories, hold it to a time budget and lint external calls out of it.
- [Serializable transactions](https://berkcansavur.github.io/relaybus/recipes/serializable-transactions.md): Run a relaybus transaction at repeatable read or serializable so PostgreSQL detects write skew without locks, with automatic rerun of serialization failures.
- [Prisma](https://berkcansavur.github.io/relaybus/recipes/prisma.md): Publish transactional outbox events from a Prisma interactive transaction with @relaybus/postgres.
- [TypeORM](https://berkcansavur.github.io/relaybus/recipes/typeorm.md): Publish events in the same TypeORM transaction as your entities using the TypeORM executor.
- [Mongoose](https://berkcansavur.github.io/relaybus/recipes/mongoose.md): Use the MongoDB transactional outbox with Mongoose sessions and replica sets.
- [Kafka between services](https://berkcansavur.github.io/relaybus/recipes/kafka-between-services.md): Send events from one service to another through Kafka without losing events between the database and the broker.
- [RabbitMQ](https://berkcansavur.github.io/relaybus/recipes/rabbitmq.md): Publish outbox events to RabbitMQ with publisher confirms and consume them with an idempotent inbox.
- [Interoperating with non-relaybus services](https://berkcansavur.github.io/relaybus/recipes/interoperating-with-other-services.md): Exchange events with services that do not use relaybus over Kafka and RabbitMQ: the wire format, and decoding plain JSON and structured CloudEvents with exactly-once handling.
- [Testing with FakeClock](https://berkcansavur.github.io/relaybus/recipes/testing-with-fakeclock.md): Test retries, delays and dead letters deterministically with FakeClock and the in-memory store.

## Reference

- [relaybus vs alternatives](https://berkcansavur.github.io/relaybus/comparison.md): How relaybus compares with @nestjs/event-emitter, @nestjs/cqrs, @nestjs/outbox, BullMQ, pg-boss and using Kafka directly.
- [Tuning for your workload](https://berkcansavur.github.io/relaybus/tuning.md): Recommended relaybus settings for a single-connection API, a high-traffic API, a worker fleet, PgBouncer in transaction mode and a MongoDB replica set.
- [Upgrading](https://berkcansavur.github.io/relaybus/upgrading.md): Step-by-step upgrades: 0.2 to 0.3: route id change and draining the old route backlog, the 5 second transaction budget, the StopResult of stop(), decorator and codec renames, error codes and the optional new packages.
- [Stability](https://berkcansavur.github.io/relaybus/stability.md): The relaybus API stability policy: semver for 0.x and 1.x, what is public API, deprecations, wire-format and database schema stability, supported runtimes.
- [Compatibility](https://berkcansavur.github.io/relaybus/compatibility.md): The tested matrix of relaybus (Node.js, CommonJS and ESM, NestJS, PostgreSQL clients and ORMs, MongoDB, Kafka, RabbitMQ), what is unsupported and notes for serverless.
- [Performance: 0.2.0 vs 0.1.0](https://berkcansavur.github.io/relaybus/performance.md): Measured throughput, latency and write amplification of relaybus 0.2.0 against 0.1.0 on PostgreSQL and MongoDB, with methodology, machine and honest sample counts.
- [Write amplification in the delivery path](https://berkcansavur.github.io/relaybus/performance/write-amplification.md): Why relaybus 0.1.0 rewrote delivery rows, how lane leases and delete-on-complete remove it, which guarantees are preserved, and what it measured.
- [The publish path and prepared statements](https://berkcansavur.github.io/relaybus/performance/publish-path.md): Per-event round trips, WAL bytes and plan times of the 0.2.0 publish and claim statements against 0.1.0, and the prepared-statement fix.
- [FAQ](https://berkcansavur.github.io/relaybus/faq.md): Answers to common questions: publishing events reliably in NestJS, the transactional outbox pattern and avoiding lost events between a database and Kafka.
- [Releases](https://berkcansavur.github.io/relaybus/releases.md): What is new in relaybus 0.4.0 and 0.3.0, breaking changes, deprecations, known issues and benchmarks, and how relaybus is versioned and released.

## Optional

- [Full documentation in one file](https://berkcansavur.github.io/relaybus/llms-full.txt): every page above concatenated as Markdown
- [Documentation website](https://berkcansavur.github.io/relaybus/): the same content as HTML
- [Source repository](https://github.com/berkcansavur/relaybus): code, issues and GitHub Releases (the changelog)
- [npm: @relaybus/core](https://www.npmjs.com/package/@relaybus/core): the engine package