@amqp-contract/contract 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -12,6 +12,90 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * @see https://github.com/standard-schema/standard-schema
  */
 type AnySchema = StandardSchemaV1;
+/**
+ * TTL-Backoff retry options for exponential backoff with configurable delays.
+ *
+ * Uses TTL + wait queue pattern. Messages are published to a wait queue with
+ * per-message TTL, then dead-lettered back to the main queue after the TTL expires.
+ *
+ * **Benefits:** Configurable delays with exponential backoff and jitter.
+ * **Limitation:** More complex, potential head-of-queue blocking with mixed TTLs.
+ */
+type TtlBackoffRetryOptions = {
+  /**
+   * TTL-Backoff mode uses wait queues with per-message TTL for exponential backoff.
+   */
+  mode: "ttl-backoff";
+  /**
+   * Maximum retry attempts before sending to DLQ.
+   * @default 3
+   */
+  maxRetries?: number;
+  /**
+   * Initial delay in ms before first retry.
+   * @default 1000
+   */
+  initialDelayMs?: number;
+  /**
+   * Maximum delay in ms between retries.
+   * @default 30000
+   */
+  maxDelayMs?: number;
+  /**
+   * Exponential backoff multiplier.
+   * @default 2
+   */
+  backoffMultiplier?: number;
+  /**
+   * Add jitter to prevent thundering herd.
+   * @default true
+   */
+  jitter?: boolean;
+};
+/**
+ * Quorum-Native retry options using RabbitMQ's native delivery limit feature.
+ *
+ * Uses quorum queue's `x-delivery-limit` feature. Messages are requeued immediately
+ * with `nack(requeue=true)`, and RabbitMQ tracks delivery count via `x-delivery-count`
+ * header. When the count exceeds the queue's `deliveryLimit`, the message is
+ * automatically dead-lettered.
+ *
+ * **Benefits:** Simpler architecture, no wait queues needed, no head-of-queue blocking.
+ * **Limitation:** Immediate retries only (no exponential backoff).
+ *
+ * @see https://www.rabbitmq.com/docs/quorum-queues#poison-message-handling
+ */
+type QuorumNativeRetryOptions = {
+  /**
+   * Quorum-Native mode uses RabbitMQ's native delivery limit feature.
+   * Requires the queue to be a quorum queue with `deliveryLimit` configured.
+   */
+  mode: "quorum-native";
+};
+/**
+ * Resolved TTL-Backoff retry options with all defaults applied.
+ *
+ * This type is used internally in queue definitions after `defineQueue` has applied
+ * default values. All fields are required.
+ *
+ * @internal
+ */
+type ResolvedTtlBackoffRetryOptions = {
+  mode: "ttl-backoff";
+  maxRetries: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+  jitter: boolean;
+};
+/**
+ * Resolved retry configuration stored in queue definitions.
+ *
+ * This is a discriminated union based on the `mode` field:
+ * - `ttl-backoff`: Has all TTL-backoff options with defaults applied
+ * - `quorum-native`: No additional options (uses RabbitMQ native retry)
+ */
+type ResolvedRetryOptions = ResolvedTtlBackoffRetryOptions | QuorumNativeRetryOptions;
 /**
  * Supported compression algorithms for message payloads.
  *
@@ -41,6 +125,225 @@ type AnySchema = StandardSchemaV1;
  * ```
  */
 type CompressionAlgorithm = "gzip" | "deflate";
+/**
+ * Supported queue types in RabbitMQ.
+ *
+ * - `quorum`: Quorum queues (default, recommended) - Provide better durability and high-availability
+ *   using the Raft consensus algorithm. Best for most production use cases.
+ * - `classic`: Classic queues - The traditional RabbitMQ queue type. Use only when you need
+ *   specific features not supported by quorum queues (e.g., non-durable queues, priority queues).
+ *
+ * Note: Quorum queues require `durable: true` and do not support `exclusive: true`.
+ * When using quorum queues, `durable` is automatically set to `true`.
+ *
+ * @see https://www.rabbitmq.com/docs/quorum-queues
+ *
+ * @example
+ * ```typescript
+ * // Create a quorum queue (default, recommended)
+ * const orderQueue = defineQueue('order-processing', {
+ *   type: 'quorum', // This is the default
+ * });
+ *
+ * // Create a classic queue (for special cases)
+ * const tempQueue = defineQueue('temp-queue', {
+ *   type: 'classic',
+ *   durable: false, // Only supported with classic queues
+ * });
+ * ```
+ */
+type QueueType = "quorum" | "classic";
+/**
+ * Common queue options shared between quorum and classic queues.
+ */
+type BaseQueueOptions = {
+  /**
+   * If true, the queue survives broker restarts. Durable queues are persisted to disk.
+   * Note: Quorum queues are always durable regardless of this setting.
+   * @default false (but forced to true for quorum queues during setup)
+   */
+  durable?: boolean;
+  /**
+   * If true, the queue is deleted when the last consumer unsubscribes.
+   * @default false
+   */
+  autoDelete?: boolean;
+  /**
+   * Dead letter configuration for handling failed or rejected messages.
+   */
+  deadLetter?: DeadLetterConfig;
+  /**
+   * Additional AMQP arguments for advanced configuration.
+   */
+  arguments?: Record<string, unknown>;
+};
+/**
+ * Options for creating a quorum queue.
+ *
+ * Quorum queues do not support:
+ * - `exclusive` - Use classic queues for exclusive access
+ * - `maxPriority` - Use classic queues for priority queues
+ *
+ * Quorum queues provide native retry support via `deliveryLimit`:
+ * - RabbitMQ tracks delivery count automatically via `x-delivery-count` header
+ * - When the limit is exceeded, messages are dead-lettered (if DLX is configured)
+ * - This is simpler than TTL-based retry and avoids head-of-queue blocking issues
+ *
+ * @example
+ * ```typescript
+ * const orderQueue = defineQueue('orders', {
+ *   type: 'quorum',
+ *   deadLetter: { exchange: dlx },
+ *   deliveryLimit: 3, // Message dead-lettered after 3 delivery attempts
+ * });
+ * ```
+ */
+type QuorumQueueOptions = BaseQueueOptions & {
+  /**
+   * Queue type: quorum (default, recommended)
+   */
+  type?: "quorum";
+  /**
+   * Quorum queues do not support exclusive mode.
+   * Use type: 'classic' if you need exclusive queues.
+   */
+  exclusive?: never;
+  /**
+   * Quorum queues do not support priority queues.
+   * Use type: 'classic' if you need priority queues.
+   */
+  maxPriority?: never;
+  /**
+   * Maximum number of delivery attempts before the message is dead-lettered.
+   *
+   * When a message is rejected (nacked) and requeued, RabbitMQ increments
+   * the `x-delivery-count` header. When this count reaches the delivery limit,
+   * the message is automatically dead-lettered (if DLX is configured) or dropped.
+   *
+   * This is a quorum queue-specific feature that provides native retry handling
+   * without the complexity of TTL-based wait queues.
+   *
+   * **Benefits over TTL-based retry:**
+   * - Simpler architecture (no wait queues needed)
+   * - No head-of-queue blocking issues (TTL only works at queue head)
+   * - Native RabbitMQ feature with atomic guarantees
+   *
+   * @minimum 1 - Must be a positive integer (1 or greater)
+   *
+   * @see https://www.rabbitmq.com/docs/quorum-queues#poison-message-handling
+   *
+   * @example
+   * ```typescript
+   * const orderQueue = defineQueue('order-processing', {
+   *   type: 'quorum',
+   *   deliveryLimit: 5, // Allow up to 5 delivery attempts
+   *   deadLetter: {
+   *     exchange: dlx,
+   *     routingKey: 'order.failed',
+   *   },
+   * });
+   * ```
+   */
+  deliveryLimit?: number;
+  /**
+   * Retry configuration for handling failed message processing.
+   *
+   * Determines how the worker handles retries for consumers using this queue:
+   * - `"ttl-backoff"` (default): Uses wait queues with exponential backoff
+   * - `"quorum-native"`: Uses RabbitMQ's native delivery limit feature
+   *
+   * When using `"ttl-backoff"` mode, the core package will automatically create
+   * a wait queue (`{queueName}-wait`) and the necessary bindings.
+   *
+   * @example
+   * ```typescript
+   * // TTL-backoff mode with custom options
+   * const orderQueue = defineQueue('order-processing', {
+   *   type: 'quorum',
+   *   deadLetter: { exchange: dlx },
+   *   retry: {
+   *     mode: 'ttl-backoff',
+   *     maxRetries: 5,
+   *     initialDelayMs: 1000,
+   *     maxDelayMs: 30000,
+   *   },
+   * });
+   *
+   * // Quorum-native mode
+   * const orderQueue = defineQueue('order-processing', {
+   *   type: 'quorum',
+   *   deliveryLimit: 5,
+   *   deadLetter: { exchange: dlx },
+   *   retry: { mode: 'quorum-native' },
+   * });
+   * ```
+   */
+  retry?: TtlBackoffRetryOptions | QuorumNativeRetryOptions;
+};
+/**
+ * Options for creating a classic queue.
+ *
+ * Classic queues support all traditional RabbitMQ features including:
+ * - `exclusive: true` - For connection-scoped queues
+ * - `maxPriority` - For priority queues
+ * - `durable: false` - For non-durable queues
+ *
+ * @example
+ * ```typescript
+ * const priorityQueue = defineQueue('tasks', {
+ *   type: 'classic',
+ *   durable: true,
+ *   maxPriority: 10,
+ * });
+ * ```
+ */
+type ClassicQueueOptions = BaseQueueOptions & {
+  /**
+   * Queue type: classic (for special cases)
+   */
+  type: "classic";
+  /**
+   * If true, the queue can only be used by the declaring connection and is deleted when
+   * that connection closes. Exclusive queues are private to the connection.
+   * @default false
+   */
+  exclusive?: boolean;
+  /**
+   * Maximum priority level for priority queue (1-255, recommended: 1-10).
+   * Sets x-max-priority argument.
+   * Only supported with classic queues.
+   */
+  maxPriority?: number;
+  /**
+   * Retry configuration for handling failed message processing.
+   *
+   * Classic queues only support TTL-backoff retry mode, which uses wait queues
+   * with exponential backoff. For quorum-native retry, use quorum queues instead.
+   *
+   * @example
+   * ```typescript
+   * const orderQueue = defineQueue('order-processing', {
+   *   type: 'classic',
+   *   durable: true,
+   *   deadLetter: { exchange: dlx },
+   *   retry: {
+   *     maxRetries: 5,
+   *     initialDelayMs: 1000,
+   *     maxDelayMs: 30000,
+   *   },
+   * });
+   * ```
+   */
+  retry?: TtlBackoffRetryOptions;
+};
+/**
+ * Options for defining a queue. Uses a discriminated union based on the `type` property
+ * to enforce quorum queue constraints at compile time.
+ *
+ * - Quorum queues (default): Do not support `exclusive` or `maxPriority`
+ * - Classic queues: Support all options including `exclusive` and `maxPriority`
+ */
+type DefineQueueOptions = QuorumQueueOptions | ClassicQueueOptions;
 /**
  * Base definition of an AMQP exchange.
  *
@@ -152,27 +455,19 @@ type DeadLetterConfig = {
   routingKey?: string;
 };
 /**
- * Definition of an AMQP queue.
- *
- * A queue stores messages until they are consumed by workers. Queues are bound to exchanges
- * to receive messages based on routing rules.
+ * Common properties shared by all queue definitions.
  */
-type QueueDefinition = {
+type BaseQueueDefinition = {
   /**
    * The name of the queue. Must be unique within the RabbitMQ virtual host.
    */
   name: string;
   /**
    * If true, the queue survives broker restarts. Durable queues are persisted to disk.
-   * @default false
+   * Note: Quorum queues are always durable regardless of this setting.
+   * @default false (but forced to true for quorum queues during setup)
    */
   durable?: boolean;
-  /**
-   * If true, the queue can only be used by the declaring connection and is deleted when
-   * that connection closes. Exclusive queues are private to the connection.
-   * @default false
-   */
-  exclusive?: boolean;
   /**
    * If true, the queue is deleted when the last consumer unsubscribes.
    * @default false
@@ -183,18 +478,6 @@ type QueueDefinition = {
    *
    * When configured, messages that are rejected, expire, or exceed queue limits
    * will be automatically forwarded to the specified dead letter exchange.
-   *
-   * @example
-   * ```typescript
-   * const dlx = defineExchange('orders-dlx', 'topic', { durable: true });
-   * const queue = defineQueue('order-processing', {
-   *   durable: true,
-   *   deadLetter: {
-   *     exchange: dlx,
-   *     routingKey: 'order.failed'
-   *   }
-   * });
-   * ```
    */
   deadLetter?: DeadLetterConfig;
   /**
@@ -205,22 +488,146 @@ type QueueDefinition = {
    * - `x-expires`: Queue expiration time in milliseconds
    * - `x-max-length`: Maximum number of messages in the queue
    * - `x-max-length-bytes`: Maximum size of the queue in bytes
-   * - `x-max-priority`: Maximum priority level for priority queues
+   */
+  arguments?: Record<string, unknown>;
+};
+/**
+ * Definition of a quorum queue.
+ *
+ * Quorum queues provide better durability and high-availability using the Raft consensus algorithm.
+ * They support native retry handling via `deliveryLimit` and both TTL-backoff and quorum-native retry modes.
+ */
+type QuorumQueueDefinition = BaseQueueDefinition & {
+  /**
+   * Queue type discriminator: quorum queue.
+   */
+  type: "quorum";
+  /**
+   * Quorum queues do not support exclusive mode.
+   * Use type: 'classic' if you need exclusive queues.
+   */
+  exclusive?: never;
+  /**
+   * Quorum queues do not support priority queues.
+   * Use type: 'classic' if you need priority queues.
+   */
+  maxPriority?: never;
+  /**
+   * Maximum number of delivery attempts before the message is dead-lettered.
    *
-   * Note: When using the `deadLetter` property, the `x-dead-letter-exchange` and
-   * `x-dead-letter-routing-key` arguments are automatically set and should not be
-   * specified in this arguments object.
+   * This is a quorum queue-specific feature. When a message is rejected (nacked)
+   * and requeued, RabbitMQ increments the `x-delivery-count` header. When this
+   * count reaches the delivery limit, the message is automatically dead-lettered
+   * (if DLX is configured) or dropped.
    *
-   * @example
-   * ```typescript
-   * {
-   *   'x-message-ttl': 86400000, // 24 hours
-   *   'x-max-priority': 10
-   * }
-   * ```
+   * @minimum 1 - Must be a positive integer (1 or greater)
+   *
+   * @see https://www.rabbitmq.com/docs/quorum-queues#poison-message-handling
    */
-  arguments?: Record<string, unknown>;
+  deliveryLimit?: number;
+  /**
+   * Retry configuration for handling failed message processing.
+   *
+   * Quorum queues support both:
+   * - `ttl-backoff`: Uses wait queues with exponential backoff (default)
+   * - `quorum-native`: Uses RabbitMQ's native delivery limit feature
+   *
+   * When the queue is created, defaults are applied for TTL-backoff options.
+   */
+  retry: ResolvedRetryOptions;
+};
+/**
+ * Definition of a classic queue.
+ *
+ * Classic queues are the traditional RabbitMQ queue type. Use them when you need
+ * specific features not supported by quorum queues (e.g., exclusive queues, priority queues).
+ */
+type ClassicQueueDefinition = BaseQueueDefinition & {
+  /**
+   * Queue type discriminator: classic queue.
+   */
+  type: "classic";
+  /**
+   * Classic queues do not support delivery limits.
+   * Use type: 'quorum' if you need native retry with delivery limits.
+   */
+  deliveryLimit?: never;
+  /**
+   * If true, the queue can only be used by the declaring connection and is deleted when
+   * that connection closes. Exclusive queues are private to the connection.
+   * @default false
+   */
+  exclusive?: boolean;
+  /**
+   * Retry configuration for handling failed message processing.
+   *
+   * Classic queues only support TTL-backoff retry mode (default).
+   * When the queue is created, defaults are applied.
+   */
+  retry: ResolvedTtlBackoffRetryOptions;
+};
+/**
+ * Definition of an AMQP queue.
+ *
+ * A discriminated union based on queue type:
+ * - `QuorumQueueDefinition`: For quorum queues (type: "quorum")
+ * - `ClassicQueueDefinition`: For classic queues (type: "classic")
+ *
+ * Use `queue.type` as the discriminator to narrow the type.
+ */
+type QueueDefinition = QuorumQueueDefinition | ClassicQueueDefinition;
+/**
+ * A queue with automatically generated TTL-backoff retry infrastructure.
+ *
+ * This type is returned by `defineQueue` when TTL-backoff retry is configured
+ * with a dead letter exchange. When passed to `defineContract`, the wait queue
+ * and bindings are automatically added to the contract.
+ *
+ * @example
+ * ```typescript
+ * const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+ * const queue = defineQueue('order-processing', {
+ *   deadLetter: { exchange: dlx },
+ *   retry: { mode: 'ttl-backoff', maxRetries: 5 },
+ * });
+ * // queue is QueueWithTtlBackoffInfrastructure
+ *
+ * const contract = defineContract({
+ *   exchanges: { dlx },
+ *   queues: { orderProcessing: queue }, // Automatically adds wait queue
+ *   // ... bindings are automatically generated
+ * });
+ * ```
+ */
+type QueueWithTtlBackoffInfrastructure = {
+  /**
+   * Discriminator to identify this as a queue with TTL-backoff infrastructure.
+   * @internal
+   */
+  __brand: "QueueWithTtlBackoffInfrastructure";
+  /**
+   * The main queue definition.
+   */
+  queue: QueueDefinition;
+  /**
+   * The wait queue for holding messages during backoff delay.
+   */
+  waitQueue: QueueDefinition;
+  /**
+   * Binding that routes failed messages to the wait queue.
+   */
+  waitQueueBinding: QueueBindingDefinition;
+  /**
+   * Binding that routes retried messages back to the main queue.
+   */
+  mainQueueRetryBinding: QueueBindingDefinition;
 };
+/**
+ * A queue entry that can be passed to `defineContract`.
+ *
+ * Can be either a plain queue definition or a queue with TTL-backoff infrastructure.
+ */
+type QueueEntry = QueueDefinition | QueueWithTtlBackoffInfrastructure;
 /**
  * Definition of a message with typed payload and optional headers.
  *
@@ -432,8 +839,11 @@ type ContractDefinition = {
   /**
    * Named queue definitions.
    * Each key becomes available as a named resource in the contract.
+   *
+   * When a queue has TTL-backoff retry configured, pass the `QueueWithTtlBackoffInfrastructure`
+   * object returned by `defineQueue`. The wait queue and bindings will be automatically added.
    */
-  queues?: Record<string, QueueDefinition>;
+  queues?: Record<string, QueueEntry>;
   /**
    * Named binding definitions.
    * Bindings can be queue-to-exchange or exchange-to-exchange.
@@ -485,7 +895,7 @@ type InferPublisherNames<TContract extends ContractDefinition> = TContract["publ
  */
 type InferConsumerNames<TContract extends ContractDefinition> = TContract["consumers"] extends Record<string, unknown> ? keyof TContract["consumers"] : never;
 //#endregion
-//#region src/builder.d.ts
+//#region src/builder/exchange.d.ts
 /**
  * Define a fanout exchange.
  *
@@ -556,52 +966,8 @@ declare function defineExchange(name: string, type: "direct", options?: Omit<Bas
  * ```
  */
 declare function defineExchange(name: string, type: "topic", options?: Omit<BaseExchangeDefinition, "name" | "type">): TopicExchangeDefinition;
-/**
- * Define an AMQP queue.
- *
- * A queue stores messages until they are consumed by workers. Queues can be bound to exchanges
- * to receive messages based on routing rules.
- *
- * @param name - The name of the queue
- * @param options - Optional queue configuration
- * @param options.durable - If true, the queue survives broker restarts (default: false)
- * @param options.exclusive - If true, the queue can only be used by the declaring connection (default: false)
- * @param options.autoDelete - If true, the queue is deleted when the last consumer unsubscribes (default: false)
- * @param options.deadLetter - Dead letter configuration for handling failed messages
- * @param options.maxPriority - Maximum priority level for priority queue (1-255, recommended: 1-10). Sets x-max-priority argument.
- * @param options.arguments - Additional AMQP arguments (e.g., x-message-ttl)
- * @returns A queue definition
- *
- * @example
- * ```typescript
- * // Basic queue
- * const orderQueue = defineQueue('order-processing', {
- *   durable: true,
- * });
- *
- * // Priority queue with max priority of 10
- * const taskQueue = defineQueue('urgent-tasks', {
- *   durable: true,
- *   maxPriority: 10,
- * });
- *
- * // Queue with dead letter exchange
- * const dlx = defineExchange('orders-dlx', 'topic', { durable: true });
- * const orderQueueWithDLX = defineQueue('order-processing', {
- *   durable: true,
- *   deadLetter: {
- *     exchange: dlx,
- *     routingKey: 'order.failed'
- *   },
- *   arguments: {
- *     'x-message-ttl': 86400000, // 24 hours
- *   }
- * });
- * ```
- */
-declare function defineQueue(name: string, options?: Omit<QueueDefinition, "name"> & {
-  maxPriority?: number;
-}): QueueDefinition;
+//#endregion
+//#region src/builder/message.d.ts
 /**
  * Define a message definition with payload and optional headers/metadata.
  *
@@ -642,13 +1008,95 @@ declare function defineMessage<TPayload extends MessageDefinition["payload"], TH
   summary?: string;
   description?: string;
 }): MessageDefinition<TPayload, THeaders>;
+//#endregion
+//#region src/builder/queue.d.ts
+/**
+ * Extract the plain QueueDefinition from a QueueEntry.
+ * If the entry is a QueueWithTtlBackoffInfrastructure, returns the inner queue.
+ * Otherwise, returns the entry as-is.
+ *
+ * @param entry - The queue entry (either plain QueueDefinition or QueueWithTtlBackoffInfrastructure)
+ * @returns The plain QueueDefinition
+ *
+ * @example
+ * ```typescript
+ * const queue = defineQueue('orders', { retry: { mode: 'ttl-backoff' }, deadLetter: { exchange: dlx } });
+ * const plainQueue = extractQueue(queue); // Returns the inner QueueDefinition
+ * ```
+ */
+declare function extractQueue(entry: QueueEntry): QueueDefinition;
+/**
+ * Define an AMQP queue.
+ *
+ * A queue stores messages until they are consumed by workers. Queues can be bound to exchanges
+ * to receive messages based on routing rules.
+ *
+ * By default, queues are created as quorum queues which provide better durability and
+ * high-availability. Use `type: 'classic'` for special cases like non-durable queues
+ * or priority queues.
+ *
+ * @param name - The name of the queue
+ * @param options - Optional queue configuration
+ * @param options.type - Queue type: 'quorum' (default, recommended) or 'classic'
+ * @param options.durable - If true, the queue survives broker restarts. Quorum queues are always durable.
+ * @param options.exclusive - If true, the queue can only be used by the declaring connection. Only supported with classic queues.
+ * @param options.autoDelete - If true, the queue is deleted when the last consumer unsubscribes (default: false)
+ * @param options.deadLetter - Dead letter configuration for handling failed messages
+ * @param options.maxPriority - Maximum priority level for priority queue (1-255, recommended: 1-10). Only supported with classic queues.
+ * @param options.arguments - Additional AMQP arguments (e.g., x-message-ttl)
+ * @returns A queue definition
+ *
+ * @example
+ * ```typescript
+ * // Quorum queue (default, recommended for production)
+ * const orderQueue = defineQueue('order-processing');
+ *
+ * // Explicit quorum queue with dead letter exchange
+ * const dlx = defineExchange('orders-dlx', 'topic', { durable: true });
+ * const orderQueueWithDLX = defineQueue('order-processing', {
+ *   type: 'quorum',
+ *   deadLetter: {
+ *     exchange: dlx,
+ *     routingKey: 'order.failed'
+ *   },
+ *   arguments: {
+ *     'x-message-ttl': 86400000, // 24 hours
+ *   }
+ * });
+ *
+ * // Classic queue (for special cases)
+ * const tempQueue = defineQueue('temp-queue', {
+ *   type: 'classic',
+ *   durable: false,
+ *   autoDelete: true,
+ * });
+ *
+ * // Priority queue (requires classic type)
+ * const taskQueue = defineQueue('urgent-tasks', {
+ *   type: 'classic',
+ *   durable: true,
+ *   maxPriority: 10,
+ * });
+ *
+ * // Queue with TTL-backoff retry (returns infrastructure automatically)
+ * const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+ * const orderQueue = defineQueue('order-processing', {
+ *   deadLetter: { exchange: dlx },
+ *   retry: { mode: 'ttl-backoff', maxRetries: 5 },
+ * });
+ * // orderQueue is QueueWithTtlBackoffInfrastructure, pass directly to defineContract
+ * ```
+ */
+declare function defineQueue(name: string, options?: DefineQueueOptions): QueueDefinition | QueueWithTtlBackoffInfrastructure;
+//#endregion
+//#region src/builder/binding.d.ts
 /**
  * Define a binding between a queue and a fanout exchange.
  *
  * Binds a queue to a fanout exchange to receive all messages published to the exchange.
  * Fanout exchanges ignore routing keys, so this overload doesn't require one.
  *
- * @param queue - The queue definition to bind
+ * @param queue - The queue definition or queue with infrastructure to bind
  * @param exchange - The fanout exchange definition
  * @param options - Optional binding configuration
  * @param options.arguments - Additional AMQP arguments for the binding
@@ -662,7 +1110,7 @@ declare function defineMessage<TPayload extends MessageDefinition["payload"], TH
  * const binding = defineQueueBinding(logsQueue, logsExchange);
  * ```
  */
-declare function defineQueueBinding(queue: QueueDefinition, exchange: FanoutExchangeDefinition, options?: Omit<Extract<QueueBindingDefinition, {
+declare function defineQueueBinding(queue: QueueEntry, exchange: FanoutExchangeDefinition, options?: Omit<Extract<QueueBindingDefinition, {
   exchange: FanoutExchangeDefinition;
 }>, "type" | "queue" | "exchange" | "routingKey">): Extract<QueueBindingDefinition, {
   exchange: FanoutExchangeDefinition;
@@ -678,7 +1126,7 @@ declare function defineQueueBinding(queue: QueueDefinition, exchange: FanoutExch
  * - `*` matches exactly one word
  * - `#` matches zero or more words
  *
- * @param queue - The queue definition to bind
+ * @param queue - The queue definition or queue with infrastructure to bind
  * @param exchange - The direct or topic exchange definition
  * @param options - Binding configuration (routingKey is required)
  * @param options.routingKey - The routing key pattern for message routing
@@ -701,7 +1149,7 @@ declare function defineQueueBinding(queue: QueueDefinition, exchange: FanoutExch
  * });
  * ```
  */
-declare function defineQueueBinding(queue: QueueDefinition, exchange: DirectExchangeDefinition | TopicExchangeDefinition, options: Omit<Extract<QueueBindingDefinition, {
+declare function defineQueueBinding(queue: QueueEntry, exchange: DirectExchangeDefinition | TopicExchangeDefinition, options: Omit<Extract<QueueBindingDefinition, {
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
 }>, "type" | "queue" | "exchange">): Extract<QueueBindingDefinition, {
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
@@ -761,6 +1209,8 @@ declare function defineExchangeBinding(destination: ExchangeDefinition, source:
 }>, "type" | "source" | "destination">): Extract<ExchangeBindingDefinition, {
   source: DirectExchangeDefinition | TopicExchangeDefinition;
 }>;
+//#endregion
+//#region src/builder/publisher.d.ts
 /**
  * Define a message publisher for a fanout exchange.
  *
@@ -835,6 +1285,8 @@ declare function definePublisher<TMessage extends MessageDefinition>(exchange: D
 }>, "exchange" | "message">): Extract<PublisherDefinition<TMessage>, {
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
 }>;
+//#endregion
+//#region src/builder/consumer.d.ts
 /**
  * Define a message consumer.
  *
@@ -877,7 +1329,9 @@ declare function definePublisher<TMessage extends MessageDefinition>(exchange: D
  * // });
  * ```
  */
-declare function defineConsumer<TMessage extends MessageDefinition>(queue: QueueDefinition, message: TMessage, options?: Omit<ConsumerDefinition<TMessage>, "queue" | "message">): ConsumerDefinition<TMessage>;
+declare function defineConsumer<TMessage extends MessageDefinition>(queue: QueueEntry, message: TMessage, options?: Omit<ConsumerDefinition<TMessage>, "queue" | "message">): ConsumerDefinition<TMessage>;
+//#endregion
+//#region src/builder/contract.d.ts
 /**
  * Define an AMQP contract.
  *
@@ -948,34 +1402,8 @@ declare function defineConsumer<TMessage extends MessageDefinition>(queue: Queue
  * ```
  */
 declare function defineContract<TContract extends ContractDefinition>(definition: TContract): TContract;
-/**
- * Publisher-first builder result for fanout and direct exchanges.
- *
- * This type represents a publisher and provides a method to create
- * a consumer that uses the same message schema with a binding to the exchange.
- *
- * This pattern is suitable for event-oriented messaging where publishers
- * emit events without knowing which queues will consume them.
- *
- * @template TMessage - The message definition
- * @template TPublisher - The publisher definition
- */
-type PublisherFirstResult<TMessage extends MessageDefinition, TPublisher extends PublisherDefinition<TMessage>> = {
-  /** The publisher definition */
-  publisher: TPublisher;
-  /**
-   * Create a consumer that receives messages from this publisher.
-   * The consumer will automatically use the same message schema and
-   * a binding will be created with the same routing key.
-   *
-   * @param queue - The queue that will consume the messages
-   * @returns An object with the consumer definition and binding
-   */
-  createConsumer: (queue: QueueDefinition) => {
-    consumer: ConsumerDefinition<TMessage>;
-    binding: QueueBindingDefinition;
-  };
-};
+//#endregion
+//#region src/builder/routing-types.d.ts
 /**
  * Type-safe routing key that validates basic format.
  *
@@ -1052,6 +1480,36 @@ type MatchesPattern<Key extends string, Pattern extends string> = Pattern extend
  * @template Key - The routing key to validate
  */
 type MatchingRoutingKey<Pattern extends string, Key extends string> = RoutingKey<Key> extends never ? never : BindingPattern<Pattern> extends never ? never : MatchesPattern<Key, Pattern> extends true ? Key : never;
+//#endregion
+//#region src/builder/publisher-first.d.ts
+/**
+ * Publisher-first builder result for fanout and direct exchanges.
+ *
+ * This type represents a publisher and provides a method to create
+ * a consumer that uses the same message schema with a binding to the exchange.
+ *
+ * This pattern is suitable for event-oriented messaging where publishers
+ * emit events without knowing which queues will consume them.
+ *
+ * @template TMessage - The message definition
+ * @template TPublisher - The publisher definition
+ */
+type PublisherFirstResult<TMessage extends MessageDefinition, TPublisher extends PublisherDefinition<TMessage>> = {
+  /** The publisher definition */
+  publisher: TPublisher;
+  /**
+   * Create a consumer that receives messages from this publisher.
+   * The consumer will automatically use the same message schema and
+   * a binding will be created with the same routing key.
+   *
+   * @param queue - The queue (or queue with infrastructure) that will consume the messages
+   * @returns An object with the consumer definition and binding
+   */
+  createConsumer: (queue: QueueEntry) => {
+    consumer: ConsumerDefinition<TMessage>;
+    binding: QueueBindingDefinition;
+  };
+};
 /**
  * Publisher-first builder result for topic exchanges.
  *
@@ -1069,11 +1527,11 @@ type PublisherFirstResultWithRoutingKey<TMessage extends MessageDefinition, TPub
    * Create a consumer that receives messages from this publisher.
    * For topic exchanges, the routing key pattern can be specified for the binding.
    *
-   * @param queue - The queue that will consume the messages
+   * @param queue - The queue (or queue with infrastructure) that will consume the messages
    * @param routingKey - Optional routing key pattern for the binding (defaults to publisher's routing key)
    * @returns An object with the consumer definition and binding
    */
-  createConsumer: <TConsumerRoutingKey extends string = TRoutingKey>(queue: QueueDefinition, routingKey?: BindingPattern<TConsumerRoutingKey>) => {
+  createConsumer: <TConsumerRoutingKey extends string = TRoutingKey>(queue: QueueEntry, routingKey?: BindingPattern<TConsumerRoutingKey>) => {
     consumer: ConsumerDefinition<TMessage>;
     binding: QueueBindingDefinition;
   };
@@ -1257,6 +1715,8 @@ declare function definePublisherFirst<TMessage extends MessageDefinition, TRouti
 }): PublisherFirstResultWithRoutingKey<TMessage, Extract<PublisherDefinition<TMessage>, {
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
 }>, TRoutingKey>;
+//#endregion
+//#region src/builder/consumer-first.d.ts
 /**
  * Consumer-first builder result for fanout and direct exchanges.
  *
@@ -1357,7 +1817,7 @@ type ConsumerFirstResultWithRoutingKey<TMessage extends MessageDefinition, TCons
  * });
  * ```
  */
-declare function defineConsumerFirst<TMessage extends MessageDefinition>(queue: QueueDefinition, exchange: FanoutExchangeDefinition, message: TMessage, options?: Omit<Extract<QueueBindingDefinition, {
+declare function defineConsumerFirst<TMessage extends MessageDefinition>(queue: QueueEntry, exchange: FanoutExchangeDefinition, message: TMessage, options?: Omit<Extract<QueueBindingDefinition, {
   exchange: FanoutExchangeDefinition;
 }>, "type" | "queue" | "exchange" | "routingKey">): ConsumerFirstResult<TMessage, ConsumerDefinition<TMessage>, Extract<QueueBindingDefinition, {
   exchange: FanoutExchangeDefinition;
@@ -1411,7 +1871,7 @@ declare function defineConsumerFirst<TMessage extends MessageDefinition>(queue:
  * });
  * ```
  */
-declare function defineConsumerFirst<TMessage extends MessageDefinition, TRoutingKey extends string>(queue: QueueDefinition, exchange: DirectExchangeDefinition, message: TMessage, options: {
+declare function defineConsumerFirst<TMessage extends MessageDefinition, TRoutingKey extends string>(queue: QueueEntry, exchange: DirectExchangeDefinition, message: TMessage, options: {
   routingKey: RoutingKey<TRoutingKey>;
   arguments?: Record<string, unknown>;
 }): ConsumerFirstResult<TMessage, ConsumerDefinition<TMessage>, Extract<QueueBindingDefinition, {
@@ -1469,12 +1929,87 @@ declare function defineConsumerFirst<TMessage extends MessageDefinition, TRoutin
  * });
  * ```
  */
-declare function defineConsumerFirst<TMessage extends MessageDefinition, TRoutingKey extends string>(queue: QueueDefinition, exchange: TopicExchangeDefinition, message: TMessage, options: {
+declare function defineConsumerFirst<TMessage extends MessageDefinition, TRoutingKey extends string>(queue: QueueEntry, exchange: TopicExchangeDefinition, message: TMessage, options: {
   routingKey: BindingPattern<TRoutingKey>;
   arguments?: Record<string, unknown>;
 }): ConsumerFirstResultWithRoutingKey<TMessage, ConsumerDefinition<TMessage>, Extract<QueueBindingDefinition, {
   exchange: TopicExchangeDefinition;
 }>>;
 //#endregion
-export { type AnySchema, type BaseExchangeDefinition, type BindingDefinition, type BindingPattern, type CompressionAlgorithm, type ConsumerDefinition, type ConsumerFirstResult, type ConsumerFirstResultWithRoutingKey, type ContractDefinition, type DeadLetterConfig, type DirectExchangeDefinition, type ExchangeBindingDefinition, type ExchangeDefinition, type FanoutExchangeDefinition, type InferConsumerNames, type InferPublisherNames, type MatchingRoutingKey, type MessageDefinition, type PublisherDefinition, type PublisherFirstResult, type PublisherFirstResultWithRoutingKey, type QueueBindingDefinition, type QueueDefinition, type RoutingKey, type TopicExchangeDefinition, defineConsumer, defineConsumerFirst, defineContract, defineExchange, defineExchangeBinding, defineMessage, definePublisher, definePublisherFirst, defineQueue, defineQueueBinding };
+//#region src/builder/ttl-backoff.d.ts
+/**
+ * Result type for TTL-backoff retry infrastructure builder.
+ *
+ * Contains the wait queue and bindings needed for TTL-backoff retry.
+ */
+type TtlBackoffRetryInfrastructure = {
+  /**
+   * The wait queue for holding messages during backoff delay.
+   * This is a classic queue with a dead letter exchange pointing back to the main queue.
+   */
+  waitQueue: QueueDefinition;
+  /**
+   * Binding that routes failed messages to the wait queue.
+   */
+  waitQueueBinding: QueueBindingDefinition;
+  /**
+   * Binding that routes retried messages back to the main queue.
+   */
+  mainQueueRetryBinding: QueueBindingDefinition;
+};
+/**
+ * Create TTL-backoff retry infrastructure for a queue.
+ *
+ * This builder helper generates the wait queue and bindings needed for TTL-backoff retry.
+ * The generated infrastructure can be spread into a contract definition.
+ *
+ * TTL-backoff retry works by:
+ * 1. Failed messages are sent to the DLX with routing key `{queueName}-wait`
+ * 2. The wait queue receives these messages and holds them for a TTL period
+ * 3. After TTL expires, messages are dead-lettered back to the DLX with routing key `{queueName}`
+ * 4. The main queue receives the retried message via its binding to the DLX
+ *
+ * @param queue - The main queue definition (must have deadLetter configured)
+ * @param options - Optional configuration for the wait queue
+ * @param options.waitQueueDurable - Whether the wait queue should be durable (default: same as main queue)
+ * @returns TTL-backoff retry infrastructure containing wait queue and bindings
+ * @throws {Error} If the queue does not have a dead letter exchange configured
+ *
+ * @example
+ * ```typescript
+ * const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+ * const orderQueue = defineQueue('order-processing', {
+ *   type: 'quorum',
+ *   deadLetter: { exchange: dlx },
+ *   retry: {
+ *     mode: 'ttl-backoff',
+ *     maxRetries: 5,
+ *     initialDelayMs: 1000,
+ *   },
+ * });
+ *
+ * // Generate TTL-backoff infrastructure
+ * const retryInfra = defineTtlBackoffRetryInfrastructure(orderQueue);
+ *
+ * // Spread into contract
+ * const contract = defineContract({
+ *   exchanges: { dlx },
+ *   queues: {
+ *     orderProcessing: orderQueue,
+ *     orderProcessingWait: retryInfra.waitQueue,
+ *   },
+ *   bindings: {
+ *     ...// your other bindings
+ *     orderWaitBinding: retryInfra.waitQueueBinding,
+ *     orderRetryBinding: retryInfra.mainQueueRetryBinding,
+ *   },
+ *   // ... publishers and consumers
+ * });
+ * ```
+ */
+declare function defineTtlBackoffRetryInfrastructure(queueEntry: QueueEntry, options?: {
+  waitQueueDurable?: boolean;
+}): TtlBackoffRetryInfrastructure;
+//#endregion
+export { type AnySchema, type BaseExchangeDefinition, type BindingDefinition, type BindingPattern, type ClassicQueueDefinition, type ClassicQueueOptions, type CompressionAlgorithm, type ConsumerDefinition, type ConsumerFirstResult, type ConsumerFirstResultWithRoutingKey, type ContractDefinition, type DeadLetterConfig, type DefineQueueOptions, type DirectExchangeDefinition, type ExchangeBindingDefinition, type ExchangeDefinition, type FanoutExchangeDefinition, type InferConsumerNames, type InferPublisherNames, type MatchingRoutingKey, type MessageDefinition, type PublisherDefinition, type PublisherFirstResult, type PublisherFirstResultWithRoutingKey, type QueueBindingDefinition, type QueueDefinition, type QueueEntry, type QueueType, type QueueWithTtlBackoffInfrastructure, type QuorumNativeRetryOptions, type QuorumQueueDefinition, type QuorumQueueOptions, type ResolvedRetryOptions, type ResolvedTtlBackoffRetryOptions, type RoutingKey, type TopicExchangeDefinition, type TtlBackoffRetryInfrastructure, type TtlBackoffRetryOptions, defineConsumer, defineConsumerFirst, defineContract, defineExchange, defineExchangeBinding, defineMessage, definePublisher, definePublisherFirst, defineQueue, defineQueueBinding, defineTtlBackoffRetryInfrastructure, extractQueue };
 //# sourceMappingURL=index.d.cts.map