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.
132 lines • 5.06 kB
text/typescript
export default SocketIoProxyClient;
export type ProxyUserDisconnect = import("../server/index.mjs").ProxyUserDisconnect;
export type ProxyUserConnection = import("../server/index.mjs").ProxyUserConnection;
export type ProxyUserConnectionUpdated = import("../server/index.mjs").ProxyUserConnectionUpdated;
export type ProxyRequest = import("../server/index.mjs").ProxyRequest;
/** @typedef {import('../server/index.mjs').ProxyUserDisconnect} ProxyUserDisconnect */
/** @typedef {import('../server/index.mjs').ProxyUserConnection} ProxyUserConnection */
/** @typedef {import('../server/index.mjs').ProxyUserConnectionUpdated} ProxyUserConnectionUpdated */
/** @typedef {import('../server/index.mjs').ProxyRequest} ProxyRequest */
/**
* SocketIoProxyClient
* -------------------
* This class acts as a high-level client wrapper for a remote Proxy Server.
*
* The proxy server forwards real Socket.IO client events (from real users) to this instance.
* Each connected user becomes a `SocketIoProxyUser`, allowing you to:
* - Listen to the user's custom events
* - Emit events back to the user
* - Detect connection, disconnection and data updates
*
* The class controls reconnection, user mapping, event routing and authentication logic.
*
* Lifecycle Summary:
* 1. `connect()` → authenticates with the proxy and starts receiving events.
* 2. Proxy notifies about users:
* - `PROXY_USER_CONNECTION`
* - `PROXY_USER_UPDATE`
* - `PROXY_USER_DISCONNECT`
* 3. Incoming user events arrive as `PROXY_REQUEST`.
* 4. You can broadcast events through `.to(room).emit()`.
*
* When destroyed, all listeners and user references are cleaned up.
*
* @beta
*/
declare class SocketIoProxyClient extends EventEmitter<[never]> {
/**
* Creates a new Proxy Client connected to a Proxy server.
*
* @param {string} proxyAddress - The URL of the proxy server.
* @param {import('socket.io-client').ManagerOptions} cfg - Socket.IO manager configuration.
*
* Configuration notes:
* - reconnection is always disabled (handled manually)
* - autoConnect is disabled; connection occurs on `.connect()`
*
* Events emitted by this class:
* - `connect` when authentication succeeds
* - `disconnect` when connection to the proxy is lost
* - `connection` when a new proxied user appears
*/
constructor(proxyAddress: string, cfg: import("socket.io-client").ManagerOptions);
/**
* Enables or disables debug logging. When enabled,
* every proxy event is logged to the console.
* @param {boolean} value
*/
set debugMode(value: boolean);
/**
* Whether debug logging is enabled.
* @returns {boolean}
*/
get debugMode(): boolean;
/**
* Returns true if the client has been destroyed and cannot be reused.
* @returns {boolean}
*/
get isDestroyed(): boolean;
/**
* The underlying raw Socket.IO client instance.
* This can be used for low-level Socket.IO operations if needed.
* @returns {import('socket.io-client').Socket}
*/
get client(): import("socket.io-client").Socket;
/**
* Sets the authentication value that will be sent when connecting
* to the proxy server through the `AUTH_PROXY` event.
* @param {null|string|number} value
*/
set auth(value: null | string | number);
/**
* True if the proxy is authenticated AND the socket is alive.
* @returns {boolean}
*/
get connected(): boolean;
/**
* Sets the reconnection attempt interval in milliseconds.
* Set to `null` to disable auto retry.
* @param {null|number} value
*/
set connTimeout(value: null | number);
/**
* Gets the reconnection attempt interval.
* @returns {null|number}
*/
get connTimeout(): null | number;
/**
* Prepares a room-targeted broadcast mechanism.
* Works similarly to Socket.IO `.to(room).emit()`.
*
* @param {string|string[]} room
* @returns {{ emit(eventName: string, ...args: any): import('socket.io-client').Socket }}
*/
to(room: string | string[]): {
emit(eventName: string, ...args: any): import("socket.io-client").Socket;
};
/**
* Establishes a connection with the proxy server and completes authentication.
*
* @returns {Promise<boolean>} Resolves `true` if authentication occurs,
* `false` if already connected.
*
* Flow:
* 1. Connect to raw Socket.IO server (if not already)
* 2. Emit `AUTH_PROXY`
* 3. Proxy responds via callback and confirms the session
*/
connect(): Promise<boolean>;
/**
* Fully disconnects from the proxy and resets internal state.
* All user objects are destroyed.
*/
disconnect(): void;
/**
* Completely destroys the instance.
* Used when the client will never be reused.
*/
destroy(): void;
#private;
}
import EventEmitter from 'events';
//# sourceMappingURL=index.d.mts.map