@amqp-contract/contract 0.3.5 → 0.5.0

package/docs/index.md

@@ -12,7 +12,7 @@
 type AnySchema = StandardSchemaV1;
 ```
 
-Defined in: [types.ts:12](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L12)
+Defined in: [types.ts:12](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L12)
 
 Any schema that conforms to Standard Schema v1.
 
@@ -32,7 +32,7 @@ https://github.com/standard-schema/standard-schema
 type BaseExchangeDefinition = object;
 ```
 
-Defined in: [types.ts:20](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L20)
+Defined in: [types.ts:20](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L20)
 
 Base definition of an AMQP exchange.
 
@@ -43,11 +43,11 @@ type and routing rules. This type contains properties common to all exchange typ
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="arguments"></a> `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for advanced configuration. Common arguments include alternate-exchange for handling unroutable messages. | [types.ts:49](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L49) |
-| <a id="autodelete"></a> `autoDelete?` | `boolean` | If true, the exchange is deleted when all queues have finished using it. **Default** `false` | [types.ts:36](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L36) |
-| <a id="durable"></a> `durable?` | `boolean` | If true, the exchange survives broker restarts. Durable exchanges are persisted to disk. **Default** `false` | [types.ts:30](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L30) |
-| <a id="internal"></a> `internal?` | `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` | [types.ts:43](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L43) |
-| <a id="name"></a> `name` | `string` | The name of the exchange. Must be unique within the RabbitMQ virtual host. | [types.ts:24](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L24) |
+| <a id="arguments"></a> `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for advanced configuration. Common arguments include alternate-exchange for handling unroutable messages. | [types.ts:49](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L49) |
+| <a id="autodelete"></a> `autoDelete?` | `boolean` | If true, the exchange is deleted when all queues have finished using it. **Default** `false` | [types.ts:36](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L36) |
+| <a id="durable"></a> `durable?` | `boolean` | If true, the exchange survives broker restarts. Durable exchanges are persisted to disk. **Default** `false` | [types.ts:30](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L30) |
+| <a id="internal"></a> `internal?` | `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` | [types.ts:43](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L43) |
+| <a id="name"></a> `name` | `string` | The name of the exchange. Must be unique within the RabbitMQ virtual host. | [types.ts:24](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L24) |
 
 ***
 
@@ -59,7 +59,7 @@ type BindingDefinition =
   | ExchangeBindingDefinition;
 ```
 
-Defined in: [types.ts:298](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L298)
+Defined in: [types.ts:298](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L298)
 
 Union type of all binding definitions.
 
@@ -69,13 +69,48 @@ A binding can be either:
 
 ***
 
+### BindingPattern
+
+```ts
+type BindingPattern<S> = S extends "" ? never : S;
+```
+
+Defined in: [builder.ts:805](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L805)
+
+Type-safe binding pattern that validates basic format and wildcards.
+
+Validates that a binding pattern follows basic AMQP binding pattern rules:
+- Can contain wildcards (* for one word, # for zero or more words)
+- Must not be empty
+- Should contain alphanumeric characters, dots, hyphens, underscores, and wildcards
+
+Note: Full character-by-character validation is not performed to avoid TypeScript
+recursion depth limits. Runtime validation is still recommended.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `S` *extends* `string` | The binding pattern string to validate |
+
+#### Example
+
+```typescript
+type ValidPattern = BindingPattern<"order.*">; // "order.*"
+type ValidHash = BindingPattern<"order.#">; // "order.#"
+type ValidConcrete = BindingPattern<"order.created">; // "order.created"
+type Invalid = BindingPattern<"">; // never (empty string)
+```
+
+***
+
 ### ConsumerDefinition
 
 ```ts
 type ConsumerDefinition<TMessage> = object;
 ```
 
-Defined in: [types.ts:354](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L354)
+Defined in: [types.ts:354](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L354)
 
 Definition of a message consumer.
 
@@ -101,8 +136,70 @@ const consumer: ConsumerDefinition = {
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="message"></a> `message` | `TMessage` | The message definition including the payload schema | [types.ts:359](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L359) |
-| <a id="queue"></a> `queue` | [`QueueDefinition`](#queuedefinition) | The queue to consume messages from | [types.ts:356](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L356) |
+| <a id="message"></a> `message` | `TMessage` | The message definition including the payload schema | [types.ts:359](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L359) |
+| <a id="queue"></a> `queue` | [`QueueDefinition`](#queuedefinition) | The queue to consume messages from | [types.ts:356](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L356) |
+
+***
+
+### ConsumerFirstResult
+
+```ts
+type ConsumerFirstResult<TMessage, TConsumer, TBinding> = object;
+```
+
+Defined in: [builder.ts:1182](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1182)
+
+Consumer-first builder result for fanout and direct exchanges.
+
+This type represents a consumer with its binding and provides a method to create
+a publisher that uses the same message schema and routing key.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TMessage` *extends* [`MessageDefinition`](#messagedefinition) | The message definition |
+| `TConsumer` *extends* [`ConsumerDefinition`](#consumerdefinition)\<`TMessage`\> | The consumer definition |
+| `TBinding` *extends* [`QueueBindingDefinition`](#queuebindingdefinition) | The queue binding definition |
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="binding"></a> `binding` | `TBinding` | The binding definition connecting the exchange to the queue | [builder.ts:1190](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1190) |
+| <a id="consumer"></a> `consumer` | `TConsumer` | The consumer definition | [builder.ts:1188](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1188) |
+| <a id="createpublisher"></a> `createPublisher` | () => `TBinding`\[`"exchange"`\] *extends* [`FanoutExchangeDefinition`](#fanoutexchangedefinition) ? `Extract`\<[`PublisherDefinition`](#publisherdefinition)\<`TMessage`\>, \{ `exchange`: [`FanoutExchangeDefinition`](#fanoutexchangedefinition); \}\> : `Extract`\<[`PublisherDefinition`](#publisherdefinition)\<`TMessage`\>, \{ `exchange`: \| [`DirectExchangeDefinition`](#directexchangedefinition) \| [`TopicExchangeDefinition`](#topicexchangedefinition); \}\> | Create a publisher that sends messages to this consumer. The publisher will automatically use the same message schema and routing key. | [builder.ts:1197](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1197) |
+
+***
+
+### ConsumerFirstResultWithRoutingKey
+
+```ts
+type ConsumerFirstResultWithRoutingKey<TMessage, TConsumer, TBinding> = object;
+```
+
+Defined in: [builder.ts:1215](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1215)
+
+Consumer-first builder result for topic exchanges.
+
+This type represents a consumer with its binding (which may use a pattern) and provides
+a method to create a publisher with a concrete routing key that matches the pattern.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TMessage` *extends* [`MessageDefinition`](#messagedefinition) | The message definition |
+| `TConsumer` *extends* [`ConsumerDefinition`](#consumerdefinition)\<`TMessage`\> | The consumer definition |
+| `TBinding` *extends* [`QueueBindingDefinition`](#queuebindingdefinition) | The queue binding definition |
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="binding-1"></a> `binding` | `TBinding` | The binding definition connecting the exchange to the queue | [builder.ts:1223](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1223) |
+| <a id="consumer-1"></a> `consumer` | `TConsumer` | The consumer definition | [builder.ts:1221](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1221) |
+| <a id="createpublisher-1"></a> `createPublisher` | \<`TPublisherRoutingKey`\>(`routingKey`) => `Extract`\<[`PublisherDefinition`](#publisherdefinition)\<`TMessage`\>, \{ `exchange`: \| [`DirectExchangeDefinition`](#directexchangedefinition) \| [`TopicExchangeDefinition`](#topicexchangedefinition); \}\> | Create a publisher that sends messages to this consumer. For topic exchanges, the routing key can be specified to match the binding pattern. | [builder.ts:1231](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L1231) |
 
 ***
 
@@ -112,7 +209,7 @@ const consumer: ConsumerDefinition = {
 type ContractDefinition = object;
 ```
 
-Defined in: [types.ts:395](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L395)
+Defined in: [types.ts:395](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L395)
 
 Complete AMQP contract definition.
 
@@ -151,11 +248,11 @@ const contract: ContractDefinition = {
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="bindings"></a> `bindings?` | `Record`\<`string`, [`BindingDefinition`](#bindingdefinition)\> | Named binding definitions. Bindings can be queue-to-exchange or exchange-to-exchange. | [types.ts:412](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L412) |
-| <a id="consumers"></a> `consumers?` | `Record`\<`string`, [`ConsumerDefinition`](#consumerdefinition)\> | Named consumer definitions. Each key requires a corresponding handler in the TypedAmqpWorker. The handler will be fully typed based on the message schema. | [types.ts:426](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L426) |
-| <a id="exchanges"></a> `exchanges?` | `Record`\<`string`, [`ExchangeDefinition`](#exchangedefinition)\> | Named exchange definitions. Each key becomes available as a named resource in the contract. | [types.ts:400](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L400) |
-| <a id="publishers"></a> `publishers?` | `Record`\<`string`, [`PublisherDefinition`](#publisherdefinition)\> | 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. | [types.ts:419](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L419) |
-| <a id="queues"></a> `queues?` | `Record`\<`string`, [`QueueDefinition`](#queuedefinition)\> | Named queue definitions. Each key becomes available as a named resource in the contract. | [types.ts:406](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L406) |
+| <a id="bindings"></a> `bindings?` | `Record`\<`string`, [`BindingDefinition`](#bindingdefinition)\> | Named binding definitions. Bindings can be queue-to-exchange or exchange-to-exchange. | [types.ts:412](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L412) |
+| <a id="consumers"></a> `consumers?` | `Record`\<`string`, [`ConsumerDefinition`](#consumerdefinition)\> | Named consumer definitions. Each key requires a corresponding handler in the TypedAmqpWorker. The handler will be fully typed based on the message schema. | [types.ts:426](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L426) |
+| <a id="exchanges"></a> `exchanges?` | `Record`\<`string`, [`ExchangeDefinition`](#exchangedefinition)\> | Named exchange definitions. Each key becomes available as a named resource in the contract. | [types.ts:400](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L400) |
+| <a id="publishers"></a> `publishers?` | `Record`\<`string`, [`PublisherDefinition`](#publisherdefinition)\> | 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. | [types.ts:419](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L419) |
+| <a id="queues"></a> `queues?` | `Record`\<`string`, [`QueueDefinition`](#queuedefinition)\> | Named queue definitions. Each key becomes available as a named resource in the contract. | [types.ts:406](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L406) |
 
 ***
 
@@ -165,7 +262,7 @@ const contract: ContractDefinition = {
 type DirectExchangeDefinition = BaseExchangeDefinition & object;
 ```
 
-Defined in: [types.ts:82](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L82)
+Defined in: [types.ts:82](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L82)
 
 A direct exchange definition.
 
@@ -176,7 +273,7 @@ This is ideal for point-to-point messaging where each message should go to speci
 
 | Name | Type | Defined in |
 | ------ | ------ | ------ |
-| `type` | `"direct"` | [types.ts:83](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L83) |
+| `type` | `"direct"` | [types.ts:83](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L83) |
 
 #### Example
 
@@ -203,7 +300,7 @@ type ExchangeBindingDefinition = object &
 };
 ```
 
-Defined in: [types.ts:262](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L262)
+Defined in: [types.ts:262](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L262)
 
 Binding between two exchanges (exchange-to-exchange routing).
 
@@ -214,9 +311,9 @@ This allows for more complex routing topologies.
 
 | Name | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. | [types.ts:272](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L272) |
-| `destination` | [`ExchangeDefinition`](#exchangedefinition) | The destination exchange that will receive forwarded messages | [types.ts:267](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L267) |
-| `type` | `"exchange"` | Discriminator indicating this is an exchange-to-exchange binding | [types.ts:264](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L264) |
+| `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. | [types.ts:272](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L272) |
+| `destination` | [`ExchangeDefinition`](#exchangedefinition) | The destination exchange that will receive forwarded messages | [types.ts:267](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L267) |
+| `type` | `"exchange"` | Discriminator indicating this is an exchange-to-exchange binding | [types.ts:264](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L264) |
 
 #### Example
 
@@ -241,7 +338,7 @@ type ExchangeDefinition =
   | TopicExchangeDefinition;
 ```
 
-Defined in: [types.ts:112](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L112)
+Defined in: [types.ts:112](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L112)
 
 Union type of all exchange definitions.
 
@@ -255,7 +352,7 @@ Represents any type of AMQP exchange: fanout, direct, or topic.
 type FanoutExchangeDefinition = BaseExchangeDefinition & object;
 ```
 
-Defined in: [types.ts:65](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L65)
+Defined in: [types.ts:65](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L65)
 
 A fanout exchange definition.
 
@@ -266,7 +363,7 @@ This is the simplest exchange type for pub/sub messaging patterns.
 
 | Name | Type | Defined in |
 | ------ | ------ | ------ |
-| `type` | `"fanout"` | [types.ts:66](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L66) |
+| `type` | `"fanout"` | [types.ts:66](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L66) |
 
 #### Example
 
@@ -284,7 +381,7 @@ const logsExchange: FanoutExchangeDefinition = defineExchange('logs', 'fanout',
 type InferConsumerNames<TContract> = TContract["consumers"] extends Record<string, unknown> ? keyof TContract["consumers"] : never;
 ```
 
-Defined in: [types.ts:462](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L462)
+Defined in: [types.ts:462](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L462)
 
 Extract consumer names from a contract.
 
@@ -316,7 +413,7 @@ type ConsumerNames = InferConsumerNames<typeof myContract>;
 type InferPublisherNames<TContract> = TContract["publishers"] extends Record<string, unknown> ? keyof TContract["publishers"] : never;
 ```
 
-Defined in: [types.ts:444](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L444)
+Defined in: [types.ts:444](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L444)
 
 Extract publisher names from a contract.
 
@@ -342,13 +439,45 @@ type PublisherNames = InferPublisherNames<typeof myContract>;
 
 ***
 
+### MatchingRoutingKey
+
+```ts
+type MatchingRoutingKey<Pattern, Key> = RoutingKey<Key> extends never ? never : BindingPattern<Pattern> extends never ? never : MatchesPattern<Key, Pattern> extends true ? Key : never;
+```
+
+Defined in: [builder.ts:867](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L867)
+
+Validate that a routing key matches a binding pattern.
+
+This is a utility type provided for users who want compile-time validation
+that a routing key matches a specific pattern. It's not enforced internally
+in the API to avoid TypeScript recursion depth issues with complex routing keys.
+
+Returns the routing key if it's valid and matches the pattern, `never` otherwise.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `Pattern` *extends* `string` | The binding pattern (can contain * and # wildcards) |
+| `Key` *extends* `string` | The routing key to validate |
+
+#### Example
+
+```typescript
+type ValidKey = MatchingRoutingKey<"order.*", "order.created">; // "order.created"
+type InvalidKey = MatchingRoutingKey<"order.*", "user.created">; // never
+```
+
+***
+
 ### MessageDefinition
 
 ```ts
 type MessageDefinition<TPayload, THeaders> = object;
 ```
 
-Defined in: [types.ts:178](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L178)
+Defined in: [types.ts:178](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L178)
 
 Definition of a message with typed payload and optional headers.
 
@@ -363,10 +492,10 @@ Definition of a message with typed payload and optional headers.
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="description"></a> `description?` | `string` | Detailed description of the message for documentation purposes. Used in AsyncAPI specification generation. | [types.ts:204](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L204) |
-| <a id="headers"></a> `headers?` | `THeaders` | Optional headers schema for validating message metadata. Must be a Standard Schema v1 compatible schema. | [types.ts:192](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L192) |
-| <a id="payload"></a> `payload` | `TPayload` | The payload schema for validating message content. Must be a Standard Schema v1 compatible schema (Zod, Valibot, ArkType, etc.). | [types.ts:186](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L186) |
-| <a id="summary"></a> `summary?` | `string` | Brief description of the message for documentation purposes. Used in AsyncAPI specification generation. | [types.ts:198](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L198) |
+| <a id="description"></a> `description?` | `string` | Detailed description of the message for documentation purposes. Used in AsyncAPI specification generation. | [types.ts:204](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L204) |
+| <a id="headers"></a> `headers?` | `THeaders` | Optional headers schema for validating message metadata. Must be a Standard Schema v1 compatible schema. | [types.ts:192](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L192) |
+| <a id="payload"></a> `payload` | `TPayload` | The payload schema for validating message content. Must be a Standard Schema v1 compatible schema (Zod, Valibot, ArkType, etc.). | [types.ts:186](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L186) |
+| <a id="summary"></a> `summary?` | `string` | Brief description of the message for documentation purposes. Used in AsyncAPI specification generation. | [types.ts:198](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L198) |
 
 ***
 
@@ -385,7 +514,7 @@ type PublisherDefinition<TMessage> = object &
 };
 ```
 
-Defined in: [types.ts:317](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L317)
+Defined in: [types.ts:317](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L317)
 
 Definition of a message publisher.
 
@@ -396,7 +525,7 @@ The message payload is validated against the schema before being sent to RabbitM
 
 | Name | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| `message` | `TMessage` | The message definition including the payload schema | [types.ts:319](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L319) |
+| `message` | `TMessage` | The message definition including the payload schema | [types.ts:319](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L319) |
 
 #### Type Parameters
 
@@ -416,6 +545,68 @@ const publisher: PublisherDefinition = {
 
 ***
 
+### PublisherFirstResult
+
+```ts
+type PublisherFirstResult<TMessage, TPublisher> = object;
+```
+
+Defined in: [builder.ts:734](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L734)
+
+Publisher-first builder result for fanout and direct exchanges.
+
+This type represents a publisher and provides a method to create
+a consumer that uses the same message schema with a binding to the exchange.
+
+This pattern is suitable for event-oriented messaging where publishers
+emit events without knowing which queues will consume them.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TMessage` *extends* [`MessageDefinition`](#messagedefinition) | The message definition |
+| `TPublisher` *extends* [`PublisherDefinition`](#publisherdefinition)\<`TMessage`\> | The publisher definition |
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="createconsumer"></a> `createConsumer` | (`queue`) => `object` | Create a consumer that receives messages from this publisher. The consumer will automatically use the same message schema and a binding will be created with the same routing key. | [builder.ts:748](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L748) |
+| <a id="publisher"></a> `publisher` | `TPublisher` | The publisher definition | [builder.ts:739](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L739) |
+
+***
+
+### PublisherFirstResultWithRoutingKey
+
+```ts
+type PublisherFirstResultWithRoutingKey<TMessage, TPublisher, TRoutingKey> = object;
+```
+
+Defined in: [builder.ts:886](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L886)
+
+Publisher-first builder result for topic exchanges.
+
+This type represents a publisher with a concrete routing key and provides a method
+to create consumers that can use routing key patterns matching the publisher's key.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TMessage` *extends* [`MessageDefinition`](#messagedefinition) | The message definition |
+| `TPublisher` *extends* [`PublisherDefinition`](#publisherdefinition)\<`TMessage`\> | The publisher definition |
+| `TRoutingKey` *extends* `string` | The literal routing key type from the publisher (for documentation purposes) |
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="createconsumer-1"></a> `createConsumer` | \<`TConsumerRoutingKey`\>(`queue`, `routingKey?`) => `object` | Create a consumer that receives messages from this publisher. For topic exchanges, the routing key pattern can be specified for the binding. | [builder.ts:901](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L901) |
+| <a id="publisher-1"></a> `publisher` | `TPublisher` | The publisher definition | [builder.ts:892](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L892) |
+
+***
+
 ### QueueBindingDefinition
 
 ```ts
@@ -431,7 +622,7 @@ type QueueBindingDefinition = object &
 };
 ```
 
-Defined in: [types.ts:214](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L214)
+Defined in: [types.ts:214](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L214)
 
 Binding between a queue and an exchange.
 
@@ -443,9 +634,9 @@ For fanout exchanges, no routing key is needed as all messages are broadcast.
 
 | Name | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. Can be used for advanced routing scenarios with the headers exchange type. | [types.ts:225](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L225) |
-| `queue` | [`QueueDefinition`](#queuedefinition) | The queue that will receive messages | [types.ts:219](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L219) |
-| `type` | `"queue"` | Discriminator indicating this is a queue-to-exchange binding | [types.ts:216](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L216) |
+| `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. Can be used for advanced routing scenarios with the headers exchange type. | [types.ts:225](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L225) |
+| `queue` | [`QueueDefinition`](#queuedefinition) | The queue that will receive messages | [types.ts:219](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L219) |
+| `type` | `"queue"` | Discriminator indicating this is a queue-to-exchange binding | [types.ts:216](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L216) |
 
 ***
 
@@ -455,7 +646,7 @@ For fanout exchanges, no routing key is needed as all messages are broadcast.
 type QueueDefinition = object;
 ```
 
-Defined in: [types.ts:123](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L123)
+Defined in: [types.ts:123](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L123)
 
 Definition of an AMQP queue.
 
@@ -466,11 +657,45 @@ to receive messages based on routing rules.
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="arguments-1"></a> `arguments?` | `Record`\<`string`, `unknown`\> | 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** `{ 'x-message-ttl': 86400000, // 24 hours 'x-dead-letter-exchange': 'dlx', 'x-max-priority': 10 }` | [types.ts:169](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L169) |
-| <a id="autodelete-1"></a> `autoDelete?` | `boolean` | If true, the queue is deleted when the last consumer unsubscribes. **Default** `false` | [types.ts:146](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L146) |
-| <a id="durable-1"></a> `durable?` | `boolean` | If true, the queue survives broker restarts. Durable queues are persisted to disk. **Default** `false` | [types.ts:133](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L133) |
-| <a id="exclusive"></a> `exclusive?` | `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` | [types.ts:140](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L140) |
-| <a id="name-1"></a> `name` | `string` | The name of the queue. Must be unique within the RabbitMQ virtual host. | [types.ts:127](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L127) |
+| <a id="arguments-1"></a> `arguments?` | `Record`\<`string`, `unknown`\> | 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** `{ 'x-message-ttl': 86400000, // 24 hours 'x-dead-letter-exchange': 'dlx', 'x-max-priority': 10 }` | [types.ts:169](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L169) |
+| <a id="autodelete-1"></a> `autoDelete?` | `boolean` | If true, the queue is deleted when the last consumer unsubscribes. **Default** `false` | [types.ts:146](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L146) |
+| <a id="durable-1"></a> `durable?` | `boolean` | If true, the queue survives broker restarts. Durable queues are persisted to disk. **Default** `false` | [types.ts:133](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L133) |
+| <a id="exclusive"></a> `exclusive?` | `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` | [types.ts:140](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L140) |
+| <a id="name-1"></a> `name` | `string` | The name of the queue. Must be unique within the RabbitMQ virtual host. | [types.ts:127](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L127) |
+
+***
+
+### RoutingKey
+
+```ts
+type RoutingKey<S> = S extends "" ? never : S extends `${string}*${string}` | `${string}#${string}` ? never : S;
+```
+
+Defined in: [builder.ts:778](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L778)
+
+Type-safe routing key that validates basic format.
+
+Validates that a routing key follows basic AMQP routing key rules:
+- Must not contain wildcards (* or #)
+- Must not be empty
+- Should contain alphanumeric characters, dots, hyphens, and underscores
+
+Note: Full character-by-character validation is not performed to avoid TypeScript
+recursion depth limits. Runtime validation is still recommended.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `S` *extends* `string` | The routing key string to validate |
+
+#### Example
+
+```typescript
+type Valid = RoutingKey<"order.created">; // "order.created"
+type Invalid = RoutingKey<"order.*">; // never (contains wildcard)
+type Invalid2 = RoutingKey<"">; // never (empty string)
+```
 
 ***
 
@@ -480,7 +705,7 @@ to receive messages based on routing rules.
 type TopicExchangeDefinition = BaseExchangeDefinition & object;
 ```
 
-Defined in: [types.ts:103](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L103)
+Defined in: [types.ts:103](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L103)
 
 A topic exchange definition.
 
@@ -494,7 +719,7 @@ Words are separated by dots (e.g., `order.created.high-value`).
 
 | Name | Type | Defined in |
 | ------ | ------ | ------ |
-| `type` | `"topic"` | [types.ts:104](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/types.ts#L104) |
+| `type` | `"topic"` | [types.ts:104](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/types.ts#L104) |
 
 #### Example
 
@@ -516,7 +741,7 @@ function defineConsumer<TMessage>(
 options?): ConsumerDefinition<TMessage>;
 ```
 
-Defined in: [builder.ts:595](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/builder.ts#L595)
+Defined in: [builder.ts:595](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L595)
 
 Define a message consumer.
 
@@ -583,7 +808,7 @@ const processOrderConsumer = defineConsumer(orderQueue, orderMessage);
 function defineContract<TContract>(definition): TContract;
 ```
 
-Defined in: [builder.ts:676](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/builder.ts#L676)
+Defined in: [builder.ts:676](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L676)
 
 Define an AMQP contract.
 
@@ -672,7 +897,7 @@ export const contract = defineContract({
 function defineMessage<TPayload, THeaders>(payload, options?): MessageDefinition<TPayload, THeaders>;
 ```
 
-Defined in: [builder.ts:197](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/builder.ts#L197)
+Defined in: [builder.ts:197](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L197)
 
 Define a message definition with payload and optional headers/metadata.
 
@@ -733,7 +958,7 @@ const orderMessage = defineMessage(
 function defineQueue(name, options?): QueueDefinition;
 ```
 
-Defined in: [builder.ts:152](https://github.com/btravers/amqp-contract/blob/d4ba5adf1e580179e8e0a4a6505d50b03f1a9b29/packages/contract/src/builder.ts#L152)
+Defined in: [builder.ts:152](https://github.com/btravers/amqp-contract/blob/2337be9d96ffc5b2bb77c6d63ca6e010efd8c2bc/packages/contract/src/builder.ts#L152)
 
 Define an AMQP queue.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amqp-contract/contract",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "description": "Contract builder for amqp-contract",
   "keywords": [
     "amqp",
@@ -45,7 +45,7 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.16",
-    "tsdown": "0.18.2",
+    "tsdown": "0.18.3",
     "typedoc": "0.28.15",
     "typedoc-plugin-markdown": "4.9.0",
     "typescript": "5.9.3",