@masumraihan/idempotency-shield 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @http-state/idempotency-shield
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Makes mutation requests (payments, orders, record creation) safe to retry. A request that carries an
+`Idempotency-Key` header is processed exactly once, even if the client retries after a network failure or a
+double click. The behavior follows the IETF `Idempotency-Key` HTTP header draft.
+
+- Works with **Express** (4 and 5) and **NestJS** (tested with 11 and 12)
+- Requires **Node.js 20 or newer** (tested on 20.0, 20.x, 22, 24 and 26)
+- No runtime dependencies
+
+## Install
+
+```bash
+npm install @http-state/idempotency-shield
+```
+
+## Express
+
+```ts
+import express from "express";
+import { idempotencyShield } from "@http-state/idempotency-shield";
+
+const app = express();
+app.use(express.json()); // register body parsers first so the payload is part of the check
+app.use(idempotencyShield({ ttlMs: 5 * 60 * 1000 }));
+```
+
+## NestJS
+
+NestJS users import from the `/nest` entry point, so Express-only apps never load `@nestjs/*`.
+
+```ts
+import { Controller, Post, Body } from "@nestjs/common";
+import { Idempotent } from "@http-state/idempotency-shield/nest";
+
+@Controller("payments")
+export class PaymentsController {
+  @Post()
+  @Idempotent({ ttlMs: 5 * 60 * 1000 }) // also registers the interceptor
+  create(@Body() dto: CreatePaymentDto) {
+    /* ... */
+  }
+}
+```
+
+To share one store (for example Redis) across the app, provide it under the `IDEMPOTENCY_STORAGE` token.
+
+## How it works
+
+Only `POST`, `PUT` and `PATCH` are guarded. Other methods pass straight through, and so do requests
+without an `Idempotency-Key` header.
+
+```
+Idempotency-Key present?
+├── no  → run the handler normally
+└── yes → claim the key atomically
+          ├── claimed          → status STARTED → run handler → save response → status COMPLETED
+          ├── STARTED          → 409 Conflict (same request still in progress)
+          ├── COMPLETED        → replay the saved response (header X-Cache-Lookup: HIT - Idempotent)
+          └── different payload for this key → 422 Unprocessable Entity
+```
+
+1. **Claim (lock).** The first request atomically creates a `STARTED` record. A duplicate that arrives while
+   the first is still running sees `STARTED` and receives `409`. Because the claim is a single atomic
+   `setIfAbsent`, two simultaneous requests can never both run.
+2. **Execute.** The handler runs normally. On Express the response is recorded at `res.write` / `res.end`, so
+   `res.send`, `res.json`, streamed and binary responses are all covered. On NestJS the handler's return value is recorded.
+3. **Memoize.** The status code and body (plus response headers on Express) are saved and the record becomes `COMPLETED` for `ttlMs`.
+4. **Replay.** A retry with the same key skips your business logic and returns the saved response with the
+   original status code.
+
+### Failures
+
+| Situation | What happens |
+| --- | --- |
+| Server crashes while processing | The key stays `STARTED` until `lockTtlMs` expires (default: `ttlMs`, at most 60 s). After that the client can retry. |
+| Handler throws or returns an error | The key is released immediately so the client can fix the problem and retry. |
+| 4xx / 5xx response (Express) | Discarded by default. Pass `cacheErrors: true` to replay 4xx/5xx responses as well. |
+| Same key, different payload | `422`. The fingerprint covers method, URL and body. |
+| Key is empty, longer than 255 characters or sent twice | `400`. |
+| Response larger than `maxBodyBytes` (Express, default 1 MiB) | Not cached and the key is released. |
+| Storage fails while saving the result | The response is still sent and the error is passed to `onError`. |
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `ttlMs` | `300000` | How long a completed response can be replayed. |
+| `lockTtlMs` | `min(ttlMs, 60000)` | How long the in-progress lock is held. |
+| `storage` | shared in-memory store | Any object implementing `IdempotencyStore`. |
+| `scope` | none | `(req) => string`. Namespaces keys, usually by user id, so users can never read each other's cached responses. |
+| `onError` | ignore | Called when the store fails after a response. |
+| `cacheErrors` | `false` | Express only. Cache responses with status 400 and above. |
+| `maxBodyBytes` | `1048576` | Express only. Largest response that will be cached. |
+
+## Production storage (Redis)
+
+The default store lives in the memory of one process. With several instances, or after a restart, a retry can
+reach a server that has never seen the key and the operation runs twice. Give every instance the same Redis
+store instead. The package ships `RedisIdempotencyStore`, which works with both `ioredis` and `redis`
+(node-redis v4+). Neither library is a dependency of this package: you pass in your own client.
+
+```ts
+import Redis from "ioredis"; // or: import { createClient } from "redis";
+import { idempotencyShield, RedisIdempotencyStore } from "@http-state/idempotency-shield";
+
+const redis = new Redis(process.env.REDIS_URL);
+app.use(idempotencyShield({ storage: new RedisIdempotencyStore(redis) }));
+```
+
+With node-redis, connect the client first (`await client.connect()`).
+For NestJS, provide the same store under the `IDEMPOTENCY_STORAGE` token.
+
+The lock is one atomic `SET key value PX ttl NX`, so simultaneous requests on different servers still produce
+exactly one winner. Keys are prefixed with `idempotency:` (change it with `keyPrefix`) and expire through the
+Redis TTL, so nothing needs cleaning up.
+
+To use another database, implement `IdempotencyStore`. Its `setIfAbsent` must be atomic.
+
+## Notes
+
+- Register the Express middleware after body parsers.
+- Replayed responses do not include `Set-Cookie`, `Date`, `Content-Length` or connection-level headers.
+- The NestJS interceptor is tested on the Express platform. Fastify is not covered by the tests.
+
+## Running the tests
+
+```bash
+npm install
+npm test
+```
+
+The Redis tests need a Redis server. They use an installed `redis-server` if there is one. Otherwise point them at
+a running Redis with `REDIS_URL`; the tests only create and remove keys starting with `idem-test-`:
+
+```bash
+# bash / Git Bash
+REDIS_URL=redis://127.0.0.1:6379 npm test
+
+# PowerShell
+$env:REDIS_URL="redis://127.0.0.1:6379"; npm test
+```
+
+For a disposable Redis, use `docker run --rm -p 6390:6379 redis:7-alpine` and
+`REDIS_URL=redis://127.0.0.1:6390`. Without Redis, the Redis tests are skipped and everything else still runs.

package/dist/core.d.ts

@@ -0,0 +1,69 @@
+import type { IdempotencyStore, IdempotentRecord } from "./storage";
+export declare const IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+export declare const CACHE_HIT_HEADER = "X-Cache-Lookup";
+export declare const CACHE_HIT_VALUE = "HIT - Idempotent";
+/** Only methods that are not idempotent by definition are guarded. */
+export declare const GUARDED_METHODS: ReadonlySet<string>;
+export declare const DEFAULT_TTL_MS: number;
+export declare const MESSAGES: {
+    readonly invalidKey: "The Idempotency-Key header must be a single non-empty value of at most 255 characters.";
+    readonly inProgress: "A request with this Idempotency-Key is already in progress.";
+    readonly mismatch: "This Idempotency-Key was already used with a different request.";
+};
+export interface IdempotencyOptions<Req = any> {
+    /** How long a completed response is kept for replay. Default: 5 minutes. */
+    ttlMs?: number | undefined;
+    /**
+     * How long the in-progress lock is held. It is the window during which a crashed
+     * request blocks retries. Default: the smaller of `ttlMs` and 60 seconds.
+     */
+    lockTtlMs?: number | undefined;
+    /** Where records are kept. Default: a shared in-memory store. */
+    storage?: IdempotencyStore | undefined;
+    /**
+     * Returns a namespace for the key, typically the authenticated user id, so that
+     * different users can never read each other's cached responses.
+     */
+    scope?: ((req: Req) => string | undefined) | undefined;
+    /** Called when the store fails while saving or releasing a record after a response. */
+    onError?: ((error: unknown) => void) | undefined;
+}
+export interface ResolvedOptions<Req = any> {
+    ttlMs: number;
+    lockTtlMs: number;
+    storage: IdempotencyStore;
+    scope: ((req: Req) => string | undefined) | undefined;
+    onError: (error: unknown) => void;
+}
+export declare function resolveOptions<Req>(options: IdempotencyOptions<Req>, fallbackStorage?: IdempotencyStore): ResolvedOptions<Req>;
+export type KeyResult = {
+    ok: true;
+    key: string | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/** Validates the raw header value. A missing header is valid and means "not idempotent". */
+export declare function readIdempotencyKey(value: string | string[] | undefined): KeyResult;
+/** Builds the storage key. The scope is URI-encoded so "a:b" + "c" never equals "a" + "b:c". */
+export declare function buildStoreKey(scope: string | undefined, key: string): string;
+/** Hashes the parts of a request that must be identical when a key is reused. */
+export declare function createFingerprint(method: string, url: string, body: unknown): string;
+export type BeginResult = {
+    kind: "acquired";
+} | {
+    kind: "in-progress";
+} | {
+    kind: "mismatch";
+} | {
+    kind: "replay";
+    record: IdempotentRecord;
+};
+/**
+ * Atomically claims the key, or reports what is already stored for it.
+ * Reading and writing as two separate steps would let two simultaneous requests
+ * both pass the check, so the claim always goes through `setIfAbsent`.
+ */
+export declare function beginRequest(storage: IdempotencyStore, storeKey: string, fingerprint: string, lockTtlMs: number): Promise<BeginResult>;
+export declare function pickReplayHeaders(headers: Record<string, number | string | string[] | undefined>): Record<string, string | string[]>;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGES = exports.DEFAULT_TTL_MS = exports.GUARDED_METHODS = exports.CACHE_HIT_VALUE = exports.CACHE_HIT_HEADER = exports.IDEMPOTENCY_KEY_HEADER = void 0;
+exports.resolveOptions = resolveOptions;
+exports.readIdempotencyKey = readIdempotencyKey;
+exports.buildStoreKey = buildStoreKey;
+exports.createFingerprint = createFingerprint;
+exports.beginRequest = beginRequest;
+exports.pickReplayHeaders = pickReplayHeaders;
+const node_crypto_1 = require("node:crypto");
+const storage_1 = require("./storage");
+exports.IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+exports.CACHE_HIT_HEADER = "X-Cache-Lookup";
+exports.CACHE_HIT_VALUE = "HIT - Idempotent";
+/** Only methods that are not idempotent by definition are guarded. */
+exports.GUARDED_METHODS = new Set(["POST", "PUT", "PATCH"]);
+exports.DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_LOCK_TTL_MS = 60 * 1000;
+const MAX_KEY_LENGTH = 255;
+exports.MESSAGES = {
+    invalidKey: `The Idempotency-Key header must be a single non-empty value of at most ${MAX_KEY_LENGTH} characters.`,
+    inProgress: "A request with this Idempotency-Key is already in progress.",
+    mismatch: "This Idempotency-Key was already used with a different request.",
+};
+function assertDuration(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive number of milliseconds.`);
+    }
+}
+function resolveOptions(options, fallbackStorage) {
+    const ttlMs = options.ttlMs ?? exports.DEFAULT_TTL_MS;
+    assertDuration("ttlMs", ttlMs);
+    const lockTtlMs = options.lockTtlMs ?? Math.min(ttlMs, DEFAULT_LOCK_TTL_MS);
+    assertDuration("lockTtlMs", lockTtlMs);
+    return {
+        ttlMs,
+        lockTtlMs,
+        storage: options.storage ?? fallbackStorage ?? (0, storage_1.getDefaultStore)(),
+        scope: options.scope,
+        onError: options.onError ?? (() => undefined),
+    };
+}
+/** Validates the raw header value. A missing header is valid and means "not idempotent". */
+function readIdempotencyKey(value) {
+    if (value === undefined)
+        return { ok: true, key: undefined };
+    if (typeof value !== "string")
+        return { ok: false, message: exports.MESSAGES.invalidKey };
+    const key = value.trim();
+    if (key.length === 0 || key.length > MAX_KEY_LENGTH) {
+        return { ok: false, message: exports.MESSAGES.invalidKey };
+    }
+    return { ok: true, key };
+}
+/** Builds the storage key. The scope is URI-encoded so "a:b" + "c" never equals "a" + "b:c". */
+function buildStoreKey(scope, key) {
+    return scope ? `${encodeURIComponent(scope)}:${key}` : key;
+}
+/** Hashes the parts of a request that must be identical when a key is reused. */
+function createFingerprint(method, url, body) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    hash.update(`${method.toUpperCase()}\n${url}\n`);
+    if (Buffer.isBuffer(body) || typeof body === "string") {
+        hash.update(body);
+    }
+    else if (body !== undefined && body !== null) {
+        try {
+            hash.update(JSON.stringify(body) ?? "");
+        }
+        catch {
+            // Unserializable bodies (for example circular objects) only count by method and URL.
+        }
+    }
+    return hash.digest("hex");
+}
+/**
+ * Atomically claims the key, or reports what is already stored for it.
+ * Reading and writing as two separate steps would let two simultaneous requests
+ * both pass the check, so the claim always goes through `setIfAbsent`.
+ */
+async function beginRequest(storage, storeKey, fingerprint, lockTtlMs) {
+    const lock = { status: "STARTED", fingerprint };
+    // A second attempt covers a record that expires between the claim and the read.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        if (await storage.setIfAbsent(storeKey, lock, lockTtlMs))
+            return { kind: "acquired" };
+        const existing = await storage.get(storeKey);
+        if (!existing)
+            continue;
+        if (existing.fingerprint !== undefined && existing.fingerprint !== fingerprint) {
+            return { kind: "mismatch" };
+        }
+        if (existing.status === "STARTED")
+            return { kind: "in-progress" };
+        return { kind: "replay", record: existing };
+    }
+    return { kind: "in-progress" };
+}
+/** Headers that describe the original connection or message framing and must not be replayed. */
+const SKIPPED_HEADERS = new Set([
+    "connection",
+    "content-length",
+    "date",
+    "keep-alive",
+    "set-cookie",
+    "transfer-encoding",
+    "x-cache-lookup",
+]);
+function pickReplayHeaders(headers) {
+    const picked = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined || SKIPPED_HEADERS.has(name.toLowerCase()))
+            continue;
+        picked[name] = Array.isArray(value) ? value : String(value);
+    }
+    return picked;
+}
+//# sourceMappingURL=core.js.map

package/dist/express-mw.d.ts

@@ -0,0 +1,17 @@
+import type { NextFunction, Request, Response } from "express";
+import type { IdempotencyOptions } from "./core";
+export interface ExpressIdempotencyOptions extends IdempotencyOptions<Request> {
+    /**
+     * Cache responses with a status of 400 or above too. By default they are discarded
+     * so the client can fix the problem and retry with the same key. Default: false.
+     */
+    cacheErrors?: boolean | undefined;
+    /** Responses larger than this are not cached and the key is released. Default: 1 MiB. */
+    maxBodyBytes?: number | undefined;
+}
+/**
+ * Express middleware that makes POST, PUT and PATCH requests safe to retry.
+ * Register it after body parsers so the request body is part of the fingerprint.
+ */
+export declare function idempotencyShield(options?: ExpressIdempotencyOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=express-mw.d.ts.map

package/dist/express-mw.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.idempotencyShield = idempotencyShield;
+const core_1 = require("./core");
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+/**
+ * Express middleware that makes POST, PUT and PATCH requests safe to retry.
+ * Register it after body parsers so the request body is part of the fingerprint.
+ */
+function idempotencyShield(options = {}) {
+    const resolved = (0, core_1.resolveOptions)(options);
+    const cacheErrors = options.cacheErrors ?? false;
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    return async function idempotencyShieldMiddleware(req, res, next) {
+        try {
+            await handle(req, res, next, resolved, cacheErrors, maxBodyBytes);
+        }
+        catch (error) {
+            // A failing store is treated as an error rather than skipping the protection.
+            next(error);
+        }
+    };
+}
+async function handle(req, res, next, options, cacheErrors, maxBodyBytes) {
+    if (!core_1.GUARDED_METHODS.has(req.method))
+        return next();
+    const parsed = (0, core_1.readIdempotencyKey)(req.headers[core_1.IDEMPOTENCY_KEY_HEADER]);
+    if (!parsed.ok) {
+        res.status(400).json({ message: parsed.message });
+        return;
+    }
+    if (parsed.key === undefined)
+        return next();
+    const storeKey = (0, core_1.buildStoreKey)(options.scope?.(req), parsed.key);
+    const fingerprint = (0, core_1.createFingerprint)(req.method, req.originalUrl || req.url, req.body);
+    const state = await (0, core_1.beginRequest)(options.storage, storeKey, fingerprint, options.lockTtlMs);
+    switch (state.kind) {
+        case "mismatch":
+            res.status(422).json({ message: core_1.MESSAGES.mismatch });
+            return;
+        case "in-progress":
+            res.status(409).json({ message: core_1.MESSAGES.inProgress });
+            return;
+        case "replay":
+            replay(res, state.record);
+            return;
+        case "acquired":
+            captureResponse(res, options, storeKey, fingerprint, cacheErrors, maxBodyBytes);
+            return next();
+    }
+}
+function replay(res, record) {
+    res.status(record.statusCode ?? 200);
+    for (const [name, value] of Object.entries(record.headers ?? {})) {
+        res.setHeader(name, value);
+    }
+    res.setHeader(core_1.CACHE_HIT_HEADER, core_1.CACHE_HIT_VALUE);
+    if (record.body === undefined) {
+        res.end();
+    }
+    else {
+        res.send(record.bodyEncoding === "base64" ? Buffer.from(record.body, "base64") : record.body);
+    }
+}
+/**
+ * Wraps res.write and res.end to record the response. Hooking the lowest level
+ * covers res.send, res.json, res.sendFile and streamed responses alike.
+ */
+function captureResponse(res, options, storeKey, fingerprint, cacheErrors, maxBodyBytes) {
+    const chunks = [];
+    let size = 0;
+    let tooLarge = false;
+    let finished = false;
+    const collect = (chunk, encoding) => {
+        if (tooLarge || chunk === undefined || chunk === null || typeof chunk === "function")
+            return;
+        const buffer = typeof chunk === "string"
+            ? Buffer.from(chunk, typeof encoding === "string" ? encoding : "utf8")
+            : Buffer.isBuffer(chunk)
+                ? chunk
+                : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > maxBodyBytes) {
+            tooLarge = true;
+            chunks.length = 0;
+            return;
+        }
+        chunks.push(buffer);
+    };
+    const settle = () => {
+        const statusCode = res.statusCode;
+        const cacheable = !tooLarge && (statusCode < 400 || cacheErrors);
+        // Fire and forget: the response must not wait on the store, and a store
+        // failure must never break the response that is being sent.
+        try {
+            const task = cacheable
+                ? options.storage.set(storeKey, buildRecord(statusCode, fingerprint, res.getHeaders(), Buffer.concat(chunks)), options.ttlMs)
+                : options.storage.delete(storeKey);
+            Promise.resolve(task).catch(options.onError);
+        }
+        catch (error) {
+            options.onError(error);
+        }
+    };
+    const originalWrite = res.write;
+    const originalEnd = res.end;
+    res.write = function (...args) {
+        collect(args[0], args[1]);
+        return originalWrite.apply(this, args);
+    };
+    res.end = function (...args) {
+        collect(args[0], args[1]);
+        if (!finished) {
+            finished = true;
+            settle();
+        }
+        return originalEnd.apply(this, args);
+    };
+}
+function buildRecord(statusCode, fingerprint, headers, body) {
+    const record = {
+        status: "COMPLETED",
+        fingerprint,
+        statusCode,
+        headers: (0, core_1.pickReplayHeaders)(headers),
+    };
+    if (body.length > 0) {
+        // Keep text readable in the store, and fall back to base64 for binary payloads.
+        const text = body.toString("utf8");
+        const isText = Buffer.from(text, "utf8").equals(body);
+        record.body = isText ? text : body.toString("base64");
+        record.bodyEncoding = isText ? "utf8" : "base64";
+    }
+    return record;
+}
+//# sourceMappingURL=express-mw.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./storage";
+export * from "./redis-store";
+export * from "./express-mw";
+export type { IdempotencyOptions } from "./core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// The Express entry point. NestJS users import from "<package>/nest", which keeps
+// the @nestjs/* packages from being required by applications that do not use them.
+__exportStar(require("./storage"), exports);
+__exportStar(require("./redis-store"), exports);
+__exportStar(require("./express-mw"), exports);
+//# sourceMappingURL=index.js.map

package/dist/nest-decorator.d.ts

@@ -0,0 +1,24 @@
+import type { CallHandler, ExecutionContext, NestInterceptor } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { Observable } from "rxjs";
+import type { IdempotencyOptions } from "./core";
+import type { IdempotencyStore } from "./storage";
+export declare const IDEMPOTENT_KEY = "idempotent_options";
+/** Injection token for providing a shared store (for example Redis) to the interceptor. */
+export declare const IDEMPOTENCY_STORAGE = "IDEMPOTENCY_STORAGE";
+export type IdempotentOptions = IdempotencyOptions<any>;
+/**
+ * Enables idempotency for a controller method or a whole controller.
+ * It also registers the interceptor, so no separate @UseInterceptors is needed.
+ */
+export declare const Idempotent: (options?: IdempotentOptions) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export declare class IdempotencyInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly storage?;
+    constructor(reflector: Reflector, storage?: IdempotencyStore | undefined);
+    intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<unknown>>;
+    private replay;
+    private complete;
+    private release;
+}
+//# sourceMappingURL=nest-decorator.d.ts.map

package/dist/nest-decorator.js

@@ -0,0 +1,153 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotencyInterceptor = exports.Idempotent = exports.IDEMPOTENCY_STORAGE = exports.IDEMPOTENT_KEY = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const rxjs_1 = require("rxjs");
+const core_2 = require("./core");
+exports.IDEMPOTENT_KEY = "idempotent_options";
+/** Injection token for providing a shared store (for example Redis) to the interceptor. */
+exports.IDEMPOTENCY_STORAGE = "IDEMPOTENCY_STORAGE";
+/** Metadata key Nest uses for @HttpCode(). */
+const HTTP_CODE_METADATA = "__httpCode__";
+/** Marks requests already handled so that registering the interceptor twice is harmless. */
+const HANDLED = Symbol("idempotency-shield.handled");
+/**
+ * Enables idempotency for a controller method or a whole controller.
+ * It also registers the interceptor, so no separate @UseInterceptors is needed.
+ */
+const Idempotent = (options = {}) => (0, common_1.applyDecorators)((0, common_1.SetMetadata)(exports.IDEMPOTENT_KEY, options), (0, common_1.UseInterceptors)(IdempotencyInterceptor));
+exports.Idempotent = Idempotent;
+let IdempotencyInterceptor = class IdempotencyInterceptor {
+    reflector;
+    storage;
+    constructor(reflector, storage) {
+        this.reflector = reflector;
+        this.storage = storage;
+    }
+    async intercept(context, next) {
+        if (context.getType() !== "http")
+            return next.handle();
+        const http = context.switchToHttp();
+        const request = http.getRequest();
+        const response = http.getResponse();
+        if (!core_2.GUARDED_METHODS.has(request.method) || request[HANDLED])
+            return next.handle();
+        const parsed = (0, core_2.readIdempotencyKey)(request.headers?.[core_2.IDEMPOTENCY_KEY_HEADER]);
+        if (!parsed.ok)
+            throw new common_1.BadRequestException(parsed.message);
+        if (parsed.key === undefined)
+            return next.handle();
+        const key = parsed.key;
+        request[HANDLED] = true;
+        const decorated = this.reflector.getAllAndOverride(exports.IDEMPOTENT_KEY, [context.getHandler(), context.getClass()]);
+        const options = (0, core_2.resolveOptions)(decorated ?? {}, this.storage);
+        const storeKey = (0, core_2.buildStoreKey)(options.scope?.(request), key);
+        const fingerprint = (0, core_2.createFingerprint)(request.method, request.originalUrl ?? request.url, request.body);
+        const state = await (0, core_2.beginRequest)(options.storage, storeKey, fingerprint, options.lockTtlMs);
+        switch (state.kind) {
+            case "mismatch":
+                throw new common_1.UnprocessableEntityException(core_2.MESSAGES.mismatch);
+            case "in-progress":
+                throw new common_1.ConflictException(core_2.MESSAGES.inProgress);
+            case "replay":
+                return (0, rxjs_1.of)(this.replay(response, state.record));
+            case "acquired":
+                break;
+        }
+        // Nest applies the final status code after interceptors run, so work it out here.
+        const statusCode = this.reflector.get(HTTP_CODE_METADATA, context.getHandler()) ??
+            (response.statusCode && response.statusCode !== 200
+                ? response.statusCode
+                : request.method === "POST"
+                    ? 201
+                    : 200);
+        let emitted = false;
+        return next.handle().pipe((0, rxjs_1.mergeMap)((data) => {
+            emitted = true;
+            return (0, rxjs_1.from)(this.complete(options, storeKey, fingerprint, statusCode, data)).pipe((0, rxjs_1.map)(() => data));
+        }), (0, rxjs_1.tap)({
+            // A handler that completes without a value leaves nothing to replay.
+            complete: () => {
+                if (!emitted)
+                    void this.release(options, storeKey);
+            },
+        }), (0, rxjs_1.catchError)((error) => (0, rxjs_1.from)(this.release(options, storeKey)).pipe((0, rxjs_1.mergeMap)(() => (0, rxjs_1.throwError)(() => error)))));
+    }
+    replay(response, record) {
+        if (typeof record.statusCode === "number")
+            response.status(record.statusCode);
+        if (typeof response.setHeader === "function") {
+            response.setHeader(core_2.CACHE_HIT_HEADER, core_2.CACHE_HIT_VALUE);
+        }
+        else if (typeof response.header === "function") {
+            response.header(core_2.CACHE_HIT_HEADER, core_2.CACHE_HIT_VALUE);
+        }
+        return record.body === undefined ? undefined : JSON.parse(record.body);
+    }
+    async complete(options, storeKey, fingerprint, statusCode, data) {
+        try {
+            const serialized = serialize(data);
+            if (!serialized.cacheable) {
+                await options.storage.delete(storeKey);
+                return;
+            }
+            await options.storage.set(storeKey, {
+                status: "COMPLETED",
+                fingerprint,
+                statusCode,
+                body: serialized.body,
+                bodyEncoding: serialized.body === undefined ? undefined : "json",
+            }, options.ttlMs);
+        }
+        catch (error) {
+            // The response must still reach the client if the store fails.
+            options.onError(error);
+        }
+    }
+    async release(options, storeKey) {
+        try {
+            await options.storage.delete(storeKey);
+        }
+        catch (error) {
+            options.onError(error);
+        }
+    }
+};
+exports.IdempotencyInterceptor = IdempotencyInterceptor;
+exports.IdempotencyInterceptor = IdempotencyInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(core_1.Reflector)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(exports.IDEMPOTENCY_STORAGE))
+], IdempotencyInterceptor);
+/** Only plain JSON-serializable return values can be replayed; streams and buffers cannot. */
+function serialize(data) {
+    if (data === undefined)
+        return { cacheable: true };
+    if (Buffer.isBuffer(data))
+        return { cacheable: false };
+    if (typeof data === "object" && data !== null) {
+        const candidate = data;
+        if (typeof candidate.pipe === "function" || typeof candidate.getStream === "function") {
+            return { cacheable: false };
+        }
+    }
+    try {
+        const body = JSON.stringify(data);
+        return body === undefined ? { cacheable: false } : { cacheable: true, body };
+    }
+    catch {
+        return { cacheable: false };
+    }
+}
+//# sourceMappingURL=nest-decorator.js.map

package/dist/redis-store.d.ts

@@ -0,0 +1,37 @@
+import type { IdempotencyStore, IdempotentRecord } from "./storage";
+/**
+ * The few Redis commands the store needs. Both `ioredis` and `redis` (node-redis v4+)
+ * clients satisfy this shape, so neither library is a dependency of this package.
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    del(key: string): Promise<unknown>;
+    set(...args: any[]): Promise<unknown>;
+}
+export interface RedisStoreOptions {
+    /** Prefix added to every key so the shield does not collide with other data. Default: "idempotency:". */
+    keyPrefix?: string | undefined;
+    /**
+     * Which client library is used. It is detected automatically, because the two
+     * libraries take their SET options in different forms.
+     */
+    client?: "ioredis" | "node-redis" | undefined;
+}
+/**
+ * Redis-backed store. Share one instance across every server process so that a retry
+ * is recognized no matter which instance receives it.
+ *
+ * The lock is a single `SET key value PX ttl NX`, which Redis executes atomically.
+ */
+export declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly redis;
+    private readonly prefix;
+    private readonly kind;
+    constructor(redis: RedisLikeClient, options?: RedisStoreOptions);
+    get(key: string): Promise<IdempotentRecord | null>;
+    setIfAbsent(key: string, record: IdempotentRecord, ttlMs: number): Promise<boolean>;
+    set(key: string, record: IdempotentRecord, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    private write;
+}
+//# sourceMappingURL=redis-store.d.ts.map

package/dist/redis-store.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisIdempotencyStore = void 0;
+/**
+ * Redis-backed store. Share one instance across every server process so that a retry
+ * is recognized no matter which instance receives it.
+ *
+ * The lock is a single `SET key value PX ttl NX`, which Redis executes atomically.
+ */
+class RedisIdempotencyStore {
+    redis;
+    prefix;
+    kind;
+    constructor(redis, options = {}) {
+        this.redis = redis;
+        this.prefix = options.keyPrefix ?? "idempotency:";
+        this.kind = options.client ?? detectClient(redis);
+    }
+    async get(key) {
+        const raw = await this.redis.get(this.prefix + key);
+        if (raw === null || raw === undefined)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // A corrupted entry is treated as missing so it cannot block the key forever.
+            return null;
+        }
+    }
+    async setIfAbsent(key, record, ttlMs) {
+        const reply = await this.write(key, record, ttlMs, true);
+        return reply === "OK";
+    }
+    async set(key, record, ttlMs) {
+        await this.write(key, record, ttlMs, false);
+    }
+    async delete(key) {
+        await this.redis.del(this.prefix + key);
+    }
+    write(key, record, ttlMs, onlyIfAbsent) {
+        const name = this.prefix + key;
+        const value = JSON.stringify(record);
+        // PX takes whole milliseconds and must be at least 1.
+        const px = Math.max(1, Math.ceil(ttlMs));
+        if (this.kind === "node-redis") {
+            return this.redis.set(name, value, onlyIfAbsent ? { PX: px, NX: true } : { PX: px });
+        }
+        return onlyIfAbsent
+            ? this.redis.set(name, value, "PX", px, "NX")
+            : this.redis.set(name, value, "PX", px);
+    }
+}
+exports.RedisIdempotencyStore = RedisIdempotencyStore;
+function detectClient(redis) {
+    // node-redis clients expose a boolean `isOpen`, ioredis clients expose a string `status`.
+    return typeof redis.isOpen === "boolean" ? "node-redis" : "ioredis";
+}
+//# sourceMappingURL=redis-store.js.map

package/dist/storage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A stored idempotency record. Records must stay JSON-serializable so that
+ * external stores (Redis, SQL, ...) can persist them as-is.
+ */
+export interface IdempotentRecord {
+    status: "STARTED" | "COMPLETED";
+    /** Hash of the original request, used to detect key reuse with a different payload. */
+    fingerprint?: string | undefined;
+    statusCode?: number | undefined;
+    /** Serialized response body (see `bodyEncoding`). */
+    body?: string | undefined;
+    /** "utf8" and "base64" hold raw bytes, "json" holds a JSON-serialized value. */
+    bodyEncoding?: "utf8" | "base64" | "json" | undefined;
+    headers?: Record<string, string | string[]> | undefined;
+}
+/**
+ * Storage contract. Implement it to back the shield with Redis or a database.
+ * `setIfAbsent` MUST be atomic (for example `SET key value NX PX ttl` in Redis),
+ * because it is what prevents two concurrent requests from running the same operation.
+ */
+export interface IdempotencyStore {
+    get(key: string): Promise<IdempotentRecord | null>;
+    /** Stores the record only if the key does not exist. Resolves to true when it was stored. */
+    setIfAbsent(key: string, record: IdempotentRecord, ttlMs: number): Promise<boolean>;
+    set(key: string, record: IdempotentRecord, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface MemoryStoreOptions {
+    /** Upper bound on stored keys. The oldest entries are evicted first. Default: 10000. */
+    maxEntries?: number | undefined;
+    /** Minimum time between sweeps of expired entries. Default: 60000. */
+    sweepIntervalMs?: number | undefined;
+}
+/**
+ * In-memory store. Suitable for a single process only: with several instances
+ * or a cluster, use a shared store instead.
+ */
+export declare class IdempotencyStorage implements IdempotencyStore {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly sweepIntervalMs;
+    private lastSweep;
+    constructor(options?: MemoryStoreOptions);
+    /** Number of entries currently held, including expired ones not yet swept. */
+    get size(): number;
+    get(key: string): Promise<IdempotentRecord | null>;
+    setIfAbsent(key: string, record: IdempotentRecord, ttlMs: number): Promise<boolean>;
+    set(key: string, record: IdempotentRecord, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    private live;
+    private write;
+    private sweepIfDue;
+}
+/** Process-wide store used when no `storage` option is given. */
+export declare function getDefaultStore(): IdempotencyStorage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotencyStorage = void 0;
+exports.getDefaultStore = getDefaultStore;
+/**
+ * In-memory store. Suitable for a single process only: with several instances
+ * or a cluster, use a shared store instead.
+ */
+class IdempotencyStorage {
+    entries = new Map();
+    maxEntries;
+    sweepIntervalMs;
+    lastSweep = Date.now();
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 10_000;
+        this.sweepIntervalMs = options.sweepIntervalMs ?? 60_000;
+    }
+    /** Number of entries currently held, including expired ones not yet swept. */
+    get size() {
+        return this.entries.size;
+    }
+    async get(key) {
+        return this.live(key)?.record ?? null;
+    }
+    async setIfAbsent(key, record, ttlMs) {
+        // No await between the check and the write, so this is atomic within one process.
+        if (this.live(key))
+            return false;
+        this.write(key, record, ttlMs);
+        return true;
+    }
+    async set(key, record, ttlMs) {
+        this.write(key, record, ttlMs);
+    }
+    async delete(key) {
+        this.entries.delete(key);
+    }
+    live(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() >= entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    write(key, record, ttlMs) {
+        this.sweepIfDue();
+        // Delete first so the key moves to the end of the insertion order.
+        this.entries.delete(key);
+        this.entries.set(key, { record, expiresAt: Date.now() + ttlMs });
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    sweepIfDue() {
+        const now = Date.now();
+        if (now - this.lastSweep < this.sweepIntervalMs)
+            return;
+        this.lastSweep = now;
+        for (const [key, entry] of this.entries) {
+            if (now >= entry.expiresAt)
+                this.entries.delete(key);
+        }
+    }
+}
+exports.IdempotencyStorage = IdempotencyStorage;
+let defaultStore;
+/** Process-wide store used when no `storage` option is given. */
+function getDefaultStore() {
+    defaultStore ??= new IdempotencyStorage();
+    return defaultStore;
+}
+//# sourceMappingURL=storage.js.map

package/package.json

@@ -1,6 +1,97 @@
 {
   "name": "@masumraihan/idempotency-shield",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "An HTTP idempotency component for Express and NestJS complying with IETF standards.",
+  "keywords": [
+    "idempotency",
+    "idempotency-key",
+    "express",
+    "nestjs",
+    "middleware",
+    "interceptor",
+    "http"
+  ],
+  "author": "",
+  "license": "ISC",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express-mw.d.ts",
+      "default": "./dist/express-mw.js"
+    },
+    "./nest": {
+      "types": "./dist/nest-decorator.d.ts",
+      "default": "./dist/nest-decorator.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "express": [
+        "dist/express-mw.d.ts"
+      ],
+      "nest": [
+        "dist/nest-decorator.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
+    "test": "npm run build && node --test test/storage.test.cjs test/express.test.cjs test/nest.test.cjs test/redis.test.cjs",
+    "prepublishOnly": "npm test",
+    "demo": "npm run build && node examples/scenario.cjs",
+    "demo:server": "npm run build && node examples/server.cjs",
+    "demo:redis": "npm run build && node examples/two-servers.cjs"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=9.0.0",
+    "@nestjs/core": ">=9.0.0",
+    "@types/express": ">=4.17.0",
+    "rxjs": ">=7.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "@types/express": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.2.8",
+    "@nestjs/core": "^11.2.8",
+    "@nestjs/platform-express": "^11.2.8",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.19.43",
+    "express": "^5.3.0",
+    "ioredis": "^6.0.0",
+    "redis": "^6.3.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "^7.0.2"
+  }
+}