@hkdigital/lib-core 0.3.10 → 0.3.12

package/dist/services/README.md

@@ -0,0 +1,200 @@
+# Services
+
+A comprehensive service management system providing standardized lifecycle management, health monitoring, and dependency orchestration for application services.
+
+## Overview
+
+The services module provides two main components:
+
+- **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.
+
+## Service States
+
+Services transition through these states during their lifecycle:
+
+- `created` - Service instantiated but not initialized
+- `initializing` - Currently running initialization
+- `initialized` - Ready to start
+- `starting` - Currently starting up
+- `running` - Operational and healthy
+- `stopping` - Currently shutting down
+- `stopped` - Cleanly stopped
+- `destroying` - Being destroyed and cleaned up
+- `destroyed` - Completely destroyed
+- `error` - Failed and non-operational
+- `recovering` - Attempting recovery from error
+
+## ServiceBase
+
+Base class that all services should extend. Provides:
+
+- Standardized lifecycle methods (`initialize`, `start`, `stop`, `destroy`)
+- Health monitoring and recovery
+- Event emission for state changes
+- Integrated logging
+- Error handling and timeout management
+
+### Basic Usage
+
+```javascript
+import { ServiceBase } from '$lib/services/index.js';
+
+class DatabaseService extends ServiceBase {
+  async _init(config) {
+    this.connectionString = config.connectionString;
+  }
+
+  async _start() {
+    this.connection = await createConnection(this.connectionString);
+  }
+
+  async _stop() {
+    await this.connection?.close();
+  }
+
+  async _healthCheck() {
+    const start = Date.now();
+    await this.connection.ping();
+    return { latency: Date.now() - start };
+  }
+}
+
+// Usage
+const db = new DatabaseService('database');
+await db.initialize({ connectionString: 'postgres://...' });
+await db.start();
+
+// Listen to events
+db.on('healthChanged', ({ healthy }) => {
+  console.log(`Database is ${healthy ? 'healthy' : 'unhealthy'}`);
+});
+```
+
+### Protected Methods to Override
+
+- `_init(config)` - Initialize service with configuration
+- `_start()` - Start the service
+- `_stop()` - Stop the service
+- `_destroy()` - Clean up resources (optional)
+- `_recover()` - Custom recovery logic (optional)
+- `_healthCheck()` - Return health status (optional)
+
+### Events
+
+- `stateChanged` - Service state transitions
+- `healthChanged` - Health status changes
+- `error` - Service errors
+
+## ServiceManager
+
+Manages multiple services with dependency resolution and coordinated lifecycle operations.
+
+### Features
+
+- Service registration with dependency declarations
+- Automatic dependency resolution and startup ordering
+- Coordinated shutdown in reverse dependency order
+- Health monitoring for all services
+- Centralized logging control
+- Service recovery management
+
+### Usage
+
+```javascript
+import { ServiceManager } from '$lib/services/index.js';
+import DatabaseService from './services/DatabaseService.js';
+import AuthService from './services/AuthService.js';
+
+const manager = new ServiceManager({
+  debug: true,
+  stopTimeout: 10000
+});
+
+// Register services with dependencies
+manager.register('database', DatabaseService, {
+  connectionString: 'postgres://localhost/myapp'
+});
+
+manager.register('auth', AuthService, {
+  secret: process.env.JWT_SECRET
+}, {
+  dependencies: ['database'] // auth depends on database
+});
+
+// Start all services in dependency order
+await manager.startAll();
+
+// Check system health
+const health = await manager.checkHealth();
+
+// Stop all services in reverse dependency order
+await manager.stopAll();
+```
+
+### Service Registration
+
+```javascript
+manager.register(name, ServiceClass, config, options);
+```
+
+- `name` - Unique service identifier
+- `ServiceClass` - Class extending ServiceBase
+- `config` - Service-specific configuration
+- `options.dependencies` - Array of service names this service depends on
+
+### Health Monitoring
+
+```javascript
+// Listen for health changes
+manager.on('service:healthChanged', ({ service, healthy }) => {
+  if (!healthy) {
+    console.error(`Service ${service} became unhealthy`);
+  }
+});
+
+// Check individual service health
+const dbHealth = await manager.getServiceHealth('database');
+
+// Check all services health
+const systemHealth = await manager.checkHealth();
+```
+
+### 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');
+```
+
+## Best Practices
+
+1. **Always extend ServiceBase** for consistent lifecycle management
+2. **Keep initialization 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
+
+## Testing
+
+Services include comprehensive test suites demonstrating:
+
+- Lifecycle state transitions
+- Error handling and recovery
+- Dependency resolution
+- Health monitoring
+- Event emission
+
+Run tests with your project's test command to ensure service reliability.

package/dist/services/index.d.ts

@@ -1 +1,6 @@
-export * from "./internal/index.js";
+export { default as ServiceBase } from "./service-base/ServiceBase.js";
+export { default as ServiceManager } from "./service-manager/ServiceManager.js";
+export * from "./service-base/constants.js";
+export * from "./service-manager/constants.js";
+export * from "./service-base/typedef.js";
+export * from "./service-manager/typedef.js";

package/dist/services/index.js

@@ -1 +1,8 @@
-export * from './internal/index.js';
+export { default as ServiceBase } from './service-base/ServiceBase.js';
+export { default as ServiceManager } from './service-manager/ServiceManager.js';
+
+export * from './service-base/constants.js';
+export * from './service-manager/constants.js';
+
+export * from './service-base/typedef.js';
+export * from './service-manager/typedef.js';

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

@@ -157,5 +157,5 @@ export type HealthStatus = import("./typedef.js").HealthStatus;
 export type StateChangeEvent = import("./typedef.js").StateChangeEvent;
 export type HealthChangeEvent = import("./typedef.js").HealthChangeEvent;
 export type ServiceErrorEvent = import("./typedef.js").ServiceErrorEvent;
-import { EventEmitter } from '../../../classes/event-emitter';
-import { Logger } from '../../../logging/internal/unified-logger';
+import { EventEmitter } from '../../classes/event-emitter';
+import { Logger } from '../../logging/internal/logger';

package/dist/services/{internal/service-base → service-base}/ServiceBase.js

@@ -50,8 +50,8 @@
  * }
  */
 
-import { EventEmitter } from '../../../classes/event-emitter';
-import { Logger, INFO } from '../../../logging/internal/unified-logger';
+import { EventEmitter } from '../../classes/event-emitter';
+import { Logger, INFO } from '../../logging/internal/logger';
 
 import {
   CREATED,

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

@@ -38,61 +38,49 @@
  */
 /**
  * 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";

package/dist/services/{internal/service-base → service-base}/constants.js

@@ -39,72 +39,60 @@
 
 /**
  * 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';

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

@@ -76,7 +76,7 @@ export type ServiceInstance = {
     /**
      * - Service logger
      */
-    logger: import("../../../logging/internal/unified-logger").Logger;
+    logger: import("../../logging/internal/logger").Logger;
     initialize: (config?: any) => Promise<boolean>;
     start: () => Promise<boolean>;
     stop: (options?: StopOptions) => Promise<boolean>;

package/dist/services/{internal/service-base → service-base}/typedef.js

@@ -59,7 +59,7 @@
  * @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 {import('../../logging/internal/logger').Logger} logger - Service logger
  * @property {(config?: *) => Promise<boolean>} initialize
  * @property {() => Promise<boolean>} start
  * @property {(options?: StopOptions) => Promise<boolean>} stop

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

@@ -141,5 +141,5 @@ export type ServiceManagerConfig = import("./typedef.js").ServiceManagerConfig;
 export type ServiceEntry = import("./typedef.js").ServiceEntry;
 export type HealthCheckResult = import("./typedef.js").HealthCheckResult;
 export type StopOptions = import("../service-base/typedef.js").StopOptions;
-import { EventEmitter } from '../../../classes/event-emitter';
-import { Logger } from '../../../logging/index.js';
+import { EventEmitter } from '../../classes/event-emitter';
+import { Logger } from '../../logging/index.js';

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

@@ -63,8 +63,8 @@
  * });
  */
 
-import { EventEmitter } from '../../../classes/event-emitter';
-import { Logger, DEBUG, INFO, WARN } from '../../../logging/index.js';
+import { EventEmitter } from '../../classes/event-emitter';
+import { Logger, DEBUG, INFO, WARN } from '../../logging/index.js';
 
 import {
   NOT_CREATED,

package/dist/typedef/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./context.js";
 export * from "./drag.js";
 export * from "./drop.js";
-export * from "./image.js";

package/dist/typedef/index.js

@@ -1,4 +1,4 @@
 export * from './context.js';
 export * from './drag.js';
 export * from './drop.js';
-export * from './image.js';
+export * from '../media/typedef.js';

package/dist/{components → ui/components}/button-group/ButtonGroup.svelte

@@ -6,7 +6,7 @@
    */
 
   import { onMount } from 'svelte';
-  import { findFirst } from '../../util/array/index.js';
+  import { findFirst } from '../../../util/array/index.js';
 
   /**
    * @type {{

package/dist/{components → ui/components}/game-box/GameBox.svelte

@@ -6,7 +6,7 @@
     getGameWidthOnPortrait
   } from './gamebox.util.js';
 
-  import { enableContainerScaling } from '../../util/design-system/index.js';
+  import { enableContainerScaling } from '../../../design/index.js';
   // import { enableContainerScaling } from '@hkdigital/lib-sveltekit/util/design-system/index.js';
 
   /**

package/dist/ui/components/hk-app-layout/HkAppLayout.state.svelte.d.ts

@@ -0,0 +1,6 @@
+export class AppLayoutState {
+    landscapeOnSmallScreen: boolean;
+}
+export const createOrGetState: (contextKey?: import("../../../typedef").ContextKey) => AppLayoutState;
+export const createState: (contextKey?: import("../../../typedef").ContextKey) => AppLayoutState;
+export const getState: (contextKey?: import("../../../typedef").ContextKey) => AppLayoutState;

package/dist/{components → ui/components}/hk-app-layout/HkAppLayout.state.svelte.js

@@ -1,4 +1,4 @@
-import { defineStateContext } from '../../util/svelte/state-context';
+import { defineStateContext } from '../../../util/svelte/state-context/index.js';
 
 import { browser } from '$app/environment';
 

package/dist/{components → ui/components}/hk-app-layout/HkAppLayout.svelte

@@ -20,7 +20,7 @@
 	 * </AppLayout>
 	 */
 
-	import { useResizeObserver } from '../../util/svelte/observe/index.js';
+	import { useResizeObserver } from '../../../util/svelte/observe/index.js';
 
 	/**
 	 * @typedef AppLayoutProps

package/dist/{components → ui/components}/image-box/ImageBox.svelte

@@ -1,7 +1,7 @@
 <script>
-	import { ImageLoader } from '../../classes/svelte/image/index.js';
-	import { ImageVariantsLoader } from '../../classes/svelte/image/index.js';
-	import { toSingleImageMeta } from '../../util/image/index.js';
+	import { ImageLoader } from '../../../network/loaders.js';
+	import { ImageVariantsLoader } from '../../../network/loaders.js';
+	import { toSingleImageMeta } from '../../../network/loaders/image/utils/index.js';
 
 	/**
 	 * @type {{
@@ -13,12 +13,12 @@
 	 *   aspect?: string,
 	 *   overflow?: string,
 	 *   fit?: 'contain' | 'cover' | 'fill',
-	 *   position?: import('../../typedef/image.js').ObjectPosition,
-	 *   imageMeta?: import('../../typedef').ImageSource,
-	 *   imageLoader?: import('../../classes/svelte/image/index.js').ImageLoader,
+	 *   position?: import('../../../network/typedef.js').ObjectPosition,
+	 *   imageSource?: import('../../../network/typedef.js').ImageSource,
+	 *   imageLoader?: import('../../../network/loaders.js').ImageLoader,
 	 *   alt?: string,
 	 *   id?: string|Symbol
-	 *   onProgress?: (progress: import('../../classes/svelte/network-loader/typedef.js').LoadingProgress, id: string|Symbol) => void,
+	 *   onProgress?: (progress: import('../../../network/typedef.js').LoadingProgress, id: string|Symbol) => void,
 	 *   [attr: string]: any
 	 * }}
 	 */
@@ -37,7 +37,7 @@
 		position = 'left top',
 
 		// Image data
-		imageMeta,
+		imageSource,
 		imageLoader,
 
 		// Accessibility
@@ -74,14 +74,14 @@
 
 	$effect(() => {
 		// Setup variants loader for responsive images
-		if (Array.isArray(imageMeta) && !imageLoader && !variantsLoader) {
-			variantsLoader = new ImageVariantsLoader(imageMeta, {
+		if (Array.isArray(imageSource) && !imageLoader && !variantsLoader) {
+			variantsLoader = new ImageVariantsLoader(imageSource, {
 				devicePixelRatio: window.devicePixelRatio
 			});
 		}
 		// Handle single image meta
-		else if (imageMeta && !variantsLoader) {
-			imageMeta_ = toSingleImageMeta(imageMeta);
+		else if (imageSource && !variantsLoader) {
+			imageMeta_ = toSingleImageMeta(imageSource);
 		}
 	});
 
@@ -107,7 +107,7 @@
 	});
 
 	$effect(() => {
-		if (!imageMeta && imageLoader && !imageLoader_) {
+		if (!imageSource && imageLoader && !imageLoader_) {
 			imageLoader_ = imageLoader;
 			imageMeta_ = imageLoader.imageMeta;
 		}
@@ -115,7 +115,7 @@
 
 	$effect(() => {
 		if (imageMeta_ && !imageLoader_) {
-			imageLoader_ = new ImageLoader({ imageMeta: imageMeta_ });
+			imageLoader_ = new ImageLoader(imageMeta_);
 		}
 	});
 

package/dist/{components → ui/components}/image-box/ImageBox.svelte.d.ts

@@ -10,9 +10,9 @@ type ImageBox = {
         height?: string;
         aspect?: string;
         overflow?: string;
-        fit?: "fill" | "cover" | "contain";
+        fit?: "fill" | "contain" | "cover";
         position?: string;
-        imageMeta?: ImageSource;
+        imageSource?: ImageSource;
         imageLoader?: ImageLoader;
         alt?: string;
         id?: string | Symbol;
@@ -29,10 +29,10 @@ declare const ImageBox: import("svelte").Component<{
     aspect?: string;
     overflow?: string;
     fit?: "contain" | "cover" | "fill";
-    position?: import("../../typedef/image.js").ObjectPosition;
-    imageMeta?: import("../../typedef").ImageSource;
-    imageLoader?: import("../../classes/svelte/image/index.js").ImageLoader;
+    position?: import("../../../network/typedef.js").ObjectPosition;
+    imageSource?: import("../../../network/typedef.js").ImageSource;
+    imageLoader?: import("../../../network/loaders.js").ImageLoader;
     alt?: string;
     id?: string | Symbol;
-    onProgress?: (progress: import("../../classes/svelte/network-loader/typedef.js").LoadingProgress, id: string | Symbol) => void;
+    onProgress?: (progress: import("../../../network/typedef.js").LoadingProgress, id: string | Symbol) => void;
 }, {}, "">;

package/dist/{components → ui/components}/image-box/index.js

@@ -1,4 +1,4 @@
-/** @typedef {import('../../config/typedef.js').ImageMeta} ImageMeta */
+/** @typedef {import('../../../config/typedef.js').ImageMeta} ImageMeta */
 
 export { default as ImageBox } from './ImageBox.svelte';
 

package/dist/{components → ui/components}/presenter/ImageSlide.svelte

@@ -3,7 +3,7 @@
 
   /**
    * @type {{
-   *   imageMeta?: import('../../typedef').ImageSource,
+   *   imageMeta?: import('../../../network/typedef.js').ImageSource,
    *   slideDuration?: number,
    *   nextSlideLabel?: string,
    *   presenter?: { gotoSlide: (name: string) => void, getCurrentSlideName: () => string },
@@ -55,7 +55,7 @@
 
 <div class="justify-self-stretch self-stretch grid" class:invisible={!show}>
   <ImageBox
-    {imageMeta}
+    imageSource={imageMeta}
     {fit}
     {position}
     onProgress={progressListener}

package/dist/{components → ui/components}/presenter/ImageSlide.svelte.d.ts

@@ -14,13 +14,13 @@ type ImageSlide = {
             loaded: () => void;
             cancel: () => void;
         };
-        fit?: "fill" | "cover" | "contain";
+        fit?: "fill" | "contain" | "cover";
         position?: string;
     }>): void;
 };
 declare const ImageSlide: import("svelte").Component<{
     [attr: string]: any;
-    imageMeta?: import("../../typedef").ImageSource;
+    imageMeta?: import("../../../network/typedef.js").ImageSource;
     slideDuration?: number;
     nextSlideLabel?: string;
     presenter?: {

package/dist/{components → ui/components}/presenter/Presenter.state.svelte.d.ts

@@ -71,4 +71,4 @@ export type Layer = import("./typedef").Layer;
 export type PresenterRef = import("./typedef").PresenterRef;
 export type LoadController = import("./typedef").LoadController;
 export type ListenerParams = import("./typedef").ListenerParams;
-import { HkPromise } from '../../classes/promise/index.js';
+import { HkPromise } from '../../../classes/promise/index.js';

package/dist/{components → ui/components}/presenter/Presenter.state.svelte.js

@@ -1,10 +1,10 @@
 import { tick } from 'svelte';
 
-import { findFirst } from '../../util/array/index.js';
+import { findFirst } from '../../../util/array/index.js';
 
 import { untrack } from 'svelte';
 
-import { HkPromise } from '../../classes/promise/index.js';
+import { HkPromise } from '../../../classes/promise/index.js';
 
 import { STAGE_BEFORE, STAGE_SHOW } from './constants.js';
 

package/dist/{components → ui/components}/presenter/util.js

@@ -1,8 +1,8 @@
 import { tick } from 'svelte';
 
-import * as expect from '../../util/expect/index.js';
+import * as expect from '../../../util/expect/index.js';
 
-import { pushNotEmpty } from '../../util/array/index.js';
+import { pushNotEmpty } from '../../../util/array/index.js';
 
 import { TRANSITION_CSS, FADE_IN, FADE_OUT } from './constants.js';
 

package/dist/{components → ui/components}/virtual-viewport/VirtualViewport.svelte

@@ -5,7 +5,7 @@
     getRootCssDesignHeight,
     getClampParams,
     clamp
-  } from '../../util/design-system/index.js';
+  } from '../../../design/index.js';
 
   /**
    * Virtual viewport component that creates a container with its own scaling