Sockette
The cutest little WebSocket wrapper! 🧦
Sockette is a tiny (367 bytes) wrapper around `WebSocket` that will automatically reconnect if the connection is lost!
In addition to attaching [additional API methods](#api), Sockette allows you to **reuse** instances, avoiding the need to redeclare all event listeners.
You have direct access to the (current) underlying `WebSocket` within every `EventListener` callback (via `event.target`).
## Install
```
$ npm install --save sockette
```
## Usage
Unlike `WebSocket`, you should declare all event listeners on initialization:
```js
const Sockette = require('sockette');
const ws = new Sockette('ws://localhost:3000', {
timeout: 5e3,
maxAttempts: 10,
onopen: e => console.log('Connected!', e),
onmessage: e => console.log('Received:', e),
onreconnect: e => console.log('Reconnecting...', e),
onmaximum: e => console.log('Stop Attempting!', e),
onclose: e => console.log('Closed!', e),
onerror: e => console.log('Error:', e)
});
ws.send('Hello, world!');
ws.json({type: 'ping'});
ws.close(); // graceful shutdown
// Reconnect 10s later
setTimeout(ws.reconnect, 10e3);
```
## API
### Sockette(url, options)
Returns: `Sockette`
Returns the `Sockette` instance.
#### url
Type: `String`
The URL you want to connect to — Should be prefixed with `ws://` or `wss://`. This is passed directly to `WebSocket`.
#### options.protocols
Type: `String|Array`
Either a single protocol string or an array of strings used to indicate sub-protocols. See the [`WebSocket` docs][MDN] for more info.
#### options.timeout
Type: `Number`
Default: `1000`
The amount of time (in `ms`) to wait in between reconnection attempts. Defaults to 1 second.
#### options.maxAttempts
Type: `Number`
Default: `Infinity`
The maximum number of attempts to reconnect.
> **Important:** Pass `-1` if you want to disable this feature. Although, this is main reason to use Sockette! :joy:
#### options.onopen
Type: `Function`
The `EventListener` to run in response to `'open'` events. It receives the `Event` object as its only parameter.
> This is called when the connection has been established and is ready to send and receive data.
> **Important:** Sockette will forget the number of previous reconnection attempts, so that the next time connection is lost, you will consistently retry `n` number of times, as determined by `options.maxAttempts`.
#### options.onmessage
Type: `Function`
The `EventListener` to run in response to `'message'` events. It receives the `Event` object as its only parameter.
> This is called when a message has been received from the server. You'll probably want `event.data`!
#### options.onreconnect
Type: `Function`
The callback to run when attempting to reconnect to the server.
If Sockette is automatically reconnecting in response to an `error` or unexpected `close` event, then your `onreconnect` callback will receive the forwarded `Event` object.
#### options.onmaximum
Type: `Function`
The callback to run when the [`maxAttempts`](o#ptionsmaxattempts) limit has been met.
This callback will receive the forwarded `Event` object from `onclose`.
#### options.onclose
Type: `Function`
The `EventListener` to run in response to `'close'` events. It receives the `Event` object as its only parameter.
> This is called when the connection has been closed for any reason.
> **Important:** If the `event.code` is _not_ `1000` or `1005` an automatic reconnect attempt will be queued.
#### options.onerror
Type: `Function`
The `EventListener` to run in response to `'error'` events. It receives the `Event` object as its only parameter.
> This is called anytime an error occurs.
> **Important:** If the `event.code` is `ECONNREFUSED`, an automatic reconnect attempt will be queued.
### send(data)
Identical to [`WebSocket#send()`][send], capable of sending multiple data types.
### close(code, reason)
Identical to [`WebSocket#close()`][close].
> **Note:** The `code` will default to `1005` unless specified.
### json(obj)
Convenience method that passes your `obj` (Object) through `JSON.stringify` before passing it to [`WebSocket#send()`][send].
### reconnect()
If [`options.maxAttempts`](#optionsmaxattempts) has not been exceeded, enqueues a reconnection attempt. Otherwise, it runs your [`options.onmaximum`](#optionsonmaximum) callback.
### open()
Initializes a new `WebSocket` — used on initialization and by [`reconnect()`](#reconnect).
## License
MIT © [Luke Edwards](https://lukeed.com)
[MDN]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
[close]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket#close()
[send]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket#send()
