ws-promise-client v4.1.9
Project moved
This project has moved here. This repository is deprecated.
ws-promise-client
ws-promise-client
is a tiny framework that builds a request-response model onto HTML5 WebSockets using ES2015 Promises. You can use this with ES2017's await
/async
to simplify your WebSocket API. Both browsers and node.js
are supported.
The official server to use with this client can be found at kdex/ws-promise-server. This client supports any server that adheres to the RPC protocol.
Getting started
Your WebSocket code could roughly map to something like this:
import Client from "ws-promise-client";
const client = new Client("ws://localhost:8080");
(async () => {
/* The client connects (it will, by default, also automatically reconnect) */
await client.open();
/* Both parties can have an array of return values in `reply` */
const [result] = await client.send({
instruction: "multiply",
args: [1, 2, 3]
});
/* Prints `6` */
console.log(result);
})();
This code creates a client, connects to a server, then sends a message and receives the according reply without the need for setting up any kind of explicit callback or message IDs.
API reference
Client.constructor(url, protocols, options)
Constructs a new ws-promise-client
connecting to the url
supporting the subprotocols protocols
. The options
argument is an optional object with the following keys:
autoReconnect (default: true)
Boolean property that determines whether to automatically reconnect to the server in case of connection losses, and also when the initial connect is unsuccessful.
reconnectionFactor (default: 1.2)
Numeric property that determines which factor to multiply the waiting time with after each reconnection try.
reconnectionMinimum (default: 2000)
Numeric property that determines the minimum amount of milliseconds to wait before reconnecting. Note that the initial reconnect will be tried immediately after a connection loss, regardless of this amount.
rpcOptions
An option object that will be passed to the constructor of ws-rpc-client
.
Client.prototype.open()
Opens the websocket connection and returns a promise that resolves once the connection is open.
Client.prototype.close()
Closes the websocket connection and returns a promise that resolves once the connection is closed.
Client.prototype.reconnect(newWaitingTime)
Reconnects to the server and returns a Promise
that resolves once the connection is (re-)opened. Before reconnecting for the first time, there will be a delay of newWaitingTime
. If newWaitingTime
is not provided, reconnectionMinimum
is used.
Client.prototype.send(payload)
Sends payload
to the server and returns a Promise
that that resolves when the server's reply has been received. For more information on which keys are needed in payload
, see the protocol (which also defines the send
method).
Events
The following standard WebSocket client events are supported:
- close
- error
- message
- open
The client also provides these additional events:
- connectionFailed
- reconnect
- instruction
The [instruction]
event is a custom event that fires once an instruction with the name of instruction
is received. For example, if the server sends a message with an instruction of showMenu
, the client will call its onShowMenu
method (if available) with the arguments that the server has put in the payload's args
property.
All events can either be handled by providing a handler method named on[Event]
(see example above) or by registering an event listeners via on(event, handler)
.
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago