@hkdigital/lib-core 0.4.18 → 0.4.19

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

@@ -9,7 +9,7 @@
  * import { ServiceBase } from './ServiceBase.js';
  * 
  * class MyService extends ServiceBase {
- *   async _init(config) {
+ *   async _configure(newConfig, oldConfig) {
  *   }
  *   
  *   async _healthCheck() {
@@ -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

@@ -24,6 +24,23 @@ 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
      *
@@ -45,13 +62,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
      *

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';
 
 /**
@@ -88,6 +88,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,6 +116,43 @@ 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
    *
@@ -194,18 +234,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.#resolveConfig(name, entry);
+
+    return await instance.configure(config);
   }
 
   /**
@@ -240,10 +282,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 +435,6 @@ export class ServiceManager extends EventEmitter {
     return Object.fromEntries(results);
   }
 
-
   /**
    * Get health status for all services
    *
@@ -401,7 +450,7 @@ export class ServiceManager extends EventEmitter {
       } else {
         health[name] = {
           name,
-          state: NOT_CREATED,
+          state: STATE_NOT_CREATED,
           healthy: false
         };
       }
@@ -419,7 +468,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 +521,6 @@ export class ServiceManager extends EventEmitter {
     return services;
   }
 
-
   /**
    * Attach event listeners to forward service events
    *
@@ -503,6 +551,35 @@ 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 #resolveConfig(serviceName, serviceEntry) {
+    let config = serviceEntry.config;
+
+    // Let plugins resolve the config
+    for (const plugin of this.#plugins.values()) {
+      if (plugin._getServiceConfig) {
+        const resolved = await plugin._getServiceConfig(
+          serviceName,
+          serviceEntry,
+          config
+        );
+        if (resolved !== undefined) {
+          config = resolved;
+          break; // First plugin that resolves wins
+        }
+      }
+    }
+
+    return config || {};
+  }
+
   /**
    * Setup logging configuration based on config.dev
    */

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

@@ -69,6 +69,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
+     */
+    _getServiceConfig?: (arg0: string, arg1: ServiceEntry, arg2: any) => Promise<any | undefined>;
+};
 /**
  * Internal service registry entry
  */

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

@@ -70,6 +70,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>} [_getServiceConfig] - Optional config resolution method
+ */
+
 // ============================================================================
 // INTERNAL TYPES
 // ============================================================================

package/dist/services/service-manager-plugins/ConfigPlugin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Plugin that resolves service configuration from a configuration object
+ */
+export default class ConfigPlugin {
+    /**
+     * Create a new object configuration plugin
+     *
+     * @param {Object<string, *>} configObject - Pre-parsed configuration object
+     */
+    constructor(configObject: {
+        [x: string]: any;
+    });
+    /** @type {string} */
+    name: string;
+    /** @type {import('../service-manager/ServiceManager.js').ServiceManager|null} */
+    manager: import("../service-manager/ServiceManager.js").ServiceManager | null;
+    /** @type {Object<string, *>} */
+    configObject: {
+        [x: string]: any;
+    };
+    /**
+     * Resolve service configuration from the configuration object
+     *
+     * @param {string} serviceName - Name of the service being configured
+     * @param {import('../service-manager/typedef.js').ServiceEntry} serviceEntry
+     *   Service registration entry
+     * @param {*} currentConfig - Current config (could be object from previous plugins)
+     *
+     * @returns {Promise<Object|undefined>}
+     *   Resolved config object, or undefined to use currentConfig as-is
+     */
+    _getServiceConfig(serviceName: string, serviceEntry: import("../service-manager/typedef.js").ServiceEntry, currentConfig: any): Promise<any | undefined>;
+    /**
+     * Update the configuration object
+     *
+     * @param {Object<string, *>} newConfigObject - New configuration object
+     */
+    updateConfigObject(newConfigObject: {
+        [x: string]: any;
+    }): void;
+    /**
+     * Merge additional configuration into the existing object
+     *
+     * @param {Object<string, *>} additionalConfig - Additional configuration
+     */
+    mergeConfig(additionalConfig: {
+        [x: string]: any;
+    }): void;
+    /**
+     * Get the current configuration object
+     *
+     * @returns {Object<string, *>} Current configuration object
+     */
+    getConfigObject(): {
+        [x: string]: any;
+    };
+    /**
+     * Update config for a specific label and push to affected services
+     *
+     * @param {string} configLabel - Config label to update
+     * @param {*} newConfig - New configuration value
+     *
+     * @returns {Promise<string[]>} Array of service names that were updated
+     */
+    updateConfigLabel(configLabel: string, newConfig: any): Promise<string[]>;
+    /**
+     * Attach plugin to ServiceManager
+     *
+     * @param {import('../service-manager/ServiceManager.js').ServiceManager} manager
+     *   ServiceManager instance
+     */
+    attach(manager: import("../service-manager/ServiceManager.js").ServiceManager): void;
+    /**
+     * Detach plugin from ServiceManager
+     */
+    detach(): void;
+    #private;
+}

package/dist/services/service-manager-plugins/ConfigPlugin.js

@@ -0,0 +1,266 @@
+/**
+ * @fileoverview Object-based configuration plugin for ServiceManager
+ *
+ * Resolves service configuration from a pre-provided configuration object
+ * using config labels that map to object properties or prefixed keys.
+ *
+ * @example
+ * // Basic usage with config object
+ * import ConfigPlugin from './ConfigPlugin.js';
+ *
+ * const configObject = {
+ *   'database': { host: 'localhost', port: 5432 },
+ *   'auth': { secret: 'my-secret', algorithm: 'HS256' }
+ * };
+ *
+ * const objectPlugin = new ConfigPlugin(configObject);
+ * manager.attachPlugin(objectPlugin);
+ *
+ * @example
+ * // With environment variables using utility
+ * import { allEnv } from '../../util/sveltekit/env.js';
+ * import ConfigPlugin from './ConfigPlugin.js';
+ *
+ * const envConfig = await allEnv();
+ * const envPlugin = new ConfigPlugin(envConfig, {
+ *   prefixMap: {
+ *     'database': 'DATABASE',
+ *     'auth': 'JWT'
+ *   }
+ * });
+ *
+ * @example
+ * // Mixed configuration sources
+ * const mixedConfig = {
+ *   ...await allEnv(),
+ *   'custom-service': { specialOption: true },
+ *   'override-service': { host: 'custom-host' }
+ * };
+ * const mixedPlugin = new ConfigPlugin(mixedConfig);
+ */
+
+import { SERVICE_STATE_CHANGED } from '../service-manager/constants.js';
+
+/**
+ * Plugin that resolves service configuration from a configuration object
+ */
+export default class ConfigPlugin {
+
+  /** @type {Map<string, *>} */
+  #pendingConfigUpdates;
+
+  /**
+   * Create a new object configuration plugin
+   *
+   * @param {Object<string, *>} configObject - Pre-parsed configuration object
+   */
+  constructor(configObject) {
+    /** @type {string} */
+    this.name = 'object-config';
+
+    /** @type {import('../service-manager/ServiceManager.js').ServiceManager|null} */
+    this.manager = null;
+
+    /** @type {Object<string, *>} */
+    this.configObject = configObject || {};
+
+    this.#pendingConfigUpdates = new Map();
+  }
+
+  /**
+   * Resolve service configuration from the configuration object
+   *
+   * @param {string} serviceName - Name of the service being configured
+   * @param {import('../service-manager/typedef.js').ServiceEntry} serviceEntry
+   *   Service registration entry
+   * @param {*} currentConfig - Current config (could be object from previous plugins)
+   *
+   * @returns {Promise<Object|undefined>}
+   *   Resolved config object, or undefined to use currentConfig as-is
+   */
+  // eslint-disable-next-line no-unused-vars
+  async _getServiceConfig(serviceName, serviceEntry, currentConfig) {
+    // Only handle string config labels from original registration
+    if (typeof serviceEntry.config !== 'string') {
+      return undefined;
+    }
+
+    const configLabel = serviceEntry.config;
+
+    // Simple object lookup
+    const config = this.configObject[configLabel];
+
+    if (config !== undefined) {
+      this.manager?.logger?.debug(
+        `Resolved object config for '${serviceName}' (label: ${configLabel})`,
+        {
+          configKeys:
+            typeof config === 'object' ? Object.keys(config) : 'primitive'
+        }
+      );
+    }
+
+    return config;
+  }
+
+  /**
+   * Update the configuration object
+   *
+   * @param {Object<string, *>} newConfigObject - New configuration object
+   */
+  updateConfigObject(newConfigObject) {
+    this.configObject = newConfigObject || {};
+    this.manager?.logger?.debug('Updated configuration object');
+  }
+
+  /**
+   * Merge additional configuration into the existing object
+   *
+   * @param {Object<string, *>} additionalConfig - Additional configuration
+   */
+  mergeConfig(additionalConfig) {
+    this.configObject = { ...this.configObject, ...additionalConfig };
+    this.manager?.logger?.debug('Merged additional configuration');
+  }
+
+  /**
+   * Get the current configuration object
+   *
+   * @returns {Object<string, *>} Current configuration object
+   */
+  getConfigObject() {
+    return { ...this.configObject };
+  }
+
+  /**
+   * Update config for a specific label and push to affected services
+   *
+   * @param {string} configLabel - Config label to update
+   * @param {*} newConfig - New configuration value
+   *
+   * @returns {Promise<string[]>} Array of service names that were updated
+   */
+  async updateConfigLabel(configLabel, newConfig) {
+    // Update the config object
+    this.configObject[configLabel] = newConfig;
+
+    // Store as pending update
+    this.#pendingConfigUpdates.set(configLabel, newConfig);
+
+    const updatedServices = [];
+
+    // Find all services using this config label
+    for (const [serviceName, serviceEntry] of this.manager.services) {
+      if (serviceEntry.config === configLabel && serviceEntry.instance) {
+        try {
+          // Try to apply config - ServiceBase.configure() will handle state validation
+          await this.#applyConfigToService(serviceName, serviceEntry, newConfig);
+          updatedServices.push(serviceName);
+          
+          // Remove from pending since it was applied
+          this.#pendingConfigUpdates.delete(configLabel);
+        } catch (error) {
+          // If configure() fails due to invalid state, it will be retried later
+          this.manager.logger.debug(
+            `Could not update config for service '${serviceName}' (${error.message}), will retry when service state allows`
+          );
+        }
+      }
+    }
+
+    this.manager.logger.debug(
+      `Config label '${configLabel}' updated, applied to ${updatedServices.length} services immediately`
+    );
+
+    return updatedServices;
+  }
+
+
+  /**
+   * Apply configuration to a specific service
+   *
+   * @param {string} serviceName - Name of the service
+   * @param {import('../service-manager/typedef.js').ServiceEntry} serviceEntry
+   *   Service entry from manager
+   * @param {*} newConfig - New configuration to apply
+   */
+  async #applyConfigToService(serviceName, serviceEntry, newConfig) {
+    await serviceEntry.instance.configure(newConfig);
+
+    this.manager.logger.info(
+      `Updated config for service '${serviceName}'`
+    );
+  }
+
+  /**
+   * Process pending config updates for services that can now be configured
+   *
+   * @param {string} serviceName - Name of the service that changed state
+   * @param {import('../service-base/ServiceBase.js').default} serviceInstance
+   *   Service instance
+   */
+  async #processPendingUpdates(serviceName, serviceInstance) {
+    const serviceEntry = this.manager.services.get(serviceName);
+    if (!serviceEntry || typeof serviceEntry.config !== 'string') {
+      return;
+    }
+
+    const configLabel = serviceEntry.config;
+    if (this.#pendingConfigUpdates.has(configLabel)) {
+      const pendingConfig = this.#pendingConfigUpdates.get(configLabel);
+      
+      try {
+        await this.#applyConfigToService(serviceName, serviceEntry, pendingConfig);
+        this.#pendingConfigUpdates.delete(configLabel);
+        
+        this.manager.logger.info(
+          `Applied pending config update for service '${serviceName}' (label: ${configLabel})`
+        );
+      } catch (error) {
+        this.manager.logger.debug(
+          `Could not apply pending config for service '${serviceName}': ${error.message}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Attach plugin to ServiceManager
+   *
+   * @param {import('../service-manager/ServiceManager.js').ServiceManager} manager
+   *   ServiceManager instance
+   */
+  attach(manager) {
+    if (this.manager) {
+      throw new Error(
+        `Plugin '${this.name}' is already attached to a ServiceManager`
+      );
+    }
+
+    this.manager = manager;
+
+    const configKeys = Object.keys(this.configObject).length;
+
+    this.manager.logger.info(
+      `ConfigPlugin attached with ${configKeys} config keys`
+    );
+
+    // Listen for service state changes to process pending updates
+    this.manager.on(SERVICE_STATE_CHANGED, async ({ service, state, instance }) => {
+      await this.#processPendingUpdates(service, instance);
+    });
+  }
+
+  /**
+   * Detach plugin from ServiceManager
+   */
+  detach() {
+    if (this.manager) {
+      // Clear pending updates
+      this.#pendingConfigUpdates.clear();
+      
+      this.manager.logger.info('ConfigPlugin detached');
+      this.manager = null;
+    }
+  }
+}