@ooneex/socket-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ooneex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @ooneex/socket-client
+
+WebSocket client for real-time bidirectional communication with automatic reconnection, event handling, and typed message serialization.
+
+![Browser](https://img.shields.io/badge/Browser-Compatible-green?style=flat-square&logo=googlechrome)
+![Bun](https://img.shields.io/badge/Bun-Compatible-orange?style=flat-square&logo=bun)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)
+![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+
+## Features
+
+✅ **Socket Class** - WebSocket client with typed send and receive operations via the `Socket` class
+
+✅ **Message Queuing** - Automatically queues messages sent before the connection is open and flushes them on connect
+
+✅ **Typed Events** - Register handlers for `onMessage`, `onOpen`, `onClose`, and `onError` with typed responses
+
+✅ **JSON Serialization** - Automatic JSON serialization for outgoing messages and deserialization for incoming responses
+
+✅ **Protocol Auto-Detection** - Automatically converts HTTP/HTTPS URLs to WS/WSS WebSocket protocols
+
+✅ **Generic Type Parameters** - Parameterize `Socket<SendData, Response>` for type-safe request and response data
+
+✅ **ISocket Interface** - Standard interface defining the WebSocket client contract
+
+✅ **Locale Support** - Request data type includes optional language/locale information
+
+## Installation
+
+```bash
+bun add @ooneex/socket-client
+```
+
+## Usage
+
+### Basic Connection
+
+```typescript
+import { Socket } from '@ooneex/socket-client';
+
+const socket = new Socket('wss://api.example.com/ws/chat');
+
+socket.onOpen(() => {
+  console.log('Connected');
+});
+
+socket.onMessage((response) => {
+  console.log('Received:', response);
+});
+
+socket.onClose((event) => {
+  console.log('Disconnected:', event.code, event.reason);
+});
+
+socket.onError((event) => {
+  console.error('Error:', event);
+});
+```
+
+### Sending Messages
+
+```typescript
+import { Socket } from '@ooneex/socket-client';
+
+const socket = new Socket('wss://api.example.com/ws/messages');
+
+// Messages are queued if the connection is not yet open
+socket.send({
+  payload: { message: 'Hello, world!' },
+  queries: { room: 'general' }
+});
+```
+
+### Typed Socket
+
+```typescript
+import { Socket, type RequestDataType } from '@ooneex/socket-client';
+
+interface ChatRequest extends RequestDataType {
+  payload: { message: string; type: 'text' | 'image' };
+}
+
+interface ChatResponse {
+  event: string;
+  data: { messageId: string; timestamp: string };
+}
+
+const socket = new Socket<ChatRequest, ChatResponse>(
+  'wss://api.example.com/ws/chat'
+);
+
+socket.onMessage((response) => {
+  // response is typed as ResponseDataType<ChatResponse>
+  console.log(response.data.event);
+});
+
+socket.send({
+  payload: { message: 'Hello!', type: 'text' }
+});
+```
+
+### Closing a Connection
+
+```typescript
+import { Socket } from '@ooneex/socket-client';
+
+const socket = new Socket('wss://api.example.com/ws');
+
+// Close with a status code and reason
+socket.close(1000, 'User disconnected');
+```
+
+## API Reference
+
+### Classes
+
+#### `Socket<SendData, Response>`
+
+WebSocket client class with typed messaging.
+
+**Constructor:**
+- `url: string` - WebSocket URL (supports `ws://`, `wss://`, `http://`, `https://`, or bare hostnames)
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `send(data)` | `void` | Send typed data as JSON (queued if not yet connected) |
+| `close(code?, reason?)` | `void` | Close the WebSocket connection |
+| `onMessage(handler)` | `void` | Register a handler for incoming messages |
+| `onOpen(handler)` | `void` | Register a handler for connection open |
+| `onClose(handler)` | `void` | Register a handler for connection close |
+| `onError(handler)` | `void` | Register a handler for errors |
+
+### Interfaces
+
+#### `ISocket<SendData, Response>`
+
+Interface defining the WebSocket client contract.
+
+### Types
+
+#### `RequestDataType`
+
+```typescript
+type RequestDataType = {
+  payload?: Record<string, unknown>;
+  queries?: Record<string, boolean | number | bigint | string>;
+  language?: LocaleInfoType;
+};
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `bun install`
+3. Run tests: `bun run test`
+4. Build the project: `bun run build`
+
+### Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Update documentation for API changes
+- Ensure all tests pass before submitting PR
+
+---
+
+Made with ❤️ by the Ooneex team

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { ResponseDataType as ResponseDataType2 } from "@ooneex/http-response";
+import { ResponseDataType } from "@ooneex/http-response";
+import { LocaleInfoType } from "@ooneex/translation";
+type RequestDataType = {
+	payload?: Record<string, unknown>;
+	queries?: Record<string, boolean | number | bigint | string>;
+	language?: LocaleInfoType;
+};
+interface ISocket<
+	SendData extends RequestDataType = RequestDataType,
+	Response extends Record<string, unknown> = Record<string, unknown>
+> {
+	close: (code?: number, reason?: string) => void;
+	send: (data: SendData) => void;
+	onMessage: (handler: (response: ResponseDataType<Response>) => void) => void;
+	onOpen: (handler: (event: Event) => void) => void;
+	onClose: (handler: (event: CloseEvent) => void) => void;
+	onError: (handler: (event: Event, response?: ResponseDataType<Response>) => void) => void;
+}
+declare class Socket<
+	SendData extends RequestDataType = RequestDataType,
+	Response extends Record<string, unknown> = Record<string, unknown>
+> implements ISocket<SendData, Response> {
+	private readonly url;
+	private ws;
+	private messageHandler?;
+	private openHandler?;
+	private errorHandler?;
+	private closeHandler?;
+	private queuedMessages;
+	constructor(url: string);
+	close(code?: number, reason?: string): void;
+	send(data: SendData): void;
+	private sendRaw;
+	onMessage(handler: (response: ResponseDataType2<Response>) => void): void;
+	onOpen(handler: (event: Event) => void): void;
+	onClose(handler: (event: CloseEvent) => void): void;
+	onError(handler: (event: Event, response?: ResponseDataType2<Response>) => void): void;
+	private buildURL;
+	private setupEventHandlers;
+	private flushQueuedMessages;
+}
+export { Socket, RequestDataType, ISocket };

package/dist/index.js

@@ -0,0 +1,3 @@
+class n{url;ws;messageHandler;openHandler;errorHandler;closeHandler;queuedMessages=[];constructor(e){this.url=e;let o=this.buildURL(this.url);this.ws=new WebSocket(o),this.setupEventHandlers()}close(e,o){this.ws.close(e,o)}send(e){let o=JSON.stringify(e);this.sendRaw(o)}sendRaw(e){if(this.ws&&this.ws.readyState===WebSocket.OPEN)this.ws.send(e);else this.queuedMessages.push(e)}onMessage(e){this.messageHandler=e}onOpen(e){this.openHandler=e}onClose(e){this.closeHandler=e}onError(e){this.errorHandler=e}buildURL(e){if(e.startsWith("ws://")||e.startsWith("wss://"))return e;if(e.startsWith("http://"))e=e.replace("http://","ws://");else if(e.startsWith("https://"))e=e.replace("https://","wss://");else if(!e.startsWith("ws://")&&!e.startsWith("wss://"))e=`wss://${e}`;return e}setupEventHandlers(){this.ws.onmessage=(e)=>{if(this.messageHandler){let o=JSON.parse(e.data);if(o.done)this.ws.close();if(o.success){this.messageHandler(o);return}if(this.errorHandler)this.errorHandler(e,o)}},this.ws.onopen=(e)=>{if(this.flushQueuedMessages(),this.openHandler)this.openHandler(e)},this.ws.onerror=(e)=>{if(this.errorHandler)this.errorHandler(e)},this.ws.onclose=(e)=>{if(this.closeHandler)this.closeHandler(e)}}flushQueuedMessages(){while(this.queuedMessages.length>0){let e=this.queuedMessages.shift();if(e!==void 0&&this.ws.readyState===WebSocket.OPEN)this.ws.send(e)}}}export{n as Socket};
+
+//# debugId=222449767EFA071D64756E2164756E21

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["src/Socket.ts"],
+  "sourcesContent": [
+    "import type { ResponseDataType } from \"@ooneex/http-response\";\nimport type { ISocket, RequestDataType } from \"./types\";\n\nexport class Socket<\n  SendData extends RequestDataType = RequestDataType,\n  Response extends Record<string, unknown> = Record<string, unknown>,\n> implements ISocket<SendData, Response>\n{\n  private ws: WebSocket;\n  private messageHandler?: (response: ResponseDataType<Response>) => void;\n  private openHandler?: (event: Event) => void;\n  private errorHandler?: (event: Event, response?: ResponseDataType<Response>) => void;\n  private closeHandler?: (event: CloseEvent) => void;\n  private queuedMessages: (string | ArrayBufferLike | Blob | ArrayBufferView)[] = [];\n\n  constructor(private readonly url: string) {\n    const fullURL = this.buildURL(this.url);\n    this.ws = new WebSocket(fullURL);\n    this.setupEventHandlers();\n  }\n\n  public close(code?: number, reason?: string): void {\n    this.ws.close(code, reason);\n  }\n\n  public send(data: SendData): void {\n    const text = JSON.stringify(data);\n    this.sendRaw(text);\n  }\n\n  private sendRaw(payload: string | ArrayBufferLike | Blob | ArrayBufferView): void {\n    if (this.ws && this.ws.readyState === WebSocket.OPEN) {\n      this.ws.send(payload);\n    } else {\n      this.queuedMessages.push(payload);\n    }\n  }\n\n  public onMessage(handler: (response: ResponseDataType<Response>) => void): void {\n    this.messageHandler = handler;\n  }\n\n  public onOpen(handler: (event: Event) => void): void {\n    this.openHandler = handler;\n  }\n\n  public onClose(handler: (event: CloseEvent) => void): void {\n    this.closeHandler = handler;\n  }\n\n  public onError(handler: (event: Event, response?: ResponseDataType<Response>) => void): void {\n    this.errorHandler = handler;\n  }\n\n  private buildURL(url: string): string {\n    if (url.startsWith(\"ws://\") || url.startsWith(\"wss://\")) {\n      return url;\n    }\n\n    // Convert HTTP(S) to WebSocket protocol\n    if (url.startsWith(\"http://\")) {\n      url = url.replace(\"http://\", \"ws://\");\n    } else if (url.startsWith(\"https://\")) {\n      url = url.replace(\"https://\", \"wss://\");\n    } else if (!url.startsWith(\"ws://\") && !url.startsWith(\"wss://\")) {\n      url = `wss://${url}`;\n    }\n\n    return url;\n  }\n\n  private setupEventHandlers(): void {\n    this.ws.onmessage = (event: MessageEvent) => {\n      if (this.messageHandler) {\n        const data = JSON.parse(event.data) as ResponseDataType<Response>;\n\n        if (data.done) {\n          this.ws.close();\n        }\n\n        if (data.success) {\n          this.messageHandler(data);\n\n          return;\n        }\n\n        if (this.errorHandler) {\n          this.errorHandler(event, data);\n        }\n      }\n    };\n\n    this.ws.onopen = (event: Event) => {\n      this.flushQueuedMessages();\n      if (this.openHandler) {\n        this.openHandler(event);\n      }\n    };\n\n    this.ws.onerror = (event: Event) => {\n      if (this.errorHandler) {\n        this.errorHandler(event);\n      }\n    };\n\n    this.ws.onclose = (event: CloseEvent) => {\n      if (this.closeHandler) {\n        this.closeHandler(event);\n      }\n    };\n  }\n\n  private flushQueuedMessages(): void {\n    while (this.queuedMessages.length > 0) {\n      const message = this.queuedMessages.shift();\n      if (message !== undefined && this.ws.readyState === WebSocket.OPEN) {\n        this.ws.send(message);\n      }\n    }\n  }\n}\n"
+  ],
+  "mappings": "AAGO,MAAM,CAIb,CAQ+B,IAPrB,GACA,eACA,YACA,aACA,aACA,eAAwE,CAAC,EAEjF,WAAW,CAAkB,EAAa,CAAb,WAC3B,IAAM,EAAU,KAAK,SAAS,KAAK,GAAG,EACtC,KAAK,GAAK,IAAI,UAAU,CAAO,EAC/B,KAAK,mBAAmB,EAGnB,KAAK,CAAC,EAAe,EAAuB,CACjD,KAAK,GAAG,MAAM,EAAM,CAAM,EAGrB,IAAI,CAAC,EAAsB,CAChC,IAAM,EAAO,KAAK,UAAU,CAAI,EAChC,KAAK,QAAQ,CAAI,EAGX,OAAO,CAAC,EAAkE,CAChF,GAAI,KAAK,IAAM,KAAK,GAAG,aAAe,UAAU,KAC9C,KAAK,GAAG,KAAK,CAAO,EAEpB,UAAK,eAAe,KAAK,CAAO,EAI7B,SAAS,CAAC,EAA+D,CAC9E,KAAK,eAAiB,EAGjB,MAAM,CAAC,EAAuC,CACnD,KAAK,YAAc,EAGd,OAAO,CAAC,EAA4C,CACzD,KAAK,aAAe,EAGf,OAAO,CAAC,EAA8E,CAC3F,KAAK,aAAe,EAGd,QAAQ,CAAC,EAAqB,CACpC,GAAI,EAAI,WAAW,OAAO,GAAK,EAAI,WAAW,QAAQ,EACpD,OAAO,EAIT,GAAI,EAAI,WAAW,SAAS,EAC1B,EAAM,EAAI,QAAQ,UAAW,OAAO,EAC/B,QAAI,EAAI,WAAW,UAAU,EAClC,EAAM,EAAI,QAAQ,WAAY,QAAQ,EACjC,QAAI,CAAC,EAAI,WAAW,OAAO,GAAK,CAAC,EAAI,WAAW,QAAQ,EAC7D,EAAM,SAAS,IAGjB,OAAO,EAGD,kBAAkB,EAAS,CACjC,KAAK,GAAG,UAAY,CAAC,IAAwB,CAC3C,GAAI,KAAK,eAAgB,CACvB,IAAM,EAAO,KAAK,MAAM,EAAM,IAAI,EAElC,GAAI,EAAK,KACP,KAAK,GAAG,MAAM,EAGhB,GAAI,EAAK,QAAS,CAChB,KAAK,eAAe,CAAI,EAExB,OAGF,GAAI,KAAK,aACP,KAAK,aAAa,EAAO,CAAI,IAKnC,KAAK,GAAG,OAAS,CAAC,IAAiB,CAEjC,GADA,KAAK,oBAAoB,EACrB,KAAK,YACP,KAAK,YAAY,CAAK,GAI1B,KAAK,GAAG,QAAU,CAAC,IAAiB,CAClC,GAAI,KAAK,aACP,KAAK,aAAa,CAAK,GAI3B,KAAK,GAAG,QAAU,CAAC,IAAsB,CACvC,GAAI,KAAK,aACP,KAAK,aAAa,CAAK,GAKrB,mBAAmB,EAAS,CAClC,MAAO,KAAK,eAAe,OAAS,EAAG,CACrC,IAAM,EAAU,KAAK,eAAe,MAAM,EAC1C,GAAI,IAAY,QAAa,KAAK,GAAG,aAAe,UAAU,KAC5D,KAAK,GAAG,KAAK,CAAO,GAI5B",
+  "debugId": "222449767EFA071D64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ooneex/socket-client",
+  "description": "WebSocket client for real-time bidirectional communication with automatic reconnection, event handling, and typed message serialization",
+  "version": "1.0.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test tests",
+    "build": "bunup",
+    "lint": "tsgo --noEmit && bunx biome lint",
+    "npm:publish": "bun publish --tolerate-republish --access public"
+  },
+  "devDependencies": {
+    "@ooneex/translation": "0.0.18",
+    "@ooneex/http-response": "0.17.0",
+    "@ooneex/app-env": "0.0.19"
+  },
+  "keywords": [
+    "bun",
+    "ooneex",
+    "realtime",
+    "socket",
+    "typescript",
+    "websocket",
+    "ws"
+  ]
+}