@amqp-contract/worker 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -27,6 +27,33 @@ declare class MessageValidationError extends WorkerError {
   readonly issues: unknown;
   constructor(consumerName: string, issues: unknown);
 }
+/**
+ * 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.
+ */
+declare class RetryableError extends WorkerError {
+  readonly cause?: unknown | undefined;
+  constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * 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.
+ */
+declare class NonRetryableError extends WorkerError {
+  readonly cause?: unknown | undefined;
+  constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Union type representing all handler errors.
+ * Use this type when defining handlers that explicitly signal error outcomes.
+ */
+type HandlerError = RetryableError | NonRetryableError;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -50,40 +77,129 @@ type InferConsumer<TContract extends ContractDefinition, TName extends InferCons
  */
 type WorkerInferConsumerInput<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = ConsumerInferInput<InferConsumer<TContract, TName>>;
 /**
- * Infer consumer handler type for a specific consumer.
- * Handlers always receive a single message by default.
- * For batch processing, use consumerOptions to configure batch behavior.
+ * Safe consumer handler type for a specific consumer.
+ * Returns a `Future<Result<void, HandlerError>>` for explicit error handling.
+ *
+ * **Recommended over unsafe handlers** for better error control:
+ * - RetryableError: Message will be retried with exponential backoff
+ * - NonRetryableError: Message will be immediately sent to DLQ
+ *
+ * @example
+ * ```typescript
+ * const handler: WorkerInferSafeConsumerHandler<typeof contract, 'processOrder'> =
+ *   (message) => Future.value(Result.Ok(undefined));
+ * ```
  */
-type WorkerInferConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Promise<void>;
+type WorkerInferSafeConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Future<Result<void, HandlerError>>;
 /**
- * Infer consumer handler type for batch processing.
- * Batch handlers receive an array of messages.
+ * Safe consumer handler type for batch processing.
+ * Returns a `Future<Result<void, HandlerError>>` for explicit error handling.
+ *
+ * @example
+ * ```typescript
+ * const handler: WorkerInferSafeConsumerBatchHandler<typeof contract, 'processOrders'> =
+ *   (messages) => Future.value(Result.Ok(undefined));
+ * ```
  */
-type WorkerInferConsumerBatchHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (messages: Array<WorkerInferConsumerInput<TContract, TName>>) => Promise<void>;
+type WorkerInferSafeConsumerBatchHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (messages: Array<WorkerInferConsumerInput<TContract, TName>>) => Future<Result<void, HandlerError>>;
 /**
- * Infer handler entry for a consumer - either a function or a tuple of [handler, options].
+ * Safe handler entry for a consumer - either a function or a tuple of [handler, options].
  *
  * Three patterns are supported:
- * 1. Simple handler: `async (message) => { ... }`
- * 2. Handler with prefetch: `[async (message) => { ... }, { prefetch: 10 }]`
- * 3. Batch handler: `[async (messages) => { ... }, { batchSize: 5, batchTimeout: 1000 }]`
+ * 1. Simple handler: `(message) => Future.value(Result.Ok(undefined))`
+ * 2. Handler with prefetch: `[(message) => ..., { prefetch: 10 }]`
+ * 3. Batch handler: `[(messages) => ..., { batchSize: 5, batchTimeout: 1000 }]`
  */
-type WorkerInferConsumerHandlerEntry<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferConsumerHandler<TContract, TName> | readonly [WorkerInferConsumerHandler<TContract, TName>, {
+type WorkerInferSafeConsumerHandlerEntry<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferSafeConsumerHandler<TContract, TName> | readonly [WorkerInferSafeConsumerHandler<TContract, TName>, {
   prefetch?: number;
   batchSize?: never;
   batchTimeout?: never;
-}] | readonly [WorkerInferConsumerBatchHandler<TContract, TName>, {
+}] | readonly [WorkerInferSafeConsumerBatchHandler<TContract, TName>, {
   prefetch?: number;
   batchSize: number;
   batchTimeout?: number;
 }];
 /**
- * Infer all consumer handlers for a contract.
- * Handlers can be either single-message handlers, batch handlers, or a tuple of [handler, options].
+ * Safe consumer handlers for a contract.
+ * All handlers return `Future<Result<void, HandlerError>>` for explicit error control.
+ */
+type WorkerInferSafeConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferSafeConsumerHandlerEntry<TContract, K> };
+/**
+ * Unsafe consumer handler type for a specific consumer.
+ * Returns a `Promise<void>` - throws exceptions on error.
+ *
+ * @deprecated Prefer using safe handlers (WorkerInferSafeConsumerHandler) that return
+ * `Future<Result<void, HandlerError>>` for better error handling.
+ *
+ * **Note:** When using unsafe handlers:
+ * - All thrown errors are treated as retryable by default (when retry is configured)
+ * - Use RetryableError or NonRetryableError to control retry behavior explicitly
+ */
+type WorkerInferUnsafeConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Promise<void>;
+/**
+ * Unsafe consumer handler type for batch processing.
+ * Returns a `Promise<void>` - throws exceptions on error.
+ *
+ * @deprecated Prefer using safe handlers (WorkerInferSafeConsumerBatchHandler) that return
+ * `Future<Result<void, HandlerError>>` for better error handling.
+ */
+type WorkerInferUnsafeConsumerBatchHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (messages: Array<WorkerInferConsumerInput<TContract, TName>>) => Promise<void>;
+/**
+ * Unsafe handler entry for a consumer - either a function or a tuple of [handler, options].
+ *
+ * @deprecated Prefer using safe handler entries (WorkerInferSafeConsumerHandlerEntry).
  */
-type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandlerEntry<TContract, K> };
+type WorkerInferUnsafeConsumerHandlerEntry<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferUnsafeConsumerHandler<TContract, TName> | readonly [WorkerInferUnsafeConsumerHandler<TContract, TName>, {
+  prefetch?: number;
+  batchSize?: never;
+  batchTimeout?: never;
+}] | readonly [WorkerInferUnsafeConsumerBatchHandler<TContract, TName>, {
+  prefetch?: number;
+  batchSize: number;
+  batchTimeout?: number;
+}];
+/**
+ * Unsafe consumer handlers for a contract.
+ *
+ * @deprecated Prefer using safe handlers (WorkerInferSafeConsumerHandlers).
+ */
+type WorkerInferUnsafeConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferUnsafeConsumerHandlerEntry<TContract, K> };
+/**
+ * @deprecated Use WorkerInferUnsafeConsumerHandler instead
+ */
+type WorkerInferConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferUnsafeConsumerHandler<TContract, TName>;
+/**
+ * @deprecated Use WorkerInferUnsafeConsumerBatchHandler instead
+ */
+type WorkerInferConsumerBatchHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferUnsafeConsumerBatchHandler<TContract, TName>;
+/**
+ * @deprecated Use WorkerInferUnsafeConsumerHandlerEntry instead
+ */
+type WorkerInferConsumerHandlerEntry<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferUnsafeConsumerHandlerEntry<TContract, TName>;
+/**
+ * @deprecated Use WorkerInferUnsafeConsumerHandlers instead
+ */
+type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = WorkerInferUnsafeConsumerHandlers<TContract>;
 //#endregion
 //#region src/worker.d.ts
+/**
+ * Retry configuration options for handling failed message processing.
+ *
+ * When enabled, the worker will automatically retry failed messages using
+ * RabbitMQ's native TTL + Dead Letter Exchange (DLX) pattern.
+ */
+type RetryOptions = {
+  /** Maximum retry attempts before sending to DLQ (default: 3) */
+  maxRetries?: number;
+  /** Initial delay in ms before first retry (default: 1000) */
+  initialDelayMs?: number;
+  /** Maximum delay in ms between retries (default: 30000) */
+  maxDelayMs?: number;
+  /** Exponential backoff multiplier (default: 2) */
+  backoffMultiplier?: number;
+  /** Add jitter to prevent thundering herd (default: true) */
+  jitter?: boolean;
+};
 /**
  * Options for creating a type-safe AMQP worker.
  *
@@ -117,21 +233,35 @@ type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in
  *   connectionOptions: {
  *     heartbeatIntervalInSeconds: 30
  *   },
- *   logger: myLogger
+ *   logger: myLogger,
+ *   retry: {
+ *     maxRetries: 3,
+ *     initialDelayMs: 1000,
+ *     maxDelayMs: 30000,
+ *     backoffMultiplier: 2,
+ *     jitter: true
+ *   }
  * };
  * ```
  */
 type CreateWorkerOptions<TContract extends ContractDefinition> = {
   /** The AMQP contract definition specifying consumers and their message schemas */
   contract: TContract;
-  /** Handlers for each consumer defined in the contract. Can be a function or a tuple of [handler, options] */
-  handlers: WorkerInferConsumerHandlers<TContract>;
+  /**
+   * Handlers for each consumer defined in the contract.
+   * Handlers must return `Future<Result<void, HandlerError>>` for explicit error handling.
+   * Use defineHandler() to create safe handlers, or defineUnsafeHandler() which wraps
+   * Promise-based handlers into safe handlers internally.
+   */
+  handlers: WorkerInferSafeConsumerHandlers<TContract>;
   /** AMQP broker URL(s). Multiple URLs provide failover support */
   urls: ConnectionUrl[];
   /** Optional connection configuration (heartbeat, reconnect settings, etc.) */
   connectionOptions?: AmqpConnectionManagerOptions | undefined;
   /** Optional logger for logging message consumption and errors */
   logger?: Logger | undefined;
+  /** Retry configuration - when undefined, uses legacy behavior (immediate requeue) */
+  retry?: RetryOptions | undefined;
 };
 /**
  * Type-safe AMQP worker for consuming messages from RabbitMQ.
@@ -177,10 +307,15 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
   private readonly contract;
   private readonly amqpClient;
   private readonly logger?;
+  /**
+   * Internal handler type - always safe handlers (`Future<Result>`).
+   * Unsafe handlers are wrapped into safe handlers by defineUnsafeHandler/defineUnsafeHandlers.
+   */
   private readonly actualHandlers;
   private readonly consumerOptions;
   private readonly batchTimers;
   private readonly consumerTags;
+  private readonly retryConfig;
   private constructor();
   /**
    * Create a type-safe AMQP worker from a contract.
@@ -198,17 +333,13 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
    *
    * @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<TContract extends ContractDefinition>({
@@ -216,7 +347,8 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
     handlers,
     urls,
     connectionOptions,
-    logger
+    logger,
+    retry
   }: CreateWorkerOptions<TContract>): Future<Result<TypedAmqpWorker<TContract>, TechnicalError>>;
   /**
    * Close the AMQP channel and connection.
@@ -235,6 +367,11 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
    * ```
    */
   close(): Future<Result<void, TechnicalError>>;
+  /**
+   * Set up wait queues for retry mechanism.
+   * Creates and binds wait queues for each consumer queue that has DLX configuration.
+   */
+  private setupWaitQueues;
   /**
    * Start consuming messages for all consumers
    */
@@ -246,149 +383,267 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
   private consume;
   /**
    * 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)
    */
   private parseAndValidateMessage;
   /**
    * Consume messages one at a time
    */
   private consumeSingle;
+  /**
+   * Handle batch processing error by applying error handling to all messages.
+   */
+  private handleBatchError;
   /**
    * Consume messages in batches
    */
   private consumeBatch;
+  /**
+   * 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
+   */
+  private handleError;
+  /**
+   * Calculate retry delay with exponential backoff and optional jitter.
+   */
+  private calculateRetryDelay;
+  /**
+   * Parse message content for republishing.
+   * Prevents double JSON serialization by converting Buffer to object when possible.
+   */
+  private parseMessageContentForRetry;
+  /**
+   * 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              │
+   * │                                                                   │
+   * └─────────────────────────────────────────────────────────────────┘
+   */
+  private publishForRetry;
+  /**
+   * Send message to dead letter queue.
+   * Nacks the message without requeue, relying on DLX configuration.
+   */
+  private sendToDLQ;
 }
 //#endregion
 //#region src/handlers.d.ts
 /**
  * Define a type-safe handler for a specific consumer in a contract.
  *
- * This utility allows you to define handlers outside of the worker creation,
- * providing better code organization and reusability.
+ * **Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
+ * providing explicit error handling and better control over retry behavior.
  *
  * Supports three patterns:
  * 1. Simple handler: just the function (single message handler)
  * 2. Handler with prefetch: [handler, { prefetch: 10 }] (single message handler with config)
  * 3. Batch handler: [batchHandler, { batchSize: 5, batchTimeout: 1000 }] (REQUIRES batchSize config)
  *
- * **Important**: Batch handlers (handlers that accept an array of messages) MUST include
- * batchSize configuration. You cannot create a batch handler without specifying batchSize.
- *
  * @template TContract - The contract definition type
  * @template TName - The consumer name from the contract
  * @param contract - The contract definition containing the consumer
  * @param consumerName - The name of the consumer from the contract
- * @param handler - The async handler function that processes messages (single or batch)
+ * @param handler - The handler function that returns `Future<Result<void, HandlerError>>`
  * @param options - Optional consumer options (prefetch, batchSize, batchTimeout)
- *   - For single-message handlers: { prefetch?: number } is optional
- *   - For batch handlers: { batchSize: number, batchTimeout?: number } is REQUIRED
  * @returns A type-safe handler that can be used with TypedAmqpWorker
  *
  * @example
  * ```typescript
- * import { defineHandler } from '@amqp-contract/worker';
+ * import { defineHandler, RetryableError, NonRetryableError } from '@amqp-contract/worker';
+ * import { Future, Result } from '@swan-io/boxed';
  * import { orderContract } from './contract';
  *
- * // Simple single-message handler without options
+ * // Simple handler with explicit error handling using mapError
  * const processOrderHandler = defineHandler(
  *   orderContract,
  *   'processOrder',
- *   async (message) => {
- *     console.log('Processing order:', message.orderId);
- *     await processPayment(message);
- *   }
- * );
- *
- * // Single-message handler with prefetch
- * const processOrderWithPrefetch = defineHandler(
- *   orderContract,
- *   'processOrder',
- *   async (message) => {
- *     await processOrder(message);
- *   },
- *   { prefetch: 10 }
+ *   (message) =>
+ *     Future.fromPromise(processPayment(message))
+ *       .mapOk(() => undefined)
+ *       .mapError((error) => new RetryableError('Payment failed', error))
  * );
  *
- * // Batch handler - MUST include batchSize
- * const processBatchOrders = defineHandler(
+ * // Handler with validation (non-retryable error)
+ * const validateOrderHandler = defineHandler(
  *   orderContract,
- *   'processOrders',
- *   async (messages) => {
- *     // messages is an array - batchSize configuration is REQUIRED
- *     await db.insertMany(messages);
- *   },
- *   { batchSize: 5, batchTimeout: 1000 }
+ *   'validateOrder',
+ *   (message) => {
+ *     if (message.amount < 1) {
+ *       // Won't be retried - goes directly to DLQ
+ *       return Future.value(Result.Error(new NonRetryableError('Invalid order amount')));
+ *     }
+ *     return Future.value(Result.Ok(undefined));
+ *   }
  * );
  * ```
  */
-declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferConsumerHandler<TContract, TName>): WorkerInferConsumerHandlerEntry<TContract, TName>;
-declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferConsumerHandler<TContract, TName>, options: {
+declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferSafeConsumerHandler<TContract, TName>): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferSafeConsumerHandler<TContract, TName>, options: {
   prefetch?: number;
   batchSize?: never;
   batchTimeout?: never;
-}): WorkerInferConsumerHandlerEntry<TContract, TName>;
-declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferConsumerBatchHandler<TContract, TName>, options: {
+}): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferSafeConsumerBatchHandler<TContract, TName>, options: {
   prefetch?: number;
   batchSize: number;
   batchTimeout?: number;
-}): WorkerInferConsumerHandlerEntry<TContract, TName>;
+}): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
 /**
  * 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)),
  * });
  * ```
+ */
+declare function defineHandlers<TContract extends ContractDefinition>(contract: TContract, handlers: WorkerInferSafeConsumerHandlers<TContract>): WorkerInferSafeConsumerHandlers<TContract>;
+/**
+ * Unsafe handler type for single messages (internal use).
+ */
+type UnsafeHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Promise<void>;
+/**
+ * Unsafe handler type for batch messages (internal use).
+ */
+type UnsafeBatchHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (messages: Array<WorkerInferConsumerInput<TContract, TName>>) => Promise<void>;
+/**
+ * Define an unsafe handler for a specific consumer in a contract.
+ *
+ * @deprecated Use `defineHandler` instead for explicit error handling with `Future<Result>`.
+ *
+ * **Warning:** Unsafe handlers use exception-based error handling:
+ * - All thrown errors are treated as retryable by default
+ * - Harder to reason about which errors should be retried
+ * - May lead to unexpected retry behavior
+ *
+ * **Note:** Internally, this function wraps the Promise-based handler into a Future-based
+ * safe handler for consistent processing in the worker.
+ *
+ * @template TContract - The contract definition type
+ * @template TName - The consumer name from the contract
+ * @param contract - The contract definition containing the consumer
+ * @param consumerName - The name of the consumer from the contract
+ * @param handler - The async handler function that processes messages
+ * @param options - Optional consumer options (prefetch, batchSize, batchTimeout)
+ * @returns A type-safe handler 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 { defineUnsafeHandler } from '@amqp-contract/worker';
  *
- * async function handleNotifyOrder(message: WorkerInferConsumerInput<typeof orderContract, 'notifyOrder'>) {
- *   await sendNotification(message);
- * }
+ * // ⚠️ Consider using defineHandler for better error handling
+ * const processOrderHandler = defineUnsafeHandler(
+ *   orderContract,
+ *   'processOrder',
+ *   async (message) => {
+ *     // Throws on error - will be retried
+ *     await processPayment(message);
+ *   }
+ * );
+ * ```
+ */
+declare function defineUnsafeHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: UnsafeHandler<TContract, TName>): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+declare function defineUnsafeHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: UnsafeHandler<TContract, TName>, options: {
+  prefetch?: number;
+  batchSize?: never;
+  batchTimeout?: never;
+}): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+declare function defineUnsafeHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: UnsafeBatchHandler<TContract, TName>, options: {
+  prefetch?: number;
+  batchSize: number;
+  batchTimeout?: number;
+}): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+/**
+ * Unsafe handler entry type for internal use.
+ */
+type UnsafeHandlerEntry<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = UnsafeHandler<TContract, TName> | readonly [UnsafeHandler<TContract, TName>, {
+  prefetch?: number;
+  batchSize?: never;
+  batchTimeout?: never;
+}] | readonly [UnsafeBatchHandler<TContract, TName>, {
+  prefetch?: number;
+  batchSize: number;
+  batchTimeout?: number;
+}];
+/**
+ * Unsafe handlers object type for internal use.
+ */
+type UnsafeHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: UnsafeHandlerEntry<TContract, K> };
+/**
+ * Define multiple unsafe handlers for consumers in a contract.
  *
- * const handlers = defineHandlers(orderContract, {
- *   processOrder: handleProcessOrder,
- *   notifyOrder: handleNotifyOrder,
+ * @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
+ * import { defineUnsafeHandlers } from '@amqp-contract/worker';
+ *
+ * // ⚠️ Consider using defineHandlers for better error handling
+ * const handlers = defineUnsafeHandlers(orderContract, {
+ *   processOrder: async (message) => {
+ *     await processPayment(message);
+ *   },
+ *   notifyOrder: async (message) => {
+ *     await sendNotification(message);
+ *   },
  * });
  * ```
  */
-declare function defineHandlers<TContract extends ContractDefinition>(contract: TContract, handlers: WorkerInferConsumerHandlers<TContract>): WorkerInferConsumerHandlers<TContract>;
+declare function defineUnsafeHandlers<TContract extends ContractDefinition>(contract: TContract, handlers: UnsafeHandlers<TContract>): WorkerInferSafeConsumerHandlers<TContract>;
 //#endregion
-export { type CreateWorkerOptions, MessageValidationError, TechnicalError, TypedAmqpWorker, type WorkerInferConsumerBatchHandler, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlerEntry, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineHandler, defineHandlers };
+export { type CreateWorkerOptions, type HandlerError, MessageValidationError, NonRetryableError, type RetryOptions, RetryableError, TechnicalError, TypedAmqpWorker, type WorkerInferConsumerBatchHandler, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlerEntry, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, type WorkerInferSafeConsumerBatchHandler, type WorkerInferSafeConsumerHandler, type WorkerInferSafeConsumerHandlerEntry, type WorkerInferSafeConsumerHandlers, type WorkerInferUnsafeConsumerBatchHandler, type WorkerInferUnsafeConsumerHandler, type WorkerInferUnsafeConsumerHandlerEntry, type WorkerInferUnsafeConsumerHandlers, defineHandler, defineHandlers, defineUnsafeHandler, defineUnsafeHandlers };
 //# sourceMappingURL=index.d.cts.map