tiny-server-essentials
Version:
A good utility toolkit to unify Express v5 and Socket.IO v4 into a seamless development experience with modular helpers, server wrappers, and WebSocket tools.
176 lines • 5.91 kB
text/typescript
export default SocketIoProxyUser;
export type ProxyUserConnection = import("../server/index.mjs").ProxyUserConnection;
/** @typedef {import('../server/index.mjs').ProxyUserConnection} ProxyUserConnection */
/**
* Represents a proxied Socket.IO user inside the architecture.
*
* This class mirrors a remote user connection received from the proxy layer and exposes
* an API very similar to a regular Socket.IO `Socket` instance, but all actions
* (emit, join, leave, broadcast, disconnect) are routed through the proxy operator.
*
* The purpose of this class is:
* - Keep an internal synchronized representation of the remote user's socket
* - Provide a safe and validated interface for broadcasting events or modifying the user's state
* - Emit local events notifying about remote room-joins, room-leaves, and metadata updates
*
* Internally, the class maintains snapshots of:
* - Rooms
* - Handshake data
* - Transport and Engine.IO details
* - Namespace information
*
* These are updated whenever the proxy sends new data.
*
* @beta
*/
declare class SocketIoProxyUser extends EventEmitter<[never]> {
/**
* Creates a new proxied user instance.
*
* @param {ProxyUserConnection} socketInfo Initial remote state snapshot
* @param {import('socket.io-client').Socket} socket Client-side operator socket
*/
constructor(socketInfo: ProxyUserConnection, socket: import("socket.io-client").Socket);
/** @returns {EventEmitter} Exposes internal user event stream */
get userConn(): EventEmitter;
/**
* Overwrites metadata with a new JSON-compatible object.
* @param {Record<string|number|symbol, any>} value
*/
set data(value: Record<string | number | symbol, any>);
/** @returns {Record<string|number|symbol, any>} Returns stored custom metadata */
get data(): Record<string | number | symbol, any>;
/**
* Returns a proxy-adjusted unique id (local socket id + remote id).
* @returns {string}
*/
get id(): string;
/** @returns {boolean} Whether the proxied user is currently connected */
get connected(): boolean;
/** @returns {boolean} Whether the proxied user is permanently disconnected */
get disconnected(): boolean;
/**
* Returns a cloned list of rooms.
* @returns {string[]}
*/
get rooms(): string[];
/**
* Returns a deep clone of Engine.IO connection details.
* @returns {{
* transport: { name: string },
* readyState: string,
* protocol: number
* }}
*/
get conn(): {
transport: {
name: string;
};
readyState: string;
protocol: number;
};
/**
* Returns a deep clone of handshake information.
* @returns {{
* headers: Object.<string, string>,
* query: Object.<string, any>,
* time: string,
* secure: boolean,
* xdomain: boolean,
* issued: number,
* url: string,
* address: string
* }}
*/
get handshake(): {
headers: {
[x: string]: string;
};
query: {
[x: string]: any;
};
time: string;
secure: boolean;
xdomain: boolean;
issued: number;
url: string;
address: string;
};
/**
* Returns a cloned namespace information object.
* @returns {{ name: string }}
*/
get nsp(): {
name: string;
};
/**
* Updates internal proxy user state and optionally emits a change event.
*
* @param {ProxyUserConnection} socketInfo Remote user state snapshot
* @param {string} [type] Optional event type to emit (e.g., "join", "leave")
* @param {string|null} [room] Room related to the update, if applicable
*/
_updateData(socketInfo: ProxyUserConnection, type?: string, room?: string | null): void;
/**
* Broadcasts an event to one or more rooms on behalf of the proxied user.
*
* This does NOT emit locally — it sends a command to the proxy.
*
* @param {string|string[]} room Target room(s)
*/
to(room: string | string[]): {
/**
* Emits a broadcast event to specified rooms through the proxy engine.
*
* @param {string} eventName
* @param {...any} args
* @returns {import('socket.io-client').Socket}
*/
emit: (eventName: string, ...args: any[]) => import("socket.io-client").Socket;
};
/**
* Emits a local event inside the proxy-user instance.
* @param {string|symbol} eventName
* @param {...any} args
*/
_emit(eventName: string | symbol, ...args: any[]): boolean;
/**
* Emits an event to the proxied user's remote socket.
*
* This does NOT emit locally — it sends a proxy-level `PROXY_EMIT`.
*
* @param {string|symbol} eventName
* @param {...any} args
* @returns {boolean} Whether the emit command was accepted
*/
emit(eventName: string | symbol, ...args: any[]): boolean;
/**
* Requests the remote user to join a room through the proxy.
*
* @param {string} room
* @returns {Promise<boolean>}
*/
join(room: string): Promise<boolean>;
/**
* Requests the remote user to leave a room through the proxy.
*
* @param {string} room
* @returns {Promise<boolean>}
*/
leave(room: string): Promise<boolean>;
/**
* Marks the proxied user as disconnected and clears local state.
* Internal use only.
*/
_disconnect(): void;
/**
* Requests the proxy to disconnect the remote user.
*
* @param {boolean} [close=false] Whether the underlying engine should also close the session
* @returns {this}
*/
disconnect(close?: boolean): this;
#private;
}
import EventEmitter from 'events';
//# sourceMappingURL=proxyUser.d.mts.map