@amqp-contract/contract 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -12,6 +12,66 @@ 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";
+};
 /**
  * Supported compression algorithms for message payloads.
  *
@@ -41,6 +101,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 +431,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 +454,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 +464,143 @@ 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
+   * - `quorum-native`: Uses RabbitMQ's native delivery limit feature
+   */
+  retry?: TtlBackoffRetryOptions | QuorumNativeRetryOptions;
+};
+/**
+ * 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.
+   */
+  retry?: TtlBackoffRetryOptions;
+};
+/**
+ * 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 +812,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.
@@ -562,33 +945,30 @@ declare function defineExchange(name: string, type: "topic", options?: Omit<Base
  * 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.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.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). Sets x-max-priority argument.
+ * @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
- * // Basic queue
- * const orderQueue = defineQueue('order-processing', {
- *   durable: true,
- * });
+ * // Quorum queue (default, recommended for production)
+ * const orderQueue = defineQueue('order-processing');
  *
- * // Priority queue with max priority of 10
- * const taskQueue = defineQueue('urgent-tasks', {
- *   durable: true,
- *   maxPriority: 10,
- * });
- *
- * // Queue with dead letter exchange
+ * // Explicit quorum queue with dead letter exchange
  * const dlx = defineExchange('orders-dlx', 'topic', { durable: true });
  * const orderQueueWithDLX = defineQueue('order-processing', {
- *   durable: true,
+ *   type: 'quorum',
  *   deadLetter: {
  *     exchange: dlx,
  *     routingKey: 'order.failed'
@@ -597,11 +977,31 @@ declare function defineExchange(name: string, type: "topic", options?: Omit<Base
  *     '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?: Omit<QueueDefinition, "name"> & {
-  maxPriority?: number;
-}): QueueDefinition;
+declare function defineQueue(name: string, options?: DefineQueueOptions): QueueDefinition | QueueWithTtlBackoffInfrastructure;
 /**
  * Define a message definition with payload and optional headers/metadata.
  *
@@ -648,7 +1048,7 @@ declare function defineMessage<TPayload extends MessageDefinition["payload"], TH
  * 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 +1062,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 +1078,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 +1101,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;
@@ -877,7 +1277,7 @@ 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>;
 /**
  * Define an AMQP contract.
  *
@@ -948,6 +1348,21 @@ declare function defineConsumer<TMessage extends MessageDefinition>(queue: Queue
  * ```
  */
 declare function defineContract<TContract extends ContractDefinition>(definition: TContract): TContract;
+/**
+ * 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;
 /**
  * Publisher-first builder result for fanout and direct exchanges.
  *
@@ -968,10 +1383,10 @@ type PublisherFirstResult<TMessage extends MessageDefinition, TPublisher extends
    * 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
+   * @param queue - The queue (or queue with infrastructure) that will consume the messages
    * @returns An object with the consumer definition and binding
    */
-  createConsumer: (queue: QueueDefinition) => {
+  createConsumer: (queue: QueueEntry) => {
     consumer: ConsumerDefinition<TMessage>;
     binding: QueueBindingDefinition;
   };
@@ -1069,11 +1484,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;
   };
@@ -1357,7 +1772,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 +1826,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 +1884,85 @@ 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;
 }>>;
+/**
+ * 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 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 };
+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 RoutingKey, type TopicExchangeDefinition, type TtlBackoffRetryInfrastructure, type TtlBackoffRetryOptions, defineConsumer, defineConsumerFirst, defineContract, defineExchange, defineExchangeBinding, defineMessage, definePublisher, definePublisherFirst, defineQueue, defineQueueBinding, defineTtlBackoffRetryInfrastructure, extractQueue };
 //# sourceMappingURL=index.d.mts.map