@amqp-contract/contract 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -3,171 +3,546 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/types.d.ts
 
 /**
- * Any schema that conforms to Standard Schema v1
+ * Any schema that conforms to Standard Schema v1.
+ *
+ * This library supports any validation library that implements the Standard Schema v1 specification,
+ * including Zod, Valibot, and ArkType. This allows you to use your preferred validation library
+ * while maintaining type safety.
+ *
+ * @see https://github.com/standard-schema/standard-schema
  */
 type AnySchema = StandardSchemaV1;
 /**
- * Definition of an AMQP exchange
+ * Base definition of an AMQP exchange.
+ *
+ * An exchange receives messages from publishers and routes them to queues based on the exchange
+ * type and routing rules. This type contains properties common to all exchange types.
  */
 type BaseExchangeDefinition = {
+  /**
+   * The name of the exchange. Must be unique within the RabbitMQ virtual host.
+   */
   name: string;
+  /**
+   * If true, the exchange survives broker restarts. Durable exchanges are persisted to disk.
+   * @default false
+   */
   durable?: boolean;
+  /**
+   * If true, the exchange is deleted when all queues have finished using it.
+   * @default false
+   */
   autoDelete?: boolean;
+  /**
+   * If true, the exchange cannot be directly published to by clients.
+   * It can only receive messages from other exchanges via exchange-to-exchange bindings.
+   * @default false
+   */
   internal?: boolean;
+  /**
+   * Additional AMQP arguments for advanced configuration.
+   * Common arguments include alternate-exchange for handling unroutable messages.
+   */
   arguments?: Record<string, unknown>;
 };
+/**
+ * A fanout exchange definition.
+ *
+ * Fanout exchanges broadcast all messages to all bound queues, ignoring routing keys.
+ * This is the simplest exchange type for pub/sub messaging patterns.
+ *
+ * @example
+ * ```typescript
+ * const logsExchange: FanoutExchangeDefinition = defineExchange('logs', 'fanout', {
+ *   durable: true
+ * });
+ * ```
+ */
 type FanoutExchangeDefinition = BaseExchangeDefinition & {
   type: "fanout";
 };
+/**
+ * A direct exchange definition.
+ *
+ * Direct exchanges route messages to queues based on exact routing key matches.
+ * This is ideal for point-to-point messaging where each message should go to specific queues.
+ *
+ * @example
+ * ```typescript
+ * const tasksExchange: DirectExchangeDefinition = defineExchange('tasks', 'direct', {
+ *   durable: true
+ * });
+ * ```
+ */
 type DirectExchangeDefinition = BaseExchangeDefinition & {
   type: "direct";
 };
+/**
+ * A topic exchange definition.
+ *
+ * Topic exchanges route messages to queues based on routing key patterns with wildcards:
+ * - `*` (star) matches exactly one word
+ * - `#` (hash) matches zero or more words
+ *
+ * Words are separated by dots (e.g., `order.created.high-value`).
+ *
+ * @example
+ * ```typescript
+ * const ordersExchange: TopicExchangeDefinition = defineExchange('orders', 'topic', {
+ *   durable: true
+ * });
+ * // Can be bound with patterns like 'order.*' or 'order.#'
+ * ```
+ */
 type TopicExchangeDefinition = BaseExchangeDefinition & {
   type: "topic";
 };
+/**
+ * Union type of all exchange definitions.
+ *
+ * Represents any type of AMQP exchange: fanout, direct, or topic.
+ */
 type ExchangeDefinition = FanoutExchangeDefinition | DirectExchangeDefinition | TopicExchangeDefinition;
 /**
- * Definition of an AMQP queue
+ * Definition of an AMQP queue.
+ *
+ * A queue stores messages until they are consumed by workers. Queues are bound to exchanges
+ * to receive messages based on routing rules.
  */
 type QueueDefinition = {
+  /**
+   * The name of the queue. Must be unique within the RabbitMQ virtual host.
+   */
   name: string;
+  /**
+   * If true, the queue survives broker restarts. Durable queues are persisted to disk.
+   * @default false
+   */
   durable?: boolean;
+  /**
+   * If true, the queue can only be used by the declaring connection and is deleted when
+   * that connection closes. Exclusive queues are private to the connection.
+   * @default false
+   */
   exclusive?: boolean;
+  /**
+   * If true, the queue is deleted when the last consumer unsubscribes.
+   * @default false
+   */
   autoDelete?: boolean;
+  /**
+   * Additional AMQP arguments for advanced configuration.
+   *
+   * Common arguments include:
+   * - `x-message-ttl`: Message time-to-live in milliseconds
+   * - `x-expires`: Queue expiration time in milliseconds
+   * - `x-max-length`: Maximum number of messages in the queue
+   * - `x-max-length-bytes`: Maximum size of the queue in bytes
+   * - `x-dead-letter-exchange`: Exchange for dead-lettered messages
+   * - `x-dead-letter-routing-key`: Routing key for dead-lettered messages
+   * - `x-max-priority`: Maximum priority level for priority queues
+   *
+   * @example
+   * ```typescript
+   * {
+   *   'x-message-ttl': 86400000, // 24 hours
+   *   'x-dead-letter-exchange': 'dlx',
+   *   'x-max-priority': 10
+   * }
+   * ```
+   */
   arguments?: Record<string, unknown>;
 };
+/**
+ * Definition of a message with typed payload and optional headers.
+ *
+ * @template TPayload - The Standard Schema v1 compatible schema for the message payload
+ * @template THeaders - The Standard Schema v1 compatible schema for the message headers (optional)
+ */
 type MessageDefinition<TPayload extends AnySchema = AnySchema, THeaders extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined> = {
+  /**
+   * The payload schema for validating message content.
+   * Must be a Standard Schema v1 compatible schema (Zod, Valibot, ArkType, etc.).
+   */
   payload: TPayload;
+  /**
+   * Optional headers schema for validating message metadata.
+   * Must be a Standard Schema v1 compatible schema.
+   */
   headers?: THeaders;
+  /**
+   * Brief description of the message for documentation purposes.
+   * Used in AsyncAPI specification generation.
+   */
   summary?: string;
+  /**
+   * Detailed description of the message for documentation purposes.
+   * Used in AsyncAPI specification generation.
+   */
   description?: string;
 };
 /**
- * Binding between queue and exchange
+ * Binding between a queue and an exchange.
+ *
+ * Defines how messages from an exchange should be routed to a queue.
+ * For direct and topic exchanges, a routing key is required.
+ * For fanout exchanges, no routing key is needed as all messages are broadcast.
  */
 type QueueBindingDefinition = {
+  /** Discriminator indicating this is a queue-to-exchange binding */
   type: "queue";
+  /** The queue that will receive messages */
   queue: QueueDefinition;
+  /**
+   * Additional AMQP arguments for the binding.
+   * Can be used for advanced routing scenarios with the headers exchange type.
+   */
   arguments?: Record<string, unknown>;
 } & ({
+  /** Direct or topic exchange requiring a routing key */
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
+  /**
+   * The routing key pattern for message routing.
+   * For direct exchanges: Must match exactly.
+   * For topic exchanges: Can use wildcards (* for one word, # for zero or more words).
+   */
   routingKey: string;
 } | {
+  /** Fanout exchange (no routing key needed) */
   exchange: FanoutExchangeDefinition;
+  /** Fanout exchanges don't use routing keys */
   routingKey?: never;
 });
 /**
- * Binding between exchange and exchange
+ * Binding between two exchanges (exchange-to-exchange routing).
+ *
+ * Defines how messages should be forwarded from a source exchange to a destination exchange.
+ * This allows for more complex routing topologies.
+ *
+ * @example
+ * ```typescript
+ * // Forward high-priority orders to a special processing exchange
+ * const binding: ExchangeBindingDefinition = {
+ *   type: 'exchange',
+ *   source: ordersExchange,
+ *   destination: highPriorityExchange,
+ *   routingKey: 'order.high-priority.*'
+ * };
+ * ```
  */
 type ExchangeBindingDefinition = {
+  /** Discriminator indicating this is an exchange-to-exchange binding */
   type: "exchange";
+  /** The destination exchange that will receive forwarded messages */
   destination: ExchangeDefinition;
+  /**
+   * Additional AMQP arguments for the binding.
+   */
   arguments?: Record<string, unknown>;
 } & ({
+  /** Direct or topic source exchange requiring a routing key */
   source: DirectExchangeDefinition | TopicExchangeDefinition;
+  /**
+   * The routing key pattern for message routing.
+   * Messages matching this pattern will be forwarded to the destination exchange.
+   */
   routingKey: string;
 } | {
+  /** Fanout source exchange (no routing key needed) */
   source: FanoutExchangeDefinition;
+  /** Fanout exchanges don't use routing keys */
   routingKey?: never;
 });
 /**
- * Binding definition - can be either queue-to-exchange or exchange-to-exchange
+ * Union type of all binding definitions.
+ *
+ * A binding can be either:
+ * - Queue-to-exchange binding: Routes messages from an exchange to a queue
+ * - Exchange-to-exchange binding: Forwards messages from one exchange to another
  */
 type BindingDefinition = QueueBindingDefinition | ExchangeBindingDefinition;
 /**
- * Definition of a message publisher
+ * Definition of a message publisher.
+ *
+ * A publisher sends messages to an exchange with automatic schema validation.
+ * The message payload is validated against the schema before being sent to RabbitMQ.
+ *
+ * @template TMessage - The message definition with payload schema
+ *
+ * @example
+ * ```typescript
+ * const publisher: PublisherDefinition = {
+ *   exchange: ordersExchange,
+ *   message: orderMessage,
+ *   routingKey: 'order.created'
+ * };
+ * ```
  */
 type PublisherDefinition<TMessage extends MessageDefinition = MessageDefinition> = {
+  /** The message definition including the payload schema */
   message: TMessage;
 } & ({
+  /** Direct or topic exchange requiring a routing key */
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
+  /**
+   * The routing key for message routing.
+   * Determines which queues will receive the published message.
+   */
   routingKey: string;
 } | {
+  /** Fanout exchange (no routing key needed) */
   exchange: FanoutExchangeDefinition;
+  /** Fanout exchanges don't use routing keys - all bound queues receive the message */
   routingKey?: never;
 });
 /**
- * Definition of a message consumer
+ * Definition of a message consumer.
+ *
+ * A consumer receives and processes messages from a queue with automatic schema validation.
+ * The message payload is validated against the schema before being passed to your handler.
+ *
+ * @template TMessage - The message definition with payload schema
+ *
+ * @example
+ * ```typescript
+ * const consumer: ConsumerDefinition = {
+ *   queue: orderProcessingQueue,
+ *   message: orderMessage
+ * };
+ * ```
  */
 type ConsumerDefinition<TMessage extends MessageDefinition = MessageDefinition> = {
+  /** The queue to consume messages from */
   queue: QueueDefinition;
+  /** The message definition including the payload schema */
   message: TMessage;
-  prefetch?: number;
-  noAck?: boolean;
 };
 /**
- * Contract definition containing all AMQP resources
+ * Complete AMQP contract definition.
+ *
+ * A contract brings together all AMQP resources into a single, type-safe definition.
+ * It defines the complete messaging topology including exchanges, queues, bindings,
+ * publishers, and consumers.
+ *
+ * The contract is used by:
+ * - Clients (TypedAmqpClient) for type-safe message publishing
+ * - Workers (TypedAmqpWorker) for type-safe message consumption
+ * - AsyncAPI generator for documentation
+ *
+ * @example
+ * ```typescript
+ * const contract: ContractDefinition = {
+ *   exchanges: {
+ *     orders: ordersExchange,
+ *   },
+ *   queues: {
+ *     orderProcessing: orderProcessingQueue,
+ *   },
+ *   bindings: {
+ *     orderBinding: orderQueueBinding,
+ *   },
+ *   publishers: {
+ *     orderCreated: orderCreatedPublisher,
+ *   },
+ *   consumers: {
+ *     processOrder: processOrderConsumer,
+ *   },
+ * };
+ * ```
  */
 type ContractDefinition = {
+  /**
+   * Named exchange definitions.
+   * Each key becomes available as a named resource in the contract.
+   */
   exchanges?: Record<string, ExchangeDefinition>;
+  /**
+   * Named queue definitions.
+   * Each key becomes available as a named resource in the contract.
+   */
   queues?: Record<string, QueueDefinition>;
+  /**
+   * Named binding definitions.
+   * Bindings can be queue-to-exchange or exchange-to-exchange.
+   */
   bindings?: Record<string, BindingDefinition>;
+  /**
+   * Named publisher definitions.
+   * Each key becomes a method on the TypedAmqpClient for publishing messages.
+   * The method will be fully typed based on the message schema.
+   */
   publishers?: Record<string, PublisherDefinition>;
+  /**
+   * Named consumer definitions.
+   * Each key requires a corresponding handler in the TypedAmqpWorker.
+   * The handler will be fully typed based on the message schema.
+   */
   consumers?: Record<string, ConsumerDefinition>;
 };
 /**
- * Infer publisher names from a contract
+ * Extract publisher names from a contract.
+ *
+ * This utility type extracts the keys of all publishers defined in a contract.
+ * It's used internally for type inference in the TypedAmqpClient.
+ *
+ * @template TContract - The contract definition
+ * @returns Union of publisher names, or never if no publishers defined
+ *
+ * @example
+ * ```typescript
+ * type PublisherNames = InferPublisherNames<typeof myContract>;
+ * // Result: 'orderCreated' | 'orderUpdated' | 'orderCancelled'
+ * ```
  */
 type InferPublisherNames<TContract extends ContractDefinition> = TContract["publishers"] extends Record<string, unknown> ? keyof TContract["publishers"] : never;
 /**
- * Infer consumer names from a contract
+ * Extract consumer names from a contract.
+ *
+ * This utility type extracts the keys of all consumers defined in a contract.
+ * It's used internally for type inference in the TypedAmqpWorker.
+ *
+ * @template TContract - The contract definition
+ * @returns Union of consumer names, or never if no consumers defined
+ *
+ * @example
+ * ```typescript
+ * type ConsumerNames = InferConsumerNames<typeof myContract>;
+ * // Result: 'processOrder' | 'sendNotification' | 'updateInventory'
+ * ```
  */
 type InferConsumerNames<TContract extends ContractDefinition> = TContract["consumers"] extends Record<string, unknown> ? keyof TContract["consumers"] : never;
+//#endregion
+//#region src/builder.d.ts
 /**
- * Infer the TypeScript type from a schema
- */
-type InferSchemaInput<TSchema extends AnySchema> = TSchema extends StandardSchemaV1<infer TInput> ? TInput : never;
-/**
- * Infer publisher message input type
- */
-type PublisherInferInput<TPublisher extends PublisherDefinition> = InferSchemaInput<TPublisher["message"]["payload"]>;
-/**
- * Infer all publishers from contract
- */
-type InferPublishers<TContract extends ContractDefinition> = NonNullable<TContract["publishers"]>;
-/**
- * Get specific publisher definition from contract
- */
-type InferPublisher<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = InferPublishers<TContract>[TName];
-/**
- * Infer publisher input type (message payload) for a specific publisher in a contract
- */
-type ClientInferPublisherInput<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = PublisherInferInput<InferPublisher<TContract, TName>>;
-/**
- * Infer all consumers from contract
- */
-type InferConsumers<TContract extends ContractDefinition> = NonNullable<TContract["consumers"]>;
-/**
- * Get specific consumer definition from contract
- */
-type InferConsumer<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = InferConsumers<TContract>[TName];
-/**
- * Infer consumer message input type
- */
-type ConsumerInferInput<TConsumer extends ConsumerDefinition> = InferSchemaInput<TConsumer["message"]["payload"]>;
-/**
- * Worker perspective types - for consuming messages
+ * Define a fanout exchange.
+ *
+ * A fanout exchange routes messages to all bound queues without considering routing keys.
+ * This exchange type is ideal for broadcasting messages to multiple consumers.
+ *
+ * @param name - The name of the exchange
+ * @param type - Must be "fanout"
+ * @param options - Optional exchange configuration
+ * @param options.durable - If true, the exchange survives broker restarts (default: false)
+ * @param options.autoDelete - If true, the exchange is deleted when no queues are bound (default: false)
+ * @param options.internal - If true, the exchange cannot be directly published to (default: false)
+ * @param options.arguments - Additional AMQP arguments for the exchange
+ * @returns A fanout exchange definition
+ *
+ * @example
+ * ```typescript
+ * const logsExchange = defineExchange('logs', 'fanout', {
+ *   durable: true
+ * });
+ * ```
  */
-type WorkerInferConsumerInput<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = ConsumerInferInput<InferConsumer<TContract, TName>>;
+declare function defineExchange(name: string, type: "fanout", options?: Omit<BaseExchangeDefinition, "name" | "type">): FanoutExchangeDefinition;
 /**
- * Infer consumer handler type for a specific consumer
+ * Define a direct exchange.
+ *
+ * A direct exchange routes messages to queues based on exact routing key matches.
+ * This exchange type is ideal for point-to-point messaging.
+ *
+ * @param name - The name of the exchange
+ * @param type - Must be "direct"
+ * @param options - Optional exchange configuration
+ * @param options.durable - If true, the exchange survives broker restarts (default: false)
+ * @param options.autoDelete - If true, the exchange is deleted when no queues are bound (default: false)
+ * @param options.internal - If true, the exchange cannot be directly published to (default: false)
+ * @param options.arguments - Additional AMQP arguments for the exchange
+ * @returns A direct exchange definition
+ *
+ * @example
+ * ```typescript
+ * const tasksExchange = defineExchange('tasks', 'direct', {
+ *   durable: true
+ * });
+ * ```
  */
-type WorkerInferConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Promise<void> | void;
+declare function defineExchange(name: string, type: "direct", options?: Omit<BaseExchangeDefinition, "name" | "type">): DirectExchangeDefinition;
 /**
- * Infer all consumer handlers for a contract
+ * Define a topic exchange.
+ *
+ * A topic exchange routes messages to queues based on routing key patterns.
+ * Routing keys can use wildcards: `*` matches one word, `#` matches zero or more words.
+ * This exchange type is ideal for flexible message routing based on hierarchical topics.
+ *
+ * @param name - The name of the exchange
+ * @param type - Must be "topic"
+ * @param options - Optional exchange configuration
+ * @param options.durable - If true, the exchange survives broker restarts (default: false)
+ * @param options.autoDelete - If true, the exchange is deleted when no queues are bound (default: false)
+ * @param options.internal - If true, the exchange cannot be directly published to (default: false)
+ * @param options.arguments - Additional AMQP arguments for the exchange
+ * @returns A topic exchange definition
+ *
+ * @example
+ * ```typescript
+ * const ordersExchange = defineExchange('orders', 'topic', {
+ *   durable: true
+ * });
+ * ```
  */
-type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandler<TContract, K> };
-//#endregion
-//#region src/builder.d.ts
-declare function defineExchange(name: string, type: "fanout", options?: Omit<BaseExchangeDefinition, "name" | "type">): FanoutExchangeDefinition;
-declare function defineExchange(name: string, type: "direct", options?: Omit<BaseExchangeDefinition, "name" | "type">): DirectExchangeDefinition;
 declare function defineExchange(name: string, type: "topic", options?: Omit<BaseExchangeDefinition, "name" | "type">): TopicExchangeDefinition;
 /**
- * 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'
+ *   }
+ * });
+ * ```
  */
 declare function defineQueue(name: string, options?: Omit<QueueDefinition, "name">): QueueDefinition;
 /**
- * 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'
+ *   }
+ * );
+ * ```
  */
 declare function defineMessage<TPayload extends MessageDefinition["payload"], THeaders extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined>(payload: TPayload, options?: {
   headers?: THeaders;
@@ -175,8 +550,24 @@ declare function defineMessage<TPayload extends MessageDefinition["payload"], TH
   description?: string;
 }): MessageDefinition<TPayload, THeaders>;
 /**
- * Define a binding between queue and fanout exchange (exchange -> queue)
- * Fanout exchanges don't use routing keys
+ * Define a binding between a queue and a fanout exchange.
+ *
+ * Binds a queue to a fanout exchange to receive all messages published to the exchange.
+ * Fanout exchanges ignore routing keys, so this overload doesn't require one.
+ *
+ * @param queue - The queue definition to bind
+ * @param exchange - The fanout exchange definition
+ * @param options - Optional binding configuration
+ * @param options.arguments - Additional AMQP arguments for the binding
+ * @returns A queue binding definition
+ *
+ * @example
+ * ```typescript
+ * const logsQueue = defineQueue('logs-queue', { durable: true });
+ * const logsExchange = defineExchange('logs', 'fanout', { durable: true });
+ *
+ * const binding = defineQueueBinding(logsQueue, logsExchange);
+ * ```
  */
 declare function defineQueueBinding(queue: QueueDefinition, exchange: FanoutExchangeDefinition, options?: Omit<Extract<QueueBindingDefinition, {
   exchange: FanoutExchangeDefinition;
@@ -184,8 +575,38 @@ declare function defineQueueBinding(queue: QueueDefinition, exchange: FanoutExch
   exchange: FanoutExchangeDefinition;
 }>;
 /**
- * Define a binding between queue and direct/topic exchange (exchange -> queue)
- * Direct and topic exchanges require a routing key
+ * Define a binding between a queue and a direct or topic exchange.
+ *
+ * Binds a queue to an exchange with a specific routing key pattern.
+ * Messages are only routed to the queue if the routing key matches the pattern.
+ *
+ * For direct exchanges: The routing key must match exactly.
+ * For topic exchanges: The routing key can include wildcards:
+ * - `*` matches exactly one word
+ * - `#` matches zero or more words
+ *
+ * @param queue - The queue definition to bind
+ * @param exchange - The direct or topic exchange definition
+ * @param options - Binding configuration (routingKey is required)
+ * @param options.routingKey - The routing key pattern for message routing
+ * @param options.arguments - Additional AMQP arguments for the binding
+ * @returns A queue binding definition
+ *
+ * @example
+ * ```typescript
+ * const orderQueue = defineQueue('order-processing', { durable: true });
+ * const ordersExchange = defineExchange('orders', 'topic', { durable: true });
+ *
+ * // Bind with exact routing key
+ * const binding = defineQueueBinding(orderQueue, ordersExchange, {
+ *   routingKey: 'order.created'
+ * });
+ *
+ * // Bind with wildcard pattern
+ * const allOrdersBinding = defineQueueBinding(orderQueue, ordersExchange, {
+ *   routingKey: 'order.*'  // Matches order.created, order.updated, etc.
+ * });
+ * ```
  */
 declare function defineQueueBinding(queue: QueueDefinition, exchange: DirectExchangeDefinition | TopicExchangeDefinition, options: Omit<Extract<QueueBindingDefinition, {
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
@@ -193,8 +614,25 @@ declare function defineQueueBinding(queue: QueueDefinition, exchange: DirectExch
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
 }>;
 /**
- * Define a binding between fanout exchange and exchange (source -> destination)
- * Fanout exchanges don't use routing keys
+ * Define a binding between two exchanges (exchange-to-exchange routing).
+ *
+ * Binds a destination exchange to a fanout source exchange.
+ * Messages published to the source exchange will be forwarded to the destination exchange.
+ * Fanout exchanges ignore routing keys, so this overload doesn't require one.
+ *
+ * @param destination - The destination exchange definition
+ * @param source - The fanout source exchange definition
+ * @param options - Optional binding configuration
+ * @param options.arguments - Additional AMQP arguments for the binding
+ * @returns An exchange binding definition
+ *
+ * @example
+ * ```typescript
+ * const sourceExchange = defineExchange('logs', 'fanout', { durable: true });
+ * const destExchange = defineExchange('all-logs', 'fanout', { durable: true });
+ *
+ * const binding = defineExchangeBinding(destExchange, sourceExchange);
+ * ```
  */
 declare function defineExchangeBinding(destination: ExchangeDefinition, source: FanoutExchangeDefinition, options?: Omit<Extract<ExchangeBindingDefinition, {
   source: FanoutExchangeDefinition;
@@ -202,8 +640,28 @@ declare function defineExchangeBinding(destination: ExchangeDefinition, source:
   source: FanoutExchangeDefinition;
 }>;
 /**
- * Define a binding between direct/topic exchange and exchange (source -> destination)
- * Direct and topic exchanges require a routing key
+ * Define a binding between two exchanges (exchange-to-exchange routing).
+ *
+ * Binds a destination exchange to a direct or topic source exchange with a routing key pattern.
+ * Messages are forwarded from source to destination only if the routing key matches the pattern.
+ *
+ * @param destination - The destination exchange definition
+ * @param source - The direct or topic source exchange definition
+ * @param options - Binding configuration (routingKey is required)
+ * @param options.routingKey - The routing key pattern for message routing
+ * @param options.arguments - Additional AMQP arguments for the binding
+ * @returns An exchange binding definition
+ *
+ * @example
+ * ```typescript
+ * const ordersExchange = defineExchange('orders', 'topic', { durable: true });
+ * const importantExchange = defineExchange('important-orders', 'topic', { durable: true });
+ *
+ * // Forward only high-value orders
+ * const binding = defineExchangeBinding(importantExchange, ordersExchange, {
+ *   routingKey: 'order.high-value.*'
+ * });
+ * ```
  */
 declare function defineExchangeBinding(destination: ExchangeDefinition, source: DirectExchangeDefinition | TopicExchangeDefinition, options: Omit<Extract<ExchangeBindingDefinition, {
   source: DirectExchangeDefinition | TopicExchangeDefinition;
@@ -211,8 +669,33 @@ declare function defineExchangeBinding(destination: ExchangeDefinition, source:
   source: DirectExchangeDefinition | TopicExchangeDefinition;
 }>;
 /**
- * Define a message publisher for fanout exchange
- * Fanout exchanges don't use routing keys
+ * Define a message publisher for a fanout exchange.
+ *
+ * A publisher sends messages to an exchange. For fanout exchanges, messages are broadcast
+ * to all bound queues regardless of routing key, so no routing key is required.
+ *
+ * The message schema is validated when publishing to ensure type safety.
+ *
+ * @param exchange - The fanout exchange definition to publish to
+ * @param message - The message definition with payload schema
+ * @param options - Optional publisher configuration
+ * @returns A publisher definition with inferred message types
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const logsExchange = defineExchange('logs', 'fanout', { durable: true });
+ * const logMessage = defineMessage(
+ *   z.object({
+ *     level: z.enum(['info', 'warn', 'error']),
+ *     message: z.string(),
+ *     timestamp: z.string().datetime(),
+ *   })
+ * );
+ *
+ * const logPublisher = definePublisher(logsExchange, logMessage);
+ * ```
  */
 declare function definePublisher<TMessage extends MessageDefinition>(exchange: FanoutExchangeDefinition, message: TMessage, options?: Omit<Extract<PublisherDefinition<TMessage>, {
   exchange: FanoutExchangeDefinition;
@@ -220,8 +703,39 @@ declare function definePublisher<TMessage extends MessageDefinition>(exchange: F
   exchange: FanoutExchangeDefinition;
 }>;
 /**
- * Define a message publisher for direct/topic exchange
- * Direct and topic exchanges require a routing key
+ * Define a message publisher for a direct or topic exchange.
+ *
+ * A publisher sends messages to an exchange with a specific routing key.
+ * The routing key determines which queues receive the message.
+ *
+ * The message schema is validated when publishing to ensure type safety.
+ *
+ * @param exchange - The direct or topic exchange definition to publish to
+ * @param message - The message definition with payload schema
+ * @param options - Publisher configuration (routingKey is required)
+ * @param options.routingKey - The routing key for message routing
+ * @returns A publisher definition with inferred message types
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const ordersExchange = defineExchange('orders', 'topic', { durable: true });
+ * const orderMessage = defineMessage(
+ *   z.object({
+ *     orderId: z.string().uuid(),
+ *     amount: z.number().positive(),
+ *   }),
+ *   {
+ *     summary: 'Order created event',
+ *     description: 'Emitted when a new order is created'
+ *   }
+ * );
+ *
+ * const orderCreatedPublisher = definePublisher(ordersExchange, orderMessage, {
+ *   routingKey: 'order.created'
+ * });
+ * ```
  */
 declare function definePublisher<TMessage extends MessageDefinition>(exchange: DirectExchangeDefinition | TopicExchangeDefinition, message: TMessage, options: Omit<Extract<PublisherDefinition<TMessage>, {
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
@@ -229,13 +743,118 @@ declare function definePublisher<TMessage extends MessageDefinition>(exchange: D
   exchange: DirectExchangeDefinition | TopicExchangeDefinition;
 }>;
 /**
- * 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
+ * // });
+ * ```
  */
 declare function defineConsumer<TMessage extends MessageDefinition>(queue: QueueDefinition, message: TMessage, options?: Omit<ConsumerDefinition<TMessage>, "queue" | "message">): ConsumerDefinition<TMessage>;
 /**
- * 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
+ * ```
  */
 declare function defineContract<TContract extends ContractDefinition>(definition: TContract): TContract;
 //#endregion
-export { type AnySchema, type BaseExchangeDefinition, type BindingDefinition, type ClientInferPublisherInput, type ConsumerDefinition, type ContractDefinition, type DirectExchangeDefinition, type ExchangeBindingDefinition, type ExchangeDefinition, type FanoutExchangeDefinition, type InferConsumerNames, type InferPublisherNames, type MessageDefinition, type PublisherDefinition, type QueueBindingDefinition, type QueueDefinition, type TopicExchangeDefinition, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineConsumer, defineContract, defineExchange, defineExchangeBinding, defineMessage, definePublisher, defineQueue, defineQueueBinding };
+export { type AnySchema, type BaseExchangeDefinition, type BindingDefinition, type ConsumerDefinition, type ContractDefinition, type DirectExchangeDefinition, type ExchangeBindingDefinition, type ExchangeDefinition, type FanoutExchangeDefinition, type InferConsumerNames, type InferPublisherNames, type MessageDefinition, type PublisherDefinition, type QueueBindingDefinition, type QueueDefinition, type TopicExchangeDefinition, defineConsumer, defineContract, defineExchange, defineExchangeBinding, defineMessage, definePublisher, defineQueue, defineQueueBinding };
 //# sourceMappingURL=index.d.mts.map