@amqp-contract/contract 0.12.0 → 0.13.0

package/README.md

@@ -18,21 +18,30 @@ pnpm add @amqp-contract/contract
 
 ## Quick Start
 
-### Recommended: Publisher-First / Consumer-First Patterns
+### Recommended: Event / Command Patterns
 
-For robust contract definitions with guaranteed consistency, use `definePublisherFirst` (for events) or `defineConsumerFirst` (for commands):
+For robust contract definitions with guaranteed consistency, use Event or Command patterns:
+
+| Pattern     | Use Case                                   | Flow                                               |
+| ----------- | ------------------------------------------ | -------------------------------------------------- |
+| **Event**   | One publisher, many consumers (broadcast)  | `defineEventPublisher` → `defineEventConsumer`     |
+| **Command** | Many publishers, one consumer (task queue) | `defineCommandConsumer` → `defineCommandPublisher` |
 
 ```typescript
 import {
-  definePublisherFirst,
+  defineEventPublisher,
+  defineEventConsumer,
+  defineCommandConsumer,
+  defineCommandPublisher,
   defineContract,
   defineExchange,
   defineQueue,
+  definePublisher,
   defineMessage,
 } from "@amqp-contract/contract";
 import { z } from "zod";
 
-// Event-oriented pattern: publisher doesn't need to know about queues
+// Event pattern: publisher broadcasts, consumers subscribe
 const ordersExchange = defineExchange("orders", "topic", { durable: true });
 const orderMessage = defineMessage(
   z.object({
@@ -41,25 +50,30 @@ const orderMessage = defineMessage(
   }),
 );
 
-const { publisher: orderCreatedPublisher, createConsumer: createOrderCreatedConsumer } =
-  definePublisherFirst(ordersExchange, orderMessage, { routingKey: "order.created" });
+// Define event publisher
+const orderCreatedEvent = defineEventPublisher(ordersExchange, orderMessage, {
+  routingKey: "order.created",
+});
 
 // Multiple queues can consume the same event
 const orderQueue = defineQueue("order-processing", { durable: true });
-const { consumer, binding } = createOrderCreatedConsumer(orderQueue);
+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 } = createOrderCreatedConsumer(
+const { consumer: analyticsConsumer, binding: analyticsBinding } = defineEventConsumer(
+  orderCreatedEvent,
   analyticsQueue,
-  "order.*",
-); // Subscribe to all order events
+  { routingKey: "order.*" }, // Subscribe to all order events
+);
 
 const contract = defineContract({
   exchanges: { orders: ordersExchange },
   queues: { orderQueue, analyticsQueue },
   bindings: { orderBinding: binding, analyticsBinding },
-  publishers: { orderCreated: orderCreatedPublisher },
+  publishers: {
+    orderCreated: definePublisher(ordersExchange, orderMessage, { routingKey: "order.created" }),
+  },
   consumers: {
     processOrder: consumer,
     trackOrders: analyticsConsumer,
@@ -72,7 +86,7 @@ const contract = defineContract({
 - ✅ Guaranteed message schema consistency between publishers and consumers
 - ✅ Routing key validation and type safety
 - ✅ Full type safety with TypeScript inference
-- ✅ Event-oriented (publisher-first) and command-oriented (consumer-first) patterns
+- ✅ Event-oriented and command-oriented patterns
 - ✅ Flexible routing key patterns for topic exchanges
 
 ## Documentation
@@ -80,8 +94,8 @@ const contract = defineContract({
 📖 **[Read the full documentation →](https://btravers.github.io/amqp-contract)**
 
 - [Getting Started Guide](https://btravers.github.io/amqp-contract/guide/defining-contracts)
-- [Publisher-First Pattern](https://btravers.github.io/amqp-contract/guide/defining-contracts#publisher-first-pattern)
-- [Consumer-First Pattern](https://btravers.github.io/amqp-contract/guide/defining-contracts#consumer-first-pattern)
+- [Event Pattern](https://btravers.github.io/amqp-contract/guide/defining-contracts#event-pattern)
+- [Command Pattern](https://btravers.github.io/amqp-contract/guide/defining-contracts#command-pattern)
 - [Complete API Reference](https://btravers.github.io/amqp-contract/api/contract)
 
 ## License

package/dist/index.cjs

@@ -165,24 +165,87 @@ function resolveTtlBackoffOptions(options) {
 }
 /**
 * Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
-* @internal
+*
+* When you configure a queue with TTL-backoff retry and a dead letter exchange,
+* `defineQueue` returns a `QueueWithTtlBackoffInfrastructure` instead of a plain
+* `QueueDefinition`. This type guard helps you distinguish between the two.
+*
+* **When to use:**
+* - When you need to check the type of a queue entry at runtime
+* - When writing generic code that handles both plain queues and infrastructure wrappers
+*
+* **Related functions:**
+* - `extractQueue()` - Use this to get the underlying queue definition from either type
+*
+* @param entry - The queue entry to check
+* @returns True if the entry is a QueueWithTtlBackoffInfrastructure, false otherwise
+*
+* @example
+* ```typescript
+* const queue = defineQueue('orders', {
+*   deadLetter: { exchange: dlx },
+*   retry: { mode: 'ttl-backoff' },
+* });
+*
+* if (isQueueWithTtlBackoffInfrastructure(queue)) {
+*   // queue has .queue, .waitQueue, .waitQueueBinding, .mainQueueRetryBinding
+*   console.log('Wait queue:', queue.waitQueue.name);
+* } else {
+*   // queue is a plain QueueDefinition
+*   console.log('Queue:', queue.name);
+* }
+* ```
 */
 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.
+*
+* **Why this function exists:**
+* When you configure a queue with TTL-backoff retry and a dead letter exchange,
+* `defineQueue` (or `defineTtlBackoffQueue`) returns a wrapper object that includes
+* the main queue, wait queue, and bindings. This function extracts the underlying
+* queue definition so you can access properties like `name`, `type`, etc.
+*
+* **When to use:**
+* - When you need to access queue properties (name, type, deadLetter, etc.)
+* - When passing a queue to functions that expect a plain QueueDefinition
+* - Works safely on both plain queues and infrastructure wrappers
+*
+* **How it works:**
+* - If the entry is a `QueueWithTtlBackoffInfrastructure`, returns `entry.queue`
+* - Otherwise, returns the entry as-is (it's already a plain QueueDefinition)
 *
 * @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
+* import { defineQueue, defineTtlBackoffQueue, extractQueue } from '@amqp-contract/contract';
+*
+* // TTL-backoff queue returns a wrapper
+* const orderQueue = defineTtlBackoffQueue('orders', {
+*   deadLetterExchange: dlx,
+*   maxRetries: 3,
+* });
+*
+* // Use extractQueue to access the queue name
+* const queueName = extractQueue(orderQueue).name; // 'orders'
+*
+* // Also works safely on plain queues
+* const plainQueue = defineQueue('simple', { type: 'quorum', retry: { mode: 'quorum-native' } });
+* const plainName = extractQueue(plainQueue).name; // 'simple'
+*
+* // Access other properties
+* const queueDef = extractQueue(orderQueue);
+* console.log(queueDef.name);       // 'orders'
+* console.log(queueDef.type);       // 'quorum'
+* console.log(queueDef.deadLetter); // { exchange: dlx, ... }
 * ```
+*
+* @see isQueueWithTtlBackoffInfrastructure - Type guard to check if extraction is needed
+* @see defineTtlBackoffQueue - Creates queues with TTL-backoff infrastructure
 */
 function extractQueue(entry) {
 	if (isQueueWithTtlBackoffInfrastructure(entry)) return entry.queue;
@@ -322,6 +385,126 @@ function defineQueue(name, options) {
 	if (retry.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
 	return queueDefinition;
 }
+/**
+* Create a quorum queue with quorum-native retry.
+*
+* This is a simplified helper that enforces best practices:
+* - Uses quorum queues (recommended for most use cases)
+* - Requires dead letter exchange for failed message handling
+* - Uses quorum-native retry mode (simpler than TTL-backoff)
+*
+* **When to use:**
+* - You want simple, immediate retries without exponential backoff
+* - You don't need configurable delays between retries
+* - You want the simplest retry configuration
+*
+* @param name - The queue name
+* @param options - Configuration options
+* @returns A quorum queue definition with quorum-native retry
+*
+* @example
+* ```typescript
+* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+*
+* const orderQueue = defineQuorumQueue('order-processing', {
+*   deadLetterExchange: dlx,
+*   deliveryLimit: 3, // Retry up to 3 times
+* });
+*
+* const contract = defineContract({
+*   exchanges: { dlx },
+*   queues: { orderProcessing: orderQueue },
+*   // ...
+* });
+* ```
+*
+* @see defineQueue - For full queue configuration options
+* @see defineTtlBackoffQueue - For queues with exponential backoff retry
+*/
+function defineQuorumQueue(name, options) {
+	const { deadLetterExchange, deadLetterRoutingKey, deliveryLimit, autoDelete, arguments: args } = options;
+	const queueOptions = {
+		type: "quorum",
+		deadLetter: deadLetterRoutingKey ? {
+			exchange: deadLetterExchange,
+			routingKey: deadLetterRoutingKey
+		} : { exchange: deadLetterExchange },
+		deliveryLimit,
+		retry: { mode: "quorum-native" }
+	};
+	if (autoDelete !== void 0) queueOptions.autoDelete = autoDelete;
+	if (args !== void 0) queueOptions.arguments = args;
+	return defineQueue(name, queueOptions);
+}
+/**
+* Create a queue with TTL-backoff retry (exponential backoff).
+*
+* This is a simplified helper that enforces best practices:
+* - Uses quorum queues (recommended for most use cases)
+* - Requires dead letter exchange for retry routing
+* - Uses TTL-backoff retry mode with configurable delays
+* - Automatically generates wait queue and bindings
+*
+* **When to use:**
+* - You need exponential backoff between retries
+* - You want configurable delays (initial delay, max delay, jitter)
+* - You're processing messages that may need time before retry
+*
+* **Returns:** A `QueueWithTtlBackoffInfrastructure` object that includes the
+* main queue, wait queue, and bindings. Pass this directly to `defineContract`
+* and it will be expanded automatically.
+*
+* @param name - The queue name
+* @param options - Configuration options
+* @returns A queue with TTL-backoff infrastructure
+*
+* @example
+* ```typescript
+* const dlx = defineExchange('orders-dlx', 'direct', { durable: true });
+*
+* const orderQueue = defineTtlBackoffQueue('order-processing', {
+*   deadLetterExchange: dlx,
+*   maxRetries: 5,
+*   initialDelayMs: 1000,  // Start with 1s delay
+*   maxDelayMs: 30000,     // Cap at 30s
+* });
+*
+* const contract = defineContract({
+*   exchanges: { dlx },
+*   queues: { orderProcessing: orderQueue }, // Wait queue auto-added
+*   // ... bindings auto-generated
+* });
+*
+* // To access the underlying queue definition (e.g., for the queue name):
+* import { extractQueue } from '@amqp-contract/contract';
+* const queueName = extractQueue(orderQueue).name;
+* ```
+*
+* @see defineQueue - For full queue configuration options
+* @see defineQuorumQueue - For queues with quorum-native retry (simpler, immediate retries)
+* @see extractQueue - To access the underlying queue definition
+*/
+function defineTtlBackoffQueue(name, options) {
+	const { deadLetterExchange, deadLetterRoutingKey, maxRetries, initialDelayMs, maxDelayMs, backoffMultiplier, jitter, autoDelete, arguments: args } = options;
+	const deadLetter = deadLetterRoutingKey ? {
+		exchange: deadLetterExchange,
+		routingKey: deadLetterRoutingKey
+	} : { exchange: deadLetterExchange };
+	const retryOptions = { mode: "ttl-backoff" };
+	if (maxRetries !== void 0) retryOptions.maxRetries = maxRetries;
+	if (initialDelayMs !== void 0) retryOptions.initialDelayMs = initialDelayMs;
+	if (maxDelayMs !== void 0) retryOptions.maxDelayMs = maxDelayMs;
+	if (backoffMultiplier !== void 0) retryOptions.backoffMultiplier = backoffMultiplier;
+	if (jitter !== void 0) retryOptions.jitter = jitter;
+	const queueOptions = {
+		type: "quorum",
+		deadLetter,
+		retry: retryOptions
+	};
+	if (autoDelete !== void 0) queueOptions.autoDelete = autoDelete;
+	if (args !== void 0) queueOptions.arguments = args;
+	return defineQueue(name, queueOptions);
+}
 
 //#endregion
 //#region src/builder/publisher.ts
@@ -368,6 +551,19 @@ function definePublisherInternal(exchange, message, options) {
 * Consumers are associated with a specific queue and message type. When you create a worker
 * with this consumer, it will process messages from the queue according to the schema.
 *
+* **Which pattern to use:**
+*
+* | Pattern | Best for | Description |
+* |---------|----------|-------------|
+* | `definePublisher` + `defineConsumer` | Independent definition | Define publishers and consumers separately with manual schema consistency |
+* | `defineEventPublisher` + `defineEventConsumer` | Event broadcasting | Define event publisher first, create consumers that subscribe to it |
+* | `defineCommandConsumer` + `defineCommandPublisher` | Task queues | Define command consumer first, create publishers that send commands to it |
+*
+* Use `defineCommandConsumer` when:
+* - One consumer receives from multiple publishers
+* - You want automatic schema consistency between consumer and publishers
+* - You're building task queue or command patterns
+*
 * @param queue - The queue definition to consume from
 * @param message - The message definition with payload schema
 * @param options - Optional consumer configuration
@@ -400,6 +596,9 @@ function definePublisherInternal(exchange, message, options) {
 * //   connection
 * // });
 * ```
+*
+* @see defineCommandConsumer - For task queue patterns with automatic schema consistency
+* @see defineEventPublisher - For event-driven patterns with automatic schema consistency
 */
 function defineConsumer(queue, message, options) {
 	return {
@@ -409,6 +608,96 @@ function defineConsumer(queue, message, options) {
 	};
 }
 
+//#endregion
+//#region src/builder/event.ts
+/**
+* Implementation of defineEventPublisher.
+* @internal
+*/
+function defineEventPublisher(exchange, message, options) {
+	const config = {
+		__brand: "EventPublisherConfig",
+		exchange,
+		message,
+		routingKey: options?.routingKey
+	};
+	if (options?.arguments !== void 0) config.arguments = options.arguments;
+	return config;
+}
+/**
+* Implementation of defineEventConsumer.
+* @internal
+*/
+function defineEventConsumer(eventPublisher, queue, options) {
+	const { exchange, message, routingKey: publisherRoutingKey } = eventPublisher;
+	const bindingRoutingKey = options?.routingKey ?? publisherRoutingKey;
+	const bindingOptions = {};
+	if (bindingRoutingKey !== void 0) bindingOptions.routingKey = bindingRoutingKey;
+	const bindingArguments = options?.arguments ?? eventPublisher.arguments;
+	if (bindingArguments !== void 0) bindingOptions.arguments = bindingArguments;
+	const binding = defineQueueBindingInternal(queue, exchange, bindingOptions);
+	return {
+		__brand: "EventConsumerResult",
+		consumer: defineConsumer(queue, message),
+		binding
+	};
+}
+/**
+* Type guard to check if a value is an EventPublisherConfig.
+*
+* @param value - The value to check
+* @returns True if the value is an EventPublisherConfig
+*/
+function isEventPublisherConfig(value) {
+	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "EventPublisherConfig";
+}
+/**
+* Type guard to check if a value is an EventConsumerResult.
+*
+* @param value - The value to check
+* @returns True if the value is an EventConsumerResult
+*/
+function isEventConsumerResult(value) {
+	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "EventConsumerResult";
+}
+
+//#endregion
+//#region src/builder/command.ts
+/**
+* Implementation of defineCommandConsumer.
+* @internal
+*/
+function defineCommandConsumer(queue, exchange, message, options) {
+	return {
+		__brand: "CommandConsumerConfig",
+		consumer: defineConsumer(queue, message),
+		binding: defineQueueBindingInternal(queue, exchange, options),
+		exchange,
+		message,
+		routingKey: options?.routingKey
+	};
+}
+/**
+* Implementation of defineCommandPublisher.
+* @internal
+*/
+function defineCommandPublisher(commandConsumer, options) {
+	const { exchange, message, routingKey: consumerRoutingKey } = commandConsumer;
+	const publisherRoutingKey = options?.routingKey ?? consumerRoutingKey;
+	const publisherOptions = {};
+	if (publisherRoutingKey !== void 0) publisherOptions.routingKey = publisherRoutingKey;
+	return definePublisherInternal(exchange, message, publisherOptions);
+}
+/**
+* Type guard to check if a value is a CommandConsumerConfig.
+*
+* @param value - The value to check
+* @returns True if the value is a CommandConsumerConfig
+*/
+function isCommandConsumerConfig(value) {
+	return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "CommandConsumerConfig";
+}
+
 //#endregion
 //#region src/builder/contract.ts
 /**
@@ -481,100 +770,49 @@ function defineConsumer(queue, message, options) {
 * ```
 */
 function defineContract(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
+	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
 		};
 	}
-	return {
-		...definition,
-		queues: expandedQueues
-	};
-}
-
-//#endregion
-//#region src/builder/publisher-first.ts
-/**
-* Implementation of definePublisherFirst.
-* @internal
-*/
-function definePublisherFirst(exchange, message, options) {
-	const publisher = definePublisherInternal(exchange, message, options);
-	if (exchange.type === "topic") {
-		const createConsumer$1 = (queue, routingKey) => {
-			const binding = defineQueueBindingInternal(queue, exchange, routingKey ? {
-				...options,
-				routingKey
-			} : options);
-			return {
-				consumer: defineConsumer(queue, message),
-				binding
-			};
-		};
-		return {
-			publisher,
-			createConsumer: createConsumer$1
-		};
+	if (inputPublishers && Object.keys(inputPublishers).length > 0) {
+		const processedPublishers = {};
+		for (const [name, entry] of Object.entries(inputPublishers)) if (isEventPublisherConfig(entry)) {
+			const publisherOptions = {};
+			if (entry.routingKey !== void 0) publisherOptions.routingKey = entry.routingKey;
+			processedPublishers[name] = definePublisherInternal(entry.exchange, entry.message, publisherOptions);
+		} else processedPublishers[name] = entry;
+		result.publishers = processedPublishers;
 	}
-	const createConsumer = (queue) => {
-		const binding = defineQueueBindingInternal(queue, exchange, options);
-		return {
-			consumer: defineConsumer(queue, message),
-			binding
-		};
-	};
-	return {
-		publisher,
-		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 = defineQueueBindingInternal(queue, exchange, options);
-	if (exchange.type === "topic") {
-		const createPublisher$1 = (routingKey) => {
-			return definePublisherInternal(exchange, message, {
-				...options,
-				routingKey
-			});
-		};
-		return {
-			consumer,
-			binding,
-			createPublisher: createPublisher$1
+	if (inputConsumers && Object.keys(inputConsumers).length > 0) {
+		const processedConsumers = {};
+		const consumerBindings = {};
+		for (const [name, entry] of Object.entries(inputConsumers)) if (isEventConsumerResult(entry)) {
+			processedConsumers[name] = entry.consumer;
+			consumerBindings[`${name}Binding`] = entry.binding;
+		} else if (isCommandConsumerConfig(entry)) {
+			processedConsumers[name] = entry.consumer;
+			consumerBindings[`${name}Binding`] = entry.binding;
+		} else processedConsumers[name] = entry;
+		result.consumers = processedConsumers;
+		if (Object.keys(consumerBindings).length > 0) result.bindings = {
+			...result.bindings,
+			...consumerBindings
 		};
 	}
-	const createPublisher = () => {
-		return definePublisherInternal(exchange, message, options);
-	};
-	return {
-		consumer,
-		binding,
-		createPublisher
-	};
+	return result;
 }
 
 //#endregion
@@ -650,15 +888,23 @@ function defineTtlBackoffRetryInfrastructure(queueEntry, options) {
 }
 
 //#endregion
+exports.defineCommandConsumer = defineCommandConsumer;
+exports.defineCommandPublisher = defineCommandPublisher;
 exports.defineConsumer = defineConsumer;
-exports.defineConsumerFirst = defineConsumerFirst;
 exports.defineContract = defineContract;
+exports.defineEventConsumer = defineEventConsumer;
+exports.defineEventPublisher = defineEventPublisher;
 exports.defineExchange = defineExchange;
 exports.defineExchangeBinding = defineExchangeBinding;
 exports.defineMessage = defineMessage;
 exports.definePublisher = definePublisher;
-exports.definePublisherFirst = definePublisherFirst;
 exports.defineQueue = defineQueue;
 exports.defineQueueBinding = defineQueueBinding;
+exports.defineQuorumQueue = defineQuorumQueue;
+exports.defineTtlBackoffQueue = defineTtlBackoffQueue;
 exports.defineTtlBackoffRetryInfrastructure = defineTtlBackoffRetryInfrastructure;
-exports.extractQueue = extractQueue;
+exports.extractQueue = extractQueue;
+exports.isCommandConsumerConfig = isCommandConsumerConfig;
+exports.isEventConsumerResult = isEventConsumerResult;
+exports.isEventPublisherConfig = isEventPublisherConfig;
+exports.isQueueWithTtlBackoffInfrastructure = isQueueWithTtlBackoffInfrastructure;