Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/akanass/rx-socket-client

Reconnectable websocket client with RxJS Subject
https://github.com/akanass/rx-socket-client

client observable reconnection rxjs7 subject websocket

Last synced: 6 months ago
JSON representation

Reconnectable websocket client with RxJS Subject

Awesome Lists containing this project

README 

          
# Rx-Socket-Client



Reconnectable 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.



This 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.



## Table of contents



* [Installation](#installation)

* [Super simple to use](#super-simple-to-use)

* [API in Detail](#api-in-detail)

    * [webSocket(urlConfigOrSource)](#websocketurlconfigorsource)

    * [.connectionStatus$](#connectionstatus$)

    * [.send(data)](#senddata)

    * [.emit(event, data)](#emitevent-data)

    * [.on(event, cb(data))](#onevent-cbdata)

    * [.on$(event)](#onevent)

    * [.onBytes(cb(data))](#onbytescbdata)

    * [.onBytes$()](#onbytes)

    * [.onClose$()](#onclose)

* [RxSocketClientConfig in detail](#rxsocketclientconfig-in-detail)

* [Contributing](#contributing)

* [Change History](#change-history)

* [License](#license)



## Installation



```sh

$ yarn add @akanass/rx-socket-client rxjs



or



$ npm install --save @akanass/rx-socket-client rxjs

```



## Super simple to use



**Rx-Socket-Client** is designed to be the simplest way possible to make web socket connections and calls.



It's fully `Typescript` | `ES6` written so you can import it :



```typescript

import { webSocket } from '@akanass/rx-socket-client';

```



or use `CommonJS`:



```javascript

const webSocket = require('@akanass/rx-socket-client').webSocket;

```



Now, it's easy to perform a `WS` calls:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



// send message

socket$.send('my message from socket');



// emit message on specific event

socket$.emit('event', 'my message from socket for event');



// receive message from server with callback

socket$.on('event', data => console.log(data)); // will display received data in console if event is fired



// receive message from server with Observable

socket$.on$('event').subscribe(data => console.log(data)); // will display received data in console if event is fired

```



[Back to top](#table-of-contents)



## API in Detail



### `webSocket(urlConfigOrSource)`



Returns an instance of `RxSocketClientSubject` with given configuration.



**Parameter:**

> ***{string | RxSocketClientConfig} urlConfigOrSource*** *(required): `url` or `RxSocketClientConfig` object with default values foreach next web socket calls*



**Result:**

> ***new*** *`RxSocketClientSubject` instance*



### `.connectionStatus$`



This property provides an **Observable** to check server's connection status.



For example:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



socket$.connectionStatus$.subscribe(isConnected => isConnected ? console.log('Server connected'): console.log('Server disconnected'));

```



### `.send(data)`



This method sends **data** to web socket server.



**Parameter:**

> ***{any} data*** *(required): data sent to web socket server. Can be of any type.*



**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.



**Note:** The message sent to server will be like this:



For **binary data**,



```

{

  type: 'binary',

  binaryData: `data`

}

```



For **others**,



```

{

  type: 'utf8',

  utf8Data: `data`

}

```



### `.emit(event, data)`



This method emits **data** for given **event** to web socket server.



**Parameters:**

> - ***{string} event*** *(required): event sent to web socket server.*

> - ***{any} data*** *(required): data sent to web socket server. Can be of any type.*



**Note:** This method calls [`.send`](#senddata) method with **object** parameter `{event, data}`.



### `.on(event, cb(data))`



This method handles **text response** for given **event** from web socket server.



**Parameters:**

> - ***{string | 'close'} event*** *(required): event represents value inside `{utf8Data.event}` or `{event}` from server response.*

> - ***{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.*



**Note:** `close` event will be only fired by `Observable` **complete** process.



**Note:** Message received from the server can be like this:



**UTF** Text Message,



```

{

  type: 'utf8',

  utf8Data: {

    event: `event`,

    data: `data`

  }

}

```



**Simple** Text Message,



```

{

  event: `event`,

  data: `data`

}

```



For example:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



// receive message from server with callback

socket$.on('event', data => console.log(data)); // will display received data in console if event is fired



// handle close from server with callback

socket$.on('close', () => console.log('Socket closed')); // will display message in console if event is fired

```



### `.on$(event)`



This method is the same as [`.on`](#onevent-cbdata) but with `Observable` result.



**Parameter:**

> ***{string} event*** *(required): event represents value inside `{utf8Data.event}` or `{event}` from server response.*



**Result:**

> *Observable instance*



**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.



For example:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



socket$.on$('event').subscribe(data => console.log(data)); // will log data from server in console if event is fired



// handle close in subscription

socket$.on$('*').subscribe(undefined, undefined, () => console.log('Socket closed'));

```



### `.onBytes(cb(data))`



This method handles **binary response** from web socket server.



**Parameter:**

> ***{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.*



**Note:** Binary received from the server can be like this:



**Bytes** Message,



```

{

  type: 'binary',

  binaryData: 

}

```



**Simple** Bytes Message,



```



```



For example:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



socket$.onBytes(data => console.log(data)); // will log data from server in console if event is fired

```



### `.onBytes$()`



This method is the same as [`.onBytes`](#onbytescbdata) but with `Observable` result.



**Result:**

> *Observable instance*



**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.



For example:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



socket$.onBytes$().subscribe(data => console.log(data)); // will log data from server in console if event is fired



// handle close in subscription

socket$.onBytes$().subscribe(undefined, undefined, () => console.log('Socket closed'));

```



### `.onClose$()`



This method handles `close` from web socket server with `Observable` result and send `complete` inside **`next`** process.



**Result:**

> *Observable instance*



For example:



```typescript

const socket$ = webSocket('ws://127.0.0.1:1235');



socket$.onClose$().subscribe(() => console.log('Socket closed')); // will log close from server in console if event is fired

```



[Back to top](#table-of-contents)



## `RxSocketClientConfig` in detail



> - ***{string} url*** *(required): connection url to web socket server.*

> - ***{string | Array} protocol*** *(optional): the protocol to use to connect.*

> - ***{'blob' | 'arraybuffer'} binaryType*** *(optional): sets the `binaryType` property of the underlying WebSocket.*

> - ***{number} reconnectInterval*** *(optional): sets the reconnection interval value. (default: `5000 ms`).*

> - ***{number} reconnectAttempts*** *(optional): sets the reconnection attempts value. (default: `10`).*

> - ***{ { new(url: string, protocol?: string | Array): WebSocket } } WebSocketCtor*** *(optional): a WebSocket constructor to use. This is useful for mocking a WebSocket for testing purposes.*



[Back to top](#table-of-contents)



## Contributing



To set up your development environment:



1. clone the repo to your workspace,

2. in the shell `cd` to the main folder,

3. hit `npm or yarn install`,

4. run `npm or yarn run test`.

    * It will lint the code and execute all tests.

    * The test coverage report can be viewed from `./coverage/lcov-report/index.html`.



[Back to top](#table-of-contents)



## Change History



* v2.0.0 (2021-09-15)

    * Upgrade all packages' versions to move on `rxjs:7.3.0` and delete incompatible packages

    * Delete browser single version due to incompatibility

    * 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`

    * Documentation

* v1.2.0 (2019-07-18)

    * Upgrade all packages' versions

    * Migrate tests to [jest](https://jestjs.io/en/) and [ts-jest](https://kulshekhar.github.io/ts-jest/)

    * Documentation

* v1.1.0 (2018-05-31)

    * Delete `error` process/methods because never called with reconnection

    * Update tests

    * Latest packages' versions

    * Documentation

* v1.0.0 (2018-05-16)

    * Carefully written from scratch to make `Rx-Socket-Client` a drop-in replacement for `WebSocketSubject`



## License



Copyright (c) 2018 **Nicolas Jessel** Licensed under the [MIT license](https://github.com/akanass/rx-socket-client/tree/master/LICENSE.md).



[Back to top](#table-of-contents)