@syncar/server 1.0.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,3602 @@
+import * as node_https from 'node:https';
+import * as node_http from 'node:http';
+import { IncomingMessage } from 'node:http';
+import WebSocket, { ServerOptions, WebSocketServer } from 'ws';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Message identifier
+ *
+ * @remarks
+ * Unique identifier for a message. Typically a UUID or similar unique string.
+ *
+ * @example
+ * ```ts
+ * const messageId: MessageId = "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+type MessageId = string;
+/**
+ * Client identifier (e.g., WebSocket connection ID)
+ *
+ * @remarks
+ * Unique identifier for a connected client. This ID is generated when
+ * a client connects and is used to address messages to specific clients.
+ *
+ * @example
+ * ```ts
+ * const clientId: ClientId = "client_123abc"
+ * ```
+ */
+type ClientId = string;
+/**
+ * Subscriber identifier (typically client ID)
+ *
+ * @remarks
+ * Identifier for a subscriber to a channel. In most cases, this is the
+ * same as the client ID, but can be different for custom subscription models.
+ *
+ * @example
+ * ```ts
+ * const subscriberId: SubscriberId = "client_123abc"
+ * ```
+ */
+type SubscriberId = string;
+/**
+ * Channel name
+ *
+ * @remarks
+ * String identifier for a channel. Channel names starting with `__` are
+ * reserved for internal use (e.g., `__broadcast__`).
+ *
+ * @example
+ * ```ts
+ * const channelName: ChannelName = "chat"
+ * ```
+ */
+type ChannelName = string;
+/**
+ * Unix timestamp in milliseconds
+ *
+ * @remarks
+ * Standard timestamp format used throughout the server for tracking
+ * connection times, message timestamps, and other time-based events.
+ *
+ * @example
+ * ```ts
+ * const timestamp: Timestamp = Date.now()
+ * ```
+ */
+type Timestamp = number;
+/**
+ * Generic data payload for messages
+ *
+ * @remarks
+ * Type alias for the data payload in messages. Can be any type,
+ * with `unknown` as the default for type safety.
+ *
+ * @template T - The type of the data payload (default: unknown)
+ *
+ * @example
+ * ```ts
+ * const payload: DataPayload<string> = "Hello world"
+ * const complexPayload: DataPayload<{ text: string; user: string }> = {
+ *   text: "Hello",
+ *   user: "Alice"
+ * }
+ * ```
+ */
+type DataPayload<T = unknown> = T;
+/**
+ * Logger interface
+ *
+ * @remarks
+ * Interface for logging operations. Implementations can write to console,
+ * files, or external logging services. All methods accept variadic arguments
+ * for flexible logging.
+ *
+ * @example
+ * ```ts
+ * const logger: ILogger = {
+ *   debug: (msg, ...args) => console.debug('[DEBUG]', msg, ...args),
+ *   info: (msg, ...args) => console.info('[INFO]', msg, ...args),
+ *   warn: (msg, ...args) => console.warn('[WARN]', msg, ...args),
+ *   error: (msg, ...args) => console.error('[ERROR]', msg, ...args),
+ * }
+ * ```
+ *
+ * @example
+ * ### Using with pino
+ * ```ts
+ * import pino from 'pino'
+ *
+ * const logger: ILogger = pino({
+ *   level: 'info',
+ *   transport: {
+ *     target: 'pino-pretty',
+ *   },
+ * })
+ * ```
+ */
+interface ILogger {
+    /**
+     * Log a debug message
+     *
+     * @param message - The log message
+     * @param args - Additional arguments to log
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log an info message
+     *
+     * @param message - The log message
+     * @param args - Additional arguments to log
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     *
+     * @param message - The log message
+     * @param args - Additional arguments to log
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     *
+     * @param message - The log message
+     * @param args - Additional arguments to log
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * ID Generator function type
+ *
+ * @remarks
+ * Function type for generating unique client IDs from incoming HTTP requests.
+ * Can be synchronous or asynchronous, and can throw to reject connections.
+ *
+ * @param request - The incoming HTTP upgrade request
+ * @returns The generated client ID
+ *
+ * @example
+ * ```ts
+ * const generateId: IdGenerator = (request) => {
+ *   const token = request.headers.authorization?.split(' ')[1]
+ *   return extractUserIdFromToken(token)
+ * }
+ * ```
+ *
+ * @example
+ * ### Async ID generator
+ * ```ts
+ * const generateId: IdGenerator = async (request) => {
+ *   const token = request.headers.authorization?.split(' ')[1]
+ *   const user = await verifyJwt(token)
+ *   return user.id
+ * }
+ * ```
+ */
+type IdGenerator = (request: IncomingMessage) => ClientId | Promise<ClientId>;
+/**
+ * Base client connection interface
+ *
+ * @remarks
+ * Represents a connected WebSocket client with metadata about the connection.
+ * This interface is used throughout the server for client tracking and management.
+ *
+ * @property id - Unique client identifier
+ * @property connectedAt - Unix timestamp (ms) when the client connected
+ * @property lastPingAt - Unix timestamp (ms) of the last ping/pong (optional)
+ * @property socket - The raw WebSocket instance
+ *
+ * @example
+ * ```ts
+ * const client: IClientConnection = {
+ *   id: 'client_123abc',
+ *   connectedAt: 1699123456789,
+ *   lastPingAt: 1699123459999,
+ *   socket: wsSocket
+ * }
+ *
+ * console.log(`Client ${client.id} connected at ${new Date(client.connectedAt).toLocaleString()}`)
+ * ```
+ */
+interface IClientConnection {
+    /** Unique client identifier */
+    readonly id: ClientId;
+    /** Connected timestamp */
+    readonly connectedAt: Timestamp;
+    /** Last ping timestamp */
+    lastPingAt?: Timestamp;
+    /** Raw WebSocket instance */
+    readonly socket: WebSocket;
+}
+/**
+ * Message types for protocol communication
+ *
+ * @remarks
+ * Enum defining all message types supported by the Synca protocol.
+ *
+ * @example
+ * ```ts
+ * if (message.type === MessageType.DATA) {
+ *   // Handle data message
+ * } else if (message.type === MessageType.SIGNAL) {
+ *   // Handle signal message
+ * }
+ * ```
+ *
+ * @see {@link SignalType} for signal message subtypes
+ */
+declare enum MessageType {
+    /** Data message - carries application data */
+    DATA = "data",
+    /** Signal message - control message for subscriptions, pings, etc. */
+    SIGNAL = "signal",
+    /** Error message - reports errors to clients */
+    ERROR = "error",
+    /** Acknowledgment message - confirms message receipt */
+    ACK = "ack"
+}
+/**
+ * Signal types for control messages
+ *
+ * @remarks
+ * Enum defining all signal types used for protocol control operations.
+ *
+ * @example
+ * ```ts
+ * if (message.type === MessageType.SIGNAL) {
+ *   if (message.signal === SignalType.SUBSCRIBE) {
+ *     // Handle subscription
+ *   } else if (message.signal === SignalType.PING) {
+ *     // Respond with pong
+ *   }
+ * }
+ * ```
+ */
+declare enum SignalType {
+    /** Subscribe to a channel */
+    SUBSCRIBE = "subscribe",
+    /** Unsubscribe from a channel */
+    UNSUBSCRIBE = "unsubscribe",
+    /** Ping message for keep-alive */
+    PING = "ping",
+    /** Pong response to ping */
+    PONG = "pong",
+    /** Confirmation of successful subscription */
+    SUBSCRIBED = "subscribed",
+    /** Confirmation of successful unsubscription */
+    UNSUBSCRIBED = "unsubscribed"
+}
+/**
+ * Standard error codes for messages
+ *
+ * @remarks
+ * Enum defining error codes used in error messages sent to clients.
+ *
+ * @example
+ * ```ts
+ * if (message.type === MessageType.ERROR) {
+ *   const { code, message } = message.data
+ *   console.error(`Error ${code}: ${message}`)
+ * }
+ * ```
+ */
+declare enum ErrorCode {
+    /** Invalid message type */
+    INVALID_MESSAGE_TYPE = "INVALID_MESSAGE_TYPE",
+    /** Channel name missing from message */
+    MISSING_CHANNEL = "MISSING_CHANNEL",
+    /** Unknown signal type */
+    UNKNOWN_SIGNAL = "UNKNOWN_SIGNAL",
+    /** Channel not found */
+    CHANNEL_NOT_FOUND = "CHANNEL_NOT_FOUND",
+    /** Reserved channel name (starts with __) */
+    RESERVED_CHANNEL_NAME = "RESERVED_CHANNEL_NAME",
+    /** Invalid message format */
+    INVALID_MESSAGE_FORMAT = "INVALID_MESSAGE_FORMAT",
+    /** ID required but not provided */
+    ID_REQUIRED = "ID_REQUIRED",
+    /** ID already taken */
+    ID_TAKEN = "ID_TAKEN",
+    /** Invalid ID format */
+    INVALID_ID_FORMAT = "INVALID_ID_FORMAT",
+    /** Rate limit exceeded */
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+}
+/**
+ * Base message interface
+ *
+ * @remarks
+ * All messages in the Synca protocol extend this interface with
+ * common fields like ID, timestamp, and optional channel.
+ *
+ * @property id - Unique message identifier
+ * @property timestamp - Unix timestamp (ms) when message was created
+ * @property channel - Optional channel name (required for most message types)
+ *
+ * @example
+ * ```ts
+ * const baseMessage: BaseMessage = {
+ *   id: generateId(),
+ *   timestamp: Date.now(),
+ *   channel: 'chat'
+ * }
+ * ```
+ */
+interface BaseMessage {
+    /** Unique message identifier */
+    id: MessageId;
+    /** Message timestamp */
+    timestamp: Timestamp;
+    /** Channel name */
+    channel?: ChannelName;
+}
+/**
+ * Data message (typed message with channel)
+ *
+ * @remarks
+ * Carries application data from sender to channel subscribers.
+ * This is the primary message type for user-defined communication.
+ *
+ * @template T - Type of the data payload (default: unknown)
+ *
+ * @property type - Message type discriminator (always DATA)
+ * @property channel - The target channel name
+ * @property data - The message data payload
+ *
+ * @example
+ * ```ts
+ * const chatMessage: DataMessage<{ text: string; user: string }> = {
+ *   id: generateId(),
+ *   timestamp: Date.now(),
+ *   type: MessageType.DATA,
+ *   channel: 'chat',
+ *   data: {
+ *     text: 'Hello world!',
+ *     user: 'Alice'
+ *   }
+ * }
+ *
+ * // Type narrowing
+ * if (message.type === MessageType.DATA) {
+ *   console.log(`${message.data.user}: ${message.data.text}`)
+ * }
+ * ```
+ */
+interface DataMessage<T = unknown> extends BaseMessage {
+    type: MessageType.DATA;
+    channel: ChannelName;
+    /** Message payload */
+    data: T;
+}
+/**
+ * Signal message (control message)
+ *
+ * @remarks
+ * Control messages for protocol operations like subscribe/unsubscribe,
+ * ping/pong keep-alive, and subscription confirmations.
+ *
+ * @property type - Message type discriminator (always SIGNAL)
+ * @property channel - The target channel name
+ * @property signal - The signal type
+ * @property data - Optional data payload
+ *
+ * @example
+ * ### Subscribe signal
+ * ```ts
+ * const subscribeSignal: SignalMessage = {
+ *   id: generateId(),
+ *   timestamp: Date.now(),
+ *   type: MessageType.SIGNAL,
+ *   channel: 'chat',
+ *   signal: SignalType.SUBSCRIBE
+ * }
+ * ```
+ *
+ * @example
+ * ### Ping signal
+ * ```ts
+ * const pingSignal: SignalMessage = {
+ *   id: generateId(),
+ *   timestamp: Date.now(),
+ *   type: MessageType.SIGNAL,
+ *   signal: SignalType.PING
+ * }
+ * ```
+ */
+interface SignalMessage extends BaseMessage {
+    type: MessageType.SIGNAL;
+    channel: ChannelName;
+    /** Signal type */
+    signal: SignalType;
+    /** Message payload */
+    data?: DataPayload;
+}
+/**
+ * Error data structure
+ *
+ * @remarks
+ * Contains error information sent to clients when an error occurs.
+ *
+ * @property message - Human-readable error message
+ * @property code - Optional machine-readable error code
+ *
+ * @example
+ * ```ts
+ * const errorData: ErrorData = {
+ *   message: 'Channel not found',
+ *   code: ErrorCode.CHANNEL_NOT_FOUND
+ * }
+ * ```
+ */
+interface ErrorData {
+    /** Human-readable error message */
+    message: string;
+    /** Machine-readable error code */
+    code?: ErrorCode;
+    /** Additional error context */
+    [key: string]: unknown;
+}
+/**
+ * Error message
+ *
+ * @remarks
+ * Sent to clients when an error occurs during message processing.
+ *
+ * @property type - Message type discriminator (always ERROR)
+ * @property data - Error details including message and optional code
+ *
+ * @example
+ * ```ts
+ * const errorMessage: ErrorMessage = {
+ *   id: generateId(),
+ *   timestamp: Date.now(),
+ *   type: MessageType.ERROR,
+ *   data: {
+ *     message: 'Channel not found',
+ *     code: ErrorCode.CHANNEL_NOT_FOUND
+ *   }
+ * }
+ * ```
+ */
+interface ErrorMessage extends BaseMessage {
+    type: MessageType.ERROR;
+    /** Error detail */
+    data: ErrorData;
+}
+/**
+ * Acknowledgment message
+ *
+ * @remarks
+ * Confirms receipt of a message. Used for reliable messaging patterns.
+ *
+ * @property type - Message type discriminator (always ACK)
+ * @property ackMessageId - ID of the message being acknowledged
+ *
+ * @example
+ * ```ts
+ * const ackMessage: AckMessage = {
+ *   id: generateId(),
+ *   timestamp: Date.now(),
+ *   type: MessageType.ACK,
+ *   ackMessageId: 'original-message-id'
+ * }
+ * ```
+ */
+interface AckMessage extends BaseMessage {
+    type: MessageType.ACK;
+    /** Original message being acknowledged */
+    ackMessageId: MessageId;
+}
+/**
+ * Union type for all supported messages in the protocol.
+ *
+ * @remarks
+ * Discriminated union of all message types. Use type narrowing with
+ * the `type` property to access specific message fields.
+ *
+ * @template T - Type of the data payload for DataMessage (default: unknown)
+ *
+ * @example
+ * ```ts
+ * function handleMessage(message: Message) {
+ *   switch (message.type) {
+ *     case MessageType.DATA:
+ *       // message is DataMessage
+ *       console.log('Data:', message.data)
+ *       break
+ *     case MessageType.SIGNAL:
+ *       // message is SignalMessage
+ *       console.log('Signal:', message.signal)
+ *       break
+ *     case MessageType.ERROR:
+ *       // message is ErrorMessage
+ *       console.error('Error:', message.data.message)
+ *       break
+ *     case MessageType.ACK:
+ *       // message is AckMessage
+ *       console.log('Ack for:', message.ackMessageId)
+ *       break
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Type narrowing with DataMessage generic
+ * ```ts
+ * interface ChatMessage {
+ *   text: string
+ *   user: string
+ * }
+ *
+ * function isChatMessage(message: Message): message is DataMessage<ChatMessage> {
+ *   return message.type === MessageType.DATA && message.channel === 'chat'
+ * }
+ *
+ * if (isChatMessage(message)) {
+ *   console.log(`${message.data.user}: ${message.data.text}`)
+ * }
+ * ```
+ */
+type Message<T = unknown> = DataMessage<T> | SignalMessage | ErrorMessage | AckMessage;
+/**
+ * Middleware action types
+ *
+ * @remarks
+ * Defines all actions that middleware can intercept and process.
+ *
+ * @example
+ * ```ts
+ * import type { IMiddlewareAction } from '@synca/server'
+ *
+ * function handleAction(action: IMiddlewareAction) {
+ *   switch (action) {
+ *     case 'connect':
+ *       console.log('Client connecting')
+ *       break
+ *     case 'disconnect':
+ *       console.log('Client disconnecting')
+ *       break
+ *     case 'message':
+ *       console.log('Message received')
+ *       break
+ *     case 'subscribe':
+ *       console.log('Channel subscription')
+ *       break
+ *     case 'unsubscribe':
+ *       console.log('Channel unsubscription')
+ *       break
+ *   }
+ * }
+ * ```
+ */
+type IMiddlewareAction = 'connect' | 'disconnect' | 'message' | 'subscribe' | 'unsubscribe';
+/**
+ * Next function type for middleware chain continuation
+ *
+ * @remarks
+ * Function passed to middleware to continue execution to the next
+ * middleware in the chain.
+ *
+ * @example
+ * ```ts
+ * const middleware: Middleware = async (context, next) => {
+ *   // Pre-processing
+ *   console.log('Before next')
+ *
+ *   // Continue to next middleware
+ *   await next()
+ *
+ *   // Post-processing
+ *   console.log('After next')
+ * }
+ * ```
+ */
+type Next = () => Promise<void>;
+/**
+ * Middleware context interface
+ *
+ * @remarks
+ * Provides middleware functions with access to request information,
+ * state management, and control flow methods. Inspired by Hono's context pattern.
+ *
+ * @template S - Type of the state object (default: Record<string, unknown>)
+ *
+ * @property req - Request information (client, message, channel, action)
+ * @property error - Optional error object
+ * @property finalized - Whether the context has been finalized
+ * @property res - Optional response data
+ * @property var - State object for storing custom data
+ * @property get - Get a value from state by key
+ * @property set - Set a value in state by key
+ * @property reject - Reject the action with a reason (throws)
+ *
+ * @example
+ * ### Basic usage
+ * ```ts
+ * const middleware: Middleware = async (context, next) => {
+ *   console.log(`Action: ${context.req.action}`)
+ *   console.log(`Client: ${context.req.client?.id}`)
+ *   console.log(`Channel: ${context.req.channel}`)
+ *
+ *   await next()
+ * }
+ * ```
+ *
+ * @example
+ * ### Using state
+ * ```ts
+ * interface MyState {
+ *   user: { id: string; email: string }
+ *   requestId: string
+ * }
+ *
+ * const middleware: Middleware<MyState> = async (context, next) => {
+ *   // Set state
+ *   context.set('requestId', generateId())
+ *
+ *   // Get state
+ *   const requestId = context.get('requestId')
+ *
+ *   await next()
+ * }
+ * ```
+ *
+ * @example
+ * ### Rejecting actions
+ * ```ts
+ * const middleware: Middleware = async (context, next) => {
+ *   if (context.req.action === 'connect') {
+ *     // Check connection validity
+ *     if (!isValidConnection(context.req.client)) {
+ *       context.reject('Connection not allowed')
+ *       // Function never returns (throws)
+ *     }
+ *   }
+ *
+ *   await next()
+ * }
+ * ```
+ */
+interface Context<S = Record<string, unknown>> {
+    /** Request information */
+    readonly req: {
+        /** The client connection (if applicable) */
+        readonly client?: IClientConnection;
+        /** The message being processed (if applicable) */
+        readonly message?: Message;
+        /** The channel name (if applicable) */
+        readonly channel?: ChannelName;
+        /** The action being performed */
+        readonly action: IMiddlewareAction;
+    };
+    /** Optional error object */
+    error?: Error;
+    /** Whether the context has been finalized */
+    finalized: boolean;
+    /** Optional response data */
+    res?: unknown;
+    /** State object for storing custom data */
+    readonly var: S;
+    /** Get a value from state by key */
+    get<K extends keyof S>(key: K): S[K];
+    /** Set a value in state by key */
+    set<K extends keyof S>(key: K, value: S[K]): void;
+    /** Reject the action with a reason (throws) */
+    reject(reason: string): never;
+}
+/**
+ * Middleware function signature
+ *
+ * @remarks
+ * Type definition for middleware functions. Middleware can be sync or async
+ * and can return any value (though the return value is typically ignored).
+ *
+ * @template S - Type of the state object (default: Record<string, unknown>)
+ *
+ * @param c - The middleware context
+ * @param next - Function to continue to the next middleware
+ *
+ * @example
+ * ```ts
+ * import type { Middleware } from '@synca/server'
+ *
+ * const authMiddleware: Middleware = async (context, next) => {
+ *   const token = context.req.message?.data?.token
+ *
+ *   if (!token) {
+ *     context.reject('Authentication required')
+ *   }
+ *
+ *   const user = await verifyToken(token)
+ *   context.set('user', user)
+ *
+ *   await next()
+ * }
+ * ```
+ *
+ * @see {@link Context} for context interface
+ * @see {@link IMiddlewareAction} for available actions
+ */
+type Middleware<S = Record<string, unknown>> = (
+/** The middleware context */
+c: Context<S>, 
+/** Function to continue to the next middleware */
+next: Next) => void | Promise<void> | unknown;
+/**
+ * Alias for Middleware type
+ *
+ * @remarks
+ * Alias maintained for backward compatibility. Prefer using `Middleware` directly.
+ *
+ * @template S - Type of the state object (default: Record<string, unknown>)
+ */
+type IMiddleware<S = Record<string, unknown>> = Middleware<S>;
+/**
+ * Middleware rejection error interface
+ *
+ * @remarks
+ * Interface for errors thrown when middleware rejects an action using
+ * `context.reject()`. This is a standard interface - actual errors should
+ * use the `MiddlewareRejectionError` class from the errors module.
+ *
+ * @property reason - Human-readable reason for rejection
+ * @property action - The action that was rejected
+ * @property name - Fixed value 'MiddlewareRejectionError' for interface compliance
+ *
+ * @example
+ * ```ts
+ * function isRejectionError(error: unknown): error is IMiddlewareRejectionError {
+ *   return (
+ *     typeof error === 'object' &&
+ *     error !== null &&
+ *     'name' in error &&
+ *     error.name === 'MiddlewareRejectionError'
+ *   )
+ * }
+ *
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   if (isRejectionError(error)) {
+ *     console.error(`Action '${error.action}' rejected: ${error.reason}`)
+ *   }
+ * }
+ * ```
+ */
+interface IMiddlewareRejectionError {
+    /** Human-readable reason for rejection */
+    reason: string;
+    /** The action that was rejected */
+    action: string;
+    /** Fixed value 'MiddlewareRejectionError' for interface compliance */
+    name: 'MiddlewareRejectionError';
+}
+
+/**
+ * Client Registry
+ * Manages connected clients, their subscriptions, and channel instances.
+ */
+declare class ClientRegistry {
+    readonly connections: Map<ClientId, IClientConnection>;
+    private readonly subscriptions;
+    private readonly channels;
+    private readonly channelInstances;
+    readonly logger?: ILogger;
+    constructor(logger?: ILogger);
+    register(connection: IClientConnection): IClientConnection;
+    unregister(clientId: ClientId): boolean;
+    private clearSubscriptions;
+    get(clientId: ClientId): IClientConnection | undefined;
+    getAll(): IClientConnection[];
+    getCount(): number;
+    registerChannel(channel: BaseChannel<unknown>): void;
+    getChannel<T = unknown>(name: ChannelName): BaseChannel<T> | undefined;
+    removeChannel(name: ChannelName): boolean;
+    subscribe(clientId: ClientId, channel: ChannelName): boolean;
+    unsubscribe(clientId: ClientId, channel: ChannelName): boolean;
+    getSubscribers(channel: ChannelName): IClientConnection[];
+    getSubscriberCount(channel: ChannelName): number;
+    getChannels(): ChannelName[];
+    getTotalSubscriptionCount(): number;
+    isSubscribed(clientId: ClientId, channel: ChannelName): boolean;
+    getClientChannels(clientId: ClientId): Set<ChannelName>;
+    getChannelSubscribers(channel: ChannelName): Set<ClientId>;
+    clear(): void;
+}
+
+/**
+ * Config Module
+ * Single source of truth for all constant values and default configuration for the server.
+ *
+ * @module config
+ */
+/**
+ * Broadcast channel name
+ * Messages sent to this channel reach ALL connected clients
+ * No subscription required for broadcast channel
+ */
+declare const BROADCAST_CHANNEL: "__broadcast__";
+/**
+ * WebSocket close codes
+ * Based on RFC 6455 and custom codes for application-specific closures
+ */
+declare const CLOSE_CODES: {
+    /**
+     * Normal closure
+     */
+    readonly NORMAL: 1000;
+    /**
+     * Endpoint is going away
+     */
+    readonly GOING_AWAY: 1001;
+    /**
+     * Protocol error
+     */
+    readonly PROTOCOL_ERROR: 1002;
+    /**
+     * Unsupported data
+     */
+    readonly UNSUPPORTED_DATA: 1003;
+    /**
+     * No status received
+     */
+    readonly NO_STATUS: 1005;
+    /**
+     * Abnormal closure
+     */
+    readonly ABNORMAL: 1006;
+    /**
+     * Invalid frame payload data
+     */
+    readonly INVALID_PAYLOAD: 1007;
+    /**
+     * Policy violation
+     */
+    readonly POLICY_VIOLATION: 1008;
+    /**
+     * Message too big
+     */
+    readonly MESSAGE_TOO_BIG: 1009;
+    /**
+     * Missing extension
+     */
+    readonly MISSING_EXTENSION: 1010;
+    /**
+     * Internal error
+     */
+    readonly INTERNAL_ERROR: 1011;
+    /**
+     * Service restart
+     */
+    readonly SERVICE_RESTART: 1012;
+    /**
+     * Try again later
+     */
+    readonly TRY_AGAIN_LATER: 1013;
+    /**
+     * Connection rejected by middleware
+     */
+    readonly REJECTED: 4001;
+    /**
+     * Rate limit exceeded
+     */
+    readonly RATE_LIMITED: 4002;
+    /**
+     * Channel not found
+     */
+    readonly CHANNEL_NOT_FOUND: 4003;
+    /**
+     * Unauthorized
+     */
+    readonly UNAUTHORIZED: 4005;
+};
+/**
+ * Application error codes
+ * Used in error messages sent to clients
+ */
+declare const ERROR_CODES: {
+    /**
+     * Action rejected by middleware
+     */
+    readonly REJECTED: "REJECTED";
+    /**
+     * Channel name missing from message
+     */
+    readonly MISSING_CHANNEL: "MISSING_CHANNEL";
+    /**
+     * Subscribe action rejected
+     */
+    readonly SUBSCRIBE_REJECTED: "SUBSCRIBE_REJECTED";
+    /**
+     * Unsubscribe action rejected
+     */
+    readonly UNSUBSCRIBE_REJECTED: "UNSUBSCRIBE_REJECTED";
+    /**
+     * Rate limit exceeded
+     */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /**
+     * Authentication failed
+     */
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    /**
+     * Authorization failed
+     */
+    readonly NOT_AUTHORIZED: "NOT_AUTHORIZED";
+    /**
+     * Channel not allowed
+     */
+    readonly CHANNEL_NOT_ALLOWED: "CHANNEL_NOT_ALLOWED";
+    /**
+     * Invalid message format
+     */
+    readonly INVALID_MESSAGE: "INVALID_MESSAGE";
+    /**
+     * Server error
+     */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+};
+
+/**
+ * Channel state information
+ *
+ * @remarks
+ * Provides runtime information about a channel including its name,
+ * subscriber count, creation time, and last message timestamp.
+ *
+ * @property name - The channel name
+ * @property subscriberCount - Current number of subscribers
+ * @property createdAt - Unix timestamp (ms) when the channel was created
+ * @property lastMessageAt - Unix timestamp (ms) of the last published message
+ *
+ * @example
+ * ```ts
+ * const state: IChannelState = {
+ *   name: 'chat',
+ *   subscriberCount: 42,
+ *   createdAt: 1699123456789,
+ *   lastMessageAt: 1699123459999
+ * }
+ * ```
+ */
+interface IChannelState {
+    /** The channel name */
+    name: string;
+    /** Current number of subscribers */
+    subscriberCount: number;
+    /** Unix timestamp (ms) when the channel was created */
+    createdAt: number;
+    /** Unix timestamp (ms) of the last published message */
+    lastMessageAt?: number;
+}
+/**
+ * Publish options for channel messages
+ *
+ * @remarks
+ * Controls which clients receive a published message through
+ * inclusion/exclusion filtering.
+ *
+ * @property to - Optional list of client IDs to receive the message (exclusive mode)
+ * @property exclude - Optional list of client IDs to exclude from receiving the message
+ *
+ * @example
+ * ```ts
+ * // Send to specific clients only
+ * channel.publish('Hello', { to: ['client-1', 'client-2'] })
+ *
+ * // Send to all except specific clients
+ * channel.publish('Hello', { exclude: ['client-123'] })
+ *
+ * // Both options can be combined (to takes precedence)
+ * channel.publish('Hello', { to: ['client-1'], exclude: ['client-2'] })
+ * ```
+ */
+interface IPublishOptions {
+    /**
+     * Optional list of client IDs to receive the message
+     *
+     * @remarks
+     * When provided, only clients in this list will receive the message.
+     * This creates an "exclusive mode" where `exclude` is still applied
+     * as a secondary filter.
+     */
+    to?: readonly ClientId[];
+    /**
+     * Optional list of client IDs to exclude from receiving the message
+     *
+     * @remarks
+     * Clients in this list will not receive the message, even if they
+     * are subscribed to the channel. Useful for excluding the sender.
+     */
+    exclude?: readonly ClientId[];
+}
+/**
+ * Base message handler signature
+ *
+ * @remarks
+ * Type-safe handler function for processing incoming messages on a channel.
+ * Handlers receive the message data, sending client, and the original message object.
+ *
+ * @template T - Type of data expected in messages
+ *
+ * @example
+ * ```ts
+ * const handler: IMessageHandler<{ text: string }> = (data, client, message) => {
+ *   console.log(`${client.id} sent: ${data.text}`)
+ *   console.log(`Message ID: ${message.id}`)
+ * }
+ *
+ * channel.onMessage(handler)
+ * ```
+ */
+type IMessageHandler<T> = (
+/** The message data payload */
+data: T, 
+/** The client connection that sent the message */
+client: IClientConnection, 
+/** The complete message object with metadata */
+message: DataMessage<T>) => void | Promise<void>;
+
+/**
+ * Base Channel implementation
+ *
+ * @remarks
+ * Abstract base class for all channel types. Handles the complexities of
+ * chunked publishing, client filtering, and message delivery. Provides
+ * automatic chunking for large broadcasts to avoid event loop blocking.
+ *
+ * @template T - Type of data published on this channel (default: unknown)
+ * @template N - Type of the channel name (default: ChannelName)
+ *
+ * @example
+ * ```ts
+ * // Extend BaseChannel for custom channel types
+ * class CustomChannel<T> extends BaseChannel<T> {
+ *   get subscriberCount() { return 0 }
+ *   isEmpty() { return true }
+ *   getMiddlewares() { return [] }
+ *   protected getTargetClients() { return [] }
+ * }
+ * ```
+ *
+ * @see {@link BroadcastChannel} for channel that sends to all clients
+ * @see {@link MulticastChannel} for channel that sends to subscribers only
+ */
+declare abstract class BaseChannel<T = unknown, N extends ChannelName = ChannelName> {
+    /** The channel name */
+    readonly name: N;
+    /** The client registry for connection management */
+    protected readonly registry: ClientRegistry;
+    /** Number of clients to process per chunk for large broadcasts (default: 500) */
+    protected readonly chunkSize: number;
+    /**
+     * Creates a new BaseChannel instance
+     *
+     * @param name - The channel name
+     * @param registry - The client registry for connection management
+     * @param chunkSize - Number of clients to process per chunk for large broadcasts (default: 500)
+     */
+    constructor(
+    /** The channel name */
+    name: N, 
+    /** The client registry for connection management */
+    registry: ClientRegistry, 
+    /** Number of clients to process per chunk for large broadcasts (default: 500) */
+    chunkSize?: number);
+    /**
+     * Get the current subscriber count
+     *
+     * @remarks
+     * Abstract method that must be implemented by subclasses.
+     * Returns the number of clients currently receiving messages from this channel.
+     */
+    abstract get subscriberCount(): number;
+    /**
+     * Check if the channel has no subscribers
+     *
+     * @remarks
+     * Abstract method that must be implemented by subclasses.
+     * Returns `true` if the channel has no subscribers.
+     */
+    abstract isEmpty(): boolean;
+    /**
+     * Get the middleware for this channel
+     *
+     * @remarks
+     * Abstract method that must be implemented by subclasses.
+     * Returns an array of middleware functions applied to this channel.
+     */
+    abstract getMiddlewares(): IMiddleware[];
+    /**
+     * Publish data to the channel
+     *
+     * @remarks
+     * Sends the data to all target clients. If the number of clients exceeds
+     * `chunkSize`, messages are sent in chunks using `setImmediate` to avoid
+     * blocking the event loop.
+     *
+     * @param data - The data to publish
+     * @param options - Optional publish options for client filtering
+     *
+     * @example
+     * ```ts
+     * // Publish to all clients
+     * channel.publish('Hello everyone!')
+     *
+     * // Publish excluding specific clients
+     * channel.publish('Hello', { exclude: ['client-123'] })
+     *
+     * // Publish to specific clients only
+     * channel.publish('Private message', { to: ['client-1', 'client-2'] })
+     * ```
+     */
+    publish(data: T, options?: IPublishOptions): void;
+    /**
+     * Dispatch an incoming client message
+     *
+     * @remarks
+     * Called when a client sends a message to this channel.
+     * Override in subclasses to handle incoming messages.
+     * Default implementation is a no-op (e.g., BroadcastChannel doesn't receive messages).
+     *
+     * @param data - The message data
+     * @param client - The client that sent the message
+     * @param message - The complete message object
+     */
+    dispatch(_data: T, _client: IClientConnection, _message: DataMessage<T>): Promise<void>;
+    protected abstract getTargetClients(options?: IPublishOptions): ClientId[];
+    protected publishToClients(data: T, clientIds: ClientId[], options?: IPublishOptions): void;
+    protected publishInChunks(data: T, clientIds: ClientId[], options?: IPublishOptions): void;
+}
+/**
+ * Broadcast Channel - sends messages to ALL connected clients
+ *
+ * @remarks
+ * A special channel that delivers messages to every connected client,
+ * regardless of subscription. This is useful for server-wide announcements,
+ * system notifications, and global events.
+ *
+ * The broadcast channel is a singleton with the reserved name `__broadcast__`.
+ * It is automatically created when the server starts and can be accessed
+ * via `server.createBroadcast()`.
+ *
+ * @template T - Type of data to be broadcast (default: unknown)
+ *
+ * @example
+ * ### Basic broadcasting
+ * ```ts
+ * const broadcast = server.createBroadcast<string>()
+ * broadcast.publish('Server maintenance in 5 minutes')
+ * ```
+ *
+ * @example
+ * ### Broadcasting objects
+ * ```ts
+ * const alerts = server.createBroadcast<{ type: string; message: string }>()
+ * alerts.publish({ type: 'warning', message: 'High load detected' })
+ * ```
+ *
+ * @example
+ * ### Client filtering
+ * ```ts
+ * // Send to all except specific clients
+ * broadcast.publish('Admin message', { exclude: ['client-123'] })
+ *
+ * // Send to specific clients only
+ * broadcast.publish('Private message', { to: ['client-1', 'client-2'] })
+ * ```
+ *
+ * @example
+ * ### System announcements
+ * ```ts
+ * const broadcast = server.createBroadcast<string>()
+ *
+ * // Send periodic announcements
+ * setInterval(() => {
+ *   const time = new Date().toLocaleTimeString()
+ *   broadcast.publish(`Server time: ${time}`)
+ * }, 60000)
+ * ```
+ *
+ * @see {@link BROADCAST_CHANNEL} for the reserved channel name constant
+ * @see {@link MulticastChannel} for subscription-based channels
+ */
+declare class BroadcastChannel<T = unknown> extends BaseChannel<T, typeof BROADCAST_CHANNEL> {
+    /**
+     * Creates a new BroadcastChannel instance
+     *
+     * @remarks
+     * BroadcastChannel is created automatically by the server and typically
+     * accessed via `server.createBroadcast()` rather than instantiated directly.
+     *
+     * @param registry - The client registry for connection management
+     * @param chunkSize - Number of clients to process per chunk for large broadcasts (default: 500)
+     */
+    constructor(registry: ClientRegistry, chunkSize?: number);
+    /**
+     * Get all connected clients as target recipients
+     *
+     * @remarks
+     * Broadcast channel targets ALL connected clients. The `options` parameter
+     * is still applied after this method returns for filtering.
+     *
+     * @param _options - Publish options (ignored for broadcast target selection)
+     * @returns Array of all connected client IDs
+     *
+     * @internal
+     */
+    protected getTargetClients(_options?: IPublishOptions): ClientId[];
+    /**
+     * Get the number of connected clients
+     *
+     * @returns The total number of connected clients
+     *
+     * @example
+     * ```ts
+     * const broadcast = server.createBroadcast<string>()
+     * console.log(`Connected clients: ${broadcast.subscriberCount}`)
+     * ```
+     */
+    get subscriberCount(): number;
+    /**
+     * Check if there are no connected clients
+     *
+     * @returns `true` if no clients are connected, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * const broadcast = server.createBroadcast<string>()
+     * if (broadcast.isEmpty()) {
+     *   console.log('No clients connected')
+     * }
+     * ```
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the middleware for this channel
+     *
+     * @remarks
+     * Broadcast channel has no middleware by default. Returns an empty array.
+     *
+     * @returns Empty array (broadcast channels don't have middleware)
+     */
+    getMiddlewares(): IMiddleware[];
+}
+/**
+ * Multicast channel options
+ *
+ * @remarks
+ * Configuration options for creating a multicast channel.
+ *
+ * @property chunkSize - Number of clients to process per chunk for large broadcasts
+ *
+ * @example
+ * ```ts
+ * const chat = server.createMulticast('chat', { chunkSize: 1000 })
+ * ```
+ */
+interface MulticastChannelOptions {
+    /**
+     * Number of clients to process per chunk for large broadcasts
+     *
+     * @remarks
+     * When broadcasting to more than this many subscribers, messages are sent
+     * in chunks to avoid blocking the event loop.
+     *
+     * @default 500
+     */
+    chunkSize?: number;
+}
+/**
+ * Multicast Channel - sends messages to subscribed clients only
+ *
+ * @remarks
+ * A topic-based channel that delivers messages only to clients that have
+ * explicitly subscribed. This is the standard channel type for implementing
+ * chat rooms, notifications, and other subscription-based messaging patterns.
+ *
+ * Key features:
+ * - Clients must subscribe to receive messages
+ * - Supports message handlers for intercepting incoming messages
+ * - Auto-relays messages to all subscribers (excluding sender) when no handler is set
+ * - Supports per-channel middleware
+ *
+ * @template T - Type of data published on this channel (default: unknown)
+ *
+ * @example
+ * ### Creating a channel
+ * ```ts
+ * const chat = server.createMulticast<{ text: string; user: string }>('chat')
+ * ```
+ *
+ * @example
+ * ### Publishing messages
+ * ```ts
+ * // Publish to all subscribers
+ * chat.publish({ text: 'Hello everyone!', user: 'Alice' })
+ *
+ * // Publish excluding sender
+ * chat.publish({ text: 'Welcome!', user: 'System' }, { exclude: ['client-123'] })
+ *
+ * // Publish to specific subscribers only
+ * chat.publish({ text: 'Private message', user: 'Bob' }, { to: ['client-1'] })
+ * ```
+ *
+ * @example
+ * ### Handling incoming messages with auto-relay
+ * ```ts
+ * // When no handler is set, messages are auto-relayed to all subscribers (excluding sender)
+ * // This is the default behavior for simple chat rooms
+ * ```
+ *
+ * @example
+ * ### Handling incoming messages with custom handler
+ * ```ts
+ * chat.onMessage((data, client) => {
+ *   console.log(`${data.user} (${client.id}): ${data.text}`)
+ *
+ *   // Apply custom logic (filtering, transformation, persistence, etc.)
+ *   if (isProfane(data.text)) {
+ *     return // Don't relay
+ *   }
+ *
+ *   // Manually publish to subscribers
+ *   chat.publish(data, { exclude: [client.id] })
+ * })
+ * ```
+ *
+ * @example
+ * ### Managing subscriptions
+ * ```ts
+ * // Subscribe a client
+ * chat.subscribe('client-123')
+ *
+ * // Unsubscribe a client
+ * chat.unsubscribe('client-123')
+ *
+ * // Check if subscribed
+ * if (chat.hasSubscriber('client-123')) {
+ *   console.log('Client is subscribed')
+ * }
+ *
+ * // Get all subscribers
+ * const subscribers = chat.getSubscribers()
+ * console.log(`Subscribers: ${Array.from(subscribers).join(', ')}`)
+ * ```
+ *
+ * @example
+ * ### Channel middleware
+ * ```ts
+ * chat.use(async (context, next) => {
+ *   if (context.req.action === 'message') {
+ *     // Filter profanity
+ *     const data = context.req.message?.data as { text: string }
+ *     if (data?.text && isProfane(data.text)) {
+ *       context.reject('Profanity is not allowed')
+ *     }
+ *   }
+ *   await next()
+ * })
+ * ```
+ *
+ * @see {@link BroadcastChannel} for broadcasting to all clients
+ */
+declare class MulticastChannel<T = unknown> extends BaseChannel<T> {
+    private readonly middlewares;
+    private readonly messageHandlers;
+    /**
+     * Creates a new MulticastChannel instance
+     *
+     * @remarks
+     * MulticastChannel is typically created via `server.createMulticast()`
+     * rather than instantiated directly.
+     *
+     * @param config.name - The channel name (must not start with `__`)
+     * @param config.registry - The client registry for connection management
+     * @param config.options - Optional channel configuration
+     *
+     * @throws {ValidationError} If the channel name is invalid (starts with `__`)
+     */
+    constructor(config: {
+        /** The channel name (must not start with `__`) */
+        name: ChannelName;
+        /** The client registry for connection management */
+        registry: ClientRegistry;
+        /** Optional channel configuration */
+        options?: MulticastChannelOptions;
+    });
+    /**
+     * Get all subscribed clients as target recipients
+     *
+     * @remarks
+     * Only clients that have subscribed to this channel will receive messages.
+     * The `options` parameter is still applied after this method returns for filtering.
+     *
+     * @param _options - Publish options (ignored for multicast target selection)
+     * @returns Array of subscribed client IDs
+     *
+     * @internal
+     */
+    protected getTargetClients(_options?: IPublishOptions): ClientId[];
+    /**
+     * Register a channel-specific middleware
+     *
+     * @remarks
+     * Adds a middleware function that runs for all actions on this channel,
+     * after global middleware. Channel middleware is useful for channel-specific
+     * validation, filtering, or enrichment.
+     *
+     * @param middleware - The middleware function to register
+     *
+     * @example
+     * ```ts
+     * chat.use(async (context, next) => {
+     *   if (context.req.action === 'message') {
+     *     const data = context.req.message?.data as { text: string }
+     *     if (data?.text && isProfane(data.text)) {
+     *       context.reject('Profanity is not allowed')
+     *     }
+     *   }
+     *   await next()
+     * })
+     * ```
+     *
+     * @see {@link IMiddleware} for middleware interface
+     */
+    use(middleware: IMiddleware): void;
+    /**
+     * Get the middleware for this channel
+     *
+     * @returns Array of middleware functions registered on this channel
+     */
+    getMiddlewares(): IMiddleware[];
+    /**
+     * Get the number of subscribers
+     *
+     * @returns The number of clients subscribed to this channel
+     *
+     * @example
+     * ```ts
+     * console.log(`Chat subscribers: ${chat.subscriberCount}`)
+     * ```
+     */
+    get subscriberCount(): number;
+    /**
+     * Register a message handler for incoming messages
+     *
+     * @remarks
+     * Registers a handler that intercepts incoming messages to this channel.
+     * When handlers are registered, they receive full control over message
+     * processing - auto-relay is disabled.
+     *
+     * @param handler - The message handler function
+     * @returns Unsubscribe function that removes the handler when called
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = chat.onMessage((data, client) => {
+     *   console.log(`${client.id}: ${data.text}`)
+     *   // Custom processing logic
+     * })
+     *
+     * // Later, remove the handler
+     * unsubscribe()
+     * ```
+     *
+     * @remarks
+     * Multiple handlers can be registered. They will be executed in the order
+     * they were registered. If any handler throws an error, it will be logged
+     * but other handlers will still execute.
+     */
+    onMessage(handler: IMessageHandler<T>): () => void;
+    /**
+     * Subscribe a client to this channel
+     *
+     * @remarks
+     * Subscribes a client to receive messages from this channel.
+     * This is typically called automatically when a client sends a
+     * subscribe signal, but can also be called manually.
+     *
+     * @param subscriber - The subscriber (client) ID to subscribe
+     * @returns `true` if subscription was successful, `false` if already subscribed
+     *
+     * @example
+     * ```ts
+     * chat.subscribe('client-123')
+     *
+     * if (chat.subscribe('client-456')) {
+     *   console.log('Subscribed successfully')
+     * }
+     * ```
+     */
+    subscribe(subscriber: SubscriberId): boolean;
+    /**
+     * Unsubscribe a client from this channel
+     *
+     * @remarks
+     * Removes a client's subscription from this channel.
+     * This is typically called automatically when a client sends an
+     * unsubscribe signal or disconnects, but can also be called manually.
+     *
+     * @param subscriber - The subscriber (client) ID to unsubscribe
+     * @returns `true` if unsubscription was successful, `false` if not subscribed
+     *
+     * @example
+     * ```ts
+     * chat.unsubscribe('client-123')
+     *
+     * if (chat.unsubscribe('client-456')) {
+     *   console.log('Unsubscribed successfully')
+     * }
+     * ```
+     */
+    unsubscribe(subscriber: SubscriberId): boolean;
+    /**
+     * Dispatch an incoming client message
+     *
+     * @remarks
+     * Processes incoming messages from clients. The behavior depends on
+     * whether message handlers are registered:
+     *
+     * - **With handlers**: All registered handlers are executed with full
+     *   control over the message. No auto-relay occurs.
+     *
+     * - **Without handlers**: The message is automatically relayed to all
+     *   subscribers except the sender.
+     *
+     * @param data - The message data payload
+     * @param client - The client that sent the message
+     * @param message - The complete message object
+     *
+     * @example
+     * ### Auto-relay mode (no handler)
+     * ```ts
+     * // Client sends message → automatically relayed to all subscribers
+     * // No need to call publish()
+     * ```
+     *
+     * @example
+     * ### Intercept mode (with handler)
+     * ```ts
+     * chat.onMessage((data, client) => {
+     *   // Full control - implement custom logic
+     *   if (isValidMessage(data)) {
+     *     chat.publish(data, { exclude: [client.id] })
+     *   }
+     * })
+     * ```
+     *
+     * @internal
+     */
+    dispatch(data: T, client: IClientConnection, message: DataMessage<T>): Promise<void>;
+    /**
+     * Check if a client is subscribed to this channel
+     *
+     * @param subscriber - The subscriber (client) ID to check
+     * @returns `true` if the client is subscribed, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * if (chat.hasSubscriber('client-123')) {
+     *   console.log('Client is subscribed to chat')
+     * }
+     * ```
+     */
+    hasSubscriber(subscriber: SubscriberId): boolean;
+    /**
+     * Get all subscribers to this channel
+     *
+     * @remarks
+     * Returns a copy of the subscribers set to prevent external modification.
+     * The returned set is a snapshot and may not reflect future changes.
+     *
+     * @returns A Set of subscriber IDs
+     *
+     * @example
+     * ```ts
+     * const subscribers = chat.getSubscribers()
+     * console.log(`Subscribers: ${Array.from(subscribers).join(', ')}`)
+     *
+     * // Check if a specific client is subscribed
+     * if (subscribers.has('client-123')) {
+     *   console.log('Client 123 is subscribed')
+     * }
+     * ```
+     */
+    getSubscribers(): Set<SubscriberId>;
+    /**
+     * Check if the channel has no subscribers
+     *
+     * @returns `true` if no clients are subscribed, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * if (chat.isEmpty()) {
+     *   console.log('No one is in the chat')
+     * }
+     * ```
+     */
+    isEmpty(): boolean;
+}
+
+type ServerInstance = WebSocketServer;
+/**
+ * WebSocket Server Transport Configuration
+ *
+ * @remarks
+ * Configuration options for the WebSocket transport layer. Extends the
+ * standard `ws` library options with Synca-specific settings.
+ *
+ * @example
+ * ```ts
+ * const config: WebSocketServerTransportConfig = {
+ *   server: httpServer,
+ *   path: '/ws',
+ *   enablePing: true,
+ *   pingInterval: 30000,
+ *   pingTimeout: 5000,
+ *   maxPayload: 1048576,
+ *   connections: new Map(),
+ *   generateId: (request) => extractUserId(request),
+ *   logger: console
+ * }
+ * ```
+ */
+interface WebSocketServerTransportConfig extends ServerOptions {
+    /**
+     * Enable client ping/pong
+     *
+     * @remarks
+     * When enabled, the server sends periodic ping frames to detect
+     * dead connections and maintain keep-alive.
+     *
+     * @default true
+     */
+    enablePing?: boolean;
+    /**
+     * Ping interval in milliseconds
+     *
+     * @remarks
+     * Time between ping frames when `enablePing` is true.
+     *
+     * @default 30000 (30 seconds)
+     */
+    pingInterval?: number;
+    /**
+     * Ping timeout in milliseconds
+     *
+     * @remarks
+     * Time to wait for pong response before closing connection.
+     *
+     * @default 5000 (5 seconds)
+     */
+    pingTimeout?: number;
+    /**
+     * Shared connection map
+     *
+     * @remarks
+     * Optional map for sharing connections across multiple server instances.
+     * If not provided, a new map will be created.
+     */
+    connections?: Map<ClientId, IClientConnection>;
+    /**
+     * Custom ID generator for new connections
+     *
+     * @remarks
+     * Function to generate unique client IDs from incoming HTTP requests.
+     * Useful for implementing custom authentication or ID generation strategies.
+     *
+     * @example
+     * ```ts
+     * generateId: async (request) => {
+     *   const token = request.headers.authorization?.split(' ')[1]
+     *   return verifyToken(token).then(user => user.id)
+     * }
+     * ```
+     */
+    generateId?: IdGenerator;
+    /**
+     * Custom WebSocket Server constructor
+     *
+     * @remarks
+     * Allows using a custom WebSocket server implementation.
+     * Defaults to the standard `ws` WebSocketServer.
+     */
+    ServerConstructor?: new (config: ServerOptions) => ServerInstance;
+    /**
+     * Logger instance
+     *
+     * @remarks
+     * Optional logger for transport-level logging.
+     */
+    logger?: ILogger;
+}
+/**
+ * WebSocket Server Transport
+ *
+ * @remarks
+ * Handles low-level WebSocket communication using the `ws` library.
+ * Manages connections, message parsing, ping/pong keep-alive, and
+ * emits high-level events for the server to consume.
+ *
+ * This transport:
+ * - Wraps the `ws` WebSocketServer
+ * - Generates unique client IDs
+ * - Handles connection lifecycle (connect, disconnect, error)
+ * - Parses incoming messages as JSON
+ * - Manages ping/pong for connection health
+ * - Emits typed events for server consumption
+ *
+ * @example
+ * ### Basic usage
+ * ```ts
+ * import { WebSocketServerTransport } from '@synca/server'
+ *
+ * const transport = new WebSocketServerTransport({
+ *   server: httpServer,
+ *   path: '/ws',
+ *   enablePing: true,
+ *   pingInterval: 30000,
+ *   pingTimeout: 5000
+ * })
+ *
+ * transport.on('connection', (client) => {
+ *   console.log(`Client connected: ${client.id}`)
+ * })
+ *
+ * transport.on('message', (clientId, message) => {
+ *   console.log(`Message from ${clientId}:`, message)
+ * })
+ *
+ * transport.on('disconnection', (clientId) => {
+ *   console.log(`Client disconnected: ${clientId}`)
+ * })
+ * ```
+ *
+ * @example
+ * ### With custom ID generator
+ * ```ts
+ * const transport = new WebSocketServerTransport({
+ *   server: httpServer,
+ *   generateId: async (request) => {
+ *     const token = request.headers.authorization?.split(' ')[1]
+ *     const user = await verifyJwt(token)
+ *     return user.id
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ### With shared connections
+ * ```ts
+ * const sharedConnections = new Map()
+ *
+ * const transport1 = new WebSocketServerTransport({
+ *   connections: sharedConnections
+ * })
+ *
+ * const transport2 = new WebSocketServerTransport({
+ *   connections: sharedConnections
+ * })
+ * ```
+ *
+ * @see {@link EventEmitter} for event methods (on, off, emit, etc.)
+ */
+declare class WebSocketServerTransport extends EventEmitter {
+    /**
+     * Map of connected clients by ID
+     *
+     * @remarks
+     * Public map of all active connections. Can be used to look up clients
+     * by ID or iterate over all connections.
+     */
+    readonly connections: Map<ClientId, IClientConnection>;
+    /** @internal */
+    private readonly wsServer;
+    /** @internal */
+    private readonly config;
+    /** @internal */
+    private pingTimer?;
+    /** @internal */
+    private authenticator?;
+    /**
+     * Creates a new WebSocket Server Transport instance
+     *
+     * @remarks
+     * Initializes the WebSocket transport layer with the provided configuration.
+     * Sets up the underlying WebSocketServer, configures ping/pong, and
+     * establishes event handlers.
+     *
+     * @param config - Transport configuration options
+     *
+     * @example
+     * ```ts
+     * const transport = new WebSocketServerTransport({
+     *   server: httpServer,
+     *   path: '/ws',
+     *   enablePing: true,
+     *   pingInterval: 30000,
+     *   pingTimeout: 5000
+     * })
+     * ```
+     *
+     * @emits connection When a new client connects
+     * @emits disconnection When a client disconnects
+     * @emits message When a message is received from a client
+     * @emits error When an error occurs
+     */
+    constructor(config: WebSocketServerTransportConfig);
+    /**
+     * Set a custom authentication handler
+     *
+     * @remarks
+     * Sets an authenticator function that receives the HTTP upgrade request
+     * and returns a client ID. The authenticator can throw to reject the connection.
+     *
+     * @param authenticator - Function that receives the HTTP upgrade request
+     * and returns a client ID (or throws to reject)
+     *
+     * @example
+     * ```ts
+     * transport.setAuthenticator(async (request) => {
+     *   const token = request.headers.authorization?.split(' ')[1]
+     *   if (!token) {
+     *     throw new Error('No token provided')
+     *   }
+     *   const user = await verifyJwt(token)
+     *   return user.id
+     * })
+     * ```
+     */
+    setAuthenticator(authenticator: (request: node_http.IncomingMessage) => string | Promise<string>): void;
+    private setupEventHandlers;
+    private handleConnection;
+    private handleMessage;
+    private handleDisconnection;
+    private setupPingPong;
+    private startPingTimer;
+    private checkConnections;
+}
+
+/**
+ * Server statistics interface
+ *
+ * @remarks
+ * Provides real-time statistics about the server state including
+ * connected clients, active channels, and total subscriptions.
+ *
+ * @property clientCount - Number of currently connected clients
+ * @property channelCount - Number of active channels
+ * @property subscriptionCount - Total number of channel subscriptions across all channels
+ * @property startedAt - Unix timestamp (ms) when the server was started
+ *
+ * @example
+ * ```ts
+ * const server = createSyncaServer({ port: 3000 })
+ * await server.start()
+ *
+ * const stats = server.getStats()
+ * console.log(`Clients: ${stats.clientCount}`)
+ * console.log(`Channels: ${stats.channelCount}`)
+ * console.log(`Started at: ${new Date(stats.startedAt!).toLocaleString()}`)
+ * ```
+ */
+interface IServerStats {
+    /** Number of currently connected clients */
+    clientCount: number;
+    /** Number of active channels */
+    channelCount: number;
+    /** Total number of channel subscriptions across all channels */
+    subscriptionCount: number;
+    /** Unix timestamp (ms) when the server was started */
+    startedAt?: number;
+}
+
+/**
+ * Server configuration options
+ *
+ * @remarks
+ * Complete configuration interface for the Synca server. These options
+ * control the WebSocket transport layer, connection handling, middleware,
+ * and performance tuning parameters.
+ *
+ * @example
+ * ```ts
+ * import { createSyncaServer } from '@synca/server'
+ *
+ * const server = createSyncaServer({
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   path: '/ws',
+ *   enablePing: true,
+ *   pingInterval: 30000,
+ *   pingTimeout: 5000,
+ *   broadcastChunkSize: 500,
+ * })
+ * ```
+ *
+ * @see {@link DEFAULT_SERVER_CONFIG} for default values
+ */
+interface IServerOptions {
+    /**
+     * HTTP or HTTPS server instance
+     *
+     * @remarks
+     * If provided, the WebSocket server will attach to this existing server.
+     * If not provided, a new HTTP server will be created automatically.
+     */
+    server?: node_http.Server | node_https.Server;
+    /**
+     * Custom connection ID generator
+     *
+     * @remarks
+     * Function to generate unique client IDs from incoming HTTP requests.
+     * Useful for implementing custom authentication or ID generation strategies.
+     *
+     * @example
+     * ```ts
+     * generateId: (request) => {
+     *   const token = request.headers.authorization?.split(' ')[1]
+     *   return extractUserIdFromToken(token)
+     * }
+     * ```
+     */
+    generateId?: IdGenerator;
+    /**
+     * Custom logger instance
+     *
+     * @remarks
+     * Logger conforming to the {@link ILogger} interface. Used for
+     * debugging, error reporting, and operational monitoring.
+     */
+    logger: ILogger;
+    /**
+     * Port to listen on (default: 3000)
+     *
+     * @remarks
+     * Only used when creating a new HTTP server. Ignored if `server`
+     * option is provided.
+     */
+    port: number;
+    /**
+     * Host to bind to (default: '0.0.0.0')
+     *
+     * @remarks
+     * Determines which network interface the server listens on.
+     * Use 'localhost' for local-only access or '0.0.0.0' for all interfaces.
+     */
+    host: string;
+    /**
+     * WebSocket path (default: '/synca')
+     *
+     * @remarks
+     * The URL path for WebSocket connections. Clients must connect to
+     * `ws://host:port/path` to establish a connection.
+     */
+    path: string;
+    /**
+     * Transport implementation
+     *
+     * @remarks
+     * Custom WebSocket transport layer. Defaults to {@link WebSocketServerTransport}
+     * if not provided. Allows for custom transport implementations.
+     */
+    transport: WebSocketServerTransport;
+    /**
+     * Enable automatic ping/pong (default: true)
+     *
+     * @remarks
+     * When enabled, the server sends periodic ping frames to detect
+     * dead connections and maintain keep-alive.
+     */
+    enablePing: boolean;
+    /**
+     * Ping interval in ms (default: 30000)
+     *
+     * @remarks
+     * Time between ping frames when `enablePing` is true.
+     * Lower values detect dead connections faster but increase bandwidth.
+     */
+    pingInterval: number;
+    /**
+     * Ping timeout in ms (default: 5000)
+     *
+     * @remarks
+     * Time to wait for pong response before closing connection.
+     * Should be significantly less than `pingInterval`.
+     */
+    pingTimeout: number;
+    /**
+     * Client registry instance
+     *
+     * @remarks
+     * Shared registry for tracking clients and subscriptions.
+     * Allows multiple server instances to share state.
+     */
+    registry: ClientRegistry;
+    /**
+     * Global middleware chain
+     *
+     * @remarks
+     * Middleware functions applied to all actions before channel-specific middleware.
+     * Executed in the order they are defined.
+     *
+     * @example
+     * ```ts
+     * middleware: [
+     *   createAuthMiddleware({ verifyToken }),
+     *   createLoggingMiddleware(),
+     *   createRateLimitMiddleware({ maxRequests: 100 })
+     * ]
+     * ```
+     */
+    middleware: IMiddleware[];
+    /**
+     * Chunk size for large broadcasts (default: 500)
+     *
+     * @remarks
+     * When broadcasting to more than this many clients, messages are sent
+     * in chunks to avoid blocking the event loop. Lower values reduce latency
+     * per chunk but increase total broadcast time.
+     */
+    broadcastChunkSize: number;
+}
+/**
+ * Synca Server - Real-time WebSocket server with pub/sub channels
+ *
+ * @remarks
+ * The main server class providing WebSocket communication with broadcast
+ * and multicast channels, middleware support, and connection management.
+ *
+ * @example
+ * ```ts
+ * import { createSyncaServer } from '@synca/server'
+ *
+ * const server = createSyncaServer({ port: 3000 })
+ * await server.start()
+ *
+ * // Create channels
+ * const broadcast = server.createBroadcast<string>()
+ * const chat = server.createMulticast<{ text: string }>('chat')
+ *
+ * // Listen for events
+ * server.on('connection', (client) => {
+ *   console.log(`Client connected: ${client.id}`)
+ * })
+ *
+ * // Publish messages
+ * broadcast.publish('Hello everyone!')
+ * chat.publish({ text: 'Welcome!' })
+ * ```
+ *
+ * @see {@link createSyncaServer} for factory function
+ */
+declare class SyncaServer {
+    private readonly config;
+    private transport;
+    readonly registry: ClientRegistry;
+    private readonly context;
+    private readonly status;
+    private connectionHandler;
+    private messageHandler;
+    private signalHandler;
+    private broadcastChannel;
+    constructor(config: IServerOptions);
+    /**
+     * Start the server and begin accepting connections
+     *
+     * @remarks
+     * Initializes the WebSocket transport layer, sets up event handlers,
+     * creates the broadcast channel, and prepares the server for connections.
+     *
+     * @throws {StateError} If the server is already started
+     *
+     * @example
+     * ```ts
+     * const server = createSyncaServer({ port: 3000 })
+     * await server.start()
+     * console.log('Server is running')
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server and close all connections
+     *
+     * @remarks
+     * Gracefully shuts down the server by clearing all handlers,
+     * removing all channels, and allowing the transport layer to close.
+     * Existing connections will be terminated.
+     *
+     * @example
+     * ```ts
+     * await server.stop()
+     * console.log('Server stopped')
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Get or create the broadcast channel
+     *
+     * @remarks
+     * Returns the singleton broadcast channel that sends messages to ALL
+     * connected clients. No subscription is required - all clients receive
+     * broadcast messages automatically.
+     *
+     * @template T - Type of data to be broadcast (default: unknown)
+     * @returns The broadcast channel instance
+     *
+     * @throws {StateError} If the server hasn't been started yet
+     *
+     * @example
+     * ```ts
+     * // Broadcast a string to all clients
+     * const broadcast = server.createBroadcast<string>()
+     * broadcast.publish('Server maintenance in 5 minutes')
+     *
+     * // Broadcast an object
+     * const alerts = server.createBroadcast<{ type: string; message: string }>()
+     * alerts.publish({ type: 'warning', message: 'High load detected' })
+     *
+     * // Exclude specific clients
+     * broadcast.publish('Admin message', { exclude: ['client-123'] })
+     *
+     * // Send to specific clients only
+     * broadcast.publish('Private message', { to: ['client-1', 'client-2'] })
+     * ```
+     *
+     * @see {@link BroadcastChannel} for channel API
+     */
+    createBroadcast<T = unknown>(): BroadcastChannel<T>;
+    /**
+     * Create or retrieve a multicast channel
+     *
+     * @remarks
+     * Creates a named channel that delivers messages only to subscribed clients.
+     * Clients must explicitly subscribe to receive messages. If a channel with
+     * the given name already exists, it will be returned instead of creating a new one.
+     *
+     * @template T - Type of data to be published on this channel (default: unknown)
+     * @param name - Unique channel name (must not start with `__` which is reserved)
+     * @returns The multicast channel instance
+     *
+     * @throws {StateError} If the server hasn't been started yet
+     * @throws {ValidationError} If the channel name is invalid (starts with `__`)
+     *
+     * @example
+     * ```ts
+     * // Create a chat channel
+     * const chat = server.createMulticast<{ text: string; user: string }>('chat')
+     *
+     * // Handle incoming messages
+     * chat.onMessage((data, client) => {
+     *   console.log(`${client.id}: ${data.text}`)
+     *   // Relay to all subscribers except sender
+     *   chat.publish(data, { exclude: [client.id] })
+     * })
+     *
+     * // Publish to all subscribers
+     * chat.publish({ text: 'Hello!', user: 'System' })
+     *
+     * // Check channel existence
+     * if (server.hasChannel('chat')) {
+     *   const existingChat = server.createMulticast('chat')
+     * }
+     *
+     * // Get all channel names
+     * const channels = server.getChannels()
+     * // ['chat', 'notifications', 'presence']
+     * ```
+     *
+     * @see {@link MulticastChannel} for channel API
+     * @see {@link BROADCAST_CHANNEL} for reserved channel name
+     */
+    createMulticast<T = unknown>(name: ChannelName): MulticastChannel<T>;
+    /**
+     * Check if a channel exists
+     *
+     * @param name - The channel name to check
+     * @returns `true` if a channel with this name exists, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * if (!server.hasChannel('chat')) {
+     *   const chat = server.createMulticast('chat')
+     * }
+     * ```
+     */
+    hasChannel(name: ChannelName): boolean;
+    /**
+     * Get all active channel names
+     *
+     * @returns Array of channel names currently registered on the server
+     *
+     * @example
+     * ```ts
+     * const channels = server.getChannels()
+     * console.log('Active channels:', channels)
+     * // ['chat', 'notifications', 'presence']
+     * ```
+     */
+    getChannels(): ChannelName[];
+    /**
+     * Register a global middleware
+     *
+     * @remarks
+     * Adds a middleware function to the global middleware chain.
+     * Global middleware runs before channel-specific middleware for all actions.
+     *
+     * @param middleware - The middleware function to register
+     *
+     * @example
+     * ```ts
+     * import { createAuthMiddleware } from '@synca/server'
+     *
+     * server.use(createAuthMiddleware({
+     *   verifyToken: async (token) => jwt.verify(token, SECRET)
+     * }))
+     * ```
+     *
+     * @see {@link IMiddleware} for middleware interface
+     */
+    use(middleware: IMiddleware): void;
+    /**
+     * Set a custom authentication handler for connection validation
+     *
+     * @remarks
+     * Sets an authenticator function that receives the HTTP upgrade request
+     * and returns a client ID. The authenticator can throw to reject the connection.
+     * This is useful for implementing token-based authentication during the
+     * WebSocket handshake.
+     *
+     * @param authenticator - A function that receives the HTTP upgrade request
+     * and returns a ClientId (or throws to reject the connection)
+     *
+     * @example
+     * ```ts
+     * server.authenticate(async (request) => {
+     *   const token = request.headers.authorization?.split(' ')[1]
+     *   if (!token) {
+     *     throw new Error('No token provided')
+     *   }
+     *   const user = await verifyJwt(token)
+     *   return user.id
+     * })
+     * ```
+     */
+    authenticate(authenticator: (request: node_http.IncomingMessage) => string | Promise<string>): void;
+    /**
+     * Get server statistics
+     *
+     * @returns Server statistics including client count, channel count,
+     * subscription count, and start time
+     *
+     * @example
+     * ```ts
+     * const stats = server.getStats()
+     * console.log(`Clients: ${stats.clientCount}`)
+     * console.log(`Channels: ${stats.channelCount}`)
+     * console.log(`Subscriptions: ${stats.subscriptionCount}`)
+     * console.log(`Started: ${new Date(stats.startedAt!).toLocaleString()}`)
+     * ```
+     *
+     * @see {@link IServerStats} for statistics structure
+     */
+    getStats(): IServerStats;
+    /**
+     * Get the server configuration (read-only)
+     *
+     * @returns Readonly copy of the server configuration options
+     *
+     * @example
+     * ```ts
+     * const config = server.getConfig()
+     * console.log(`Port: ${config.port}`)
+     * console.log(`Host: ${config.host}`)
+     * console.log(`Path: ${config.path}`)
+     * ```
+     */
+    getConfig(): Readonly<IServerOptions>;
+    /**
+     * Get the client registry
+     *
+     * @returns The client registry instance used by this server
+     *
+     * @remarks
+     * The registry manages client connections and channel subscriptions.
+     * Direct access allows for advanced operations like manual client
+     * lookup or subscription management.
+     *
+     * @example
+     * ```ts
+     * const registry = server.getRegistry()
+     * const client = registry.get('client-123')
+     * if (client) {
+     *   console.log(`Client connected at: ${new Date(client.connectedAt).toLocaleString()}`)
+     * }
+     * ```
+     *
+     * @see {@link ClientRegistry} for registry API
+     */
+    getRegistry(): ClientRegistry;
+    private setupTransportHandlers;
+}
+/**
+ * Create a Synca server with automatic WebSocket transport setup
+ *
+ * @remarks
+ * Factory function that creates a configured SyncaServer instance.
+ * Automatically sets up the WebSocket transport layer if not provided,
+ * merges user configuration with defaults, and creates the client registry.
+ *
+ * @param config - Optional partial server configuration. All properties are optional
+ * and will be merged with {@link DEFAULT_SERVER_CONFIG}.
+ *
+ * @returns Configured Synca server instance ready to be started
+ *
+ * @example
+ * ### Basic usage
+ * ```ts
+ * import { createSyncaServer } from '@synca/server'
+ *
+ * const server = createSyncaServer({ port: 3000 })
+ * await server.start()
+ * ```
+ *
+ * @example
+ * ### With custom configuration
+ * ```ts
+ * const server = createSyncaServer({
+ *   port: 8080,
+ *   host: 'localhost',
+ *   path: '/ws',
+ *   enablePing: true,
+ *   pingInterval: 30000,
+ *   pingTimeout: 5000,
+ *   broadcastChunkSize: 1000,
+ * })
+ * await server.start()
+ * ```
+ *
+ * @example
+ * ### With existing HTTP server
+ * ```ts
+ * import { createServer } from 'node:http'
+ * import { createSyncaServer } from '@synca/server'
+ *
+ * const httpServer = createServer((req, res) => {
+ *   res.writeHead(200)
+ *   res.end('OK')
+ * })
+ *
+ * const server = createSyncaServer({
+ *   server: httpServer,
+ *   path: '/ws',
+ * })
+ *
+ * await server.start()
+ * ```
+ *
+ * @example
+ * ### With Express
+ * ```ts
+ * import express from 'express'
+ * import { createSyncaServer } from '@synca/server'
+ *
+ * const app = express()
+ * const httpServer = app.listen(3000)
+ *
+ * const server = createSyncaServer({
+ *   server: httpServer,
+ *   path: '/ws',
+ * })
+ *
+ * await server.start()
+ * ```
+ *
+ * @example
+ * ### With custom logger
+ * ```ts
+ * import { createSyncaServer } from '@synca/server'
+ *
+ * const server = createSyncaServer({
+ *   port: 3000,
+ *   logger: {
+ *     debug: (msg, ...args) => console.debug('[DEBUG]', msg, ...args),
+ *     info: (msg, ...args) => console.info('[INFO]', msg, ...args),
+ *     warn: (msg, ...args) => console.warn('[WARN]', msg, ...args),
+ *     error: (msg, ...args) => console.error('[ERROR]', msg, ...args),
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ### With middleware
+ * ```ts
+ * import { createSyncaServer, createLoggingMiddleware } from '@synca/server'
+ *
+ * const server = createSyncaServer({
+ *   port: 3000,
+ *   middleware: [
+ *     createLoggingMiddleware(),
+ *   ],
+ * })
+ *
+ * await server.start()
+ * ```
+ *
+ * @see {@link SyncaServer} for server class API
+ * @see {@link DEFAULT_SERVER_CONFIG} for default configuration values
+ */
+declare function createSyncaServer(config?: Partial<IServerOptions>): SyncaServer;
+
+/**
+ * Middleware Factories
+ * Factory functions for creating common middleware implementations.
+ *
+ * @module middleware/factories
+ */
+
+/**
+ * Auth middleware options
+ *
+ * @example
+ * ```ts
+ * const options: AuthMiddlewareOptions = {
+ *   verifyToken: async (token) => {
+ *     const user = await verifyJwt(token)
+ *     return { id: user.id, email: user.email }
+ *   },
+ *   getToken: (context) => {
+ *     // Extract token from message or connection
+ *     return context.message?.data?.token
+ *   },
+ *   attachProperty: 'user'
+ * }
+ * ```
+ */
+interface AuthMiddlewareOptions {
+    /**
+     * Verify and decode a token
+     * Returns the user data to attach to the client
+     *
+     * @param token - The token to verify
+     * @returns User data to attach
+     * @throws Error if token is invalid
+     */
+    verifyToken: (token: string) => Promise<unknown> | unknown;
+    /**
+     * Extract token from the middleware context
+     *
+     * @param c - The middleware context
+     * @returns The token string or undefined if not found
+     */
+    getToken?: (c: Context) => string | undefined;
+    /**
+     * Property name to attach verified user data
+     * @default 'user'
+     */
+    attachProperty?: string;
+    /**
+     * Actions to require authentication
+     * @default All actions require auth
+     */
+    actions?: IMiddlewareAction[];
+}
+/**
+ * Create an authentication middleware
+ *
+ * This middleware verifies tokens and attaches user data to clients.
+ * Rejects connections that fail authentication.
+ *
+ * @param options - Authentication options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * import { createAuthMiddleware } from '@synca/server/middleware'
+ *
+ * const authMiddleware = createAuthMiddleware({
+ *   verifyToken: async (token) => {
+ *     const user = await jwt.verify(token, SECRET)
+ *     return { id: user.sub, email: user.email }
+ *   },
+ *   getToken: (context) => context.message?.data?.token,
+ *   attachProperty: 'user'
+ * })
+ *
+ * server.use(authMiddleware)
+ * ```
+ */
+declare function createAuthMiddleware(options: AuthMiddlewareOptions): IMiddleware;
+/**
+ * Logging middleware options
+ *
+ * @example
+ * ```ts
+ * const options: LoggingMiddlewareOptions = {
+ *   logger: console,
+ *   logLevel: 'info',
+ *   includeMessageData: false
+ * }
+ * ```
+ */
+interface LoggingMiddlewareOptions {
+    /**
+     * Logger instance to use
+     * @default console
+     */
+    logger?: Pick<Console, 'log' | 'info' | 'warn' | 'error'>;
+    /**
+     * Log level
+     * @default 'info'
+     */
+    logLevel?: 'log' | 'info' | 'warn' | 'error';
+    /**
+     * Whether to include message data in logs
+     * @default false
+     */
+    includeMessageData?: boolean;
+    /**
+     * Custom format function for log output
+     *
+     * @param context - The middleware context
+     * @returns Formatted log string
+     */
+    format?: (context: {
+        action: string;
+        clientId?: string;
+        channel?: string;
+        message?: unknown;
+        duration?: number;
+    }) => string;
+    /**
+     * Actions to log
+     * @default All actions are logged
+     */
+    actions?: IMiddlewareAction[];
+}
+/**
+ * Create a logging middleware
+ *
+ * Logs all middleware actions with client and action information.
+ *
+ * @param options - Logging options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * import { createLoggingMiddleware } from '@synca/server/middleware'
+ *
+ * const loggingMiddleware = createLoggingMiddleware({
+ *   logger: console,
+ *   logLevel: 'info',
+ *   includeMessageData: false
+ * })
+ *
+ * server.use(loggingMiddleware)
+ * ```
+ */
+declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): IMiddleware;
+/**
+ * Rate limit middleware options
+ *
+ * @example
+ * ```ts
+ * const options: RateLimitMiddlewareOptions = {
+ *   maxRequests: 100,
+ *   windowMs: 60000,
+ *   getMessageId: (context) => context.client?.id ?? ''
+ * }
+ * ```
+ */
+interface RateLimitMiddlewareOptions {
+    /**
+     * Maximum number of requests allowed per window
+     * @default 100
+     */
+    maxRequests?: number;
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Extract a unique identifier for rate limiting
+     * Defaults to client ID
+     *
+     * @param c - The middleware context
+     * @returns Unique identifier for rate limiting
+     */
+    getMessageId?: (c: Context) => string;
+    /**
+     * Actions to rate limit
+     * @default 'message' only
+     */
+    actions?: IMiddlewareAction[];
+}
+/**
+ * Create a rate limiting middleware
+ *
+ * Limits the rate of requests per client within a time window.
+ *
+ * @param options - Rate limit options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * import { createRateLimitMiddleware } from '@synca/server/middleware'
+ *
+ * const rateLimitMiddleware = createRateLimitMiddleware({
+ *   maxRequests: 100,
+ *   windowMs: 60000
+ * })
+ *
+ * server.use(rateLimitMiddleware)
+ * ```
+ */
+declare function createRateLimitMiddleware(options?: RateLimitMiddlewareOptions): IMiddleware;
+/**
+ * Channel whitelist middleware options
+ *
+ * @example
+ * ```ts
+ * const options: ChannelWhitelistMiddlewareOptions = {
+ *   allowedChannels: ['chat', 'notifications'],
+ *   isDynamic: false
+ * }
+ * ```
+ */
+interface ChannelWhitelistMiddlewareOptions {
+    /**
+     * List of allowed channels
+     * If isDynamic is true, this is used as a fallback
+     */
+    allowedChannels?: ChannelName[];
+    /**
+     * Dynamic check function for channel access
+     * If provided, this takes precedence over allowedChannels
+     *
+     * @param channel - The channel name to check
+     * @param client - The client attempting to access the channel
+     * @returns true if channel is allowed
+     *
+     * @example
+     * ```ts
+     * const isDynamic: (channel, client) => {
+     *   // Check if user has permission for this channel
+     *   return user.permissions.includes(channel)
+     * }
+     * ```
+     */
+    isDynamic?: (channel: ChannelName, client?: IClientConnection) => boolean;
+    /**
+     * Whether to also check unsubscribe actions
+     * @default false (only restrict subscribe)
+     */
+    restrictUnsubscribe?: boolean;
+}
+/**
+ * Create a channel whitelist middleware
+ *
+ * Restricts which channels clients can subscribe to.
+ *
+ * @param options - Channel whitelist options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * import { createChannelWhitelistMiddleware } from '@synca/server/middleware'
+ *
+ * const whitelistMiddleware = createChannelWhitelistMiddleware({
+ *   allowedChannels: ['chat', 'notifications']
+ * })
+ *
+ * server.use(whitelistMiddleware)
+ * ```
+ */
+declare function createChannelWhitelistMiddleware(options?: ChannelWhitelistMiddlewareOptions): IMiddleware;
+
+/**
+ * Context Data Options
+ *
+ * @remarks
+ * Options for creating a new middleware context with pre-populated state.
+ *
+ * @template S - Type of the state object (default: Record<string, unknown>)
+ *
+ * @property action - The middleware action being performed
+ * @property client - Optional client connection
+ * @property message - Optional message being processed
+ * @property channel - Optional channel name
+ * @property initialState - Optional initial state values
+ *
+ * @example
+ * ```ts
+ * const options: ContextOptions<{ user: UserInfo }> = {
+ *   action: 'message',
+ *   client: connection,
+ *   message: dataMessage,
+ *   channel: 'chat',
+ *   initialState: { user: { id: '123', name: 'Alice' } }
+ * }
+ * ```
+ */
+interface ContextOptions<S = Record<string, unknown>> {
+    /** The middleware action being performed */
+    action: IMiddlewareAction;
+    /** Optional client connection */
+    client?: IClientConnection;
+    /** Optional message being processed */
+    message?: Message;
+    /** Optional channel name */
+    channel?: ChannelName;
+    /** Optional initial state values */
+    initialState?: S;
+}
+/**
+ * Create a new Hono-style middleware context
+ *
+ * @remarks
+ * Creates a lightweight middleware context using closures to ensure properties
+ * can be destructured safely. The context provides access to request information,
+ * state management, and control flow methods.
+ *
+ * @template S - Type of the state object (default: Record<string, unknown>)
+ *
+ * @param options - Context initialization options
+ * @returns A new Context object
+ *
+ * @example
+ * ### Basic usage
+ * ```ts
+ * const context = createContext({
+ *   action: 'message',
+ *   client: connection,
+ *   message: dataMessage,
+ *   channel: 'chat'
+ * })
+ * ```
+ *
+ * @example
+ * ### With initial state
+ * ```ts
+ * interface AppState {
+ *   user: { id: string; name: string }
+ *   requestId: string
+ * }
+ *
+ * const context = createContext<AppState>({
+ *   action: 'message',
+ *   initialState: {
+ *     user: { id: '123', name: 'Alice' },
+ *     requestId: generateId()
+ *   }
+ * })
+ *
+ * // Access state
+ * const user = context.get('user')
+ * const requestId = context.get('requestId')
+ * ```
+ *
+ * @see {@link Context} for the context interface
+ */
+declare function createContext<S = Record<string, unknown>>(options: ContextOptions<S>): Context<S>;
+/**
+ * Context Manager - manages and executes middleware functions
+ *
+ * @remarks
+ * The ContextManager is responsible for registering middleware functions
+ * and executing them in the correct order for various actions (connect,
+ * disconnect, message, subscribe, unsubscribe).
+ *
+ * Key features:
+ * - Global middleware registration
+ * - Per-action middleware execution
+ * - Channel-specific middleware support
+ * - Automatic error wrapping and reporting
+ *
+ * @example
+ * ```ts
+ * import { ContextManager } from '@synca/server'
+ *
+ * const manager = new ContextManager()
+ *
+ * // Register middleware
+ * manager.use(async (context, next) => {
+ *   console.log(`Action: ${context.req.action}`)
+ *   await next()
+ * })
+ *
+ * // Execute middleware for an action
+ * const context = await manager.executeConnection(client, 'connect')
+ * ```
+ *
+ * @see {@link createSyncaServer} for server-level context management
+ */
+declare class ContextManager {
+    /** Registered middleware functions */
+    protected readonly middlewares: IMiddleware[];
+    /**
+     * Register a middleware function
+     *
+     * @remarks
+     * Adds a middleware function to the global middleware chain.
+     * Middleware is executed in the order it is registered.
+     *
+     * @param middleware - The middleware function to register
+     *
+     * @example
+     * ```ts
+     * manager.use(async (context, next) => {
+     *   console.log('Before')
+     *   await next()
+     *   console.log('After')
+     * })
+     * ```
+     */
+    use(middleware: IMiddleware): void;
+    /**
+     * Remove a middleware function
+     *
+     * @remarks
+     * Removes a previously registered middleware function from the chain.
+     *
+     * @param middleware - The middleware function to remove
+     * @returns `true` if the middleware was found and removed, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * const middleware = async (context, next) => { /* ... *\/ }
+     * manager.use(middleware)
+     *
+     * // Later, remove it
+     * if (manager.remove(middleware)) {
+     *   console.log('Middleware removed')
+     * }
+     * ```
+     */
+    remove(middleware: IMiddleware): boolean;
+    /**
+     * Clear all middleware
+     *
+     * @remarks
+     * Removes all registered middleware functions from the chain.
+     *
+     * @example
+     * ```ts
+     * manager.clear()
+     * console.log('All middleware cleared')
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get all registered middleware
+     *
+     * @remarks
+     * Returns a shallow copy of the middleware array to prevent
+     * external modification.
+     *
+     * @returns Array of middleware functions
+     *
+     * @example
+     * ```ts
+     * const allMiddleware = manager.getMiddlewares()
+     * console.log(`Registered middleware: ${allMiddleware.length}`)
+     * ```
+     */
+    getMiddlewares(): IMiddleware[];
+    /**
+     * Get the complete middleware pipeline
+     *
+     * @remarks
+     * Returns the combined middleware pipeline including global middleware
+     * and any channel-specific middleware from the provided channel instance.
+     *
+     * @param channelInstance - Optional channel instance with middleware
+     * @returns Combined array of middleware functions
+     *
+     * @example
+     * ```ts
+     * const chat = server.createMulticast('chat')
+     * const pipeline = manager.getPipeline(chat)
+     * // Returns global middleware + chat channel middleware
+     * ```
+     *
+     * @internal
+     */
+    getPipeline(channelInstance?: {
+        getMiddlewares?: () => IMiddleware[];
+    }): IMiddleware[];
+    /**
+     * Execute middleware for connection actions
+     *
+     * @remarks
+     * Creates a connection context and executes the middleware pipeline
+     * for connect or disconnect actions.
+     *
+     * @param client - The client connection
+     * @param action - The action ('connect' or 'disconnect')
+     * @returns The executed context
+     *
+     * @example
+     * ```ts
+     * await manager.executeConnection(client, 'connect')
+     * await manager.executeConnection(client, 'disconnect')
+     * ```
+     *
+     * @internal
+     */
+    executeConnection(client: IClientConnection, action: 'connect' | 'disconnect'): Promise<Context>;
+    /**
+     * Execute middleware for message actions
+     *
+     * @remarks
+     * Creates a message context and executes the middleware pipeline
+     * for incoming client messages.
+     *
+     * @param client - The client connection
+     * @param message - The message being processed
+     * @returns The executed context
+     *
+     * @example
+     * ```ts
+     * await manager.executeMessage(client, dataMessage)
+     * ```
+     *
+     * @internal
+     */
+    executeMessage(client: IClientConnection, message: Message): Promise<Context>;
+    /**
+     * Execute middleware for subscribe actions
+     *
+     * @remarks
+     * Creates a subscribe context and executes the middleware pipeline
+     * for channel subscription requests.
+     *
+     * @param client - The client connection
+     * @param channel - The channel name
+     * @param finalHandler - Optional final handler to execute after middleware
+     * @returns The executed context
+     *
+     * @example
+     * ```ts
+     * await manager.executeSubscribe(client, 'chat', async () => {
+     *   // Final handler - perform the actual subscription
+     *   channel.subscribe(client.id)
+     * })
+     * ```
+     *
+     * @internal
+     */
+    executeSubscribe(client: IClientConnection, channel: ChannelName, finalHandler?: () => Promise<void>): Promise<Context>;
+    /**
+     * Execute middleware for unsubscribe actions
+     *
+     * @remarks
+     * Creates an unsubscribe context and executes the middleware pipeline
+     * for channel unsubscription requests.
+     *
+     * @param client - The client connection
+     * @param channel - The channel name
+     * @param finalHandler - Optional final handler to execute after middleware
+     * @returns The executed context
+     *
+     * @example
+     * ```ts
+     * await manager.executeUnsubscribe(client, 'chat', async () => {
+     *   // Final handler - perform the actual unsubscription
+     *   channel.unsubscribe(client.id)
+     * })
+     * ```
+     *
+     * @internal
+     */
+    executeUnsubscribe(client: IClientConnection, channel: ChannelName, finalHandler?: () => Promise<void>): Promise<Context>;
+    /**
+     * Execute middleware pipeline
+     *
+     * @remarks
+     * Executes the provided middleware functions in order, wrapping
+     * each to capture and report errors appropriately.
+     *
+     * @param context - The middleware context
+     * @param middlewares - The middleware functions to execute (defaults to registered middleware)
+     * @param finalHandler - Optional final handler to execute after all middleware
+     * @returns The executed context
+     *
+     * @throws {MiddlewareExecutionError} If a middleware function throws an unexpected error
+     *
+     * @example
+     * ```ts
+     * const context = createContext({ action: 'message' })
+     * await manager.execute(context)
+     * ```
+     *
+     * @internal
+     */
+    execute(context: Context, middlewares?: IMiddleware[], finalHandler?: () => Promise<void>): Promise<Context>;
+    /**
+     * Create a connection context
+     *
+     * @remarks
+     * Creates a middleware context for connection or disconnect actions.
+     *
+     * @param client - The client connection
+     * @param action - The action ('connect' or 'disconnect')
+     * @returns A new connection context
+     *
+     * @example
+     * ```ts
+     * const context = manager.createConnectionContext(client, 'connect')
+     * ```
+     *
+     * @internal
+     */
+    createConnectionContext(client: IClientConnection, action: 'connect' | 'disconnect'): Context;
+    /**
+     * Create a message context
+     *
+     * @remarks
+     * Creates a middleware context for message processing.
+     *
+     * @param client - The client connection
+     * @param message - The message being processed
+     * @returns A new message context
+     *
+     * @example
+     * ```ts
+     * const context = manager.createMessageContext(client, dataMessage)
+     * ```
+     *
+     * @internal
+     */
+    createMessageContext(client: IClientConnection, message: Message): Context;
+    /**
+     * Create a subscribe context
+     *
+     * @remarks
+     * Creates a middleware context for channel subscription.
+     *
+     * @param client - The client connection
+     * @param channel - The channel name
+     * @returns A new subscribe context
+     *
+     * @example
+     * ```ts
+     * const context = manager.createSubscribeContext(client, 'chat')
+     * ```
+     *
+     * @internal
+     */
+    createSubscribeContext(client: IClientConnection, channel: ChannelName): Context;
+    /**
+     * Create an unsubscribe context
+     *
+     * @remarks
+     * Creates a middleware context for channel unsubscription.
+     *
+     * @param client - The client connection
+     * @param channel - The channel name
+     * @returns A new unsubscribe context
+     *
+     * @example
+     * ```ts
+     * const context = manager.createUnsubscribeContext(client, 'chat')
+     * ```
+     *
+     * @internal
+     */
+    createUnsubscribeContext(client: IClientConnection, channel: ChannelName): Context;
+    /**
+     * Get the number of registered middleware
+     *
+     * @returns The count of middleware functions
+     *
+     * @example
+     * ```ts
+     * console.log(`Middleware count: ${manager.getCount()}`)
+     * ```
+     */
+    getCount(): number;
+    /**
+     * Check if any middleware is registered
+     *
+     * @returns `true` if at least one middleware is registered, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * if (manager.hasMiddleware()) {
+     *   console.log('Middleware is configured')
+     * }
+     * ```
+     */
+    hasMiddleware(): boolean;
+}
+
+/**
+ * Errors Module
+ *
+ * @description
+ * Custom error classes for the Synca server. All errors extend from
+ * {@link SyncaError} and include error codes for programmatic handling.
+ *
+ * @remarks
+ * The error hierarchy:
+ *
+ * - {@link SyncaError} - Base error class
+ *   - {@link ConfigError} - Server configuration issues
+ *   - {@link TransportError} - WebSocket transport issues
+ *   - {@link ChannelError} - Channel operation failures
+ *   - {@link ClientError} - Client operation failures
+ *   - {@link MessageError} - Message processing failures
+ *   - {@link ValidationError} - Input validation failures
+ *   - {@link StateError} - Invalid state operations
+ * - {@link MiddlewareRejectionError} - Explicit middleware rejections
+ * - {@link MiddlewareExecutionError} - Unexpected middleware errors
+ *
+ * @example
+ * ### Throwing errors
+ * ```ts
+ * import { StateError, ValidationError } from '@synca/server'
+ *
+ * function createChannel(name: string) {
+ *   if (!name) {
+ *     throw new ValidationError('Channel name is required')
+ *   }
+ *   if (!server.started) {
+ *     throw new StateError('Server must be started first')
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Catching errors
+ * ```ts
+ * import {
+ *   SyncaError,
+ *   MiddlewareRejectionError,
+ *   StateError
+ * } from '@synca/server'
+ *
+ * try {
+ *   await server.start()
+ * } catch (error) {
+ *   if (error instanceof StateError) {
+ *     console.error('Invalid state:', error.message)
+ *   } else if (error instanceof MiddlewareRejectionError) {
+ *     console.error(`Action rejected: ${error.reason}`)
+ *   } else if (error instanceof SyncaError) {
+ *     console.error(`[${error.code}] ${error.message}`)
+ *   }
+ * }
+ * ```
+ *
+ * @module errors
+ */
+
+/**
+ * Base Synca error class
+ *
+ * @remarks
+ * All custom errors in the Synca server extend this class. Provides
+ * consistent error handling with error codes, context, and serialization.
+ *
+ * @property code - Error code for programmatic handling
+ * @property context - Optional additional error context
+ *
+ * @example
+ * ```ts
+ * throw new SyncaError('Something went wrong', 'CUSTOM_ERROR', { userId: '123' })
+ * ```
+ *
+ * @example
+ * ### Error handling
+ * ```ts
+ * try {
+ *   // ...
+ * } catch (error) {
+ *   if (error instanceof SyncaError) {
+ *     console.log(error.code)        // 'CUSTOM_ERROR'
+ *     console.log(error.message)     // 'Something went wrong'
+ *     console.log(error.context)     // { userId: '123' }
+ *     console.log(error.toJSON())    // Serialized error
+ *   }
+ * }
+ * ```
+ */
+declare class SyncaError extends Error {
+    /**
+     * Error code for programmatic error handling
+     *
+     * @remarks
+     * Machine-readable error code that can be used for conditional
+     * error handling and error response generation.
+     */
+    readonly code: string;
+    /**
+     * Additional error context (optional)
+     *
+     * @remarks
+     * Arbitrary data attached to the error for debugging or logging.
+     * Common uses include user IDs, request IDs, or validation details.
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * Creates a new SyncaError
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling (default: 'SYNNEL_ERROR')
+     * @param context - Optional additional error context
+     */
+    constructor(message: string, code?: string, context?: Record<string, unknown>);
+    /**
+     * Convert error to JSON for logging/serialization
+     *
+     * @returns JSON representation of the error
+     *
+     * @example
+     * ```ts
+     * const error = new SyncaError('Failed', 'FAIL', { id: 123 })
+     * console.log(JSON.stringify(error.toJSON(), null, 2))
+     * // {
+     * //   "name": "SyncaError",
+     * //   "message": "Failed",
+     * //   "code": "FAIL",
+     * //   "context": { "id": 123 },
+     * //   "stack": "..."
+     * // }
+     * ```
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        context?: Record<string, unknown>;
+        stack?: string;
+    };
+    /**
+     * Get a summary of the error for logging
+     *
+     * @returns Formatted error summary string
+     *
+     * @example
+     * ```ts
+     * const error = new SyncaError('Failed', 'FAIL')
+     * console.log(error.toString())
+     * // "[SyncaError:FAIL] Failed"
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Configuration error
+ *
+ * @remarks
+ * Thrown when server configuration is invalid or missing required values.
+ *
+ * @example
+ * ```ts
+ * if (!config.port) {
+ *   throw new ConfigError('Port is required', { config })
+ * }
+ * ```
+ */
+declare class ConfigError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Transport error
+ *
+ * @remarks
+ * Thrown when the transport layer fails (WebSocket connection issues, etc.).
+ *
+ * @example
+ * ```ts
+ * if (!wsServer) {
+ *   throw new TransportError('WebSocket server not initialized')
+ * }
+ * ```
+ */
+declare class TransportError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Channel error
+ *
+ * @remarks
+ * Thrown when channel operations fail (invalid channel name, etc.).
+ *
+ * @example
+ * ```ts
+ * if (channelName.startsWith('__')) {
+ *   throw new ChannelError('Reserved channel name', { channelName })
+ * }
+ * ```
+ */
+declare class ChannelError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Client error
+ *
+ * @remarks
+ * Thrown when client operations fail (client not found, etc.).
+ *
+ * @example
+ * ```ts
+ * if (!registry.has(clientId)) {
+ *   throw new ClientError('Client not found', { clientId })
+ * }
+ * ```
+ */
+declare class ClientError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Message error
+ *
+ * @remarks
+ * Thrown when message processing fails (invalid format, etc.).
+ *
+ * @example
+ * ```ts
+ * if (!message.type) {
+ *   throw new MessageError('Invalid message format', { message })
+ * }
+ * ```
+ */
+declare class MessageError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Validation error
+ *
+ * @remarks
+ * Thrown when input validation fails.
+ *
+ * @example
+ * ```ts
+ * if (!isValidChannelName(name)) {
+ *   throw new ValidationError('Invalid channel name', { name })
+ * }
+ * ```
+ */
+declare class ValidationError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * State error
+ *
+ * @remarks
+ * Thrown when an operation is invalid for the current state.
+ *
+ * @example
+ * ```ts
+ * if (server.started) {
+ *   throw new StateError('Server is already started')
+ * }
+ *
+ * if (!server.started) {
+ *   throw new StateError('Server must be started first')
+ * }
+ * ```
+ */
+declare class StateError extends SyncaError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Middleware rejection error
+ *
+ * @remarks
+ * Thrown when middleware explicitly rejects an action using the
+ * `context.reject()` function. This is an expected error type that
+ * indicates intentional rejection rather than a failure.
+ *
+ * @property reason - Human-readable reason for the rejection
+ * @property action - The action that was rejected
+ * @property code - Optional error code for programmatic handling
+ * @property context - Additional context about the rejection
+ *
+ * @example
+ * ### Throwing from middleware
+ * ```ts
+ * const middleware: Middleware = async (context, next) => {
+ *   if (!context.req.client) {
+ *     context.reject('Client is required')
+ *     // Function never returns (throws MiddlewareRejectionError)
+ *   }
+ *   await next()
+ * }
+ * ```
+ *
+ * @example
+ * ### Catching rejections
+ * ```ts
+ * try {
+ *   await manager.executeConnection(client, 'connect')
+ * } catch (error) {
+ *   if (error instanceof MiddlewareRejectionError) {
+ *     console.log(`Action '${error.action}' rejected: ${error.reason}`)
+ *     // Send error to client
+ *     client.socket.send(JSON.stringify({
+ *       type: 'error',
+ *       data: { message: error.reason, code: error.code }
+ *     }))
+ *   }
+ * }
+ * ```
+ */
+declare class MiddlewareRejectionError extends Error implements IMiddlewareRejectionError {
+    /**
+     * The reason for rejection
+     *
+     * @remarks
+     * Human-readable explanation of why the action was rejected.
+     */
+    readonly reason: string;
+    /**
+     * The action that was rejected
+     *
+     * @remarks
+     * One of: 'connect', 'disconnect', 'message', 'subscribe', 'unsubscribe'
+     */
+    readonly action: string;
+    /**
+     * Error name (fixed value for interface compliance)
+     */
+    readonly name = "MiddlewareRejectionError";
+    /**
+     * Optional error code for programmatic handling
+     *
+     * @remarks
+     * Can be used for mapping to client-facing error codes.
+     */
+    readonly code?: string;
+    /**
+     * Additional context about the rejection
+     *
+     * @remarks
+     * Arbitrary data for debugging or logging.
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * Creates a new MiddlewareRejectionError
+     *
+     * @param reason - Human-readable reason for the rejection
+     * @param action - The action that was rejected
+     * @param code - Optional error code for programmatic handling
+     * @param context - Additional context about the rejection
+     */
+    constructor(reason: string, action: IMiddlewareAction | string, code?: string, context?: Record<string, unknown>);
+    /**
+     * Convert error to JSON for logging/serialization
+     *
+     * @returns JSON representation of the rejection error
+     *
+     * @example
+     * ```ts
+     * const error = new MiddlewareRejectionError('Not allowed', 'subscribe', 'FORBIDDEN')
+     * console.log(JSON.stringify(error.toJSON(), null, 2))
+     * // {
+     * //   "name": "MiddlewareRejectionError",
+     * //   "reason": "Not allowed",
+     * //   "action": "subscribe",
+     * //   "code": "FORBIDDEN",
+     * //   "message": "Action 'subscribe' rejected: Not allowed",
+     * //   "stack": "..."
+     * // }
+     * ```
+     */
+    toJSON(): {
+        name: string;
+        reason: string;
+        action: string;
+        code?: string;
+        context?: Record<string, unknown>;
+        message: string;
+        stack?: string;
+    };
+    /**
+     * Get a summary of the rejection for logging
+     *
+     * @returns Formatted error summary string
+     *
+     * @example
+     * ```ts
+     * const error = new MiddlewareRejectionError('Not allowed', 'subscribe')
+     * console.log(error.toString())
+     * // "[MiddlewareRejectionError:subscribe] Not allowed"
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Middleware execution error
+ *
+ * @remarks
+ * Thrown when a middleware function throws an unexpected error
+ * (not using `context.reject()`). This indicates a bug or failure
+ * in the middleware rather than an intentional rejection.
+ *
+ * @property action - The action being processed when the error occurred
+ * @property middleware - The name/index of the middleware that failed
+ * @property cause - The original error thrown by the middleware
+ *
+ * @example
+ * ### Error scenario
+ * ```ts
+ * const buggyMiddleware: Middleware = async (context, next) => {
+ *   // This throws an unexpected error
+ *   JSON.parse(context.req.message as string)
+ *   await next()
+ * }
+ * // Results in MiddlewareExecutionError
+ * ```
+ *
+ * @example
+ * ### Catching execution errors
+ * ```ts
+ * try {
+ *   await manager.execute(context)
+ * } catch (error) {
+ *   if (error instanceof MiddlewareExecutionError) {
+ *     console.error(`${error.middleware} failed during ${error.action}:`)
+ *     console.error(error.cause)
+ *   }
+ * }
+ * ```
+ */
+declare class MiddlewareExecutionError extends Error {
+    /**
+     * The action being processed when the error occurred
+     */
+    readonly action: string;
+    /**
+     * The name/index of the middleware that failed
+     */
+    readonly middleware: string;
+    /**
+     * The original error thrown by the middleware
+     */
+    readonly cause: Error;
+    /**
+     * Creates a new MiddlewareExecutionError
+     *
+     * @param action - The action being processed
+     * @param middleware - The name/index of the middleware
+     * @param cause - The original error
+     */
+    constructor(action: string, middleware: string, cause: Error);
+    /**
+     * Get the original error cause
+     *
+     * @returns The original error thrown by the middleware
+     *
+     * @example
+     * ```ts
+     * if (error instanceof MiddlewareExecutionError) {
+     *   const originalError = error.getCause()
+     *   console.error('Original error:', originalError.message)
+     * }
+     * ```
+     */
+    getCause(): Error;
+    /**
+     * Get a summary of the error for logging
+     *
+     * @returns Formatted error summary string
+     *
+     * @example
+     * ```ts
+     * const error = new MiddlewareExecutionError('message', 'auth', originalError)
+     * console.log(error.toString())
+     * // "[MiddlewareExecutionError] auth failed during message: Invalid token"
+     * ```
+     */
+    toString(): string;
+}
+
+export { type AckMessage, BROADCAST_CHANNEL, BroadcastChannel, CLOSE_CODES, ChannelError, type ChannelName, ClientError, type ClientId, ConfigError, type Context, ContextManager, type DataMessage, ERROR_CODES, ErrorCode, type ErrorMessage, type IChannelState, type IClientConnection, type IMessageHandler, type IPublishOptions, type IServerOptions, type IServerStats, type Message, MessageError, type MessageId, MessageType, type Middleware, MiddlewareExecutionError, MiddlewareRejectionError, MulticastChannel, type SignalMessage, SignalType, StateError, type SubscriberId, SyncaServer as Synca, SyncaError, SyncaServer, type Timestamp, TransportError, ValidationError, WebSocketServerTransport, createAuthMiddleware, createChannelWhitelistMiddleware, createContext, createLoggingMiddleware, createRateLimitMiddleware, createSyncaServer };