Handlers

Handlers are the core mechanism for processing WebSocket requests in WSX. They define how your server responds to different types of client interactions.

Handler Basics

Handler Function Signature

All handlers follow the same signature:

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

Registering Handlers

import { html } from "@wsx-sh/core";

// Named handler
wsx.on("button-click", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: html`<div>Button clicked!</div>`,
  };
});

// Default handler (catches all events)
wsx.on(async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: html`<div>Default response</div>`,
  };
});

Request Object

WSXRequest Properties

interface WSXRequest {
  id: string; // Unique request identifier
  handler: string; // Handler name (from wx-send)
  target: string; // Target selector (from wx-target)
  trigger: string; // Trigger event (click, submit, etc.)
  data?: Record<string, any>; // Form data or custom data
  swap?: string; // Swap specification
}

Accessing Request Data

wsx.on("search", async (request, connection) => {
  const query = request.data?.query || "";
  const page = request.data?.page || 1;

  // Process search...
  return {
    id: request.id,
    target: request.target,
    html: `<div>Results for: ${query}</div>`,
  };
});

Response Object

WSXResponse Properties

interface WSXResponse {
  id: string; // Must match request.id
  target: string; // CSS selector for target element
  html: string; // HTML content to swap
  swap?: string; // How to swap content
  oob?: WSXOOBUpdate[]; // Out-of-band updates
}

Basic Response

wsx.on("update-content", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>Updated at ${new Date().toLocaleTimeString()}</div>`,
  };
});

Handler Types

JSON Channel Handlers

Use wsx.onJson() to react to structured payloads that are broadcast or targeted to your server. JSON handlers receive a message envelope with id, channel, data, and optional metadata.

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

Stream Handlers

Binary streams are ideal for audio, video, or other raw payloads. Register them with wsx.onStream() and work with the supplied Uint8Array data plus metadata.

wsx.onStream('audio', async (message, data) => {
  console.log(`Frame ${message.id} -> ${data.byteLength} bytes`);
});

Paired helpers like wsx.broadcastStream() and wsx.sendStreamToConnection() mirror the HTML response workflow but operate on binary buffers.

Named Handlers

Handle specific actions by name:

wsx.on("user-login", async (request, connection) => {
  const { username, password } = request.data;
  const user = await authenticate(username, password);

  if (user) {
    connection.sessionData = { user };
    return {
      id: request.id,
      target: request.target,
      html: `<div>Welcome, ${user.name}!</div>`,
    };
  } else {
    return {
      id: request.id,
      target: request.target,
      html: `<div class="error">Invalid credentials</div>`,
    };
  }
});

Event-Based Handlers

Handle by trigger type:

wsx.on("click", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>Clicked at ${new Date().toLocaleTimeString()}</div>`,
  };
});

wsx.on("submit", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>Form submitted with data: ${JSON.stringify(
      request.data
    )}</div>`,
  };
});

Catch-All Handler

Handle all unmatched requests:

wsx.on(async (request, connection) => {
  console.log(`Unhandled request: ${request.handler}`);

  return {
    id: request.id,
    target: request.target,
    html: `<div>Handler "${request.handler}" not found</div>`,
  };
});

Advanced Handler Patterns

Conditional Logic

wsx.on("admin-action", async (request, connection) => {
  const user = connection.sessionData?.user;

  if (!user?.isAdmin) {
    return {
      id: request.id,
      target: request.target,
      html: `<div class="error">Access denied</div>`,
    };
  }

  // Admin logic here...
  return {
    id: request.id,
    target: request.target,
    html: `<div>Admin action completed</div>`,
  };
});

Async Operations

wsx.on("save-data", async (request, connection) => {
  try {
    const result = await database.save(request.data);

    return {
      id: request.id,
      target: request.target,
      html: `<div class="success">Data saved: ${result.id}</div>`,
    };
  } catch (error) {
    return {
      id: request.id,
      target: request.target,
      html: `<div class="error">Save failed: ${error.message}</div>`,
    };
  }
});

Multiple Responses

Return arrays for multiple updates:

wsx.on("complex-update", async (request, connection) => {
  const updates = await getMultipleUpdates();

  return updates.map((update) => ({
    id: request.id,
    target: update.target,
    html: update.html,
  }));
});

Handler Chaining

Middleware Pattern

// Authentication middleware
function requireAuth(handler) {
  return async (request, connection) => {
    if (!connection.sessionData?.authenticated) {
      return {
        id: request.id,
        target: request.target,
        html: `<div class="error">Authentication required</div>`,
      };
    }

    return handler(request, connection);
  };
}

// Use middleware
wsx.on(
  "protected-action",
  requireAuth(async (request, connection) => {
    return {
      id: request.id,
      target: request.target,
      html: `<div>Protected action executed</div>`,
    };
  })
);

Validation

function validateRequest(schema) {
  return (handler) => async (request, connection) => {
    const validation = schema.validate(request.data);

    if (validation.error) {
      return {
        id: request.id,
        target: request.target,
        html: `<div class="error">Validation failed: ${validation.error.message}</div>`,
      };
    }

    return handler(request, connection);
  };
}

Error Handling

Try-Catch Pattern

wsx.on("risky-operation", async (request, connection) => {
  try {
    const result = await performRiskyOperation(request.data);

    return {
      id: request.id,
      target: request.target,
      html: `<div class="success">Operation completed: ${result}</div>`,
    };
  } catch (error) {
    console.error("Risky operation failed:", error);

    return {
      id: request.id,
      target: request.target,
      html: `<div class="error">Operation failed</div>`,
    };
  }
});

Graceful Degradation

wsx.on("fallback-handler", async (request, connection) => {
  try {
    const primaryResult = await primaryService.process(request.data);
    return {
      id: request.id,
      target: request.target,
      html: `<div>Primary: ${primaryResult}</div>`,
    };
  } catch (error) {
    // Fallback to secondary service
    const fallbackResult = await fallbackService.process(request.data);
    return {
      id: request.id,
      target: request.target,
      html: `<div>Fallback: ${fallbackResult}</div>`,
    };
  }
});

Best Practices

Always Return Responses: Handlers should return a response object
Handle Errors: Use try-catch blocks for async operations
Validate Input: Check request data before processing
Use Session Data: Store connection-specific state in sessionData
Keep Handlers Focused: Each handler should handle one specific action
Log Appropriately: Log errors and important events

Next Steps

Learn about Triggers for client-side events
Explore Out-of-Band Updates for multiple element updates
Understand Swaps for content replacement strategies

Get Started

Core Concepts

Client Guide

Server Guide

Framework Integration

Handlers

Handlers

Handler Basics

Handler Function Signature

Registering Handlers

Request Object

WSXRequest Properties

Accessing Request Data

Response Object

WSXResponse Properties

Basic Response

Handler Types

JSON Channel Handlers

Stream Handlers

Named Handlers

Event-Based Handlers

Catch-All Handler

Advanced Handler Patterns

Conditional Logic

Async Operations

Multiple Responses

Handler Chaining

Middleware Pattern

Validation

Error Handling

Try-Catch Pattern

Graceful Degradation

Best Practices

Next Steps

​Handlers

​Handler Basics

​Handler Function Signature

​Registering Handlers

​Request Object

​WSXRequest Properties

​Accessing Request Data

​Response Object

​WSXResponse Properties

​Basic Response

​Handler Types

​JSON Channel Handlers

​Stream Handlers

​Named Handlers

​Event-Based Handlers

​Catch-All Handler

​Advanced Handler Patterns

​Conditional Logic

​Async Operations

​Multiple Responses

​Handler Chaining

​Middleware Pattern

​Validation

​Error Handling

​Try-Catch Pattern

​Graceful Degradation

​Best Practices

​Next Steps

Handlers

Handler Basics

Handler Function Signature

Registering Handlers

Request Object

WSXRequest Properties

Accessing Request Data

Response Object

WSXResponse Properties

Basic Response

Handler Types

JSON Channel Handlers

Stream Handlers

Named Handlers

Event-Based Handlers

Catch-All Handler

Advanced Handler Patterns

Conditional Logic

Async Operations

Multiple Responses

Handler Chaining

Middleware Pattern

Validation

Error Handling

Try-Catch Pattern

Graceful Degradation

Best Practices

Next Steps