@hkdigital/lib-core 0.3.3 → 0.3.5

package/dist/{classes/services → services/internal/service-base}/typedef.d.ts

@@ -1,12 +1,3 @@
-/**
- * Service configuration object passed to service initialization
- */
-export type ServiceConfig = {
-    /**
-     * - Service-specific configuration properties
-     */
-    key?: any;
-};
 /**
  * Options for creating a service instance
  */
@@ -62,6 +53,40 @@ export type HealthStatus = {
      */
     key?: any;
 };
+/**
+ * Base class interface that services must implement
+ */
+export type ServiceInstance = {
+    /**
+     * - Service name
+     */
+    name: string;
+    /**
+     * - Current state
+     */
+    state: string;
+    /**
+     * - Health status
+     */
+    healthy: boolean;
+    /**
+     * - Last error
+     */
+    error: Error | null;
+    /**
+     * - Service logger
+     */
+    logger: import("../../../logging/internal/unified-logger").Logger;
+    initialize: (config?: any) => Promise<boolean>;
+    start: () => Promise<boolean>;
+    stop: (options?: StopOptions) => Promise<boolean>;
+    recover: () => Promise<boolean>;
+    destroy: () => Promise<boolean>;
+    getHealth: () => Promise<HealthStatus>;
+    setLogLevel: (level: string) => boolean;
+    on: (event: string, handler: Function) => Function;
+    emit: (event: string, data: any) => boolean;
+};
 export type StateChangeEvent = {
     /**
      * - Service name (added by ServiceManager)
@@ -107,141 +132,3 @@ export type ServiceErrorEvent = {
      */
     error: Error;
 };
-/**
- * Service class constructor type
- */
-export type ServiceConstructor = new (name: string, options?: ServiceOptions) => ServiceInstance;
-/**
- * Options for registering a service
- */
-export type ServiceRegistrationOptions = {
-    /**
-     * - Services this service depends on
-     */
-    dependencies?: string[];
-    /**
-     * - Tags for grouping services
-     */
-    tags?: string[];
-    /**
-     * - Startup priority (higher starts first)
-     */
-    priority?: number;
-};
-/**
- * Configuration for ServiceManager
- */
-export type ServiceManagerConfig = {
-    /**
-     * - Debug mode switch
-     */
-    debug?: boolean;
-    /**
-     * - Auto-start services on registration
-     */
-    autoStart?: boolean;
-    /**
-     * - Default timeout for stopping services
-     */
-    stopTimeout?: number;
-    /**
-     * - Initial log level for ServiceManager
-     */
-    logLevel?: string;
-    /**
-     * - Logging configuration
-     */
-    logConfig?: LogConfig;
-};
-/**
- * Logging configuration
- */
-export type LogConfig = {
-    /**
-     * - Default log level for services
-     */
-    defaultLevel?: string;
-    /**
-     * - Override level for all services
-     */
-    globalLevel?: string;
-    /**
-     * - Per-service log levels
-     */
-    serviceLevels?: {
-        [x: string]: string;
-    };
-};
-/**
- * Internal service registry entry
- */
-export type ServiceEntry = {
-    /**
-     * - Service class constructor
-     */
-    ServiceClass: ServiceConstructor;
-    /**
-     * - Service instance (lazy-created)
-     */
-    instance: ServiceInstance | null;
-    /**
-     * - Service configuration
-     */
-    config: ServiceConfig;
-    /**
-     * - Service dependencies
-     */
-    dependencies: string[];
-    /**
-     * - Services that depend on this one
-     */
-    dependents: Set<string>;
-    /**
-     * - Service tags
-     */
-    tags: string[];
-    /**
-     * - Startup priority
-     */
-    priority: number;
-};
-/**
- * Result of health check for all services
- */
-export type HealthCheckResult = {
-    [x: string]: HealthStatus;
-};
-/**
- * Base class interface that services must implement
- */
-export type ServiceInstance = {
-    /**
-     * - Service name
-     */
-    name: string;
-    /**
-     * - Current state
-     */
-    state: string;
-    /**
-     * - Health status
-     */
-    healthy: boolean;
-    /**
-     * - Last error
-     */
-    error: Error | null;
-    /**
-     * - Service logger
-     */
-    logger: import("../logging").Logger;
-    initialize: (config?: ServiceConfig) => Promise<boolean>;
-    start: () => Promise<boolean>;
-    stop: (options?: StopOptions) => Promise<boolean>;
-    recover: () => Promise<boolean>;
-    destroy: () => Promise<boolean>;
-    getHealth: () => Promise<HealthStatus>;
-    setLogLevel: (level: string) => boolean;
-    on: (event: string, handler: Function) => Function;
-    emit: (event: string, data: any) => boolean;
-};

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

@@ -0,0 +1,101 @@
+/**
+ * @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 _healthCheck() {
+ *     // Return type is HealthStatus
+ *     return { latency: 10 };
+ *   }
+ * }
+ */
+
+// ============================================================================
+// PUBLIC TYPES
+// ============================================================================
+
+/**
+ * Options for creating a service instance
+ *
+ * @typedef {Object} ServiceOptions
+ * @property {string} [logLevel] - Initial log level for the service
+ * @property {number} [shutdownTimeout=5000] - Timeout for graceful shutdown
+ */
+
+/**
+ * Options for stopping a service
+ *
+ * @typedef {Object} StopOptions
+ * @property {number} [timeout] - Override shutdown timeout
+ * @property {boolean} [force=false] - Force stop even if timeout exceeded
+ */
+
+/**
+ * Health status returned by service health checks
+ *
+ * @typedef {Object} HealthStatus
+ * @property {string} name - Service name
+ * @property {string} state - Current service state
+ * @property {boolean} healthy - Whether the service is healthy
+ * @property {string} [error] - Error message if unhealthy
+ * @property {string} [checkError] - Error from health check itself
+ * @property {*} [key] - Additional health check properties
+ */
+
+/**
+ * Base class interface that services must implement
+ *
+ * @typedef {Object} ServiceInstance
+ * @property {string} name - Service name
+ * @property {string} state - Current state
+ * @property {boolean} healthy - Health status
+ * @property {Error|null} error - Last error
+ * @property {import('../../../logging/internal/unified-logger').Logger} logger - Service logger
+ * @property {(config?: *) => Promise<boolean>} initialize
+ * @property {() => Promise<boolean>} start
+ * @property {(options?: StopOptions) => Promise<boolean>} stop
+ * @property {() => Promise<boolean>} recover
+ * @property {() => Promise<boolean>} destroy
+ * @property {() => Promise<HealthStatus>} getHealth
+ * @property {(level: string) => boolean} setLogLevel
+ * @property {(event: string, handler: Function) => Function} on
+ * @property {(event: string, data: any) => boolean} emit
+ */
+
+// ============================================================================
+// INTERNAL TYPES
+// ============================================================================
+
+/**
+ * @typedef {Object} StateChangeEvent
+ * @property {string} service - Service name (added by ServiceManager)
+ * @property {string} oldState - Previous state
+ * @property {string} newState - New state
+ */
+
+/**
+ * @typedef {Object} HealthChangeEvent
+ * @property {string} service - Service name (added by ServiceManager)
+ * @property {boolean} healthy - Current health status
+ * @property {boolean} [wasHealthy] - Previous health status
+ */
+
+/**
+ * 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
+ */
+
+export {};

package/dist/{classes/services → services/internal/service-manager}/ServiceManager.d.ts

@@ -1,11 +1,11 @@
 /**
  * @typedef {import('./typedef.js').ServiceConstructor} ServiceConstructor
- * @typedef {import('./typedef.js').ServiceConfig} ServiceConfig
  * @typedef {import('./typedef.js').ServiceRegistrationOptions} ServiceRegistrationOptions
  * @typedef {import('./typedef.js').ServiceManagerConfig} ServiceManagerConfig
- * @typedef {import('./typedef.js').StopOptions} StopOptions
  * @typedef {import('./typedef.js').ServiceEntry} ServiceEntry
  * @typedef {import('./typedef.js').HealthCheckResult} HealthCheckResult
+ *
+ * @typedef {import('../service-base/typedef.js').StopOptions} StopOptions
  */
 /**
  * Service Manager for lifecycle and dependency management
@@ -29,12 +29,12 @@ export class ServiceManager extends EventEmitter {
      *
      * @param {string} name - Unique service identifier
      * @param {ServiceConstructor} ServiceClass - Service class constructor
-     * @param {ServiceConfig} [config={}] - Service configuration
+     * @param {*} [config={}] - Service configuration
      * @param {ServiceRegistrationOptions} [options={}] - Registration options
      *
      * @throws {Error} If service name is already registered
      */
-    register(name: string, ServiceClass: ServiceConstructor, config?: ServiceConfig, options?: ServiceRegistrationOptions): void;
+    register(name: string, ServiceClass: ServiceConstructor, config?: any, options?: ServiceRegistrationOptions): void;
     /**
      * Get or create a service instance
      *
@@ -153,7 +153,7 @@ export class ServiceManager extends EventEmitter {
      *
      * @private
      * @param {string} name - Service name
-     * @param {import('./typedef.js').ServiceInstance} instance
+     * @param {import('../service-base/typedef.js').ServiceInstance} instance
      *   Service instance
      */
     private _attachServiceEvents;
@@ -169,11 +169,10 @@ export class ServiceManager extends EventEmitter {
 }
 export default ServiceManager;
 export type ServiceConstructor = import("./typedef.js").ServiceConstructor;
-export type ServiceConfig = import("./typedef.js").ServiceConfig;
 export type ServiceRegistrationOptions = import("./typedef.js").ServiceRegistrationOptions;
 export type ServiceManagerConfig = import("./typedef.js").ServiceManagerConfig;
-export type StopOptions = import("./typedef.js").StopOptions;
 export type ServiceEntry = import("./typedef.js").ServiceEntry;
 export type HealthCheckResult = import("./typedef.js").HealthCheckResult;
-import { EventEmitter } from '../events';
-import { Logger } from '../logging';
+export type StopOptions = import("../service-base/typedef.js").StopOptions;
+import { EventEmitter } from '../../../classes/event-emitter';
+import { Logger } from '../../../logging/index.js';

package/dist/{classes/services → services/internal/service-manager}/ServiceManager.js

@@ -63,24 +63,24 @@
  * });
  */
 
-import { EventEmitter } from '../events';
-import { Logger, DEBUG, INFO, WARN } from '../logging';
+import { EventEmitter } from '../../../classes/event-emitter';
+import { Logger, DEBUG, INFO, WARN } from '../../../logging/index.js';
 
 import {
   NOT_CREATED,
   CREATED,
   RUNNING,
   DESTROYED
-} from './service-states.js';
+} from '../service-base/constants.js';
 
 /**
  * @typedef {import('./typedef.js').ServiceConstructor} ServiceConstructor
- * @typedef {import('./typedef.js').ServiceConfig} ServiceConfig
  * @typedef {import('./typedef.js').ServiceRegistrationOptions} ServiceRegistrationOptions
  * @typedef {import('./typedef.js').ServiceManagerConfig} ServiceManagerConfig
- * @typedef {import('./typedef.js').StopOptions} StopOptions
  * @typedef {import('./typedef.js').ServiceEntry} ServiceEntry
  * @typedef {import('./typedef.js').HealthCheckResult} HealthCheckResult
+ *
+ * @typedef {import('../service-base/typedef.js').StopOptions} StopOptions
  */
 
 /**
@@ -118,7 +118,7 @@ export class ServiceManager extends EventEmitter {
    *
    * @param {string} name - Unique service identifier
    * @param {ServiceConstructor} ServiceClass - Service class constructor
-   * @param {ServiceConfig} [config={}] - Service configuration
+   * @param {*} [config={}] - Service configuration
    * @param {ServiceRegistrationOptions} [options={}] - Registration options
    *
    * @throws {Error} If service name is already registered
@@ -545,7 +545,7 @@ export class ServiceManager extends EventEmitter {
    *
    * @private
    * @param {string} name - Service name
-   * @param {import('./typedef.js').ServiceInstance} instance
+   * @param {import('../service-base/typedef.js').ServiceInstance} instance
    *   Service instance
    */
   _attachServiceEvents(name, instance) {

package/dist/services/internal/service-manager/constants.d.ts

@@ -0,0 +1,4 @@
+export const SERVICE_STATE_CHANGED: "service:state-changed";
+export const SERVICE_HEALTH_CHANGED: "service:health-changed";
+export const SERVICE_ERROR: "service:error";
+export const SERVICE_LOG: "service:log";

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

@@ -0,0 +1,6 @@
+
+// Log event names
+export const SERVICE_STATE_CHANGED = 'service:state-changed';
+export const SERVICE_HEALTH_CHANGED = 'service:health-changed';
+export const SERVICE_ERROR = 'service:error';
+export const SERVICE_LOG = 'service:log';

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

@@ -0,0 +1,104 @@
+/**
+ * Options for registering a service
+ */
+export type ServiceRegistrationOptions = {
+    /**
+     * - Services this service depends on
+     */
+    dependencies?: string[];
+    /**
+     * - Tags for grouping services
+     */
+    tags?: string[];
+    /**
+     * - Startup priority (higher starts first)
+     */
+    priority?: number;
+};
+/**
+ * Configuration for ServiceManager
+ */
+export type ServiceManagerConfig = {
+    /**
+     * - Debug mode switch
+     */
+    debug?: boolean;
+    /**
+     * - Auto-start services on registration
+     */
+    autoStart?: boolean;
+    /**
+     * - Default timeout for stopping services
+     */
+    stopTimeout?: number;
+    /**
+     * - Initial log level for ServiceManager
+     */
+    logLevel?: string;
+    /**
+     * - Logging configuration
+     */
+    logConfig?: LogConfig;
+};
+/**
+ * Logging configuration
+ */
+export type LogConfig = {
+    /**
+     * - Default log level for services
+     */
+    defaultLevel?: string;
+    /**
+     * - Override level for all services
+     */
+    globalLevel?: string;
+    /**
+     * - Per-service log levels
+     */
+    serviceLevels?: {
+        [x: string]: string;
+    };
+};
+/**
+ * Result of health check for all services
+ */
+export type HealthCheckResult = {
+    [x: string]: HealthStatus;
+};
+/**
+ * Service class constructor type
+ */
+export type ServiceConstructor = new (name: string, options?: ServiceOptions) => ServiceInstance;
+/**
+ * Internal service registry entry
+ */
+export type ServiceEntry = {
+    /**
+     * - Service class constructor
+     */
+    ServiceClass: ServiceConstructor;
+    /**
+     * - Service instance (lazy-created)
+     */
+    instance: ServiceInstance | null;
+    /**
+     * - Service configuration
+     */
+    config: any;
+    /**
+     * - Service dependencies
+     */
+    dependencies: string[];
+    /**
+     * - Services that depend on this one
+     */
+    dependents: Set<string>;
+    /**
+     * - Service tags
+     */
+    tags: string[];
+    /**
+     * - Startup priority
+     */
+    priority: number;
+};

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

@@ -0,0 +1,90 @@
+/**
+ * @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);
+ */
+
+// ============================================================================
+// PUBLIC TYPES
+// ============================================================================
+
+/**
+ * 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)
+ */
+
+/**
+ * Configuration for ServiceManager
+ *
+ * @typedef {Object} ServiceManagerConfig
+ * @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} [logLevel] - Initial log level for ServiceManager
+ * @property {LogConfig} [logConfig={}] - Logging configuration
+ */
+
+/**
+ * Logging configuration
+ *
+ * @typedef {Object} LogConfig
+ * @property {string} [defaultLevel] - Default log level for services
+ * @property {string} [globalLevel] - Override level for all services
+ * @property {Object<string, string>} [serviceLevels] - Per-service log levels
+ */
+
+/**
+ * Result of health check for all services
+ * @typedef {Object<string, HealthStatus>} HealthCheckResult
+ */
+
+/**
+ * Service class constructor type
+ *
+ * @typedef {new (name: string, options?: ServiceOptions) => ServiceInstance} ServiceConstructor
+ */
+
+// ============================================================================
+// INTERNAL TYPES
+// ============================================================================
+
+/**
+ * Internal service registry entry
+ *
+ * @typedef {Object} ServiceEntry
+ * @property {ServiceConstructor} ServiceClass - Service class constructor
+ * @property {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
+ */
+
+export {};

package/package.json

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

package/dist/classes/services/index.d.ts

@@ -1,4 +0,0 @@
-export { default as ServiceBase } from "./ServiceBase.js";
-export { default as ServiceManager } from "./ServiceManager.js";
-export * from "./service-states.js";
-export * from "./typedef.js";

package/dist/classes/services/index.js

@@ -1,5 +0,0 @@
-export { default as ServiceBase } from './ServiceBase.js';
-export { default as ServiceManager } from './ServiceManager.js';
-
-export * from './service-states.js';
-export * from './typedef.js';