ResilienceBehaviorOptions

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:301

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.

Examples

Query retry with an explicit transient-error classifier

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) {}
}

Command timeout without retry

class RebuildProjectionHandler {
  @pipeline.wrap({ kind: 'command' }, [ResilienceBehavior, {
    timeout: { duration: 30_000, strategy: 'cooperative' },
  }])
  async handle(command: RebuildProjectionCommand) {}
}

Properties

bulkhead?

optional bulkhead?: BulkheadOptions

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:306

Bulkhead (concurrency limiter) policy. Reused across invocations.

handle?

optional handle?: (error) => boolean

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:320

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 handleAllErrors only when handling every thrown error is intentionally part of the policy.

Parameters

error

unknown

Returns

boolean

handleAllErrors?

optional handleAllErrors?: boolean

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:327

Explicitly opt into Cockatiel’s handleAll semantics when no classifier is supplied. Prefer handle in production so validation, authorization, domain and programmer errors are not retried.

order?

optional order?: HandlerResilienceLayer[]

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:336

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']

policy?

optional policy?: IPolicy<IDefaultPolicyContext, never>

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:347

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.

retry?

optional retry?: RetryOptions

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:303

Retry policy.

telemetry?

optional telemetry?: ResilienceTelemetry

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:339

Optional telemetry hooks.

timeout?

optional timeout?: TimeoutOptions

Defined in: packages/pipeline-resilience/src/interfaces/resilience-options.interface.ts:309

Timeout policy.