One-line idempotency middleware for Express

[violetta98]

A client retries a POST, your handler runs twice, and someone gets charged twice. It's the kind of bug you hear about from support rather than from a test.

import express from "express";
import { InMemoryBackend } from "idemkit";
import { idempotency } from "idemkit/express";

const app = express();
app.use(idempotency({ backend: new InMemoryBackend() }));

app.post("/charge", (req, res) => {
  res.status(201).json({ charged: true }); // runs once per Idempotency-Key
});

Send the same request twice and the second one comes back with idempotency-replayed: true, handler never touched. Redis, Postgres, Mongo or DynamoDB in production.

It also survives the awkward case: if a worker dies mid-charge, the key frees itself instead of staying stuck, and that worker's late write gets rejected rather than overwriting the real result.

Zero dependencies, Apache-2.0: https://github.com/idemkit/idemkit

If you find it useful, a star would be much appreciated.

[krzysdz]

POST is neither safe nor idempotent. PUT is intended for idempotent actions - it sets the target to a specific value, whether or not it alredy exists. If you need to detect replied requests, then these are not idempotent (in which case you wouldn't have to care about this). Doing a thing on the first request and then behaving differently on the second one is very much not idempotency.

As others have already written in other projects, where you have opened similar discussions, what you're trying to do is wrong and a misunderstanding of the problem (and vocabulary).

[violetta98]

POST not being idempotent is the premise of the pattern, not an objection to it. If POST were idempotent there would be nothing to build.

Worth pinning the definition down first. RFC 9110 §9.2.2: a method is idempotent if "the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request." The criterion is the effect on the server, not whether the handler takes the same branch. One charge stays one charge, and the client gets back the same status and body, so two requests are indistinguishable from one. Running the charge a second time is what would break the property.

Which brings me to "doing a thing on the first request and then behaving differently on the second one is very much not idempotency". That is exactly what the specifications prescribe. Google's AIP-155: "Providing a request ID must guarantee idempotency", and "if a duplicate request is detected, the server should return the response for the previously successful request, because the client most likely did not receive the previous response."

Stripe implements the same thing and documents it plainly: "Stripe's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key... Subsequent requests with the same key return the same result, including 500 errors." They also reject a reused key whose parameters differ, and they draw precisely the distinction you're drawing: "All POST requests accept idempotency keys. Don't send idempotency keys in GET and DELETE requests because it has no effect. These requests are idempotent by definition."

PUT is idempotent if it is implemented correctly, and §9.2.2 is explicit that the protocol does not enforce that. If it is implemented wrongly, with a handler that charges the card on every call, two concurrent PUTs still charge twice. Whichever verb you pick, something has to make the check and the write a single atomic step, and that is the part this does.

On vocabulary: draft-ietf-httpapi-idempotency-key-header in the httpapi working group (expired, v07 October 2025) opens with "can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant." The IETF, Google and Stripe all use the term this way for this mechanism.