@amqp-contract/contract 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -26,33 +26,30 @@ function defineExchange(name, type, options) {
 * 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,
-* });
-*
-* // Priority queue with max priority of 10
-* const taskQueue = defineQueue('urgent-tasks', {
-*   durable: true,
-*   maxPriority: 10,
-* });
+* // Quorum queue (default, recommended for production)
+* const orderQueue = defineQueue('order-processing');
 *
-* // 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'
@@ -61,24 +58,92 @@ function defineExchange(name, type, options) {
 *     '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 { 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
-			}
+	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 queueDefinition$1 = {
+			...baseProps,
+			type: "quorum"
+		};
+		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 (quorumOpts.retry !== void 0) queueDefinition$1.retry = quorumOpts.retry;
+		if (quorumOpts.retry?.mode === "ttl-backoff" && queueDefinition$1.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition$1);
+		return queueDefinition$1;
+	}
+	const classicOpts = opts;
+	const queueDefinition = {
+		...baseProps,
+		type: "classic"
+	};
+	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 (classicOpts.retry !== void 0) queueDefinition.retry = classicOpts.retry;
+	if (classicOpts.retry?.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
+	return queueDefinition;
+}
+/**
+* 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
+		}
+	};
 	return {
-		name,
-		...queueOptions
+		__brand: "QueueWithTtlBackoffInfrastructure",
+		queue,
+		waitQueue,
+		waitQueueBinding: callDefineQueueBinding(waitQueue, dlx, { routingKey: waitQueueName }),
+		mainQueueRetryBinding: callDefineQueueBinding(queue, dlx, { routingKey: queue.name })
 	};
 }
 /**
@@ -127,22 +192,23 @@ function defineMessage(payload, options) {
 *
 * 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 = extractQueue(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 }
@@ -240,7 +306,7 @@ function definePublisher(exchange, message, options) {
 */
 function defineConsumer(queue, message, options) {
 	return {
-		queue,
+		queue: extractQueue(queue),
 		message,
 		...options
 	};
@@ -315,7 +381,56 @@ function defineConsumer(queue, message, options) {
 * ```
 */
 function defineContract(definition) {
-	return definition;
+	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
+	};
+}
+/**
+* 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;
 }
 /**
 * Helper to call definePublisher with proper type handling.
@@ -398,6 +513,75 @@ function defineConsumerFirst(queue, exchange, message, options) {
 		createPublisher
 	};
 }
+/**
+* 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: callDefineQueueBinding(waitQueue, dlx, { routingKey: waitQueueName }),
+		mainQueueRetryBinding: callDefineQueueBinding(queue, dlx, { routingKey: queue.name })
+	};
+}
 
 //#endregion
 exports.defineConsumer = defineConsumer;
@@ -409,4 +593,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;