NestJS Service Bus

A powerful NestJS library for building reliable distributed systems with RabbitMQ. Simplifies message-based communication with support for the Saga Pattern, Routing Slips, and comprehensive Retry Strategies for managing distributed transactions.

📚 Documentation

- 📖 Complete Documentation Index - Find everything in one place
- 🛠️ Setup Guide - Installation and configuration details
- 📘 Routing Slips Guide - Activity-based workflow orchestration
- 📕 Saga Compensation Guide - Event-driven state machine compensation
- 💾 Saga Persistence Guide - Production-ready state persistence
- ⚙️ Retry Strategies - Handle failures gracefully
- 👨‍💻 Code Examples - Full working examples

Why Use This Library?

In a microservices architecture, handling transactions that span across multiple services (distributed transactions) is a significant challenge. The Saga Pattern provides an effective solution for maintaining data consistency by orchestrating a sequence of local transactions, with the ability to roll back if any step fails.

This library offers:

* Easy NestJS Integration: Leveraging NestJS features like dependency injection, decorators, and modules for seamless Service Bus configuration and usage.
* Saga Pattern Implementation: Provides tools and structures to define, execute, and monitor Sagas, ensuring data consistency even when failures occur.
* Production-Ready Saga Persistence: Database-backed state management with support for MongoDB, PostgreSQL, and in-memory storage, including optimistic locking and auto-archiving.
* Routing Slips Pattern: Activity-based workflow coordination with automatic compensation for distributed transactions.
* Comprehensive Retry Strategies: Four retry strategies (Immediate, Interval, Intervals, Exponential) at two levels (Retry + Redelivery).
* RabbitMQ Powered: Utilizes RabbitMQ's performance and reliability as the message transport layer, supporting queuing, routing, and publish/subscribe.
* Scalability: Designed to be easily extensible and customizable to meet specific project needs.
* Robust Error Handling: Built-in error handling mechanisms help manage failure scenarios and trigger compensation steps within a Saga.

Getting Started

$3

``bash
npm install nestjs-bustransit uuid

or

yarn add nestjs-bustransit uuid
`

Roadmap

- [x] RabbitMq Broker
- [x] Retry Level 1 (Immediate, Interval, Intervals, Exponential)
- [x] Retry Level 2 (Redelivery with all strategies)
- [x] Saga pattern
- [x] Saga compensation
- [x] Saga state persistence (MongoDB, PostgreSQL, In-Memory)
- [x] Routing slips pattern
- [ ] Kafka broker

Core Features

$3

Comprehensive retry mechanisms with 4 strategies (Immediate, Interval, Intervals, Exponential) at 2 levels (Retry + Redelivery). Handle transient failures gracefully with automatic backoff and requeuing.

→ Read the Retry Strategies Guide

$3

Easy setup for message consumers and producers with NestJS dependency injection. Configure endpoints, prefetch counts, and retry policies with a fluent API.

→ See Configuration Examples

`typescript
// Configure consumers and retry policies
x.AddConsumer(SubmitOrderConsumer);
x.UsingRabbitMq('my-app', (context, cfg) => {
cfg.ReceiveEndpoint("orders-queue", e => {
e.ConfigureConsumer(SubmitOrderConsumer, context, c => {
c.UseMessageRetry(r => r.Immediate(5));
c.UseRedelivery(r => r.Exponential(5, 5000, 2));
});
});
});
`

$3

Event-driven state machines with automatic compensation. Build complex workflows that maintain data consistency across distributed services. Define compensating actions that execute in reverse order when failures occur.

Key Features:
- State machine orchestration
- Event-driven transitions
- Automatic LIFO compensation
- Long-running process support

→ Read the Saga Compensation Guide
→ View Saga Examples

!Saga Workflow

$3

Production-ready state management for saga state machines with database persistence. Persist saga state across application restarts with support for multiple storage backends.

Key Features:
- Multiple storage adapters (InMemory, MongoDB, PostgreSQL)
- Optimistic locking for concurrent updates
- Auto-archiving with configurable TTL
- Retry logic with exponential backoff
- Backward compatible (defaults to in-memory)
- Async configuration support

→ Read the Saga Persistence Guide
→ Configuration Guide
→ Migration Guide

`typescript
// Configure persistence for production
@Module({
imports: [
SagaPersistenceModule.forRoot({
type: SagaPersistenceType.MongoDB,
connection: {
uri: 'mongodb://localhost:27017',
database: 'bustransit',
collectionName: 'saga_states'
},
autoArchive: true,
archiveTTL: 86400 * 30 // 30 days
}),
BusTransit.AddBusTransit.setUp(bus => {
bus.AddSagaStateMachine(OrderStateMachine, OrderState);
})
]
})
export class AppModule {}
``

$3

Activity-based workflow orchestration inspired by MassTransit's Routing Slips. Build dynamic, multi-service workflows with reusable activities and automatic compensation.

Key Features:
- Reusable activity components
- Dynamic runtime itineraries
- Automatic LIFO compensation
- Rich event system (Completed, Faulted, ActivityCompleted, etc.)
- Variable passing between activities

→ Read the Routing Slips Guide
→ Quick Start Tutorial
→ View Routing Slip Examples

When to use:
- Routing Slips: Multi-service workflows, dynamic orchestration, reusable activities
- Saga Compensation: Complex state machines, long-running processes, event-driven flows

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.