Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lukeed/sockette

The cutest little WebSocket wrapper! 🧦
https://github.com/lukeed/sockette

Last synced: about 1 month ago
JSON representation

The cutest little WebSocket wrapper! 🧦

Lists

README 

        


  Sockette




Sockette





  

    version

  

  

    CI

  

  

    licenses

  

  

    downloads

  




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`, `1001`, 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 `1000` 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