Choo-websocket NPM

choo-websocket

Small wrapper around WebSocket browser API, for choo apps

Usage

var choo = require('choo')
var html = require('choo/html')

var app = choo()
app.use(require('choo-websocket')())
app.route('/', mainView)
app.mount('body')

function mainView (state, emit) {
  return html`
    <body>
      <pre id="results"></pre>
      <p>Send something through sockets:</p>
      <input id="message" />
      <button onclick=${onclick}>Send</button>
    </body>
  `

  function onclick () {
    emit('ws:send', document.getElementById('message').value)
    document.getElementById('message').value = ''
  }
}

function live (state, emitter) {
  emitter.on('DOMContentLoaded', function () {
    emitter.on('ws:open', () => {
      console.log('Connection established')
    })
    emitter.on('ws:message', (data, event) => {
      var msgElement = document.getElementById('results')
      msgElement.textContent = msgElement.textContent + data + '\n'
    })
  })
}

Events

`ws:error` | `ws.events.ERROR`

Emitted if the WebSocket constructor or any of its methods throws an exception.

`ws:open` | `ws.events.OPEN`

Emitted when the connection is established and the readyState property of the socket changes to OPEN. You should only listen to this method, since the constructor and the add-socket event silently open sockets for you. This event handler will get two arguments, the event object, and the id of the socket that got opened, you can use that id to directly access to the socket through state.sockets[id] or passing it to events like send and close. If you don't pass the id, it will asume the default socket (the one created when the plugin got registered).

`ws:close` | `ws.events.CLOSE`

Emitted when the connection is closed and the readyState property of the socket changes to CLOSED. When you listen to this, handler will take two arguments, the event object and the socket id. When you emit this, it will take three arguments the code for the close, the reason string and the id of the socket you want to close. If you don't pass the id, it will asume the default socket (the one created when the plugin got registered).

`ws:send` | `ws.events.SEND`

Emitted to send a message through the socket. Emit this event passing the data you want to send, and an optional id as reference of the socket that you want to send the message.

`ws:message` | `ws.events.MESSAGE`

Listen to this event to get messages from the socket. The handler of this event will get three arguments, the data sent, the whole evet and the id of the socket that got the message.

`ws:add-socket` | `ws.events.ADD_SOCKET`

Add a socket. Accept a route, an options object and an optional id, if you pass a route of an existing socket it will override it. If you don't pass any id, it will create a random string as id. This id is used to identify the WebSocket instance in the app state and to emit and listen for events only to specific instances. Keep in mind that this is agnostic to the server side implementation, so its up to you to handle different websockets from server. In the example folder, there is a simple implementation of rooms using the ws module. Some other libraries like socket.io has this concept built in.

API

`plugin = ws([route], [opts])`

The plugin accepts three optional parameters. You can pass the route for the web socket, which defaults to window.location.host. Notice that you don't need to specify the ws protocol. Also you can pass some options as a second argument.

secure: Boolean. Set to true if you are in a secure environment. If you mix environment, it will throw on creation of the socket.
protocols: Array or String. Use it to specify sub protocols for the socket.

If the object is correctly created, then you have a sockets object where every propertie is a key to the WebSocket instance that you added.