@amqp-contract/worker 0.5.0 → 0.7.0

package/README.md

@@ -16,12 +16,22 @@
 pnpm add @amqp-contract/worker
 ```
 
+## Features
+
+- ✅ **Type-safe message consumption** — Handlers are fully typed based on your contract
+- ✅ **Automatic validation** — Messages are validated before reaching your handlers
+- ✅ **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
+
 ## Usage
 
+### Basic Usage
+
 ```typescript
-import { TypedAmqpWorker } from '@amqp-contract/worker';
-import type { Logger } from '@amqp-contract/core';
-import { contract } from './contract';
+import { TypedAmqpWorker } from "@amqp-contract/worker";
+import type { Logger } from "@amqp-contract/core";
+import { contract } from "./contract";
 
 // Optional: Create a logger implementation
 const logger: Logger = {
@@ -36,7 +46,7 @@ const worker = await TypedAmqpWorker.create({
   contract,
   handlers: {
     processOrder: async (message) => {
-      console.log('Processing order:', message.orderId);
+      console.log("Processing order:", message.orderId);
 
       // Your business logic here
       await processPayment(message);
@@ -45,7 +55,7 @@ const worker = await TypedAmqpWorker.create({
       // If an exception is thrown, the message is automatically requeued
     },
   },
-  urls: ['amqp://localhost'],
+  urls: ["amqp://localhost"],
   logger, // Optional: logs message consumption and errors
 });
 
@@ -55,6 +65,10 @@ const worker = await TypedAmqpWorker.create({
 // await worker.close();
 ```
 
+### 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).
+
 ## Defining Handlers Externally
 
 You can define handlers outside of the worker creation using `defineHandler` and `defineHandlers` for better code organization. See the [Worker API documentation](https://btravers.github.io/amqp-contract/api/worker) for details.
@@ -75,7 +89,7 @@ handlers: {
       // Message is requeued for retry
       throw error;
     }
-  }
+  };
 }
 ```
 

package/dist/index.cjs

@@ -1,5 +1,7 @@
 let _amqp_contract_core = require("@amqp-contract/core");
 let _swan_io_boxed = require("@swan-io/boxed");
+let node_zlib = require("node:zlib");
+let node_util = require("node:util");
 
 //#region src/errors.ts
 /**
@@ -36,6 +38,29 @@ var MessageValidationError = class extends WorkerError {
 	}
 };
 
+//#endregion
+//#region src/decompression.ts
+const gunzipAsync = (0, node_util.promisify)(node_zlib.gunzip);
+const inflateAsync = (0, node_util.promisify)(node_zlib.inflate);
+/**
+* Decompress a buffer based on the content-encoding header.
+*
+* @param buffer - The buffer to decompress
+* @param contentEncoding - The content-encoding header value (e.g., 'gzip', 'deflate')
+* @returns A promise that resolves to the decompressed buffer
+* @throws Error if decompression fails or if the encoding is unsupported
+*
+* @internal
+*/
+async function decompressBuffer(buffer, contentEncoding) {
+	if (!contentEncoding) return buffer;
+	switch (contentEncoding.toLowerCase()) {
+		case "gzip": return gunzipAsync(buffer);
+		case "deflate": return inflateAsync(buffer);
+		default: throw new Error(`Unsupported content-encoding: ${contentEncoding}`);
+	}
+}
+
 //#endregion
 //#region src/worker.ts
 /**
@@ -79,11 +104,23 @@ var MessageValidationError = class extends WorkerError {
 * ```
 */
 var TypedAmqpWorker = class TypedAmqpWorker {
+	actualHandlers;
+	consumerOptions;
+	batchTimers = /* @__PURE__ */ new Map();
+	consumerTags = /* @__PURE__ */ new Set();
 	constructor(contract, amqpClient, handlers, logger) {
 		this.contract = contract;
 		this.amqpClient = amqpClient;
-		this.handlers = handlers;
 		this.logger = logger;
+		this.actualHandlers = {};
+		this.consumerOptions = {};
+		for (const consumerName of Object.keys(handlers)) {
+			const handlerEntry = handlers[consumerName];
+			if (Array.isArray(handlerEntry)) {
+				this.actualHandlers[consumerName] = handlerEntry[0];
+				this.consumerOptions[consumerName] = handlerEntry[1];
+			} else this.actualHandlers[consumerName] = handlerEntry;
+		}
 	}
 	/**
 	* Create a type-safe AMQP worker from a contract.
@@ -138,7 +175,17 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	* ```
 	*/
 	close() {
-		return _swan_io_boxed.Future.fromPromise(this.amqpClient.close()).mapError((error) => new TechnicalError("Failed to close AMQP connection", error)).mapOk(() => void 0);
+		for (const timer of this.batchTimers.values()) clearTimeout(timer);
+		this.batchTimers.clear();
+		return _swan_io_boxed.Future.all(Array.from(this.consumerTags).map((consumerTag) => _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.cancel(consumerTag)).mapErrorToResult((error) => {
+			this.logger?.warn("Failed to cancel consumer during close", {
+				consumerTag,
+				error
+			});
+			return _swan_io_boxed.Result.Ok(void 0);
+		}))).map(_swan_io_boxed.Result.all).tapOk(() => {
+			this.consumerTags.clear();
+		}).flatMapOk(() => _swan_io_boxed.Future.fromPromise(this.amqpClient.close())).mapError((error) => new TechnicalError("Failed to close AMQP connection", error)).mapOk(() => void 0);
 	}
 	/**
 	* Start consuming messages for all consumers
@@ -146,6 +193,21 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 	consumeAll() {
 		if (!this.contract.consumers) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError("No consumers defined in contract")));
 		const consumerNames = Object.keys(this.contract.consumers);
+		let maxPrefetch = 0;
+		for (const consumerName of consumerNames) {
+			const options = this.consumerOptions[consumerName];
+			if (options?.prefetch !== void 0) {
+				if (options.prefetch <= 0 || !Number.isInteger(options.prefetch)) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Invalid prefetch value for "${String(consumerName)}": must be a positive integer`)));
+				maxPrefetch = Math.max(maxPrefetch, options.prefetch);
+			}
+			if (options?.batchSize !== void 0) {
+				const effectivePrefetch = options.prefetch ?? options.batchSize;
+				maxPrefetch = Math.max(maxPrefetch, effectivePrefetch);
+			}
+		}
+		if (maxPrefetch > 0) this.amqpClient.channel.addSetup(async (channel) => {
+			await channel.prefetch(maxPrefetch);
+		});
 		return _swan_io_boxed.Future.all(consumerNames.map((consumerName) => this.consume(consumerName))).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
 	}
 	waitForConnectionReady() {
@@ -163,17 +225,34 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 			const available = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
 			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Consumer not found: "${String(consumerName)}". Available consumers: ${available}`)));
 		}
-		const handler = this.handlers[consumerName];
+		const handler = this.actualHandlers[consumerName];
 		if (!handler) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Handler for "${String(consumerName)}" not provided`)));
-		return _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.consume(consumer.queue.name, async (msg) => {
-			if (msg === null) {
-				this.logger?.warn("Consumer cancelled by server", {
-					consumerName: String(consumerName),
-					queueName: consumer.queue.name
-				});
-				return;
-			}
-			const parseResult = _swan_io_boxed.Result.fromExecution(() => JSON.parse(msg.content.toString()));
+		const options = this.consumerOptions[consumerName] ?? {};
+		if (options.batchSize !== void 0) {
+			if (options.batchSize <= 0 || !Number.isInteger(options.batchSize)) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Invalid batchSize for "${String(consumerName)}": must be a positive integer`)));
+		}
+		if (options.batchTimeout !== void 0) {
+			if (typeof options.batchTimeout !== "number" || !Number.isFinite(options.batchTimeout) || options.batchTimeout <= 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Invalid batchTimeout for "${String(consumerName)}": must be a positive number`)));
+		}
+		if (options.batchSize !== void 0 && options.batchSize > 0) return this.consumeBatch(consumerName, consumer, options, handler);
+		else return this.consumeSingle(consumerName, consumer, handler);
+	}
+	/**
+	* Parse and validate a message from AMQP
+	* @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) => {
+			this.logger?.error("Error decompressing message", {
+				consumerName: String(consumerName),
+				queueName: consumer.queue.name,
+				contentEncoding: msg.properties.contentEncoding,
+				error
+			});
+			this.amqpClient.channel.nack(msg, false, false);
+		});
+		const parseMessage = (buffer) => {
+			const parseResult = _swan_io_boxed.Result.fromExecution(() => JSON.parse(buffer.toString()));
 			if (parseResult.isError()) {
 				this.logger?.error("Error parsing message", {
 					consumerName: String(consumerName),
@@ -181,20 +260,41 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 					error: parseResult.error
 				});
 				this.amqpClient.channel.nack(msg, false, false);
-				return;
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(void 0));
 			}
-			const rawValidation = consumer.message.payload["~standard"].validate(parseResult.value);
-			await _swan_io_boxed.Future.fromPromise(rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation)).mapOkToResult((validationResult) => {
-				if (validationResult.issues) return _swan_io_boxed.Result.Error(new MessageValidationError(String(consumerName), validationResult.issues));
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(parseResult.value));
+		};
+		const validateMessage = (parsedMessage) => {
+			const rawValidation = consumer.message.payload["~standard"].validate(parsedMessage);
+			return _swan_io_boxed.Future.fromPromise(rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation)).mapOkToResult((validationResult) => {
+				if (validationResult.issues) {
+					const error = new MessageValidationError(String(consumerName), validationResult.issues);
+					this.logger?.error("Message validation failed", {
+						consumerName: String(consumerName),
+						queueName: consumer.queue.name,
+						error
+					});
+					this.amqpClient.channel.nack(msg, false, false);
+					return _swan_io_boxed.Result.Error(void 0);
+				}
 				return _swan_io_boxed.Result.Ok(validationResult.value);
-			}).tapError((error) => {
-				this.logger?.error("Message validation failed", {
+			});
+		};
+		return decompressMessage.flatMapOk(parseMessage).flatMapOk(validateMessage);
+	}
+	/**
+	* Consume messages one at a time
+	*/
+	consumeSingle(consumerName, consumer, handler) {
+		return _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.consume(consumer.queue.name, async (msg) => {
+			if (msg === null) {
+				this.logger?.warn("Consumer cancelled by server", {
 					consumerName: String(consumerName),
-					queueName: consumer.queue.name,
-					error
+					queueName: consumer.queue.name
 				});
-				this.amqpClient.channel.nack(msg, false, false);
-			}).flatMapOk((validatedMessage) => _swan_io_boxed.Future.fromPromise(handler(validatedMessage)).tapError((error) => {
+				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,
@@ -208,88 +308,104 @@ var TypedAmqpWorker = class TypedAmqpWorker {
 				});
 				this.amqpClient.channel.ack(msg);
 			}).toPromise();
-		})).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
+		})).tapOk((reply) => {
+			this.consumerTags.add(reply.consumerTag);
+		}).mapError((error) => new TechnicalError(`Failed to start consuming for "${String(consumerName)}"`, error)).mapOk(() => void 0);
+	}
+	/**
+	* Consume messages in batches
+	*/
+	consumeBatch(consumerName, consumer, options, handler) {
+		const batchSize = options.batchSize;
+		const batchTimeout = options.batchTimeout ?? 1e3;
+		const timerKey = String(consumerName);
+		let batch = [];
+		let isProcessing = false;
+		const processBatch = async () => {
+			if (isProcessing || batch.length === 0) return;
+			isProcessing = true;
+			const currentBatch = batch;
+			batch = [];
+			const timer = this.batchTimers.get(timerKey);
+			if (timer) {
+				clearTimeout(timer);
+				this.batchTimers.delete(timerKey);
+			}
+			const messages = currentBatch.map((item) => item.message);
+			this.logger?.info("Processing batch", {
+				consumerName: String(consumerName),
+				queueName: consumer.queue.name,
+				batchSize: currentBatch.length
+			});
+			try {
+				await handler(messages);
+				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) {
+				this.logger?.error("Error processing batch", {
+					consumerName: String(consumerName),
+					queueName: consumer.queue.name,
+					batchSize: currentBatch.length,
+					error
+				});
+				for (const item of currentBatch) this.amqpClient.channel.nack(item.amqpMessage, false, true);
+			} finally {
+				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
+					});
+				});
+			}, batchTimeout);
+			this.batchTimers.set(timerKey, timer);
+		};
+		return _swan_io_boxed.Future.fromPromise(this.amqpClient.channel.consume(consumer.queue.name, async (msg) => {
+			if (msg === null) {
+				this.logger?.warn("Consumer cancelled by server", {
+					consumerName: String(consumerName),
+					queueName: consumer.queue.name
+				});
+				await processBatch();
+				return;
+			}
+			const validationResult = await this.parseAndValidateMessage(msg, consumer, consumerName).toPromise();
+			if (validationResult.isError()) return;
+			batch.push({
+				message: validationResult.value,
+				amqpMessage: msg
+			});
+			if (batch.length >= batchSize) {
+				await processBatch();
+				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);
 	}
 };
 
 //#endregion
 //#region src/handlers.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.
-*
-* @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
-* @returns A type-safe handler that can be used with TypedAmqpWorker
-*
-* @example
-* ```typescript
-* import { defineHandler } from '@amqp-contract/worker';
-* import { orderContract } from './contract';
-*
-* // Define handler outside of worker creation
-* const processOrderHandler = defineHandler(
-*   orderContract,
-*   'processOrder',
-*   async (message) => {
-*     // message is fully typed based on the contract
-*     console.log('Processing order:', message.orderId);
-*     await processPayment(message);
-*   }
-* );
-*
-* // Use the handler in worker
-* const worker = await TypedAmqpWorker.create({
-*   contract: orderContract,
-*   handlers: {
-*     processOrder: processOrderHandler,
-*   },
-*   connection: 'amqp://localhost',
-* });
-* ```
-*
-* @example
-* ```typescript
-* // Define multiple handlers
-* const processOrderHandler = defineHandler(
-*   orderContract,
-*   'processOrder',
-*   async (message) => {
-*     await processOrder(message);
-*   }
-* );
-*
-* const notifyOrderHandler = defineHandler(
-*   orderContract,
-*   'notifyOrder',
-*   async (message) => {
-*     await sendNotification(message);
-*   }
-* );
-*
-* // Compose handlers
-* const worker = await TypedAmqpWorker.create({
-*   contract: orderContract,
-*   handlers: {
-*     processOrder: processOrderHandler,
-*     notifyOrder: notifyOrderHandler,
-*   },
-*   connection: 'amqp://localhost',
-* });
-* ```
-*/
-function defineHandler(contract, consumerName, handler) {
+function defineHandler(contract, consumerName, handler, options) {
 	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}`);
 	}
+	if (options) return [handler, options];
 	return handler;
 }
 /**

package/dist/index.d.cts

@@ -50,13 +50,38 @@ 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
+ * 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.
  */
 type WorkerInferConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Promise<void>;
 /**
- * Infer all consumer handlers for a contract
+ * Infer consumer handler type for batch processing.
+ * Batch handlers receive an array of messages.
  */
-type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandler<TContract, K> };
+type WorkerInferConsumerBatchHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (messages: Array<WorkerInferConsumerInput<TContract, TName>>) => Promise<void>;
+/**
+ * Infer 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 }]`
+ */
+type WorkerInferConsumerHandlerEntry<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = WorkerInferConsumerHandler<TContract, TName> | readonly [WorkerInferConsumerHandler<TContract, TName>, {
+  prefetch?: number;
+  batchSize?: never;
+  batchTimeout?: never;
+}] | readonly [WorkerInferConsumerBatchHandler<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].
+ */
+type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandlerEntry<TContract, K> };
 //#endregion
 //#region src/worker.d.ts
 /**
@@ -69,9 +94,24 @@ type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in
  * const options: CreateWorkerOptions<typeof contract> = {
  *   contract: myContract,
  *   handlers: {
+ *     // Simple handler
  *     processOrder: async (message) => {
  *       console.log('Processing order:', message.orderId);
- *     }
+ *     },
+ *     // Handler with options (prefetch)
+ *     processPayment: [
+ *       async (message) => {
+ *         console.log('Processing payment:', message.paymentId);
+ *       },
+ *       { prefetch: 10 }
+ *     ],
+ *     // Handler with batch processing
+ *     processNotifications: [
+ *       async (messages) => {
+ *         console.log('Processing batch:', messages.length);
+ *       },
+ *       { batchSize: 5, batchTimeout: 1000 }
+ *     ]
  *   },
  *   urls: ['amqp://localhost'],
  *   connectionOptions: {
@@ -84,7 +124,7 @@ type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in
 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 */
+  /** Handlers for each consumer defined in the contract. Can be a function or a tuple of [handler, options] */
   handlers: WorkerInferConsumerHandlers<TContract>;
   /** AMQP broker URL(s). Multiple URLs provide failover support */
   urls: ConnectionUrl[];
@@ -136,8 +176,11 @@ type CreateWorkerOptions<TContract extends ContractDefinition> = {
 declare class TypedAmqpWorker<TContract extends ContractDefinition> {
   private readonly contract;
   private readonly amqpClient;
-  private readonly handlers;
   private readonly logger?;
+  private readonly actualHandlers;
+  private readonly consumerOptions;
+  private readonly batchTimers;
+  private readonly consumerTags;
   private constructor();
   /**
    * Create a type-safe AMQP worker from a contract.
@@ -201,6 +244,19 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
    * Start consuming messages for a specific consumer
    */
   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)
+   */
+  private parseAndValidateMessage;
+  /**
+   * Consume messages one at a time
+   */
+  private consumeSingle;
+  /**
+   * Consume messages in batches
+   */
+  private consumeBatch;
 }
 //#endregion
 //#region src/handlers.d.ts
@@ -210,11 +266,22 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
  * This utility allows you to define handlers outside of the worker creation,
  * providing better code organization and reusability.
  *
+ * 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
+ * @param handler - The async handler function that processes messages (single or batch)
+ * @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
@@ -222,58 +289,49 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
  * import { defineHandler } from '@amqp-contract/worker';
  * import { orderContract } from './contract';
  *
- * // Define handler outside of worker creation
+ * // Simple single-message handler without options
  * const processOrderHandler = defineHandler(
  *   orderContract,
  *   'processOrder',
  *   async (message) => {
- *     // message is fully typed based on the contract
  *     console.log('Processing order:', message.orderId);
  *     await processPayment(message);
  *   }
  * );
  *
- * // Use the handler in worker
- * const worker = await TypedAmqpWorker.create({
- *   contract: orderContract,
- *   handlers: {
- *     processOrder: processOrderHandler,
- *   },
- *   connection: 'amqp://localhost',
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Define multiple handlers
- * const processOrderHandler = defineHandler(
+ * // Single-message handler with prefetch
+ * const processOrderWithPrefetch = defineHandler(
  *   orderContract,
  *   'processOrder',
  *   async (message) => {
  *     await processOrder(message);
- *   }
+ *   },
+ *   { prefetch: 10 }
  * );
  *
- * const notifyOrderHandler = defineHandler(
+ * // Batch handler - MUST include batchSize
+ * const processBatchOrders = defineHandler(
  *   orderContract,
- *   'notifyOrder',
- *   async (message) => {
- *     await sendNotification(message);
- *   }
- * );
- *
- * // Compose handlers
- * const worker = await TypedAmqpWorker.create({
- *   contract: orderContract,
- *   handlers: {
- *     processOrder: processOrderHandler,
- *     notifyOrder: notifyOrderHandler,
+ *   'processOrders',
+ *   async (messages) => {
+ *     // messages is an array - batchSize configuration is REQUIRED
+ *     await db.insertMany(messages);
  *   },
- *   connection: 'amqp://localhost',
- * });
+ *   { batchSize: 5, batchTimeout: 1000 }
+ * );
  * ```
  */
-declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferConsumerHandler<TContract, TName>): WorkerInferConsumerHandler<TContract, TName>;
+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: {
+  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: {
+  prefetch?: number;
+  batchSize: number;
+  batchTimeout?: number;
+}): WorkerInferConsumerHandlerEntry<TContract, TName>;
 /**
  * Define multiple type-safe handlers for consumers in a contract.
  *
@@ -332,5 +390,5 @@ declare function defineHandler<TContract extends ContractDefinition, TName exten
  */
 declare function defineHandlers<TContract extends ContractDefinition>(contract: TContract, handlers: WorkerInferConsumerHandlers<TContract>): WorkerInferConsumerHandlers<TContract>;
 //#endregion
-export { type CreateWorkerOptions, MessageValidationError, TechnicalError, TypedAmqpWorker, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineHandler, defineHandlers };
+export { type CreateWorkerOptions, MessageValidationError, TechnicalError, TypedAmqpWorker, type WorkerInferConsumerBatchHandler, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlerEntry, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineHandler, defineHandlers };
 //# sourceMappingURL=index.d.cts.map