@hkdigital/lib-sveltekit 0.2.11 → 0.2.13

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

@@ -1,350 +1,179 @@
 /**
- * @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
+ * @typedef {import('./typedef.js').ServiceConstructor} ServiceConstructor
+ * @typedef {import('./typedef.js').ServiceConfig} ServiceConfig
+ * @typedef {import('./typedef.js').ServiceRegistrationOptions} ServiceRegistrationOptions
+ * @typedef {import('./typedef.js').ServiceManagerConfig} ServiceManagerConfig
+ * @typedef {import('./typedef.js').StopOptions} StopOptions
+ * @typedef {import('./typedef.js').ServiceEntry} ServiceEntry
+ * @typedef {import('./typedef.js').HealthCheckResult} HealthCheckResult
  */
 /**
- * Manager for coordinating services lifecycle
+ * Service Manager for lifecycle and dependency management
+ * @extends EventEmitter
  */
-export default class ServiceManager {
+export class ServiceManager extends EventEmitter {
     /**
-     * Create a new service manager
+     * Create a new ServiceManager instance
      *
-     * @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}
+     * @param {ServiceManagerConfig} [config={}] - Manager configuration
      */
+    constructor(config?: ServiceManagerConfig);
+    /** @type {Map<string, ServiceEntry>} */
+    services: Map<string, ServiceEntry>;
+    /** @type {Logger} */
     logger: Logger;
+    /** @type {ServiceManagerConfig} */
+    config: ServiceManagerConfig;
     /**
-     * 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
+     * Register a service class with the manager
      *
-     * @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} name - Unique service identifier
+     * @param {ServiceConstructor} ServiceClass - Service class constructor
+     * @param {ServiceConfig} [config={}] - Service configuration
+     * @param {ServiceRegistrationOptions} [options={}] - Registration options
      *
-     * @param {string} eventName - Event name
-     * @param {*} data - Event data
-     * @returns {boolean} True if event had listeners
-     * @private
+     * @throws {Error} If service name is already registered
      */
-    private _emit;
+    register(name: string, ServiceClass: ServiceConstructor, config?: ServiceConfig, options?: ServiceRegistrationOptions): void;
     /**
-     * Register a service
+     * Get or create a service instance
      *
      * @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 }
-     * });
+     * @returns {import('./typedef.js').ServiceBase|null}
+     *   Service instance or null if not found
      */
-    register(name: string, instance: any, options?: {
-        dependencies?: string[];
-        config?: any;
-    }): boolean;
+    get(name: string): import("./typedef.js").ServiceBase | null;
     /**
-     * Unregister a service
+     * Initialize a service
      *
      * @param {string} name - Service name
-     * @returns {boolean} True if unregistration was successful
      *
-     * @example
-     * manager.unregister('api');
+     * @returns {Promise<boolean>} True if initialization succeeded
      */
-    unregister(name: string): boolean;
+    initService(name: string): Promise<boolean>;
     /**
-     * Get a service instance
+     * Start a service and its dependencies
      *
      * @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');
+     * @returns {Promise<boolean>} True if service started successfully
      */
-    getService(name: string): any | null;
+    startService(name: string): Promise<boolean>;
     /**
-     * Initialize a specific service
+     * Stop a 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 {StopOptions} [options={}] - Stop options
      *
-     * @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 }
-     * });
+     * @returns {Promise<boolean>} True if service stopped successfully
      */
-    initializeAll(configs?: any): Promise<boolean>;
+    stopService(name: string, options?: StopOptions): Promise<boolean>;
     /**
-     * Start a specific service and its dependencies
+     * Recover a service from error state
      *
      * @param {string} name - Service name
-     * @returns {Promise<boolean>} True if start was successful
      *
-     * @example
-     * await manager.startService('api');
+     * @returns {Promise<boolean>} True if recovery succeeded
      */
-    startService(name: string): Promise<boolean>;
+    recoverService(name: string): Promise<boolean>;
     /**
-     * Start all services in dependency order
+     * Start all registered services in dependency order
      *
-     * @returns {Promise<boolean>} True if all services started successfully
-     *
-     * @example
-     * await manager.startAll();
+     * @returns {Promise<Object<string, boolean>>} Map of service results
      */
-    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>;
+    startAll(): Promise<{
+        [x: string]: 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
+     * @param {StopOptions} [options={}] - Stop options
      *
-     * @example
-     * await manager.stopAll();
+     * @returns {Promise<Object<string, boolean>>} Map of service results
      */
-    stopAll(options?: {
-        force?: boolean;
-    }): Promise<boolean>;
+    stopAll(options?: StopOptions): Promise<{
+        [x: string]: boolean;
+    }>;
     /**
-     * Destroy a service and remove it from the manager
+     * Stop services sequentially
      *
-     * @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');
+     * @private
+     * @param {string[]} serviceNames - Ordered list of service names
+     * @param {Map<string, boolean>} results - Results map to populate
+     * @param {StopOptions} options - Stop options
      */
-    destroyService(name: string, options?: {
-        force?: boolean;
-    }): Promise<boolean>;
+    private _stopAllSequentially;
     /**
-     * Destroy all services and shutdown the manager
+     * Get health status for all services
      *
-     * @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();
+     * @returns {Promise<HealthCheckResult>} Health status for all services
      */
-    destroyAll(options?: {
-        force?: boolean;
-    }): Promise<boolean>;
+    checkHealth(): Promise<HealthCheckResult>;
     /**
-     * Recover a service and its dependencies from error state
+     * Check if a service is currently running
      *
      * @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
-     * });
+     * @returns {Promise<boolean>} True if service is running
      */
-    recoverService(name: string, options?: {
-        recursive?: boolean;
-        autoStart?: boolean;
-    }): Promise<boolean>;
+    isRunning(name: string): 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();
+     * Set log level for a service or globally
      *
-     * // Recover all services without auto-starting
-     * await manager.recoverAll({ autoStart: false });
+     * @param {string} name - Service name or '*' for global
+     * @param {string} level - Log level to set
      */
-    recoverAll(options?: {
-        autoStart?: boolean;
-    }): Promise<boolean>;
+    setLogLevel(name: string, level: string): void;
     /**
-     * Set log level for a specific service or all services
+     * Get all services with a specific tag
      *
-     * @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
+     * @param {string} tag - Tag to filter by
      *
-     * @example
-     * // Set level for specific service
-     * manager.setLogLevel(DEBUG, 'database');
-     *
-     * // Set level for all services including manager
-     * manager.setLogLevel(INFO);
+     * @returns {string[]} Array of service names
      */
-    setLogLevel(level: string, serviceName?: string): boolean;
+    getServicesByTag(tag: string): string[];
     /**
-     * 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
+     * Setup logging configuration based on config.dev
      *
      * @private
-     * @param {string} serviceName - Service name
-     * @param {Object} event - State change event
      */
-    private _handleStateChanged;
+    private _setupLogging;
     /**
-     * Handle error events from services
+     * Get the appropriate log level for a service
      *
      * @private
-     * @param {string} serviceName - Service name
-     * @param {Object} event - Error event
-     */
-    private _handleError;
-    /**
-     * Update the dependency graph
+     * @param {string} name - Service name
      *
-     * @private
+     * @returns {string|undefined} Log level or undefined
      */
-    private _updateDependencyGraph;
+    private _getServiceLogLevel;
     /**
-     * Check for circular dependencies in the graph
+     * Attach event listeners to forward service events
      *
      * @private
+     * @param {string} name - Service name
+     * @param {import('./typedef.js').ServiceBase} instance
+     *   Service instance
      */
-    private _checkForCircularDependencies;
+    private _attachServiceEvents;
     /**
-     * Get optimal service start order based on dependencies
+     * Sort services by dependencies using topological sort
      *
      * @private
-     * @returns {string[]} Services in dependency order
+     *
+     * @returns {string[]} Service names in dependency order
+     * @throws {Error} If circular dependencies are detected
      */
-    private _getStartOrder;
+    private _topologicalSort;
 }
-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;
-};
+export default ServiceManager;
+export type ServiceConstructor = import("./typedef.js").ServiceConstructor;
+export type ServiceConfig = import("./typedef.js").ServiceConfig;
+export type ServiceRegistrationOptions = import("./typedef.js").ServiceRegistrationOptions;
+export type ServiceManagerConfig = import("./typedef.js").ServiceManagerConfig;
+export type StopOptions = import("./typedef.js").StopOptions;
+export type ServiceEntry = import("./typedef.js").ServiceEntry;
+export type HealthCheckResult = import("./typedef.js").HealthCheckResult;
 import { EventEmitter } from '../events';
 import { Logger } from '../logging';