alepha 0.13.7 → 0.14.0

package/dist/topic/{index.d.ts → core/index.d.ts}

@@ -3,14 +3,14 @@ import { Alepha, KIND, Primitive, Service, Static, TSchema } from "alepha";
 import { DateTimeProvider, DurationLike } from "alepha/datetime";
 import * as alepha_logger0 from "alepha/logger";
 
-//#region ../../src/topic/errors/TopicTimeoutError.d.ts
+//#region ../../src/topic/core/errors/TopicTimeoutError.d.ts
 declare class TopicTimeoutError extends Error {
   readonly topic: string;
   readonly timeout: number;
   constructor(topic: string, timeout: number);
 }
 //#endregion
-//#region ../../src/topic/providers/TopicProvider.d.ts
+//#region ../../src/topic/core/providers/TopicProvider.d.ts
 /**
  * Base class for topic providers.
  */
@@ -44,7 +44,7 @@ declare abstract class TopicProvider {
 type SubscribeCallback = (message: string) => Promise<void> | void;
 type UnSubscribeFn = () => Promise<void>;
 //#endregion
-//#region ../../src/topic/primitives/$topic.d.ts
+//#region ../../src/topic/core/primitives/$topic.d.ts
 /**
  * Creates a topic primitive for publish/subscribe messaging and event-driven architecture.
  *
@@ -287,7 +287,7 @@ interface TopicMessageSchema {
 }
 type TopicHandler<T extends TopicMessageSchema = TopicMessageSchema> = (message: TopicMessage<T>) => unknown;
 //#endregion
-//#region ../../src/topic/primitives/$subscriber.d.ts
+//#region ../../src/topic/core/primitives/$subscriber.d.ts
 /**
  * Creates a subscriber primitive to listen for messages from a specific topic.
  *
@@ -480,7 +480,7 @@ interface SubscriberPrimitiveOptions<T extends TopicMessageSchema> {
 }
 declare class SubscriberPrimitive<T extends TopicMessageSchema> extends Primitive<SubscriberPrimitiveOptions<T>> {}
 //#endregion
-//#region ../../src/topic/providers/MemoryTopicProvider.d.ts
+//#region ../../src/topic/core/providers/MemoryTopicProvider.d.ts
 declare class MemoryTopicProvider extends TopicProvider {
   protected readonly log: alepha_logger0.Logger;
   protected readonly subscriptions: Record<string, SubscribeCallback[]>;
@@ -507,7 +507,7 @@ declare class MemoryTopicProvider extends TopicProvider {
   unsubscribe(topic: string): Promise<void>;
 }
 //#endregion
-//#region ../../src/topic/index.d.ts
+//#region ../../src/topic/core/index.d.ts
 /**
  * Generic interface for pub/sub messaging.
  * Gives you the ability to create topics and subscribers.

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/topic/core/errors/TopicTimeoutError.ts","../../../src/topic/core/providers/TopicProvider.ts","../../../src/topic/core/primitives/$topic.ts","../../../src/topic/core/primitives/$subscriber.ts","../../../src/topic/core/providers/MemoryTopicProvider.ts","../../../src/topic/core/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/topic/{index.js → core/index.js}

@@ -2,7 +2,7 @@ import { $hook, $inject, $module, Alepha, KIND, Primitive, createPrimitive } fro
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 
-//#region ../../src/topic/primitives/$subscriber.ts
+//#region ../../src/topic/core/primitives/$subscriber.ts
 /**
 * Creates a subscriber primitive to listen for messages from a specific topic.
 *
@@ -65,7 +65,7 @@ var SubscriberPrimitive = class extends Primitive {};
 $subscriber[KIND] = SubscriberPrimitive;
 
 //#endregion
-//#region ../../src/topic/errors/TopicTimeoutError.ts
+//#region ../../src/topic/core/errors/TopicTimeoutError.ts
 var TopicTimeoutError = class extends Error {
 	topic;
 	timeout;
@@ -77,7 +77,7 @@ var TopicTimeoutError = class extends Error {
 };
 
 //#endregion
-//#region ../../src/topic/providers/TopicProvider.ts
+//#region ../../src/topic/core/providers/TopicProvider.ts
 /**
 * Base class for topic providers.
 */
@@ -104,7 +104,7 @@ var TopicProvider = class {
 };
 
 //#endregion
-//#region ../../src/topic/providers/MemoryTopicProvider.ts
+//#region ../../src/topic/core/providers/MemoryTopicProvider.ts
 var MemoryTopicProvider = class extends TopicProvider {
 	log = $logger();
 	subscriptions = {};
@@ -155,7 +155,7 @@ var MemoryTopicProvider = class extends TopicProvider {
 };
 
 //#endregion
-//#region ../../src/topic/primitives/$topic.ts
+//#region ../../src/topic/core/primitives/$topic.ts
 /**
 * Creates a topic primitive for publish/subscribe messaging and event-driven architecture.
 *
@@ -249,7 +249,7 @@ var TopicPrimitive = class extends Primitive {
 $topic[KIND] = TopicPrimitive;
 
 //#endregion
-//#region ../../src/topic/index.ts
+//#region ../../src/topic/core/index.ts
 /**
 * Generic interface for pub/sub messaging.
 * Gives you the ability to create topics and subscribers.

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["handlers: Array<() => Promise<unknown>>","ref: { timeout?: Timeout }"],"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 { createPrimitive, KIND, Primitive } 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  /**\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 Primitive<SubscriberPrimitiveOptions<T>> {}\n\n$subscriber[KIND] = SubscriberPrimitive;\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 \"../primitives/$subscriber.ts\";\nimport { $topic } from \"../primitives/$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.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      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  createPrimitive,\n  KIND,\n  Primitive,\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 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// ---------------------------------------------------------------------------------------------------------------------\n\nexport class TopicPrimitive<T extends TopicMessageSchema> extends Primitive<\n  TopicPrimitiveOptions<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] = TopicPrimitive;\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 \"./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 * 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  primitives: [$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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"}

package/dist/{topic-redis → topic/redis}/index.d.ts

@@ -4,7 +4,7 @@ import { SubscribeCallback, TopicProvider, UnSubscribeFn } from "alepha/topic";
 import * as alepha_logger0 from "alepha/logger";
 import { RedisProvider, RedisSubscriberProvider } from "alepha/redis";
 
-//#region ../../src/topic-redis/providers/RedisTopicProvider.d.ts
+//#region ../../src/topic/redis/providers/RedisTopicProvider.d.ts
 declare class RedisTopicProvider extends TopicProvider {
   protected readonly env: {
     REDIS_TOPIC_PREFIX: string;
@@ -29,7 +29,7 @@ declare class RedisTopicProvider extends TopicProvider {
   unsubscribe(name: string, callback?: SubscribeCallback): Promise<void>;
 }
 //#endregion
-//#region ../../src/topic-redis/index.d.ts
+//#region ../../src/topic/redis/index.d.ts
 /**
  * Plugin for Alepha Topic that provides Redis pub/sub capabilities.
  *

package/dist/topic/redis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/topic/redis/providers/RedisTopicProvider.ts","../../../src/topic/redis/index.ts"],"sourcesContent":[],"mappings":";;;;;;;cAea,kBAAA,SAA2B,aAAA;;;;EAA3B,mBAAA,MAAmB,EAEL,MAFK;EAEL,mBAAA,aAAA,EACO,aADP;EACO,mBAAA,uBAAA,EACU,uBADV;EACU,mBAAA,GAAA,EAAA,cAAA,CAEpB,MAFoB;EAAA,mBAEpB,KAAA,EAAA,OAAA,CAEE,aAFF,CAAA,OAAA,CAAA;EAAA,MAEE,CAAA,KAAA,EAAA,MAAA,CAAA,EAAA,MAAA;EAoB8B;;;EAUnD,OAAA,CAAA,KAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,EAVmD,OAUnD,CAAA,IAAA,CAAA;EAYU;;;EAlDsC,SAAA,CAAA,IAAA,EAAA,MAAA,EAAA,QAAA,EAqCvC,iBArCuC,CAAA,EAsChD,OAtCgD,CAsCxC,aAtCwC,CAAA;;;;ECCxC,WAAA,CAAA,IAAA,EAAA,MAWX,EAAA,QAX2B,CAW3B,EDsCa,iBCjDc,CAAA,EDkDxB,OClDwB,CAAA,IAAA,CAAA;;;;;;;;;;ADDhB,cCCA,gBDDmB,ECCH,OAAA,CAAA,ODDG,CCY9B,OAAA,CAX2B,MAAA,CDDG"}

package/dist/{topic-redis → topic/redis}/index.js

@@ -3,7 +3,7 @@ import { AlephaTopic, TopicProvider } from "alepha/topic";
 import { $logger } from "alepha/logger";
 import { RedisProvider, RedisSubscriberProvider } from "alepha/redis";
 
-//#region ../../src/topic-redis/providers/RedisTopicProvider.ts
+//#region ../../src/topic/redis/providers/RedisTopicProvider.ts
 const envSchema = t.object({ REDIS_TOPIC_PREFIX: t.text({ default: "topic" }) });
 var RedisTopicProvider = class extends TopicProvider {
 	env = $env(envSchema);
@@ -48,7 +48,7 @@ var RedisTopicProvider = class extends TopicProvider {
 };
 
 //#endregion
-//#region ../../src/topic-redis/index.ts
+//#region ../../src/topic/redis/index.ts
 /**
 * Plugin for Alepha Topic that provides Redis pub/sub capabilities.
 *

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/topic/redis/providers/RedisTopicProvider.ts","../../../src/topic/redis/index.ts"],"sourcesContent":["import { $env, $hook, $inject, Alepha, t } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { RedisProvider, RedisSubscriberProvider } from \"alepha/redis\";\nimport {\n  type SubscribeCallback,\n  TopicProvider,\n  type UnSubscribeFn,\n} from \"alepha/topic\";\n\nconst envSchema = t.object({\n  REDIS_TOPIC_PREFIX: t.text({\n    default: \"topic\",\n  }),\n});\n\nexport class RedisTopicProvider extends TopicProvider {\n  protected readonly env = $env(envSchema);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly redisProvider = $inject(RedisProvider);\n  protected readonly redisSubscriberProvider = $inject(RedisSubscriberProvider);\n\n  protected readonly log = $logger();\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  public prefix(queue: string): string {\n    return `${this.env.REDIS_TOPIC_PREFIX}:${queue}`;\n  }\n\n  /**\n   * Publish a message to a topic.\n   */\n  public async publish(topic: string, message: string): Promise<void> {\n    await this.redisProvider.publisher.publish(this.prefix(topic), message);\n  }\n\n  /**\n   * Subscribe to a topic.\n   */\n  public async subscribe(\n    name: string,\n    callback: SubscribeCallback,\n  ): Promise<UnSubscribeFn> {\n    const topic = this.prefix(name);\n    await this.redisSubscriberProvider.subscriber.subscribe(topic, callback);\n\n    return () => this.unsubscribe(name, callback);\n  }\n\n  /**\n   * Unsubscribe from a topic.\n   */\n  public async unsubscribe(\n    name: string,\n    callback?: SubscribeCallback,\n  ): Promise<void> {\n    const topic = this.prefix(name);\n\n    await this.redisSubscriberProvider.subscriber.unsubscribe(topic, callback);\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaTopic, TopicProvider } from \"alepha/topic\";\nimport { RedisTopicProvider } from \"./providers/RedisTopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisTopicProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Topic that provides Redis pub/sub capabilities.\n *\n * @see {@link RedisTopicProvider}\n * @module alepha.topic.redis\n */\nexport const AlephaTopicRedis = $module({\n  name: \"alepha.topic.redis\",\n  services: [RedisTopicProvider],\n  register: (alepha: Alepha): Alepha =>\n    alepha\n      .with({\n        optional: true,\n        provide: TopicProvider,\n        use: RedisTopicProvider,\n      })\n      .with(AlephaTopic),\n});\n"],"mappings":";;;;;;AASA,MAAM,YAAY,EAAE,OAAO,EACzB,oBAAoB,EAAE,KAAK,EACzB,SAAS,SACV,CAAC,EACH,CAAC;AAEF,IAAa,qBAAb,cAAwC,cAAc;CACpD,AAAmB,MAAM,KAAK,UAAU;CACxC,AAAmB,SAAS,QAAQ,OAAO;CAC3C,AAAmB,gBAAgB,QAAQ,cAAc;CACzD,AAAmB,0BAA0B,QAAQ,wBAAwB;CAE7E,AAAmB,MAAM,SAAS;CAElC,AAAmB,QAAQ,MAAM;EAC/B,IAAI;EACJ,SAAS,YAAY;GACnB,MAAM,cAAc,KAAK,aAAa;AACtC,OAAI,YAAY,QAAQ;AACtB,UAAM,QAAQ,IAAI,YAAY,KAAK,OAAO,IAAI,CAAC,CAAC;AAChD,SAAK,MAAM,cAAc,YACvB,MAAK,IAAI,MAAM,wBAAwB,WAAW,KAAK,GAAG;;;EAIjE,CAAC;CAEF,AAAO,OAAO,OAAuB;AACnC,SAAO,GAAG,KAAK,IAAI,mBAAmB,GAAG;;;;;CAM3C,MAAa,QAAQ,OAAe,SAAgC;AAClE,QAAM,KAAK,cAAc,UAAU,QAAQ,KAAK,OAAO,MAAM,EAAE,QAAQ;;;;;CAMzE,MAAa,UACX,MACA,UACwB;EACxB,MAAM,QAAQ,KAAK,OAAO,KAAK;AAC/B,QAAM,KAAK,wBAAwB,WAAW,UAAU,OAAO,SAAS;AAExE,eAAa,KAAK,YAAY,MAAM,SAAS;;;;;CAM/C,MAAa,YACX,MACA,UACe;EACf,MAAM,QAAQ,KAAK,OAAO,KAAK;AAE/B,QAAM,KAAK,wBAAwB,WAAW,YAAY,OAAO,SAAS;;;;;;;;;;;;ACrD9E,MAAa,mBAAmB,QAAQ;CACtC,MAAM;CACN,UAAU,CAAC,mBAAmB;CAC9B,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC,CACD,KAAK,YAAY;CACvB,CAAC"}

package/dist/vite/index.d.ts

@@ -181,6 +181,17 @@ interface CopyAssetsOptions {
    * Output directory for copied assets.
    */
   distDir: string;
+  /**
+   * @default process.cwd()
+   */
+  root?: string;
+  /**
+   * Add Runner for logging (@see Alepha CLI)
+   */
+  run?: (opts: {
+    name: string;
+    handler: () => Promise<void>;
+  }) => Promise<string>;
 }
 /**
  * Copy assets from Alepha packages to the build output directory.
@@ -201,6 +212,13 @@ interface GenerateCloudflareOptions {
    * @default "dist"
    */
   distDir?: string;
+  /**
+   * Additional Wrangler configuration options to merge into wrangler.jsonc.
+   */
+  config?: WranglerConfig;
+}
+interface WranglerConfig {
+  [key: string]: any;
 }
 /**
  * Generate Cloudflare Workers deployment configuration.
@@ -452,7 +470,7 @@ interface ViteAlephaBuildOptions {
    *
    * @default false
    */
-  cloudflare?: boolean;
+  cloudflare?: boolean | WranglerConfig;
   /**
    * If true, the build will be optimized for Docker deployment.
    * Additionally, it will generate a Dockerfile in the dist directory.
@@ -536,7 +554,8 @@ declare global {
  *
  * @module alepha.vite
  */
+//# sourceMappingURL=index.d.ts.map
 
 //#endregion
-export { AlephaBuildMode, AlephaRunner, AlephaRunnerOptions, AlephaRunnerState, BufferedLogger, BuildClientOptions, BuildServerOptions, BuildServerResult, CopyAssetsOptions, GenerateCloudflareOptions, GenerateDockerOptions, GenerateExternalsOptions, GenerateSitemapOptions, GenerateVercelOptions, PrerenderPagesOptions, PrerenderPagesResult, VercelConfig, ViteAlephaBuildOptions, ViteAlephaDevOptions, ViteAlephaOptions, ViteCompressOptions, boot, buildClient, buildServer, compressFile, copyAssets, createAlephaRunner, createBufferedLogger, generateCloudflare, generateDocker, generateExternals, generateSitemap, generateVercel, isViteInternalPath, prerenderPages, viteAlepha, viteAlephaBuild, viteAlephaDev, viteCompress };
+export { AlephaBuildMode, AlephaRunner, AlephaRunnerOptions, AlephaRunnerState, BufferedLogger, BuildClientOptions, BuildServerOptions, BuildServerResult, CopyAssetsOptions, GenerateCloudflareOptions, GenerateDockerOptions, GenerateExternalsOptions, GenerateSitemapOptions, GenerateVercelOptions, PrerenderPagesOptions, PrerenderPagesResult, VercelConfig, ViteAlephaBuildOptions, ViteAlephaDevOptions, ViteAlephaOptions, ViteCompressOptions, WranglerConfig, boot, buildClient, buildServer, compressFile, copyAssets, createAlephaRunner, createBufferedLogger, generateCloudflare, generateDocker, generateExternals, generateSitemap, generateVercel, isViteInternalPath, prerenderPages, viteAlepha, viteAlephaBuild, viteAlephaDev, viteCompress };
 //# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/vite/helpers/boot.ts","../../src/vite/helpers/createBufferedLogger.ts","../../src/vite/plugins/viteCompress.ts","../../src/vite/tasks/buildClient.ts","../../src/vite/tasks/buildServer.ts","../../src/vite/tasks/copyAssets.ts","../../src/vite/tasks/generateCloudflare.ts","../../src/vite/tasks/generateDocker.ts","../../src/vite/tasks/generateExternals.ts","../../src/vite/tasks/generateSitemap.ts","../../src/vite/tasks/generateVercel.ts","../../src/vite/tasks/prerenderPages.ts","../../src/vite/tasks/runAlepha.ts","../../src/vite/plugins/viteAlephaBuild.ts","../../src/vite/plugins/viteAlephaDev.ts","../../src/vite/plugins/viteAlepha.ts","../../src/vite/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/vite/index.js

@@ -352,7 +352,7 @@ async function buildServer(opts) {
 	if (opts.clientDir) template = `__alepha.set("alepha.react.server.template", \`${(await readFile(`${opts.distDir}/${opts.clientDir}/index.html`, "utf-8")).replace(/>\s*</g, "><").trim()}\`);\n`;
 	await writeFile(`${opts.distDir}/index.js`, `// This file was automatically generated. DO NOT MODIFY.
 // Changes to this file will be lost when the code is regenerated.
-\nimport './server/${entryFile}';${template}`.trim());
+\nimport './server/${entryFile}';\n\n${template}`.trim());
 	return { entryFile };
 }
 /**
@@ -399,13 +399,20 @@ const importAlepha = async (entry, options) => {
 * Used by modules like AlephaServerSwagger to distribute UI files.
 */
 async function copyAssets(opts) {
-	const root = process.cwd();
+	const root = opts.root ?? process.cwd();
 	const assets = (await importAlepha(opts.entry)).store.get("alepha.build.assets");
 	if (!assets || assets.length === 0) return;
-	const require = createRequire(join(root, opts.entry));
-	const buildAssetsDir = join(root, `${opts.distDir}/assets`);
-	await mkdir(buildAssetsDir).catch(() => null);
-	for (const pkgName of assets ?? []) await cp(resolve(dirname(require.resolve(`${pkgName}/package.json`)), "assets"), buildAssetsDir, { recursive: true });
+	const fn = async () => {
+		const require = createRequire(join(root, opts.entry));
+		const buildAssetsDir = join(root, `${opts.distDir}/assets`);
+		await mkdir(buildAssetsDir).catch(() => null);
+		for (const pkgName of assets ?? []) await cp(resolve(dirname(require.resolve(`${pkgName}/package.json`)), "assets"), buildAssetsDir, { recursive: true });
+	};
+	if (opts.run) await opts.run({
+		name: "copy assets",
+		handler: fn
+	});
+	else await fn();
 }
 
 //#endregion
@@ -421,20 +428,33 @@ const WARNING_COMMENT$1 = "// This file was automatically generated. DO NOT MODI
 async function generateCloudflare(opts = {}) {
 	const distDir = opts.distDir ?? "dist";
 	const root = process.cwd();
-	await writeWranglerConfig(root, distDir, basename(root));
-	await writeWorkerEntryPoint(root, distDir);
-}
-/**
-* Write the wrangler.jsonc configuration file for Cloudflare Workers
-*/
-async function writeWranglerConfig(root, distDir, name) {
+	const name = basename(root);
+	const hasAssets = await access(join(root, distDir, "public")).then(() => true).catch(() => false);
 	const wrangler = {
 		name,
 		main: "./main.cloudflare.js",
 		compatibility_flags: ["nodejs_compat"],
-		compatibility_date: "2025-11-17"
+		compatibility_date: "2025-11-17",
+		...opts.config
+	};
+	if (hasAssets) wrangler.assets ??= {
+		directory: "./public",
+		binding: "ASSETS"
 	};
+	const url = process.env.DATABASE_URL;
+	if (url?.startsWith("cloudflare-d1:")) {
+		const [name$1, id] = url.replace("cloudflare-d1://", "").replace("cloudflare-d1:", "").split(":");
+		wrangler.d1_databases = wrangler.d1_databases || [];
+		wrangler.d1_databases.push({
+			binding: name$1,
+			database_name: name$1,
+			database_id: id
+		});
+		wrangler.vars ??= {};
+		wrangler.vars.DATABASE_URL = `cloudflare-d1://${name$1}:${id}`;
+	}
 	await writeFile(join(root, distDir, "wrangler.jsonc"), JSON.stringify(wrangler, null, 2));
+	await writeWorkerEntryPoint(root, distDir);
 }
 /**
 * Write the worker entry point that bootstraps Alepha and handles fetch requests
@@ -444,9 +464,11 @@ async function writeWorkerEntryPoint(root, distDir) {
 import "./index.js";
 
 export default {
-  fetch: async (request) => {
+  fetch: async (request, env) => {
     const ctx = { req: request, res: undefined };
 
+    __alepha.set("cloudflare.env", env);
+
     await __alepha.start();
     await __alepha.events.emit("web:request", ctx);
 
@@ -769,6 +791,7 @@ var AlephaRunner = class {
 				return;
 			}
 			this.state.app.store.set("alepha.node.server", server.httpServer);
+			console.log("");
 			await this.state.app.start();
 			this.state.started = true;
 			process.env = { ...before };
@@ -867,8 +890,9 @@ async function viteAlephaBuild(options = {}) {
 	const clientDir = "public";
 	let rootConfig = {};
 	return {
-		name: "alepha-build",
+		name: "alepha:build",
 		apply: "build",
+		[OPTIONS]: options,
 		config(config, ctx) {
 			if (process.env.ALEPHA_BUILD_MODE === "cli") return;
 			if (!process.env.VITE_DOUBLE_BUILD_DONE) rootConfig = config;
@@ -945,7 +969,10 @@ async function viteAlephaBuild(options = {}) {
 				clientDir,
 				config: typeof options.vercel === "boolean" ? {} : options.vercel
 			});
-			if (options.cloudflare) await generateCloudflare({ distDir });
+			if (options.cloudflare) await generateCloudflare({
+				distDir,
+				config: typeof options.cloudflare === "boolean" ? {} : options.cloudflare
+			});
 			if (options.docker) await generateDocker({
 				distDir,
 				...typeof options.docker === "boolean" ? {} : options.docker
@@ -1031,10 +1058,12 @@ async function viteAlephaDev(options = {}) {
 				next();
 			});
 			server.config.logger.info = (msg) => {
-				runner.app?.log?.info(msg.trim());
+				console.log(msg);
 			};
 			server.config.logger.clearScreen = () => {};
-			await runner.start(server);
+			return async () => {
+				await runner.start(server);
+			};
 		},
 		async closeBundle() {}
 	};