@hkdigital/lib-core 0.4.18 → 0.4.19

package/dist/services/README.md

@@ -15,9 +15,9 @@ All services follow a standardized state machine with proper error handling, log
 
 Services transition through these states during their lifecycle:
 
-- `created` - Service instantiated but not initialized
-- `initializing` - Currently running initialization
-- `initialized` - Ready to start
+- `created` - Service instantiated but not configured
+- `configuring` - Currently running configuration
+- `configured` - Ready to start
 - `starting` - Currently starting up
 - `running` - Operational and healthy
 - `stopping` - Currently shutting down
@@ -31,7 +31,8 @@ Services transition through these states during their lifecycle:
 
 Base class that all services should extend. Provides:
 
-- Standardized lifecycle methods (`initialize`, `start`, `stop`, `destroy`)
+- Standardized lifecycle methods (`configure`, `start`, `stop`, `destroy`)
+- Flexible configuration system with reconfiguration support
 - Health monitoring and recovery
 - Event emission for state changes
 - Integrated logging
@@ -43,8 +44,35 @@ Base class that all services should extend. Provides:
 import { ServiceBase } from '$lib/services/index.js';
 
 class DatabaseService extends ServiceBase {
-  async _init(config) {
-    this.connectionString = config.connectionString;
+  // eslint-disable-next-line no-unused-vars
+  async _configure(newConfig, oldConfig = null) {
+
+    if (!oldConfig) {
+      // Initial configuration
+
+      this.connectionString = newConfig.connectionString;
+      this.maxConnections = newConfig.maxConnections || 10;
+      return;
+    }
+
+    if (oldConfig.connectionString !== newConfig.connectionString) {
+      // Reconfiguration - handle changes intelligently
+
+      // Connection changed - need to reconnect
+      await this.connection?.close();
+
+      this.connectionString = newConfig.connectionString;
+      if (this.state === 'running') {
+        this.connection = await createConnection(this.connectionString);
+      }
+    }
+
+    if (oldConfig.maxConnections !== newConfig.maxConnections) {
+      // Pool size changed - update without reconnect
+      //
+      this.maxConnections = newConfig.maxConnections;
+      await this.connection?.setMaxConnections(this.maxConnections);
+    }
   }
 
   async _start() {
@@ -64,18 +92,27 @@ class DatabaseService extends ServiceBase {
 
 // Usage
 const db = new DatabaseService('database');
-await db.initialize({ connectionString: 'postgres://...' });
+await db.configure({
+  connectionString: 'postgres://localhost/myapp',
+  maxConnections: 20
+});
 await db.start();
 
 // Listen to events
 db.on('healthChanged', ({ healthy }) => {
   console.log(`Database is ${healthy ? 'healthy' : 'unhealthy'}`);
 });
+
+// Reconfigure at runtime
+await db.configure({
+  connectionString: 'postgres://localhost/myapp',
+  maxConnections: 50  // Hot-reloaded without restart
+});
 ```
 
 ### Protected Methods to Override
 
-- `_init(config)` - Initialize service with configuration
+- `_configure(newConfig, oldConfig = null)` - Configure service (handles both initial setup and reconfiguration)
 - `_start()` - Start the service
 - `_stop()` - Stop the service
 - `_destroy()` - Clean up resources (optional)
@@ -100,6 +137,7 @@ Manages multiple services with dependency resolution and coordinated lifecycle o
 - Health monitoring for all services
 - Centralized logging control
 - Service recovery management
+- Plugin system for extending configuration resolution
 
 ### Usage
 
@@ -177,10 +215,197 @@ manager.on('service:error', async ({ service, error }) => {
 await manager.recoverService('database');
 ```
 
+## Configuration Plugins
+
+ServiceManager supports plugins that can resolve service configuration dynamically. This is particularly useful for environment-based configuration.
+
+### ConfigPlugin
+
+The most common plugin for resolving service configuration from a pre-parsed configuration object. Perfect for environment variables, config files, or any structured configuration source.
+
+#### Basic Usage with Environment Variables
+
+```javascript
+import { ServiceManager } from '$lib/services/index.js';
+import ConfigPlugin from '$lib/services/service-manager-plugins/ConfigPlugin.js';
+import { getPrivateEnv } from '$lib/util/sveltekit/env-private.js';
+
+// Load and auto-group environment variables
+const envConfig = getPrivateEnv();
+// Example result:
+// {
+//   database: { host: 'localhost', port: 5432, name: 'myapp' },
+//   redis: { host: 'cache-server', port: 6379 },
+//   jwtSecret: 'mysecret'
+// }
+
+// Create plugin with grouped config
+const configPlugin = new ConfigPlugin(envConfig);
+
+// Attach to ServiceManager
+const manager = new ServiceManager();
+manager.attachPlugin(configPlugin);
+
+// Register services with config labels (not config objects)
+manager.register('database', DatabaseService, 'database');  // Uses envConfig.database
+manager.register('cache', RedisService, 'redis');           // Uses envConfig.redis
+
+await manager.startAll();
+```
+
+#### Environment Variable Grouping
+
+The environment utilities automatically group related variables by prefix:
+
+```bash
+# Environment variables:
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_NAME=myapp
+REDIS_HOST=cache-server
+REDIS_PORT=6379
+JWT_SECRET=mysecret
+SINGLE_FLAG=true
+```
+
+```javascript
+const envConfig = getPrivateEnv();
+// Auto-groups into:
+// {
+//   database: { host: 'localhost', port: 5432, name: 'myapp' },
+//   redis: { host: 'cache-server', port: 6379 },
+//   jwtSecret: 'mysecret',
+//   singleFlag: true
+// }
+```
+
+#### Advanced Configuration Sources
+
+```javascript
+// Combine multiple config sources
+const config = {
+  ...getPrivateEnv(),              // Environment variables
+  ...await loadConfigFile(),       // Config file
+  database: {                      // Override specific settings
+    ...envConfig.database,
+    connectionTimeout: 5000
+  }
+};
+
+const plugin = new ConfigPlugin(config);
+```
+
+#### Plugin Benefits
+
+1. **Simple Service Registration** - Use string labels instead of complex config objects
+2. **Environment Integration** - Seamless SvelteKit environment variable integration
+3. **Dynamic Configuration** - Update config object for live updates
+4. **Clear Separation** - Configuration logic separate from service logic
+5. **Extensible** - Easy to add custom configuration sources
+
+#### Available Environment Utilities
+
+```javascript
+// Server-side only (private + public env vars)
+import { getAllEnv } from '$lib/util/sveltekit/env-all.js';
+const config = getAllEnv();
+
+// Server-side only (private env vars only)
+import { getPrivateEnv } from '$lib/util/sveltekit/env-private.js';
+const config = getPrivateEnv();
+
+// Client + server safe (public env vars only)  
+import { getPublicEnv } from '$lib/util/sveltekit/env-public.js';
+const config = getPublicEnv();
+```
+
+### Plugin Methods
+
+```javascript
+// Update configuration at runtime
+configPlugin.updateConfigObject(newConfig);
+
+// Merge additional configuration
+configPlugin.mergeConfig({ additionalSettings: true });
+
+// Get current configuration
+const currentConfig = configPlugin.getConfigObject();
+```
+
+### Live Configuration Updates
+
+The ConfigPlugin supports pushing configuration updates to running services:
+
+```javascript
+// Update config for a specific label and notify all affected services
+const updatedServices = await configPlugin.updateConfigLabel('database', {
+  host: 'new-host.example.com',
+  port: 5433,
+  maxConnections: 50
+});
+
+// Returns array of service names that were updated: ['user-service', 'order-service']
+console.log(`Updated ${updatedServices.length} services`);
+```
+
+#### How Live Updates Work
+
+1. **Updates the plugin's config object** for the specified label
+2. **Finds all running services** that use that config label  
+3. **Calls `_configure(newConfig, oldConfig)`** on each service instance
+4. **Updates the resolved config** stored in the ServiceManager
+5. **Returns the list** of successfully updated service names
+6. **Handles errors gracefully** with detailed logging
+
+#### Service Requirements for Live Updates
+
+For services to support live configuration updates, they must:
+
+1. **Implement intelligent `_configure()` logic** that can handle both initial setup and reconfiguration
+2. **Check for meaningful changes** between old and new config
+3. **Apply changes without full restart** when possible
+
+```javascript
+class DatabaseService extends ServiceBase {
+  // eslint-disable-next-line no-unused-vars
+  async _configure(newConfig, oldConfig = null) {
+    if (!oldConfig) {
+      // Initial configuration
+      this.connectionString = newConfig.connectionString;
+      this.maxConnections = newConfig.maxConnections || 10;
+      return;
+    }
+
+    // Live reconfiguration - handle changes intelligently
+    if (oldConfig.connectionString !== newConfig.connectionString) {
+      // Connection changed - need to reconnect
+      await this.connection?.close();
+      this.connectionString = newConfig.connectionString;
+      
+      if (this.state === 'running') {
+        this.connection = await createConnection(this.connectionString);
+      }
+    }
+
+    if (oldConfig.maxConnections !== newConfig.maxConnections) {
+      // Pool size changed - update without reconnect
+      this.maxConnections = newConfig.maxConnections;
+      await this.connection?.setMaxConnections(this.maxConnections);
+    }
+  }
+}
+```
+
+This enables powerful scenarios like:
+- **Runtime environment updates** without service restarts
+- **A/B testing configuration changes** with instant rollback
+- **Dynamic scaling** based on load conditions
+- **Configuration management systems** that push updates to running applications
+
 ## Best Practices
 
 1. **Always extend ServiceBase** for consistent lifecycle management
-2. **Keep initialization lightweight** - heavy work should be in `_start()`
+2. **Keep configuration lightweight** - heavy work should be in `_start()`
 3. **Implement proper cleanup** in `_stop()` to prevent resource leaks
 4. **Use health checks** for monitoring critical service functionality
 5. **Declare dependencies explicitly** when registering with ServiceManager

package/dist/services/service-base/ServiceBase.d.ts

@@ -1,8 +1,7 @@
 /**
- * @typedef {import('./typedef.js').ServiceOptions} ServiceOptions
- * @typedef {import('./typedef.js').StopOptions} StopOptions
- * @typedef {import('./typedef.js').HealthStatus} HealthStatus
+ * @typedef {import('./typedef.js').ServiceState} ServiceState
  * @typedef {import('./typedef.js').StateChangeEvent} StateChangeEvent
+ * @typedef {import('./typedef.js').TargetStateChangeEvent} TargetStateChangeEvent
  * @typedef {import('./typedef.js').HealthChangeEvent} HealthChangeEvent
  * @typedef {import('./typedef.js').ServiceErrorEvent} ServiceErrorEvent
  */
@@ -15,13 +14,15 @@ export class ServiceBase extends EventEmitter {
      * Create a new service instance
      *
      * @param {string} name - Service name
-     * @param {ServiceOptions} [options={}] - Service options
+     * @param {import('./typedef.js').ServiceOptions} [options={}] - Service options
      */
-    constructor(name: string, options?: ServiceOptions);
+    constructor(name: string, options?: import("./typedef.js").ServiceOptions);
     /** @type {string} */
     name: string;
-    /** @type {string} */
-    state: string;
+    /** @type {ServiceState} */
+    state: ServiceState;
+    /** @type {ServiceState} */
+    targetState: ServiceState;
     /** @type {boolean} */
     healthy: boolean;
     /** @type {Error|null} */
@@ -31,13 +32,13 @@ export class ServiceBase extends EventEmitter {
     /** @private @type {number} */
     private _shutdownTimeout;
     /**
-     * Initialize the service with configuration
+     * Configure the service with configuration
      *
      * @param {*} [config={}] - Service-specific configuration
      *
-     * @returns {Promise<boolean>} True if initialization succeeded
+     * @returns {Promise<boolean>} True if configuration succeeded
      */
-    initialize(config?: any): Promise<boolean>;
+    configure(config?: any): Promise<boolean>;
     /**
      * Start the service
      *
@@ -47,11 +48,11 @@ export class ServiceBase extends EventEmitter {
     /**
      * Stop the service with optional timeout
      *
-     * @param {StopOptions} [options={}] - Stop options
+     * @param {import('./typedef.js').StopOptions} [options={}] - Stop options
      *
      * @returns {Promise<boolean>} True if the service stopped successfully
      */
-    stop(options?: StopOptions): Promise<boolean>;
+    stop(options?: import("./typedef.js").StopOptions): Promise<boolean>;
     /**
      * Recover the service from error state
      *
@@ -67,9 +68,10 @@ export class ServiceBase extends EventEmitter {
     /**
      * Get the current health status of the service
      *
-     * @returns {Promise<HealthStatus>} Health status object
+     * @returns {Promise<import('./typedef.js').HealthStatus>}
+     *   Health status object
      */
-    getHealth(): Promise<HealthStatus>;
+    getHealth(): Promise<import("./typedef.js").HealthStatus>;
     /**
      * Set the service log level
      *
@@ -79,14 +81,38 @@ export class ServiceBase extends EventEmitter {
      */
     setLogLevel(level: string): boolean;
     /**
-     * Initialize the service (override in subclass)
+     * Configure the service (handles both initial config and reconfiguration)
      *
      * @protected
-     * @param {*} config - Service configuration
+     * @param {any} newConfig - Configuration to apply
+     * @param {any} [oldConfig=null] - Previous config (null = initial setup)
      *
      * @returns {Promise<void>}
-     */
-    protected _init(config: any): Promise<void>;
+     *
+     * @remarks
+     * This method is called both for initial setup and reconfiguration.
+     * When oldConfig is provided, you should:
+     * 1. Compare oldConfig vs newConfig to determine changes
+     * 2. Clean up resources that need replacing
+     * 3. Apply only the changes that are necessary
+     * 4. Preserve resources that don't need changing
+     *
+     * @example
+     * async _configure(newConfig, oldConfig = null) {
+     *   if (!oldConfig) {
+     *     // Initial setup
+     *     this.connection = new Connection(newConfig.url);
+     *     return;
+     *   }
+     *
+     *   // Reconfiguration
+     *   if (oldConfig.url !== newConfig.url) {
+     *     await this.connection.close();
+     *     this.connection = new Connection(newConfig.url);
+     *   }
+     * }
+     */
+    protected _configure(newConfig: any, oldConfig?: any): Promise<void>;
     /**
      * Start the service (override in subclass)
      *
@@ -131,14 +157,24 @@ export class ServiceBase extends EventEmitter {
      * Set the service state and emit event
      *
      * @private
-     * @param {string} newState - New state value
+     * @param {ServiceState} newState - New state value
+     * @emits {StateChangeEvent} EVENT_STATE_CHANGED
      */
     private _setState;
+    /**
+     * Set the service target state and emit event
+     *
+     * @private
+     * @param {ServiceState} newTargetState - New target state value
+     * @emits {TargetStateChangeEvent} EVENT_TARGET_STATE_CHANGED
+     */
+    private _setTargetState;
     /**
      * Set the health status and emit event if changed
      *
      * @private
      * @param {boolean} healthy - New health status
+     * @emits {HealthChangeEvent} EVENT_HEALTH_CHANGED
      */
     private _setHealthy;
     /**
@@ -147,14 +183,15 @@ export class ServiceBase extends EventEmitter {
      * @private
      * @param {string} operation - Operation that failed
      * @param {Error} error - Error that occurred
+     * @emits {ServiceErrorEvent} EVENT_ERROR
      */
     private _setError;
+    #private;
 }
 export default ServiceBase;
-export type ServiceOptions = import("./typedef.js").ServiceOptions;
-export type StopOptions = import("./typedef.js").StopOptions;
-export type HealthStatus = import("./typedef.js").HealthStatus;
+export type ServiceState = import("./typedef.js").ServiceState;
 export type StateChangeEvent = import("./typedef.js").StateChangeEvent;
+export type TargetStateChangeEvent = import("./typedef.js").TargetStateChangeEvent;
 export type HealthChangeEvent = import("./typedef.js").HealthChangeEvent;
 export type ServiceErrorEvent = import("./typedef.js").ServiceErrorEvent;
 import { EventEmitter } from '../../generic/events.js';