WebSocket#

Teasim WebSocket extends Bun's WebSocket which uses uWebSocket under the hood.

To use websocket, just call ws():

import { Teasim } from "teasim";

const app = new Teasim()
  .ws("/ws", {
    message(ws, message) {
      ws.send(message);
    },
  })
  .listen(8080);

Like a normal route, WebSockets also accepts a schema object to strictly type and validate requests.

Configuration#

You can set Teasim constructor to set the Web Socket value.

new Teasim({
  websocket: {
    idleTimeout: 30,
  },
});

Teasim's WebSocket implementation extends Bun's WebSocket configuration so if you wish to configure the websocket you can refer to Bun's WebSocket documentation to learn more about this.

Below is a config that extends from Bun WebSocket

perMessageDeflate#

@default false

Enable compression for clients that support it.

By default, compression is disabled.

maxPayloadLength#

The maximum size of a message.

idleTimeout#

@default 120

After a connection has not received a message for this many seconds, it will be closed.

backpressureLimit#

@default 16777216 (16MB)

The maximum number of bytes that can be buffered for a single connection.

closeOnBackpressureLimit#

@default false

Close the connection if the backpressure limit is reached.

Methods#

Below are the new methods that are available to the WebSocket route

ws#

Create a websocket handler

Example:

import { Teasim } from "teasim";

const app = new Teasim()
  .ws("/ws", {
    message(ws, message) {
      ws.send(message);
    },
  })
  .listen(8080);

Type:

.ws(endpoint: path, options: Partial<WebSocketHandler<Context>>): this

endpoint: A path to exposed as websocket handler options: Customize WebSocket handler behavior

WebSocketHandler#

WebSocketHandler extends config from config.

Below is a config which is accepted by ws.

schema#

Validatation for an incoming WebSocket request.

• headers: validate headers before upgrade to WebSocket
• params: validate path paramters
• query: validate query parameters
• body: validate websocket message
• response: validate websocket response

open#

Callback function for new websocket connection.

Type:

open(ws: ServerWebSocket<{
    // uid for each connection
    id: string
    data: Context
}>): this

message#

Callback function for incoming websocket message.

Type:

message(
    ws: ServerWebSocket<{
        // uid for each connection
        id: string
        data: Context
    }>,
    message: Message
): this

Message type based on schema.message. Default is string.

close#

Callback function for closing websocket connection.

Type:

close(ws: ServerWebSocket<{
    // uid for each connection
    id: string
    data: Context
}>): this

drain#

Callback function for the server is ready to accept more data.

Type:

drain(
    ws: ServerWebSocket<{
        // uid for each connection
        id: string
        data: Context
    }>,
    code: number,
    reason: string
): this

parse#

Parse middleware to parse the request before upgrading the HTTP connection to WebSocket.

beforeHandle#

Before Handle middleware which execute before upgrading the HTTP connection to WebSocket.

Ideal place for validation.

transform#

Transform middleware which execute before validation.

transformMessage#

Like transform, but execute before validation of WebSocket message

header#

Additional headers to add before upgrade connection to WebSocket.

WebSocket message validation:#

Validate incoming WebSocket message.

By default Teasim will parse incoming stringified JSON message as Object for validation.

import { Teasim } from 'teasim'

const app = new Teasim()
    .ws('/ws', {
        // validate incoming message
        body: t.Object({
            message: t.String()
        })
        message(ws, { message }) {
            ws.send({
                message,
                time: Date.now()
            })
        }
    )
    .listen(8080)