WebSocket based JSONRPC client
npm install @wsrpc/clientWSRPC 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
- 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.
Install via npm:
npm install @wsrpc/client
Let's implement application, that tells jokes by request and collects feedback
about them (see jsfiddle).
Backend)
is located at demo.wsrpc.info.
``html`
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(...);
...
Parameter | Type | Required | Description
-------------------|---------|----------|------------
URL | string | Yes | Absolute or relative URLreconnectTimeout | 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);
`
#### 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' });
This software follows Semantic Versioning