@hkdigital/lib-core 0.4.18 → 0.4.20

package/dist/services/service-base/typedef.js

@@ -1,17 +1,17 @@
 /**
  * @fileoverview Type definitions for ServiceBase class.
- * 
+ *
  * This file contains all TypeScript/JSDoc type definitions used by
  * the ServiceBase class and service implementations.
- * 
+ *
  * @example
  * // In your service implementation
  * import { ServiceBase } from './ServiceBase.js';
- * 
+ *
  * class MyService extends ServiceBase {
- *   async _init(config) {
+ *   async _configure(newConfig, oldConfig) {
  *   }
- *   
+ *
  *   async _healthCheck() {
  *     // Return type is HealthStatus
  *     return { latency: 10 };
@@ -23,6 +23,24 @@
 // PUBLIC TYPES
 // ============================================================================
 
+/**
+ * All possible service states during lifecycle management
+ *
+ * @typedef {import('./constants.js').STATE_NOT_CREATED |
+ *           import('./constants.js').STATE_CREATED |
+ *           import('./constants.js').STATE_CONFIGURING |
+ *           import('./constants.js').STATE_CONFIGURED |
+ *           import('./constants.js').STATE_STARTING |
+ *           import('./constants.js').STATE_RUNNING |
+ *           import('./constants.js').STATE_STOPPING |
+ *           import('./constants.js').STATE_STOPPED |
+ *           import('./constants.js').STATE_DESTROYING |
+ *           import('./constants.js').STATE_DESTROYED |
+ *           import('./constants.js').STATE_ERROR |
+ *           import('./constants.js').STATE_RECOVERING
+ * } ServiceState
+ */
+
 /**
  * Options for creating a service instance
  *
@@ -57,11 +75,11 @@
  *
  * @typedef {Object & Record<string, any>} ServiceInstance
  * @property {string} name - Service name
- * @property {string} state - Current state
+ * @property {ServiceState} state - Current state
  * @property {boolean} healthy - Health status
  * @property {Error|null} error - Last error
  * @property {import('../../logging/index.js').Logger} logger - Service logger
- * @property {(config?: *) => Promise<boolean>} initialize
+ * @property {(config?: *) => Promise<boolean>} configure
  * @property {() => Promise<boolean>} start
  * @property {(options?: StopOptions) => Promise<boolean>} stop
  * @property {() => Promise<boolean>} recover
@@ -79,13 +97,18 @@
 /**
  * @typedef {Object} StateChangeEvent
  * @property {string} service - Service name (added by ServiceManager)
- * @property {string} oldState - Previous state
- * @property {string} newState - New state
+ * @property {ServiceState} oldState - Previous state
+ * @property {ServiceState} newState - New state
+ */
+
+/**
+ * @typedef {Object} TargetStateChangeEvent
+ * @property {ServiceState} oldTargetState - Previous target state
+ * @property {ServiceState} newTargetState - New target state
  */
 
 /**
  * @typedef {Object} HealthChangeEvent
- * @property {string} service - Service name (added by ServiceManager)
  * @property {boolean} healthy - Current health status
  * @property {boolean} [wasHealthy] - Previous health status
  */
@@ -94,7 +117,6 @@
  * Event emitted when service encounters an error
  *
  * @typedef {Object} ServiceErrorEvent
- * @property {string} service - Service name
  * @property {string} operation - Operation that failed
  * @property {Error} error - Error that occurred
  */

package/dist/services/service-manager/ServiceManager.d.ts

@@ -3,6 +3,7 @@
  * @typedef {import('./typedef.js').ServiceRegistrationOptions} ServiceRegistrationOptions
  * @typedef {import('./typedef.js').ServiceManagerConfig} ServiceManagerConfig
  * @typedef {import('./typedef.js').ServiceEntry} ServiceEntry
+ * @typedef {import('./typedef.js').ServiceConfigOrLabel} ServiceConfigOrLabel
  * @typedef {import('./typedef.js').HealthCheckResult} HealthCheckResult
  *
  * @typedef {import('../service-base/typedef.js').StopOptions} StopOptions
@@ -24,17 +25,35 @@ export class ServiceManager extends EventEmitter {
     logger: Logger;
     /** @type {ServiceManagerConfig} */
     config: ServiceManagerConfig;
+    /**
+     * Attach a plugin to the ServiceManager
+     *
+     * @param {import('./typedef.js').ServiceManagerPlugin} plugin
+     *   Plugin instance
+     *
+     * @throws {Error} If plugin name is already registered
+     */
+    attachPlugin(plugin: import("./typedef.js").ServiceManagerPlugin): void;
+    /**
+     * Detach a plugin from the ServiceManager
+     *
+     * @param {string} pluginName - Name of the plugin to detach
+     *
+     * @returns {boolean} True if plugin was detached
+     */
+    detachPlugin(pluginName: string): boolean;
     /**
      * Register a service class with the manager
      *
      * @param {string} name - Unique service identifier
      * @param {ServiceConstructor} ServiceClass - Service class constructor
-     * @param {*} [config={}] - Service configuration
+     * @param {ServiceConfigOrLabel} [serviceConfigOrLabel={}]
+     *   Service configuration object or config label string
      * @param {ServiceRegistrationOptions} [options={}] - Registration options
      *
      * @throws {Error} If service name is already registered
      */
-    register(name: string, ServiceClass: ServiceConstructor, config?: any, options?: ServiceRegistrationOptions): void;
+    register(name: string, ServiceClass: ServiceConstructor, serviceConfigOrLabel?: ServiceConfigOrLabel, options?: ServiceRegistrationOptions): void;
     /**
      * Get or create a service instance
      *
@@ -45,13 +64,13 @@ export class ServiceManager extends EventEmitter {
      */
     get(name: string): import("../service-base/typedef.js").ServiceInstance | null;
     /**
-     * Initialize a service
+     * Configure a service
      *
      * @param {string} name - Service name
      *
-     * @returns {Promise<boolean>} True if initialization succeeded
+     * @returns {Promise<boolean>} True if configuration succeeded
      */
-    initService(name: string): Promise<boolean>;
+    configureService(name: string): Promise<boolean>;
     /**
      * Start a service and its dependencies
      *
@@ -139,6 +158,7 @@ export type ServiceConstructor = import("./typedef.js").ServiceConstructor;
 export type ServiceRegistrationOptions = import("./typedef.js").ServiceRegistrationOptions;
 export type ServiceManagerConfig = import("./typedef.js").ServiceManagerConfig;
 export type ServiceEntry = import("./typedef.js").ServiceEntry;
+export type ServiceConfigOrLabel = import("./typedef.js").ServiceConfigOrLabel;
 export type HealthCheckResult = import("./typedef.js").HealthCheckResult;
 export type StopOptions = import("../service-base/typedef.js").StopOptions;
 import { EventEmitter } from '../../generic/events.js';

package/dist/services/service-manager/ServiceManager.js

@@ -67,10 +67,10 @@ import { EventEmitter } from '../../generic/events.js';
 import { Logger, DEBUG, INFO, WARN } from '../../logging/index.js';
 
 import {
-  NOT_CREATED,
-  CREATED,
-  RUNNING,
-  DESTROYED
+  STATE_NOT_CREATED,
+  STATE_CREATED,
+  STATE_RUNNING,
+  STATE_DESTROYED
 } from '../service-base/constants.js';
 
 /**
@@ -78,6 +78,7 @@ import {
  * @typedef {import('./typedef.js').ServiceRegistrationOptions} ServiceRegistrationOptions
  * @typedef {import('./typedef.js').ServiceManagerConfig} ServiceManagerConfig
  * @typedef {import('./typedef.js').ServiceEntry} ServiceEntry
+ * @typedef {import('./typedef.js').ServiceConfigOrLabel} ServiceConfigOrLabel
  * @typedef {import('./typedef.js').HealthCheckResult} HealthCheckResult
  *
  * @typedef {import('../service-base/typedef.js').StopOptions} StopOptions
@@ -88,6 +89,9 @@ import {
  * @extends EventEmitter
  */
 export class ServiceManager extends EventEmitter {
+  /** @type {Map<string, import('./typedef.js').ServiceManagerPlugin>} */
+  #plugins = new Map();
+
   /**
    * Create a new ServiceManager instance
    *
@@ -113,17 +117,55 @@ export class ServiceManager extends EventEmitter {
     this.#setupLogging();
   }
 
+  /**
+   * Attach a plugin to the ServiceManager
+   *
+   * @param {import('./typedef.js').ServiceManagerPlugin} plugin
+   *   Plugin instance
+   *
+   * @throws {Error} If plugin name is already registered
+   */
+  attachPlugin(plugin) {
+    if (this.#plugins.has(plugin.name)) {
+      throw new Error(`Plugin '${plugin.name}' is already attached`);
+    }
+
+    this.#plugins.set(plugin.name, plugin);
+    plugin.attach(this);
+
+    this.logger.debug(`Attached plugin '${plugin.name}'`);
+  }
+
+  /**
+   * Detach a plugin from the ServiceManager
+   *
+   * @param {string} pluginName - Name of the plugin to detach
+   *
+   * @returns {boolean} True if plugin was detached
+   */
+  detachPlugin(pluginName) {
+    const plugin = this.#plugins.get(pluginName);
+    if (!plugin) return false;
+
+    plugin.detach();
+    this.#plugins.delete(pluginName);
+
+    this.logger.debug(`Detached plugin '${pluginName}'`);
+    return true;
+  }
+
   /**
    * Register a service class with the manager
    *
    * @param {string} name - Unique service identifier
    * @param {ServiceConstructor} ServiceClass - Service class constructor
-   * @param {*} [config={}] - Service configuration
+   * @param {ServiceConfigOrLabel} [serviceConfigOrLabel={}]
+   *   Service configuration object or config label string
    * @param {ServiceRegistrationOptions} [options={}] - Registration options
    *
    * @throws {Error} If service name is already registered
    */
-  register(name, ServiceClass, config = {}, options = {}) {
+  register(name, ServiceClass, serviceConfigOrLabel = {}, options = {}) {
     if (this.services.has(name)) {
       throw new Error(`Service '${name}' already registered`);
     }
@@ -132,11 +174,11 @@ export class ServiceManager extends EventEmitter {
     const entry = {
       ServiceClass,
       instance: null,
-      config,
+      serviceConfigOrLabel,
       dependencies: options.dependencies || [],
       dependents: new Set(),
       tags: options.tags || [],
-      priority: options.priority || 0
+      startupPriority: options.startupPriority || 0
     };
 
     // Track dependents
@@ -194,18 +236,20 @@ export class ServiceManager extends EventEmitter {
   }
 
   /**
-   * Initialize a service
+   * Configure a service
    *
    * @param {string} name - Service name
    *
-   * @returns {Promise<boolean>} True if initialization succeeded
+   * @returns {Promise<boolean>} True if configuration succeeded
    */
-  async initService(name) {
+  async configureService(name) {
     const instance = this.get(name);
     if (!instance) return false;
 
     const entry = this.services.get(name);
-    return await instance.initialize(entry.config);
+    const config = await this.#resolveServiceConfig(name, entry);
+
+    return await instance.configure(config);
   }
 
   /**
@@ -240,10 +284,18 @@ export class ServiceManager extends EventEmitter {
     const instance = this.get(name);
     if (!instance) return false;
 
-    // Initialize if needed
-    if (instance.state === CREATED || instance.state === DESTROYED) {
-      const initialized = await this.initService(name);
-      if (!initialized) return false;
+    if (
+      instance.state === STATE_CREATED ||
+      instance.state === STATE_DESTROYED
+    ) {
+      // Service is not created or has been destroyed
+      // => configure needed
+
+      const configured = await this.configureService(name);
+
+      if (!configured) {
+        return false;
+      }
     }
 
     return await instance.start();
@@ -385,7 +437,6 @@ export class ServiceManager extends EventEmitter {
     return Object.fromEntries(results);
   }
 
-
   /**
    * Get health status for all services
    *
@@ -401,7 +452,7 @@ export class ServiceManager extends EventEmitter {
       } else {
         health[name] = {
           name,
-          state: NOT_CREATED,
+          state: STATE_NOT_CREATED,
           healthy: false
         };
       }
@@ -419,7 +470,7 @@ export class ServiceManager extends EventEmitter {
    */
   async isRunning(name) {
     const instance = this.get(name);
-    return instance ? instance.state === RUNNING : false;
+    return instance ? instance.state === STATE_RUNNING : false;
   }
 
   /**
@@ -472,7 +523,6 @@ export class ServiceManager extends EventEmitter {
     return services;
   }
 
-
   /**
    * Attach event listeners to forward service events
    *
@@ -503,6 +553,39 @@ export class ServiceManager extends EventEmitter {
 
   // Internal methods
 
+  /**
+   * Resolve service configuration using plugins
+   *
+   * @param {string} serviceName - Name of the service being configured
+   * @param {ServiceEntry} serviceEntry - Service registration entry
+   *
+   * @returns {Promise<*>} Resolved configuration object
+   */
+  async #resolveServiceConfig(serviceName, serviceEntry) {
+    let serviceConfigOrLabel = serviceEntry.serviceConfigOrLabel;
+
+    if (typeof serviceConfigOrLabel === 'string') {
+      const configLabel = serviceConfigOrLabel;
+
+      // Let plugins resolve the config
+      for (const plugin of this.#plugins.values()) {
+        if (plugin.resolveServiceConfig) {
+          const config = await plugin.resolveServiceConfig(
+            serviceName,
+            serviceEntry,
+            configLabel
+          );
+          if (config !== undefined) {
+            return config; // First plugin that resolves wins
+          }
+        }
+      }
+    } else {
+      const config = serviceConfigOrLabel;
+      return config;
+    }
+  }
+
   /**
    * Setup logging configuration based on config.dev
    */

package/dist/services/service-manager/constants.js

@@ -1,4 +1,3 @@
-
 // Log event names
 export const SERVICE_STATE_CHANGED = 'service:state-changed';
 export const SERVICE_HEALTH_CHANGED = 'service:health-changed';

package/dist/services/service-manager/typedef.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Service configuration - either a config object or a config label string
+ */
+export type ServiceConfigOrLabel = {
+    [x: string]: any;
+} | string;
 /**
  * Options for registering a service
  */
@@ -11,9 +17,9 @@ export type ServiceRegistrationOptions = {
      */
     tags?: string[];
     /**
-     * - Startup priority (higher starts first)
+     * - Higher starts first
      */
-    priority?: number;
+    startupPriority?: number;
 };
 /**
  * Configuration for ServiceManager
@@ -69,6 +75,31 @@ export type HealthCheckResult = {
  * Service class constructor type
  */
 export type ServiceConstructor = new (name: string, options?: import("../service-base/typedef.js").ServiceOptions) => import("../service-base/typedef.js").ServiceInstance;
+/**
+ * ServiceManager plugin interface
+ */
+export type ServiceManagerPlugin = {
+    /**
+     * - Unique plugin identifier
+     */
+    name: string;
+    /**
+     * - ServiceManager reference
+     */
+    manager: import("./ServiceManager.js").ServiceManager | null;
+    /**
+     * - Attach to ServiceManager
+     */
+    attach: (arg0: import("./ServiceManager.js").ServiceManager) => void;
+    /**
+     * - Detach from ServiceManager
+     */
+    detach: () => void;
+    /**
+     * - Optional config resolution method
+     */
+    resolveServiceConfig?: (arg0: string, arg1: ServiceEntry, arg2: any) => Promise<any | undefined>;
+};
 /**
  * Internal service registry entry
  */
@@ -81,24 +112,15 @@ export type ServiceEntry = {
      * - Service instance (lazy-created)
      */
     instance: import("../service-base/typedef.js").ServiceInstance | null;
-    /**
-     * - Service configuration
-     */
-    config: any;
-    /**
-     * - Service dependencies
-     */
+    serviceConfigOrLabel: ServiceConfigOrLabel;
     dependencies: string[];
     /**
-     * - Services that depend on this one
+     * - Services that depend on this service
      */
     dependents: Set<string>;
-    /**
-     * - Service tags
-     */
     tags: string[];
     /**
      * - Startup priority
      */
-    priority: number;
+    startupPriority: number;
 };

package/dist/services/service-manager/typedef.js

@@ -1,28 +1,28 @@
 /**
  * @fileoverview Type definitions for ServiceManager class.
- * 
+ *
  * This file contains all TypeScript/JSDoc type definitions used by
  * the ServiceManager class and service registration.
- * 
+ *
  * @example
  * // When using ServiceManager
  * import { ServiceManager } from './ServiceManager.js';
- * 
+ *
  * // @ typedef {import('./typedef-service-manager.js').ServiceManagerConfig} ServiceManagerConfig
  * // @ typedef {import('./typedef-service-manager.js').ServiceRegistrationOptions} ServiceRegistrationOptions
- * 
+ *
  * const config = {
  *   environment: 'development',
  *   stopTimeout: 5000
  * };
- * 
+ *
  * const manager = new ServiceManager(config);
- * 
+ *
  * const options = {
  *   dependencies: ['database'],
  *   tags: ['critical']
  * };
- * 
+ *
  * manager.register('auth', AuthService, {}, options);
  */
 
@@ -30,13 +30,19 @@
 // PUBLIC TYPES
 // ============================================================================
 
+/**
+ * Service configuration - either a config object or a config label string
+ *
+ * @typedef {Object<string, *>|string} ServiceConfigOrLabel
+ */
+
 /**
  * Options for registering a service
  *
  * @typedef {Object} ServiceRegistrationOptions
  * @property {string[]} [dependencies=[]] - Services this service depends on
  * @property {string[]} [tags=[]] - Tags for grouping services
- * @property {number} [priority=0] - Startup priority (higher starts first)
+ * @property {number} [startupPriority=0] - Higher starts first
  */
 
 /**
@@ -70,6 +76,17 @@
  * @typedef {new (name: string, options?: import('../service-base/typedef.js').ServiceOptions) => import('../service-base/typedef.js').ServiceInstance} ServiceConstructor
  */
 
+/**
+ * ServiceManager plugin interface
+ *
+ * @typedef {Object} ServiceManagerPlugin
+ * @property {string} name - Unique plugin identifier
+ * @property {import('./ServiceManager.js').ServiceManager|null} manager - ServiceManager reference
+ * @property {function(import('./ServiceManager.js').ServiceManager): void} attach - Attach to ServiceManager
+ * @property {function(): void} detach - Detach from ServiceManager
+ * @property {function(string, ServiceEntry, *): Promise<*|undefined>} [resolveServiceConfig] - Optional config resolution method
+ */
+
 // ============================================================================
 // INTERNAL TYPES
 // ============================================================================
@@ -80,11 +97,11 @@
  * @typedef {Object} ServiceEntry
  * @property {ServiceConstructor} ServiceClass - Service class constructor
  * @property {import('../service-base/typedef.js').ServiceInstance|null} instance - Service instance (lazy-created)
- * @property {*} config - Service configuration
- * @property {string[]} dependencies - Service dependencies
- * @property {Set<string>} dependents - Services that depend on this one
- * @property {string[]} tags - Service tags
- * @property {number} priority - Startup priority
+ * @property {ServiceConfigOrLabel} serviceConfigOrLabel
+ * @property {string[]} dependencies
+ * @property {Set<string>} dependents - Services that depend on this service
+ * @property {string[]} tags
+ * @property {number} startupPriority - Startup priority
  */
 
 export {};