alepha 0.20.1 → 0.20.2

package/dist/topic/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/topic/core/primitives/$subscriber.ts","../../../src/topic/core/errors/TopicTimeoutError.ts","../../../src/topic/core/providers/TopicProvider.ts","../../../src/topic/core/providers/MemoryTopicProvider.ts","../../../src/topic/core/primitives/$topic.ts","../../../src/topic/core/index.ts"],"sourcesContent":["import {\n  createPrimitive,\n  KIND,\n  PipelinePrimitive,\n  type PipelinePrimitiveOptions,\n} from \"alepha\";\nimport type {\n  TopicHandler,\n  TopicMessageSchema,\n  TopicPrimitive,\n} from \"./$topic.ts\";\n\n/**\n * Creates a subscriber primitive 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 primitive\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: SubscriberPrimitiveOptions<T>,\n): SubscriberPrimitive<T> => {\n  return createPrimitive(SubscriberPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface SubscriberPrimitiveOptions<T extends TopicMessageSchema>\n  extends PipelinePrimitiveOptions {\n  /**\n   * The topic primitive 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 primitive\n   *   handler: async (message) => { } // Process messages here\n   * });\n   * ```\n   */\n  topic: TopicPrimitive<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 SubscriberPrimitive<\n  T extends TopicMessageSchema,\n> extends PipelinePrimitive<SubscriberPrimitiveOptions<T>> {}\n\n$subscriber[KIND] = SubscriberPrimitive;\n","import { AlephaError } from \"alepha\";\n\nexport class TopicTimeoutError extends AlephaError {\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 { DateTimeProvider, type Timeout } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { TemplatedPathParser } from \"alepha/router\";\nimport { TopicTimeoutError } from \"../errors/TopicTimeoutError.ts\";\nimport { $subscriber } from \"../primitives/$subscriber.ts\";\nimport {\n  $topic,\n  type TopicHandler,\n  type TopicMessage,\n  type TopicMessageSchema,\n  type TopicWaitOptions,\n} from \"../primitives/$topic.ts\";\n\n/**\n * Base class for topic providers.\n */\nexport abstract class TopicProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n\n  /**\n   * Publish a raw 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(\n    topic: string,\n    message: string,\n    options?: TopicPublishOptions,\n  ): Promise<void>;\n\n  /**\n   * Subscribe to a topic with a raw callback.\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    options?: TopicSubscribeOptions,\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   * Encode and publish a typed message to a topic.\n   */\n  public async publishMessage<T extends TopicMessageSchema>(\n    name: string,\n    schema: T[\"payload\"],\n    payload: TopicMessage<T>[\"payload\"],\n    options?: TopicPublishOptions,\n  ): Promise<void> {\n    let topicName = name;\n    if (options?.params) {\n      const parser = new TemplatedPathParser(name);\n      topicName = parser.interpolate(options.params);\n    }\n\n    await this.publish(\n      topicName,\n      JSON.stringify({\n        payload: this.alepha.codec.encode(schema, payload),\n      }),\n      options,\n    );\n  }\n\n  /**\n   * Parse a raw message string into a typed topic message.\n   */\n  public parseMessage<T extends TopicMessageSchema>(\n    schema: T[\"payload\"],\n    message: string,\n  ): TopicMessage<T> {\n    const { payload } = JSON.parse(message);\n    return {\n      payload: this.alepha.codec.decode(\n        schema,\n        payload,\n      ) as TopicMessage<T>[\"payload\"],\n    } as TopicMessage<T>;\n  }\n\n  /**\n   * Subscribe a typed handler to a topic, with error wrapping and message parsing.\n   */\n  public async subscribeHandler<T extends TopicMessageSchema>(\n    name: string,\n    schema: T[\"payload\"],\n    handler: TopicHandler<T>,\n    options?: TopicSubscribeOptions,\n  ): Promise<UnSubscribeFn> {\n    const parser = new TemplatedPathParser(name);\n    const subscribeTopic = parser.hasParams\n      ? parser.wildcardize(this.wildcardChar())\n      : name;\n\n    return this.subscribe(\n      subscribeTopic,\n      async (message, receivedTopic?: string) => {\n        try {\n          const parsed = this.parseMessage<T>(schema, message);\n\n          if (parser.hasParams && receivedTopic) {\n            const params = parser.extract(receivedTopic);\n            await handler({ ...parsed, params } as TopicMessage<T>);\n          } else {\n            await handler(parsed);\n          }\n        } catch (error) {\n          this.log.error(\"Message processing has failed\", error);\n        }\n      },\n      options,\n    );\n  }\n\n  /**\n   * Wait for a single message matching an optional filter, with timeout.\n   */\n  public async waitForMessage<T extends TopicMessageSchema>(\n    name: string,\n    schema: T[\"payload\"],\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; clear?: () => void } = {};\n\n      (async () => {\n        const clear = await this.subscribe(name, (raw) => {\n          const message = this.parseMessage<T>(schema, raw);\n          if (!filter(message)) {\n            return;\n          }\n\n          ref.timeout?.clear();\n          if (ref.clear) {\n            ref.clear();\n          }\n          resolve(message);\n        });\n\n        ref.clear = clear;\n\n        const timeoutDuration = options.timeout ?? [10, \"seconds\"];\n\n        ref.timeout = this.dateTimeProvider.createTimeout(() => {\n          clear();\n          reject(\n            new TopicTimeoutError(\n              name,\n              this.dateTimeProvider.duration(timeoutDuration).asMilliseconds(),\n            ),\n          );\n        }, timeoutDuration);\n      })();\n    });\n  }\n\n  /**\n   * The wildcard character used for pattern subscriptions.\n   * Override in subclasses for provider-specific wildcards.\n   */\n  protected wildcardChar(): string {\n    return \"+\";\n  }\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.primitives($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.primitives($subscriber);\n    for (const subscriber of subscribers) {\n      if (subscriber.options.topic.provider !== this) {\n        continue;\n      }\n\n      const handler = subscriber.handler.run.bind(subscriber.handler);\n      handlers.push(() => subscriber.options.topic.subscribe(handler));\n    }\n\n    return handlers;\n  }\n}\n\nexport type SubscribeCallback = (\n  message: string,\n  topic?: string,\n) => Promise<void> | void;\n\nexport type UnSubscribeFn = () => Promise<void>;\n\nexport interface TopicPublishOptions {\n  retain?: boolean;\n  params?: Record<string, string>;\n}\n\n// biome-ignore lint/suspicious/noEmptyInterface: augmented by provider-specific modules (e.g. MqttTopicProvider)\nexport interface TopicSubscribeOptions {}\n","import { $hook } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  type SubscribeCallback,\n  TopicProvider,\n  type TopicPublishOptions,\n  type TopicSubscribeOptions,\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  protected readonly retained: Record<string, string> = {};\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   * @param options\n   */\n  public async publish(\n    topic: string,\n    message: string,\n    options?: TopicPublishOptions,\n  ): Promise<void> {\n    if (options?.retain) {\n      this.retained[topic] = message;\n    }\n\n    for (const [pattern, callbacks] of Object.entries(this.subscriptions)) {\n      if (this.topicMatches(pattern, topic)) {\n        for (const callback of callbacks) {\n          await callback(message, topic);\n        }\n      }\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    _options?: TopicSubscribeOptions,\n  ): Promise<UnSubscribeFn> {\n    if (!this.subscriptions[topic]) {\n      this.subscriptions[topic] = [];\n    }\n\n    this.subscriptions[topic].push(callback);\n\n    // Deliver retained messages matching the pattern\n    for (const [retainedTopic, retainedMessage] of Object.entries(\n      this.retained,\n    )) {\n      if (this.topicMatches(topic, retainedTopic)) {\n        await callback(retainedMessage, retainedTopic);\n      }\n    }\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  /**\n   * Check if a topic matches a subscription pattern.\n   * Supports `+` single-level wildcard.\n   */\n  protected topicMatches(pattern: string, topic: string): boolean {\n    if (pattern === topic) {\n      return true;\n    }\n\n    const patternParts = pattern.split(\"/\");\n    const topicParts = topic.split(\"/\");\n\n    if (patternParts.length !== topicParts.length) {\n      return false;\n    }\n\n    return patternParts.every(\n      (part, i) => part === \"+\" || part === topicParts[i],\n    );\n  }\n}\n","import {\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Service,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\nimport { MemoryTopicProvider } from \"../providers/MemoryTopicProvider.ts\";\nimport {\n  TopicProvider,\n  type TopicPublishOptions,\n  type UnSubscribeFn,\n} from \"../providers/TopicProvider.ts\";\n\n/**\n * Creates a topic primitive 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: TopicPrimitiveOptions<T>,\n): TopicPrimitive<T> => {\n  return createPrimitive(TopicPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface TopicPrimitiveOptions<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   * Whether the last published message should be retained and delivered to new subscribers.\n   *\n   * When enabled, the provider stores the last message for this topic.\n   * New subscribers immediately receive the retained message upon subscribing.\n   *\n   * Supported by Memory, Redis, and MQTT providers.\n   *\n   * @default false\n   */\n  retain?: boolean;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class TopicPrimitive<T extends TopicMessageSchema> extends Primitive<\n  TopicPrimitiveOptions<T>\n> {\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(\n    message: T extends { params: TSchema }\n      ? { params: Static<T[\"params\"]>; payload: TopicMessage<T>[\"payload\"] }\n      : TopicMessage<T>[\"payload\"],\n  ): Promise<void> {\n    const hasParams = this.options.schema.params;\n    const payload = hasParams ? (message as any).payload : message;\n    const params = hasParams ? (message as any).params : undefined;\n\n    await this.provider.publishMessage<T>(\n      this.name,\n      this.options.schema.payload,\n      payload,\n      {\n        retain: this.options.retain,\n        mqtt: (this.options as any).mqtt,\n        params,\n      } as TopicPublishOptions,\n    );\n  }\n\n  public async subscribe(handler: TopicHandler<T>): Promise<UnSubscribeFn> {\n    return this.provider.subscribeHandler<T>(\n      this.name,\n      this.options.schema.payload,\n      handler,\n      { mqtt: (this.options as any).mqtt },\n    );\n  }\n\n  public async wait(\n    options: TopicWaitOptions<T> = {},\n  ): Promise<TopicMessage<T>> {\n    return this.provider.waitForMessage<T>(\n      this.name,\n      this.options.schema.payload,\n      options,\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\n$topic[KIND] = TopicPrimitive;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface TopicMessage<T extends TopicMessageSchema> {\n  payload: Static<T[\"payload\"]>;\n  params: T extends { params: TSchema } ? Static<T[\"params\"]> : never;\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  params?: 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 \"./primitives/$subscriber.ts\";\nimport { $topic } from \"./primitives/$topic.ts\";\nimport { MemoryTopicProvider } from \"./providers/MemoryTopicProvider.ts\";\nimport { TopicProvider } from \"./providers/TopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./errors/TopicTimeoutError.ts\";\nexport * from \"./primitives/$subscriber.ts\";\nexport * from \"./primitives/$topic.ts\";\nexport * from \"./providers/MemoryTopicProvider.ts\";\nexport * from \"./providers/TopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Publish/subscribe messaging for event-driven architectures.\n *\n * **Features:**\n * - Pub/sub topics with type-safe messages\n * - Topic subscription handlers\n * - Multiple subscriber support\n * - Message filtering and routing\n * - Providers: Memory (dev), Redis (production)\n *\n * @module alepha.topic\n */\nexport const AlephaTopic = $module({\n  name: \"alepha.topic\",\n  primitives: [$topic, $subscriber],\n  services: [TopicProvider],\n  variants: [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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/topic/core/primitives/$subscriber.ts","../../../src/topic/core/errors/TopicTimeoutError.ts","../../../src/topic/core/providers/TopicProvider.ts","../../../src/topic/core/providers/MemoryTopicProvider.ts","../../../src/topic/core/primitives/$topic.ts","../../../src/topic/core/index.ts"],"sourcesContent":["import {\n  createPrimitive,\n  KIND,\n  PipelinePrimitive,\n  type PipelinePrimitiveOptions,\n} from \"alepha\";\nimport type {\n  TopicHandler,\n  TopicMessageSchema,\n  TopicPrimitive,\n} from \"./$topic.ts\";\n\n/**\n * Creates a subscriber primitive 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 primitive\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: SubscriberPrimitiveOptions<T>,\n): SubscriberPrimitive<T> => {\n  return createPrimitive(SubscriberPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface SubscriberPrimitiveOptions<T extends TopicMessageSchema>\n  extends PipelinePrimitiveOptions {\n  /**\n   * The topic primitive 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 primitive\n   *   handler: async (message) => { } // Process messages here\n   * });\n   * ```\n   */\n  topic: TopicPrimitive<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 SubscriberPrimitive<\n  T extends TopicMessageSchema,\n> extends PipelinePrimitive<SubscriberPrimitiveOptions<T>> {}\n\n$subscriber[KIND] = SubscriberPrimitive;\n","import { AlephaError } from \"alepha\";\n\nexport class TopicTimeoutError extends AlephaError {\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 { DateTimeProvider, type Timeout } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { TemplatedPathParser } from \"alepha/router\";\nimport { TopicTimeoutError } from \"../errors/TopicTimeoutError.ts\";\nimport { $subscriber } from \"../primitives/$subscriber.ts\";\nimport {\n  $topic,\n  type TopicHandler,\n  type TopicMessage,\n  type TopicMessageSchema,\n  type TopicWaitOptions,\n} from \"../primitives/$topic.ts\";\n\n/**\n * Base class for topic providers.\n */\nexport abstract class TopicProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n\n  /**\n   * Publish a raw 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(\n    topic: string,\n    message: string,\n    options?: TopicPublishOptions,\n  ): Promise<void>;\n\n  /**\n   * Subscribe to a topic with a raw callback.\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    options?: TopicSubscribeOptions,\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   * Encode and publish a typed message to a topic.\n   */\n  public async publishMessage<T extends TopicMessageSchema>(\n    name: string,\n    schema: T[\"payload\"],\n    payload: TopicMessage<T>[\"payload\"],\n    options?: TopicPublishOptions,\n  ): Promise<void> {\n    let topicName = name;\n    if (options?.params) {\n      const parser = new TemplatedPathParser(name);\n      topicName = parser.interpolate(options.params);\n    }\n\n    await this.publish(\n      topicName,\n      JSON.stringify({\n        payload: this.alepha.codec.encode(schema, payload),\n      }),\n      options,\n    );\n  }\n\n  /**\n   * Parse a raw message string into a typed topic message.\n   */\n  public parseMessage<T extends TopicMessageSchema>(\n    schema: T[\"payload\"],\n    message: string,\n  ): TopicMessage<T> {\n    const { payload } = JSON.parse(message);\n    return {\n      payload: this.alepha.codec.decode(\n        schema,\n        payload,\n      ) as TopicMessage<T>[\"payload\"],\n    } as TopicMessage<T>;\n  }\n\n  /**\n   * Subscribe a typed handler to a topic, with error wrapping and message parsing.\n   */\n  public async subscribeHandler<T extends TopicMessageSchema>(\n    name: string,\n    schema: T[\"payload\"],\n    handler: TopicHandler<T>,\n    options?: TopicSubscribeOptions,\n  ): Promise<UnSubscribeFn> {\n    const parser = new TemplatedPathParser(name);\n    const subscribeTopic = parser.hasParams\n      ? parser.wildcardize(this.wildcardChar())\n      : name;\n\n    return this.subscribe(\n      subscribeTopic,\n      async (message, receivedTopic?: string) => {\n        try {\n          const parsed = this.parseMessage<T>(schema, message);\n\n          if (parser.hasParams && receivedTopic) {\n            const params = parser.extract(receivedTopic) ?? {};\n            await handler({ ...parsed, params } as TopicMessage<T>);\n          } else {\n            await handler(parsed);\n          }\n        } catch (error) {\n          this.log.error(\"Message processing has failed\", error);\n        }\n      },\n      options,\n    );\n  }\n\n  /**\n   * Wait for a single message matching an optional filter, with timeout.\n   */\n  public async waitForMessage<T extends TopicMessageSchema>(\n    name: string,\n    schema: T[\"payload\"],\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; clear?: () => void } = {};\n\n      (async () => {\n        const clear = await this.subscribe(name, (raw) => {\n          const message = this.parseMessage<T>(schema, raw);\n          if (!filter(message)) {\n            return;\n          }\n\n          ref.timeout?.clear();\n          if (ref.clear) {\n            ref.clear();\n          }\n          resolve(message);\n        });\n\n        ref.clear = clear;\n\n        const timeoutDuration = options.timeout ?? [10, \"seconds\"];\n\n        ref.timeout = this.dateTimeProvider.createTimeout(() => {\n          clear();\n          reject(\n            new TopicTimeoutError(\n              name,\n              this.dateTimeProvider.duration(timeoutDuration).asMilliseconds(),\n            ),\n          );\n        }, timeoutDuration);\n      })();\n    });\n  }\n\n  /**\n   * The wildcard character used for pattern subscriptions.\n   * Override in subclasses for provider-specific wildcards.\n   */\n  protected wildcardChar(): string {\n    return \"+\";\n  }\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.primitives($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.primitives($subscriber);\n    for (const subscriber of subscribers) {\n      if (subscriber.options.topic.provider !== this) {\n        continue;\n      }\n\n      const handler = subscriber.handler.run.bind(subscriber.handler);\n      handlers.push(() => subscriber.options.topic.subscribe(handler));\n    }\n\n    return handlers;\n  }\n}\n\nexport type SubscribeCallback = (\n  message: string,\n  topic?: string,\n) => Promise<void> | void;\n\nexport type UnSubscribeFn = () => Promise<void>;\n\nexport interface TopicPublishOptions {\n  retain?: boolean;\n  params?: Record<string, string>;\n}\n\n// biome-ignore lint/suspicious/noEmptyInterface: augmented by provider-specific modules (e.g. MqttTopicProvider)\nexport interface TopicSubscribeOptions {}\n","import { $hook } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  type SubscribeCallback,\n  TopicProvider,\n  type TopicPublishOptions,\n  type TopicSubscribeOptions,\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  protected readonly retained: Record<string, string> = {};\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   * @param options\n   */\n  public async publish(\n    topic: string,\n    message: string,\n    options?: TopicPublishOptions,\n  ): Promise<void> {\n    if (options?.retain) {\n      this.retained[topic] = message;\n    }\n\n    for (const [pattern, callbacks] of Object.entries(this.subscriptions)) {\n      if (this.topicMatches(pattern, topic)) {\n        for (const callback of callbacks) {\n          await callback(message, topic);\n        }\n      }\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    _options?: TopicSubscribeOptions,\n  ): Promise<UnSubscribeFn> {\n    if (!this.subscriptions[topic]) {\n      this.subscriptions[topic] = [];\n    }\n\n    this.subscriptions[topic].push(callback);\n\n    // Deliver retained messages matching the pattern\n    for (const [retainedTopic, retainedMessage] of Object.entries(\n      this.retained,\n    )) {\n      if (this.topicMatches(topic, retainedTopic)) {\n        await callback(retainedMessage, retainedTopic);\n      }\n    }\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  /**\n   * Check if a topic matches a subscription pattern.\n   * Supports `+` single-level wildcard.\n   */\n  protected topicMatches(pattern: string, topic: string): boolean {\n    if (pattern === topic) {\n      return true;\n    }\n\n    const patternParts = pattern.split(\"/\");\n    const topicParts = topic.split(\"/\");\n\n    if (patternParts.length !== topicParts.length) {\n      return false;\n    }\n\n    return patternParts.every(\n      (part, i) => part === \"+\" || part === topicParts[i],\n    );\n  }\n}\n","import {\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Service,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\nimport { MemoryTopicProvider } from \"../providers/MemoryTopicProvider.ts\";\nimport {\n  TopicProvider,\n  type TopicPublishOptions,\n  type UnSubscribeFn,\n} from \"../providers/TopicProvider.ts\";\n\n/**\n * Creates a topic primitive 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: TopicPrimitiveOptions<T>,\n): TopicPrimitive<T> => {\n  return createPrimitive(TopicPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface TopicPrimitiveOptions<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   * Whether the last published message should be retained and delivered to new subscribers.\n   *\n   * When enabled, the provider stores the last message for this topic.\n   * New subscribers immediately receive the retained message upon subscribing.\n   *\n   * Supported by Memory, Redis, and MQTT providers.\n   *\n   * @default false\n   */\n  retain?: boolean;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class TopicPrimitive<T extends TopicMessageSchema> extends Primitive<\n  TopicPrimitiveOptions<T>\n> {\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(\n    message: T extends { params: TSchema }\n      ? { params: Static<T[\"params\"]>; payload: TopicMessage<T>[\"payload\"] }\n      : TopicMessage<T>[\"payload\"],\n  ): Promise<void> {\n    const hasParams = this.options.schema.params;\n    const payload = hasParams ? (message as any).payload : message;\n    const params = hasParams ? (message as any).params : undefined;\n\n    await this.provider.publishMessage<T>(\n      this.name,\n      this.options.schema.payload,\n      payload,\n      {\n        retain: this.options.retain,\n        mqtt: (this.options as any).mqtt,\n        params,\n      } as TopicPublishOptions,\n    );\n  }\n\n  public async subscribe(handler: TopicHandler<T>): Promise<UnSubscribeFn> {\n    return this.provider.subscribeHandler<T>(\n      this.name,\n      this.options.schema.payload,\n      handler,\n      { mqtt: (this.options as any).mqtt },\n    );\n  }\n\n  public async wait(\n    options: TopicWaitOptions<T> = {},\n  ): Promise<TopicMessage<T>> {\n    return this.provider.waitForMessage<T>(\n      this.name,\n      this.options.schema.payload,\n      options,\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\n$topic[KIND] = TopicPrimitive;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface TopicMessage<T extends TopicMessageSchema> {\n  payload: Static<T[\"payload\"]>;\n  params: T extends { params: TSchema } ? Static<T[\"params\"]> : never;\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  params?: 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 \"./primitives/$subscriber.ts\";\nimport { $topic } from \"./primitives/$topic.ts\";\nimport { MemoryTopicProvider } from \"./providers/MemoryTopicProvider.ts\";\nimport { TopicProvider } from \"./providers/TopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./errors/TopicTimeoutError.ts\";\nexport * from \"./primitives/$subscriber.ts\";\nexport * from \"./primitives/$topic.ts\";\nexport * from \"./providers/MemoryTopicProvider.ts\";\nexport * from \"./providers/TopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Publish/subscribe messaging for event-driven architectures.\n *\n * **Features:**\n * - Pub/sub topics with type-safe messages\n * - Topic subscription handlers\n * - Multiple subscriber support\n * - Message filtering and routing\n * - Providers: Memory (dev), Redis (production)\n *\n * @module alepha.topic\n */\nexport const AlephaTopic = $module({\n  name: \"alepha.topic\",\n  primitives: [$topic, $subscriber],\n  services: [TopicProvider],\n  variants: [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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"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "alepha",
   "description": "Easy-to-use modern TypeScript framework for building many kind of applications.",
   "author": "Feunard",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
@@ -108,16 +108,6 @@
       "import": "./dist/api/files/index.js",
       "default": "./dist/api/files/index.js"
     },
-    "./api/invitations": {
-      "types": "./dist/api/invitations/index.d.ts",
-      "import": "./dist/api/invitations/index.js",
-      "default": "./dist/api/invitations/index.js"
-    },
-    "./api/issues": {
-      "types": "./dist/api/issues/index.d.ts",
-      "import": "./dist/api/issues/index.js",
-      "default": "./dist/api/issues/index.js"
-    },
     "./api/jobs": {
       "types": "./dist/api/jobs/index.d.ts",
       "react-native": "./dist/api/jobs/index.browser.js",
@@ -156,11 +146,6 @@
       "import": "./dist/api/payments/index.js",
       "default": "./dist/api/payments/index.js"
     },
-    "./api/subscriptions": {
-      "types": "./dist/api/subscriptions/index.d.ts",
-      "import": "./dist/api/subscriptions/index.js",
-      "default": "./dist/api/subscriptions/index.js"
-    },
     "./api/users": {
       "types": "./dist/api/users/index.d.ts",
       "react-native": "./dist/api/users/index.browser.js",
@@ -175,13 +160,6 @@
       "import": "./dist/api/verifications/index.js",
       "default": "./dist/api/verifications/index.js"
     },
-    "./api/workflows": {
-      "types": "./dist/api/workflows/index.d.ts",
-      "react-native": "./dist/api/workflows/index.browser.js",
-      "browser": "./dist/api/workflows/index.browser.js",
-      "import": "./dist/api/workflows/index.js",
-      "default": "./dist/api/workflows/index.js"
-    },
     "./batch": {
       "types": "./dist/batch/index.d.ts",
       "import": "./dist/batch/index.js",
@@ -376,6 +354,11 @@
       "import": "./dist/react/testing/index.js",
       "default": "./dist/react/testing/index.js"
     },
+    "./react/ui": {
+      "types": "./dist/react/ui/index.d.ts",
+      "import": "./dist/react/ui/index.js",
+      "default": "./dist/react/ui/index.js"
+    },
     "./react/websocket": {
       "types": "./dist/react/websocket/index.d.ts",
       "import": "./dist/react/websocket/index.js",

package/src/api/files/jobs/FileJobs.ts

@@ -6,8 +6,9 @@ export class FileJobs {
   protected readonly fileService = $inject(FileService);
 
   public readonly purgeFiles = $scheduler({
+    name: "api:files:purgeFiles",
     description: "Purge files that are marked for deletion",
-    cron: "0 0 * * *", // Every day at midnight
+    cron: "0 * * * *", // Hourly at minute 0
     handler: async () => {
       const files = await this.fileService.findExpiredFiles();