@hkdigital/lib-core 0.5.92 → 0.5.93

package/README.md

@@ -3,7 +3,28 @@
 Core library that we use to power up our SvelteKit projects
 
 This is a library for [SvelteKit](https://svelte.dev/) projects.
-It contains common code, base components and documentation that help you with setting up a new project.
+It contains common code, base components and documentation that help
+you with setting up a new project.
+
+## Table of Contents
+
+- [Using the library](#using-the-library)
+  - [Install](#install)
+  - [Peer Dependencies](#peer-dependencies)
+  - [Design System & Configuration](#design-system--configuration)
+  - [Logging System](#logging-system)
+- [Documentation](#documentation)
+  - [Update](#update)
+  - [Available scripts](#available-scripts)
+  - [Import Validation](#import-validation)
+  - [Import Patterns and Export Structure](#import-patterns-and-export-structure)
+  - [CSS Architecture](#css-architecture-appcss)
+  - [Critical: data-theme Attribute](#critical-data-theme-attribute)
+- [Building the library](#building-the-library)
+- [Running the showcase app](#running-the-showcase-app)
+- [Developing](#developing)
+- [Publishing](#publishing)
+- [Contribute](#contribute)
 
 ## Using the library
 
@@ -247,14 +268,47 @@ The library includes a comprehensive logging system that provides:
 
 ## Documentation
 
-For detailed setup guides and configuration:
-- **Project setup**: [docs/setup/new-project.md](./docs/setup/new-project.md) - SvelteKit project setup
-- **Library setup**: [docs/setup/new-lib.md](./docs/setup/new-lib.md) - SvelteKit library setup
-- **Services & logging**: [docs/setup/services-logging.md](./docs/setup/services-logging.md) - Service management architecture
-- **Configuration files**: [docs/config/root-config-files.md](./docs/config/root-config-files.md) - Config file reference
-- **Design system**: [src/lib/design/README.md](./src/lib/design/README.md) - Design tokens and theming
-- **Vite configuration**: [src/lib/config/README.md](./src/lib/config/README.md) - Build configuration
-- **Logging system**: [src/lib/logging/README.md](./src/lib/logging/README.md) - Server and client logging
+Comprehensive documentation organized by topic.
+
+### Getting Started
+
+Start here if you're setting up a new project or library:
+
+- **[New project setup](./docs/setup/new-project.md)** - Complete guide
+  for setting up a SvelteKit application with lib-core
+- **[New library setup](./docs/setup/new-lib.md)** - Complete guide for
+  setting up a SvelteKit library with lib-core
+
+### Architecture Guides
+
+Learn how the different systems work together:
+
+- **[Services & logging architecture](./docs/setup/services-logging.md)**
+  - How service management and logging integrate with SvelteKit
+- **[Service patterns](./src/lib/services/PATTERNS.md)** - Best
+  practices and design patterns for implementing services
+- **[Service plugins](./src/lib/services/PLUGINS.md)** - ConfigPlugin
+  and custom plugin development
+
+### API Reference
+
+Detailed API documentation for each module:
+
+- **[Logging](./src/lib/logging/README.md)** - Server and client
+  logging API, log levels, and formatters
+- **[Services](./src/lib/services/README.md)** - ServiceBase and
+  ServiceManager API reference
+- **[Design system](./src/lib/design/README.md)** - Design tokens,
+  theming, and UI utilities
+- **[Vite configuration](./src/lib/config/README.md)** - Build
+  configuration and optimization
+
+### Configuration
+
+Reference documentation for configuration files:
+
+- **[Root config files](./docs/config/root-config-files.md)** - Guide
+  to vite.config.js, tailwind.config.js, and other root configs
 
 ### Update
 

package/dist/browser/info/device.js

@@ -131,13 +131,8 @@ export function getIsPhone() {
  * @returns {boolean} true if mobile device
  */
 export function getIsMobile() {
-  // @ts-ignore
-  if (navigator?.userAgentData?.mobile !== undefined) {
-    // Modern API - most reliable
-    // @ts-ignore
-    return navigator.userAgentData.mobile;
-  }
-
+  // Check Apple devices first - userAgentData.mobile is unreliable for
+  // iPads with M-series chips (reports false despite being mobile)
   if (getIsAppleMobile()) {
     return true;
   }
@@ -146,6 +141,13 @@ export function getIsMobile() {
     return true;
   }
 
+  // @ts-ignore
+  if (navigator?.userAgentData?.mobile !== undefined) {
+    // Modern API - use as fallback
+    // @ts-ignore
+    return navigator.userAgentData.mobile;
+  }
+
   return false;
 }
 

package/dist/logging/README.md

@@ -3,6 +3,14 @@
 Universal logging utilities for SvelteKit applications with
 server/client/universal logger factories.
 
+**See also:**
+- **Architecture**: [docs/setup/services-logging.md](../../docs/setup/services-logging.md)
+  - How logging and services work together
+- **Services**: [src/lib/services/README.md](../services/README.md) -
+  Service management system
+- **Main README**: [README.md](../../README.md) - Library overview and
+  setup
+
 ## Installation
 
 ```bash
@@ -182,61 +190,15 @@ export function handleError({ error, event }) {
 }
 ```
 
-### Client Service Integration
-
-When integrating with a service management system, you can set up global 
-error handling and forward service logs to the main logger:
-
-```javascript
-import { ServiceManager } from '@hkdigital/lib-core/services/index.js';
-import { initClientLogger } from '$lib/logging/client.js';
-
-/** @type {ServiceManager} */
-let manager;
-
-export async function initClientServices() {
-  if (!manager) {
-    const logger = initClientLogger();
-
-    // Catch errors and unhandled promise rejections
-    
-    // Log unhandled errors
-    window.addEventListener('error', (event) => {
-      logger.error(event, { url: window.location.pathname });
-      event.preventDefault();
-    });
-
-    // Log unhandled promise rejections
-    window.addEventListener('unhandledrejection', (event) => {
-      logger.error(event, { url: window.location.pathname });
-      // Ignored by Firefox
-      event.preventDefault();
-    });
-
-    manager = new ServiceManager({ debug: true });
-
-    // Listen to all log events and forward them to the logger
-    manager.onLogEvent((logEvent) => {
-      logger.logFromEvent(logEvent);
-    });
-
-    // Register services
-    manager.register(SERVICE_AUDIO, AudioService);
-    manager.register(SERVICE_EVENT_LOG, EventLogService);
-    manager.register(SERVICE_PLAYER_DATA, PlayerDataService);
-  }
+### Service Integration
 
-  await manager.startAll();
-  return manager;
-}
+For integrating logging with the service management system, including
+how to forward service logs to the main logger, see:
 
-export function getManager() {
-  if (!manager) {
-    throw new Error('Client services should be initialised first');
-  }
-  return manager;
-}
-```
+- [Services README](../services/README.md) - ServiceManager log event
+  forwarding
+- [Services & Logging Architecture](../../docs/setup/services-logging.md)
+  - Complete integration examples
 
 ## Development
 

package/dist/services/PATTERNS.md

@@ -0,0 +1,476 @@
+# Service Patterns and Best Practices
+
+Design patterns and best practices for implementing services with the
+ServiceBase and ServiceManager system.
+
+**See also:**
+- **API Reference**: [README.md](./README.md) - ServiceBase and
+  ServiceManager API
+- **Plugins**: [PLUGINS.md](./PLUGINS.md) - Plugin system and
+  ConfigPlugin
+- **Architecture**: [docs/setup/services-logging.md](../../docs/setup/services-logging.md)
+  - Integration patterns
+
+## Service Access Patterns
+
+Services receive helpful utilities in their constructor options for
+accessing other services and the manager.
+
+### Basic Pattern
+
+```javascript
+/**
+ * Example service that depends on other services
+ */
+class AuthService extends ServiceBase {
+  /** @type {(<T>(serviceName: string) => T)} */
+  #getService;
+
+  /** @type {() => import('@hkdigital/lib-core/services/index.js').ServiceManager} */
+  #getManager;
+
+  constructor(serviceName, options) {
+    super(serviceName, options);
+
+    // Store service access utilities as private methods
+    this.#getService = options.getService;   // Bound getService function
+    this.#getManager = options.getManager;   // Function to get manager (lazy)
+  }
+
+  async authenticateUser(credentials) {
+    // Access other services with full type safety and error checking
+    const database = this.#getService('database');
+    const user = await database.findUser(credentials.username);
+
+    // Access manager for advanced operations when needed
+    const manager = this.#getManager();
+    const health = await manager.checkHealth();
+
+    return user;
+  }
+}
+```
+
+### Recommended Pattern: Private Methods
+
+The recommended approach is to store service access functions as
+**private methods** using the hash prefix. This pattern provides:
+
+**Benefits:**
+- **Keeps the API clean** - No public getService/getManager methods
+  exposed
+- **Prevents serialization issues** - Private fields don't serialize
+  to JSON
+- **Enforces proper encapsulation** - Service dependencies stay
+  internal
+- **Provides type safety** - Full generic support with
+  `this.#getService<DatabaseService>('database')`
+
+**Example:**
+
+```javascript
+/**
+ * Unified service for tracking complete player data including progress
+ * and profile matches
+ */
+export default class PlayerService extends ServiceBase {
+
+  /** @type {(<T>(serviceName: string) => T)} */
+  #getService;
+
+  /**
+   * @param {string} serviceName
+   * @param {import('@hkdigital/lib-core/services/typedef.js').ServiceOptions} [options]
+   */
+  constructor(serviceName, options) {
+    super(serviceName, options);
+
+    this.#getService = options?.getService;
+  }
+
+  async getPlayerProfile(playerId) {
+    // Access dependent services cleanly
+    const database = this.#getService('database');
+    const analytics = this.#getService('analytics');
+
+    const profile = await database.getPlayer(playerId);
+    const stats = await analytics.getPlayerStats(playerId);
+
+    return { ...profile, stats };
+  }
+}
+```
+
+### Service Access Methods
+
+ServiceManager provides two access patterns:
+
+```javascript
+// 1. Permissive - returns undefined if not found/created
+const service = manager.get('optional-service');
+if (service) {
+  // Use service safely
+}
+
+// 2. Strict - throws error if not found/created
+const service = manager.getService('required-service'); // Throws if missing
+```
+
+**When to use each:**
+- Use `get()` for optional services or when checking availability
+- Use `getService()` for required dependencies (clearer error messages)
+
+### Constructor Utilities Benefits
+
+**Lightweight:**
+Functions don't serialize, keeping services serialization-safe.
+
+**Lazy access:**
+Manager is only accessed when needed, avoiding circular dependencies
+during initialization.
+
+**Type safety:**
+Full generic support with JSDoc annotations enables IDE autocomplete
+and type checking.
+
+**Error handling:**
+Clear, consistent errors when services are missing or not yet
+initialized.
+
+## Configuration Patterns
+
+### Initial Configuration vs Reconfiguration
+
+Services should handle both initial setup and runtime reconfiguration
+intelligently.
+
+**Pattern:**
+
+```javascript
+class DatabaseService extends ServiceBase {
+  // eslint-disable-next-line no-unused-vars
+  async _configure(newConfig, oldConfig = null) {
+    if (!oldConfig) {
+      // Initial configuration - store all settings
+      this.connectionString = newConfig.connectionString;
+      this.maxConnections = newConfig.maxConnections || 10;
+      this.timeout = newConfig.timeout || 5000;
+      return;
+    }
+
+    // Reconfiguration - handle changes intelligently
+    if (oldConfig.connectionString !== newConfig.connectionString) {
+      // Connection changed - need to reconnect
+      await this.connection?.close();
+      this.connectionString = newConfig.connectionString;
+
+      if (this.state === 'running') {
+        this.connection = await createConnection(this.connectionString);
+      }
+    }
+
+    if (oldConfig.maxConnections !== newConfig.maxConnections) {
+      // Pool size changed - update without reconnect
+      this.maxConnections = newConfig.maxConnections;
+      await this.connection?.setMaxConnections(this.maxConnections);
+    }
+
+    if (oldConfig.timeout !== newConfig.timeout) {
+      // Timeout changed - just update the setting
+      this.timeout = newConfig.timeout;
+    }
+  }
+}
+```
+
+**Key principles:**
+- Check `!oldConfig` to detect initial configuration
+- Compare old and new config to identify what changed
+- Apply minimal changes (don't restart if not needed)
+- Update running state when possible
+
+### Configuration Defaults
+
+Handle missing configuration gracefully with sensible defaults.
+
+**Pattern:**
+
+```javascript
+async _configure(newConfig, oldConfig = null) {
+  // Use defaults for missing values
+  this.host = newConfig.host || 'localhost';
+  this.port = newConfig.port || 5432;
+  this.maxConnections = newConfig.maxConnections || 10;
+  this.timeout = newConfig.timeout || 5000;
+  this.retryAttempts = newConfig.retryAttempts ?? 3; // Use ?? for zero values
+}
+```
+
+## Lifecycle Patterns
+
+### Proper Resource Management
+
+Always clean up resources in the stop method.
+
+**Pattern:**
+
+```javascript
+class WebSocketService extends ServiceBase {
+  async _start() {
+    this.ws = new WebSocket(this.url);
+    this.intervalId = setInterval(() => this.#ping(), 30000);
+
+    await new Promise((resolve) => {
+      this.ws.onopen = resolve;
+    });
+  }
+
+  async _stop() {
+    // Clear timers
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+
+    // Close connections
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  async _destroy() {
+    // Clean up any remaining resources
+    await this._stop();
+  }
+}
+```
+
+### Async Initialization
+
+Keep `_configure()` lightweight, do heavy work in `_start()`.
+
+**Good:**
+
+```javascript
+async _configure(newConfig, oldConfig = null) {
+  // Just store config
+  this.apiKey = newConfig.apiKey;
+  this.endpoint = newConfig.endpoint;
+}
+
+async _start() {
+  // Heavy work here
+  this.client = await createApiClient(this.apiKey, this.endpoint);
+  await this.client.authenticate();
+}
+```
+
+**Bad:**
+
+```javascript
+async _configure(newConfig, oldConfig = null) {
+  // Don't do heavy work in configure
+  this.client = await createApiClient(newConfig.apiKey);
+  await this.client.authenticate(); // ❌ Heavy operation
+}
+```
+
+## Health Check Patterns
+
+### Return Useful Metrics
+
+Health checks should return actionable information.
+
+**Pattern:**
+
+```javascript
+async _healthCheck() {
+  const start = Date.now();
+
+  try {
+    await this.connection.ping();
+
+    return {
+      latency: Date.now() - start,
+      connections: this.connection.activeConnections,
+      queueSize: this.connection.queueSize
+    };
+  } catch (error) {
+    return {
+      error: error.message,
+      lastSuccessful: this.lastSuccessfulPing
+    };
+  }
+}
+```
+
+### Implement Recovery Logic
+
+Provide custom recovery for services that can auto-heal.
+
+**Pattern:**
+
+```javascript
+async _recover() {
+  // Close broken connection
+  await this.connection?.close();
+
+  // Wait before reconnecting
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Recreate connection
+  this.connection = await createConnection(this.connectionString);
+
+  // Verify it works
+  await this.connection.ping();
+}
+```
+
+## Error Handling Patterns
+
+### Graceful Degradation
+
+Handle errors without crashing the entire system.
+
+**Pattern:**
+
+```javascript
+class CacheService extends ServiceBase {
+  async get(key) {
+    try {
+      return await this.redis.get(key);
+    } catch (error) {
+      this.logger.warn('Cache read failed, falling back', { key, error });
+      return null; // Graceful fallback
+    }
+  }
+
+  async set(key, value) {
+    try {
+      await this.redis.set(key, value);
+    } catch (error) {
+      this.logger.error('Cache write failed', { key, error });
+      // Don't throw - cache writes are not critical
+    }
+  }
+}
+```
+
+### Timeout Handling
+
+Set appropriate timeouts for long-running operations.
+
+**Pattern:**
+
+```javascript
+async _start() {
+  const timeout = this.config.startTimeout || 10000;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    this.connection = await fetch(this.endpoint, {
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+```
+
+## Dependency Management Patterns
+
+### Declare Dependencies Explicitly
+
+Always declare service dependencies for proper startup ordering.
+
+**Pattern:**
+
+```javascript
+// Register services with explicit dependencies
+manager.register('database', DatabaseService, dbConfig);
+
+manager.register(
+  'cache',
+  CacheService,
+  cacheConfig,
+  {
+    dependencies: ['database'] // Cache needs database
+  }
+);
+
+manager.register(
+  'auth',
+  AuthService,
+  authConfig,
+  {
+    dependencies: ['database', 'cache'] // Auth needs both
+  }
+);
+```
+
+### Startup Priority
+
+Use priority for services that should start early.
+
+**Pattern:**
+
+```javascript
+// Start logger first (highest priority)
+manager.register(
+  'logger',
+  LoggerService,
+  logConfig,
+  { startupPriority: 100 }
+);
+
+// Then database (high priority)
+manager.register(
+  'database',
+  DatabaseService,
+  dbConfig,
+  { startupPriority: 50 }
+);
+
+// Then other services (default priority: 0)
+manager.register('auth', AuthService, authConfig);
+```
+
+## Best Practices
+
+### Service Design
+
+1. **Always extend ServiceBase** for consistent lifecycle management
+2. **Keep configuration 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. **Handle errors gracefully** and implement recovery where
+   appropriate
+
+### Service Registration
+
+6. **Declare dependencies explicitly** when registering with
+   ServiceManager
+7. **Use descriptive service names** for better logging and debugging
+8. **Set appropriate priorities** for services with ordering
+   requirements
+
+### Service Implementation
+
+9. **Store service access as private methods** using hash prefix
+10. **Return useful metrics** from health checks
+11. **Implement intelligent reconfiguration** that applies minimal
+    changes
+12. **Handle missing config gracefully** with sensible defaults
+
+### Resource Management
+
+13. **Clean up all resources** in `_stop()` (timers, connections,
+    listeners)
+14. **Set appropriate timeouts** for long-running operations
+15. **Use graceful degradation** instead of throwing errors when
+    possible
+16. **Test service lifecycle** (start, stop, restart, reconfigure)