WS Builder
Easily build a WebSocket API - uses ws
The idea of WS Builder is to use plugins to interact with WebSockets.
Example
See example directory: gitlab
Another example is: UP Down Site
WsServer
The WsServer class creates an instance of WS.Server using the opts and startedCb passed into it.
The following scenarios will invoke all plugins in the plugins array in order:
- connection - plugins will be invoked with
{'action': 'connect'} - message - plugins will be invoked with
{'action': 'message'} - close of connection - plugins will be invoked with
{'action': 'close'} - server error - plugins will be invoked with
{'action': 'serverError'} - socket error - plugins will be invoked with
{'action': 'clientError'} - plugin error - plugins will be invoked with
{'action': 'pluginError'}
class WsServer {
public readonly server: WS.Server
public plugins: Plugin[]
public constructor(opts?: WS.ServerOptions, startedCb?: () => void)
}Plugin
A plugin is a class that implements the Plugin interface.
type pluginArgs = {
ws: WS
action: 'connect' | 'message' | 'close' | 'serverError' | 'clientError' | 'pluginError'
data: any
}
interface Plugin {
handle(args: pluginArgs): void
}Premade plugins
Currently the following plugins exist inside this module:
JsonParser
Json parser is a plugin that will run every message through JSON.parse, any plugin after JsonParser will receive data as an object if it was originally stringified JSON.
Usage
// TS
import { WsServer, JsonParser } from 'ws-builder'
// JS
const { WsServer, JsonParser } = require('ws-builder')
const parser = new JsonParser(true) // true to error on invalid JSON, false catches the error
const server = new WsServer({ port: 3005 })
server.plugins.push(parser)
// Send a message to server
import * as WS from 'ws'
const WS = require('ws')
const ws = new WS('ws://localhost:3005')
ws.on('open', () => {
ws.send(JSON.stringify({
key: 'value'
}))
})KeyRouter
Key Router is a routing plugin, it contains an object called keys which is a key/value pair or route keys to handlerFunctions.
Usage
// TS
import { WsServer, KeyRouter } from 'ws-builder'
// JS
const { WsServer, KeyRouter } = require('ws-builder')
// param 1: true to throw error if message body does not contain the 'key' key
// param 2: true to throw error if value of 'key' is not in the 'keys' object
// param 3: true to add 'help' key which will send an array of keys
const router = new KeyRouter(true, true, true)
router.keys.value = (ws: WS, msg: WS.Data) => {
// Do something with msg and send response with ws.send
// msg: { key: 'value', data: { some: 'kind of data' } }
}
const server = new WsServer({ port: 3005 })
server.plugins.push(router)
// Send a message to server
import * as WS from 'ws'
const WS = require('ws')
const ws = new WS('ws://localhost:3005')
ws.on('open', () => {
ws.send(JSON.stringify({
key: 'value',
data: {
some: 'kind of data'
}
}))
})Logger
Logger simply logs the data passed to it using a function set in it's logFuncs object.
Usage
// TS
import { WsServer, Logger } from 'ws-builder'
// JS
const { WsServer, Logger } = require('ws-builder')
const logger = new Logger()
logger.logFuncs = {
log: logFunction, // Defaults to console.log, will be used for any logging that is not an error
warn: warnFunction, // Defaults to console.warn, currently will never be used
error: errorFunction // Defaults to console.error, will be used when handler is called with { action: '*Error' } (where * is a wildcard)
}
const server = new WsServer({ port: 3005 })
server.plugins.push(logger)
// Send a message to server
import * as WS from 'ws'
const WS = require('ws')
const ws = new WS('ws://localhost:3005')
ws.on('open', () => {
ws.send(JSON.stringify({
test: true
}))
})