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('ws://echo.websocket.org');

wsp.open()
  .then(() => console.log('Opened.'))
  .then(() => wsp.request({foo: 'bar'}))
  .then(response => console.log('Response message received', response))
  .then(() => wsp.close())
  .then(() => console.log('Closed.'));

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('ws://echo.websocket.org', {
  createWebSocket: url => new W3CWebSocket(url)
});

wsp.open()
  .then(() => console.log('Opened.'));
  ...

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 .sendJson() / .send() methods:

   wsp.sendJson({foo: 'bar'}); // does not return promise
   

API

WebSocketAsPromised

Kind: global class

• WebSocketAsPromised
  • new WebSocketAsPromised(url, [options])
  • .ws ⇒ WebSocket
  • .isOpening ⇒ Boolean
  • .isOpened ⇒ Boolean
  • .isClosing ⇒ Boolean
  • .isClosed ⇒ Boolean
  • .onMessage ⇒ Channel
  • .onClose ⇒ Channel
  • .open() ⇒ Promise
  • .request(data, [options]) ⇒ Promise
  • .sendJson(data)
  • .send(data)
  • .close() ⇒ Promise

new WebSocketAsPromised(url, [options])

Constructor. Unlike original WebSocket it does not immediately open connection. Please call open() method manually to connect.

Param	Type	Default	Description
url	String		WebSocket URL
[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.isOpening ⇒ Boolean

Is WebSocket connection in opening state.

Kind: instance property of WebSocketAsPromised

wsp.isOpened ⇒ Boolean

Is WebSocket connection opened.

Kind: instance property of WebSocketAsPromised

wsp.isClosing ⇒ Boolean

Is WebSocket connection in closing state.

Kind: instance property of WebSocketAsPromised

wsp.isClosed ⇒ Boolean

Is WebSocket connection closed.

Kind: instance property of WebSocketAsPromised

wsp.onMessage ⇒ Channel

Event channel triggered every time when message from server arrives. Listener accepts two arguments:

1. original event.data
2. jsonData if JSON parse succeeded

Kind: instance property of WebSocketAsPromised
See: https://vitalets.github.io/chnl/#channel
Example

wsp.onMessage.addListener((data, jsonData) => console.log(data, jsonData));

wsp.onClose ⇒ Channel

Event channel triggered when connection closed. Listener accepts single argument {code, reason}.

Kind: instance property of WebSocketAsPromised
See: https://vitalets.github.io/chnl/#channel

wsp.open() ⇒ Promise

Opens WebSocket connection.

Kind: instance method of WebSocketAsPromised

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.sendJson(data)

Sends JSON data and does not wait for response.

Kind: instance method of WebSocketAsPromised

Param	Type
data	Object

wsp.send(data)

Sends any WebSocket compatible data.

Kind: instance method of WebSocketAsPromised

Param	Type
data	String | ArrayBuffer | Blob

wsp.close() ⇒ Promise

Closes WebSocket connection.

Kind: instance method of WebSocketAsPromised

License

MIT @ Vitaliy Potapov