@amqp-contract/worker 0.1.4 → 0.2.1

package/dist/index.d.cts

@@ -1,40 +1,188 @@
-import { Options } from "amqplib";
-import { ContractDefinition, WorkerInferConsumerHandlers } from "@amqp-contract/contract";
+import { ConsumerDefinition, ContractDefinition, InferConsumerNames } from "@amqp-contract/contract";
+import { Future, Result } from "@swan-io/boxed";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { AmqpConnectionManagerOptions, ConnectionUrl } from "amqp-connection-manager";
 
+//#region src/errors.d.ts
+/**
+ * Base error class for worker errors
+ */
+declare abstract class WorkerError extends Error {
+  protected constructor(message: string);
+}
+/**
+ * Error for technical/runtime failures in worker operations
+ * This includes validation failures, parsing failures, and processing failures
+ */
+declare class TechnicalError extends WorkerError {
+  readonly cause?: unknown | undefined;
+  constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Error thrown when message validation fails
+ */
+declare class MessageValidationError extends WorkerError {
+  readonly consumerName: string;
+  readonly issues: unknown;
+  constructor(consumerName: string, issues: unknown);
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Infer the TypeScript type from a schema
+ */
+type InferSchemaInput<TSchema extends StandardSchemaV1> = TSchema extends StandardSchemaV1<infer TInput> ? TInput : never;
+/**
+ * Infer consumer message input type
+ */
+type ConsumerInferInput<TConsumer extends ConsumerDefinition> = InferSchemaInput<TConsumer["message"]["payload"]>;
+/**
+ * Infer all consumers from contract
+ */
+type InferConsumers<TContract extends ContractDefinition> = NonNullable<TContract["consumers"]>;
+/**
+ * Get specific consumer definition from contract
+ */
+type InferConsumer<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = InferConsumers<TContract>[TName];
+/**
+ * Worker perspective types - for consuming messages
+ */
+type WorkerInferConsumerInput<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = ConsumerInferInput<InferConsumer<TContract, TName>>;
+/**
+ * Infer consumer handler type for a specific consumer
+ */
+type WorkerInferConsumerHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>> = (message: WorkerInferConsumerInput<TContract, TName>) => Promise<void>;
+/**
+ * Infer all consumer handlers for a contract
+ */
+type WorkerInferConsumerHandlers<TContract extends ContractDefinition> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandler<TContract, K> };
+//#endregion
 //#region src/worker.d.ts
-
 /**
- * Options for creating a worker
+ * Options for creating a type-safe AMQP worker.
+ *
+ * @typeParam TContract - The contract definition type
+ *
+ * @example
+ * ```typescript
+ * const options: CreateWorkerOptions<typeof contract> = {
+ *   contract: myContract,
+ *   handlers: {
+ *     processOrder: async (message) => {
+ *       console.log('Processing order:', message.orderId);
+ *     }
+ *   },
+ *   urls: ['amqp://localhost'],
+ *   connectionOptions: {
+ *     heartbeatIntervalInSeconds: 30
+ *   }
+ * };
+ * ```
  */
-interface CreateWorkerOptions<TContract extends ContractDefinition> {
+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: WorkerInferConsumerHandlers<TContract>;
-  connection: string | Options.Connect;
-}
+  /** AMQP broker URL(s). Multiple URLs provide failover support */
+  urls: ConnectionUrl[];
+  /** Optional connection configuration (heartbeat, reconnect settings, etc.) */
+  connectionOptions?: AmqpConnectionManagerOptions | undefined;
+};
 /**
- * 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();
+ * ```
  */
 declare class TypedAmqpWorker<TContract extends ContractDefinition> {
   private readonly contract;
+  private readonly amqpClient;
   private readonly handlers;
-  private readonly connectionOptions;
-  private channel;
-  private connection;
-  private consumerTags;
   private constructor();
   /**
-   * Create a type-safe AMQP worker from a contract
-   * The worker will automatically connect and start consuming all messages
-   */
-  static create<TContract extends ContractDefinition>(options: CreateWorkerOptions<TContract>): Promise<TypedAmqpWorker<TContract>>;
-  /**
-   * Close the connection
+   * 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);
+   * }
+   * ```
    */
-  close(): Promise<void>;
+  static create<TContract extends ContractDefinition>({
+    contract,
+    handlers,
+    urls,
+    connectionOptions
+  }: CreateWorkerOptions<TContract>): Future<Result<TypedAmqpWorker<TContract>, TechnicalError>>;
   /**
-   * Connect to AMQP broker
+   * 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');
+   * }
+   * ```
    */
-  private init;
+  close(): Future<Result<void, TechnicalError>>;
   /**
    * Start consuming messages for all consumers
    */
@@ -43,35 +191,136 @@ declare class TypedAmqpWorker<TContract extends ContractDefinition> {
    * Start consuming messages for a specific consumer
    */
   private consume;
-  /**
-   * Stop consuming messages
-   */
-  private stopConsuming;
 }
 //#endregion
-//#region src/errors.d.ts
-/**
- * Base error class for worker errors
- */
-declare abstract class WorkerError extends Error {
-  protected constructor(message: string);
-}
+//#region src/handlers.d.ts
 /**
- * Error for technical/runtime failures in worker operations
- * This includes validation failures, parsing failures, and processing failures
+ * 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',
+ * });
+ * ```
  */
-declare class TechnicalError extends WorkerError {
-  readonly cause?: unknown | undefined;
-  constructor(message: string, cause?: unknown | undefined);
-}
+declare function defineHandler<TContract extends ContractDefinition, TName extends InferConsumerNames<TContract>>(contract: TContract, consumerName: TName, handler: WorkerInferConsumerHandler<TContract, TName>): WorkerInferConsumerHandler<TContract, TName>;
 /**
- * Error thrown when message validation fails
+ * 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,
+ * });
+ * ```
  */
-declare class MessageValidationError extends WorkerError {
-  readonly consumerName: string;
-  readonly issues: unknown;
-  constructor(consumerName: string, issues: unknown);
-}
+declare function defineHandlers<TContract extends ContractDefinition>(contract: TContract, handlers: WorkerInferConsumerHandlers<TContract>): WorkerInferConsumerHandlers<TContract>;
 //#endregion
-export { type CreateWorkerOptions, MessageValidationError, TechnicalError, TypedAmqpWorker };
+export { type CreateWorkerOptions, MessageValidationError, TechnicalError, TypedAmqpWorker, type WorkerInferConsumerHandler, type WorkerInferConsumerHandlers, type WorkerInferConsumerInput, defineHandler, defineHandlers };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/worker.ts","../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;AAcA;AAAuD,UAAtC,mBAAsC,CAAA,kBAAA,kBAAA,CAAA,CAAA;EAC3C,QAAA,EAAA,SAAA;EAC4B,QAAA,EAA5B,2BAA4B,CAAA,SAAA,CAAA;EAA5B,UAAA,EAAA,MAAA,GACW,OAAA,CAAQ,OADnB;;;AAOZ;;AAewC,cAf3B,eAe2B,CAAA,kBAfO,kBAeP,CAAA,CAAA;EACP,iBAAA,QAAA;EAApB,iBAAA,QAAA;EACgB,iBAAA,iBAAA;EAAhB,QAAA,OAAA;EAAR,QAAA,UAAA;EAUY,QAAA,YAAA;EAAO,QAAA,WAAA,CAAA;;;;;EC7BX,OAAA,MAAA,CAAA,kBDiB2B,kBCjBO,CAAA,CAAA,OAAA,EDkBlC,mBClBkC,CDkBd,SClBc,CAAA,CAAA,EDmB1C,OCnB0C,CDmBlC,eCnBkC,CDmBlB,SCnBkB,CAAA,CAAA;EAalC;;;WDgBI;;;;;;;;;;;;;;;;;;;;;;;uBC/CF,WAAA,SAAoB,KAAA;EDWlB,UAAA,WAAA,CAAmB,OAAA,EAAA,MAAA;;;;;;AAGE,cCIzB,cAAA,SAAuB,WAAA,CDJE;EAMzB,SAAA,KAAA,CAAA,EAAA,OAAe,GAAA,SAAA;EAAmB,WAAA,CAAA,OAAA,EAAA,MAAA,EAAA,KAAA,CAAA,EAAA,OAAA,GAAA,SAAA;;;;;AAiBlC,cCNA,sBAAA,SAA+B,WAAA,CDM/B;EAAR,SAAA,YAAA,EAAA,MAAA;EAUY,SAAA,MAAA,EAAA,OAAA;EAAO,WAAA,CAAA,YAAA,EAAA,MAAA,EAAA,MAAA,EAAA,OAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts","../src/types.ts","../src/worker.ts","../src/handlers.ts"],"sourcesContent":[],"mappings":"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"}