Server API Reference - WSX Documentation

WSXServer

The main server class that manages WebSocket connections and request handling.

Constructor

new WSXServer(adapter: WSXServerAdapter)

Creates a new WSX server instance with the provided adapter. Parameters:

adapter - A WSXServerAdapter implementation (Express, Hono, or custom)

Example:

import { WSXServer } from "@wsx-sh/core";
import { createExpressAdapter } from "@wsx-sh/express";

const adapter = createExpressAdapter();
const wsx = new WSXServer(adapter);

Methods

on()

on(handler: string, handlerFunction: WSXHandler): WSXServer
on(handlerFunction: WSXHandler): WSXServer

Parameters:

handler (optional) - Handler name to match against wx-send attribute
handlerFunction - Function to handle the request

Returns: WSXServer instance for chaining Examples:

// Named handler
wsx.on("update-user", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>User updated</div>`,
  };
});

// Catch-all handler
wsx.on(async (request, connection) => {
  console.log(`Received: ${request.handler}`);
  return {
    id: request.id,
    target: request.target,
    html: `<div>Handled: ${request.handler}</div>`,
  };
});

onJson()

onJson(channel: string, handler: WSXJSONHandler): WSXServer
onJson(handler: WSXJSONHandler): WSXServer

Parameters:

channel (optional) - JSON channel name to handle
handler - Function invoked with WSXJSONMessage objects

Example:

wsx.onJson('presence', async (message, connection) => {
  wsx.broadcastJson('presence', {
    userId: connection.id,
    status: message.data.status,
  });
});

// Observe every JSON payload
wsx.onJson(async (message) => {
  console.log(message.channel, message.data);
});

onStream()

onStream(channel: string, handler: WSXStreamHandler): WSXServer
onStream(handler: WSXStreamHandler): WSXServer

Parameters:

channel (optional) - Stream channel name to handle
handler - Function invoked with WSXStreamMessage metadata and the binary payload

Example:

wsx.onStream('audio', async (message, data) => {
  console.log(`Received ${data.byteLength} bytes on`, message.channel);
});

wsx.onStream(async (message) => {
  console.log('Stream message on', message.channel);
});

broadcast()

Send a message to all connected clients.

broadcast(target: string, html: string, swap?: string): void

Parameters:

target - CSS selector for the target element
html - HTML content to insert
swap (optional) - Swap method (default: ‘innerHTML’)

Example:

wsx.broadcast("#status", "<div>Server updated</div>", "innerHTML");

broadcastJson()

Publish a JSON payload to every connected client.

broadcastJson(channel: string, data: any, options?: WSXJSONSendOptions): string

Parameters:

channel - Logical channel name
data - JSON-serializable payload
options (optional) - Additional metadata or explicit identifier

Returns: Unique message identifier sent to clients Example:

wsx.broadcastJson('presence', { userId: 'conn_5', status: 'online' });

broadcastStream()

Send a binary payload to every connected client.

broadcastStream(channel: string, payload: WSXBinaryData, options?: WSXStreamSendOptions): string

Parameters:

channel - Stream channel name
payload - Binary data (ArrayBuffer or typed array)
options (optional) - Metadata or explicit stream identifier

Returns: Generated stream identifier Example:

wsx.broadcastStream('audio', audioChunk, { metadata: { mimeType: 'audio/webm' } });

sendToConnection()

Send a message to a specific connection.

sendToConnection(connectionId: string, target: string, html: string, swap?: string): void

Parameters:

connectionId - ID of the target connection
target - CSS selector for the target element
html - HTML content to insert
swap (optional) - Swap method (default: ‘innerHTML’)

Example:

wsx.sendToConnection(
  "conn_123",
  "#notification",
  "<div>Personal message</div>"
);

sendJsonToConnection()

Send a JSON message to a specific connection.

sendJsonToConnection(connectionId: string, channel: string, data: any, options?: WSXJSONSendOptions): string | undefined

Parameters:

connectionId - Target connection ID
channel - JSON channel name
data - JSON-serializable payload
options (optional) - Metadata or explicit message identifier

Returns: Message identifier, or undefined if the connection is not found Example:

wsx.sendJsonToConnection(connection.id, 'presence', { status: 'typing' });

sendStreamToConnection()

Send a binary stream frame to a specific connection.

sendStreamToConnection(connectionId: string, channel: string, payload: WSXBinaryData, options?: WSXStreamSendOptions): string | undefined

Parameters:

connectionId - Target connection ID
channel - Stream channel name
payload - Binary payload (ArrayBuffer or typed array)
options (optional) - Metadata or explicit identifier

Returns: Stream identifier, or undefined if the connection is missing Example:

wsx.sendStreamToConnection(connection.id, 'audio', audioChunk, { metadata: { sequence: 5 } });

getConnections()

Get all active connections.

getConnections(): WSXConnection[]

Returns: Array of active WSXConnection objects Example:

const connections = wsx.getConnections();
console.log(`Active connections: ${connections.length}`);

getConnectionCount()

Get the number of active connections.

getConnectionCount(): number

Returns: Number of active connections Example:

const count = wsx.getConnectionCount();
console.log(`${count} clients connected`);

removeConnection()

Remove a connection from the server.

removeConnection(connectionId: string): void

Parameters:

connectionId - ID of the connection to remove

Example:

wsx.removeConnection("conn_123");

getApp()

Get the underlying framework app instance.

getApp(): any

Returns: The framework-specific app instance (Express app, Hono app, etc.) Example:

const app = wsx.getApp();
app.get("/health", (req, res) => res.json({ status: "ok" }));

WSXRequest

Interface representing an incoming WebSocket request.

interface WSXRequest {
  id: string; // Unique request ID
  handler: string; // Handler name from wx-send
  target: string; // CSS selector from wx-target
  trigger: string; // Event trigger name
  data?: Record<string, any>; // Form data or wx-data
  swap?: string; // Swap specification
}

Properties:

id - Unique identifier for the request
handler - Handler name specified in wx-send attribute
target - CSS selector from wx-target attribute
trigger - Event that triggered the request
data - Form data or data from wx-data attribute
swap - Swap specification from wx-swap attribute

WSXResponse

Interface representing a response to send back to the client.

interface WSXResponse {
  id: string; // Request ID to match
  target: string; // CSS selector for target element
  html: string; // HTML content to insert
  swap?: string; // Swap method
  oob?: WSXOOBUpdate[]; // Out-of-band updates
}

Properties:

id - Must match the request ID
target - CSS selector for the element to update
html - HTML content to insert
swap - How to insert the content (innerHTML, outerHTML, etc.)
oob - Array of out-of-band updates for other elements

WSXOOBUpdate

Interface for out-of-band updates.

interface WSXOOBUpdate {
  target: string; // CSS selector
  html: string; // HTML content
  swap?: string; // Swap method
}

Properties:

target - CSS selector for the element to update
html - HTML content to insert
swap - How to insert the content

WSXConnection

Interface representing a WebSocket connection.

interface WSXConnection {
  id: string; // Unique connection ID
  sessionData?: Record<string, any>; // Session data
  send(data: string): void; // Send data to client
  close(): void; // Close connection
}

Properties:

id - Unique identifier for the connection
sessionData - Object for storing session-specific data
send() - Method to send data to the client
close() - Method to close the connection

WSXHandler

Type definition for handler functions.

type WSXHandler = (
  request: WSXRequest,
  connection: WSXConnection
) => Promise<WSXResponse | WSXResponse[] | void>;

Parameters:

request - The incoming request
connection - The connection that sent the request

Returns: Promise that resolves to:

WSXResponse - Single response
WSXResponse[] - Array of responses
void - No response (useful for side effects only)

WSXBinaryData

Union type representing allowed binary payloads.

type WSXBinaryData = ArrayBuffer | ArrayBufferView;

WSXJSONMessage

Structure passed to JSON handlers and received on the client.

interface WSXJSONMessage {
  id: string;
  channel: string;
  data: any;
  metadata?: Record<string, any>;
}

WSXJSONHandler

Type definition for JSON message handlers.

type WSXJSONHandler = (
  message: WSXJSONMessage,
  connection: WSXConnection
) => Promise<void> | void;

WSXJSONSendOptions

Optional options when sending JSON messages.

interface WSXJSONSendOptions {
  id?: string;
  metadata?: Record<string, any>;
}

WSXStreamMessage

Metadata describing a binary stream frame.

interface WSXStreamMessage {
  id: string;
  channel: string;
  metadata?: Record<string, any>;
}

WSXStreamHandler

Type definition for stream handlers.

type WSXStreamHandler = (
  message: WSXStreamMessage,
  data: Uint8Array,
  connection: WSXConnection
) => Promise<void> | void;

WSXStreamSendOptions

Optional options when sending binary stream frames.

interface WSXStreamSendOptions {
  id?: string;
  metadata?: Record<string, any>;
}

WSXServerAdapter

Interface that framework adapters must implement.

interface WSXServerAdapter {
  setupWebSocket(
    path: string,
    onMessage: (data: string, connection: WSXConnection) => void
  ): void;
  onConnection?(connection: WSXConnection): void;
  onDisconnection?(connection: WSXConnection): void;
  getApp(): any;
}

Methods:

setupWebSocket() - Set up WebSocket handling
onConnection() - Optional connection handler
onDisconnection() - Optional disconnection handler
getApp() - Return the framework app instance

Error Handling

WSX provides built-in error handling, but you can customize it:

wsx.on("error-prone-handler", async (request, connection) => {
  try {
    // Your logic here
    return {
      id: request.id,
      target: request.target,
      html: "<div>Success</div>",
    };
  } catch (error) {
    console.error("Handler error:", error);
    return {
      id: request.id,
      target: request.target,
      html: '<div class="error">Something went wrong</div>',
    };
  }
});

Best Practices

Handler Organization

// Group related handlers
const userHandlers = {
  async updateUser(request, connection) {
    // Update user logic
  },

  async deleteUser(request, connection) {
    // Delete user logic
  },
};

// Register handlers
Object.entries(userHandlers).forEach(([name, handler]) => {
  wsx.on(name, handler);
});

Connection Management

// Track user sessions
const userSessions = new Map();

wsx.on("login", async (request, connection) => {
  const userId = request.data.userId;
  userSessions.set(connection.id, userId);
  connection.sessionData = { userId };

  return {
    id: request.id,
    target: request.target,
    html: "<div>Logged in successfully</div>",
  };
});

Broadcasting Patterns

// Broadcast to specific users
function broadcastToUser(userId, target, html) {
  const connections = wsx.getConnections();
  connections
    .filter((conn) => conn.sessionData?.userId === userId)
    .forEach((conn) => {
      wsx.sendToConnection(conn.id, target, html);
    });
}

// Broadcast to all except sender
function broadcastExcept(senderId, target, html) {
  const connections = wsx.getConnections();
  connections
    .filter((conn) => conn.id !== senderId)
    .forEach((conn) => {
      wsx.sendToConnection(conn.id, target, html);
    });
}

Next Steps

Client API

Learn about the client-side API

Type Definitions

Complete TypeScript type definitions

Examples

See real-world usage examples

Advanced Usage

Advanced patterns and optimization

API Reference

​WSXServer

​Constructor

​Methods

​on()

​onJson()

​onStream()

​broadcast()

​broadcastJson()

​broadcastStream()

​sendToConnection()

​sendJsonToConnection()

​sendStreamToConnection()

​getConnections()

​getConnectionCount()

​removeConnection()

​getApp()

​WSXRequest

​WSXResponse

​WSXOOBUpdate

​WSXConnection

​WSXHandler

​WSXBinaryData

​WSXJSONMessage

​WSXJSONHandler

​WSXJSONSendOptions

​WSXStreamMessage

​WSXStreamHandler

​WSXStreamSendOptions

​WSXServerAdapter

​Error Handling

​Best Practices

​Handler Organization

​Connection Management

​Broadcasting Patterns

​Next Steps

Client API

Type Definitions

Examples

Advanced Usage

WSXServer

Constructor

Methods

on()

onJson()

onStream()

broadcast()

broadcastJson()

broadcastStream()

sendToConnection()

sendJsonToConnection()

sendStreamToConnection()

getConnections()

getConnectionCount()

removeConnection()

getApp()

WSXRequest

WSXResponse

WSXOOBUpdate

WSXConnection

WSXHandler

WSXBinaryData

WSXJSONMessage

WSXJSONHandler

WSXJSONSendOptions

WSXStreamMessage

WSXStreamHandler

WSXStreamSendOptions

WSXServerAdapter

Error Handling

Best Practices

Handler Organization

Connection Management

Broadcasting Patterns

Next Steps