choo-websocket
v2.0.0
Published
Small wraper around WebSocket browser API, for choo apps
Readme
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.
See Also
- choo-sse - Small wrapper around server-sent event browser API, for choo apps.