@hkdigital/lib-sveltekit 0.1.70 → 0.1.72

package/dist/classes/services/ServiceManager.d.ts

@@ -0,0 +1,350 @@
+/**
+ * @typedef {Object} ServiceEntry
+ * @property {Object} instance - Service instance
+ * @property {Object} config - Service configuration
+ * @property {string[]} dependencies - List of service dependencies
+ * @property {Function} stateChangedUnsubscribe - Unsubscribe function for state events
+ * @property {Function} errorUnsubscribe - Unsubscribe function for error events
+ */
+/**
+ * Manager for coordinating services lifecycle
+ */
+export default class ServiceManager {
+    /**
+     * Create a new service manager
+     *
+     * @param {Object} [options] - Manager options
+     * @param {string} [options.logLevel=INFO] - Log level for the manager
+     */
+    constructor(options?: {
+        logLevel?: string;
+    });
+    /**
+     * Map of registered services
+     * @type {Map<string, ServiceEntry>}
+     * @private
+     */
+    private services;
+    /**
+     * Event emitter for service events
+     * @type {EventEmitter}
+     */
+    events: EventEmitter;
+    /**
+     * Service manager logger
+     * @type {Logger}
+     */
+    logger: Logger;
+    /**
+     * Service dependency graph
+     * @type {Map<string, Set<string>>}
+     * @private
+     */
+    private dependencyGraph;
+    /**
+     * Register an event handler
+     *
+     * @param {string} eventName - Event name
+     * @param {Function} handler - Event handler
+     * @returns {Function} Unsubscribe function
+     */
+    on(eventName: string, handler: Function): Function;
+    /**
+     * Remove an event handler
+     *
+     * @param {string} eventName - Event name
+     * @param {Function} handler - Event handler
+     * @returns {boolean} True if handler was removed
+     */
+    off(eventName: string, handler: Function): boolean;
+    /**
+     * Emit an event
+     *
+     * @param {string} eventName - Event name
+     * @param {*} data - Event data
+     * @returns {boolean} True if event had listeners
+     * @private
+     */
+    private _emit;
+    /**
+     * Register a service
+     *
+     * @param {string} name - Service name
+     * @param {Object} instance - Service instance
+     * @param {Object} [options] - Registration options
+     * @param {string[]} [options.dependencies=[]] - Service dependencies
+     * @param {Object} [options.config={}] - Service configuration
+     * @returns {boolean} True if registration was successful
+     *
+     * @example
+     * manager.register('database', new DatabaseService());
+     * manager.register('api', new ApiService(), {
+     *   dependencies: ['database'],
+     *   config: { port: 3000 }
+     * });
+     */
+    register(name: string, instance: any, options?: {
+        dependencies?: string[];
+        config?: any;
+    }): boolean;
+    /**
+     * Unregister a service
+     *
+     * @param {string} name - Service name
+     * @returns {boolean} True if unregistration was successful
+     *
+     * @example
+     * manager.unregister('api');
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a service instance
+     *
+     * @param {string} name - Service name
+     * @returns {Object|null} Service instance or null if not found
+     *
+     * @example
+     * const db = manager.getService('database');
+     * await db.query('SELECT * FROM users');
+     */
+    getService(name: string): any | null;
+    /**
+     * Initialize a specific service
+     *
+     * @param {string} name - Service name
+     * @param {Object} [config] - Service configuration (overrides config from
+     *                            registration)
+     * @returns {Promise<boolean>} True if initialization was successful
+     *
+     * @example
+     * await manager.initializeService('database', {
+     *   connectionString: 'mongodb://localhost:27017'
+     * });
+     */
+    initializeService(name: string, config?: any): Promise<boolean>;
+    /**
+     * Initialize all registered services
+     *
+     * @param {Object} [configs] - Configuration map for services
+     * @returns {Promise<boolean>} True if all services initialized successfully
+     *
+     * @example
+     * await manager.initializeAll({
+     *   database: { connectionString: 'mongodb://localhost:27017' },
+     *   api: { port: 3000 }
+     * });
+     */
+    initializeAll(configs?: any): Promise<boolean>;
+    /**
+     * Start a specific service and its dependencies
+     *
+     * @param {string} name - Service name
+     * @returns {Promise<boolean>} True if start was successful
+     *
+     * @example
+     * await manager.startService('api');
+     */
+    startService(name: string): Promise<boolean>;
+    /**
+     * Start all services in dependency order
+     *
+     * @returns {Promise<boolean>} True if all services started successfully
+     *
+     * @example
+     * await manager.startAll();
+     */
+    startAll(): Promise<boolean>;
+    /**
+     * Stop a specific service and services that depend on it
+     *
+     * @param {string} name - Service name
+     * @param {Object} [options] - Stop options
+     * @param {boolean} [options.force=false] - Force stop even with dependents
+     * @returns {Promise<boolean>} True if stop was successful
+     *
+     * @example
+     * await manager.stopService('database');
+     */
+    stopService(name: string, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Stop all services in reverse dependency order
+     *
+     * @param {Object} [options] - Stop options
+     * @param {boolean} [options.force=false] - Force stop even with errors
+     * @returns {Promise<boolean>} True if all services stopped successfully
+     *
+     * @example
+     * await manager.stopAll();
+     */
+    stopAll(options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Destroy a service and remove it from the manager
+     *
+     * @param {string} name - Service name
+     * @param {Object} [options] - Destroy options
+     * @param {boolean} [options.force=false] - Force destroy even with dependents
+     * @returns {Promise<boolean>} True if service was destroyed
+     *
+     * @example
+     * await manager.destroyService('api');
+     */
+    destroyService(name: string, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Destroy all services and shutdown the manager
+     *
+     * @param {Object} [options] - Destroy options
+     * @param {boolean} [options.force=false] - Force destroy even with errors
+     * @returns {Promise<boolean>} True if all services were destroyed
+     *
+     * @example
+     * await manager.destroyAll();
+     */
+    destroyAll(options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Recover a service and its dependencies from error state
+     *
+     * @param {string} name - Service name
+     * @param {Object} [options] - Recovery options
+     * @param {boolean} [options.recursive=true] - Recursively recover dependencies
+     * @param {boolean} [options.autoStart=true] - Auto-start service after recovery
+     * @returns {Promise<boolean>} True if recovery was successful
+     *
+     * @example
+     * // Recover a service and its dependencies
+     * await manager.recoverService('api');
+     *
+     * // Recover just this service without auto-starting
+     * await manager.recoverService('database', {
+     *   recursive: false,
+     *   autoStart: false
+     * });
+     */
+    recoverService(name: string, options?: {
+        recursive?: boolean;
+        autoStart?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Recover all services in dependency order
+     *
+     * @param {Object} [options] - Recovery options
+     * @param {boolean} [options.autoStart=true] - Auto-start services after recovery
+     * @returns {Promise<boolean>} True if all recoveries were successful
+     *
+     * @example
+     * // Recover all services and auto-start them
+     * await manager.recoverAll();
+     *
+     * // Recover all services without auto-starting
+     * await manager.recoverAll({ autoStart: false });
+     */
+    recoverAll(options?: {
+        autoStart?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Set log level for a specific service or all services
+     *
+     * @param {string} level - New log level
+     * @param {string} [serviceName] - Service to set level for, or all if omitted
+     * @returns {boolean} True if level was set successfully
+     *
+     * @example
+     * // Set level for specific service
+     * manager.setLogLevel(DEBUG, 'database');
+     *
+     * // Set level for all services including manager
+     * manager.setLogLevel(INFO);
+     */
+    setLogLevel(level: string, serviceName?: string): boolean;
+    /**
+     * Get the names of all registered services
+     *
+     * @returns {string[]} List of service names
+     *
+     * @example
+     * const services = manager.getServiceNames();
+     * console.log(`Registered services: ${services.join(', ')}`);
+     */
+    getServiceNames(): string[];
+    /**
+     * Get service status information
+     *
+     * @param {string} [name] - Service name, or all if omitted
+     * @returns {Object|Array|null} Service status or null if not found
+     *
+     * @example
+     * // Get status for all services
+     * const allStatus = manager.getServiceStatus();
+     *
+     * // Get status for specific service
+     * const dbStatus = manager.getServiceStatus('database');
+     * console.log(`Database state: ${dbStatus.state}`);
+     */
+    getServiceStatus(name?: string): any | any[] | null;
+    /**
+     * Handle state change events from services
+     *
+     * @private
+     * @param {string} serviceName - Service name
+     * @param {Object} event - State change event
+     */
+    private _handleStateChanged;
+    /**
+     * Handle error events from services
+     *
+     * @private
+     * @param {string} serviceName - Service name
+     * @param {Object} event - Error event
+     */
+    private _handleError;
+    /**
+     * Update the dependency graph
+     *
+     * @private
+     */
+    private _updateDependencyGraph;
+    /**
+     * Check for circular dependencies in the graph
+     *
+     * @private
+     */
+    private _checkForCircularDependencies;
+    /**
+     * Get optimal service start order based on dependencies
+     *
+     * @private
+     * @returns {string[]} Services in dependency order
+     */
+    private _getStartOrder;
+}
+export type ServiceEntry = {
+    /**
+     * - Service instance
+     */
+    instance: any;
+    /**
+     * - Service configuration
+     */
+    config: any;
+    /**
+     * - List of service dependencies
+     */
+    dependencies: string[];
+    /**
+     * - Unsubscribe function for state events
+     */
+    stateChangedUnsubscribe: Function;
+    /**
+     * - Unsubscribe function for error events
+     */
+    errorUnsubscribe: Function;
+};
+import { EventEmitter } from '../events';
+import { Logger } from '../logging';