Type Definitions

WSX provides comprehensive TypeScript type definitions for type-safe development.

Core Types

WSXRequest

Represents a request from the client to the server.

interface WSXRequest {
  id: string; // Unique request identifier
  handler: string; // Handler name to invoke
  target: string; // CSS selector for target element
  trigger?: string; // Trigger event information
  data?: Record<string, any>; // Request data payload
  swap?: string; // Content swap specification
  headers?: Record<string, string>; // Request headers
  timestamp?: number; // Request timestamp
}

Example

const request: WSXRequest = {
  id: "req-123",
  handler: "get-user",
  target: "#user-info",
  data: { userId: 123 },
  swap: "innerHTML",
};

WSXResponse

Represents a response from the server to the client.

interface WSXResponse {
  id: string; // Request ID this response belongs to
  target: string; // CSS selector for target element
  html: string; // HTML content to swap
  swap?: string; // How to swap the content
  oob?: WSXOOBUpdate[]; // Out-of-band updates
  headers?: Record<string, string>; // Response headers
  error?: string; // Error message if request failed
  timestamp?: number; // Response timestamp
}

Example

const response: WSXResponse = {
  id: "req-123",
  target: "#user-info",
  html: "<div>John Doe</div>",
  swap: "innerHTML",
  oob: [
    {
      target: "#notification",
      html: "<div>User loaded</div>",
      swap: "beforeend",
    },
  ],
};

WSXOOBUpdate

Represents an out-of-band update for multiple element updates.

interface WSXOOBUpdate {
  target: string; // CSS selector for target element
  html: string; // HTML content to swap
  swap?: string; // How to swap the content
  delay?: number; // Delay before applying update (ms)
}

Example

const oobUpdate: WSXOOBUpdate = {
  target: "#sidebar",
  html: "<div>Updated sidebar</div>",
  swap: "innerHTML",
  delay: 1000,
};

WSXBinaryData

Represents binary payloads exchanged over stream channels.

type WSXBinaryData = ArrayBuffer | ArrayBufferView;

WSXJSONMessage

Represents a JSON message transferred over WSX channels.

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

WSXJSONSendOptions

Optional settings when sending JSON messages.

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

WSXStreamMessage

Metadata attached to a binary stream frame.

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

WSXStreamSendOptions

Optional settings when sending stream frames.

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

WSXConnection

Represents a WebSocket connection on the server side.

interface WSXConnection {
  id: string; // Unique connection identifier
  sessionData?: Record<string, any>; // Session storage
  send(data: string | WSXBinaryData): void; // Send data (HTML/JSON)
  close(): void; // Close connection

  // Optional properties
  request?: any; // Original HTTP request
  ip?: string; // Client IP address
  headers?: Record<string, string>; // Connection headers
  authenticated?: boolean; // Authentication status
  lastActivity?: number; // Last activity timestamp
}

Example

function handleRequest(
  request: WSXRequest,
  connection: WSXConnection
): WSXResponse {
  // Store data in session
  connection.sessionData = {
    ...connection.sessionData,
    lastRequest: request.handler,
  };

  return {
    id: request.id,
    target: request.target,
    html: `<div>Hello from ${connection.id}</div>`,
  };
}

Handler Types

WSXHandler

Type definition for request handlers.

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

Example

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

const getUserHandler: WSXHandler = async (request, connection) => {
  const { userId } = request.data;
  const user = await getUserById(userId);

  return {
    id: request.id,
    target: request.target,
    html: html`<div>${user.name}</div>`,
  };
};

WSXJSONHandler

Type definition for JSON channel handlers.

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

WSXStreamHandler

Type definition for binary stream handlers.

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

WSXErrorHandler

Type definition for error handlers.

type WSXErrorHandler = (
  error: Error,
  request?: WSXRequest,
  connection?: WSXConnection
) => WSXResponse | void;

Example

const errorHandler: WSXErrorHandler = (error, request, connection) => {
  console.error("Handler error:", error);

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

WSXMiddleware

Type definition for middleware functions.

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

Example

const authMiddleware: WSXMiddleware = async (request, connection, next) => {
  const user = connection.sessionData?.user;

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

  return await next();
};

Client Types

WSXClientOptions

Configuration options for the WSX client.

interface WSXClientOptions {
  url: string; // WebSocket server URL
  autoConnect?: boolean; // Auto-connect on instantiation
  reconnect?: boolean; // Auto-reconnect on connection loss
  reconnectInterval?: number; // Reconnection interval in ms
  maxReconnectAttempts?: number; // Maximum reconnection attempts
  debug?: boolean; // Enable debug logging
  timeout?: number; // Default request timeout
  headers?: Record<string, string>; // Default headers
  protocols?: string[]; // WebSocket protocols
}

Example

const options: WSXClientOptions = {
  url: "ws://localhost:3000/ws",
  autoConnect: true,
  reconnect: true,
  reconnectInterval: 3000,
  maxReconnectAttempts: 10,
  debug: false,
  timeout: 30000,
};

WSXSendOptions

Options for sending requests.

interface WSXSendOptions {
  swap?: string; // Content swap type
  timeout?: number; // Request timeout
  headers?: Record<string, string>; // Request headers
  confirm?: string; // Confirmation message
  indicator?: string; // Loading indicator selector
  disable?: boolean; // Disable element during request
}

Example

const sendOptions: WSXSendOptions = {
  swap: "beforeend",
  timeout: 10000,
  confirm: "Are you sure?",
  indicator: "#loading",
  disable: true,
};

WSXEventMap

Type map for WSX client events.

interface WSXEventMap {
  connect: () => void;
  disconnect: () => void;
  message: (message: any) => void;
  error: (error: Error) => void;
  reconnect: () => void;
  reconnected: () => void;
  request: (request: WSXRequest) => void;
  response: (response: WSXResponse) => void;
}

Example

wsx.on("connect", () => {
  console.log("Connected");
});

wsx.on("error", (error: Error) => {
  console.error("Error:", error);
});

Server Types

WSXServerOptions

Configuration options for the WSX server.

interface WSXServerOptions {
  path?: string; // WebSocket path
  maxConnections?: number; // Maximum concurrent connections
  maxMessageSize?: number; // Maximum message size in bytes
  pingInterval?: number; // Ping interval in ms
  pongTimeout?: number; // Pong timeout in ms
  compression?: boolean; // Enable compression
  cors?: {
    origin?: string | string[];
    credentials?: boolean;
    methods?: string[];
    headers?: string[];
  };
}

Example

const serverOptions: WSXServerOptions = {
  path: "/ws",
  maxConnections: 1000,
  maxMessageSize: 1024 * 1024, // 1MB
  pingInterval: 30000,
  pongTimeout: 10000,
  compression: true,
  cors: {
    origin: ["http://localhost:3000"],
    credentials: true,
  },
};

WSXAdapter

Interface for server adapters.

interface WSXAdapter {
  setupWebSocket(path: string, onMessage: MessageHandler): void;
  getApp(): any;
  onConnection?(connection: WSXConnection): void;
  onDisconnection?(connection: WSXConnection): void;
  onError?(error: Error, connection?: WSXConnection): void;
}

Example

class CustomAdapter implements WSXAdapter {
  setupWebSocket(path: string, onMessage: MessageHandler): void {
    // Implementation
  }

  getApp(): any {
    return this.app;
  }

  onConnection(connection: WSXConnection): void {
    console.log(`Connection ${connection.id} established`);
  }
}

MessageHandler

Type for message handling functions.

type MessageHandler = (data: string, connection: WSXConnection) => void;

Utility Types

WSXHtmlHelper

Type for the HTML template helper function.

type WSXHtmlHelper = (
  strings: TemplateStringsArray,
  ...values: any[]
) => string;

Example

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

// The html helper provides better TypeScript support
const template: string = html`
  <div class="user">
    <h2>${user.name}</h2>
    <p>${user.email}</p>
  </div>
`;

WSXSwapType

Union type for content swap types.

type WSXSwapType =
  | "innerHTML"
  | "outerHTML"
  | "beforebegin"
  | "afterbegin"
  | "beforeend"
  | "afterend"
  | "none";

Example

function swapContent(target: string, html: string, swap: WSXSwapType): void {
  const element = document.querySelector(target);
  if (!element) return;

  switch (swap) {
    case "innerHTML":
      element.innerHTML = html;
      break;
    case "outerHTML":
      element.outerHTML = html;
      break;
    // ... other cases
  }
}

WSXTriggerType

Union type for trigger types.

type WSXTriggerType =
  | "click"
  | "submit"
  | "change"
  | "input"
  | "keyup"
  | "keydown"
  | "focus"
  | "blur"
  | "load"
  | "scroll"
  | "resize"
  | "custom";

WSXRequestStatus

Union type for request statuses.

type WSXRequestStatus =
  | "pending"
  | "sent"
  | "success"
  | "error"
  | "timeout"
  | "cancelled";

Generic Types

WSXData

Generic type for request data.

type WSXData<T = any> = T extends Record<string, any> ? T : Record<string, any>;

Example

interface UserData {
  id: number;
  name: string;
  email: string;
}

const request: WSXRequest = {
  id: "req-123",
  handler: "update-user",
  target: "#user-info",
  data: { id: 1, name: "John", email: "john@example.com" } as WSXData<UserData>,
};

WSXResult

Generic type for handler results.

type WSXResult<T = any> = Promise<T> | T;

Example

const handler = async (request: WSXRequest): WSXResult<WSXResponse> => {
  const user = await fetchUser(request.data.id);

  return {
    id: request.id,
    target: request.target,
    html: `<div>${user.name}</div>`,
  };
};

Validation Types

WSXValidationRule

Type for validation rules.

interface WSXValidationRule {
  required?: boolean;
  type?: "string" | "number" | "email" | "url" | "date";
  minLength?: number;
  maxLength?: number;
  pattern?: RegExp;
  custom?: (value: any) => boolean | string;
}

Example

const validationRules: Record<string, WSXValidationRule> = {
  email: {
    required: true,
    type: "email",
    maxLength: 255,
  },
  age: {
    required: true,
    type: "number",
    custom: (value) => value >= 18 || "Must be 18 or older",
  },
};

WSXValidationResult

Type for validation results.

interface WSXValidationResult {
  valid: boolean;
  errors: Record<string, string>;
  data: Record<string, any>;
}

Authentication Types

WSXUser

Type for authenticated users.

interface WSXUser {
  id: string | number;
  username?: string;
  email?: string;
  roles?: string[];
  permissions?: string[];
  metadata?: Record<string, any>;
}

Example

const user: WSXUser = {
  id: 123,
  username: "john_doe",
  email: "john@example.com",
  roles: ["user", "admin"],
  permissions: ["read", "write", "delete"],
};

WSXAuthContext

Type for authentication context.

interface WSXAuthContext {
  user?: WSXUser;
  token?: string;
  isAuthenticated: boolean;
  login: (credentials: any) => Promise<void>;
  logout: () => Promise<void>;
  refresh: () => Promise<void>;
}

Configuration Types

WSXConfig

Type for global WSX configuration.

interface WSXConfig {
  url?: string;
  debug?: boolean;
  timeout?: number;
  retries?: number;
  headers?: Record<string, string>;
  middleware?: WSXMiddleware[];
  errorHandler?: WSXErrorHandler;
}

Module Declaration

Global Types

declare global {
  interface Window {
    wsx: WSXClient;
    wx: () => WSXClient;
  }
}

Module Exports

export {
  WSXRequest,
  WSXResponse,
  WSXOOBUpdate,
  WSXConnection,
  WSXHandler,
  WSXErrorHandler,
  WSXMiddleware,
  WSXClientOptions,
  WSXSendOptions,
  WSXEventMap,
  WSXServerOptions,
  WSXAdapter,
  MessageHandler,
  WSXHtmlHelper,
  WSXSwapType,
  WSXTriggerType,
  WSXRequestStatus,
  WSXData,
  WSXResult,
  WSXValidationRule,
  WSXValidationResult,
  WSXUser,
  WSXAuthContext,
  WSXConfig,
};

Usage Examples

Client-Side Usage

import {
  WSXClient,
  WSXClientOptions,
  WSXRequest,
  WSXResponse,
} from "@wsx-sh/client";

const options: WSXClientOptions = {
  url: "ws://localhost:3000/ws",
  debug: true,
};

const client = new WSXClient(options);

// Type-safe request
const request: WSXRequest = {
  id: client.generateId(),
  handler: "get-user",
  target: "#user-info",
  data: { userId: 123 },
};

// Send request with proper typing
client
  .send(request.handler, request.target, request.data)
  .then((response: WSXResponse) => {
    console.log("Response:", response);
  })
  .catch((error: Error) => {
    console.error("Error:", error);
  });

Server-Side Usage

import {
  WSXServer,
  WSXHandler,
  WSXRequest,
  WSXResponse,
  WSXConnection,
} from "@wsx-sh/server";
import { html } from "@wsx-sh/core";

const server = new WSXServer();

// Type-safe handler
const getUserHandler: WSXHandler = async (
  request: WSXRequest,
  connection: WSXConnection
): Promise<WSXResponse> => {
  const { userId } = request.data;

  // Type-safe session access
  const sessionUser = connection.sessionData?.user as WSXUser;

  if (!sessionUser) {
    return {
      id: request.id,
      target: request.target,
      html: html`<div class="error">Authentication required</div>`,
      error: "Not authenticated",
    };
  }

  const user = await getUserById(userId);

  return {
    id: request.id,
    target: request.target,
    html: html`<div>Welcome, ${user.name}!</div>`,
  };
};

server.on("get-user", getUserHandler);

Best Practices

Use Strict Types: Enable strict TypeScript mode for better type checking
Generic Constraints: Use generic constraints for better type inference
Interface Segregation: Keep interfaces focused and minimal
Type Guards: Use type guards for runtime type checking
Utility Types: Leverage TypeScript utility types for transformations
Documentation: Document complex types with JSDoc comments
Validation: Combine TypeScript types with runtime validation

Next Steps

Learn about Client API Reference for detailed method documentation
Explore Performance Optimization for type-safe performance patterns
Understand Security Best Practices for secure type implementations

​Type Definitions

​Core Types

​WSXRequest

​Example

​WSXResponse

​Example

​WSXOOBUpdate

​Example

​WSXBinaryData

​WSXJSONMessage

​WSXJSONSendOptions

​WSXStreamMessage

​WSXStreamSendOptions

​WSXConnection

​Example

​Handler Types

​WSXHandler

​Example

​WSXJSONHandler

​WSXStreamHandler

​WSXErrorHandler

​Example

​WSXMiddleware

​Example

​Client Types

​WSXClientOptions

​Example

​WSXSendOptions

​Example

​WSXEventMap

​Example

​Server Types

​WSXServerOptions

​Example

​WSXAdapter

​Example

​MessageHandler

​Utility Types

​WSXHtmlHelper

​Example

​WSXSwapType

​Example

​WSXTriggerType

​WSXRequestStatus

​Generic Types

​WSXData

​Example

​WSXResult

​Example

​Validation Types

​WSXValidationRule

​Example

​WSXValidationResult

​Authentication Types

​WSXUser

​Example

​WSXAuthContext

​Configuration Types

​WSXConfig

​Module Declaration

​Global Types

​Module Exports

​Usage Examples

​Client-Side Usage

​Server-Side Usage

​Best Practices

​Next Steps

Type Definitions

Core Types

WSXRequest

Example

WSXResponse

Example

WSXOOBUpdate

Example

WSXBinaryData

WSXJSONMessage

WSXJSONSendOptions

WSXStreamMessage

WSXStreamSendOptions

WSXConnection

Example

Handler Types

WSXHandler

Example

WSXJSONHandler

WSXStreamHandler

WSXErrorHandler

Example

WSXMiddleware

Example

Client Types

WSXClientOptions

Example

WSXSendOptions

Example

WSXEventMap

Example

Server Types

WSXServerOptions

Example

WSXAdapter

Example

MessageHandler

Utility Types

WSXHtmlHelper

Example

WSXSwapType

Example

WSXTriggerType

WSXRequestStatus

Generic Types

WSXData

Example

WSXResult

Example

Validation Types

WSXValidationRule

Example

WSXValidationResult

Authentication Types

WSXUser

Example

WSXAuthContext

Configuration Types

WSXConfig

Module Declaration

Global Types

Module Exports

Usage Examples

Client-Side Usage

Server-Side Usage

Best Practices

Next Steps