@onebun/core 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

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

@@ -1150,6 +1150,100 @@ describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', ()
       await callOnApplicationDestroy(emptyObj, 'SIGTERM');
     });
   });
+
+  describe('Standalone Service Pattern (docs/api/services.md)', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     * Standalone services (not injected anywhere) still have their
+     * onModuleInit called. This is useful for background workers,
+     * cron jobs, event listeners, etc.
+     */
+    it('should call onModuleInit for standalone services not injected anywhere', async () => {
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const effectLib = await import('effect');
+
+      let schedulerStarted = false;
+
+      // From docs: Standalone service pattern
+      @Service()
+      class TaskSchedulerService extends BaseService implements OnModuleInit {
+        async onModuleInit(): Promise<void> {
+          // Main work happens here — no need to be injected anywhere
+          schedulerStarted = true;
+          this.logger.info('Task scheduler started');
+        }
+      }
+
+      @Module({
+        providers: [TaskSchedulerService],
+        // No controllers use this service — it works on its own
+      })
+      class SchedulerModule {}
+
+      const mod = new moduleMod.OneBunModule(SchedulerModule, testUtils.makeMockLoggerLayer());
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      // Scheduler was started even though nothing injected it
+      expect(schedulerStarted).toBe(true);
+    });
+
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     * onModuleInit is called sequentially in dependency order:
+     * dependencies complete their init before dependents start theirs.
+     */
+    it('should call onModuleInit in dependency order so dependencies are fully initialized', async () => {
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const effectLib = await import('effect');
+      const decorators = await import('./decorators/decorators');
+
+      const initOrder: string[] = [];
+
+      @Service()
+      class DatabaseService extends BaseService implements OnModuleInit {
+        private ready = false;
+
+        async onModuleInit(): Promise<void> {
+          this.ready = true;
+          initOrder.push('database');
+        }
+
+        isReady(): boolean {
+          return this.ready;
+        }
+      }
+
+      @Service()
+      class CacheService extends BaseService implements OnModuleInit {
+        private db: DatabaseService;
+
+        constructor(db: DatabaseService) {
+          super();
+          this.db = db;
+        }
+
+        async onModuleInit(): Promise<void> {
+          // At this point, DatabaseService.onModuleInit has already completed
+          initOrder.push(`cache:db-ready=${this.db.isReady()}`);
+        }
+      }
+
+      decorators.registerDependencies(CacheService, [DatabaseService]);
+
+      @Module({
+        providers: [DatabaseService, CacheService],
+      })
+      class AppModule {}
+
+      const mod = new moduleMod.OneBunModule(AppModule, testUtils.makeMockLoggerLayer());
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      // Database initialized first, then cache saw database was ready
+      expect(initOrder).toEqual(['database', 'cache:db-ready=true']);
+    });
+  });
 });
 
 describe('getService API Documentation Examples (docs/api/core.md)', () => {
@@ -2905,6 +2999,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', () => {
@@ -2918,7 +3058,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: {
@@ -2926,8 +3066,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(),
@@ -3204,8 +3348,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(),
       });
@@ -3240,10 +3386,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',
         },
@@ -3323,6 +3470,7 @@ import {
   SharedRedisProvider,
   createWsServiceDefinition,
   createWsClient,
+  createNativeWsClient,
   matchPattern,
   makeMockLoggerLayer,
   hasOnModuleInit,

package/src/module/module.test.ts

@@ -853,6 +853,188 @@ describe('OneBunModule', () => {
     });
   });
 
+  describe('Lifecycle hooks', () => {
+    const { clearGlobalModules } = require('../decorators/decorators');
+    const { clearGlobalServicesRegistry: clearRegistry, OneBunModule: ModuleClass } = require('./module');
+    const { OnModuleInit } = require('./lifecycle');
+
+    beforeEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    afterEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    test('should call onModuleInit for a service that is not injected anywhere', async () => {
+      let initCalled = false;
+
+      @Service()
+      class StandaloneService {
+        async onModuleInit(): Promise<void> {
+          initCalled = true;
+        }
+      }
+
+      @Module({
+        providers: [StandaloneService],
+        // No controllers, no exports — this service is not injected anywhere
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(initCalled).toBe(true);
+    });
+
+    test('should call onModuleInit for multiple standalone services', async () => {
+      const initLog: string[] = [];
+
+      @Service()
+      class WorkerServiceA {
+        async onModuleInit(): Promise<void> {
+          initLog.push('A');
+        }
+      }
+
+      @Service()
+      class WorkerServiceB {
+        async onModuleInit(): Promise<void> {
+          initLog.push('B');
+        }
+      }
+
+      @Service()
+      class WorkerServiceC {
+        async onModuleInit(): Promise<void> {
+          initLog.push('C');
+        }
+      }
+
+      @Module({
+        providers: [WorkerServiceA, WorkerServiceB, WorkerServiceC],
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(initLog).toContain('A');
+      expect(initLog).toContain('B');
+      expect(initLog).toContain('C');
+      expect(initLog.length).toBe(3);
+    });
+
+    test('should call onModuleInit for standalone service in a child module', async () => {
+      let childInitCalled = false;
+
+      @Service()
+      class ChildStandaloneService {
+        async onModuleInit(): Promise<void> {
+          childInitCalled = true;
+        }
+      }
+
+      @Module({
+        providers: [ChildStandaloneService],
+      })
+      class ChildModule {}
+
+      @Module({
+        imports: [ChildModule],
+      })
+      class RootModule {}
+
+      const module = new ModuleClass(RootModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(childInitCalled).toBe(true);
+    });
+
+    test('should call onModuleInit sequentially in dependency order', async () => {
+      const initLog: string[] = [];
+      const { registerDependencies } = require('../decorators/decorators');
+
+      @Service()
+      class DependencyService {
+        async onModuleInit(): Promise<void> {
+          // Simulate async work to make ordering matter
+          await new Promise<void>((resolve) => {
+            setTimeout(resolve, 5);
+          });
+          initLog.push('dependency-completed');
+        }
+
+        getValue() {
+          return 42;
+        }
+      }
+
+      @Service()
+      class DependentService {
+        async onModuleInit(): Promise<void> {
+          initLog.push('dependent-started');
+        }
+      }
+
+      // Register DependentService -> DependencyService dependency
+      registerDependencies(DependentService, [DependencyService]);
+
+      @Module({
+        providers: [DependencyService, DependentService],
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      // DependencyService.onModuleInit must complete BEFORE DependentService.onModuleInit starts
+      expect(initLog).toEqual(['dependency-completed', 'dependent-started']);
+    });
+
+    test('should have dependencies already injected when onModuleInit is called', async () => {
+      let depValueInInit: number | null = null;
+      const { registerDependencies } = require('../decorators/decorators');
+
+      @Service()
+      class ConfigService {
+        getPort() {
+          return 8080;
+        }
+      }
+
+      @Service()
+      class ServerService {
+        private configService: ConfigService;
+
+        constructor(configService: ConfigService) {
+          this.configService = configService;
+        }
+
+        async onModuleInit(): Promise<void> {
+          // At this point configService should already be injected
+          depValueInInit = this.configService.getPort();
+        }
+      }
+
+      registerDependencies(ServerService, [ConfigService]);
+
+      @Module({
+        providers: [ConfigService, ServerService],
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(depValueInInit).not.toBeNull();
+      expect(depValueInInit as unknown as number).toBe(8080);
+    });
+  });
+
   describe('Module DI scoping (exports only for cross-module)', () => {
     const {
       Controller: ControllerDecorator,

package/src/module/module.ts

@@ -555,7 +555,10 @@ export class OneBunModule implements ModuleInstance {
   }
 
   /**
-   * Call onModuleInit lifecycle hook for all services that implement it
+   * Call onModuleInit lifecycle hook for all services that implement it.
+   * Hooks are called sequentially in dependency order (dependencies first),
+   * so each service's onModuleInit completes before its dependents' onModuleInit starts.
+   * This is called for ALL services in providers, even if they are not injected anywhere.
    */
   callServicesOnModuleInit(): Effect.Effect<unknown, never, void> {
     if (this.pendingServiceInits.length === 0) {
@@ -564,25 +567,23 @@ export class OneBunModule implements ModuleInstance {
 
     this.logger.debug(`Calling onModuleInit for ${this.pendingServiceInits.length} service(s)`);
 
-    // Run all service onModuleInit hooks sequentially
-    const initPromises = this.pendingServiceInits.map(async ({ name, instance }) => {
-      try {
-        if (hasOnModuleInit(instance)) {
-          await instance.onModuleInit();
+    return Effect.promise(async () => {
+      // Run onModuleInit hooks sequentially in dependency order
+      // (pendingServiceInits is already ordered: dependencies first)
+      for (const { name, instance } of this.pendingServiceInits) {
+        try {
+          if (hasOnModuleInit(instance)) {
+            await instance.onModuleInit();
+          }
+          this.logger.debug(`Service ${name} onModuleInit completed`);
+        } catch (error) {
+          this.logger.error(`Service ${name} onModuleInit failed: ${error}`);
+          throw error;
         }
-        this.logger.debug(`Service ${name} onModuleInit completed`);
-      } catch (error) {
-        this.logger.error(`Service ${name} onModuleInit failed: ${error}`);
-        throw error;
       }
+      // Clear the list after initialization
+      this.pendingServiceInits = [];
     });
-
-    return Effect.promise(() => Promise.all(initPromises)).pipe(
-      Effect.map(() => {
-        // Clear the list after initialization
-        this.pendingServiceInits = [];
-      }),
-    );
   }
 
   /**
@@ -764,24 +765,35 @@ export class OneBunModule implements ModuleInstance {
   }
 
   /**
-   * Get controller instance (searches this module then child modules recursively).
+   * 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.getControllerInstance(controllerClass);
+      const childInstance = childModule.findControllerInstance(controllerClass);
       if (childInstance) {
         return childInstance;
       }
     }
-    this.logger.warn(`No instance found for controller ${controllerClass.name}`);
 
     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}`);
+    }
+
+    return instance;
+  }
+
   /**
    * Get all controller instances from this module and child modules (recursive).
    */

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