@hkdigital/lib-core 0.4.37 → 0.4.39

package/dist/logging/internal/adapters/console.js

@@ -382,19 +382,22 @@ export class ConsoleAdapter {
       );
 
       // Clean up pnpm paths - convert complex pnpm paths to simple package names
-      // Before: functionName@node_modules/.pnpm/package+name@version_deps.../node_modules/package/dist/...
+      // Before: functionName@node_modules/.pnpm/package+name@version_deps.../node_modules/package/dist/...  
       // After: functionName@package/dist/...
       cleaned = cleaned.replace(
         /node_modules\/\.pnpm\/[^\/]+@[^_]+[^\/]*\/node_modules\/(@[^\/]+\/[^\/]+|[^\/]+)\//g,
         '$1/'
       );
 
-      // Clean up regular node_modules paths - convert to simple package names
+      // Clean up regular node_modules paths - convert to simple package names  
       cleaned = cleaned.replace(
         /node_modules\/(@[^\/]+\/[^\/]+|[^\/]+)\//g,
         '$1/'
       );
 
+      // Fix double @@ that can occur from the above replacements
+      cleaned = cleaned.replace(/@@/g, '@');
+
       // Clean up query parameters on source files
       cleaned = cleaned.replace(/\?[tv]=[a-f0-9]+/g, '');
 

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

@@ -36,11 +36,11 @@ export class ServiceBase extends EventEmitter {
      *
      * @param {Object<string,any>|null} [config={}]
      *
-     * @returns {Promise<boolean>} True if configuration succeeded
+     * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
      */
     configure(config?: {
         [x: string]: any;
-    } | null): Promise<boolean>;
+    } | null): Promise<import("./typedef.js").OperationResult>;
     /**
      * Get the last applied config
      *
@@ -52,29 +52,29 @@ export class ServiceBase extends EventEmitter {
     /**
      * Start the service
      *
-     * @returns {Promise<boolean>} True if the service started successfully
+     * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
      */
-    start(): Promise<boolean>;
+    start(): Promise<import("./typedef.js").OperationResult>;
     /**
      * Stop the service with optional timeout
      *
      * @param {import('./typedef.js').StopOptions} [options={}] - Stop options
      *
-     * @returns {Promise<boolean>} True if the service stopped successfully
+     * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
      */
-    stop(options?: import("./typedef.js").StopOptions): Promise<boolean>;
+    stop(options?: import("./typedef.js").StopOptions): Promise<import("./typedef.js").OperationResult>;
     /**
      * Recover the service from error state
      *
-     * @returns {Promise<boolean>} True if recovery succeeded
+     * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
      */
-    recover(): Promise<boolean>;
+    recover(): Promise<import("./typedef.js").OperationResult>;
     /**
      * Destroy the service and cleanup resources
      *
-     * @returns {Promise<boolean>} True if destruction succeeded
+     * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
      */
-    destroy(): Promise<boolean>;
+    destroy(): Promise<import("./typedef.js").OperationResult>;
     /**
      * Get the current health status of the service
      *
@@ -85,11 +85,11 @@ export class ServiceBase extends EventEmitter {
     /**
      * Set the service log level
      *
-     * @param {string} level - New log level
+     * @param {import('../../logging/typedef.js').LogLevel} level - New log level
      *
      * @returns {boolean} True if the level was set successfully
      */
-    setLogLevel(level: string): boolean;
+    setLogLevel(level: import("../../logging/typedef.js").LogLevel): boolean;
     /**
      * Configure the service (handles both initial config and reconfiguration)
      *

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

@@ -130,7 +130,7 @@ export class ServiceBase extends EventEmitter {
    *
    * @param {Object<string,any>|null} [config={}]
    *
-   * @returns {Promise<boolean>} True if configuration succeeded
+   * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
    */
   async configure(config = {}) {
     if (
@@ -140,8 +140,9 @@ export class ServiceBase extends EventEmitter {
       this.state !== STATE_STOPPED &&
       this.state !== STATE_DESTROYED
     ) {
-      this.logger.warn(`Cannot configure from state: ${this.state}`);
-      return false;
+      const error = new Error(`Cannot configure from state: ${this.state}`);
+      this.logger.warn(error.message);
+      return { ok: false, error };
     }
 
     const wasRunning = this.state === STATE_RUNNING;
@@ -156,10 +157,10 @@ export class ServiceBase extends EventEmitter {
 
       this._setState(wasRunning ? STATE_RUNNING : STATE_CONFIGURED);
       this.logger.info('Service configured');
-      return true;
+      return { ok: true };
     } catch (error) {
       this._setError('configuration', /** @type {Error} */ (error));
-      return false;
+      return { ok: false, error: this.error };
     }
   }
 
@@ -175,12 +176,13 @@ export class ServiceBase extends EventEmitter {
   /**
    * Start the service
    *
-   * @returns {Promise<boolean>} True if the service started successfully
+   * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
    */
   async start() {
     if (this.state !== STATE_CONFIGURED && this.state !== STATE_STOPPED) {
-      this.logger.warn(`Cannot start from state: ${this.state}`);
-      return false;
+      const error = new Error(`Cannot start from state: ${this.state}`);
+      this.logger.warn(error.message);
+      return { ok: false, error };
     }
 
     try {
@@ -193,10 +195,10 @@ export class ServiceBase extends EventEmitter {
       this._setState(STATE_RUNNING);
       this._setHealthy(true);
       this.logger.info('Service started');
-      return true;
+      return { ok: true };
     } catch (error) {
       this._setError('startup', /** @type {Error} */ (error));
-      return false;
+      return { ok: false, error: this.error };
     }
   }
 
@@ -205,12 +207,12 @@ export class ServiceBase extends EventEmitter {
    *
    * @param {import('./typedef.js').StopOptions} [options={}] - Stop options
    *
-   * @returns {Promise<boolean>} True if the service stopped successfully
+   * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
    */
   async stop(options = {}) {
     if (this.state !== STATE_RUNNING && this.state !== STATE_ERROR) {
       this.logger.warn(`Cannot stop from state: ${this.state}`);
-      return true; // Already stopped
+      return { ok: true }; // Already stopped
     }
 
     const timeout = options.timeout ?? this._shutdownTimeout;
@@ -237,7 +239,7 @@ export class ServiceBase extends EventEmitter {
 
       this._setState(STATE_STOPPED);
       this.logger.info('Service stopped');
-      return true;
+      return { ok: true };
     } catch (error) {
       if (
         /** @type {Error} */ (error).message === 'Shutdown timeout' &&
@@ -245,24 +247,25 @@ export class ServiceBase extends EventEmitter {
       ) {
         this.logger.warn('Forced shutdown after timeout');
         this._setState(STATE_STOPPED);
-        return true;
+        return { ok: true };
       }
       this._setError('shutdown', /** @type {Error} */ (error));
-      return false;
+      return { ok: false, error: this.error };
     }
   }
 
   /**
    * Recover the service from error state
    *
-   * @returns {Promise<boolean>} True if recovery succeeded
+   * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
    */
   async recover() {
     if (this.state !== STATE_ERROR) {
-      this.logger.warn(
+      const error = new Error(
         `Can only recover from ERROR state, current: ${this.state}`
       );
-      return false;
+      this.logger.warn(error.message);
+      return { ok: false, error };
     }
 
     try {
@@ -278,31 +281,37 @@ export class ServiceBase extends EventEmitter {
       } else {
         // Default: restart
         this._setState(STATE_STOPPED);
-        await this.start();
+        const startResult = await this.start();
+        if (!startResult.ok) {
+          return startResult; // Forward the start error
+        }
       }
 
       this.error = null;
       this.logger.info('Recovery successful');
-      return true;
+      return { ok: true };
     } catch (error) {
       this._setError('recovery', /** @type {Error} */ (error));
-      return false;
+      return { ok: false, error: this.error };
     }
   }
 
   /**
    * Destroy the service and cleanup resources
    *
-   * @returns {Promise<boolean>} True if destruction succeeded
+   * @returns {Promise<import('./typedef.js').OperationResult>} Operation result
    */
   async destroy() {
     if (this.state === STATE_DESTROYED) {
-      return true;
+      return { ok: true };
     }
 
     try {
       if (this.state === STATE_RUNNING) {
-        await this.stop();
+        const stopResult = await this.stop();
+        if (!stopResult.ok) {
+          return stopResult; // Forward the stop error
+        }
       }
 
       this._setTargetState(STATE_DESTROYED);
@@ -321,10 +330,10 @@ export class ServiceBase extends EventEmitter {
       this.removeAllListeners();
       this.logger.removeAllListeners();
 
-      return true;
+      return { ok: true };
     } catch (error) {
       this._setError('destruction', /** @type {Error} */ (error));
-      return false;
+      return { ok: false, error: this.error };
     }
   }
 
@@ -361,7 +370,7 @@ export class ServiceBase extends EventEmitter {
   /**
    * Set the service log level
    *
-   * @param {string} level - New log level
+   * @param {import('../../logging/typedef.js').LogLevel} level - New log level
    *
    * @returns {boolean} True if the level was set successfully
    */

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

@@ -1,3 +1,16 @@
+/**
+ * Result of a service operation
+ */
+export type OperationResult = {
+    /**
+     * - Whether the operation succeeded
+     */
+    ok: boolean;
+    /**
+     * - Error details if operation failed
+     */
+    error?: Error | undefined;
+};
 /**
  * All possible service states during lifecycle management
  */

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

@@ -23,6 +23,14 @@
 // PUBLIC TYPES
 // ============================================================================
 
+/**
+ * Result of a service operation
+ *
+ * @typedef {Object} OperationResult
+ * @property {boolean} ok - Whether the operation succeeded
+ * @property {Error} [error] - Error details if operation failed
+ */
+
 /**
  * All possible service states during lifecycle management
  *

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

@@ -72,42 +72,46 @@ export class ServiceManager extends EventEmitter {
      *
      * @param {string} name - Service name
      *
-     * @returns {Promise<boolean>} True if configuration succeeded
+     * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+     *   Operation result
      */
-    configureService(name: string): Promise<boolean>;
+    configureService(name: string): Promise<import("../service-base/typedef.js").OperationResult>;
     /**
      * Start a service and its dependencies
      *
      * @param {string} name - Service name
      *
-     * @returns {Promise<boolean>} True if service started successfully
+     * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+     *   Operation result
      */
-    startService(name: string): Promise<boolean>;
+    startService(name: string): Promise<import("../service-base/typedef.js").OperationResult>;
     /**
      * Stop a service
      *
      * @param {string} name - Service name
      * @param {StopOptions} [options={}] - Stop options
      *
-     * @returns {Promise<boolean>} True if service stopped successfully
+     * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+     *   Operation result
      */
-    stopService(name: string, options?: StopOptions): Promise<boolean>;
+    stopService(name: string, options?: StopOptions): Promise<import("../service-base/typedef.js").OperationResult>;
     /**
      * Recover a service from error state
      *
      * @param {string} name - Service name
      *
-     * @returns {Promise<boolean>} True if recovery succeeded
+     * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+     *   Operation result
      */
-    recoverService(name: string): Promise<boolean>;
+    recoverService(name: string): Promise<import("../service-base/typedef.js").OperationResult>;
     /**
      * Start all registered services in dependency order
      *
-     * @returns {Promise<Object<string, boolean>>} Map of service results
+     * @throws {DetailedError} if one of the services did not start
+     *
+     * @returns {Promise<string[]>} list of started service names
      */
-    startAll(): Promise<{
-        [x: string]: boolean;
-    }>;
+    startAll(): Promise<string[]>;
     /**
      * Stop all services in reverse dependency order
      *

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

@@ -65,6 +65,7 @@
 
 import { EventEmitter } from '../../generic/events.js';
 import { Logger, DEBUG, INFO } from '../../logging/index.js';
+import { DetailedError } from '../../generic/errors.js';
 
 import {
   SERVICE_LOG,
@@ -265,11 +266,15 @@ export class ServiceManager extends EventEmitter {
    *
    * @param {string} name - Service name
    *
-   * @returns {Promise<boolean>} True if configuration succeeded
+   * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+   *   Operation result
    */
   async configureService(name) {
     const instance = this.get(name);
-    if (!instance) return false;
+    if (!instance) {
+      const error = new Error(`Service [${name}] not found`);
+      return { ok: false, error };
+    }
 
     const entry = this.#getServiceEntry(name);
 
@@ -283,13 +288,15 @@ export class ServiceManager extends EventEmitter {
    *
    * @param {string} name - Service name
    *
-   * @returns {Promise<boolean>} True if service started successfully
+   * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+   *   Operation result
    */
   async startService(name) {
     const entry = this.#getServiceEntry(name);
     if (!entry) {
-      this.logger.warn(`Cannot start unregistered service '${name}'`);
-      return false;
+      const error = new Error(`Service [${name}] not registered`);
+      this.logger.warn(error.message);
+      return { ok: false, error };
     }
 
     // Start dependencies first
@@ -297,19 +304,25 @@ export class ServiceManager extends EventEmitter {
       if (!(await this.isRunning(dep))) {
         this.logger.debug(`Starting dependency '${dep}' for '${name}'`);
 
-        const started = await this.startService(dep);
+        const dependencyResult = await this.startService(dep);
 
-        if (!started) {
-          this.logger.error(
-            new Error(`Failed to start dependency '${dep}' for '${name}'`)
+        if (!dependencyResult.ok) {
+          const error = new DetailedError(
+            `Failed to start dependency [${dep}] for service [${name}]`,
+            null,
+            dependencyResult.error
           );
-          return false;
+          this.logger.error(error);
+          return { ok: false, error };
         }
       }
     }
 
     const instance = this.get(name);
-    if (!instance) return false;
+    if (!instance) {
+      const error = new Error(`Service [${name}] instance not found`);
+      return { ok: false, error };
+    }
 
     if (
       instance.state === STATE_CREATED ||
@@ -318,10 +331,10 @@ export class ServiceManager extends EventEmitter {
       // Service is not created or has been destroyed
       // => configure needed
 
-      const configured = await this.configureService(name);
+      const configResult = await this.configureService(name);
 
-      if (!configured) {
-        return false;
+      if (!configResult.ok) {
+        return configResult; // Forward the configuration error
       }
     }
 
@@ -334,14 +347,15 @@ export class ServiceManager extends EventEmitter {
    * @param {string} name - Service name
    * @param {StopOptions} [options={}] - Stop options
    *
-   * @returns {Promise<boolean>} True if service stopped successfully
+   * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+   *   Operation result
    */
   async stopService(name, options = {}) {
     const instance = this.get(name);
 
     if (!instance) {
       this.logger.warn(`Cannot stop unregistered service '${name}'`);
-      return true; // Already stopped
+      return { ok: true }; // Already stopped
     }
 
     // Check dependents
@@ -356,10 +370,11 @@ export class ServiceManager extends EventEmitter {
       }
 
       if (runningDependents.length > 0) {
-        this.logger.warn(
-          `Cannot stop '${name}' - required by: ${runningDependents.join(', ')}`
+        const error = new Error(
+          `Cannot stop [${name}] - required by: ${runningDependents.join(', ')}`
         );
-        return false;
+        this.logger.warn(error.message);
+        return { ok: false, error };
       }
     }
 
@@ -371,11 +386,15 @@ export class ServiceManager extends EventEmitter {
    *
    * @param {string} name - Service name
    *
-   * @returns {Promise<boolean>} True if recovery succeeded
+   * @returns {Promise<import('../service-base/typedef.js').OperationResult>}
+   *   Operation result
    */
   async recoverService(name) {
     const instance = this.get(name);
-    if (!instance) return false;
+    if (!instance) {
+      const error = new Error(`Service [${name}] not found`);
+      return { ok: false, error };
+    }
 
     return await instance.recover();
   }
@@ -383,25 +402,35 @@ export class ServiceManager extends EventEmitter {
   /**
    * Start all registered services in dependency order
    *
-   * @returns {Promise<Object<string, boolean>>} Map of service results
+   * @throws {DetailedError} if one of the services did not start
+   *
+   * @returns {Promise<string[]>} list of started service names
    */
   async startAll() {
     this.logger.info('Starting all services');
 
     // Sort by priority and dependencies
     const sorted = this.#topologicalSort();
-    const results = new Map();
 
-    for (const name of sorted) {
-      const success = await this.startService(name);
-      results.set(name, success);
+    /** @type {string[]} */
+    const startedServiceNames = [];
 
-      if (!success) {
-        throw new Error(`Failed to start service [${name}], stopping`);
+    for (const name of sorted) {
+      const result = await this.startService(name);
+      startedServiceNames.push(name);
+
+      if (!result.ok) {
+        // Create detailed error with the actual service failure
+        const detailedError = new DetailedError(
+          `Failed to start service [${name}], stopping`,
+          null,
+          result.error
+        );
+        throw detailedError;
       }
     }
 
-    return Object.fromEntries(results);
+    return startedServiceNames;
   }
 
   /**
@@ -729,8 +758,8 @@ export class ServiceManager extends EventEmitter {
   async #stopAllSequentially(serviceNames, results, options) {
     for (const name of serviceNames) {
       try {
-        const success = await this.stopService(name, options);
-        results.set(name, success);
+        const result = await this.stopService(name, options);
+        results.set(name, result.ok);
       } catch (error) {
         this.logger.error(
           `Error stopping '${name}'`,

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

@@ -1,3 +1,4 @@
+export type LogLevel = import("../../logging/typedef.js").LogLevel;
 /**
  * Service configuration - either a config object or a config label string
  */
@@ -40,18 +41,18 @@ export type ServiceManagerConfig = {
     /**
      * - Default log level for new services
      */
-    defaultLogLevel?: string | undefined;
+    defaultLogLevel?: import("../../logging/typedef.js").LogLevel | undefined;
     /**
      * - Initial log level for ServiceManager
      */
-    managerLogLevel?: string | undefined;
+    managerLogLevel?: import("../../logging/typedef.js").LogLevel | undefined;
     /**
      * Per-service log levels:
      * - String: "auth:debug,database:info"
      * - Object: { auth: "debug", database: "info" }
      */
     serviceLogLevels?: string | {
-        [x: string]: string;
+        [x: string]: import("../../logging/typedef.js").LogLevel;
     } | undefined;
 };
 /**

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

@@ -26,6 +26,8 @@
  * manager.register('auth', AuthService, {}, options);
  */
 
+/** @typedef {import('../../logging/typedef.js').LogLevel} LogLevel */
+
 // ============================================================================
 // PUBLIC TYPES
 // ============================================================================
@@ -52,9 +54,9 @@
  * @property {boolean} [debug=false] - Debug mode switch
  * @property {boolean} [autoStart=false] - Auto-start services on registration
  * @property {number} [stopTimeout=10000] - Default timeout for stopping services
- * @property {string} [defaultLogLevel] - Default log level for new services
- * @property {string} [managerLogLevel] - Initial log level for ServiceManager
- * @property {string|Object<string,string>} [serviceLogLevels]
+ * @property {LogLevel} [defaultLogLevel] - Default log level for new services
+ * @property {LogLevel} [managerLogLevel] - Initial log level for ServiceManager
+ * @property {string|Object<string,LogLevel>} [serviceLogLevels]
  *   Per-service log levels:
  *   - String: "auth:debug,database:info"
  *   - Object: { auth: "debug", database: "info" }

package/package.json

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