@hkdigital/lib-core 0.5.92 → 0.5.93

package/dist/services/README.md

@@ -1,19 +1,37 @@
 # Services
 
-A comprehensive service management system providing standardized lifecycle management, health monitoring, and dependency orchestration for application services.
+A comprehensive service management system providing standardized
+lifecycle management, health monitoring, and dependency orchestration
+for application services.
+
+**See also:**
+- **Architecture**: [docs/setup/services-logging.md](../../docs/setup/services-logging.md)
+  - How services and logging work together
+- **Patterns**: [PATTERNS.md](./PATTERNS.md) - Service access patterns
+  and best practices
+- **Plugins**: [PLUGINS.md](./PLUGINS.md) - ConfigPlugin and plugin
+  system
+- **Logging**: [src/lib/logging/README.md](../logging/README.md) -
+  Logging system integration
+- **Main README**: [README.md](../../README.md) - Library overview and
+  setup
 
 ## Overview
 
 The services module provides two main components:
 
-- **ServiceBase** - Base class for implementing services with lifecycle management
-- **ServiceManager** - Orchestrates multiple services with dependency resolution
+- **ServiceBase** - Base class for implementing services with lifecycle
+  management
+- **ServiceManager** - Orchestrates multiple services with dependency
+  resolution
 
-All services follow a standardized state machine with proper error handling, logging, and health monitoring.
+All services follow a standardized state machine with proper error
+handling, logging, and health monitoring.
 
-## Service states
+## Service States
 
-Services transition through these states during their lifecycle. Use these constants from `$lib/services/service-base/constants.js`:
+Services transition through these states during their lifecycle. Use
+these constants from `$lib/services/service-base/constants.js`:
 
 - `STATE_CREATED` - Service instantiated but not configured
 - `STATE_CONFIGURING` - Currently running configuration
@@ -42,7 +60,8 @@ if (service.state === STATE_RUNNING) {
 
 Base class that all services should extend. Provides:
 
-- Standardized lifecycle methods (`configure`, `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
@@ -59,19 +78,17 @@ class DatabaseService extends ServiceBase {
   async _configure(newConfig, oldConfig = null) {
     if (!oldConfig) {
       // Initial configuration
-
       this.connectionString = newConfig.connectionString;
       this.maxConnections = newConfig.maxConnections || 10;
       return;
     }
 
+    // Reconfiguration - handle changes intelligently
     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);
       }
@@ -79,7 +96,6 @@ class DatabaseService extends ServiceBase {
 
     if (oldConfig.maxConnections !== newConfig.maxConnections) {
       // Pool size changed - update without reconnect
-      //
       this.maxConnections = newConfig.maxConnections;
       await this.connection?.setMaxConnections(this.maxConnections);
     }
@@ -122,16 +138,23 @@ await db.configure({
 
 ### Protected Methods to Override
 
-- `_configure(newConfig, oldConfig = null)` - Configure service (handles both initial setup and reconfiguration)
+Implement these methods to define service behavior:
+
+- `_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)
 - `_recover()` - Custom recovery logic (optional)
 - `_healthCheck()` - Return health status (optional)
 
-### Service events
+**See [PATTERNS.md](./PATTERNS.md) for implementation patterns and best
+practices.**
+
+### Service Events
 
-ServiceBase emits these events (constants from `$lib/services/service-base/constants.js`):
+ServiceBase emits these events (constants from
+`$lib/services/service-base/constants.js`):
 
 - `EVENT_STATE_CHANGED` - Service state transitions
 - `EVENT_TARGET_STATE_CHANGED` - Target state changes
@@ -139,7 +162,8 @@ ServiceBase emits these events (constants from `$lib/services/service-base/const
 - `EVENT_ERROR` - Service errors
 
 ```javascript
-import { EVENT_STATE_CHANGED } from '$lib/services/service-base/constants.js';
+import { EVENT_STATE_CHANGED }
+  from '$lib/services/service-base/constants.js';
 
 service.on(EVENT_STATE_CHANGED, ({ state, previousState }) => {
   console.log(`Service transitioned from ${previousState} to ${state}`);
@@ -148,7 +172,8 @@ service.on(EVENT_STATE_CHANGED, ({ state, previousState }) => {
 
 ## ServiceManager
 
-Manages multiple services with dependency resolution and coordinated lifecycle operations.
+Manages multiple services with dependency resolution and coordinated
+lifecycle operations.
 
 ### Features
 
@@ -160,7 +185,7 @@ Manages multiple services with dependency resolution and coordinated lifecycle o
 - Service recovery management
 - Plugin system for extending configuration resolution
 
-### Usage
+### Basic Usage
 
 ```javascript
 import { ServiceManager } from '@hkdigital/lib-core/services/index.js';
@@ -199,121 +224,63 @@ const health = await manager.checkHealth();
 await manager.stopAll();
 ```
 
-### Service Access Patterns
-
-Services receive helpful utilities in their constructor options for accessing other services:
+### Service Registration
 
 ```javascript
-/**
- * Example service that depends on other services
- */
-class AuthService extends ServiceBase {
-  /** @type {(<T>(serviceName: string) => T)} */
-  #getService;
+manager.register(name, ServiceClass, serviceConfigOrLabel, options);
+```
+
+**Parameters:**
+- `name` - Unique service identifier
+- `ServiceClass` - Class extending ServiceBase
+- `serviceConfigOrLabel` - Service configuration object
+  (`Object<string, *>`) or config label string (when using ConfigPlugin)
+- `options.dependencies` - Array of service names this service depends
+  on
+- `options.startupPriority` - Higher priority services start first
+  (default: 0)
 
-  /** @type {() => import('@hkdigital/lib-core/services/index.js').ServiceManager} */
-  #getManager;
+### Service Access
 
-  constructor(serviceName, options) {
-    super(serviceName, options);
-    
-    // Store service access utilities as private methods
-    this.#getService = options.getService;   // Bound getService function
-    this.#getManager = options.getManager;   // Function to get manager (lazy)
-  }
-  
-  async authenticateUser(credentials) {
-    // Access other services with full type safety and error checking
-    const database = this.#getService('database');
-    const user = await database.findUser(credentials.username);
-    
-    // Access manager for advanced operations when needed
-    const manager = this.#getManager();
-    const health = await manager.checkHealth();
-    
-    return user;
-  }
-}
-```
+ServiceManager provides methods to access registered services:
 
-**Best Practice Pattern:**
+```javascript
+// Permissive - returns undefined if not found/created
+const service = manager.get('optional-service');
+if (service) {
+  // Use service safely
+}
 
-The recommended approach is to store service access functions as **private methods** using the hash prefix. This pattern:
+// Strict - throws error if not found/created
+const service = manager.getService('required-service');
+```
 
-- **Keeps the API clean** - No public getService/getManager methods exposed
-- **Prevents serialization issues** - Private fields don't serialize to JSON
-- **Enforces proper encapsulation** - Service dependencies stay internal
-- **Provides type safety** - Full generic support with `this.#getService<DatabaseService>('database')`
+**Within services**, use constructor utilities for type-safe access:
 
 ```javascript
-/**
- * Unified service for tracking complete player data including progress and 
- * profile matches
- */
-export default class PlayerService extends ServiceBase {
-  
+class AuthService extends ServiceBase {
   /** @type {(<T>(serviceName: string) => T)} */
   #getService;
 
-  /**
-   * @param {string} serviceName
-   * @param {import('@hkdigital/lib-core/services/typedef.js').ServiceOptions} [options]
-   */
   constructor(serviceName, options) {
     super(serviceName, options);
-
-    this.#getService = options?.getService;
+    this.#getService = options.getService;
   }
 
-  async getPlayerProfile(playerId) {
-    // Access dependent services cleanly
+  async authenticate(credentials) {
     const database = this.#getService('database');
-    const analytics = this.#getService('analytics');
-    
-    const profile = await database.getPlayer(playerId);
-    const stats = await analytics.getPlayerStats(playerId);
-    
-    return { ...profile, stats };
+    return await database.findUser(credentials.username);
   }
 }
 ```
 
-**Service Access Methods:**
-
-```javascript
-// ServiceManager provides two access patterns:
-
-// 1. Permissive - returns undefined if not found/created
-const service = manager.get('optional-service');
-if (service) {
-  // Use service safely
-}
-
-// 2. Strict - throws error if not found/created  
-const service = manager.getService('required-service'); // Throws if missing
-```
-
-**Benefits of constructor utilities:**
-
-- **Lightweight** - Functions don't serialize, keeping services serialization-safe
-- **Lazy access** - Manager is only accessed when needed
-- **Type safety** - Full generic support with `getService<DatabaseService>('database')`
-- **Error handling** - Clear errors when services are missing
-
-### Service Registration
-
-```javascript
-manager.register(name, ServiceClass, serviceConfigOrLabel, options);
-```
-
-- `name` - Unique service identifier
-- `ServiceClass` - Class extending ServiceBase
-- `serviceConfigOrLabel` - Service configuration object (`Object<string, *>`) or config label string
-- `options.dependencies` - Array of service names this service depends on
-- `options.startupPriority` - Higher priority services start first (default: 0)
+**See [PATTERNS.md](./PATTERNS.md) for detailed service access
+patterns.**
 
 ### Health Monitoring
 
+Monitor service health individually or system-wide:
+
 ```javascript
 import {
   SERVICE_HEALTH_CHANGED,
@@ -338,6 +305,21 @@ const systemHealth = await manager.checkHealth();
 
 ### Error Handling and Recovery
 
+ServiceManager provides automatic error handling and recovery:
+
+```javascript
+// Listen for service errors
+manager.on(SERVICE_ERROR, async ({ service, error }) => {
+  console.log(`Service ${service} failed:`, error.message);
+
+  // Attempt automatic recovery
+  await manager.recoverService(service);
+});
+
+// Manual recovery
+await manager.recoverService('database');
+```
+
 ### Logging Configuration
 
 ServiceManager provides centralized logging control for all services:
@@ -369,31 +351,19 @@ manager.setServiceLogLevel({
 manager.setServiceLogLevel('database:info,auth:debug');
 ```
 
-### ServiceManager events
+### ServiceManager Events
 
-ServiceManager emits these events (constants from `$lib/services/service-manager/constants.js`):
+ServiceManager emits these events (constants from
+`$lib/services/service-manager/constants.js`):
 
 - `SERVICE_STATE_CHANGED` - Service state changes
 - `SERVICE_HEALTH_CHANGED` - Service health changes
 - `SERVICE_ERROR` - Service errors
 - `SERVICE_LOG` - Service log messages
 
-```javascript
-// Listen for service errors
-manager.on(SERVICE_ERROR, async ({ service, error }) => {
-  console.log(`Service ${service} failed:`, error.message);
-
-  // Attempt automatic recovery
-  await manager.recoverService(service);
-});
-
-// Manual recovery
-await manager.recoverService('database');
-```
-
 ### Log Event Forwarding
 
-Forward all service log events to a centralised logger:
+Forward all service log events to a centralized logger:
 
 ```javascript
 import { ServiceManager } from '$lib/services/index.js';
@@ -417,149 +387,106 @@ await manager.startAll();
 unsubscribe();
 ```
 
+**See [docs/setup/services-logging.md](../../docs/setup/services-logging.md)
+for complete integration examples.**
+
 ## Plugins
 
-ServiceManager supports plugins e.g. to resolve service configurations dynamically.
+ServiceManager supports plugins to extend functionality, primarily for
+dynamic configuration resolution.
 
 ### 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
+The most common plugin for resolving service configuration from
+environment variables or config files:
 
 ```javascript
 import { ServiceManager } from '$lib/services/index.js';
-
 import ConfigPlugin from '$lib/services/manager-plugins/ConfigPlugin.js';
-
 import { getPrivateEnv } from '$lib/util/sveltekit/env-private.js';
 
-// Load and auto-group environment variables
+// Load environment config
 const envConfig = getPrivateEnv();
-//
-// Example:
-//
-// DATABASE_HOST=localhost
-// DATABASE_PORT=5432
-// DATABASE_NAME=myapp
-// REDIS_HOST=cache-server
-// REDIS_PORT=6379
-// JWT_SECRET=mysecret
-// =>
-// {
-//   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
+// Create and attach plugin
+const configPlugin = new ConfigPlugin(envConfig);
 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
+manager.register('database', DatabaseService, 'database');
+manager.register('cache', RedisService, 'redis');
 
 await manager.startAll();
+
+// Hot-reload configuration
+await configPlugin.replaceConfig('database', newDatabaseConfig);
 ```
 
-#### Configuration
+**See [PLUGINS.md](./PLUGINS.md) for complete plugin documentation and
+live configuration updates.**
 
-The plugin constructor accepts an object with configuration data, which can come from any source. E.g. the environment or a configuration file.
+## Quick Reference
 
-```javascript
-// Combine multiple config sources
-const config = {
-  ...getPrivateEnv(), // Environment variables
-  ...(await loadConfigFile()), // Config file
-  database: {
-    // Override specific settings
-    ...envConfig.database,
-    connectionTimeout: 5000
-  }
-};
+### Service Lifecycle
 
-const plugin = new ConfigPlugin(config);
+```
+created → configuring → configured → starting → running
+                                                    ↓
+                                                 stopping → stopped → destroying → destroyed
+                                                    ↓
+                                                  error ← → recovering
 ```
 
-### Methods
+### Common Operations
 
 ```javascript
-// Replace all configurations and clean up unused ones
-await configPlugin.replaceAllConfigs(newConfig);
-
-// Replace configuration for a specific label
-await configPlugin.replaceConfig('database', newDatabaseConfig);
-
-// Clean up configurations not used by any service
-await configPlugin.cleanupConfigs();
-```
+// Create and start service
+const service = new MyService('my-service');
+await service.configure(config);
+await service.start();
 
-### Live Configuration Updates
+// Check health
+const health = await service.healthCheck();
 
-The ConfigPlugin supports pushing configuration updates to running services:
+// Reconfigure
+await service.configure(newConfig);
 
-```javascript
-// Replace config for a specific label and notify all affected services
-const updatedServices = await configPlugin.replaceConfig('database', {
-  host: 'new-host.example.com',
-  port: 5433,
-  maxConnections: 50
-});
+// Stop service
+await service.stop();
 
-// Returns array of service names that were updated: ['user-service', 'order-service']
-console.log(`Updated ${updatedServices.length} services`);
+// Destroy service
+await service.destroy();
 ```
 
-#### 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
+### ServiceManager Operations
 
 ```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;
-    }
+// Register services
+manager.register('name', ServiceClass, config, options);
 
-    // Live reconfiguration - handle changes intelligently
-    if (oldConfig.connectionString !== newConfig.connectionString) {
-      // Connection changed - need to reconnect
-      await this.connection?.close();
-      this.connectionString = newConfig.connectionString;
+// Lifecycle
+await manager.startAll();
+await manager.stopAll();
+await manager.destroyAll();
 
-      if (this.state === 'running') {
-        this.connection = await createConnection(this.connectionString);
-      }
-    }
+// Access
+const service = manager.get('name');
+const service = manager.getService('name'); // Throws if missing
 
-    if (oldConfig.maxConnections !== newConfig.maxConnections) {
-      // Pool size changed - update without reconnect
-      this.maxConnections = newConfig.maxConnections;
-      await this.connection?.setMaxConnections(this.maxConnections);
-    }
-  }
-}
+// Health
+const health = await manager.checkHealth();
+const serviceHealth = await manager.getServiceHealth('name');
+
+// Recovery
+await manager.recoverService('name');
 ```
 
-## Best Practices
+## Next Steps
 
-1. **Always extend ServiceBase** for consistent lifecycle management
-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
-6. **Handle errors gracefully** and implement recovery where appropriate
-7. **Use descriptive service names** for better logging and debugging
+- **Patterns**: See [PATTERNS.md](./PATTERNS.md) for service access
+  patterns, configuration patterns, and best practices
+- **Plugins**: See [PLUGINS.md](./PLUGINS.md) for ConfigPlugin and
+  custom plugins
+- **Architecture**: See [docs/setup/services-logging.md](../../docs/setup/services-logging.md)
+  for integration with logging and SvelteKit hooks

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.92",
+	"version": "0.5.93",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"