@onebun/core 0.1.20 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "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

@@ -2905,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', () => {
@@ -2918,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: {
@@ -2926,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(),
@@ -3204,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(),
       });
@@ -3240,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',
         },
@@ -3323,6 +3376,7 @@ import {
   SharedRedisProvider,
   createWsServiceDefinition,
   createWsClient,
+  createNativeWsClient,
   matchPattern,
   makeMockLoggerLayer,
   hasOnModuleInit,

package/src/module/module.ts

@@ -764,24 +764,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));
         }
       }
     }

package/src/websocket/ws-client.test.ts

@@ -15,7 +15,7 @@ import type { WsServiceDefinition } from './ws-service-definition';
 
 import { useFakeTimers } from '../testing/test-utils';
 
-import { createWsClient } from './ws-client';
+import { createWsClient, createNativeWsClient } from './ws-client';
 import { WsConnectionState } from './ws-client.types';
 import { WsHandlerType } from './ws.types';
 
@@ -114,7 +114,7 @@ describe('WsClient', () => {
     it('should create client with default options', () => {
       const definition = createMockDefinition();
       const client = createWsClient(definition, { url: 'ws://localhost:3000' });
-      
+
       expect(client).toBeDefined();
       expect(typeof client.connect).toBe('function');
       expect(typeof client.disconnect).toBe('function');
@@ -123,6 +123,40 @@ describe('WsClient', () => {
     });
   });
 
+  describe('createNativeWsClient', () => {
+    it('should create standalone client without definition', () => {
+      const client = createNativeWsClient({ url: 'ws://localhost:3000/chat' });
+
+      expect(client).toBeDefined();
+      expect(typeof client.connect).toBe('function');
+      expect(typeof client.disconnect).toBe('function');
+      expect(typeof client.isConnected).toBe('function');
+      expect(typeof client.getState).toBe('function');
+      expect(typeof client.on).toBe('function');
+      expect(typeof client.off).toBe('function');
+      expect(typeof client.emit).toBe('function');
+      expect(typeof client.send).toBe('function');
+    });
+
+    it('should connect and use emit/send/on like typed client', async () => {
+      const client = createNativeWsClient({ url: 'ws://localhost:3000/chat' });
+      await client.connect();
+
+      const ws = MockWebSocket.getLastInstance();
+      expect(ws).toBeDefined();
+      expect(client.isConnected()).toBe(true);
+
+      client.on('welcome', (data) => expect(data).toBeDefined());
+      ws?.receiveMessage(JSON.stringify({ event: 'welcome', data: { msg: 'hi' } }));
+
+      client.send('ping', {});
+      expect(ws?.sentMessages.some((m) => m.includes('ping'))).toBe(true);
+
+      client.disconnect();
+      expect(client.isConnected()).toBe(false);
+    });
+  });
+
   describe('connect', () => {
     it('should connect to WebSocket server', async () => {
       const definition = createMockDefinition();
@@ -312,20 +346,23 @@ describe('WsClient', () => {
       expect(handler).toHaveBeenCalled();
     });
 
-    it('should handle Engine.IO PING packet', async () => {
+    it('should handle Engine.IO PING packet when using Socket.IO protocol', async () => {
       const definition = createMockDefinition();
-      const client = createWsClient(definition, { url: 'ws://localhost:3000' });
-      
+      const client = createWsClient(definition, {
+        url: 'ws://localhost:3000/socket.io',
+        protocol: 'socketio',
+      });
+
       await client.connect();
-      
+
       const ws = MockWebSocket.getLastInstance();
       if (ws) {
-        ws.sentMessages.length = 0; // Clear previous messages
-        
+        ws.sentMessages.length = 0;
+
         // Send PING (Engine.IO packet type 2)
         ws.receiveMessage('2');
       }
-      
+
       // Should respond with PONG (Engine.IO packet type 3)
       expect(ws?.sentMessages).toContain('3');
     });

package/src/websocket/ws-client.ts

@@ -6,27 +6,49 @@
  */
 
 /* eslint-disable @typescript-eslint/no-magic-numbers */
+/* eslint-disable import/order -- type vs value from same path; keep single mixed import */
 
-import type {
-  WsClientOptions,
-  WsClient,
-  WsGatewayClient,
-  WsEventListener,
-  WsClientEvent,
-  WsClientEventListeners,
-  PendingRequest,
-  TypedWsClient,
+import {
+  type NativeWsClient,
+  type PendingRequest,
+  type TypedWsClient,
+  type WsClient,
+  type WsClientEventListeners,
+  type WsClientEvent,
+  type WsClientOptions,
+  type WsEventListener,
+  type WsGatewayClient,
+  WsConnectionState,
 } from './ws-client.types';
 import type { WsServiceDefinition } from './ws-service-definition';
 
-import { WsConnectionState } from './ws-client.types';
+/** Client lifecycle event names (subscriptions go to client, not server events) */
+const WS_CLIENT_EVENTS: WsClientEvent[] = [
+  'connect',
+  'disconnect',
+  'error',
+  'reconnect',
+  'reconnect_attempt',
+  'reconnect_failed',
+];
+
+function isClientEvent(event: string): event is WsClientEvent {
+  return WS_CLIENT_EVENTS.includes(event as WsClientEvent);
+}
+
+/** Dummy definition for standalone client (single logical gateway) */
+const NATIVE_WS_DUMMY_DEFINITION: WsServiceDefinition = {
+  _module: null,
+  _endpoints: [],
+  _gateways: new Map([['default', { name: 'default', path: '/', events: new Map() }]]),
+};
 import { matchPattern, isPattern } from './ws-pattern-matcher';
 import {
   parseMessage,
   createPongPacket,
+  createFullEventMessage,
   EngineIOPacketType,
   SocketIOPacketType,
-  isNativeMessage,
   parseNativeMessage,
   createNativeMessage,
 } from './ws-socketio-protocol';
@@ -35,6 +57,7 @@ import {
  * Default client options
  */
 const DEFAULT_OPTIONS: Partial<WsClientOptions> = {
+  protocol: 'native',
   reconnect: true,
   reconnectInterval: 1000,
   maxReconnectAttempts: 10,
@@ -85,23 +108,22 @@ class WsClientImpl<TDef extends WsServiceDefinition> implements WsClient<TDef> {
         let url = this.options.url;
         const params = new URLSearchParams();
 
-        // Add Socket.IO parameters
-        params.set('EIO', '4');
-        params.set('transport', 'websocket');
+        const protocol = this.options.protocol ?? 'native';
+        if (protocol === 'socketio') {
+          params.set('EIO', '4');
+          params.set('transport', 'websocket');
+        }
 
-        // Add auth token
         if (this.options.auth?.token) {
           params.set('token', this.options.auth.token);
         }
 
-        // Add namespace
         if (this.options.namespace) {
           params.set('namespace', this.options.namespace);
         }
 
-        // Append params to URL
         const separator = url.includes('?') ? '&' : '?';
-        url = `${url}${separator}${params.toString()}`;
+        url = params.toString() ? `${url}${separator}${params.toString()}` : url;
 
         // Create WebSocket connection
         // Use globalThis.WebSocket for browser compatibility
@@ -204,23 +226,22 @@ class WsClientImpl<TDef extends WsServiceDefinition> implements WsClient<TDef> {
    * Handle incoming message
    */
   private handleMessage(data: string): void {
-    // Try native format first
-    if (isNativeMessage(data)) {
+    const protocol = this.options.protocol ?? 'native';
+
+    if (protocol === 'native') {
       const native = parseNativeMessage(data);
       if (native) {
         this.handleEvent(native.event, native.data, native.ack);
-
-        return;
       }
+
+      return;
     }
 
-    // Parse Socket.IO format
+    // Socket.IO format
     const { engineIO, socketIO } = parseMessage(data);
 
-    // Handle Engine.IO packets
     switch (engineIO.type) {
       case EngineIOPacketType.OPEN:
-        // Handle handshake
         if (engineIO.data) {
           try {
             const handshake = JSON.parse(engineIO.data as string);
@@ -239,7 +260,6 @@ class WsClientImpl<TDef extends WsServiceDefinition> implements WsClient<TDef> {
         return;
 
       case EngineIOPacketType.PONG:
-        // Server responded to our ping
         return;
 
       case EngineIOPacketType.CLOSE:
@@ -248,7 +268,6 @@ class WsClientImpl<TDef extends WsServiceDefinition> implements WsClient<TDef> {
         return;
 
       case EngineIOPacketType.MESSAGE:
-        // Socket.IO packet
         if (socketIO) {
           this.handleSocketIOPacket(socketIO);
         }
@@ -468,8 +487,11 @@ class WsClientImpl<TDef extends WsServiceDefinition> implements WsClient<TDef> {
       throw new Error('Not connected');
     }
 
-    // Use native format (simpler)
-    const message = createNativeMessage(event, data, ackId);
+    const protocol = this.options.protocol ?? 'native';
+    const message =
+      protocol === 'socketio'
+        ? createFullEventMessage(event, data ?? {}, '/', ackId)
+        : createNativeMessage(event, data, ackId);
     this.ws.send(message);
   }
 
@@ -626,3 +648,64 @@ export function createWsClient<TDef extends WsServiceDefinition>(
     },
   });
 }
+
+/**
+ * Create a standalone WebSocket client without a service definition.
+ * Uses the same native message format and API (emit, send, on, off) as the typed client.
+ * Use in frontend or when you do not want to depend on backend modules.
+ *
+ * @param options - Client options (url, protocol, auth, reconnect, etc.)
+ * @returns Standalone client with connect, disconnect, on, off, emit, send
+ *
+ * @example
+ * ```typescript
+ * import { createNativeWsClient } from '@onebun/core';
+ *
+ * const client = createNativeWsClient({
+ *   url: 'ws://localhost:3000/chat',
+ *   protocol: 'native',
+ *   auth: { token: 'xxx' },
+ * });
+ *
+ * await client.connect();
+ * client.on('welcome', (data) => console.log(data));
+ * client.on('connect', () => console.log('Connected'));
+ *
+ * await client.emit('chat:message', { text: 'Hello' });
+ * client.send('typing', {});
+ * client.disconnect();
+ * ```
+ */
+export function createNativeWsClient(options: WsClientOptions): NativeWsClient {
+  const typed = createWsClient(NATIVE_WS_DUMMY_DEFINITION, options);
+  const gateway = (typed as unknown as Record<string, WsGatewayClient>).default;
+
+  return {
+    connect: () => typed.connect(),
+    disconnect: () => typed.disconnect(),
+    isConnected: () => typed.isConnected(),
+    getState: () => typed.getState(),
+
+    on(event: string, listener: WsEventListener | WsClientEventListeners[WsClientEvent]): void {
+      if (isClientEvent(event)) {
+        typed.on(event, listener as WsClientEventListeners[typeof event]);
+      } else {
+        gateway.on(event, listener as WsEventListener);
+      }
+    },
+
+    off(
+      event: string,
+      listener?: WsEventListener | WsClientEventListeners[WsClientEvent],
+    ): void {
+      if (isClientEvent(event)) {
+        typed.off(event, listener as WsClientEventListeners[typeof event]);
+      } else {
+        gateway.off(event, listener as WsEventListener);
+      }
+    },
+
+    emit: <T = unknown>(event: string, data?: unknown) => gateway.emit<T>(event, data),
+    send: (event: string, data?: unknown) => gateway.send(event, data),
+  };
+}

package/src/websocket/ws-client.types.ts

@@ -6,12 +6,19 @@
 
 import type { WsServiceDefinition, WsGatewayDefinition } from './ws-service-definition';
 
+/**
+ * WebSocket protocol to use when connecting
+ */
+export type WsClientProtocol = 'native' | 'socketio';
+
 /**
  * Options for WebSocket client
  */
 export interface WsClientOptions {
-  /** WebSocket server URL */
+  /** WebSocket server URL (for Socket.IO use the server root or socketio path, e.g. ws://host/socket.io) */
   url: string;
+  /** Protocol to use (default: 'native') */
+  protocol?: WsClientProtocol;
   /** Authentication options */
   auth?: {
     /** Bearer token */
@@ -127,3 +134,25 @@ export interface PendingRequest {
   reject: (error: Error) => void;
   timeout: ReturnType<typeof setTimeout>;
 }
+
+/**
+ * Standalone WebSocket client (no service definition).
+ * Same message format and API as the typed client, but without gateway proxies.
+ * Use in frontend or when you do not want to depend on backend module/definitions.
+ */
+export interface NativeWsClient {
+  connect(): Promise<void>;
+  disconnect(): void;
+  isConnected(): boolean;
+  getState(): WsConnectionState;
+  /** Lifecycle events: connect, disconnect, error, reconnect, reconnect_attempt, reconnect_failed */
+  on<E extends WsClientEvent>(event: E, listener: WsClientEventListeners[E]): void;
+  /** Server events (event names from your gateway) */
+  on<T = unknown>(event: string, listener: WsEventListener<T>): void;
+  off<E extends WsClientEvent>(event: E, listener?: WsClientEventListeners[E]): void;
+  off(event: string, listener?: WsEventListener): void;
+  /** Send event and wait for acknowledgement */
+  emit<T = unknown>(event: string, data?: unknown): Promise<T>;
+  /** Send event without waiting for response */
+  send(event: string, data?: unknown): void;
+}

package/src/websocket/ws-guards.test.ts

@@ -32,6 +32,7 @@ describe('ws-guards', () => {
     connectedAt: Date.now(),
     auth: null,
     metadata: {},
+    protocol: 'native',
     ...overrides,
   });
 

package/src/websocket/ws-handler.ts

@@ -13,6 +13,7 @@ import type {
   WsHandlerMetadata,
   WebSocketApplicationOptions,
 } from './ws.types';
+import type { WsHandlerResponse } from './ws.types';
 import type { Server, ServerWebSocket } from 'bun';
 
 import type { SyncLogger } from '@onebun/logger';
@@ -30,7 +31,6 @@ import {
   createFullEventMessage,
   EngineIOPacketType,
   SocketIOPacketType,
-  isNativeMessage,
   parseNativeMessage,
   createNativeMessage,
   DEFAULT_PING_INTERVAL,
@@ -68,14 +68,19 @@ export class WsHandler {
   private pingTimeoutMs: number;
   private maxPayload: number;
   private pingIntervals: Map<string, ReturnType<typeof setInterval>> = new Map();
+  private socketioEnabled: boolean;
+  private socketioPath: string;
 
   constructor(
     private logger: SyncLogger,
     private options: WebSocketApplicationOptions = {},
   ) {
     this.storage = new InMemoryWsStorage();
-    this.pingIntervalMs = options.pingInterval ?? DEFAULT_PING_INTERVAL;
-    this.pingTimeoutMs = options.pingTimeout ?? DEFAULT_PING_TIMEOUT;
+    const socketio = options.socketio;
+    this.socketioEnabled = socketio?.enabled ?? false;
+    this.socketioPath = socketio?.path ?? '/socket.io';
+    this.pingIntervalMs = socketio?.pingInterval ?? DEFAULT_PING_INTERVAL;
+    this.pingTimeoutMs = socketio?.pingTimeout ?? DEFAULT_PING_TIMEOUT;
     this.maxPayload = options.maxPayload ?? DEFAULT_MAX_PAYLOAD;
   }
 
@@ -183,15 +188,20 @@ export class WsHandler {
     const url = new URL(req.url);
     const path = url.pathname;
 
-    // Find matching gateway
-    const gateway = this.getGatewayForPath(path);
-    if (!gateway) {
-      return new Response('Not Found', { status: 404 });
+    let protocol: WsClientData['protocol'] = 'native';
+
+    if (this.socketioEnabled && path.startsWith(this.socketioPath)) {
+      protocol = 'socketio';
+    } else {
+      const gateway = this.getGatewayForPath(path);
+      if (!gateway) {
+        return new Response('Not Found', { status: 404 });
+      }
     }
 
     // Extract auth from query or headers
-    const token = url.searchParams.get('token') || 
-                  req.headers.get('Authorization')?.replace('Bearer ', '');
+    const token = url.searchParams.get('token') ||
+      req.headers.get('Authorization')?.replace('Bearer ', '');
 
     // Create client ID
     const clientId = crypto.randomUUID();
@@ -201,11 +211,14 @@ export class WsHandler {
       id: clientId,
       rooms: [],
       connectedAt: Date.now(),
-      auth: token ? {
-        authenticated: false,
-        token,
-      } : null,
+      auth: token
+        ? {
+          authenticated: false,
+          token,
+        }
+        : null,
       metadata: {},
+      protocol,
     };
 
     // Try to upgrade
@@ -225,7 +238,7 @@ export class WsHandler {
    */
   private async handleOpen(ws: ServerWebSocket<WsClientData>): Promise<void> {
     const client = ws.data;
-    this.logger.debug(`WebSocket client connected: ${client.id}`);
+    this.logger.debug(`WebSocket client connected: ${client.id} (${client.protocol})`);
 
     // Store client
     await this.storage.addClient(client);
@@ -235,16 +248,16 @@ export class WsHandler {
       gateway.instance._registerSocket(client.id, ws);
     }
 
-    // Send Socket.IO handshake
-    const handshake = createHandshake(client.id, {
-      pingInterval: this.pingIntervalMs,
-      pingTimeout: this.pingTimeoutMs,
-      maxPayload: this.maxPayload,
-    });
-    ws.send(createOpenPacket(handshake));
-
-    // Start ping interval
-    this.startPingInterval(client.id, ws);
+    if (client.protocol === 'socketio') {
+      // Send Socket.IO handshake
+      const handshake = createHandshake(client.id, {
+        pingInterval: this.pingIntervalMs,
+        pingTimeout: this.pingTimeoutMs,
+        maxPayload: this.maxPayload,
+      });
+      ws.send(createOpenPacket(handshake));
+      this.startPingInterval(client.id, ws);
+    }
 
     // Call OnConnect handlers
     for (const [_, gateway] of this.gateways) {
@@ -253,7 +266,7 @@ export class WsHandler {
         try {
           const result = await this.executeHandler(gateway, handler, ws, undefined, {});
           if (result && isWsHandlerResponse(result)) {
-            ws.send(createNativeMessage(result.event, result.data));
+            ws.send(this.encodeResponse(client.protocol, result));
           }
         } catch (error) {
           this.logger.error(`Error in OnConnect handler: ${error}`);
@@ -262,6 +275,25 @@ export class WsHandler {
     }
   }
 
+  /**
+   * Encode handler response for the client's protocol
+   */
+  private encodeResponse(
+    protocol: WsClientData['protocol'],
+    result: WsHandlerResponse,
+    ackId?: number,
+  ): string {
+    if (protocol === 'socketio') {
+      if (ackId !== undefined) {
+        return createFullAckMessage(ackId, result);
+      }
+
+      return createFullEventMessage(result.event, result.data);
+    }
+
+    return createNativeMessage(result.event, result.data, ackId);
+  }
+
   /**
    * Handle incoming message
    */
@@ -270,21 +302,20 @@ export class WsHandler {
     message: string | Buffer,
   ): Promise<void> {
     const messageStr = typeof message === 'string' ? message : message.toString();
+    const protocol = ws.data.protocol;
 
-    // Try native format first
-    if (isNativeMessage(messageStr)) {
+    if (protocol === 'native') {
       const native = parseNativeMessage(messageStr);
       if (native) {
         await this.routeMessage(ws, native.event, native.data, native.ack);
-
-        return;
       }
+
+      return;
     }
 
-    // Parse Socket.IO format
+    // Socket.IO format
     const { engineIO, socketIO } = parseMessage(messageStr);
 
-    // Handle Engine.IO packets
     switch (engineIO.type) {
       case EngineIOPacketType.PING:
         ws.send(createPongPacket(engineIO.data as string | undefined));
@@ -292,7 +323,6 @@ export class WsHandler {
         return;
 
       case EngineIOPacketType.PONG:
-        // Client responded to ping - connection is alive
         return;
 
       case EngineIOPacketType.CLOSE:
@@ -301,7 +331,6 @@ export class WsHandler {
         return;
 
       case EngineIOPacketType.MESSAGE:
-        // Socket.IO packet
         if (socketIO) {
           await this.handleSocketIOPacket(ws, socketIO);
         }
@@ -378,14 +407,10 @@ export class WsHandler {
         if (match.matched) {
           try {
             const result = await this.executeHandler(gateway, handler, ws, data, match.params);
-            
+
             // Send response
-            if (result !== undefined) {
-              if (ackId !== undefined) {
-                ws.send(createFullAckMessage(ackId, result));
-              } else if (isWsHandlerResponse(result)) {
-                ws.send(createNativeMessage(result.event, result.data));
-              }
+            if (result !== undefined && isWsHandlerResponse(result)) {
+              ws.send(this.encodeResponse(ws.data.protocol, result, ackId));
             }
           } catch (error) {
             this.logger.error(`Error in message handler: ${error}`);
@@ -430,12 +455,8 @@ export class WsHandler {
         if (match.matched) {
           try {
             const result = await this.executeHandler(gateway, handler, ws, data, match.params, roomName);
-            if (result !== undefined) {
-              if (ackId !== undefined) {
-                ws.send(createFullAckMessage(ackId, result));
-              } else if (isWsHandlerResponse(result)) {
-                ws.send(createNativeMessage(result.event, result.data));
-              }
+            if (result !== undefined && isWsHandlerResponse(result)) {
+              ws.send(this.encodeResponse(ws.data.protocol, result, ackId));
             }
           } catch (error) {
             this.logger.error(`Error in OnJoinRoom handler: ${error}`);
@@ -478,12 +499,8 @@ export class WsHandler {
         if (match.matched) {
           try {
             const result = await this.executeHandler(gateway, handler, ws, data, match.params, roomName);
-            if (result !== undefined) {
-              if (ackId !== undefined) {
-                ws.send(createFullAckMessage(ackId, result));
-              } else if (isWsHandlerResponse(result)) {
-                ws.send(createNativeMessage(result.event, result.data));
-              }
+            if (result !== undefined && isWsHandlerResponse(result)) {
+              ws.send(this.encodeResponse(ws.data.protocol, result, ackId));
             }
           } catch (error) {
             this.logger.error(`Error in OnLeaveRoom handler: ${error}`);

package/src/websocket/ws-storage-memory.test.ts

@@ -28,6 +28,7 @@ describe('InMemoryWsStorage', () => {
       connectedAt: Date.now(),
       auth: null,
       metadata: {},
+      protocol: 'native',
     });
 
     it('should add and retrieve a client', async () => {
@@ -135,6 +136,7 @@ describe('InMemoryWsStorage', () => {
       connectedAt: Date.now(),
       auth: null,
       metadata: {},
+      protocol: 'native',
     });
 
     it('should add client to room', async () => {
@@ -227,6 +229,7 @@ describe('InMemoryWsStorage', () => {
         connectedAt: Date.now(),
         auth: null,
         metadata: {},
+        protocol: 'native',
       };
       await storage.addClient(client);
       await storage.createRoom({ name: 'test-room', clientIds: [] });

package/src/websocket/ws-storage-redis.test.ts

@@ -78,6 +78,7 @@ describe('RedisWsStorage', () => {
     connectedAt: Date.now(),
     auth: null,
     metadata: {},
+    protocol: 'native',
     ...options,
   });
 

package/src/websocket/ws.types.ts

@@ -26,6 +26,11 @@ export interface WsAuthData {
   token?: string;
 }
 
+/**
+ * WebSocket protocol used by the client
+ */
+export type WsProtocol = 'native' | 'socketio';
+
 /**
  * WebSocket client data (fixed fields)
  */
@@ -40,6 +45,8 @@ export interface WsClientData {
   auth: WsAuthData | null;
   /** Custom metadata */
   metadata: Record<string, unknown>;
+  /** Protocol used by the client */
+  protocol: WsProtocol;
 }
 
 /**
@@ -178,18 +185,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;
 }
@@ -315,15 +334,19 @@ export function isWsHandlerResponse(value: unknown): value is WsHandlerResponse
  * Check if value is a valid WsClientData
  */
 export function isWsClientData(value: unknown): value is WsClientData {
+  const v = value as WsClientData;
+
   return (
     typeof value === 'object' &&
     value !== null &&
     'id' in value &&
-    typeof (value as WsClientData).id === 'string' &&
+    typeof v.id === 'string' &&
     'rooms' in value &&
-    Array.isArray((value as WsClientData).rooms) &&
+    Array.isArray(v.rooms) &&
     'connectedAt' in value &&
-    typeof (value as WsClientData).connectedAt === 'number'
+    typeof v.connectedAt === 'number' &&
+    'protocol' in value &&
+    (v.protocol === 'native' || v.protocol === 'socketio')
   );
 }