websocket-as-promised

websocket-as-promised

Promise-based W3C WebSocket wrapper

This library allows to use promises when connecting, disconnecting and messaging with WebSocket server.

Installation

npm install websocket-as-promised --save

Usage in browser

const WebSocketAsPromised = require('websocket-as-promised');

const wsp = new WebSocketAsPromised();

// connect
wsp.open('ws://echo.websocket.org')
  .then(() => console.log('Connected.'));

// send data and expect response message
wsp.request({foo: 'bar'})
  .then(response => console.log('Response message received', response));

// disconnect
wsp.close()
  .then(() => console.log('Disconnected.'));

Usage in Node.js

As there is no built-in WebSocket client in Node.js, you should use a third-party module. The most popular W3C compatible solution is websocket:

const W3CWebSocket = require('websocket').w3cwebsocket;
const WebSocketAsPromised = require('websocket-as-promised');

const wsp = new WebSocketAsPromised({
  createWebSocket: url => new W3CWebSocket(url)
});
wsp.open('ws://echo.websocket.org')
  .then(...)

Messaging

1. if you want to send message and expect server's response - you should use .request() method that returns promise:

   wsp.request({foo: 'bar'}); // returns promise
   // actually sends message with unique id: {id: 'xxxxx', foo: 'bar'}
   // promise waits response message with the same id: {id: 'xxxxx', response: 'ok'}
   

2. if you want to just send data and do not expect any response - use .send() method that does not return promise:

   wsp.send({foo: 'bar'}); // returns undefined
   

API

WebSocketAsPromised

Kind: global class

• WebSocketAsPromised
  • new WebSocketAsPromised([options])
  • .ws ⇒ WebSocket
  • .isConnecting ⇒ Boolean
  • .isConnected ⇒ Boolean
  • .isDisconnecting ⇒ Boolean
  • .onMessage ⇒ Channel
  • .open(url) ⇒ Promise
  • .request(data, [options]) ⇒ Promise
  • .send(data)
  • .close() ⇒ Promise

new WebSocketAsPromised([options])

Constructor

Param	Type	Default	Description
[options]	Object
[options.createWebSocket]	function	url => new Websocket(url)	custom WebSocket creation method
[options.idProp]	String	"id"	id property name attached to each message
[options.timeout]	Number	0	default timeout for requests

wsp.ws ⇒ WebSocket

Returns original WebSocket instance created by options.createWebSocket.

Kind: instance property of WebSocketAsPromised

wsp.isConnecting ⇒ Boolean

Is WebSocket in connecting state.

Kind: instance property of WebSocketAsPromised

wsp.isConnected ⇒ Boolean

Is WebSocket connected.

Kind: instance property of WebSocketAsPromised

wsp.isDisconnecting ⇒ Boolean

Is WebSocket in disconnecting state.

Kind: instance property of WebSocketAsPromised

wsp.onMessage ⇒ Channel

OnMessage channel with .addListener / .removeListener methods.

Kind: instance property of WebSocketAsPromised
See: https://github.com/vitalets/chnl

wsp.open(url) ⇒ Promise

Opens WebSocket connection.

Kind: instance method of WebSocketAsPromised

Param	Type
url	String

wsp.request(data, [options]) ⇒ Promise

Performs JSON request and waits for response.

Kind: instance method of WebSocketAsPromised

Param	Type
data	Object
[options]	Object
[options.timeout]	Number

wsp.send(data)

Performs JSON request and does not wait for response.

Kind: instance method of WebSocketAsPromised

Param	Type
data	Object

wsp.close() ⇒ Promise

Closes WebSocket connection.

Kind: instance method of WebSocketAsPromised

License

MIT @ Vitaliy Potapov