@asenajs/asena 0.7.1 → 0.8.1

package/dist/lib/server/AsenaServerFactory.d.ts

@@ -2,15 +2,50 @@ import type { AsenaServer } from './AsenaServer';
 import type { AsenaAdapter } from '../adapter';
 import type { ServerLogger } from '../logger';
 import type { Class } from './types';
+/**
+ * @description Health endpoint options for headless/hybrid deployments
+ */
+export interface HealthOptions {
+    /**
+     * Port for the health endpoint mini server
+     */
+    port: number;
+    /**
+     * Endpoint path
+     * @default '/healthz'
+     */
+    path?: string;
+}
 /**
  * @description Configuration options for AsenaServer creation
+ *
+ * `adapter` is required unless `headless: true` is set. HEADLESS mode opens
+ * no HTTP server, but microservice transports, events, schedules and configs
+ * still run - useful for internal services driven purely by microservice
+ * messages.
  */
-export interface AsenaServerOptions<A extends AsenaAdapter<any, any>> {
-    adapter: A;
+export interface AsenaServerOptions<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>> {
+    adapter?: A;
+    /**
+     * Explicit opt-in for booting without an HTTP adapter. Required when
+     * `adapter` is omitted, so a wiring bug that yields an undefined adapter
+     * fails fast instead of silently starting an HTTP-less application.
+     */
+    headless?: boolean;
     logger: ServerLogger;
     port?: number;
     components?: Class[];
     gc?: boolean;
+    health?: HealthOptions;
+    /**
+     * Replace registered components with pre-created test doubles, keyed by service name
+     * (Spring's `@MockBean`).
+     *
+     * Seeded before user components are registered, so the real class is never constructed
+     * and every dependent captures the double. Core services cannot be overridden - they
+     * have already resolved their dependencies during bootstrap phases 1-5.
+     */
+    overrides?: Record<string, object>;
 }
 /**
  * @description Factory for creating AsenaServer instances
@@ -22,5 +57,5 @@ export declare class AsenaServerFactory {
      * @param {AsenaServerOptions<A>} options - Server configuration options
      * @returns {Promise<AsenaServer<A>>} Fully configured AsenaServer instance
      */
-    static create<A extends AsenaAdapter<any, any>>(options: AsenaServerOptions<A>): Promise<AsenaServer<A>>;
+    static create<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>>(options: AsenaServerOptions<A>): Promise<AsenaServer<A>>;
 }

package/dist/lib/server/AsenaServerFactory.js

@@ -13,7 +13,11 @@ export class AsenaServerFactory {
      * @returns {Promise<AsenaServer<A>>} Fully configured AsenaServer instance
      */
     static async create(options) {
-        const { adapter, logger, port, components, gc } = options;
+        const { adapter, logger, port, components, gc, health, overrides } = options;
+        if (!adapter && !options.headless) {
+            throw new Error("AsenaServerFactory.create: no 'adapter' provided - pass an HTTP adapter, " +
+                "or set 'headless: true' to intentionally start without one");
+        }
         logger.info(`
     ___    _____  ______ _   __ ___ 
    /   |  / ___/ / ____// | / //   |
@@ -36,6 +40,18 @@ export class AsenaServerFactory {
         // Phase 6: Register user components
         const iocEngine = await coreContainer.resolve(ICoreServiceNames.IOC_ENGINE);
         iocEngine.setConfig(config);
+        // Seed overrides before any user component is registered: Container builds injection
+        // closures eagerly, so a double added later would be missed by existing dependents
+        if (overrides) {
+            const coreServiceNames = new Set(Object.values(ICoreServiceNames));
+            for (const [name, instance] of Object.entries(overrides)) {
+                if (coreServiceNames.has(name)) {
+                    throw new Error(`Cannot override core service '${name}' - core services are wired during bootstrap ` +
+                        'phases 1-5 and have already captured their dependencies by this point.');
+                }
+                coreContainer.container.overrideInstance(name, instance);
+            }
+        }
         if (components?.length) {
             const injectableComponents = components.map((comp) => {
                 const face = getTypedMetadata(ComponentConstants.InterfaceKey, comp);
@@ -56,8 +72,11 @@ export class AsenaServerFactory {
         // Resolve AsenaServer (with all dependencies injected)
         const server = await coreContainer.resolve(ICoreServiceNames.ASENA_SERVER);
         // Configure server
-        if (port)
+        // Explicit !== undefined: port 0 is meaningful (let Bun pick a free ephemeral port)
+        if (port !== undefined)
             server.port(port);
+        if (health)
+            server.health(health);
         if (gc !== undefined)
             server._gc = gc;
         return server;

package/dist/lib/server/AsenaServerFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"AsenaServerFactory.js","sourceRoot":"","sources":["../../../lib/server/AsenaServerFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAK9E,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAa1D;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B;;;;OAIG;IACI,MAAM,CAAC,KAAK,CAAC,MAAM,CACxB,OAA8B;QAE9B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;QAE1D,MAAM,CAAC,IAAI,CAAC;;;;;;;KAOX,CAAC,CAAC;QAEH,mBAAmB;QACnB,MAAM,MAAM,GAAG,MAAM,cAAc,EAAE,CAAC;QAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QAC7C,CAAC;QAED,uBAAuB;QACvB,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC;QAE1C,qCAAqC;QACrC,MAAM,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAE/C,0DAA0D;QAC1D,MAAM,aAAa,CAAC,SAAS,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;QAEhG,oCAAoC;QACpC,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,OAAO,CAAY,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAEvF,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE5B,IAAI,UAAU,EAAE,MAAM,EAAE,CAAC;YACvB,MAAM,oBAAoB,GAA0B,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBAC1E,MAAM,IAAI,GAAW,gBAAgB,CAAS,kBAAkB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;gBAErF,OAAO;oBACL,KAAK,EAAE,IAAI;oBACX,SAAS,EAAE,IAAI;iBAChB,CAAC;YACJ,CAAC,CAAC,CAAC;YAEH,MAAM,SAAS,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,MAAM,EAAE,CAAC;YAClB,MAAM,SAAS,CAAC,iBAAiB,EAAE,CAAC;QACtC,CAAC;QAED,aAAa,CAAC,QAAQ,CAAC,kBAAkB,CAAC,oBAAoB,CAAC,CAAC;QAEhE,uCAAuC;QACvC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAEtD,MAAM,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,YAAY,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QAE1F,uDAAuD;QACvD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAiB,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAE3F,mBAAmB;QACnB,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE5B,IAAI,EAAE,KAAK,SAAS;YAAG,MAAc,CAAC,GAAG,GAAG,EAAE,CAAC;QAE/C,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}
+{"version":3,"file":"AsenaServerFactory.js","sourceRoot":"","sources":["../../../lib/server/AsenaServerFactory.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/config/AsenaConfig.d.ts

@@ -1,6 +1,57 @@
 import type { AsenaContext, AsenaServeOptions } from '../../adapter';
 import type { WebSocketTransport } from '../web/websocket';
 import type { MiddlewareClass } from '../web/middleware';
+import type { MessagingInterceptor } from '../microservice/types';
+import type { MicroserviceTransport } from '../microservice/MicroserviceTransport';
+/**
+ * Object form of the transport() hook - configures WebSocket and microservice
+ * transports separately (all fields optional)
+ */
+export interface AsenaTransportConfig {
+    /**
+     * WebSocket transport for cross-pod messaging (same as the bare return form)
+     */
+    websocket?: WebSocketTransport | Promise<WebSocketTransport>;
+    /**
+     * Microservice transport(s). A single transport is registered under the
+     * name 'default'; a named map allows multiple brokers in one project
+     * (e.g. part on Redis, part on NATS).
+     *
+     * @example
+     * microservice: new RedisMicroserviceTransport({ ... })
+     * @example
+     * microservice: { default: redisTransport, analytics: natsTransport }
+     */
+    microservice?: MicroserviceTransport | Record<string, MicroserviceTransport> | Promise<MicroserviceTransport | Record<string, MicroserviceTransport>>;
+    /**
+     * Messaging interceptors applied to all microservice transports
+     * (e.g. OpenTelemetry trace propagation)
+     */
+    interceptors?: MessagingInterceptor[];
+}
+/**
+ * Normalized result of the transport() hook
+ */
+export interface NormalizedTransportConfig {
+    websocket?: WebSocketTransport;
+    microservices: Map<string, MicroserviceTransport>;
+    interceptors: MessagingInterceptor[];
+}
+/**
+ * Normalize the transport() hook result into a single shape.
+ *
+ * - A bare WebSocketTransport (has a publish function) is the legacy form → { websocket }
+ * - An object form is discriminated per field; a single MicroserviceTransport
+ *   (has a send function) becomes the 'default' named transport
+ * - An object with none of the known fields throws (catches accidentally
+ *   returning a bare MicroserviceTransport, which would otherwise be a silent no-op)
+ *
+ * CAVEAT: the legacy detection is duck-typed on `publish`. A custom
+ * MicroserviceTransport that also defines a `publish` method would be
+ * mistaken for a bare WebSocketTransport when returned bare - such
+ * transports must use the explicit `{ microservice: ... }` object form.
+ */
+export declare function normalizeTransportConfig(result: WebSocketTransport | AsenaTransportConfig): Promise<NormalizedTransportConfig>;
 /**
  * Route configuration for global middleware
  */
@@ -114,18 +165,45 @@ export interface AsenaConfig<C extends AsenaContext<any, any> = AsenaContext<any
      */
     globalMiddlewares?(): Promise<GlobalMiddlewareEntry[]> | GlobalMiddlewareEntry[];
     /**
-     * WebSocket transport for cross-pod messaging.
+     * Transport configuration for cross-pod WebSocket messaging and
+     * microservice messaging.
      *
-     * When not specified, BunLocalTransport is used (single-pod, zero overhead).
-     * For multi-pod deployments, return a custom transport (e.g., RedisTransport).
+     * Two return forms are supported:
+     * 1. Bare WebSocketTransport (legacy, backward compatible) - configures
+     *    only the WebSocket transport. When not specified, BunLocalTransport
+     *    is used (single-pod, zero overhead).
+     * 2. AsenaTransportConfig object - configures WebSocket and microservice
+     *    transports separately, plus messaging interceptors.
      *
      * @example
      * ```typescript
+     * // Legacy form - WebSocket only
      * transport() {
      *   return new RedisTransport(this.redis);
      * }
+     *
+     * // Object form - WebSocket + microservice
+     * transport() {
+     *   return {
+     *     websocket: new RedisTransport(this.redis),
+     *     microservice: new RedisMicroserviceTransport({
+     *       url: 'redis://localhost:6379',
+     *       serviceName: 'order-service',
+     *     }),
+     *   };
+     * }
+     *
+     * // Multiple named microservice transports (multi-broker projects)
+     * transport() {
+     *   return {
+     *     microservice: {
+     *       default: new RedisMicroserviceTransport({ ... }),
+     *       analytics: new NatsMicroserviceTransport({ ... }),
+     *     },
+     *   };
+     * }
      * ```
      */
-    transport?(): WebSocketTransport | Promise<WebSocketTransport>;
+    transport?(): WebSocketTransport | AsenaTransportConfig | Promise<WebSocketTransport | AsenaTransportConfig>;
 }
 export type AsenaConfigFunctions = 'onError' | 'serveOptions' | 'globalMiddlewares' | 'transport';

package/dist/lib/server/config/AsenaConfig.js

@@ -1,2 +1,40 @@
-export {};
+import { DEFAULT_TRANSPORT_NAME } from '../microservice/types';
+/**
+ * Normalize the transport() hook result into a single shape.
+ *
+ * - A bare WebSocketTransport (has a publish function) is the legacy form → { websocket }
+ * - An object form is discriminated per field; a single MicroserviceTransport
+ *   (has a send function) becomes the 'default' named transport
+ * - An object with none of the known fields throws (catches accidentally
+ *   returning a bare MicroserviceTransport, which would otherwise be a silent no-op)
+ *
+ * CAVEAT: the legacy detection is duck-typed on `publish`. A custom
+ * MicroserviceTransport that also defines a `publish` method would be
+ * mistaken for a bare WebSocketTransport when returned bare - such
+ * transports must use the explicit `{ microservice: ... }` object form.
+ */
+export async function normalizeTransportConfig(result) {
+    // Legacy form: bare WebSocketTransport (publish is its only required member)
+    if (typeof result.publish === 'function') {
+        return { websocket: result, microservices: new Map(), interceptors: [] };
+    }
+    const config = result;
+    if (config.websocket === undefined && config.microservice === undefined && config.interceptors === undefined) {
+        throw new Error('transport() returned an object without websocket/microservice/interceptors fields - return a WebSocketTransport or an AsenaTransportConfig object');
+    }
+    const websocket = config.websocket ? await config.websocket : undefined;
+    const microservices = new Map();
+    if (config.microservice) {
+        const resolved = await config.microservice;
+        if (typeof resolved.send === 'function') {
+            microservices.set(DEFAULT_TRANSPORT_NAME, resolved);
+        }
+        else {
+            for (const [name, transport] of Object.entries(resolved)) {
+                microservices.set(name, transport);
+            }
+        }
+    }
+    return { websocket, microservices, interceptors: config.interceptors || [] };
+}
 //# sourceMappingURL=AsenaConfig.js.map

package/dist/lib/server/config/AsenaConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"AsenaConfig.js","sourceRoot":"","sources":["../../../../lib/server/config/AsenaConfig.ts"],"names":[],"mappings":""}
+{"version":3,"file":"AsenaConfig.js","sourceRoot":"","sources":["../../../../lib/server/config/AsenaConfig.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AA2C/D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAiD;IAEjD,6EAA6E;IAC7E,IAAI,OAAQ,MAA6B,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACjE,OAAO,EAAE,SAAS,EAAE,MAA4B,EAAE,aAAa,EAAE,IAAI,GAAG,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IACjG,CAAC;IAED,MAAM,MAAM,GAAG,MAA8B,CAAC;IAE9C,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC7G,MAAM,IAAI,KAAK,CACb,mJAAmJ,CACpJ,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAExE,MAAM,aAAa,GAAG,IAAI,GAAG,EAAiC,CAAC;IAE/D,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;QAE3C,IAAI,OAAQ,QAAkC,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACnE,aAAa,CAAC,GAAG,CAAC,sBAAsB,EAAE,QAAiC,CAAC,CAAC;QAC/E,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAiD,CAAC,EAAE,CAAC;gBAClG,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC;AAC/E,CAAC"}

package/dist/lib/server/decorators/components/MessageController.d.ts

@@ -0,0 +1,49 @@
+import type { MessageControllerParams } from '../../microservice';
+/**
+ * @description MessageController decorator - Marks a class as a microservice message controller
+ *
+ * Message controllers contain @MessagePattern (request/response) and
+ * @EventPattern (fire-and-forget) decorated methods. They are registered into the
+ * microservice transport configured via the @Config transport() hook.
+ *
+ * The prefix is joined (with a dot) onto every @MessagePattern AND @EventPattern
+ * in the class. A single handler opts out with `prefix: false`.
+ *
+ * @param params - Optional configuration or prefix string
+ *
+ * @example
+ * // With prefix
+ * @MessageController('order')
+ * export class OrderHandler {
+ *   @MessagePattern('create')  // Handles 'order.create'
+ *   async create(data: CreateOrderDto, context: MessageContext) {
+ *     return this.orderService.create(data);
+ *   }
+ *
+ *   @EventPattern('created')  // Handles 'order.created'
+ *   async onCreated(event: OrderEvent) { }
+ *
+ *   // Absolute - another service's event vocabulary
+ *   @EventPattern({ pattern: 'payment.completed', prefix: false })
+ *   async onPaymentCompleted(event: PaymentEvent) { }
+ * }
+ *
+ * @example
+ * // Without prefix
+ * @MessageController()
+ * export class GlobalHandler {
+ *   @MessagePattern('ping')  // Handles 'ping'
+ *   async ping() {
+ *     return 'pong';
+ *   }
+ * }
+ *
+ * @example
+ * // Bound to a named transport (multi-broker projects)
+ * @MessageController({ prefix: 'metrics', transport: 'analytics' })
+ * export class AnalyticsHandler {
+ *   @EventPattern('page.viewed')  // Handles 'metrics.page.viewed'
+ *   async onPageViewed(event: PageViewedEvent) { }
+ * }
+ */
+export declare const MessageController: (params?: MessageControllerParams | string) => ClassDecorator;

package/dist/lib/server/decorators/components/MessageController.js

@@ -0,0 +1,62 @@
+import { ComponentConstants, ComponentType } from '../../../ioc';
+import { defineComponent } from '../../../ioc/component';
+import { defineTypedMetadata } from '../../../utils';
+import { DEFAULT_TRANSPORT_NAME } from '../../microservice';
+/**
+ * @description MessageController decorator - Marks a class as a microservice message controller
+ *
+ * Message controllers contain @MessagePattern (request/response) and
+ * @EventPattern (fire-and-forget) decorated methods. They are registered into the
+ * microservice transport configured via the @Config transport() hook.
+ *
+ * The prefix is joined (with a dot) onto every @MessagePattern AND @EventPattern
+ * in the class. A single handler opts out with `prefix: false`.
+ *
+ * @param params - Optional configuration or prefix string
+ *
+ * @example
+ * // With prefix
+ * @MessageController('order')
+ * export class OrderHandler {
+ *   @MessagePattern('create')  // Handles 'order.create'
+ *   async create(data: CreateOrderDto, context: MessageContext) {
+ *     return this.orderService.create(data);
+ *   }
+ *
+ *   @EventPattern('created')  // Handles 'order.created'
+ *   async onCreated(event: OrderEvent) { }
+ *
+ *   // Absolute - another service's event vocabulary
+ *   @EventPattern({ pattern: 'payment.completed', prefix: false })
+ *   async onPaymentCompleted(event: PaymentEvent) { }
+ * }
+ *
+ * @example
+ * // Without prefix
+ * @MessageController()
+ * export class GlobalHandler {
+ *   @MessagePattern('ping')  // Handles 'ping'
+ *   async ping() {
+ *     return 'pong';
+ *   }
+ * }
+ *
+ * @example
+ * // Bound to a named transport (multi-broker projects)
+ * @MessageController({ prefix: 'metrics', transport: 'analytics' })
+ * export class AnalyticsHandler {
+ *   @EventPattern('page.viewed')  // Handles 'metrics.page.viewed'
+ *   async onPageViewed(event: PageViewedEvent) { }
+ * }
+ */
+export const MessageController = (params) => {
+    // Normalize params BEFORE defineComponent - a bare string must become a prefix,
+    // otherwise paramsGenerator would treat it as the component name
+    const _params = typeof params === 'string' ? { prefix: params, name: undefined } : params || { prefix: undefined, name: undefined };
+    return defineComponent(ComponentType.MESSAGE_CONTROLLER, _params, (target) => {
+        // Store prefix + transport binding metadata for PrepareMicroserviceService
+        defineTypedMetadata(ComponentConstants.MessagePrefixKey, _params.prefix || '', target);
+        defineTypedMetadata(ComponentConstants.MessageTransportKey, _params.transport || DEFAULT_TRANSPORT_NAME, target);
+    });
+};
+//# sourceMappingURL=MessageController.js.map

package/dist/lib/server/decorators/components/MessageController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageController.js","sourceRoot":"","sources":["../../../../../lib/server/decorators/components/MessageController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAyC,EAAkB,EAAE;IAC7F,gFAAgF;IAChF,iEAAiE;IACjE,MAAM,OAAO,GACX,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAEtH,OAAO,eAAe,CAAC,aAAa,CAAC,kBAAkB,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE;QAC3E,2EAA2E;QAC3E,mBAAmB,CAAS,kBAAkB,CAAC,gBAAgB,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QAE/F,mBAAmB,CACjB,kBAAkB,CAAC,mBAAmB,EACtC,OAAO,CAAC,SAAS,IAAI,sBAAsB,EAC3C,MAAM,CACP,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/lib/server/decorators/components/index.d.ts

@@ -8,3 +8,4 @@ export * from './WebSocket';
 export * from './StaticServe';
 export * from './EventService';
 export * from './FrontendController';
+export * from './MessageController';

package/dist/lib/server/decorators/components/index.js

@@ -8,4 +8,5 @@ export * from './WebSocket';
 export * from './StaticServe';
 export * from './EventService';
 export * from './FrontendController';
+export * from './MessageController';
 //# sourceMappingURL=index.js.map

package/dist/lib/server/decorators/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../lib/server/decorators/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,6CAA6C,CAAC;AAC5D,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../lib/server/decorators/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,6CAA6C,CAAC;AAC5D,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/lib/server/event/EventDispatchService.d.ts

@@ -26,14 +26,10 @@ export declare class EventDispatchService implements ICoreService {
      */
     private warmedUp;
     /**
-     * Exact pattern cache for O(1) lookup
-     * Key: exact event pattern, Value: handlers for that pattern
+     * Hybrid lookup index (exact Map + wildcard array), shared implementation
+     * with the microservice transports
      */
-    private exactMatches;
-    /**
-     * Wildcard patterns that need O(n) matching
-     */
-    private wildcardPatterns;
+    private index;
     /**
      * Register a handler for an event pattern
      *

package/dist/lib/server/event/EventDispatchService.js

@@ -6,7 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { CoreService } from '../../ioc';
 import { ICoreServiceNames } from '../../ioc';
-import { matchesEventPattern } from './eventPatternMatcher';
+import { PatternHandlerIndex } from './PatternHandlerIndex';
 /**
  * @description Internal event dispatch service
  * Handles pattern matching, storage, and dispatching of events
@@ -33,14 +33,10 @@ let EventDispatchService = class EventDispatchService {
      */
     warmedUp = false;
     /**
-     * Exact pattern cache for O(1) lookup
-     * Key: exact event pattern, Value: handlers for that pattern
+     * Hybrid lookup index (exact Map + wildcard array), shared implementation
+     * with the microservice transports
      */
-    exactMatches = new Map();
-    /**
-     * Wildcard patterns that need O(n) matching
-     */
-    wildcardPatterns = [];
+    index = new PatternHandlerIndex();
     /**
      * Register a handler for an event pattern
      *
@@ -94,24 +90,8 @@ let EventDispatchService = class EventDispatchService {
         if (!this.warmedUp) {
             this.warmup();
         }
-        const handlersToCall = [];
-        // 1. Check exact match cache - O(1)
-        const exactHandlers = this.exactMatches.get(eventName);
-        if (exactHandlers) {
-            for (const handler of exactHandlers) {
-                // Find full subscription info (for 'once' support)
-                const sub = this.handlers.find((s) => s.handler === handler && s.pattern === eventName);
-                if (sub) {
-                    handlersToCall.push(sub);
-                }
-            }
-        }
-        // 2. Check wildcard patterns - O(n) but smaller n
-        for (const sub of this.wildcardPatterns) {
-            if (matchesEventPattern(eventName, sub.pattern)) {
-                handlersToCall.push(sub);
-            }
-        }
+        // 1-2. Collect matching subscriptions: exact matches O(1), then wildcards O(n)
+        const handlersToCall = this.index.collect(eventName);
         // 3. No handlers matched
         if (handlersToCall.length === 0) {
             return false;
@@ -159,19 +139,9 @@ let EventDispatchService = class EventDispatchService {
      * @private
      */
     warmup() {
-        this.exactMatches.clear();
-        this.wildcardPatterns = [];
+        this.index.clear();
         for (const sub of this.handlers) {
-            if (sub.pattern.includes('*')) {
-                // Wildcard pattern - needs O(n) matching on dispatch
-                this.wildcardPatterns.push(sub);
-            }
-            else {
-                // Exact pattern - O(1) lookup on dispatch
-                const handlers = this.exactMatches.get(sub.pattern) || [];
-                handlers.push(sub.handler);
-                this.exactMatches.set(sub.pattern, handlers);
-            }
+            this.index.add(sub.pattern, sub);
         }
         this.warmedUp = true;
     }
@@ -191,8 +161,7 @@ let EventDispatchService = class EventDispatchService {
      */
     clearHandlers() {
         this.handlers = [];
-        this.exactMatches.clear();
-        this.wildcardPatterns = [];
+        this.index.clear();
         this.warmedUp = false;
     }
 };

package/dist/lib/server/event/EventDispatchService.js.map

@@ -1 +1 @@
-{"version":3,"file":"EventDispatchService.js","sourceRoot":"","sources":["../../../../lib/server/event/EventDispatchService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EventDispatchService.js","sourceRoot":"","sources":["../../../../lib/server/event/EventDispatchService.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/event/PatternHandlerIndex.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @description Shared pattern → handler index with the hybrid lookup strategy
+ * used across Asena's event and messaging systems:
+ *
+ * - Exact patterns → Map (O(1) lookup on collect)
+ * - Wildcard patterns → Array (O(n) matchesEventPattern check, smaller n)
+ *
+ * Consumers: EventDispatchService (in-process events), InMemoryTransport and
+ * RedisMicroserviceTransport (microservice event handlers). The generic type T
+ * lets each consumer store what it needs (a bare handler or a subscription object).
+ *
+ * Collection order: exact matches first (registration order), then wildcard
+ * matches (registration order).
+ */
+export declare class PatternHandlerIndex<T> {
+    /**
+     * Exact pattern → entries (O(1) fast path)
+     */
+    private exact;
+    /**
+     * Wildcard patterns, matched with matchesEventPattern on collect
+     */
+    private wildcard;
+    /**
+     * Register an entry under a pattern
+     */
+    add(pattern: string, entry: T): void;
+    /**
+     * Remove a specific entry registered under a pattern (identity comparison)
+     *
+     * @returns true if the entry was found and removed
+     */
+    remove(pattern: string, entry: T): boolean;
+    /**
+     * Collect all entries whose pattern matches the given event name
+     */
+    collect(eventName: string): T[];
+    /**
+     * All registered patterns - exact first (registration order), then wildcard
+     *
+     * Diagnostics only: consumers use it to explain why an expected source
+     * matched no handler (e.g. the Kafka transport's external-topic hint).
+     */
+    patterns(): string[];
+    /**
+     * Whether the index holds no entries at all
+     */
+    get isEmpty(): boolean;
+    /**
+     * Remove all entries
+     */
+    clear(): void;
+}