@amqp-contract/contract

---

@amqp-contract/contract

Type Aliases

AnySchema

type AnySchema = StandardSchemaV1;

Defined in: types.ts:12

Any schema that conforms to Standard Schema v1.

This library supports any validation library that implements the Standard Schema v1 specification, including Zod, Valibot, and ArkType. This allows you to use your preferred validation library while maintaining type safety.

See

https://github.com/standard-schema/standard-schema

---

BaseExchangeDefinition

type BaseExchangeDefinition<TName> = object;

Defined in: types.ts:394

Base definition of an AMQP exchange.

An exchange receives messages from publishers and routes them to queues based on the exchange type and routing rules. This type contains properties common to all exchange types.

Type Parameters

Type Parameter	Default type
TName extends string	string

Properties

Property	Type	Description	Defined in
arguments?	Record<string, unknown>	Additional AMQP arguments for advanced configuration. Common arguments include alternate-exchange for handling unroutable messages.	types.ts:421
autoDelete?	boolean	If true, the exchange is deleted when all queues have finished using it.	types.ts:409
durable?	boolean	If true, the exchange survives broker restarts. Durable exchanges are persisted to disk. Default true	types.ts:404
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.	types.ts:415
name	TName	The name of the exchange. Must be unique within the RabbitMQ virtual host.	types.ts:398

---

BindingDefinition

type BindingDefinition = 
  | QueueBindingDefinition
  | ExchangeBindingDefinition;

Defined in: types.ts:891

Union type of all binding definitions.

A binding can be either:

• Queue-to-exchange binding: Routes messages from an exchange to a queue
• Exchange-to-exchange binding: Forwards messages from one exchange to another

---

BindingPattern

type BindingPattern<S> = S extends "" ? never : S;

Defined in: builder/routing-types.ts:52

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

type ValidPattern = BindingPattern<"order.*">; // "order.*"
type ValidHash = BindingPattern<"order.#">; // "order.#"
type ValidConcrete = BindingPattern<"order.created">; // "order.created"
type Invalid = BindingPattern<"">; // never (empty string)

---

BridgedPublisherConfig

type BridgedPublisherConfig<TMessage, TBridgeExchange, TTargetExchange> = object;

Defined in: builder/command.ts:61

Configuration for a bridged command publisher.

A bridged publisher publishes to a bridge exchange (local domain), which forwards messages to the target exchange (remote domain) via an exchange-to-exchange binding.

Type Parameters

Type Parameter	Description
TMessage extends MessageDefinition	The message definition
TBridgeExchange extends ExchangeDefinition	The bridge (local domain) exchange definition
TTargetExchange extends ExchangeDefinition	The target (remote domain) exchange definition

Properties

Property	Type	Description	Defined in
__brand	"BridgedPublisherConfig"	Discriminator to identify this as a bridged publisher config	builder/command.ts:67
bridgeExchange	TBridgeExchange	The bridge (local domain) exchange	builder/command.ts:73
exchangeBinding	ExchangeBindingDefinition	The exchange-to-exchange binding (bridge → target)	builder/command.ts:71
publisher	PublisherDefinition<TMessage>	The publisher definition (publishes to bridge exchange)	builder/command.ts:69
targetExchange	TTargetExchange	The target (remote domain) exchange	builder/command.ts:75

---

BridgedPublisherConfigBase

type BridgedPublisherConfigBase = object;

Defined in: types.ts:1024

Base type for bridged publisher configuration.

A bridged publisher publishes to a bridge exchange, which forwards messages to the target exchange via an exchange-to-exchange binding.

See

defineCommandPublisher with bridgeExchange option

Properties

Property	Type	Defined in
__brand	"BridgedPublisherConfig"	types.ts:1025
bridgeExchange	ExchangeDefinition	types.ts:1028
exchangeBinding	ExchangeBindingDefinition	types.ts:1027
publisher	PublisherDefinition	types.ts:1026
targetExchange	ExchangeDefinition	types.ts:1029

---

ClassicQueueDefinition

type ClassicQueueDefinition<TName> = BaseQueueDefinition<TName> & object;

Defined in: types.ts:608

Definition of a classic queue.

Classic queues are the traditional RabbitMQ queue type. Use them when you need specific features not supported by quorum queues (e.g., exclusive queues, auto-deleting queues, priority queues).

Type Declaration

Name	Type	Description	Defined in
autoDelete?	boolean	If true, the queue is deleted when the last consumer unsubscribes.	types.ts:628
durable	boolean	If true, the queue survives broker restarts. Durable queues are persisted to disk.	types.ts:617
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.	types.ts:623
maxPriority?	number	Maximum priority level for priority queue (1-255, recommended: 1-10). Sets x-max-priority argument.	types.ts:634
type	"classic"	Queue type discriminator: classic queue.	types.ts:612

Type Parameters

Type Parameter	Default type
TName extends string	string

---

ClassicQueueOptions

type ClassicQueueOptions = BaseQueueOptions & object;

Defined in: types.ts:342

Options for creating a classic queue.

Classic queues support all traditional RabbitMQ features including:

• exclusive - For connection-scoped queues
• autoDelete - For auto-deleting queues when consumers disconnect
• maxPriority - For priority queues
• durable: false - For non-durable queues

Type Declaration

Name	Type	Description	Defined in
autoDelete?	boolean	If true, the queue is deleted when the last consumer unsubscribes.	types.ts:363
durable?	boolean	If true, the queue survives broker restarts. Durable queues are persisted to disk. Default true	types.ts:352
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.	types.ts:358
maxPriority?	number	Maximum priority level for priority queue (1-255, recommended: 1-10). Sets x-max-priority argument.	types.ts:369
type	"classic"	Queue type: classic (for special cases)	types.ts:346

Example

const priorityQueue = defineQueue('tasks', {
  type: 'classic',
  maxPriority: 10,
});

---

CommandConsumerConfig

type CommandConsumerConfig<TMessage, TExchange, TRoutingKey, TQueue> = object;

Defined in: builder/command.ts:29

Configuration for a command consumer.

Commands are sent by one or more publishers to a single consumer (task queue pattern). The consumer "owns" the queue, and publishers send commands to it.

Type Parameters

Type Parameter	Default type	Description
TMessage extends MessageDefinition	-	The message definition
TExchange extends ExchangeDefinition	-	The exchange definition
TRoutingKey extends string | undefined	undefined	The routing key type (undefined for fanout and headers exchanges)
TQueue extends QueueEntry	QueueEntry	-

Properties

Property	Type	Description	Defined in
__brand	"CommandConsumerConfig"	Discriminator to identify this as a command consumer config	builder/command.ts:36
binding	QueueBindingDefinition	The binding connecting the queue to the exchange	builder/command.ts:40
consumer	ConsumerDefinition<TMessage>	The consumer definition for processing commands	builder/command.ts:38
exchange	TExchange	The exchange that receives commands	builder/command.ts:42
message	TMessage	The message definition	builder/command.ts:46
queue	TQueue	The queue this consumer reads from	builder/command.ts:44
routingKey	TRoutingKey	The routing key pattern for the binding	builder/command.ts:48

---

CommandConsumerConfigBase

type CommandConsumerConfigBase = object;

Defined in: types.ts:988

Base type for command consumer configuration.

This is a simplified type used in ContractDefinition. The full generic type is defined in the builder module.

See

defineCommandConsumer for creating command consumers

Properties

Property	Type	Defined in
__brand	"CommandConsumerConfig"	types.ts:989
binding	QueueBindingDefinition	types.ts:991
consumer	ConsumerDefinition	types.ts:990
exchange	ExchangeDefinition	types.ts:992
message	MessageDefinition	types.ts:994
queue	QueueEntry	types.ts:993
routingKey	string | undefined	types.ts:995

---

CompressionAlgorithm

type CompressionAlgorithm = "gzip" | "deflate";

Defined in: types.ts:199

Supported compression algorithms for message payloads.

• gzip: GZIP compression (standard, widely supported, good compression ratio)
• deflate: DEFLATE compression (faster than gzip, slightly less compression)

Compression is configured at runtime via PublishOptions when calling AmqpClient.publish, not at publisher definition time.

When compression is enabled, the message payload is compressed before publishing and automatically decompressed when consuming. The content-encoding AMQP message property is set to indicate the compression algorithm used.

To disable compression, simply omit the compression option (it's optional).

Example

// Define a publisher without compression configuration
const orderCreatedPublisher = definePublisher(exchange, message, {
  routingKey: "order.created",
});

// Later, choose whether to compress at publish time
await client.publish("orderCreated", payload, {
  compression: "gzip",
});

---

ConsumerDefinition

type ConsumerDefinition<TMessage> = object;

Defined in: types.ts:952

Definition of a message consumer.

A consumer receives and processes messages from a queue with automatic schema validation. The message payload is validated against the schema before being passed to your handler. If the message is compressed (indicated by the content-encoding header), it will be automatically decompressed before validation.

Example

const consumer: ConsumerDefinition = {
  queue: orderProcessingQueue,
  message: orderMessage
};

Type Parameters

Type Parameter	Default type	Description
TMessage extends MessageDefinition	MessageDefinition	The message definition with payload schema

Properties

Property	Type	Description	Defined in
message	TMessage	The message definition including the payload schema	types.ts:957
queue	QueueEntry	The queue to consume messages from	types.ts:954

---

ConsumerEntry

type ConsumerEntry = 
  | ConsumerDefinition
  | EventConsumerResultBase
  | CommandConsumerConfigBase;

Defined in: types.ts:1162

Consumer entry that can be passed to defineContract's consumers section.

Can be either:

• A plain ConsumerDefinition from defineConsumer
• An EventConsumerResult from defineEventConsumer (binding auto-extracted)
• A CommandConsumerConfig from defineCommandConsumer (binding auto-extracted)

---

ContractDefinition

type ContractDefinition = object;

Defined in: types.ts:1093

Complete AMQP contract definition (output type).

A contract brings together all AMQP resources into a single, type-safe definition. It defines the complete messaging topology including exchanges, queues, bindings, publishers, and consumers.

The contract is used by:

• Clients (TypedAmqpClient) for type-safe message publishing
• Workers (TypedAmqpWorker) for type-safe message consumption
• AsyncAPI generator for documentation

Example

const contract: ContractDefinition = {
  exchanges: {
    orders: ordersExchange,
  },
  queues: {
    orderProcessing: orderProcessingQueue,
  },
  bindings: {
    orderBinding: orderQueueBinding,
  },
  publishers: {
    orderCreated: orderCreatedPublisher,
  },
  consumers: {
    processOrder: processOrderConsumer,
  },
};

Properties

Property	Type	Description	Defined in
bindings?	Record<string, BindingDefinition>	Named binding definitions. Bindings can be queue-to-exchange or exchange-to-exchange.	types.ts:1113
consumers?	Record<string, 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:1127
exchanges?	Record<string, ExchangeDefinition>	Named exchange definitions. Each key becomes available as a named resource in the contract.	types.ts:1098
publishers?	Record<string, 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:1120
queues?	Record<string, QueueEntry>	Named queue definitions. Each key becomes available as a named resource in the contract. When a queue has TTL-backoff retry configured, pass the QueueWithTtlBackoffInfrastructure object returned by defineQueue. The wait queue, exchanges, and bindings will be automatically added.	types.ts:1107
rpcs?	Record<string, RpcDefinition>	Named RPC definitions. Each key gets: - A handler in the TypedAmqpWorker that returns the typed response. - A client.call(name, request, options) method on the TypedAmqpClient. RPC entries do not appear in publishers or consumers because each end of an RPC plays both roles (publisher of one direction, consumer of the other).	types.ts:1138

---

ContractDefinitionInput

type ContractDefinitionInput = object;

Defined in: types.ts:1191

Contract definition input type with automatic extraction of event/command patterns.

Users only define publishers and consumers. Exchanges, queues, and bindings are automatically extracted from these definitions.

Example

const contract = defineContract({
  publishers: {
    // EventPublisherConfig → auto-extracted to publisher
    orderCreated: defineEventPublisher(ordersExchange, orderMessage, { routingKey: "order.created" }),
  },
  consumers: {
    // CommandConsumerConfig → auto-extracted to consumer + binding
    processOrder: defineCommandConsumer(orderQueue, ordersExchange, orderMessage, { routingKey: "order.process" }),
    // EventConsumerResult → auto-extracted to consumer + binding
    notify: defineEventConsumer(orderCreatedEvent, notificationQueue),
  },
});

See

defineContract - Processes this input and returns a ContractDefinition

Properties

Property	Type	Description	Defined in
consumers?	Record<string, ConsumerEntry>	Named consumer definitions. Can accept: - ConsumerDefinition from defineConsumer - EventConsumerResult from defineEventConsumer (binding auto-extracted) - CommandConsumerConfig from defineCommandConsumer (binding auto-extracted)	types.ts:1209
publishers?	Record<string, PublisherEntry>	Named publisher definitions. Can accept: - PublisherDefinition from definePublisher - EventPublisherConfig from defineEventPublisher (auto-extracted to publisher)	types.ts:1199
rpcs?	Record<string, RpcDefinition>	Named RPC definitions from defineRpc. Each entry contributes its queue (and DLX if any) to the contract topology and exposes a typed client.call(name, ...) / worker handler pair.	types.ts:1216

---

ContractOutput

type ContractOutput<TContract> = object;

Defined in: types.ts:1533

Contract output type with all resources extracted and properly typed.

This type represents the fully expanded contract with:

• exchanges: Extracted from publishers and consumer bindings
• queues: Extracted from consumers
• bindings: Extracted from event/command consumers
• publishers: Normalized publisher definitions
• consumers: Normalized consumer definitions

Type Parameters

Type Parameter
TContract extends ContractDefinitionInput

Properties

Property	Type	Defined in
bindings	TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractBindingsFromConsumers<TContract["consumers"]> : object & TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractExchangeBindingsFromConsumers<TContract["consumers"]> : object & TContract["publishers"] extends Record<string, PublisherEntry> ? ExtractExchangeBindingsFromPublishers<TContract["publishers"]> : object	types.ts:1558
consumers	TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractConsumerDefinitions<TContract["consumers"]> : object	types.ts:1570
exchanges	TContract["publishers"] extends Record<string, PublisherEntry> ? ExtractExchangesFromPublishers<TContract["publishers"]> : object & TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractExchangesFromConsumers<TContract["consumers"]> : object & TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractDeadLetterExchangesFromConsumers<TContract["consumers"]> : object & TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractBridgeExchangesFromConsumers<TContract["consumers"]> : object & TContract["publishers"] extends Record<string, PublisherEntry> ? ExtractTargetExchangesFromPublishers<TContract["publishers"]> : object & TContract["rpcs"] extends Record<string, RpcDefinition> ? ExtractDeadLetterExchangesFromRpcs<TContract["rpcs"]> : object	types.ts:1534
publishers	TContract["publishers"] extends Record<string, PublisherEntry> ? ExtractPublisherDefinitions<TContract["publishers"]> : object	types.ts:1567
queues	TContract["consumers"] extends Record<string, ConsumerEntry> ? ExtractQueuesFromConsumers<TContract["consumers"]> : object & TContract["rpcs"] extends Record<string, RpcDefinition> ? ExtractQueuesFromRpcs<TContract["rpcs"]> : object	types.ts:1552
rpcs	TContract["rpcs"] extends Record<string, RpcDefinition> ? TContract["rpcs"] : object	types.ts:1573

---

DeadLetterConfig

type DeadLetterConfig = object;

Defined in: types.ts:518

Configuration for dead letter exchange (DLX) on a queue.

When a message in a queue is rejected, expires, or exceeds the queue length limit, it can be automatically forwarded to a dead letter exchange for further processing or storage.

Properties

Property	Type	Description	Defined in
exchange	ExchangeDefinition	The exchange to send dead-lettered messages to. This exchange must be declared in the contract.	types.ts:523
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:529

---

DefineQueueOptions

type DefineQueueOptions = 
  | QuorumQueueOptions
  | ClassicQueueOptions;

Defined in: types.ts:379

Options for defining a queue. Uses a discriminated union based on the type property to enforce quorum queue constraints at compile time.

• Quorum queues (default): Do not support exclusive, autoDelete, or maxPriority
• Classic queues: Support all options including exclusive, autoDelete, and maxPriority

---

DirectExchangeDefinition

type DirectExchangeDefinition<TName> = BaseExchangeDefinition<TName> & object;

Defined in: types.ts:459

A direct exchange definition.

Direct exchanges route messages to queues based on exact routing key matches. This is ideal for point-to-point messaging where each message should go to specific queues.

Type Declaration

Name	Type	Defined in
type	"direct"	types.ts:461

Type Parameters

Type Parameter	Default type
TName extends string	string

Example

const tasksExchange: DirectExchangeDefinition = defineExchange('tasks', {
  type: 'direct',
});

---

EventConsumerResult

type EventConsumerResult<TMessage, TExchange, TQueue, TExchangeBinding, TBridgeExchange> = object;

Defined in: builder/event.ts:54

Result from defineEventConsumer.

Contains the consumer definition and binding needed to subscribe to an event. Can be used directly in defineContract's consumers section - the binding will be automatically extracted.

Type Parameters

Type Parameter	Default type	Description
TMessage extends MessageDefinition	-	The message definition
TExchange extends ExchangeDefinition	ExchangeDefinition	-
TQueue extends QueueEntry	QueueEntry	-
TExchangeBinding extends ExchangeBindingDefinition | undefined	ExchangeBindingDefinition | undefined	-
TBridgeExchange extends ExchangeDefinition | undefined	ExchangeDefinition | undefined	-

Properties

Property	Type	Description	Defined in
__brand	"EventConsumerResult"	Discriminator to identify this as an event consumer result	builder/event.ts:64
binding	QueueBindingDefinition	The binding connecting the queue to the exchange	builder/event.ts:68
bridgeExchange	TBridgeExchange	The bridge (local domain) exchange when bridging, if configured	builder/event.ts:76
consumer	ConsumerDefinition<TMessage>	The consumer definition for processing messages	builder/event.ts:66
exchange	TExchange	The source exchange this consumer subscribes to	builder/event.ts:70
exchangeBinding	TExchangeBinding	The exchange-to-exchange binding when bridging, if configured	builder/event.ts:74
queue	TQueue	The queue this consumer reads from	builder/event.ts:72

---

EventConsumerResultBase

type EventConsumerResultBase = object;

Defined in: types.ts:1006

Base type for event consumer result.

This is a simplified type used in ContractDefinitionInput. The full generic type is defined in the builder module.

See

defineEventConsumer for creating event consumers

Properties

Property	Type	Defined in
__brand	"EventConsumerResult"	types.ts:1007
binding	QueueBindingDefinition	types.ts:1009
bridgeExchange	ExchangeDefinition | undefined	types.ts:1013
consumer	ConsumerDefinition	types.ts:1008
exchange	ExchangeDefinition	types.ts:1010
exchangeBinding	ExchangeBindingDefinition | undefined	types.ts:1012
queue	QueueEntry	types.ts:1011

---

EventPublisherConfig

type EventPublisherConfig<TMessage, TExchange, TRoutingKey> = object;

Defined in: builder/event.ts:28

Configuration for an event publisher.

Events are published without knowing who consumes them. Multiple consumers can subscribe to the same event. This follows the pub/sub pattern where publishers broadcast events and consumers subscribe to receive them.

Type Parameters

Type Parameter	Default type	Description
TMessage extends MessageDefinition	-	The message definition
TExchange extends ExchangeDefinition	-	The exchange definition
TRoutingKey extends string | undefined	undefined	The routing key type (undefined for fanout and headers exchanges)

Properties

Property	Type	Description	Defined in
__brand	"EventPublisherConfig"	Discriminator to identify this as an event publisher config	builder/event.ts:34
arguments?	Record<string, unknown>	Additional AMQP arguments	builder/event.ts:42
exchange	TExchange	The exchange to publish to	builder/event.ts:36
message	TMessage	The message definition	builder/event.ts:38
routingKey	TRoutingKey	The routing key for direct/topic exchanges	builder/event.ts:40

---

EventPublisherConfigBase

type EventPublisherConfigBase = object;

Defined in: types.ts:972

Base type for event publisher configuration.

This is a simplified type used in ContractDefinition. The full generic type is defined in the builder module.

See

defineEventPublisher for creating event publishers

Properties

Property	Type	Defined in
__brand	"EventPublisherConfig"	types.ts:973
arguments?	Record<string, unknown>	types.ts:977
exchange	ExchangeDefinition	types.ts:974
message	MessageDefinition	types.ts:975
routingKey	string | undefined	types.ts:976

---

ExchangeBindingDefinition

type ExchangeBindingDefinition = object & 
  | {
  routingKey: string;
  source:   | DirectExchangeDefinition
     | TopicExchangeDefinition;
}
  | {
  routingKey?: never;
  source:   | FanoutExchangeDefinition
     | HeadersExchangeDefinition;
};

Defined in: types.ts:855

Binding between two exchanges (exchange-to-exchange routing).

Defines how messages should be forwarded from a source exchange to a destination exchange. This allows for more complex routing topologies.

Type Declaration

Name	Type	Description	Defined in
arguments?	Record<string, unknown>	Additional AMQP arguments for the binding.	types.ts:865
destination	ExchangeDefinition	The destination exchange that will receive forwarded messages	types.ts:860
type	"exchange"	Discriminator indicating this is an exchange-to-exchange binding	types.ts:857

Example

// Forward high-priority orders to a special processing exchange
const binding: ExchangeBindingDefinition = {
  type: 'exchange',
  source: ordersExchange,
  destination: highPriorityExchange,
  routingKey: 'order.high-priority.*'
};

---

ExchangeDefinition

type ExchangeDefinition<TName> = 
  | TopicExchangeDefinition<TName>
  | DirectExchangeDefinition<TName>
  | FanoutExchangeDefinition<TName>
  | HeadersExchangeDefinition<TName>;

Defined in: types.ts:505

Union type of all exchange definitions.

Represents any type of AMQP exchange: topic, direct, fanout, headers.

Type Parameters

Type Parameter	Default type
TName extends string	string

---

FanoutExchangeDefinition

type FanoutExchangeDefinition<TName> = BaseExchangeDefinition<TName> & object;

Defined in: types.ts:477

A fanout exchange definition.

Fanout exchanges broadcast all messages to all bound queues, ignoring routing keys. This is the simplest exchange type for pub/sub messaging patterns.

Type Declaration

Name	Type	Defined in
type	"fanout"	types.ts:479

Type Parameters

Type Parameter	Default type
TName extends string	string

Example

const logsExchange: FanoutExchangeDefinition = defineExchange('logs', {
  type: 'fanout',
});

---

HeadersExchangeDefinition

type HeadersExchangeDefinition<TName> = BaseExchangeDefinition<TName> & object;

Defined in: types.ts:495

A headers exchange definition.

Headers exchanges route messages based on header values rather than routing keys. This is useful for more complex routing scenarios where metadata is important.

Type Declaration

Name	Type	Defined in
type	"headers"	types.ts:497

Type Parameters

Type Parameter	Default type
TName extends string	string

Example

const routesExchange: HeadersExchangeDefinition = defineExchange('routes', {
  type: 'headers',
});

---

ImmediateRequeueRetryOptions

type ImmediateRequeueRetryOptions = object;

Defined in: types.ts:88

Immediate-Requeue retry options.

Failed messages are requeued immediately. For quorum queues, messages are requeued with nack(requeue=true), and the worker tracks delivery count via the native RabbitMQ x-delivery-count header. For classic queues, messages are re-published on the same queue, and the worker tracks delivery count via a custom x-retry-count header. When the count exceeds maxRetries, the message is automatically dead-lettered (if DLX is configured) or dropped.

Benefits: Simpler architecture, no wait queues needed, no head-of-queue blocking. Limitation: Immediate retries only (no exponential backoff).

See

https://www.rabbitmq.com/docs/quorum-queues#poison-message-handling

Properties

Property	Type	Description	Defined in
maxRetries?	number	Maximum retry attempts before sending to DLQ. Minimum 1 - Must be a positive integer (1 or greater) Default 3	types.ts:98
mode	"immediate-requeue"	Immediate-Requeue mode.	types.ts:92

---

InferConsumerNames

type InferConsumerNames<TContract> = TContract["consumers"] extends Record<string, unknown> ? keyof TContract["consumers"] : never;

Defined in: types.ts:1609

Extract consumer names from a contract.

This utility type extracts the keys of all consumers defined in a contract. It's used internally for type inference in the TypedAmqpWorker.

Type Parameters

Type Parameter	Description
TContract extends ContractDefinition	The contract definition

Returns

Union of consumer names, or never if no consumers defined

Example

type ConsumerNames = InferConsumerNames<typeof myContract>;
// Result: 'processOrder' | 'sendNotification' | 'updateInventory'

---

InferPublisherNames

type InferPublisherNames<TContract> = TContract["publishers"] extends Record<string, unknown> ? keyof TContract["publishers"] : never;

Defined in: types.ts:1591

Extract publisher names from a contract.

This utility type extracts the keys of all publishers defined in a contract. It's used internally for type inference in the TypedAmqpClient.

Type Parameters

Type Parameter	Description
TContract extends ContractDefinition	The contract definition

Returns

Union of publisher names, or never if no publishers defined

Example

type PublisherNames = InferPublisherNames<typeof myContract>;
// Result: 'orderCreated' | 'orderUpdated' | 'orderCancelled'

---

InferRpcNames

type InferRpcNames<TContract> = TContract["rpcs"] extends Record<string, RpcDefinition> ? keyof TContract["rpcs"] : never;

Defined in: types.ts:1621

Extract RPC names from a contract.

Each name in this union has a typed worker handler and a client.call(name, ...) method. RPC names are disjoint from InferConsumerNames and InferPublisherNames.

Type Parameters

Type Parameter	Description
TContract extends ContractDefinition	The contract definition

Returns

Union of RPC names, or never if no RPCs defined

---

MatchingRoutingKey

type MatchingRoutingKey<Pattern, Key> = RoutingKey<Key> extends never ? never : BindingPattern<Pattern> extends never ? never : MatchesPattern<Key, Pattern> extends true ? Key : never;

Defined in: builder/routing-types.ts:114

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

type ValidKey = MatchingRoutingKey<"order.*", "order.created">; // "order.created"
type InvalidKey = MatchingRoutingKey<"order.*", "user.created">; // never

---

MessageDefinition

type MessageDefinition<TPayload, THeaders> = object;

Defined in: types.ts:769

Definition of a message with typed payload and optional headers.

Type Parameters

Type Parameter	Default type	Description
TPayload extends AnySchema	AnySchema	The Standard Schema v1 compatible schema for the message payload
THeaders extends | StandardSchemaV1<Record<string, unknown>> | undefined	| StandardSchemaV1<Record<string, unknown>> | undefined	The Standard Schema v1 compatible schema for the message headers (optional)

Properties

Property	Type	Description	Defined in
description?	string	Detailed description of the message for documentation purposes. Used in AsyncAPI specification generation.	types.ts:797
headers?	THeaders	Optional headers schema for validating message metadata. Must be a Standard Schema v1 compatible schema.	types.ts:785
payload	TPayload	The payload schema for validating message content. Must be a Standard Schema v1 compatible schema (Zod, Valibot, ArkType, etc.).	types.ts:779
summary?	string	Brief description of the message for documentation purposes. Used in AsyncAPI specification generation.	types.ts:791

---

PublisherDefinition

type PublisherDefinition<TMessage> = object & 
  | {
  exchange:   | DirectExchangeDefinition
     | TopicExchangeDefinition;
  routingKey: string;
}
  | {
  exchange:   | FanoutExchangeDefinition
     | HeadersExchangeDefinition;
  routingKey?: never;
};

Defined in: types.ts:913

Definition of a message publisher.

A publisher sends messages to an exchange with automatic schema validation. The message payload is validated against the schema before being sent to RabbitMQ.

Compression can be optionally applied at publish time by specifying a compression algorithm when calling the publish method.

Type Declaration

Name	Type	Description	Defined in
message	TMessage	The message definition including the payload schema	types.ts:915

Type Parameters

Type Parameter	Default type	Description
TMessage extends MessageDefinition	MessageDefinition	The message definition with payload schema

Example

const publisher: PublisherDefinition = {
  exchange: ordersExchange,
  message: orderMessage,
  routingKey: 'order.created'
};

---

PublisherEntry

type PublisherEntry = 
  | PublisherDefinition
  | EventPublisherConfigBase
  | BridgedPublisherConfigBase;

Defined in: types.ts:1149

Publisher entry that can be passed to defineContract's publishers section.

Can be either:

• A plain PublisherDefinition from definePublisher
• An EventPublisherConfig from defineEventPublisher (auto-extracted to publisher)
• An BridgedPublisherConfig from defineCommandPublisher (auto-extracted to publisher)

---

QueueBindingDefinition

type QueueBindingDefinition = object & 
  | {
  exchange:   | DirectExchangeDefinition
     | TopicExchangeDefinition;
  routingKey: string;
}
  | {
  exchange:   | FanoutExchangeDefinition
     | HeadersExchangeDefinition;
  routingKey?: never;
};

Defined in: types.ts:807

Binding between a queue and an exchange.

Defines how messages from an exchange should be routed to a queue. For direct and topic exchanges, a routing key is required. For fanout and headers exchanges, no routing key is needed.

Type Declaration

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:818
queue	QueueDefinition	The queue that will receive messages	types.ts:812
type	"queue"	Discriminator indicating this is a queue-to-exchange binding	types.ts:809

---

QueueDefinition

type QueueDefinition<TName> = 
  | QuorumQueueDefinition<TName>
  | ClassicQueueDefinition<TName>;

Defined in: types.ts:646

Definition of an AMQP queue.

A discriminated union based on queue type:

• QuorumQueueDefinition: For quorum queues (type: "quorum")
• ClassicQueueDefinition: For classic queues (type: "classic")

Use queue.type as the discriminator to narrow the type.

Type Parameters

Type Parameter	Default type
TName extends string	string

---

QueueEntry

type QueueEntry<TName> = 
  | QueueDefinition<TName>
  | QueueWithTtlBackoffInfrastructure<TName>;

Defined in: types.ts:749

A queue entry that can be passed to defineContract.

Can be either a plain queue definition or a queue with TTL-backoff infrastructure.

Type Parameters

Type Parameter	Default type
TName extends string	string

---

QueueType

type QueueType = "quorum" | "classic";

Defined in: types.ts:227

Supported queue types in RabbitMQ.

• quorum: Quorum queues (default, recommended) - Provide better durability and high-availability using the Raft consensus algorithm. Best for most production use cases.
• classic: Classic queues - The traditional RabbitMQ queue type. Use only when you need specific features not supported by quorum queues (e.g., non-durable queues, priority queues).

Note: Quorum queues only support durable queues, and do not support exclusive, auto-deleting, or priority queues.

See

https://www.rabbitmq.com/docs/quorum-queues

Example

// Create a quorum queue (default, recommended)
const orderQueue = defineQueue('order-processing', {
  type: 'quorum', // This is the default
});

// Create a classic queue (for special cases)
const tempQueue = defineQueue('temp-queue', {
  type: 'classic',
  durable: false, // Only supported with classic queues
});

---

QueueWithTtlBackoffInfrastructure

type QueueWithTtlBackoffInfrastructure<TName> = object;

Defined in: types.ts:706

A queue with automatically generated TTL-backoff retry infrastructure.

This type is returned by defineQueue when TTL-backoff retry is configured. When passed to defineContract, the wait queue, exchanges, and bindings are automatically added to the contract.

Example

const exchange = defineExchange('orders');
const queue = defineQueue('order-processing', {
  retry: { mode: 'ttl-backoff', maxRetries: 5 },
});
// queue is QueueWithTtlBackoffInfrastructure
const message = defineMessage(z.object({ orderId: z.string() }));
const orderCreated = defineEventPublisher(exchange, message, { routingKey: 'order.created' });

// Wait queue, exchanges, and bindings are automatically extracted
const contract = defineContract({
  publishers: { orderCreated },
  consumers: { processOrder: defineEventConsumer(orderCreated, queue) },
});

Type Parameters

Type Parameter	Default type
TName extends string	string

Properties

Property	Type	Description	Defined in
queue	QueueDefinition<TName>	The main queue definition.	types.ts:716
retryExchange	HeadersExchangeDefinition	Retry exchange used to route messages to retry back to the main queue.	types.ts:731
retryQueueBinding	QueueBindingDefinition	Binding that routes messages to retry back to the main queue.	types.ts:741
waitExchange	HeadersExchangeDefinition	Wait exchange used to route failed messages to the wait queue.	types.ts:726
waitQueue	QueueDefinition	The wait queue for holding messages during backoff delay.	types.ts:721
waitQueueBinding	QueueBindingDefinition	Binding that routes failed messages to the wait queue.	types.ts:736

---

QuorumQueueDefinition

type QuorumQueueDefinition<TName> = BaseQueueDefinition<TName> & object;

Defined in: types.ts:572

Definition of a quorum queue.

Quorum queues provide better durability and high-availability using the Raft consensus algorithm.

Type Declaration

Name	Type	Description	Defined in
autoDelete?	never	Quorum queues do not support auto-delete mode. Use type: 'classic' if you need auto-deleting queues.	types.ts:593
durable	true	Quorum queues only support durable queues.	types.ts:581
exclusive?	never	Quorum queues do not support exclusive mode. Use type: 'classic' if you need exclusive queues.	types.ts:587
maxPriority?	never	Quorum queues do not support priority queues. Use type: 'classic' if you need priority queues.	types.ts:599
type	"quorum"	Queue type discriminator: quorum queue.	types.ts:576

Type Parameters

Type Parameter	Default type
TName extends string	string

---

QuorumQueueOptions

type QuorumQueueOptions = BaseQueueOptions & object;

Defined in: types.ts:295

Options for creating a quorum queue.

Quorum queues do not support:

• exclusive - Use classic queues for connection-scoped queues
• autoDelete - Use classic queues for auto-deleting queues when consumers disconnect
• maxPriority - Use classic queues for priority queues
• durable: false - Use classic queues for non-durable queues

Quorum queues provide native retry support for immediate-requeue retry mode:

• RabbitMQ tracks delivery count automatically via x-delivery-count header
• When the limit is exceeded, messages are dead-lettered (if DLX is configured) or dropped
• This is simpler than TTL-based retry and avoids head-of-queue blocking issues

Type Declaration

Name	Type	Description	Defined in
autoDelete?	never	Quorum queues do not support auto-delete mode. Use type: 'classic' if you need auto-deleting queues.	types.ts:316
durable?	true	Quorum queues only support durable queues.	types.ts:304
exclusive?	never	Quorum queues do not support exclusive mode. Use type: 'classic' if you need exclusive queues.	types.ts:310
maxPriority?	never	Quorum queues do not support priority queues. Use type: 'classic' if you need priority queues.	types.ts:322
type?	"quorum"	Queue type: quorum (default, recommended)	types.ts:299

Example

const orderQueue = defineQueue('orders', {
  type: 'quorum',
  deadLetter: { exchange: dlx },
  retry: { mode: 'immediate-requeue', maxRetries: 3 } // Message dead-lettered after 3 retry attempts
});

---

ResolvedRetryOptions

type ResolvedRetryOptions = 
  | NoneRetryOptions
  | ResolvedImmediateRequeueRetryOptions
  | ResolvedTtlBackoffRetryOptions;

Defined in: types.ts:166

Resolved retry configuration stored in queue definitions.

This is a discriminated union based on the mode field:

• none: No retry attempts are made; failed messages are handled by DLQ/reject
• immediate-requeue: Has all immediate-requeue retry options with default applied
• ttl-backoff: Has all TTL-backoff retry options with defaults applied

When using ttl-backoff mode, the core package will automatically create a wait queue and the necessary exchanges and bindings.

---

RoutingKey

type RoutingKey<S> = S extends "" ? never : S extends `${string}*${string}` | `${string}#${string}` ? never : S;

Defined in: builder/routing-types.ts:25

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

type Valid = RoutingKey<"order.created">; // "order.created"
type Invalid = RoutingKey<"order.*">; // never (contains wildcard)
type Invalid2 = RoutingKey<"">; // never (empty string)

---

RpcDefinition

type RpcDefinition<TRequestMessage, TResponseMessage, TQueue> = object;

Defined in: types.ts:1047

Definition of an RPC operation: a request/response pair flowing over a request queue with replies routed back via direct reply-to.

An RPC is bidirectional on both ends — the server consumes requests and publishes responses; the client publishes requests and consumes responses — so it has its own slot in the contract (rpcs) rather than being shoehorned into consumers or publishers.

See

defineRpc for creating RPC definitions

Type Parameters

Type Parameter	Default type	Description
TRequestMessage extends MessageDefinition	MessageDefinition	The request message definition
TResponseMessage extends MessageDefinition	MessageDefinition	The response message definition
TQueue extends QueueEntry	QueueEntry	The request queue entry

Properties

Property	Type	Description	Defined in
queue	TQueue	The queue that receives RPC requests. Replies are routed back via direct reply-to.	types.ts:1053
request	TRequestMessage	Schema for the request payload (validated on both publish and consume).	types.ts:1055
response	TResponseMessage	Schema for the response payload (validated on both worker reply and client receive).	types.ts:1057

---

TopicExchangeDefinition

type TopicExchangeDefinition<TName> = BaseExchangeDefinition<TName> & object;

Defined in: types.ts:441

A topic exchange definition.

Topic exchanges route messages to queues based on routing key patterns with wildcards:

• * (star) matches exactly one word
• # (hash) matches zero or more words

Words are separated by dots (e.g., order.created.high-value).

Type Declaration

Name	Type	Defined in
type	"topic"	types.ts:443

Type Parameters

Type Parameter	Default type
TName extends string	string

Example

const ordersExchange: TopicExchangeDefinition = defineExchange('orders', {
  type: 'topic', // This is the default type, so it can be omitted
});
// Can be bound with patterns like 'order.*' or 'order.#'

---

TtlBackoffRetryOptions

type TtlBackoffRetryOptions = object;

Defined in: types.ts:27

TTL-Backoff retry options for exponential backoff with configurable delays.

Uses TTL + wait queue pattern. Messages are published to a wait queue with per-message TTL, then dead-lettered back to the main queue after the TTL expires.

Benefits: Configurable delays with exponential backoff and jitter. Limitation: More complex, potential head-of-queue blocking with mixed TTLs.

Properties

Property	Type	Description	Defined in
backoffMultiplier?	number	Exponential backoff multiplier. Default 2	types.ts:52
initialDelayMs?	number	Initial delay in ms before first retry. Default 1000	types.ts:42
jitter?	boolean	Add jitter to prevent thundering herd. Default true	types.ts:57
maxDelayMs?	number	Maximum delay in ms between retries. Default 30000	types.ts:47
maxRetries?	number	Maximum retry attempts before sending to DLQ. Minimum 1 - Must be a positive integer (1 or greater) Default 3	types.ts:37
mode	"ttl-backoff"	TTL-Backoff mode uses wait queues with per-message TTL for exponential backoff.	types.ts:31
retryExchangeName?	string	Name of the retry exchange. Default 'retry-exchange'	types.ts:72
waitExchangeName?	string	Name of the wait exchange. Default 'wait-exchange'	types.ts:67
waitQueueName?	string	Name of the wait queue. Default '{queueName}-wait'	types.ts:62

Functions

defineConsumer()

function defineConsumer<TMessage>(
   queue, 
   message, 
   options?): ConsumerDefinition<TMessage>;

Defined in: builder/consumer.ts:120

Define a message consumer.

A consumer receives and processes messages from a queue. The message schema is validated automatically when messages are consumed, ensuring type safety for your handlers.

Consumers are associated with a specific queue and message type. When you create a worker with this consumer, it will process messages from the queue according to the schema.

Which pattern to use:

Pattern	Best for	Description
definePublisher + defineConsumer	Independent definition	Define publishers and consumers separately with manual schema consistency
defineEventPublisher + defineEventConsumer	Event broadcasting	Define event publisher first, create consumers that subscribe to it
defineCommandConsumer + defineCommandPublisher	Task queues	Define command consumer first, create publishers that send commands to it

Use defineCommandConsumer when:

• One consumer receives from multiple publishers
• You want automatic schema consistency between consumer and publishers
• You're building task queue or command patterns

Type Parameters

Type Parameter
TMessage extends MessageDefinition

Parameters

Parameter	Type	Description
queue	QueueEntry	The queue definition to consume from
message	TMessage	The message definition with payload schema
options?	Omit<ConsumerDefinition<TMessage>, "queue" | "message">	Optional consumer configuration

Returns

ConsumerDefinition<TMessage>

A consumer definition with inferred message types

Example

import { z } from 'zod';

const orderQueue = defineQueue('order-processing');
const orderMessage = defineMessage(
  z.object({
    orderId: z.string().uuid(),
    customerId: z.string().uuid(),
    amount: z.number().positive(),
  })
);

const processOrderConsumer = defineConsumer(orderQueue, orderMessage);

// Later, when creating a worker, you'll provide a handler for this consumer:
// const worker = await TypedAmqpWorker.create({
//   contract,
//   handlers: {
//     processOrder: async (message) => {
//       // message is automatically typed based on the schema
//       console.log(message.orderId); // string
//     }
//   },
//   connection
// });

See

• defineCommandConsumer - For task queue patterns with automatic schema consistency
• defineEventPublisher - For event-driven patterns with automatic schema consistency

---

defineContract()

function defineContract<TContract>(definition): ContractOutput<TContract>;

Defined in: builder/contract.ts:136

Define an AMQP contract.

A contract is the central definition of your AMQP messaging topology. It brings together publishers and consumers in a single, type-safe definition. Exchanges, queues, and bindings are automatically extracted from publishers and consumers.

The contract is used by both clients (for publishing) and workers (for consuming) to ensure type safety throughout your messaging infrastructure. TypeScript will infer all message types and publisher/consumer names from the contract.

Type Parameters

Type Parameter
TContract extends ContractDefinitionInput

Parameters

Parameter	Type	Description
definition	TContract	The contract definition containing publishers and consumers

Returns

ContractOutput<TContract>

The contract definition with fully inferred exchanges, queues, bindings, publishers, and consumers

Example

import {
  defineContract,
  defineExchange,
  defineQueue,
  defineEventPublisher,
  defineEventConsumer,
  defineMessage,
} from '@amqp-contract/contract';
import { z } from 'zod';

// Define resources
const ordersExchange = defineExchange('orders');
const dlx = defineExchange('orders-dlx', { type: 'direct' });
const orderQueue = defineQueue('order-processing', {
  deadLetter: { exchange: dlx },
  retry: { mode: 'immediate-requeue', maxRetries: 3 },
});
const orderMessage = defineMessage(
  z.object({
    orderId: z.string(),
    amount: z.number(),
  })
);

// Define event publisher
const orderCreatedEvent = defineEventPublisher(ordersExchange, orderMessage, {
  routingKey: 'order.created',
});

// Compose contract - exchanges, queues, bindings are auto-extracted
export const contract = defineContract({
  publishers: {
    orderCreated: orderCreatedEvent,
  },
  consumers: {
    processOrder: defineEventConsumer(orderCreatedEvent, orderQueue),
  },
});

// TypeScript now knows:
// - contract.exchanges.orders, contract.exchanges['orders-dlx']
// - contract.queues['order-processing']
// - contract.bindings.processOrderBinding
// - client.publish('orderCreated', { orderId: string, amount: number })
// - handler: (message: { orderId: string, amount: number }) => Future<Result<void, HandlerError>>

---

defineMessage()

function defineMessage<TPayload, THeaders>(payload, options?): MessageDefinition<TPayload, THeaders>;

Defined in: builder/message.ts:39

Define a message definition with payload and optional headers/metadata.

A message definition specifies the schema for message payloads and headers using Standard Schema v1 compatible libraries (Zod, Valibot, ArkType, etc.). The schemas are used for automatic validation when publishing or consuming messages.

Type Parameters

Type Parameter	Default type
TPayload extends AnySchema	-
THeaders extends | StandardSchemaV1<Record<string, unknown>, Record<string, unknown>> | undefined	undefined

Parameters

Parameter	Type	Description
payload	TPayload	The payload schema (must be Standard Schema v1 compatible)
options?	{ description?: string; headers?: THeaders; summary?: string; }	Optional message metadata
options.description?	string	Detailed description for documentation (used in AsyncAPI generation)
options.headers?	THeaders	Optional header schema for message headers
options.summary?	string	Brief description for documentation (used in AsyncAPI generation)

Returns

MessageDefinition<TPayload, THeaders>

A message definition with inferred types

Example

import { z } from 'zod';

const orderMessage = defineMessage(
  z.object({
    orderId: z.string().uuid(),
    customerId: z.string().uuid(),
    amount: z.number().positive(),
    items: z.array(z.object({
      productId: z.string(),
      quantity: z.number().int().positive(),
    })),
  }),
  {
    summary: 'Order created event',
    description: 'Emitted when a new order is created in the system'
  }
);

---

defineQueue()

Call Signature

function defineQueue<TName, TDlx>(name, options): QueueEntryWithDeadLetterExchange<TName, TDlx>;

Defined in: builder/queue.ts:113

Define an AMQP queue.

A queue stores messages until they are consumed by workers. Queues can be bound to exchanges to receive messages based on routing rules.

By default, queues are created as quorum queues which provide better durability and high-availability. Use type: 'classic' for special cases like non-durable queues or priority queues.

Type Parameters

Type Parameter
TName extends string
TDlx extends ExchangeDefinition

Parameters

Parameter	Type	Description
name	TName	The name of the queue
options	DefineQueueOptionsWithDeadLetterExchange<TDlx>	Optional queue configuration

Returns

QueueEntryWithDeadLetterExchange<TName, TDlx>

A queue definition

Example

// Quorum queue (default, recommended for production)
const orderQueue = defineQueue('order-processing');

// Explicit quorum queue with dead letter exchange
const dlx = defineExchange('orders-dlx');
const orderQueueWithDLX = defineQueue('order-processing', {
  type: 'quorum',
  deadLetter: {
    exchange: dlx,
    routingKey: 'order.failed'
  },
  arguments: {
    'x-message-ttl': 86400000, // 24 hours
  }
});

// Classic queue (for special cases)
const tempQueue = defineQueue('temp-queue', {
  type: 'classic',
  durable: false,
  autoDelete: true,
});

// Priority queue (requires classic type)
const taskQueue = defineQueue('urgent-tasks', {
  type: 'classic',
  maxPriority: 10,
});

// Queue with TTL-backoff retry (returns infrastructure automatically)
const dlx = defineExchange('orders-dlx', { type: 'direct' });
const orderQueue = defineQueue('order-processing', {
  deadLetter: { exchange: dlx },
  retry: { mode: 'ttl-backoff', maxRetries: 5 },
});
// orderQueue is QueueWithTtlBackoffInfrastructure, pass directly to defineContract

Call Signature

function defineQueue<TName>(name, options?): QueueEntry<TName>;

Defined in: builder/queue.ts:118

Define an AMQP queue.

A queue stores messages until they are consumed by workers. Queues can be bound to exchanges to receive messages based on routing rules.

By default, queues are created as quorum queues which provide better durability and high-availability. Use type: 'classic' for special cases like non-durable queues or priority queues.

Type Parameters

Type Parameter
TName extends string

Parameters

Parameter	Type	Description
name	TName	The name of the queue
options?	DefineQueueOptions	Optional queue configuration

Returns

QueueEntry<TName>

A queue definition

Example

// Quorum queue (default, recommended for production)
const orderQueue = defineQueue('order-processing');

// Explicit quorum queue with dead letter exchange
const dlx = defineExchange('orders-dlx');
const orderQueueWithDLX = defineQueue('order-processing', {
  type: 'quorum',
  deadLetter: {
    exchange: dlx,
    routingKey: 'order.failed'
  },
  arguments: {
    'x-message-ttl': 86400000, // 24 hours
  }
});

// Classic queue (for special cases)
const tempQueue = defineQueue('temp-queue', {
  type: 'classic',
  durable: false,
  autoDelete: true,
});

// Priority queue (requires classic type)
const taskQueue = defineQueue('urgent-tasks', {
  type: 'classic',
  maxPriority: 10,
});

// Queue with TTL-backoff retry (returns infrastructure automatically)
const dlx = defineExchange('orders-dlx', { type: 'direct' });
const orderQueue = defineQueue('order-processing', {
  deadLetter: { exchange: dlx },
  retry: { mode: 'ttl-backoff', maxRetries: 5 },
});
// orderQueue is QueueWithTtlBackoffInfrastructure, pass directly to defineContract

---

defineRpc()

function defineRpc<TRequestMessage, TResponseMessage, TQueue>(queue, messages): RpcDefinition<TRequestMessage, TResponseMessage, TQueue>;

Defined in: builder/rpc.ts:41

Define an RPC operation: a request/response pair flowing over a request queue with replies routed back via RabbitMQ direct reply-to.

RPC is bidirectional on both ends — the worker handler consumes the request and produces the response; client.call(name, request, options) publishes the request and awaits the typed response. Both sides share the same definition, so request and response schemas cannot drift between them.

Plug the result into defineContract({ rpcs: { name: ... } }). RPCs do not appear in publishers or consumers.

Type Parameters

Type Parameter
TRequestMessage extends MessageDefinition
TResponseMessage extends MessageDefinition
TQueue extends QueueEntry

Parameters

Parameter	Type	Description
queue	TQueue	The queue that receives RPC requests. The queue name is used as the routing key on the AMQP default direct exchange.
messages	{ request: TRequestMessage; response: TResponseMessage; }	-
messages.request	TRequestMessage	Schema validated against incoming request payloads (server side) and outgoing requests (client side).
messages.response	TResponseMessage	Schema validated against handler return values (server side) and incoming replies (client side).

Returns

RpcDefinition<TRequestMessage, TResponseMessage, TQueue>

Example

import { defineQueue, defineMessage, defineRpc, defineContract } from '@amqp-contract/contract';
import { z } from 'zod';

const calculate = defineRpc(defineQueue('rpc.calculate'), {
  request: defineMessage(z.object({ a: z.number(), b: z.number() })),
  response: defineMessage(z.object({ sum: z.number() })),
});

const contract = defineContract({ rpcs: { calculate } });

// Server (worker): handler returns the typed response
//   handlers: { calculate: ({ payload }) => okAsync({ sum: payload.a + payload.b }) }

// Client: typed call with required timeout
//   const result = await client.call('calculate', { a: 1, b: 2 }, { timeoutMs: 5_000 });

---

extractConsumer()

function extractConsumer(entry): ConsumerDefinition;

Defined in: builder/consumer.ts:54

Extract the ConsumerDefinition from any ConsumerEntry type.

Handles the following entry types:

• ConsumerDefinition: returned as-is
• EventConsumerResult: returns the nested .consumer property
• CommandConsumerConfig: returns the nested .consumer property

Use this function when you need to access the underlying ConsumerDefinition from a consumer entry that may have been created with defineEventConsumer or defineCommandConsumer.

Parameters

Parameter	Type	Description
entry	ConsumerEntry	The consumer entry to extract from

Returns

ConsumerDefinition

The underlying ConsumerDefinition

Example

// Works with plain ConsumerDefinition
const consumer1 = defineConsumer(queue, message);
extractConsumer(consumer1).queue.name; // "my-queue"

// Works with EventConsumerResult
const consumer2 = defineEventConsumer(eventPublisher, queue);
extractConsumer(consumer2).queue.name; // "my-queue"

// Works with CommandConsumerConfig
const consumer3 = defineCommandConsumer(queue, exchange, message, { routingKey: "cmd" });
extractConsumer(consumer3).queue.name; // "my-queue"

---

extractQueue()

function extractQueue<T>(entry): ExtractQueueFromEntry<T>;

Defined in: builder/queue-utils.ts:60

Extract the plain QueueDefinition from a QueueEntry.

Why this function exists: When you configure a queue with TTL-backoff retry, defineQueue returns a wrapper object that includes the main queue, wait queue, headers exchanges, and bindings. This function extracts the underlying queue definition so you can access properties like name, type, etc.

When to use:

• When you need to access queue properties (name, type, etc.)
• When passing a queue to functions that expect a plain QueueDefinition
• Works safely on both plain queues and infrastructure wrappers

How it works:

• If the entry is a QueueWithTtlBackoffInfrastructure, returns entry.queue
• Otherwise, returns the entry as-is (it's already a plain QueueDefinition)

Type Parameters

Type Parameter
T extends QueueEntry

Parameters

Parameter	Type	Description
entry	T	The queue entry (either plain QueueDefinition or QueueWithTtlBackoffInfrastructure)

Returns

ExtractQueueFromEntry<T>

The plain QueueDefinition

Example

import { defineQueue, extractQueue } from '@amqp-contract/contract';

// TTL-backoff queue returns a wrapper
const orderQueue = defineQueue('orders', {
  retry: { mode: 'ttl-backoff', maxRetries: 3 },
});

// Use extractQueue to access the queue name
const queueName = extractQueue(orderQueue).name; // 'orders'

// Also works safely on plain queues
const plainQueue = defineQueue('simple', { type: 'quorum', retry: { mode: 'immediate-requeue' } });
const plainName = extractQueue(plainQueue).name; // 'simple'

// Access other properties
const queueDef = extractQueue(orderQueue);
console.log(queueDef.name);       // 'orders'
console.log(queueDef.type);       // 'quorum'

See

isQueueWithTtlBackoffInfrastructure - Type guard to check if extraction is needed

---

isBridgedPublisherConfig()

function isBridgedPublisherConfig(value): value is BridgedPublisherConfig<MessageDefinition, ExchangeDefinition, ExchangeDefinition>;

Defined in: builder/command.ts:514

Type guard to check if a value is a BridgedPublisherConfig.

Parameters

Parameter	Type	Description
value	unknown	The value to check

Returns

value is BridgedPublisherConfig<MessageDefinition, ExchangeDefinition, ExchangeDefinition>

True if the value is a BridgedPublisherConfig

---

isCommandConsumerConfig()

function isCommandConsumerConfig(value): value is CommandConsumerConfig<MessageDefinition, ExchangeDefinition, string | undefined, QueueEntry>;

Defined in: builder/command.ts:497

Type guard to check if a value is a CommandConsumerConfig.

Parameters

Parameter	Type	Description
value	unknown	The value to check

Returns

value is CommandConsumerConfig<MessageDefinition, ExchangeDefinition, string | undefined, QueueEntry>

True if the value is a CommandConsumerConfig

---

isEventConsumerResult()

function isEventConsumerResult(value): value is EventConsumerResult<MessageDefinition, ExchangeDefinition, QueueEntry, ExchangeBindingDefinition | undefined, ExchangeDefinition | undefined>;

Defined in: builder/event.ts:616

Type guard to check if a value is an EventConsumerResult.

Parameters

Parameter	Type	Description
value	unknown	The value to check

Returns

value is EventConsumerResult<MessageDefinition, ExchangeDefinition, QueueEntry, ExchangeBindingDefinition | undefined, ExchangeDefinition | undefined>

True if the value is an EventConsumerResult

---

isEventPublisherConfig()

function isEventPublisherConfig(value): value is EventPublisherConfig<MessageDefinition, ExchangeDefinition, string | undefined>;

Defined in: builder/event.ts:599

Type guard to check if a value is an EventPublisherConfig.

Parameters

Parameter	Type	Description
value	unknown	The value to check

Returns

value is EventPublisherConfig<MessageDefinition, ExchangeDefinition, string | undefined>

True if the value is an EventPublisherConfig

---

isQueueWithTtlBackoffInfrastructure()

function isQueueWithTtlBackoffInfrastructure(entry): entry is QueueWithTtlBackoffInfrastructure;

Defined in: builder/ttl-backoff.ts:43

Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.

When you configure a queue with TTL-backoff retry, defineQueue returns a QueueWithTtlBackoffInfrastructure instead of a plain QueueDefinition. This type guard helps you distinguish between the two.

When to use:

• When you need to check the type of a queue entry at runtime
• When writing generic code that handles both plain queues and infrastructure wrappers

Related functions:

• extractQueue() - Use this to get the underlying queue definition from either type

Parameters

Parameter	Type	Description
entry	QueueEntry	The queue entry to check

Returns

entry is QueueWithTtlBackoffInfrastructure

True if the entry is a QueueWithTtlBackoffInfrastructure, false otherwise

Example

const queue = defineQueue('orders', {
  retry: { mode: 'ttl-backoff' },
});

if (isQueueWithTtlBackoffInfrastructure(queue)) {
  // queue has .queue, .waitQueue, .waitQueueBinding, .retryQueueBinding, .waitExchange, .retryExchange
  console.log('Wait queue:', queue.waitQueue.name);
} else {
  // queue is a plain QueueDefinition
  console.log('Queue:', queue.name);
}