ioserver 1.4.2 → 2.0.1

package/dist/IOServer.d.ts

@@ -0,0 +1,260 @@
+/**
+ * @fileoverview IOServer - A TypeScript framework for building real-time applications
+ * with Socket.IO and Fastify integration. Provides modular architecture with
+ * Services, Controllers, Managers, and Watchers.
+ *
+ * @author Ben Mz <0x42en@users.noreply.github.com>
+ * @version 2.0.0
+ * @since 1.0.0
+ */
+import { FastifyInstance } from 'fastify';
+import { Server as SocketIOServer } from 'socket.io';
+declare module 'fastify' {
+    interface FastifyInstance {
+        io: SocketIOServer;
+    }
+}
+/**
+ * Configuration options for IOServer instance
+ * @interface IOServerOptions
+ */
+export interface IOServerOptions {
+    /** Logging verbosity level - defaults to 'ERROR' */
+    verbose?: LogLevel;
+    /** Server hostname - defaults to 'localhost' */
+    host?: string;
+    /** Server port number - defaults to 8080 */
+    port?: number;
+    /** Enable Socket.IO cookies - defaults to false */
+    cookie?: boolean;
+    /** Transport modes for Socket.IO - defaults to ['websocket', 'polling'] */
+    mode?: TransportMode | TransportMode[];
+    /** CORS configuration options */
+    cors?: any;
+    /** Path to routes directory - defaults to './routes' */
+    routes?: string;
+}
+/**
+ * Configuration options for registering a Service
+ * @interface ServiceOptions
+ */
+export interface ServiceOptions {
+    /** Service namespace (optional, defaults to '/') */
+    name?: string;
+    /** Service class constructor that extends BaseService */
+    service: new (appHandle: AppHandle) => any;
+    /** Array of middleware classes to apply to this service */
+    middlewares?: (new () => any)[];
+}
+/**
+ * Configuration options for registering a Controller
+ * @interface ControllerOptions
+ */
+export interface ControllerOptions {
+    /** Controller name that matches the route file name */
+    name: string;
+    /** Controller class constructor that extends BaseController */
+    controller: new (appHandle: AppHandle) => any;
+    /** Array of middleware classes to apply to this controller */
+    middlewares?: (new () => any)[];
+    /** URL prefix for all routes in this controller */
+    prefix?: string;
+}
+/**
+ * Configuration options for registering a Manager
+ * @interface ManagerOptions
+ */
+export interface ManagerOptions {
+    /** Manager name (used as property name in appHandle) */
+    name: string;
+    /** Manager class constructor that extends BaseManager */
+    manager: new (appHandle: AppHandle) => any;
+}
+/**
+ * Configuration options for registering a Watcher
+ * @interface WatcherOptions
+ */
+export interface WatcherOptions {
+    /** Watcher name for identification */
+    name: string;
+    /** Watcher class constructor that extends BaseWatcher */
+    watcher: new (appHandle: AppHandle) => any;
+}
+/**
+ * Options for sending real-time messages to clients
+ * @interface SendToOptions
+ */
+export interface SendToOptions {
+    /** Target namespace (optional, defaults to '/') */
+    namespace?: string;
+    /** Event name to emit */
+    event: string;
+    /** Data payload to send */
+    data: any;
+    /** Target specific room (optional) */
+    room?: string;
+    /** Target specific socket ID (optional) */
+    sid?: string;
+}
+/**
+ * Application handle providing shared functionality across all components
+ * @interface AppHandle
+ */
+export interface AppHandle {
+    /** Function to send real-time messages to clients */
+    send: (options: SendToOptions) => boolean;
+    /** Logging function with level-based filtering */
+    log: (level: number, text: string) => void;
+    /** Current logging verbosity level */
+    verbose: LogLevel;
+    /** Dynamic properties for registered managers */
+    [key: string]: any;
+}
+/**
+ * Log levels for controlling verbosity of output
+ */
+export type LogLevel = 'EMERGENCY' | 'ALERT' | 'CRITICAL' | 'ERROR' | 'WARNING' | 'NOTIFICATION' | 'INFORMATION' | 'DEBUG';
+/**
+ * Transport modes supported by Socket.IO
+ */
+export type TransportMode = 'websocket' | 'polling';
+/**
+ * Main IOServer class - A framework for building real-time applications
+ *
+ * Combines Fastify HTTP server with Socket.IO for WebSocket support,
+ * providing a modular architecture with Services, Controllers, Managers, and Watchers.
+ *
+ * @example
+ * ```typescript
+ * const server = new IOServer({
+ *   host: 'localhost',
+ *   port: 3000,
+ *   verbose: 'INFO'
+ * });
+ *
+ * server.addService({ service: ChatService });
+ * server.addController({ name: 'api', controller: ApiController });
+ * await server.start();
+ * ```
+ */
+export declare class IOServer {
+    private static readonly VERSION;
+    private static readonly DEFAULT_PORT;
+    private static readonly DEFAULT_HOST;
+    private static readonly LOG_LEVELS;
+    private static readonly TRANSPORTS;
+    private static readonly RESERVED_NAMES;
+    private readonly host;
+    private readonly port;
+    private readonly verbose;
+    private readonly routesPath;
+    private readonly webapp;
+    private socketio;
+    private readonly appHandle;
+    private readonly serviceLists;
+    private readonly managerLists;
+    private readonly methodLists;
+    private readonly watcherLists;
+    private readonly controllerLists;
+    private readonly middlewareLists;
+    /**
+     * Creates a new IOServer instance
+     * @param {IOServerOptions} options - Configuration options for the server
+     */
+    constructor(options?: IOServerOptions);
+    private validatePort;
+    private validateLogLevel;
+    private processTransportModes;
+    private processCorsOptions;
+    private initializeFastify;
+    private setupPlugins;
+    private setupSocketIO;
+    private log;
+    private unique;
+    private registerInternalClass;
+    private getListMap;
+    private dumpMethods;
+    /**
+     * Registers a watcher component for background tasks
+     * @param {WatcherOptions} options - Watcher configuration options
+     * @throws {IOServerError} When watcher instantiation fails
+     */
+    addWatcher(options: WatcherOptions): void;
+    /**
+     * Registers a manager component for shared functionality
+     * @param {ManagerOptions} options - Manager configuration options
+     * @throws {IOServerError} When manager instantiation fails
+     */
+    addManager(options: ManagerOptions): void;
+    /**
+     * Registers a service component for real-time WebSocket handling
+     * @param {ServiceOptions} options - Service configuration options
+     * @throws {IOServerError} When service instantiation fails
+     */
+    addService(options: ServiceOptions): void;
+    /**
+     * Registers a controller component for HTTP route handling
+     * @param {ControllerOptions} options - Controller configuration options
+     * @throws {IOServerError} When controller instantiation or route loading fails
+     */
+    addController(options: ControllerOptions): void;
+    private registerControllerRoutes;
+    /**
+     * Retrieves a registered service by name
+     * @param {string} name - The service name
+     * @returns {any} The service instance or undefined if not found
+     */
+    getService(name: string): any;
+    /**
+     * Starts the IOServer instance
+     * Initializes Socket.IO, starts watchers, and begins listening for connections
+     * @returns {Promise<void>} Promise that resolves when server is started
+     * @throws {IOServerError} When server startup fails
+     */
+    start(): Promise<void>;
+    /**
+     * Gets the server hostname
+     * @returns {string} The server hostname
+     */
+    getHost(): string;
+    /**
+     * Gets the server port number
+     * @returns {number} The server port
+     */
+    getPort(): number;
+    /**
+     * Gets the Fastify instance
+     * @returns {FastifyInstance} The Fastify application instance
+     */
+    getApp(): FastifyInstance;
+    /**
+     * Stops the IOServer instance
+     * @returns {Promise<void>} Promise that resolves when server is stopped
+     * @throws {IOServerError} When server shutdown fails
+     */
+    stop(): Promise<void>;
+    /**
+     * Sends real-time messages to connected clients
+     * @param {SendToOptions} options - Options for message delivery
+     * @returns {boolean} True if message was sent successfully, false otherwise
+     */
+    sendTo(options: SendToOptions): boolean;
+    /**
+     * Handles new WebSocket connections for a specific service
+     * @private
+     * @param {string} serviceName - The name of the service
+     * @returns {Function} Connection handler function
+     */
+    private handleConnection;
+    /**
+     * Creates a callback handler for WebSocket method calls
+     * @private
+     * @param {string} serviceName - The name of the service
+     * @param {string} methodName - The name of the method
+     * @param {any} socket - The Socket.IO socket instance
+     * @returns {Function} Callback handler function
+     */
+    private handleCallback;
+}
+export default IOServer;
+//# sourceMappingURL=IOServer.d.ts.map

package/dist/IOServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOServer.d.ts","sourceRoot":"","sources":["../src/IOServer.ts"],"names":[],"mappings":"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"}