WebSocket

Define IWebsocket handlers with @Websocket, inject WebsocketServer by path, then send or brocast text and binary frames to connected clients.

Define & register

Implement IWebsocket on a class decorated with @Websocket. Register it on the root module under websocket. Inject WebsocketServer with the same path for send / brocast APIs.

@Websocket({ path, ssl?, pingpongInterval? }) — path is the URL endpoint; pingpongInterval is keep-alive in ms
@Module({ websocket: [ChatWebsocket] }) — register the handler class
@InjectWebsocketServer("/chat-websocket") — inject the server for that path (works on the handler, services, or controllers)
onAuthenticate — return ClientInfo ({ id, … }) to accept, or null to reject

TSXhandler + module

import {
  InjectWebsocketServer,
  Module,
  Websocket,
  WebsocketServer,
} from "@quan-erp/shared-backend-core";
import type {
  ClientInfo,
  IWebsocket,
  WebsocketClient,
  WebsocketEvents,
} from "@quan-erp/shared-backend-core";
import type { IncomingMessage } from "http";
import type WebSocket from "ws";
import metadata from "../../module.metadata.json" with { type: "json" };

@Websocket({
  ssl: false,
  pingpongInterval: 1000,
  path: "/chat-websocket",
})
export class ChatWebsocket implements IWebsocket {
  @InjectWebsocketServer("/chat-websocket")
  websocket: WebsocketServer;

  onAuthenticate(ws: WebSocket, req: IncomingMessage): ClientInfo | null {
    return { id: "user-42" }; // null rejects the connection
  }

  on(
    event: WebsocketEvents,
    client: WebsocketClient,
    data: any,
    isBinary: boolean,
  ) {
    // see receive section
  }

  onUpgrade() {}
  onDestoryed() {}
}

@Module({
  name: metadata.name,
  providers: [],
  controllers: [],
  entities: [],
  websocket: [ChatWebsocket],
})
export class MyPluginModule {}

Message wrappers

Outbound payloads must implement WebsocketMessage (getMessage()). Use the built-in wrappers — do not pass raw strings to sendText / brocast.

WebsocketTextEventMessage(event, payload) — JSON { event, payload }; preferred for app events
WebsocketTextMessage(data) — plain text / raw JSON string frame
WebsocketBinaryMessage(payload: Buffer) — binary Buffer frame

TSXwrappers

import {
  WebsocketBinaryMessage,
  WebsocketTextEventMessage,
  WebsocketTextMessage,
} from "@quan-erp/shared-backend-core";

new WebsocketTextEventMessage("kitchen", { orderId: 12 });
// → send/brocast as JSON: {"event":"kitchen","payload":{"orderId":12}}

new WebsocketTextMessage("Hello");
// → plain text frame

new WebsocketBinaryMessage(Buffer.from([0x01, 0x02]));
// → binary frame

Send text (one client)

Target a client by the id returned from onAuthenticate (ClientInfo.id). sendText accepts WebsocketTextEventMessage or WebsocketTextMessage. All sockets sharing that client id receive the frame.

TSXsendText

import {
  InjectWebsocketServer,
  Service,
  WebsocketServer,
  WebsocketTextEventMessage,
  WebsocketTextMessage,
} from "@quan-erp/shared-backend-core";

@Service()
export class ChatPushService {
  @InjectWebsocketServer("/chat-websocket")
  private ws: WebsocketServer;

  notifyUser(userId: string) {
    this.ws.sendText(
      userId,
      new WebsocketTextEventMessage("inbox", {
        title: "New message",
      }),
    );

    this.ws.sendText(
      userId,
      new WebsocketTextMessage("ping"),
    );
  }
}

Send binary (one client)

Use sendBinary with WebsocketBinaryMessage for Buffer payloads (files, compressed blobs, custom protocols).

TSXsendBinary

import {
  InjectWebsocketServer,
  Service,
  WebsocketBinaryMessage,
  WebsocketServer,
} from "@quan-erp/shared-backend-core";

@Service()
export class FileStreamService {
  @InjectWebsocketServer("/chat-websocket")
  private ws: WebsocketServer;

  pushChunk(clientId: string, chunk: Buffer) {
    this.ws.sendBinary(
      clientId,
      new WebsocketBinaryMessage(chunk),
    );
  }
}

Brocast (all clients)

WebsocketServer.brocast (spelled brocast in the API) sends one WebsocketMessage to every connected client on that path. Works with text event, plain text, or binary wrappers.

Method name is brocast — not broadcast
Use from controllers/services after domain writes (e.g. kitchen board refresh)
Payload must be a WebsocketMessage wrapper

TSXbrocast from controller

import {
  Controller,
  InjectWebsocketServer,
  Post,
  ResponseDto,
  WebsocketServer,
  WebsocketTextEventMessage,
} from "@quan-erp/shared-backend-core";

@Controller("/order")
export class OrderController {
  @InjectWebsocketServer("/chat-websocket")
  private wsServer: WebsocketServer;

  @Post("/")
  async create() {
    // … persist order …
    this.wsServer.brocast(
      new WebsocketTextEventMessage("kitchen", "New Order"),
    );
    return ResponseDto.ok({ ok: true });
  }
}

TSXbrocast binary

import {
  WebsocketBinaryMessage,
  WebsocketServer,
} from "@quan-erp/shared-backend-core";

declare const ws: WebsocketServer;
ws.brocast(new WebsocketBinaryMessage(Buffer.from("raw-bytes")));

Raw send on current client

Inside on(), you can also write to the active socket with client.getWebsocket().send(...). Prefer WebsocketServer helpers when targeting by client id or brocasting.

TSXraw send

import type { WebsocketClient } from "@quan-erp/shared-backend-core";
import { WebsocketTextEventMessage } from "@quan-erp/shared-backend-core";

function reply(client: WebsocketClient) {
  client
    .getWebsocket()
    .send(new WebsocketTextEventMessage("ack", { ok: true }).getMessage());
}

Receive text & binary

on(event, client, data, isBinary) is called for connection lifecycle and frames. Use WebsocketMessageHandler to route structured text events ({ event, payload }) vs generic message / close handlers. Binary frames skip JSON event parsing.

isBinary === false — data is a string; JSON with an event field can match onTextEvent("name")
isBinary === true — data is binary; use .on("message", …) (text-event routing is skipped)
onTextEvent callbacks take no args — close over data / client from on() if you need the payload
Always call .execute() at the end of the chain

TSXreceive

import {
  InjectWebsocketServer,
  Websocket,
  WebsocketMessageHandler,
  WebsocketServer,
  WebsocketTextEventMessage,
} from "@quan-erp/shared-backend-core";
import type {
  IWebsocket,
  WebsocketClient,
  WebsocketEvents,
} from "@quan-erp/shared-backend-core";

@Websocket({ ssl: false, pingpongInterval: 1000, path: "/chat-websocket" })
export class ChatWebsocket implements IWebsocket {
  @InjectWebsocketServer("/chat-websocket")
  websocket: WebsocketServer;

  onAuthenticate() {
    return { id: "user-42" };
  }

  on(
    event: WebsocketEvents,
    client: WebsocketClient,
    data: any,
    isBinary: boolean,
  ) {
    new WebsocketMessageHandler(event, data, isBinary)
      .onTextEvent("chat-room", () => {
        const parsed = JSON.parse(String(data));
        this.websocket.brocast(
          new WebsocketTextEventMessage("chat-room", parsed.payload),
        );
      })
      .on("message", () => {
        if (isBinary) {
          // Buffer / ArrayBuffer-like frame in data
          return;
        }
        // plain text or non-event JSON
      })
      .on("close", () => {
        // client disconnected
      })
      .execute();
  }

  onUpgrade() {}
  onDestoryed() {}
}

Inspect clients

getAllClients() — every WebsocketClient on this path
getByClientId(id) — sockets for that authenticated id (array or null)
client.getClientId() / getClientData() — identity from onAuthenticate

WebsocketServer API

sendText(clientId, WebsocketTextEventMessage | WebsocketTextMessage)
sendBinary(clientId, WebsocketBinaryMessage)
brocast(WebsocketMessage) — all clients on the path
getByClientId(clientId) / getAllClients()