@amqp-contract/contract 0.3.5 → 0.5.0

package/README.md

@@ -16,76 +16,67 @@
 pnpm add @amqp-contract/contract
 ```
 
-## Usage
+## Quick Start
+
+### Recommended: Publisher-First / Consumer-First Patterns
+
+For robust contract definitions with guaranteed consistency, use `definePublisherFirst` (for events) or `defineConsumerFirst` (for commands):
 
 ```typescript
-import { defineContract, defineExchange, defineQueue, defineQueueBinding, defineExchangeBinding, definePublisher, defineConsumer, defineMessage } from '@amqp-contract/contract';
+import { definePublisherFirst, defineContract, defineExchange, defineQueue, defineMessage } from '@amqp-contract/contract';
 import { z } from 'zod';
 
-// Define exchanges and queues first so they can be referenced
+// Event-oriented pattern: publisher doesn't need to know about queues
 const ordersExchange = defineExchange('orders', 'topic', { durable: true });
-const analyticsExchange = defineExchange('analytics', 'topic', { durable: true });
-const orderProcessingQueue = defineQueue('order-processing', { durable: true });
-const analyticsProcessingQueue = defineQueue('analytics-processing', { durable: true });
-
-// Define message schemas with metadata
-const orderMessage = defineMessage(
-  z.object({
-    orderId: z.string(),
-    amount: z.number(),
-  }),
-  {
-    summary: 'Order created event',
-    description: 'Emitted when a new order is created',
-  }
+const orderMessage = defineMessage(z.object({
+  orderId: z.string(),
+  amount: z.number(),
+}));
+
+const orderCreatedEvent = definePublisherFirst(
+  ordersExchange,
+  orderMessage,
+  { routingKey: 'order.created' }
 );
 
-// Define your contract using object references
+// Multiple queues can consume the same event
+const orderQueue = defineQueue('order-processing', { durable: true });
+const { consumer, binding } = orderCreatedEvent.createConsumer(orderQueue);
+
+// For topic exchanges, consumers can override with their own pattern
+const analyticsQueue = defineQueue('analytics', { durable: true });
+const { consumer: analyticsConsumer, binding: analyticsBinding } =
+  orderCreatedEvent.createConsumer(analyticsQueue, 'order.*');  // Subscribe to all order events
+
 const contract = defineContract({
-  exchanges: {
-    orders: ordersExchange,
-    analytics: analyticsExchange,
-  },
-  queues: {
-    orderProcessing: orderProcessingQueue,
-    analyticsProcessing: analyticsProcessingQueue,
-  },
-  bindings: {
-    // Queue-to-exchange binding
-    orderBinding: defineQueueBinding(orderProcessingQueue, ordersExchange, {
-      routingKey: 'order.created',
-    }),
-    // Exchange-to-exchange binding
-    analyticsBinding: defineExchangeBinding(analyticsExchange, ordersExchange, {
-      routingKey: 'order.#',
-    }),
-    // Queue receives from analytics exchange
-    analyticsQueueBinding: defineQueueBinding(analyticsProcessingQueue, analyticsExchange, {
-      routingKey: 'order.#',
-    }),
-  },
-  publishers: {
-    orderCreated: definePublisher(ordersExchange, orderMessage, {
-      routingKey: 'order.created',
-    }),
-  },
+  exchanges: { orders: ordersExchange },
+  queues: { orderQueue, analyticsQueue },
+  bindings: { orderBinding: binding, analyticsBinding },
+  publishers: { orderCreated: orderCreatedEvent.publisher },
   consumers: {
-    processOrder: defineConsumer(orderProcessingQueue, orderMessage, {
-      prefetch: 10,
-    }),
-    processAnalytics: defineConsumer(analyticsProcessingQueue, orderMessage),
+    processOrder: consumer,
+    trackOrders: analyticsConsumer,
   },
 });
 ```
 
-## API
+**Benefits:**
 
-For complete API documentation, see the [Contract API Reference](https://btravers.github.io/amqp-contract/api/contract).
+- ✅ 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
+- ✅ Flexible routing key patterns for topic exchanges
 
 ## Documentation
 
 📖 **[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)
+- [Complete API Reference](https://btravers.github.io/amqp-contract/api/contract)
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -287,13 +287,96 @@ 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);
+}
+/**
+* Implementation of definePublisherFirst.
+* @internal
+*/
+function definePublisherFirst(exchange, message, options) {
+	const publisher = callDefinePublisher(exchange, message, options);
+	if (exchange.type === "topic") {
+		const createConsumer$1 = (queue, routingKey) => {
+			const binding = callDefineQueueBinding(queue, exchange, routingKey ? {
+				...options,
+				routingKey
+			} : options);
+			return {
+				consumer: defineConsumer(queue, message),
+				binding
+			};
+		};
+		return {
+			publisher,
+			createConsumer: createConsumer$1
+		};
+	}
+	const createConsumer = (queue) => {
+		const binding = callDefineQueueBinding(queue, exchange, options);
+		return {
+			consumer: defineConsumer(queue, message),
+			binding
+		};
+	};
+	return {
+		publisher,
+		createConsumer
+	};
+}
+/**
+* Implementation of defineConsumerFirst.
+* @internal
+*/
+function defineConsumerFirst(queue, exchange, message, options) {
+	const consumer = defineConsumer(queue, message);
+	const binding = callDefineQueueBinding(queue, exchange, options);
+	if (exchange.type === "topic") {
+		const createPublisher$1 = (routingKey) => {
+			return callDefinePublisher(exchange, message, {
+				...options,
+				routingKey
+			});
+		};
+		return {
+			consumer,
+			binding,
+			createPublisher: createPublisher$1
+		};
+	}
+	const createPublisher = () => {
+		return callDefinePublisher(exchange, message, options);
+	};
+	return {
+		consumer,
+		binding,
+		createPublisher
+	};
+}
 
 //#endregion
 exports.defineConsumer = defineConsumer;
+exports.defineConsumerFirst = defineConsumerFirst;
 exports.defineContract = defineContract;
 exports.defineExchange = defineExchange;
 exports.defineExchangeBinding = defineExchangeBinding;
 exports.defineMessage = defineMessage;
 exports.definePublisher = definePublisher;
+exports.definePublisherFirst = definePublisherFirst;
 exports.defineQueue = defineQueue;
 exports.defineQueueBinding = defineQueueBinding;