alepha 0.9.4 → 0.9.5

package/queue.d.ts

@@ -115,17 +115,305 @@ interface NextMessage {
 //#endregion
 //#region src/descriptors/$queue.d.ts
 /**
- * Create a new queue.
+ * Creates a queue descriptor for asynchronous message processing with background workers.
+ *
+ * This descriptor provides a powerful message queue system that enables decoupled, asynchronous
+ * communication between different parts of your application. It supports multiple storage backends,
+ * type-safe message handling, and automatic worker processing with intelligent retry mechanisms.
+ *
+ * **Key Features**
+ *
+ * - **Type-Safe Messages**: Full TypeScript support with schema validation using TypeBox
+ * - **Multiple Storage Backends**: Support for in-memory, Redis, and custom queue providers
+ * - **Background Processing**: Automatic worker threads for message processing
+ * - **Reliable Delivery**: Built-in retry mechanisms and error handling
+ * - **Scalable Architecture**: Horizontal scaling support with distributed queue backends
+ * - **Dead Letter Queues**: Failed message handling with configurable retry policies
+ *
+ * **Use Cases**
+ *
+ * Perfect for decoupling application components and handling asynchronous tasks:
+ * - Background job processing
+ * - Email and notification sending
+ * - Image/file processing pipelines
+ * - Event-driven architectures
+ * - Microservice communication
+ * - Long-running data operations
+ *
+ * @example
+ * **Basic queue with automatic processing:**
+ * ```ts
+ * import { $queue } from "alepha/queue";
+ * import { t } from "alepha";
+ *
+ * class NotificationService {
+ *   emailQueue = $queue({
+ *     name: "email-notifications",
+ *     schema: t.object({
+ *       to: t.string(),
+ *       subject: t.string(),
+ *       body: t.string(),
+ *       priority: t.optional(t.enum(["high", "normal"]))
+ *     }),
+ *     handler: async (message) => {
+ *       // This runs in a background worker
+ *       await this.sendEmail(message.payload);
+ *       console.log(`Email sent to ${message.payload.to}`);
+ *     }
+ *   });
+ *
+ *   async sendWelcomeEmail(userEmail: string) {
+ *     // Push message to queue for background processing
+ *     await this.emailQueue.push({
+ *       to: userEmail,
+ *       subject: "Welcome to our platform!",
+ *       body: "Thank you for joining us...",
+ *       priority: "high"
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Batch processing with multiple messages:**
+ * ```ts
+ * class ImageProcessor {
+ *   imageQueue = $queue({
+ *     name: "image-processing",
+ *     description: "Process uploaded images for optimization and thumbnails",
+ *     schema: t.object({
+ *       imageId: t.string(),
+ *       originalUrl: t.string(),
+ *       userId: t.string(),
+ *       operations: t.array(t.union([
+ *         t.literal("resize"),
+ *         t.literal("compress"),
+ *         t.literal("thumbnail")
+ *       ]))
+ *     }),
+ *     handler: async (message) => {
+ *       const { imageId, originalUrl, operations } = message.payload;
+ *
+ *       for (const operation of operations) {
+ *         await this.processImage(imageId, originalUrl, operation);
+ *       }
+ *
+ *       console.log(`Processed image ${imageId} with operations: ${operations.join(", ")}`);
+ *     }
+ *   });
+ *
+ *   async processUploadedImages(images: Array<{id: string; url: string; userId: string}>) {
+ *     // Process multiple images in parallel
+ *     const messages = images.map(img => ({
+ *       imageId: img.id,
+ *       originalUrl: img.url,
+ *       userId: img.userId,
+ *       operations: ["resize", "compress", "thumbnail"] as const
+ *     }));
+ *
+ *     // Push all messages at once for efficient batch processing
+ *     await this.imageQueue.push(...messages);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Redis-backed queue for production scalability:**
+ * ```ts
+ * class OrderProcessor {
+ *   orderQueue = $queue({
+ *     name: "order-processing",
+ *     provider: RedisQueueProvider,  // Use Redis for distributed processing
+ *     schema: t.object({
+ *       orderId: t.string(),
+ *       customerId: t.string(),
+ *       items: t.array(t.object({
+ *         productId: t.string(),
+ *         quantity: t.number(),
+ *         price: t.number()
+ *       })),
+ *       paymentMethod: t.string(),
+ *       shippingAddress: t.object({
+ *         street: t.string(),
+ *         city: t.string(),
+ *         zipCode: t.string(),
+ *         country: t.string()
+ *       })
+ *     }),
+ *     handler: async (message) => {
+ *       const { orderId, customerId, items } = message.payload;
+ *
+ *       // Process payment
+ *       await this.processPayment(orderId, items);
+ *
+ *       // Update inventory
+ *       await this.updateInventory(items);
+ *
+ *       // Send confirmation email
+ *       await this.sendOrderConfirmation(customerId, orderId);
+ *
+ *       // Schedule shipping
+ *       await this.scheduleShipping(orderId, message.payload.shippingAddress);
+ *
+ *       console.log(`Order ${orderId} processed successfully`);
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Memory-only queue for development and testing:**
+ * ```ts
+ * class DevTaskProcessor {
+ *   taskQueue = $queue({
+ *     name: "dev-tasks",
+ *     provider: "memory",  // Use in-memory queue for development
+ *     schema: t.object({
+ *       taskType: t.enum(["cleanup", "backup", "report"]),
+ *       data: t.record(t.string(), t.any()),
+ *       scheduledAt: t.optional(t.string())
+ *     }),
+ *     handler: async (message) => {
+ *       const { taskType, data } = message.payload;
+ *
+ *       switch (taskType) {
+ *         case "cleanup":
+ *           await this.performCleanup(data);
+ *           break;
+ *         case "backup":
+ *           await this.createBackup(data);
+ *           break;
+ *         case "report":
+ *           await this.generateReport(data);
+ *           break;
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
  */
 declare const $queue: {
   <T extends TSchema>(options: QueueDescriptorOptions<T>): QueueDescriptor<T>;
   [KIND]: typeof QueueDescriptor;
 };
 interface QueueDescriptorOptions<T extends TSchema> {
+  /**
+   * Unique name for the queue.
+   *
+   * This name is used for:
+   * - Queue identification across the system
+   * - Storage backend key generation
+   * - Logging and monitoring
+   * - Worker assignment and routing
+   *
+   * If not provided, defaults to the property key where the queue is declared.
+   *
+   * @example "email-notifications"
+   * @example "image-processing"
+   * @example "order-fulfillment"
+   */
   name?: string;
+  /**
+   * Human-readable description of the queue's purpose.
+   *
+   * Used for:
+   * - Documentation generation
+   * - Monitoring dashboards
+   * - Development team communication
+   * - Queue management interfaces
+   *
+   * @example "Process user registration emails and welcome sequences"
+   * @example "Handle image uploads, resizing, and thumbnail generation"
+   * @example "Manage order processing, payment, and shipping workflows"
+   */
   description?: string;
+  /**
+   * Queue storage provider configuration.
+   *
+   * Options:
+   * - **"memory"**: In-memory queue (default for development, lost on restart)
+   * - **Service<QueueProvider>**: Custom provider class (e.g., RedisQueueProvider)
+   * - **undefined**: Uses the default queue provider from dependency injection
+   *
+   * **Provider Selection Guidelines**:
+   * - Development: Use "memory" for fast, simple testing
+   * - Production: Use Redis or database-backed providers for persistence
+   * - High-throughput: Use specialized providers with connection pooling
+   * - Distributed systems: Use Redis or message brokers for scalability
+   *
+   * @default Uses injected QueueProvider
+   * @example "memory"
+   * @example RedisQueueProvider
+   * @example DatabaseQueueProvider
+   */
   provider?: "memory" | Service<QueueProvider>;
+  /**
+   * TypeBox schema defining the structure of messages in this queue.
+   *
+   * This schema:
+   * - Validates all messages pushed to the queue
+   * - Provides full TypeScript type inference
+   * - Ensures type safety between producers and consumers
+   * - Enables automatic serialization/deserialization
+   *
+   * **Schema Design Best Practices**:
+   * - Keep schemas simple and focused on the specific task
+   * - Use optional fields for data that might not always be available
+   * - Include version fields for schema evolution
+   * - Use union types for different message types in the same queue
+   *
+   * @example
+   * ```ts
+   * t.object({
+   *   userId: t.string(),
+   *   action: t.enum(["create", "update"]),
+   *   data: t.record(t.string(), t.any()),
+   *   timestamp: t.optional(t.number())
+   * })
+   * ```
+   */
   schema: T;
+  /**
+   * Message handler function that processes queue messages.
+   *
+   * This function:
+   * - Runs in background worker threads for non-blocking processing
+   * - Receives type-safe message payloads based on the schema
+   * - Should be idempotent to handle potential retries
+   * - Can throw errors to trigger retry mechanisms
+   * - Has access to the full Alepha dependency injection container
+   *
+   * **Handler Best Practices**:
+   * - Keep handlers focused on a single responsibility
+   * - Use proper error handling and logging
+   * - Make operations idempotent when possible
+   * - Validate critical business logic within handlers
+   * - Consider using transactions for data consistency
+   *
+   * @param message - The queue message with validated payload
+   * @returns Promise that resolves when processing is complete
+   *
+   * @example
+   * ```ts
+   * handler: async (message) => {
+   *   const { userId, email, template } = message.payload;
+   *
+   *   try {
+   *     await this.emailService.send({
+   *       to: email,
+   *       template,
+   *       data: { userId }
+   *     });
+   *
+   *     await this.userService.markEmailSent(userId, template);
+   *   } catch (error) {
+   *     // Log error and let the queue system handle retries
+   *     this.logger.error(`Failed to send email to ${email}`, error);
+   *     throw error;
+   *   }
+   * }
+   * ```
+   */
   handler?: (message: QueueMessage<T>) => Promise<void>;
 }
 declare class QueueDescriptor<T extends TSchema> extends Descriptor<QueueDescriptorOptions<T>> {
@@ -145,14 +433,375 @@ interface QueueMessage<T extends TSchema> {
 //#endregion
 //#region src/descriptors/$consumer.d.ts
 /**
- * Consumer descriptor.
+ * Creates a consumer descriptor to process messages from a specific queue.
+ *
+ * This descriptor creates a dedicated message consumer that connects to a queue and processes
+ * its messages using a custom handler function. Consumers provide a clean way to separate
+ * message production from consumption, enabling scalable architectures where multiple
+ * consumers can process messages from the same queue.
+ *
+ * **Key Features**
+ *
+ * - **Queue Integration**: Seamlessly connects to any $queue descriptor
+ * - **Type Safety**: Full TypeScript support inherited from the connected queue's schema
+ * - **Dedicated Processing**: Isolated message processing logic separate from the queue
+ * - **Worker Management**: Automatic integration with the worker system for background processing
+ * - **Error Handling**: Built-in error handling and retry mechanisms from the queue system
+ * - **Scalability**: Multiple consumers can process the same queue for horizontal scaling
+ *
+ * **Use Cases**
+ *
+ * Perfect for creating specialized message processors:
+ * - Dedicated email sending services
+ * - Image processing workers
+ * - Data synchronization tasks
+ * - Event handlers for specific domains
+ * - Microservice message consumers
+ * - Background job processors
+ *
+ * @example
+ * **Basic consumer setup:**
+ * ```ts
+ * import { $queue, $consumer } from "alepha/queue";
+ * import { t } from "alepha";
+ *
+ * class EmailService {
+ *   // Define the queue
+ *   emailQueue = $queue({
+ *     name: "emails",
+ *     schema: t.object({
+ *       to: t.string(),
+ *       subject: t.string(),
+ *       body: t.string(),
+ *       template: t.optional(t.string())
+ *     })
+ *   });
+ *
+ *   // Create a dedicated consumer for this queue
+ *   emailConsumer = $consumer({
+ *     queue: this.emailQueue,
+ *     handler: async (message) => {
+ *       const { to, subject, body, template } = message.payload;
+ *
+ *       if (template) {
+ *         await this.sendTemplatedEmail(to, template, { subject, body });
+ *       } else {
+ *         await this.sendPlainEmail(to, subject, body);
+ *       }
+ *
+ *       console.log(`Email sent to ${to}: ${subject}`);
+ *     }
+ *   });
+ *
+ *   async sendWelcomeEmail(userEmail: string) {
+ *     // Push to queue - consumer will automatically process it
+ *     await this.emailQueue.push({
+ *       to: userEmail,
+ *       subject: "Welcome!",
+ *       body: "Thanks for joining our platform.",
+ *       template: "welcome"
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Multiple specialized consumers for different message types:**
+ * ```ts
+ * class NotificationService {
+ *   notificationQueue = $queue({
+ *     name: "notifications",
+ *     schema: t.object({
+ *       type: t.enum(["email", "sms", "push"]),
+ *       recipient: t.string(),
+ *       message: t.string(),
+ *       metadata: t.optional(t.record(t.string(), t.any()))
+ *     })
+ *   });
+ *
+ *   // Email-specific consumer
+ *   emailConsumer = $consumer({
+ *     queue: this.notificationQueue,
+ *     handler: async (message) => {
+ *       if (message.payload.type === "email") {
+ *         await this.emailProvider.send({
+ *           to: message.payload.recipient,
+ *           subject: message.payload.metadata?.subject || "Notification",
+ *           body: message.payload.message
+ *         });
+ *       }
+ *     }
+ *   });
+ *
+ *   // SMS-specific consumer
+ *   smsConsumer = $consumer({
+ *     queue: this.notificationQueue,
+ *     handler: async (message) => {
+ *       if (message.payload.type === "sms") {
+ *         await this.smsProvider.send({
+ *           to: message.payload.recipient,
+ *           message: message.payload.message
+ *         });
+ *       }
+ *     }
+ *   });
+ *
+ *   // Push notification consumer
+ *   pushConsumer = $consumer({
+ *     queue: this.notificationQueue,
+ *     handler: async (message) => {
+ *       if (message.payload.type === "push") {
+ *         await this.pushProvider.send({
+ *           deviceToken: message.payload.recipient,
+ *           title: message.payload.metadata?.title || "Notification",
+ *           body: message.payload.message
+ *         });
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Consumer with advanced error handling and logging:**
+ * ```ts
+ * class OrderProcessor {
+ *   orderQueue = $queue({
+ *     name: "order-processing",
+ *     schema: t.object({
+ *       orderId: t.string(),
+ *       customerId: t.string(),
+ *       items: t.array(t.object({
+ *         productId: t.string(),
+ *         quantity: t.number(),
+ *         price: t.number()
+ *       }))
+ *     })
+ *   });
+ *
+ *   orderConsumer = $consumer({
+ *     queue: this.orderQueue,
+ *     handler: async (message) => {
+ *       const { orderId, customerId, items } = message.payload;
+ *
+ *       try {
+ *         // Log processing start
+ *         this.logger.info(`Processing order ${orderId} for customer ${customerId}`);
+ *
+ *         // Validate inventory
+ *         await this.validateInventory(items);
+ *
+ *         // Process payment
+ *         const paymentResult = await this.processPayment(orderId, items);
+ *         if (!paymentResult.success) {
+ *           throw new Error(`Payment failed: ${paymentResult.error}`);
+ *         }
+ *
+ *         // Update inventory
+ *         await this.updateInventory(items);
+ *
+ *         // Create shipment
+ *         await this.createShipment(orderId, customerId);
+ *
+ *         // Send confirmation
+ *         await this.sendOrderConfirmation(customerId, orderId);
+ *
+ *         this.logger.info(`Order ${orderId} processed successfully`);
+ *
+ *       } catch (error) {
+ *         // Log detailed error information
+ *         this.logger.error(`Failed to process order ${orderId}`, {
+ *           error: error.message,
+ *           orderId,
+ *           customerId,
+ *           itemCount: items.length
+ *         });
+ *
+ *         // Re-throw to trigger queue retry mechanism
+ *         throw error;
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Consumer for batch processing with performance optimization:**
+ * ```ts
+ * class DataProcessor {
+ *   dataQueue = $queue({
+ *     name: "data-processing",
+ *     schema: t.object({
+ *       batchId: t.string(),
+ *       records: t.array(t.object({
+ *         id: t.string(),
+ *         data: t.record(t.string(), t.any())
+ *       })),
+ *       processingOptions: t.object({
+ *         validateData: t.boolean(),
+ *         generateReport: t.boolean(),
+ *         notifyCompletion: t.boolean()
+ *       })
+ *     })
+ *   });
+ *
+ *   dataConsumer = $consumer({
+ *     queue: this.dataQueue,
+ *     handler: async (message) => {
+ *       const { batchId, records, processingOptions } = message.payload;
+ *       const startTime = Date.now();
+ *
+ *       this.logger.info(`Starting batch processing for ${batchId} with ${records.length} records`);
+ *
+ *       try {
+ *         // Process records in chunks for better performance
+ *         const chunkSize = 100;
+ *         const chunks = this.chunkArray(records, chunkSize);
+ *
+ *         for (let i = 0; i < chunks.length; i++) {
+ *           const chunk = chunks[i];
+ *
+ *           if (processingOptions.validateData) {
+ *             await this.validateChunk(chunk);
+ *           }
+ *
+ *           await this.processChunk(chunk);
+ *
+ *           // Log progress
+ *           const progress = ((i + 1) / chunks.length) * 100;
+ *           this.logger.debug(`Batch ${batchId} progress: ${progress.toFixed(1)}%`);
+ *         }
+ *
+ *         if (processingOptions.generateReport) {
+ *           await this.generateProcessingReport(batchId, records.length);
+ *         }
+ *
+ *         if (processingOptions.notifyCompletion) {
+ *           await this.notifyBatchCompletion(batchId);
+ *         }
+ *
+ *         const duration = Date.now() - startTime;
+ *         this.logger.info(`Batch ${batchId} completed in ${duration}ms`);
+ *
+ *       } catch (error) {
+ *         const duration = Date.now() - startTime;
+ *         this.logger.error(`Batch ${batchId} failed after ${duration}ms`, error);
+ *         throw error;
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
  */
 declare const $consumer: {
   <T extends TSchema>(options: ConsumerDescriptorOptions<T>): ConsumerDescriptor<T>;
   [KIND]: typeof ConsumerDescriptor;
 };
 interface ConsumerDescriptorOptions<T extends TSchema> {
+  /**
+   * The queue descriptor that this consumer will process messages from.
+   *
+   * This establishes the connection between the consumer and its source queue:
+   * - The consumer inherits the queue's message schema for type safety
+   * - Messages pushed to the queue will be automatically routed to this consumer
+   * - Multiple consumers can be attached to the same queue for parallel processing
+   * - The consumer will use the queue's provider and configuration settings
+   *
+   * **Queue Integration Benefits**:
+   * - Type safety: Consumer handler gets fully typed message payloads
+   * - Schema validation: Messages are validated before reaching the consumer
+   * - Error handling: Failed messages can be retried or moved to dead letter queues
+   * - Monitoring: Queue metrics include consumer processing statistics
+   *
+   * @example
+   * ```ts
+   * // First, define a queue
+   * emailQueue = $queue({
+   *   name: "emails",
+   *   schema: t.object({ to: t.string(), subject: t.string() })
+   * });
+   *
+   * // Then, create a consumer for that queue
+   * emailConsumer = $consumer({
+   *   queue: this.emailQueue,  // Reference the queue descriptor
+   *   handler: async (message) => { } // process email
+   * });
+   * ```
+   */
   queue: QueueDescriptor<T>;
+  /**
+   * Message handler function that processes individual messages from the queue.
+   *
+   * This function:
+   * - Receives fully typed and validated message payloads from the connected queue
+   * - Runs in the background worker system for non-blocking operation
+   * - Should implement the core business logic for processing this message type
+   * - Can throw errors to trigger the queue's retry mechanisms
+   * - Has access to the full Alepha dependency injection container
+   * - Should be idempotent to handle potential duplicate deliveries
+   *
+   * **Handler Design Guidelines**:
+   * - Keep handlers focused on a single responsibility
+   * - Use proper error handling and meaningful error messages
+   * - Log important processing steps for debugging and monitoring
+   * - Consider transaction boundaries for data consistency
+   * - Make operations idempotent when possible
+   * - Validate business rules within the handler logic
+   *
+   * **Error Handling Strategy**:
+   * - Throw errors for temporary failures that should be retried
+   * - Log and handle permanent failures gracefully
+   * - Use specific error types to control retry behavior
+   * - Consider implementing circuit breakers for external service calls
+   *
+   * @param message - The queue message containing the validated payload
+   * @param message.payload - The typed message data based on the queue's schema
+   * @returns Promise that resolves when processing is complete
+   *
+   * @example
+   * ```ts
+   * handler: async (message) => {
+   *   const { userId, action, data } = message.payload;
+   *
+   *   try {
+   *     // Log processing start
+   *     this.logger.info(`Processing ${action} for user ${userId}`);
+   *
+   *     // Validate business rules
+   *     if (!await this.userService.exists(userId)) {
+   *       throw new Error(`User ${userId} not found`);
+   *     }
+   *
+   *     // Perform the main processing logic
+   *     switch (action) {
+   *       case "create":
+   *         await this.processCreation(userId, data);
+   *         break;
+   *       case "update":
+   *         await this.processUpdate(userId, data);
+   *         break;
+   *       default:
+   *         throw new Error(`Unknown action: ${action}`);
+   *     }
+   *
+   *     // Log successful completion
+   *     this.logger.info(`Successfully processed ${action} for user ${userId}`);
+   *
+   *   } catch (error) {
+   *     // Log error with context
+   *     this.logger.error(`Failed to process ${action} for user ${userId}`, {
+   *       error: error.message,
+   *       userId,
+   *       action,
+   *       data
+   *     });
+   *
+   *     // Re-throw to trigger queue retry mechanism
+   *     throw error;
+   *   }
+   * }
+   * ```
+   */
   handler: (message: {
     payload: Static<T["payload"]>;
   }) => Promise<void>;