alepha 0.9.4 → 0.9.5

package/topic.d.ts

@@ -39,7 +39,246 @@ type UnSubscribeFn = () => Promise<void>;
 //#endregion
 //#region src/descriptors/$topic.d.ts
 /**
- * Create a new topic.
+ * Creates a topic descriptor for pub/sub messaging and event-driven architecture.
+ *
+ * This descriptor provides a powerful publish/subscribe system that enables decoupled communication
+ * between different parts of your application. Topics allow multiple publishers to send messages
+ * and multiple subscribers to receive them, creating flexible event-driven architectures with
+ * support for real-time messaging and asynchronous event processing.
+ *
+ * **Key Features**
+ *
+ * - **Publish/Subscribe Pattern**: Decoupled communication between publishers and subscribers
+ * - **Multiple Subscribers**: One-to-many message distribution with automatic fan-out
+ * - **Type-Safe Messages**: Full TypeScript support with schema validation using TypeBox
+ * - **Real-time Processing**: Immediate message delivery to active subscribers
+ * - **Event Filtering**: Subscribe to specific message types using filter functions
+ * - **Timeout Support**: Wait for specific messages with configurable timeouts
+ * - **Multiple Backends**: Support for in-memory, Redis, and custom topic providers
+ * - **Error Resilience**: Built-in error handling and message processing recovery
+ *
+ * **Use Cases**
+ *
+ * Perfect for event-driven architectures and real-time communication:
+ * - User activity notifications
+ * - Real-time chat and messaging systems
+ * - System event broadcasting
+ * - Microservice communication
+ * - Live data updates and synchronization
+ * - Application state change notifications
+ * - Webhook and external API event handling
+ *
+ * @example
+ * **Basic topic with publish/subscribe:**
+ * ```ts
+ * import { $topic } from "alepha/topic";
+ * import { t } from "alepha";
+ *
+ * class NotificationService {
+ *   userActivity = $topic({
+ *     name: "user-activity",
+ *     schema: {
+ *       payload: t.object({
+ *         userId: t.string(),
+ *         action: t.enum(["login", "logout", "purchase"]),
+ *         timestamp: t.number(),
+ *         metadata: t.optional(t.record(t.string(), t.any()))
+ *       })
+ *     },
+ *     handler: async (message) => {
+ *       // This subscriber runs automatically for all messages
+ *       console.log(`User ${message.payload.userId} performed ${message.payload.action}`);
+ *     }
+ *   });
+ *
+ *   async trackUserLogin(userId: string) {
+ *     // Publish event - all subscribers will receive it
+ *     await this.userActivity.publish({
+ *       userId,
+ *       action: "login",
+ *       timestamp: Date.now(),
+ *       metadata: { source: "web", ip: "192.168.1.1" }
+ *     });
+ *   }
+ *
+ *   async setupAdditionalSubscriber() {
+ *     // Add another subscriber dynamically
+ *     await this.userActivity.subscribe(async (message) => {
+ *       if (message.payload.action === "purchase") {
+ *         await this.sendPurchaseConfirmation(message.payload.userId);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Real-time chat system with multiple subscribers:**
+ * ```ts
+ * class ChatService {
+ *   messagesTopic = $topic({
+ *     name: "chat-messages",
+ *     description: "Real-time chat messages for all rooms",
+ *     schema: {
+ *       payload: t.object({
+ *         messageId: t.string(),
+ *         roomId: t.string(),
+ *         userId: t.string(),
+ *         content: t.string(),
+ *         timestamp: t.number(),
+ *         messageType: t.enum(["text", "image", "file"])
+ *       })
+ *     }
+ *   });
+ *
+ *   async sendMessage(roomId: string, userId: string, content: string) {
+ *     await this.messagesTopic.publish({
+ *       messageId: generateId(),
+ *       roomId,
+ *       userId,
+ *       content,
+ *       timestamp: Date.now(),
+ *       messageType: "text"
+ *     });
+ *   }
+ *
+ *   // Different services can subscribe to the same topic
+ *   async setupMessageLogging() {
+ *     await this.messagesTopic.subscribe(async (message) => {
+ *       // Log all messages for compliance
+ *       await this.auditLogger.log({
+ *         action: "message_sent",
+ *         roomId: message.payload.roomId,
+ *         userId: message.payload.userId,
+ *         timestamp: message.payload.timestamp
+ *       });
+ *     });
+ *   }
+ *
+ *   async setupNotificationService() {
+ *     await this.messagesTopic.subscribe(async (message) => {
+ *       // Send push notifications to offline users
+ *       const offlineUsers = await this.getOfflineUsersInRoom(message.payload.roomId);
+ *       await this.sendPushNotifications(offlineUsers, {
+ *         title: `New message in ${message.payload.roomId}`,
+ *         body: message.payload.content
+ *       });
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Event filtering and waiting for specific messages:**
+ * ```ts
+ * class OrderService {
+ *   orderEvents = $topic({
+ *     name: "order-events",
+ *     schema: {
+ *       payload: t.object({
+ *         orderId: t.string(),
+ *         status: t.union([
+ *           t.literal("created"),
+ *           t.literal("paid"),
+ *           t.literal("shipped"),
+ *           t.literal("delivered"),
+ *           t.literal("cancelled")
+ *         ]),
+ *         timestamp: t.number(),
+ *         data: t.optional(t.record(t.string(), t.any()))
+ *       })
+ *     }
+ *   });
+ *
+ *   async processOrder(orderId: string) {
+ *     // Publish order created event
+ *     await this.orderEvents.publish({
+ *       orderId,
+ *       status: "created",
+ *       timestamp: Date.now()
+ *     });
+ *
+ *     // Wait for payment confirmation with timeout
+ *     try {
+ *       const paymentEvent = await this.orderEvents.wait({
+ *         timeout: [5, "minutes"],
+ *         filter: (message) =>
+ *           message.payload.orderId === orderId &&
+ *           message.payload.status === "paid"
+ *       });
+ *
+ *       console.log(`Order ${orderId} was paid at ${paymentEvent.payload.timestamp}`);
+ *
+ *       // Continue with shipping...
+ *       await this.initiateShipping(orderId);
+ *
+ *     } catch (error) {
+ *       if (error instanceof TopicTimeoutError) {
+ *         console.log(`Payment timeout for order ${orderId}`);
+ *         await this.cancelOrder(orderId);
+ *       }
+ *     }
+ *   }
+ *
+ *   async setupOrderTracking() {
+ *     // Subscribe only to shipping events
+ *     await this.orderEvents.subscribe(async (message) => {
+ *       if (message.payload.status === "shipped") {
+ *         await this.updateTrackingInfo(message.payload.orderId, message.payload.data);
+ *         await this.notifyCustomer(message.payload.orderId, "Your order has shipped!");
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Redis-backed topic for distributed systems:**
+ * ```ts
+ * class DistributedEventSystem {
+ *   systemEvents = $topic({
+ *     name: "system-events",
+ *     provider: RedisTopicProvider,  // Use Redis for cross-service communication
+ *     schema: {
+ *       payload: t.object({
+ *         eventType: t.string(),
+ *         serviceId: t.string(),
+ *         data: t.record(t.string(), t.any()),
+ *         timestamp: t.number(),
+ *         correlationId: t.optional(t.string())
+ *       })
+ *     },
+ *     handler: async (message) => {
+ *       // Central event handler for all system events
+ *       await this.processSystemEvent(message.payload);
+ *     }
+ *   });
+ *
+ *   async publishServiceHealth(serviceId: string, healthy: boolean) {
+ *     await this.systemEvents.publish({
+ *       eventType: "service.health",
+ *       serviceId,
+ *       data: { healthy, checkedAt: new Date().toISOString() },
+ *       timestamp: Date.now()
+ *     });
+ *   }
+ *
+ *   async setupHealthMonitoring() {
+ *     await this.systemEvents.subscribe(async (message) => {
+ *       if (message.payload.eventType === "service.health") {
+ *         await this.updateServiceStatus(
+ *           message.payload.serviceId,
+ *           message.payload.data.healthy
+ *         );
+ *
+ *         if (!message.payload.data.healthy) {
+ *           await this.alertOnCall(`Service ${message.payload.serviceId} is down`);
+ *         }
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
  */
 declare const $topic: {
   <T extends TopicMessageSchema>(options: TopicDescriptorOptions<T>): TopicDescriptor<T>;
@@ -47,29 +286,176 @@ declare const $topic: {
 };
 interface TopicDescriptorOptions<T extends TopicMessageSchema> {
   /**
-   * Topic key.
+   * Unique name identifier for the topic.
+   *
+   * This name is used for:
+   * - Topic identification across the pub/sub system
+   * - Message routing between publishers and subscribers
+   * - Logging and debugging topic-related operations
+   * - Provider-specific topic management (channels, keys, etc.)
    *
-   * If not provided, the propertyKey is used as the topic name.
+   * If not provided, defaults to the property key where the topic is declared.
+   *
+   * **Naming Conventions**:
+   * - Use descriptive, hierarchical names: "user.activity", "order.events"
+   * - Avoid spaces and special characters
+   * - Consider using dot notation for categorization
+   * - Keep names concise but meaningful
+   *
+   * @example "user-activity"
+   * @example "chat.messages"
+   * @example "system.health.checks"
+   * @example "payment.webhooks"
    */
   name?: string;
   /**
-   * Describe the topic. For documentation purposes.
+   * Human-readable description of the topic's purpose and usage.
+   *
+   * Used for:
+   * - Documentation generation and API references
+   * - Developer onboarding and understanding
+   * - Monitoring dashboards and admin interfaces
+   * - Team communication about system architecture
+   *
+   * **Description Best Practices**:
+   * - Explain what events/messages this topic handles
+   * - Mention key use cases and subscribers
+   * - Include any important timing or ordering guarantees
+   * - Note any special processing requirements
+   *
+   * @example "Real-time user activity events for analytics and notifications"
+   * @example "Order lifecycle events from creation to delivery"
+   * @example "Chat messages broadcast to all room participants"
+   * @example "System health checks and service status updates"
    */
   description?: string;
   /**
-   * Override the default topic provider.
+   * Topic provider configuration for message storage and delivery.
+   *
+   * Options:
+   * - **"memory"**: In-memory provider (default for development, lost on restart)
+   * - **Service<TopicProvider>**: Custom provider class (e.g., RedisTopicProvider)
+   * - **undefined**: Uses the default topic provider from dependency injection
+   *
+   * **Provider Selection Guidelines**:
+   * - **Development**: Use "memory" for fast, simple testing without external dependencies
+   * - **Production**: Use Redis or message brokers for persistence and scalability
+   * - **Distributed systems**: Use Redis/RabbitMQ for cross-service communication
+   * - **High-throughput**: Use specialized providers with connection pooling
+   * - **Real-time**: Ensure provider supports low-latency message delivery
    *
-   * If not provided, the default provider is used.
-   * If "memory" is provided, the default in-memory provider is used.
-   * If a class is provided, it must extend `TopicProvider`.
+   * **Provider Capabilities**:
+   * - Message persistence and durability
+   * - Subscriber management and connection handling
+   * - Message ordering and delivery guarantees
+   * - Horizontal scaling and load distribution
+   *
+   * @default Uses injected TopicProvider
+   * @example "memory"
+   * @example RedisTopicProvider
+   * @example RabbitMQTopicProvider
    */
   provider?: "memory" | Service<TopicProvider>;
   /**
-   * Topic message schema.
+   * TypeBox schema defining the structure of messages published to this topic.
+   *
+   * The schema must include:
+   * - **payload**: Required schema for the main message data
+   * - **headers**: Optional schema for message metadata
+   *
+   * This schema:
+   * - Validates all messages published to the topic
+   * - Provides full TypeScript type inference for subscribers
+   * - Ensures type safety between publishers and subscribers
+   * - Enables automatic serialization/deserialization
+   *
+   * **Schema Design Best Practices**:
+   * - Keep payload schemas focused and cohesive
+   * - Use optional fields for data that might not always be present
+   * - Include timestamp fields for event ordering
+   * - Consider versioning for schema evolution
+   * - Use union types for different event types in the same topic
+   *
+   * @example
+   * ```ts
+   * {
+   *   payload: t.object({
+   *     eventId: t.string(),
+   *     eventType: t.enum(["created", "updated"]),
+   *     data: t.record(t.string(), t.any()),
+   *     timestamp: t.number(),
+   *     userId: t.optional(t.string())
+   *   }),
+   *   headers: t.optional(t.object({
+   *     source: t.string(),
+   *     correlationId: t.string()
+   *   }))
+   * }
+   * ```
    */
   schema: T;
   /**
-   * Add a subscriber handler.
+   * Default subscriber handler function that processes messages published to this topic.
+   *
+   * This handler:
+   * - Automatically subscribes when the topic is initialized
+   * - Receives all messages published to the topic
+   * - Runs for every message without additional subscription setup
+   * - Can be supplemented with additional subscribers via `subscribe()` method
+   * - Should handle errors gracefully to avoid breaking other subscribers
+   *
+   * **Handler Design Guidelines**:
+   * - Keep handlers focused on a single responsibility
+   * - Use proper error handling and logging
+   * - Consider performance impact for high-frequency topics
+   * - Make handlers idempotent when possible
+   * - Validate business rules within the handler logic
+   * - Log important processing steps for debugging
+   *
+   * **Error Handling Strategy**:
+   * - Log errors but don't re-throw to avoid affecting other subscribers
+   * - Use try-catch blocks for external service calls
+   * - Consider implementing circuit breakers for resilience
+   * - Monitor error rates and patterns for system health
+   *
+   * @param message - The topic message with validated payload and headers
+   * @param message.payload - The typed message data based on the schema
+   * @returns Promise that resolves when processing is complete
+   *
+   * @example
+   * ```ts
+   * handler: async (message) => {
+   *   const { eventType, data, timestamp } = message.payload;
+   *
+   *   try {
+   *     // Log message receipt
+   *     this.logger.info(`Processing ${eventType} event`, { timestamp, data });
+   *
+   *     // Process based on event type
+   *     switch (eventType) {
+   *       case "created":
+   *         await this.handleCreation(data);
+   *         break;
+   *       case "updated":
+   *         await this.handleUpdate(data);
+   *         break;
+   *       default:
+   *         this.logger.warn(`Unknown event type: ${eventType}`);
+   *     }
+   *
+   *     this.logger.info(`Successfully processed ${eventType} event`);
+   *
+   *   } catch (error) {
+   *     // Log error but don't re-throw to avoid affecting other subscribers
+   *     this.logger.error(`Failed to process ${eventType} event`, {
+   *       error: error.message,
+   *       eventType,
+   *       timestamp,
+   *       data
+   *     });
+   *   }
+   * }
+   * ```
    */
   handler?: TopicHandler<T>;
 }
@@ -101,14 +487,420 @@ type TopicHandler<T extends TopicMessageSchema = TopicMessageSchema> = (message:
 //#endregion
 //#region src/descriptors/$subscriber.d.ts
 /**
- * Subscribe to a $topic.
+ * Creates a subscriber descriptor to listen for messages from a specific topic.
+ *
+ * This descriptor creates a dedicated message subscriber that connects to a topic and processes
+ * its messages using a custom handler function. Subscribers provide a clean way to separate
+ * message publishing from consumption, enabling scalable pub/sub architectures where multiple
+ * subscribers can react to the same events independently.
+ *
+ * ## Key Features
+ *
+ * - **Topic Integration**: Seamlessly connects to any $topic descriptor
+ * - **Type Safety**: Full TypeScript support inherited from the connected topic's schema
+ * - **Dedicated Processing**: Isolated message processing logic separate from the topic
+ * - **Real-time Processing**: Immediate message delivery when events are published
+ * - **Error Isolation**: Subscriber errors don't affect other subscribers or the topic
+ * - **Scalability**: Multiple subscribers can listen to the same topic independently
+ *
+ * ## Use Cases
+ *
+ * Perfect for creating specialized event handlers:
+ * - Notification services for user events
+ * - Analytics and logging systems
+ * - Data synchronization between services
+ * - Real-time UI updates
+ * - Event-driven workflow triggers
+ * - Audit and compliance logging
+ *
+ * @example
+ * **Basic subscriber setup:**
+ * ```ts
+ * import { $topic, $subscriber } from "alepha/topic";
+ * import { t } from "alepha";
+ *
+ * class UserActivityService {
+ *   // Define the topic
+ *   userEvents = $topic({
+ *     name: "user-activity",
+ *     schema: {
+ *       payload: t.object({
+ *         userId: t.string(),
+ *         action: t.enum(["login", "logout", "purchase"]),
+ *         timestamp: t.number(),
+ *         metadata: t.optional(t.record(t.string(), t.any()))
+ *       })
+ *     }
+ *   });
+ *
+ *   // Create a dedicated subscriber for this topic
+ *   activityLogger = $subscriber({
+ *     topic: this.userEvents,
+ *     handler: async (message) => {
+ *       const { userId, action, timestamp } = message.payload;
+ *
+ *       await this.auditLogger.log({
+ *         event: 'user_activity',
+ *         userId,
+ *         action,
+ *         timestamp,
+ *         source: 'user-activity-topic'
+ *       });
+ *
+ *       this.log.info(`User ${userId} performed ${action} at ${new Date(timestamp).toISOString()}`);
+ *     }
+ *   });
+ *
+ *   async trackUserLogin(userId: string, metadata: Record<string, any>) {
+ *     // Publish to topic - subscriber will automatically process it
+ *     await this.userEvents.publish({
+ *       userId,
+ *       action: "login",
+ *       timestamp: Date.now(),
+ *       metadata
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Multiple specialized subscribers for different concerns:**
+ * ```ts
+ * class OrderEventHandlers {
+ *   orderEvents = $topic({
+ *     name: "order-events",
+ *     schema: {
+ *       payload: t.object({
+ *         orderId: t.string(),
+ *         customerId: t.string(),
+ *         status: t.union([
+ *           t.literal("created"),
+ *           t.literal("paid"),
+ *           t.literal("shipped"),
+ *           t.literal("delivered")
+ *         ]),
+ *         data: t.optional(t.record(t.string(), t.any()))
+ *       })
+ *     }
+ *   });
+ *
+ *   // Analytics subscriber
+ *   analyticsSubscriber = $subscriber({
+ *     topic: this.orderEvents,
+ *     handler: async (message) => {
+ *       await this.analytics.track('order_status_changed', {
+ *         orderId: message.payload.orderId,
+ *         customerId: message.payload.customerId,
+ *         status: message.payload.status,
+ *         timestamp: Date.now()
+ *       });
+ *     }
+ *   });
+ *
+ *   // Email notification subscriber
+ *   emailSubscriber = $subscriber({
+ *     topic: this.orderEvents,
+ *     handler: async (message) => {
+ *       const { customerId, orderId, status } = message.payload;
+ *
+ *       const templates = {
+ *         'paid': 'order-confirmation',
+ *         'shipped': 'order-shipped',
+ *         'delivered': 'order-delivered'
+ *       };
+ *
+ *       const template = templates[status];
+ *       if (template) {
+ *         await this.emailService.send({
+ *           customerId,
+ *           template,
+ *           data: { orderId, status }
+ *         });
+ *       }
+ *     }
+ *   });
+ *
+ *   // Inventory management subscriber
+ *   inventorySubscriber = $subscriber({
+ *     topic: this.orderEvents,
+ *     handler: async (message) => {
+ *       if (message.payload.status === 'paid') {
+ *         await this.inventoryService.reserveItems(message.payload.orderId);
+ *       } else if (message.payload.status === 'delivered') {
+ *         await this.inventoryService.confirmDelivery(message.payload.orderId);
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Subscriber with advanced error handling and filtering:**
+ * ```ts
+ * class NotificationSubscriber {
+ *   systemEvents = $topic({
+ *     name: "system-events",
+ *     schema: {
+ *       payload: t.object({
+ *         eventType: t.string(),
+ *         severity: t.enum(["info", "warning", "error"]),
+ *         serviceId: t.string(),
+ *         message: t.string(),
+ *         data: t.optional(t.record(t.string(), t.any()))
+ *       })
+ *     }
+ *   });
+ *
+ *   alertSubscriber = $subscriber({
+ *     topic: this.systemEvents,
+ *     handler: async (message) => {
+ *       const { eventType, severity, serviceId, message: eventMessage, data } = message.payload;
+ *
+ *       try {
+ *         // Only process error events for alerting
+ *         if (severity !== 'error') {
+ *           return;
+ *         }
+ *
+ *         // Log the event
+ *         this.logger.error(`System alert from ${serviceId}`, {
+ *           eventType,
+ *           message: eventMessage,
+ *           data
+ *         });
+ *
+ *         // Send alerts based on service criticality
+ *         const criticalServices = ['payment', 'auth', 'database'];
+ *         const isCritical = criticalServices.includes(serviceId);
+ *
+ *         if (isCritical) {
+ *           // Immediate alert for critical services
+ *           await this.alertService.sendImmediate({
+ *             title: `Critical Error in ${serviceId}`,
+ *             message: eventMessage,
+ *             severity: 'critical',
+ *             metadata: { eventType, serviceId, data }
+ *           });
+ *         } else {
+ *           // Queue non-critical alerts for batching
+ *           await this.alertService.queueAlert({
+ *             title: `Error in ${serviceId}`,
+ *             message: eventMessage,
+ *             severity: 'error',
+ *             metadata: { eventType, serviceId, data }
+ *           });
+ *         }
+ *
+ *         // Update service health status
+ *         await this.healthMonitor.recordError(serviceId, eventType);
+ *
+ *       } catch (error) {
+ *         // Log subscriber errors but don't re-throw
+ *         // This prevents one failing subscriber from affecting others
+ *         this.log.error(`Alert subscriber failed`, {
+ *           originalEvent: { eventType, serviceId, severity },
+ *           subscriberError: error.message
+ *         });
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Subscriber for real-time data aggregation:**
+ * ```ts
+ * class MetricsAggregator {
+ *   userActivityTopic = $topic({
+ *     name: "user-metrics",
+ *     schema: {
+ *       payload: t.object({
+ *         userId: t.string(),
+ *         sessionId: t.string(),
+ *         eventType: t.string(),
+ *         timestamp: t.number(),
+ *         duration: t.optional(t.number()),
+ *         metadata: t.optional(t.record(t.string(), t.any()))
+ *       })
+ *     }
+ *   });
+ *
+ *   metricsSubscriber = $subscriber({
+ *     topic: this.userActivityTopic,
+ *     handler: async (message) => {
+ *       const { userId, sessionId, eventType, timestamp, duration, metadata } = message.payload;
+ *
+ *       // Update real-time metrics
+ *       await Promise.all([
+ *         // Update user activity counters
+ *         this.metricsStore.increment(`user:${userId}:events:${eventType}`, 1),
+ *         this.metricsStore.increment(`global:events:${eventType}`, 1),
+ *
+ *         // Track session activity
+ *         this.sessionStore.updateActivity(sessionId, timestamp),
+ *
+ *         // Record duration metrics if provided
+ *         duration ? this.metricsStore.recordDuration(`events:${eventType}:duration`, duration) : Promise.resolve(),
+ *
+ *         // Update time-based aggregations
+ *         this.timeSeriesStore.addPoint({
+ *           metric: `user_activity.${eventType}`,
+ *           timestamp,
+ *           value: 1,
+ *           tags: { userId, sessionId }
+ *         })
+ *       ]);
+ *
+ *       // Trigger real-time dashboard updates
+ *       await this.dashboardService.updateRealTimeStats({
+ *         eventType,
+ *         userId,
+ *         timestamp
+ *       });
+ *
+ *       this.logger.debug(`Processed metrics for ${eventType}`, {
+ *         userId,
+ *         eventType,
+ *         timestamp
+ *       });
+ *     }
+ *   });
+ * }
+ * ```
  */
 declare const $subscriber: {
   <T extends TopicMessageSchema>(options: SubscriberDescriptorOptions<T>): SubscriberDescriptor<T>;
   [KIND]: typeof SubscriberDescriptor;
 };
 interface SubscriberDescriptorOptions<T extends TopicMessageSchema> {
+  /**
+   * The topic descriptor that this subscriber will listen to for messages.
+   *
+   * This establishes the connection between the subscriber and its source topic:
+   * - The subscriber inherits the topic's message schema for type safety
+   * - Messages published to the topic will be automatically delivered to this subscriber
+   * - Multiple subscribers can listen to the same topic independently
+   * - The subscriber will use the topic's provider and configuration settings
+   *
+   * **Topic Integration Benefits**:
+   * - Type safety: Subscriber handler gets fully typed message payloads
+   * - Schema validation: Messages are validated before reaching the subscriber
+   * - Real-time delivery: Messages are delivered immediately upon publication
+   * - Error isolation: Subscriber errors don't affect the topic or other subscribers
+   * - Monitoring: Topic metrics include subscriber processing statistics
+   *
+   * @example
+   * ```ts
+   * // First, define a topic
+   * userEvents = $topic({
+   *   name: "user-activity",
+   *   schema: {
+   *     payload: t.object({ userId: t.string(), action: t.string() })
+   *   }
+   * });
+   *
+   * // Then, create a subscriber for that topic
+   * activitySubscriber = $subscriber({
+   *   topic: this.userEvents,  // Reference the topic descriptor
+   *   handler: async (message) => { } // Process messages here
+   * });
+   * ```
+   */
   topic: TopicDescriptor<T>;
+  /**
+   * Message handler function that processes individual messages from the topic.
+   *
+   * This function:
+   * - Receives fully typed and validated message payloads from the connected topic
+   * - Executes immediately when messages are published to the topic
+   * - Should implement the core business logic for reacting to these events
+   * - Runs independently of other subscribers to the same topic
+   * - Should handle errors gracefully to avoid affecting other subscribers
+   * - Has access to the full Alepha dependency injection container
+   *
+   * **Handler Design Guidelines**:
+   * - Keep handlers focused on a single responsibility
+   * - Use proper error handling and logging
+   * - Consider performance impact for high-frequency topics
+   * - Make handlers idempotent when possible for reliability
+   * - Validate business rules within the handler logic
+   * - Log important processing steps for debugging and monitoring
+   *
+   * **Error Handling Strategy**:
+   * - Log errors but don't re-throw to avoid affecting other subscribers
+   * - Use try-catch blocks for external service calls
+   * - Implement circuit breakers for resilience with external systems
+   * - Monitor error rates and patterns for system health
+   * - Consider implementing retry logic for temporary failures
+   *
+   * **Performance Considerations**:
+   * - Keep handler execution time minimal for high-throughput topics
+   * - Use background queues for heavy processing triggered by events
+   * - Implement batching for efficiency when processing many similar events
+   * - Consider async processing patterns for non-critical operations
+   *
+   * @param message - The topic message with validated payload and optional headers
+   * @param message.payload - The typed message data based on the topic's schema
+   * @returns Promise that resolves when processing is complete
+   *
+   * @example
+   * ```ts
+   * handler: async (message) => {
+   *   const { userId, eventType, timestamp } = message.payload;
+   *
+   *   try {
+   *     // Log event receipt
+   *     this.logger.info(`Processing ${eventType} event for user ${userId}`, {
+   *       timestamp,
+   *       userId,
+   *       eventType
+   *     });
+   *
+   *     // Perform event-specific processing
+   *     switch (eventType) {
+   *       case 'user.login':
+   *         await this.updateLastLogin(userId, timestamp);
+   *         await this.sendWelcomeNotification(userId);
+   *         break;
+   *       case 'user.logout':
+   *         await this.updateSessionDuration(userId, timestamp);
+   *         break;
+   *       case 'user.purchase':
+   *         await this.updateRewardsPoints(userId, message.payload.purchaseAmount);
+   *         await this.triggerRecommendations(userId);
+   *         break;
+   *       default:
+   *         this.logger.warn(`Unknown event type: ${eventType}`);
+   *     }
+   *
+   *     // Update analytics
+   *     await this.analytics.track(eventType, {
+   *       userId,
+   *       timestamp,
+   *       source: 'topic-subscriber'
+   *     });
+   *
+   *     this.logger.info(`Successfully processed ${eventType} for user ${userId}`);
+   *
+   *   } catch (error) {
+   *     // Log error but don't re-throw to avoid affecting other subscribers
+   *     this.logger.error(`Failed to process ${eventType} for user ${userId}`, {
+   *       error: error.message,
+   *       stack: error.stack,
+   *       userId,
+   *       eventType,
+   *       timestamp
+   *     });
+   *
+   *     // Optionally send to error tracking service
+   *     await this.errorTracker.captureException(error, {
+   *       context: { userId, eventType, timestamp },
+   *       tags: { component: 'topic-subscriber' }
+   *     });
+   *   }
+   * }
+   * ```
+   */
   handler: TopicHandler<T>;
 }
 declare class SubscriberDescriptor<T extends TopicMessageSchema> extends Descriptor<SubscriberDescriptorOptions<T>> {}