@amqp-contract/worker 0.7.0 → 0.8.0

package/README.md

@@ -20,6 +20,7 @@ pnpm add @amqp-contract/worker
 
 - ✅ **Type-safe message consumption** — Handlers are fully typed based on your contract
 - ✅ **Automatic validation** — Messages are validated before reaching your handlers
+- ✅ **Automatic retry with exponential backoff** — Built-in retry mechanism using RabbitMQ TTL+DLX pattern
 - ✅ **Prefetch configuration** — Control message flow with per-consumer prefetch settings
 - ✅ **Batch processing** — Process multiple messages at once for better throughput
 - ✅ **Automatic reconnection** — Built-in connection management with failover support
@@ -67,7 +68,33 @@ const worker = await TypedAmqpWorker.create({
 
 ### Advanced Features
 
-For advanced features like prefetch configuration and batch processing, see the [Worker Usage Guide](https://btravers.github.io/amqp-contract/guide/worker-usage).
+For advanced features like prefetch configuration, batch processing, and **automatic retry with exponential backoff**, see the [Worker Usage Guide](https://btravers.github.io/amqp-contract/guide/worker-usage).
+
+#### Retry with Exponential Backoff
+
+Enable automatic retry for failed messages:
+
+```typescript
+const worker = await TypedAmqpWorker.create({
+  contract,
+  handlers: {
+    processOrder: async (message) => {
+      // If this throws, message is automatically retried with exponential backoff
+      await processPayment(message);
+    },
+  },
+  urls: ["amqp://localhost"],
+  retry: {
+    maxRetries: 3, // Retry up to 3 times
+    initialDelayMs: 1000, // Start with 1 second delay
+    maxDelayMs: 30000, // Max 30 seconds between retries
+    backoffMultiplier: 2, // Double the delay each time
+    jitter: true, // Add randomness to prevent thundering herd
+  },
+});
+```
+
+The retry mechanism uses RabbitMQ's native TTL and Dead Letter Exchange pattern, so it doesn't block the consumer during retry delays. See the [Error Handling and Retry](https://btravers.github.io/amqp-contract/guide/worker-usage#error-handling-and-retry) section in the guide for complete details.
 
 ## Defining Handlers Externally
 
@@ -86,7 +113,8 @@ handlers: {
       // Message acknowledged automatically on success
     } catch (error) {
       // Exception automatically caught by worker
-      // Message is requeued for retry
+      // With retry configured: message is retried with exponential backoff
+      // Without retry: message is immediately requeued
       throw error;
     }
   };
@@ -95,12 +123,13 @@ handlers: {
 
 **Error Types:**
 
-Worker defines error classes for internal use:
+Worker defines error classes:
 
 - `TechnicalError` - Runtime failures (parsing, processing)
 - `MessageValidationError` - Message fails schema validation
+- `RetryableError` - Optional error class for explicit retry signaling (all errors are retryable by default when retry is configured)
 
-These errors are logged but **handlers don't need to use them** - just throw standard exceptions.
+**Handlers don't need to use these error classes** - just throw standard exceptions. The worker handles retry automatically based on your configuration.
 
 ## API
 

package/dist/index.cjs

@@ -37,6 +37,34 @@ var MessageValidationError = class extends WorkerError {
 		this.name = "MessageValidationError";
 	}
 };
+/**
+* Retryable errors - transient failures that may succeed on retry
+* Examples: network timeouts, rate limiting, temporary service unavailability
+*
+* Use this error type when the operation might succeed if retried.
+* The worker will apply exponential backoff and retry the message.
+*/
+var RetryableError = class extends WorkerError {
+	constructor(message, cause) {
+		super(message);
+		this.cause = cause;
+		this.name = "RetryableError";
+	}
+};
+/**
+* Non-retryable errors - permanent failures that should not be retried
+* Examples: invalid data, business rule violations, permanent external failures
+*
+* Use this error type when retrying would not help - the message will be
+* immediately sent to the dead letter queue (DLQ) if configured.
+*/
+var NonRetryableError = class extends WorkerError {
+	constructor(message, cause) {
+		super(message);
+		this.cause = cause;
+		this.name = "NonRetryableError";
+	}
+};
 
 //#endregion
 //#region src/decompression.ts
@@ -104,23 +132,38 @@ async function decompressBuffer(buffer, contentEncoding) {
 * ```
 */
 var TypedAmqpWorker = class TypedAmqpWorker {
+	/**
+	* Internal handler type - always safe handlers (`Future<Result>`).
+	* Unsafe handlers are wrapped into safe handlers by defineUnsafeHandler/defineUnsafeHandlers.
+	*/
 	actualHandlers;
 	consumerOptions;
 	batchTimers = /* @__PURE__ */ new Map();
 	consumerTags = /* @__PURE__ */ new Set();
-	constructor(contract, amqpClient, handlers, logger) {
+	retryConfig;
+	constructor(contract, amqpClient, handlers, logger, retryOptions) {
 		this.contract = contract;
 		this.amqpClient = amqpClient;
 		this.logger = logger;
 		this.actualHandlers = {};
 		this.consumerOptions = {};
-		for (const consumerName of Object.keys(handlers)) {
-			const handlerEntry = handlers[consumerName];
+		const handlersRecord = handlers;
+		for (const consumerName of Object.keys(handlersRecord)) {
+			const handlerEntry = handlersRecord[consumerName];
+			const typedConsumerName = consumerName;
 			if (Array.isArray(handlerEntry)) {
-				this.actualHandlers[consumerName] = handlerEntry[0];
-				this.consumerOptions[consumerName] = handlerEntry[1];
-			} else this.actualHandlers[consumerName] = handlerEntry;
+				this.actualHandlers[typedConsumerName] = handlerEntry[0];
+				this.consumerOptions[typedConsumerName] = handlerEntry[1];
+			} else this.actualHandlers[typedConsumerName] = handlerEntry;
 		}
+		if (retryOptions === void 0) this.retryConfig = null;
+		else this.retryConfig = {
+			maxRetries: retryOptions.maxRetries ?? 3,
+			initialDelayMs: retryOptions.initialDelayMs ?? 1e3,
+			maxDelayMs: retryOptions.maxDelayMs ?? 3e4,
+			backoffMultiplier: retryOptions.backoffMultiplier ?? 2,
+			jitter: retryOptions.jitter ?? true
+		};
 	}
 	/**
 	* Create a type-safe AMQP worker from a contract.
@@ -138,25 +181,21 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	*
 	* @example
 	* ```typescript
-	* const workerResult = await TypedAmqpWorker.create({
+	* const worker = await TypedAmqpWorker.create({
 	*   contract: myContract,
 	*   handlers: {
 	*     processOrder: async (msg) => console.log('Order:', msg.orderId)
 	*   },
 	*   urls: ['amqp://localhost']
 	* }).resultToPromise();
-	*
-	* if (workerResult.isError()) {
-	*   console.error('Failed to create worker:', workerResult.error);
-	* }
 	* ```
 	*/
-	static create({ contract, handlers, urls, connectionOptions, logger }) {
+	static create({ contract, handlers, urls, connectionOptions, logger, retry }) {
 		const worker = new TypedAmqpWorker(contract, new _amqp_contract_core.AmqpClient(contract, {
 			urls,
 			connectionOptions
-		}), handlers, logger);
-		return worker.waitForConnectionReady().flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
+		}), handlers, logger, retry);
+		return worker.waitForConnectionReady().flatMapOk(() => worker.setupWaitQueues()).flatMapOk(() => worker.consumeAll()).mapOk(() => worker);
 	}
 	/**
 	* Close the AMQP channel and connection.
@@ -188,6 +227,42 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		}).flatMapOk(() => _swan_io_boxed.Future.fromPromise(this.amqpClient.close())).mapError((error) => new TechnicalError("Failed to close AMQP connection", error)).mapOk(() => void 0);
 	}
 	/**
+	* Set up wait queues for retry mechanism.
+	* Creates and binds wait queues for each consumer queue that has DLX configuration.
+	*/
+	setupWaitQueues() {
+		if (this.retryConfig === null) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		if (!this.contract.consumers || !this.contract.queues) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		const setupTasks = [];
+		for (const consumerName of Object.keys(this.contract.consumers)) {
+			const consumer = this.contract.consumers[consumerName];
+			if (!consumer) continue;
+			const queue = consumer.queue;
+			const deadLetter = queue.deadLetter;
+			if (!deadLetter) continue;
+			const queueName = queue.name;
+			const waitQueueName = `${queueName}-wait`;
+			const dlxName = deadLetter.exchange.name;
+			const setupTask = _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.addSetup(async (channel) => {
+				await channel.assertQueue(waitQueueName, {
+					durable: queue.durable ?? false,
+					deadLetterExchange: dlxName,
+					deadLetterRoutingKey: queueName
+				});
+				await channel.bindQueue(waitQueueName, dlxName, `${queueName}-wait`);
+				this.logger?.info("Wait queue created and bound", {
+					consumerName: String(consumerName),
+					queueName,
+					waitQueueName,
+					dlxName
+				});
+			})).mapError((error) => new TechnicalError(`Failed to setup wait queue for "${String(consumerName)}"`, error));
+			setupTasks.push(setupTask);
+		}
+		if (setupTasks.length === 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		return _swan_io_boxed.Future.all(setupTasks).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
+	}
+	/**
 	* Start consuming messages for all consumers
 	*/
 	consumeAll() {
@@ -239,10 +314,10 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	}
 	/**
 	* Parse and validate a message from AMQP
-	* @returns Future<Result<validated message, void>> - Ok with validated message, or Error (already handled with nack)
+	* @returns `Future<Result<validated message, void>>` - Ok with validated message, or Error (already handled with nack)
 	*/
 	parseAndValidateMessage(msg, consumer, consumerName) {
-		const decompressMessage = _swan_io_boxed.Future.fromPromise(decompressBuffer(msg.content, msg.properties.contentEncoding)).mapError((error) => {
+		const decompressMessage = _swan_io_boxed.Future.fromPromise(decompressBuffer(msg.content, msg.properties.contentEncoding)).tapError((error) => {
 			this.logger?.error("Error decompressing message", {
 				consumerName: String(consumerName),
 				queueName: consumer.queue.name,
@@ -294,25 +369,33 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				});
 				return;
 			}
-			await this.parseAndValidateMessage(msg, consumer, consumerName).flatMapOk((validatedMessage) => _swan_io_boxed.Future.fromPromise(handler(validatedMessage)).tapError((error) => {
-				this.logger?.error("Error processing message", {
-					consumerName: String(consumerName),
-					queueName: consumer.queue.name,
-					error
-				});
-				this.amqpClient.channel.nack(msg, false, true);
-			})).tapOk(() => {
+			await this.parseAndValidateMessage(msg, consumer, consumerName).flatMapOk((validatedMessage) => handler(validatedMessage).flatMapOk(() => {
 				this.logger?.info("Message consumed successfully", {
 					consumerName: String(consumerName),
 					queueName: consumer.queue.name
 				});
 				this.amqpClient.channel.ack(msg);
-			}).toPromise();
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+			}).flatMapError((handlerError) => {
+				this.logger?.error("Error processing message", {
+					consumerName: String(consumerName),
+					queueName: consumer.queue.name,
+					errorType: handlerError.name,
+					error: handlerError.message
+				});
+				return this.handleError(handlerError, msg, String(consumerName), consumer);
+			})).toPromise();
 		})).tapOk((reply) => {
 			this.consumerTags.add(reply.consumerTag);
 		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
 	}
 	/**
+	* Handle batch processing error by applying error handling to all messages.
+	*/
+	handleBatchError(error, currentBatch, consumerName, consumer) {
+		return _swan_io_boxed.Future.all(currentBatch.map((item) => this.handleError(error, item.amqpMessage, consumerName, consumer))).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
+	}
+	/**
 	* Consume messages in batches
 	*/
 	consumeBatch(consumerName, consumer, options, handler) {
@@ -321,8 +404,8 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 		const timerKey = String(consumerName);
 		let batch = [];
 		let isProcessing = false;
-		const processBatch = async () => {
-			if (isProcessing || batch.length === 0) return;
+		const processBatch = () => {
+			if (isProcessing || batch.length === 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
 			isProcessing = true;
 			const currentBatch = batch;
 			batch = [];
@@ -337,37 +420,33 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				queueName: consumer.queue.name,
 				batchSize: currentBatch.length
 			});
-			try {
-				await handler(messages);
+			return handler(messages).flatMapOk(() => {
 				for (const item of currentBatch) this.amqpClient.channel.ack(item.amqpMessage);
 				this.logger?.info("Batch processed successfully", {
 					consumerName: String(consumerName),
 					queueName: consumer.queue.name,
 					batchSize: currentBatch.length
 				});
-			} catch (error) {
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+			}).flatMapError((handlerError) => {
 				this.logger?.error("Error processing batch", {
 					consumerName: String(consumerName),
 					queueName: consumer.queue.name,
 					batchSize: currentBatch.length,
-					error
+					errorType: handlerError.name,
+					error: handlerError.message
 				});
-				for (const item of currentBatch) this.amqpClient.channel.nack(item.amqpMessage, false, true);
-			} finally {
+				return this.handleBatchError(handlerError, currentBatch, String(consumerName), consumer);
+			}).tap(() => {
 				isProcessing = false;
-			}
+			});
 		};
 		const scheduleBatchProcessing = () => {
 			if (isProcessing) return;
 			const existingTimer = this.batchTimers.get(timerKey);
 			if (existingTimer) clearTimeout(existingTimer);
 			const timer = setTimeout(() => {
-				processBatch().catch((error) => {
-					this.logger?.error("Unexpected error in batch processing", {
-						consumerName: String(consumerName),
-						error
-					});
-				});
+				processBatch().toPromise();
 			}, batchTimeout);
 			this.batchTimers.set(timerKey, timer);
 		};
@@ -377,7 +456,7 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 					consumerName: String(consumerName),
 					queueName: consumer.queue.name
 				});
-				await processBatch();
+				await processBatch().toPromise();
 				return;
 			}
 			const validationResult = await this.parseAndValidateMessage(msg, consumer, consumerName).toPromise();
@@ -387,94 +466,292 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				amqpMessage: msg
 			});
 			if (batch.length >= batchSize) {
-				await processBatch();
+				await processBatch().toPromise();
 				if (batch.length > 0 && !this.batchTimers.has(timerKey)) scheduleBatchProcessing();
 			} else if (!this.batchTimers.has(timerKey)) scheduleBatchProcessing();
 		})).tapOk((reply) => {
 			this.consumerTags.add(reply.consumerTag);
 		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
 	}
+	/**
+	* Handle error in message processing with retry logic.
+	*
+	* Flow:
+	* 1. If NonRetryableError -> send directly to DLQ (no retry)
+	* 2. If no retry config -> legacy behavior (immediate requeue)
+	* 3. If max retries exceeded -> send to DLQ
+	* 4. Otherwise -> publish to wait queue with TTL for retry
+	*/
+	handleError(error, msg, consumerName, consumer) {
+		if (error instanceof NonRetryableError) {
+			this.logger?.error("Non-retryable error, sending to DLQ immediately", {
+				consumerName,
+				errorType: error.name,
+				error: error.message
+			});
+			this.sendToDLQ(msg, consumer);
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		}
+		if (this.retryConfig === null) {
+			this.logger?.warn("Error in handler (legacy mode: immediate requeue)", {
+				consumerName,
+				error: error.message
+			});
+			this.amqpClient.channel.nack(msg, false, true);
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		}
+		const retryCount = msg.properties.headers?.["x-retry-count"] ?? 0;
+		const config = this.retryConfig;
+		if (retryCount >= config.maxRetries) {
+			this.logger?.error("Max retries exceeded, sending to DLQ", {
+				consumerName,
+				retryCount,
+				maxRetries: config.maxRetries,
+				error: error.message
+			});
+			this.sendToDLQ(msg, consumer);
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		}
+		const delayMs = this.calculateRetryDelay(retryCount);
+		this.logger?.warn("Retrying message", {
+			consumerName,
+			retryCount: retryCount + 1,
+			delayMs,
+			error: error.message
+		});
+		return this.publishForRetry(msg, consumer, retryCount + 1, delayMs, error);
+	}
+	/**
+	* Calculate retry delay with exponential backoff and optional jitter.
+	*/
+	calculateRetryDelay(retryCount) {
+		const { initialDelayMs, maxDelayMs, backoffMultiplier, jitter } = this.retryConfig;
+		let delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, retryCount), maxDelayMs);
+		if (jitter) delay = delay * (.5 + Math.random() * .5);
+		return Math.floor(delay);
+	}
+	/**
+	* Parse message content for republishing.
+	* Prevents double JSON serialization by converting Buffer to object when possible.
+	*/
+	parseMessageContentForRetry(msg, queueName) {
+		let content = msg.content;
+		if (!msg.properties.contentEncoding) try {
+			content = JSON.parse(msg.content.toString());
+		} catch (err) {
+			this.logger?.warn("Failed to parse message for retry, using original buffer", {
+				queueName,
+				error: err
+			});
+		}
+		return content;
+	}
+	/**
+	* Publish message to wait queue for retry after TTL expires.
+	*
+	* ┌─────────────────────────────────────────────────────────────────┐
+	* │ Retry Flow (Native RabbitMQ TTL + DLX Pattern)                   │
+	* ├─────────────────────────────────────────────────────────────────┤
+	* │                                                                   │
+	* │ 1. Handler throws any Error                                      │
+	* │    ↓                                                              │
+	* │ 2. Worker publishes to DLX with routing key: {queue}-wait        │
+	* │    ↓                                                              │
+	* │ 3. DLX routes to wait queue: {queue}-wait                        │
+	* │    (with expiration: calculated backoff delay)                   │
+	* │    ↓                                                              │
+	* │ 4. Message waits in queue until TTL expires                      │
+	* │    ↓                                                              │
+	* │ 5. Expired message dead-lettered to DLX                          │
+	* │    (with routing key: {queue})                                   │
+	* │    ↓                                                              │
+	* │ 6. DLX routes back to main queue → RETRY                         │
+	* │    ↓                                                              │
+	* │ 7. If retries exhausted: nack without requeue → DLQ              │
+	* │                                                                   │
+	* └─────────────────────────────────────────────────────────────────┘
+	*/
+	publishForRetry(msg, consumer, newRetryCount, delayMs, error) {
+		const queueName = consumer.queue.name;
+		const deadLetter = consumer.queue.deadLetter;
+		if (!deadLetter) {
+			this.logger?.warn("Cannot retry: queue does not have DLX configured, falling back to nack with requeue", { queueName });
+			this.amqpClient.channel.nack(msg, false, true);
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		}
+		const dlxName = deadLetter.exchange.name;
+		const waitRoutingKey = `${queueName}-wait`;
+		this.amqpClient.channel.ack(msg);
+		const content = this.parseMessageContentForRetry(msg, queueName);
+		return _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.publish(dlxName, waitRoutingKey, content, {
+			...msg.properties,
+			expiration: delayMs.toString(),
+			headers: {
+				...msg.properties.headers,
+				"x-retry-count": newRetryCount,
+				"x-last-error": error.message,
+				"x-first-failure-timestamp": msg.properties.headers?.["x-first-failure-timestamp"] ?? Date.now()
+			}
+		})).mapError((error$1) => new TechnicalError("Failed to publish message for retry", error$1)).mapOkToResult((published) => {
+			if (!published) {
+				this.logger?.error("Failed to publish message for retry (write buffer full)", {
+					queueName,
+					waitRoutingKey,
+					retryCount: newRetryCount
+				});
+				return _swan_io_boxed.Result.Error(new TechnicalError("Failed to publish message for retry (write buffer full)"));
+			}
+			this.logger?.info("Message published for retry", {
+				queueName,
+				waitRoutingKey,
+				retryCount: newRetryCount,
+				delayMs
+			});
+			return _swan_io_boxed.Result.Ok(void 0);
+		});
+	}
+	/**
+	* Send message to dead letter queue.
+	* Nacks the message without requeue, relying on DLX configuration.
+	*/
+	sendToDLQ(msg, consumer) {
+		const queueName = consumer.queue.name;
+		if (!(consumer.queue.deadLetter !== void 0)) this.logger?.warn("Queue does not have DLX configured - message will be lost on nack", { queueName });
+		this.logger?.info("Sending message to DLQ", {
+			queueName,
+			deliveryTag: msg.fields.deliveryTag
+		});
+		this.amqpClient.channel.nack(msg, false, false);
+	}
 };
 
 //#endregion
 //#region src/handlers.ts
-function defineHandler(contract, consumerName, handler, options) {
+/**
+* Validate that a consumer exists in the contract
+*/
+function validateConsumerExists(contract, consumerName) {
 	const consumers = contract.consumers;
 	if (!consumers || !(consumerName in consumers)) {
 		const availableConsumers = consumers ? Object.keys(consumers) : [];
 		const available = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
-		throw new Error(`Consumer "${String(consumerName)}" not found in contract. Available consumers: ${available}`);
+		throw new Error(`Consumer "${consumerName}" not found in contract. Available consumers: ${available}`);
 	}
+}
+/**
+* Validate that all handlers reference valid consumers
+*/
+function validateHandlers(contract, handlers) {
+	const consumers = contract.consumers;
+	const availableConsumers = Object.keys(consumers ?? {});
+	const availableConsumerNames = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
+	for (const handlerName of Object.keys(handlers)) if (!consumers || !(handlerName in consumers)) throw new Error(`Consumer "${handlerName}" not found in contract. Available consumers: ${availableConsumerNames}`);
+}
+/**
+* Wrap a Promise-based handler into a Future-based safe handler.
+* This is used internally by defineUnsafeHandler to convert Promise handlers to Future handlers.
+*/
+function wrapUnsafeHandler(handler) {
+	return (input) => {
+		return _swan_io_boxed.Future.fromPromise(handler(input)).mapOkToResult(() => _swan_io_boxed.Result.Ok(void 0)).flatMapError((error) => {
+			if (error instanceof NonRetryableError || error instanceof RetryableError) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(error));
+			const retryableError = new RetryableError(error instanceof Error ? error.message : String(error), error);
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(retryableError));
+		});
+	};
+}
+function defineHandler(contract, consumerName, handler, options) {
+	validateConsumerExists(contract, String(consumerName));
 	if (options) return [handler, options];
 	return handler;
 }
 /**
 * Define multiple type-safe handlers for consumers in a contract.
 *
-* This utility allows you to define all handlers at once outside of the worker creation,
-* ensuring type safety and providing better code organization.
+* **Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
+* providing explicit error handling and better control over retry behavior.
 *
 * @template TContract - The contract definition type
 * @param contract - The contract definition containing the consumers
-* @param handlers - An object with async handler functions for each consumer
+* @param handlers - An object with handler functions for each consumer
 * @returns A type-safe handlers object that can be used with TypedAmqpWorker
 *
 * @example
 * ```typescript
-* import { defineHandlers } from '@amqp-contract/worker';
+* import { defineHandlers, RetryableError } from '@amqp-contract/worker';
+* import { Future } from '@swan-io/boxed';
 * import { orderContract } from './contract';
 *
-* // Define all handlers at once
 * const handlers = defineHandlers(orderContract, {
-*   processOrder: async (message) => {
-*     // message is fully typed based on the contract
-*     console.log('Processing order:', message.orderId);
-*     await processPayment(message);
-*   },
-*   notifyOrder: async (message) => {
-*     await sendNotification(message);
-*   },
-*   shipOrder: async (message) => {
-*     await prepareShipment(message);
-*   },
-* });
-*
-* // Use the handlers in worker
-* const worker = await TypedAmqpWorker.create({
-*   contract: orderContract,
-*   handlers,
-*   connection: 'amqp://localhost',
+*   processOrder: (message) =>
+*     Future.fromPromise(processPayment(message))
+*       .mapOk(() => undefined)
+*       .mapError((error) => new RetryableError('Payment failed', error)),
+*   notifyOrder: (message) =>
+*     Future.fromPromise(sendNotification(message))
+*       .mapOk(() => undefined)
+*       .mapError((error) => new RetryableError('Notification failed', error)),
 * });
 * ```
+*/
+function defineHandlers(contract, handlers) {
+	validateHandlers(contract, handlers);
+	return handlers;
+}
+function defineUnsafeHandler(contract, consumerName, handler, options) {
+	validateConsumerExists(contract, String(consumerName));
+	const wrappedHandler = wrapUnsafeHandler(handler);
+	if (options) return [wrappedHandler, options];
+	return wrappedHandler;
+}
+/**
+* Define multiple unsafe handlers for consumers in a contract.
+*
+* @deprecated Use `defineHandlers` instead for explicit error handling with `Future<Result>`.
+*
+* **Warning:** Unsafe handlers use exception-based error handling.
+* Consider migrating to safe handlers for better error control.
+*
+* **Note:** Internally, this function wraps all Promise-based handlers into Future-based
+* safe handlers for consistent processing in the worker.
+*
+* @template TContract - The contract definition type
+* @param contract - The contract definition containing the consumers
+* @param handlers - An object with async handler functions for each consumer
+* @returns A type-safe handlers object that can be used with TypedAmqpWorker
 *
 * @example
 * ```typescript
-* // Separate handler definitions for better organization
-* async function handleProcessOrder(message: WorkerInferConsumerInput<typeof orderContract, 'processOrder'>) {
-*   await processOrder(message);
-* }
+* import { defineUnsafeHandlers } from '@amqp-contract/worker';
 *
-* async function handleNotifyOrder(message: WorkerInferConsumerInput<typeof orderContract, 'notifyOrder'>) {
-*   await sendNotification(message);
-* }
-*
-* const handlers = defineHandlers(orderContract, {
-*   processOrder: handleProcessOrder,
-*   notifyOrder: handleNotifyOrder,
+* // ⚠️ Consider using defineHandlers for better error handling
+* const handlers = defineUnsafeHandlers(orderContract, {
+*   processOrder: async (message) => {
+*     await processPayment(message);
+*   },
+*   notifyOrder: async (message) => {
+*     await sendNotification(message);
+*   },
 * });
 * ```
 */
-function defineHandlers(contract, handlers) {
-	const consumers = contract.consumers;
-	const availableConsumers = Object.keys(consumers ?? {});
-	const availableConsumerNames = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
-	for (const handlerName of Object.keys(handlers)) if (!consumers || !(handlerName in consumers)) throw new Error(`Consumer "${handlerName}" not found in contract. Available consumers: ${availableConsumerNames}`);
-	return handlers;
+function defineUnsafeHandlers(contract, handlers) {
+	validateHandlers(contract, handlers);
+	const result = {};
+	for (const [name, entry] of Object.entries(handlers)) if (Array.isArray(entry)) {
+		const [handler, options] = entry;
+		result[name] = [wrapUnsafeHandler(handler), options];
+	} else result[name] = wrapUnsafeHandler(entry);
+	return result;
 }
 
 //#endregion
 exports.MessageValidationError = MessageValidationError;
+exports.NonRetryableError = NonRetryableError;
+exports.RetryableError = RetryableError;
 exports.TechnicalError = TechnicalError;
 exports.TypedAmqpWorker = TypedAmqpWorker;
 exports.defineHandler = defineHandler;
-exports.defineHandlers = defineHandlers;
+exports.defineHandlers = defineHandlers;
+exports.defineUnsafeHandler = defineUnsafeHandler;
+exports.defineUnsafeHandlers = defineUnsafeHandlers;