@onebun/core 0.1.19 → 0.1.21

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