README

observable-socket

An observable socket, no duh. Tested with ws and window.WebSocket.

observable-socket assumes Promise is available. If you're targeting an environment that does not support native Promises, use babel-polyfill or something similar.

Usage

install it.

npm i observable-socket

import and use it.

const ObservableSocket = require('observable-socket')
const WS = require('ws')

/**
 * Create an echo socket by connecting to the echo socket provided by
 * websocket.org.
 */
const echoSocket = ObservableSocket.create(new WS('wss://echo.websocket.org'))

/**
 * Subscribing to `echoSocket` receives messages from the underlying
 * WebSocket.
 */
echoSocket.down.subscribe(
  function next (msg) {
    console.log(msg.data)
  },

  function error (e) {
    console.error('uh oh! ', e)
  },

  function complete () {
    console.warn('Socket has closed')
  }
)

/**
 * We can send messages too!
 */
echoSocket.up('hi!')

<script type="text/javascript">
    window.debug = lbl => msg => console.log(`${lbl}: ${msg}`) // debug however you like
</script>
<script type="text/javascript" src="https://unpkg.com/rxjs/bundles/rxjs.umd.min.js"></script>
<script type="text/javascript" src="https://unpkg.com/observable-socket@6.0.0/dist/browser.min.js"></script>

<script>
    var socket = ObservableSocket.create(new WebSocket('wss://echo.websocket.org'))

    // Send messages up the socket
    socket.up('hello')

    // Receive messages down the socket
    socket.down.subscribe(
        msg => console.log(msg.data),
        () => console.log('done'),
        err => console.error(err)
    )
</script>

API

This module exports a function that takes a WebSocket, and returns an object with two properties, up and down.

socket.up

up is a function to push messages up the socket. This will create a queue of messages that will not be sent until the socket is connected.

socket.down

down is an RxJS stream. You can subscribe to it.

Reconnecting...

observable-socket does not construct WebSockets, therefore there isn't a notion of "healing" a connection. Instead, when a socket drops, the complete of observable-socket is called, which can be leveraged into creating a new socket, and re-wrapping observable-socket around it. An example of how this can be done:

gist

Bundles and packages and boxes and goodies...

There are a few different bundles in dist/:

browser
commonjs
esm

Usage no npm install needed!