ws-frame

ws-frame was used for one of my private project, and I make it as a library which is an utility for WebSocket. It could make your WebSocket more smartly because it could be reconnect to the server automatically.

中文版使用说明

Get started

Install ws-frame

First, you need to install the package into your project.

npm install ws-frame
yarn add ws-frame	

• Be attention: This library is written under the gramma of ES Module. You could use it in your @vue/cli, create-react-app generated projects and webpack projects.
• But it is not suitable for browser or Node.js development. You could download the source code from github and do some changes to meet your requirements.

Import ws-frame

Add the below codes into your .js file which would use this library.

import wsframe from "ws-frame";

Construct a wsframe object

Create a WebSocket connection managed by wsframe.

var wsc = new wsframe({
    server: "ws://127.0.0.1:6099/test"
});

You could create a WebSocket connection by new wsframe(options), and the options is a javascript object could contains below members.

If there is a * symbol after the name of the field means this field is required.

| field | type | default | descript | | ------------------ | -------- | --------------------- | ------------------------------------------------------------ | | server * | string | - | The url of the server you need to connect to.For example: ws://127.0.0.1:6099/test | | debugLog | bool | false | Output the log of each stage switching.Only for debug, it should be always false. | | connectTimeout | number | 5000 | The max time between the wsframe.open called and the connection is successfully connected.If time is over, the connection would be closed and try to reconnect if reconnect is set to true.Unit: ms | | reconnect | bool | true | While lost or timeout, should wsframe automatically reconnect to the server. | | reconnectDelay | number | 5000 | How long would wait before wsframe reconnect to the server.Unit: ms | | sendPing | bool | true | If true, send a heart-beat to the server looply. | | sendPingPeriod | number | 29999 | If sendPing is true, how long would be wait between each heart-beat sending. | | pingPongTimeout | number | 10000 | If sendPing is true, the max time between the heart-beat sent and the server responses the heart-beat.If time is over, the connection would be closed and try to reconnect if reconnect is set to true.Unit: ms | | generatePingPack | function | () => 'ping' | The function used to generate the heart-beat package.The return value is the message set to the server. | | isPongChecking | function | (msg)=>msg==='pong' | The function used for checking the heart-beat is responded correctly.If return true, the server responded correctly. | | pongNotFireReceive | bool | true | After the heart-beat checking completed, would the checked message still trigger the received event. |

Bind the events

wsc.on("<event name>", callback);

function callback(evt){ ... }

<event name> could be:

| event name | description | | ---------------- | ------------------------------------------------------------ | | lost | When 1.the connection is closed accidently, or 2.determined as timeout via ping-pong timeout checking. The connection would be closed and this event would be triggered.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance. | | inited | When 1.The first time connected to the server, or 2.closed manually then reconnect to the server,This event would be triggered.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance. | | reconnected | If the connection is lost, usually after the lost event is triggered.And then reconnected to the server.This event would be triggered.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance.evt.server: the url of the remote server. | | connected | After inited or reconnected is triggered, this event would be always triggered after them.If you need to do something on after what ever the connection is connected, use this.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance.evt.server: the url of the remote server. | | timeout | When the max time is over after the connection is open, and the connection is not successfully connected. This event would be triggered.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance.evt.server: the url of the remote server. | | closed | Only would be triggered, after calling wsframe.close()to close the connection manually.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance. | | try-to-reconnect | Before wsframe try to reconnect to the server, this event would be triggered.Usually after the lost event and timeout event.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance.evt.delay How long would be delayed to try to reconnect. | | received | While the message from the server is received.The parameters of function callback(evt)：evt.wsc: The original managed WebSocket Instance.evt.payload: The received data, could be string or ArrayBuffer. |

Some usable properties

wsc.$props.onlineState // => "offline" or "online"

You could read some information about the currently using wsframe object from wsframe.$props.

| field | type | description | | ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | connectState | "lost" | "closed" | "timeout" | "connected" | "not-connect" | "reconnecting" | The state of the current connection. It could be:lost - Closed accidently.closed - Manually closed.timeout - Connect timeout.connected - Connected.not-connect - Finished initializing but not start to connect.reconnecting - Reconnecting. | | onlineState | "online" | "offline" | The state of the current server.online - Onlineoffline - Offline | | lastPingTime | Date | The last ping sent time, but would clear after each start of the connection. | | lastPongTime | Date | The last heart-beat response received time, but would clear after each start of the connection. | | inited | bool | Is initialization is completed.Startup: falseAfter connected to the server: trueManually closed: false.If the connection closed accidently, it would not be changed. |

The diagram