@amqp-contract/contract 0.1.4 → 0.2.1

package/dist/index.d.cts

@@ -3,198 +3,858 @@ 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;
 /**
- * Exchange types supported by AMQP
+ * 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 ExchangeType = "direct" | "fanout" | "topic" | "headers";
-/**
- * Definition of an AMQP exchange
- */
-interface ExchangeDefinition {
+type BaseExchangeDefinition = {
+  /**
+   * The name of the exchange. Must be unique within the RabbitMQ virtual host.
+   */
   name: string;
-  type: ExchangeType;
+  /**
+   * 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>;
-}
-/**
- * Definition of an AMQP queue
- */
-interface QueueDefinition {
+};
+/**
+ * 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.
+ *
+ * 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>;
-}
-/**
- * Binding between queue and exchange
- */
-interface QueueBindingDefinition {
+};
+/**
+ * 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 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";
-  queue: string;
-  exchange: string;
-  routingKey?: string;
+  /** 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>;
-}
-/**
- * Binding between exchange and exchange
- */
-interface ExchangeBindingDefinition {
+} & ({
+  /** 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 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";
-  source: string;
-  destination: string;
-  routingKey?: string;
+  /** The destination exchange that will receive forwarded messages */
+  destination: ExchangeDefinition;
+  /**
+   * Additional AMQP arguments for the binding.
+   */
   arguments?: Record<string, unknown>;
-}
-/**
- * Binding definition - can be either queue-to-exchange or exchange-to-exchange
+} & ({
+  /** 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;
+});
+/**
+ * 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
- */
-interface PublisherDefinition<TMessageSchema extends AnySchema = AnySchema> {
-  exchange: string;
-  routingKey?: string;
-  message: TMessageSchema;
-}
-/**
- * Definition of a message consumer
- */
-interface ConsumerDefinition<TMessageSchema extends AnySchema = AnySchema, THandlerResultSchema extends AnySchema = AnySchema> {
-  queue: string;
-  message: TMessageSchema;
-  handlerResult?: THandlerResultSchema;
-  prefetch?: number;
-  noAck?: boolean;
-}
-/**
- * Contract definition containing all AMQP resources
- */
-interface ContractDefinition<TExchanges extends Record<string, ExchangeDefinition> = Record<string, ExchangeDefinition>, TQueues extends Record<string, QueueDefinition> = Record<string, QueueDefinition>, TBindings extends Record<string, BindingDefinition> = Record<string, BindingDefinition>, TPublishers extends Record<string, PublisherDefinition> = Record<string, PublisherDefinition>, TConsumers extends Record<string, ConsumerDefinition> = Record<string, ConsumerDefinition>> {
-  exchanges?: TExchanges;
-  queues?: TQueues;
-  bindings?: TBindings;
-  publishers?: TPublishers;
-  consumers?: TConsumers;
-}
-/**
- * Infer the TypeScript type from a schema
- */
-type InferSchemaInput<TSchema extends AnySchema> = TSchema extends StandardSchemaV1<infer TInput> ? TInput : never;
-/**
- * Infer the output type from a schema
- */
-type InferSchemaOutput<TSchema extends AnySchema> = TSchema extends StandardSchemaV1<unknown, infer TOutput> ? TOutput : never;
-/**
- * Infer publisher message input type
- */
-type PublisherInferInput<TPublisher extends PublisherDefinition> = InferSchemaInput<TPublisher["message"]>;
-/**
- * Infer consumer message input type
- */
-type ConsumerInferInput<TConsumer extends ConsumerDefinition> = InferSchemaInput<TConsumer["message"]>;
-/**
- * Infer consumer handler result type
- */
-type ConsumerInferHandlerResult<TConsumer extends ConsumerDefinition> = TConsumer["handlerResult"] extends AnySchema ? InferSchemaOutput<TConsumer["handlerResult"]> : void;
-/**
- * Consumer handler function type
- * Handlers return Promise for async handling
- * where HandlerResult is inferred from the consumer's handlerResult schema (defaults to void)
- */
-type ConsumerHandler<TConsumer extends ConsumerDefinition> = (message: ConsumerInferInput<TConsumer>) => Promise<ConsumerInferHandlerResult<TConsumer>>;
-/**
- * Infer all publishers from contract
- */
-type InferPublishers<TContract extends ContractDefinition> = NonNullable<TContract["publishers"]>;
-/**
- * Infer all consumers from contract
- */
-type InferConsumers<TContract extends ContractDefinition> = NonNullable<TContract["consumers"]>;
-/**
- * Infer publisher names from contract
- */
-type InferPublisherNames<TContract extends ContractDefinition> = keyof InferPublishers<TContract>;
-/**
- * Infer consumer names from contract
- */
-type InferConsumerNames<TContract extends ContractDefinition> = keyof InferConsumers<TContract>;
-/**
- * Get specific publisher definition from contract
- */
-type InferPublisher<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = InferPublishers<TContract>[TName];
-/**
- * Get specific consumer definition from contract
- */
-type InferConsumer<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = InferConsumers<TContract>[TName];
-/**
- * Client perspective types - for publishing messages
- */
-type ClientInferPublisherInput<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = PublisherInferInput<InferPublisher<TContract, TName>>;
-/**
- * Worker perspective types - for consuming messages
- */
-type WorkerInferConsumerInput<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = ConsumerInferInput<InferConsumer<TContract, TName>>;
-/**
- * Worker perspective - consumer handler result type
- */
-type WorkerInferConsumerHandlerResult<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = ConsumerInferHandlerResult<InferConsumer<TContract, TName>>;
-/**
- * Worker perspective - consumer handler type
- */
-type WorkerInferConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = ConsumerHandler<InferConsumer<TContract, TName>>;
-/**
- * Map of all consumer handlers for a contract
- */
-type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandler<TContract, K> };
+ * 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.
+ *
+ * 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;
+};
+/**
+ * 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>;
+};
+/**
+ * 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;
+/**
+ * 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
 /**
- * Message schema with metadata
- */
-interface MessageSchema<TSchema extends AnySchema = AnySchema> extends AnySchema {
-  readonly name: string;
-  readonly schema: TSchema;
-  readonly "~standard": TSchema["~standard"];
-}
-/**
- * Define a message schema with metadata
- */
-declare function defineMessage<TSchema extends AnySchema>(name: string, schema: TSchema): MessageSchema<TSchema>;
-/**
- * Define an AMQP exchange
- */
-declare function defineExchange(name: string, type: ExchangeType, options?: Omit<ExchangeDefinition, "name" | "type">): ExchangeDefinition;
-/**
- * Define an AMQP queue
+ * 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
+ * });
+ * ```
+ */
+declare function defineExchange(name: string, type: "fanout", options?: Omit<BaseExchangeDefinition, "name" | "type">): FanoutExchangeDefinition;
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function defineExchange(name: string, type: "direct", options?: Omit<BaseExchangeDefinition, "name" | "type">): DirectExchangeDefinition;
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function defineExchange(name: string, type: "topic", options?: Omit<BaseExchangeDefinition, "name" | "type">): TopicExchangeDefinition;
+/**
+ * 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 binding between queue and exchange
- */
-declare function defineBinding(queue: string, exchange: string, options?: Omit<QueueBindingDefinition, "type" | "queue" | "exchange">): QueueBindingDefinition;
-/**
- * Define a binding between exchange and exchange (source -> destination)
- */
-declare function defineExchangeBinding(destination: string, source: string, options?: Omit<ExchangeBindingDefinition, "type" | "source" | "destination">): ExchangeBindingDefinition;
-/**
- * Define a message publisher
- */
-declare function definePublisher<TMessageSchema extends AnySchema>(exchange: string, message: TMessageSchema, options?: Omit<PublisherDefinition<TMessageSchema>, "exchange" | "message">): PublisherDefinition<TMessageSchema>;
-/**
- * Define a message consumer
- */
-declare function defineConsumer<TMessageSchema extends AnySchema, THandlerResultSchema extends AnySchema = AnySchema>(queue: string, message: TMessageSchema, options?: Omit<ConsumerDefinition<TMessageSchema, THandlerResultSchema>, "queue" | "message">): ConsumerDefinition<TMessageSchema, THandlerResultSchema>;
-/**
- * Define an AMQP contract
- */
-declare function defineContract<TContract extends ContractDefinition<TExchanges, TQueues, TBindings, TPublishers, TConsumers>, TExchanges extends Record<string, ExchangeDefinition> = Record<string, ExchangeDefinition>, TQueues extends Record<string, QueueDefinition> = Record<string, QueueDefinition>, TBindings extends Record<string, BindingDefinition> = Record<string, BindingDefinition>, TPublishers extends Record<string, PublisherDefinition> = Record<string, PublisherDefinition>, TConsumers extends Record<string, ConsumerDefinition> = Record<string, ConsumerDefinition>>(definition: TContract): TContract;
+ * 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;
+  summary?: string;
+  description?: string;
+}): MessageDefinition<TPayload, THeaders>;
+/**
+ * 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;
+}>, "type" | "queue" | "exchange" | "routingKey">): Extract<QueueBindingDefinition, {
+  exchange: FanoutExchangeDefinition;
+}>;
+/**
+ * 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;
+}>, "type" | "queue" | "exchange">): Extract<QueueBindingDefinition, {
+  exchange: DirectExchangeDefinition | TopicExchangeDefinition;
+}>;
+/**
+ * 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;
+}>, "type" | "source" | "destination" | "routingKey">): Extract<ExchangeBindingDefinition, {
+  source: FanoutExchangeDefinition;
+}>;
+/**
+ * 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;
+}>, "type" | "source" | "destination">): Extract<ExchangeBindingDefinition, {
+  source: DirectExchangeDefinition | TopicExchangeDefinition;
+}>;
+/**
+ * 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;
+}>, "exchange" | "message" | "routingKey">): Extract<PublisherDefinition<TMessage>, {
+  exchange: FanoutExchangeDefinition;
+}>;
+/**
+ * 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;
+}>, "exchange" | "message">): Extract<PublisherDefinition<TMessage>, {
+  exchange: DirectExchangeDefinition | TopicExchangeDefinition;
+}>;
+/**
+ * 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.
+ *
+ * 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 BindingDefinition, type ClientInferPublisherInput, type ConsumerDefinition, type ConsumerHandler, type ConsumerInferHandlerResult, type ConsumerInferInput, type ContractDefinition, type ExchangeBindingDefinition, type ExchangeDefinition, type ExchangeType, type InferConsumer, type InferConsumerNames, type InferConsumers, type InferPublisher, type InferPublisherNames, type InferPublishers, type InferSchemaInput, type InferSchemaOutput, type MessageSchema, type PublisherDefinition, type PublisherInferInput, type QueueBindingDefinition, type QueueDefinition, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlerResult, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineBinding, defineConsumer, defineContract, defineExchange, defineExchangeBinding, defineMessage, definePublisher, defineQueue };
+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.cts.map