alepha 0.13.0 → 0.13.1

package/dist/topic/index.cjs

@@ -1,282 +0,0 @@
-let alepha = require("alepha");
-let alepha_datetime = require("alepha/datetime");
-let alepha_logger = require("alepha/logger");
-
-//#region src/topic/descriptors/$subscriber.ts
-/**
-* Creates a subscriber descriptor to listen for messages from a specific topic.
-*
-* Provides a dedicated message subscriber that connects to a topic and processes messages
-* with custom handler logic, enabling scalable pub/sub architectures where multiple
-* subscribers can react to the same events independently.
-*
-* **Key Features**
-* - Seamless integration with any $topic descriptor
-* - Full type safety inherited from topic schema
-* - Real-time message delivery when events are published
-* - Error isolation between subscribers
-* - Support for multiple independent subscribers per topic
-*
-* **Common Use Cases**
-* - Notification services and audit logging
-* - Analytics and metrics collection
-* - Data synchronization and real-time UI updates
-*
-* @example
-* ```ts
-* class UserActivityService {
-*   userEvents = $topic({
-*     name: "user-activity",
-*     schema: {
-*       payload: t.object({
-*         userId: t.text(),
-*         action: t.enum(["login", "logout", "purchase"]),
-*         timestamp: t.number()
-*       })
-*     }
-*   });
-*
-*   activityLogger = $subscriber({
-*     topic: this.userEvents,
-*     handler: async (message) => {
-*       const { userId, action, timestamp } = message.payload;
-*       await this.auditLogger.log({
-*         userId,
-*         action,
-*         timestamp
-*       });
-*     }
-*   });
-*
-*   async trackUserLogin(userId: string) {
-*     await this.userEvents.publish({
-*       userId,
-*       action: "login",
-*       timestamp: Date.now()
-*     });
-*   }
-* }
-* ```
-*/
-const $subscriber = (options) => {
-	return (0, alepha.createDescriptor)(SubscriberDescriptor, options);
-};
-var SubscriberDescriptor = class extends alepha.Descriptor {};
-$subscriber[alepha.KIND] = SubscriberDescriptor;
-
-//#endregion
-//#region src/topic/errors/TopicTimeoutError.ts
-var TopicTimeoutError = class extends Error {
-	topic;
-	timeout;
-	constructor(topic, timeout) {
-		super(`Timeout of ${timeout}ms exceeded for topic ${topic}`);
-		this.timeout = timeout;
-		this.topic = topic;
-	}
-};
-
-//#endregion
-//#region src/topic/providers/TopicProvider.ts
-/**
-* Base class for topic providers.
-*/
-var TopicProvider = class {
-	alepha = (0, alepha.$inject)(alepha.Alepha);
-	/**
-	* Returns the list of $subscribers for this provider.
-	*/
-	subscribers() {
-		const handlers = [];
-		const topics = this.alepha.descriptors($topic);
-		for (const topic of topics) {
-			if (topic.provider !== this) continue;
-			const handler = topic.options.handler;
-			if (handler && topic.provider === this) handlers.push(() => topic.subscribe(handler));
-		}
-		const subscribers = this.alepha.descriptors($subscriber);
-		for (const subscriber of subscribers) {
-			if (subscriber.options.topic.provider !== this) continue;
-			handlers.push(() => subscriber.options.topic.subscribe(subscriber.options.handler));
-		}
-		return handlers;
-	}
-};
-
-//#endregion
-//#region src/topic/providers/MemoryTopicProvider.ts
-var MemoryTopicProvider = class extends TopicProvider {
-	log = (0, alepha_logger.$logger)();
-	subscriptions = {};
-	start = (0, alepha.$hook)({
-		on: "start",
-		handler: async () => {
-			const subscribers = this.subscribers();
-			if (subscribers.length) {
-				await Promise.all(subscribers.map((fn) => fn()));
-				for (const subscriber of subscribers) this.log.debug(`Subscribed to topic '${subscriber.name}'`);
-			}
-		}
-	});
-	/**
-	* Publish a message to a topic.
-	*
-	* @param topic
-	* @param message
-	*/
-	async publish(topic, message) {
-		if (!this.subscriptions[topic]) return;
-		for (const callback of this.subscriptions[topic]) await callback(message);
-	}
-	/**
-	* Subscribe to a topic.
-	*
-	* @param topic - The topic to subscribe to.
-	* @param callback
-	*/
-	async subscribe(topic, callback) {
-		if (!this.subscriptions[topic]) this.subscriptions[topic] = [];
-		this.subscriptions[topic].push(callback);
-		return async () => {
-			const callbacks = this.subscriptions[topic];
-			if (!callbacks) return;
-			this.subscriptions[topic] = callbacks.filter((cb) => cb !== callback);
-			if (this.subscriptions[topic].length === 0) delete this.subscriptions[topic];
-		};
-	}
-	/**
-	* Unsubscribe from a topic.
-	*
-	* @param topic - The topic to unsubscribe from.
-	*/
-	async unsubscribe(topic) {
-		delete this.subscriptions[topic];
-	}
-};
-
-//#endregion
-//#region src/topic/descriptors/$topic.ts
-/**
-* Creates a topic descriptor for publish/subscribe messaging and event-driven architecture.
-*
-* Enables decoupled communication through a pub/sub pattern where publishers send messages
-* and multiple subscribers receive them. Supports type-safe messages, real-time delivery,
-* event filtering, and pluggable backends (memory, Redis, custom providers).
-*
-* **Use Cases**: User notifications, real-time chat, event broadcasting, microservice communication
-*
-* @example
-* ```ts
-* class NotificationService {
-*   userActivity = $topic({
-*     name: "user-activity",
-*     schema: {
-*       payload: t.object({
-*         userId: t.text(),
-*         action: t.enum(["login", "logout", "purchase"]),
-*         timestamp: t.number()
-*       })
-*     },
-*     handler: async (message) => {
-*       console.log(`User ${message.payload.userId}: ${message.payload.action}`);
-*     }
-*   });
-*
-*   async trackLogin(userId: string) {
-*     await this.userActivity.publish({ userId, action: "login", timestamp: Date.now() });
-*   }
-*
-*   async subscribeToEvents() {
-*     await this.userActivity.subscribe(async (message) => {
-*       // Additional subscriber logic
-*     });
-*   }
-* }
-* ```
-*/
-const $topic = (options) => {
-	return (0, alepha.createDescriptor)(TopicDescriptor, options);
-};
-var TopicDescriptor = class extends alepha.Descriptor {
-	log = (0, alepha_logger.$logger)();
-	dateTimeProvider = (0, alepha.$inject)(alepha_datetime.DateTimeProvider);
-	provider = this.$provider();
-	get name() {
-		return this.options.name || this.config.propertyKey;
-	}
-	async publish(payload) {
-		await this.provider.publish(this.name, JSON.stringify({ payload: this.alepha.codec.encode(this.options.schema.payload, payload) }));
-	}
-	async subscribe(handler) {
-		return this.provider.subscribe(this.name, async (message) => {
-			try {
-				await handler(this.parseMessage(message));
-			} catch (error) {
-				this.log.error("Message processing has failed", error);
-			}
-		});
-	}
-	async wait(options = {}) {
-		const filter = options.filter ?? (() => true);
-		return new Promise((resolve, reject) => {
-			const ref = {};
-			(async () => {
-				const clear = await this.provider.subscribe(this.name, (raw) => {
-					const message = this.parseMessage(raw);
-					if (!filter(message)) return;
-					ref.timeout?.clear();
-					clear();
-					resolve(message);
-				});
-				const timeoutDuration = options.timeout ?? [10, "seconds"];
-				ref.timeout = this.dateTimeProvider.createTimeout(() => {
-					clear();
-					reject(new TopicTimeoutError(this.name, this.dateTimeProvider.duration(timeoutDuration).asMilliseconds()));
-				}, timeoutDuration);
-			})();
-		});
-	}
-	$provider() {
-		if (!this.options.provider) return this.alepha.inject(TopicProvider);
-		if (this.options.provider === "memory") return this.alepha.inject(MemoryTopicProvider);
-		return this.alepha.inject(this.options.provider);
-	}
-	parseMessage(message) {
-		const { payload } = JSON.parse(message);
-		return { payload: this.alepha.codec.decode(this.options.schema.payload, payload) };
-	}
-};
-$topic[alepha.KIND] = TopicDescriptor;
-
-//#endregion
-//#region src/topic/index.ts
-/**
-* Generic interface for pub/sub messaging.
-* Gives you the ability to create topics and subscribers.
-* This module provides only a memory implementation of the topic provider.
-*
-* @see {@link $topic}
-* @see {@link $subscriber}
-* @module alepha.topic
-*/
-const AlephaTopic = (0, alepha.$module)({
-	name: "alepha.topic",
-	descriptors: [$topic, $subscriber],
-	services: [TopicProvider, MemoryTopicProvider],
-	register: (alepha$1) => alepha$1.with({
-		optional: true,
-		provide: TopicProvider,
-		use: MemoryTopicProvider
-	})
-});
-
-//#endregion
-exports.$subscriber = $subscriber;
-exports.$topic = $topic;
-exports.AlephaTopic = AlephaTopic;
-exports.MemoryTopicProvider = MemoryTopicProvider;
-exports.SubscriberDescriptor = SubscriberDescriptor;
-exports.TopicDescriptor = TopicDescriptor;
-exports.TopicProvider = TopicProvider;
-exports.TopicTimeoutError = TopicTimeoutError;
-//# sourceMappingURL=index.cjs.map

package/dist/topic/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","names":["Descriptor","KIND","Alepha","handlers: Array<() => Promise<unknown>>","Descriptor","DateTimeProvider","ref: { timeout?: Timeout }","KIND","alepha"],"sources":["../../src/topic/descriptors/$subscriber.ts","../../src/topic/errors/TopicTimeoutError.ts","../../src/topic/providers/TopicProvider.ts","../../src/topic/providers/MemoryTopicProvider.ts","../../src/topic/descriptors/$topic.ts","../../src/topic/index.ts"],"sourcesContent":["import { createDescriptor, Descriptor, KIND } from \"alepha\";\nimport type {\n  TopicDescriptor,\n  TopicHandler,\n  TopicMessageSchema,\n} from \"./$topic.ts\";\n\n/**\n * Creates a subscriber descriptor to listen for messages from a specific topic.\n *\n * Provides a dedicated message subscriber that connects to a topic and processes messages\n * with custom handler logic, enabling scalable pub/sub architectures where multiple\n * subscribers can react to the same events independently.\n *\n * **Key Features**\n * - Seamless integration with any $topic descriptor\n * - Full type safety inherited from topic schema\n * - Real-time message delivery when events are published\n * - Error isolation between subscribers\n * - Support for multiple independent subscribers per topic\n *\n * **Common Use Cases**\n * - Notification services and audit logging\n * - Analytics and metrics collection\n * - Data synchronization and real-time UI updates\n *\n * @example\n * ```ts\n * class UserActivityService {\n *   userEvents = $topic({\n *     name: \"user-activity\",\n *     schema: {\n *       payload: t.object({\n *         userId: t.text(),\n *         action: t.enum([\"login\", \"logout\", \"purchase\"]),\n *         timestamp: t.number()\n *       })\n *     }\n *   });\n *\n *   activityLogger = $subscriber({\n *     topic: this.userEvents,\n *     handler: async (message) => {\n *       const { userId, action, timestamp } = message.payload;\n *       await this.auditLogger.log({\n *         userId,\n *         action,\n *         timestamp\n *       });\n *     }\n *   });\n *\n *   async trackUserLogin(userId: string) {\n *     await this.userEvents.publish({\n *       userId,\n *       action: \"login\",\n *       timestamp: Date.now()\n *     });\n *   }\n * }\n * ```\n */\nexport const $subscriber = <T extends TopicMessageSchema>(\n  options: SubscriberDescriptorOptions<T>,\n): SubscriberDescriptor<T> => {\n  return createDescriptor(SubscriberDescriptor<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface SubscriberDescriptorOptions<T extends TopicMessageSchema> {\n  /**\n   * The topic descriptor that this subscriber will listen to for messages.\n   *\n   * This establishes the connection between the subscriber and its source topic:\n   * - The subscriber inherits the topic's message schema for type safety\n   * - Messages published to the topic will be automatically delivered to this subscriber\n   * - Multiple subscribers can listen to the same topic independently\n   * - The subscriber will use the topic's provider and configuration settings\n   *\n   * **Topic Integration Benefits**:\n   * - Type safety: Subscriber handler gets fully typed message payloads\n   * - Schema validation: Messages are validated before reaching the subscriber\n   * - Real-time delivery: Messages are delivered immediately upon publication\n   * - Error isolation: Subscriber errors don't affect the topic or other subscribers\n   * - Monitoring: Topic metrics include subscriber processing statistics\n   *\n   * @example\n   * ```ts\n   * // First, define a topic\n   * userEvents = $topic({\n   *   name: \"user-activity\",\n   *   schema: {\n   *     payload: t.object({ userId: t.text(), action: t.text() })\n   *   }\n   * });\n   *\n   * // Then, create a subscriber for that topic\n   * activitySubscriber = $subscriber({\n   *   topic: this.userEvents,  // Reference the topic descriptor\n   *   handler: async (message) => { } // Process messages here\n   * });\n   * ```\n   */\n  topic: TopicDescriptor<T>;\n\n  /**\n   * Message handler function that processes individual messages from the topic.\n   *\n   * This function:\n   * - Receives fully typed and validated message payloads from the connected topic\n   * - Executes immediately when messages are published to the topic\n   * - Should implement the core business logic for reacting to these events\n   * - Runs independently of other subscribers to the same topic\n   * - Should handle errors gracefully to avoid affecting other subscribers\n   * - Has access to the full Alepha dependency injection container\n   *\n   * **Handler Design Guidelines**:\n   * - Keep handlers focused on a single responsibility\n   * - Use proper error handling and logging\n   * - Consider performance impact for high-frequency topics\n   * - Make handlers idempotent when possible for reliability\n   * - Validate business rules within the handler logic\n   * - Log important processing steps for debugging and monitoring\n   *\n   * **Error Handling Strategy**:\n   * - Log errors but don't re-throw to avoid affecting other subscribers\n   * - Use try-catch blocks for external service calls\n   * - Implement circuit breakers for resilience with external systems\n   * - Monitor error rates and patterns for system health\n   * - Consider implementing retry logic for temporary failures\n   *\n   * **Performance Considerations**:\n   * - Keep handler execution time minimal for high-throughput topics\n   * - Use background queues for heavy processing triggered by events\n   * - Implement batching for efficiency when processing many similar events\n   * - Consider async processing patterns for non-critical operations\n   *\n   * @param message - The topic message with validated payload and optional headers\n   * @param message.payload - The typed message data based on the topic's schema\n   * @returns Promise that resolves when processing is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (message) => {\n   *   const { userId, eventType, timestamp } = message.payload;\n   *\n   *   try {\n   *     // Log event receipt\n   *     this.logger.info(`Processing ${eventType} event for user ${userId}`, {\n   *       timestamp,\n   *       userId,\n   *       eventType\n   *     });\n   *\n   *     // Perform event-specific processing\n   *     switch (eventType) {\n   *       case 'user.login':\n   *         await this.updateLastLogin(userId, timestamp);\n   *         await this.sendWelcomeNotification(userId);\n   *         break;\n   *       case 'user.logout':\n   *         await this.updateSessionDuration(userId, timestamp);\n   *         break;\n   *       case 'user.purchase':\n   *         await this.updateRewardsPoints(userId, message.payload.purchaseAmount);\n   *         await this.triggerRecommendations(userId);\n   *         break;\n   *       default:\n   *         this.logger.warn(`Unknown event type: ${eventType}`);\n   *     }\n   *\n   *     // Update analytics\n   *     await this.analytics.track(eventType, {\n   *       userId,\n   *       timestamp,\n   *       source: 'topic-subscriber'\n   *     });\n   *\n   *     this.logger.info(`Successfully processed ${eventType} for user ${userId}`);\n   *\n   *   } catch (error) {\n   *     // Log error but don't re-throw to avoid affecting other subscribers\n   *     this.logger.error(`Failed to process ${eventType} for user ${userId}`, {\n   *       error: error.message,\n   *       stack: error.stack,\n   *       userId,\n   *       eventType,\n   *       timestamp\n   *     });\n   *\n   *     // Optionally send to error tracking service\n   *     await this.errorTracker.captureException(error, {\n   *       context: { userId, eventType, timestamp },\n   *       tags: { component: 'topic-subscriber' }\n   *     });\n   *   }\n   * }\n   * ```\n   */\n  handler: TopicHandler<T>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class SubscriberDescriptor<\n  T extends TopicMessageSchema,\n> extends Descriptor<SubscriberDescriptorOptions<T>> {}\n\n$subscriber[KIND] = SubscriberDescriptor;\n","export class TopicTimeoutError extends Error {\n  public readonly topic: string;\n  public readonly timeout: number;\n\n  constructor(topic: string, timeout: number) {\n    super(`Timeout of ${timeout}ms exceeded for topic ${topic}`);\n    this.timeout = timeout;\n    this.topic = topic;\n  }\n}\n","import { $inject, Alepha } from \"alepha\";\nimport { $subscriber } from \"../descriptors/$subscriber.ts\";\nimport { $topic } from \"../descriptors/$topic.ts\";\n\n/**\n * Base class for topic providers.\n */\nexport abstract class TopicProvider {\n  protected readonly alepha = $inject(Alepha);\n\n  /**\n   * Publish a message to a topic.\n   *\n   * @param topic - The topic to publish to.\n   * @param message - The message to publish.\n   */\n  public abstract publish(topic: string, message: string): Promise<void>;\n\n  /**\n   * Subscribe to a topic.\n   *\n   * @param topic - The topic to subscribe to.\n   * @param callback - The callback to call when a message is received.\n   */\n  public abstract subscribe(\n    topic: string,\n    callback: SubscribeCallback,\n  ): Promise<UnSubscribeFn>;\n\n  /**\n   * Unsubscribe from a topic.\n   *\n   * @param topic - The topic to unsubscribe from.\n   */\n  public abstract unsubscribe(topic: string): Promise<void>;\n\n  /**\n   * Returns the list of $subscribers for this provider.\n   */\n  protected subscribers(): Array<() => Promise<unknown>> {\n    const handlers: Array<() => Promise<unknown>> = [];\n\n    const topics = this.alepha.descriptors($topic);\n\n    for (const topic of topics) {\n      if (topic.provider !== this) {\n        continue;\n      }\n\n      const handler = topic.options.handler;\n      if (handler && topic.provider === this) {\n        handlers.push(() => topic.subscribe(handler));\n      }\n    }\n\n    const subscribers = this.alepha.descriptors($subscriber);\n    for (const subscriber of subscribers) {\n      if (subscriber.options.topic.provider !== this) {\n        continue;\n      }\n\n      handlers.push(() =>\n        subscriber.options.topic.subscribe(subscriber.options.handler),\n      );\n    }\n\n    return handlers;\n  }\n}\n\nexport type SubscribeCallback = (message: string) => Promise<void> | void;\n\nexport type UnSubscribeFn = () => Promise<void>;\n","import { $hook } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  type SubscribeCallback,\n  TopicProvider,\n  type UnSubscribeFn,\n} from \"./TopicProvider.ts\";\n\nexport class MemoryTopicProvider extends TopicProvider {\n  protected readonly log = $logger();\n  protected readonly subscriptions: Record<string, SubscribeCallback[]> = {};\n\n  protected readonly start = $hook({\n    on: \"start\",\n    handler: async () => {\n      const subscribers = this.subscribers();\n      if (subscribers.length) {\n        await Promise.all(subscribers.map((fn) => fn()));\n        for (const subscriber of subscribers) {\n          this.log.debug(`Subscribed to topic '${subscriber.name}'`);\n        }\n      }\n    },\n  });\n\n  /**\n   * Publish a message to a topic.\n   *\n   * @param topic\n   * @param message\n   */\n  public async publish(topic: string, message: string): Promise<void> {\n    if (!this.subscriptions[topic]) {\n      return;\n    }\n\n    for (const callback of this.subscriptions[topic]) {\n      await callback(message);\n    }\n  }\n\n  /**\n   * Subscribe to a topic.\n   *\n   * @param topic - The topic to subscribe to.\n   * @param callback\n   */\n\n  public async subscribe(\n    topic: string,\n    callback: SubscribeCallback,\n  ): Promise<UnSubscribeFn> {\n    if (!this.subscriptions[topic]) {\n      this.subscriptions[topic] = [];\n    }\n\n    this.subscriptions[topic].push(callback);\n\n    return async () => {\n      const callbacks = this.subscriptions[topic];\n      if (!callbacks) {\n        return;\n      }\n\n      this.subscriptions[topic] = callbacks.filter((cb) => cb !== callback);\n      if (this.subscriptions[topic].length === 0) {\n        delete this.subscriptions[topic];\n      }\n    };\n  }\n\n  /**\n   * Unsubscribe from a topic.\n   *\n   * @param topic - The topic to unsubscribe from.\n   */\n  public async unsubscribe(topic: string): Promise<void> {\n    delete this.subscriptions[topic];\n  }\n}\n","import {\n  $inject,\n  createDescriptor,\n  Descriptor,\n  KIND,\n  type Service,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport {\n  DateTimeProvider,\n  type DurationLike,\n  type Timeout,\n} from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { TopicTimeoutError } from \"../errors/TopicTimeoutError.ts\";\nimport { MemoryTopicProvider } from \"../providers/MemoryTopicProvider.ts\";\nimport {\n  TopicProvider,\n  type UnSubscribeFn,\n} from \"../providers/TopicProvider.ts\";\n\n/**\n * Creates a topic descriptor for publish/subscribe messaging and event-driven architecture.\n *\n * Enables decoupled communication through a pub/sub pattern where publishers send messages\n * and multiple subscribers receive them. Supports type-safe messages, real-time delivery,\n * event filtering, and pluggable backends (memory, Redis, custom providers).\n *\n * **Use Cases**: User notifications, real-time chat, event broadcasting, microservice communication\n *\n * @example\n * ```ts\n * class NotificationService {\n *   userActivity = $topic({\n *     name: \"user-activity\",\n *     schema: {\n *       payload: t.object({\n *         userId: t.text(),\n *         action: t.enum([\"login\", \"logout\", \"purchase\"]),\n *         timestamp: t.number()\n *       })\n *     },\n *     handler: async (message) => {\n *       console.log(`User ${message.payload.userId}: ${message.payload.action}`);\n *     }\n *   });\n *\n *   async trackLogin(userId: string) {\n *     await this.userActivity.publish({ userId, action: \"login\", timestamp: Date.now() });\n *   }\n *\n *   async subscribeToEvents() {\n *     await this.userActivity.subscribe(async (message) => {\n *       // Additional subscriber logic\n *     });\n *   }\n * }\n * ```\n */\nexport const $topic = <T extends TopicMessageSchema>(\n  options: TopicDescriptorOptions<T>,\n): TopicDescriptor<T> => {\n  return createDescriptor(TopicDescriptor<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface TopicDescriptorOptions<T extends TopicMessageSchema> {\n  /**\n   * Unique name identifier for the topic.\n   *\n   * This name is used for:\n   * - Topic identification across the pub/sub system\n   * - Message routing between publishers and subscribers\n   * - Logging and debugging topic-related operations\n   * - Provider-specific topic management (channels, keys, etc.)\n   *\n   * If not provided, defaults to the property key where the topic is declared.\n   *\n   * **Naming Conventions**:\n   * - Use descriptive, hierarchical names: \"user.activity\", \"order.events\"\n   * - Avoid spaces and special characters\n   * - Consider using dot notation for categorization\n   * - Keep names concise but meaningful\n   *\n   * @example \"user-activity\"\n   * @example \"chat.messages\"\n   * @example \"system.health.checks\"\n   * @example \"payment.webhooks\"\n   */\n  name?: string;\n\n  /**\n   * Human-readable description of the topic's purpose and usage.\n   *\n   * Used for:\n   * - Documentation generation and API references\n   * - Developer onboarding and understanding\n   * - Monitoring dashboards and admin interfaces\n   * - Team communication about system architecture\n   *\n   * **Description Best Practices**:\n   * - Explain what events/messages this topic handles\n   * - Mention key use cases and subscribers\n   * - Include any important timing or ordering guarantees\n   * - Note any special processing requirements\n   *\n   * @example \"Real-time user activity events for analytics and notifications\"\n   * @example \"Order lifecycle events from creation to delivery\"\n   * @example \"Chat messages broadcast to all room participants\"\n   * @example \"System health checks and service status updates\"\n   */\n  description?: string;\n\n  /**\n   * Topic provider configuration for message storage and delivery.\n   *\n   * Options:\n   * - **\"memory\"**: In-memory provider (default for development, lost on restart)\n   * - **Service<TopicProvider>**: Custom provider class (e.g., RedisTopicProvider)\n   * - **undefined**: Uses the default topic provider from dependency injection\n   *\n   * **Provider Selection Guidelines**:\n   * - **Development**: Use \"memory\" for fast, simple testing without external dependencies\n   * - **Production**: Use Redis or message brokers for persistence and scalability\n   * - **Distributed systems**: Use Redis/RabbitMQ for cross-service communication\n   * - **High-throughput**: Use specialized providers with connection pooling\n   * - **Real-time**: Ensure provider supports low-latency message delivery\n   *\n   * **Provider Capabilities**:\n   * - Message persistence and durability\n   * - Subscriber management and connection handling\n   * - Message ordering and delivery guarantees\n   * - Horizontal scaling and load distribution\n   *\n   * @default Uses injected TopicProvider\n   * @example \"memory\"\n   * @example RedisTopicProvider\n   * @example RabbitMQTopicProvider\n   */\n  provider?: \"memory\" | Service<TopicProvider>;\n\n  /**\n   * TypeBox schema defining the structure of messages published to this topic.\n   *\n   * The schema must include:\n   * - **payload**: Required schema for the main message data\n   * - **headers**: Optional schema for message metadata\n   *\n   * This schema:\n   * - Validates all messages published to the topic\n   * - Provides full TypeScript type inference for subscribers\n   * - Ensures type safety between publishers and subscribers\n   * - Enables automatic serialization/deserialization\n   *\n   * **Schema Design Best Practices**:\n   * - Keep payload schemas focused and cohesive\n   * - Use optional fields for data that might not always be present\n   * - Include timestamp fields for event ordering\n   * - Consider versioning for schema evolution\n   * - Use union types for different event types in the same topic\n   *\n   * @example\n   * ```ts\n   * {\n   *   payload: t.object({\n   *     eventId: t.text(),\n   *     eventType: t.enum([\"created\", \"updated\"]),\n   *     data: t.record(t.text(), t.any()),\n   *     timestamp: t.number(),\n   *     userId: t.optional(t.text())\n   *   }),\n   *   headers: t.optional(t.object({\n   *     source: t.text(),\n   *     correlationId: t.text()\n   *   }))\n   * }\n   * ```\n   */\n  schema: T;\n\n  /**\n   * Default subscriber handler function that processes messages published to this topic.\n   *\n   * This handler:\n   * - Automatically subscribes when the topic is initialized\n   * - Receives all messages published to the topic\n   * - Runs for every message without additional subscription setup\n   * - Can be supplemented with additional subscribers via `subscribe()` method\n   * - Should handle errors gracefully to avoid breaking other subscribers\n   *\n   * **Handler Design Guidelines**:\n   * - Keep handlers focused on a single responsibility\n   * - Use proper error handling and logging\n   * - Consider performance impact for high-frequency topics\n   * - Make handlers idempotent when possible\n   * - Validate business rules within the handler logic\n   * - Log important processing steps for debugging\n   *\n   * **Error Handling Strategy**:\n   * - Log errors but don't re-throw to avoid affecting other subscribers\n   * - Use try-catch blocks for external service calls\n   * - Consider implementing circuit breakers for resilience\n   * - Monitor error rates and patterns for system health\n   *\n   * @param message - The topic message with validated payload and headers\n   * @param message.payload - The typed message data based on the schema\n   * @returns Promise that resolves when processing is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (message) => {\n   *   const { eventType, data, timestamp } = message.payload;\n   *\n   *   try {\n   *     // Log message receipt\n   *     this.logger.info(`Processing ${eventType} event`, { timestamp, data });\n   *\n   *     // Process based on event type\n   *     switch (eventType) {\n   *       case \"created\":\n   *         await this.handleCreation(data);\n   *         break;\n   *       case \"updated\":\n   *         await this.handleUpdate(data);\n   *         break;\n   *       default:\n   *         this.logger.warn(`Unknown event type: ${eventType}`);\n   *     }\n   *\n   *     this.logger.info(`Successfully processed ${eventType} event`);\n   *\n   *   } catch (error) {\n   *     // Log error but don't re-throw to avoid affecting other subscribers\n   *     this.logger.error(`Failed to process ${eventType} event`, {\n   *       error: error.message,\n   *       eventType,\n   *       timestamp,\n   *       data\n   *     });\n   *   }\n   * }\n   * ```\n   */\n  handler?: TopicHandler<T>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class TopicDescriptor<T extends TopicMessageSchema> extends Descriptor<\n  TopicDescriptorOptions<T>\n> {\n  protected readonly log = $logger();\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n  public readonly provider = this.$provider();\n\n  public get name(): string {\n    return this.options.name || this.config.propertyKey;\n  }\n\n  public async publish(payload: TopicMessage<T>[\"payload\"]): Promise<void> {\n    await this.provider.publish(\n      this.name,\n      JSON.stringify({\n        payload: this.alepha.codec.encode(this.options.schema.payload, payload),\n      }),\n    );\n  }\n\n  public async subscribe(handler: TopicHandler<T>): Promise<UnSubscribeFn> {\n    return this.provider.subscribe(this.name, async (message) => {\n      try {\n        await handler(this.parseMessage(message));\n      } catch (error) {\n        this.log.error(\"Message processing has failed\", error);\n      }\n    });\n  }\n\n  public async wait(\n    options: TopicWaitOptions<T> = {},\n  ): Promise<TopicMessage<T>> {\n    const filter = options.filter ?? (() => true);\n\n    return new Promise((resolve, reject) => {\n      const ref: { timeout?: Timeout } = {};\n\n      (async () => {\n        const clear = await this.provider.subscribe(this.name, (raw) => {\n          const message = this.parseMessage(raw);\n          if (!filter(message)) {\n            return;\n          }\n\n          ref.timeout?.clear();\n          clear();\n          resolve(message);\n        });\n\n        const timeoutDuration = options.timeout ?? [10, \"seconds\"];\n\n        ref.timeout = this.dateTimeProvider.createTimeout(() => {\n          clear();\n          reject(\n            new TopicTimeoutError(\n              this.name,\n              this.dateTimeProvider.duration(timeoutDuration).asMilliseconds(),\n            ),\n          );\n        }, timeoutDuration);\n      })();\n    });\n  }\n\n  protected $provider(): TopicProvider {\n    if (!this.options.provider) {\n      return this.alepha.inject(TopicProvider);\n    }\n\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemoryTopicProvider);\n    }\n\n    return this.alepha.inject(this.options.provider);\n  }\n\n  protected parseMessage(message: string): TopicMessage<T> {\n    const { payload } = JSON.parse(message);\n    return {\n      payload: this.alepha.codec.decode(\n        this.options.schema.payload,\n        payload,\n      ) as TopicMessage<T>[\"payload\"],\n    };\n  }\n}\n\n$topic[KIND] = TopicDescriptor;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface TopicMessage<T extends TopicMessageSchema> {\n  payload: Static<T[\"payload\"]>;\n}\n\nexport interface TopicWaitOptions<T extends TopicMessageSchema> {\n  timeout?: DurationLike;\n  filter?: (message: { payload: Static<T[\"payload\"]> }) => boolean;\n}\n\nexport interface TopicMessageSchema {\n  payload: TSchema;\n}\n\nexport type TopicHandler<T extends TopicMessageSchema = TopicMessageSchema> = (\n  message: TopicMessage<T>,\n) => unknown;\n","import { $module, type Alepha } from \"alepha\";\nimport { $subscriber } from \"./descriptors/$subscriber.ts\";\nimport { $topic } from \"./descriptors/$topic.ts\";\nimport { MemoryTopicProvider } from \"./providers/MemoryTopicProvider.ts\";\nimport { TopicProvider } from \"./providers/TopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$subscriber.ts\";\nexport * from \"./descriptors/$topic.ts\";\nexport * from \"./errors/TopicTimeoutError.ts\";\nexport * from \"./providers/MemoryTopicProvider.ts\";\nexport * from \"./providers/TopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Generic interface for pub/sub messaging.\n * Gives you the ability to create topics and subscribers.\n * This module provides only a memory implementation of the topic provider.\n *\n * @see {@link $topic}\n * @see {@link $subscriber}\n * @module alepha.topic\n */\nexport const AlephaTopic = $module({\n  name: \"alepha.topic\",\n  descriptors: [$topic, $subscriber],\n  services: [TopicProvider, MemoryTopicProvider],\n  register: (alepha: Alepha) =>\n    alepha.with({\n      optional: true,\n      provide: TopicProvider,\n      use: MemoryTopicProvider,\n    }),\n});\n"],"mappings":"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"}