@node-idempotency/nestjs

@node-idempotency/nestjs

Nestjs wrapper for Node-Idempotency. Implements @node-idempotency/core as a nestjs interceptor.

Why?

Network requests are unpredictable; clients/proxies may send duplicate or concurrent requests due to retries or network issues. To ensure smooth operation, servers must process each request only once. This package detects and handles duplicates, preventing issues like double charging the customer. It's:

• Race Condition free: Ensures consistent behavior even during concurrent requests.
• Modular: Easily integrates with your storage or existing implementation, adding a decorator makes the endpoint idempotent.
• Customizable: options to tweak the library as per your need.
• RFC compliant: Adheres to standards for compatibility with other systems/clients.

How?

instal

npm i @node-idempotency/nestjs

usage

• Register the module

import { NodeIdempotencyModule } from '@node-idempotency/nestjs';

@Module({
  imports: [
    NodeIdempotencyModule.forRootAsync({
      storage: {
        adapter: StorageAdapterEnum.memory, // or 'redis'
        options: /* adapter options */,
      },
      ...idempotencyOptions, // additional idempotency options
    }),
  ],
})
export class AppModule {}

// OR using factory method

import { NodeIdempotencyModule } from '@node-idempotency/nestjs';
import { type DynamicModule, Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";

@Module({})
export class AppModule {
    static forRootAsync(): DynamicModule {
    return {
      global: true,
      module: AppModule,
      controllers: [AppController],
      imports: [
        NodeIdempotencyModule.forRootAsync({
          imports: [ConfigModule.forRoot()],
          inject: [ConfigService],
          useFactory: async (configService: ConfigService) => {
            return {
              storage: {
                adapter: StorageAdapterEnum.redis,
                options: {
                  url: configService.get("REDIS_URL"),
                },
              },
              cacheTTLMS: configService.get("CACHE_TTL"),
              ...idempotencyOptions, // additional idempotency options
            };
          },
        }),
      ],
    };
  }
}

• storage.adapter can either be memory, redis or an instance of Storage interface.
• storage.options are options to the storage client, required for redis, is client options of redis client.
• idempotencyOptions are the IdempotencyOptions passed to @node-idempotency/core/Idempotency

• Decorate controllers or handlers

• Decorating controllers

import { Controller, Get, Post, HttpCode, Body } from "@nestjs/common";
import { Idempotent } from "@node-idempotency/nestjs";

@Controller()
@Idempotent({ ...idempotencyOptions }) // Override module-level options
export class CounterController {
  counter = 0;

  @Get()
  getNumber(): number {
    return this.counter++;
  }

  @Post()
  @HttpCode(201)
  async addNumber(@Body() { number }: { number: number }): Promise<number> {
    this.counter += number;
    return this.counter;
  }
}

• Decorating selected handlers

import { Controller, Get, Post, HttpCode, Body } from "@nestjs/common";
import { Idempotent } from "@node-idempotency/nestjs";

@Controller()
export class CounterController {
  counter = 0;

  @Idempotent({ ...idempotencyOptions }) // Override module-level options
  @Get()
  getNumber(): number {
    return this.counter++;
  }

  @Post()
  @HttpCode(201)
  async addNumber(@Body() { number }: { number: number }): Promise<number> {
    this.counter += number;
    return this.counter;
  }
}

Library also exports the interceptor, you can use it like you would use any nestjs interceptors(ex: registering globaly)

import { NodeIdempotencyInterceptor } from "@node-idempotency/nestjs";