@amqp-contract/worker 0.1.4 → 0.2.1

package/README.md

@@ -1,6 +1,12 @@
 # @amqp-contract/worker
 
-Type-safe AMQP worker for consuming messages using amqp-contract with standard async/await error handling.
+**Type-safe AMQP worker for consuming messages using amqp-contract with standard async/await error handling.**
+
+[![CI](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@amqp-contract/worker.svg?logo=npm)](https://www.npmjs.com/package/@amqp-contract/worker)
+[![npm downloads](https://img.shields.io/npm/dm/@amqp-contract/worker.svg)](https://www.npmjs.com/package/@amqp-contract/worker)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 📖 **[Full documentation →](https://btravers.github.io/amqp-contract/api/worker)**
 
@@ -39,6 +45,10 @@ const worker = await TypedAmqpWorker.create({
 // await worker.close();
 ```
 
+## 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.
+
 ## Error Handling
 
 Worker handlers use standard Promise-based async/await pattern:
@@ -70,61 +80,11 @@ These errors are logged but **handlers don't need to use them** - just throw sta
 
 ## API
 
-### `TypedAmqpWorker.create(options)`
-
-Create a type-safe AMQP worker from a contract with message handlers. Automatically connects and starts consuming all messages.
-
-**Parameters:**
-
-- `options.contract` - Contract definition
-- `options.handlers` - Object with async handler functions for each consumer
-- `options.connection` - AMQP connection URL (string) or connection options (Options.Connect)
-
-**Returns:** `Promise<TypedAmqpWorker>`
-
-**Example:**
-
-```typescript
-const worker = await TypedAmqpWorker.create({
-  contract,
-  handlers: {
-    // Each handler receives type-checked message
-    processOrder: async (message) => {
-      // message.orderId is type-checked
-      console.log(message.orderId);
-    },
-    processPayment: async (message) => {
-      // Different message type for this consumer
-      await handlePayment(message);
-    },
-  },
-  connection: {
-    hostname: 'localhost',
-    port: 5672,
-    username: 'guest',
-    password: 'guest',
-  },
-});
-```
-
-### Handler Signature
-
-```typescript
-type Handler<T> = (message: T) => Promise<void>
-```
-
-Handlers are simple async functions that:
-
-- Receive type-checked message as parameter
-- Return `Promise<void>`
-- Can throw exceptions (message will be requeued)
-- Message is acknowledged automatically on success
-
-### `TypedAmqpWorker.close()`
+See the [Worker API documentation](https://btravers.github.io/amqp-contract/api/worker) for complete API reference.
 
-Stop consuming and close the channel and connection.
+## Documentation
 
-**Returns:** `Promise<void>`
+📖 **[Read the full documentation →](https://btravers.github.io/amqp-contract)**
 
 ## License
 

package/dist/index.cjs

@@ -1,4 +1,4 @@
-let amqplib = require("amqplib");
+let _amqp_contract_core = require("@amqp-contract/core");
 let _swan_io_boxed = require("@swan-io/boxed");
 
 //#region src/errors.ts
@@ -39,128 +39,296 @@ var MessageValidationError = class extends WorkerError {
 //#endregion
 //#region src/worker.ts
 /**
-* Type-safe AMQP worker for consuming messages
+* Type-safe AMQP worker for consuming messages from RabbitMQ.
+*
+* This class provides automatic message validation, connection management,
+* and error handling for consuming messages based on a contract definition.
+*
+* @typeParam TContract - The contract definition type
+*
+* @example
+* ```typescript
+* import { TypedAmqpWorker } from '@amqp-contract/worker';
+* import { z } from 'zod';
+*
+* const contract = defineContract({
+*   queues: {
+*     orderProcessing: defineQueue('order-processing', { durable: true })
+*   },
+*   consumers: {
+*     processOrder: defineConsumer('order-processing', z.object({
+*       orderId: z.string(),
+*       amount: z.number()
+*     }))
+*   }
+* });
+*
+* const worker = await TypedAmqpWorker.create({
+*   contract,
+*   handlers: {
+*     processOrder: async (message) => {
+*       console.log('Processing order', message.orderId);
+*       // Process the order...
+*     }
+*   },
+*   urls: ['amqp://localhost']
+* }).resultToPromise();
+*
+* // Close when done
+* await worker.close().resultToPromise();
+* ```
 */
 var TypedAmqpWorker = class TypedAmqpWorker {
-	channel = null;
-	connection = null;
-	consumerTags = [];
-	constructor(contract, handlers, connectionOptions) {
+	constructor(contract, amqpClient, handlers) {
 		this.contract = contract;
+		this.amqpClient = amqpClient;
 		this.handlers = handlers;
-		this.connectionOptions = connectionOptions;
 	}
 	/**
-	* Create a type-safe AMQP worker from a contract
-	* The worker will automatically connect and start consuming all messages
+	* Create a type-safe AMQP worker from a contract.
+	*
+	* Connection management (including automatic reconnection) is handled internally
+	* by amqp-connection-manager via the {@link AmqpClient}. The worker will set up
+	* consumers for all contract-defined handlers asynchronously in the background
+	* once the underlying connection and channels are ready.
+	*
+	* @param options - Configuration options for the worker
+	* @returns A Future that resolves to a Result containing the worker or an error
+	*
+	* @example
+	* ```typescript
+	* const workerResult = 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 async create(options) {
-		const worker = new TypedAmqpWorker(options.contract, options.handlers, options.connection);
-		await worker.init();
-		await worker.consumeAll();
-		return worker;
+	static create({ contract, handlers, urls, connectionOptions }) {
+		const worker = new TypedAmqpWorker(contract, new _amqp_contract_core.AmqpClient(contract, {
+			urls,
+			connectionOptions
+		}), handlers);
+		return worker.consumeAll().mapOk(() => worker);
 	}
 	/**
-	* Close the connection
+	* Close the AMQP channel and connection.
+	*
+	* This gracefully closes the connection to the AMQP broker,
+	* stopping all message consumption and cleaning up resources.
+	*
+	* @returns A Future that resolves to a Result indicating success or failure
+	*
+	* @example
+	* ```typescript
+	* const closeResult = await worker.close().resultToPromise();
+	* if (closeResult.isOk()) {
+	*   console.log('Worker closed successfully');
+	* }
+	* ```
 	*/
-	async close() {
-		await this.stopConsuming();
-		if (this.channel) {
-			await this.channel.close();
-			this.channel = null;
-		}
-		if (this.connection) {
-			await this.connection.close();
-			this.connection = null;
-		}
-	}
-	/**
-	* Connect to AMQP broker
-	*/
-	async init() {
-		this.connection = await (0, amqplib.connect)(this.connectionOptions);
-		this.channel = await this.connection.createChannel();
-		if (this.contract.exchanges) for (const exchange of Object.values(this.contract.exchanges)) await this.channel.assertExchange(exchange.name, exchange.type, {
-			durable: exchange.durable,
-			autoDelete: exchange.autoDelete,
-			internal: exchange.internal,
-			arguments: exchange.arguments
-		});
-		if (this.contract.queues) for (const queue of Object.values(this.contract.queues)) await this.channel.assertQueue(queue.name, {
-			durable: queue.durable,
-			exclusive: queue.exclusive,
-			autoDelete: queue.autoDelete,
-			arguments: queue.arguments
-		});
-		if (this.contract.bindings) {
-			for (const binding of Object.values(this.contract.bindings)) if (binding.type === "queue") await this.channel.bindQueue(binding.queue, binding.exchange, binding.routingKey ?? "", binding.arguments);
-			else if (binding.type === "exchange") await this.channel.bindExchange(binding.destination, binding.source, binding.routingKey ?? "", binding.arguments);
-		}
+	close() {
+		return _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
 	*/
-	async consumeAll() {
-		if (!this.contract.consumers) throw new Error("No consumers defined in contract");
+	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);
-		for (const consumerName of consumerNames) await this.consume(consumerName);
+		return _swan_io_boxed.Future.all(consumerNames.map((consumerName) => this.consume(consumerName))).map(_swan_io_boxed.Result.all).mapOk(() => void 0);
 	}
 	/**
 	* Start consuming messages for a specific consumer
 	*/
-	async consume(consumerName) {
-		if (!this.channel) throw new Error("Worker not initialized. Use TypedAmqpWorker.create() to obtain an initialized worker instance.");
+	consume(consumerName) {
 		const consumers = this.contract.consumers;
-		if (!consumers) throw new Error("No consumers defined in contract");
+		if (!consumers) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError("No consumers defined in contract")));
 		const consumer = consumers[consumerName];
-		if (!consumer || typeof consumer !== "object") {
+		if (!consumer) {
 			const availableConsumers = Object.keys(consumers);
 			const available = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
-			throw new Error(`Consumer not found: "${String(consumerName)}". Available consumers: ${available}`);
+			return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new TechnicalError(`Consumer not found: "${String(consumerName)}". Available consumers: ${available}`)));
 		}
-		const consumerDef = consumer;
 		const handler = this.handlers[consumerName];
-		if (!handler) throw new Error(`Handler for "${String(consumerName)}" not provided`);
-		if (consumerDef.prefetch !== void 0) await this.channel.prefetch(consumerDef.prefetch);
-		const result = await this.channel.consume(consumerDef.queue, async (msg) => {
-			if (!msg) return;
+		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) => {
 			const parseResult = _swan_io_boxed.Result.fromExecution(() => JSON.parse(msg.content.toString()));
 			if (parseResult.isError()) {
 				console.error(new TechnicalError(`Error parsing message for consumer "${String(consumerName)}"`, parseResult.error));
-				this.channel?.nack(msg, false, false);
-				return;
-			}
-			const content = parseResult.value;
-			const rawValidation = consumerDef.message["~standard"].validate(content);
-			const resolvedValidation = rawValidation instanceof Promise ? await rawValidation : rawValidation;
-			const validationResult = typeof resolvedValidation === "object" && resolvedValidation !== null && "issues" in resolvedValidation && resolvedValidation.issues ? _swan_io_boxed.Result.Error(new MessageValidationError(String(consumerName), resolvedValidation.issues)) : _swan_io_boxed.Result.Ok(typeof resolvedValidation === "object" && resolvedValidation !== null && "value" in resolvedValidation ? resolvedValidation.value : content);
-			if (validationResult.isError()) {
-				console.error(validationResult.error);
-				this.channel?.nack(msg, false, false);
+				this.amqpClient.channel.nack(msg, false, false);
 				return;
 			}
-			const validatedMessage = validationResult.value;
-			try {
-				await handler(validatedMessage);
-				if (!consumerDef.noAck) this.channel?.ack(msg);
-			} catch (error) {
+			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.Result.Ok(validationResult.value);
+			}).tapError((error) => {
+				console.error(error);
+				this.amqpClient.channel.nack(msg, false, false);
+			}).flatMapOk((validatedMessage) => _swan_io_boxed.Future.fromPromise(handler(validatedMessage)).tapError((error) => {
 				console.error(new TechnicalError(`Error processing message for consumer "${String(consumerName)}"`, error));
-				this.channel?.nack(msg, false, true);
-			}
-		}, { noAck: consumerDef.noAck ?? false });
-		this.consumerTags.push(result.consumerTag);
-	}
-	/**
-	* Stop consuming messages
-	*/
-	async stopConsuming() {
-		if (!this.channel) return;
-		for (const tag of this.consumerTags) await this.channel.cancel(tag);
-		this.consumerTags = [];
+				this.amqpClient.channel.nack(msg, false, true);
+			})).tapOk(() => {
+				this.amqpClient.channel.ack(msg);
+			}).toPromise();
+		})).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) {
+	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}`);
+	}
+	return handler;
+}
+/**
+* Define multiple type-safe handlers for consumers in a contract.
+*
+* This utility allows you to define all handlers at once outside of the worker creation,
+* ensuring type safety and providing better code organization.
+*
+* @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 { defineHandlers } from '@amqp-contract/worker';
+* 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',
+* });
+* ```
+*
+* @example
+* ```typescript
+* // Separate handler definitions for better organization
+* async function handleProcessOrder(message: WorkerInferConsumerInput<typeof orderContract, 'processOrder'>) {
+*   await processOrder(message);
+* }
+*
+* async function handleNotifyOrder(message: WorkerInferConsumerInput<typeof orderContract, 'notifyOrder'>) {
+*   await sendNotification(message);
+* }
+*
+* const handlers = defineHandlers(orderContract, {
+*   processOrder: handleProcessOrder,
+*   notifyOrder: handleNotifyOrder,
+* });
+* ```
+*/
+function defineHandlers(contract, handlers) {
+	const consumers = contract.consumers;
+	const availableConsumers = Object.keys(consumers ?? {});
+	const availableConsumerNames = availableConsumers.length > 0 ? availableConsumers.join(", ") : "none";
+	for (const handlerName of Object.keys(handlers)) if (!consumers || !(handlerName in consumers)) throw new Error(`Consumer "${handlerName}" not found in contract. Available consumers: ${availableConsumerNames}`);
+	return handlers;
+}
+
 //#endregion
 exports.MessageValidationError = MessageValidationError;
 exports.TechnicalError = TechnicalError;
-exports.TypedAmqpWorker = TypedAmqpWorker;
+exports.TypedAmqpWorker = TypedAmqpWorker;
+exports.defineHandler = defineHandler;
+exports.defineHandlers = defineHandlers;