> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsx.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Client API Reference

> Complete reference for WSX client-side API

# Client API Reference

The WSX client provides a JavaScript API for interacting with WSX servers, sending requests, and handling responses.

## WSX Client Class

### Constructor

```javascript theme={null}
const wsx = new WSX(options)
```

#### Parameters

* `options` (Object): Configuration options
  * `url` (string): WebSocket server URL
  * `autoConnect` (boolean): Auto-connect on instantiation (default: `true`)
  * `reconnect` (boolean): Auto-reconnect on connection loss (default: `true`)
  * `reconnectInterval` (number): Reconnection interval in ms (default: `3000`)
  * `maxReconnectAttempts` (number): Maximum reconnection attempts (default: `10`)
  * `debug` (boolean): Enable debug logging (default: `false`)

#### Example

```javascript theme={null}
const wsx = new WSX({
  url: 'ws://localhost:3000/ws',
  autoConnect: true,
  reconnect: true,
  reconnectInterval: 3000,
  maxReconnectAttempts: 10,
  debug: false
});
```

## Connection Methods

### connect()

Establishes a WebSocket connection to the server.

```javascript theme={null}
wsx.connect()
```

#### Returns

* `Promise<void>`: Resolves when connection is established

#### Example

```javascript theme={null}
try {
  await wsx.connect();
  console.log('Connected to WSX server');
} catch (error) {
  console.error('Connection failed:', error);
}
```

### disconnect()

Closes the WebSocket connection.

```javascript theme={null}
wsx.disconnect()
```

#### Example

```javascript theme={null}
wsx.disconnect();
```

### isConnected()

Checks if the client is currently connected.

```javascript theme={null}
wsx.isConnected()
```

#### Returns

* `boolean`: `true` if connected, `false` otherwise

#### Example

```javascript theme={null}
if (wsx.isConnected()) {
  console.log('Client is connected');
}
```

## Request Methods

### send()

Sends a request to the server.

```javascript theme={null}
wsx.send(handler, target, data, options)
```

#### Parameters

* `handler` (string): Handler name on the server
* `target` (string): CSS selector for the target element
* `data` (Object): Data to send with the request (optional)
* `options` (Object): Request options (optional)
  * `swap` (string): How to swap the response content
  * `trigger` (string): Trigger information
  * `timeout` (number): Request timeout in ms

#### Returns

* `Promise<WSXResponse>`: Promise that resolves with the server response

#### Example

```javascript theme={null}
try {
  const response = await wsx.send('get-user', '#user-info', { userId: 123 });
  console.log('Response received:', response);
} catch (error) {
  console.error('Request failed:', error);
}
```

### sendForm()

Sends form data to the server.

```javascript theme={null}
wsx.sendForm(handler, target, formElement, options)
```

#### Parameters

* `handler` (string): Handler name on the server
* `target` (string): CSS selector for the target element
* `formElement` (HTMLFormElement): Form element to serialize
* `options` (Object): Request options (optional)

#### Returns

* `Promise<WSXResponse>`: Promise that resolves with the server response

#### Example

```javascript theme={null}
const form = document.getElementById('userForm');
try {
  const response = await wsx.sendForm('submit-user', '#result', form);
  console.log('Form submitted:', response);
} catch (error) {
  console.error('Form submission failed:', error);
}
```

### sendFile()

Sends a file to the server.

```javascript theme={null}
wsx.sendFile(handler, target, file, options)
```

#### Parameters

* `handler` (string): Handler name on the server
* `target` (string): CSS selector for the target element
* `file` (File): File to upload
* `options` (Object): Request options (optional)
  * `onProgress` (Function): Progress callback function

#### Returns

* `Promise<WSXResponse>`: Promise that resolves with the server response

#### Example

```javascript theme={null}
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];

try {
  const response = await wsx.sendFile('upload-file', '#upload-result', file, {
    onProgress: (progress) => {
      console.log(`Upload progress: ${progress}%`);
    }
  });
  console.log('File uploaded:', response);
} catch (error) {
  console.error('File upload failed:', error);
}
```

## Data Channel Methods

### sendJson()

Send a JSON payload to the server on a named channel.

```javascript theme={null}
wsx.sendJson(channel, data, options?)
```

#### Parameters

* `channel` (string): Logical channel name shared with the server
* `data` (\*): JSON-serializable payload
* `options` (Object, optional): Additional options
  * `id` (string): Explicit message identifier
  * `metadata` (Object): Extra metadata forwarded untouched

#### Returns

* `string`: Identifier assigned to the message

#### Example

```javascript theme={null}
const messageId = wsx.sendJson('presence', { status: 'online' }, {
  metadata: { since: Date.now() },
});
```

### onJson()

Register a handler for JSON messages. Accepts either a channel/handler pair or a catch-all handler.

```javascript theme={null}
wsx.onJson(channel, handler)
wsx.onJson(handler)
```

#### Parameters

* `channel` (string|function): Channel to listen on, or the handler for catch-all usage
* `handler` (function, optional): Callback receiving `{ id, channel, data, metadata }`

#### Returns

* `WSX`: The client instance for chaining

#### Example

```javascript theme={null}
wsx.onJson('presence', ({ data }) => {
  console.log('Presence update', data);
});

wsx.onJson((message) => {
  console.log('JSON =>', message.channel, message.data);
});
```

### offJson()

Remove JSON handlers.

```javascript theme={null}
wsx.offJson(channel?)
```

#### Parameters

* `channel` (string, optional): Channel to remove; omit to clear all JSON handlers

#### Returns

* `WSX`: The client instance

#### Example

```javascript theme={null}
wsx.offJson('presence');
wsx.offJson(); // Remove every JSON handler
```

### sendStream()

Send a binary payload to the server on a named stream channel.

```javascript theme={null}
await wsx.sendStream(channel, payload, options?)
```

#### Parameters

* `channel` (string): Stream channel name
* `payload` (ArrayBuffer|ArrayBufferView|Blob): Binary data to transmit
* `options` (Object, optional): Additional options
  * `id` (string): Explicit stream identifier
  * `metadata` (Object): Metadata forwarded with the frame

#### Returns

* `Promise<string>`: Resolves with the stream identifier

#### Example

```javascript theme={null}
const streamId = await wsx.sendStream('audio', microphoneChunk, {
  metadata: { mimeType: microphoneChunk.type },
});
```

### onStream()

Register a handler for incoming binary stream frames.

```javascript theme={null}
wsx.onStream(channel, handler)
wsx.onStream(handler)
```

#### Parameters

* `channel` (string|function): Channel to observe, or the catch-all handler
* `handler` (function, optional): Callback receiving `{ id, channel, metadata, data, arrayBuffer }`

#### Returns

* `WSX`: The client instance

#### Example

```javascript theme={null}
wsx.onStream('audio', ({ data, metadata }) => {
  console.log('Received audio chunk', metadata);
});
```

### offStream()

Remove stream handlers.

```javascript theme={null}
wsx.offStream(channel?)
```

#### Parameters

* `channel` (string, optional): Channel to remove; omit to clear all stream handlers

#### Returns

* `WSX`: The client instance

#### Example

```javascript theme={null}
wsx.offStream('audio');
wsx.offStream();
```

## Event Handling

### on()

Registers an event listener.

```javascript theme={null}
wsx.on(event, callback)
```

#### Parameters

* `event` (string): Event name
* `callback` (Function): Event handler function

#### Events

* `connect`: Fired when connection is established
* `disconnect`: Fired when connection is closed
* `message`: Fired when a message is received
* `error`: Fired when an error occurs
* `reconnect`: Fired when reconnection starts
* `reconnected`: Fired when reconnection succeeds

#### Example

```javascript theme={null}
wsx.on('connect', () => {
  console.log('Connected to server');
});

wsx.on('disconnect', () => {
  console.log('Disconnected from server');
});

wsx.on('error', (error) => {
  console.error('Connection error:', error);
});

wsx.on('message', (message) => {
  console.log('Message received:', message);
});
```

### off()

Removes an event listener.

```javascript theme={null}
wsx.off(event, callback)
```

#### Parameters

* `event` (string): Event name
* `callback` (Function): Event handler function to remove

#### Example

```javascript theme={null}
function handleConnect() {
  console.log('Connected');
}

wsx.on('connect', handleConnect);
wsx.off('connect', handleConnect);
```

### once()

Registers a one-time event listener.

```javascript theme={null}
wsx.once(event, callback)
```

#### Parameters

* `event` (string): Event name
* `callback` (Function): Event handler function

#### Example

```javascript theme={null}
wsx.once('connect', () => {
  console.log('Connected for the first time');
});
```

## DOM Integration

### processResponse()

Processes a server response and updates the DOM.

```javascript theme={null}
wsx.processResponse(response)
```

#### Parameters

* `response` (WSXResponse): Server response object

#### Example

```javascript theme={null}
const response = {
  id: 'req-123',
  target: '#content',
  html: '<div>New content</div>',
  swap: 'innerHTML'
};

wsx.processResponse(response);
```

### swapContent()

Swaps content in a target element.

```javascript theme={null}
wsx.swapContent(target, html, swapType)
```

#### Parameters

* `target` (string|HTMLElement): Target element or selector
* `html` (string): HTML content to swap
* `swapType` (string): How to swap the content

#### Swap Types

* `innerHTML`: Replace element's inner HTML
* `outerHTML`: Replace the entire element
* `beforebegin`: Insert before the element
* `afterbegin`: Insert as first child
* `beforeend`: Insert as last child
* `afterend`: Insert after the element

#### Example

```javascript theme={null}
wsx.swapContent('#content', '<div>New content</div>', 'innerHTML');
wsx.swapContent('#list', '<li>New item</li>', 'beforeend');
```

## Utility Methods

### generateId()

Generates a unique request ID.

```javascript theme={null}
wsx.generateId()
```

#### Returns

* `string`: Unique identifier

#### Example

```javascript theme={null}
const requestId = wsx.generateId();
console.log('Request ID:', requestId);
```

### serializeForm()

Serializes a form element to an object.

```javascript theme={null}
wsx.serializeForm(formElement)
```

#### Parameters

* `formElement` (HTMLFormElement): Form element to serialize

#### Returns

* `Object`: Serialized form data

#### Example

```javascript theme={null}
const form = document.getElementById('myForm');
const formData = wsx.serializeForm(form);
console.log('Form data:', formData);
```

### parseSelector()

Parses a CSS selector and returns element information.

```javascript theme={null}
wsx.parseSelector(selector)
```

#### Parameters

* `selector` (string): CSS selector

#### Returns

* `Object`: Parsed selector information

#### Example

```javascript theme={null}
const parsed = wsx.parseSelector('#content .item:first-child');
console.log('Parsed selector:', parsed);
```

## Configuration Methods

### setConfig()

Updates client configuration.

```javascript theme={null}
wsx.setConfig(options)
```

#### Parameters

* `options` (Object): Configuration options to update

#### Example

```javascript theme={null}
wsx.setConfig({
  debug: true,
  reconnectInterval: 5000
});
```

### getConfig()

Gets current client configuration.

```javascript theme={null}
wsx.getConfig()
```

#### Returns

* `Object`: Current configuration

#### Example

```javascript theme={null}
const config = wsx.getConfig();
console.log('Current config:', config);
```

## Request Queue Methods

### getQueueSize()

Gets the current request queue size.

```javascript theme={null}
wsx.getQueueSize()
```

#### Returns

* `number`: Number of queued requests

#### Example

```javascript theme={null}
const queueSize = wsx.getQueueSize();
console.log('Queue size:', queueSize);
```

### clearQueue()

Clears the request queue.

```javascript theme={null}
wsx.clearQueue()
```

#### Example

```javascript theme={null}
wsx.clearQueue();
```

## Static Methods

### WSX.create()

Creates a new WSX instance with default configuration.

```javascript theme={null}
WSX.create(url, options)
```

#### Parameters

* `url` (string): WebSocket server URL
* `options` (Object): Configuration options (optional)

#### Returns

* `WSX`: New WSX instance

#### Example

```javascript theme={null}
const wsx = WSX.create('ws://localhost:3000/ws', {
  debug: true
});
```

### WSX.version

Gets the WSX client version.

```javascript theme={null}
WSX.version
```

#### Returns

* `string`: Version string

#### Example

```javascript theme={null}
console.log('WSX version:', WSX.version);
```

## Error Handling

### WSXError

Base error class for WSX-related errors.

```javascript theme={null}
class WSXError extends Error {
  constructor(message, code, details)
}
```

#### Properties

* `message` (string): Error message
* `code` (string): Error code
* `details` (Object): Additional error details

#### Example

```javascript theme={null}
try {
  await wsx.send('invalid-handler', '#target');
} catch (error) {
  if (error instanceof WSXError) {
    console.error('WSX Error:', error.message);
    console.error('Error code:', error.code);
    console.error('Details:', error.details);
  }
}
```

### ConnectionError

Error thrown when connection fails.

```javascript theme={null}
class ConnectionError extends WSXError
```

### TimeoutError

Error thrown when request times out.

```javascript theme={null}
class TimeoutError extends WSXError
```

### ValidationError

Error thrown when request validation fails.

```javascript theme={null}
class ValidationError extends WSXError
```

## HTML Attributes

### wx-config

Configures WSX for a page or element.

```html theme={null}
<div wx-config='{"url": "ws://localhost:3000/ws", "debug": true}'>
  <!-- WSX-enabled content -->
</div>
```

### wx-send

Specifies the handler to call when triggered.

```html theme={null}
<button wx-send="click-handler">Click me</button>
```

### wx-target

Specifies the target element for the response.

```html theme={null}
<button wx-send="click-handler" wx-target="#result">Click me</button>
```

### wx-trigger

Specifies when to trigger the request.

```html theme={null}
<input wx-send="search" wx-target="#results" wx-trigger="keyup delay:300ms" />
```

### wx-swap

Specifies how to swap the response content.

```html theme={null}
<button wx-send="add-item" wx-target="#list" wx-swap="beforeend">Add Item</button>
```

### wx-include

Specifies what data to include with the request.

```html theme={null}
<input wx-send="validate" wx-target="#feedback" wx-include="value" />
<form wx-send="submit" wx-target="#result" wx-include="form">
  <!-- form fields -->
</form>
```

### wx-confirm

Shows a confirmation dialog before sending the request.

```html theme={null}
<button wx-send="delete-item" wx-target="#result" wx-confirm="Are you sure?">
  Delete
</button>
```

### wx-disable

Disables the element while the request is in progress.

```html theme={null}
<button wx-send="submit" wx-target="#result" wx-disable="true">
  Submit
</button>
```

### wx-indicator

Shows a loading indicator while the request is in progress.

```html theme={null}
<button wx-send="submit" wx-target="#result" wx-indicator="#loading">
  Submit
</button>
<div id="loading" style="display: none;">Loading...</div>
```

## Global Functions

### window\.wsx

Global WSX instance created automatically when WSX is initialized with HTML attributes.

#### Example

```javascript theme={null}
// Access global WSX instance
window.wsx.send('test-handler', '#target');
```

### wx()

Shorthand function for accessing the global WSX instance.

```javascript theme={null}
wx().send('test-handler', '#target');
```

## Data Channel Types

### WSXJSONOptions

Optional configuration when sending JSON messages.

```typescript theme={null}
interface WSXJSONOptions {
  id?: string;
  metadata?: Record<string, any>;
}
```

### WSXStreamOptions

Optional configuration for binary stream frames.

```typescript theme={null}
interface WSXStreamOptions {
  id?: string;
  metadata?: Record<string, any>;
}
```

### WSXJSONDetail

Structure delivered to JSON handlers and DOM events.

```typescript theme={null}
interface WSXJSONDetail {
  id: string;
  channel: string;
  data: any;
  metadata: Record<string, any>;
}
```

### WSXStreamDetail

Structure delivered to stream handlers and DOM events.

```typescript theme={null}
interface WSXStreamDetail {
  id: string;
  channel: string;
  metadata: Record<string, any>;
  data: Uint8Array;
  arrayBuffer: ArrayBuffer;
}
```

## Best Practices

1. **Error Handling**: Always wrap WSX calls in try-catch blocks
2. **Event Cleanup**: Remove event listeners when no longer needed
3. **Connection Management**: Handle connection state changes appropriately
4. **Request Queuing**: Monitor queue size to prevent memory issues
5. **Performance**: Use appropriate swap types for optimal DOM updates
6. **Security**: Validate and sanitize all data before sending
7. **Accessibility**: Ensure dynamic content updates are accessible

## Browser Compatibility

WSX client supports:

* Chrome 60+
* Firefox 55+
* Safari 11+
* Edge 79+

For older browsers, consider using polyfills for:

* WebSocket
* Promise
* fetch API

## Next Steps

* Learn about [Type Definitions](/api-reference/types) for TypeScript support
* Explore [Performance Optimization](/advanced/performance) for client-side optimization
* Understand [Security Best Practices](/advanced/security) for secure client implementation