Saga Module for Nestjs framework

Description

This is a NestJS module designed to facilitate the implementation and management of sagas. Sagas are a pattern for managing distributed transactions and long-running processes in a reliable and consistent manner. This package provides a structured way to define, execute, and handle compensations for sagas, ensuring that your application can maintain data consistency across multiple services and operations.

Installation

1npm install @mahyar-kd/nestjs-saga

OR

1yard add @mahyar-kd/nestjs-saga

Usage

Create Saga Command

This class represents a command that will be used in the saga. It contains the data required for the saga to execute.

1export class SampleSagaCommand {
2  constructor(
3    public readonly sampleData: any,
4  ) {}
5}

Create Saga Step

This class implements the SagaStep interface and defines the steps of the saga. It includes methods for invoking the step and handling compensation in case of failure.

1import { SagaStep } from '@mahyar-kd/nestjs-saga';
2
3@Injectable()
4export class SampleSagaStep implements SagaStep {
5  private logger: Logger = new Logger(SampleSagaStep.name, {
6    timestamp: true,
7  });
8
9  constructor(
10    @Inject(CommandBus)
11    public readonly commandBus: CommandBus,
12    @Inject(QueryBus)
13    private readonly queryBus: QueryBus,
14  ) {}
15
16  /**
17   * Invokes the saga step with the given command.
18   * @param cmd - The command to be executed in this step.
19   */
20  async invoke(cmd: SampleSagaCommand) {}
21
22  /**
23   * Handles compensation logic for the saga step in case of failure.
24   * @param cmd - The command to be compensated.
25   */
26  async withCompensation(cmd: SampleSagaCommand) {}
27}

Create Saga

This class defines the saga itself, using the SagaBuilder to chain the steps together. It specifies the command to be used and the steps to be executed.

1import { SagaStep } from '@mahyar-kd/nestjs-saga';
2
3@Saga(SampleSagaCommand)
4export class SampleSaga {
5    constructor(
6    @Inject(SampleSagaStep)
7    public readonly sampleSagaStep: SampleSagaStep,
8  ) {}
9  // Define `saga` field using Builder<SampleSagaCommand> or if you want to return
10  // some value use: SagaBuilder<SampleSagaStep, SampleSagaResponse>
11  
12  saga = new SagaBuilder<SampleSagaCommand>()
13
14    .step(SampleSagaStep.name)
15    .invoke(async (cmd: SampleSagaCommand) =>
16      this.sampleSagaStep.invoke(cmd),
17    )
18    .withCompensation(async (cmd: SampleSagaCommand) =>
19      this.sampleSagaStep.withCompensation(cmd),
20    )
21}

Executing the Saga Command

This code snippet shows how to execute the saga command using the CommandBus. It also demonstrates how to handle exceptions using the SagaExceptionConverterHelper.

1await this.commandBus
2  .execute(new SampleSagaCommand(sampleData))
3  .catch((error) =>
4    SagaExceptionConverterHelper.toHttpException(error.originalError),
5  );