Registry / web-framework / express-idempotency-middleware

express-idempotency-middleware

library1.0.2jsnpmunverified

Express middleware for idempotent POST requests using Idempotency-Key header (version 1.0.2, stable release, active development). Provides pluggable stores (Memory, Redis, Postgres), in-flight concurrency control with wait or reject strategies, and safe response replay with header whitelist. TypeScript-first, ESM-only, requires Node ≥18 and Express 4 or 5. Differentiators: built-in in-flight handling via wait timeout polling, stable response fingerprinting, and separate replay header whitelist for security-aware caching of location headers without cookies or auth tokens. Designed for payment, order, and webhook idempotency scenarios.

web-framework http-networking

npm install express-idempotency-middleware

github ↗package ↗

INSTALL

IMPORT

SIG · EXPRESS-IDEMPOTENC

express-idempotency-middleware

web-frameworkjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

idempotencyMiddleware

✓ import { idempotencyMiddleware } from 'express-idempotency-middleware'

✗ const { idempotencyMiddleware } = require('express-idempotency-middleware')

ESM-only package; CommonJS require is not supported

MemoryStore

✓ import { MemoryStore } from 'express-idempotency-middleware'

✗ import MemoryStore from 'express-idempotency-middleware/MemoryStore'

MemoryStore is a named export, not a default export or subpath

IdemOptions

✓ import type { IdemOptions } from 'express-idempotency-middleware'

✗ import { IdemOptions } from 'express-idempotency-middleware'

Type-only import for TypeScript; requires 'type' keyword for runtime efficiency

Creates an Express app with idempotency middleware on POST /payments, using MemoryStore, wait strategy for in-flight requests, and replay header whitelist.

import express from 'express'; import { idempotencyMiddleware, MemoryStore } from 'express-idempotency-middleware'; const app = express(); app.use(express.json()); const store = new MemoryStore(); app.post( '/payments', idempotencyMiddleware({ store, ttlMs: 24 * 60 * 60 * 1000, inFlight: { strategy: 'wait', waitTimeoutMs: 3000, pollMs: 100 }, replay: { headerWhitelist: ['location'] } }), async (req, res) => { const orderId = 'ord_' + Math.random().toString(36).slice(2); res.setHeader('Location', `/orders/${orderId}`); res.status(201).json({ orderId }); } ); app.listen(3000);

Debug

Known issues

breakingESM-only package: require() throws ERR_REQUIRE_ESM

fix

Use ESM imports: import { idempotencyMiddleware } from 'express-idempotency-middleware'

affects: >=1.0.0

gotchaMemoryStore does not persist across server restarts; use Redis or Postgres store in production

fix

Implement custom store implementing Store interface or use provided examples for RedisStore/PostgresStore

affects: >=1.0.0

gotchaIdempotency-Key is case-sensitive and must be a string; omit or empty key with requireKey:false returns 400

fix

Always send a valid non-empty Idempotency-Key header, or set requireKey:true to enforce

affects: >=1.0.0

deprecatedNode.js <18 is not supported; engines field specifies >=18.0.0

fix

Upgrade Node.js to version 18 or later

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Named export 'idempotencyMiddleware' not found. The requested module 'express-idempotency-middleware' is a CommonJS module which may not support all module.exports as named exports.

Using CommonJS require() instead of ESM import

fix

Change to ESM import: import { idempotencyMiddleware } from 'express-idempotency-middleware' or use dynamic import()

TypeError: store.get is not a function

Custom store does not implement required store interface (get, set, delete methods)

fix

Ensure custom store implements Store interface with get(key), set(key, value, ttl?), and delete(key) async methods

Idempotency-Status: conflict (409)

Idempotency-Key reused with different request body or method than original

fix

Ensure all retries use exactly the same request body, headers (except whitelist), and method

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

expressrequiredPeer dependency: middleware integrates with Express request/response objects

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/YevhenMykhailenko/idempotency-express ↗

packagehttps://www.npmjs.com/package/express-idempotency-middleware ↗