@cqrs-ddd/pipeline-resilience 0.5.0

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

@@ -0,0 +1,326 @@
+import type { IPolicy } from 'cockatiel';
+/**
+ * The resilience layers that can be composed, listed from **outermost**
+ * (runs first / wraps everything) to **innermost** (closest to the handler).
+ *
+ * The default composition order is:
+ * `fallback → retry → circuitBreaker → bulkhead → timeout → handler`.
+ */
+export type ResilienceLayer = 'fallback' | 'retry' | 'circuitBreaker' | 'bulkhead' | 'timeout';
+/**
+ * The layers {@link ResilienceBehavior} applies around a whole handler.
+ * Circuit breaker and fallback belong to a dependency, so they exist only on
+ * named policies ({@link ResiliencePolicyOptions}).
+ */
+export type HandlerResilienceLayer = Exclude<ResilienceLayer, 'circuitBreaker' | 'fallback'>;
+/** Jitter strategy used by the exponential backoff generator. */
+export type JitterStrategy = 'decorrelated' | 'none' | 'full' | 'half';
+/** Backoff strategy controlling the delay between retry attempts. */
+export type RetryBackoff = 
+/** Wait a fixed `delay` (ms) between every attempt. */
+{
+    type: 'constant';
+    delay: number;
+}
+/**
+ * Decorrelated-jitter exponential backoff (recommended). All fields are
+ * optional and fall back to cockatiel's defaults
+ * (`initialDelay: 128`, `maxDelay: 30_000`, `exponent: 2`).
+ */
+ | {
+    type: 'exponential';
+    initialDelay?: number;
+    maxDelay?: number;
+    exponent?: number;
+    jitter?: JitterStrategy;
+}
+/** Walk through an explicit list of delays (ms); the last value repeats. */
+ | {
+    type: 'iterable';
+    delays: number[];
+};
+/** Retry configuration of a named policy: re-runs the call on a handled failure. */
+export interface RetryPolicyOptions {
+    /**
+     * Maximum number of retry attempts after the initial call (e.g. `3` allows
+     * the original execution plus up to three retries), matching Cockatiel's
+     * `retry(..., { maxAttempts })` semantics.
+     */
+    maxAttempts: number;
+    /** Delay strategy between attempts. Defaults to no delay. */
+    backoff?: RetryBackoff;
+}
+/** Retry configuration of the behavior — re-runs all downstream pipeline work on a handled failure. */
+export interface RetryOptions extends RetryPolicyOptions {
+    /**
+     * Explicit acknowledgement that replaying the handler/downstream behaviors is
+     * safe. Required for `command` and `event` retries because those request kinds
+     * commonly perform side effects.
+     *
+     * Queries do not require this acknowledgement.
+     *
+     * Set this only when the operation is genuinely replay-safe — for example the
+     * side effect is protected by a downstream idempotency key, transaction, or
+     * otherwise repeatable contract. `@cqrs-ddd/pipeline-idempotency` does not make
+     * arbitrary external effects exactly-once by itself.
+     *
+     * @example Replay-safe command retry
+     * ```ts
+     * @pipeline.wrap({ kind: 'command' }, [ResilienceBehavior, {
+     *   retry: {
+     *     maxAttempts: 2,
+     *     replaySafe: true,
+     *     backoff: { type: 'exponential', maxDelay: 1_000 },
+     *   },
+     *   handle: (error) => error instanceof TransientGatewayError,
+     * }])
+     * ```
+     */
+    replaySafe?: boolean;
+}
+/** Circuit breaker strategy controlling when the circuit opens. */
+export type BreakerStrategy = 
+/** Open after `threshold` consecutive failures. */
+{
+    type: 'consecutive';
+    threshold: number;
+}
+/**
+ * Open when the failure proportion exceeds `threshold` (0–1) within a
+ * rolling `duration` (ms) window. `minimumRps` avoids tripping under low load.
+ */
+ | {
+    type: 'sampling';
+    threshold: number;
+    duration: number;
+    minimumRps?: number;
+}
+/**
+ * Open when the failure proportion exceeds `threshold` (0–1) over the last
+ * `size` calls (count-based sliding window).
+ */
+ | {
+    type: 'count';
+    threshold: number;
+    size: number;
+    minimumNumberOfCalls?: number;
+};
+/** Circuit breaker configuration. */
+export interface CircuitBreakerOptions {
+    /**
+     * Milliseconds the circuit stays open before allowing a trial (half-open)
+     * call through.
+     */
+    halfOpenAfter: number;
+    /** The breaker policy controlling when the circuit trips. */
+    breaker: BreakerStrategy;
+}
+/** Timeout configuration of a named policy. Underlying work stops only when it cooperates with the abort signal. */
+export interface TimeoutPolicyOptions {
+    /** Duration in milliseconds after which the call times out. */
+    duration: number;
+    /**
+     * - `aggressive` (default): reject immediately with `TaskCancelledError`.
+     * - `cooperative`: signal cancellation and wait for the call to settle.
+     */
+    strategy?: 'aggressive' | 'cooperative';
+}
+/** Timeout configuration of the behavior. Underlying work stops only when it cooperates with the abort signal. */
+export interface TimeoutOptions extends TimeoutPolicyOptions {
+    /**
+     * Explicit acknowledgement that an `aggressive` timeout is safe on a `command`
+     * or `event` handler. The caller is answered while the handler keeps running,
+     * so a retry, a released idempotency claim or a client retry can run the same
+     * side effect alongside it. Required for those request kinds unless the
+     * strategy is `cooperative`.
+     */
+    replaySafe?: boolean;
+}
+/** Bulkhead configuration — limits concurrent in-flight executions. */
+export interface BulkheadOptions {
+    /** Maximum number of concurrent executions. */
+    limit: number;
+    /** Optional number of queued executions allowed beyond `limit`. */
+    queue?: number;
+}
+/** Fallback configuration — substitutes a value when execution fails. */
+export type FallbackOptions = 
+/** Return a static `value` when a handled failure occurs. */
+{
+    value: unknown;
+}
+/** Lazily produce a value when a handled failure occurs. */
+ | {
+    factory: () => unknown;
+};
+/** What every telemetry hook receives. */
+export interface ResilienceTelemetryEvent {
+    /** The named policy that fired the event; absent for a handler's policy. */
+    policyName?: string;
+}
+/**
+ * Optional telemetry hooks fired by the underlying cockatiel policies.
+ *
+ * These are attached once per policy: per handler for the behavior, per name
+ * for a named policy. They are scoped to that policy rather than to a single
+ * request.
+ */
+export interface ResilienceTelemetry {
+    /** Fired before each retry, with the upcoming attempt number and delay (ms). */
+    onRetry?(event: ResilienceTelemetryEvent & {
+        attempt: number;
+        delay: number;
+        /**
+         * The request that triggered this retry.
+         *
+         * A policy is cached per handler, so a handler registered for several event
+         * types shares one policy; without this the consumer could not tell which
+         * event is actually retrying.
+         */
+        requestName?: string;
+    }): void;
+    /** Fired when the circuit breaker opens (trips). */
+    onCircuitOpen?(event: ResilienceTelemetryEvent): void;
+    /** Fired when the circuit breaker closes (recovers). */
+    onCircuitClose?(event: ResilienceTelemetryEvent): void;
+    /** Fired when the circuit breaker enters the half-open trial state. */
+    onCircuitHalfOpen?(event: ResilienceTelemetryEvent): void;
+    /** Fired when a timeout is reached. */
+    onTimeout?(event: ResilienceTelemetryEvent): void;
+    /** Fired when the bulkhead rejects a call (capacity + queue exhausted). */
+    onBulkheadRejected?(event: ResilienceTelemetryEvent): void;
+}
+/**
+ * A named policy for an outbound dependency, declared once in
+ * `new ResiliencePolicies({ ... })` and shared by every caller through
+ * `ResiliencePolicies` or `@InjectResiliencePolicy(name)`.
+ *
+ * It wraps one outbound call, not a handler, so it offers every layer —
+ * a circuit breaker per dependency, a fallback value for one call — and needs
+ * no `replaySafe` acknowledgment: the adapter retries only its own call.
+ * Retry, circuit breaker and fallback still require `handle(error)` or
+ * `handleAllErrors: true`.
+ *
+ * @example A payment API shared by several handlers
+ * ```ts
+ * new ResiliencePolicies({
+ *   paymentsApi: {
+ *       handle: (error) => error instanceof PaymentGatewayUnavailableError,
+ *       retry: { maxAttempts: 2, backoff: { type: 'exponential' } },
+ *       circuitBreaker: { halfOpenAfter: 30_000, breaker: { type: 'consecutive', threshold: 5 } },
+ *       timeout: { duration: 3_000, strategy: 'cooperative' },
+ *   },
+ * });
+ * ```
+ */
+export interface ResiliencePolicyOptions {
+    /** Retry the call. */
+    retry?: RetryPolicyOptions;
+    /** Circuit breaker, shared by every caller of the policy. */
+    circuitBreaker?: CircuitBreakerOptions;
+    /** Concurrency limit, shared by every caller of the policy. */
+    bulkhead?: BulkheadOptions;
+    /** Timeout of one call. */
+    timeout?: TimeoutPolicyOptions;
+    /** Value returned in place of a handled failure. */
+    fallback?: FallbackOptions;
+    /** Selects the errors retry, circuit breaker and fallback act on. */
+    handle?: (error: unknown) => boolean;
+    /** Acts on every error; set it only deliberately. */
+    handleAllErrors?: boolean;
+    /**
+     * Composition order, outermost first.
+     *
+     * @default ['fallback', 'retry', 'circuitBreaker', 'bulkhead', 'timeout']
+     */
+    order?: ResilienceLayer[];
+    /** Telemetry hooks; every event carries the policy name. */
+    telemetry?: ResilienceTelemetry;
+}
+/**
+ * Per-handler (or global default) resilience configuration.
+ *
+ * Compose any subset of the layers below; only the ones you set are applied.
+ * Supply via `pipeline.wrap(options, [ResilienceBehavior, { ... }])` for a handler, or via
+ * the `ResilienceBehavior` constructor as application-wide defaults.
+ *
+ * ### Safety model
+ *
+ * Handler-level resilience wraps `next()`. A retry therefore replays everything
+ * downstream of this behavior, including the handler itself. Because that can
+ * repeat side effects, the package makes the dangerous choices explicit:
+ *
+ * - timeout / bulkhead may be configured without an error classifier;
+ * - retry requires `handle(error)` unless `handleAllErrors: true` is
+ *   explicitly selected;
+ * - retries for commands/events additionally require `retry.replaySafe: true`.
+ *
+ * A circuit breaker and a fallback belong to an outbound dependency, not to a
+ * handler: declare them on a named policy (`new ResiliencePolicies({ ... })`)
+ * and use it in the adapter, so only the remote call is repeated or short-circuited.
+ * The behavior contract rejects them here.
+ *
+ * @example Query retry with an explicit transient-error classifier
+ * ```ts
+ * class GetCatalogHandler {
+ *   @pipeline.wrap({ kind: 'query' }, [ResilienceBehavior, {
+ *     retry: { maxAttempts: 3, backoff: { type: 'exponential' } },
+ *     timeout: { duration: 2_000 },
+ *     handle: (error) => error instanceof CatalogUnavailableError,
+ *   }])
+ *   async handle(query: GetCatalogQuery) {}
+ * }
+ * ```
+ *
+ * @example Command timeout without retry
+ * ```ts
+ * class RebuildProjectionHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [ResilienceBehavior, {
+ *     timeout: { duration: 30_000, strategy: 'cooperative' },
+ *   }])
+ *   async handle(command: RebuildProjectionCommand) {}
+ * }
+ * ```
+ */
+export interface ResilienceBehaviorOptions {
+    /** Retry policy. */
+    retry?: RetryOptions;
+    /** Bulkhead (concurrency limiter) policy. Reused across invocations. */
+    bulkhead?: BulkheadOptions;
+    /** Timeout policy. */
+    timeout?: TimeoutOptions;
+    /**
+     * Predicate selecting which thrown errors are treated as *handled* failures
+     * (eligible for retry). Return `true` only for failures that really are safe
+     * for the configured policy.
+     *
+     * A declarative retry requires an explicit classifier.
+     * Use {@link handleAllErrors} only when handling every thrown error is
+     * intentionally part of the policy.
+     */
+    handle?: (error: unknown) => boolean;
+    /**
+     * Explicitly opt into Cockatiel's `handleAll` semantics when no classifier is
+     * supplied. Prefer {@link handle} in production so validation, authorization,
+     * domain and programmer errors are not retried.
+     */
+    handleAllErrors?: boolean;
+    /**
+     * Override the composition order of the configured layers. Only the listed,
+     * configured layers are wrapped; unlisted layers are skipped. The first entry
+     * is the outermost wrapper, the last is closest to the handler.
+     *
+     * @default ['retry', 'bulkhead', 'timeout']
+     */
+    order?: HandlerResilienceLayer[];
+    /** Optional telemetry hooks. */
+    telemetry?: ResilienceTelemetry;
+    /**
+     * Escape hatch: provide a fully pre-built cockatiel `IPolicy`. When set, all
+     * declarative options above are ignored and this policy is used verbatim.
+     * Declarative safety validation is skipped because the caller owns the policy
+     * semantics directly.
+     */
+    policy?: IPolicy;
+}
+//# sourceMappingURL=resilience-options.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resilience-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/resilience-options.interface.ts"],"names":[],"mappings":"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"}

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

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

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

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

package/dist/resilience-policies.d.ts

@@ -0,0 +1,48 @@
+import type { PipelineLogger } from '@cqrs-ddd/pipeline';
+import type { IDefaultPolicyContext } from 'cockatiel';
+import { type AnyPolicy } from './helpers/policy-factory.js';
+import type { ResiliencePolicyOptions } from './interfaces/resilience-options.interface.js';
+/**
+ * The named policies of the application, for outbound adapters: a payment API
+ * client, an SMTP sender, a partner webhook.
+ *
+ * Every policy declared in the constructor's `options` is built once, when this registry is created at startup, and
+ * shared by every caller — so a circuit breaker or bulkhead tracks the
+ * dependency, whatever handler calls it. An invalid policy fails startup with
+ * {@link ResiliencePolicyConfigurationError}.
+ *
+ * @example An adapter running its call through a shared policy
+ * ```ts
+ * export class PaymentsClient {
+ *   constructor(private readonly policies: ResiliencePolicies) {}
+ *
+ *   charge(order: Order): Promise<Receipt> {
+ *     return this.policies.execute('paymentsApi', ({ signal }) =>
+ *       this.http.post('/charges', order, { signal }),
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class ResiliencePolicies {
+    private readonly policies;
+    constructor(options?: Record<string, ResiliencePolicyOptions>, logger?: PipelineLogger);
+    /** The declared policy names, in declaration order. */
+    get names(): readonly string[];
+    /**
+     * Returns the shared cockatiel policy declared under `name`.
+     *
+     * @throws ResiliencePolicyConfigurationError when no policy has that name.
+     */
+    get(name: string): AnyPolicy;
+    /**
+     * Runs `fn` through the policy declared under `name`. `fn` receives the
+     * policy's `signal`, aborted on a cooperative timeout: pass it to the
+     * outbound call so the call really stops. With a fallback, the fallback
+     * value is returned in place of a handled failure.
+     *
+     * @throws ResiliencePolicyConfigurationError when no policy has that name.
+     */
+    execute<T>(name: string, fn: (context: IDefaultPolicyContext) => PromiseLike<T> | T): Promise<T>;
+}
+//# sourceMappingURL=resilience-policies.d.ts.map

package/dist/resilience-policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience-policies.d.ts","sourceRoot":"","sources":["../src/resilience-policies.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EACL,KAAK,SAAS,EAEf,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IAEzD,YACE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,EACjD,MAAM,CAAC,EAAE,cAAc,EAMxB;IAED,uDAAuD;IACvD,IAAI,KAAK,IAAI,SAAS,MAAM,EAAE,CAE7B;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAU3B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,EACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,GACzD,OAAO,CAAC,CAAC,CAAC,CAEZ;CACF"}

package/dist/resilience-policies.js

@@ -0,0 +1,75 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { ResiliencePolicyConfigurationError } from './errors/resilience-policy-configuration.error.js';
+import { buildResiliencePolicy, } from './helpers/policy-factory.js';
+/**
+ * The named policies of the application, for outbound adapters: a payment API
+ * client, an SMTP sender, a partner webhook.
+ *
+ * Every policy declared in the constructor's `options` is built once, when this registry is created at startup, and
+ * shared by every caller — so a circuit breaker or bulkhead tracks the
+ * dependency, whatever handler calls it. An invalid policy fails startup with
+ * {@link ResiliencePolicyConfigurationError}.
+ *
+ * @example An adapter running its call through a shared policy
+ * ```ts
+ * export class PaymentsClient {
+ *   constructor(private readonly policies: ResiliencePolicies) {}
+ *
+ *   charge(order: Order): Promise<Receipt> {
+ *     return this.policies.execute('paymentsApi', ({ signal }) =>
+ *       this.http.post('/charges', order, { signal }),
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export class ResiliencePolicies {
+    policies = new Map();
+    constructor(options, logger) {
+        const log = logger ?? console;
+        for (const [name, policyOptions] of Object.entries(options ?? {})) {
+            this.policies.set(name, buildNamedPolicy(name, policyOptions, log));
+        }
+    }
+    /** The declared policy names, in declaration order. */
+    get names() {
+        return [...this.policies.keys()];
+    }
+    /**
+     * Returns the shared cockatiel policy declared under `name`.
+     *
+     * @throws ResiliencePolicyConfigurationError when no policy has that name.
+     */
+    get(name) {
+        const policy = this.policies.get(name);
+        if (!policy) {
+            const declared = this.names.length > 0 ? this.names.join(', ') : '(none)';
+            throw new ResiliencePolicyConfigurationError(name, `no policy has this name; declared: ${declared}`);
+        }
+        return policy;
+    }
+    /**
+     * Runs `fn` through the policy declared under `name`. `fn` receives the
+     * policy's `signal`, aborted on a cooperative timeout: pass it to the
+     * outbound call so the call really stops. With a fallback, the fallback
+     * value is returned in place of a handled failure.
+     *
+     * @throws ResiliencePolicyConfigurationError when no policy has that name.
+     */
+    execute(name, fn) {
+        return this.get(name).execute(fn);
+    }
+}
+function buildNamedPolicy(name, options, logger) {
+    const classifiesErrors = typeof options.handle === 'function' || options.handleAllErrors === true;
+    if ((options.retry || options.circuitBreaker || options.fallback) &&
+        !classifiesErrors) {
+        throw new ResiliencePolicyConfigurationError(name, 'retry, circuitBreaker and fallback require handle(error) or handleAllErrors: true');
+    }
+    const policy = buildResiliencePolicy(options, { logger, policyName: name });
+    if (!policy) {
+        throw new ResiliencePolicyConfigurationError(name, 'it configures no layer (retry, circuitBreaker, bulkhead, timeout or fallback)');
+    }
+    return policy;
+}
+//# sourceMappingURL=resilience-policies.js.map

package/dist/resilience-policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience-policies.js","sourceRoot":"","sources":["../src/resilience-policies.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE,OAAO,EAAE,kCAAkC,EAAE,MAAM,mDAAmD,CAAC;AACvG,OAAO,EAEL,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAGrC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,kBAAkB;IACZ,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAEzD,YACE,OAAiD,EACjD,MAAuB;QAEvB,MAAM,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,IAAI,KAAK;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAY;QACd,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC1E,MAAM,IAAI,kCAAkC,CAC1C,IAAI,EACJ,sCAAsC,QAAQ,EAAE,CACjD,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CACL,IAAY,EACZ,EAA0D;QAE1D,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE,CAAe,CAAC;IAClD,CAAC;CACF;AAED,SAAS,gBAAgB,CACvB,IAAY,EACZ,OAAgC,EAChC,MAAsB;IAEtB,MAAM,gBAAgB,GACpB,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,eAAe,KAAK,IAAI,CAAC;IAC3E,IACE,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC;QAC7D,CAAC,gBAAgB,EACjB,CAAC;QACD,MAAM,IAAI,kCAAkC,CAC1C,IAAI,EACJ,mFAAmF,CACpF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,kCAAkC,CAC1C,IAAI,EACJ,+EAA+E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/resilience.behavior.d.ts

@@ -0,0 +1,64 @@
+import type { PipelineLogger } from '@cqrs-ddd/pipeline';
+import { type IPipelineBehavior, type IPipelineBehaviorContract, type IPipelineBehaviorOptionsResolver, type IPipelineContext, type NextDelegate, PIPELINE_BEHAVIOR_CONTRACT } from '@cqrs-ddd/pipeline';
+import type { ResilienceBehaviorOptions } from './interfaces/resilience-options.interface.js';
+/**
+ * Pipeline behavior that wraps each command / query / event handler in a
+ * cockatiel resilience policy — the layers that make sense around a whole
+ * handler: retry, timeout and bulkhead.
+ *
+ * A circuit breaker and a fallback belong to an outbound dependency, not to a
+ * handler: declare them on a named policy (`new ResiliencePolicies({ ... })`)
+ * and use it in the adapter through {@link ResiliencePolicies}. The behavior
+ * contract rejects them here.
+ *
+ * Resolution of the effective options for a handler where this behavior is
+ * attached:
+ * 1. Application-wide defaults, the first constructor argument.
+ * 2. Per-handler options from `pipeline.wrap(options, [ResilienceBehavior, { ... }])`,
+ *    shallow-merged on top of the defaults (handler keys win).
+ *
+ * Policies are built **lazily on first invocation and cached per handler**, so
+ * a stateful layer (bulkhead) correctly shares state across
+ * every request to that handler. When no options resolve, the behavior caches
+ * that result and passes subsequent invocations directly to `next()` without
+ * constructing or executing a cockatiel policy.
+ *
+ * ### Replay / error-classification safety
+ *
+ * A handler-level retry calls `next()` again, which means the complete
+ * downstream pipeline and handler are replayed. To avoid accidental duplicate
+ * side effects, command/event retries must explicitly set
+ * `retry.replaySafe: true`. A retry must also define which errors are transient via `handle(error)`, unless the caller
+ * intentionally opts into `handleAllErrors: true`. An `aggressive` timeout
+ * (the default strategy) on a command/event answers the caller while the
+ * handler keeps running, so it requires `strategy: 'cooperative'` or
+ * `timeout.replaySafe: true`.
+ *
+ * Timeout and bulkhead-only policies do not require an error classifier because
+ * they do not decide which application errors are retryable.
+ * A custom pre-built Cockatiel `policy` also bypasses the declarative safety
+ * checks because the caller owns its semantics directly.
+ */
+export declare class ResilienceBehavior implements IPipelineBehavior, IPipelineBehaviorOptionsResolver<ResilienceBehaviorOptions> {
+    private readonly defaultOptions?;
+    static readonly [PIPELINE_BEHAVIOR_CONTRACT]: IPipelineBehaviorContract;
+    private readonly logger;
+    /**
+     * Per-handler policy cache. `null` means "resolved, but nothing configured"
+     * (pass-through), distinct from `undefined` ("not yet resolved").
+     */
+    private readonly policyCache;
+    constructor(defaultOptions?: ResilienceBehaviorOptions | undefined, logger?: PipelineLogger);
+    handle(context: IPipelineContext, next: NextDelegate): Promise<unknown>;
+    /** Resolves, validates, and caches the composed policy for the handler in `context`. */
+    private resolvePolicy;
+    /**
+     * Rejects ambiguous whole-handler resilience configurations before Cockatiel
+     * policy creation. This turns replay/error-classification assumptions into an
+     * explicit application decision instead of a hidden default.
+     */
+    private assertSafeConfiguration;
+    /** Shallow-merges pipeline-level options over the constructor defaults. */
+    resolveEffectiveOptions(options?: ResilienceBehaviorOptions): ResilienceBehaviorOptions | undefined;
+}
+//# sourceMappingURL=resilience.behavior.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.behavior.d.ts","sourceRoot":"","sources":["../src/resilience.behavior.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,0BAA0B,EAG3B,MAAM,oBAAoB,CAAC;AAU5B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AAgE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,kBACX,YACE,iBAAiB,EACjB,gCAAgC,CAAC,yBAAyB,CAAC;IA6B3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IA3BlC,MAAM,CAAC,QAAQ,CAAC,CAAC,0BAA0B,CAAC,EAAE,yBAAyB,CAiBrE;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4C;IAExE,YACmB,cAAc,CAAC,EAAE,yBAAyB,YAAA,EAC3D,MAAM,CAAC,EAAE,cAAc,EAGxB;IAEK,MAAM,CACV,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,OAAO,CAAC,CAkBlB;IAED,wFAAwF;IACxF,OAAO,CAAC,aAAa;IAsBrB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAc/B,2EAA2E;IAC3E,uBAAuB,CACrB,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,GAAG,SAAS,CAGvC;CACF"}