Merge pull request #34 from AsenaJs/release-v0.5.0

Release v0.5.0

Author: LibirSoft

.gitignore

@@ -2,4 +2,9 @@
 node_modules
 dist
 build
-.env
+roadmaps
+.env
+/.claude/
+/.cursor/
+/junit.xml
+/CLAUDE.md

CHANGELOG.md

@@ -1,5 +1,31 @@
 # @asenajs/asena
 
+## 0.5.0
+
+### Minor Changes
+
+- # Ulak WebSocket Messaging System
+
+  Add centralized WebSocket message broker (Ulak) that eliminates circular dependencies in WebSocket communication.
+
+  **Features:**
+  - Namespace-based routing for WebSocket messages
+  - Type-safe messaging with full TypeScript support
+  - Bulk operations for efficient multi-namespace broadcasting
+  - Comprehensive error handling with UlakError
+  - Pattern matching for exact and wildcard namespaces
+
+  **Breaking Changes:**
+  - `AsenaWebSocketServer` constructor no longer accepts `topic` parameter
+  - `AsenaWebSocketServer.websocketCount` getter removed
+  - Custom adapter implementations need to update their constructor calls
+
+  **Bug Fixes:**
+  - Fix IocEngine empty dependency error in non-minified codebases
+
+  **Enhanced Features:**
+  - @Inject decorator now supports tuple injection pattern for advanced DI scenarios
+
 ## 0.4.0
 
 ### Minor Changes

lib/ioc/Container.ts

@@ -3,6 +3,7 @@ import type { ComponentType, ContainerService, Dependencies, Expressions, Strate
 import { ComponentConstants } from './constants';
 import { getOwnTypedMetadata, getTypedMetadata } from '../utils/typedMetadata';
 import { CircularDependencyDetector } from './CircularDependencyDetector';
+import { CORE_SERVICE } from './decorators/CoreService';
 
 export class Container {
 
@@ -259,15 +260,36 @@ export class Container {
     }
   }
 
+  /**
+   * @description Checks if a class is a framework class (CoreService)
+   * Framework classes can traverse the prototype chain even if they contain native code patterns
+   * @param {any} cls - The class to check
+   * @returns {boolean} True if the class is a framework class
+   */
+  private isFrameworkClass(cls: any): boolean {
+    if (!cls || cls === Object.prototype) {
+      return false;
+    }
+
+    // Check if class is marked as a CoreService
+    const isCoreService = getTypedMetadata<boolean>(CORE_SERVICE, cls);
+
+    return Boolean(isCoreService);
+  }
+
   private getPrototypeChain(Class: any): any[] {
     const chain: any[] = [];
     let currentClass = Class;
 
-    while (
-      currentClass &&
-      currentClass !== Object.prototype &&
-      (currentClass.name === 'IocEngine' || !currentClass.toString().includes('[native code]'))
-    ) {
+    while (currentClass && currentClass !== Object.prototype) {
+      const classSource = currentClass.toString();
+      const isNativeCode = classSource.includes('[native code]');
+
+      // Stop at native code unless it's a framework class
+      if (isNativeCode && !this.isFrameworkClass(currentClass)) {
+        break;
+      }
+
       chain.push(currentClass);
       currentClass = Object.getPrototypeOf(currentClass);
     }

lib/ioc/CoreContainer.ts

@@ -8,6 +8,7 @@ import { PrepareConfigService } from '../server/src/services/PrepareConfigServic
 import { PrepareWebsocketService } from '../server/src/services/PrepareWebsocketService';
 import { PrepareValidatorService } from '../server/src/services/PrepareValidatorService';
 import { PrepareStaticServeConfigService } from '../server/src/services/PrepareStaticServeConfigService';
+import { Ulak } from '../server/messaging/Ulak';
 
 /**
  * @description CoreContainer manages framework-level services
@@ -114,12 +115,16 @@ export class CoreContainer {
   }
 
   /**
-   * @description Phase 5: Register all Prepare Services
+   * @description Phase 5: Register all Prepare Services and Internal Services
    * They will inject Container and Logger automatically
    * @returns {Promise<void>}
    */
   private async registerPrepareServices(): Promise<void> {
     const services = [
+      // Internal messaging system (must be registered before prepare services)
+      { name: ICoreServiceNames.__ULAK__, Class: Ulak },
+
+      // Prepare services
       { name: ICoreServiceNames.PREPARE_MIDDLEWARE_SERVICE, Class: PrepareMiddlewareService },
       { name: ICoreServiceNames.PREPARE_CONFIG_SERVICE, Class: PrepareConfigService },
       { name: ICoreServiceNames.PREPARE_WEBSOCKET_SERVICE, Class: PrepareWebsocketService },

lib/ioc/component/decorators/Inject.ts

@@ -6,28 +6,70 @@ import { defineTypedMetadata, getOwnTypedMetadata, getTypedMetadata } from '../.
 /**
  * Property decorator to inject a dependency.
  *
- * @param {Class } Injection - The class of component to inject.
- * @param expression - The expression to evaluate on the injected class.
- * @returns {PropertyDecorator} - The property decorator function.
+ * Supports three syntaxes:
+ * 1. Class injection: `@Inject(UserService)`
+ * 2. String injection with expression: `@Inject('UserService', (s) => s.getUsers())`
+ * 3. Tuple injection (helper pattern): `@Inject(ulak('/chat'))` where ulak() returns [serviceName, expression]
+ *
+ * @param {Class | string | readonly [string, (injectedClass: any) => any]} Injection - The dependency to inject
+ * @param expression - Optional expression to evaluate on the injected class (only used with Class or string)
+ * @returns {PropertyDecorator} - The property decorator function
+ *
+ * @example
+ * ```typescript
+ * // Class injection
+ * @Inject(UserService)
+ * private userService: UserService;
+ *
+ * // String injection with expression
+ * @Inject('UserService', (s) => s.getAllUsers())
+ * private users: User[];
+ *
+ * // Tuple injection (helper pattern)
+ * @Inject(ulak('/chat'))
+ * private chat: Ulak.NameSpace<'/chat'>;
+ * ```
  */
-export const Inject = (Injection: Class | string, expression?: (injectedClass: any) => any): PropertyDecorator => {
+export const Inject = (
+  Injection: Class | string | readonly [string | Class, (injectedClass: any) => any],
+  expression?: (injectedClass: any) => any,
+): PropertyDecorator => {
   return (target: object, propertyKey: string): void => {
+    let dependencyName: string;
+    let resolvedExpression: ((injectedClass: any) => any) | undefined = expression;
+
+    // Check if Injection is a tuple [serviceName, expression]
+    if (Array.isArray(Injection) && Injection.length === 2) {
+      const [name, tupleExpression] = Injection;
+
+      // Check Name type, it can be a Class or String
+      dependencyName = typeof name === 'string' ? name : getTypedMetadata<string>(ComponentConstants.NameKey, name);
+
+      resolvedExpression = tupleExpression;
+    } else if (typeof Injection === 'string') {
+      dependencyName = Injection;
+    } else {
+      // Injection is a Class
+      dependencyName = getTypedMetadata<string>(ComponentConstants.NameKey, Injection);
+    }
+
+    // Store dependency
     const dependencies: Dependencies =
       getOwnTypedMetadata<Dependencies>(ComponentConstants.DependencyKey, target.constructor) || {};
 
     if (!dependencies[propertyKey]) {
-      dependencies[propertyKey] =
-        typeof Injection === 'string' ? Injection : getTypedMetadata<string>(ComponentConstants.NameKey, Injection);
+      dependencies[propertyKey] = dependencyName;
     }
 
     defineTypedMetadata<Dependencies>(ComponentConstants.DependencyKey, dependencies, target.constructor);
 
-    if (expression) {
+    // Store expression if provided
+    if (resolvedExpression) {
       const expressions: Expressions =
         getOwnTypedMetadata<Expressions>(ComponentConstants.ExpressionKey, target.constructor) || {};
 
       if (!expressions[propertyKey]) {
-        expressions[propertyKey] = expression;
+        expressions[propertyKey] = resolvedExpression;
       }
 
       defineTypedMetadata<Expressions>(ComponentConstants.ExpressionKey, expressions, target.constructor);

lib/ioc/types/ICoreServiceNamesType.ts

@@ -10,6 +10,9 @@ export enum ICoreServiceNames {
   IOC_ENGINE = 'IocEngine',
   ASENA_ADAPTER = 'AsenaAdapter',
 
+  // Internal Messaging Services (Phase 5)
+  __ULAK__ = '__Ulak__',
+
   // Prepare Services (Phase 5)
   PREPARE_MIDDLEWARE_SERVICE = 'PrepareMiddlewareService',
   PREPARE_CONFIG_SERVICE = 'PrepareConfigService',

lib/server/AsenaServer.ts

@@ -20,15 +20,15 @@ import * as path from 'node:path';
 import type { MiddlewareClass, ValidatorClass } from './web/middleware';
 import { ComponentConstants } from '../ioc/constants';
 import * as bun from 'bun';
-import { green, type ServerLogger, yellow } from '../logger';
+import { blue, green, type ServerLogger, yellow } from '../logger';
 import { getOwnTypedMetadata, getTypedMetadata } from '../utils/typedMetadata';
 import type { PrepareMiddlewareService } from './src/services/PrepareMiddlewareService';
 import type { PrepareConfigService } from './src/services/PrepareConfigService';
 import type { PrepareWebsocketService } from './src/services/PrepareWebsocketService';
 import type { PrepareValidatorService } from './src/services/PrepareValidatorService';
 import type { PrepareStaticServeConfigService } from './src/services/PrepareStaticServeConfigService';
-import { Inject } from '../ioc/component';
-import type { GlobalMiddlewareEntry, GlobalMiddlewareConfig } from './config/AsenaConfig';
+import { Inject, PostConstruct } from '../ioc/component';
+import type { GlobalMiddlewareConfig, GlobalMiddlewareEntry } from './config/AsenaConfig';
 
 /**
  * @description AsenaServer - Main server class for Asena framework
@@ -74,14 +74,9 @@ export class AsenaServer<A extends AsenaAdapter<any, any>> implements ICoreServi
    * @description Lifecycle hook - called after dependencies are injected
    * @returns {void}
    */
+  @PostConstruct()
   public onInit(): void {
-    this._logger.info(`
-    ___    _____  ______ _   __ ___ 
-   /   |  / ___/ / ____// | / //   |
-  / /| |  \\__ \\ / __/  /  |/ // /| |
- / ___ | ___/ // /___ / /|  // ___ |
-/_/  |_|/____//_____//_/ |_//_/  |_|  
-    `);
+    this._logger.info(`${blue('[AsenaServer]')} is initialized`);
   }
 
   /**

lib/server/AsenaServerFactory.ts

@@ -35,6 +35,15 @@ export class AsenaServerFactory {
   ): Promise<AsenaServer<A>> {
     const { adapter, logger, port, components, gc } = options;
 
+    logger.info(`
+    ___    _____  ______ _   __ ___ 
+   /   |  / ___/ / ____// | / //   |
+  / /| |  \\__ \\ / __/  /  |/ // /| |
+ / ___ | ___/ // /___ / /|  // ___ |
+/_/  |_|/____//_____//_/ |_//_/  |_|  
+------------------------------------------------------------
+    `);
+
     // Read config file
     const config = await readConfigFile();
 

lib/server/decorators/components/Controller.ts

@@ -1,6 +1,5 @@
-import { ComponentType, type ControllerParams } from '../../../ioc';
+import { ComponentConstants, ComponentType, type ControllerParams } from '../../../ioc';
 import { defineComponent } from '../../../ioc/component';
-import { ComponentConstants } from '../../../ioc';
 import { defineMiddleware } from '../../web/helper';
 import { defineTypedMetadata } from '../../../utils/typedMetadata';
 

lib/server/decorators/components/Middleware.ts

@@ -1,7 +1,6 @@
 import type { MiddlewareParams } from '../../../ioc/types/decorators/MiddlewareParams';
 import { defineComponent } from '../../../ioc/component';
-import { ComponentType } from '../../../ioc';
-import { ComponentConstants } from '../../../ioc';
+import { ComponentConstants, ComponentType } from '../../../ioc';
 import { defineTypedMetadata } from '../../../utils/typedMetadata';
 import { VALIDATOR_METHODS } from '../../../adapter';