Webbs is a thin abstraction over the WebSocket
API available in modern browsers. It provides vital missing features: automatic reconnect with exponential backoff, and offline buffering of outgoing messages.
Small (≈ 180 LoC, 2.4 KiB minified), dependency-free, simple, hackable.
Webbs is meant for a CommonJS-compatible bundler, such as Webpack or browserify. Install it from NPM:
npm i -E webbs
# or
yarn add -E webbs
Then import:
import {Webbs} from 'webbs'
Creates a new instance. It starts blank and inert. You must call .open(url, protocol)
to actually open a connection.
import {Webbs} from 'webbs'
const webbs = new Webbs()
webbs.onEachOpen =
webbs.onEachClose =
webbs.onEachError =
webbs.onEachMessage =
function report(event) {
console.info('Something happened:', event)
}
webbs.open('ws://my-host:my-port', 'optional-protocol')
Always one of: 'CLOSED'
, 'CONNECTING'
, 'OPEN'
. Initially 'CLOSED'
.
Opens the connection. Will automatically reconnect if disconnected. Stores webbs.url
and webbs.protocol
for automatic reconnects. Idempotent: has no effect if already connected.
const webbs = new Webbs()
webbs.open('ws://my-host:my-port', 'optional-protocol')
Empties the outgoing message buffer, closes the connection, and doesn't reconnect. Can be reopened later. Will trigger onEachClose
if the underlying websocket is open.
Also aliased as webbs.deinit
.
webbs.close()
// some time later
webbs.open(webbs.url, webbs.protocol)
Same as .close()
. Aliased for compatibility with my other libraries, where deinit
is the dominant interface for "closing" things.
Sends message
over the websocket, if open. The message must be compatible with WebSocket.prototype.send
(string or blob).
If not connected, adds message
to webbs.outgoingBuffer
. When connected, will send all buffered messages at once.
const webbs = new Webbs()
// These get buffered
webbs.send('my msg')
webbs.send(new Blob([1, 2, 3]))
// If this succeeds, the messages will be automatically sent
webbs.open('ws://my-host:my-port')
Initially undefined
; you can assign a function. Gets called whenever an underlying native websocket successfully connects. May be triggered multiple times over the lifetime of the webbs
instance.
webbs.onEachOpen = function report(event) {
console.info('Socket reconnected:', event)
}
Initially undefined
; you can assign a function. Gets called whenever an underlying native websocket closes. May be triggered multiple times over the lifetime of the webbs
instance.
Counter-intuitively, this doesn't have symmetry with .onEachOpen
. When reconnecting, .onEachClose
will be called on each failed attempt.
Calling webbs.close()
or webbs.deinit()
always triggers onEachClose
. If the underlying websocket was open, it's triggered asynchronously and receives the relevant DOM event. If the websocket wasn't open, it's triggered synchronously and receives undefined
.
webbs.onEachClose = function report(event) {
console.warn('Socket disconnected:', event)
}
Initially undefined
; you can assign a function. Gets called whenever an underlying native websocket fails to connect or loses an active connection. May be triggered multiple times over the lifetime of the webbs
instance.
webbs.onEachError = function report(event) {
console.warn('Socket error:', event)
}
Initially undefined
; you can assign a function. Gets called whenever an underlying native websocket receives a message.
webbs.onEachMessage = function report(event) {
console.info('Socket message:', event)
}
Better minification. Slightly breaking.
- use ES5-style class to avoid Babel garbage in the output
- replaced
webbs.getState()
with thewebbs.state
getter - 2.6 KiB → 2.4 KiB
Breaking improvements and cleanup:
- moved
url
andprotocol
arguments from constructor to.open
.close
and.deinit
are now equivalent- added
webbs.getState
- better ordering of state changes and callbacks; a webbs instance now reaches a consistent state before invoking the corresponding
onEach
callback onEachClose
is always called on.close
, even if there was no underlying socket- removed
sendJson
; just define a function if you want
I'm receptive to suggestions. If this library almost satisfies you but needs changes, open an issue or chat me up. Contacts: https://mitranim.com/#contacts