@hkdigital/lib-core 0.3.14 → 0.4.3

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

@@ -1,10 +1,21 @@
+/**
+ * @typedef {Object} ErrorSummaryMeta
+ * @property {string} category - Error category (rethrow, validation, http, promise, error)
+ * @property {string} method - Specific method (rethrow, expect, httpGet, hkpromise.timeout, etc)
+ * @property {string} [origin] - User function name where error originated
+ * @property {number} [relevantFrameIndex] - Index of most relevant stack frame to highlight
+ */
+
 /**
  * @typedef {Object} ErrorSummary
  * @property {string} name - The name of the exception/error
  * @property {string} message - The error message
+ * @property {ErrorSummaryMeta} [meta] - Error meta
  * @property {string} [stack] Stack trace (in debug mode for first exception)
  * @property {number} [status] - HTTP status code (for HttpError instances)
  * @property {*} [details] - Additional error details (for HttpError instances)
+ * @property {string} [errorType] - Formatted error type for display
+ * @property {string[]} [stackFrames] - Cleaned stack frames for terminal display
  */
 
  export default {};

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

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

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

@@ -1,7 +1,7 @@
 import { Logger } from '../logger/index.js';
-
 import { PinoAdapter } from '../adapters/pino.js';
-import { INFO } from '../constants.js';
+import { INFO } from '../../constants.js';
+// import { expectNoSSRContext } from '../../../util/ssr/index.js';
 
 /**
  * Create a server-side logger with pino adapter
@@ -12,10 +12,20 @@ import { INFO } from '../constants.js';
  * @returns {Logger} Configured logger instance
  */
 export function createServerLogger(name, level = INFO, pinoOptions = {}) {
+  // Guard against SSR serialization issues
+  // expectNoSSRContext();
+
   const logger = new Logger(name, level);
   const adapter = new PinoAdapter(pinoOptions);
 
   // Connect adapter to logger events
+  //
+  // @note pino might fail if:
+  //   pino tries to create a worker thread for pino-pretty before the
+  //   development environment is fully ready, causing the transport target
+  //   determination to fail
+  //   -> Stop and start the dev server
+  //
   logger.on('log', (logEvent) => adapter.handleLog(logEvent));
 
   return logger;

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

@@ -33,6 +33,7 @@ export default class Logger extends EventEmitter {
      *
      * @param {string} message - Log message
      * @param {*} [details] - Additional details
+     *
      * @returns {boolean} True if the log was emitted
      */
     info(message: string, details?: any): boolean;
@@ -41,23 +42,24 @@ export default class Logger extends EventEmitter {
      *
      * @param {string} message - Log message
      * @param {*} [details] - Additional details
+     *
      * @returns {boolean} True if the log was emitted
      */
     warn(message: string, details?: any): boolean;
     /**
      * Log an error message
      *
-     * @param {string} message - Log message
-     * @param {*} [details] - Additional details
+     * @param {Error|string} originalErrorOrMessage
+     * @param {Error} [originalError]
+     *
      * @returns {boolean} True if the log was emitted
      */
-    error(message: string, details?: any): boolean;
+    error(originalErrorOrMessage: Error | string, originalError?: Error, ...args: any[]): boolean;
     /**
      * Create a child logger with additional context
      *
      * @param {string} namespace
      *   Namespace of the context (needed for chaining contexts)
-     *
      * @param {Object} additionalContext - Additional context data
      *
      * @returns {Logger} New logger instance with merged context
@@ -70,9 +72,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';
+import { EventEmitter } from '../../../generic/events.js';

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

@@ -32,7 +32,7 @@
  * logger.setLevel(DEBUG); // Now debug messages will also be logged
  */
 
-import { EventEmitter } from '../../../classes/event-emitter';
+import { EventEmitter } from '../../../generic/events.js';
 
 import {
   DEBUG,
@@ -41,7 +41,12 @@ import {
   ERROR,
   LEVELS,
   LOG
-} from '../constants.js';
+} from '../../constants.js';
+
+import { DetailedError } from '../../../generic/errors.js';
+import { LoggerError } from '../../errors.js';
+
+import { toArray } from '../../../util/array/index.js';
 
 /**
  * Logger class for consistent logging
@@ -99,6 +104,7 @@ export default class Logger extends EventEmitter {
    *
    * @param {string} message - Log message
    * @param {*} [details] - Additional details
+   *
    * @returns {boolean} True if the log was emitted
    */
   info(message, details) {
@@ -110,6 +116,7 @@ export default class Logger extends EventEmitter {
    *
    * @param {string} message - Log message
    * @param {*} [details] - Additional details
+   *
    * @returns {boolean} True if the log was emitted
    */
   warn(message, details) {
@@ -119,12 +126,41 @@ export default class Logger extends EventEmitter {
   /**
    * Log an error message
    *
-   * @param {string} message - Log message
-   * @param {*} [details] - Additional details
+   * @param {Error|string} originalErrorOrMessage
+   * @param {Error} [originalError]
+   *
    * @returns {boolean} True if the log was emitted
    */
-  error(message, details) {
-    return this.#log(ERROR, message, details);
+  error(originalErrorOrMessage, originalError) {
+
+    if( originalErrorOrMessage instanceof Error )
+    {
+      // params: {error} originalErrorOrMessage
+      const loggerError = new LoggerError(originalErrorOrMessage);
+
+      const message = originalErrorOrMessage.message;
+
+      return this.#log(ERROR, message, loggerError);
+    }
+    else if( typeof originalErrorOrMessage === 'string' && originalError instanceof Error ) {
+      // params: {string} message, {error} originalError
+      const detailedError = new DetailedError(
+        originalErrorOrMessage,
+        null,
+        originalError
+      );
+
+      return this.#log(ERROR, detailedError.message, detailedError);
+    }
+    else {
+      // wrong params
+      const detailedError = new DetailedError(
+        'Invalid parameters supplied to Logger.error',
+        toArray(arguments)
+      );
+
+      return this.#log(ERROR, detailedError.message, detailedError);
+    }
   }
 
   /**
@@ -132,7 +168,6 @@ export default class Logger extends EventEmitter {
    *
    * @param {string} namespace
    *   Namespace of the context (needed for chaining contexts)
-   *
    * @param {Object} additionalContext - Additional context data
    *
    * @returns {Logger} New logger instance with merged context
@@ -157,7 +192,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 +240,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/test-errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Test functions for generating various types of errors for logging demonstration
+ */
+/**
+ * Simple error: division by zero (which creates NaN in JS, so we'll throw manually)
+ */
+export function throwSimpleError(): number;
+/**
+ * Simple error occurring in a sub function
+ */
+export function throwErrorInSubFunction(): void;
+/**
+ * Promise rejection in async function
+ */
+export function throwPromiseRejection(): Promise<any>;
+/**
+ * HkPromise timeout
+ */
+export function throwHkPromiseTimeout(): Promise<any>;
+/**
+ * HTTP request that fails
+ */
+export function throwHttpException(): Promise<Response>;
+/**
+ * Expect validation error
+ */
+export function throwExpectError(): void;
+/**
+ * Rethrow chain error
+ */
+export function throwRethrowChainError(): void;
+/**
+ * Raw valibot validation error (without expect wrapper)
+ */
+export function throwRawValibotError(): any;

package/dist/logging/internal/test-errors.js

@@ -0,0 +1,137 @@
+import { expect, rethrow } from '../../util/index.js';
+import { HkPromise } from '../../generic/promises.js';
+import { httpGet } from '../../network/http/index.js';
+import { v } from '../../valibot/index.js';
+
+/**
+ * Test functions for generating various types of errors for logging demonstration
+ */
+
+/**
+ * Simple error: division by zero (which creates NaN in JS, so we'll throw manually)
+ */
+export function throwSimpleError() {
+  const a = 10;
+  const b = 0;
+  
+  if (b === 0) {
+    throw new Error('Division by zero is not allowed');
+  }
+  
+  return a / b; // This won't be reached
+}
+
+/**
+ * Simple error occurring in a sub function
+ */
+export function throwErrorInSubFunction() {
+  function deepFunction() {
+    function evenDeeperFunction() {
+      throw new Error('Error occurred in deeply nested function');
+    }
+    
+    evenDeeperFunction();
+  }
+  
+  function callDeepFunction() {
+    deepFunction();
+  }
+  
+  callDeepFunction();
+}
+
+/**
+ * Promise rejection in async function
+ */
+export async function throwPromiseRejection() {
+  // Create a promise that rejects after a short delay
+  const rejectedPromise = new Promise((resolve, reject) => {
+    setTimeout(() => {
+      reject(new Error('Promise was rejected after timeout'));
+    }, 100);
+  });
+  
+  // Await the promise (will throw)
+  return await rejectedPromise;
+}
+
+/**
+ * HkPromise timeout
+ */
+export async function throwHkPromiseTimeout() {
+  // Create an HkPromise that times out
+  const timeoutPromise = new HkPromise((resolve) => {
+    // Never resolve this promise to cause timeout
+    setTimeout(() => {
+      // This resolve will never be reached because timeout occurs first
+      resolve('This should not complete');
+    }, 2000);
+  });
+  
+  // Set timeout of 500ms (will timeout before the 2000ms resolve)
+  timeoutPromise.setTimeout(500, 'HkPromise timeout after 500ms');
+  
+  return await timeoutPromise;
+}
+
+/**
+ * HTTP request that fails
+ */
+export async function throwHttpException() {
+  // Try to fetch with an invalid URL format
+  const response = await httpGet({
+    url: 'not-a-valid-url-format'
+  });
+  return response;
+}
+
+/**
+ * Expect validation error
+ */
+export function throwExpectError() {
+  try {
+    // This will always fail and trigger an expect error
+    expect.string(123);
+  } catch (e) {
+    rethrow('throwExpectError failed', e);
+  }
+}
+
+/**
+ * Rethrow chain error
+ */
+export function throwRethrowChainError() {
+  function level1Function() {
+    try {
+      level2Function();
+    } catch (e) {
+      rethrow('Error in level1Function', e);
+    }
+  }
+  
+  function level2Function() {
+    try {
+      level3Function();
+    } catch (e) {
+      rethrow('Error in level2Function', e);
+    }
+  }
+  
+  function level3Function() {
+    throw new Error('Original error at deepest level');
+  }
+  
+  level1Function();
+}
+
+/**
+ * Raw valibot validation error (without expect wrapper)
+ */
+export function throwRawValibotError() {
+  // This calls valibot.parse directly, not through expect_*
+  const schema = v.string();
+  const invalidValue = 456;
+  
+  // This will throw a ValiError directly from our valibotParser wrapper
+  return v.parse(schema, invalidValue);
+}

package/dist/network/cache/IndexedDbCache.d.ts

@@ -50,7 +50,7 @@ export default class IndexedDbCache {
      * @private
      */
     private cleanupState;
-    postponeCleanupTimer: number;
+    postponeCleanupTimer: NodeJS.Timeout;
     /**
      * Initialize the database connection
      *

package/dist/network/cache/MemoryResponseCache.d.ts

@@ -28,6 +28,7 @@
  * @property {number|null} expires - Expiration timestamp (null if no expiration)
  * @property {string|null} etag - ETag header if present
  * @property {string|null} lastModified - Last-Modified header if present
+ * @property {string|null} cacheVersion - Cache version identifier
  */
 /**
  * In-memory response cache implementation
@@ -103,4 +104,8 @@ export type CacheEntry = {
      * - Last-Modified header if present
      */
     lastModified: string | null;
+    /**
+     * - Cache version identifier
+     */
+    cacheVersion: string | null;
 };

package/dist/network/cache/MemoryResponseCache.js

@@ -29,6 +29,7 @@
  * @property {number|null} expires - Expiration timestamp (null if no expiration)
  * @property {string|null} etag - ETag header if present
  * @property {string|null} lastModified - Last-Modified header if present
+ * @property {string|null} cacheVersion - Cache version identifier
  */
 
 /**
@@ -75,7 +76,8 @@ export default class MemoryResponseCache {
       timestamp: entry.timestamp,
       expires: entry.expires,
       etag: entry.etag,
-      lastModified: entry.lastModified
+      lastModified: entry.lastModified,
+      cacheVersion: entry.cacheVersion
     };
   }
 
@@ -104,7 +106,8 @@ export default class MemoryResponseCache {
       lastAccessed: now,
       expires,
       etag: response.headers.get('ETag'),
-      lastModified: response.headers.get('Last-Modified')
+      lastModified: response.headers.get('Last-Modified'),
+      cacheVersion: metadata.cacheVersion || null
     });
   }
 

package/dist/network/errors.d.ts

@@ -0,0 +1,2 @@
+export * from "./errors/api.js";
+export * from "./errors/http.js";

package/dist/network/errors.js

@@ -0,0 +1,2 @@
+export * from './errors/api.js';
+export * from './errors/http.js';

package/dist/network/http/caching.js

@@ -135,7 +135,7 @@ export async function getCachedResponse(cacheKeyParams) {
  * @param {string} type Type of storage ('indexed-db', 'memory')
  * @param {Object} options Options for the storage adapter
  *
- * @returns {import('../../classes/cache').CacheStorage}
+ * @returns {import('../cache.js').CacheStorage}
  */
 function createCacheStorage(type = 'indexed-db', options = {}) {
   switch (type) {

package/dist/network/http/errors.d.ts

@@ -13,6 +13,6 @@
  *
  * @param {object} response
  *
- * @returns {Error} error
+ * @returns {Promise<Error>} error
  */
-export function getErrorFromResponse(response: object): Error;
+export function getErrorFromResponse(response: object): Promise<Error>;

package/dist/network/http/errors.js

@@ -1,4 +1,5 @@
 import * as expect from '../../util/expect/index.js';
+import { DetailedError } from '../../generic/errors.js';
 
 import { CONTENT_TYPE } from '../../constants/http/index.js';
 
@@ -19,7 +20,7 @@ import { APPLICATION_JSON } from '../../constants/mime/index.js';
  *
  * @param {object} response
  *
- * @returns {Error} error
+ * @returns {Promise<Error>} error
  */
 export async function getErrorFromResponse(response) {
 	expect.object(response);
@@ -77,21 +78,12 @@ export async function getErrorFromResponse(response) {
 			}
 		}
 	} else {
-		const tmp = await response.text();
-
-		if (tmp.length) {
-			message = tmp;
-		} else {
-			message = response.statusText;
-		}
+		// For non-JSON responses, always use status text (avoid HTML pages)
+		message = response.statusText || `HTTP ${response.status}`;
 	}
 	// console.log( "message", message );
 
-	const error = new Error(message);
-
-	if (details) {
-		error.details = details;
-	}
+	const error = new DetailedError(message, details);
 
 	return error;
 }

package/dist/network/http/http-request.js

@@ -11,7 +11,7 @@ import {
 import { APPLICATION_JSON } from '../../constants/mime/application.js';
 import { CONTENT_TYPE } from '../../constants/http/headers.js';
 
-import { AbortError, TimeoutError } from '../../errors/api.js';
+import { AbortError, TimeoutError } from '../errors/api.js';
 
 import * as expect from '../../util/expect/index.js';
 

package/dist/network/http/json-request.js

@@ -2,7 +2,7 @@ import { METHOD_GET, METHOD_POST } from '../../constants/http/methods.js';
 
 import { APPLICATION_JSON } from '../../constants/mime/application.js';
 import { CONTENT_TYPE } from '../../constants/http/headers.js';
-import { ResponseError } from '../../errors/index.js';
+import { ResponseError } from '../errors.js';
 
 import * as expect from '../../util/expect/index.js';
 

package/dist/network/http/response.js

@@ -1,4 +1,4 @@
-import { ResponseError, HttpError } from '../../errors/index.js';
+import { ResponseError, HttpError } from '../errors.js';
 import * as expect from '../../util/expect/index.js';
 import { toURL } from './url.js';
 

package/dist/network/http/url.js

@@ -1,4 +1,4 @@
-import { TypeOrValueError } from '../../errors/index.js';
+import { TypeOrValueError } from '../../generic/errors.js';
 
 /**
  * Returns an URL instance

package/dist/network/loaders/README.md

@@ -44,22 +44,29 @@ Loads responsive image variants, automatically selecting the best size for conta
 ```javascript
 import { ImageVariantsLoader } from '$lib/network/loaders.js';
 
-const loader = new ImageVariantsLoader();
-
-// Load responsive variants
+// Responsive image variants (array of ImageMeta)
 const imageSource = [
   { src: '/image-400.jpg', width: 400, height: 300 },
   { src: '/image-800.jpg', width: 800, height: 600 },
   { src: '/image-1200.jpg', width: 1200, height: 900 }
 ];
 
-await loader.load({
-  imageSource,
+const loader = new ImageVariantsLoader(imageSource, {
+  devicePixelRatio: window.devicePixelRatio
+});
+
+// Set optimal image variant for container
+loader.setOptimalImageVariant({
   containerWidth: 600,
   containerHeight: 400,
-  fit: 'cover', // or 'contain', 'fill'
-  devicePixelRatio: window.devicePixelRatio
+  fit: 'cover' // or 'contain', 'fill'
 });
+
+// Access the selected variant and loader
+if (loader.loaded) {
+  const objectURL = loader.getObjectURL();
+  // Use objectURL in img src
+}
 ```
 
 ### ImageScene

package/dist/network/loaders/audio/AudioScene.svelte.js

@@ -1,7 +1,8 @@
 import * as expect from '../../../util/expect/index.js';
 
+import { LoadingStateMachine } from '../../../state/classes.js';
+
 import {
-	LoadingStateMachine,
 	STATE_INITIAL,
 	STATE_LOADING,
 	STATE_UNLOADING,
@@ -10,7 +11,7 @@ import {
 	STATE_ERROR,
 	LOAD,
 	LOADED
-} from '../../../classes/svelte/loading-state-machine/index.js';
+} from '../../../state/classes/loading-state-machine/constants.js';
 
 import AudioLoader from './AudioLoader.svelte.js';
 

package/dist/network/loaders/image/ImageLoader.svelte.d.ts

@@ -5,9 +5,9 @@
  */
 export default class ImageLoader extends NetworkLoader {
     /**
-     * @param {import('../typedef.js').ImageSource} imageSource
+     * @param {import('../../../config/typedef.js').ImageSource} imageSource
      */
-    constructor(imageSource: import("../typedef.js").ImageSource);
+    constructor(imageSource: import("../../../config/typedef.js").ImageSource);
     get imageMeta(): import("./typedef.js").ImageMeta;
     get url(): string;
     #private;

package/dist/network/loaders/image/ImageLoader.svelte.js

@@ -16,7 +16,7 @@ export default class ImageLoader extends NetworkLoader {
   #imageMeta;
 
   /**
-   * @param {import('../typedef.js').ImageSource} imageSource
+   * @param {import('../../../config/typedef.js').ImageSource} imageSource
    */
   constructor(imageSource) {
     const imageMeta = toSingleImageMeta(imageSource);

package/dist/network/loaders/image/ImageScene.svelte.d.ts

@@ -17,11 +17,11 @@ export default class ImageScene {
      *
      * @param {object} _
      * @param {string} _.label
-     * @param {import('../typedef.js').ImageSource} _.imageSource
+     * @param {import('../../../config/typedef.js').ImageSource} _.imageSource
      */
     defineImage({ label, imageSource }: {
         label: string;
-        imageSource: import("../typedef.js").ImageSource;
+        imageSource: import("../../../config/typedef.js").ImageSource;
     }): void;
     /**
      * Start loading all image sources