@asenajs/asena 0.6.3 → 0.7.0

package/dist/lib/server/web/websocket/AsenaSocket.d.ts

@@ -1,5 +1,6 @@
 import type { ServerWebSocket, ServerWebSocketSendStatus, WebSocketReadyState } from 'bun';
 import type { WebSocketData } from './types';
+import type { WebSocketTransport } from './WebSocketTransport';
 /**
  * Wrapper class for Bun's ServerWebSocket that provides Asena-specific WebSocket functionality.
  * This class acts as a facade over the native Bun WebSocket implementation, adding features like
@@ -15,7 +16,7 @@ import type { WebSocketData } from './types';
  * socket.unsubscribe('chat-room');
  * ```
  */
-export declare class AsenaSocket<T> implements ServerWebSocket<WebSocketData<T>> {
+export declare class AsenaSocket<T> {
     readonly subscriptions: string[];
     /**
      * The underlying Bun ServerWebSocket instance.
@@ -52,13 +53,20 @@ export declare class AsenaSocket<T> implements ServerWebSocket<WebSocketData<T>>
      * @private
      */
     private _namespace;
+    /**
+     * Optional transport layer for cross-pod message publishing.
+     * When set, publish operations go through the transport instead of direct ws.publish().
+     * @private
+     */
+    private _transport?;
     /**
      * Creates a new AsenaSocket instance wrapping a Bun ServerWebSocket.
      *
      * @param ws - The native Bun ServerWebSocket instance to wrap
      * @param namespace - The namespace this socket belongs to
+     * @param transport - Optional WebSocket transport for cross-pod publishing
      */
-    constructor(ws: ServerWebSocket<WebSocketData<T>>, namespace: string);
+    constructor(ws: ServerWebSocket<WebSocketData<T>>, namespace: string, transport?: WebSocketTransport);
     /**
      * Sends data to the client. Automatically detects whether data is text or binary.
      *
@@ -114,17 +122,19 @@ export declare class AsenaSocket<T> implements ServerWebSocket<WebSocketData<T>>
      * Publishes data to all clients subscribed to the specified topic.
      * The topic is automatically prefixed with the namespace.
      *
+     * When a transport is configured, messages are routed through the transport
+     * layer for cross-pod delivery. Otherwise, uses Bun's native ws.publish().
+     *
      * @param topic - The topic name to publish to (will be prefixed with namespace)
      * @param data - The data to publish (string, ArrayBuffer, TypedArray, or DataView)
      * @param compress - Whether to compress the data (default: false)
-     * @returns The send status indicating success or failure
      *
      * @example
      * ```typescript
      * socket.publish('chat-room', 'Hello everyone!');
      * ```
      */
-    publish(topic: string, data: string | ArrayBufferLike | DataView, compress?: boolean): ServerWebSocketSendStatus;
+    publish(topic: string, data: string | ArrayBufferLike | DataView, compress?: boolean): void;
     /**
      * Publishes text data to all clients subscribed to the specified topic.
      * The topic is automatically prefixed with the namespace.
@@ -132,9 +142,8 @@ export declare class AsenaSocket<T> implements ServerWebSocket<WebSocketData<T>>
      * @param topic - The topic name to publish to (will be prefixed with namespace)
      * @param data - The text string to publish
      * @param compress - Whether to compress the data (default: false)
-     * @returns The send status indicating success or failure
      */
-    publishText(topic: string, data: string, compress?: boolean): ServerWebSocketSendStatus;
+    publishText(topic: string, data: string, compress?: boolean): void;
     /**
      * Publishes binary data to all clients subscribed to the specified topic.
      * The topic is automatically prefixed with the namespace.
@@ -142,9 +151,8 @@ export declare class AsenaSocket<T> implements ServerWebSocket<WebSocketData<T>>
      * @param topic - The topic name to publish to (will be prefixed with namespace)
      * @param data - The binary data to publish (ArrayBuffer, TypedArray, or DataView)
      * @param compress - Whether to compress the data (default: false)
-     * @returns The send status indicating success or failure
      */
-    publishBinary(topic: string, data: ArrayBufferLike | DataView, compress?: boolean): ServerWebSocketSendStatus;
+    publishBinary(topic: string, data: ArrayBufferLike | DataView, compress?: boolean): void;
     /**
      * Subscribes this socket to a topic/room. Once subscribed, the socket will receive
      * all messages published to this topic. The topic is automatically prefixed with the namespace.

package/dist/lib/server/web/websocket/AsenaSocket.js

@@ -50,13 +50,20 @@ export class AsenaSocket {
      * @private
      */
     _namespace;
+    /**
+     * Optional transport layer for cross-pod message publishing.
+     * When set, publish operations go through the transport instead of direct ws.publish().
+     * @private
+     */
+    _transport;
     /**
      * Creates a new AsenaSocket instance wrapping a Bun ServerWebSocket.
      *
      * @param ws - The native Bun ServerWebSocket instance to wrap
      * @param namespace - The namespace this socket belongs to
+     * @param transport - Optional WebSocket transport for cross-pod publishing
      */
-    constructor(ws, namespace) {
+    constructor(ws, namespace, transport) {
         this.ws = ws;
         this._data = ws.data;
         this._id = ws.data.id;
@@ -64,6 +71,7 @@ export class AsenaSocket {
         this._binaryType = ws.binaryType;
         this._readyState = ws.readyState;
         this._namespace = namespace;
+        this._transport = transport;
         this.subscriptions = ws.subscriptions;
     }
     /**
@@ -135,10 +143,12 @@ export class AsenaSocket {
      * Publishes data to all clients subscribed to the specified topic.
      * The topic is automatically prefixed with the namespace.
      *
+     * When a transport is configured, messages are routed through the transport
+     * layer for cross-pod delivery. Otherwise, uses Bun's native ws.publish().
+     *
      * @param topic - The topic name to publish to (will be prefixed with namespace)
      * @param data - The data to publish (string, ArrayBuffer, TypedArray, or DataView)
      * @param compress - Whether to compress the data (default: false)
-     * @returns The send status indicating success or failure
      *
      * @example
      * ```typescript
@@ -146,7 +156,12 @@ export class AsenaSocket {
      * ```
      */
     publish(topic, data, compress) {
-        return this.ws.publish(this.createTopic(topic), data, compress);
+        if (this._transport) {
+            this._transport.publish(this.createTopic(topic), data);
+        }
+        else {
+            this.ws.publish(this.createTopic(topic), data, compress);
+        }
     }
     /**
      * Publishes text data to all clients subscribed to the specified topic.
@@ -155,10 +170,14 @@ export class AsenaSocket {
      * @param topic - The topic name to publish to (will be prefixed with namespace)
      * @param data - The text string to publish
      * @param compress - Whether to compress the data (default: false)
-     * @returns The send status indicating success or failure
      */
     publishText(topic, data, compress) {
-        return this.ws.publishText(this.createTopic(topic), data, compress);
+        if (this._transport) {
+            this._transport.publish(this.createTopic(topic), data);
+        }
+        else {
+            this.ws.publishText(this.createTopic(topic), data, compress);
+        }
     }
     /**
      * Publishes binary data to all clients subscribed to the specified topic.
@@ -167,10 +186,14 @@ export class AsenaSocket {
      * @param topic - The topic name to publish to (will be prefixed with namespace)
      * @param data - The binary data to publish (ArrayBuffer, TypedArray, or DataView)
      * @param compress - Whether to compress the data (default: false)
-     * @returns The send status indicating success or failure
      */
     publishBinary(topic, data, compress) {
-        return this.ws.publishBinary(this.createTopic(topic), data, compress);
+        if (this._transport) {
+            this._transport.publish(this.createTopic(topic), data);
+        }
+        else {
+            this.ws.publishBinary(this.createTopic(topic), data, compress);
+        }
     }
     /**
      * Subscribes this socket to a topic/room. Once subscribed, the socket will receive

package/dist/lib/server/web/websocket/AsenaSocket.js.map

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

package/dist/lib/server/web/websocket/AsenaWebSocketServer.d.ts

@@ -1,28 +1,27 @@
-import type { Server } from 'bun';
+import type { WebSocketTransport } from './WebSocketTransport';
 /**
  * AsenaWebSocketServer class handles WebSocket server operations and message broadcasting
  *
- * This class provides a thin wrapper around Bun's WebSocket Server implementation.
+ * This class provides a thin wrapper around the WebSocket transport layer.
  * All WebSocket services share a single instance of this wrapper for efficiency.
  */
 export declare class AsenaWebSocketServer {
     /**
-     * The underlying Bun WebSocket server instance
+     * The transport layer used for publishing messages
      * @private
      */
-    private server;
+    private transport;
     /**
      * Creates a new instance of AsenaWebSocketServer
      *
-     * @param server - The Bun Server instance to use
+     * @param transport - The WebSocket transport to use for publishing
      */
-    constructor(server: Server<any>);
+    constructor(transport: WebSocketTransport);
     /**
      * Publishes data to a specific namespace
      *
      * @param nameSpace - The target namespace to publish to
      * @param data - The data to publish. Supports ArrayBuffer, objects, strings, and numbers
-     * @returns void
      */
     to(nameSpace: string, data?: any): void;
     /**

package/dist/lib/server/web/websocket/AsenaWebSocketServer.js

@@ -1,40 +1,39 @@
 /**
  * AsenaWebSocketServer class handles WebSocket server operations and message broadcasting
  *
- * This class provides a thin wrapper around Bun's WebSocket Server implementation.
+ * This class provides a thin wrapper around the WebSocket transport layer.
  * All WebSocket services share a single instance of this wrapper for efficiency.
  */
 export class AsenaWebSocketServer {
     /**
-     * The underlying Bun WebSocket server instance
+     * The transport layer used for publishing messages
      * @private
      */
-    server;
+    transport;
     /**
      * Creates a new instance of AsenaWebSocketServer
      *
-     * @param server - The Bun Server instance to use
+     * @param transport - The WebSocket transport to use for publishing
      */
-    constructor(server) {
-        this.server = server;
+    constructor(transport) {
+        this.transport = transport;
     }
     /**
      * Publishes data to a specific namespace
      *
      * @param nameSpace - The target namespace to publish to
      * @param data - The data to publish. Supports ArrayBuffer, objects, strings, and numbers
-     * @returns void
      */
     to(nameSpace, data) {
-        if (data instanceof ArrayBuffer || data instanceof DataView || data instanceof SharedArrayBuffer) {
-            this.server.publish(nameSpace, data);
+        if (data instanceof ArrayBuffer || data instanceof DataView) {
+            this.transport.publish(nameSpace, data);
             return;
         }
         if ((typeof data === 'object' || typeof data === 'string') && data !== null) {
-            this.server.publish(nameSpace, JSON.stringify(data));
+            this.transport.publish(nameSpace, JSON.stringify(data));
         }
         else if (typeof data === 'number' || data === null || data === undefined) {
-            this.server.publish(nameSpace, String(data));
+            this.transport.publish(nameSpace, String(data));
         }
     }
     /**

package/dist/lib/server/web/websocket/AsenaWebSocketServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"AsenaWebSocketServer.js","sourceRoot":"","sources":["../../../../../lib/server/web/websocket/AsenaWebSocketServer.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAC/B;;;OAGG;IACK,MAAM,CAAc;IAE5B;;;;OAIG;IACH,YAAmB,MAAmB;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACI,EAAE,CAAC,SAAiB,EAAE,IAAU;QACrC,IAAI,IAAI,YAAY,WAAW,IAAI,IAAI,YAAY,QAAQ,IAAI,IAAI,YAAY,iBAAiB,EAAE,CAAC;YACjG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAC5E,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3E,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,EAAE,CAAC,SAAiB,EAAE,IAAU;QACrC,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;CACF"}
+{"version":3,"file":"AsenaWebSocketServer.js","sourceRoot":"","sources":["../../../../../lib/server/web/websocket/AsenaWebSocketServer.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAC/B;;;OAGG;IACK,SAAS,CAAqB;IAEtC;;;;OAIG;IACH,YAAmB,SAA6B;QAC9C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACI,EAAE,CAAC,SAAiB,EAAE,IAAU;QACrC,IAAI,IAAI,YAAY,WAAW,IAAI,IAAI,YAAY,QAAQ,EAAE,CAAC;YAC5D,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACxC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAC5E,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3E,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,EAAE,CAAC,SAAiB,EAAE,IAAU;QACrC,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;CACF"}

package/dist/lib/server/web/websocket/BunLocalTransport.d.ts

@@ -0,0 +1,16 @@
+import type { Server } from 'bun';
+import type { WebSocketData } from './types';
+import type { WebSocketTransport } from './WebSocketTransport';
+/**
+ * Default WebSocket transport using Bun's native server.publish().
+ *
+ * Single-pod only - messages are delivered to local sockets via Bun's
+ * built-in pub/sub mechanism. Zero overhead, no external dependencies.
+ *
+ * This is the default transport when no custom transport is configured.
+ */
+export declare class BunLocalTransport implements WebSocketTransport {
+    private server;
+    init(server: Server<WebSocketData>): Promise<void>;
+    publish(topic: string, data: string | ArrayBuffer | ArrayBufferView): void;
+}

package/dist/lib/server/web/websocket/BunLocalTransport.js

@@ -0,0 +1,18 @@
+/**
+ * Default WebSocket transport using Bun's native server.publish().
+ *
+ * Single-pod only - messages are delivered to local sockets via Bun's
+ * built-in pub/sub mechanism. Zero overhead, no external dependencies.
+ *
+ * This is the default transport when no custom transport is configured.
+ */
+export class BunLocalTransport {
+    server;
+    async init(server) {
+        this.server = server;
+    }
+    publish(topic, data) {
+        this.server.publish(topic, data);
+    }
+}
+//# sourceMappingURL=BunLocalTransport.js.map

package/dist/lib/server/web/websocket/BunLocalTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BunLocalTransport.js","sourceRoot":"","sources":["../../../../../lib/server/web/websocket/BunLocalTransport.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IACpB,MAAM,CAAwB;IAE/B,KAAK,CAAC,IAAI,CAAC,MAA6B;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAEM,OAAO,CAAC,KAAa,EAAE,IAA4C;QACxE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAA4B,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/lib/server/web/websocket/WebSocketTransport.d.ts

@@ -0,0 +1,76 @@
+import type { Server } from 'bun';
+import type { WebSocketData } from './types';
+/**
+ * Interface for WebSocket message transport.
+ *
+ * Abstracts the publish mechanism so WebSocket messages can be delivered
+ * across multiple server instances (pods) via external message brokers
+ * like Redis or NATS.
+ *
+ * The default implementation (BunLocalTransport) uses Bun's native
+ * server.publish() for single-pod deployments with zero overhead.
+ *
+ * @example
+ * ```typescript
+ * // Custom Redis transport
+ * class RedisTransport implements WebSocketTransport {
+ *   private server: Server;
+ *   private podId = crypto.randomUUID();
+ *
+ *   async init(server: Server) {
+ *     this.server = server;
+ *     // Subscribe to Redis for inbound messages from other pods
+ *     this.redis.psubscribe('ws:*', (channel, message) => {
+ *       const { data, origin } = JSON.parse(message);
+ *       if (origin !== this.podId) {
+ *         server.publish(channel.replace('ws:', ''), data);
+ *       }
+ *     });
+ *   }
+ *
+ *   publish(topic: string, data: string | ArrayBuffer | ArrayBufferView) {
+ *     // Local delivery
+ *     this.server.publish(topic, data);
+ *     // Remote delivery
+ *     this.redis.publish(`ws:${topic}`, JSON.stringify({ data, origin: this.podId }));
+ *   }
+ *
+ *   async destroy() {
+ *     this.redis.punsubscribe('ws:*');
+ *   }
+ * }
+ * ```
+ */
+export interface WebSocketTransport {
+    /**
+     * Publish data to a topic.
+     *
+     * Responsible for BOTH local and remote delivery:
+     * - BunLocalTransport: server.publish() only (single-pod)
+     * - Remote transports: server.publish() (local) + broker publish (remote)
+     *
+     * @param topic - The topic/channel to publish to (namespace-prefixed)
+     * @param data - The data to publish
+     */
+    publish(topic: string, data: string | ArrayBuffer | ArrayBufferView): void;
+    /**
+     * Initialize transport with Bun server reference.
+     *
+     * Called during server startup, before any WebSocket connections are accepted.
+     * Remote transports should:
+     * 1. Store the server reference for local message delivery
+     * 2. Subscribe to the message broker for inbound messages from other pods
+     * 3. Relay inbound messages to local sockets via server.publish()
+     *
+     * @param server - The Bun server instance
+     */
+    init?(server: Server<WebSocketData>): Promise<void>;
+    /**
+     * Cleanup transport resources.
+     *
+     * Called during server shutdown. Remote transports should:
+     * 1. Unsubscribe from message broker channels
+     * 2. Close broker connections
+     */
+    destroy?(): Promise<void>;
+}

package/dist/lib/server/web/websocket/WebSocketTransport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=WebSocketTransport.js.map

package/dist/lib/server/web/websocket/WebSocketTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketTransport.js","sourceRoot":"","sources":["../../../../../lib/server/web/websocket/WebSocketTransport.ts"],"names":[],"mappings":""}

package/dist/lib/server/web/websocket/index.d.ts

@@ -2,3 +2,5 @@ export * from './AsenaWebSocketService';
 export * from './types';
 export * from './AsenaSocket';
 export * from './AsenaWebSocketServer';
+export * from './WebSocketTransport';
+export * from './BunLocalTransport';

package/dist/lib/server/web/websocket/index.js

@@ -2,4 +2,6 @@ export * from './AsenaWebSocketService';
 export * from './types';
 export * from './AsenaSocket';
 export * from './AsenaWebSocketServer';
+export * from './WebSocketTransport';
+export * from './BunLocalTransport';
 //# sourceMappingURL=index.js.map

package/dist/lib/server/web/websocket/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../lib/server/web/websocket/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../lib/server/web/websocket/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/lib/server/web/websocket/types.d.ts

@@ -14,6 +14,19 @@ export interface WSEvents<T extends ServerWebSocket<any> = ServerWebSocket<any>>
     onOpenInternal: (ws: T) => void | Promise<void>;
     onCloseInternal: (ws: T, code: number, reason: string) => void | Promise<void>;
 }
+/**
+ * WebSocket ping strategy for keepalive.
+ *
+ * - `'adapter'` (default): Disables Bun's native sendPings and uses the adapter's
+ *   own heartbeat mechanism via `ws.ping()`. Controlled by `heartbeatInterval` option.
+ *   This avoids Bun's aggressive, non-configurable ping timeout (4-16s) that can
+ *   kill connections under load. See: https://github.com/oven-sh/bun/issues/26554
+ *
+ * - `'native'`: Delegates ping/pong entirely to Bun's built-in `sendPings` mechanism.
+ *   Bun automatically sends pings and closes connections that don't respond within
+ *   its internal timeout. Simpler but less configurable.
+ */
+export type SendPingStrategy = 'adapter' | 'native';
 /**
  * Options for configuring the WebSocket server.
  */
@@ -24,6 +37,17 @@ export interface WSOptions {
     idleTimeout?: number;
     publishToSelf?: boolean;
     sendPings?: boolean;
+    /**
+     * WebSocket ping strategy for keepalive.
+     * - 'adapter' (default): Uses adapter's heartbeat mechanism via ws.ping()
+     * - 'native': Uses Bun's built-in sendPings
+     */
+    sendPingStrategy?: SendPingStrategy;
+    /**
+     * Heartbeat interval in milliseconds.
+     * Only used when sendPingStrategy is 'adapter'.
+     */
+    heartbeatInterval?: number;
     perMessageDeflate: boolean | {
         compress?: WebSocketCompressor | boolean;
         decompress?: WebSocketCompressor | boolean;

package/dist/lib/utils/index.d.ts

@@ -1,2 +1,4 @@
 export { matchesPattern, shouldApplyMiddleware } from './patternMatcher';
 export { getTypedMetadata, getOwnTypedMetadata, defineTypedMetadata } from './typedMetadata';
+export { extractControllerRouteInfo, extractComponentName, isValidator, isController, isService, isMiddleware, getComponentType, } from './metadataExtractor';
+export type { ControllerRouteInfo } from './metadataExtractor';

package/dist/lib/utils/index.js

@@ -1,3 +1,4 @@
 export { matchesPattern, shouldApplyMiddleware } from './patternMatcher';
 export { getTypedMetadata, getOwnTypedMetadata, defineTypedMetadata } from './typedMetadata';
+export { extractControllerRouteInfo, extractComponentName, isValidator, isController, isService, isMiddleware, getComponentType, } from './metadataExtractor';
 //# sourceMappingURL=index.js.map

package/dist/lib/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}

package/dist/lib/utils/metadataExtractor.d.ts

@@ -0,0 +1,88 @@
+import type { Route } from '../adapter';
+/**
+ * Extracted route information from a controller instance.
+ * Provides a stable public API for reading controller metadata
+ * without exposing internal ComponentConstants symbols.
+ */
+export interface ControllerRouteInfo {
+    /** Base path from @Controller decorator (e.g., '/api/users') */
+    basePath: string;
+    /** Component name from @Controller decorator or class name */
+    controllerName: string;
+    /** Optional description for the controller (used as OpenAPI tag description) */
+    description: string;
+    /** Route map: { [methodName]: { path, method, description, validator, ... } } */
+    routes: Route;
+}
+/**
+ * Extracts route metadata from a controller instance.
+ *
+ * @param controller - A resolved controller instance from the container
+ * @returns Controller route information including base path, name, and route definitions
+ *
+ * @example
+ * ```typescript
+ * const controllers = await container.resolveAll(ComponentType.CONTROLLER);
+ * for (const controller of controllers) {
+ *   const info = extractControllerRouteInfo(controller);
+ *   console.log(info.basePath, info.controllerName, Object.keys(info.routes));
+ * }
+ * ```
+ */
+export declare function extractControllerRouteInfo(controller: any): ControllerRouteInfo;
+/**
+ * Extracts the registered component name from a class or instance.
+ *
+ * @param target - A class constructor or instance
+ * @returns The component name, or empty string if not found
+ *
+ * @example
+ * ```typescript
+ * const name = extractComponentName(MyValidator);
+ * const validator = await container.resolve(name);
+ * ```
+ */
+export declare function extractComponentName(target: any): string;
+/**
+ * Checks if a class is decorated with `@Middleware({ validator: true })`.
+ *
+ * @param target - A class constructor
+ * @returns true if the class is a validator middleware
+ *
+ * @example
+ * ```typescript
+ * // In a PostProcessor:
+ * postProcess<T>(instance: T, Class: any): T {
+ *   if (isValidator(Class)) {
+ *     // collect validator instance
+ *   }
+ *   return instance;
+ * }
+ * ```
+ */
+export declare function isValidator(target: any): boolean;
+/**
+ * Checks if a class is decorated with `@Controller`.
+ *
+ * @param target - A class constructor
+ */
+export declare function isController(target: any): boolean;
+/**
+ * Checks if a class is decorated with `@Service`.
+ *
+ * @param target - A class constructor
+ */
+export declare function isService(target: any): boolean;
+/**
+ * Checks if a class is decorated with `@Middleware`.
+ *
+ * @param target - A class constructor
+ */
+export declare function isMiddleware(target: any): boolean;
+/**
+ * Returns the component type string if the class is an Asena component.
+ *
+ * @param target - A class constructor
+ * @returns Component type ('SERVICE', 'CONTROLLER', 'MIDDLEWARE', etc.) or undefined
+ */
+export declare function getComponentType(target: any): string | undefined;