@amqp-contract/worker 0.4.0 → 0.6.0

package/docs/index.md

@@ -8,7 +8,7 @@
 
 ### MessageValidationError
 
-Defined in: [packages/worker/src/errors.ts:35](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L35)
+Defined in: [packages/worker/src/errors.ts:35](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L35)
 
 Error thrown when message validation fails
 
@@ -24,7 +24,7 @@ Error thrown when message validation fails
 new MessageValidationError(consumerName, issues): MessageValidationError;
 ```
 
-Defined in: [packages/worker/src/errors.ts:36](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L36)
+Defined in: [packages/worker/src/errors.ts:36](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L36)
 
 ###### Parameters
 
@@ -48,8 +48,8 @@ WorkerError.constructor
 | Property | Modifier | Type | Description | Inherited from | Defined in |
 | ------ | ------ | ------ | ------ | ------ | ------ |
 | <a id="cause"></a> `cause?` | `public` | `unknown` | - | `WorkerError.cause` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:26 |
-| <a id="consumername"></a> `consumerName` | `readonly` | `string` | - | - | [packages/worker/src/errors.ts:37](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L37) |
-| <a id="issues"></a> `issues` | `readonly` | `unknown` | - | - | [packages/worker/src/errors.ts:38](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L38) |
+| <a id="consumername"></a> `consumerName` | `readonly` | `string` | - | - | [packages/worker/src/errors.ts:37](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L37) |
+| <a id="issues"></a> `issues` | `readonly` | `unknown` | - | - | [packages/worker/src/errors.ts:38](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L38) |
 | <a id="message"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
 | <a id="name"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
 | <a id="stack"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
@@ -159,7 +159,7 @@ WorkerError.prepareStackTrace
 
 ### TechnicalError
 
-Defined in: [packages/worker/src/errors.ts:22](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L22)
+Defined in: [packages/worker/src/errors.ts:22](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L22)
 
 Error for technical/runtime failures in worker operations
 This includes validation failures, parsing failures, and processing failures
@@ -176,7 +176,7 @@ This includes validation failures, parsing failures, and processing failures
 new TechnicalError(message, cause?): TechnicalError;
 ```
 
-Defined in: [packages/worker/src/errors.ts:23](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L23)
+Defined in: [packages/worker/src/errors.ts:23](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L23)
 
 ###### Parameters
 
@@ -199,7 +199,7 @@ WorkerError.constructor
 
 | Property | Modifier | Type | Description | Inherited from | Defined in |
 | ------ | ------ | ------ | ------ | ------ | ------ |
-| <a id="cause-1"></a> `cause?` | `readonly` | `unknown` | - | `WorkerError.cause` | [packages/worker/src/errors.ts:25](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/errors.ts#L25) |
+| <a id="cause-1"></a> `cause?` | `readonly` | `unknown` | - | `WorkerError.cause` | [packages/worker/src/errors.ts:25](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/errors.ts#L25) |
 | <a id="message-1"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
 | <a id="name-1"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
 | <a id="stack-1"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
@@ -309,7 +309,7 @@ WorkerError.prepareStackTrace
 
 ### TypedAmqpWorker
 
-Defined in: [packages/worker/src/worker.ts:83](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L83)
+Defined in: [packages/worker/src/worker.ts:129](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L129)
 
 Type-safe AMQP worker for consuming messages from RabbitMQ.
 
@@ -363,7 +363,7 @@ await worker.close().resultToPromise();
 close(): Future<Result<void, TechnicalError>>;
 ```
 
-Defined in: [packages/worker/src/worker.ts:159](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L159)
+Defined in: [packages/worker/src/worker.ts:242](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L242)
 
 Close the AMQP channel and connection.
 
@@ -391,12 +391,12 @@ if (closeResult.isOk()) {
 static create<TContract>(options): Future<Result<TypedAmqpWorker<TContract>, TechnicalError>>;
 ```
 
-Defined in: [packages/worker/src/worker.ts:120](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L120)
+Defined in: [packages/worker/src/worker.ts:203](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L203)
 
 Create a type-safe AMQP worker from a contract.
 
 Connection management (including automatic reconnection) is handled internally
-by amqp-connection-manager via the AmqpClient. The worker will set up
+by amqp-connection-manager via the [AmqpClient](https://btravers.github.io/amqp-contract/api/core#amqpclient). The worker will set up
 consumers for all contract-defined handlers asynchronously in the background
 once the underlying connection and channels are ready.
 
@@ -445,7 +445,7 @@ if (workerResult.isError()) {
 type CreateWorkerOptions<TContract> = object;
 ```
 
-Defined in: [packages/worker/src/worker.ts:30](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L30)
+Defined in: [packages/worker/src/worker.ts:76](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L76)
 
 Options for creating a type-safe AMQP worker.
 
@@ -455,9 +455,24 @@ Options for creating a type-safe AMQP worker.
 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: {
@@ -477,11 +492,41 @@ const options: CreateWorkerOptions<typeof contract> = {
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="connectionoptions"></a> `connectionOptions?` | `AmqpConnectionManagerOptions` | Optional connection configuration (heartbeat, reconnect settings, etc.) | [packages/worker/src/worker.ts:38](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L38) |
-| <a id="contract"></a> `contract` | `TContract` | The AMQP contract definition specifying consumers and their message schemas | [packages/worker/src/worker.ts:32](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L32) |
-| <a id="handlers"></a> `handlers` | [`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\> | Handlers for each consumer defined in the contract | [packages/worker/src/worker.ts:34](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L34) |
-| <a id="logger"></a> `logger?` | `Logger` | Optional logger for logging message consumption and errors | [packages/worker/src/worker.ts:40](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L40) |
-| <a id="urls"></a> `urls` | `ConnectionUrl`[] | AMQP broker URL(s). Multiple URLs provide failover support | [packages/worker/src/worker.ts:36](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/worker.ts#L36) |
+| <a id="connectionoptions"></a> `connectionOptions?` | `AmqpConnectionManagerOptions` | Optional connection configuration (heartbeat, reconnect settings, etc.) | [packages/worker/src/worker.ts:84](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L84) |
+| <a id="contract"></a> `contract` | `TContract` | The AMQP contract definition specifying consumers and their message schemas | [packages/worker/src/worker.ts:78](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L78) |
+| <a id="handlers"></a> `handlers` | [`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\> | Handlers for each consumer defined in the contract. Can be a function or a tuple of [handler, options] | [packages/worker/src/worker.ts:80](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L80) |
+| <a id="logger"></a> `logger?` | `Logger` | Optional logger for logging message consumption and errors | [packages/worker/src/worker.ts:86](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L86) |
+| <a id="urls"></a> `urls` | `ConnectionUrl`[] | AMQP broker URL(s). Multiple URLs provide failover support | [packages/worker/src/worker.ts:82](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/worker.ts#L82) |
+
+***
+
+### WorkerInferConsumerBatchHandler()
+
+```ts
+type WorkerInferConsumerBatchHandler<TContract, TName> = (messages) => Promise<void>;
+```
+
+Defined in: [packages/worker/src/types.ts:56](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/types.ts#L56)
+
+Infer consumer handler type for batch processing.
+Batch handlers receive an array of messages.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `messages` | [`WorkerInferConsumerInput`](#workerinferconsumerinput)\<`TContract`, `TName`\>[] |
+
+#### Returns
+
+`Promise`\<`void`\>
 
 ***
 
@@ -491,9 +536,11 @@ const options: CreateWorkerOptions<typeof contract> = {
 type WorkerInferConsumerHandler<TContract, TName> = (message) => Promise<void>;
 ```
 
-Defined in: [packages/worker/src/types.ts:45](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/types.ts#L45)
+Defined in: [packages/worker/src/types.ts:47](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/types.ts#L47)
 
-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 Parameters
 
@@ -514,15 +561,51 @@ Infer consumer handler type for a specific consumer
 
 ***
 
+### WorkerInferConsumerHandlerEntry
+
+```ts
+type WorkerInferConsumerHandlerEntry<TContract, TName> = 
+  | WorkerInferConsumerHandler<TContract, TName>
+  | readonly [WorkerInferConsumerHandler<TContract, TName>, {
+  batchSize?: never;
+  batchTimeout?: never;
+  prefetch?: number;
+}]
+  | readonly [WorkerInferConsumerBatchHandler<TContract, TName>, {
+  batchSize: number;
+  batchTimeout?: number;
+  prefetch?: number;
+}];
+```
+
+Defined in: [packages/worker/src/types.ts:69](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/types.ts#L69)
+
+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 Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+***
+
 ### WorkerInferConsumerHandlers
 
 ```ts
-type WorkerInferConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandler<TContract, K> };
+type WorkerInferConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandlerEntry<TContract, K> };
 ```
 
-Defined in: [packages/worker/src/types.ts:53](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/types.ts#L53)
+Defined in: [packages/worker/src/types.ts:87](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/types.ts#L87)
 
-Infer all consumer handlers for a contract
+Infer all consumer handlers for a contract.
+Handlers can be either single-message handlers, batch handlers, or a tuple of [handler, options].
 
 #### Type Parameters
 
@@ -538,7 +621,7 @@ Infer all consumer handlers for a contract
 type WorkerInferConsumerInput<TContract, TName> = ConsumerInferInput<InferConsumer<TContract, TName>>;
 ```
 
-Defined in: [packages/worker/src/types.ts:37](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/types.ts#L37)
+Defined in: [packages/worker/src/types.ts:37](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/types.ts#L37)
 
 Worker perspective types - for consuming messages
 
@@ -553,95 +636,263 @@ Worker perspective types - for consuming messages
 
 ### defineHandler()
 
+#### Call Signature
+
 ```ts
 function defineHandler<TContract, TName>(
    contract, 
    consumerName, 
-handler): WorkerInferConsumerHandler<TContract, TName>;
+handler): WorkerInferConsumerHandlerEntry<TContract, TName>;
 ```
 
-Defined in: [packages/worker/src/handlers.ts:73](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/handlers.ts#L73)
+Defined in: [packages/worker/src/handlers.ts:70](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/handlers.ts#L70)
 
 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.
 
-#### Type Parameters
+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.
+
+##### Type Parameters
 
 | Type Parameter | Description |
 | ------ | ------ |
 | `TContract` *extends* `ContractDefinition` | The contract definition type |
 | `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
 
-#### Parameters
+##### Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
 | `contract` | `TContract` | The contract definition containing the consumer |
 | `consumerName` | `TName` | The name of the consumer from the contract |
-| `handler` | [`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\> | The async handler function that processes messages |
+| `handler` | [`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
 
-#### Returns
+##### Returns
 
-[`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\>
+[`WorkerInferConsumerHandlerEntry`](#workerinferconsumerhandlerentry)\<`TContract`, `TName`\>
 
 A type-safe handler that can be used with TypedAmqpWorker
 
-#### Examples
+##### Example
 
 ```typescript
 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,
+// Single-message handler with prefetch
+const processOrderWithPrefetch = defineHandler(
+  orderContract,
+  'processOrder',
+  async (message) => {
+    await processOrder(message);
   },
-  connection: 'amqp://localhost',
-});
+  { prefetch: 10 }
+);
+
+// Batch handler - MUST include batchSize
+const processBatchOrders = defineHandler(
+  orderContract,
+  'processOrders',
+  async (messages) => {
+    // messages is an array - batchSize configuration is REQUIRED
+    await db.insertMany(messages);
+  },
+  { batchSize: 5, batchTimeout: 1000 }
+);
 ```
 
+#### Call Signature
+
+```ts
+function defineHandler<TContract, TName>(
+   contract, 
+   consumerName, 
+   handler, 
+options): WorkerInferConsumerHandlerEntry<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/handlers.ts:78](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/handlers.ts#L78)
+
+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.
+
+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.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+| `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumer |
+| `consumerName` | `TName` | The name of the consumer from the contract |
+| `handler` | [`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
+| `options` | \{ `batchSize?`: `undefined`; `batchTimeout?`: `undefined`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) - For single-message handlers: { prefetch?: number } is optional - For batch handlers: { batchSize: number, batchTimeout?: number } is REQUIRED |
+| `options.batchSize?` | `undefined` | - |
+| `options.batchTimeout?` | `undefined` | - |
+| `options.prefetch?` | `number` | - |
+
+##### Returns
+
+[`WorkerInferConsumerHandlerEntry`](#workerinferconsumerhandlerentry)\<`TContract`, `TName`\>
+
+A type-safe handler that can be used with TypedAmqpWorker
+
+##### Example
+
 ```typescript
-// Define multiple handlers
+import { defineHandler } from '@amqp-contract/worker';
+import { orderContract } from './contract';
+
+// Simple single-message handler without options
 const processOrderHandler = defineHandler(
   orderContract,
   'processOrder',
   async (message) => {
-    await processOrder(message);
+    console.log('Processing order:', message.orderId);
+    await processPayment(message);
   }
 );
 
-const notifyOrderHandler = defineHandler(
+// Single-message handler with prefetch
+const processOrderWithPrefetch = defineHandler(
   orderContract,
-  'notifyOrder',
+  'processOrder',
   async (message) => {
-    await sendNotification(message);
+    await processOrder(message);
+  },
+  { prefetch: 10 }
+);
+
+// Batch handler - MUST include batchSize
+const processBatchOrders = defineHandler(
+  orderContract,
+  'processOrders',
+  async (messages) => {
+    // messages is an array - batchSize configuration is REQUIRED
+    await db.insertMany(messages);
+  },
+  { batchSize: 5, batchTimeout: 1000 }
+);
+```
+
+#### Call Signature
+
+```ts
+function defineHandler<TContract, TName>(
+   contract, 
+   consumerName, 
+   handler, 
+options): WorkerInferConsumerHandlerEntry<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/handlers.ts:87](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/handlers.ts#L87)
+
+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.
+
+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.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+| `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumer |
+| `consumerName` | `TName` | The name of the consumer from the contract |
+| `handler` | [`WorkerInferConsumerBatchHandler`](#workerinferconsumerbatchhandler)\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
+| `options` | \{ `batchSize`: `number`; `batchTimeout?`: `number`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) - For single-message handlers: { prefetch?: number } is optional - For batch handlers: { batchSize: number, batchTimeout?: number } is REQUIRED |
+| `options.batchSize` | `number` | - |
+| `options.batchTimeout?` | `number` | - |
+| `options.prefetch?` | `number` | - |
+
+##### Returns
+
+[`WorkerInferConsumerHandlerEntry`](#workerinferconsumerhandlerentry)\<`TContract`, `TName`\>
+
+A type-safe handler that can be used with TypedAmqpWorker
+
+##### Example
+
+```typescript
+import { defineHandler } from '@amqp-contract/worker';
+import { orderContract } from './contract';
+
+// Simple single-message handler without options
+const processOrderHandler = defineHandler(
+  orderContract,
+  'processOrder',
+  async (message) => {
+    console.log('Processing order:', message.orderId);
+    await processPayment(message);
   }
 );
 
-// Compose handlers
-const worker = await TypedAmqpWorker.create({
-  contract: orderContract,
-  handlers: {
-    processOrder: processOrderHandler,
-    notifyOrder: notifyOrderHandler,
+// Single-message handler with prefetch
+const processOrderWithPrefetch = defineHandler(
+  orderContract,
+  'processOrder',
+  async (message) => {
+    await processOrder(message);
   },
-  connection: 'amqp://localhost',
-});
+  { prefetch: 10 }
+);
+
+// Batch handler - MUST include batchSize
+const processBatchOrders = defineHandler(
+  orderContract,
+  'processOrders',
+  async (messages) => {
+    // messages is an array - batchSize configuration is REQUIRED
+    await db.insertMany(messages);
+  },
+  { batchSize: 5, batchTimeout: 1000 }
+);
 ```
 
 ***
@@ -652,7 +903,7 @@ const worker = await TypedAmqpWorker.create({
 function defineHandlers<TContract>(contract, handlers): WorkerInferConsumerHandlers<TContract>;
 ```
 
-Defined in: [packages/worker/src/handlers.ts:152](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker/src/handlers.ts#L152)
+Defined in: [packages/worker/src/handlers.ts:181](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker/src/handlers.ts#L181)
 
 Define multiple type-safe handlers for consumers in a contract.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amqp-contract/worker",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Worker utilities for consuming messages using amqp-contract",
   "keywords": [
     "amqp",
@@ -44,8 +44,8 @@
   "dependencies": {
     "@standard-schema/spec": "1.1.0",
     "@swan-io/boxed": "3.2.1",
-    "@amqp-contract/contract": "0.4.0",
-    "@amqp-contract/core": "0.4.0"
+    "@amqp-contract/contract": "0.6.0",
+    "@amqp-contract/core": "0.6.0"
   },
   "devDependencies": {
     "@types/amqplib": "0.10.8",
@@ -53,14 +53,13 @@
     "@vitest/coverage-v8": "4.0.16",
     "amqp-connection-manager": "5.0.0",
     "amqplib": "0.10.9",
-    "tsdown": "0.18.2",
+    "tsdown": "0.18.3",
     "typedoc": "0.28.15",
     "typedoc-plugin-markdown": "4.9.0",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
     "zod": "4.2.1",
-    "@amqp-contract/client": "0.4.0",
-    "@amqp-contract/testing": "0.4.0",
+    "@amqp-contract/testing": "0.6.0",
     "@amqp-contract/tsconfig": "0.0.0",
     "@amqp-contract/typedoc": "0.0.1"
   },
@@ -68,9 +67,9 @@
     "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
     "build:docs": "typedoc",
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest run --project unit",
+    "test": "vitest run --project integration",
     "test:integration": "vitest run --project integration",
-    "test:watch": "vitest --project unit",
+    "test:watch": "vitest --project integration",
     "typecheck": "tsc --noEmit"
   }
 }