@asenajs/asena 0.7.1 → 0.8.1

package/dist/lib/server/microservice/decorators/EventPattern.js

@@ -0,0 +1,59 @@
+import { ComponentConstants } from '../../../ioc';
+import { defineTypedMetadata, getOwnTypedMetadata } from '../../../utils';
+/**
+ * @description EventPattern decorator - Marks a method as a fire-and-forget event handler
+ *
+ * Methods decorated with @EventPattern will be automatically registered into the
+ * configured microservice transport when the server boots (via PrepareMicroserviceService).
+ * No reply is produced; delivery is at-least-once on durable transports, so handlers
+ * should be idempotent (use context.messageId for deduplication).
+ *
+ * The controller prefix is joined onto the pattern ('order' + 'created' →
+ * 'order.created'), matching what ulak.messages('order').emit('created') publishes.
+ * Pass `prefix: false` when the pattern is absolute — another service's event
+ * vocabulary, a Kafka external topic name, or a global catch-all.
+ * Wildcards are supported: 'payment.*', '*.completed', 'user.*.created'.
+ * Note that under a prefix, '*' becomes 'order.*' and is no longer a global catch-all.
+ *
+ * @param params - Event pattern or configuration object
+ *
+ * @example
+ * @MessageController('order')
+ * export class OrderHandler {
+ *   @EventPattern('created')  // Handles 'order.created'
+ *   async onCreated(event: OrderEvent, context: MessageContext) { }
+ *
+ *   // Absolute - another service's event vocabulary
+ *   @EventPattern({ pattern: 'payment.completed', prefix: false })
+ *   async onPaymentCompleted(event: PaymentEvent, context: MessageContext) {
+ *     await this.orderService.markPaid(event.orderId);
+ *   }
+ *
+ *   @EventPattern('*')  // Wildcards allowed - handles 'order.*'
+ *   async onAnyOrderEvent(event: any, context: MessageContext) { }
+ *
+ *   @EventPattern({ pattern: 'stock.depleted', skip: true })  // Temporarily disabled
+ *   async onStockDepleted(event: any, context: MessageContext) { }
+ * }
+ */
+export function EventPattern(params) {
+    // Normalize params - support both object and string
+    const _params = typeof params === 'string' ? { pattern: params, skip: false } : params;
+    return function (target, propertyKey, descriptor) {
+        // Get existing handlers metadata (other @MessagePattern/@EventPattern methods)
+        const handlers = getOwnTypedMetadata(ComponentConstants.MessageHandlersKey, target.constructor) || {};
+        // Add this handler's metadata
+        handlers[propertyKey.toString()] = {
+            pattern: _params.pattern,
+            type: 'event',
+            methodName: propertyKey.toString(),
+            // `!== false` covers the string shorthand and objects that omit the flag
+            prefix: _params.prefix !== false,
+            skip: _params.skip || false,
+        };
+        // Store updated metadata
+        defineTypedMetadata(ComponentConstants.MessageHandlersKey, handlers, target.constructor);
+        return descriptor;
+    };
+}
+//# sourceMappingURL=EventPattern.js.map

package/dist/lib/server/microservice/decorators/EventPattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventPattern.js","sourceRoot":"","sources":["../../../../../lib/server/microservice/decorators/EventPattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmC;IAC9D,oDAAoD;IACpD,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvF,OAAO,UAAU,MAAc,EAAE,WAA4B,EAAE,UAA8B;QAC3F,+EAA+E;QAC/E,MAAM,QAAQ,GACZ,mBAAmB,CACjB,kBAAkB,CAAC,kBAAkB,EACrC,MAAM,CAAC,WAAW,CACnB,IAAI,EAAE,CAAC;QAEV,8BAA8B;QAC9B,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG;YACjC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,WAAW,CAAC,QAAQ,EAAE;YAClC,yEAAyE;YACzE,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,KAAK;YAChC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK;SAC5B,CAAC;QAEF,yBAAyB;QACzB,mBAAmB,CAAC,kBAAkB,CAAC,kBAAkB,EAAE,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QAEzF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/server/microservice/decorators/MessagePattern.d.ts

@@ -0,0 +1,31 @@
+import type { MessagePatternParams } from '../types';
+/**
+ * @description MessagePattern decorator - Marks a method as a request/response handler
+ *
+ * Methods decorated with @MessagePattern will be automatically registered into the
+ * configured microservice transport when the server boots (via PrepareMicroserviceService).
+ * The method's return value is sent back to the caller as the reply.
+ *
+ * The controller prefix is joined onto the pattern ('order' + 'create' → 'order.create').
+ * Pass `prefix: false` to register the pattern verbatim.
+ * Wildcards are NOT allowed — request/response requires exact routing — and
+ * `prefix: false` does not relax that.
+ *
+ * @param params - Request pattern or configuration object
+ *
+ * @example
+ * @MessageController('order')
+ * export class OrderHandler {
+ *   @MessagePattern('create')  // Handles 'order.create'
+ *   async create(data: CreateOrderDto, context: MessageContext) {
+ *     return this.orderService.create(data);  // reply sent to caller
+ *   }
+ *
+ *   @MessagePattern({ pattern: 'ping', prefix: false })  // Handles 'ping'
+ *   async ping(data: any, context: MessageContext) { }
+ *
+ *   @MessagePattern({ pattern: 'delete', skip: true })  // Temporarily disabled
+ *   async delete(data: any, context: MessageContext) { }
+ * }
+ */
+export declare function MessagePattern(params: MessagePatternParams | string): MethodDecorator;

package/dist/lib/server/microservice/decorators/MessagePattern.js

@@ -0,0 +1,55 @@
+import { ComponentConstants } from '../../../ioc';
+import { defineTypedMetadata, getOwnTypedMetadata } from '../../../utils';
+/**
+ * @description MessagePattern decorator - Marks a method as a request/response handler
+ *
+ * Methods decorated with @MessagePattern will be automatically registered into the
+ * configured microservice transport when the server boots (via PrepareMicroserviceService).
+ * The method's return value is sent back to the caller as the reply.
+ *
+ * The controller prefix is joined onto the pattern ('order' + 'create' → 'order.create').
+ * Pass `prefix: false` to register the pattern verbatim.
+ * Wildcards are NOT allowed — request/response requires exact routing — and
+ * `prefix: false` does not relax that.
+ *
+ * @param params - Request pattern or configuration object
+ *
+ * @example
+ * @MessageController('order')
+ * export class OrderHandler {
+ *   @MessagePattern('create')  // Handles 'order.create'
+ *   async create(data: CreateOrderDto, context: MessageContext) {
+ *     return this.orderService.create(data);  // reply sent to caller
+ *   }
+ *
+ *   @MessagePattern({ pattern: 'ping', prefix: false })  // Handles 'ping'
+ *   async ping(data: any, context: MessageContext) { }
+ *
+ *   @MessagePattern({ pattern: 'delete', skip: true })  // Temporarily disabled
+ *   async delete(data: any, context: MessageContext) { }
+ * }
+ */
+export function MessagePattern(params) {
+    // Normalize params - support both object and string
+    const _params = typeof params === 'string' ? { pattern: params, skip: false } : params;
+    if (_params.pattern.includes('*')) {
+        throw new Error(`@MessagePattern('${_params.pattern}') cannot contain wildcards - request/response requires exact patterns. Use @EventPattern for wildcard subscriptions.`);
+    }
+    return function (target, propertyKey, descriptor) {
+        // Get existing handlers metadata (other @MessagePattern/@EventPattern methods)
+        const handlers = getOwnTypedMetadata(ComponentConstants.MessageHandlersKey, target.constructor) || {};
+        // Add this handler's metadata
+        handlers[propertyKey.toString()] = {
+            pattern: _params.pattern,
+            type: 'message',
+            methodName: propertyKey.toString(),
+            // `!== false` covers the string shorthand and objects that omit the flag
+            prefix: _params.prefix !== false,
+            skip: _params.skip || false,
+        };
+        // Store updated metadata
+        defineTypedMetadata(ComponentConstants.MessageHandlersKey, handlers, target.constructor);
+        return descriptor;
+    };
+}
+//# sourceMappingURL=MessagePattern.js.map

package/dist/lib/server/microservice/decorators/MessagePattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessagePattern.js","sourceRoot":"","sources":["../../../../../lib/server/microservice/decorators/MessagePattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqC;IAClE,oDAAoD;IACpD,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvF,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,CAAC,OAAO,uHAAuH,CAC3J,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,MAAc,EAAE,WAA4B,EAAE,UAA8B;QAC3F,+EAA+E;QAC/E,MAAM,QAAQ,GACZ,mBAAmB,CACjB,kBAAkB,CAAC,kBAAkB,EACrC,MAAM,CAAC,WAAW,CACnB,IAAI,EAAE,CAAC;QAEV,8BAA8B;QAC9B,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG;YACjC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,SAAS;YACf,UAAU,EAAE,WAAW,CAAC,QAAQ,EAAE;YAClC,yEAAyE;YACzE,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,KAAK;YAChC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK;SAC5B,CAAC;QAEF,yBAAyB;QACzB,mBAAmB,CAAC,kBAAkB,CAAC,kBAAkB,EAAE,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QAEzF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,2 @@
+export * from './MessagePattern';
+export * from './EventPattern';

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

@@ -0,0 +1,3 @@
+export * from './MessagePattern';
+export * from './EventPattern';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../lib/server/microservice/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/lib/server/microservice/index.d.ts

@@ -0,0 +1,5 @@
+export * from './MicroserviceTransport';
+export * from './types';
+export * from './InMemoryTransport';
+export * from './interceptorChain';
+export * from './decorators';

package/dist/lib/server/microservice/index.js

@@ -0,0 +1,11 @@
+// Transport SPI
+export * from './MicroserviceTransport';
+// Types (params, metadata, interceptor SPI)
+export * from './types';
+// In-process reference transport
+export * from './InMemoryTransport';
+// Interceptor composition (used by Ulak and PrepareMicroserviceService)
+export * from './interceptorChain';
+// Decorators
+export * from './decorators';
+//# sourceMappingURL=index.js.map

package/dist/lib/server/microservice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../lib/server/microservice/index.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,cAAc,yBAAyB,CAAC;AAExC,4CAA4C;AAC5C,cAAc,SAAS,CAAC;AAExB,iCAAiC;AACjC,cAAc,qBAAqB,CAAC;AAEpC,wEAAwE;AACxE,cAAc,oBAAoB,CAAC;AAEnC,aAAa;AACb,cAAc,cAAc,CAAC"}

package/dist/lib/server/microservice/interceptorChain.d.ts

@@ -0,0 +1,20 @@
+import type { MessageContext } from './MicroserviceTransport';
+import type { MessagingInterceptor, OutboundContext } from './types';
+/**
+ * @description Composes interceptor onSend hooks around an outgoing operation.
+ * Interceptors run in registration order (first interceptor is outermost).
+ *
+ * @param interceptors - Registered messaging interceptors
+ * @param ctx - Outbound context (interceptors may mutate ctx.headers)
+ * @param operation - The actual transport send/emit call
+ */
+export declare function composeOnSend(interceptors: MessagingInterceptor[], ctx: OutboundContext, operation: () => Promise<any>): Promise<any>;
+/**
+ * @description Composes interceptor onReceive hooks around a handler invocation.
+ * Interceptors run in registration order (first interceptor is outermost).
+ *
+ * @param interceptors - Registered messaging interceptors
+ * @param ctx - Incoming message context
+ * @param operation - The actual handler invocation
+ */
+export declare function composeOnReceive(interceptors: MessagingInterceptor[], ctx: MessageContext, operation: () => Promise<any>): Promise<any>;

package/dist/lib/server/microservice/interceptorChain.js

@@ -0,0 +1,39 @@
+/**
+ * @description Composes interceptor onSend hooks around an outgoing operation.
+ * Interceptors run in registration order (first interceptor is outermost).
+ *
+ * @param interceptors - Registered messaging interceptors
+ * @param ctx - Outbound context (interceptors may mutate ctx.headers)
+ * @param operation - The actual transport send/emit call
+ */
+export function composeOnSend(interceptors, ctx, operation) {
+    let next = operation;
+    for (let i = interceptors.length - 1; i >= 0; i--) {
+        const interceptor = interceptors[i];
+        if (interceptor.onSend) {
+            const inner = next;
+            next = () => interceptor.onSend(ctx, inner);
+        }
+    }
+    return next();
+}
+/**
+ * @description Composes interceptor onReceive hooks around a handler invocation.
+ * Interceptors run in registration order (first interceptor is outermost).
+ *
+ * @param interceptors - Registered messaging interceptors
+ * @param ctx - Incoming message context
+ * @param operation - The actual handler invocation
+ */
+export function composeOnReceive(interceptors, ctx, operation) {
+    let next = operation;
+    for (let i = interceptors.length - 1; i >= 0; i--) {
+        const interceptor = interceptors[i];
+        if (interceptor.onReceive) {
+            const inner = next;
+            next = () => interceptor.onReceive(ctx, inner);
+        }
+    }
+    return next();
+}
+//# sourceMappingURL=interceptorChain.js.map

package/dist/lib/server/microservice/interceptorChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptorChain.js","sourceRoot":"","sources":["../../../../lib/server/microservice/interceptorChain.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAoC,EACpC,GAAoB,EACpB,SAA6B;IAE7B,IAAI,IAAI,GAAG,SAAS,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAEpC,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC;YAEnB,IAAI,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,OAAO,IAAI,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAAoC,EACpC,GAAmB,EACnB,SAA6B;IAE7B,IAAI,IAAI,GAAG,SAAS,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAEpC,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,IAAI,CAAC;YAEnB,IAAI,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,EAAE,CAAC;AAChB,CAAC"}

package/dist/lib/server/microservice/types.d.ts

@@ -0,0 +1,142 @@
+import type { ComponentParams } from '../../ioc';
+import type { MessageContext } from './MicroserviceTransport';
+/**
+ * @description Name used when a single (unnamed) microservice transport is configured
+ */
+export declare const DEFAULT_TRANSPORT_NAME = "default";
+/**
+ * @description Parameters for @MessageController decorator
+ */
+export interface MessageControllerParams extends ComponentParams {
+    /**
+     * Prefix joined (with a dot) onto every @MessagePattern AND @EventPattern in
+     * this controller. A single handler opts out with `prefix: false`.
+     * Must be a literal path segment — a wildcard prefix is rejected at boot.
+     * @example 'order' turns @MessagePattern('create') into 'order.create'
+     *          and @EventPattern('created') into 'order.created'
+     */
+    prefix?: string;
+    /**
+     * Name of the microservice transport this controller binds to.
+     * Only needed when multiple named transports are configured in transport()
+     * (e.g. part of the project on Redis, part on NATS).
+     * @default 'default'
+     */
+    transport?: string;
+}
+/**
+ * @description Parameters for @MessagePattern method decorator
+ */
+export interface MessagePatternParams {
+    /**
+     * Request pattern to handle. Must be exact — wildcards are not allowed
+     * (request/response requires exact routing).
+     * @example 'create' (joined with the controller prefix → 'order.create')
+     */
+    pattern: string;
+    /**
+     * Join the @MessageController prefix onto `pattern`.
+     * Set false to register the pattern verbatim — for patterns that belong to
+     * another service's vocabulary rather than this controller's.
+     * @default true
+     */
+    prefix?: boolean;
+    /**
+     * Skip this handler (useful for temporarily disabling handlers)
+     * @default false
+     */
+    skip?: boolean;
+}
+/**
+ * @description Parameters for @EventPattern method decorator
+ */
+export interface EventPatternParams {
+    /**
+     * Event pattern to handle. Wildcards are supported.
+     * The controller prefix is joined on unless `prefix: false`.
+     * @example 'created' (joined with the controller prefix → 'order.created')
+     */
+    pattern: string;
+    /**
+     * Join the @MessageController prefix onto `pattern`.
+     * Set false for absolute names: another service's event vocabulary, a Kafka
+     * external topic name, or a global catch-all ('*').
+     * @default true
+     */
+    prefix?: boolean;
+    /**
+     * Skip this handler (useful for temporarily disabling handlers)
+     * @default false
+     */
+    skip?: boolean;
+}
+/**
+ * @description Metadata stored for each @MessagePattern/@EventPattern method
+ * Used by PrepareMicroserviceService to register handlers into the transport
+ */
+export interface MessageHandlerMetadata {
+    /**
+     * Pattern as written on the decorator. The @MessageController prefix is
+     * joined on later by PrepareMicroserviceService unless `prefix` is false.
+     */
+    pattern: string;
+    /**
+     * Handler semantics: request/response ('message') or fire-and-forget ('event')
+     */
+    type: 'message' | 'event';
+    /**
+     * Method name to call when a message arrives
+     */
+    methodName: string;
+    /**
+     * Whether the controller prefix is joined onto `pattern`.
+     * Normalized at decoration time (`prefix: false` opt-out → false).
+     */
+    prefix: boolean;
+    /**
+     * Whether this handler should be skipped
+     */
+    skip: boolean;
+}
+/**
+ * @description Context passed to MessagingInterceptor.onSend for outgoing messages
+ */
+export interface OutboundContext {
+    /**
+     * Full outgoing pattern (prefix already applied)
+     */
+    pattern: string;
+    /**
+     * Whether this is a request ('send') or a fire-and-forget event ('emit')
+     */
+    kind: 'send' | 'emit';
+    /**
+     * Mutable outgoing headers — interceptors inject metadata here (e.g. trace context)
+     */
+    headers: Record<string, string>;
+    /**
+     * Outgoing payload (read-only by convention)
+     */
+    data: unknown;
+}
+/**
+ * @description Zero-dependency messaging interceptor SPI.
+ *
+ * Both hooks are wrappers around the actual operation, so an interceptor can
+ * measure duration and observe errors/replies (e.g. OpenTelemetry spans).
+ * Interceptors are registered via the transport() config hook:
+ * `transport() { return { microservice, interceptors: [myInterceptor] } }`
+ */
+export interface MessagingInterceptor {
+    /**
+     * Wraps outgoing send/emit. Mutate ctx.headers to inject metadata,
+     * call next() to perform the operation (its promise resolves with the
+     * reply for 'send', undefined for 'emit').
+     */
+    onSend?(ctx: OutboundContext, next: () => Promise<any>): Promise<any>;
+    /**
+     * Wraps an incoming handler invocation. Call next() to run the handler
+     * (and any inner interceptors); its promise carries the handler result.
+     */
+    onReceive?(ctx: MessageContext, next: () => Promise<any>): Promise<any>;
+}

package/dist/lib/server/microservice/types.js

@@ -0,0 +1,5 @@
+/**
+ * @description Name used when a single (unnamed) microservice transport is configured
+ */
+export const DEFAULT_TRANSPORT_NAME = 'default';
+//# sourceMappingURL=types.js.map

package/dist/lib/server/microservice/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../lib/server/microservice/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC"}

package/dist/lib/server/src/services/PrepareEventService.d.ts

@@ -15,6 +15,7 @@ import type { ICoreService } from '../../../ioc';
  * - Prefix='user', event='created' → 'user.created'
  * - Prefix='user', event='*.updated' → 'user.*.updated'
  * - Prefix='user', event='' → 'user'
+ * - Handler opted out (prefix: false) → event, verbatim
  */
 export declare class PrepareEventService implements ICoreService {
     readonly serviceName = "PrepareEventService";
@@ -31,7 +32,9 @@ export declare class PrepareEventService implements ICoreService {
     /**
      * Build final event pattern from prefix and event
      *
-     * Rules:
+     * Rules (identical to PrepareMicroserviceService.buildPattern and
+     * UlakMessages.buildPattern):
+     * - Handler opted out (prefix: false) → event
      * - No prefix → event
      * - No event → prefix
      * - Both → prefix.event

package/dist/lib/server/src/services/PrepareEventService.js

@@ -26,6 +26,7 @@ import { getTypedMetadata } from '../../../utils';
  * - Prefix='user', event='created' → 'user.created'
  * - Prefix='user', event='*.updated' → 'user.*.updated'
  * - Prefix='user', event='' → 'user'
+ * - Handler opted out (prefix: false) → event, verbatim
  */
 let PrepareEventService = class PrepareEventService {
     serviceName = 'PrepareEventService';
@@ -65,7 +66,9 @@ let PrepareEventService = class PrepareEventService {
                 continue;
             }
             // Build final event pattern
-            const finalPattern = this.buildEventPattern(prefix, metadata.pattern);
+            // `!== false`: metadata written by a pre-0.8 decorator build carries no
+            // flag and must follow the current default (apply the prefix)
+            const finalPattern = this.buildEventPattern(prefix, metadata.pattern, metadata.prefix !== false);
             // Bind method to service instance
             const boundHandler = service[methodName].bind(service);
             // Register with EventEmitter
@@ -75,12 +78,16 @@ let PrepareEventService = class PrepareEventService {
     /**
      * Build final event pattern from prefix and event
      *
-     * Rules:
+     * Rules (identical to PrepareMicroserviceService.buildPattern and
+     * UlakMessages.buildPattern):
+     * - Handler opted out (prefix: false) → event
      * - No prefix → event
      * - No event → prefix
      * - Both → prefix.event
      */
-    buildEventPattern(prefix, event) {
+    buildEventPattern(prefix, event, applyPrefix) {
+        if (!applyPrefix)
+            return event;
         if (!prefix)
             return event;
         if (!event)

package/dist/lib/server/src/services/PrepareEventService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PrepareEventService.js","sourceRoot":"","sources":["../../../../../lib/server/src/services/PrepareEventService.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;;;;;;;;;;;;;;;GAgBG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IACd,WAAW,GAAG,qBAAqB,CAAC;IAG5C,SAAS,CAAa;IAGtB,eAAe,CAAwB;IAE/C;;OAEG;IACI,KAAK,CAAC,OAAO;QAClB,gCAAgC;QAChC,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QAEhF,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjD,sCAAsC;YACtC,OAAO;QACT,CAAC;QAED,gCAAgC;QAChC,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,oBAAoB,CAAC,OAAY;QAC7C,0BAA0B;QAC1B,MAAM,MAAM,GAAG,gBAAgB,CAAS,kBAAkB,CAAC,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAEtG,4BAA4B;QAC5B,MAAM,QAAQ,GAAG,gBAAgB,CAC/B,kBAAkB,CAAC,gBAAgB,EACnC,OAAO,CAAC,WAAW,CACpB,CAAC;QAEF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,wBAAwB;YACxB,OAAO;QACT,CAAC;QAED,wBAAwB;QACxB,KAAK,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9D,4BAA4B;YAC5B,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAClB,SAAS;YACX,CAAC;YAED,4BAA4B;YAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAEtE,kCAAkC;YAClC,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAEvD,6BAA6B;YAC7B,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,iBAAiB,CAAC,MAAc,EAAE,KAAa;QACrD,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,IAAI,CAAC,KAAK;YAAE,OAAO,MAAM,CAAC;QAC1B,OAAO,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;IAC9B,CAAC;CACF,CAAA;AAxES;IADP,MAAM,CAAC,iBAAiB,CAAC,SAAS,CAAC;;sDACN;AAGtB;IADP,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,CAAC;;4DACF;AAPpC,mBAAmB;IAD/B,WAAW,CAAC,iBAAiB,CAAC,qBAAqB,CAAC;GACxC,mBAAmB,CA4E/B"}
+{"version":3,"file":"PrepareEventService.js","sourceRoot":"","sources":["../../../../../lib/server/src/services/PrepareEventService.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;;;;;;;;;;;;;;;;GAiBG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IACd,WAAW,GAAG,qBAAqB,CAAC;IAG5C,SAAS,CAAa;IAGtB,eAAe,CAAwB;IAE/C;;OAEG;IACI,KAAK,CAAC,OAAO;QAClB,gCAAgC;QAChC,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QAEhF,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjD,sCAAsC;YACtC,OAAO;QACT,CAAC;QAED,gCAAgC;QAChC,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,oBAAoB,CAAC,OAAY;QAC7C,0BAA0B;QAC1B,MAAM,MAAM,GAAG,gBAAgB,CAAS,kBAAkB,CAAC,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAEtG,4BAA4B;QAC5B,MAAM,QAAQ,GAAG,gBAAgB,CAC/B,kBAAkB,CAAC,gBAAgB,EACnC,OAAO,CAAC,WAAW,CACpB,CAAC;QAEF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,wBAAwB;YACxB,OAAO;QACT,CAAC;QAED,wBAAwB;QACxB,KAAK,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9D,4BAA4B;YAC5B,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAClB,SAAS;YACX,CAAC;YAED,4BAA4B;YAC5B,wEAAwE;YACxE,8DAA8D;YAC9D,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC;YAEjG,kCAAkC;YAClC,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAEvD,6BAA6B;YAC7B,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACK,iBAAiB,CAAC,MAAc,EAAE,KAAa,EAAE,WAAoB;QAC3E,IAAI,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,IAAI,CAAC,KAAK;YAAE,OAAO,MAAM,CAAC;QAC1B,OAAO,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;IAC9B,CAAC;CACF,CAAA;AA7ES;IADP,MAAM,CAAC,iBAAiB,CAAC,SAAS,CAAC;;sDACN;AAGtB;IADP,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,CAAC;;4DACF;AAPpC,mBAAmB;IAD/B,WAAW,CAAC,iBAAiB,CAAC,qBAAqB,CAAC;GACxC,mBAAmB,CAiF/B"}

package/dist/lib/server/src/services/PrepareMicroserviceService.d.ts

@@ -0,0 +1,66 @@
+import type { ICoreService } from '../../../ioc';
+import type { MessagingInterceptor } from '../../microservice/types';
+import type { DestroyOptions, MicroserviceTransport } from '../../microservice/MicroserviceTransport';
+/**
+ * @description PrepareMicroserviceService - Registers microservice message handlers during bootstrap
+ *
+ * Scan Process:
+ * 1. Resolve all ComponentType.MESSAGE_CONTROLLER from container
+ * 2. Extract prefix + transport binding metadata from class
+ * 3. Extract handler metadata (@MessagePattern/@EventPattern methods)
+ * 4. Build final pattern: the controller prefix is joined onto BOTH message and event
+ *    patterns, unless the handler opted out with prefix: false
+ * 5. Bind method to instance, wrap with interceptor onReceive chain
+ * 6. Register into the bound transport, then init() + listen() every transport
+ * 7. Wire transports into Ulak (send/emit client side)
+ *
+ * Rules:
+ * - Controllers found but no transport configured → throw (fail fast)
+ * - Transport configured but no controllers → still init + wire Ulak (client-only mode);
+ *   the transport contract guarantees no consumer loop starts with zero handlers
+ * - Controller bound to an unknown named transport → throw listing available names
+ * - A handler with prefix: false registers its pattern verbatim (external topics,
+ *   another service's event vocabulary, global catch-alls)
+ * - A prefix containing '*' is a boot error - the prefix must be a literal path segment
+ */
+export declare class PrepareMicroserviceService implements ICoreService {
+    readonly serviceName = "PrepareMicroserviceService";
+    private container;
+    private logger;
+    private ulak;
+    private transports;
+    /**
+     * Prepare microservice handlers - Called during bootstrap (before the HTTP adapter starts)
+     *
+     * @param transports - Named transports from the transport() config hook
+     * @param interceptors - Messaging interceptors applied to all transports
+     */
+    prepare(transports?: Map<string, MicroserviceTransport>, interceptors?: MessagingInterceptor[]): Promise<void>;
+    /**
+     * Gracefully shut down all transports - Called from AsenaServer.stop()
+     */
+    destroy(options?: DestroyOptions): Promise<void>;
+    /**
+     * Register all handlers from a single message controller
+     */
+    private registerController;
+    /**
+     * Build the final pattern from the controller prefix and the handler pattern
+     *
+     * Rules (identical for @MessagePattern and @EventPattern, and identical to
+     * UlakMessages.buildPattern on the outbound side and PrepareEventService
+     * .buildEventPattern for the in-process event system):
+     * - Handler opted out (prefix: false) → pattern
+     * - No prefix                         → pattern
+     * - No pattern                        → prefix
+     * - Both                              → prefix.pattern
+     */
+    private buildPattern;
+    /**
+     * Log one line per controller with the RESOLVED patterns
+     *
+     * Asena 0.8 changed the prefix rule for @EventPattern, so the joined result
+     * must be visible at boot - but per-handler lines would drown the startup output.
+     */
+    private logResolved;
+}