@amqp-contract/contract 0.13.0 → 0.15.0

package/README.md

@@ -36,7 +36,6 @@ import {
   defineContract,
   defineExchange,
   defineQueue,
-  definePublisher,
   defineMessage,
 } from "@amqp-contract/contract";
 import { z } from "zod";
@@ -57,26 +56,23 @@ const orderCreatedEvent = defineEventPublisher(ordersExchange, orderMessage, {
 
 // Multiple queues can consume the same event
 const orderQueue = defineQueue("order-processing", { durable: true });
-const { consumer, binding } = defineEventConsumer(orderCreatedEvent, orderQueue);
-
-// For topic exchanges, consumers can override with their own pattern
 const analyticsQueue = defineQueue("analytics", { durable: true });
-const { consumer: analyticsConsumer, binding: analyticsBinding } = defineEventConsumer(
-  orderCreatedEvent,
-  analyticsQueue,
-  { routingKey: "order.*" }, // Subscribe to all order events
-);
 
+// Compose contract - configs go directly, bindings auto-generated
 const contract = defineContract({
   exchanges: { orders: ordersExchange },
   queues: { orderQueue, analyticsQueue },
-  bindings: { orderBinding: binding, analyticsBinding },
   publishers: {
-    orderCreated: definePublisher(ordersExchange, orderMessage, { routingKey: "order.created" }),
+    // EventPublisherConfig → auto-extracted to publisher
+    orderCreated: orderCreatedEvent,
   },
   consumers: {
-    processOrder: consumer,
-    trackOrders: analyticsConsumer,
+    // EventConsumerResult → auto-extracted to consumer + binding
+    processOrder: defineEventConsumer(orderCreatedEvent, orderQueue),
+    // For topic exchanges, consumers can override with their own pattern
+    trackOrders: defineEventConsumer(orderCreatedEvent, analyticsQueue, {
+      routingKey: "order.*", // Subscribe to all order events
+    }),
   },
 });
 ```

package/dist/index.cjs

@@ -1,3 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region src/builder/exchange.ts
 /**
@@ -269,76 +270,17 @@ function wrapWithTtlBackoffInfrastructure(queue) {
 		},
 		retry: resolveTtlBackoffOptions(void 0)
 	};
+	const waitQueueBinding = defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName });
+	const mainQueueRetryBinding = defineQueueBindingInternal(queue, dlx, { routingKey: queue.name });
 	return {
 		__brand: "QueueWithTtlBackoffInfrastructure",
 		queue,
+		deadLetter: queue.deadLetter,
 		waitQueue,
-		waitQueueBinding: defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName }),
-		mainQueueRetryBinding: defineQueueBindingInternal(queue, dlx, { routingKey: queue.name })
+		waitQueueBinding,
+		mainQueueRetryBinding
 	};
 }
-/**
-* 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";
@@ -353,18 +295,18 @@ function defineQueue(name, options) {
 		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 = {
+		const retry = inputRetry.mode === "quorum-native" ? inputRetry : resolveTtlBackoffOptions(inputRetry);
+		const queueDefinition = {
 			...baseProps,
 			type: "quorum",
-			retry: retry$1
+			retry
 		};
 		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;
+			queueDefinition.deliveryLimit = quorumOpts.deliveryLimit;
 		}
-		if (retry$1.mode === "ttl-backoff" && queueDefinition$1.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition$1);
-		return queueDefinition$1;
+		if (retry.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
+		return queueDefinition;
 	}
 	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").`);
@@ -411,10 +353,10 @@ function defineQueue(name, options) {
 *   deliveryLimit: 3, // Retry up to 3 times
 * });
 *
+* // Use in a contract — exchanges, queues, and bindings are auto-extracted
 * const contract = defineContract({
-*   exchanges: { dlx },
-*   queues: { orderProcessing: orderQueue },
-*   // ...
+*   publishers: { ... },
+*   consumers: { processOrder: defineEventConsumer(event, orderQueue) },
 * });
 * ```
 *
@@ -469,10 +411,10 @@ function defineQuorumQueue(name, options) {
 *   maxDelayMs: 30000,     // Cap at 30s
 * });
 *
+* // Use in a contract — wait queue, bindings, and DLX are auto-extracted
 * const contract = defineContract({
-*   exchanges: { dlx },
-*   queues: { orderProcessing: orderQueue }, // Wait queue auto-added
-*   // ... bindings auto-generated
+*   publishers: { ... },
+*   consumers: { processOrder: defineEventConsumer(event, extractQueue(orderQueue)) },
 * });
 *
 * // To access the underlying queue definition (e.g., for the queue name):
@@ -543,6 +485,52 @@ function definePublisherInternal(exchange, message, options) {
 //#endregion
 //#region src/builder/consumer.ts
 /**
+* Type guard to check if an entry is an EventConsumerResult.
+*/
+function isEventConsumerResultEntry(entry) {
+	return "__brand" in entry && entry.__brand === "EventConsumerResult";
+}
+/**
+* Type guard to check if an entry is a CommandConsumerConfig.
+*/
+function isCommandConsumerConfigEntry(entry) {
+	return "__brand" in entry && entry.__brand === "CommandConsumerConfig";
+}
+/**
+* Extract the ConsumerDefinition from any ConsumerEntry type.
+*
+* Handles the following entry types:
+* - ConsumerDefinition: returned as-is
+* - EventConsumerResult: returns the nested `.consumer` property
+* - CommandConsumerConfig: returns the nested `.consumer` property
+*
+* Use this function when you need to access the underlying ConsumerDefinition
+* from a consumer entry that may have been created with defineEventConsumer
+* or defineCommandConsumer.
+*
+* @param entry - The consumer entry to extract from
+* @returns The underlying ConsumerDefinition
+*
+* @example
+* ```typescript
+* // Works with plain ConsumerDefinition
+* const consumer1 = defineConsumer(queue, message);
+* extractConsumer(consumer1).queue.name; // "my-queue"
+*
+* // Works with EventConsumerResult
+* const consumer2 = defineEventConsumer(eventPublisher, queue);
+* extractConsumer(consumer2).queue.name; // "my-queue"
+*
+* // Works with CommandConsumerConfig
+* const consumer3 = defineCommandConsumer(queue, exchange, message, { routingKey: "cmd" });
+* extractConsumer(consumer3).queue.name; // "my-queue"
+* ```
+*/
+function extractConsumer(entry) {
+	if (isEventConsumerResultEntry(entry) || isCommandConsumerConfigEntry(entry)) return entry.consumer;
+	return entry;
+}
+/**
 * Define a message consumer.
 *
 * A consumer receives and processes messages from a queue. The message schema is validated
@@ -636,10 +624,14 @@ function defineEventConsumer(eventPublisher, queue, options) {
 	const bindingArguments = options?.arguments ?? eventPublisher.arguments;
 	if (bindingArguments !== void 0) bindingOptions.arguments = bindingArguments;
 	const binding = defineQueueBindingInternal(queue, exchange, bindingOptions);
+	const consumer = defineConsumer(queue, message);
 	return {
 		__brand: "EventConsumerResult",
-		consumer: defineConsumer(queue, message),
-		binding
+		consumer,
+		binding,
+		exchange,
+		queue: consumer.queue,
+		deadLetterExchange: consumer.queue.deadLetter?.exchange
 	};
 }
 /**
@@ -668,11 +660,14 @@ function isEventConsumerResult(value) {
 * @internal
 */
 function defineCommandConsumer(queue, exchange, message, options) {
+	const consumer = defineConsumer(queue, message);
 	return {
 		__brand: "CommandConsumerConfig",
-		consumer: defineConsumer(queue, message),
+		consumer,
 		binding: defineQueueBindingInternal(queue, exchange, options),
 		exchange,
+		queue: consumer.queue,
+		deadLetterExchange: consumer.queue.deadLetter?.exchange,
 		message,
 		routingKey: options?.routingKey
 	};
@@ -704,19 +699,17 @@ function isCommandConsumerConfig(value) {
 * Define an AMQP contract.
 *
 * A contract is the central definition of your AMQP messaging topology. It brings together
-* all exchanges, queues, bindings, publishers, and consumers in a single, type-safe definition.
+* publishers and consumers in a single, type-safe definition. Exchanges, queues, and bindings
+* are automatically extracted from publishers and consumers.
 *
 * The contract is used by both clients (for publishing) and workers (for consuming) to ensure
 * type safety throughout your messaging infrastructure. TypeScript will infer all message types
 * and publisher/consumer names from the contract.
 *
-* @param definition - The contract definition containing all AMQP resources
-* @param definition.exchanges - Named exchange definitions
-* @param definition.queues - Named queue definitions
-* @param definition.bindings - Named binding definitions (queue-to-exchange or exchange-to-exchange)
+* @param definition - The contract definition containing publishers and consumers
 * @param definition.publishers - Named publisher definitions for sending messages
 * @param definition.consumers - Named consumer definitions for receiving messages
-* @returns The same contract definition with full type inference
+* @returns The contract definition with fully inferred exchanges, queues, bindings, publishers, and consumers
 *
 * @example
 * ```typescript
@@ -724,16 +717,20 @@ function isCommandConsumerConfig(value) {
 *   defineContract,
 *   defineExchange,
 *   defineQueue,
-*   defineQueueBinding,
-*   definePublisher,
-*   defineConsumer,
+*   defineEventPublisher,
+*   defineEventConsumer,
 *   defineMessage,
 * } from '@amqp-contract/contract';
 * import { z } from 'zod';
 *
 * // Define resources
 * const ordersExchange = defineExchange('orders', 'topic', { durable: true });
-* const orderQueue = defineQueue('order-processing', { durable: true });
+* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+* const orderQueue = defineQueue('order-processing', {
+*   deadLetter: { exchange: dlx },
+*   retry: { mode: 'quorum-native' },
+*   deliveryLimit: 3,
+* });
 * const orderMessage = defineMessage(
 *   z.object({
 *     orderId: z.string(),
@@ -741,76 +738,114 @@ function isCommandConsumerConfig(value) {
 *   })
 * );
 *
-* // Compose contract
+* // Define event publisher
+* const orderCreatedEvent = defineEventPublisher(ordersExchange, orderMessage, {
+*   routingKey: 'order.created',
+* });
+*
+* // Compose contract - exchanges, queues, bindings are auto-extracted
 * export const contract = defineContract({
-*   exchanges: {
-*     orders: ordersExchange,
-*   },
-*   queues: {
-*     orderProcessing: orderQueue,
-*   },
-*   bindings: {
-*     orderBinding: defineQueueBinding(orderQueue, ordersExchange, {
-*       routingKey: 'order.created',
-*     }),
-*   },
 *   publishers: {
-*     orderCreated: definePublisher(ordersExchange, orderMessage, {
-*       routingKey: 'order.created',
-*     }),
+*     orderCreated: orderCreatedEvent,
 *   },
 *   consumers: {
-*     processOrder: defineConsumer(orderQueue, orderMessage),
+*     processOrder: defineEventConsumer(orderCreatedEvent, orderQueue),
 *   },
 * });
 *
 * // TypeScript now knows:
+* // - contract.exchanges.orders, contract.exchanges['orders-dlx']
+* // - contract.queues['order-processing']
+* // - contract.bindings.processOrderBinding
 * // - client.publish('orderCreated', { orderId: string, amount: number })
-* // - handler: async (message: { orderId: string, amount: number }) => void
+* // - handler: (message: { orderId: string, amount: number }) => Future<Result<void, HandlerError>>
 * ```
 */
 function defineContract(definition) {
-	const { publishers: inputPublishers, consumers: inputConsumers, ...rest } = definition;
-	const result = rest;
-	if (definition.queues && Object.keys(definition.queues).length > 0) {
-		const expandedQueues = {};
-		const queueBindings = {};
-		for (const [name, entry] of Object.entries(definition.queues)) if (isQueueWithTtlBackoffInfrastructure(entry)) {
-			expandedQueues[name] = entry.queue;
-			expandedQueues[`${name}Wait`] = entry.waitQueue;
-			queueBindings[`${name}WaitBinding`] = entry.waitQueueBinding;
-			queueBindings[`${name}RetryBinding`] = entry.mainQueueRetryBinding;
-		} else expandedQueues[name] = entry;
-		result.queues = expandedQueues;
-		if (Object.keys(queueBindings).length > 0) result.bindings = {
-			...result.bindings,
-			...queueBindings
-		};
-	}
+	const { publishers: inputPublishers, consumers: inputConsumers } = definition;
+	const result = {
+		exchanges: {},
+		queues: {},
+		bindings: {},
+		publishers: {},
+		consumers: {}
+	};
 	if (inputPublishers && Object.keys(inputPublishers).length > 0) {
 		const processedPublishers = {};
+		const exchanges = {};
 		for (const [name, entry] of Object.entries(inputPublishers)) if (isEventPublisherConfig(entry)) {
+			exchanges[entry.exchange.name] = entry.exchange;
 			const publisherOptions = {};
 			if (entry.routingKey !== void 0) publisherOptions.routingKey = entry.routingKey;
 			processedPublishers[name] = definePublisherInternal(entry.exchange, entry.message, publisherOptions);
-		} else processedPublishers[name] = entry;
+		} else {
+			const publisher = entry;
+			exchanges[publisher.exchange.name] = publisher.exchange;
+			processedPublishers[name] = publisher;
+		}
 		result.publishers = processedPublishers;
+		result.exchanges = {
+			...result.exchanges,
+			...exchanges
+		};
 	}
 	if (inputConsumers && Object.keys(inputConsumers).length > 0) {
 		const processedConsumers = {};
 		const consumerBindings = {};
+		const queues = {};
+		const exchanges = {};
 		for (const [name, entry] of Object.entries(inputConsumers)) if (isEventConsumerResult(entry)) {
 			processedConsumers[name] = entry.consumer;
 			consumerBindings[`${name}Binding`] = entry.binding;
+			const queueEntry = entry.consumer.queue;
+			queues[queueEntry.name] = queueEntry;
+			exchanges[entry.binding.exchange.name] = entry.binding.exchange;
+			if (queueEntry.deadLetter?.exchange) exchanges[queueEntry.deadLetter.exchange.name] = queueEntry.deadLetter.exchange;
 		} else if (isCommandConsumerConfig(entry)) {
 			processedConsumers[name] = entry.consumer;
 			consumerBindings[`${name}Binding`] = entry.binding;
-		} else processedConsumers[name] = entry;
+			const queueEntry = entry.consumer.queue;
+			queues[queueEntry.name] = queueEntry;
+			exchanges[entry.exchange.name] = entry.exchange;
+			if (queueEntry.deadLetter?.exchange) exchanges[queueEntry.deadLetter.exchange.name] = queueEntry.deadLetter.exchange;
+		} else {
+			const consumer = entry;
+			processedConsumers[name] = consumer;
+			const queueEntry = consumer.queue;
+			queues[queueEntry.name] = queueEntry;
+			if (queueEntry.deadLetter?.exchange) exchanges[queueEntry.deadLetter.exchange.name] = queueEntry.deadLetter.exchange;
+		}
+		for (const queue of Object.values(queues)) if (queue.retry?.mode === "ttl-backoff" && queue.deadLetter) {
+			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)
+			};
+			queues[waitQueueName] = waitQueue;
+			consumerBindings[`${queue.name}WaitBinding`] = defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName });
+			consumerBindings[`${queue.name}RetryBinding`] = defineQueueBindingInternal(queue, dlx, { routingKey: queue.name });
+			exchanges[dlx.name] = dlx;
+		}
 		result.consumers = processedConsumers;
-		if (Object.keys(consumerBindings).length > 0) result.bindings = {
+		result.bindings = {
 			...result.bindings,
 			...consumerBindings
 		};
+		result.queues = {
+			...result.queues,
+			...queues
+		};
+		result.exchanges = {
+			...result.exchanges,
+			...exchanges
+		};
 	}
 	return result;
 }
@@ -848,23 +883,15 @@ function defineContract(definition) {
 *   },
 * });
 *
-* // Generate TTL-backoff infrastructure
-* const retryInfra = defineTtlBackoffRetryInfrastructure(orderQueue);
-*
-* // Spread into contract
+* // Infrastructure is auto-extracted when using defineContract:
 * const contract = defineContract({
-*   exchanges: { dlx },
-*   queues: {
-*     orderProcessing: orderQueue,
-*     orderProcessingWait: retryInfra.waitQueue,
-*   },
-*   bindings: {
-*     ...// your other bindings
-*     orderWaitBinding: retryInfra.waitQueueBinding,
-*     orderRetryBinding: retryInfra.mainQueueRetryBinding,
-*   },
-*   // ... publishers and consumers
+*   publishers: { ... },
+*   consumers: { processOrder: defineEventConsumer(event, extractQueue(orderQueue)) },
 * });
+* // contract.queues includes the wait queue, contract.bindings includes retry bindings
+*
+* // Or generate manually for advanced use cases:
+* const retryInfra = defineTtlBackoffRetryInfrastructure(orderQueue);
 * ```
 */
 function defineTtlBackoffRetryInfrastructure(queueEntry, options) {
@@ -903,6 +930,7 @@ exports.defineQueueBinding = defineQueueBinding;
 exports.defineQuorumQueue = defineQuorumQueue;
 exports.defineTtlBackoffQueue = defineTtlBackoffQueue;
 exports.defineTtlBackoffRetryInfrastructure = defineTtlBackoffRetryInfrastructure;
+exports.extractConsumer = extractConsumer;
 exports.extractQueue = extractQueue;
 exports.isCommandConsumerConfig = isCommandConsumerConfig;
 exports.isEventConsumerResult = isEventConsumerResult;