@amqp-contract/contract 0.10.0 → 0.12.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 
-//#region src/builder.ts
+//#region src/builder/exchange.ts
 /**
 * Define an AMQP exchange.
 *
@@ -20,67 +20,9 @@ function defineExchange(name, type, options) {
 		...options
 	};
 }
-/**
-* 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
-*   }
-* });
-* ```
-*/
-function defineQueue(name, options) {
-	const { maxPriority, ...queueOptions } = options ?? {};
-	if (maxPriority !== void 0) {
-		if (maxPriority < 1 || maxPriority > 255) throw new Error(`Invalid maxPriority: ${maxPriority}. Must be between 1 and 255. Recommended range: 1-10.`);
-		return {
-			name,
-			...queueOptions,
-			arguments: {
-				...queueOptions.arguments,
-				"x-max-priority": maxPriority
-			}
-		};
-	}
-	return {
-		name,
-		...queueOptions
-	};
-}
+
+//#endregion
+//#region src/builder/message.ts
 /**
 * Define a message definition with payload and optional headers/metadata.
 *
@@ -122,33 +64,63 @@ function defineMessage(payload, options) {
 		...options
 	};
 }
+
+//#endregion
+//#region src/builder/binding.ts
+/**
+* Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
+* Duplicated here to avoid circular dependency with queue.ts.
+* @internal
+*/
+function isQueueWithTtlBackoffInfrastructure$1(entry) {
+	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
+}
+/**
+* Extract the plain QueueDefinition from a QueueEntry.
+* Duplicated here to avoid circular dependency with queue.ts.
+* @internal
+*/
+function extractQueueInternal(entry) {
+	if (isQueueWithTtlBackoffInfrastructure$1(entry)) return entry.queue;
+	return entry;
+}
 /**
 * Define a binding between a queue and an exchange.
 *
 * This is the implementation function - use the type-specific overloads for better type safety.
 *
-* @param queue - The queue definition to bind
+* @param queue - The queue definition or queue with infrastructure to bind
 * @param exchange - The exchange definition
 * @param options - Optional binding configuration
 * @returns A queue binding definition
 * @internal
 */
 function defineQueueBinding(queue, exchange, options) {
+	const queueDef = extractQueueInternal(queue);
 	if (exchange.type === "fanout") return {
 		type: "queue",
-		queue,
+		queue: queueDef,
 		exchange,
 		...options?.arguments && { arguments: options.arguments }
 	};
 	return {
 		type: "queue",
-		queue,
+		queue: queueDef,
 		exchange,
 		routingKey: options?.routingKey,
 		...options?.arguments && { arguments: options.arguments }
 	};
 }
 /**
+* Internal helper to call defineQueueBinding with proper type handling.
+* Used by queue.ts to avoid circular dependency.
+* @internal
+*/
+function defineQueueBindingInternal(queue, exchange, options) {
+	if (exchange.type === "fanout") return defineQueueBinding(queue, exchange, options);
+	return defineQueueBinding(queue, exchange, options);
+}
+/**
 * Define a binding between two exchanges (exchange-to-exchange routing).
 *
 * This is the implementation function - use the type-specific overloads for better type safety.
@@ -174,6 +146,185 @@ function defineExchangeBinding(destination, source, options) {
 		...options?.arguments && { arguments: options.arguments }
 	};
 }
+
+//#endregion
+//#region src/builder/queue.ts
+/**
+* Resolve TTL-backoff retry options with defaults applied.
+* @internal
+*/
+function resolveTtlBackoffOptions(options) {
+	return {
+		mode: "ttl-backoff",
+		maxRetries: options?.maxRetries ?? 3,
+		initialDelayMs: options?.initialDelayMs ?? 1e3,
+		maxDelayMs: options?.maxDelayMs ?? 3e4,
+		backoffMultiplier: options?.backoffMultiplier ?? 2,
+		jitter: options?.jitter ?? true
+	};
+}
+/**
+* Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
+* @internal
+*/
+function isQueueWithTtlBackoffInfrastructure(entry) {
+	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
+}
+/**
+* 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
+* ```
+*/
+function extractQueue(entry) {
+	if (isQueueWithTtlBackoffInfrastructure(entry)) return entry.queue;
+	return entry;
+}
+/**
+* Wrap a queue definition with TTL-backoff retry infrastructure.
+* @internal
+*/
+function wrapWithTtlBackoffInfrastructure(queue) {
+	if (!queue.deadLetter) throw new Error(`Queue "${queue.name}" does not have a dead letter exchange configured. TTL-backoff retry requires deadLetter to be set on the queue.`);
+	const dlx = queue.deadLetter.exchange;
+	const waitQueueName = `${queue.name}-wait`;
+	const waitQueue = {
+		name: waitQueueName,
+		type: "quorum",
+		durable: queue.durable ?? true,
+		deadLetter: {
+			exchange: dlx,
+			routingKey: queue.name
+		},
+		retry: resolveTtlBackoffOptions(void 0)
+	};
+	return {
+		__brand: "QueueWithTtlBackoffInfrastructure",
+		queue,
+		waitQueue,
+		waitQueueBinding: defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName }),
+		mainQueueRetryBinding: defineQueueBindingInternal(queue, dlx, { routingKey: queue.name })
+	};
+}
+/**
+* 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
+* ```
+*/
+function defineQueue(name, options) {
+	const opts = options ?? {};
+	const type = opts.type ?? "quorum";
+	const baseProps = { name };
+	if (opts.durable !== void 0) baseProps.durable = opts.durable;
+	if (opts.autoDelete !== void 0) baseProps.autoDelete = opts.autoDelete;
+	if (opts.deadLetter !== void 0) baseProps.deadLetter = opts.deadLetter;
+	if (opts.arguments !== void 0) baseProps.arguments = opts.arguments;
+	if (type === "quorum") {
+		const quorumOpts = opts;
+		const inputRetry = quorumOpts.retry ?? { mode: "ttl-backoff" };
+		if (inputRetry.mode === "quorum-native") {
+			if (quorumOpts.deliveryLimit === void 0) throw new Error(`Queue "${name}" uses quorum-native retry mode but deliveryLimit is not configured. Quorum-native retry requires deliveryLimit to be set.`);
+		}
+		const retry$1 = inputRetry.mode === "quorum-native" ? inputRetry : resolveTtlBackoffOptions(inputRetry);
+		const queueDefinition$1 = {
+			...baseProps,
+			type: "quorum",
+			retry: retry$1
+		};
+		if (quorumOpts.deliveryLimit !== void 0) {
+			if (quorumOpts.deliveryLimit < 1 || !Number.isInteger(quorumOpts.deliveryLimit)) throw new Error(`Invalid deliveryLimit: ${quorumOpts.deliveryLimit}. Must be a positive integer.`);
+			queueDefinition$1.deliveryLimit = quorumOpts.deliveryLimit;
+		}
+		if (retry$1.mode === "ttl-backoff" && queueDefinition$1.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition$1);
+		return queueDefinition$1;
+	}
+	const classicOpts = opts;
+	if (classicOpts.retry?.mode === "quorum-native") throw new Error(`Queue "${name}" uses quorum-native retry mode but is a classic queue. Quorum-native retry requires quorum queues (type: "quorum").`);
+	const retry = resolveTtlBackoffOptions(classicOpts.retry);
+	const queueDefinition = {
+		...baseProps,
+		type: "classic",
+		retry
+	};
+	if (classicOpts.exclusive !== void 0) queueDefinition.exclusive = classicOpts.exclusive;
+	if (classicOpts.maxPriority !== void 0) {
+		if (classicOpts.maxPriority < 1 || classicOpts.maxPriority > 255) throw new Error(`Invalid maxPriority: ${classicOpts.maxPriority}. Must be between 1 and 255. Recommended range: 1-10.`);
+		queueDefinition.arguments = {
+			...queueDefinition.arguments,
+			"x-max-priority": classicOpts.maxPriority
+		};
+	}
+	if (retry.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
+	return queueDefinition;
+}
+
+//#endregion
+//#region src/builder/publisher.ts
 /**
 * Define a message publisher.
 *
@@ -197,6 +348,18 @@ function definePublisher(exchange, message, options) {
 	};
 }
 /**
+* Helper to call definePublisher with proper type handling.
+* Type safety is enforced by overloaded public function signatures.
+* @internal
+*/
+function definePublisherInternal(exchange, message, options) {
+	if (exchange.type === "fanout") return definePublisher(exchange, message, options);
+	return definePublisher(exchange, message, options);
+}
+
+//#endregion
+//#region src/builder/consumer.ts
+/**
 * Define a message consumer.
 *
 * A consumer receives and processes messages from a queue. The message schema is validated
@@ -240,11 +403,14 @@ function definePublisher(exchange, message, options) {
 */
 function defineConsumer(queue, message, options) {
 	return {
-		queue,
+		queue: extractQueue(queue),
 		message,
 		...options
 	};
 }
+
+//#endregion
+//#region src/builder/contract.ts
 /**
 * Define an AMQP contract.
 *
@@ -315,35 +481,44 @@ function defineConsumer(queue, message, options) {
 * ```
 */
 function defineContract(definition) {
-	return definition;
-}
-/**
-* Helper to call definePublisher with proper type handling.
-* Type safety is enforced by overloaded public function signatures.
-* @internal
-*/
-function callDefinePublisher(exchange, message, options) {
-	if (exchange.type === "fanout") return definePublisher(exchange, message, options);
-	return definePublisher(exchange, message, options);
-}
-/**
-* Helper to call defineQueueBinding with proper type handling.
-* Type safety is enforced by overloaded public function signatures.
-* @internal
-*/
-function callDefineQueueBinding(queue, exchange, options) {
-	if (exchange.type === "fanout") return defineQueueBinding(queue, exchange, options);
-	return defineQueueBinding(queue, exchange, options);
+	if (!definition.queues || Object.keys(definition.queues).length === 0) return definition;
+	const queues = definition.queues;
+	const expandedQueues = {};
+	const autoBindings = {};
+	for (const [name, entry] of Object.entries(queues)) if (isQueueWithTtlBackoffInfrastructure(entry)) {
+		expandedQueues[name] = entry.queue;
+		expandedQueues[`${name}Wait`] = entry.waitQueue;
+		autoBindings[`${name}WaitBinding`] = entry.waitQueueBinding;
+		autoBindings[`${name}RetryBinding`] = entry.mainQueueRetryBinding;
+	} else expandedQueues[name] = entry;
+	if (Object.keys(autoBindings).length > 0) {
+		const mergedBindings = {
+			...definition.bindings,
+			...autoBindings
+		};
+		return {
+			...definition,
+			queues: expandedQueues,
+			bindings: mergedBindings
+		};
+	}
+	return {
+		...definition,
+		queues: expandedQueues
+	};
 }
+
+//#endregion
+//#region src/builder/publisher-first.ts
 /**
 * Implementation of definePublisherFirst.
 * @internal
 */
 function definePublisherFirst(exchange, message, options) {
-	const publisher = callDefinePublisher(exchange, message, options);
+	const publisher = definePublisherInternal(exchange, message, options);
 	if (exchange.type === "topic") {
 		const createConsumer$1 = (queue, routingKey) => {
-			const binding = callDefineQueueBinding(queue, exchange, routingKey ? {
+			const binding = defineQueueBindingInternal(queue, exchange, routingKey ? {
 				...options,
 				routingKey
 			} : options);
@@ -358,7 +533,7 @@ function definePublisherFirst(exchange, message, options) {
 		};
 	}
 	const createConsumer = (queue) => {
-		const binding = callDefineQueueBinding(queue, exchange, options);
+		const binding = defineQueueBindingInternal(queue, exchange, options);
 		return {
 			consumer: defineConsumer(queue, message),
 			binding
@@ -369,16 +544,19 @@ function definePublisherFirst(exchange, message, options) {
 		createConsumer
 	};
 }
+
+//#endregion
+//#region src/builder/consumer-first.ts
 /**
 * Implementation of defineConsumerFirst.
 * @internal
 */
 function defineConsumerFirst(queue, exchange, message, options) {
 	const consumer = defineConsumer(queue, message);
-	const binding = callDefineQueueBinding(queue, exchange, options);
+	const binding = defineQueueBindingInternal(queue, exchange, options);
 	if (exchange.type === "topic") {
 		const createPublisher$1 = (routingKey) => {
-			return callDefinePublisher(exchange, message, {
+			return definePublisherInternal(exchange, message, {
 				...options,
 				routingKey
 			});
@@ -390,7 +568,7 @@ function defineConsumerFirst(queue, exchange, message, options) {
 		};
 	}
 	const createPublisher = () => {
-		return callDefinePublisher(exchange, message, options);
+		return definePublisherInternal(exchange, message, options);
 	};
 	return {
 		consumer,
@@ -399,6 +577,78 @@ function defineConsumerFirst(queue, exchange, message, options) {
 	};
 }
 
+//#endregion
+//#region src/builder/ttl-backoff.ts
+/**
+* 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
+* });
+* ```
+*/
+function defineTtlBackoffRetryInfrastructure(queueEntry, options) {
+	const queue = extractQueue(queueEntry);
+	if (!queue.deadLetter) throw new Error(`Queue "${queue.name}" does not have a dead letter exchange configured. TTL-backoff retry requires deadLetter to be set on the queue.`);
+	const dlx = queue.deadLetter.exchange;
+	const waitQueueName = `${queue.name}-wait`;
+	const waitQueue = defineQueue(waitQueueName, {
+		type: "quorum",
+		durable: options?.waitQueueDurable ?? queue.durable ?? true,
+		deadLetter: {
+			exchange: dlx,
+			routingKey: queue.name
+		}
+	});
+	return {
+		waitQueue,
+		waitQueueBinding: defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName }),
+		mainQueueRetryBinding: defineQueueBindingInternal(queue, dlx, { routingKey: queue.name })
+	};
+}
+
 //#endregion
 exports.defineConsumer = defineConsumer;
 exports.defineConsumerFirst = defineConsumerFirst;
@@ -409,4 +659,6 @@ exports.defineMessage = defineMessage;
 exports.definePublisher = definePublisher;
 exports.definePublisherFirst = definePublisherFirst;
 exports.defineQueue = defineQueue;
-exports.defineQueueBinding = defineQueueBinding;
+exports.defineQueueBinding = defineQueueBinding;
+exports.defineTtlBackoffRetryInfrastructure = defineTtlBackoffRetryInfrastructure;
+exports.extractQueue = extractQueue;