@amqp-contract/contract 0.2.0 → 0.3.0

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)**
 
@@ -143,6 +149,10 @@ The API enforces routing key requirements based on exchange type:
 
 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,7 +1,17 @@
 
 //#region src/builder.ts
 /**
-* Define an AMQP exchange
+* 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 defineExchange(name, type, options) {
 	return {
@@ -11,7 +21,29 @@ function defineExchange(name, type, options) {
 	};
 }
 /**
-* Define an AMQP queue
+* 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 defineQueue(name, options) {
 	return {
@@ -20,7 +52,39 @@ function defineQueue(name, options) {
 	};
 }
 /**
-* Define a message definition with payload and optional headers/metadata
+* 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 defineMessage(payload, options) {
 	return {
@@ -29,7 +93,15 @@ function defineMessage(payload, options) {
 	};
 }
 /**
-* Define a binding between queue and exchange (exchange -> queue)
+* 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 defineQueueBinding(queue, exchange, options) {
 	if (exchange.type === "fanout") return {
@@ -47,7 +119,15 @@ function defineQueueBinding(queue, exchange, options) {
 	};
 }
 /**
-* 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 {
@@ -65,7 +145,15 @@ function defineExchangeBinding(destination, source, options) {
 	};
 }
 /**
-* 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 {
@@ -79,7 +167,46 @@ function definePublisher(exchange, message, options) {
 	};
 }
 /**
-* 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 {
@@ -89,7 +216,73 @@ 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;