@amqp-contract/worker-nestjs 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { AmqpConnectionManagerOptions, ConnectionUrl } from "amqp-connection-manager";
 import { DynamicModule, ModuleMetadata, OnModuleDestroy, OnModuleInit, Type } from "@nestjs/common";
-import { WorkerInferConsumerHandler, WorkerInferConsumerHandlers, WorkerInferConsumerHandlers as WorkerInferConsumerHandlers$1, WorkerInferConsumerInput, defineHandler, defineHandlers } from "@amqp-contract/worker";
+import { WorkerInferConsumerHandlers, WorkerInferConsumerHandlers as WorkerInferConsumerHandlers$1, defineHandler, defineHandlers } from "@amqp-contract/worker";
 import { ContractDefinition } from "@amqp-contract/contract";
 
 //#region src/worker.service.d.ts
@@ -190,5 +190,5 @@ declare class AmqpWorkerModule {
  */
 declare const MODULE_OPTIONS_TOKEN: unique symbol;
 //#endregion
-export { AmqpWorkerModule, type AmqpWorkerModuleAsyncOptions, type AmqpWorkerModuleOptions, AmqpWorkerService, MODULE_OPTIONS_TOKEN, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineHandler, defineHandlers };
+export { AmqpWorkerModule, type AmqpWorkerModuleAsyncOptions, type AmqpWorkerModuleOptions, AmqpWorkerService, MODULE_OPTIONS_TOKEN, type WorkerInferConsumerHandlers, defineHandler, defineHandlers };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { DynamicModule, ModuleMetadata, OnModuleDestroy, OnModuleInit, Type } from "@nestjs/common";
-import { WorkerInferConsumerHandler, WorkerInferConsumerHandlers, WorkerInferConsumerHandlers as WorkerInferConsumerHandlers$1, WorkerInferConsumerInput, defineHandler, defineHandlers } from "@amqp-contract/worker";
+import { WorkerInferConsumerHandlers, WorkerInferConsumerHandlers as WorkerInferConsumerHandlers$1, defineHandler, defineHandlers } from "@amqp-contract/worker";
 import { AmqpConnectionManagerOptions, ConnectionUrl } from "amqp-connection-manager";
 import { ContractDefinition } from "@amqp-contract/contract";
 
@@ -190,5 +190,5 @@ declare class AmqpWorkerModule {
  */
 declare const MODULE_OPTIONS_TOKEN: unique symbol;
 //#endregion
-export { AmqpWorkerModule, type AmqpWorkerModuleAsyncOptions, type AmqpWorkerModuleOptions, AmqpWorkerService, MODULE_OPTIONS_TOKEN, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineHandler, defineHandlers };
+export { AmqpWorkerModule, type AmqpWorkerModuleAsyncOptions, type AmqpWorkerModuleOptions, AmqpWorkerService, MODULE_OPTIONS_TOKEN, type WorkerInferConsumerHandlers, defineHandler, defineHandlers };
 //# sourceMappingURL=index.d.mts.map

package/docs/index.md

@@ -8,7 +8,7 @@
 
 ### AmqpWorkerModule
 
-Defined in: [worker-nestjs/src/worker.module.ts:88](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L88)
+Defined in: [worker-nestjs/src/worker.module.ts:88](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L88)
 
 NestJS module for AMQP worker integration
 This module provides type-safe AMQP worker functionality using @amqp-contract/worker
@@ -79,7 +79,7 @@ new AmqpWorkerModule(): AmqpWorkerModule;
 static forRoot<TContract>(options): DynamicModule;
 ```
 
-Defined in: [worker-nestjs/src/worker.module.ts:95](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L95)
+Defined in: [worker-nestjs/src/worker.module.ts:95](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L95)
 
 Register the AMQP worker module with synchronous configuration
 
@@ -107,7 +107,7 @@ A dynamic module for NestJS
 static forRootAsync<TContract>(options): DynamicModule;
 ```
 
-Defined in: [worker-nestjs/src/worker.module.ts:117](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L117)
+Defined in: [worker-nestjs/src/worker.module.ts:117](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L117)
 
 Register the AMQP worker module with asynchronous configuration
 
@@ -133,11 +133,11 @@ A dynamic module for NestJS
 
 ### AmqpWorkerService
 
-Defined in: [worker-nestjs/src/worker.service.ts:74](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L74)
+Defined in: [worker-nestjs/src/worker.service.ts:74](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L74)
 
 Type-safe AMQP worker service for NestJS applications.
 
-This service wraps TypedAmqpWorker and integrates it with the NestJS
+This service wraps [TypedAmqpWorker](https://btravers.github.io/amqp-contract/api/worker#typedamqpworker) and integrates it with the NestJS
 lifecycle, automatically starting message consumption on module init and
 cleaning up resources on module destroy.
 
@@ -186,7 +186,7 @@ export class AppModule {}
 new AmqpWorkerService<TContract>(options): AmqpWorkerService<TContract>;
 ```
 
-Defined in: [worker-nestjs/src/worker.service.ts:79](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L79)
+Defined in: [worker-nestjs/src/worker.service.ts:79](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L79)
 
 ###### Parameters
 
@@ -206,7 +206,7 @@ Defined in: [worker-nestjs/src/worker.service.ts:79](https://github.com/btravers
 onModuleDestroy(): Promise<void>;
 ```
 
-Defined in: [worker-nestjs/src/worker.service.ts:105](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L105)
+Defined in: [worker-nestjs/src/worker.service.ts:105](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L105)
 
 Close the AMQP worker when the NestJS module is destroyed.
 
@@ -230,7 +230,7 @@ OnModuleDestroy.onModuleDestroy
 onModuleInit(): Promise<void>;
 ```
 
-Defined in: [worker-nestjs/src/worker.service.ts:94](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L94)
+Defined in: [worker-nestjs/src/worker.service.ts:94](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L94)
 
 Initialize the AMQP worker when the NestJS module starts.
 
@@ -261,7 +261,7 @@ OnModuleInit.onModuleInit
 type AmqpWorkerModuleAsyncOptions<TContract> = object;
 ```
 
-Defined in: [worker-nestjs/src/worker.module.ts:22](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L22)
+Defined in: [worker-nestjs/src/worker.module.ts:22](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L22)
 
 Options for async module configuration using factory pattern
 
@@ -275,9 +275,9 @@ Options for async module configuration using factory pattern
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="imports"></a> `imports?` | `ModuleMetadata`\[`"imports"`\] | Optional list of imported modules that export providers needed by the factory | [worker-nestjs/src/worker.module.ts:37](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L37) |
-| <a id="inject"></a> `inject?` | (`string` \| `symbol` \| `Type`\<`unknown`\>)[] | Optional dependencies to inject into the factory function. Can be a token (string/symbol) a class or a reference to a provider. | [worker-nestjs/src/worker.module.ts:33](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L33) |
-| <a id="usefactory"></a> `useFactory` | (...`args`) => `AmqpWorkerModuleOptionsFactory`\<`TContract`\> | Factory function that returns the module options. Can use injected dependencies to create configuration. | [worker-nestjs/src/worker.module.ts:28](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module.ts#L28) |
+| <a id="imports"></a> `imports?` | `ModuleMetadata`\[`"imports"`\] | Optional list of imported modules that export providers needed by the factory | [worker-nestjs/src/worker.module.ts:37](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L37) |
+| <a id="inject"></a> `inject?` | (`string` \| `symbol` \| `Type`\<`unknown`\>)[] | Optional dependencies to inject into the factory function. Can be a token (string/symbol) a class or a reference to a provider. | [worker-nestjs/src/worker.module.ts:33](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L33) |
+| <a id="usefactory"></a> `useFactory` | (...`args`) => `AmqpWorkerModuleOptionsFactory`\<`TContract`\> | Factory function that returns the module options. Can use injected dependencies to create configuration. | [worker-nestjs/src/worker.module.ts:28](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module.ts#L28) |
 
 ***
 
@@ -287,7 +287,7 @@ Options for async module configuration using factory pattern
 type AmqpWorkerModuleOptions<TContract> = object;
 ```
 
-Defined in: [worker-nestjs/src/worker.service.ts:28](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L28)
+Defined in: [worker-nestjs/src/worker.service.ts:28](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L28)
 
 Configuration options for the AMQP worker NestJS module.
 
@@ -318,183 +318,304 @@ const options: AmqpWorkerModuleOptions<typeof contract> = {
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="connectionoptions"></a> `connectionOptions?` | `AmqpConnectionManagerOptions` | Optional connection configuration (heartbeat, reconnect settings, etc.) | [worker-nestjs/src/worker.service.ts:36](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L36) |
-| <a id="contract"></a> `contract` | `TContract` | The AMQP contract definition specifying consumers and their message schemas | [worker-nestjs/src/worker.service.ts:30](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L30) |
-| <a id="handlers"></a> `handlers` | [`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\> | Message handlers for each consumer defined in the contract | [worker-nestjs/src/worker.service.ts:32](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L32) |
-| <a id="urls"></a> `urls` | `ConnectionUrl`[] | AMQP broker URL(s). Multiple URLs provide failover support | [worker-nestjs/src/worker.service.ts:34](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.service.ts#L34) |
+| <a id="connectionoptions"></a> `connectionOptions?` | `AmqpConnectionManagerOptions` | Optional connection configuration (heartbeat, reconnect settings, etc.) | [worker-nestjs/src/worker.service.ts:36](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L36) |
+| <a id="contract"></a> `contract` | `TContract` | The AMQP contract definition specifying consumers and their message schemas | [worker-nestjs/src/worker.service.ts:30](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L30) |
+| <a id="handlers"></a> `handlers` | [`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\> | Message handlers for each consumer defined in the contract | [worker-nestjs/src/worker.service.ts:32](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L32) |
+| <a id="urls"></a> `urls` | `ConnectionUrl`[] | AMQP broker URL(s). Multiple URLs provide failover support | [worker-nestjs/src/worker.service.ts:34](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.service.ts#L34) |
 
 ***
 
-### WorkerInferConsumerHandler()
+### WorkerInferConsumerHandlers
 
 ```ts
-type WorkerInferConsumerHandler<TContract, TName> = (message) => Promise<void>;
+type WorkerInferConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandlerEntry<TContract, K> };
 ```
 
-Defined in: worker/dist/index.d.mts:55
+Defined in: worker/dist/index.d.mts:84
 
-Infer consumer handler type for a specific consumer
+Infer all consumer handlers for a contract.
+Handlers can be either single-message handlers, batch handlers, or a tuple of [handler, options].
 
 #### Type Parameters
 
 | Type Parameter |
 | ------ |
 | `TContract` *extends* `ContractDefinition` |
-| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
 
-#### Parameters
+## Variables
 
-| Parameter | Type |
-| ------ | ------ |
-| `message` | [`WorkerInferConsumerInput`](#workerinferconsumerinput)\<`TContract`, `TName`\> |
+### MODULE\_OPTIONS\_TOKEN
 
-#### Returns
+```ts
+const MODULE_OPTIONS_TOKEN: typeof MODULE_OPTIONS_TOKEN;
+```
 
-`Promise`\<`void`\>
+Defined in: [worker-nestjs/src/worker.module-definition.ts:5](https://github.com/btravers/amqp-contract/blob/8711ad20abb1d4e537ec473d43e85fac3ebd4d0b/packages/worker-nestjs/src/worker.module-definition.ts#L5)
 
-***
+Injection token for AMQP worker module options
+Used by NestJS DI system to inject configuration into AmqpWorkerService
 
-### WorkerInferConsumerHandlers
+## Functions
+
+### defineHandler()
+
+#### Call Signature
 
 ```ts
-type WorkerInferConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandler<TContract, K> };
+function defineHandler<TContract, TName>(
+   contract, 
+   consumerName, 
+handler): WorkerInferConsumerHandlerEntry<TContract, TName>;
 ```
 
-Defined in: worker/dist/index.d.mts:59
+Defined in: worker/dist/index.d.mts:323
 
-Infer all consumer handlers for a contract
+Define a type-safe handler for a specific consumer in a contract.
 
-#### Type Parameters
+This utility allows you to define handlers outside of the worker creation,
+providing better code organization and reusability.
 
-| Type Parameter |
-| ------ |
-| `TContract` *extends* `ContractDefinition` |
+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.
 
-### WorkerInferConsumerInput
+##### Type Parameters
 
-```ts
-type WorkerInferConsumerInput<TContract, TName> = ConsumerInferInput<InferConsumer<TContract, TName>>;
-```
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+| `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
 
-Defined in: worker/dist/index.d.mts:51
+##### Parameters
 
-Worker perspective types - for consuming messages
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumer |
+| `consumerName` | `TName` | The name of the consumer from the contract |
+| `handler` | `WorkerInferConsumerHandler`\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
 
-#### Type Parameters
+##### Returns
 
-| Type Parameter |
-| ------ |
-| `TContract` *extends* `ContractDefinition` |
-| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+`WorkerInferConsumerHandlerEntry`\<`TContract`, `TName`\>
 
-## Variables
+A type-safe handler that can be used with TypedAmqpWorker
 
-### MODULE\_OPTIONS\_TOKEN
+##### Example
 
-```ts
-const MODULE_OPTIONS_TOKEN: typeof MODULE_OPTIONS_TOKEN;
-```
+```typescript
+import { defineHandler } from '@amqp-contract/worker';
+import { orderContract } from './contract';
 
-Defined in: [worker-nestjs/src/worker.module-definition.ts:5](https://github.com/btravers/amqp-contract/blob/6a6c658de853e244d99f97019419401bb9a8d86d/packages/worker-nestjs/src/worker.module-definition.ts#L5)
+// Simple single-message handler without options
+const processOrderHandler = defineHandler(
+  orderContract,
+  'processOrder',
+  async (message) => {
+    console.log('Processing order:', message.orderId);
+    await processPayment(message);
+  }
+);
 
-Injection token for AMQP worker module options
-Used by NestJS DI system to inject configuration into AmqpWorkerService
+// Single-message handler with prefetch
+const processOrderWithPrefetch = defineHandler(
+  orderContract,
+  'processOrder',
+  async (message) => {
+    await processOrder(message);
+  },
+  { prefetch: 10 }
+);
 
-## Functions
+// 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 }
+);
+```
 
-### defineHandler()
+#### Call Signature
 
 ```ts
 function defineHandler<TContract, TName>(
    contract, 
    consumerName, 
-handler): WorkerInferConsumerHandler<TContract, TName>;
+   handler, 
+options): WorkerInferConsumerHandlerEntry<TContract, TName>;
 ```
 
-Defined in: worker/dist/index.d.mts:276
+Defined in: worker/dist/index.d.mts:324
 
 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`\<`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
+##### Returns
 
-[`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\>
+`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: worker/dist/index.d.mts:329
+
+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`\<`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`\<`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 }
 );
 
-// Compose handlers
-const worker = await TypedAmqpWorker.create({
-  contract: orderContract,
-  handlers: {
-    processOrder: processOrderHandler,
-    notifyOrder: notifyOrderHandler,
+// Batch handler - MUST include batchSize
+const processBatchOrders = defineHandler(
+  orderContract,
+  'processOrders',
+  async (messages) => {
+    // messages is an array - batchSize configuration is REQUIRED
+    await db.insertMany(messages);
   },
-  connection: 'amqp://localhost',
-});
+  { batchSize: 5, batchTimeout: 1000 }
+);
 ```
 
 ***
@@ -505,7 +626,7 @@ const worker = await TypedAmqpWorker.create({
 function defineHandlers<TContract>(contract, handlers): WorkerInferConsumerHandlers<TContract>;
 ```
 
-Defined in: worker/dist/index.d.mts:333
+Defined in: worker/dist/index.d.mts:390
 
 Define multiple type-safe handlers for consumers in a contract.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amqp-contract/worker-nestjs",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "NestJS integration for @amqp-contract/worker",
   "keywords": [
     "amqp",
@@ -43,11 +43,13 @@
     "docs"
   ],
   "dependencies": {
-    "@amqp-contract/contract": "0.4.0",
-    "@amqp-contract/worker": "0.4.0"
+    "@amqp-contract/contract": "0.6.0",
+    "@amqp-contract/worker": "0.6.0"
   },
   "devDependencies": {
     "@nestjs/common": "11.1.10",
+    "@nestjs/core": "11.1.10",
+    "@nestjs/testing": "11.1.10",
     "@swan-io/boxed": "3.2.1",
     "@types/node": "25.0.3",
     "@vitest/coverage-v8": "4.0.16",
@@ -55,12 +57,13 @@
     "amqplib": "0.10.9",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2",
-    "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/testing": "0.6.0",
     "@amqp-contract/tsconfig": "0.0.0",
     "@amqp-contract/typedoc": "0.0.1"
   },
@@ -75,6 +78,7 @@
     "build:docs": "typedoc",
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
     "test:watch": "vitest --project unit",
     "typecheck": "tsc --noEmit"
   }