IdempotencyOptions

Defined in: src/http/cache/IdempotencyKey.ts:28

Idempotency-key middleware. Implements the Stripe / Adyen pattern: clients send an Idempotency-Key header on retryable requests (typically POST), and the server records the first response under that key so subsequent requests with the same key replay the same outcome.

Three states for a given key:

1. Absent — handler runs; the (status, headers, body) tuple is cached under the key for ttlMs (default 24h).
2. In-flight — another worker is currently processing this key. We respond 409 Conflict so the client retries later.
3. Completed — replay the cached response verbatim.

Storage is JSON-encoded — bodies that are Uint8Array are base64’d so the round-trip preserves bytes.

Usage:

const dedup = idempotent({ cache: ext.cache(), ttlMs: 24 * 60 * 60_000 }); route(post(‘/payments’, dedup(handler)));

Properties

cache

readonly cache: Cache

Defined in: src/http/cache/IdempotencyKey.ts:29

---

headerName?

readonly optional headerName?: string

Defined in: src/http/cache/IdempotencyKey.ts:37

Header to read the idempotency key from. Default: 'idempotency-key' (the standard). Header names are matched case-insensitively against the req.headers map (which holds them lower-cased).

---

keyPrefix?

readonly optional keyPrefix?: string

Defined in: src/http/cache/IdempotencyKey.ts:41

Cache-key namespace. Default: 'idem:'.

---

missingHeader?

readonly optional missingHeader?: "reject" | "pass-through"

Defined in: src/http/cache/IdempotencyKey.ts:48

What to do when the request lacks the header. Default: 'reject' (respond 400). Setting 'pass-through' runs the handler unchanged — useful when only some clients use idempotency and you don’t want to break the others.

---

ttlMs?

readonly optional ttlMs?: number

Defined in: src/http/cache/IdempotencyKey.ts:31

How long to remember responses. Default: 24 hours.