@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

1npm i @node-idempotency/nestjs

usage

1. Register the module

1import { NodeIdempotencyModule } from '@node-idempotency/nestjs';
2
3@Module({
4  imports: [
5    NodeIdempotencyModule.forRootAsync({
6      storage: {
7        adapter: StorageAdapterEnum.memory, // or 'redis'
8        options: /* adapter options */,
9      },
10      ...idempotencyOptions, // additional idempotency options
11    }),
12  ],
13})
14export class AppModule {}
15
16// OR using factory method
17
18import { NodeIdempotencyModule } from '@node-idempotency/nestjs';
19import { type DynamicModule, Module } from "@nestjs/common";
20import { ConfigModule, ConfigService } from "@nestjs/config";
21
22@Module({})
23export class AppModule {
24    static forRootAsync(): DynamicModule {
25    return {
26      global: true,
27      module: AppModule,
28      controllers: [AppController],
29      imports: [
30        NodeIdempotencyModule.forRootAsync({
31          imports: [ConfigModule.forRoot()],
32          inject: [ConfigService],
33          useFactory: async (configService: ConfigService) => {
34            return {
35              storage: {
36                adapter: StorageAdapterEnum.redis,
37                options: {
38                  url: configService.get("REDIS_URL"),
39                },
40              },
41              cacheTTLMS: configService.get("CACHE_TTL"),
42              ...idempotencyOptions, // additional idempotency options
43            };
44          },
45        }),
46      ],
47    };
48  }
49}
50
51

• 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

2. Decorate controllers or handlers

• Decorating controllers

1import { Controller, Get, Post, HttpCode, Body } from "@nestjs/common";
2import { Idempotent } from "@node-idempotency/nestjs";
3
4@Controller()
5@Idempotent({ ...idempotencyOptions }) // Override module-level options
6export class CounterController {
7  counter = 0;
8
9  @Get()
10  getNumber(): number {
11    return this.counter++;
12  }
13
14  @Post()
15  @HttpCode(201)
16  async addNumber(@Body() { number }: { number: number }): Promise<number> {
17    this.counter += number;
18    return this.counter;
19  }
20}

• Decorating selected handlers

1import { Controller, Get, Post, HttpCode, Body } from "@nestjs/common";
2import { Idempotent } from "@node-idempotency/nestjs";
3
4@Controller()
5export class CounterController {
6  counter = 0;
7
8  @Idempotent({ ...idempotencyOptions }) // Override module-level options
9  @Get()
10  getNumber(): number {
11    return this.counter++;
12  }
13
14  @Post()
15  @HttpCode(201)
16  async addNumber(@Body() { number }: { number: number }): Promise<number> {
17    this.counter += number;
18    return this.counter;
19  }
20}

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

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