https://github.com/betaweb/websockets
A simple JavaScript class to handle browser-side Websockets
https://github.com/betaweb/websockets
browser javascript javascript-class simple-api websocket websocket-client websockets
Last synced: 2 months ago
JSON representation
A simple JavaScript class to handle browser-side Websockets
- Host: GitHub
- URL: https://github.com/betaweb/websockets
- Owner: betaWeb
- Created: 2020-04-30T13:46:45.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2020-05-07T08:52:23.000Z (about 5 years ago)
- Last Synced: 2025-03-08T22:08:19.226Z (3 months ago)
- Topics: browser, javascript, javascript-class, simple-api, websocket, websocket-client, websockets
- Language: JavaScript
- Size: 314 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Websockets
A simple JavaScript class to handle browser-side Websockets.
> Note : this library provides an API only for browser-side Websokets.
## Getting started
Include `Websockets.min.js` script in your HTML :
```html
```
And declare a new instance in your script :
```javascript
const client = new Websockets({
port: 9000,
scheme: 'ws',
onprogress(progress, dataSize, data) {
if (progress === 0) {
console.log('Data sended successfully !')
} else {
console.log(`${dataSize - progress}/${dataSize} bytes have been sent.`)
}
}
})
client.on(Websockets.DEFAULT_EVENTS.CONNECTED, () => {
console.log("It's alive ! ALIVE !")
})
client.on('wakedup', () => {
console.log("Waked up !")
})
await client.connect()
await client.emit('wakeup', { body: "It's time to wake up !" })
client.destroy()
```
And.. that's it ! :)
## Available getters and methods
### Getters
```typescript
// Websockets class default options
static DEFAULT_OPTIONS: Object.
// WebSocket native API close codes by status
static CLOSE_STATUS: Object.
// WebSocket native API close messages by codes
static CLOSE_STATUS_MESSAGES: Object.
// Websockets class default events
static DEFAULT_EVENTS: Object.
// returns true if WebSocket API is supported by the actual browser, false otherwise
static hasSupport: Boolean
// WebSocket schme ('auto', 'ws', 'wss')
scheme: String
// WebSocket URL
url: String
// Registered events via `Websockets.on()` method
events: Object.
// returns true if WebSocket client is instantiated, false otherwise
isInitialized: Boolean
// returns true if WebSocket client is connecting, false otherwise
isConnecting: Boolean
// returns true if WebSocket client is connected, false otherwise
isOpen: Boolean
// returns true if WebSocket client is sending data, false otherwise
isSending: Boolean
// returns true if WebSocket connection is closing or closed, false otherwise
isClosed: Boolean
```
### Methods
```typescript
connect(): Promise
```
Connect the WebSocket client to the specified endpoint.
__Example :__
```javascript
await client.connect()
```
```typescript
send(data: any): Promise
```
send data to the server.
__Example :__
```javascript
await client.send('PING')
```
```typescript
emit(type: String, payload?: any = '', namespaced?: boolean = true): Promise
```
Format a data object with `type` and `payload`, and send it to the server. If `namespaced` is false, `type` parameter will doesn't be prefixed by the namespace specified in the Websockets instance options.
__Example :__
```javascript
// Emit 'USER_MESSAGE' event to the server with a payload
await client.emit('USER_MESSAGE', { message: 'Hello, World !', user_id: 1 })
// Emit 'USER_MESSAGE' event to the server with a payload and without namespace
await client.emit('USER_MESSAGE', { message: 'Hello, World !', user_id: 1 }, false)
```
```typescript
on(type: String, callback: Function, namespaced?: boolean = true): Websockets
```
Add an event. If `namespaced` is false, `type` parameter will doesn't be prefixed by the namespace specified in the Websockets instance options.
__Example :__
```javascript
// Listen to 'PONG' event from the server
client.on('PONG', () => console.log('The server responds with PONG !'))
// Send 'PING' event to the server
await client.send('PING')
```
```typescript
once(type: String, callback: Function, namespaced?: boolean = true): Websockets
```
Add an event. This event will be listenend only once. After that, it will be deleted.
If `namespaced` is false, `type` parameter will doesn't be prefixed by the namespace specified in the Websockets instance options.
__Example :__
```javascript
// Listen to 'PONG' event from the server
client.once('PONG', () => console.log('This event is unique !'))
// Send 'PING' event to the server
await client.send('PING')
```
```typescript
off(type: String, callback?: Function = null, namespaced?: boolean = true): Websockets
```
Removes an event. if `callback` parameter is `null`, all events of type `type` will be removed, otherwise, only the event that corresponds to the `callback` parameter will be removed. If `namespaced` is false, `type` parameter doesn't be prefixed by the namespace specified in the Websockets instance options.
__Example :__
```javascript
const onPong = () => console.log("The server responds with PONG !\n")
// Listen to 'PONG' event from the server
client.on('PONG', onPong)
// Send 'PING' event to the server
await client.send('PING')
// Detach 'PONG' event listener
client.off('PONG', onPong)
```
```typescript
onMessage(callback: Function): Websockets
```
The callback parameter will be triggered with each message sent from the server.
__Example :__
```javascript
client.onMessage(data => console.log(data))
```
```typescript
disconnect(): void
```
disconnect the WebSocket client.
__Example :__
```javascript
client.disconnect()
```
```typescript
destroy(): void
```
Remove all Websockets events and disconnect the WebSocket client.
__Example :__
```javascript
client.destroy()
```
## Instance options
TODO