@hkdigital/lib-core 0.3.1

package/dist/classes/services/service-states.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Check if a state transition is valid
+ *
+ * @param {string} fromState - Current state
+ * @param {string} toState - Desired state
+ *
+ * @returns {boolean} True if transition is valid
+ */
+export function isValidTransition(fromState: string, toState: string): boolean;
+/**
+ * Check if a service is in an operational state
+ *
+ * @param {string} state - Current state
+ *
+ * @returns {boolean} True if operational
+ */
+export function isOperational(state: string): boolean;
+/**
+ * Check if a service is in a transitional state
+ *
+ * @param {string} state - Current state
+ *
+ * @returns {boolean} True if transitioning
+ */
+export function isTransitioning(state: string): boolean;
+/**
+ * Check if a service is in an inactive state
+ *
+ * @param {string} state - Current state
+ *
+ * @returns {boolean} True if inactive
+ */
+export function isInactive(state: string): boolean;
+/**
+ * @fileoverview Service state constants for the service management system.
+ *
+ * Defines all possible states a service can be in during its lifecycle.
+ * Services transition through these states as they are initialized, started,
+ * stopped, and handle errors or recovery.
+ *
+ * @example
+ * // Using state constants in a service
+ * import { RUNNING, ERROR } from './service-states.js';
+ *
+ * class MyService extends ServiceBase {
+ *   async doWork() {
+ *     if (this.state !== RUNNING) {
+ *       throw new Error('Service not running');
+ *     }
+ *     // ... do work
+ *   }
+ * }
+ *
+ * @example
+ * // Checking service states
+ * import { RUNNING, ERROR, STOPPED } from './service-states.js';
+ *
+ * const service = serviceManager.get('database');
+ *
+ * switch (service.state) {
+ *   case RUNNING:
+ *     console.log('Service is operational');
+ *     break;
+ *   case ERROR:
+ *     console.log('Service has failed');
+ *     break;
+ *   case STOPPED:
+ *     console.log('Service is stopped');
+ *     break;
+ * }
+ */
+/**
+ * Service has not been created yet
+ * @const {string}
+ */
+export const NOT_CREATED: "not-created";
+/**
+ * Service has been created but not initialized
+ * @const {string}
+ */
+export const CREATED: "created";
+/**
+ * Service is currently initializing
+ * @const {string}
+ */
+export const INITIALIZING: "initializing";
+/**
+ * Service has been initialized and is ready to start
+ * @const {string}
+ */
+export const INITIALIZED: "initialized";
+/**
+ * Service is currently starting up
+ * @const {string}
+ */
+export const STARTING: "starting";
+/**
+ * Service is running and operational
+ * @const {string}
+ */
+export const RUNNING: "running";
+/**
+ * Service is currently shutting down
+ * @const {string}
+ */
+export const STOPPING: "stopping";
+/**
+ * Service has been stopped
+ * @const {string}
+ */
+export const STOPPED: "stopped";
+/**
+ * Service is being destroyed and cleaned up
+ * @const {string}
+ */
+export const DESTROYING: "destroying";
+/**
+ * Service has been destroyed and cannot be used
+ * @const {string}
+ */
+export const DESTROYED: "destroyed";
+/**
+ * Service encountered an error and is not operational
+ * @const {string}
+ */
+export const ERROR: "error";
+/**
+ * Service is attempting to recover from an error
+ * @const {string}
+ */
+export const RECOVERING: "recovering";
+export namespace VALID_TRANSITIONS {
+    let created: string[];
+    let initializing: string[];
+    let initialized: string[];
+    let starting: string[];
+    let running: string[];
+    let stopping: string[];
+    let stopped: string[];
+    let destroying: string[];
+    let destroyed: string[];
+    let error: string[];
+    let recovering: string[];
+}
+/**
+ * States that indicate the service is operational
+ * @const {string[]}
+ */
+export const OPERATIONAL_STATES: string[];
+/**
+ * States that indicate the service is transitioning
+ * @const {string[]}
+ */
+export const TRANSITIONAL_STATES: string[];
+/**
+ * States that indicate the service is not operational
+ * @const {string[]}
+ */
+export const INACTIVE_STATES: string[];

package/dist/classes/services/service-states.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Service state constants for the service management system.
+ *
+ * Defines all possible states a service can be in during its lifecycle.
+ * Services transition through these states as they are initialized, started,
+ * stopped, and handle errors or recovery.
+ *
+ * @example
+ * // Using state constants in a service
+ * import { RUNNING, ERROR } from './service-states.js';
+ *
+ * class MyService extends ServiceBase {
+ *   async doWork() {
+ *     if (this.state !== RUNNING) {
+ *       throw new Error('Service not running');
+ *     }
+ *     // ... do work
+ *   }
+ * }
+ *
+ * @example
+ * // Checking service states
+ * import { RUNNING, ERROR, STOPPED } from './service-states.js';
+ *
+ * const service = serviceManager.get('database');
+ *
+ * switch (service.state) {
+ *   case RUNNING:
+ *     console.log('Service is operational');
+ *     break;
+ *   case ERROR:
+ *     console.log('Service has failed');
+ *     break;
+ *   case STOPPED:
+ *     console.log('Service is stopped');
+ *     break;
+ * }
+ */
+
+/**
+ * Service has not been created yet
+ * @const {string}
+ */
+export const NOT_CREATED = 'not-created';
+
+/**
+ * Service has been created but not initialized
+ * @const {string}
+ */
+export const CREATED = 'created';
+
+/**
+ * Service is currently initializing
+ * @const {string}
+ */
+export const INITIALIZING = 'initializing';
+
+/**
+ * Service has been initialized and is ready to start
+ * @const {string}
+ */
+export const INITIALIZED = 'initialized';
+
+/**
+ * Service is currently starting up
+ * @const {string}
+ */
+export const STARTING = 'starting';
+
+/**
+ * Service is running and operational
+ * @const {string}
+ */
+export const RUNNING = 'running';
+
+/**
+ * Service is currently shutting down
+ * @const {string}
+ */
+export const STOPPING = 'stopping';
+
+/**
+ * Service has been stopped
+ * @const {string}
+ */
+export const STOPPED = 'stopped';
+
+/**
+ * Service is being destroyed and cleaned up
+ * @const {string}
+ */
+export const DESTROYING = 'destroying';
+
+/**
+ * Service has been destroyed and cannot be used
+ * @const {string}
+ */
+export const DESTROYED = 'destroyed';
+
+/**
+ * Service encountered an error and is not operational
+ * @const {string}
+ */
+export const ERROR = 'error';
+
+/**
+ * Service is attempting to recover from an error
+ * @const {string}
+ */
+export const RECOVERING = 'recovering';
+
+/**
+ * Valid state transitions map
+ * Maps each state to the states it can transition to
+ * @const {Object<string, string[]>}
+ */
+export const VALID_TRANSITIONS = {
+  [CREATED]: [INITIALIZING, DESTROYING],
+  [INITIALIZING]: [INITIALIZED, ERROR, DESTROYING],
+  [INITIALIZED]: [STARTING, DESTROYING],
+  [STARTING]: [RUNNING, ERROR, STOPPING],
+  [RUNNING]: [STOPPING, ERROR],
+  [STOPPING]: [STOPPED, ERROR],
+  [STOPPED]: [STARTING, DESTROYING, INITIALIZING],
+  [DESTROYING]: [DESTROYED, ERROR],
+  [DESTROYED]: [CREATED], // Can be recreated
+  [ERROR]: [RECOVERING, STOPPING, DESTROYING],
+  [RECOVERING]: [RUNNING, STOPPED, ERROR]
+};
+
+/**
+ * States that indicate the service is operational
+ * @const {string[]}
+ */
+export const OPERATIONAL_STATES = [RUNNING];
+
+/**
+ * States that indicate the service is transitioning
+ * @const {string[]}
+ */
+export const TRANSITIONAL_STATES = [
+  INITIALIZING,
+  STARTING,
+  STOPPING,
+  DESTROYING,
+  RECOVERING
+];
+
+/**
+ * States that indicate the service is not operational
+ * @const {string[]}
+ */
+export const INACTIVE_STATES = [
+  CREATED,
+  INITIALIZED,
+  STOPPED,
+  DESTROYED,
+  ERROR
+];
+
+/**
+ * Check if a state transition is valid
+ *
+ * @param {string} fromState - Current state
+ * @param {string} toState - Desired state
+ *
+ * @returns {boolean} True if transition is valid
+ */
+export function isValidTransition(fromState, toState) {
+  const validStates = VALID_TRANSITIONS[fromState];
+  return validStates ? validStates.includes(toState) : false;
+}
+
+/**
+ * Check if a service is in an operational state
+ *
+ * @param {string} state - Current state
+ *
+ * @returns {boolean} True if operational
+ */
+export function isOperational(state) {
+  return OPERATIONAL_STATES.includes(state);
+}
+
+/**
+ * Check if a service is in a transitional state
+ *
+ * @param {string} state - Current state
+ *
+ * @returns {boolean} True if transitioning
+ */
+export function isTransitioning(state) {
+  return TRANSITIONAL_STATES.includes(state);
+}
+
+/**
+ * Check if a service is in an inactive state
+ *
+ * @param {string} state - Current state
+ *
+ * @returns {boolean} True if inactive
+ */
+export function isInactive(state) {
+  return INACTIVE_STATES.includes(state);
+}

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

@@ -0,0 +1,247 @@
+/**
+ * Service configuration object passed to service initialization
+ */
+export type ServiceConfig = {
+    /**
+     * - Service-specific configuration properties
+     */
+    key?: any;
+};
+/**
+ * Options for creating a service instance
+ */
+export type ServiceOptions = {
+    /**
+     * - Initial log level for the service
+     */
+    logLevel?: string;
+    /**
+     * - Timeout for graceful shutdown
+     */
+    shutdownTimeout?: number;
+};
+/**
+ * Options for stopping a service
+ */
+export type StopOptions = {
+    /**
+     * - Override shutdown timeout
+     */
+    timeout?: number;
+    /**
+     * - Force stop even if timeout exceeded
+     */
+    force?: boolean;
+};
+/**
+ * Health status returned by service health checks
+ */
+export type HealthStatus = {
+    /**
+     * - Service name
+     */
+    name: string;
+    /**
+     * - Current service state
+     */
+    state: string;
+    /**
+     * - Whether the service is healthy
+     */
+    healthy: boolean;
+    /**
+     * - Error message if unhealthy
+     */
+    error?: string;
+    /**
+     * - Error from health check itself
+     */
+    checkError?: string;
+    /**
+     * - Additional health check properties
+     */
+    key?: any;
+};
+export type StateChangeEvent = {
+    /**
+     * - Service name (added by ServiceManager)
+     */
+    service: string;
+    /**
+     * - Previous state
+     */
+    oldState: string;
+    /**
+     * - New state
+     */
+    newState: string;
+};
+export type HealthChangeEvent = {
+    /**
+     * - Service name (added by ServiceManager)
+     */
+    service: string;
+    /**
+     * - Current health status
+     */
+    healthy: boolean;
+    /**
+     * - Previous health status
+     */
+    wasHealthy?: boolean;
+};
+/**
+ * Event emitted when service encounters an error
+ */
+export type ServiceErrorEvent = {
+    /**
+     * - Service name
+     */
+    service: string;
+    /**
+     * - Operation that failed
+     */
+    operation: string;
+    /**
+     * - Error that occurred
+     */
+    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;
+};