@amqp-contract/contract 0.1.4 → 0.2.1

package/README.md

@@ -1,6 +1,12 @@
 # @amqp-contract/contract
 
-Contract builder for amqp-contract - Define type-safe AMQP messaging contracts.
+**Contract builder for amqp-contract - Define type-safe AMQP messaging contracts.**
+
+[![CI](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@amqp-contract/contract.svg?logo=npm)](https://www.npmjs.com/package/@amqp-contract/contract)
+[![npm downloads](https://img.shields.io/npm/dm/@amqp-contract/contract.svg)](https://www.npmjs.com/package/@amqp-contract/contract)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 📖 **[Full documentation →](https://btravers.github.io/amqp-contract/api/contract)**
 
@@ -13,52 +19,61 @@ pnpm add @amqp-contract/contract
 ## Usage
 
 ```typescript
-import { defineContract, defineExchange, defineQueue, defineBinding, defineExchangeBinding, definePublisher, defineConsumer } from '@amqp-contract/contract';
+import { defineContract, defineExchange, defineQueue, defineQueueBinding, defineExchangeBinding, definePublisher, defineConsumer, defineMessage } from '@amqp-contract/contract';
 import { z } from 'zod';
 
-// Define your contract
+// Define exchanges and queues first so they can be referenced
+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',
+  }
+);
+
+// Define your contract using object references
 const contract = defineContract({
   exchanges: {
-    orders: defineExchange('orders', 'topic', { durable: true }),
-    analytics: defineExchange('analytics', 'topic', { durable: true }),
+    orders: ordersExchange,
+    analytics: analyticsExchange,
   },
   queues: {
-    orderProcessing: defineQueue('order-processing', { durable: true }),
-    analyticsProcessing: defineQueue('analytics-processing', { durable: true }),
+    orderProcessing: orderProcessingQueue,
+    analyticsProcessing: analyticsProcessingQueue,
   },
   bindings: {
     // Queue-to-exchange binding
-    orderBinding: defineBinding('order-processing', 'orders', {
+    orderBinding: defineQueueBinding(orderProcessingQueue, ordersExchange, {
       routingKey: 'order.created',
     }),
     // Exchange-to-exchange binding
-    analyticsBinding: defineExchangeBinding('analytics', 'orders', {
+    analyticsBinding: defineExchangeBinding(analyticsExchange, ordersExchange, {
       routingKey: 'order.#',
     }),
     // Queue receives from analytics exchange
-    analyticsQueueBinding: defineBinding('analytics-processing', 'analytics', {
+    analyticsQueueBinding: defineQueueBinding(analyticsProcessingQueue, analyticsExchange, {
       routingKey: 'order.#',
     }),
   },
   publishers: {
-    orderCreated: definePublisher('orders', z.object({
-      orderId: z.string(),
-      amount: z.number(),
-    }), {
+    orderCreated: definePublisher(ordersExchange, orderMessage, {
       routingKey: 'order.created',
     }),
   },
   consumers: {
-    processOrder: defineConsumer('order-processing', z.object({
-      orderId: z.string(),
-      amount: z.number(),
-    }), {
+    processOrder: defineConsumer(orderProcessingQueue, orderMessage, {
       prefetch: 10,
     }),
-    processAnalytics: defineConsumer('analytics-processing', z.object({
-      orderId: z.string(),
-      amount: z.number(),
-    })),
+    processAnalytics: defineConsumer(analyticsProcessingQueue, orderMessage),
   },
 });
 ```
@@ -67,32 +82,77 @@ const contract = defineContract({
 
 ### `defineExchange(name, type, options?)`
 
-Define an AMQP exchange.
+Define an AMQP exchange. Returns an exchange definition object that can be referenced by bindings and publishers.
+
+**Types:** `'fanout'`, `'direct'`, or `'topic'`
 
 ### `defineQueue(name, options?)`
 
-Define an AMQP queue.
+Define an AMQP queue. Returns a queue definition object that can be referenced by bindings and consumers.
+
+### `defineMessage(payloadSchema, options?)`
+
+Define a message definition with a payload schema and optional metadata (headers, summary, description).
+This is useful for documentation generation and type inference.
+
+### `defineQueueBinding(queue, exchange, options?)`
 
-### `defineBinding(queue, exchange, options?)`
+Define a binding between a queue and an exchange. Pass the queue and exchange objects (not strings).
 
-Define a binding between a queue and an exchange.
+**For fanout exchanges:** Routing key is optional (fanout ignores routing keys).
+**For direct/topic exchanges:** Routing key is required in options.
 
 ### `defineExchangeBinding(destination, source, options?)`
 
 Define a binding between two exchanges (source → destination). Messages published to the source exchange will be routed to the destination exchange based on the routing key pattern.
 
-### `definePublisher(exchange, messageSchema, options?)`
+Pass the exchange objects (not strings).
 
-Define a message publisher with validation schema.
+### `definePublisher(exchange, message, options?)`
 
-### `defineConsumer(queue, messageSchema, options?)`
+Define a message publisher with validation schema. Pass the exchange object (not a string).
 
-Define a message consumer with validation schema.
+**For fanout exchanges:** Routing key is optional (fanout ignores routing keys).
+**For direct/topic exchanges:** Routing key is required in options.
+
+### `defineConsumer(queue, message, options?)`
+
+Define a message consumer with validation schema. Pass the queue object (not a string).
 
 ### `defineContract(definition)`
 
 Create a complete AMQP contract with exchanges, queues, bindings, publishers, and consumers.
 
+## Key Concepts
+
+### Composition Pattern
+
+The contract API uses a composition pattern where you:
+
+1. Define exchanges and queues first as variables
+2. Reference these objects in bindings, publishers, and consumers
+3. Compose everything together in `defineContract`
+
+This provides:
+
+- **Better type safety**: TypeScript can validate exchange/queue types
+- **Better refactoring**: Rename an exchange in one place
+- **DRY principle**: Define once, reference many times
+
+### Exchange Types & Routing Keys
+
+The API enforces routing key requirements based on exchange type:
+
+- **Fanout exchanges**: Don't use routing keys (all messages go to all bound queues)
+- **Direct exchanges**: Require explicit routing keys for exact matching
+- **Topic exchanges**: Require routing key patterns (e.g., `order.*`, `order.#`)
+
+TypeScript enforces these rules at compile time through discriminated unions.
+
+## Documentation
+
+📖 **[Read the full documentation →](https://btravers.github.io/amqp-contract)**
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -1,68 +1,212 @@
 
 //#region src/builder.ts
 /**
-* Define a message schema with metadata
+* Define an AMQP exchange.
+*
+* An exchange receives messages from publishers and routes them to queues based on the exchange type
+* and routing rules. This is the implementation function - use the type-specific overloads for better
+* type safety.
+*
+* @param name - The name of the exchange
+* @param type - The type of exchange: "fanout", "direct", or "topic"
+* @param options - Optional exchange configuration
+* @returns An exchange definition
+* @internal
 */
-function defineMessage(name, schema) {
+function defineExchange(name, type, options) {
 	return {
 		name,
-		schema,
-		"~standard": schema["~standard"]
+		type,
+		...options
 	};
 }
 /**
-* Define an AMQP exchange
+* 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.arguments - Additional AMQP arguments (e.g., x-message-ttl, x-dead-letter-exchange)
+* @returns A queue definition
+*
+* @example
+* ```typescript
+* const orderProcessingQueue = defineQueue('order-processing', {
+*   durable: true,
+*   arguments: {
+*     'x-message-ttl': 86400000, // 24 hours
+*     'x-dead-letter-exchange': 'orders-dlx'
+*   }
+* });
+* ```
 */
-function defineExchange(name, type, options) {
+function defineQueue(name, options) {
 	return {
 		name,
-		type,
 		...options
 	};
 }
 /**
-* Define an AMQP queue
+* Define a message definition with payload and optional headers/metadata.
+*
+* A message definition specifies the schema for message payloads and headers using
+* Standard Schema v1 compatible libraries (Zod, Valibot, ArkType, etc.).
+* The schemas are used for automatic validation when publishing or consuming messages.
+*
+* @param payload - The payload schema (must be Standard Schema v1 compatible)
+* @param options - Optional message metadata
+* @param options.headers - Optional header schema for message headers
+* @param options.summary - Brief description for documentation (used in AsyncAPI generation)
+* @param options.description - Detailed description for documentation (used in AsyncAPI generation)
+* @returns A message definition with inferred types
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+*
+* const orderMessage = defineMessage(
+*   z.object({
+*     orderId: z.string().uuid(),
+*     customerId: z.string().uuid(),
+*     amount: z.number().positive(),
+*     items: z.array(z.object({
+*       productId: z.string(),
+*       quantity: z.number().int().positive(),
+*     })),
+*   }),
+*   {
+*     summary: 'Order created event',
+*     description: 'Emitted when a new order is created in the system'
+*   }
+* );
+* ```
 */
-function defineQueue(name, options) {
+function defineMessage(payload, options) {
 	return {
-		name,
+		payload,
 		...options
 	};
 }
 /**
-* Define a binding between queue and exchange
+* 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 exchange - The exchange definition
+* @param options - Optional binding configuration
+* @returns A queue binding definition
+* @internal
 */
-function defineBinding(queue, exchange, options) {
+function defineQueueBinding(queue, exchange, options) {
+	if (exchange.type === "fanout") return {
+		type: "queue",
+		queue,
+		exchange,
+		...options?.arguments && { arguments: options.arguments }
+	};
 	return {
 		type: "queue",
 		queue,
 		exchange,
-		...options
+		routingKey: options?.routingKey,
+		...options?.arguments && { arguments: options.arguments }
 	};
 }
 /**
-* Define a binding between exchange and exchange (source -> destination)
+* Define a binding between two exchanges (exchange-to-exchange routing).
+*
+* This is the implementation function - use the type-specific overloads for better type safety.
+*
+* @param destination - The destination exchange definition
+* @param source - The source exchange definition
+* @param options - Optional binding configuration
+* @returns An exchange binding definition
+* @internal
 */
 function defineExchangeBinding(destination, source, options) {
+	if (source.type === "fanout") return {
+		type: "exchange",
+		source,
+		destination,
+		...options?.arguments && { arguments: options.arguments }
+	};
 	return {
 		type: "exchange",
 		source,
 		destination,
-		...options
+		routingKey: options?.routingKey ?? "",
+		...options?.arguments && { arguments: options.arguments }
 	};
 }
 /**
-* Define a message publisher
+* Define a message publisher.
+*
+* This is the implementation function - use the type-specific overloads for better type safety.
+*
+* @param exchange - The exchange definition
+* @param message - The message definition
+* @param options - Optional publisher configuration
+* @returns A publisher definition
+* @internal
 */
 function definePublisher(exchange, message, options) {
+	if (exchange.type === "fanout") return {
+		exchange,
+		message
+	};
 	return {
 		exchange,
 		message,
-		...options
+		routingKey: options?.routingKey ?? ""
 	};
 }
 /**
-* Define a message consumer
+* Define a message consumer.
+*
+* A consumer receives and processes messages from a queue. The message schema is validated
+* automatically when messages are consumed, ensuring type safety for your handlers.
+*
+* 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.
+*
+* @param queue - The queue definition to consume from
+* @param message - The message definition with payload schema
+* @param options - Optional consumer configuration
+* @returns A consumer definition with inferred message types
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+*
+* const orderQueue = defineQueue('order-processing', { durable: true });
+* const orderMessage = defineMessage(
+*   z.object({
+*     orderId: z.string().uuid(),
+*     customerId: z.string().uuid(),
+*     amount: z.number().positive(),
+*   })
+* );
+*
+* const processOrderConsumer = defineConsumer(orderQueue, orderMessage);
+*
+* // Later, when creating a worker, you'll provide a handler for this consumer:
+* // const worker = await TypedAmqpWorker.create({
+* //   contract,
+* //   handlers: {
+* //     processOrder: async (message) => {
+* //       // message is automatically typed based on the schema
+* //       console.log(message.orderId); // string
+* //     }
+* //   },
+* //   connection
+* // });
+* ```
 */
 function defineConsumer(queue, message, options) {
 	return {
@@ -72,18 +216,84 @@ function defineConsumer(queue, message, options) {
 	};
 }
 /**
-* Define an AMQP contract
+* 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.
+*
+* 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.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
+*
+* @example
+* ```typescript
+* import {
+*   defineContract,
+*   defineExchange,
+*   defineQueue,
+*   defineQueueBinding,
+*   definePublisher,
+*   defineConsumer,
+*   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 orderMessage = defineMessage(
+*   z.object({
+*     orderId: z.string(),
+*     amount: z.number(),
+*   })
+* );
+*
+* // Compose contract
+* 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',
+*     }),
+*   },
+*   consumers: {
+*     processOrder: defineConsumer(orderQueue, orderMessage),
+*   },
+* });
+*
+* // TypeScript now knows:
+* // - client.publish('orderCreated', { orderId: string, amount: number })
+* // - handler: async (message: { orderId: string, amount: number }) => void
+* ```
 */
 function defineContract(definition) {
 	return definition;
 }
 
 //#endregion
-exports.defineBinding = defineBinding;
 exports.defineConsumer = defineConsumer;
 exports.defineContract = defineContract;
 exports.defineExchange = defineExchange;
 exports.defineExchangeBinding = defineExchangeBinding;
 exports.defineMessage = defineMessage;
 exports.definePublisher = definePublisher;
-exports.defineQueue = defineQueue;
+exports.defineQueue = defineQueue;
+exports.defineQueueBinding = defineQueueBinding;