@hkdigital/lib-core 0.3.10 → 0.3.12

package/dist/errors/index.d.ts

@@ -2,3 +2,4 @@ export * from "./api.js";
 export * from "./generic.js";
 export * from "./http.js";
 export * from "./jwt.js";
+export * from "./promise.js";

package/dist/errors/index.js

@@ -2,3 +2,4 @@ export * from './api.js';
 export * from './generic.js';
 export * from './http.js';
 export * from './jwt.js';
+export * from './promise.js';

package/dist/errors/promise.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Promise-related error classes
+ */
+/**
+ * Error class specifically for HkPromise operations
+ * Provides timeout and cancelled properties with proper type safety
+ */
+export class PromiseError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {object} [options] - Error options
+     * @param {boolean} [options.timeout=false] - Whether this is a timeout error
+     * @param {boolean} [options.cancelled=false] - Whether this is a cancellation error
+     * @param {Error|*} [options.cause] - Original error or cause
+     * @param {*} [options.details] - Additional details object
+     */
+    constructor(message: string, options?: {
+        timeout?: boolean;
+        cancelled?: boolean;
+        cause?: Error | any;
+        details?: any;
+    });
+    timeout: boolean;
+    cancelled: boolean;
+    cause: any;
+    details: any;
+}

package/dist/errors/promise.js

@@ -0,0 +1,26 @@
+/**
+ * Promise-related error classes
+ */
+
+/**
+ * Error class specifically for HkPromise operations
+ * Provides timeout and cancelled properties with proper type safety
+ */
+export class PromiseError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {object} [options] - Error options
+   * @param {boolean} [options.timeout=false] - Whether this is a timeout error
+   * @param {boolean} [options.cancelled=false] - Whether this is a cancellation error
+   * @param {Error|*} [options.cause] - Original error or cause
+   * @param {*} [options.details] - Additional details object
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'PromiseError';
+    this.timeout = options.timeout ?? false;
+    this.cancelled = options.cancelled ?? false;
+    this.cause = options.cause;
+    this.details = options.details;
+  }
+}

package/dist/logging/README.md

@@ -0,0 +1,158 @@
+# Logging
+
+Universal logging utilities for SvelteKit applications with server/client/universal logger factories.
+
+## Installation
+
+```bash
+pnpm add -D pino-pretty
+```
+
+## Usage
+
+```javascript
+import { createServerLogger,
+         createClientLogger,
+         createLogger } from '@hkdigital/lib-core/logging/index.js';
+
+// Server-side logging (uses pino)
+const serverLogger = createServerLogger('app');
+
+// Client-side logging (uses console)
+const clientLogger = createClientLogger('app'); 
+
+// Universal logger (works on both server and client)
+const logger = createLogger('app');
+
+// Log at different levels
+logger.debug('Debug info', { data: 'details' });
+logger.info('Info message');
+logger.warn('Warning message');
+logger.error('Error message', { error: new Error('Something went wrong') });
+```
+
+## SvelteKit Integration
+
+### Server-side logging (src/hooks.server.js)
+
+```javascript
+import { createServerLogger } from '@hkdigital/lib-core/logging/index.js';
+
+let logger;
+
+// Initialize server logging and services
+export async function init() {
+  logger = createServerLogger('server');
+  
+  try {
+    logger.info('Initializing server');
+    
+    // Initialize your services here
+    // const serviceManager = new ServiceManager();
+    // await serviceManager.startAll();
+    
+    logger.info('Server initialization complete');
+  } catch (error) {
+    logger.error('Server initialization failed:', error);
+    throw error;
+  }
+}
+
+// Graceful shutdown
+export async function destroy() {
+  if (logger) {
+    logger.info('Shutting down server');
+    
+    // Clean up services here
+    // if (serviceManager) {
+    //   await serviceManager.stopAll();
+    // }
+  }
+}
+
+/** @type {import('@sveltejs/kit').Handle} */
+export async function handle({ event, resolve }) {
+  const start = Date.now();
+  
+  logger?.info('Request started', {
+    method: event.request.method,
+    url: event.url.pathname,
+    userAgent: event.request.headers.get('user-agent')
+  });
+
+  try {
+    const response = await resolve(event);
+    const duration = Date.now() - start;
+    
+    logger?.info('Request completed', {
+      method: event.request.method,
+      url: event.url.pathname,
+      status: response.status,
+      duration: `${duration}ms`
+    });
+    
+    return response;
+  } catch (error) {
+    logger?.error('Request failed', {
+      method: event.request.method,
+      url: event.url.pathname,
+      error: error.message,
+      stack: error.stack
+    });
+    throw error;
+  }
+}
+```
+
+### Client-side logging (src/hooks.client.js)
+
+```javascript
+import { createClientLogger } from '@hkdigital/lib-core/logging/index.js';
+
+const logger = createClientLogger('client');
+
+/** @type {import('@sveltejs/kit').HandleClientError} */
+export function handleError({ error, event }) {
+  logger.error('Client error occurred', {
+    message: error.message,
+    stack: error.stack,
+    url: event.url?.pathname,
+    userAgent: navigator.userAgent
+  });
+}
+
+// Initialize client-side logging
+export function init() {
+  logger.info('Client application initialized', {
+    userAgent: navigator.userAgent,
+    viewport: `${window.innerWidth}x${window.innerHeight}`
+  });
+  
+  // Log unhandled errors
+  window.addEventListener('error', (event) => {
+    logger.error('Unhandled error', {
+      message: event.error?.message || event.message,
+      filename: event.filename,
+      lineno: event.lineno,
+      colno: event.colno
+    });
+  });
+  
+  // Log unhandled promise rejections
+  window.addEventListener('unhandledrejection', (event) => {
+    logger.error('Unhandled promise rejection', {
+      reason: event.reason
+    });
+  });
+}
+
+// Cleanup when app is destroyed
+export function destroy() {
+  logger.info('Client application destroyed');
+  // Note: Console adapter doesn't require cleanup
+}
+```
+
+## Development
+
+Requires `pino-pretty` as peer dependency for development mode formatting.

package/dist/logging/index.d.ts

@@ -1,4 +1,6 @@
 export { createServerLogger } from "./internal/factories/server.js";
 export { createClientLogger } from "./internal/factories/client.js";
 export { createLogger } from "./internal/factories/universal.js";
-export * from "./internal/unified-logger/index.js";
+export { Logger } from "./internal/logger/index.js";
+export * from "./internal/constants.js";
+export * from "./internal/typedef.js";

package/dist/logging/index.js

@@ -3,5 +3,9 @@ export { createServerLogger } from './internal/factories/server.js';
 export { createClientLogger } from './internal/factories/client.js';
 export { createLogger } from './internal/factories/universal.js';
 
-// Logger, constants and typedefs
-export * from './internal/unified-logger/index.js';
+// Logger (advanced usage)
+export { Logger } from './internal/logger/index.js';
+
+// Constants and typedefs
+export * from './internal/constants.js';
+export * from './internal/typedef.js';

package/dist/logging/internal/adapters/console.js

@@ -1,4 +1,4 @@
-import { LEVELS } from '../unified-logger/constants.js';
+import { LEVELS } from '../constants.js';
 
 /**
  * (Browser) console adapter that uses native DevTools styling

package/dist/logging/internal/adapters/pino.js

@@ -55,19 +55,37 @@ export class PinoAdapter {
       }
     };
 
-    const devOptions = dev
-      ? {
-          level: 'debug',
-          transport: {
-            target: 'pino-pretty',
-            options: {
-              colorize: true
-            }
+    // Add error handling for missing pino-pretty in dev
+    if (dev) {
+      const devOptions = {
+        level: 'debug',
+        transport: {
+          target: 'pino-pretty',
+          options: {
+            colorize: true
           }
         }
-      : {};
-
-    this.pino = pino({ ...baseOptions, ...devOptions, ...options });
+      };
+
+      try {
+        this.pino = pino({ ...baseOptions, ...devOptions, ...options });
+      } catch (error) {
+        if (error.message.includes('pino-pretty')) {
+          const errorMessage = `
+╭─────────────────────────────────────────────────────────────╮
+│                     Missing Dependency                      │
+├─────────────────────────────────────────────────────────────┤
+│  'pino-pretty' is required for development logging          │
+│  Install it with: pnpm add -D pino-pretty                   │
+╰─────────────────────────────────────────────────────────────╯`;
+          console.error(errorMessage);
+          throw new Error('pino-pretty is required for development mode');
+        }
+        throw error;
+      }
+    } else {
+      this.pino = pino({ ...baseOptions, ...options });
+    }
   }
 
   /**

package/dist/logging/internal/factories/client.d.ts

@@ -7,4 +7,4 @@
  * @returns {Logger} Configured logger instance
  */
 export function createClientLogger(name: string, level?: string, consoleOptions?: any): Logger;
-import { Logger } from '../unified-logger';
+import { Logger } from '../logger/index.js';

package/dist/logging/internal/factories/client.js

@@ -1,6 +1,6 @@
-import { Logger } from '../unified-logger';
+import { Logger } from '../logger/index.js';
 import { ConsoleAdapter } from '../adapters/console.js';
-import { INFO } from '../unified-logger/constants.js';
+import { INFO } from '../constants.js';
 
 /**
  * Create a client-side logger with console adapter

package/dist/logging/internal/factories/server.d.ts

@@ -7,4 +7,4 @@
  * @returns {Logger} Configured logger instance
  */
 export function createServerLogger(name: string, level?: string, pinoOptions?: any): Logger;
-import { Logger } from '../unified-logger';
+import { Logger } from '../logger/index.js';

package/dist/logging/internal/factories/server.js

@@ -1,7 +1,7 @@
-import { Logger } from '../unified-logger';
+import { Logger } from '../logger/index.js';
 
 import { PinoAdapter } from '../adapters/pino.js';
-import { INFO } from '../unified-logger/constants.js';
+import { INFO } from '../constants.js';
 
 /**
  * Create a server-side logger with pino adapter

package/dist/logging/internal/factories/universal.d.ts

@@ -4,6 +4,6 @@
  * @param {string} serviceName - Name of the service
  * @param {string} [level] - Initial log level
  * @param {Object} [options] - Additional options
- * @returns {import('../unified-logger').Logger} Configured logger instance
+ * @returns {import('../logger').Logger} Configured logger instance
  */
-export function createLogger(serviceName: string, level?: string, options?: any): import("../unified-logger").Logger;
+export function createLogger(serviceName: string, level?: string, options?: any): import("../logger").Logger;

package/dist/logging/internal/factories/universal.js

@@ -11,7 +11,7 @@ import { createClientLogger } from './client.js';
  * @param {string} serviceName - Name of the service
  * @param {string} [level] - Initial log level
  * @param {Object} [options] - Additional options
- * @returns {import('../unified-logger').Logger} Configured logger instance
+ * @returns {import('../logger').Logger} Configured logger instance
  */
 export function createLogger(serviceName, level, options = {}) {
   if (browser) {

package/dist/logging/internal/{unified-logger → logger}/Logger.d.ts

@@ -70,9 +70,9 @@ export default class Logger extends EventEmitter {
      * forwarded to this logger.
      *
      * @param {string} eventName
-     * @param {import('./typedef.js').LogEventData} eventData
+     * @param {import('../typedef.js').LogEventData} eventData
      */
-    logFromEvent(eventName: string, eventData: import("./typedef.js").LogEventData): boolean;
+    logFromEvent(eventName: string, eventData: import("../typedef.js").LogEventData): boolean;
     #private;
 }
 import { EventEmitter } from '../../../classes/event-emitter';

package/dist/logging/internal/{unified-logger → logger}/Logger.js

@@ -41,7 +41,7 @@ import {
   ERROR,
   LEVELS,
   LOG
-} from './constants.js';
+} from '../constants.js';
 
 /**
  * Logger class for consistent logging
@@ -157,7 +157,7 @@ export default class Logger extends EventEmitter {
    * forwarded to this logger.
    *
    * @param {string} eventName
-   * @param {import('./typedef.js').LogEventData} eventData
+   * @param {import('../typedef.js').LogEventData} eventData
    */
   logFromEvent(eventName, eventData) {
     const level = eventData.level;
@@ -205,7 +205,7 @@ export default class Logger extends EventEmitter {
   /**
    * Internal event loggin method
    *
-   * @param {import('./typedef.js').LogEvent} logEvent
+   * @param {import('../typedef.js').LogEvent} logEvent
    */
   #logEvent(logEvent) {
     // Emit as both specific level event and generic 'log' event

package/dist/logging/internal/logger/index.d.ts

@@ -0,0 +1 @@
+export { default as Logger } from "./Logger.js";

package/dist/logging/internal/logger/index.js

@@ -0,0 +1 @@
+export { default as Logger } from './Logger.js';

package/dist/logging/internal/{unified-logger/typedef.d.ts → typedef.d.ts}

@@ -1,5 +1,6 @@
 declare const _default: {};
 export default _default;
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
 export type LogEventData = {
     /**
      * - When the log event was created
@@ -12,7 +13,7 @@ export type LogEventData = {
     /**
      * - Log level (DEBUG, INFO, WARN, ERROR)
      */
-    level: string;
+    level: LogLevel;
     /**
      * - The log message
      */

package/dist/logging/internal/{unified-logger/typedef.js → typedef.js}

@@ -1,8 +1,12 @@
+/**
+ * @typedef {'debug'|'info'|'warn'|'error'|'none'} LogLevel
+ */
+
 /**
  * @typedef {Object} LogEventData
  * @property {Date} timestamp - When the log event was created
  * @property {string} source - Name of the source where the event came from
- * @property {string} level - Log level (DEBUG, INFO, WARN, ERROR)
+ * @property {LogLevel} level - Log level (DEBUG, INFO, WARN, ERROR)
  * @property {string} message - The log message
  * @property {Object|null} context
  *   Default context data from the logger (null if no context)

package/dist/network/README.md

@@ -0,0 +1,173 @@
+# Network
+
+Network utilities for HTTP requests, responses, caching, and specialized media loaders.
+
+## Quick Start
+
+```javascript
+import * as http from '$lib/network/http.js';
+import * as cache from '$lib/network/cache.js';
+import * as loaders from '$lib/network/loaders.js';
+```
+
+## HTTP Utilities
+
+### Making Requests
+
+```javascript
+import { httpRequest, jsonRequest } from '$lib/network/http.js';
+
+// Basic HTTP request
+const response = await httpRequest('https://api.example.com/data');
+
+// JSON request with POST
+const result = await jsonRequest('https://api.example.com/users', {
+  method: 'POST',
+  body: { name: 'John', email: 'john@example.com' }
+});
+```
+
+### URL Utilities
+
+```javascript
+import { toURL, addSearchParams } from '$lib/network/http.js';
+
+const url = toURL('https://example.com', { page: 1, limit: 10 });
+// Result: https://example.com?page=1&limit=10
+```
+
+### Headers and Response Handling
+
+```javascript
+import { 
+  setRequestHeaders, 
+  waitForAndCheckResponse,
+  getErrorFromResponse 
+} from '$lib/network/http.js';
+
+// Set custom headers
+const headers = setRequestHeaders({ 'Authorization': 'Bearer token' });
+
+// Handle response with error checking
+const response = await fetch('/api/data');
+const result = await waitForAndCheckResponse(response);
+```
+
+## Caching
+
+### Memory Cache (for temporary storage)
+
+```javascript
+import { MemoryResponseCache } from '$lib/network/cache.js';
+
+const cache = new MemoryResponseCache();
+
+// Store response with 1-hour expiration
+const response = await fetch('https://api.example.com/data');
+await cache.set('api-data', response, { expiresIn: 3600000 });
+
+// Retrieve cached response
+const cached = await cache.get('api-data');
+if (cached) {
+  console.log('Cached data:', cached.response);
+}
+```
+
+### IndexedDB Cache (for persistent storage)
+
+```javascript
+import { IndexedDbCache } from '$lib/network/cache.js';
+
+const cache = new IndexedDbCache('my-app-cache');
+
+// Store response persistently
+const response = await fetch('https://api.example.com/users');
+await cache.set('users-list', response, { 
+  expiresIn: 86400000, // 24 hours
+  etag: response.headers.get('etag')
+});
+
+// Check if cached version is still valid
+const cached = await cache.get('users-list');
+if (cached && !cache.isExpired(cached)) {
+  return cached.response;
+}
+```
+
+## Media Loaders
+
+Advanced network-based loaders for media assets with loading state management and streaming support. See the [loaders documentation](./loaders/README.md) for detailed usage examples.
+
+```javascript
+import { ImageLoader, AudioLoader, ImageScene } from '$lib/network/loaders.js';
+
+// Load a single image with progress tracking
+const imageLoader = new ImageLoader({ imageSource: { src: '/image.jpg' } });
+imageLoader.load();
+
+// Load multiple images as a scene
+const scene = new ImageScene();
+scene.defineImage({ label: 'hero', imageSource: heroImage });
+scene.load();
+```
+
+## Network State Management
+
+For managing loading states across network operations:
+
+```javascript
+import { NetworkLoader } from '$lib/network/states/index.js';
+
+// Base class for custom network loaders
+class CustomLoader extends NetworkLoader {
+  // Implementation
+}
+```
+
+## Available Exports
+
+### HTTP (`$lib/network/http.js`)
+- `httpRequest()` - Make HTTP requests with configuration
+- `jsonRequest()` - Make JSON API requests  
+- `toURL()` - Convert strings to URL objects with params
+- `setRequestHeaders()` - Set and merge request headers
+- `waitForAndCheckResponse()` - Handle responses with error checking
+- `getErrorFromResponse()` - Extract errors from failed responses
+- HTTP constants and error types
+
+### Cache (`$lib/network/cache.js`)
+- `MemoryResponseCache` - In-memory response caching
+- `IndexedDbCache` - Persistent browser storage caching
+- Cache-related type definitions
+
+### Loaders (`$lib/network/loaders.js`)
+- `ImageLoader` - Single image loading with progress tracking
+- `ImageVariantsLoader` - Responsive image variants loading
+- `ImageScene` - Multi-image loading and management
+- `AudioLoader` - Audio data loading and processing
+- `AudioScene` - Multi-audio loading and management
+- Media utilities and type definitions
+
+### States (`$lib/network/states/`)
+- `NetworkLoader` - Base class for network-based loaders
+- Loading state management and progress tracking
+
+## Error Handling
+
+All HTTP utilities throw structured errors:
+
+```javascript
+import { httpRequest } from '$lib/network/http.js';
+
+try {
+  const response = await httpRequest('/api/data');
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Request was cancelled');
+  } else if (error.name === 'TimeoutError') {
+    console.log('Request timed out');
+  } else {
+    console.log('HTTP error:', error.message);
+  }
+}
+```

package/dist/network/cache.d.ts

@@ -0,0 +1,3 @@
+export { default as MemoryResponseCache } from "./cache/MemoryResponseCache.js";
+export { default as IndexedDbCache } from "./cache/IndexedDbCache.js";
+export * from "./cache/typedef.js";

package/dist/network/cache.js

@@ -0,0 +1,4 @@
+export { default as MemoryResponseCache } from "./cache/MemoryResponseCache.js";
+export { default as IndexedDbCache } from "./cache/IndexedDbCache.js";
+
+export * from './cache/typedef.js';

package/dist/{util → network}/http/caching.js

@@ -1,11 +1,9 @@
-import {
-  MemoryResponseCache,
-  IndexedDbCache
-} from '../../classes/cache';
+import MemoryResponseCache from '../cache/MemoryResponseCache.js';
+import IndexedDbCache from '../cache/IndexedDbCache.js';
 
 import { browser } from '$app/environment';
 
-import { isTestEnv } from '../env';
+import { isTestEnv } from '../../util/env';
 
 let defaultCacheStorage = null;
 

package/dist/{util → network}/http/errors.js

@@ -1,4 +1,4 @@
-import * as expect from '../expect/index.js';
+import * as expect from '../../util/expect/index.js';
 
 import { CONTENT_TYPE } from '../../constants/http/index.js';
 

package/dist/{util → network}/http/headers.js

@@ -1,4 +1,4 @@
-import * as expect from '../expect/index.js';
+import * as expect from '../../util/expect/index.js';
 
 /**
  * Set headers in an existing `Headers` object

package/dist/{util → network}/http/http-request.js

@@ -13,7 +13,7 @@ import { CONTENT_TYPE } from '../../constants/http/headers.js';
 
 import { AbortError, TimeoutError } from '../../errors/api.js';
 
-import * as expect from '../expect/index.js';
+import * as expect from '../../util/expect/index.js';
 
 import { toURL } from './url.js';
 import { setRequestHeaders } from './headers.js';
@@ -21,7 +21,7 @@ import { waitForAndCheckResponse } from './response.js';
 
 import { getCachedResponse, storeResponseInCache } from './caching.js';
 
-import { isTestEnv } from '../env';
+import { isTestEnv } from '../../util/env';
 
 /**
  * Default configuration for HTTP requests