@amqp-contract/contract 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +19 -7
  2. package/dist/index.cjs +43 -3
  3. package/dist/index.d.cts +344 -45
  4. package/dist/index.d.cts.map +1 -1
  5. package/dist/index.d.mts +344 -45
  6. package/dist/index.d.mts.map +1 -1
  7. package/dist/index.mjs +43 -3
  8. package/dist/index.mjs.map +1 -1
  9. package/docs/index.md +258 -62
  10. package/package.json +2 -2
package/docs/index.md CHANGED
@@ -12,7 +12,7 @@
12
12
  type AnySchema = StandardSchemaV1;
13
13
  ```
14
14
 
15
- Defined in: [types.ts:12](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L12)
15
+ Defined in: [types.ts:12](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L12)
16
16
 
17
17
  Any schema that conforms to Standard Schema v1.
18
18
 
@@ -32,7 +32,7 @@ https://github.com/standard-schema/standard-schema
32
32
  type BaseExchangeDefinition = object;
33
33
  ```
34
34
 
35
- Defined in: [types.ts:20](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L20)
35
+ Defined in: [types.ts:20](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L20)
36
36
 
37
37
  Base definition of an AMQP exchange.
38
38
 
@@ -43,11 +43,11 @@ type and routing rules. This type contains properties common to all exchange typ
43
43
 
44
44
  | Property | Type | Description | Defined in |
45
45
  | ------ | ------ | ------ | ------ |
46
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L49) |
47
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L36) |
48
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L30) |
49
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L43) |
50
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L24) |
46
+ | <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/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L49) |
47
+ | <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/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L36) |
48
+ | <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/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L30) |
49
+ | <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/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L43) |
50
+ | <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/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L24) |
51
51
 
52
52
  ***
53
53
 
@@ -59,7 +59,7 @@ type BindingDefinition =
59
59
  | ExchangeBindingDefinition;
60
60
  ```
61
61
 
62
- Defined in: [types.ts:298](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L298)
62
+ Defined in: [types.ts:340](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L340)
63
63
 
64
64
  Union type of all binding definitions.
65
65
 
@@ -69,13 +69,48 @@ A binding can be either:
69
69
 
70
70
  ***
71
71
 
72
+ ### BindingPattern
73
+
74
+ ```ts
75
+ type BindingPattern<S> = S extends "" ? never : S;
76
+ ```
77
+
78
+ Defined in: [builder.ts:816](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L816)
79
+
80
+ Type-safe binding pattern that validates basic format and wildcards.
81
+
82
+ Validates that a binding pattern follows basic AMQP binding pattern rules:
83
+ - Can contain wildcards (* for one word, # for zero or more words)
84
+ - Must not be empty
85
+ - Should contain alphanumeric characters, dots, hyphens, underscores, and wildcards
86
+
87
+ Note: Full character-by-character validation is not performed to avoid TypeScript
88
+ recursion depth limits. Runtime validation is still recommended.
89
+
90
+ #### Type Parameters
91
+
92
+ | Type Parameter | Description |
93
+ | ------ | ------ |
94
+ | `S` *extends* `string` | The binding pattern string to validate |
95
+
96
+ #### Example
97
+
98
+ ```typescript
99
+ type ValidPattern = BindingPattern<"order.*">; // "order.*"
100
+ type ValidHash = BindingPattern<"order.#">; // "order.#"
101
+ type ValidConcrete = BindingPattern<"order.created">; // "order.created"
102
+ type Invalid = BindingPattern<"">; // never (empty string)
103
+ ```
104
+
105
+ ***
106
+
72
107
  ### ConsumerDefinition
73
108
 
74
109
  ```ts
75
110
  type ConsumerDefinition<TMessage> = object;
76
111
  ```
77
112
 
78
- Defined in: [types.ts:354](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L354)
113
+ Defined in: [types.ts:396](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L396)
79
114
 
80
115
  Definition of a message consumer.
81
116
 
@@ -101,8 +136,8 @@ const consumer: ConsumerDefinition = {
101
136
 
102
137
  | Property | Type | Description | Defined in |
103
138
  | ------ | ------ | ------ | ------ |
104
- | <a id="message"></a> `message` | `TMessage` | The message definition including the payload schema | [types.ts:359](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L359) |
105
- | <a id="queue"></a> `queue` | [`QueueDefinition`](#queuedefinition) | The queue to consume messages from | [types.ts:356](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L356) |
139
+ | <a id="message"></a> `message` | `TMessage` | The message definition including the payload schema | [types.ts:401](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L401) |
140
+ | <a id="queue"></a> `queue` | [`QueueDefinition`](#queuedefinition) | The queue to consume messages from | [types.ts:398](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L398) |
106
141
 
107
142
  ***
108
143
 
@@ -112,9 +147,9 @@ const consumer: ConsumerDefinition = {
112
147
  type ConsumerFirstResult<TMessage, TConsumer, TBinding> = object;
113
148
  ```
114
149
 
115
- Defined in: [builder.ts:936](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L936)
150
+ Defined in: [builder.ts:1193](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1193)
116
151
 
117
- Consumer-first builder result.
152
+ Consumer-first builder result for fanout and direct exchanges.
118
153
 
119
154
  This type represents a consumer with its binding and provides a method to create
120
155
  a publisher that uses the same message schema and routing key.
@@ -131,9 +166,40 @@ a publisher that uses the same message schema and routing key.
131
166
 
132
167
  | Property | Type | Description | Defined in |
133
168
  | ------ | ------ | ------ | ------ |
134
- | <a id="binding"></a> `binding` | `TBinding` | The binding definition connecting the exchange to the queue | [builder.ts:944](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L944) |
135
- | <a id="consumer"></a> `consumer` | `TConsumer` | The consumer definition | [builder.ts:942](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L942) |
136
- | <a id="createpublisher"></a> `createPublisher` | () => [`PublisherDefinition`](#publisherdefinition)\<`TMessage`\> | Create a publisher that sends messages to this consumer. The publisher will automatically use the same message schema and routing key. | [builder.ts:951](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L951) |
169
+ | <a id="binding"></a> `binding` | `TBinding` | The binding definition connecting the exchange to the queue | [builder.ts:1201](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1201) |
170
+ | <a id="consumer"></a> `consumer` | `TConsumer` | The consumer definition | [builder.ts:1199](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1199) |
171
+ | <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:1208](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1208) |
172
+
173
+ ***
174
+
175
+ ### ConsumerFirstResultWithRoutingKey
176
+
177
+ ```ts
178
+ type ConsumerFirstResultWithRoutingKey<TMessage, TConsumer, TBinding> = object;
179
+ ```
180
+
181
+ Defined in: [builder.ts:1226](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1226)
182
+
183
+ Consumer-first builder result for topic exchanges.
184
+
185
+ This type represents a consumer with its binding (which may use a pattern) and provides
186
+ a method to create a publisher with a concrete routing key that matches the pattern.
187
+
188
+ #### Type Parameters
189
+
190
+ | Type Parameter | Description |
191
+ | ------ | ------ |
192
+ | `TMessage` *extends* [`MessageDefinition`](#messagedefinition) | The message definition |
193
+ | `TConsumer` *extends* [`ConsumerDefinition`](#consumerdefinition)\<`TMessage`\> | The consumer definition |
194
+ | `TBinding` *extends* [`QueueBindingDefinition`](#queuebindingdefinition) | The queue binding definition |
195
+
196
+ #### Properties
197
+
198
+ | Property | Type | Description | Defined in |
199
+ | ------ | ------ | ------ | ------ |
200
+ | <a id="binding-1"></a> `binding` | `TBinding` | The binding definition connecting the exchange to the queue | [builder.ts:1234](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1234) |
201
+ | <a id="consumer-1"></a> `consumer` | `TConsumer` | The consumer definition | [builder.ts:1232](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1232) |
202
+ | <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:1242](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L1242) |
137
203
 
138
204
  ***
139
205
 
@@ -143,7 +209,7 @@ a publisher that uses the same message schema and routing key.
143
209
  type ContractDefinition = object;
144
210
  ```
145
211
 
146
- Defined in: [types.ts:395](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L395)
212
+ Defined in: [types.ts:437](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L437)
147
213
 
148
214
  Complete AMQP contract definition.
149
215
 
@@ -182,11 +248,34 @@ const contract: ContractDefinition = {
182
248
 
183
249
  | Property | Type | Description | Defined in |
184
250
  | ------ | ------ | ------ | ------ |
185
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L412) |
186
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L426) |
187
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L400) |
188
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L419) |
189
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L406) |
251
+ | <a id="bindings"></a> `bindings?` | `Record`\<`string`, [`BindingDefinition`](#bindingdefinition)\> | Named binding definitions. Bindings can be queue-to-exchange or exchange-to-exchange. | [types.ts:454](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L454) |
252
+ | <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:468](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L468) |
253
+ | <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:442](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L442) |
254
+ | <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:461](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L461) |
255
+ | <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:448](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L448) |
256
+
257
+ ***
258
+
259
+ ### DeadLetterConfig
260
+
261
+ ```ts
262
+ type DeadLetterConfig = object;
263
+ ```
264
+
265
+ Defined in: [types.ts:124](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L124)
266
+
267
+ Configuration for dead letter exchange (DLX) on a queue.
268
+
269
+ When a message in a queue is rejected, expires, or exceeds the queue length limit,
270
+ it can be automatically forwarded to a dead letter exchange for further processing
271
+ or storage.
272
+
273
+ #### Properties
274
+
275
+ | Property | Type | Description | Defined in |
276
+ | ------ | ------ | ------ | ------ |
277
+ | <a id="exchange"></a> `exchange` | [`ExchangeDefinition`](#exchangedefinition) | The exchange to send dead-lettered messages to. This exchange must be declared in the contract. | [types.ts:129](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L129) |
278
+ | <a id="routingkey"></a> `routingKey?` | `string` | Optional routing key to use when forwarding messages to the dead letter exchange. If not specified, the original message routing key is used. | [types.ts:135](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L135) |
190
279
 
191
280
  ***
192
281
 
@@ -196,7 +285,7 @@ const contract: ContractDefinition = {
196
285
  type DirectExchangeDefinition = BaseExchangeDefinition & object;
197
286
  ```
198
287
 
199
- Defined in: [types.ts:82](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L82)
288
+ Defined in: [types.ts:82](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L82)
200
289
 
201
290
  A direct exchange definition.
202
291
 
@@ -207,7 +296,7 @@ This is ideal for point-to-point messaging where each message should go to speci
207
296
 
208
297
  | Name | Type | Defined in |
209
298
  | ------ | ------ | ------ |
210
- | `type` | `"direct"` | [types.ts:83](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L83) |
299
+ | `type` | `"direct"` | [types.ts:83](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L83) |
211
300
 
212
301
  #### Example
213
302
 
@@ -234,7 +323,7 @@ type ExchangeBindingDefinition = object &
234
323
  };
235
324
  ```
236
325
 
237
- Defined in: [types.ts:262](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L262)
326
+ Defined in: [types.ts:304](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L304)
238
327
 
239
328
  Binding between two exchanges (exchange-to-exchange routing).
240
329
 
@@ -245,9 +334,9 @@ This allows for more complex routing topologies.
245
334
 
246
335
  | Name | Type | Description | Defined in |
247
336
  | ------ | ------ | ------ | ------ |
248
- | `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. | [types.ts:272](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L272) |
249
- | `destination` | [`ExchangeDefinition`](#exchangedefinition) | The destination exchange that will receive forwarded messages | [types.ts:267](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L267) |
250
- | `type` | `"exchange"` | Discriminator indicating this is an exchange-to-exchange binding | [types.ts:264](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L264) |
337
+ | `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. | [types.ts:314](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L314) |
338
+ | `destination` | [`ExchangeDefinition`](#exchangedefinition) | The destination exchange that will receive forwarded messages | [types.ts:309](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L309) |
339
+ | `type` | `"exchange"` | Discriminator indicating this is an exchange-to-exchange binding | [types.ts:306](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L306) |
251
340
 
252
341
  #### Example
253
342
 
@@ -272,7 +361,7 @@ type ExchangeDefinition =
272
361
  | TopicExchangeDefinition;
273
362
  ```
274
363
 
275
- Defined in: [types.ts:112](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L112)
364
+ Defined in: [types.ts:112](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L112)
276
365
 
277
366
  Union type of all exchange definitions.
278
367
 
@@ -286,7 +375,7 @@ Represents any type of AMQP exchange: fanout, direct, or topic.
286
375
  type FanoutExchangeDefinition = BaseExchangeDefinition & object;
287
376
  ```
288
377
 
289
- Defined in: [types.ts:65](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L65)
378
+ Defined in: [types.ts:65](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L65)
290
379
 
291
380
  A fanout exchange definition.
292
381
 
@@ -297,7 +386,7 @@ This is the simplest exchange type for pub/sub messaging patterns.
297
386
 
298
387
  | Name | Type | Defined in |
299
388
  | ------ | ------ | ------ |
300
- | `type` | `"fanout"` | [types.ts:66](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L66) |
389
+ | `type` | `"fanout"` | [types.ts:66](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L66) |
301
390
 
302
391
  #### Example
303
392
 
@@ -315,7 +404,7 @@ const logsExchange: FanoutExchangeDefinition = defineExchange('logs', 'fanout',
315
404
  type InferConsumerNames<TContract> = TContract["consumers"] extends Record<string, unknown> ? keyof TContract["consumers"] : never;
316
405
  ```
317
406
 
318
- Defined in: [types.ts:462](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L462)
407
+ Defined in: [types.ts:504](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L504)
319
408
 
320
409
  Extract consumer names from a contract.
321
410
 
@@ -347,7 +436,7 @@ type ConsumerNames = InferConsumerNames<typeof myContract>;
347
436
  type InferPublisherNames<TContract> = TContract["publishers"] extends Record<string, unknown> ? keyof TContract["publishers"] : never;
348
437
  ```
349
438
 
350
- Defined in: [types.ts:444](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L444)
439
+ Defined in: [types.ts:486](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L486)
351
440
 
352
441
  Extract publisher names from a contract.
353
442
 
@@ -373,13 +462,45 @@ type PublisherNames = InferPublisherNames<typeof myContract>;
373
462
 
374
463
  ***
375
464
 
465
+ ### MatchingRoutingKey
466
+
467
+ ```ts
468
+ type MatchingRoutingKey<Pattern, Key> = RoutingKey<Key> extends never ? never : BindingPattern<Pattern> extends never ? never : MatchesPattern<Key, Pattern> extends true ? Key : never;
469
+ ```
470
+
471
+ Defined in: [builder.ts:878](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L878)
472
+
473
+ Validate that a routing key matches a binding pattern.
474
+
475
+ This is a utility type provided for users who want compile-time validation
476
+ that a routing key matches a specific pattern. It's not enforced internally
477
+ in the API to avoid TypeScript recursion depth issues with complex routing keys.
478
+
479
+ Returns the routing key if it's valid and matches the pattern, `never` otherwise.
480
+
481
+ #### Type Parameters
482
+
483
+ | Type Parameter | Description |
484
+ | ------ | ------ |
485
+ | `Pattern` *extends* `string` | The binding pattern (can contain * and # wildcards) |
486
+ | `Key` *extends* `string` | The routing key to validate |
487
+
488
+ #### Example
489
+
490
+ ```typescript
491
+ type ValidKey = MatchingRoutingKey<"order.*", "order.created">; // "order.created"
492
+ type InvalidKey = MatchingRoutingKey<"order.*", "user.created">; // never
493
+ ```
494
+
495
+ ***
496
+
376
497
  ### MessageDefinition
377
498
 
378
499
  ```ts
379
500
  type MessageDefinition<TPayload, THeaders> = object;
380
501
  ```
381
502
 
382
- Defined in: [types.ts:178](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L178)
503
+ Defined in: [types.ts:220](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L220)
383
504
 
384
505
  Definition of a message with typed payload and optional headers.
385
506
 
@@ -394,10 +515,10 @@ Definition of a message with typed payload and optional headers.
394
515
 
395
516
  | Property | Type | Description | Defined in |
396
517
  | ------ | ------ | ------ | ------ |
397
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L204) |
398
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L192) |
399
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L186) |
400
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L198) |
518
+ | <a id="description"></a> `description?` | `string` | Detailed description of the message for documentation purposes. Used in AsyncAPI specification generation. | [types.ts:246](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L246) |
519
+ | <a id="headers"></a> `headers?` | `THeaders` | Optional headers schema for validating message metadata. Must be a Standard Schema v1 compatible schema. | [types.ts:234](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L234) |
520
+ | <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:228](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L228) |
521
+ | <a id="summary"></a> `summary?` | `string` | Brief description of the message for documentation purposes. Used in AsyncAPI specification generation. | [types.ts:240](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L240) |
401
522
 
402
523
  ***
403
524
 
@@ -416,7 +537,7 @@ type PublisherDefinition<TMessage> = object &
416
537
  };
417
538
  ```
418
539
 
419
- Defined in: [types.ts:317](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L317)
540
+ Defined in: [types.ts:359](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L359)
420
541
 
421
542
  Definition of a message publisher.
422
543
 
@@ -427,7 +548,7 @@ The message payload is validated against the schema before being sent to RabbitM
427
548
 
428
549
  | Name | Type | Description | Defined in |
429
550
  | ------ | ------ | ------ | ------ |
430
- | `message` | `TMessage` | The message definition including the payload schema | [types.ts:319](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L319) |
551
+ | `message` | `TMessage` | The message definition including the payload schema | [types.ts:361](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L361) |
431
552
 
432
553
  #### Type Parameters
433
554
 
@@ -453,9 +574,9 @@ const publisher: PublisherDefinition = {
453
574
  type PublisherFirstResult<TMessage, TPublisher> = object;
454
575
  ```
455
576
 
456
- Defined in: [builder.ts:734](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L734)
577
+ Defined in: [builder.ts:745](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L745)
457
578
 
458
- Publisher-first builder result.
579
+ Publisher-first builder result for fanout and direct exchanges.
459
580
 
460
581
  This type represents a publisher and provides a method to create
461
582
  a consumer that uses the same message schema with a binding to the exchange.
@@ -474,8 +595,38 @@ emit events without knowing which queues will consume them.
474
595
 
475
596
  | Property | Type | Description | Defined in |
476
597
  | ------ | ------ | ------ | ------ |
477
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L748) |
478
- | <a id="publisher"></a> `publisher` | `TPublisher` | The publisher definition | [builder.ts:739](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L739) |
598
+ | <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:759](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L759) |
599
+ | <a id="publisher"></a> `publisher` | `TPublisher` | The publisher definition | [builder.ts:750](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L750) |
600
+
601
+ ***
602
+
603
+ ### PublisherFirstResultWithRoutingKey
604
+
605
+ ```ts
606
+ type PublisherFirstResultWithRoutingKey<TMessage, TPublisher, TRoutingKey> = object;
607
+ ```
608
+
609
+ Defined in: [builder.ts:897](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L897)
610
+
611
+ Publisher-first builder result for topic exchanges.
612
+
613
+ This type represents a publisher with a concrete routing key and provides a method
614
+ to create consumers that can use routing key patterns matching the publisher's key.
615
+
616
+ #### Type Parameters
617
+
618
+ | Type Parameter | Description |
619
+ | ------ | ------ |
620
+ | `TMessage` *extends* [`MessageDefinition`](#messagedefinition) | The message definition |
621
+ | `TPublisher` *extends* [`PublisherDefinition`](#publisherdefinition)\<`TMessage`\> | The publisher definition |
622
+ | `TRoutingKey` *extends* `string` | The literal routing key type from the publisher (for documentation purposes) |
623
+
624
+ #### Properties
625
+
626
+ | Property | Type | Description | Defined in |
627
+ | ------ | ------ | ------ | ------ |
628
+ | <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:912](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L912) |
629
+ | <a id="publisher-1"></a> `publisher` | `TPublisher` | The publisher definition | [builder.ts:903](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L903) |
479
630
 
480
631
  ***
481
632
 
@@ -494,7 +645,7 @@ type QueueBindingDefinition = object &
494
645
  };
495
646
  ```
496
647
 
497
- Defined in: [types.ts:214](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L214)
648
+ Defined in: [types.ts:256](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L256)
498
649
 
499
650
  Binding between a queue and an exchange.
500
651
 
@@ -506,9 +657,9 @@ For fanout exchanges, no routing key is needed as all messages are broadcast.
506
657
 
507
658
  | Name | Type | Description | Defined in |
508
659
  | ------ | ------ | ------ | ------ |
509
- | `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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L225) |
510
- | `queue` | [`QueueDefinition`](#queuedefinition) | The queue that will receive messages | [types.ts:219](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L219) |
511
- | `type` | `"queue"` | Discriminator indicating this is a queue-to-exchange binding | [types.ts:216](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L216) |
660
+ | `arguments?` | `Record`\<`string`, `unknown`\> | Additional AMQP arguments for the binding. Can be used for advanced routing scenarios with the headers exchange type. | [types.ts:267](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L267) |
661
+ | `queue` | [`QueueDefinition`](#queuedefinition) | The queue that will receive messages | [types.ts:261](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L261) |
662
+ | `type` | `"queue"` | Discriminator indicating this is a queue-to-exchange binding | [types.ts:258](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L258) |
512
663
 
513
664
  ***
514
665
 
@@ -518,7 +669,7 @@ For fanout exchanges, no routing key is needed as all messages are broadcast.
518
669
  type QueueDefinition = object;
519
670
  ```
520
671
 
521
- Defined in: [types.ts:123](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L123)
672
+ Defined in: [types.ts:144](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L144)
522
673
 
523
674
  Definition of an AMQP queue.
524
675
 
@@ -529,11 +680,46 @@ to receive messages based on routing rules.
529
680
 
530
681
  | Property | Type | Description | Defined in |
531
682
  | ------ | ------ | ------ | ------ |
532
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L169) |
533
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L146) |
534
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L133) |
535
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L140) |
536
- | <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/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L127) |
683
+ | <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-max-priority`: Maximum priority level for priority queues Note: When using the `deadLetter` property, the `x-dead-letter-exchange` and `x-dead-letter-routing-key` arguments are automatically set and should not be specified in this arguments object. **Example** `{ 'x-message-ttl': 86400000, // 24 hours 'x-max-priority': 10 }` | [types.ts:211](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L211) |
684
+ | <a id="autodelete-1"></a> `autoDelete?` | `boolean` | If true, the queue is deleted when the last consumer unsubscribes. **Default** `false` | [types.ts:167](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L167) |
685
+ | <a id="deadletter"></a> `deadLetter?` | [`DeadLetterConfig`](#deadletterconfig) | Dead letter configuration for handling failed or rejected messages. When configured, messages that are rejected, expire, or exceed queue limits will be automatically forwarded to the specified dead letter exchange. **Example** `const dlx = defineExchange('orders-dlx', 'topic', { durable: true }); const queue = defineQueue('order-processing', { durable: true, deadLetter: { exchange: dlx, routingKey: 'order.failed' } });` | [types.ts:187](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L187) |
686
+ | <a id="durable-1"></a> `durable?` | `boolean` | If true, the queue survives broker restarts. Durable queues are persisted to disk. **Default** `false` | [types.ts:154](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L154) |
687
+ | <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:161](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L161) |
688
+ | <a id="name-1"></a> `name` | `string` | The name of the queue. Must be unique within the RabbitMQ virtual host. | [types.ts:148](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L148) |
689
+
690
+ ***
691
+
692
+ ### RoutingKey
693
+
694
+ ```ts
695
+ type RoutingKey<S> = S extends "" ? never : S extends `${string}*${string}` | `${string}#${string}` ? never : S;
696
+ ```
697
+
698
+ Defined in: [builder.ts:789](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L789)
699
+
700
+ Type-safe routing key that validates basic format.
701
+
702
+ Validates that a routing key follows basic AMQP routing key rules:
703
+ - Must not contain wildcards (* or #)
704
+ - Must not be empty
705
+ - Should contain alphanumeric characters, dots, hyphens, and underscores
706
+
707
+ Note: Full character-by-character validation is not performed to avoid TypeScript
708
+ recursion depth limits. Runtime validation is still recommended.
709
+
710
+ #### Type Parameters
711
+
712
+ | Type Parameter | Description |
713
+ | ------ | ------ |
714
+ | `S` *extends* `string` | The routing key string to validate |
715
+
716
+ #### Example
717
+
718
+ ```typescript
719
+ type Valid = RoutingKey<"order.created">; // "order.created"
720
+ type Invalid = RoutingKey<"order.*">; // never (contains wildcard)
721
+ type Invalid2 = RoutingKey<"">; // never (empty string)
722
+ ```
537
723
 
538
724
  ***
539
725
 
@@ -543,7 +729,7 @@ to receive messages based on routing rules.
543
729
  type TopicExchangeDefinition = BaseExchangeDefinition & object;
544
730
  ```
545
731
 
546
- Defined in: [types.ts:103](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L103)
732
+ Defined in: [types.ts:103](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L103)
547
733
 
548
734
  A topic exchange definition.
549
735
 
@@ -557,7 +743,7 @@ Words are separated by dots (e.g., `order.created.high-value`).
557
743
 
558
744
  | Name | Type | Defined in |
559
745
  | ------ | ------ | ------ |
560
- | `type` | `"topic"` | [types.ts:104](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/types.ts#L104) |
746
+ | `type` | `"topic"` | [types.ts:104](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/types.ts#L104) |
561
747
 
562
748
  #### Example
563
749
 
@@ -579,7 +765,7 @@ function defineConsumer<TMessage>(
579
765
  options?): ConsumerDefinition<TMessage>;
580
766
  ```
581
767
 
582
- Defined in: [builder.ts:595](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L595)
768
+ Defined in: [builder.ts:606](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L606)
583
769
 
584
770
  Define a message consumer.
585
771
 
@@ -646,7 +832,7 @@ const processOrderConsumer = defineConsumer(orderQueue, orderMessage);
646
832
  function defineContract<TContract>(definition): TContract;
647
833
  ```
648
834
 
649
- Defined in: [builder.ts:676](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L676)
835
+ Defined in: [builder.ts:687](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L687)
650
836
 
651
837
  Define an AMQP contract.
652
838
 
@@ -735,7 +921,7 @@ export const contract = defineContract({
735
921
  function defineMessage<TPayload, THeaders>(payload, options?): MessageDefinition<TPayload, THeaders>;
736
922
  ```
737
923
 
738
- Defined in: [builder.ts:197](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L197)
924
+ Defined in: [builder.ts:208](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L208)
739
925
 
740
926
  Define a message definition with payload and optional headers/metadata.
741
927
 
@@ -796,7 +982,7 @@ const orderMessage = defineMessage(
796
982
  function defineQueue(name, options?): QueueDefinition;
797
983
  ```
798
984
 
799
- Defined in: [builder.ts:152](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/contract/src/builder.ts#L152)
985
+ Defined in: [builder.ts:163](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/contract/src/builder.ts#L163)
800
986
 
801
987
  Define an AMQP queue.
802
988
 
@@ -819,11 +1005,21 @@ A queue definition
819
1005
  #### Example
820
1006
 
821
1007
  ```typescript
822
- const orderProcessingQueue = defineQueue('order-processing', {
1008
+ // Basic queue
1009
+ const orderQueue = defineQueue('order-processing', {
823
1010
  durable: true,
1011
+ });
1012
+
1013
+ // Queue with dead letter exchange
1014
+ const dlx = defineExchange('orders-dlx', 'topic', { durable: true });
1015
+ const orderQueueWithDLX = defineQueue('order-processing', {
1016
+ durable: true,
1017
+ deadLetter: {
1018
+ exchange: dlx,
1019
+ routingKey: 'order.failed'
1020
+ },
824
1021
  arguments: {
825
1022
  'x-message-ttl': 86400000, // 24 hours
826
- 'x-dead-letter-exchange': 'orders-dlx'
827
1023
  }
828
1024
  });
829
1025
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amqp-contract/contract",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "description": "Contract builder for amqp-contract",
5
5
  "keywords": [
6
6
  "amqp",
@@ -45,7 +45,7 @@
45
45
  },
46
46
  "devDependencies": {
47
47
  "@vitest/coverage-v8": "4.0.16",
48
- "tsdown": "0.18.2",
48
+ "tsdown": "0.18.3",
49
49
  "typedoc": "0.28.15",
50
50
  "typedoc-plugin-markdown": "4.9.0",
51
51
  "typescript": "5.9.3",