WSRPC client
------------


Easy to use javascript client for
wsrpc-aiohttp or
wsrpc-tornado websocket servers.

See online demo and
documentation with examples.

* Features
* Installation
* Usage
* API
* Global configuration
* Constructor options
* Methods

Features

- Allows to call server functions from the client side and to
call client functions from the server side (e.g. to notify clients about
events);
- Async connection protocol: both server or client are able to call
multiple functions and get responses as soon as each response would be
ready in any order;
- Transfers any exceptions from a client side to the server side and
vise versa;
- No dependencies;
- Messaging is based on JsonRPC protocol;
- Provides typescript interface, ES6 module and
UMD distribution as well.
- Ability to implement very complex scenarios.

Installation

Install via npm:

npm install @wsrpc/client

Usage

Let's implement application, that tells jokes by request and collects feedback
about them (see jsfiddle).

Backend)
is located at demo.wsrpc.info.

``html


`

API

Global configuration

#### WSRPC.DEBUG
Static boolean flag, controls whether debug information should be displayed.

Can be enabled/disabled at any moment.
`js
WSRPC.DEBUG = true;
var RPC = new WSRPC(...);
...
`

#### WSRPC.TRACE
Static boolean flag, controls whether information about events and errors
should be traced.

Can be enabled/disabled at any moment.
`js
WSRPC.TRACE = true;
var RPC = new WSRPC(...);
...
`

Constructor options

URL, reconnectTimeout = 1000

Parameter | Type | Required | Description
-------------------|---------|----------|------------
URL | string | Yes | Absolute or relative URL
reconnectTimeout | number | No | Timeout for reconnecting, defaults to 1000 ms

`js
// Url can be relative (schema for websocket would be detected automatically
// depending on page http/https schema)
var RelativeUrlRPC = new WSRPC('/ws/', 5000);

// Absolute websocket url example
var UnsecureRPC = new WSRPC('ws://example.com/ws', 5000);

// Secure absolute websocket url example
var SecureRPC = new WSRPC('wss://example.com/ws', 5000);
`

Methods

#### WSRPC.connect()
Establishes connection with the server.

`js
var RPC = new WSRPC(url);
RPC.connect();
`

#### WSRPC.destroy()
Closes socket.

`js
var RPC = new WSRPC(url);

var deferred = RPC.onEvent('onconnect');
deferred.resolve = function() {
RPC.destroy();
};

RPC.connect();
`

#### WSRPC.state()
Get current socket state as a string.

Possible values: CONNECTING, OPEN, CLOSING, CLOSED.

`js
var RPC = new WSRPC(url);
console.log(RPC.state()); // Displays CLOSED
`

#### WSRPC.stateCode()
Get current socket state code (integer). Possible values:

Code | State
-----|---------
0 | CONNECTING
1 | OPEN
2 | CLOSING
3 | CLOSED

`js
var RPC = new WSRPC(url);
console.log(RPC.stateCode()); // Displays 3
`

#### WSRPC.addRoute(name, callback)
Register route on the client with specified name, route added later replaces
route added earlier with the same name.

Parameter | Type
----------|------
name | string
callback | function

Callback would be called with object type parameter data containing
parameters from server. Callback return value would be received by server.

`js
var RPC = new WSRPC(url);
RPC.addRoute('askUser', function(data) {
// Data is object, containing parameters from server.
// Would display question ask user to enter response and return response
// to the server.
return { response: prompt(data.question) };
});
`

#### WSRPC.deleteRoute(name)
Remove specified client route.

Parameter | Type
----------|------
name | string

`js
var RPC = new WSRPC(url);
RPC.addRoute('askUser', function() { return {} });
RPC.deleteRoute('askUser');
`

#### WSRPC.call(route, params)
Call server function with specified parameters, returns Promise that can be
awaited using await syntax.

Parameter | Type
----------|------
route | string
params | object

`js
var RPC = new WSRPC(url);
RPC.connect();
RPC.call('serverRoute', {
param1: 'value1',
param2: 'value2'
}).then((result) => {
alert(result);
}, (error) => {
alert(error.type + '("' + error.message + '")');
});
`

#### WSRPC.addEventListener(event, callback)
Add permanent callback for event (see onEvent to register one time event).
Returns eventId, that can be used later to remove event.

Parameter | Type
----------|------
event | string
callback | function

`js
var RPC = new WSRPC(url);
RPC.addEventListener('onconnect', function() {
console.log('Connected to the server!');
});
`

#### WSRPC.removeEventListener(event, eventId)
Remove event listener using eventId (returned by addEventListener).

Parameter | Type
----------|------
event | string
eventId | integer

`js
var RPC = new WSRPC(url);
var eventId = RPC.addEventListener('onconnect', function() {
console.log('Connected to the server!');
});
RPC.removeEventListener('onconnect', eventId);
`

#### WSRPC.onEvent(event)
Get deferred object, that would execute only once for specified event.
deferred.promise is a native Promise and can be awaited using await syntax.

Parameter | Type
----------|------
event | string

`js
var RPC = new WSRPC(url);

var deferred = RPC.onEvent('onconnect');
deferred.resolve = function() {
RPC.destroy();
};

RPC.connect();
`

#### WSRPC.proxy
Proxy for WSRPC.call method to call the remote functions by dot notation.

Parameter | Type
----------|------
params | object

`js
var RPC = new WSRPC(url);
RPC.connect();
RPC.proxy.serverRoute({
param1: 'value1',
param2: 'value2'
}).then((result) => {
alert(result);
}, (error) => {
alert(error.type + '("' + error.message + '")');
});
`


$3


#### Function based Proxy example:
Python server code:
`python
from wsrpc_aiohttp import WebSocketAsync

async def subtract(socket: WebSocketAsync, *, a, b):
return a - b

WebSocketAsync.add_route('subtract', subtract)
`
Javascript client code:
`js
var RPC = new WSRPC(url);
RPC.connect();
await RPC.proxy.subtract({a: 1, b: 9});
`

#### Class based Proxy example:
Python server code:
`python
from wsrpc_aiohttp import decorators, WebSocketAsync

class Storage(Route):
async def init(self):
self._internal = dict()

@decorators.proxy
async def get(self, key, default=None):
return self._internal.get(key, default)

@decorators.proxy
async def set(self, key, value):
self._internal[key] = value
return True

WebSocketAsync.add_route('kv', Storage)
`

Javascript client code:
`js
var RPC = new WSRPC(url);
RPC.connect();
await RPC.proxy.kv.set({ key: 'foo', value: 'bar' });
await RPC.proxy.kv.get({ key: 'foo' });
``

Versioning

This software follows Semantic Versioning