Namespaces and events

Declare a WebSocket namespace with @WebSocket() and mark each event handler with @WebSocketEvent(). The event generator discovers these decorated classes and registers their handlers with the configured adapter.

chat-websocket.ts

import { WebSocket, WebSocketEvent, WsConnection, WsData } from '@axisparkjs/websocket';
import type { WebSocketConnection } from '@axisparkjs/websocket';

@WebSocket('/chat')
export class ChatWebSocket {
    @WebSocketEvent('message')
    onMessage(
        @WsConnection() connection: WebSocketConnection,
        @WsData() data: { text: string }
    ) {
        // Handle the message. Returning a value sends it through the message acknowledgment.
        return { received: data.text };
    }
}

The namespace argument is optional; @WebSocket() declares the default namespace. The adapter normalizes namespace names to start with /, so @WebSocket('chat') and @WebSocket('/chat') refer to /chat.

Each class can declare multiple event handlers. Pass a string to match one exact event name, or a RegExp to handle event names that match a pattern:

@WebSocketEvent('message')
onMessage() {}

@WebSocketEvent(/^user:\w+$/)
onUserEvent() {}

Regex patterns are tested against the complete event name using JavaScript RegExp semantics. The adapter does not add anchors, so an unanchored pattern can match part of an event name. All JavaScript regex flags are honored. Global (g) and sticky (y) patterns are evaluated from index zero for every event, and their lastIndex is restored afterward so matching does not depend on earlier events. String event names continue to match exactly.

If multiple regex patterns match one event name, each matching handler runs. An exact event handler and a matching regex handler can both handle the same event.

Handle a new connection

The Socket.IO adapter supports a special connection event. A handler declared with that name runs once when a client connects to the namespace. It receives a connection context, so use @WsConnection() to access the client:

@WebSocket('/chat')
export class ChatWebSocket {
    @WebSocketEvent('connection')
    onConnect(@WsConnection() connection: WebSocketConnection) {
        connection.emit('welcome', { connectionId: connection.id });
    }

    @WebSocketEvent('message')
    onMessage(@WsData() data: { text: string }) {
        ...
    }
}

The connection event is reserved by the Socket.IO adapter for this lifecycle hook. It is not registered as an ordinary client message handler.

Event parameters

The plugin provides decorators for injecting values from the current WebSocket event:

Decorator	Value
@WsConnection()	Current connection.
@WsMessage()	Full message, including its data and optional acknowledgment callback.
@WsData()	Message data (message.data).
@WsAck()	Optional acknowledgment callback (message.ack).

Import these decorators from @axisparkjs/websocket. A handler can also use dependency injection in its class constructor, like other AxiSpark components.

Acknowledgments and results

The WebSocket result resolver sends successful handler results to the message's acknowledgment callback. If a handler needs to acknowledge explicitly, inject @WsAck() and call the callback when appropriate. If the client did not provide an acknowledgment callback, the callback is undefined.

WebSocket errors are returned to an available acknowledgment callback with error, status, and an optional description field.