@node-idempotency/core

makes any request idempotent.

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.
• Customizable: options to tweak the library as per your need.
• RFC compliant: Adheres to standards for compatibility with other systems/clients.

and powers

• @node-idempotency/nestjs - Plug and Play nestjs wrapper for @node-idempotency/core

• @node-idempotency/express - Plug and Play express middleware for @node-idempotency/core

• @node-idempotency/fastify - Plug and Play fastify plugin for @node-idempotency/core

if above packages dont meet your needs, you can utilise the core package directly to tweek it as per your needs.

---

How?

install

1npm i @node-idempotency/core

usage

The flow for idempotency is simple, you call the onRequest handler, when you receieve the request from clients before it reaches your business logic/controller.

onRequest handler validates request for conflicts, figerprint missmatch, no idempotency-key(when idempotency is enforced) and gives back the response if the key is already seen, you typically give back the "cached" response to the client.

if its a new request, it marks the request as progress generates fingerprint using body (so that it can validate conflicts for duplicate requests and figure out fingerprint missmatch), and returns undefined, you are responsible here to pass the request to your controller/business logic.

onResponse handler is called by you when your business logic completes for the first time, so that the response can be stored and the request can be marked as complete.

1import { Idempotency } from "@node-idempotency/core";
2import { MemoryStorageAdapter } from "@node-idempotency/storage-adapter-memory";
3
4// Create an Idempotency instance using a MemoryStorageAdapter
5const idempotency = new Idempotency(new MemoryStorageAdapter(), {
6  ...idempotencyOptions,
7});
8
9// On receiving a request, call `onRequest` to validate idempotency
10try {
11  const response = await idempotency.onRequest({
12    method: "POST",
13    headers: { "idempotency-key": "123" },
14    body: { pay: 100 },
15    path: "/charge",
16    options: { ...idempotencyOptions }, // Optional request-level overrides
17  });
18
19  if (!response) {
20    // New request, allow it to proceed
21    return;
22  }
23
24  // Duplicate request, return previous response
25  // Example: res.status(response.additional.status).send(response.body)
26} catch (err) {
27  // Handle idempotency errors (conflict, in-progress, fingerprint mismatch, etc.)
28  // Refer to API documentation for specific error codes
29}
30
31// Intercept response to complete the idempotency cycle
32const response = await idempotency.onResponse(
33  {
34    method: "POST",
35    headers: { "idempotency-key": "123" },
36    body: { pay: 100 },
37    path: "/charge",
38    options: { ...idempotencyOptions }, // Optional request-level overrides
39  },
40  {
41    body: { charge: "success" }, // or error: your_error
42    additional: { status: 201 },
43  },
44);

check details about the api here