@onebun/core 0.1.19 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -41,7 +41,7 @@
   "dependencies": {
     "effect": "^3.13.10",
     "arktype": "^2.0.0",
-    "@onebun/logger": "^0.1.6",
+    "@onebun/logger": "^0.1.7",
     "@onebun/envs": "^0.1.4",
     "@onebun/metrics": "^0.1.6",
     "@onebun/requests": "^0.1.3",

package/src/application/application.ts

@@ -554,15 +554,16 @@ export class OneBunApplication {
           // Handle WebSocket upgrade if gateways exist
           if (hasWebSocketGateways && app.wsHandler) {
             const upgradeHeader = req.headers.get('upgrade')?.toLowerCase();
-            
-            // Check for WebSocket upgrade or Socket.IO polling
-            if (upgradeHeader === 'websocket' || path.startsWith('/socket.io')) {
+            const socketioEnabled = app.options.websocket?.socketio?.enabled ?? false;
+            const socketioPath = app.options.websocket?.socketio?.path ?? '/socket.io';
+
+            const isSocketIoPath = socketioEnabled && path.startsWith(socketioPath);
+            if (upgradeHeader === 'websocket' || isSocketIoPath) {
               const response = await app.wsHandler.handleUpgrade(req, server);
               if (response === undefined) {
                 return undefined; // Successfully upgraded
               }
 
-              // Return response if upgrade failed
               return response;
             }
           }
@@ -920,7 +921,16 @@ export class OneBunApplication {
       // Initialize WebSocket gateways with server
       if (hasWebSocketGateways && this.wsHandler && this.server) {
         this.wsHandler.initializeGateways(this.server);
-        this.logger.info(`WebSocket server enabled at ws://${this.options.host}:${this.options.port}`);
+        this.logger.info(
+          `WebSocket server (native) enabled at ws://${this.options.host}:${this.options.port}`,
+        );
+        const socketioEnabled = this.options.websocket?.socketio?.enabled ?? false;
+        if (socketioEnabled) {
+          const sioPath = this.options.websocket?.socketio?.path ?? '/socket.io';
+          this.logger.info(
+            `WebSocket server (Socket.IO) enabled at ws://${this.options.host}:${this.options.port}${sioPath}`,
+          );
+        }
       }
 
       this.logger.info(`Server started on http://${this.options.host}:${this.options.port}`);

package/src/docs-examples.test.ts

@@ -2327,6 +2327,49 @@ describe('Architecture Documentation (docs/architecture.md)', () => {
       expect(SharedModule).toBeDefined();
       expect(ApiModule).toBeDefined();
     });
+
+    /**
+     * Exports are only required for cross-module injection.
+     * Within a module, any provider can be injected into controllers without being in exports.
+     */
+    it('should allow controller to inject same-module provider without exports', async () => {
+      const effectLib = await import('effect');
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const decorators = await import('./decorators/decorators');
+
+      @Service()
+      class InternalService extends BaseService {
+        getData(): string {
+          return 'internal';
+        }
+      }
+
+      @Controller('/local')
+      class LocalController extends BaseController {
+        constructor(@decorators.Inject(InternalService) private readonly internal: InternalService) {
+          super();
+        }
+        getData(): string {
+          return this.internal.getData();
+        }
+      }
+
+      @Module({
+        providers: [InternalService],
+        controllers: [LocalController],
+        // No exports - InternalService is only used inside this module
+      })
+      class LocalModule {}
+
+      const mod = new moduleMod.OneBunModule(LocalModule, testUtils.makeMockLoggerLayer());
+      mod.getLayer();
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      const controller = mod.getControllerInstance(LocalController) as LocalController;
+      expect(controller).toBeDefined();
+      expect(controller.getData()).toBe('internal');
+    });
   });
 });
 
@@ -2862,6 +2905,52 @@ describe('WebSocket Gateway API Documentation (docs/api/websocket.md)', () => {
       expect(typeof client.disconnect).toBe('function');
       expect(typeof client.on).toBe('function');
     });
+
+    it('should create client with protocol native (default)', () => {
+      @WebSocketGateway({ path: '/ws' })
+      class WsGateway extends BaseWebSocketGateway {}
+
+      @Module({ controllers: [WsGateway] })
+      class AppModule {}
+
+      const definition = createWsServiceDefinition(AppModule);
+      const client = createWsClient(definition, {
+        url: 'ws://localhost:3000/ws',
+        protocol: 'native',
+      });
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with protocol socketio', () => {
+      @WebSocketGateway({ path: '/ws' })
+      class WsGateway extends BaseWebSocketGateway {}
+
+      @Module({ controllers: [WsGateway] })
+      class AppModule {}
+
+      const definition = createWsServiceDefinition(AppModule);
+      const client = createWsClient(definition, {
+        url: 'ws://localhost:3000/socket.io',
+        protocol: 'socketio',
+      });
+      expect(client).toBeDefined();
+    });
+
+    /**
+     * @source docs/api/websocket.md#standalone-client-no-definition
+     */
+    it('should create standalone client without definition', () => {
+      const client = createNativeWsClient({
+        url: 'ws://localhost:3000/chat',
+        protocol: 'native',
+        auth: { token: 'xxx' },
+      });
+      expect(client).toBeDefined();
+      expect(typeof client.connect).toBe('function');
+      expect(typeof client.emit).toBe('function');
+      expect(typeof client.send).toBe('function');
+      expect(typeof client.on).toBe('function');
+    });
   });
 
   describe('Application Configuration', () => {
@@ -2875,7 +2964,7 @@ describe('WebSocket Gateway API Documentation (docs/api/websocket.md)', () => {
       @Module({ controllers: [TestGateway] })
       class AppModule {}
 
-      // From docs: Application Options example
+      // From docs: Application Options example (native + optional Socket.IO)
       const app = new OneBunApplication(AppModule, {
         port: 3000,
         websocket: {
@@ -2883,8 +2972,12 @@ describe('WebSocket Gateway API Documentation (docs/api/websocket.md)', () => {
           storage: {
             type: 'memory',
           },
-          pingInterval: 25000,
-          pingTimeout: 20000,
+          socketio: {
+            enabled: true,
+            path: '/socket.io',
+            pingInterval: 25000,
+            pingTimeout: 20000,
+          },
           maxPayload: 1048576,
         },
         loggerLayer: makeMockLoggerLayer(),
@@ -3161,8 +3254,10 @@ describe('WebSocket Chat Example (docs/examples/websocket-chat.md)', () => {
       const app = new OneBunApplication(ChatModule, {
         port: 3000,
         websocket: {
-          pingInterval: 25000,
-          pingTimeout: 20000,
+          socketio: {
+            pingInterval: 25000,
+            pingTimeout: 20000,
+          },
         },
         loggerLayer: makeMockLoggerLayer(),
       });
@@ -3197,10 +3292,11 @@ describe('WebSocket Chat Example (docs/examples/websocket-chat.md)', () => {
       })
       class ChatModule {}
 
-      // From docs: Typed Client example
+      // From docs: Typed Client (native) example
       const definition = createWsServiceDefinition(ChatModule);
       const client = createWsClient(definition, {
         url: 'ws://localhost:3000/chat',
+        protocol: 'native',
         auth: {
           token: 'user-jwt-token',
         },
@@ -3280,6 +3376,7 @@ import {
   SharedRedisProvider,
   createWsServiceDefinition,
   createWsClient,
+  createNativeWsClient,
   matchPattern,
   makeMockLoggerLayer,
   hasOnModuleInit,

package/src/module/module.test.ts

@@ -10,7 +10,11 @@ import {
   afterEach,
   mock,
 } from 'bun:test';
-import { Context } from 'effect';
+import {
+  Context,
+  Effect,
+  Layer,
+} from 'effect';
 
 import { Module } from '../decorators/decorators';
 import { makeMockLoggerLayer } from '../testing/test-utils';
@@ -157,7 +161,6 @@ describe('OneBunModule', () => {
 
     test('should detect circular dependencies and provide detailed error message', () => {
       const { registerDependencies } = require('../decorators/decorators');
-      const { Effect, Layer } = require('effect');
       const { LoggerService } = require('@onebun/logger');
 
       // Collect error messages
@@ -849,4 +852,145 @@ describe('OneBunModule', () => {
       expect((apiService as ApiService).getConnectionTimeout()).toBe(5000);
     });
   });
+
+  describe('Module DI scoping (exports only for cross-module)', () => {
+    const {
+      Controller: ControllerDecorator,
+      Get,
+      Inject,
+      clearGlobalModules,
+    } = require('../decorators/decorators');
+    const { Controller: BaseController } = require('./controller');
+    const { clearGlobalServicesRegistry: clearRegistry, OneBunModule: ModuleClass } = require('./module');
+
+    beforeEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    afterEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    test('controller can inject provider from same module without exports', async () => {
+      @Service()
+      class CounterService {
+        private count = 0;
+        getCount() {
+          return this.count;
+        }
+        increment() {
+          this.count += 1;
+        }
+      }
+
+      class CounterController extends BaseController {
+        constructor(@Inject(CounterService) private readonly counterService: CounterService) {
+          super();
+        }
+        getCount() {
+          return this.counterService.getCount();
+        }
+      }
+      const CounterControllerDecorated = ControllerDecorator('/counter')(CounterController);
+      Get('/')(CounterControllerDecorated.prototype, 'getCount', Object.getOwnPropertyDescriptor(CounterControllerDecorated.prototype, 'getCount')!);
+
+      @Module({
+        providers: [CounterService],
+        controllers: [CounterControllerDecorated],
+        // No exports - CounterService is only used inside this module
+      })
+      class FeatureModule {}
+
+      const module = new ModuleClass(FeatureModule, mockLoggerLayer);
+      module.getLayer();
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const controller = module.getControllerInstance(CounterControllerDecorated) as CounterController;
+      expect(controller).toBeDefined();
+      expect(controller.getCount()).toBe(0);
+    });
+
+    test('child module controller injects own provider; root can resolve controller', async () => {
+      @Service()
+      class ChildService {
+        getValue() {
+          return 'child';
+        }
+      }
+
+      class ChildController extends BaseController {
+        constructor(@Inject(ChildService) private readonly childService: ChildService) {
+          super();
+        }
+        getValue() {
+          return this.childService.getValue();
+        }
+      }
+      const ChildControllerDecorated = ControllerDecorator('/child')(ChildController);
+      Get('/')(ChildControllerDecorated.prototype, 'getValue', Object.getOwnPropertyDescriptor(ChildControllerDecorated.prototype, 'getValue')!);
+
+      @Module({
+        providers: [ChildService],
+        controllers: [ChildControllerDecorated],
+      })
+      class ChildModule {}
+
+      @Module({
+        imports: [ChildModule],
+      })
+      class RootModule {}
+
+      const rootModule = new ModuleClass(RootModule, mockLoggerLayer);
+      rootModule.getLayer();
+      await Effect.runPromise(rootModule.setup() as Effect.Effect<unknown, never, never>);
+
+      const allControllers = rootModule.getControllers();
+      expect(allControllers).toContain(ChildControllerDecorated);
+      const controller = rootModule.getControllerInstance(ChildControllerDecorated) as ChildController;
+      expect(controller).toBeDefined();
+      expect(controller.getValue()).toBe('child');
+    });
+
+    test('exported service from imported module is injectable in importing module', async () => {
+      @Service()
+      class SharedService {
+        getLabel() {
+          return 'shared';
+        }
+      }
+
+      @Module({
+        providers: [SharedService],
+        exports: [SharedService],
+      })
+      class SharedModule {}
+
+      class AppController extends BaseController {
+        constructor(@Inject(SharedService) private readonly sharedService: SharedService) {
+          super();
+        }
+        getLabel() {
+          return this.sharedService.getLabel();
+        }
+      }
+      const AppControllerDecorated = ControllerDecorator('/app')(AppController);
+      Get('/')(AppControllerDecorated.prototype, 'getLabel', Object.getOwnPropertyDescriptor(AppControllerDecorated.prototype, 'getLabel')!);
+
+      @Module({
+        imports: [SharedModule],
+        controllers: [AppControllerDecorated],
+      })
+      class AppModule {}
+
+      const module = new ModuleClass(AppModule, mockLoggerLayer);
+      module.getLayer();
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const controller = module.getControllerInstance(AppControllerDecorated) as AppController;
+      expect(controller).toBeDefined();
+      expect(controller.getLabel()).toBe('shared');
+    });
+  });
 });

package/src/module/module.ts

@@ -169,9 +169,6 @@ export class OneBunModule implements ModuleInstance {
         // Merge layers
         layer = Layer.merge(layer, childModule.getLayer());
 
-        // Add controllers from child module
-        controllers.push(...childModule.getControllers());
-
         // Get exported services from child module and register them for DI
         const exportedServices = childModule.getExportedServices();
         for (const [tag, instance] of exportedServices) {
@@ -386,48 +383,20 @@ export class OneBunModule implements ModuleInstance {
    */
   createControllerInstances(): Effect.Effect<unknown, never, void> {
     return Effect.sync(() => {
-      // Services are already created in initModule via createServicesWithDI
-      // Just need to set up controllers with DI
-
-      // Get module metadata to access providers for controller dependency registration
-      const moduleMetadata = getModuleMetadata(this.moduleClass);
-      if (moduleMetadata && moduleMetadata.providers) {
-        // Create map of available services for dependency resolution
-        const availableServices = new Map<string, Function>();
-
-        // For each provider that is a class constructor, add to available services map
-        for (const provider of moduleMetadata.providers) {
-          if (typeof provider === 'function') {
-            availableServices.set(provider.name, provider);
-          }
-        }
-
-        // Also add services from imported modules
-        for (const childModule of this.childModules) {
-          const childMetadata = getModuleMetadata(childModule.moduleClass);
-          if (childMetadata?.exports) {
-            for (const exported of childMetadata.exports) {
-              if (typeof exported === 'function') {
-                availableServices.set(exported.name, exported);
-              }
-            }
-          }
-        }
-
-        // Add global services to available services for dependency resolution
-        for (const [, instance] of globalServicesRegistry) {
-          if (instance && typeof instance === 'object') {
-            availableServices.set(instance.constructor.name, instance.constructor);
-          }
+      // Build map of available services from this module's DI scope (own providers + imported exports + global)
+      const availableServices = new Map<string, Function>();
+      for (const [, instance] of this.serviceInstances) {
+        if (instance && typeof instance === 'object') {
+          availableServices.set(instance.constructor.name, instance.constructor);
         }
+      }
 
-        // Automatically analyze and register dependencies for all controllers
-        for (const controllerClass of this.controllers) {
-          registerControllerDependencies(controllerClass, availableServices);
-        }
+      // Automatically analyze and register dependencies for all controllers of this module
+      for (const controllerClass of this.controllers) {
+        registerControllerDependencies(controllerClass, availableServices);
       }
 
-      // Now create controller instances with automatic dependency injection
+      // Create controller instances with automatic dependency injection
       this.createControllersWithDI();
     }).pipe(Effect.provide(this.rootLayer));
   }
@@ -567,7 +536,12 @@ export class OneBunModule implements ModuleInstance {
           discard: true,
         }),
       ),
-      // Then create controller instances
+      // Create controller instances in child modules first, then this module (each uses its own DI scope)
+      Effect.flatMap(() =>
+        Effect.forEach(this.childModules, (childModule) => childModule.createControllerInstances(), {
+          discard: true,
+        }),
+      ),
       Effect.flatMap(() => this.createControllerInstances()),
       // Then call onModuleInit for controllers
       Effect.flatMap(() => this.callControllersOnModuleInit()),
@@ -780,18 +754,38 @@ export class OneBunModule implements ModuleInstance {
   }
 
   /**
-   * Get all controllers from this module
+   * Get all controllers from this module and child modules (recursive).
+   * Used by the application layer for routing and lifecycle.
    */
   getControllers(): Function[] {
-    return this.controllers;
+    const fromChildren = this.childModules.flatMap((child) => child.getControllers());
+
+    return [...this.controllers, ...fromChildren];
   }
 
   /**
-   * Get controller instance
+   * Find controller instance (searches this module then child modules recursively, no logging).
    */
-  getControllerInstance(controllerClass: Function): Controller | undefined {
+  private findControllerInstance(controllerClass: Function): Controller | undefined {
     const instance = this.controllerInstances.get(controllerClass);
+    if (instance) {
+      return instance;
+    }
+    for (const childModule of this.childModules) {
+      const childInstance = childModule.findControllerInstance(controllerClass);
+      if (childInstance) {
+        return childInstance;
+      }
+    }
+
+    return undefined;
+  }
 
+  /**
+   * Get controller instance (searches this module then child modules recursively).
+   */
+  getControllerInstance(controllerClass: Function): Controller | undefined {
+    const instance = this.findControllerInstance(controllerClass);
     if (!instance) {
       this.logger.warn(`No instance found for controller ${controllerClass.name}`);
     }
@@ -800,10 +794,17 @@ export class OneBunModule implements ModuleInstance {
   }
 
   /**
-   * Get all controller instances
+   * Get all controller instances from this module and child modules (recursive).
    */
   getControllerInstances(): Map<Function, Controller> {
-    return this.controllerInstances;
+    const merged = new Map<Function, Controller>(this.controllerInstances);
+    for (const childModule of this.childModules) {
+      for (const [cls, instance] of childModule.getControllerInstances()) {
+        merged.set(cls, instance);
+      }
+    }
+
+    return merged;
   }
 
   /**

package/src/types.ts

@@ -381,18 +381,30 @@ export interface WsStorageOptions {
   };
 }
 
+/**
+ * Socket.IO-specific options (optional; when enabled, Socket.IO runs on its own path)
+ */
+export interface WebSocketSocketIOOptions {
+  /** Enable Socket.IO protocol (default: false) */
+  enabled?: boolean;
+  /** Path for Socket.IO connections (default: '/socket.io') */
+  path?: string;
+  /** Ping interval in milliseconds (default: 25000) */
+  pingInterval?: number;
+  /** Ping timeout in milliseconds (default: 20000) */
+  pingTimeout?: number;
+}
+
 /**
  * WebSocket configuration for OneBunApplication
  */
 export interface WebSocketApplicationOptions {
   /** Enable/disable WebSocket (default: auto - enabled if gateways exist) */
   enabled?: boolean;
+  /** Socket.IO options; when enabled, Socket.IO is served on socketio.path */
+  socketio?: WebSocketSocketIOOptions;
   /** Storage options */
   storage?: WsStorageOptions;
-  /** Ping interval in milliseconds for heartbeat (socket.io) */
-  pingInterval?: number;
-  /** Ping timeout in milliseconds (socket.io) */
-  pingTimeout?: number;
   /** Maximum payload size in bytes */
   maxPayload?: number;
 }

package/src/websocket/ws-base-gateway.test.ts

@@ -41,6 +41,7 @@ function createClientData(id: string, rooms: string[] = []): WsClientData {
     connectedAt: Date.now(),
     auth: null,
     metadata: {},
+    protocol: 'native',
   };
 }
 

package/src/websocket/ws-base-gateway.ts

@@ -9,11 +9,11 @@ import type { WsStorageAdapter, WsPubSubStorageAdapter } from './ws-storage';
 import type {
   WsClientData,
   WsRoom,
-  WsMessage,
   WsServer,
 } from './ws.types';
 import type { Server, ServerWebSocket } from 'bun';
 
+import { createFullEventMessage, createNativeMessage } from './ws-socketio-protocol';
 import { WsStorageEvent, isPubSubAdapter } from './ws-storage';
 
 /**
@@ -247,6 +247,16 @@ export abstract class BaseWebSocketGateway {
     }
   }
 
+  /**
+   * Encode message for client's protocol
+   * @internal
+   */
+  private _encodeMessage(protocol: WsClientData['protocol'], event: string, data: unknown): string {
+    return protocol === 'socketio'
+      ? createFullEventMessage(event, data ?? {})
+      : createNativeMessage(event, data);
+  }
+
   /**
    * Send to local client only
    * @internal
@@ -254,8 +264,7 @@ export abstract class BaseWebSocketGateway {
   private _localEmit(clientId: string, event: string, data: unknown): void {
     const socket = clientSockets.get(clientId);
     if (socket) {
-      const message: WsMessage = { event, data };
-      socket.send(JSON.stringify(message));
+      socket.send(this._encodeMessage(socket.data.protocol, event, data));
     }
   }
 
@@ -280,12 +289,11 @@ export abstract class BaseWebSocketGateway {
    * @internal
    */
   private _localBroadcast(event: string, data: unknown, excludeClientIds?: string[]): void {
-    const message = JSON.stringify({ event, data } as WsMessage);
     const excludeSet = new Set(excludeClientIds || []);
 
     for (const [clientId, socket] of clientSockets) {
       if (!excludeSet.has(clientId)) {
-        socket.send(message);
+        socket.send(this._encodeMessage(socket.data.protocol, event, data));
       }
     }
   }
@@ -323,14 +331,13 @@ export abstract class BaseWebSocketGateway {
     }
 
     const clientIds = await this.storage.getClientsInRoom(roomName);
-    const message = JSON.stringify({ event, data } as WsMessage);
     const excludeSet = new Set(excludeClientIds || []);
 
     for (const clientId of clientIds) {
       if (!excludeSet.has(clientId)) {
         const socket = clientSockets.get(clientId);
         if (socket) {
-          socket.send(message);
+          socket.send(this._encodeMessage(socket.data.protocol, event, data));
         }
       }
     }
@@ -355,15 +362,13 @@ export abstract class BaseWebSocketGateway {
       }
     }
 
-    // Send to each unique client
-    const message = JSON.stringify({ event, data } as WsMessage);
     const excludeSet = new Set(excludeClientIds || []);
 
     for (const clientId of clientIdsSet) {
       if (!excludeSet.has(clientId)) {
         const socket = clientSockets.get(clientId);
         if (socket) {
-          socket.send(message);
+          socket.send(this._encodeMessage(socket.data.protocol, event, data));
         }
       }
     }