@hkdigital/lib-core 0.3.11 → 0.3.13

package/dist/network/states/mocks.js

@@ -1,30 +1,30 @@
-import { CONTENT_TYPE, CONTENT_LENGTH } from '../../constants/http/index.js';
-
-import { OCTET_STREAM } from '../../constants/mime/application.js';
-
-const BASE64_DATA =
-  'UklGRnwAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YVgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
-
-/**
- * Create a response value that can be used by a mocked
- * fetch function
- *
- * @returns {Response}
- */
-export function createDataResponse(/* data , options */) {
-  const binaryString = atob(BASE64_DATA);
-  const bytes = new Uint8Array(binaryString.length);
-
-  for (let i = 0; i < binaryString.length; i++) {
-    bytes[i] = binaryString.charCodeAt(i);
-  }
-
-  const response = new Response(bytes, {
-    headers: new Headers({
-      [CONTENT_TYPE]: OCTET_STREAM,
-      [CONTENT_LENGTH]: String(bytes.length)
-    })
-  });
-
-  return response;
-}
+import { CONTENT_TYPE, CONTENT_LENGTH } from '../../constants/http/index.js';
+
+import { OCTET_STREAM } from '../../constants/mime/application.js';
+
+const BASE64_DATA =
+  'UklGRnwAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YVgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
+
+/**
+ * Create a response value that can be used by a mocked
+ * fetch function
+ *
+ * @returns {Response}
+ */
+export function createDataResponse(/* data , options */) {
+  const binaryString = atob(BASE64_DATA);
+  const bytes = new Uint8Array(binaryString.length);
+
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+
+  const response = new Response(bytes, {
+    headers: new Headers({
+      [CONTENT_TYPE]: OCTET_STREAM,
+      [CONTENT_LENGTH]: String(bytes.length)
+    })
+  });
+
+  return response;
+}

package/dist/network/states/typedef.js

@@ -1,8 +1,8 @@
-/**
- * @typedef {Object} LoadingProgress
- * @property {number} bytesLoaded
- * @property {number} size
- * @property {boolean} loaded
- */
-
-export default {};
+/**
+ * @typedef {Object} LoadingProgress
+ * @property {number} bytesLoaded
+ * @property {number} size
+ * @property {boolean} loaded
+ */
+
+export default {};

package/dist/network/typedef.js

@@ -1,10 +1,10 @@
-/**
- * Network module type definitions
- * 
- * Re-exports types from all network submodules for convenient access
- */
-
-export * from './http/typedef.js';
-export * from './cache/typedef.js';
-export * from './states/typedef.js';
+/**
+ * Network module type definitions
+ * 
+ * Re-exports types from all network submodules for convenient access
+ */
+
+export * from './http/typedef.js';
+export * from './cache/typedef.js';
+export * from './states/typedef.js';
 export * from './loaders/typedef.js';

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';