{"id":26796176,"url":"https://github.com/akanass/rx-socket-client","last_synced_at":"2025-04-22T19:57:23.161Z","repository":{"id":32458794,"uuid":"85966650","full_name":"akanass/rx-socket-client","owner":"akanass","description":"Reconnectable websocket client with RxJS Subject","archived":false,"fork":false,"pushed_at":"2023-03-04T04:02:32.000Z","size":312,"stargazers_count":11,"open_issues_count":3,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T18:17:36.950Z","etag":null,"topics":["client","observable","reconnection","rxjs7","subject","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akanass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-23T15:35:10.000Z","updated_at":"2022-11-10T20:37:32.000Z","dependencies_parsed_at":"2023-01-14T21:17:07.294Z","dependency_job_id":null,"html_url":"https://github.com/akanass/rx-socket-client","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akanass%2Frx-socket-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akanass%2Frx-socket-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akanass%2Frx-socket-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akanass%2Frx-socket-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akanass","download_url":"https://codeload.github.com/akanass/rx-socket-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250315783,"owners_count":21410473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","observable","reconnection","rxjs7","subject","websocket"],"created_at":"2025-03-29T18:17:41.559Z","updated_at":"2025-04-22T19:57:23.090Z","avatar_url":"https://github.com/akanass.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rx-Socket-Client\n\nReconnectable websocket client, [RxJS](http://reactivex.io/rxjs) compliant, wrote in full [Typescript](https://www.typescriptlang.org/docs/tutorial.html) | [ES6](https://babeljs.io/docs/learn-es2015/) for client and browser side.\n\nThis library is an **enhancement** of [RxJS WebSocketSubject](https://github.com/ReactiveX/rxjs/blob/master/src/internal/observable/dom/WebSocketSubject.ts) to add more features and the native support of **Node.js** environment.\n\n\n## Table of contents\n\n* [Installation](#installation)\n* [Super simple to use](#super-simple-to-use)\n* [API in Detail](#api-in-detail)\n    * [webSocket(urlConfigOrSource)](#websocketurlconfigorsource)\n    * [.connectionStatus$](#connectionstatus$)\n    * [.send(data)](#senddata)\n    * [.emit(event, data)](#emitevent-data)\n    * [.on(event, cb(data))](#onevent-cbdata)\n    * [.on$(event)](#onevent)\n    * [.onBytes(cb(data))](#onbytescbdata)\n    * [.onBytes$()](#onbytes)\n    * [.onClose$()](#onclose)\n* [RxSocketClientConfig in detail](#rxsocketclientconfig-in-detail)\n* [Contributing](#contributing)\n* [Change History](#change-history)\n* [License](#license)\n\n## Installation\n\n```sh\n$ yarn add @akanass/rx-socket-client rxjs\n\nor\n\n$ npm install --save @akanass/rx-socket-client rxjs\n```\n\n## Super simple to use\n\n**Rx-Socket-Client** is designed to be the simplest way possible to make web socket connections and calls.\n\nIt's fully `Typescript` | `ES6` written so you can import it :\n\n```typescript\nimport { webSocket } from '@akanass/rx-socket-client';\n```\n\nor use `CommonJS`:\n\n```javascript\nconst webSocket = require('@akanass/rx-socket-client').webSocket;\n```\n\nNow, it's easy to perform a `WS` calls:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\n// send message\nsocket$.send('my message from socket');\n\n// emit message on specific event\nsocket$.emit('event', 'my message from socket for event');\n\n// receive message from server with callback\nsocket$.on('event', data =\u003e console.log(data)); // will display received data in console if event is fired\n\n// receive message from server with Observable\nsocket$.on$('event').subscribe(data =\u003e console.log(data)); // will display received data in console if event is fired\n```\n\n[Back to top](#table-of-contents)\n\n## API in Detail\n\n### `webSocket(urlConfigOrSource)`\n\nReturns an instance of `RxSocketClientSubject` with given configuration.\n\n**Parameter:**\n\u003e ***{string | RxSocketClientConfig} urlConfigOrSource*** *(required): `url` or `RxSocketClientConfig` object with default values foreach next web socket calls*\n\n**Result:**\n\u003e ***new*** *`RxSocketClientSubject` instance*\n\n### `.connectionStatus$`\n\nThis property provides an **Observable** to check server's connection status.\n\nFor example:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\nsocket$.connectionStatus$.subscribe(isConnected =\u003e isConnected ? console.log('Server connected'): console.log('Server disconnected'));\n```\n\n### `.send(data)`\n\nThis method sends **data** to web socket server.\n\n**Parameter:**\n\u003e ***{any} data*** *(required): data sent to web socket server. Can be of any type.*\n\n**Note:** If `data` is an **object**, it'll be **stringified** with `JSON.stringify`. If it's a **string** or a **buffer**, it'll be sent like this **without** transformation.\n\n**Note:** The message sent to server will be like this:\n\nFor **binary data**,\n\n```\n{\n  type: 'binary',\n  binaryData: `data`\n}\n```\n\nFor **others**,\n\n```\n{\n  type: 'utf8',\n  utf8Data: `data`\n}\n```\n\n### `.emit(event, data)`\n\nThis method emits **data** for given **event** to web socket server.\n\n**Parameters:**\n\u003e - ***{string} event*** *(required): event sent to web socket server.*\n\u003e - ***{any} data*** *(required): data sent to web socket server. Can be of any type.*\n\n**Note:** This method calls [`.send`](#senddata) method with **object** parameter `{event, data}`.\n\n### `.on(event, cb(data))`\n\nThis method handles **text response** for given **event** from web socket server.\n\n**Parameters:**\n\u003e - ***{string | 'close'} event*** *(required): event represents value inside `{utf8Data.event}` or `{event}` from server response.*\n\u003e - ***{function} cb*** *(required): cb is the function executed if event matches the response from the server. `data` in parameter is the **text** data received from the server.*\n\n**Note:** `close` event will be only fired by `Observable` **complete** process.\n\n**Note:** Message received from the server can be like this:\n\n**UTF** Text Message,\n\n```\n{\n  type: 'utf8',\n  utf8Data: {\n    event: `event`,\n    data: `data`\n  }\n}\n```\n\n**Simple** Text Message,\n\n```\n{\n  event: `event`,\n  data: `data`\n}\n```\n\nFor example:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\n// receive message from server with callback\nsocket$.on('event', data =\u003e console.log(data)); // will display received data in console if event is fired\n\n// handle close from server with callback\nsocket$.on('close', () =\u003e console.log('Socket closed')); // will display message in console if event is fired\n```\n\n### `.on$(event)`\n\nThis method is the same as [`.on`](#onevent-cbdata) but with `Observable` result.\n\n**Parameter:**\n\u003e ***{string} event*** *(required): event represents value inside `{utf8Data.event}` or `{event}` from server response.*\n\n**Result:**\n\u003e *Observable instance*\n\n**Note:** `close` event is not supported with this method, check after for specific implementation. But, you can just use `complete` section of each **subscription** to handle them in each event if you want.\n\nFor example:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\nsocket$.on$('event').subscribe(data =\u003e console.log(data)); // will log data from server in console if event is fired\n\n// handle close in subscription\nsocket$.on$('*').subscribe(undefined, undefined, () =\u003e console.log('Socket closed'));\n```\n\n### `.onBytes(cb(data))`\n\nThis method handles **binary response** from web socket server.\n\n**Parameter:**\n\u003e ***{function} cb*** *(required): cb is the function executed with the response from the server. `data` in parameter is the **binary** data received from the server.*\n\n**Note:** Binary received from the server can be like this:\n\n**Bytes** Message,\n\n```\n{\n  type: 'binary',\n  binaryData: \u003cBuffer 74 6f 74 6f\u003e\n}\n```\n\n**Simple** Bytes Message,\n\n```\n\u003cBuffer 74 6f 74 6f\u003e\n```\n\nFor example:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\nsocket$.onBytes(data =\u003e console.log(data)); // will log data from server in console if event is fired\n```\n\n### `.onBytes$()`\n\nThis method is the same as [`.onBytes`](#onbytescbdata) but with `Observable` result.\n\n**Result:**\n\u003e *Observable instance*\n\n**Note:** `close` event is not supported with this method, check after for specific implementation. But, you can just use `complete` section of each **subscription** to handle them in each event if you want.\n\nFor example:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\nsocket$.onBytes$().subscribe(data =\u003e console.log(data)); // will log data from server in console if event is fired\n\n// handle close in subscription\nsocket$.onBytes$().subscribe(undefined, undefined, () =\u003e console.log('Socket closed'));\n```\n\n### `.onClose$()`\n\nThis method handles `close` from web socket server with `Observable` result and send `complete` inside **`next`** process.\n\n**Result:**\n\u003e *Observable instance*\n\nFor example:\n\n```typescript\nconst socket$ = webSocket('ws://127.0.0.1:1235');\n\nsocket$.onClose$().subscribe(() =\u003e console.log('Socket closed')); // will log close from server in console if event is fired\n```\n\n[Back to top](#table-of-contents)\n\n## `RxSocketClientConfig` in detail\n\n\u003e - ***{string} url*** *(required): connection url to web socket server.*\n\u003e - ***{string | Array\u003cstring\u003e} protocol*** *(optional): the protocol to use to connect.*\n\u003e - ***{'blob' | 'arraybuffer'} binaryType*** *(optional): sets the `binaryType` property of the underlying WebSocket.*\n\u003e - ***{number} reconnectInterval*** *(optional): sets the reconnection interval value. (default: `5000 ms`).*\n\u003e - ***{number} reconnectAttempts*** *(optional): sets the reconnection attempts value. (default: `10`).*\n\u003e - ***{ { new(url: string, protocol?: string | Array\u003cstring\u003e): WebSocket } } WebSocketCtor*** *(optional): a WebSocket constructor to use. This is useful for mocking a WebSocket for testing purposes.*\n\n[Back to top](#table-of-contents)\n\n## Contributing\n\nTo set up your development environment:\n\n1. clone the repo to your workspace,\n2. in the shell `cd` to the main folder,\n3. hit `npm or yarn install`,\n4. run `npm or yarn run test`.\n    * It will lint the code and execute all tests.\n    * The test coverage report can be viewed from `./coverage/lcov-report/index.html`.\n\n[Back to top](#table-of-contents)\n\n## Change History\n\n* v2.0.0 (2021-09-15)\n    * Upgrade all packages' versions to move on `rxjs:7.3.0` and delete incompatible packages\n    * Delete browser single version due to incompatibility\n    * Delete `es5` version and now module is only on `es2015` and if you want an older support, your bundle system should transpile it to `es5`\n    * Documentation\n* v1.2.0 (2019-07-18)\n    * Upgrade all packages' versions\n    * Migrate tests to [jest](https://jestjs.io/en/) and [ts-jest](https://kulshekhar.github.io/ts-jest/)\n    * Documentation\n* v1.1.0 (2018-05-31)\n    * Delete `error` process/methods because never called with reconnection\n    * Update tests\n    * Latest packages' versions\n    * Documentation\n* v1.0.0 (2018-05-16)\n    * Carefully written from scratch to make `Rx-Socket-Client` a drop-in replacement for `WebSocketSubject`\n\n## License\n\nCopyright (c) 2018 **Nicolas Jessel** Licensed under the [MIT license](https://github.com/akanass/rx-socket-client/tree/master/LICENSE.md).\n\n[Back to top](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakanass%2Frx-socket-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakanass%2Frx-socket-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakanass%2Frx-socket-client/lists"}