@hazeljs/saga

Distributed Transaction Management for HazelJS. Orchestration, Choreography, and Auto-Compensation.

Manage complex, multi-service transactions with ease. Whether you prefer centralized control (Orchestration) or decentralized event-driven flows (Choreography), HazelJS Saga provides a robust, decorator-based framework to ensure data consistency across your distributed system.

Features

• 🔄 Dual Models — Orchestration for centralized control and Choreography for decentralized, event-driven coordination.
• 🛠️ Decorator-Based API — Declarative Saga definition using @Saga, @SagaStep, and @OnEvent.
• ⏪ Auto-Compensation — Automatically reverses completed steps in reverse order when a failure occurs.
• 📊 Status Management — Built-in tracking for STARTED, COMPENSATING, ABORTED, and COMPLETED states.
• 🧠 Context Awareness — Type-safe SagaContext to pass state and data across multiple transaction steps.
• 🔌 HazelJS Integration — Seamlessly works with @hazeljs/event-emitter and @hazeljs/core.

Installation

npm install @hazeljs/saga

Peer Dependencies

@hazeljs/saga works with @hazeljs/core for runtime integration and @hazeljs/event-emitter for choreography events. Install them alongside:

npm install @hazeljs/core @hazeljs/event-emitter

You do not need to install or import reflect-metadata yourself. @hazeljs/saga declares it as a regular dependency and its decorator modules load it via a side-effect import. Just enable experimentalDecorators in your tsconfig.json.

Quick Start (Orchestration)

The Orchestration model uses a central class to coordinate the workflow. If a step fails, compensation methods are automatically triggered.

1. Define the Saga

import { Saga, SagaStep } from '@hazeljs/saga';

@Saga({ name: 'order-saga' })
export class OrderSaga {
  @SagaStep({ order: 1, compensate: 'cancelOrder' })
  async createOrder(data: any) {
    console.log('Order created for:', data.productId);
    return { orderId: 'ord_123' };
  }

  @SagaStep({ order: 2, compensate: 'releaseInventory' })
  async reserveInventory(data: any) {
    // Logic to reserve stock...
    return { status: 'RESERVED' };
  }

  async cancelOrder(data: any) {
    console.log('Reversing order...');
  }

  async releaseInventory(data: any) {
    console.log('Releasing stock...');
  }
}

2. Execute the Saga

import { SagaOrchestrator } from '@hazeljs/saga';

const orchestrator = SagaOrchestrator.getInstance();
const context = await orchestrator.start('order-saga', { productId: 'p1', userId: 'u1' });

console.log(`Saga Status: ${context.status}`); // COMPLETED or ABORTED

Orchestration vs. Choreography

| Feature | Orchestration | Choreography | | -------------- | ----------------------------------- | ---------------------------------------------- | | Control | Centralized in one class | Decentralized across handlers | | Coupling | High (Orchestrator knows all steps) | Low (Each service reacts to events) | | Complexity | Simple for small/medium flows | Better for very large, loosely coupled systems | | Visibility | Single point of truth | Distributed across the system |

Saga Choreography

Choreography is entirely event-driven. Handlers subscribe to events and emit new ones to trigger the next phase of the transaction.

import { SagaChoreography, OnEvent } from '@hazeljs/saga';

@SagaChoreography()
export class ShippingChoreography {
  @OnEvent('inventory.reserved')
  async handleInventoryReserved(order: any) {
    console.log('Shipping label generated for:', order.id);
    // Emit 'shipping.labeled' to continue the flow
  }

  @OnEvent('payment.failed')
  async handlePaymentFailed(order: any) {
    console.log('Cancelling shipping for:', order.id);
    // Manual compensation for choreography
  }
}

Saga Lifecycle & Statuses

The SagaContext tracks the status of the transaction as it progresses:

| Status | Description | | -------------- | ------------------------------------------------------ | | STARTED | Execution has begun. | | COMPLETED | All steps finished successfully. | | FAILED | A step encountered an error; compensation is pending. | | COMPENSATING | Reversing previously completed steps. | | ABORTED | Compensation finished; the transaction is rolled back. |

API Reference

SagaOrchestrator

class SagaOrchestrator {
  static getInstance(): SagaOrchestrator;
  registerSaga(name: string, target: any): void;
  registerStep(sagaName: string, methodName: string, options: SagaStepOptions): void;
  start<T>(sagaName: string, initialData: T): Promise<SagaContext<T>>;
}

Decorators

• @Saga(options) — Marks a class as a centralized Saga Orchestrator.
• @SagaStep(options) — Marks a method as a step. Options include order and compensate (method name).
• @SagaChoreography() — Marks a class as a collection of event-driven saga handlers.
• @OnEvent(eventName) — Subscribes a method to a specific event within a choreography.

Use Cases

• 🛒 E-commerce Checkout — Coordinating orders, payments, and inventory.
• 🏨 Hotel/Flight Bookings — Managing multi-vendor reservation systems.
• 💳 Financial Transfers — Ensuring atomic-like consistency across different account services.
• 🏗️ Infrastructure Provisioning — rolling back cloud resource creation on failure.

License

Apache-2.0

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.