@cqrs-ddd/pipeline-idempotency 0.5.0

package/dist/interfaces/idempotency-options.interface.d.ts

@@ -0,0 +1,97 @@
+import type { IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { IdempotencyRequestKind } from './idempotency-record.interface.js';
+/**
+ * Derives the digest of the authorization scope a request runs under.
+ *
+ * Returned value is compared, not interpreted: any deterministic string works,
+ * and it should cover every dimension whose change must stop a stored response
+ * from being replayed — the effective permission rules and the trusted context
+ * their conditions resolve against.
+ *
+ * Throw when the required context is missing rather than returning a placeholder;
+ * the behavior calls this **before** claiming the key, so a throw prevents the
+ * operation from being claimed at all. Returning `undefined` means "this request
+ * has no scope", which cannot be replayed against a record that has one.
+ */
+export type IdempotencyReplayScopeFactory = (context: IPipelineContext) => string | undefined;
+/**
+ * Derives the idempotency key for a request from the pipeline context. A common
+ * HTTP pattern is to copy the `Idempotency-Key` header into the CQRS command at
+ * the controller boundary and read it from `context.request`. An upstream
+ * behavior may alternatively place application metadata in `context.items`.
+ * Return `undefined` to skip deduplication for this request.
+ */
+export type IdempotencyKeyFactory = (context: IPipelineContext) => string | undefined;
+/**
+ * Per-handler idempotency options, shallow-merged over the constructor defaults.
+ *
+ * @example Tenant/principal-scoped command idempotency
+ * ```ts
+ * // Fails closed when the tenant or principal is missing and escapes every
+ * // segment; never build a key with a template string.
+ * const createOrderKey = createPartitionedIdempotencyKeyFactory({
+ *   action: 'order.create',
+ *   principal: (ctx) => ['user', ctx.items.get(CURRENT_USER_ID) as string],
+ *   operation: (ctx) => (ctx.request as CreateOrderCommand).idempotencyKey,
+ * });
+ *
+ * class CreateOrderHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [IdempotencyBehavior, {
+ *     keyFactory: createOrderKey,
+ *     ttl: 24 * 60 * 60 * 1000,
+ *   }])
+ *   async handle(command: CreateOrderCommand) {}
+ * }
+ * ```
+ */
+export interface IdempotencyBehaviorOptions {
+    /**
+     * Derives the idempotency key from the request/context. **Required** for the
+     * behavior to do anything — without a key (or when it returns `undefined`)
+     * the handler runs normally. Include tenant/principal ownership whenever a
+     * replay would otherwise bypass handler-level authorization.
+     */
+    keyFactory?: IdempotencyKeyFactory;
+    /**
+     * How long a key is remembered, in milliseconds. After this window the key
+     * may be reused and a fresh execution occurs. Successful completion restarts
+     * the TTL for the replay record. Must be a positive safe integer. Default
+     * `86_400_000` (24h).
+     */
+    ttl?: number;
+    /**
+     * Which request kinds this policy applies to. Default `['command']` — queries
+     * are naturally idempotent and usually want `@cqrs-ddd/pipeline-cache`
+     * instead.
+     */
+    scope?: IdempotencyRequestKind[];
+    /**
+     * Hash the request payload and reject a later call that reuses the same key
+     * with a *different* body (`422`). Default `true`. Disable if your key already
+     * fully identifies the payload.
+     */
+    fingerprint?: boolean;
+    /**
+     * Binds replay to the caller's authorization scope while keeping the operation
+     * key stable.
+     *
+     * The digest is captured when the key is claimed and stored on the record. A
+     * later duplicate may only replay the stored response when its digest matches;
+     * a mismatch, or a record stored without one, raises
+     * `IdempotencyConflictError` with reason `replay_scope` (`409`). The record is
+     * neither deleted nor re-executed, so a permission change can never cause the
+     * side effect to run twice.
+     *
+     * Configure it for any operation whose response or effect depends on the
+     * caller's permissions. Without it, replay is bound only by the key and the
+     * payload fingerprint.
+     */
+    replayScopeFactory?: IdempotencyReplayScopeFactory;
+    /**
+     * When the handler throws, release the key so the client can safely retry
+     * (`true`, default). Set `false` to keep the key claimed and surface a
+     * conflict on retry (favors strict at-most-once over retryability).
+     */
+    releaseOnError?: boolean;
+}
+//# sourceMappingURL=idempotency-options.interface.d.ts.map

package/dist/interfaces/idempotency-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/idempotency-options.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC1C,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,gBAAgB,KACtB,MAAM,GAAG,SAAS,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAEnC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAEjC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IAEnD;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/dist/interfaces/idempotency-options.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=idempotency-options.interface.js.map

package/dist/interfaces/idempotency-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-options.interface.js","sourceRoot":"","sources":["../../src/interfaces/idempotency-options.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/interfaces/idempotency-record.interface.d.ts

@@ -0,0 +1,52 @@
+/** Pipeline request kinds an idempotency policy can apply to. */
+export type IdempotencyRequestKind = 'command' | 'query' | 'event' | 'unknown';
+/** Lifecycle state of an idempotency key. */
+export type IdempotencyStatus = 'in_progress' | 'completed';
+/** Values that have one portable representation across all bundled stores. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * The durable record stored under an idempotency key. While a handler runs the
+ * record is `in_progress`; once it succeeds the record flips to `completed` and
+ * carries the captured {@link response} for replay.
+ */
+export interface IdempotencyRecord {
+    /** The idempotency key this record is stored under. */
+    key: string;
+    /** Whether the original request is still running or has completed. */
+    status: IdempotencyStatus;
+    /** The request type name, e.g. `CreateUserCommand`. */
+    requestName: string;
+    /**
+     * Unique owner token for the execution that claimed this record. Every claim
+     * `IdempotencyBehavior` makes sets it, and `completeIfOwned` and
+     * `deleteIfOwned` compare against it. It may be absent from a record written
+     * through the unconditional `set` or claimed outside the behavior; such a
+     * record can still be read and replayed, but no owner check matches it.
+     */
+    claimId?: string;
+    /**
+     * Stable hash of the original request payload. Used to detect a key being
+     * reused with a *different* body (a client bug or replay attack).
+     */
+    fingerprint?: string;
+    /**
+     * Digest of the authorization scope the original execution ran under, when the
+     * behavior is configured with a `replayScopeFactory`.
+     *
+     * Replay compares this against the current caller's scope and refuses on a
+     * mismatch, so a response authorized under one set of permissions is never
+     * returned to a caller who no longer holds them. It is deliberately **not**
+     * part of the key: a key that changed with permissions would let the same
+     * side effect execute again.
+     */
+    replayScope?: string;
+    /** JSON snapshot of the handler response, captured once completed. */
+    response?: JsonValue;
+    /** ISO-8601 timestamp the key was first claimed. */
+    createdAt: string;
+    /** ISO-8601 timestamp the original request completed, when applicable. */
+    completedAt?: string;
+}
+//# sourceMappingURL=idempotency-record.interface.d.ts.map

package/dist/interfaces/idempotency-record.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-record.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/idempotency-record.interface.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/E,6CAA6C;AAC7C,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,WAAW,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,EAAE,iBAAiB,CAAC;IAC1B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/interfaces/idempotency-record.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=idempotency-record.interface.js.map

package/dist/interfaces/idempotency-record.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-record.interface.js","sourceRoot":"","sources":["../../src/interfaces/idempotency-record.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/interfaces/idempotency-store.interface.d.ts

@@ -0,0 +1,59 @@
+import type { IdempotencyRecord } from './idempotency-record.interface.js';
+/** A value that may be returned synchronously or as a promise. */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Backend-agnostic store for idempotency records — the single seam every
+ * storage backend implements. Because {@link IdempotencyBehavior} depends only
+ * on this interface, swapping the backend (memory, Redis, Postgres, your own)
+ * is a one-line change of the store passed to `IdempotencyBehavior`; handlers never
+ * change.
+ *
+ * Concurrent duplicate exclusion hinges on {@link setIfAbsent} being **atomic**
+ * — it must claim the key only if no live record exists (e.g. Redis `SET NX PX`,
+ * or a Postgres conditional upsert that replaces only expired conflicts).
+ * Atomic claiming prevents two live duplicates from both acquiring the same
+ * key; it does not by itself imply exactly-once execution across failures/retries.
+ *
+ * Ownership-sensitive transitions use `claimId`. A stale execution whose claim
+ * expired must never complete or delete a newer execution's record. Built-in
+ * stores implement this with an atomic compare-and-set / compare-and-delete.
+ */
+export interface IdempotencyStore {
+    /**
+     * Returns the live (non-expired) record for `key`, or `undefined` if there is
+     * none.
+     */
+    get(key: string): MaybePromise<IdempotencyRecord | undefined>;
+    /**
+     * Atomically stores `record` **only if** no live record exists for `key`.
+     *
+     * @returns `true` if the key was claimed by this call, `false` if a live
+     * record already existed.
+     */
+    setIfAbsent(key: string, record: IdempotencyRecord, ttlMs: number): MaybePromise<boolean>;
+    /**
+     * Atomically replaces the live `in_progress` record with `record` only when
+     * the existing record is still owned by `claimId`.
+     *
+     * @returns `true` when this claim completed its own record; `false` when the
+     * claim expired, was replaced, or was otherwise no longer owned by the caller.
+     */
+    completeIfOwned(key: string, claimId: string, record: IdempotencyRecord, ttlMs: number): MaybePromise<boolean>;
+    /**
+     * Atomically removes the live record only when it is still owned by
+     * `claimId`. Used by `releaseOnError` so a stale failure cannot delete a
+     * newer execution's claim.
+     */
+    deleteIfOwned(key: string, claimId: string): MaybePromise<boolean>;
+    /**
+     * Unconditional overwrite for administrative or custom use. Pipeline
+     * execution completion uses {@link completeIfOwned}, not this method.
+     */
+    set(key: string, record: IdempotencyRecord, ttlMs: number): MaybePromise<void>;
+    /**
+     * Unconditional delete for administrative or custom use. Pipeline
+     * failure release uses {@link deleteIfOwned}, not this method.
+     */
+    delete(key: string): MaybePromise<void>;
+}
+//# sourceMappingURL=idempotency-store.interface.d.ts.map

package/dist/interfaces/idempotency-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/idempotency-store.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,kEAAkE;AAClE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IAE9D;;;;;OAKG;IACH,WAAW,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,YAAY,CAAC,OAAO,CAAC,CAAC;IAEzB;;;;;;OAMG;IACH,eAAe,CACb,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,YAAY,CAAC,OAAO,CAAC,CAAC;IAEzB;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAEnE;;;OAGG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,YAAY,CAAC,IAAI,CAAC,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CACzC"}

package/dist/interfaces/idempotency-store.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=idempotency-store.interface.js.map

package/dist/interfaces/idempotency-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-store.interface.js","sourceRoot":"","sources":["../../src/interfaces/idempotency-store.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/stores/memory.store.d.ts

@@ -0,0 +1,48 @@
+import type { IdempotencyRecord } from '../interfaces/idempotency-record.interface.js';
+import type { IdempotencyStore } from '../interfaces/idempotency-store.interface.js';
+export interface MemoryIdempotencyStoreOptions {
+    /** Maximum number of entries allowed in the store. Defaults to 10,000. */
+    maxEntries?: number;
+    /**
+     * Interval in milliseconds for periodic background cleanup of expired entries.
+     * Defaults to 30,000 ms. If 0 or negative, periodic cleanup timer is disabled.
+     */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Zero-dependency, in-process {@link IdempotencyStore} backed by a `Map` with
+ * per-entry expiry and bounded memory capacity. The **default** store — ideal
+ * for a single instance, tests, or local development.
+ *
+ * Because Node runs JavaScript on a single thread, {@link setIfAbsent},
+ * {@link completeIfOwned}, and {@link deleteIfOwned} are effectively atomic
+ * here. State is **not** shared across processes, so for a multi-instance
+ * deployment use {@link RedisIdempotencyStore} or
+ * {@link PostgresIdempotencyStore}.
+ */
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly cleanupTimer?;
+    constructor(options?: MemoryIdempotencyStoreOptions);
+    /** Current number of active (stored) entries. */
+    get size(): number;
+    /**
+     * Iterates through all entries and removes any whose TTL has elapsed.
+     * Returns the count of deleted entries.
+     */
+    cleanupExpired(): number;
+    /** Stops the periodic cleanup timer and releases timer resources. */
+    destroy(): void;
+    private ensureCapacity;
+    get(key: string): IdempotencyRecord | undefined;
+    setIfAbsent(key: string, record: IdempotencyRecord, ttlMs: number): boolean;
+    completeIfOwned(key: string, claimId: string, record: IdempotencyRecord, ttlMs: number): boolean;
+    deleteIfOwned(key: string, claimId: string): boolean;
+    set(key: string, record: IdempotencyRecord, ttlMs: number): void;
+    delete(key: string): void;
+    private write;
+    /** Returns the entry for `key` if present and not expired, pruning if it is. */
+    private live;
+}
+//# sourceMappingURL=memory.store.d.ts.map

package/dist/stores/memory.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.store.d.ts","sourceRoot":"","sources":["../../src/stores/memory.store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAOrF,MAAM,WAAW,6BAA6B;IAC5C,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAiB;IAE/C,YAAY,OAAO,CAAC,EAAE,6BAA6B,EAWlD;IAED,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,cAAc,IAAI,MAAM,CAUvB;IAED,qEAAqE;IACrE,OAAO,IAAI,IAAI,CAId;IAED,OAAO,CAAC,cAAc;IAYtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAG9C;IAED,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAO1E;IAED,eAAe,CACb,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAWT;IAED,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAMnD;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAK/D;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAExB;IAED,OAAO,CAAC,KAAK;IAOb,gFAAgF;IAChF,OAAO,CAAC,IAAI;CASb"}

package/dist/stores/memory.store.js

@@ -0,0 +1,119 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { cloneIdempotencyRecord } from '../helpers/json-snapshot.js';
+/**
+ * Zero-dependency, in-process {@link IdempotencyStore} backed by a `Map` with
+ * per-entry expiry and bounded memory capacity. The **default** store — ideal
+ * for a single instance, tests, or local development.
+ *
+ * Because Node runs JavaScript on a single thread, {@link setIfAbsent},
+ * {@link completeIfOwned}, and {@link deleteIfOwned} are effectively atomic
+ * here. State is **not** shared across processes, so for a multi-instance
+ * deployment use {@link RedisIdempotencyStore} or
+ * {@link PostgresIdempotencyStore}.
+ */
+export class MemoryIdempotencyStore {
+    entries = new Map();
+    maxEntries;
+    cleanupTimer;
+    constructor(options) {
+        this.maxEntries = options?.maxEntries ?? 10_000;
+        const interval = options?.cleanupIntervalMs ?? 30_000;
+        if (interval > 0) {
+            this.cleanupTimer = setInterval(() => {
+                this.cleanupExpired();
+            }, interval);
+            if (typeof this.cleanupTimer?.unref === 'function') {
+                this.cleanupTimer.unref();
+            }
+        }
+    }
+    /** Current number of active (stored) entries. */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Iterates through all entries and removes any whose TTL has elapsed.
+     * Returns the count of deleted entries.
+     */
+    cleanupExpired() {
+        const now = Date.now();
+        let count = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt <= now) {
+                this.entries.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Stops the periodic cleanup timer and releases timer resources. */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+    }
+    ensureCapacity() {
+        if (this.entries.size < this.maxEntries) {
+            return;
+        }
+        this.cleanupExpired();
+        if (this.entries.size >= this.maxEntries) {
+            throw new Error(`MemoryIdempotencyStore capacity (${this.maxEntries}) reached: cannot evict active or unexpired claims.`);
+        }
+    }
+    get(key) {
+        const record = this.live(key)?.record;
+        return record ? cloneIdempotencyRecord(record) : undefined;
+    }
+    setIfAbsent(key, record, ttlMs) {
+        if (this.live(key)) {
+            return false;
+        }
+        this.ensureCapacity();
+        this.write(key, record, ttlMs);
+        return true;
+    }
+    completeIfOwned(key, claimId, record, ttlMs) {
+        const current = this.live(key);
+        if (current?.record.status !== 'in_progress' ||
+            current.record.claimId !== claimId) {
+            return false;
+        }
+        this.write(key, record, ttlMs);
+        return true;
+    }
+    deleteIfOwned(key, claimId) {
+        const current = this.live(key);
+        if (!current || current.record.claimId !== claimId) {
+            return false;
+        }
+        return this.entries.delete(key);
+    }
+    set(key, record, ttlMs) {
+        if (!this.entries.has(key)) {
+            this.ensureCapacity();
+        }
+        this.write(key, record, ttlMs);
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+    write(key, record, ttlMs) {
+        this.entries.set(key, {
+            record: cloneIdempotencyRecord(record),
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    /** Returns the entry for `key` if present and not expired, pruning if it is. */
+    live(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+}
+//# sourceMappingURL=memory.store.js.map

package/dist/stores/memory.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.store.js","sourceRoot":"","sources":["../../src/stores/memory.store.ts"],"names":[],"mappings":"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"}

package/dist/stores/postgres.store.d.ts

@@ -0,0 +1,72 @@
+import type { IdempotencyRecord } from '../interfaces/idempotency-record.interface.js';
+import type { IdempotencyStore } from '../interfaces/idempotency-store.interface.js';
+/** A single returned row, keyed by column name. */
+export interface PostgresRowLike {
+    [column: string]: unknown;
+}
+/** Minimal structural shape of a `pg` query result. */
+export interface PostgresQueryResultLike {
+    rows: PostgresRowLike[];
+    rowCount?: number | null;
+}
+/**
+ * Minimal structural shape of a `pg` `Pool` / `Client`. Declared locally so this
+ * package does not hard-depend on `pg` — a real `Pool` or `Client` satisfies it.
+ * Add it in your app: `pnpm add pg`.
+ */
+export interface PostgresQueryableLike {
+    query(text: string, values?: unknown[]): Promise<PostgresQueryResultLike>;
+}
+/** Options for {@link PostgresIdempotencyStore}. */
+export interface PostgresIdempotencyStoreOptions {
+    /**
+     * Destination table, optionally schema-qualified (e.g. `app.idempotency_keys`).
+     * Default `'idempotency_keys'`. Validated as a safe SQL identifier.
+     */
+    table?: string;
+}
+/**
+ * SQL that creates the idempotency table and its `expires_at` index. Run it
+ * from an application migration, not at request time.
+ *
+ * `response` holds the response as JSON text rather than `jsonb`: `jsonb`
+ * rejects the `\u0000` and unpaired-surrogate escapes `JSON.stringify` writes,
+ * and a completed response must always be storable and replay exactly.
+ *
+ * @param table - Table name (validated). Default `'idempotency_keys'`.
+ * @returns SQL statements required by {@link PostgresIdempotencyStore}.
+ */
+export declare function createIdempotencyTableSql(table?: string): string;
+/**
+ * {@link IdempotencyStore} backed by **Postgres** (`pg`) — a drop-in
+ * replacement that shares state across instances without a separate Redis.
+ *
+ * Create the table once with {@link createIdempotencyTableSql}. Atomicity of
+ * {@link setIfAbsent} comes from a conditional `INSERT … ON CONFLICT … DO
+ * UPDATE`: an absent key is inserted, an expired key is atomically replaced,
+ * and a live conflict is left untouched. Completion/release also compare
+ * `claim_id` in the same SQL statement, so a stale execution cannot mutate a
+ * newer claim. The table name is validated as a plain SQL identifier (it is
+ * interpolated, not parameterized); all values are passed as bound parameters.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * await pool.query(createIdempotencyTableSql());
+ * const store = new PostgresIdempotencyStore(pool);
+ * ```
+ */
+export declare class PostgresIdempotencyStore implements IdempotencyStore {
+    private readonly db;
+    private readonly table;
+    constructor(db: PostgresQueryableLike, options?: PostgresIdempotencyStoreOptions);
+    get(key: string): Promise<IdempotencyRecord | undefined>;
+    setIfAbsent(key: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
+    completeIfOwned(key: string, claimId: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
+    deleteIfOwned(key: string, claimId: string): Promise<boolean>;
+    set(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    private toValues;
+}
+//# sourceMappingURL=postgres.store.d.ts.map

package/dist/stores/postgres.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.store.d.ts","sourceRoot":"","sources":["../../src/stores/postgres.store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAErF,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3E;AAED,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,SAAqB,GAAG,MAAM,CAe5E;AA6CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAI7D,OAAO,CAAC,QAAQ,CAAC,EAAE;IAHrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,YACmB,EAAE,EAAE,qBAAqB,EAC1C,OAAO,GAAE,+BAAoC,EAG9C;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAW7D;IAEK,WAAW,CACf,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB;IAEK,eAAe,CACnB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB;IAEK,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUlE;IAEK,GAAG,CACP,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAiBf;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;IAED,OAAO,CAAC,QAAQ;CAajB"}