alepha 0.14.3 → 0.15.0

package/dist/topic/core/index.d.ts

@@ -17,28 +17,28 @@ declare class TopicTimeoutError extends Error {
 declare abstract class TopicProvider {
   protected readonly alepha: Alepha;
   /**
-   * Publish a message to a topic.
-   *
-   * @param topic - The topic to publish to.
-   * @param message - The message to publish.
-   */
+       * Publish a message to a topic.
+       *
+       * @param topic - The topic to publish to.
+       * @param message - The message to publish.
+       */
   abstract publish(topic: string, message: string): Promise<void>;
   /**
-   * Subscribe to a topic.
-   *
-   * @param topic - The topic to subscribe to.
-   * @param callback - The callback to call when a message is received.
-   */
+       * Subscribe to a topic.
+       *
+       * @param topic - The topic to subscribe to.
+       * @param callback - The callback to call when a message is received.
+       */
   abstract subscribe(topic: string, callback: SubscribeCallback): Promise<UnSubscribeFn>;
   /**
-   * Unsubscribe from a topic.
-   *
-   * @param topic - The topic to unsubscribe from.
-   */
+       * Unsubscribe from a topic.
+       *
+       * @param topic - The topic to unsubscribe from.
+       */
   abstract unsubscribe(topic: string): Promise<void>;
   /**
-   * Returns the list of $subscribers for this provider.
-   */
+       * Returns the list of $subscribers for this provider.
+       */
   protected subscribers(): Array<() => Promise<unknown>>;
 }
 type SubscribeCallback = (message: string) => Promise<void> | void;
@@ -89,177 +89,177 @@ declare const $topic: {
 };
 interface TopicPrimitiveOptions<T extends TopicMessageSchema> {
   /**
-   * 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, 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"
-   */
+       * 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, 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;
   /**
-   * 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"
-   */
+       * 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;
   /**
-   * 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
-   *
-   * **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
-   */
+       * 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
+       *
+       * **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>;
   /**
-   * 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.text(),
-   *     eventType: t.enum(["created", "updated"]),
-   *     data: t.record(t.text(), t.any()),
-   *     timestamp: t.number(),
-   *     userId: t.optional(t.text())
-   *   }),
-   *   headers: t.optional(t.object({
-   *     source: t.text(),
-   *     correlationId: t.text()
-   *   }))
-   * }
-   * ```
-   */
+       * 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.text(),
+       *     eventType: t.enum(["created", "updated"]),
+       *     data: t.record(t.text(), t.any()),
+       *     timestamp: t.number(),
+       *     userId: t.optional(t.text())
+       *   }),
+       *   headers: t.optional(t.object({
+       *     source: t.text(),
+       *     correlationId: t.text()
+       *   }))
+       * }
+       * ```
+       */
   schema: T;
   /**
-   * 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
-   *     });
-   *   }
-   * }
-   * ```
-   */
+       * 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>;
 }
 declare class TopicPrimitive<T extends TopicMessageSchema> extends Primitive<TopicPrimitiveOptions<T>> {
@@ -349,133 +349,133 @@ declare const $subscriber: {
 };
 interface SubscriberPrimitiveOptions<T extends TopicMessageSchema> {
   /**
-   * The topic primitive 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.text(), action: t.text() })
-   *   }
-   * });
-   *
-   * // Then, create a subscriber for that topic
-   * activitySubscriber = $subscriber({
-   *   topic: this.userEvents,  // Reference the topic primitive
-   *   handler: async (message) => { } // Process messages here
-   * });
-   * ```
-   */
+       * The topic primitive 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.text(), action: t.text() })
+       *   }
+       * });
+       *
+       * // Then, create a subscriber for that topic
+       * activitySubscriber = $subscriber({
+       *   topic: this.userEvents,  // Reference the topic primitive
+       *   handler: async (message) => { } // Process messages here
+       * });
+       * ```
+       */
   topic: TopicPrimitive<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' }
-   *     });
-   *   }
-   * }
-   * ```
-   */
+       * 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 SubscriberPrimitive<T extends TopicMessageSchema> extends Primitive<SubscriberPrimitiveOptions<T>> {}
@@ -486,24 +486,24 @@ declare class MemoryTopicProvider extends TopicProvider {
   protected readonly subscriptions: Record<string, SubscribeCallback[]>;
   protected readonly start: alepha1.HookPrimitive<"start">;
   /**
-   * Publish a message to a topic.
-   *
-   * @param topic
-   * @param message
-   */
+       * Publish a message to a topic.
+       *
+       * @param topic
+       * @param message
+       */
   publish(topic: string, message: string): Promise<void>;
   /**
-   * Subscribe to a topic.
-   *
-   * @param topic - The topic to subscribe to.
-   * @param callback
-   */
+       * Subscribe to a topic.
+       *
+       * @param topic - The topic to subscribe to.
+       * @param callback
+       */
   subscribe(topic: string, callback: SubscribeCallback): Promise<UnSubscribeFn>;
   /**
-   * Unsubscribe from a topic.
-   *
-   * @param topic - The topic to unsubscribe from.
-   */
+       * Unsubscribe from a topic.
+       *
+       * @param topic - The topic to unsubscribe from.
+       */
   unsubscribe(topic: string): Promise<void>;
 }
 //#endregion