@idempotix/express

@idempotix/express

Express middleware for HTTP idempotency.

Installation

npm install @idempotix/core @idempotix/express

Quick Start

import express from 'express';
import { express as idempotent } from '@idempotix/express';

const app = express();
app.use(express.json());

// Zero-config: memory storage, 24h TTL
app.post('/orders', idempotent(), async (req, res) => {
  const order = await createOrder(req.body);
  res.status(201).json(order);
});

Configuration

app.post(
  '/payments',
  idempotent({
    storage: redis(), // Storage adapter
    ttl: '1h', // Cache duration
    required: true, // Require Idempotency-Key header
    methods: ['POST', 'PUT'], // HTTP methods to protect
    failOpen: true, // Continue if storage fails
    getKey: (req) => req.headers['x-request-id'], // Custom key extraction
    getHash: (req) => hashObject(req.body), // Custom hash function
    onHit: (key, response) => {}, // Cache hit callback
    onMiss: (key) => {}, // Cache miss callback
    onError: (key, error) => {}, // Error callback
  }),
  handler
);

Pre-configured Factory

Share configuration across routes:

import { configure } from '@idempotix/express';
import { redis } from '@idempotix/redis';

const idempotent = configure({
  storage: redis(),
  ttl: '1h',
});

app.post('/orders', idempotent(), orderHandler);
app.post('/payments', idempotent({ required: true }), paymentHandler);

Headers

Header	Direction	Description
Idempotency-Key	Request	Client-provided unique key
Idempotency-Key	Response	Echo of the key used
Idempotency-Replay	Response	true when returning cached response

Error Responses

All errors follow RFC 7807 Problem Details:

Status	Type	Cause
400	key-required	Missing key when required: true
409	conflict	Request with same key in progress
422	mismatch	Same key reused with different body

{
  "type": "https://Idempotix.dev/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A request with this idempotency key is already being processed"
}

With Redis

import { redis } from '@idempotix/redis';

app.post('/orders', idempotent({ storage: redis() }), handler);

License

MIT