@akanass/rx-socket-client

Rx-Socket-Client

Reconnectable websocket client, RxJS compliant, wrote in full Typescript | ES6 for client and browser side.

This library is an enhancement of RxJS WebSocketSubject to add more features and the native support of Node.js environment.

Table of contents

• Installation
• Super simple to use
• Browser compatibility
• API in Detail
  • webSocket(urlConfigOrSource)
  • .connectionStatus$
  • .send(data)
  • .emit(event, data)
  • .on(event, cb(data))
  • .on$(event)
  • .onBytes(cb(data))
  • .onBytes$()
  • .onError$()
  • .onClose$()
• RxSocketClientConfig in detail
• Contributing
• Change History
• License

Installation

$ 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 :

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

or use CommonJS:

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

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

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

Browser compatibility

Rx-Socket-Client can be used in your favorite browser to have all features in your own front application.

Just import browser/index.js script and enjoy:

<script src="node_modules/@akanass/rx-socket-client/browser/index.js" type="application/javascript"></script>
<script type="application/javascript">
    const socket$ = rsc.webSocket('ws://127.0.0.1:1235');

    // send message
    socket$.send('my message from socket');
</script>

Browser version is a standalone version so you just need to copy/paste file from node_modules/@akanass/rx-socket-client/browser/index.js when you want to create your bundle and change path to it.

Back to top

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:

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 method with object parameter {event, data}.

.on(event, cb(data))

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

Parameters:

• {string | 'error' | '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: error event will be only fired by Observable error process.

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:

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 error from server with callback
socket$.on('error', error => console.error(error)); // will display error 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 but with Observable result.

Parameter:

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

Result:

Observable instance

Note: error and close event are not supported with this method, check after for specific implementation. But, you can just use error and complete section of each subscription to handle them in each event if you want.

For example:

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 error and close in subscription
socket$.on$('*').subscribe(undefined, error => console.error(error), () => 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: <Buffer 74 6f 74 6f>
}

Simple Bytes Message,

<Buffer 74 6f 74 6f>

For example:

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 but with Observable result.

Result:

Observable instance

Note: error and close event are not supported with this method, check after for specific implementation. But, you can just use error and complete section of each subscription to handle them in each event if you want.

For example:

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 error and close in subscription
socket$.onBytes$().subscribe(undefined, error => console.error(error), () => console.log('Socket closed'));

.onError$()

This method handles error from web socket server with Observable result and send error inside next process.

Result:

Observable instance

For example:

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

socket$.onError$().subscribe(error => console.error(error)); // will log error from server in console if one occurred

.onClose$()

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

Result:

Observable instance

For example:

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

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

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

Change History

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

Back to top