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.
212 lines • 7.98 kB
text/typescript
export default TinyIo;
export type Socket = import("socket.io").Socket;
export type HttpStatusCode = number;
export type IPExtractor = (socket: Socket) => string[];
export type DomainValidator = (socket: Socket) => boolean;
/**
* Represents the structured data extracted from an HTTP Origin header.
*/
export type OriginData = {
/**
* - The raw Origin header value.
*/
raw: string | null;
/**
* - The protocol used (e.g., 'http' or 'https').
*/
protocol?: string | undefined;
/**
* - The hostname extracted from the origin.
*/
hostname?: string | undefined;
/**
* - The port number (explicit or default based on protocol).
*/
port?: string | undefined;
/**
* - The full reconstructed URL from the origin.
*/
full?: string | undefined;
/**
* - Any parsing error encountered while processing the origin.
*/
error?: string | undefined;
};
/** @typedef {import('socket.io').Socket} Socket */
/**
* @typedef {number} HttpStatusCode
*/
/**
* @typedef {(socket: Socket) => string[]} IPExtractor
*/
/**
* @typedef {(socket: Socket) => boolean} DomainValidator
*/
/**
* Represents the structured data extracted from an HTTP Origin header.
*
* @typedef {Object} OriginData
* @property {string|null} raw - The raw Origin header value.
* @property {string} [protocol] - The protocol used (e.g., 'http' or 'https').
* @property {string} [hostname] - The hostname extracted from the origin.
* @property {string} [port] - The port number (explicit or default based on protocol).
* @property {string} [full] - The full reconstructed URL from the origin.
* @property {string} [error] - Any parsing error encountered while processing the origin.
*/
/**
* TinyIo is a wrapper for Socket.IO v4,
* designed to simplify WebSocket server management,
* client communication, and event handling.
*
* It offers streamlined integration and utility methods
* for real-time bidirectional communication.
*
* @class
*/
declare class TinyIo {
/**
* Creates a new instance of the Socket.IO server wrapper.
*
* @param {HttpServer | HttpsServer | number | import('socket.io').ServerOptions} [server] - An instance of a Node.js HTTP/HTTPS server, a port number, or Socket.IO options.
* @param {import('socket.io').ServerOptions} [options] - Configuration options for the Socket.IO server instance.
*
* @throws {Error} If `server` is not a valid server, number, or object.
* @throws {Error} If `options` is not a non-null plain object.
*/
constructor(server?: HttpServer | HttpsServer | number | import("socket.io").ServerOptions, options?: import("socket.io").ServerOptions);
root: SocketIOServer<import("socket.io").DefaultEventsMap, import("socket.io").DefaultEventsMap, import("socket.io").DefaultEventsMap, any>;
/**
* Init instance.
*
* @param {TinyWebInstance} [web] - An instance of TinyWebInstance.
*
* @throws {Error} If `web` is not an instance of TinyWebInstance.
*/
init(web?: TinyWebInstance): void;
/** @type {TinyWebInstance} */ web: TinyWebInstance;
/**
* Parses the Origin header from a Socket.IO connection handshake and extracts structured information.
*
* @param {Socket} socket - The connected Socket.IO socket instance.
* @returns {OriginData} An object containing detailed parts of the Origin header, or error info if parsing fails.
*/
getOrigin(socket: Socket): OriginData;
/**
* Returns the current TinyWeb instance.
*
* @returns {TinyWebInstance} The active Http server.
*/
getWeb(): TinyWebInstance;
/**
* Returns the current Http server instance.
*
* @returns {HttpServer | HttpsServer} The active Http server.
*/
getServer(): HttpServer | HttpsServer;
/**
* Returns the current Socket.IO server instance.
*
* @returns {import('socket.io').Server} The active Socket.IO server.
*/
getRoot(): import("socket.io").Server;
/**
* Registers a new IP extractor under a specific key.
*
* Each extractor must be a function that receives an Express `Request` and returns a string (IP) or null.
* The key `"DEFAULT"` is reserved and cannot be used directly.
*
* @param {string} key
* @param {IPExtractor} callback
* @throws {Error} If the key is invalid or already registered.
*/
addIpExtractor(key: string, callback: IPExtractor): void;
/**
* Removes a registered IP extractor.
*
* Cannot remove the extractor currently in use unless it's set to "DEFAULT".
*
* @param {string} key
* @throws {Error} If the key is invalid or in use.
*/
removeIpExtractor(key: string): void;
/**
* Returns a shallow clone of the current extractors.
*
* @returns {{ [key: string]: IPExtractor }}
*/
getIpExtractors(): {
[key: string]: IPExtractor;
};
/**
* Sets the currently active extractor key.
*
* @param {string} key
* @throws {Error} If the key is not found.
*/
setActiveIpExtractor(key: string): void;
/**
* Returns the current extractor function based on the active key.
*
* @returns {IPExtractor}
*/
getActiveExtractor(): IPExtractor;
/**
* Extracts the IP address from a request using the active extractor.
* @param {Socket} socket
* @returns {string[]}
*/
extractIp(socket: Socket): string[];
/**
* Registers a new domain validator under a specific key.
*
* Each validator must be a function that receives an Express `Request` object and returns a boolean.
* The key `"ALL"` is reserved and cannot be used as a validator key.
*
* @param {string} key - The key name identifying the validator (e.g., 'host', 'x-forwarded-host').
* @param {DomainValidator} callback - The validation function to be added.
* @throws {Error} If the key is not a string.
* @throws {Error} If the key is "ALL".
* @throws {Error} If the callback is not a function.
* @throws {Error} If a validator with the same key already exists.
*/
addDomainValidator(key: string, callback: DomainValidator): void;
/**
* Removes a registered domain validator by its key.
*
* Cannot remove the validator currently being used by the domain type checker,
* unless the type checker is set to "ALL".
*
* @param {string} key - The key name of the validator to remove.
* @throws {Error} If the key is not a string.
* @throws {Error} If no validator is found under the given key.
* @throws {Error} If the validator is currently in use by the domain type checker.
*/
removeDomainValidator(key: string): void;
/**
* Returns a shallow clone of the current domain validators map.
*
* The returned object maps each key to its corresponding validation function.
*
* @returns {{ [key: string]: DomainValidator }} A cloned object of the validators.
*/
getDomainValidators(): {
[key: string]: DomainValidator;
};
/**
* Sets the current domain validation strategy by key name.
*
* The provided key must exist in the registered domain validators,
* or be the string `"ALL"` to enable all validators simultaneously (not recommended).
*
* @param {string} key - The key of the validator to use (e.g., 'hostname', 'x-forwarded-host'), or 'ALL'.
* @throws {Error} If the key is not a string.
* @throws {Error} If the key is not found among the validators and is not 'ALL'.
*/
setDomainTypeChecker(key: string): void;
#private;
}
import { Server as SocketIOServer } from 'socket.io';
import TinyWebInstance from './TinyWebInstance.mjs';
import { Server as HttpServer } from 'http';
import { Server as HttpsServer } from 'https';
//# sourceMappingURL=TinyIo.d.mts.map