Socketto
Tiny wrapper for WebSocket Web API
Installation
Install with npm:
npm i socketto
Install with yarn:
yarn add socketto
Usage
You can create a WebSocket connection based on the example below:
import Socketto from 'socketto'
const ws = new Socketto('ws://localhost:8080',
{ // these events are optional
onOpen: () => console.log('OPEN'),
onReconnect: () => console.log('RECONNECT'),
onMessage: (data) => { console.log(`RECEIVED MESSAGE ${data}`) },
onRetry: () => { console.log('RETRY TO CONNECT') },
onFailed: () => { console.log('FAILED TO CREATE CONNECTION') }
},
{ // these options are optional
waitToReconnect: 1000,
maxReconnectAttempts: 4
}
)
// open connection
ws.createConnection()
Events
You can add callbacks up to four event handler that WebSocket listens to:
onOpen()
This event will be triggered when WebSocket connection is opened
onReconnect()
This event will be triggered when WebSocket connection is estabilished successfully after retry
onMessage(data)
This event will be triggered when WebSocket receives message from server. Usually is used to render the message in UI. The parameter can be anything (e.g. string, object, etc.)
onRetry()
This event will be triggered everytime WebSocket try to reconnect
onFailed()
This event will be triggered when WebSocket failed to create a connection after retry a certain times
Options
waitToReconnect
How long WebSocket will wait before trying to reconnect. Default value is 3 seconds
maxReconnectAttempts
Maximum retry number allowed. Default value is 3
Reconnect
Socketto can reconnect by default using exponential backoff. It means that Socketto will increase the waiting time between retries after each retry failure. On default configuration, Socketto will try to reconnect 3 times, and wait for 3 seconds at the first retry. You can change the configuration when opening the connection. For example:
import Socketto from 'socketto'
const ws = new Socketto('ws://localhost:8080', {
// event callbacks
}, {
maxReconnectAttempts: 5,
waitToReconnect: 5000
})
With this configuration, Socketto will try to reconnect 5 times maximum, and will wait for 5 seconds for the first retry.
API
.createConnection()
ws.createConnection()
This API will try to open a WebSocket connection based on constructor parameters
.closeConnection()
ws.closeConnection()
Close the WebSocket connection. By calling this API, WebSocket will immediately close its connection without retry
.send()
ws.send('send-dummy-message')
Send any data through WebSocket connection
.readyState
ws.readyState
Returns the current state of WebSocket connection based on MDN
Value | State | Description |
---|---|---|
0 | CONNECTING | Socket has been created. The connection is not yet open. |
1 | OPEN | The connection is open and ready to communicate. |
2 | CLOSING | The connection is in the process of closing. |
3 | CLOSED | The connection is closed or couldn't be opened. |