@amqp-contract/core

---

@amqp-contract/core

Classes

AmqpClient

Defined in: amqp-client.ts:49

AMQP client that manages connections and channels with automatic topology setup.

This class handles:

• Connection management with automatic reconnection via amqp-connection-manager
• Connection pooling and sharing across instances with the same URLs
• Automatic AMQP topology setup (exchanges, queues, bindings) from contract
• Channel creation with JSON serialization enabled by default

Example

const client = new AmqpClient(contract, {
  urls: ['amqp://localhost'],
  connectionOptions: { heartbeatIntervalInSeconds: 30 }
});

// Use the channel to publish messages
await client.channel.publish('exchange', 'routingKey', { data: 'value' });

// Close when done
await client.close();

Constructors

Constructor

new AmqpClient(contract, options): AmqpClient;

Defined in: amqp-client.ts:66

Create a new AMQP client instance.

The client will automatically:

• Get or create a shared connection using the singleton pattern
• Set up AMQP topology (exchanges, queues, bindings) from the contract
• Create a channel with JSON serialization enabled

Parameters

Parameter	Type	Description
contract	ContractDefinition	The contract definition specifying the AMQP topology
options	AmqpClientOptions	Client configuration options

Returns

AmqpClient

Properties

Property	Modifier	Type	Defined in
channel	readonly	ChannelWrapper	amqp-client.ts:51

Methods

close()

close(): Promise<void>;

Defined in: amqp-client.ts:143

Close the channel and release the connection reference.

This will:

• Close the channel wrapper
• Decrease the reference count on the shared connection
• Close the connection if this was the last client using it

Returns

Promise<void>

A promise that resolves when the channel and connection are closed

getConnection()

getConnection(): IAmqpConnectionManager;

Defined in: amqp-client.ts:129

Get the underlying connection manager

This method exposes the AmqpConnectionManager instance that this client uses. The connection is automatically shared across all AmqpClient instances that use the same URLs and connection options.

Returns

IAmqpConnectionManager

The AmqpConnectionManager instance used by this client

---

ConnectionManagerSingleton

Defined in: connection-manager.ts:23

Connection manager singleton for sharing AMQP connections across clients.

This singleton implements connection pooling to avoid creating multiple connections to the same broker, which is a RabbitMQ best practice. Connections are identified by their URLs and connection options, and reference counting ensures connections are only closed when all clients have released them.

Example

const manager = ConnectionManagerSingleton.getInstance();
const connection = manager.getConnection(['amqp://localhost']);
// ... use connection ...
await manager.releaseConnection(['amqp://localhost']);

Methods

getConnection()

getConnection(urls, connectionOptions?): IAmqpConnectionManager;

Defined in: connection-manager.ts:52

Get or create a connection for the given URLs and options.

If a connection already exists with the same URLs and options, it is reused and its reference count is incremented. Otherwise, a new connection is created.

Parameters

Parameter	Type	Description
urls	ConnectionUrl[]	AMQP broker URL(s)
connectionOptions?	AmqpConnectionManagerOptions	Optional connection configuration

Returns

IAmqpConnectionManager

The AMQP connection manager instance

releaseConnection()

releaseConnection(urls, connectionOptions?): Promise<void>;

Defined in: connection-manager.ts:81

Release a connection reference.

Decrements the reference count for the connection. If the count reaches zero, the connection is closed and removed from the pool.

Parameters

Parameter	Type	Description
urls	ConnectionUrl[]	AMQP broker URL(s) used to identify the connection
connectionOptions?	AmqpConnectionManagerOptions	Optional connection configuration used to identify the connection

Returns

Promise<void>

A promise that resolves when the connection is released (and closed if necessary)

getInstance()

static getInstance(): ConnectionManagerSingleton;

Defined in: connection-manager.ts:35

Get the singleton instance of the connection manager.

Returns

ConnectionManagerSingleton

The singleton instance

Type Aliases

AmqpClientOptions

type AmqpClientOptions = object;

Defined in: amqp-client.ts:20

Options for creating an AMQP client.

Properties

Property	Type	Description	Defined in
channelOptions?	Partial<CreateChannelOpts>	Optional channel configuration options.	amqp-client.ts:23
connectionOptions?	AmqpConnectionManagerOptions	Optional connection configuration (heartbeat, reconnect settings, etc.).	amqp-client.ts:22
urls	ConnectionUrl[]	AMQP broker URL(s). Multiple URLs provide failover support.	amqp-client.ts:21

---

Logger

type Logger = object;

Defined in: logger.ts:30

Logger interface for amqp-contract packages.

Provides a simple logging abstraction that can be implemented by users to integrate with their preferred logging framework.

Example

// Simple console logger implementation
const logger: Logger = {
  debug: (message, context) => console.debug(message, context),
  info: (message, context) => console.info(message, context),
  warn: (message, context) => console.warn(message, context),
  error: (message, context) => console.error(message, context),
};

Methods

debug()

debug(message, context?): void;

Defined in: logger.ts:36

Log debug level messages

Parameters

Parameter	Type	Description
message	string	The log message
context?	LoggerContext	Optional context to include with the log

Returns

void

error()

error(message, context?): void;

Defined in: logger.ts:57

Log error level messages

Parameters

Parameter	Type	Description
message	string	The log message
context?	LoggerContext	Optional context to include with the log

Returns

void

info()

info(message, context?): void;

Defined in: logger.ts:43

Log info level messages

Parameters

Parameter	Type	Description
message	string	The log message
context?	LoggerContext	Optional context to include with the log

Returns

void

warn()

warn(message, context?): void;

Defined in: logger.ts:50

Log warning level messages

Parameters

Parameter	Type	Description
message	string	The log message
context?	LoggerContext	Optional context to include with the log

Returns

void

---

LoggerContext

type LoggerContext = Record<string, unknown> & object;

Defined in: logger.ts:9

Context object for logger methods.

This type includes reserved keys that provide consistent naming for common logging context properties.

Type Declaration

Name	Type	Defined in
error?	unknown	logger.ts:10

Functions

setupAmqpTopology()

function setupAmqpTopology(channel, contract): Promise<void>;

Defined in: setup.ts:24

Setup AMQP topology (exchanges, queues, and bindings) from a contract definition.

This function sets up the complete AMQP topology in the correct order:

1. Assert all exchanges defined in the contract
2. Validate dead letter exchanges are declared before referencing them
3. Assert all queues with their configurations (including dead letter settings)
4. Create all bindings (queue-to-exchange and exchange-to-exchange)

Parameters

Parameter	Type	Description
channel	Channel	The AMQP channel to use for topology setup
contract	ContractDefinition	The contract definition containing the topology specification

Returns

Promise<void>

Throws

If any exchanges, queues, or bindings fail to be created

Throws

If a queue references a dead letter exchange not declared in the contract

Example

const channel = await connection.createChannel();
await setupAmqpTopology(channel, contract);