Idempotency Middleware for Express

import express from 'express';
import { idempotency, IIdempotencyDataAdapter } from 'express-idempotency';
import { v4 as uuidv4 } from 'uuid';

// IMPORTANT: For production, replace this with a persistent storage solution (Redis, MongoDB, etc.)
// The default in-memory adapter is not suitable for production environments.
class InMemoryDataAdapter implements IIdempotencyDataAdapter {
    private store = new Map<string, { request: any; response: any; status: string }>();

    async get(idempotencyKey: string): Promise<{ request: any; response: any; status: string } | null> {
        return this.store.get(idempotencyKey) || null;
    }

    async set(idempotencyKey: string, request: any, response: any, status: string): Promise<void> {
        this.store.set(idempotencyKey, { request, response, status });
    }

    async remove(idempotencyKey: string): Promise<void> {
        this.store.delete(idempotencyKey);
    }
}

const app = express();
const port = 3000;

// Middleware to parse JSON bodies
app.use(express.json());

// Initialize the idempotency middleware. Always provide a production-ready data adapter.
app.use(
    idempotency({
        dataAdapter: new InMemoryDataAdapter(), // Replace with a real data adapter for production!
        // Other options like idempotencyKeyHeader, intentValidator, responseValidator can be customized here.
    })
);

// Declare `getSharedIdempotencyService` for TypeScript if it's globally available.
// In a real application, consider explicitly importing a service factory if available,
// or accessing a request-scoped service if the middleware attaches it (e.g., `req.idempotencyService`).
declare function getSharedIdempotencyService(): {
    isHit(req: express.Request): boolean;
    reportError(req: express.Request): void;
};

app.post('/process-payment', (req, res) => {
    // Retrieve the IdempotencyService instance.
    const idempotencyService = getSharedIdempotencyService();

    // Crucial: Check if the request is an idempotency hit. If so, prevent further processing.
    if (idempotencyService.isHit(req)) {
        console.log('Idempotency hit detected, a cached response should have been sent by the middleware.');
        // The middleware is designed to send the cached response and then call next().
        // Your route handler should return early here to avoid re-executing business logic.
        return;
    }

    // --- Your business logic starts here (only for non-idempotent requests) ---
    console.log('Processing new payment for:', req.body);
    const transactionId = uuidv4();
    const amount = req.body.amount;

    if (amount <= 0) {
        // If an error occurs during processing, report it to the middleware
        // so that the idempotency state for this key can be cleared or updated.
        idempotencyService.reportError(req);
        return res.status(400).json({ error: 'Amount must be positive.' });
    }

    // Simulate an asynchronous payment processing operation
    setTimeout(() => {
        const responseData = {
            message: `Payment for ${amount} processed successfully.`,
            transactionId: transactionId,
            status: 'completed',
        };
        res.status(200).json(responseData);
        console.log('Payment processed and response sent.');
    }, 1000);
});

app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
    console.log(`
To test, send a POST request with an 'Idempotency-Key' header:`)
    console.log(`curl -X POST -H "Content-Type: application/json" -H "Idempotency-Key: my-unique-key-123" -d '{"amount": 100}' http://localhost:${port}/process-payment`);
    console.log(`
Repeat the curl command with the *same* 'my-unique-key-123' to observe idempotency in action (cached response).`);
    console.log(`Use a *different* key for a new payment.`);
});