@cqrs-ddd/pipeline-idempotency 0.5.0

package/dist/helpers/partitioned-key.js

@@ -0,0 +1,36 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { tenantSegments, } from '@cqrs-ddd/pipeline';
+import { joinKeySegments } from '@cqrs-ddd/safe-stringify';
+import { MissingIdempotencyPartitionError } from '../errors/missing-partition.error.js';
+export function createPartitionedIdempotencyKeyFactory(options) {
+    const onMissingOperation = options.onMissingOperation ?? 'throw';
+    return (context) => {
+        const tenant = tenantSegments(context, options, MissingIdempotencyPartitionError);
+        const principal = principalSegments(options.principal(context));
+        if (!principal) {
+            throw new MissingIdempotencyPartitionError(context.requestName, 'principal', 'Resolve the principal from authenticated context. There is no shared ' +
+                'fallback: it would merge every unresolved caller into one namespace.');
+        }
+        const operation = options.operation(context)?.trim();
+        if (!operation) {
+            if (onMissingOperation === 'skip')
+                return undefined;
+            throw new MissingIdempotencyPartitionError(context.requestName, 'operation', "Return an operation identifier, or configure onMissingOperation: 'skip'.");
+        }
+        return joinKeySegments([
+            ...(options.version ? [options.version] : []),
+            ...tenant,
+            ...principal,
+            options.action ?? context.requestName,
+            operation,
+        ]);
+    };
+}
+/** Normalizes a principal to non-empty trimmed segments, or `undefined`. */
+function principalSegments(value) {
+    const segments = (typeof value === 'string' ? [value] : (value ?? [])).map((segment) => (typeof segment === 'string' ? segment.trim() : ''));
+    return segments.length > 0 && segments.every((segment) => segment !== '')
+        ? segments
+        : undefined;
+}
+//# sourceMappingURL=partitioned-key.js.map

package/dist/helpers/partitioned-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitioned-key.js","sourceRoot":"","sources":["../../src/helpers/partitioned-key.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAGL,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,gCAAgC,EAAE,MAAM,sCAAsC,CAAC;AA8GxF,MAAM,UAAU,sCAAsC,CACpD,OAAyC;IAEzC,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,OAAO,CAAC;IAEjE,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,cAAc,CAC3B,OAAO,EACP,OAAO,EACP,gCAAgC,CACjC,CAAC;QAEF,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,gCAAgC,CACxC,OAAO,CAAC,WAAW,EACnB,WAAW,EACX,uEAAuE;gBACrE,sEAAsE,CACzE,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,IAAI,kBAAkB,KAAK,MAAM;gBAAE,OAAO,SAAS,CAAC;YACpD,MAAM,IAAI,gCAAgC,CACxC,OAAO,CAAC,WAAW,EACnB,WAAW,EACX,0EAA0E,CAC3E,CAAC;QACJ,CAAC;QAED,OAAO,eAAe,CAAC;YACrB,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,GAAG,MAAM;YACT,GAAG,SAAS;YACZ,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,WAAW;YACrC,SAAS;SACV,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,SAAS,iBAAiB,CACxB,KAA6C;IAE7C,MAAM,QAAQ,GAAG,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CACxE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACjE,CAAC;IACF,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC;QACvE,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,20 @@
+import type { IdempotencyConflictError } from './errors/idempotency-conflict.error.js';
+/** An HTTP answer for an error: status, JSON body and headers. */
+export interface HttpResponse {
+    status: number;
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+/**
+ * The HTTP answer for an {@link IdempotencyConflictError}: `409 Conflict` for an
+ * operation in progress or a different replay scope, `422 Unprocessable Entity` for a
+ * key reused with another payload.
+ *
+ * @example
+ * ```ts
+ * const { status, body } = toHttpResponse(error);
+ * res.status(status).json(body);
+ * ```
+ */
+export declare function toHttpResponse(error: IdempotencyConflictError): HttpResponse;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAEvF,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CAY5E"}

package/dist/http.js

@@ -0,0 +1,26 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * The HTTP answer for an {@link IdempotencyConflictError}: `409 Conflict` for an
+ * operation in progress or a different replay scope, `422 Unprocessable Entity` for a
+ * key reused with another payload.
+ *
+ * @example
+ * ```ts
+ * const { status, body } = toHttpResponse(error);
+ * res.status(status).json(body);
+ * ```
+ */
+export function toHttpResponse(error) {
+    return {
+        status: error.statusCode,
+        body: {
+            statusCode: error.statusCode,
+            error: error.statusCode === 409 ? 'Conflict' : 'Unprocessable Entity',
+            message: error.message,
+            idempotencyKey: error.key,
+            reason: error.reason,
+        },
+        headers: {},
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAWtE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,KAA+B;IAC5D,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,UAAU;QACxB,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,sBAAsB;YACrE,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,cAAc,EAAE,KAAK,CAAC,GAAG;YACzB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB;QACD,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC"}

package/dist/idempotency.behavior.d.ts

@@ -0,0 +1,117 @@
+import { type IPipelineBehavior, type IPipelineBehaviorContract, type IPipelineBehaviorOptionsResolver, type IPipelineContext, type NextDelegate, PIPELINE_BEHAVIOR_CONTRACT, type PipelineItemToken, type PipelineLogger } from '@cqrs-ddd/pipeline';
+import type { IdempotencyBehaviorOptions } from './interfaces/idempotency-options.interface.js';
+import type { IdempotencyStore } from './interfaces/idempotency-store.interface.js';
+/**
+ * Unique symbol key set on `context.items` holding the active idempotency key string.
+ *
+ * @example
+ * ```ts
+ * const key = context.items.get(IDEMPOTENCY_KEY_ITEM) as string | undefined;
+ * ```
+ */
+export declare const IDEMPOTENCY_KEY_ITEM: unique symbol;
+/**
+ * Typed token for {@link IDEMPOTENCY_KEY_ITEM}: the active idempotency key. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const IDEMPOTENCY_KEY_ITEM_TOKEN: PipelineItemToken<string>;
+/**
+ * Unique symbol key set on `context.items` to `true` when the response was replayed
+ * from a previously-stored record (the handler did not run this time).
+ *
+ * @example
+ * ```ts
+ * const wasReplayed = context.items.get(IDEMPOTENCY_REPLAYED_ITEM) === true;
+ * ```
+ */
+export declare const IDEMPOTENCY_REPLAYED_ITEM: unique symbol;
+/**
+ * Typed token for {@link IDEMPOTENCY_REPLAYED_ITEM}: the idempotent replay flag. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const IDEMPOTENCY_REPLAYED_ITEM_TOKEN: PipelineItemToken<boolean>;
+/**
+ * Unique symbol key set on `context.items` to `true` when a handler completed after
+ * its claim had expired or been replaced. The successful handler result is returned,
+ * but this execution is not allowed to overwrite the newer owner's replay state.
+ *
+ * @example
+ * ```ts
+ * const ownershipLost = context.items.get(IDEMPOTENCY_OWNERSHIP_LOST_ITEM) === true;
+ * ```
+ */
+export declare const IDEMPOTENCY_OWNERSHIP_LOST_ITEM: unique symbol;
+/**
+ * Typed token for {@link IDEMPOTENCY_OWNERSHIP_LOST_ITEM}: the idempotency ownership-lost flag. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN: PipelineItemToken<boolean>;
+/**
+ * Pipeline behavior that deduplicates concurrent requests sharing an
+ * idempotency key and replays the stored response after a successful execution.
+ *
+ * For each in-scope request it derives a key
+ * ({@link IdempotencyBehaviorOptions.keyFactory}), then atomically claims it in
+ * a pluggable {@link IdempotencyStore}:
+ *
+ * - **first claim** → run the handler and store the completed response;
+ * - **duplicate, completed** → return the stored response (no re-execution);
+ * - **duplicate, in progress** → throw {@link IdempotencyConflictError} (`409`);
+ * - **key reused with a different payload** → throw it as `key_reuse` (`422`);
+ * - **completed under a different authorization scope** → throw it as
+ *   `replay_scope` (`409`), when a
+ *   {@link IdempotencyBehaviorOptions.replayScopeFactory} is configured. The
+ *   record is kept and the handler is not re-executed, so a permission change
+ *   cannot duplicate the effect.
+ *
+ * Each claim carries a unique owner token. Completion and release compare that
+ * token atomically, so an execution that outlives its TTL cannot overwrite or
+ * delete a newer claim after the key is reclaimed.
+ *
+ * When the handler throws, `releaseOnError` controls whether the key remains
+ * claimed. It defaults to `true`, so failed executions release the key and a
+ * later retry may execute the handler again. Set it to `false` when retaining
+ * the claim after a failure is preferable to retryability.
+ *
+ * Store-agnostic by design: memory (default), Redis, Postgres, or your own are
+ * one-line swaps of the store passed to the constructor. When no key is produced,
+ * the handler runs normally.
+ *
+ * @example Per-handler idempotency
+ * Keyed off an optional `Idempotency-Key` header and partitioned by tenant and principal:
+ * ```ts
+ * class CreatePaymentHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [IdempotencyBehavior, {
+ *     keyFactory: createPartitionedIdempotencyKeyFactory({
+ *       principal: (c) => c.items.get('currentUserId') as string | undefined,
+ *       operation: (c) => c.items.get('idempotencyKey') as string | undefined,
+ *       onMissingOperation: 'skip',
+ *     }),
+ *     ttl: 86_400_000,
+ *   }])
+ *   async handle(command: CreatePaymentCommand) {}
+ * }
+ * ```
+ */
+export declare class IdempotencyBehavior implements IPipelineBehavior, IPipelineBehaviorOptionsResolver<IdempotencyBehaviorOptions> {
+    private readonly store;
+    static readonly [PIPELINE_BEHAVIOR_CONTRACT]: IPipelineBehaviorContract;
+    private readonly logger;
+    private readonly defaults;
+    constructor(store: IdempotencyStore, defaults?: IdempotencyBehaviorOptions, logger?: PipelineLogger);
+    handle(context: IPipelineContext, next: NextDelegate): Promise<unknown>;
+    /**
+     * The key was already claimed. Replay a completed response, or surface a
+     * conflict for an in-progress duplicate, a key reused with a new payload, or a
+     * completed record whose replay scope does not match the caller's.
+     */
+    private replayOrConflict;
+    /**
+     * Release a failed execution's claim only if it still owns the key; never let
+     * cleanup break propagation of the original handler error.
+     */
+    private release;
+    /** Shallow-merges pipeline-level options over the constructor defaults. */
+    resolveEffectiveOptions(options?: IdempotencyBehaviorOptions): IdempotencyBehaviorOptions;
+}
+//# sourceMappingURL=idempotency.behavior.d.ts.map

package/dist/idempotency.behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.behavior.d.ts","sourceRoot":"","sources":["../src/idempotency.behavior.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,0BAA0B,EAI1B,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAEpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAMhG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAAiB,CAAC,MAAM,CACS,CAAC;AAE3E;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAAE,iBAAiB,CAAC,OAAO,CAIpE,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,eAE3C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qCAAqC,EAAE,iBAAiB,CAAC,OAAO,CAI1E,CAAC;AAcJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,mBACX,YACE,iBAAiB,EACjB,gCAAgC,CAAC,0BAA0B,CAAC;IA+D5D,OAAO,CAAC,QAAQ,CAAC,KAAK;IA7DxB,MAAM,CAAC,QAAQ,CAAC,CAAC,0BAA0B,CAAC,EAAE,yBAAyB,CAuDrE;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,YACmB,KAAK,EAAE,gBAAgB,EACxC,QAAQ,CAAC,EAAE,0BAA0B,EACrC,MAAM,CAAC,EAAE,cAAc,EAexB;IAEK,MAAM,CACV,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,OAAO,CAAC,CAuIlB;IAED;;;;OAIG;YACW,gBAAgB;IAqE9B;;;OAGG;YACW,OAAO;IAYrB,2EAA2E;IAC3E,uBAAuB,CACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,0BAA0B,CAG5B;CACF"}

package/dist/idempotency.behavior.js

@@ -0,0 +1,332 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { randomUUID } from 'node:crypto';
+import { createPipelineItem, PIPELINE_BEHAVIOR_CONTRACT, setPipelineItem, } from '@cqrs-ddd/pipeline';
+import { untyped } from '@cqrs-ddd/untyped';
+import { DEFAULT_IDEMPOTENCY_TTL_MS } from './constants/tokens.js';
+import { IdempotencyCompletionError } from './errors/idempotency-completion.error.js';
+import { IdempotencyConflictError } from './errors/idempotency-conflict.error.js';
+import { fingerprintValue } from './helpers/fingerprint.js';
+import { toJsonSnapshot } from './helpers/json-snapshot.js';
+/**
+ * Unique symbol key set on `context.items` holding the active idempotency key string.
+ *
+ * @example
+ * ```ts
+ * const key = context.items.get(IDEMPOTENCY_KEY_ITEM) as string | undefined;
+ * ```
+ */
+export const IDEMPOTENCY_KEY_ITEM = Symbol('IDEMPOTENCY_KEY_ITEM');
+/**
+ * Typed token for {@link IDEMPOTENCY_KEY_ITEM}: the active idempotency key. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const IDEMPOTENCY_KEY_ITEM_TOKEN = createPipelineItem('IDEMPOTENCY_KEY_ITEM', IDEMPOTENCY_KEY_ITEM);
+/**
+ * Unique symbol key set on `context.items` to `true` when the response was replayed
+ * from a previously-stored record (the handler did not run this time).
+ *
+ * @example
+ * ```ts
+ * const wasReplayed = context.items.get(IDEMPOTENCY_REPLAYED_ITEM) === true;
+ * ```
+ */
+export const IDEMPOTENCY_REPLAYED_ITEM = Symbol('IDEMPOTENCY_REPLAYED_ITEM');
+/**
+ * Typed token for {@link IDEMPOTENCY_REPLAYED_ITEM}: the idempotent replay flag. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const IDEMPOTENCY_REPLAYED_ITEM_TOKEN = createPipelineItem('IDEMPOTENCY_REPLAYED_ITEM', IDEMPOTENCY_REPLAYED_ITEM);
+/**
+ * Unique symbol key set on `context.items` to `true` when a handler completed after
+ * its claim had expired or been replaced. The successful handler result is returned,
+ * but this execution is not allowed to overwrite the newer owner's replay state.
+ *
+ * @example
+ * ```ts
+ * const ownershipLost = context.items.get(IDEMPOTENCY_OWNERSHIP_LOST_ITEM) === true;
+ * ```
+ */
+export const IDEMPOTENCY_OWNERSHIP_LOST_ITEM = Symbol('IDEMPOTENCY_OWNERSHIP_LOST_ITEM');
+/**
+ * Typed token for {@link IDEMPOTENCY_OWNERSHIP_LOST_ITEM}: the idempotency ownership-lost flag. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN = createPipelineItem('IDEMPOTENCY_OWNERSHIP_LOST_ITEM', IDEMPOTENCY_OWNERSHIP_LOST_ITEM);
+const DEFAULT_SCOPE = ['command'];
+/** Whether this request kind is configured for idempotency. */
+function inScope(options, requestKind) {
+    return (options?.scope ?? DEFAULT_SCOPE).includes(requestKind);
+}
+/**
+ * Pipeline behavior that deduplicates concurrent requests sharing an
+ * idempotency key and replays the stored response after a successful execution.
+ *
+ * For each in-scope request it derives a key
+ * ({@link IdempotencyBehaviorOptions.keyFactory}), then atomically claims it in
+ * a pluggable {@link IdempotencyStore}:
+ *
+ * - **first claim** → run the handler and store the completed response;
+ * - **duplicate, completed** → return the stored response (no re-execution);
+ * - **duplicate, in progress** → throw {@link IdempotencyConflictError} (`409`);
+ * - **key reused with a different payload** → throw it as `key_reuse` (`422`);
+ * - **completed under a different authorization scope** → throw it as
+ *   `replay_scope` (`409`), when a
+ *   {@link IdempotencyBehaviorOptions.replayScopeFactory} is configured. The
+ *   record is kept and the handler is not re-executed, so a permission change
+ *   cannot duplicate the effect.
+ *
+ * Each claim carries a unique owner token. Completion and release compare that
+ * token atomically, so an execution that outlives its TTL cannot overwrite or
+ * delete a newer claim after the key is reclaimed.
+ *
+ * When the handler throws, `releaseOnError` controls whether the key remains
+ * claimed. It defaults to `true`, so failed executions release the key and a
+ * later retry may execute the handler again. Set it to `false` when retaining
+ * the claim after a failure is preferable to retryability.
+ *
+ * Store-agnostic by design: memory (default), Redis, Postgres, or your own are
+ * one-line swaps of the store passed to the constructor. When no key is produced,
+ * the handler runs normally.
+ *
+ * @example Per-handler idempotency
+ * Keyed off an optional `Idempotency-Key` header and partitioned by tenant and principal:
+ * ```ts
+ * class CreatePaymentHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [IdempotencyBehavior, {
+ *     keyFactory: createPartitionedIdempotencyKeyFactory({
+ *       principal: (c) => c.items.get('currentUserId') as string | undefined,
+ *       operation: (c) => c.items.get('idempotencyKey') as string | undefined,
+ *       onMissingOperation: 'skip',
+ *     }),
+ *     ttl: 86_400_000,
+ *   }])
+ *   async handle(command: CreatePaymentCommand) {}
+ * }
+ * ```
+ */
+export class IdempotencyBehavior {
+    store;
+    static [PIPELINE_BEHAVIOR_CONTRACT] = {
+        order: (context) => {
+            const options = context.effectiveOptions;
+            if (!inScope(options, context.requestKind)) {
+                return undefined;
+            }
+            return {
+                after: ['@cqrs-ddd/pipeline-casl:CaslBehavior', 'CaslBehavior'],
+            };
+        },
+        validate: (context) => {
+            const options = context.effectiveOptions;
+            if (!inScope(options, context.requestKind)) {
+                return undefined;
+            }
+            if ((context.declarationSource === 'handler' ||
+                context.declarationSource === 'both') &&
+                !options?.keyFactory) {
+                return [
+                    {
+                        handlerName: context.handlerName,
+                        behaviorName: IdempotencyBehavior.name,
+                        message: 'Explicit IdempotencyBehavior intent requires an explicit `keyFactory` for deduplication',
+                        fix: 'Provide keyFactory in the idempotent({ keyFactory }) entry ' +
+                            'or use createPartitionedIdempotencyKeyFactory(...).',
+                    },
+                ];
+            }
+            if (options?.keyFactory && typeof options.keyFactory !== 'function') {
+                return [
+                    {
+                        handlerName: context.handlerName,
+                        behaviorName: IdempotencyBehavior.name,
+                        message: `IdempotencyBehavior keyFactory must be a callable function, received ${typeof options.keyFactory}`,
+                        fix: 'Pass a valid function (ctx) => string as the keyFactory option of the idempotent({ keyFactory }) entry.',
+                    },
+                ];
+            }
+            return undefined;
+        },
+    };
+    logger;
+    defaults;
+    constructor(store, defaults, logger) {
+        this.store = store;
+        const candidate = untyped(this.store ?? {});
+        if (typeof candidate.completeIfOwned !== 'function' ||
+            typeof candidate.deleteIfOwned !== 'function') {
+            throw new TypeError('The configured IdempotencyStore is missing required methods. ' +
+                'IdempotencyStore requires atomic completeIfOwned() and deleteIfOwned() operations.');
+        }
+        this.defaults = defaults ?? {};
+        this.logger = logger ?? console;
+    }
+    async handle(context, next) {
+        const options = this.resolveEffectiveOptions(context.getBehaviorOptions(IdempotencyBehavior));
+        if (!inScope(options, context.requestKind)) {
+            return next();
+        }
+        const key = options.keyFactory?.(context);
+        if (!key) {
+            // No idempotency key → nothing to dedupe; run normally.
+            return next();
+        }
+        setPipelineItem(context, IDEMPOTENCY_KEY_ITEM_TOKEN, key);
+        const ttl = options.ttl ?? DEFAULT_IDEMPOTENCY_TTL_MS;
+        if (!Number.isSafeInteger(ttl) || ttl <= 0) {
+            throw new TypeError('Idempotency ttl must be a positive safe integer in milliseconds.');
+        }
+        const fingerprint = (options.fingerprint ?? true)
+            ? fingerprintValue(context.request)
+            : undefined;
+        // Resolved before the claim, so a replayScopeFactory that throws rejects the
+        // operation before any key is claimed.
+        const replayScope = options.replayScopeFactory?.(context);
+        const scopeRequired = options.replayScopeFactory !== undefined;
+        const claimId = randomUUID();
+        const claim = {
+            key,
+            status: 'in_progress',
+            requestName: context.requestName,
+            claimId,
+            fingerprint,
+            replayScope,
+            createdAt: new Date().toISOString(),
+        };
+        let claimed = await this.store.setIfAbsent(key, claim, ttl);
+        if (!claimed) {
+            const existing = await this.store.get(key);
+            if (existing) {
+                return this.replayOrConflict(context, key, fingerprint, { replayScope, scopeRequired }, existing);
+            }
+            // The record disappeared or expired after the failed claim. Give this
+            // request one bounded opportunity to claim the now-available key instead
+            // of reporting a false in-progress conflict.
+            claimed = await this.store.setIfAbsent(key, claim, ttl);
+            if (!claimed) {
+                return this.replayOrConflict(context, key, fingerprint, {
+                    replayScope,
+                    scopeRequired,
+                });
+            }
+        }
+        let response;
+        try {
+            response = await next();
+        }
+        catch (error) {
+            if (options.releaseOnError ?? true) {
+                await this.release(key, claimId);
+            }
+            throw error;
+        }
+        let responseSnapshot;
+        try {
+            responseSnapshot = toJsonSnapshot(response);
+        }
+        catch (cause) {
+            // The handler already succeeded, so retain the claim until expiry rather
+            // than allowing an immediate retry to repeat completed side effects.
+            this.logger.error?.(`Idempotency response snapshot failed after ${context.requestName} ` +
+                `executed successfully (key: ${key}). The claim is retained until it ` +
+                'expires; retrying the business request may repeat side effects.', cause.stack, IdempotencyBehavior.name);
+            throw new IdempotencyCompletionError(key, claimId, cause, 'snapshot');
+        }
+        // The handler has already succeeded. Completion must be conditional on
+        // still owning the claim; a stale execution must never overwrite a newer
+        // execution that reclaimed the key after this claim's TTL elapsed.
+        let completed;
+        try {
+            completed = await this.store.completeIfOwned(key, claimId, {
+                ...claim,
+                status: 'completed',
+                response: responseSnapshot,
+                completedAt: new Date().toISOString(),
+            }, ttl);
+        }
+        catch (cause) {
+            this.logger.error?.(`Idempotency completion persistence failed after ${context.requestName} ` +
+                `executed successfully (key: ${key}). Retrying the business request may ` +
+                'repeat side effects.', cause instanceof Error ? cause.stack : undefined, IdempotencyBehavior.name);
+            throw new IdempotencyCompletionError(key, claimId, cause, 'store');
+        }
+        if (!completed) {
+            setPipelineItem(context, IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN, true);
+            this.logger.error?.(`Idempotency claim ownership was lost after ${context.requestName} ` +
+                `completed successfully (key: ${key}). The successful result is being ` +
+                'returned, but this execution did not overwrite the newer claim.', IdempotencyBehavior.name);
+        }
+        return response;
+    }
+    /**
+     * The key was already claimed. Replay a completed response, or surface a
+     * conflict for an in-progress duplicate, a key reused with a new payload, or a
+     * completed record whose replay scope does not match the caller's.
+     */
+    async replayOrConflict(context, key, fingerprint, scope, knownExisting) {
+        const existing = knownExisting ?? (await this.store.get(key));
+        // A second failed claim followed by another disappearing record indicates
+        // repeated contention. The retry is deliberately bounded to avoid a hot
+        // loop if a backend is unstable or claims are being rapidly replaced.
+        if (!existing) {
+            throw new IdempotencyConflictError({
+                key,
+                requestName: context.requestName,
+                reason: 'in_progress',
+            });
+        }
+        // A fingerprinted request never replays a record that cannot prove payload identity.
+        if (existing.requestName !== context.requestName ||
+            (fingerprint && existing.fingerprint !== fingerprint)) {
+            throw new IdempotencyConflictError({
+                key,
+                requestName: context.requestName,
+                reason: 'key_reuse',
+            });
+        }
+        if (existing.status === 'in_progress') {
+            throw new IdempotencyConflictError({
+                key,
+                requestName: context.requestName,
+                reason: 'in_progress',
+            });
+        }
+        // A completed record may only be replayed to a caller whose authorization
+        // scope matches the one it was produced under. A record stored without a
+        // scope cannot prove that, so it fails closed rather than replaying. The
+        // record is retained: re-executing a completed operation would duplicate it.
+        if (scope.scopeRequired &&
+            (existing.replayScope === undefined ||
+                existing.replayScope !== scope.replayScope)) {
+            this.logger.warn?.(`Refusing to replay ${context.requestName} (key: ${key}): the stored ` +
+                'response was authorized under a different scope than this caller.', IdempotencyBehavior.name);
+            throw new IdempotencyConflictError({
+                key,
+                requestName: context.requestName,
+                reason: 'replay_scope',
+            });
+        }
+        setPipelineItem(context, IDEMPOTENCY_REPLAYED_ITEM_TOKEN, true);
+        this.logger.debug?.(`Replaying idempotent response for ${context.requestName} (key: ${key})`, IdempotencyBehavior.name);
+        return existing.response;
+    }
+    /**
+     * Release a failed execution's claim only if it still owns the key; never let
+     * cleanup break propagation of the original handler error.
+     */
+    async release(key, claimId) {
+        try {
+            await this.store.deleteIfOwned(key, claimId);
+        }
+        catch (error) {
+            this.logger.warn?.(`Failed to release idempotency key "${key}": ` +
+                `${error instanceof Error ? error.message : error}`, IdempotencyBehavior.name);
+        }
+    }
+    /** Shallow-merges pipeline-level options over the constructor defaults. */
+    resolveEffectiveOptions(options) {
+        if (!options)
+            return this.defaults;
+        return { ...this.defaults, ...options };
+    }
+}
+//# sourceMappingURL=idempotency.behavior.js.map

package/dist/idempotency.behavior.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Idempotent commands: the behavior, its stores, key factories and `idempotent()`. The HTTP mapping of its errors is the `@cqrs-ddd/pipeline-idempotency/http` entry point.
+ *
+ * @module main
+ */
+export { DEFAULT_IDEMPOTENCY_TTL_MS } from './constants/tokens.js';
+export { IdempotencyCompletionError, type IdempotencyFinalizationPhase, } from './errors/idempotency-completion.error.js';
+export { IdempotencyConflictError, type IdempotencyConflictReason, } from './errors/idempotency-conflict.error.js';
+export { type IdempotencyPartitionDimension, MissingIdempotencyPartitionError, } from './errors/missing-partition.error.js';
+export { buildIdempotencyAttributes } from './helpers/build-attributes.js';
+export { fingerprintValue } from './helpers/fingerprint.js';
+export { type IdempotencyIntentOptions, idempotent, } from './helpers/idempotency.intent.js';
+export { createPartitionedIdempotencyKeyFactory, type IdempotencyOperationFactory, type IdempotencyPrincipalFactory, type PartitionedIdempotencyKeyOptions, } from './helpers/partitioned-key.js';
+export { IDEMPOTENCY_KEY_ITEM, IDEMPOTENCY_KEY_ITEM_TOKEN, IDEMPOTENCY_OWNERSHIP_LOST_ITEM, IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN, IDEMPOTENCY_REPLAYED_ITEM, IDEMPOTENCY_REPLAYED_ITEM_TOKEN, IdempotencyBehavior, } from './idempotency.behavior.js';
+export type { IdempotencyBehaviorOptions, IdempotencyKeyFactory, IdempotencyReplayScopeFactory, } from './interfaces/idempotency-options.interface.js';
+export type { IdempotencyRecord, IdempotencyRequestKind, IdempotencyStatus, JsonValue, } from './interfaces/idempotency-record.interface.js';
+export type { IdempotencyStore, MaybePromise, } from './interfaces/idempotency-store.interface.js';
+export { MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, } from './stores/memory.store.js';
+export { createIdempotencyTableSql, PostgresIdempotencyStore, type PostgresIdempotencyStoreOptions, type PostgresQueryableLike, type PostgresQueryResultLike, type PostgresRowLike, } from './stores/postgres.store.js';
+export { type RedisClientLike, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, } from './stores/redis.store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EACL,0BAA0B,EAC1B,KAAK,4BAA4B,GAClC,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,wBAAwB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,6BAA6B,EAClC,gCAAgC,GACjC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,KAAK,wBAAwB,EAC7B,UAAU,GACX,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,sCAAsC,EACtC,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,gCAAgC,GACtC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,qCAAqC,EACrC,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,0BAA0B,EAC1B,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,+CAA+C,CAAC;AACvD,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,SAAS,GACV,MAAM,8CAA8C,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,YAAY,GACb,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Idempotent commands: the behavior, its stores, key factories and `idempotent()`. The HTTP mapping of its errors is the `@cqrs-ddd/pipeline-idempotency/http` entry point.
+ *
+ * @module main
+ */
+export { DEFAULT_IDEMPOTENCY_TTL_MS } from './constants/tokens.js';
+export { IdempotencyCompletionError, } from './errors/idempotency-completion.error.js';
+export { IdempotencyConflictError, } from './errors/idempotency-conflict.error.js';
+export { MissingIdempotencyPartitionError, } from './errors/missing-partition.error.js';
+export { buildIdempotencyAttributes } from './helpers/build-attributes.js';
+export { fingerprintValue } from './helpers/fingerprint.js';
+export { idempotent, } from './helpers/idempotency.intent.js';
+export { createPartitionedIdempotencyKeyFactory, } from './helpers/partitioned-key.js';
+export { IDEMPOTENCY_KEY_ITEM, IDEMPOTENCY_KEY_ITEM_TOKEN, IDEMPOTENCY_OWNERSHIP_LOST_ITEM, IDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKEN, IDEMPOTENCY_REPLAYED_ITEM, IDEMPOTENCY_REPLAYED_ITEM_TOKEN, IdempotencyBehavior, } from './idempotency.behavior.js';
+export { MemoryIdempotencyStore, } from './stores/memory.store.js';
+export { createIdempotencyTableSql, PostgresIdempotencyStore, } from './stores/postgres.store.js';
+export { RedisIdempotencyStore, } from './stores/redis.store.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;GAIG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EACL,0BAA0B,GAE3B,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,wBAAwB,GAEzB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAEL,gCAAgC,GACjC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAEL,UAAU,GACX,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,sCAAsC,GAIvC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,qCAAqC,EACrC,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AAgBnC,OAAO,EACL,sBAAsB,GAEvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GAKzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC"}