@asenajs/asena 0.7.1 → 0.8.0

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;
+}

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

@@ -0,0 +1,193 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { ComponentConstants, ComponentType, CoreService, ICoreServiceNames } from '../../../ioc';
+import { Inject } from '../../../ioc/component';
+import { getTypedMetadata } from '../../../utils';
+import { blue, yellow } from '../../../logger';
+import { DEFAULT_TRANSPORT_NAME } from '../../microservice/types';
+import { composeOnReceive } from '../../microservice/interceptorChain';
+/**
+ * @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
+ */
+let PrepareMicroserviceService = class PrepareMicroserviceService {
+    serviceName = 'PrepareMicroserviceService';
+    container;
+    logger;
+    ulak;
+    transports = new Map();
+    /**
+     * 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
+     */
+    async prepare(transports = new Map(), interceptors = []) {
+        const controllers = await this.container.resolveAll(ComponentType.MESSAGE_CONTROLLER);
+        const hasControllers = controllers !== null && controllers.length > 0;
+        if (transports.size === 0) {
+            if (hasControllers) {
+                throw new Error('@MessageController components found but no microservice transport configured - configure a microservice transport in your @Config transport()');
+            }
+            // No transports, no controllers - nothing to do
+            return;
+        }
+        this.transports = transports;
+        if (hasControllers) {
+            for (const controller of controllers) {
+                this.registerController(controller, interceptors);
+            }
+        }
+        // Connect and start consuming (transports with zero handlers start no consumer)
+        for (const [name, transport] of transports) {
+            await transport.init();
+            await transport.listen();
+            this.logger.info(`${blue('[Microservice]')} Transport "${name}" (${transport.name}) ready`);
+        }
+        // Wire the client side (Ulak.send/emit)
+        this.ulak.setMicroserviceTransports(transports, interceptors);
+    }
+    /**
+     * Gracefully shut down all transports - Called from AsenaServer.stop()
+     */
+    async destroy(options) {
+        for (const [name, transport] of this.transports) {
+            try {
+                await transport.destroy(options);
+            }
+            catch (error) {
+                this.logger.error(`${blue('[Microservice]')} Transport "${name}" destroy failed`, error);
+            }
+        }
+        this.transports = new Map();
+    }
+    /**
+     * Register all handlers from a single message controller
+     */
+    registerController(controller, interceptors) {
+        const prefix = getTypedMetadata(ComponentConstants.MessagePrefixKey, controller.constructor) || '';
+        const transportName = getTypedMetadata(ComponentConstants.MessageTransportKey, controller.constructor) ||
+            DEFAULT_TRANSPORT_NAME;
+        const transport = this.transports.get(transportName);
+        if (!transport) {
+            const available = Array.from(this.transports.keys()).join(', ');
+            throw new Error(`@MessageController "${controller.constructor.name}" is bound to transport "${transportName}" but it is not configured - available transports: ${available}`);
+        }
+        const handlers = getTypedMetadata(ComponentConstants.MessageHandlersKey, controller.constructor);
+        if (!handlers) {
+            // No @MessagePattern/@EventPattern methods - skip
+            return;
+        }
+        const resolved = [];
+        for (const [methodName, metadata] of Object.entries(handlers)) {
+            if (metadata.skip) {
+                continue;
+            }
+            // `!== false`: metadata written by a pre-0.8 decorator build carries no
+            // flag and must follow the current default (apply the prefix)
+            const applyPrefix = metadata.prefix !== false;
+            // A wildcard prefix is nonsense in every direction: it produced a loud
+            // transport error on the message side and would now silently produce a
+            // bizarre event subscription ('order.*.created')
+            if (applyPrefix && prefix.includes('*')) {
+                throw new Error(`@MessageController "${controller.constructor.name}" has a wildcard prefix "${prefix}" - ` +
+                    'the prefix is joined onto @MessagePattern and @EventPattern patterns and must be a literal ' +
+                    'path segment (use prefix: false on a handler that must keep its pattern verbatim)');
+            }
+            const bound = controller[methodName].bind(controller);
+            const wrapped = (data, context) => composeOnReceive(interceptors, context, () => Promise.resolve(bound(data, context)));
+            const finalPattern = this.buildPattern(prefix, metadata.pattern, applyPrefix);
+            if (metadata.type === 'message') {
+                transport.registerMessageHandler(finalPattern, wrapped);
+                resolved.push({ kind: 'msg', pattern: finalPattern });
+            }
+            else {
+                transport.registerEventHandler(finalPattern, wrapped);
+                resolved.push({ kind: 'evt', pattern: finalPattern });
+            }
+        }
+        this.logResolved(controller.constructor.name, transportName, prefix, resolved);
+    }
+    /**
+     * 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
+     */
+    buildPattern(prefix, pattern, applyPrefix) {
+        if (!applyPrefix)
+            return pattern;
+        if (!prefix)
+            return pattern;
+        if (!pattern)
+            return prefix;
+        return `${prefix}.${pattern}`;
+    }
+    /**
+     * 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.
+     */
+    logResolved(controllerName, transportName, prefix, resolved) {
+        if (!resolved.length) {
+            return;
+        }
+        const parts = [];
+        const messages = resolved.filter((entry) => entry.kind === 'msg').map((entry) => entry.pattern);
+        const events = resolved.filter((entry) => entry.kind === 'evt').map((entry) => entry.pattern);
+        if (messages.length)
+            parts.push(`msg: ${messages.join(', ')}`);
+        if (events.length)
+            parts.push(`evt: ${events.join(', ')}`);
+        this.logger.info(`${blue('[Microservice]')} ${yellow(controllerName)} → "${transportName}"` +
+            `${prefix ? ` (prefix "${prefix}")` : ''} ${parts.join(' | ')}`);
+    }
+};
+__decorate([
+    Inject(ICoreServiceNames.CONTAINER),
+    __metadata("design:type", Function)
+], PrepareMicroserviceService.prototype, "container", void 0);
+__decorate([
+    Inject(ICoreServiceNames.SERVER_LOGGER),
+    __metadata("design:type", Object)
+], PrepareMicroserviceService.prototype, "logger", void 0);
+__decorate([
+    Inject(ICoreServiceNames.__ULAK__),
+    __metadata("design:type", Function)
+], PrepareMicroserviceService.prototype, "ulak", void 0);
+PrepareMicroserviceService = __decorate([
+    CoreService(ICoreServiceNames.PREPARE_MICROSERVICE_SERVICE)
+], PrepareMicroserviceService);
+export { PrepareMicroserviceService };
+//# sourceMappingURL=PrepareMicroserviceService.js.map

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

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

package/dist/lib/test/factory/deepMock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Creates a deep mock object backed by native Proxy
+ *
+ * Any property access returns a memoized Bun mock function, and calling one
+ * returns another deep mock node - so arbitrary call chains work without any
+ * upfront shape definition. Used by mockComponent to evaluate @Inject expression
+ * transformations (e.g. the ulak() helper) without a running application.
+ *
+ * @returns Deep mock root node
+ *
+ * @example
+ * ```typescript
+ * const deepMock = createDeepMock();
+ *
+ * // Any chain works out of the box
+ * const channel = deepMock.namespace('/chat');
+ * await channel.broadcast({ text: 'hello' });
+ *
+ * expect(channel.broadcast).toHaveBeenCalledWith({ text: 'hello' });
+ *
+ * // Mocks are configurable like any Bun mock
+ * channel.getSocketCount.mockReturnValue(5);
+ * ```
+ */
+export declare function createDeepMock(): any;

package/dist/lib/test/factory/deepMock.js

@@ -0,0 +1,105 @@
+import { mock } from 'bun:test';
+/**
+ * Keys that must NOT resolve to a mock function on a deep mock node.
+ *
+ * `then`/`catch`/`finally`: if property access returned a function, the node
+ * would be treated as a thenable and `await deepMock` would never resolve.
+ * `toJSON`: keeps JSON.stringify from invoking an auto-generated mock.
+ */
+const IGNORED_KEYS = new Set(['then', 'catch', 'finally', 'toJSON']);
+/**
+ * Creates a leaf mock: a REAL Bun mock function (no Proxy wrapper)
+ *
+ * Leaves must stay raw because Bun's expect() matchers and mock configuration
+ * methods (mockReturnValue, mockResolvedValue...) brand-check their target -
+ * a Proxy-wrapped mock fails "Expected value must be a mock function". The
+ * default implementation returns a memoized deep node so call chains continue.
+ *
+ * @param path - Access path of this mock, used as the function name for debugging
+ * @returns Bun mock function
+ *
+ * @internal
+ */
+function createDeepMockLeaf(path) {
+    let callResult;
+    const leaf = mock(() => {
+        callResult ??= createDeepMockNode(`${path}()`);
+        return callResult;
+    });
+    Object.defineProperty(leaf, 'name', { value: path, configurable: true });
+    return leaf;
+}
+/**
+ * Creates a deep mock node
+ *
+ * A node is a Proxy whose target is a Bun mock function: the node is callable
+ * (returning a memoized child node) and any unknown property resolves to a
+ * memoized raw leaf mock.
+ *
+ * @param path - Access path of this node, used as the function name for debugging
+ * @returns Proxy-wrapped mock function
+ *
+ * @internal
+ */
+function createDeepMockNode(path) {
+    let callResult;
+    const fn = mock(() => {
+        callResult ??= createDeepMockNode(`${path}()`);
+        return callResult;
+    });
+    Object.defineProperty(fn, 'name', { value: path, configurable: true });
+    const children = new Map();
+    return new Proxy(fn, {
+        get(target, key) {
+            // Pass through everything that exists on the mock function itself
+            // (mock state, Function.prototype members). Methods are bound to the
+            // raw target so native brand checks keep working through the Proxy.
+            if (Reflect.has(target, key)) {
+                const value = Reflect.get(target, key, target);
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            if (IGNORED_KEYS.has(key)) {
+                return undefined;
+            }
+            // Well-known symbols (Symbol.iterator, Symbol.toPrimitive, inspect
+            // symbols...) fall back to engine defaults instead of becoming mocks
+            if (typeof key === 'symbol') {
+                return undefined;
+            }
+            // Memoized per key so repeated access returns the SAME mock function
+            // and call counts accumulate across accesses
+            if (!children.has(key)) {
+                children.set(key, createDeepMockLeaf(`${path}.${String(key)}`));
+            }
+            return children.get(key);
+        },
+    });
+}
+/**
+ * Creates a deep mock object backed by native Proxy
+ *
+ * Any property access returns a memoized Bun mock function, and calling one
+ * returns another deep mock node - so arbitrary call chains work without any
+ * upfront shape definition. Used by mockComponent to evaluate @Inject expression
+ * transformations (e.g. the ulak() helper) without a running application.
+ *
+ * @returns Deep mock root node
+ *
+ * @example
+ * ```typescript
+ * const deepMock = createDeepMock();
+ *
+ * // Any chain works out of the box
+ * const channel = deepMock.namespace('/chat');
+ * await channel.broadcast({ text: 'hello' });
+ *
+ * expect(channel.broadcast).toHaveBeenCalledWith({ text: 'hello' });
+ *
+ * // Mocks are configurable like any Bun mock
+ * channel.getSocketCount.mockReturnValue(5);
+ * ```
+ */
+export function createDeepMock() {
+    return createDeepMockNode('deepMock');
+}
+//# sourceMappingURL=deepMock.js.map

package/dist/lib/test/factory/deepMock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepMock.js","sourceRoot":"","sources":["../../../../lib/test/factory/deepMock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAc,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,UAAe,CAAC;IAEpB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE;QACrB,UAAU,KAAK,kBAAkB,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAE/C,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,UAAe,CAAC;IAEpB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;QACnB,UAAU,KAAK,kBAAkB,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAE/C,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,OAAO,IAAI,KAAK,CAAC,EAAE,EAAE;QACnB,GAAG,CAAC,MAAM,EAAE,GAAG;YACb,kEAAkE;YAClE,qEAAqE;YACrE,oEAAoE;YACpE,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;gBAE/C,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAClE,CAAC;YAED,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,mEAAmE;YACnE,qEAAqE;YACrE,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,qEAAqE;YACrE,6CAA6C;YAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,kBAAkB,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC"}

package/dist/lib/test/factory/ulakStub.d.ts

@@ -0,0 +1,44 @@
+import type { Mock } from 'bun:test';
+import type { Ulak } from '../../server/messaging';
+/**
+ * A Ulak.NameSpace stub whose methods are all Bun mock functions
+ *
+ * Extends Ulak.NameSpace so any method added to the interface in the future
+ * breaks this file's compilation instead of silently drifting out of sync.
+ */
+export interface TestUlakNameSpace<T extends string = string> extends Ulak.NameSpace<T> {
+    broadcast: Mock<(data: any) => Promise<void>>;
+    to: Mock<(room: string, data: any) => Promise<void>>;
+    toSocket: Mock<(socketId: string, data: any) => Promise<void>>;
+    toMany: Mock<(rooms: string[], data: any) => Promise<void>>;
+    getSocketCount: Mock<() => number>;
+}
+/**
+ * Creates a typed Ulak namespace stub for tests
+ *
+ * Use it as an explicit override for @Inject(ulak(...)) fields when you want
+ * a fully typed mock instead of the automatic deep mock generated by
+ * mockComponent.
+ *
+ * @param path - The namespace path the stub reports (defaults to '/')
+ * @returns Ulak.NameSpace implementation with all methods mocked
+ *
+ * @example
+ * ```typescript
+ * import { mockComponent, createTestUlakStub } from '@asenajs/asena/test';
+ *
+ * const statsChannel = createTestUlakStub('/ws/public/stats');
+ *
+ * const { instance } = mockComponent(UserService, {
+ *   overrides: { statsChannel },
+ * });
+ *
+ * await instance.createAnonUser('John');
+ *
+ * expect(statsChannel.broadcast).toHaveBeenCalledWith({
+ *   action: 'update',
+ *   data: { newUser: 1 },
+ * });
+ * ```
+ */
+export declare function createTestUlakStub<T extends string = string>(path?: T): TestUlakNameSpace<T>;

package/dist/lib/test/factory/ulakStub.js

@@ -0,0 +1,40 @@
+import { mock } from 'bun:test';
+/**
+ * Creates a typed Ulak namespace stub for tests
+ *
+ * Use it as an explicit override for @Inject(ulak(...)) fields when you want
+ * a fully typed mock instead of the automatic deep mock generated by
+ * mockComponent.
+ *
+ * @param path - The namespace path the stub reports (defaults to '/')
+ * @returns Ulak.NameSpace implementation with all methods mocked
+ *
+ * @example
+ * ```typescript
+ * import { mockComponent, createTestUlakStub } from '@asenajs/asena/test';
+ *
+ * const statsChannel = createTestUlakStub('/ws/public/stats');
+ *
+ * const { instance } = mockComponent(UserService, {
+ *   overrides: { statsChannel },
+ * });
+ *
+ * await instance.createAnonUser('John');
+ *
+ * expect(statsChannel.broadcast).toHaveBeenCalledWith({
+ *   action: 'update',
+ *   data: { newUser: 1 },
+ * });
+ * ```
+ */
+export function createTestUlakStub(path = '/') {
+    return {
+        path,
+        broadcast: mock(async () => undefined),
+        to: mock(async () => undefined),
+        toSocket: mock(async () => undefined),
+        toMany: mock(async () => undefined),
+        getSocketCount: mock(() => 0),
+    };
+}
+//# sourceMappingURL=ulakStub.js.map

package/dist/lib/test/factory/ulakStub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulakStub.js","sourceRoot":"","sources":["../../../../lib/test/factory/ulakStub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAkBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,kBAAkB,CAA4B,OAAU,GAAQ;IAC9E,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QACtC,EAAE,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QAC/B,QAAQ,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QACrC,MAAM,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QACnC,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KAC9B,CAAC;AACJ,CAAC"}

package/dist/lib/test/harness/createTestApp.d.ts

@@ -0,0 +1,33 @@
+import type { AsenaAdapter } from '../../adapter';
+import type { TestApp, TestAppOptions } from './types';
+/**
+ * Boots a full Asena application for testing - the equivalent of Spring's `@SpringBootTest`.
+ *
+ * Everything runs for real: the IoC container, all bootstrap phases, the adapter and its
+ * routing pipeline. Only the components you name are registered, and any of them can be
+ * swapped for a double through `overrides`.
+ *
+ * @param options - Adapter, components and optional overrides
+ * @returns A started app with a fluent HTTP client attached
+ *
+ * @example
+ * ```typescript
+ * const [adapter] = createHonoAdapter({ logger: silentLogger });
+ * const app = await createTestApp({
+ *   adapter,
+ *   components: [UserController, UserService],
+ *   overrides: { UserService: { findById: mock(async () => ({ id: '1', name: 'Ada' })) } },
+ * });
+ *
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ *
+ * await app.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Automatic cleanup, and no TCP port taken at all
+ * await using app = await createTestApp({ adapter, components, dispatch: 'socket' });
+ * ```
+ */
+export declare function createTestApp<A extends AsenaAdapter<any, any> = AsenaAdapter<any, any>>(options: TestAppOptions<A>): Promise<TestApp>;

package/dist/lib/test/harness/createTestApp.js

@@ -0,0 +1,105 @@
+import { unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AsenaServerFactory } from '../../server/AsenaServerFactory';
+import { TestHttpCall } from '../http/TestHttpCall';
+import { silentLogger } from './silentLogger';
+// Monotonic, not random: workflow scripts and test runners may run many apps per process
+// and a collision would surface as a confusing EADDRINUSE on a socket file
+let socketCounter = 0;
+function nextSocketPath() {
+    socketCounter += 1;
+    return join(tmpdir(), `asena-test-${process.pid}-${socketCounter}.sock`);
+}
+/**
+ * Boots a full Asena application for testing - the equivalent of Spring's `@SpringBootTest`.
+ *
+ * Everything runs for real: the IoC container, all bootstrap phases, the adapter and its
+ * routing pipeline. Only the components you name are registered, and any of them can be
+ * swapped for a double through `overrides`.
+ *
+ * @param options - Adapter, components and optional overrides
+ * @returns A started app with a fluent HTTP client attached
+ *
+ * @example
+ * ```typescript
+ * const [adapter] = createHonoAdapter({ logger: silentLogger });
+ * const app = await createTestApp({
+ *   adapter,
+ *   components: [UserController, UserService],
+ *   overrides: { UserService: { findById: mock(async () => ({ id: '1', name: 'Ada' })) } },
+ * });
+ *
+ * await app.get('/users/1').expectStatus(200).expectJson({ id: '1', name: 'Ada' });
+ *
+ * await app.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Automatic cleanup, and no TCP port taken at all
+ * await using app = await createTestApp({ adapter, components, dispatch: 'socket' });
+ * ```
+ */
+export async function createTestApp(options) {
+    const { adapter, components, overrides, logger = silentLogger, dispatch = 'server' } = options;
+    const socketPath = dispatch === 'socket' ? nextSocketPath() : undefined;
+    const server = await AsenaServerFactory.create({
+        adapter,
+        logger,
+        components,
+        overrides,
+        // Port 0 lets Bun assign a free ephemeral port, which removes the random-port race
+        port: options.port ?? 0,
+    });
+    await server.start(socketPath ? { unix: socketPath } : undefined);
+    const port = server.httpServer?.port ?? 0;
+    const baseUrl = socketPath ? 'http://localhost' : `http://localhost:${port}`;
+    const call = (path, init, method) => {
+        const requestInit = { ...init };
+        if (method) {
+            requestInit.method = method;
+        }
+        if (socketPath) {
+            // Bun routes the request over the socket while still parsing the URL for path/query
+            requestInit.unix = socketPath;
+        }
+        return new TestHttpCall(`${baseUrl}${path}`, requestInit);
+    };
+    let stopped = false;
+    const app = {
+        server,
+        container: server.coreContainer.container,
+        port,
+        baseUrl,
+        socketPath,
+        resolve: async (name) => (await server.coreContainer.container.resolve(name)),
+        wsUrl: (path) => (socketPath ? `ws+unix://${socketPath}:${path}` : `ws://localhost:${port}${path}`),
+        request: (path, init) => call(path, init),
+        get: (path, init) => call(path, init, 'GET'),
+        post: (path, init) => call(path, init, 'POST'),
+        put: (path, init) => call(path, init, 'PUT'),
+        patch: (path, init) => call(path, init, 'PATCH'),
+        delete: (path, init) => call(path, init, 'DELETE'),
+        head: (path, init) => call(path, init, 'HEAD'),
+        options: (path, init) => call(path, init, 'OPTIONS'),
+        stop: async () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            await server.stop();
+            if (socketPath) {
+                // Bun removes the socket file on a clean stop; this only matters after a crash
+                await unlink(socketPath).catch(() => {
+                    // Already gone - nothing to clean up
+                });
+            }
+        },
+        [Symbol.asyncDispose]: async () => {
+            await app.stop();
+        },
+    };
+    return app;
+}
+//# sourceMappingURL=createTestApp.js.map

package/dist/lib/test/harness/createTestApp.js.map

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