@hkdigital/lib-core 0.4.23 → 0.4.25

package/dist/logging/internal/adapters/pino.d.ts

@@ -8,13 +8,18 @@ export class PinoAdapter {
      * @param {Object} [options] - Pino configuration options
      */
     constructor(options?: any);
-    pino: pino.Logger<never, boolean>;
+    /**
+     * Promise that resolves when transport is ready
+     *
+     * @returns {Promise<void>} Promise that resolves when ready
+     */
+    ready(): Promise<void>;
     /**
      * Handle log events from Logger
      *
      * @param {Object} logEvent - Log event from Logger
      */
-    handleLog(logEvent: any): void;
+    handleLog(logEvent: any): Promise<void>;
     /**
      * Create a child logger with additional context
      *
@@ -24,4 +29,3 @@ export class PinoAdapter {
     child(context: any): PinoAdapter;
     #private;
 }
-import pino from 'pino';

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

@@ -4,11 +4,12 @@
 import pino from 'pino';
 import { dev } from '$app/environment';
 
+import { HkPromise } from '../../../generic/promises.js';
+
 import {
   detectErrorMeta,
   findRelevantFrameIndex,
-  formatErrorDisplay,
-  parseFunctionName
+  formatErrorDisplay
 } from './formatting.js';
 
 /**
@@ -17,26 +18,38 @@ import {
 export class PinoAdapter {
   #projectRoot = null;
 
+  /** @type {import('pino').Logger|Object|null} */
+  #pino = null;
+
+  #options = null;
+  #messageQueue = [];
+  #isInitializing = false;
+  #isTransportReady = false;
+  #retryCount = 0;
+  #maxRetries = 3;
+  #retryDelay = 1000;
+  #readyPromise = null;
+
   /**
    * Create a new PinoAdapter
    *
    * @param {Object} [options] - Pino configuration options
    */
   constructor(options = {}) {
-    // Determine project root once for stack trace cleaning
     this.#projectRoot = import.meta.env.VITE_PROJECT_ROOT || process.cwd();
-    const baseOptions = {
-      serializers: {
+    this.#options = options;
+    this.#readyPromise = new HkPromise();
+  }
 
-        //
-        // Use 'errors' property to trigger Pino's error serializer
-        // The serializer traverses the error.cause chain and outputs an array
-        // of serialized error objects, which is why we use 'errors' (plural)
-        // instead of Pino's standard 'err' property (which expects a single
-        // error)
-        //
+  /**
+   * Get base configuration options for pino
+   *
+   * @returns {Object} Base pino configuration
+   */
+  #getBaseOptions() {
+    return {
+      serializers: {
         errors: (err) => {
-
           /** @type {import('./typedef').ErrorSummary[]} */
           const chain = [];
           let loggedAt = null;
@@ -45,7 +58,6 @@ export class PinoAdapter {
           let isFirst = true;
 
           while (current && current instanceof Error) {
-            // Check if this is the first error and it's a LoggerError - extract logging context
             if (isFirst && current.name === 'LoggerError') {
               if (current.stack) {
                 const cleanedStackString = this.#cleanStackTrace(current.stack);
@@ -57,24 +69,23 @@ export class PinoAdapter {
                       line && line !== current.name + ': ' + current.message
                   );
 
-                // For LoggerError, we know it's a logger.error call, so find the relevant frame
-                const loggerErrorIndex = cleanedStackArray.findIndex(frame =>
-                  (frame.includes('Logger.error') && frame.includes('logger/Logger.js')) ||
-                  (frame.includes('error@') && frame.includes('logger/Logger.js'))
+                const loggerErrorIndex = cleanedStackArray.findIndex(
+                  (frame) =>
+                    (frame.includes('Logger.error') &&
+                      frame.includes('logger/Logger.js')) ||
+                    (frame.includes('error@') &&
+                      frame.includes('logger/Logger.js'))
                 );
 
-                if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStackArray.length) {
+                if (
+                  loggerErrorIndex >= 0 &&
+                  loggerErrorIndex + 1 < cleanedStackArray.length
+                ) {
                   const relevantFrame = cleanedStackArray[loggerErrorIndex + 1];
-
-                  // Extract function name from the relevant frame
-                  // const functionName = parseFunctionName(relevantFrame);
-
-                  // const errorType = functionName ? `logger.error in ${functionName}` : 'logger.error';
-                  loggedAt = relevantFrame.slice(3); // remove "at "
+                  loggedAt = relevantFrame.slice(3);
                 }
               }
 
-              // Skip the LoggerError and move to the actual error
               current = current.cause;
               isFirst = false;
               continue;
@@ -85,9 +96,7 @@ export class PinoAdapter {
               message: current.message
             };
 
-            // Add error metadata for structured logging and terminal display
             if (current.stack) {
-              // Convert cleaned stack string to array format expected by formatting functions
               const cleanedStackString = this.#cleanStackTrace(current.stack);
               const cleanedStackArray = cleanedStackString
                 .split('\n')
@@ -106,18 +115,18 @@ export class PinoAdapter {
               serialized.meta = errorMeta;
               serialized.errorType = formatErrorDisplay(errorMeta);
 
-              // Include stack frames for terminal display
               serialized.stackFrames = cleanedStackArray
                 .slice(0, 9)
                 .map((frame, index) => {
                   const marker = index === relevantFrameIndex ? '→' : ' ';
-
                   return `${marker} ${frame}`;
                 });
             }
 
-            // Include HttpError-specific properties
-            const httpError = /** @type {import('../../../network/errors.js').HttpError} */ (current);
+            const httpError =
+              /** @type {import('../../../network/errors.js').HttpError} */ (
+                current
+              );
             if (httpError.status !== undefined) {
               serialized.status = httpError.status;
             }
@@ -134,27 +143,50 @@ export class PinoAdapter {
         }
       }
     };
+  }
+
+  /**
+   * Initialize pino instance with retry logic for transport setup
+   */
+  async #initializePino() {
+    if (this.#isInitializing || this.#pino) {
+      return;
+    }
+
+    this.#isInitializing = true;
 
-    // Add error handling for missing pino-pretty in dev
-    if ( dev) {
-      const devOptions = {
-        level: 'debug',
-        transport: {
-          target: 'pino-pretty',
-          options: {
+    const baseOptions = this.#getBaseOptions();
+
+    while (this.#retryCount <= this.#maxRetries) {
+      try {
+        if (dev) {
+          // Use intermediate transport to avoid worker thread issues
+          const { default: createPrettyTransport } = await import('../transports/pretty-transport.js');
+          const prettyTransport = await createPrettyTransport({
             colorize: true,
             ignore: 'hostname,pid'
-          }
+          });
+          
+          const devOptions = {
+            level: 'debug'
+          };
+
+          this.#pino = pino({ ...baseOptions, ...devOptions, ...this.#options }, prettyTransport);
+        } else {
+          this.#pino = pino({ ...baseOptions, ...this.#options });
         }
-      };
 
-      try {
-        this.pino = pino({ ...baseOptions, ...devOptions, ...options });
+        this.#isTransportReady = true;
+        this.#isInitializing = false;
+        this.#flushMessageQueue();
+        this.#readyPromise.tryResolve();
+        return;
+
       } catch (error) {
-        if (
-          error.message.includes('Cannot find module') &&
-          error.message.includes('pino-pretty')
-        ) {
+        this.#retryCount++;
+
+        if (error.message.includes('Cannot find module') &&
+            error.message.includes('pino-pretty')) {
           const errorMessage = `
 ╭─────────────────────────────────────────────────────────────╮
 │                     Missing Dependency                      │
@@ -165,13 +197,82 @@ export class PinoAdapter {
           console.error(errorMessage);
           throw new Error('pino-pretty is required for development mode');
         }
-        throw error;
+
+        if (this.#retryCount > this.#maxRetries) {
+          console.error('Failed to initialize pino transport after retries:', error.message);
+          this.#fallbackToConsole();
+          this.#readyPromise.tryResolve();
+          return;
+        }
+
+        await new Promise(resolve => setTimeout(resolve, this.#retryDelay * this.#retryCount));
+      }
+    }
+  }
+
+  /**
+   * Flush queued messages to pino transport
+   */
+  #flushMessageQueue() {
+    if (!this.#pino || !this.#isTransportReady) {
+      return;
+    }
+
+    while (this.#messageQueue.length > 0) {
+      const queuedLog = this.#messageQueue.shift();
+      try {
+        this.#pino[queuedLog.level](queuedLog.data, queuedLog.message);
+      } catch (error) {
+        console.error('Failed to flush queued log message:', error.message);
+        this.#isTransportReady = false;
+        this.#messageQueue.unshift(queuedLog);
+        break;
       }
-    } else {
-      this.pino = pino({ ...baseOptions, ...options });
     }
   }
 
+  /**
+   * Fallback to console logging when transport fails
+   */
+  #fallbackToConsole() {
+    this.#isTransportReady = true;
+    this.#isInitializing = false;
+
+    while (this.#messageQueue.length > 0) {
+      const queuedLog = this.#messageQueue.shift();
+      console[queuedLog.level === 'error' ? 'error' : 'log'](
+        `[${queuedLog.level.toUpperCase()}] ${queuedLog.message}`,
+        queuedLog.data
+      );
+    }
+
+    this.#pino = {
+      debug: (data, msg) => console.log(`[DEBUG] ${msg}`, data),
+      info: (data, msg) => console.log(`[INFO] ${msg}`, data),
+      warn: (data, msg) => console.warn(`[WARN] ${msg}`, data),
+      error: (data, msg) => console.error(`[ERROR] ${msg}`, data),
+      // eslint-disable-next-line no-unused-vars
+      child: (context) => this
+    };
+  }
+
+  /**
+   * Promise that resolves when transport is ready
+   *
+   * @returns {Promise<void>} Promise that resolves when ready
+   */
+  ready() {
+    if (this.#isTransportReady) {
+      return Promise.resolve();
+    }
+
+    if (!this.#isInitializing) {
+      this.#initializePino();
+    }
+
+    return this.#readyPromise;
+  }
+
   /**
    * Clean stack trace by removing project root path and simplifying node_modules
    *
@@ -201,8 +302,7 @@ export class PinoAdapter {
 
     // Simplify pnpm paths: node_modules/.pnpm/package@version_deps/node_modules/package
     // becomes: node_modules/package
-    const pnpmRegex =
-      /node_modules\/\.pnpm\/([^@/]+)@[^/]+\/node_modules\/\1/g;
+    const pnpmRegex = /node_modules\/\.pnpm\/([^@/]+)@[^/]+\/node_modules\/\1/g;
     cleaned = cleaned.replace(pnpmRegex, 'node_modules/$1');
 
     // Also handle cases where the package name might be different in the final path
@@ -211,9 +311,10 @@ export class PinoAdapter {
 
     // Filter out Node.js internal modules and internal logger methods
     const lines = cleaned.split('\n');
-    const filteredLines = lines.filter(line => 
-      !line.includes('node:internal') &&
-      !(line.includes('#toError') && line.includes('logger/Logger.js'))
+    const filteredLines = lines.filter(
+      (line) =>
+        !line.includes('node:internal') &&
+        !(line.includes('#toError') && line.includes('logger/Logger.js'))
     );
     cleaned = filteredLines.join('\n');
 
@@ -225,7 +326,7 @@ export class PinoAdapter {
    *
    * @param {Object} logEvent - Log event from Logger
    */
-  handleLog(logEvent) {
+  async handleLog(logEvent) {
     const { level, message, details, source, timestamp } = logEvent;
 
     const logData = {
@@ -233,34 +334,58 @@ export class PinoAdapter {
       timestamp
     };
 
-    // Check if details contains an error and promote it to error property for
-    // pino serializer
     if (details) {
       if (details instanceof Error) {
-        // details is directly an error
         logData.errors = details;
       } else if (details.error instanceof Error) {
-        // details has an error property
         logData.errors = details.error;
-        // Include other details except the error
         // eslint-disable-next-line no-unused-vars
         const { error, ...otherDetails } = details;
         if (Object.keys(otherDetails).length > 0) {
           logData.details = otherDetails;
         }
       } else {
-        // No error found in details, include all details
         logData.details = details;
       }
     }
 
-    // Check if we have loggedAt info from the serializer
-    if (logData.errors && typeof logData.errors === 'object' && logData.errors.loggedAt) {
+    if (
+      logData.errors &&
+      typeof logData.errors === 'object' &&
+      logData.errors.loggedAt
+    ) {
       logData.loggedAt = logData.errors.loggedAt;
       logData.errors = logData.errors.chain;
     }
 
-    this.pino[level](logData, message);
+    // Queue message if transport not ready
+    if (!this.#isTransportReady) {
+      this.#messageQueue.push({ level, data: logData, message });
+
+      // Limit queue size to prevent memory issues
+      if (this.#messageQueue.length > 1000) {
+        this.#messageQueue.shift();
+      }
+
+      // Initialize transport if not already doing so
+      if (!this.#isInitializing) {
+        this.#initializePino();
+      }
+      return;
+    }
+
+    // Try to log directly, queue on failure
+    try {
+      this.#pino[level](logData, message);
+    } catch (error) {
+      console.error('Transport failed, queuing message:', error.message);
+      this.#isTransportReady = false;
+      this.#messageQueue.push({ level, data: logData, message });
+
+      // Retry transport initialization
+      this.#retryCount = 0;
+      setTimeout(() => this.#initializePino(), this.#retryDelay);
+    }
   }
 
   /**
@@ -270,9 +395,17 @@ export class PinoAdapter {
    * @returns {PinoAdapter} New adapter instance with context
    */
   child(context) {
-    const childPino = this.pino.child(context);
+    if (!this.#pino) {
+      // Return new adapter that inherits parent options with context
+      return new PinoAdapter({ ...this.#options, ...context });
+    }
+
+    const childPino = this.#pino.child(context);
     const adapter = new PinoAdapter();
-    adapter.pino = childPino;
+    adapter.#pino = childPino;
+    adapter.#isTransportReady = this.#isTransportReady;
+    adapter.#readyPromise = new HkPromise();
+    adapter.#readyPromise.tryResolve();
     return adapter;
   }
 }

package/dist/logging/internal/transports/pretty-transport.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Custom transport wrapper for pino-pretty that avoids worker threads
+ * and provides lazy loading to prevent Vite hot reload interference
+ */
+/**
+ * Create a pino-pretty transport that loads synchronously but initializes
+ * pino-pretty lazily to avoid worker thread conflicts with Vite
+ *
+ * @param {Object} [opts] - pino-pretty options
+ * @param {boolean} [opts.colorize=true] - Enable colored output
+ * @param {string} [opts.ignore] - Fields to ignore in output
+ * @returns {Promise<Object>} Transport-compatible object
+ */
+export default function createPrettyTransport(opts?: {
+    colorize?: boolean;
+    ignore?: string;
+}): Promise<any>;

package/dist/logging/internal/transports/pretty-transport.js

@@ -0,0 +1,104 @@
+/**
+ * Custom transport wrapper for pino-pretty that avoids worker threads
+ * and provides lazy loading to prevent Vite hot reload interference
+ */
+
+/**
+ * Create a pino-pretty transport that loads synchronously but initializes
+ * pino-pretty lazily to avoid worker thread conflicts with Vite
+ *
+ * @param {Object} [opts] - pino-pretty options
+ * @param {boolean} [opts.colorize=true] - Enable colored output
+ * @param {string} [opts.ignore] - Fields to ignore in output
+ * @returns {Promise<Object>} Transport-compatible object
+ */
+export default async function createPrettyTransport(opts = {}) {
+  let prettyStream = null;
+  let messageQueue = [];
+  let isInitializing = false;
+
+  /**
+   * Initialize pino-pretty stream
+   */
+  async function initializePrettyStream() {
+    if (isInitializing || prettyStream) {
+      return;
+    }
+
+    isInitializing = true;
+
+    try {
+      const { default: pinoPretty } = await import('pino-pretty');
+      prettyStream = pinoPretty({
+        colorize: true,
+        ignore: 'hostname,pid',
+        ...opts
+      });
+
+      // Flush queued messages
+      while (messageQueue.length > 0) {
+        const chunk = messageQueue.shift();
+        prettyStream.write(chunk);
+      }
+
+    } catch (error) {
+      console.error('Failed to initialize pino-pretty:', error.message);
+      
+      // Fallback to console output
+      prettyStream = {
+        write(chunk) {
+          try {
+            const log = JSON.parse(chunk);
+            const level = log.level >= 50 ? 'ERROR' : 
+                         log.level >= 40 ? 'WARN' : 
+                         log.level >= 30 ? 'INFO' : 'DEBUG';
+            console.log(`[${level}] ${log.msg}`, log);
+          } catch {
+            console.log(chunk);
+          }
+        }
+      };
+
+      // Flush queue to console fallback
+      while (messageQueue.length > 0) {
+        const chunk = messageQueue.shift();
+        prettyStream.write(chunk);
+      }
+    }
+
+    isInitializing = false;
+  }
+
+  return {
+    /**
+     * Write log message to transport
+     *
+     * @param {string} chunk - JSON log message
+     */
+    write(chunk) {
+      if (!prettyStream) {
+        messageQueue.push(chunk);
+        
+        // Limit queue size
+        if (messageQueue.length > 1000) {
+          messageQueue.shift();
+        }
+
+        // Start initialization if not already started
+        if (!isInitializing) {
+          initializePrettyStream();
+        }
+        return;
+      }
+
+      try {
+        prettyStream.write(chunk);
+      } catch (error) {
+        console.error('Pretty stream write failed:', error.message);
+        messageQueue.push(chunk);
+        prettyStream = null;
+        initializePrettyStream();
+      }
+    }
+  };
+}

package/dist/logging/internal/transports/test-transport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Test transport for validating lazy initialization behavior
+ */
+/**
+ * Create a mock transport for testing lazy initialization scenarios
+ *
+ * @param {Object} [opts] - Test configuration options
+ * @param {number} [opts.delay=100] - Initialization delay in milliseconds
+ * @param {boolean} [opts.shouldFail=false] - Whether initialization should fail
+ * @param {string} [opts.failureMessage] - Custom failure message
+ * @param {boolean} [opts.shouldFailOnWrite=false] - Fail on write operations
+ * @returns {Promise<Object>} Transport-compatible object
+ */
+export default function createTestTransport(opts?: {
+    delay?: number;
+    shouldFail?: boolean;
+    failureMessage?: string;
+    shouldFailOnWrite?: boolean;
+}): Promise<any>;

package/dist/logging/internal/transports/test-transport.js

@@ -0,0 +1,79 @@
+/**
+ * Test transport for validating lazy initialization behavior
+ */
+
+/**
+ * Create a mock transport for testing lazy initialization scenarios
+ *
+ * @param {Object} [opts] - Test configuration options
+ * @param {number} [opts.delay=100] - Initialization delay in milliseconds
+ * @param {boolean} [opts.shouldFail=false] - Whether initialization should fail
+ * @param {string} [opts.failureMessage] - Custom failure message
+ * @param {boolean} [opts.shouldFailOnWrite=false] - Fail on write operations
+ * @returns {Promise<Object>} Transport-compatible object
+ */
+export default async function createTestTransport(opts = {}) {
+  const { 
+    delay = 100, 
+    shouldFail = false,
+    failureMessage = 'Test transport setup failed',
+    shouldFailOnWrite = false
+  } = opts;
+
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      if (shouldFail) {
+        reject(new Error(failureMessage));
+        return;
+      }
+
+      const messages = [];
+      
+      resolve({
+        /**
+         * Write log message to test transport
+         *
+         * @param {string} chunk - JSON log message
+         */
+        write(chunk) {
+          if (shouldFailOnWrite) {
+            throw new Error('Test transport write failure');
+          }
+          
+          messages.push(chunk);
+        },
+
+        /**
+         * Get all captured messages
+         *
+         * @returns {string[]} Array of log message chunks
+         */
+        getMessages() {
+          return [...messages];
+        },
+
+        /**
+         * Clear captured messages
+         */
+        clear() {
+          messages.length = 0;
+        },
+
+        /**
+         * Get parsed log objects from captured messages
+         *
+         * @returns {Object[]} Array of parsed log objects
+         */
+        getParsedMessages() {
+          return messages.map(chunk => {
+            try {
+              return JSON.parse(chunk);
+            } catch {
+              return { raw: chunk };
+            }
+          });
+        }
+      });
+    }, delay);
+  });
+}

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

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