@amqp-contract/contract 0.11.0 → 0.12.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-//#region src/builder.ts
+//#region src/builder/exchange.ts
 /**
 * Define an AMQP exchange.
 *
@@ -19,6 +19,200 @@ function defineExchange(name, type, options) {
 		...options
 	};
 }
+
+//#endregion
+//#region src/builder/message.ts
+/**
+* Define a message definition with payload and optional headers/metadata.
+*
+* A message definition specifies the schema for message payloads and headers using
+* Standard Schema v1 compatible libraries (Zod, Valibot, ArkType, etc.).
+* The schemas are used for automatic validation when publishing or consuming messages.
+*
+* @param payload - The payload schema (must be Standard Schema v1 compatible)
+* @param options - Optional message metadata
+* @param options.headers - Optional header schema for message headers
+* @param options.summary - Brief description for documentation (used in AsyncAPI generation)
+* @param options.description - Detailed description for documentation (used in AsyncAPI generation)
+* @returns A message definition with inferred types
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+*
+* const orderMessage = defineMessage(
+*   z.object({
+*     orderId: z.string().uuid(),
+*     customerId: z.string().uuid(),
+*     amount: z.number().positive(),
+*     items: z.array(z.object({
+*       productId: z.string(),
+*       quantity: z.number().int().positive(),
+*     })),
+*   }),
+*   {
+*     summary: 'Order created event',
+*     description: 'Emitted when a new order is created in the system'
+*   }
+* );
+* ```
+*/
+function defineMessage(payload, options) {
+	return {
+		payload,
+		...options
+	};
+}
+
+//#endregion
+//#region src/builder/binding.ts
+/**
+* Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
+* Duplicated here to avoid circular dependency with queue.ts.
+* @internal
+*/
+function isQueueWithTtlBackoffInfrastructure$1(entry) {
+	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
+}
+/**
+* Extract the plain QueueDefinition from a QueueEntry.
+* Duplicated here to avoid circular dependency with queue.ts.
+* @internal
+*/
+function extractQueueInternal(entry) {
+	if (isQueueWithTtlBackoffInfrastructure$1(entry)) return entry.queue;
+	return entry;
+}
+/**
+* Define a binding between a queue and an exchange.
+*
+* This is the implementation function - use the type-specific overloads for better type safety.
+*
+* @param queue - The queue definition or queue with infrastructure to bind
+* @param exchange - The exchange definition
+* @param options - Optional binding configuration
+* @returns A queue binding definition
+* @internal
+*/
+function defineQueueBinding(queue, exchange, options) {
+	const queueDef = extractQueueInternal(queue);
+	if (exchange.type === "fanout") return {
+		type: "queue",
+		queue: queueDef,
+		exchange,
+		...options?.arguments && { arguments: options.arguments }
+	};
+	return {
+		type: "queue",
+		queue: queueDef,
+		exchange,
+		routingKey: options?.routingKey,
+		...options?.arguments && { arguments: options.arguments }
+	};
+}
+/**
+* Internal helper to call defineQueueBinding with proper type handling.
+* Used by queue.ts to avoid circular dependency.
+* @internal
+*/
+function defineQueueBindingInternal(queue, exchange, options) {
+	if (exchange.type === "fanout") return defineQueueBinding(queue, exchange, options);
+	return defineQueueBinding(queue, exchange, options);
+}
+/**
+* Define a binding between two exchanges (exchange-to-exchange routing).
+*
+* This is the implementation function - use the type-specific overloads for better type safety.
+*
+* @param destination - The destination exchange definition
+* @param source - The source exchange definition
+* @param options - Optional binding configuration
+* @returns An exchange binding definition
+* @internal
+*/
+function defineExchangeBinding(destination, source, options) {
+	if (source.type === "fanout") return {
+		type: "exchange",
+		source,
+		destination,
+		...options?.arguments && { arguments: options.arguments }
+	};
+	return {
+		type: "exchange",
+		source,
+		destination,
+		routingKey: options?.routingKey ?? "",
+		...options?.arguments && { arguments: options.arguments }
+	};
+}
+
+//#endregion
+//#region src/builder/queue.ts
+/**
+* Resolve TTL-backoff retry options with defaults applied.
+* @internal
+*/
+function resolveTtlBackoffOptions(options) {
+	return {
+		mode: "ttl-backoff",
+		maxRetries: options?.maxRetries ?? 3,
+		initialDelayMs: options?.initialDelayMs ?? 1e3,
+		maxDelayMs: options?.maxDelayMs ?? 3e4,
+		backoffMultiplier: options?.backoffMultiplier ?? 2,
+		jitter: options?.jitter ?? true
+	};
+}
+/**
+* Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
+* @internal
+*/
+function isQueueWithTtlBackoffInfrastructure(entry) {
+	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
+}
+/**
+* Extract the plain QueueDefinition from a QueueEntry.
+* If the entry is a QueueWithTtlBackoffInfrastructure, returns the inner queue.
+* Otherwise, returns the entry as-is.
+*
+* @param entry - The queue entry (either plain QueueDefinition or QueueWithTtlBackoffInfrastructure)
+* @returns The plain QueueDefinition
+*
+* @example
+* ```typescript
+* const queue = defineQueue('orders', { retry: { mode: 'ttl-backoff' }, deadLetter: { exchange: dlx } });
+* const plainQueue = extractQueue(queue); // Returns the inner QueueDefinition
+* ```
+*/
+function extractQueue(entry) {
+	if (isQueueWithTtlBackoffInfrastructure(entry)) return entry.queue;
+	return entry;
+}
+/**
+* Wrap a queue definition with TTL-backoff retry infrastructure.
+* @internal
+*/
+function wrapWithTtlBackoffInfrastructure(queue) {
+	if (!queue.deadLetter) throw new Error(`Queue "${queue.name}" does not have a dead letter exchange configured. TTL-backoff retry requires deadLetter to be set on the queue.`);
+	const dlx = queue.deadLetter.exchange;
+	const waitQueueName = `${queue.name}-wait`;
+	const waitQueue = {
+		name: waitQueueName,
+		type: "quorum",
+		durable: queue.durable ?? true,
+		deadLetter: {
+			exchange: dlx,
+			routingKey: queue.name
+		},
+		retry: resolveTtlBackoffOptions(void 0)
+	};
+	return {
+		__brand: "QueueWithTtlBackoffInfrastructure",
+		queue,
+		waitQueue,
+		waitQueueBinding: defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName }),
+		mainQueueRetryBinding: defineQueueBindingInternal(queue, dlx, { routingKey: queue.name })
+	};
+}
 /**
 * Define an AMQP queue.
 *
@@ -91,22 +285,30 @@ function defineQueue(name, options) {
 	if (opts.arguments !== void 0) baseProps.arguments = opts.arguments;
 	if (type === "quorum") {
 		const quorumOpts = opts;
+		const inputRetry = quorumOpts.retry ?? { mode: "ttl-backoff" };
+		if (inputRetry.mode === "quorum-native") {
+			if (quorumOpts.deliveryLimit === void 0) throw new Error(`Queue "${name}" uses quorum-native retry mode but deliveryLimit is not configured. Quorum-native retry requires deliveryLimit to be set.`);
+		}
+		const retry$1 = inputRetry.mode === "quorum-native" ? inputRetry : resolveTtlBackoffOptions(inputRetry);
 		const queueDefinition$1 = {
 			...baseProps,
-			type: "quorum"
+			type: "quorum",
+			retry: retry$1
 		};
 		if (quorumOpts.deliveryLimit !== void 0) {
 			if (quorumOpts.deliveryLimit < 1 || !Number.isInteger(quorumOpts.deliveryLimit)) throw new Error(`Invalid deliveryLimit: ${quorumOpts.deliveryLimit}. Must be a positive integer.`);
 			queueDefinition$1.deliveryLimit = quorumOpts.deliveryLimit;
 		}
-		if (quorumOpts.retry !== void 0) queueDefinition$1.retry = quorumOpts.retry;
-		if (quorumOpts.retry?.mode === "ttl-backoff" && queueDefinition$1.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition$1);
+		if (retry$1.mode === "ttl-backoff" && queueDefinition$1.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition$1);
 		return queueDefinition$1;
 	}
 	const classicOpts = opts;
+	if (classicOpts.retry?.mode === "quorum-native") throw new Error(`Queue "${name}" uses quorum-native retry mode but is a classic queue. Quorum-native retry requires quorum queues (type: "quorum").`);
+	const retry = resolveTtlBackoffOptions(classicOpts.retry);
 	const queueDefinition = {
 		...baseProps,
-		type: "classic"
+		type: "classic",
+		retry
 	};
 	if (classicOpts.exclusive !== void 0) queueDefinition.exclusive = classicOpts.exclusive;
 	if (classicOpts.maxPriority !== void 0) {
@@ -116,129 +318,12 @@ function defineQueue(name, options) {
 			"x-max-priority": classicOpts.maxPriority
 		};
 	}
-	if (classicOpts.retry !== void 0) queueDefinition.retry = classicOpts.retry;
-	if (classicOpts.retry?.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
+	if (retry.mode === "ttl-backoff" && queueDefinition.deadLetter) return wrapWithTtlBackoffInfrastructure(queueDefinition);
 	return queueDefinition;
 }
-/**
-* Wrap a queue definition with TTL-backoff retry infrastructure.
-* @internal
-*/
-function wrapWithTtlBackoffInfrastructure(queue) {
-	if (!queue.deadLetter) throw new Error(`Queue "${queue.name}" does not have a dead letter exchange configured. TTL-backoff retry requires deadLetter to be set on the queue.`);
-	const dlx = queue.deadLetter.exchange;
-	const waitQueueName = `${queue.name}-wait`;
-	const waitQueue = {
-		name: waitQueueName,
-		type: "quorum",
-		durable: queue.durable ?? true,
-		deadLetter: {
-			exchange: dlx,
-			routingKey: queue.name
-		}
-	};
-	return {
-		__brand: "QueueWithTtlBackoffInfrastructure",
-		queue,
-		waitQueue,
-		waitQueueBinding: callDefineQueueBinding(waitQueue, dlx, { routingKey: waitQueueName }),
-		mainQueueRetryBinding: callDefineQueueBinding(queue, dlx, { routingKey: queue.name })
-	};
-}
-/**
-* Define a message definition with payload and optional headers/metadata.
-*
-* A message definition specifies the schema for message payloads and headers using
-* Standard Schema v1 compatible libraries (Zod, Valibot, ArkType, etc.).
-* The schemas are used for automatic validation when publishing or consuming messages.
-*
-* @param payload - The payload schema (must be Standard Schema v1 compatible)
-* @param options - Optional message metadata
-* @param options.headers - Optional header schema for message headers
-* @param options.summary - Brief description for documentation (used in AsyncAPI generation)
-* @param options.description - Detailed description for documentation (used in AsyncAPI generation)
-* @returns A message definition with inferred types
-*
-* @example
-* ```typescript
-* import { z } from 'zod';
-*
-* const orderMessage = defineMessage(
-*   z.object({
-*     orderId: z.string().uuid(),
-*     customerId: z.string().uuid(),
-*     amount: z.number().positive(),
-*     items: z.array(z.object({
-*       productId: z.string(),
-*       quantity: z.number().int().positive(),
-*     })),
-*   }),
-*   {
-*     summary: 'Order created event',
-*     description: 'Emitted when a new order is created in the system'
-*   }
-* );
-* ```
-*/
-function defineMessage(payload, options) {
-	return {
-		payload,
-		...options
-	};
-}
-/**
-* Define a binding between a queue and an exchange.
-*
-* This is the implementation function - use the type-specific overloads for better type safety.
-*
-* @param queue - The queue definition or queue with infrastructure to bind
-* @param exchange - The exchange definition
-* @param options - Optional binding configuration
-* @returns A queue binding definition
-* @internal
-*/
-function defineQueueBinding(queue, exchange, options) {
-	const queueDef = extractQueue(queue);
-	if (exchange.type === "fanout") return {
-		type: "queue",
-		queue: queueDef,
-		exchange,
-		...options?.arguments && { arguments: options.arguments }
-	};
-	return {
-		type: "queue",
-		queue: queueDef,
-		exchange,
-		routingKey: options?.routingKey,
-		...options?.arguments && { arguments: options.arguments }
-	};
-}
-/**
-* Define a binding between two exchanges (exchange-to-exchange routing).
-*
-* This is the implementation function - use the type-specific overloads for better type safety.
-*
-* @param destination - The destination exchange definition
-* @param source - The source exchange definition
-* @param options - Optional binding configuration
-* @returns An exchange binding definition
-* @internal
-*/
-function defineExchangeBinding(destination, source, options) {
-	if (source.type === "fanout") return {
-		type: "exchange",
-		source,
-		destination,
-		...options?.arguments && { arguments: options.arguments }
-	};
-	return {
-		type: "exchange",
-		source,
-		destination,
-		routingKey: options?.routingKey ?? "",
-		...options?.arguments && { arguments: options.arguments }
-	};
-}
+
+//#endregion
+//#region src/builder/publisher.ts
 /**
 * Define a message publisher.
 *
@@ -262,6 +347,18 @@ function definePublisher(exchange, message, options) {
 	};
 }
 /**
+* Helper to call definePublisher with proper type handling.
+* Type safety is enforced by overloaded public function signatures.
+* @internal
+*/
+function definePublisherInternal(exchange, message, options) {
+	if (exchange.type === "fanout") return definePublisher(exchange, message, options);
+	return definePublisher(exchange, message, options);
+}
+
+//#endregion
+//#region src/builder/consumer.ts
+/**
 * Define a message consumer.
 *
 * A consumer receives and processes messages from a queue. The message schema is validated
@@ -310,6 +407,9 @@ function defineConsumer(queue, message, options) {
 		...options
 	};
 }
+
+//#endregion
+//#region src/builder/contract.ts
 /**
 * Define an AMQP contract.
 *
@@ -406,58 +506,18 @@ function defineContract(definition) {
 		queues: expandedQueues
 	};
 }
-/**
-* Type guard to check if a queue entry is a QueueWithTtlBackoffInfrastructure.
-* @internal
-*/
-function isQueueWithTtlBackoffInfrastructure(entry) {
-	return typeof entry === "object" && entry !== null && "__brand" in entry && entry.__brand === "QueueWithTtlBackoffInfrastructure";
-}
-/**
-* Extract the plain QueueDefinition from a QueueEntry.
-* If the entry is a QueueWithTtlBackoffInfrastructure, returns the inner queue.
-* Otherwise, returns the entry as-is.
-*
-* @param entry - The queue entry (either plain QueueDefinition or QueueWithTtlBackoffInfrastructure)
-* @returns The plain QueueDefinition
-*
-* @example
-* ```typescript
-* const queue = defineQueue('orders', { retry: { mode: 'ttl-backoff' }, deadLetter: { exchange: dlx } });
-* const plainQueue = extractQueue(queue); // Returns the inner QueueDefinition
-* ```
-*/
-function extractQueue(entry) {
-	if (isQueueWithTtlBackoffInfrastructure(entry)) return entry.queue;
-	return entry;
-}
-/**
-* Helper to call definePublisher with proper type handling.
-* Type safety is enforced by overloaded public function signatures.
-* @internal
-*/
-function callDefinePublisher(exchange, message, options) {
-	if (exchange.type === "fanout") return definePublisher(exchange, message, options);
-	return definePublisher(exchange, message, options);
-}
-/**
-* Helper to call defineQueueBinding with proper type handling.
-* Type safety is enforced by overloaded public function signatures.
-* @internal
-*/
-function callDefineQueueBinding(queue, exchange, options) {
-	if (exchange.type === "fanout") return defineQueueBinding(queue, exchange, options);
-	return defineQueueBinding(queue, exchange, options);
-}
+
+//#endregion
+//#region src/builder/publisher-first.ts
 /**
 * Implementation of definePublisherFirst.
 * @internal
 */
 function definePublisherFirst(exchange, message, options) {
-	const publisher = callDefinePublisher(exchange, message, options);
+	const publisher = definePublisherInternal(exchange, message, options);
 	if (exchange.type === "topic") {
 		const createConsumer$1 = (queue, routingKey) => {
-			const binding = callDefineQueueBinding(queue, exchange, routingKey ? {
+			const binding = defineQueueBindingInternal(queue, exchange, routingKey ? {
 				...options,
 				routingKey
 			} : options);
@@ -472,7 +532,7 @@ function definePublisherFirst(exchange, message, options) {
 		};
 	}
 	const createConsumer = (queue) => {
-		const binding = callDefineQueueBinding(queue, exchange, options);
+		const binding = defineQueueBindingInternal(queue, exchange, options);
 		return {
 			consumer: defineConsumer(queue, message),
 			binding
@@ -483,16 +543,19 @@ function definePublisherFirst(exchange, message, options) {
 		createConsumer
 	};
 }
+
+//#endregion
+//#region src/builder/consumer-first.ts
 /**
 * Implementation of defineConsumerFirst.
 * @internal
 */
 function defineConsumerFirst(queue, exchange, message, options) {
 	const consumer = defineConsumer(queue, message);
-	const binding = callDefineQueueBinding(queue, exchange, options);
+	const binding = defineQueueBindingInternal(queue, exchange, options);
 	if (exchange.type === "topic") {
 		const createPublisher$1 = (routingKey) => {
-			return callDefinePublisher(exchange, message, {
+			return definePublisherInternal(exchange, message, {
 				...options,
 				routingKey
 			});
@@ -504,7 +567,7 @@ function defineConsumerFirst(queue, exchange, message, options) {
 		};
 	}
 	const createPublisher = () => {
-		return callDefinePublisher(exchange, message, options);
+		return definePublisherInternal(exchange, message, options);
 	};
 	return {
 		consumer,
@@ -512,6 +575,9 @@ function defineConsumerFirst(queue, exchange, message, options) {
 		createPublisher
 	};
 }
+
+//#endregion
+//#region src/builder/ttl-backoff.ts
 /**
 * Create TTL-backoff retry infrastructure for a queue.
 *
@@ -577,8 +643,8 @@ function defineTtlBackoffRetryInfrastructure(queueEntry, options) {
 	});
 	return {
 		waitQueue,
-		waitQueueBinding: callDefineQueueBinding(waitQueue, dlx, { routingKey: waitQueueName }),
-		mainQueueRetryBinding: callDefineQueueBinding(queue, dlx, { routingKey: queue.name })
+		waitQueueBinding: defineQueueBindingInternal(waitQueue, dlx, { routingKey: waitQueueName }),
+		mainQueueRetryBinding: defineQueueBindingInternal(queue, dlx, { routingKey: queue.name })
 	};
 }